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

package/docs/models/model-selection.md

@@ -17,7 +17,13 @@ It is a **static reference**. It does not change runtime model routing — routi
 The table below is a snapshot of the [DeepSWE](https://deepswe.datacurve.ai/) leaderboard (v1.1, highest published thinking level per model), a long-horizon coding-agent benchmark reporting `pass@1` and average dollars per task. The source reports 113 tasks and was updated September 3, 2026. DeepSWE's own default table view is **Best** — the best-scoring configuration per model — so four models show a different row there than the highest-effort row used here; the snapshot note below the table names them. Benchmarks and pricing drift and new models ship constantly, so **treat the live leaderboards as authoritative** and refresh this page from them rather than hand-maintaining scores. See [Evals](/models/evals). **Last compiled: 2026-09-03.**
 </Note>
 
-Artificial Analysis was reviewed separately on **2026-09-05** against its September 4 Intelligence Index v4.2 revision. The DeepSWE table remains the September 3 snapshot; an independent September 5 browser check confirmed its update date and Gemini 3.8 Flash row, not every configuration.
+Artificial Analysis was reviewed separately on **2026-09-08** against its **September 7 Intelligence Index v4.3** revision. The DeepSWE table remains the September 3 snapshot and was not revalidated in this refresh; the earlier September 5 browser check confirmed its update date and Gemini 3.8 Flash row, not every configuration.
+
+## Answering model-choice questions
+
+For any task-specific model recommendation, not just workflow authoring, read the [task-type picker](/models/evals#pick-by-task-type) and its per-benchmark charts, then consult [Artificial Analysis](https://artificialanalysis.ai/) for the relevant live evaluation and methodology. Recommend a task-fit candidate and explain the cost or latency tradeoff. Cite the benchmark version, retrieval date and exact model/effort configuration. An aggregate leaderboard winner is not a winner on every task.
+
+If live results cannot be retrieved, use the dated docs snapshot and say it was not refreshed. Check the configured catalog before suggesting an exact provider/model ID or effort level; catalog presence does not prove live access. Keep benchmark measurement settings separate from production effort recommendations.
 
 ## Benchmark levels are measurement settings
 
@@ -32,18 +38,18 @@ reports the ambiguity. Use `--provider <provider> --model <id>` or `--model <pro
 
 ## AA cross-check for current candidates
 
-These are selected candidates, not a replacement DeepSWE frontier. The linked model pages and [rendered AA highlights](https://artificialanalysis.ai/) were retrieved **2026-09-05** under Intelligence Index **v4.2**, announced **2026-09-04**. Model-page metrics have no separate visible update timestamp. Scores are index points, not pass percentages; cost is weighted USD per **AA Intelligence Index task**, not DeepSWE cost. Speed is the model-page summary in standardized output tokens per second, not full-task latency.
+These are selected candidates, not a replacement DeepSWE frontier. The [AA leaderboard](https://artificialanalysis.ai/leaderboards/models) was retrieved **2026-09-08** under Intelligence Index **v4.3**, announced **2026-09-07**. Scores are index points, not pass percentages; cost is weighted USD per **AA Intelligence Index task**, not DeepSWE cost. Speed uses the default 10k-input workload in standardized output tokens per second, not full-task latency. The source has no separate publication timestamp for these measurements.
 
 | Model and AA measurement configuration | Intelligence Index | AA $/task | Output tokens/s | Candidate role and tradeoff |
 | --- | --- | --- | --- | --- |
-| [Claude Fable 5.1, Adaptive Reasoning, Max Effort, Default Fallback](https://artificialanalysis.ai/models/claude-fable-5-1) | 57 | $6.12 | 68.7 | Quality-first planning and judgment candidate; leads AA's displayed intelligence highlights, but has the highest task cost of this shortlist |
-| [GPT-6 Astra, max](https://artificialanalysis.ai/models/gpt-6-astra) | 55 | $2.57 | 87.5 | High-stakes planning and document-reasoning candidate with lower AA task cost than Fable 5.1 |
-| [Gemini 3.8 Flash, high](https://artificialanalysis.ai/models/gemini-3-8-flash) | 47 | $0.74 | Not reported | Cost-conscious coding candidate with strong separate DeepSWE evidence; do not invent API speed from its token price |
-| [GPT-5.6 Luna, max](https://artificialanalysis.ai/models/gpt-5-6-luna) | 43 | $0.10 | 134.8 | Budget research and worker candidate when its lower measured quality is acceptable |
+| [Claude Fable 5.1, max with default fallback](https://artificialanalysis.ai/models/claude-fable-5-1) | 53 | $7.63 | 69 | Knowledge-work planning candidate; xhigh also displays 53 at $5.98 per task |
+| [GPT-6 Astra, max](https://artificialanalysis.ai/models/gpt-6-astra) | 53 | $3.26 | 62 | Terminal and document-reasoning candidate; xhigh displays 53 at $2.31 and scores higher on those two individual evaluations |
+| [Gemini 3.8 Flash, high](https://artificialanalysis.ai/models/gemini-3-8-flash) | 41 | $1.24 | 286 | Strong historical Datacurve result, but only 20% on the new Terminal-Bench v4.0; check the intended task distribution |
+| [GPT-5.6 Luna, max](https://artificialanalysis.ai/models/gpt-5-6-luna) | 38 | $0.18 | 121 | Budget long-context candidate with verification; 12% on Terminal-Bench v4.0 |
 
-AA's [v4.2 announcement](https://artificialanalysis.ai/articles/artificial-analysis-intelligence-index-v4-2) places Fable 5.1 and Opus 5 ahead on AA-Briefcase, while Astra leads GDP.pdf. The measured numbers behind that: Fable 5.1 max and Opus 5 max score 58% on AA-Briefcase and 63% and 62% on GDPval-AA v2, against 53% and 54% for Astra max; Astra max scores 33% on GDP.pdf against 26% for Fable 5.1 max and 22% for Opus 5 max. Use those task-specific signals for knowledge-work planning versus document research; the full per-evaluation tables for every catalog model are in [Evals](/models/evals#per-evaluation-scores-for-catalog-models), with a [task-type picker](/models/evals#pick-by-task-type) at the top of that page. An aggregate lead does not establish security-review reliability or the best model for every role. Keep Fable's **Default Fallback** qualifier: this is not evidence for an arbitrary no-fallback configuration.
+AA's [v4.3 announcement](https://artificialanalysis.ai/articles/artificial-analysis-intelligence-index-v4-3) replaces 𝜏³-Banking with AutomationBench-AA and Terminal-Bench v2.1 with v4.0. Fable 5.1 max with default fallback scores 58% normalized Elo on AA-Briefcase and 63% on GDPval-AA v2, versus Astra max at 53% and 54%. These are transformed Elo displays, **not pass rates**. Astra xhigh scores 32% GDP.pdf All-pass and 60% Terminal-Bench v4.0; Astra max scores 31% and 59%. Use the [per-evaluation tables](/models/evals#per-evaluation-scores-for-catalog-models) and [task-type picker](/models/evals#pick-by-task-type), not an aggregate rank. A rounded lead does not establish statistical significance, security-review reliability or the best model for every role. Fable's default-fallback result is not evidence for an arbitrary no-fallback configuration.
 
-The separate [Coding Agent Index v1.4](https://artificialanalysis.ai/agents/coding-agents), also retrieved 2026-09-05, reports **Claude Code - Fable 5.1 (max) (with fallback)** at **70**, **$9.18/task** and **24.0 minutes agent wall time/task**, versus **Opencode - Gemini 3.8 Flash (high)** at **61**, **$2.04/task** and **11.9 minutes**, and **Codex - GPT-5.6 Luna (max)** at **57**, **$0.29/task** and **8.0 minutes**. Those agent-specific measurements illustrate a quality/cost/time tradeoff; neither is an Atomic result or a base-model score. Fable 5.1 is measured there even though it is absent from the Datacurve snapshot below. All fourteen rows, with their DeepSWE, Terminal-Bench and SWE-Atlas-QnA components, are tabulated in [Evals](/models/evals#coding-agent-index-v14-is-a-different-comparison); read the methodology and units there before combining evidence.
+The separate [Coding Agent Index v1.4](https://artificialanalysis.ai/agents/coding-agents), retrieved 2026-09-08, still uses Terminal-Bench v2.1 alongside DeepSWE and SWE-Atlas-QnA. It reports Claude Code + Fable 5.1 max with fallback at **70**, **$9.18/task** and **24.0 minutes/task**, Opencode + Gemini 3.8 Flash high at **61**, **$2.04/task** and **11.9 minutes/task**, and Codex + Luna max at **57**, **$0.29/task** and **8.0 minutes/task**. These are named-agent runs, not Atomic or interchangeable base-model results. All fourteen rows are in [Evals](/models/evals#coding-agent-index-v14-is-a-different-comparison). Fable 5.1 remains absent from the separately dated Datacurve snapshot below.
 
 ## Recommendation chart
 
@@ -115,13 +121,13 @@ Reserve `max` for a high-cost-of-error role or an explicit user request. An expl
 
 ## Scenario-based guidance
 
-Pick by the cost of being wrong in each role, not by raw accuracy. Match the role to the benchmark that best measures it (see [Evals](/models/evals) and its [task-type picker](/models/evals#pick-by-task-type)). The percentages below are AA per-evaluation scores read on 2026-09-05 for the named configuration.
+Pick by the cost of being wrong in each role, not by raw accuracy. The AA evidence below was read on 2026-09-08; the Datacurve evidence remains the September 3 snapshot. See [Evals](/models/evals) for measurement settings, normalized Elo versus pass-rate units and source links.
 
-- **Reviewer / judgment gates** — use `max` when the reviewer makes a security, identity, adversarial, or final-approval decision whose wrong verdict discards an entire loop. `gemini-3.8-flash` is the DeepSWE accuracy ceiling and reaches it at a fraction of top-tier cost; `claude-opus-5` and `gpt-5.6-sol` are the near-peers when a different family is wanted. For code-reading judgments, the Anthropic rows separate: Claude Code + Fable 5.1 and + Opus 5 score 56% and 55% on SWE-Atlas-QnA against 51% for Codex + Astra and 38% for Opencode + Gemini 3.8 Flash. Use another family when decorrelated errors matter.
-- **Codebase mapping / planner** — start at `high` for repository mapping, lifecycle analysis, compatibility, and plans. Gemini 3.8 Flash is a cost-conscious coding candidate but near the bottom of the catalog on AA-Briefcase (35%; only Gemini 3.7 Flash is lower at 31%); for plans that resemble knowledge work, Fable 5.1 max and Opus 5 max (58%) or, on a budget, GLM-5.3-Flash (48% for $0.18 per AA task) measure better. Raise production effort only when the plan gates a high-cost loop or the user asks, and only to a level advertised by that exact catalog entry.
-- **Debugger / triage / repair** — start at `high`; deep reasoning pays off when root-causing or repairing is costly. Weight DeepSWE and Terminal-Bench together rather than treating either as a complete measure: Terminal-Bench v2.1 is flat at 88–91% across Fable 5.1 max, Astra at every effort, Sol max and xhigh, Opus 5 max through high, Terra max and Gemini 3.8 Flash high, so DeepSWE cost and steps decide among them.
-- **Research / synthesis** — use `high` for demanding research and evidence reconciliation; use `medium` for routine synthesis when the evidence is already strong. `gpt-5.6-luna` is the budget starting point for long-context work (84% on AA-LCR v1.1 for $0.10 per AA task), but it abstains only 7% of the time on AA-Omniscience, so back it with verification tool nodes; evaluate Astra (33% GDP.pdf All-pass, the leader) when document-reasoning failures justify more cost, and GLM-5.3-Flash or GLM-5.3 (72% and 70% non-hallucination) when a wrong fact is worse than an abstention. Weight AA-LCR v1.1, GDP.pdf and AA-Omniscience rather than general intelligence alone.
-- **Orchestrator / worker / cheap loops** — Luna offers the best broad cost/accuracy balance for code, but scores 31% on 𝜏³-Banking, the lowest catalog row, so prefer GLM-5.3-Flash (47%) or Muse Spark 1.3 (52%) when the loop is tool-call heavy. GLM-5.3 Flash is the cheapest live frontier point at 63% for $0.24 with 123 average steps. Gemini 3.8 Flash is the most accurate frontier point but averages 166 steps and 143k output tokens per task, which makes it a judgment-gate choice rather than an automatic worker default. DeepSeek V4 Pro and Flash are provider-diversity options, not budget-frontier choices.
+- **Reviewer / judgment gates.** Use `max` for a high-cost-of-error security, identity, adversarial or final-approval decision, subject to the configured model's supported efforts. No external benchmark here establishes security-review reliability. Claude Code + Fable 5.1 max with fallback and Claude Code + Opus 5 xhigh score 56% and 55% on SWE-Atlas-QnA, versus 51% for Codex + Astra max, but those harness-specific results need validation in Atomic.
+- **Codebase mapping / planner.** Start at `high`. For knowledge-work deliverables, Fable 5.1 max with fallback scores 58% normalized Elo on AA-Briefcase, Opus 5 max 57%, and GLM-5.3-Flash 48% at $0.25 per Index task. These are candidates, not measured repository-planning pass rates. Raise effort only for the role's cost of error or the user's request.
+- **Debugger / triage / repair.** Start at `high`. The new Terminal-Bench v4.0 is no longer flat near 90%: Astra xhigh scores 60%, Fable 5.1 xhigh with fallback 55%, Opus 5 max 49%, and Gemini 3.8 Flash high 20%. Keep Datacurve cost and steps as separate evidence; do not transfer its 74% Gemini result into this benchmark.
+- **Research / synthesis.** Use `high` for demanding reconciliation and `medium` for routine synthesis. Luna max scores 84% on AA-LCR at $0.18 per Index task, but its 7% non-hallucination rate counts partial answers or not attempted among non-correct responses, not all answers. Verify factual claims. Astra xhigh leads the displayed GDP.pdf rows at 32%; GLM-5.3-Flash and GLM-5.3 max score 72% and 70% non-hallucination.
+- **Orchestrator / worker / cheap loops.** Use AutomationBench-AA for SaaS tool workflows: Astra max 68%, GLM-5.3-Flash 60%, Luna max 50%. GLM-5.3-Flash and Luna remain budget candidates on the separately dated Datacurve frontier. Gemini 3.8 Flash's 166 steps and 143k output tokens in that snapshot argue against choosing workers on pass rate alone. Validate the tradeoff on the actual workflow.
 - **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 domain not directly measured by these coding tables. Choose effort by the review or approval role. Fable 5.1's AA-Briefcase results make it a candidate for knowledge-work deliverables, not proof of product-design quality; evaluate it on the intended design tasks and do not carry Fable 5's DeepSWE row over to it.
 - **Interactive coding sessions** — use `high` for complex, multi-step coding and `medium` for routine edits; reserve `max` for a high-cost-of-error judgment or an explicit user request.

package/docs/models/pareto-efficiency.md

@@ -13,7 +13,7 @@ The axes here are `pass@1` (accuracy) and `average dollars per task` (cost), tak
 Figures are a snapshot of DeepSWE v1.1 using the highest published thinking level for each of the 21 models displayed on the September 3, 2026 leaderboard. They include the August 21 pricing corrections for GPT-5.6 Sol and DeepSeek V4, and GPT-6 Astra's costs are DeepSWE's expected launch pricing rather than billed rates. DeepSWE's own default table view is **Best** — the best-scoring configuration per model — which picks a different row for four models; the frontier under that reading is stated below. DeepSWE publishes a live cost-vs-score scatter, so **read the frontier off the live chart** rather than trusting a static list. **Last compiled: 2026-09-03.**
 </Note>
 
-The [AA review](/models/evals) is separately dated **2026-09-05**. AA Intelligence Index v4.2 uses weighted intelligence and its own cost per task; AA Coding Agent Index v1.4 uses agent-specific runs across several benchmarks. Neither defines the Datacurve frontier on this page. A September 5 browser check confirmed the September 3 DeepSWE update and Gemini 3.8 Flash's measured row, without recomputing this entire snapshot.
+The [AA review](/models/evals) is separately dated **2026-09-08**. Intelligence Index v4.3, announced September 7, uses weighted intelligence and its own cost per task; Coding Agent Index v1.4 still uses agent-specific runs including Terminal-Bench v2.1 rather than v4.0. Neither defines the Datacurve frontier on this page. This refresh did not revalidate or recompute the September 3 DeepSWE snapshot. The earlier September 5 browser check confirmed its update date and Gemini 3.8 Flash's row.
 
 ## The frontier
 
@@ -75,7 +75,7 @@ Efficiency is not the only axis. A dominated model can still earn a slot when it
 - **glm-5.3 [max]** remains the best open-weights point; the new frontier ceiling is closed-weights, so the open-weights niche survives the frontier change intact.
 - **gemini-3.8-flash [high]** holds the frontier ceiling but is Google-family and step-heavy at 166 average steps; pair it with a model from another family for fallback diversity rather than routing every stage through one provider.
 - **claude-fable-5** remains useful where Anthropic-family behavior is specifically wanted, such as the quality-first, unbenchmarked design chain.
-- **claude-fable-5-1** is available in Atomic's catalog but is absent from the September 3, 2026 Datacurve snapshot, so it has no position on this frontier. It is measured by AA Intelligence Index and by AA with Claude Code, as detailed in the [September 5 AA cross-check](/models/model-selection#aa-cross-check-for-current-candidates). Those results justify evaluation for quality-first work, not importing an AA score or cost into this DeepSWE chart. Its cache pricing may matter for long sessions, but a token-price discount is not a measured cost-per-task saving or accuracy result.
+- **claude-fable-5-1** is available in Atomic's catalog but absent from the September 3, 2026 Datacurve snapshot, so it has no position on this frontier. The [September 8 AA cross-check](/models/model-selection#aa-cross-check-for-current-candidates) includes Fable 5.1's max and xhigh default-fallback measurements. Those results justify task-specific evaluation, not importing AA scores or costs into this DeepSWE chart. A token-price discount is not a measured task-cost saving.
 - **Unmeasured models** may remain operational defaults when a family lacks current DeepSWE or Artificial Analysis coverage, but they should not inherit a predecessor's score.
 
 ## How to use this

package/docs/providers.md

@@ -116,7 +116,9 @@ 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:xhigh`, `github-copilot/grok-4.6:xhigh`, 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.
+Atomic defaults xAI sessions to `grok-4.6`. Built-in workflow and subagent fallback chains use `xai/grok-4.6:xhigh`, `github-copilot/grok-4.6:xhigh`, and `openrouter/x-ai/grok-4.6:xhigh`; 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.
+
+The `codebase-locator`, `codebase-pattern-finder`, and `codebase-research-locator` agents use GPT-5.6 Luna at `xhigh` and Grok fallbacks at `medium` instead. Goal and Ralph orchestration, Ralph research, and Open Claude Design use GPT-6 Astra at `medium`; Ralph prompt refinement remains at `high`.
 
 ### Radius
 
@@ -142,45 +144,45 @@ On a remote or headless machine, paste the authorization code or final redirect
 
 Remote pi.dev catalogs persist their ETag and are revalidated with `If-None-Match`; an empty `304` keeps the cached models and counts as a successful check. Atomic renders the cached snapshot immediately, preserves each provider's last usable catalog on refresh failure, and prefers newer bundled data over stale remote overlays. See [Custom Models](/models#catalog-freshness-and-precedence).
 
-| Provider | Environment Variable | `auth.json` key |
-|----------|----------------------|------------------|
-| Anthropic | `ANTHROPIC_API_KEY` or bearer-only `ANTHROPIC_AUTH_TOKEN` | `anthropic` |
-| Ant Ling | `ANT_LING_API_KEY` | `ant-ling` |
-| Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
-| OpenAI | `OPENAI_API_KEY` | `openai` |
-| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
-| NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |
-| Google Gemini | `GEMINI_API_KEY` | `google` |
-| Google Vertex AI | `GOOGLE_CLOUD_API_KEY` | `google-vertex` |
-| Mistral | `MISTRAL_API_KEY` | `mistral` |
-| Groq | `GROQ_API_KEY` | `groq` |
-| Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
-| Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`) | `cloudflare-ai-gateway` |
-| Cloudflare Workers AI | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`) | `cloudflare-workers-ai` |
-| xAI | `XAI_API_KEY` | `xai` |
-| OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
-| Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
-| ZAI | `ZAI_API_KEY` | `zai` |
-| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` | `zai-coding-cn` |
-| OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
-| OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
-| Radius | `RADIUS_API_KEY` | `radius` |
-| Hugging Face | `HF_TOKEN` | `huggingface` |
-| Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
-| Together AI | `TOGETHER_API_KEY` | `together` |
-| Baseten | `BASETEN_API_KEY` | `baseten` |
-| Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
-| MiniMax | `MINIMAX_API_KEY` | `minimax` |
-| MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
-| Moonshot AI | `MOONSHOT_API_KEY` | `moonshotai` |
-| Moonshot AI (China) | `MOONSHOT_API_KEY` | `moonshotai-cn` |
-| Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan` |
-| Qwen Token Plan (Individual) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan-individual` |
-| Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` | `qwen-token-plan-cn` |
-| Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
-| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` | `xiaomi-token-plan-cn` |
-| 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` |
+| Provider                           | Environment Variable                                                      | `auth.json` key              |
+| ---------------------------------- | ------------------------------------------------------------------------- | ---------------------------- |
+| Anthropic                          | `ANTHROPIC_API_KEY` or bearer-only `ANTHROPIC_AUTH_TOKEN`                 | `anthropic`                  |
+| Ant Ling                           | `ANT_LING_API_KEY`                                                        | `ant-ling`                   |
+| Azure OpenAI Responses             | `AZURE_OPENAI_API_KEY`                                                    | `azure-openai-responses`     |
+| OpenAI                             | `OPENAI_API_KEY`                                                          | `openai`                     |
+| DeepSeek                           | `DEEPSEEK_API_KEY`                                                        | `deepseek`                   |
+| NVIDIA NIM                         | `NVIDIA_API_KEY`                                                          | `nvidia`                     |
+| Google Gemini                      | `GEMINI_API_KEY`                                                          | `google`                     |
+| Google Vertex AI                   | `GOOGLE_CLOUD_API_KEY`                                                    | `google-vertex`              |
+| Mistral                            | `MISTRAL_API_KEY`                                                         | `mistral`                    |
+| Groq                               | `GROQ_API_KEY`                                                            | `groq`                       |
+| Cerebras                           | `CEREBRAS_API_KEY`                                                        | `cerebras`                   |
+| Cloudflare AI Gateway              | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`) | `cloudflare-ai-gateway`      |
+| Cloudflare Workers AI              | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`)                          | `cloudflare-workers-ai`      |
+| xAI                                | `XAI_API_KEY`                                                             | `xai`                        |
+| OpenRouter                         | `OPENROUTER_API_KEY`                                                      | `openrouter`                 |
+| Vercel AI Gateway                  | `AI_GATEWAY_API_KEY`                                                      | `vercel-ai-gateway`          |
+| ZAI                                | `ZAI_API_KEY`                                                             | `zai`                        |
+| ZAI Coding Plan (China)            | `ZAI_CODING_CN_API_KEY`                                                   | `zai-coding-cn`              |
+| OpenCode Zen                       | `OPENCODE_API_KEY`                                                        | `opencode`                   |
+| OpenCode Go                        | `OPENCODE_API_KEY`                                                        | `opencode-go`                |
+| Radius                             | `RADIUS_API_KEY`                                                          | `radius`                     |
+| Hugging Face                       | `HF_TOKEN`                                                                | `huggingface`                |
+| Fireworks                          | `FIREWORKS_API_KEY`                                                       | `fireworks`                  |
+| Together AI                        | `TOGETHER_API_KEY`                                                        | `together`                   |
+| Baseten                            | `BASETEN_API_KEY`                                                         | `baseten`                    |
+| Kimi For Coding                    | `KIMI_API_KEY`                                                            | `kimi-coding`                |
+| MiniMax                            | `MINIMAX_API_KEY`                                                         | `minimax`                    |
+| MiniMax (China)                    | `MINIMAX_CN_API_KEY`                                                      | `minimax-cn`                 |
+| Moonshot AI                        | `MOONSHOT_API_KEY`                                                        | `moonshotai`                 |
+| Moonshot AI (China)                | `MOONSHOT_API_KEY`                                                        | `moonshotai-cn`              |
+| Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY`                                                 | `qwen-token-plan`            |
+| Qwen Token Plan (Individual)       | `QWEN_TOKEN_PLAN_API_KEY`                                                 | `qwen-token-plan-individual` |
+| Qwen Token Plan (China)            | `QWEN_TOKEN_PLAN_CN_API_KEY`                                              | `qwen-token-plan-cn`         |
+| Xiaomi MiMo                        | `XIAOMI_API_KEY`                                                          | `xiaomi`                     |
+| Xiaomi MiMo Token Plan (China)     | `XIAOMI_TOKEN_PLAN_CN_API_KEY`                                            | `xiaomi-token-plan-cn`       |
+| 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`      |
 
 Z.AI and Z.AI Coding Plan (China) default to `glm-5.3` (`zai/glm-5.3` and `zai-coding-cn/glm-5.3`), and both direct providers also expose the multimodal `glm-5.3-flash`. Baseten defaults to its directly selectable `zai-org/GLM-5.3` and also exposes `zai-org/GLM-5.3-Fast` and the multimodal `zai-org/GLM-5.3-Flash`; OpenRouter exposes `z-ai/glm-5.3` and `z-ai/glm-5.3-flash`. The full and Flash entries support `low`, `high`, and `max` reasoning; Baseten's Fast entry also supports `off`. Built-in workflow and subagent chains include the Z.AI, Z.AI Coding Plan, Baseten, and OpenRouter routes at `:high`. Use Baseten's `zai-org/GLM-5.2` or `zai-org/GLM-5.3-Fast` when fully disabled reasoning is required. 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. These catalogs follow their upstream providers, so use `--list-models` for the current entries.
 
