@bastani/atomic 0.9.18 → 0.9.19-alpha.10

package/docs/usage.md

@@ -1,7 +1,16 @@
+---
+title: "Interactive use"
+description: "Interactive mode, slash commands, the message queue, sessions, and context files."
+---
+
 # Using Atomic
 
 This page collects day-to-day usage details that do not fit on the quickstart page.
 
+## On this page and its reference
+
+This page covers interactive use: the interactive loop, slash commands, the message queue, sessions, context files, and the design principles behind them. Every command, flag, argument, and environment variable now lives in the [CLI reference](/reference/cli).
+
 ## Interactive Mode
 
 <p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600" /></p>
@@ -37,6 +46,14 @@ While ordinary agent work is active, the exact one-cell `∀` remains visible an
 
 See [Keybindings](/keybindings) for all shortcuts and customization.
 
+On native Windows, `!` and `!!` execute PowerShell (preferring `pwsh.exe`, then `powershell.exe` on `PATH`). Linux, macOS, and WSL use Bash. Extension-provided execution operations still take precedence. `shellCommandPrefix` is still prepended, so use syntax matching the selected shell; `shellPath` configures Bash, not Windows interactive PowerShell. Escape or Ctrl+C cancels a running command. `!!` output remains excluded from model context.
+
+On Windows, ALT+Z lends the terminal to an interactive PowerShell subshell. Type `exit` to return to the same Atomic session; owned background tasks keep running. CTRL+Z remains editor undo. On POSIX systems, CTRL+Z suspends Atomic and `fg` resumes it.
+
+## Startup typing
+
+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.
+
 ## Slash Commands
 
 Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
@@ -47,7 +64,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/model` | Switch models and automatically save the startup default |
 | `/thinking` | Switch thinking level and automatically save the startup default |
 | `/scoped-models` | Enable/disable models for CTRL+P cycling |
-| `/workflow` | List/run workflows; manage runs (connect/inspect/pause/interrupt/quit/resume); reload workflow resources |
+| `/workflow` | List/run workflows; manage runs (connect/inspect/pause/quit/resume); reload workflow resources |
 | `/settings` | Theme, message delivery, transport, and other preferences |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
@@ -141,251 +158,55 @@ Treat exported and shared sessions as sensitive: transcripts can contain source
 
 ## CLI Reference
 
-```bash
-atomic [options] [@files...] [messages...]
-```
-
-Use `--` to end option parsing when positional prompt text begins with `-`, `--`, or `@`. Every argument after the terminator is treated as literal message text rather than an option or file argument:
-
-```bash
-atomic --print -- "- leading-dash prompt"
-```
+Moved to [CLI reference](/reference/cli#cli-reference).
 
 ### Package Commands
 
-```bash
-atomic install <source> [-l]       # Install package, -l for project-local
-atomic remove <source> [-l]        # Remove package
-atomic uninstall <source> [-l]     # Alias for remove
-atomic update [source|self|atomic] # Update Atomic only, or one package source
-atomic update --all                # Update Atomic and packages; reconcile pinned git refs
-atomic update --extensions         # Update packages only; reconcile pinned git refs
-atomic update --models             # Force-refresh authenticated provider model catalogs
-atomic update --self               # Update Atomic only
-atomic update --extension <src>    # Update one package
-atomic list                        # List installed packages
-atomic config                      # Enable/disable package resources
-```
-
-These commands manage Atomic packages and `atomic update` can update the Atomic CLI installation. To uninstall Atomic itself, see [Quickstart](/quickstart#uninstall). `atomic config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `atomic update` never prompts for project trust.
-
-See [Atomic Packages](/packages) for package sources and security notes.
+Moved to [CLI reference](/reference/cli#package-commands).
 
 ### Credential Commands
 
-```bash
-atomic auth check [--provider <p>] [--model <model>] [--json] [--credentials] [--no-refresh]
-atomic auth print-api-key --model <model> [--provider <p>]
-atomic auth print-bearer-token --model <model> [--provider <p>] [--min-expiry <dur>]
-```
-
-`atomic auth check` verifies the effective credential a provider or model would use before a session starts. It requires at least one of `--provider` or `--model`, prints `ready`, `not_ready`, or `invalid` to stdout, and exits `0`, `1`, or `2` for those states. `--json` adds the resolved provider when one is found, credential kind, and any reason. By default, a check never emits credential material.
-
-`--credentials` is an explicit export opt-in. It requires `--provider` or an exact `--model` target; a fuzzy model match on an otherwise-ready provider is refused as `invalid` (exit `2`) rather than exporting a credential for a provider you did not name. If that provider is not ready, the check remains `not_ready` (exit `1`). On a ready check, plain stdout becomes the resolved credential alone and JSON adds it only in the `credentials` field. A non-ready raw export leaves stdout empty and reports its status on stderr; a JSON export returns the status object without a credential. Credential writes can also exit `8` (nothing written) or `9` (only a fragment written). Treat the stream like `print-api-key` or `print-bearer-token` output.
-
-Checks refresh expired OAuth credentials by default, using Atomic's normal locked `auth.json` update path. Pass `--no-refresh` to read credentials without creating, locking, or mutating `auth.json`; this is useful when a probe must not change stored auth state. It still reads Atomic's primary and legacy credential paths and resolves configured API-key values, including `!command`, through the normal provider configuration. In this read-only mode, malformed `auth.json` is `invalid` (exit `2`) rather than an unavailable credential. An OAuth credential export requires at least 30 minutes of life: the normal path can refresh it, while `--no-refresh` refuses a shorter-lived token.
-
-The credential commands print one configured credential for an external client — a proxy, a script, or another tool that needs the same key Atomic already holds. The credential goes to **stdout and nothing else**; warnings, provider selection, refresh notices, and help all go to stderr, so `KEY=$(atomic auth print-api-key --model gpt-5.5)` can never capture a diagnostic.
-
-`--model` is required for the two `print-*` exports. An exporting auth check needs `--provider` or an exact `--model` target. When several configured providers offer a model, pass `--provider` to choose one. The two `print-*` subcommands accept only `--provider` and `--model`: any other flag — including `--export`, `--session-dir`, `--print`, and `--help` — is a usage error rather than a flag this path happens to ignore.
-
-`atomic auth` on its own — and `atomic auth help`, `--help`, or `-h` — prints this usage on stderr and exits `0`. `atomic auth check --help` (or `-h`) does the same until a `--` terminator; after it, the flag is not help. Any other subcommand exits `1` and names all three valid commands. Help never uses stdout, so raw credential export stdout is a credential or empty; a JSON export writes an object that carries a credential only in its `credentials` field.
-
-`print-bearer-token` works only on OAuth providers and `print-api-key` only on API-key providers; asking for the wrong kind is an error rather than a silent fallback. A bearer token with less than `--min-expiry` remaining (default `30m`, accepting `ms`, `s`, `m`, or `h`) is refreshed first. Both `--min-expiry 30m` and `--min-expiry=30m` are accepted. `--min-expiry` with `print-api-key` is a usage error — even after a `--` terminator — because an API key has no expiry. A failed refresh leaves your stored credential untouched.
-
-Credential-export exits (`print-api-key`, `print-bearer-token`, and the `--credentials` write itself):
-
-| Exit | Meaning |
-|------|---------|
-| `0` | Credential written to stdout, one trailing newline |
-| `1` | Usage error |
-| `2` | No credential configured for that model/provider |
-| `3` | Several configured providers match — pass `--provider` |
-| `4` | That credential kind is unsupported for the provider |
-| `5` | OAuth refresh failed; the stored credential is unchanged |
-| `6` | The provider cannot mint a token that lives as long as `--min-expiry` |
-| `7` | The provider's OAuth credential could not be used — no claim is made about the stored credential |
-| `8` | The credential could not be written; nothing was emitted |
-| `9` | Only part of the credential was written; discard the output |
-
-Auth-check exits:
-
-| Exit | `atomic auth check` |
-|------|---------------------|
-| `0` | `ready` |
-| `1` | `not_ready`, including a fuzzy `--model` with `--credentials` when its resolved provider is not ready |
-| `2` | `invalid`, including check usage errors (unknown option, neither `--provider` nor `--model`, and a fuzzy `--model` with `--credentials` when its resolved provider is otherwise ready) |
-| `8` | With `--credentials`, the credential could not be written; nothing was emitted |
-| `9` | With `--credentials`, only part of the credential was written; discard the output |
-
-Exit `5` is reported only for a refresh that itself failed, which happens before anything is persisted; that is the only exit that promises your stored credential is untouched. Any other OAuth failure exits `7` and makes no such promise.
-
-For raw credential exports, stdout is empty on every non-zero exit but one. Once the credential reaches stdout the command has succeeded: if the stream then fails to drain — a reader that closed the pipe, for example — that is reported on stderr and the exit code stays `0`, because a non-zero exit here would contradict the bytes the caller already holds. The exception is exit `9`, which reports that only part of the credential was written before the stream failed; those bytes cannot be recalled, so stdout is not empty, and the output is a fragment to discard rather than a credential to use. `auth check --credentials --json` may instead write a credential-free JSON status object on a non-zero check result. See [Security](/security#credential-export) before wiring this into a script.
+Moved to [CLI reference](/reference/cli#credential-commands).
 
 ### Modes
 
-| Flag | Description |
-|------|-------------|
-| default | Interactive mode (fullscreen TUI) |
-| `-p`, `--print` | Print response and exit |
-| `--mode json` | Output all events as JSON lines; see [JSON mode](/json) |
-| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](/rpc) |
-| `--export <in> [out]` | Export a session to HTML |
-
-Interactive sessions always use fullscreen: the transcript scrolls independently above a sticky dock containing the editor, status line, usage meter, extension widgets, and footer. Wheel and trackpad gestures go first to a focused workflow graph or stage chat overlay; events those overlays do not consume fall through to the alternate-screen viewport. Non-overlay focused components do not block pi-tui's mouse path, so transcript scrolling, scrollbar interaction, and drag selection still work. Selection copies automatically by default; disable `fullscreenCopyOnSelect` to highlight text without copying. Ctrl+X closes workflow tool detail to the graph, clears a scoped-model selection, returns stage chat to its graph, or returns a workflow graph to main chat. It does not copy. `/copy` always copies the last assistant message. The `fullscreenExitOutput` setting controls 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. See [Settings](/settings) and [Terminal setup](/terminal-setup).
-
-In print mode, Atomic also reads piped stdin and merges it into the initial prompt:
-
-```bash
-cat README.md | atomic -p "Summarize this text"
-```
-
-When a print-mode turn correctly finishes by calling an opt-in terminating structured-output tool created with `createStructuredOutputTool` (for example from an extension, SDK caller, or workflow item with a schema), Atomic ends after that tool result without an extra follow-up assistant turn. Print-mode stdout contains the terminating structured JSON payload, so `atomic -p` remains script-friendly while the same value is also available through the SDK `capture` sink, tool `details`, a configured file sink, or workflow `result.structured`. This also works for custom factory names such as `final_decision`. Non-terminating or unrelated tool results are not printed as the final response.
+Moved to [CLI reference](/reference/cli#modes).
 
 ### Model Options
 
-| Option | Description |
-|--------|-------------|
-| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
-| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
-| `--api-key <key>` | API key, overriding environment variables |
-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; model capability mapping still governs availability |
-| `--models <patterns>` | Comma-separated patterns for CTRL+P cycling |
-| `--list-models [search]` | List available models |
+Moved to [CLI reference](/reference/cli#model-options).
 
 ### Session Options
 
-| Option | Description |
-|--------|-------------|
-| `-c`, `--continue` | Continue the most recent session |
-| `-r`, `--resume` | Browse and select a session |
-| `--session <path\|id>` | Use a specific session file or partial UUID |
-| `--session-id <id>` | Use an exact project session ID; warn and create it when missing |
-| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
-| `--session-dir <dir>` | Custom session storage directory |
-| `--name <name>`, `-n <name>` | Set the session display name |
-| `--no-session` | Ephemeral mode; do not save |
+Moved to [CLI reference](/reference/cli#session-options).
 
 ### Tool Options
 
-| Option | Description |
-|--------|-------------|
-| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools; mandatory `intercom` remains available |
-| `--exclude-tools <list>`, `-xt <list>` | Denylist specific built-in, extension, and custom tools; mandatory `intercom` cannot be excluded |
-| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
-| `--no-tools`, `-nt` | Disable every tool except mandatory `intercom` |
-
-Default built-in tools: `read`, `bash`, `edit`, `write`, `find`, `search`, `ask_user_question`, `todo`, plus `powershell` on native Windows when a PowerShell executable is available. `find.paths` accepts directories, files, or glob paths such as `*.ts` and honors `timeout`; `search` accepts `pattern`, optional `paths`, `i`, `gitignore`, and `skip` for regex content-search pagination. Use `--exclude-tools` to disable one or more non-mandatory tools while leaving the rest available, for example `atomic --exclude-tools ask_user_question`. The `defaultTools` setting selects which built-in tools a session starts with; `--tools` replaces that default with a strict allowlist over non-mandatory built-in, custom, and extension tools; `--no-builtin-tools` removes only built-ins; `--no-tools` removes every tool except ordinary bundled `intercom`. `ls` remains available as an SDK compatibility tool but is not enabled by default.
+Moved to [CLI reference](/reference/cli#tool-options).
 
 ### Project Trust Options
 
-| Option | Description |
-|--------|-------------|
-| `--approve`, `-a` | Trust project-local files/resources for this run |
-| `--no-approve`, `-na` | Ignore project-local files/resources for this run |
-
-Project trust gates `.atomic`/legacy `.pi` project resources, project package settings, project-local context files, and `.agents/skills` discovered from the project tree. Saved trust decisions can be managed with `/trust`; see [Security](/security).
+Moved to [CLI reference](/reference/cli#project-trust-options).
 
 ### Resource Options
 
-| Option | Description |
-|--------|-------------|
-| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
-| `--no-extensions`, `-ne` | Disable optional extension discovery; mandatory bundled Intercom remains loaded |
-| `--skill <path>` | Load a skill; repeatable |
-| `--no-skills`, `-ns` | Disable skill discovery |
-| `--prompt-template <path>` | Load a prompt template; repeatable |
-| `--no-prompt-templates`, `-np` | Disable prompt template discovery |
-| `--theme <path>` | Load a theme; repeatable |
-| `--no-themes` | Disable theme discovery |
-| `--no-context-files`, `-nc` | Disable context-file discovery and loading |
-
-Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
-
-```bash
-atomic --no-extensions -e ./my-extension.ts
-```
+Moved to [CLI reference](/reference/cli#resource-options).
 
 ### Other Options
 
-| Option | Description |
-|--------|-------------|
-| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
-| `--append-system-prompt <text>` | Append to system prompt |
-| `--use-theme <name[/name]>` | Set the interactive theme for this run without saving it; see [Themes](/themes#initial-theme) |
-| `--offline` | Disable startup network operations, including update checks, package updates, and telemetry |
-| `--verbose` | Force verbose startup |
-| `-h`, `--help` | Show help |
-| `-v`, `--version` | Show version |
+Moved to [CLI reference](/reference/cli#other-options).
 
 ### File Arguments
 
-Prefix files with `@` to include them in the message:
-
-```bash
-atomic @prompt.md "Answer this"
-atomic -p @screenshot.png "What's in this image?"
-atomic @code.ts @test.ts "Review these files"
-```
+Moved to [CLI reference](/reference/cli#file-arguments).
 
 ### Examples
 
-```bash
-# Interactive with initial prompt
-atomic "List all .ts files in src/"
-
-# Non-interactive
-atomic -p "Summarize this codebase"
-
-# Non-interactive with piped stdin
-cat README.md | atomic -p "Summarize this text"
-
-# Different model
-atomic --provider openai --model gpt-4o "Help me refactor"
-
-# Model with provider prefix
-atomic --model openai/gpt-4o "Help me refactor"
-
-# Model with thinking level shorthand
-atomic --model sonnet:high "Solve this complex problem"
-
-# Limit model cycling
-atomic --models "claude-*,gpt-4o"
-
-# Read-only mode
-atomic --tools read,search,find,ls -p "Review the code"
-```
+Moved to [CLI reference](/reference/cli#examples).
 
 ### Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `AI_AGENT` | Set to `atomic` by the CLI, RPC, and compiled binary entry points and in every Atomic-owned child-process environment so generic tooling can identify Atomic processes; child environments override caller-supplied values without mutating the caller's environment object |
-| `ATOMIC_CODING_AGENT_DIR` | Override config directory; default is `~/.atomic/agent`. Bundled intercom runtime/config files live under its `intercom/` subdirectory |
-| `ATOMIC_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
-| `ATOMIC_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
-| `ATOMIC_REDUCED_MOTION` | Set to `1` to skip startup choreography and render the ordinary working identity as a static regular accent `∀` without a timer |
-| `ATOMIC_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
-| `ATOMIC_SKIP_VERSION_CHECK` | Skip the Atomic version update check at startup. This prevents the latest-version request |
-| `ATOMIC_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
-| `NODE_COMPILE_CACHE` | Override the directory for Node's persistent compile cache, which Atomic enables automatically on Node >= 22.8 to speed up startup (most noticeable on Windows). Set `NODE_DISABLE_COMPILE_CACHE=1` to opt out |
-| `PI_CACHE_RETENTION` | Provider/upstream-specific prompt-cache retention knob; set to `long` where supported |
-| `ATOMIC_NO_PTY` | Set to `1` to disable PTY use for bash commands (`PI_NO_PTY` is a legacy alias) |
-| `VISUAL`, `EDITOR` | External editor for CTRL+G |
-
-Every bash execution runs in the foreground and receives one execution-time snapshot of the active session:
-
-| Atomic variable | Exact compatibility alias | Value |
-|-----------------|---------------------------|-------|
-| `ATOMIC_SESSION_ID` | `PI_SESSION_ID` | Active session ID |
-| `ATOMIC_SESSION_FILE` | `PI_SESSION_FILE` | Active session JSONL path; omitted for unsaved sessions |
-| `ATOMIC_PROVIDER` | `PI_PROVIDER` | Active model provider; omitted when no model is selected |
-| `ATOMIC_MODEL` | `PI_MODEL` | Active model ID; omitted when no model is selected |
-| `ATOMIC_REASONING_LEVEL` | `PI_REASONING_LEVEL` | Active reasoning level |
-
-The snapshot is taken when the command executes, not when the tool is created, so resumed sessions, workflow stages, isolated sessions, model changes, and concurrent sessions cannot reuse stale metadata. Atomic preserves all unrelated inherited and caller-supplied environment variables; only the ten names above are cleared and overlaid. Factory-created bash tools expose the same metadata by default and can set `exposeSessionEnvironment: false` to omit it.
-
-`PI_*` aliases are also supported for app-specific `ATOMIC_*` variables for legacy compatibility. For example, [Intercom](/intercom) honors `PI_CODING_AGENT_DIR` when `ATOMIC_CODING_AGENT_DIR` is unset and still reads legacy `~/.pi/agent/intercom/config.json` when the Atomic config is absent. `PI_CACHE_RETENTION` is not one of those aliases and has no `ATOMIC_*` equivalent. Use `PI_CACHE_RETENTION=long` when configuring prompt-cache retention for providers/upstreams that support long-lived caches. Intercom's default broker starter works across Node-based installs, Bun source checkouts, and standalone Atomic binaries without requiring `npx`, `tsx`, or `bun` to be present on `PATH`; custom broker commands remain explicit opt-in overrides.
+Moved to [CLI reference](/reference/cli#environment-variables).
 
 ## Design Principles
 

package/docs/web-access.md

@@ -0,0 +1,50 @@
+# Fetching web content
+
+Atomic's bundled `fetch_content` tool reads webpages, PDFs, GitHub repositories, YouTube videos, and local video files.
+
+## Arguments
+
+Always pass the lowercase `urls` field as a nonempty array of strings, even for one URL:
+
+```json
+{"urls": ["https://example.com/article"]}
+```
+
+For multiple pages:
+
+```json
+{"urls": ["https://example.com/one", "https://example.com/two"]}
+```
+
+For a video, include the question in `prompt`:
+
+```json
+{"urls": ["/path/to/recording.mp4"], "prompt": "What error appears on screen?"}
+```
+
+For webpages, `urls` is enough. `prompt` and `model` apply to video analysis, not webpage filtering or extraction. `forceClone` applies only to GitHub repositories.
+
+Use `frames` and `timestamp` only when you want images from YouTube or local video files. Omit both for readable text or transcripts. `frames` alone samples the whole video; `timestamp` accepts seconds, a time such as `1:25`, or a range such as `1:25-2:00`.
+
+```json
+{"urls": ["/path/to/recording.mp4"], "timestamp": "1:25-2:00", "frames": 3}
+```
+
+Frame extraction requires ffmpeg, plus yt-dlp for YouTube. Non-video inputs ignore `frames` and `timestamp` and are fetched normally, even in a batch containing videos. Video inputs still validate timestamps and report extraction errors.
+
+Existing prompts or integrations using `{"url": "..."}` must change to `{"urls": ["..."]}`. The singular `url` field is no longer accepted by `fetch_content`. This does not change the `url` selector on `get_search_content`.
+
+Atomic can normalize a scalar `urls` string into a one-item array. Always use the documented array form in prompts and integrations; the legacy `url` field is not normalized.
+
+## Troubleshooting
+
+If argument validation fails, check that:
+
+- The field is `urls`, not `URLs` or `url`.
+- Its value is an array, not a string or an object.
+- The array contains at least one nonempty string.
+- The call has no unrecognized fields.
+
+If every URL in a batch fails, the error lists each URL and its cause. Extraction errors may still include partial content, shown as incomplete excerpts. Check the URLs and retry transient failures individually with `fetch_content({ urls: ["<failed URL>"] })`. For blocked pages or repeated extraction failures, try an accessible alternate URL or use `web_search`. `get_search_content` cannot recover missing content from a failed fetch.
+
+When fetched content is truncated, follow the returned `get_search_content` call to retrieve the stored content.

package/docs/windows.md

@@ -20,15 +20,15 @@ Every attempt removes its own `atomic-install-*` staging directory under the Win
 
 After the script is fetched, it enables TLS 1.2 for its own GitHub requests and restores the caller's prior protocol setting. A downloaded script cannot repair the connection used to fetch itself: on a legacy Windows PowerShell 5.1 host where the literal `irm` command cannot reach GitHub, enable TLS 1.2 in that shell before rerunning the same one-liner.
 
-The installer adds the bin directory to the User PATH and the current PowerShell process. Restart the terminal when it finishes so other processes see the new PATH. A custom `ATOMIC_BIN_DIR` containing `;` cannot be one Windows PATH entry, so the installer leaves PATH untouched and prints a direct-run command for `atomic.cmd` instead. If the bin directory already holds a same-stem launcher that `PATHEXT` resolves before `atomic.cmd`, such as a stale `atomic.exe` from an older Node-based install, the installer reports it and stops before downloading anything; remove that entry and rerun. Because the shim is `atomic.cmd`, `PATHEXT` must include `.CMD` for bare `atomic` to resolve; if it does not, the installer says so and stops rather than reporting a success you could not use. An unexpected regular `current` entry under `ATOMIC_INSTALL_DIR`, or a regular `atomic-current` entry under `ATOMIC_BIN_DIR`, is reported and left untouched instead of being moved or deleted. A pinned `-Ref` is honored literally: if GitHub answers with a different release tag, the install stops before downloading anything. Package-manager installation remains available but requires Node.js; see the [Quickstart](/quickstart#package-managers).
+The installer adds the bin directory to the User PATH and the current PowerShell process. Restart the terminal when it finishes so other processes see the new PATH. A custom `ATOMIC_BIN_DIR` containing `;` cannot be one Windows PATH entry, so the installer leaves PATH untouched and prints a direct-run command for `atomic.cmd` instead. If the bin directory already holds a same-stem launcher that `PATHEXT` resolves before `atomic.cmd`, such as a stale `atomic.exe` from an older Node-based install, the installer reports it and stops before downloading anything; remove that entry and rerun. Because the shim is `atomic.cmd`, `PATHEXT` must include `.CMD` for bare `atomic` to resolve; if it does not, the installer says so and stops rather than reporting a success you could not use. An unexpected regular `current` entry under `ATOMIC_INSTALL_DIR`, or a regular `atomic-current` entry under `ATOMIC_BIN_DIR`, is reported and left untouched instead of being moved or deleted. A pinned `-Ref` is honored literally: if GitHub answers with a different release tag, the install stops before downloading anything. Package-manager installation remains available but requires Node.js; see the [Quickstart](/getting-started/installation#package-managers).
 
-By default, Atomic uses a Bash shell for the `bash` tool and `!`/`!!` shortcuts. If you use those surfaces, Atomic checks these locations in order:
+Atomic uses a Bash shell for the `bash` tool. For that tool, Atomic checks these locations in order:
 
 1. Custom path from `~/.atomic/agent/settings.json` (legacy `~/.pi/agent/settings.json` also supported)
 2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
 3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
 
-For users who want the default Bash surfaces, [Git for Windows](https://git-scm.com/download/win) is sufficient. Native Windows users can instead enable the optional PowerShell tool described below; `!`/`!!` remain Bash-only.
+For the Bash tool, [Git for Windows](https://git-scm.com/download/win) is sufficient. Native Windows `!`/`!!` shortcuts instead use PowerShell, preferring `pwsh.exe` and falling back to `powershell.exe` on `PATH`. They do not use `shellPath`; any `shellCommandPrefix` must use PowerShell syntax. WSL remains Bash-based.
 
 ## Custom Shell Path
 
@@ -47,7 +47,8 @@ Atomic mounts the themed startup identity and focused editor before waiting for
 
 The isolated engine binds a mandatory minimal runtime first, with Intercom available, then stages bundled workflows, subagents, MCP, web access, optional tools, provider overrides, skills, prompts, and themes. Prompt dispatch, extension commands, model/resource commands, session replacement, and tool-aware RPC operations wait for a generation-scoped resource-ready gate. After a failure, `/reload` starts a fresh transactional resource attempt instead of waiting forever on the rejected gate. `session_start` messages wait too. A failed transactional candidate does not publish host-managed settings, providers, tools, resources, event subscriptions, or system-prompt state. Extension-owned session-scoped objects remain shared by design and are not rolled back.
 
-The same source path is used for package-manager and release-archive builds. Node installs retain Node's persistent compile cache and its `NODE_DISABLE_COMPILE_CACHE=1` coverage opt-out. Release builds syntax-minify the shared application sidecar without shortening identifiers and compile the launcher with bytecode on Windows x64 and ARM64, matching Linux and macOS — but Bun 1.4.0 Windows bytecode launchers must be compiled on a Windows host. Despite the embedded-bytecode alignment fix ([#26299](https://github.com/oven-sh/bun/pull/26299)) and integrity fallback ([#31961](https://github.com/oven-sh/bun/pull/31961)), the same compile cross-run from a non-Windows host produces an executable that segfaults before user code runs, even on `--version`: the 0.9.18-alpha.1 payload was built on Linux, so the shipped Windows launcher crashed while the Windows-hosted smoke build passed. `publish.yml` therefore builds both Windows archives on the Windows runner and the Linux release-payload job runs `build-binaries.sh --skip-windows`. The pinned Bun 1.4.0 probe cross-compiles `bun-windows-x64-baseline` and `bun-windows-arm64` launchers and verifies their PE machine types. Cross-compilation does not prove runtime compatibility, so release validation must still exercise the full archive, TUI, workflows, tools, extensions, workers, and native add-ons on Windows x64 and real Windows ARM64 hardware. No measured Windows speedup is claimed yet.
+The same source path is used for package-manager and release-archive builds. Node installs retain Node's persistent compile cache and its `NODE_DISABLE_COMPILE_CACHE=1` coverage opt-out. Release builds syntax-minify the shared application sidecar without shortening identifiers and compile the launcher with bytecode on Windows x64 and ARM64, matching Linux and macOS — but Windows bytecode launchers must still be compiled on a Windows host, preserving the safeguard from Bun 1.4.0. Despite the embedded-bytecode alignment fix ([#26299](https://github.com/oven-sh/bun/pull/26299)) and integrity fallback ([#31961](https://github.com/oven-sh/bun/pull/31961)), the same compile cross-run from a non-Windows host produced an executable that segfaulted before user code ran, even on `--version`: the 0.9.18-alpha.1 payload was built on Linux, so the shipped Windows launcher crashed while the Windows-hosted smoke build passed. `publish.yml` therefore builds both Windows archives on the Windows runner and the Linux release-payload job runs `build-binaries.sh --skip-windows`. The pinned Bun 1.4.2 probe cross-compiles `bun-windows-x64-baseline` and `bun-windows-arm64` launchers and verifies their PE machine types. Cross-compilation does not prove runtime compatibility, so release validation must still exercise the full archive, TUI, workflows, tools, extensions, workers, and native add-ons on Windows x64 and real Windows ARM64 hardware. No measured Windows speedup is claimed yet.
+
 ## Filesystem Watchers
 
 On Windows, Atomic canonicalizes paths before starting native filesystem watchers. If a watcher target cannot be canonicalized or still contains an unsafe 8.3 short-name component such as `USERNA~1`, Atomic avoids native `fs.watch` for that target and uses polling where the feature supports it. This protects long-running sessions, footer git status refreshes, and custom theme reloads from Windows/libuv path-prefix assertion crashes.
@@ -62,7 +63,7 @@ If Atomic cannot safely self-update the current installation, it exits with a cl
 
 ### PowerShell tool
 
-On native Windows, Atomic registers the `powershell` tool by default when PowerShell 7 (`pwsh.exe`) or Windows PowerShell (`powershell.exe`) is on `PATH`. If neither executable is available, the tool is omitted so the agent is not offered a command that cannot run. Add `powershell` to `defaultTools` to enable it explicitly when you want it active alongside a narrower built-in selection. The `bash` tool and `!`/`!!` shortcuts continue to use Bash. Both `ATOMIC_*` and legacy `PI_*` session variables are available.
+On native Windows, Atomic registers the `powershell` tool by default when PowerShell 7 (`pwsh.exe`) or Windows PowerShell (`powershell.exe`) is on `PATH`. If neither executable is available, the tool is omitted so the agent is not offered a command that cannot run. Add `powershell` to `defaultTools` to enable it explicitly when you want it active alongside a narrower built-in selection. The `bash` tool continues to use Bash; `!`/`!!` use PowerShell. Both `ATOMIC_*` and legacy `PI_*` session variables are available.
 
 PowerShell calls are rendered in the transcript with a `PS>` prompt so they are never mistaken for Bash, and truncated PowerShell output is spilled to its own `atomic-powershell-*` temp file rather than the Bash one.
 

package/docs/workflows/api-reference.md

@@ -1,3 +1,8 @@
+---
+title: "API reference"
+description: "Exhaustive workflow, stage, and context contracts."
+---
+
 # Workflow API Reference
 
 Use this reference while authoring definitions or integrating the workflow SDK programmatically. For a continuous first workflow, start with [Custom Workflow Authoring](/workflows/authoring).
@@ -405,7 +410,7 @@ ctx.tool<TValue extends WorkflowSerializableValue>(
 
 Runs arbitrary TypeScript code as a tracked, non-attachable durable workflow graph node and caches its serializable result by call order plus the content hash of `name` and `args`. The node is created before `fn` runs and may appear before, between, after, or without model stages. A completed call replays without rerunning `fn`, so use this primitive for workflow-owned durable side effects; keep pure computation as ordinary TypeScript.
 
-**Cancellation and deadlines.** Every callback receives a `WorkflowToolContext` whose `signal` aborts when the run is cancelled, when the run is gracefully quit, or when this single node is aborted with `workflow({ action: "quit"|"interrupt", runId, stageId: "<tool node id or name>" })`. Forward it to `fetch`, a child process, or any client that accepts an `AbortSignal` so a stuck call can be stopped:
+**Cancellation and deadlines.** Every callback receives a `WorkflowToolContext` whose `signal` aborts when the run is cancelled, when the run is gracefully quit, or when this single node is aborted with `workflow({ action: "quit"|"pause", runId, stageId: "<tool node id or name>" })`. Forward it to `fetch`, a child process, or any client that accepts an `AbortSignal` so a stuck call can be stopped:
 
 ```ts
 await ctx.tool(
@@ -432,7 +437,7 @@ Callbacks that spawn child processes or perform network I/O need an explicit `ti
 
 With `timeoutMs`, each retry receives a fresh signal and deadline. Run cancellation and operator abort remain cancellation rather than timeout, and a callback that completes before its deadline is unchanged. Omitting `timeoutMs` keeps the existing unbounded callback path.
 
-See [`ctx.tool` — durable cached tool execution](/workflows/operations#ctxtool--durable-cached-tool-execution) for durable failure replay, process-output safety, explicit repair handoffs, and cancellation behavior.
+See [`ctx.tool` — durable cached tool execution](/workflows/operations#ctx-tool-—-durable-cached-tool-execution) for durable failure replay, process-output safety, explicit repair handoffs, and cancellation behavior.
 
 ### `ctx.exit(options?)`
 
@@ -454,7 +459,7 @@ interface WorkflowExitOptions<TOutputs extends WorkflowOutputValues = WorkflowOu
 
 Intentionally ends the current run from any call depth. `status` defaults to `"completed"`; `failed` exits default to `resumable: false`, and `resumable: true` keeps the durable run eligible for a later retry. Supplying `resumable` with another status records a non-resumable authoring failure. The runtime persists and displays `reason`, and `outputs` may provide only declared, schema-valid, serializable output keys.
 
-See [Early exit with `ctx.exit()`](/workflows/authoring#early-exit-with-ctxexit) for snapshotting, cleanup, replay, and race semantics.
+See [Early exit with `ctx.exit()`](/workflows/authoring#early-exit-with-ctx-exit) for snapshotting, cleanup, replay, and race semantics.
 
 ## Task and Stage Options
 
@@ -527,6 +532,8 @@ readonly fallbackThinkingLevels?: readonly string[];
 
 Request/context incompatibility also advances it, including HTTP 400/413/422 bad, unprocessable, or payload-too-large requests; unsupported tools or parameters; context-length or context-window overflow; and `too large`, `invalid_request`, or `bad_request` errors. This lets the chain reach the current selected user model when no configured candidate can serve the request.
 
+If extension initialization fails and its session cannot be cleaned up, the stage stops without trying another model. Later prompts or attachment attempts on that stage also fail. Inspect both the initialization and cleanup errors and resolve the extension failure before starting a new run; changing fallback models does not fix a cleanup failure.
+
 A context overflow that the stage session's compaction has already failed to resolve is terminal for its candidate: it skips the same-candidate retry, because re-sending an identical request cannot fit a context compaction could not shrink, and advances straight to the next candidate.
 
 A schema-backed stage advances the chain for one more reason. Each candidate gets the stage prompt plus up to three corrective follow-ups to produce a valid `structured_output` call. A candidate that spends that whole budget without one has failed the stage even though every turn returned cleanly, so it fails over exactly like a rate-limited candidate: its attempts are recorded as failures carrying the structured-output error, a `[fallback]` warning is recorded, its session is disposed, and the next candidate receives the original stage prompt with a fresh correction budget. A capture that already succeeded is never retried on another model. When no candidate remains, the stage still fails with the structured-output contract error and every exhausted candidate's attempts are recorded as failures.
@@ -571,7 +578,7 @@ readonly excludedTools?: readonly string[];
 
 `tools` is an allowlist across built-in and bundled extension tools. `excludedTools` and `noTools: "all"` still win for every tool except mandatory ordinary `intercom`, which remains registered and active.
 
-The bundled `subagent` tool is available by default on the same terms as main chat. A workflow stage is a top-level session, so it may delegate once; the children it launches may not delegate or control another child. Delegation is exactly one level deep and nothing configures it — there is no config option, agent frontmatter field, or tool parameter for the level. The in-process admission door carries each child's issued depth in its typed child policy, the executor refuses any launch or `interrupt` from a session that was itself admitted as a child, and the Rust `SubagentControl` admission door refuses a child deeper than the single permitted level. That depth is never carried through process environment. Bundled subagent definitions from `@bastani/subagents` are available to that tool. Explicitly list tools such as `subagent`, `web_search`, `fetch_content`, or `intercom` when using an allowlist; in-process child sessions load the bundled resources while suppressing the workflow extension lifecycle.
+The bundled `subagent` tool is available by default on the same terms as main chat. A workflow stage is a top-level session, so it may delegate once; the children it launches may not delegate or control another child. Delegation is exactly one level deep and nothing configures it: there is no config option, agent frontmatter field, or tool parameter for the level. The in-process admission door carries each child's issued depth in its typed child policy, the executor refuses any launch or `kill` from a session that was itself admitted as a child, and the Rust `SubagentControl` admission door refuses a child deeper than the single permitted level. That depth is never carried through process environment. Bundled subagent definitions from `@bastani/subagents` are available to that tool. Explicitly list tools such as `subagent`, `web_search`, `fetch_content`, or `intercom` when using an allowlist; in-process child sessions load the bundled resources while suppressing the workflow extension lifecycle.
 
 Workflow stages use the same upstream-compatible `bash` tool as normal Atomic sessions. Enabled commands run through the configured shell with the stage process permissions. There is no command-text allow/deny option: expose or hide shell access with these tool fields, prefer narrow custom tools for repeatable operations, and use a container, VM, or other sandbox for stronger isolation.
 
@@ -602,7 +609,7 @@ readonly schema?: TSchema;
 
 Enables a schema-specific, single-use final-answer tool for that item. `ctx.stage`, `ctx.task`, `ctx.chain`, and `ctx.parallel` items accept a TypeBox schema or a plain JSON Schema descriptor object. The schema may describe an object, array, or primitive, and the captured JSON value becomes the schema-backed `stage.prompt(...)` result or `WorkflowTaskResult.structured`; task text remains formatted JSON for handoffs.
 
-A schema-backed `StageContext` supports one `prompt()` call, so create another stage for another structured prompt. Missing or invalid `structured_output` calls receive up to three corrective follow-ups quoting the contract error and reminding the model to call `structured_output` instead of replying with plain JSON. That budget is per model candidate: a candidate that spends the initial prompt and all three follow-ups without a valid call is treated as a failed candidate and the stage advances to the next entry in [`fallbackModels`](#fallbackmodels--fallbackthinkinglevels), which receives the original stage prompt and its own fresh budget. The recorded attempt error names what the turn actually looked like — no assistant message after the prompt, an assistant message with empty text, or the `structured_output` validation error — so a repeated external cause is attributable. With no fallback candidate left, the stage fails with the contract error rather than completing. An explicit tool allowlist automatically receives the final-answer tool, while items without `schema` do not.
+A schema-backed `StageContext` supports one `prompt()` call, so create another stage for another structured prompt. Missing or invalid `structured_output` calls receive up to three corrective follow-ups quoting the contract error and reminding the model to call `structured_output` instead of replying with plain JSON. That budget is per model candidate: a candidate that spends the initial prompt and all three follow-ups without a valid call is treated as a failed candidate and the stage advances to the next entry in [`fallbackModels`](#fallbackmodels-/-fallbackthinkinglevels), which receives the original stage prompt and its own fresh budget. The recorded attempt error names what the turn actually looked like — no assistant message after the prompt, an assistant message with empty text, or the `structured_output` validation error — so a repeated external cause is attributable. With no fallback candidate left, the stage fails with the contract error rather than completing. An explicit tool allowlist automatically receives the final-answer tool, while items without `schema` do not.
 
 When `schema` and `output` are both configured, the successful `structured_output` turn carries two separate results. All ordinary assistant text blocks from that exact message, in order, are written to the artifact; the successful tool arguments become the typed schema-backed workflow value. The runtime snapshots both sides against the exact successful tool-call id rather than searching by tool name, so corrective attempts and later admitted turns cannot replace either result, and it never serializes the tool arguments into the artifact. When the successful message carries no ordinary text — including when a model-fallback session recreation leaves the live session without that message — the artifact falls back to the most recent earlier assistant text that made no `structured_output` call; if no such text exists the artifact is empty and its receipt includes the standard empty-artifact warning. Stages with `schema` but no `output` keep their existing result-text behavior. Builtin pattern workflows that hand structured decisions to later stages (`adversarial-verification`, `generate-and-filter`, `tournament`, `loop-until-done`) persist those decisions themselves, so their `*.json` inter-stage artifacts remain machine-readable JSON.
 
@@ -615,11 +622,15 @@ readonly outputMode?: "inline" | "file-only";
 
 Writes stage/task output to a path or disables output persistence with `false`. `outputMode` defaults to `inline`; `file-only` keeps the parent result compact by returning an artifact reference instead of full text and requires an output path.
 
-The runner writes the stage's **final assistant message** to `output` after the stage ends, so that path belongs to the runner. For a schema-backed stage, this means the ordinary text in the assistant message that calls `structured_output`, not the structured tool arguments. A stage that declares `output:` also automatically gets a full, rendered, line-oriented transcript of its session, and one appended instruction telling the model that its final message becomes the artifact — the workflow definition does not need to describe any of this.
+The runner owns `output`. For an ordinary stage, it saves the completed assistant answers from the current prompt generation in order. The first answer is unchanged; later answers are appended after `## Supplement 1`, `## Supplement 2`, and so on. Text blocks retain their original text, including whitespace and repeated answers. Tool-call progress, reasoning, user input, tool results and earlier session history remain transcript-only. A single answer therefore keeps its existing artifact format. A schema-backed stage retains its separate contract: the ordinary text paired with the successful `structured_output` call owns the artifact, not the tool arguments.
+
+Follow-ups admitted before generation close, including executor continuations and work drained during close, supplement the artifact rather than silently replacing its report. Corrections should explicitly say what they correct; the runner does not infer revision intent from wording or text length. After completion, retained-session chat and unrelated messages cannot replace the saved artifact or receipt. Repeated finalization does not append content again. For an intentional replacement, author a new tracked stage with its own output path; a completed tracked stage still rejects a second `prompt()`. A direct internal context's new authored prompt starts a fresh generation, while executor continuations stay in the active generation. Stages without `output` retain their existing last-response behavior.
+
+Accepted answers are captured independently of the session's compactable context. Compaction cannot remove them from the handoff. Navigating to an existing session-tree branch restores context, not output: its historical answers are not appended, while newly generated continuations still supplement the current report. If a continuation falls back to another model, earlier successful answers remain; only the failed attempt's provisional answers are discarded before the successful continuation is appended. Capture stops after generation close drains admitted work, so later retained-session chat does not accumulate in the completed output generation.
 
-An admitted external turn (for example, a subagent completion) can arrive while the stage is still running and remains visible both to the model and in the companion transcript. The runner does not try to work out which turn was "really" the deliverable: that is an inference about intent, and an earlier revision that scored candidates by byte size got it wrong in both directions. If a late turn displaces the intended content, the transcript still holds it.
+A stage declaring `output` also gets a rendered, line-oriented companion transcript and an instruction explaining its output contract. Workflow prompts should describe the deliverable, not reimplement artifact writing.
 
-The companion transcript is written once under the durable Atomic config root at `~/.atomic/workflows/runs/<runId>/transcripts/` (or the equivalent configured agent root; `ATOMIC_WORKFLOW_ARTIFACT_DIR` overrides that root). It is never placed inside the repository tree or OS temporary storage: a home-scoped durable location survives both worktree deletion and OS temp purges, and staying outside the repo keeps full tool output — which may contain secrets — from being committed accidentally. Run-scoped artifact directories are pruned only when their durable/live run record is terminal (or the directory is an unowned orphan) and older than the exported `WORKFLOW_ARTIFACT_RETENTION_MS` policy. Running, paused, quit, blocked, and awaiting-input runs are exempt indefinitely because their artifacts are live resume dependencies. A live continuation transitively protects the original run directory in its `resumedFromRunId` chain, even when intermediate continuations have different run IDs; merely quoting another run's artifact path does not protect that unrelated owner or make the quoting run depend on it. A **failed** run with no live continuation is terminal and does age out: it stays retryable, but the retention window is the grace period it gets, otherwise repeated recoverable failures would accumulate artifacts forever. When a terminal durable owner is aged out, the durable entry is deleted first; if authoritative deletion is unavailable or refuses, the artifact directory is preserved. Goal ledgers, Ralph implementation notes, and QA video paths share that same durable root and retention policy. The receipt names both absolute paths. Search the transcript with `rg`, then read only the narrow line ranges you need; do not read the whole transcript into a downstream prompt. The transcript is a secondary searchable record; the output artifact remains the curated handoff.
+The companion transcript is saved under the durable Atomic config root at `~/.atomic/workflows/runs/<runId>/transcripts/` (or the equivalent configured agent root; `ATOMIC_WORKFLOW_ARTIFACT_DIR` overrides that root). It is refreshed when newly admitted answers update the artifact before close. It is never placed inside the repository tree or OS temporary storage: a home-scoped durable location survives both worktree deletion and OS temp purges, and staying outside the repo keeps full tool output — which may contain secrets — from being committed accidentally. Run-scoped artifact directories are pruned only when their durable/live run record is terminal (or the directory is an unowned orphan) and older than the exported `WORKFLOW_ARTIFACT_RETENTION_MS` policy. Running, paused, quit, blocked, and awaiting-input runs are exempt indefinitely because their artifacts are live resume dependencies. A live continuation transitively protects the original run directory in its `resumedFromRunId` chain, even when intermediate continuations have different run IDs; merely quoting another run's artifact path does not protect that unrelated owner or make the quoting run depend on it. A **failed** run with no live continuation is terminal and does age out: it stays retryable, but the retention window is the grace period it gets, otherwise repeated recoverable failures would accumulate artifacts forever. When a terminal durable owner is aged out, the durable entry is deleted first; if authoritative deletion is unavailable or refuses, the artifact directory is preserved. Goal ledgers, Ralph implementation notes, and QA video paths share that same durable root and retention policy. The receipt names both absolute paths. Search the transcript with `rg`, then read only the narrow line ranges you need; do not read the whole transcript into a downstream prompt. The transcript is a secondary searchable record; the output artifact remains the curated handoff.
 
 The receipt reports facts only. An empty artifact produces `WARNING: the stage artifact is empty; search the companion transcript for this stage's work.` A non-empty artifact is never classified, however short and even if it only names its own output path: deciding whether such text is a pointer or a deliverable requires knowing what the author meant, and the regex bank that previously attempted it produced false alarms on genuine short output. The transcript named in every receipt is the recovery path for anything that looks wrong to a reader.
 
@@ -675,7 +686,7 @@ Selects or creates a reusable same-repository Git worktree for `ctx.stage`, `ctx
 - **Caching and diagnostics:** Temporary isolation defaults to the runner invocation cwd, and relative task cwd values resolve there. Reusable setup is cached by canonical repository and target identity independently of equivalent path spelling or `baseBranch`, revalidates checkout identity before reuse, retries one transient timeout from read-only repository probes, and reports the exact Git command, cwd, timeout, elapsed time, exit status or signal, and spawn error details on failure.
 - **Security boundary:** Worktrees isolate checkouts and cwd, not the operating system. Use a container, VM, or another OS-enforced boundary for untrusted code that can race or mutate arbitrary paths.
 
-For lower-level integrations, [`setupGitWorktree(options)`](#setupgitworktreeoptions) returns the validated and remapped setup result.
+For lower-level integrations, [`setupGitWorktree(options)`](#setupgitworktree-options) returns the validated and remapped setup result.
 
 ### `sessionDir`
 
@@ -732,7 +743,9 @@ readonly concurrency?: number;
 readonly failFast?: boolean;
 ```
 
-`WorkflowParallelOptions` uses `concurrency` to bound active tasks in an authored `ctx.parallel(...)`. When omitted, the runtime uses the workflow's `defaultConcurrency` setting, which defaults to `4`; parallel execution is fail-fast unless `failFast` is explicitly `false`.
+`WorkflowParallelOptions` uses `concurrency` to bound active tasks in an authored `ctx.parallel(...)`. When omitted, the runtime uses the workflow's `defaultConcurrency` setting, which defaults to `3`; explicit configuration and per-call concurrency remain honored. Parallel execution is fail-fast unless `failFast` is explicitly `false`.
+
+For a dynamic parallel step array that cannot be scanned, set `possibleStageNames: ["review-*"]` in the call's options. Supply a literal array covering every possible step name; `*` matches a varying name component. This metadata only controls advance stage discovery, not execution or concurrency. Named helpers can forward `options.possibleStageNames` directly to their parallel calls when every direct caller supplies a literal array, including through named relative imports. Use plain data properties in those caller options; options methods/getters, mutation, and side-effecting parameter defaults are not supported for discovery. Opaque forwarding and unannotated dynamic calls still produce discovery warnings.
 
 ### Stage prompt options (`StagePromptOptions`)
 
@@ -831,7 +844,10 @@ Runs the lower-level completion adapter and returns text. Completion options can
 ```typescript
 stage.sendUserMessage(
   content: string | readonly (StageTextContent | StageImageContent)[],
-  options?: { readonly deliverAs?: "steer" | "followUp" },
+  options?: {
+    readonly deliverAs?: "steer" | "followUp";
+    readonly expandPromptTemplates?: boolean;
+  },
 ): Promise<void>;
 ```
 
@@ -839,6 +855,8 @@ Sends a normal follow-on user turn to the retained stage session. This method st
 
 `deliverAs: "steer"` is consumed after the current assistant response finishes its whole tool batch and before the next model request; `deliverAs: "followUp"` is consumed only when the agent would otherwise stop. Each queue is FIFO in admission order, and steering keeps priority over an earlier-submitted follow-up.
 
+Native session delivery is literal by default. Set `expandPromptTemplates: true` to opt into the session's existing skill/prompt-template expansion and registered extension-command dispatch; a command may be handled without creating a user turn. Stage admission still applies before delivery. The attached stage composer opts into this path for `/skill:` invocations only; ordinary programmatic messages keep the default. Custom adapters must implement the option to provide equivalent behavior.
+
 Native sessions accept strings or text/image content blocks. Non-native fallback adapters accept only strings and reject block arrays; `deliverAs` affects streaming delivery only, and follow-on turns retain the stage MCP scope.
 
 Externally produced Intercom and subagent notices admitted before the generation closes drain through the same session. When a busy stage owns a foreground subagent, exact-owner detach gets first refusal before Intercom enters this boundary; unclaimed traffic then uses normal stage admission. Closing the atomic boundary cancels still-running stage-owned children and suppresses their later findings and completion notices. Ordinary traffic not owned by that stage arriving afterward cannot reopen the completed stage and retains the existing single main-chat route.
@@ -946,6 +964,7 @@ interface WorkflowTaskResult extends WorkflowTaskContext {
   readonly sessionFile?: string;
   readonly artifacts?: readonly WorkflowArtifact[];
   readonly model?: string;
+  readonly thinkingLevel?: string;
   readonly attemptedModels?: readonly string[];
   readonly modelAttempts?: readonly WorkflowModelAttempt[];
   readonly warnings?: readonly string[];
@@ -979,7 +998,7 @@ When a stage explicitly configures `model` or `fallbackModels`, each recorded at
 ```typescript
 interface WorkflowDetails extends WorkflowSerializableObject {
   readonly mode: "named" | "single" | "parallel" | "chain" | "inspection" | "control";
-  readonly action?: "list" | "get" | "inputs" | "run" | "status" | "interrupt" | "resume";
+  readonly action?: "list" | "get" | "inputs" | "run" | "status" | "pause" | "resume";
   readonly runId?: string;
   readonly status: "accepted" | "running" | WorkflowExitStatus | "failed" | "killed" | "noop";
   readonly context?: "fresh" | "fork";