@@ -351,12 +353,12 @@ Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway. Worke
 
 AI Gateway authentication uses `CLOUDFLARE_API_KEY` as `cf-aig-authorization`. Upstream authentication can be one of:
 
-| Mode | Request auth | Upstream auth |
-|------|--------------|---------------|
-| Workers AI | Cloudflare token only | Cloudflare-native |
-| Unified billing | Cloudflare token only | Cloudflare handles upstream auth and deducts credits |
-| Stored BYOK | Cloudflare token only | Cloudflare injects provider keys stored in the AI Gateway dashboard |
-| Inline BYOK | Cloudflare token plus upstream `Authorization` header | The request supplies the upstream provider key |
+| Mode            | Request auth                                          | Upstream auth                                                       |
+| --------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
+| Workers AI      | Cloudflare token only                                 | Cloudflare-native                                                   |
+| Unified billing | Cloudflare token only                                 | Cloudflare handles upstream auth and deducts credits                |
+| Stored BYOK     | Cloudflare token only                                 | Cloudflare injects provider keys stored in the AI Gateway dashboard |
+| Inline BYOK     | Cloudflare token plus upstream `Authorization` header | The request supplies the upstream provider key                      |
 
 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.
 

package/docs/quickstart.md

@@ -4,7 +4,7 @@ This page gets you from install to a useful first Atomic session. Atomic is the
 
 ## Prerequisites
 
-- **Package install:** Node.js 22.19 or newer plus npm, pnpm, Yarn, or Bun. Use Bun 1.4.0+ for Bun installs or workflow-authoring examples.
+- **Package install:** Node.js 22.19 or newer plus npm, pnpm, Yarn, or Bun. Use Bun 1.4.2+ for Bun installs or workflow-authoring examples.
 - **Release archive install:** macOS and Linux need `tar` and either `curl` or `wget`; Windows uses built-in PowerShell commands. This path does not need Node.js or a package manager.
 - **Model-provider access** — use a supported subscription login or API key. Run `/login` after startup.
 

package/docs/sdk.md

@@ -13,6 +13,241 @@ The SDK provides programmatic access to atomic's agent capabilities. Use it to e
 
 See [examples/sdk/](https://github.com/bastani-inc/atomic/tree/main/packages/coding-agent/examples/sdk) for working examples from minimal to full control.
 
+## Owner-bound task supervisor (S1)
+
+S1 adds an SDK-only task foundation in `src/core/tasks/contracts.ts` and
+`src/core/tasks/supervisor.ts`, backed by the native `TaskSupervisor`. It is an
+internal trusted-host integration surface, not a new CLI command. The package root
+exports the narrow `AgentTaskHost` adapter and its integration types, not the raw
+supervisor. Runtime-created subagent contexts use it; bash/PTY and task UI integration are separate slices.
+
+`AgentTaskHost` binds an actual trusted scope and mandatory `authorizeLaunch` guard.
+Its `startAgentTask(intent, operation, runnerFactory)` returns a Result containing
+`{taskId, lease}` after setup. Each launch supplies its own factory receiving the
+original `AbortSignal`, reference and `reportActivity` context. Return separate
+`result` and `cleanup` promises; yielding never replaces either promise, and only
+confirmed cleanup may report `reaped`. Exact operation replay never calls another factory.
+`observeAgentLaunch(taskId, policy?)` delegates to S1 initial observation; `waitForTask`,
+`resolveTask`, `cancelTask`, `watchOwnerTasks` and `close` remain owner-scoped S1 doors.
+Observation returns the exact Result/WaitOutcome DTO, not a new model response shape.
+These APIs are for trusted first-party hosts, never model-supplied ownership or permission.
+
+For already-admitted in-process tasks, the optional `taskExecution` runner hooks
+retain the original execution and cleanup promises. An exact Intercom commit
+yields the registered observation. In an explicit foreground group it also yields
+active sibling observations through the existing group signal, once per child;
+neither path detaches or completes those executions. Public launches in actual sessions use this bridge by default.
+
+Each workflow admission boundary allocates one process-private stage attempt identity.
+The actual stage session binds its original session/run/stage identity; fallback session
+replacement keeps that identity and the same lazily bound `bindAgentTaskHost` owner.
+Replacement disposal does not close tasks. Boundary sealing fences task admission and
+starts owner closure; generation close awaits independent cleanup and surfaces failure.
+Fresh boundaries have fresh identities, including restoration; history is not a restart
+capability. Public producers, durable callback joins and nonvisual completion intent/admission use this owner binding.
+
+When a task completion outbox is created from session history, it immediately retries
+unacknowledged terminal completion intents through the current admission boundary.
+It does not wait for another task to settle or recreate execution capabilities.
+Acknowledged intents are not redelivered. Failed admission keeps the original completion
+identity pending for retry; a closed boundary prevents admission.
+Top-level session initialization restores admission keys from persisted custom messages,
+so a crash after delivery is persisted but before its outbox acknowledgement does not
+deliver the same completion again.
+
+A host binds its actual session or workflow-stage scope with `bindHostSession`,
+provides launch authorization and a runner factory, then calls `openTaskOwner`.
+Authorization runs before native admission. `startAgentTask` registers an agent
+task before runner setup and returns its lease without waiting for completion.
+Exact operation replay reuses that task and execution; a fresh operation creates
+a distinct task. Leases are environment-local capabilities, cannot be serialized,
+and cannot be reconstructed from task IDs or historical records.
+
+`initialObservation` applies launch policy: omitted policy yields
+`default-background`, explicit background yields `explicit`, and foreground
+registers a wait with its requested budget. A ready terminal result wins.
+`await waitForTask(task, budgetMs?, designation?)` and
+`await foregroundTask(task, budgetMs?)` return a Result containing a WaitOutcome,
+not a lease. Native registration and the WaitId registry are populated synchronously
+before either door awaits. Host lifecycle actions can use `findWait(waitId)` to
+yield or dispose a registered observation; ordinary callers need no extra observe call.
+SDK waits do not replace the host designation unless given a matching HostSession.
+An elapsed/explicit yield or observer disposal never stops or relaunches execution;
+a later yield of a disposed wait replays its ObserverCancelled Result.
+
+Requested agent waits default to 30000 ms. Supply owner-host settings through
+`bindHostSession({ scope, tasks: { wait: { kind: "automatic", agentBudgetMs: 5000 } },
+authorizeLaunch, createRunner })`; `{ kind: "until-settled" }` disables timed yielding.
+Per-call budgets override settings, including zero for immediate yield. These settings
+apply to explicit foreground-first launch, live foregrounding and task-ID waits,
+never to a default independent launch. Wide numeric budgets are not narrowed to u32.
+Accepted `NaN` budgets (including configured `agentBudgetMs`) do not panic native
+scheduling. The implementation leaves such observations pending until explicit yield,
+settlement, observer disposal or owner closure: the elapsed comparison never reaches
+`NaN`. It uses bounded sleep chunks without rewriting the caller's budget. This is
+scheduling behavior, not a new finite-only input restriction or an RFC-mandated deadline;
+other numeric budgets and per-call precedence are unchanged.
+
+`await cancelTask(task, cause)` returns a Result containing a cancellation receipt
+and preserves the first accepted cause. `closeTaskOwner` seals admission before
+draining and succeeds only after independent cleanup acknowledgement. The trusted
+runner supplies separate result and cleanup promises: confirmed reaping after
+cancellation can close even if no result arrives. Natural cleanup-first delivery
+waits for its outcome before acknowledging reaping. External native owner closure
+also aborts resources attached to already-settled results without rewriting them.
+Failed cleanup remains observable; absent acknowledgement can leave close pending.
+User cancellation retains pending input attention until settlement or owner closure;
+event-reduced and reattached snapshots report the same native facts. Runner result
+rejections become failed `RunnerFailed` results; cleanup rejections become diagnostic
+`CleanupFailed` resources, never successful reaping. Setup throws retain `SpawnFailed`
+and unconfirmed cleanup. Strings and Error messages are preserved verbatim; other JS
+values use safe string conversion, with `Unprintable JavaScript rejection` if conversion
+throws. Cancelled cleanup still does not depend on the result promise settling.
+This slice exercises fake runners, not force-stop or real-process cleanup guarantees.
+
+### Supervised command SDK
+
+`startCommandTask(owner, intent, operation)` starts an owned Unix pipe/PTY or Windows pipe/ConPTY command.
+The command intent keeps execution timeout separate from observation: `waitForTask`
+defaults to 10000 ms for commands, and expiry returns a yielded observation without
+terminating the process. On Unix, owner closure sends TERM, allows 250 ms grace, then KILL,
+reaps the leader and confirms process-group exit and reader drain. A cleanup failure
+retains diagnostics instead of claiming a closed owner. This is normal owner/host
+shutdown cleanup, not a guarantee for forced host death or a blocked JavaScript loop.
+
+Both native and facade `CommandIntent` accept optional `shell: { program, args }`:
+the executable is launched directly with `command` appended as one final argv argument.
+Omitting `shell` preserves the default native pipe shell. `inheritEnv` defaults to
+`true`; `false` uses exactly the supplied environment rather than inheriting the host's.
+Both fields participate in operation replay identity.
+
+`taskStdin(task)` returns a non-serializable stdin capability. `writeTaskInput` takes
+an operation ID and `{kind:"bytes", bytes:Uint8Array}` or `{kind:"eof"}`. Empty bytes
+are a no-op. Input has 65536 byte credits, refuses excess input before admission,
+and replays recorded receipts without resending bytes. Ambiguous partial delivery
+returns `InputDeliveryUnknown`, including operation ID and known accepted-byte count.
+
+`readTaskOutput(task, {start, maximumBytes})` returns owned byte chunks at decimal
+offsets, requested bounds, omitted ranges and an optional next offset. Requests
+are clamped to the 1 MiB live-preview bound before allocating or reading a page;
+use `nextOffset` to continue. It does not sanitize or normalize bytes. Retention
+uses a 1 MiB live head/tail, 8 MiB foreground spill threshold and 5 GiB disk cap.
+Retained output is not conversation history. File-spool policy uses supervised
+pipe drains, never inherited direct file writers. Stdout, stderr and descendants
+share one serialized disk budget; crossing writes retain only the permitted prefix.
+The file remains within the cap during foreground collection and termination.
+After foreground collection yields, rejected overflow kills the group and settles
+`OutputLimitExceeded` after confirmed cleanup. Spool setup failure refuses launch
+with `SpawnFailed`. Drained pipe/PTY output instead keeps running with bounded
+retained bytes and omissions.
+Unix PTY resize uses the retained portable-pty master; Windows PTY uses ConPTY.
+Windows pipe and ConPTY commands start suspended and enter a kill-on-close Job Object
+before resume. Failed containment refuses execution, with no unsupervised spawn fallback.
+Cleanup must be confirmed; failures retain diagnostic resources rather than reporting reaping.
+Native Windows legacy WSL `bash.exe` stdin transport remains refused for owned launch:
+Windows jobs cannot supervise the Linux guest process tree. Atomic running inside WSL
+uses the normal POSIX/Bash path instead.
+
+Bash tools and `createLocalBashOperations` accept a trusted `taskOwner` binding.
+On Unix and native Windows, that binding obtains pipe/PTY processes through supervised admission,
+preserving configured shell arguments, cwd, environment and existing authorization.
+Foreground collection honors the owner's command wait configuration, including
+`until-settled`; the automatic default is 10000 ms. A yielded process stays owned
+and its retained output remains readable. Bash output inserts explicit
+`[Output omitted: bytes start-end]` markers, with an exclusive end offset, between
+retained chunks rather than silently joining gaps. Without that binding, existing
+bash and native PTY execution are unchanged. No UI is added.
+
+`watchOwnerTasks(owner, cursor?)` provides an opaque `lease`, snapshot,
+decimal-string cursor and disposable `AsyncIterable<NativeEvent>`. Each iterator
+observes one contiguous delivery epoch. On local backlog overflow or native journal
+reset, the subscription updates its authoritative `snapshot` and `cursor`, discards
+stale queued deltas, and completes the old iterator (`next()` returns `done:true`,
+including an already-pending read). This also works when an oversized final settlement
+leaves no retained event, without later activity or cleanup. No synthetic reset event
+is inserted and the `NativeEvent` and subscription types are unchanged.
+
+After any iterator completion, reconcile `subscription.snapshot` at
+`subscription.cursor`. If the owner is still live and observation is still wanted,
+obtain another iterator from the **same** `subscription.events`; the old iterator stays
+done. Reset does not dispose the subscription or close the owner. Subsequent deltas
+are authentic and ordered; ignore events at or below an already-applied snapshot
+cursor. Explicit `dispose()` (idempotent) or breaking out of a live iterator ends
+observation, not the owner. Owner closure also ends delivery. Track your own disposal
+when deciding whether to resume. New subscriptions are refused once owner closing
+begins; existing subscriptions continue through cleanup/closure.
+Calling `dispose()` from `onReconcile` also stops the active drain from publishing
+its retained events. Pending and newly created iterators finish without those events;
+the reconciled snapshot remains available.
+
+The optional `subscription.onReconcile` callback is a convenience, not required for
+correctness; callback exceptions remain visible as `subscription.failure`. Raw strings
+and Error messages are preserved; unprintable values (including hostile conversion or
+revoked proxies) use `Unprintable JavaScript rejection`. Diagnostic conversion cannot
+interrupt event delivery or rearming the fallback poll. Native callbacks are wake hints;
+journal drains and reset snapshots are authoritative. Each live subscription has one
+fallback poll, stopped on disposal or observed closure.
+The native byte journal and facade delivery backlog are bounded. Each task separately
+retains its most recent 256 accepted activity report IDs, SHA-256 payload hashes and
+receipts (`TASK_REPORT_IDENTITY_WINDOW`). Within that window, identical payloads return
+`duplicate` with the original cursor; conflicting payloads return `ReportConflict`.
+Neither check emits events or refreshes retention order. An evicted ID is fresh: while
+the task is live it is `accepted`, applies its activity again and gets a new cursor;
+existing terminal and owner-close guards still apply. Terminal outcome reports and
+their recorded receipts are retained separately for the task record's lifetime and
+never evicted by activity churn. This bounds identity entry count, not caller ID length,
+task count, terminal payloads or total task-history memory. S1 adds no persistence layer.
+
+Activity IDs have no reserved spellings, including `runner-outcome`, empty strings
+and isolated surrogates. The facade submits its own result through private trusted
+runner support: the actor selects a free terminal identity and accepts the outcome
+under the same lock. With at most 256 retained activity IDs, at most 257 distinct
+candidates suffice; selection emits no events and retains no extra ID history.
+Caller-supplied reports still use the unchanged `reportTaskOutcome` contract:
+same-ID cross-kind reports conflict, and terminal replay retains its original receipt.
+The internal support also reuses an accepted terminal identity, so a different result
+cannot replace it; cancellation-first still rejects late natural outcomes. Normal,
+rejected and setup-failure results all use this path without bypassing cleanup evidence.
+
+Caller-provided strings retain their exact JavaScript UTF-16 code units, including
+isolated surrogates, valid pairs and embedded NUL, across scopes, intent, operation/report
+identity, activity, results and nested output/cleanup metadata. They remain ordinary
+`string` fields, not encoded wrappers. Replacing a surrogate with U+FFFD is a changed
+payload or identity, never an exact replay. Nonempty descriptions supply the title;
+otherwise the first nonblank task line is copied without rewriting its code units,
+falling back to the agent name. Absent optional fields, empty strings, known zero metrics
+and ordered duplicate data remain distinct. The optional `elapsedMs`, `toolCount` and `tokenCount` metrics and
+completed/failed `exitCode` preserve JavaScript numbers without narrowing or normalization,
+including fractional and extreme values. Within the retained activity window (and for
+terminal reports throughout the task record's lifetime), exact replay distinguishes
+omission, zero and negative zero; repeated NaN and infinite values acknowledge once.
+Changed numeric payloads return `ReportConflict` without earning another event. `OutputRef` is
+metadata, not proof of retained bytes: output
+storage, `readTaskOutput`, command input, persistence, completion delivery and
+real agent/Intercom integration belong to later slices. The credential-free
+repository fixture `test/fixtures/task-s1-demo.ts` exercises this real facade and
+native actor with one fake runner.
+
+### Task transcript references
+
+An admitted runner can call `context.bindTranscript(sessionManager)` with its existing
+child session history. `readTaskTranscript(task, cursor?)` in `core/tasks/transcript.ts`
+reads that binding through the task capability. It returns message and content-block
+references, not copied text: `id`, `kind`, `source`, and `toolCallId` when applicable.
+Kinds are `prompt`, `assistant`, `tool-call`, `tool-result`, and `response`.
+Thinking blocks and non-conversation entries are excluded. Repeated source IDs are
+deduplicated; repeated messages with different IDs remain distinct.
+
+The first page contains up to 100 recent references in source order. Pass the opaque
+`nextCursor` to read earlier references; `omittedEarlier` identifies remaining older
+content. Cursors belong to one task and bound session. An unknown task returns
+`UnknownTask`, a cursor from another task/session returns `ScopeMismatch`, and an
+unbound or empty history returns `TranscriptUnavailable` with `Transcript unavailable`.
+This adapter does not launch work or reconstruct live capabilities from history.
+Production subagent runners bind their child history, and main and attached workflow
+chat hosts mount the shared inspector. Command detail reads are scoped to the current
+selection and view lifetime: late results and errors cannot overwrite another view.
+
 ## Quick Start
 
 ```typescript
@@ -161,6 +396,8 @@ interface AgentSession {
 
 `compact()` serializes older context to numbered lines, asks the session model for JSON deleted ranges, validates them, and mechanically reconstructs a durable verbatim transcript string. It appends a `compaction` entry with `details.strategy: "verbatim-lines"`; the recent tail remains ordinary messages. The model never authors replacement context text.
 
+`session.navigateTree()` rejects during streaming, compaction, or branch summarization rather than queueing the navigation. The active branch stays unchanged. Wait for the operation to finish before retrying.
+
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
 ### createAgentSessionRuntime() and AgentSessionRuntime
@@ -599,6 +836,13 @@ Atomic's built-in `bash` tool matches upstream pi: when `bash` is enabled, comma
 
 `createPowerShellTool()` and `createPowerShellToolDefinition()` provide the same tool used by interactive sessions. When their default local operations execute on native Windows, they prefer `pwsh.exe`, fall back to `powershell.exe`, and throw a clear error when neither executable is available. `createLocalPowerShellOperations()` and `getPowerShellConfig()` are also exported for custom integrations. The PowerShell factories expose the current `ATOMIC_*` and legacy `PI_*` session snapshot by default; set `exposeSessionEnvironment: false` to opt out.
 
+PowerShell tools and local operations accept a trusted `taskOwner` binding and the same
+`wait` observation policy as bash. Owned native Windows execution automatically yields
+after the owner's command budget (normally 10000 ms); explicit per-call budgets override it,
+and execution timeout remains separate. Commands use encoded PowerShell transport internally,
+while task descriptions retain the original command text. Without a supported owner,
+explicit background requests are refused and foreground execution waits for completion.
+
 ```typescript
 import { createPowerShellTool } from "@bastani/atomic";
 

package/docs/settings.md

@@ -9,10 +9,14 @@ Atomic uses JSON settings files with project settings overriding global settings
 
 Edit directly or use `/settings` for common options. Choosing a model or thinking level with `/model`, `/thinking`, or their cycling shortcuts automatically saves it as the startup default. Thinking choices also update the active model's saved thinking level. `/scoped-models` saves cycle-list changes automatically. SDK calls, session restoration, and automatic fallbacks do not overwrite these defaults unless persistence is explicitly requested. Atomic also reads legacy `~/.pi/agent/settings.json` and `.pi/settings.json` as compatibility fallbacks, with `.atomic` paths taking precedence.
 
+Saving an Atomic setting applies only the changed fields to the corresponding `.atomic` file; it does not copy untouched fallback fields out of `.pi`. To intentionally override an inherited array such as `packages`, set it in `.atomic`, including an explicit empty array (`"packages": []`) when the inherited list should be disabled.
+
 ## Project Trust
 
 On interactive startup, Atomic asks before trusting a project folder that contains trust-gated project inputs and has no saved decision for the folder or a parent folder in `~/.atomic/agent/trust.json`. Trusting a project allows Atomic to load project-local `.atomic/settings.json` and `.atomic` resources, legacy `.pi/settings.json` and `.pi` resources, project-local context files, install missing project packages, and execute project extensions.
 
+Before a startup trust dialog opens, Atomic binds permitted user/global and explicitly authorized CLI extensions to a trust-safe session. Their existing `ui_prompt_start` / `ui_prompt_end` handlers can observe the wait with a live session context. Project resources and borrowed project-local code remain blocked until authorized. Approval finishes startup in the same session without reloading those reporters; isolated interactive sessions ask through the engine's RPC-backed host UI. This requires no model request.
+
 Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore trust-gated project inputs, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
 
 If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.atomic/agent/settings.json`, or change it with `/settings`.
@@ -21,12 +25,20 @@ If no extension or saved decision applies, `defaultProjectTrust` controls the fa
 
 Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.atomic/agent/trust.json` only; the current session is not reloaded, so restart Atomic for changes to take effect.
 
-If a bare directory starts without trust-gated inputs, Atomic may run the interactive session as implicitly trusted. Inert state directories such as `.atomic/todos/` and `.atomic/sessions/` do not require trust and do not disable deferred resource startup. On the normal interactive TTY fast path, Atomic paints the shell and makes the input editor responsive before scanning bundled extension packages, skills, prompts, themes, context files, and system-prompt files. After the input handler is ready, Atomic starts extension/resource loading in the background. If the first submitted prompt arrives before that loading settles, Atomic keeps the prompt spinner visible and waits at the readiness gate before calling the model so extension tools, prompt templates, skills, resources, and extension-registered provider updates are available on that first turn. Deferred loading uses async discovery and cooperative yields around resource-loading work, so visible typing, Enter, Ctrl+C, rendering, and the normal prompt spinner remain responsive while the background work finishes. Startup does not show a resource-loading spinner before the user submits a prompt. Explicit provider/model selection, explicit resource flags, system-prompt inputs, metadata commands, non-TTY modes, and unresolved project-trust prompts stay on the synchronous path because those operations need complete resources before the session is created. When resources finish loading, Atomic shows the normal resources disclosure so newly added skills, prompts, themes, and extensions are visible. If trust-requiring config appears later, Atomic prompts again on the next launch until you explicitly save a persistent trust decision; the only automatic persistence of implicit startup trust is the existing `/reload` flow after reload discovers trust-requiring resources in an already-trusted session.
+If a bare directory starts without trust-gated inputs, Atomic may run the interactive session as implicitly trusted. Inert state directories such as `.atomic/todos/` and `.atomic/sessions/` do not require trust and do not disable deferred resource startup. On the normal interactive TTY fast path, Atomic paints the shell and makes the input editor responsive before scanning bundled extension packages, skills, prompts, themes, context files, and system-prompt files. After the input handler is ready, Atomic starts extension/resource loading in the background. If the first submitted prompt arrives before that loading settles, Atomic keeps the prompt spinner visible and waits at the readiness gate before calling the model so extension tools, prompt templates, skills, resources, and extension-registered provider updates are available on that first turn. Deferred loading uses async discovery and cooperative yields around resource-loading work, so visible typing, Enter, Ctrl+C, rendering, and the normal prompt spinner remain responsive while the background work finishes. Startup does not show a resource-loading spinner before the user submits a prompt. Explicit provider/model selection, explicit resource flags, system-prompt inputs, metadata commands, and non-TTY modes normally use eager resource loading; interactive trust authorization instead uses the trust-safe session described above before completing approved resources and model selection. When resources finish loading, Atomic shows the normal resources disclosure so newly added skills, prompts, themes, and extensions are visible. If trust-requiring config appears later, Atomic prompts again on the next launch until you explicitly save a persistent trust decision; the only automatic persistence of implicit startup trust is the existing `/reload` flow after reload discovers trust-requiring resources in an already-trusted session.
 
 Settings and trust JSON files may start with a UTF-8 BOM, as commonly written by older Windows tools; Atomic strips that leading marker before parsing.
 
 ## All Settings
 
+### Herdr
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `herdr.enabled` | boolean | `true` | Enable the built-in reporter in an eligible Herdr pane. Set to `false`, then reload or restart to opt out. Requires `mode: "tui"`, a UI, and the Herdr environment variables. Child sessions and other modes never claim. |
+
+See [Herdr](/herdr) for state aggregation, reporter conflicts, privacy, and Herdr 0.8.2 limitations.
+
 ### Model & Thinking
 
 | Setting | Type | Default | Description |
@@ -294,8 +306,8 @@ When `images.autoResize` is enabled, Atomic normalizes images before sending the
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows) |
-| `shellCommandPrefix` | string | - | Prefix for every bash command (e.g., `"shopt -s expand_aliases"`) |
+| `shellPath` | string | - | Custom Bash path (e.g., for Cygwin on Windows); does not select the PowerShell used by native Windows `!`/`!!` or the interactive subshell |
+| `shellCommandPrefix` | string | - | Prefix for shell commands, including `!`/`!!`; use PowerShell syntax for native Windows interactive commands and Bash syntax elsewhere (e.g., `"shopt -s expand_aliases"`) |
 | `bashInterceptor.enabled` | boolean | `false` | When true, block shell commands that have dedicated tools and offer remaining `bash` tool calls to `user_bash` extension handlers before local execution. Also available in `/settings` as **Bash Interceptor**. |
 | `search.contextBefore` | number | `1` | Number of context lines before each `search` match. |
 | `search.contextAfter` | number | `3` | Number of context lines after each `search` match. |