@bastani/atomic 0.9.19-alpha.5 → 0.9.19-alpha.7

package/docs/intercom.md

@@ -25,34 +25,41 @@ Atomic bundles `@bastani/intercom`, a first-party extension for direct 1:1 messa
 - Supervisor decisions and structured interviews for delegated subagents
 - Pair debugging between sessions
 
+## Where to go next
+
+Intercom coordinates several Atomic sessions on one machine. Read this page for the quick start and the coordination patterns, then continue:
+
+- [Intercom operations](/intercom/operations) — connection lifecycle, delivery behavior, notifications, shortcuts, internals, and limits.
+- [Intercom reference](/intercom/reference) — the `intercom` tool contract and every intercom setting.
+
 ## Table of Contents
 
 - [Quick Start](#quick-start)
   - [From the Keyboard](#from-the-keyboard)
   - [From the Agent](#from-the-agent)
   - [Receiving Messages](#receiving-messages)
-- [How Connection Works](#how-connection-works)
-- [The intercom Tool](#the-intercom-tool)
-  - [Actions](#actions)
-  - [Targeting Sessions and Pending Workflow Stages](#targeting-sessions-and-pending-workflow-stages)
-  - [Deferred delivery to pending stages](#deferred-delivery-to-pending-stages)
-  - [send vs ask vs reply](#send-vs-ask-vs-reply)
-  - [Attachments](#attachments)
+- [How Connection Works](/intercom/operations#how-connection-works)
+- [The intercom Tool](/intercom/reference#the-intercom-tool)
+  - [Actions](/intercom/reference#actions)
+  - [Targeting Sessions and Pending Workflow Stages](/intercom/reference#targeting-sessions-and-pending-workflow-stages)
+  - [Deferred delivery to pending stages](/intercom/reference#deferred-delivery-to-pending-stages)
+  - [send vs ask vs reply](/intercom/reference#send-vs-ask-vs-reply)
+  - [Attachments](/intercom/reference#attachments)
 - [Coordination Patterns](#coordination-patterns)
 - [Subagent Escalation: contact_supervisor](#subagent-escalation-contact_supervisor)
   - [When the Tool Appears](#when-the-tool-appears)
   - [The Three Reasons](#the-three-reasons)
   - [What the Supervisor Sees](#what-the-supervisor-sees)
   - [Structured Interview Replies](#structured-interview-replies)
-- [Workflow and Subagent Notifications](#workflow-and-subagent-notifications)
-  - [Workflow Delivery Modes](#workflow-delivery-modes)
-  - [Subagent Control Notices](#subagent-control-notices)
-  - [Delivery Ordering](#delivery-ordering)
-- [Configuration](#configuration)
-- [Keyboard Shortcuts](#keyboard-shortcuts)
-- [How It Works](#how-it-works)
+- [Workflow and Subagent Notifications](/intercom/operations#workflow-and-subagent-notifications)
+  - [Workflow Delivery Modes](/intercom/operations#workflow-delivery-modes)
+  - [Subagent Control Notices](/intercom/operations#subagent-control-notices)
+  - [Delivery Ordering](/intercom/operations#delivery-ordering)
+- [Configuration](/intercom/reference#configuration)
+- [Keyboard Shortcuts](/intercom/operations#keyboard-shortcuts)
+- [How It Works](/intercom/operations#how-it-works)
 - [Intercom vs Shared-Room Messengers](#intercom-vs-shared-room-messengers)
-- [Limitations](#limitations)
+- [Limitations](/intercom/operations#limitations)
 - [Related Docs](#related-docs)
 
 ## Quick Start
@@ -127,122 +134,39 @@ Atomic treats ordinary `intercom` as a mandatory runtime tool in main chat and e
 
 ## How Connection Works
 
-Intercom connections are normally tool-driven. Ordinary sessions and delegated children load and register the lightweight wrapper at startup, while broker connection and heavy initialization wait until an Intercom tool, `/intercom`, or the ALT+M overlay is invoked. One exception is supervisor authorization: launching an Intercom-enabled subagent connects the parent runtime long enough to request a broker capability for that child; the child's own connection remains lazy until it invokes `contact_supervisor`. The parent restores issued capabilities across reconnects, and the child uses the broker-confirmed current supervisor ID. Concurrent callers share one import and connection attempt, and broker state is leased to the active session generation and cleaned up on shutdown or replacement.
-
-A session becomes intercom-connected when all of these are true:
-
-- the mandatory bundled Intercom extension is loaded in that Atomic model session
-- the model or user has invoked an Intercom surface in that session, **or** the parent runtime is authorizing an Intercom-enabled child supervisor relationship
-- the local broker is running or can be auto-started
-
-The session list and ALT+M picker show connected agent sessions, not every open Atomic process. Internal workflow routing/control connections, model-less `ctx.ui` prompts, and `ctx.tool` nodes are not recipients and do not contribute to session counts or presence events. Genuine agents remain visible and messageable while executing tools, including `tool:workflow`, or awaiting human input.
-
-Name sessions with `/name` so they can target each other (for example `/name planner` and `/name worker`). If a session is unnamed, Intercom exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d-1111-4222-8333-123456789abc` so other sessions can still target it. That alias is not persisted as the session title, so resume pickers keep showing the transcript snippet instead of a generic name.
+Moved to [Intercom operations](/intercom/operations#how-connection-works).
 
 ### Troubleshooting initialization
 
-`Intercom heavy initialization failed; a later call will retry: …` means initialization can be attempted again on a later Intercom call. Interactive sessions show this as a yellow warning in the chat pane, without a console stack trace; non-interactive sessions (print, JSON, and RPC) retain console diagnostics. Terminal relay and cleanup failures appear as error notifications in interactive sessions.
-
-If initialization keeps failing, check the reported cause and `~/.atomic/agent/intercom/broker.log` (or the Intercom directory under `ATOMIC_CODING_AGENT_DIR`). Do not automatically resend an operation reported with an unknown delivery outcome; check with the recipient first.
+Moved to [Intercom operations](/intercom/operations#troubleshooting-initialization).
 
 ## The intercom Tool
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `action` | string | `"list"`, `"groups"`, `"join"`, `"leave"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
-| `to` | string | Exact session name/full session ID, or `workflow:<rootRunId>/<segment>[/<segment>...]`; `*` matches one segment and `**` any depth. Sends support pending/future patterns and broadcast; `ask` requires a live target. |
-| `message` | string | Message text (for send/ask/reply) |
-| `attachments` | array | Optional `file`, `snippet`, or `context` attachments |
-| `replyTo` | string | Optional message ID for threading or replying to an `ask` |
-| `group` | string | Group name for `join` or an optional targeted `leave`; read-only group filter for `list`/`status`. `send`/`ask` remain limited to shared memberships. |
+Moved to [Intercom reference](/intercom/reference#the-intercom-tool).
 
 ### Actions
 
-| Action | Behavior |
-|--------|----------|
-| `join` | Adds a trimmed named group membership and creates the group if needed. The action waits for broker acknowledgement and reports the complete resulting membership set. `default` is shared; `true` and `auto` are reserved for subagent auto-groups. |
-| `leave` | With `group`, removes only that membership and keeps all others. Without `group`, resets the session to its resolved startup home group. Both forms report the resulting membership set. |
-| `groups` | Lists every group represented by a connected session, with its session count and a marker for each group this session belongs to. Use it to discover names rather than guessing. |
-| `list` | Returns the current session, active sessions sharing a membership, materialized workflow stages labeled `PENDING` or `RUNNING` with canonical path targets, and possible future literals, globs, and child paths with queued counts. Pass `group` for a read-only view of one group. |
-| `send` | Fire-and-forget delivery through ordinary Intercom. A live workflow-stage match receives the message immediately. A pending, future, name, or pattern path is persisted as sticky delivery and returns `queued`; valid paths outside the known set also return `notInKnownSet`. Requires `to` and `message`; cannot message the current session. |
-| `ask` | Sends a message and blocks until a live recipient replies (10-minute timeout). An ask to a known workflow stage whose session has not initialized is refused with `pending_stage_ask_unsupported` and recommends ordinary `send`; holding a waiter until a stage eventually starts would be unbounded. A live recipient disconnect fails promptly. Parallel children continue in the same execution after a correlated reply; single-child parent handoffs remain unchanged. |
-| `reply` | Replies to the intercom-triggered message of the current turn; otherwise falls back to the single unresolved inbound ask. With multiple pending asks, pass `to` or inspect with `pending` first. |
-| `pending` | Lists unresolved inbound asks with sender, message ID, elapsed time, and a short preview. |
-| `status` | Shows connection status, session ID, every group this session belongs to, and the count of active sessions visible through those memberships. A `group` filter remains a read-only peek. |
-
-To give two plain chat sessions a private shared membership, have both call:
-
-```typescript
-intercom({ action: "join", group: "api-review" })
-```
-
-Joining is additive: existing memberships remain active, and the broker updates presence without changing the session ID. Use `intercom({ action: "groups" })` to discover all available names and membership markers. `intercom({ action: "leave", group: "api-review" })` removes only that membership; `intercom({ action: "leave" })` resets to the home group resolved at startup. Rejected or unacknowledged changes leave client and inheritance state unchanged. Ordinary delivery requires a shared membership, while `contact_supervisor` retains its capability-based cross-group path.
-
-An ordinary host session can join several workflow invocation groups and send to
-each group's `workflow:<rootRunId>/**` target, including after a broker reconnect.
-Reconnection preserves the session's startup identity separately from its joined
-memberships; joining a workflow does not turn the host into a workflow worker.
-Groups explicitly left stay absent after reconnect; the startup identity is not
-automatically added back to the membership list.
-Actual workflow workers retain their original invocation boundary across reconnects:
-joining another group does not grant that invocation's parent-control authority.
-
-Sent and received messages are recorded in session history as `intercom_sent` / `intercom_received` entries.
+Moved to [Intercom reference](/intercom/reference#actions).
 
 ### Targeting Sessions and Pending Workflow Stages
 
-Live-session lookup accepts only an exact full Intercom session ID or an exact case-insensitive session name. Workflow stages use the canonical `workflow:<rootRunId>/<segment>[/<segment>...]` path printed by `intercom list` and workflow status surfaces; an exact target works while the row is `PENDING` and after it becomes `RUNNING`. Each segment may be a stage name, run id, or glob: `*` matches one segment and may be embedded, while `**` matches any depth. Status surfaces label pending stages whose pre-start delivery capability is unavailable without presenting a usable target and never advertise a retained pending stage after its run terminates. The `sessionId` shown by `workflow status` belongs to the workflow SDK and is **not** an Intercom target.
-
-Known non-agent IDs, names, and workflow paths are refused rather than delivered or queued for a future agent. This includes run-level `ctx.ui` prompts, synthetic prompt stages (including retained completed prompts), and `ctx.tool` nodes. Knowing an internal connection's ID does not bypass this broker policy, and supervisor delivery cannot bypass it either. Workflow patterns and `workflow:<rootRunId>/**` still queue for future agent stages, but never deliver to prompt/tool nodes or routing connections.
-
-This refusal also covers nested paths using boundary-stage names or IDs, mixed with materialized run-ID segments. The same spellings still resolve genuine agent stages.
-
-A genuine agent's registered aliases remain valid when its pending-delivery capability is unavailable or its stage completes, even if a non-agent node shares its display name. The host retains that agent identity separately from discovery eligibility so aliases can be restored after an agent or broker reconnect. An agent's human-input wait is not a model-less `ctx.ui` node.
-
-If several live agent stages share a workflow-stage name, `ask` remains ambiguous: use an exact stage-ID path from `intercom list`. Name-based `send` retains sticky delivery to matching agents. A prompt or tool with that same name does not turn genuine-agent matches into non-agent refusals.
-
-Before steering a stage from the main chat, enter the workflow invocation context by joining `workflow:<rootRunId>` with `intercom({ action: "join", group: "workflow:<rootRunId>" })`; workflow-owned invocation sessions already start there. A member of that invocation group can list, `send` to, and live-`ask` exact stages in any invocation-owned subgroup (`workflow:<rootRunId>/<name>`), including intentionally isolated reviewer batches. This control is directional: a session registered as a subgroup stage cannot gain parent control by joining the invocation group, subgroup members cannot discover or reach sibling subgroups, and another workflow invocation remains refused. `PENDING` accepts queued `send` only; `RUNNING` accepts immediate `send` and correlated `ask`/`reply`.
+Moved to [Intercom reference](/intercom/reference#targeting-sessions-and-pending-workflow-stages).
 
 ### Deferred delivery to pending stages
 
-Send material updates through Intercom to every affected workflow stage, including stages that have not started. Inside `workflow:<rootRunId>`, `intercom list` shows live sessions, materialized `PENDING`/`RUNNING` stages, and possible future literal, glob, and nested-child targets with queued counts. A deferred send returns `queued`, including its FIFO position, rather than claiming delivery; live matches receive the ordinary inbound message immediately.
-
-Name and pattern paths remain sticky for every future matching stage until the root terminates. When shared scope or acceptance criteria change, broadcast one authoritative update to `workflow:<rootRunId>/**` (or a narrower path pattern) rather than enumerating stages: `**` reaches every live stage now and every future descendant. A syntactically valid path outside the persisted known set still queues and returns `notInKnownSet`; if it never delivers, root-terminal settlement sends the correlated undeliverable notification. A sticky entry delivered at least once is not reported undeliverable.
-
-The workflows extension persists up to **50 queued messages per target** with workflow state. Messages survive resume/replay and broker restart, and logical message IDs prevent redelivery to the same materialized stage across stage-attempt restarts. When a matching stage session initializes, it receives the FIFO entries through the ordinary Intercom inbound path before its first model turn, under the heading **Messages received before you started**, with sender identity and `Sent:` timestamps visible separately from the task prompt.
-
-Only a workflow invocation member with eligible invocation-control authority can queue to its invocation-owned stages; this includes a main-chat session that explicitly joined `workflow:<rootRunId>`. Subgroup peers and another root run remain refused even if they add that membership. An explicit stage `group: "default"` is a shared-group escape, is not workflow-owned, and does not receive pending invocation delivery. An ineligible attempt is refused with `Target workflow run is in a different intercom group`. The 51st queued message is refused with `Pending stage message queue is full (limit 50)` rather than evicting an earlier entry.
-
-If the destination stage is skipped, the run terminates, or the stage becomes terminal before its session initializes, Atomic marks the queued message undeliverable and sends the correlated failure notification when acknowledgment was requested. Use `ask` only on a live, reply-capable exact target. Pending, future, and pattern asks return `pending_stage_ask_unsupported`; use ordinary `send`, because a stage may start much later or never start.
+Moved to [Intercom reference](/intercom/reference#deferred-delivery-to-pending-stages).
 
 ### Groups
 
-Every session belongs to a non-empty set of intercom **groups**. Sessions with no group configured retain exactly the legacy behavior: they belong only to the implicit `"default"` group and can see and message each other. A session can ordinarily discover, resolve, and message another session when their membership sets intersect; exact-ID sends with no shared membership are rejected by the broker.
-
-- `list` still lists sessions. Without a filter it returns the union of sessions visible through any of your memberships; with `group`, it gives a read-only view of that one group.
-- `groups` lists every currently available group, its connected-session count, and whether this session is a member.
-- `join` adds one membership. `leave` removes the named membership, while bare `leave` resets the complete set to the startup home group.
-- `status` reports the complete membership set. `session_joined`/`session_left`/`presence_update` events are delivered whenever a membership change affects visibility.
-
-A session's home group is resolved with this precedence: explicit stage/task/subagent group > runtime-owned workflow invocation group or inherited launching-session group > env `ATOMIC_INTERCOM_GROUP` (legacy `PI_INTERCOM_GROUP`) > Intercom `config.json` `"group"` > `"default"`. Workflow stage named groups and `group: true` are namespaced under `workflow:<rootRunId>/...`, preventing cross-run collisions while preserving sibling isolation. `group: "default"` remains the explicit non-owned escape. The invocation group has asymmetric exact-target control over its owned subgroups; ownership does not grant reverse or lateral access.
-
-The broker, not the client, marks validated supervisor traffic. Ordinary `send` frames remain membership-isolated even if a raw client forges a supervisor marker, and replies cross back only through an exact broker-recorded `replyTo` match. Parent-held authorization state is restored after reconnects. During child admission, the parent wrapper may lazy-load and connect the broker provider to mint that exact child's capability. The child still connects only when it uses an Intercom delivery path. Single-child claimed decisions or interviews terminally hand off before child send or waiter admission; parallel requests use the broker and correlated reply wait. A claimed provider failure aborts launch, while runtimes with no provider omit supervisor metadata and do not expose a broken channel.
+Moved to [Intercom reference](/intercom/reference#groups).
 
 ### send vs ask vs reply
 
-**`send`** is fire-and-forget — the tool returns immediately after delivery. By default it sends immediately, including in interactive sessions. If you want an approval dialog before non-reply sends, set `confirmSend: true` in config; replies that include `replyTo` still skip confirmation so reply-hint flows continue without an extra approval step.
-
-**`ask`** sends the message and blocks until the recipient responds (10-minute timeout). If the recipient disconnects after delivery, only the exact ask to that peer fails promptly; the timeout remains the backstop for a connected but unresponsive recipient. Up to `maxPendingAsks` waits (default: 6) may run concurrently, including same-target and mixed-target fan-out. Exact sender/message correlation keeps out-of-order replies and selective disconnects from cross-settling another call. Parallel children use this path even when asking their launching parent: only the requester waits, siblings keep executing, and the reply returns from the waiting tool call in the original child execution. A single-child launch retains the exception that a claimed parent ask ends that child and returns a dynamic `[TASK_CONTEXT]` handoff.
-
-An `idle` registration does not guarantee reply capability. Completed, failed, interrupted, or cancelled noninteractive subagent children reject new asks immediately with `Target noninteractive child is terminal and cannot reply`; launch a fresh child with explicit context instead. If termination wins after admission but before a reply, the exact pending ask fails explicitly too. Live interactive idle sessions remain askable, and completed workflow stages with a retained reply-capable post-mortem conversation keep their existing reopening behavior. `send` transport behavior is unchanged; a retained registration is not a promise that a terminal child's model will consume a send.
-
-**`contact_supervisor`** keeps a narrower policy: one blocking decision/interview wait per child may coexist with ordinary peer asks, but a second concurrent supervisor wait receives `Already waiting for a supervisor reply`. Claimed foreground handoffs allocate no waiter. Mutual peer asks are supported, although both sessions must process inbound work to reply; the per-waiter timeout remains the backstop.
-
-**`reply`** is receiver-side sugar for replying to an inbound ask. In the turn triggered by an incoming intercom message, `intercom({ action: "reply", message: "..." })` targets that exact sender and message automatically. If you reply later, it falls back to the single unresolved inbound ask; with multiple pending asks, use `pending` and pass `to`, or pass the listed message ID as `replyTo` to disambiguate multiple asks from the same sender. Under the hood this is still a normal `send` with the exact `replyTo` value.
+Moved to [Intercom reference](/intercom/reference#send-vs-ask-vs-reply).
 
 ### Attachments
 
-`send`, `ask`, and `reply` accept an `attachments` array of `{ type, name, content, language? }` objects where `type` is `"file"`, `"snippet"`, or `"context"`. Attachment content is included in the recipient's agent-visible message body. When a parent-targeted foreground `ask` is terminally handed off at the source, the same ordered attachment array is retained and rendered with the question for the launching parent; duplicate names and content are not rewritten. Attachments are supported in the protocol but not in the ALT+M compose overlay.
+Moved to [Intercom reference](/intercom/reference#attachments).
 
 ## Coordination Patterns
 
@@ -345,6 +269,21 @@ For a parallel child, the supervisor receives the question with its child/run id
 
 Single-child claimed handoffs instead include terminal run metadata, ordered attachments, the original delegated task, and an explicit fresh-start `[TASK_CONTEXT]` call. That legacy single-child path still requires a new run identity for follow-up work.
 
+For a single-child claimed handoff, the fresh-start instruction has this form:
+
+```text
+Subagent yielded for parent input (worker, child 1).
+Previous run (terminal): 78f659a3
+Question:
+Which API should I use?
+
+Start a fresh subagent with a new run identity, replacing <SUPERVISOR_ANSWER> with your answer:
+subagent({
+  "agent": "worker",
+  "task": "[TASK_CONTEXT] ... Continue with this supervisor answer: <SUPERVISOR_ANSWER>"
+})
+```
+
 ### Structured Interview Replies
 
 `interview_request` questions use the shape `{ id, type, question, options?, context? }` where `type` is `single`, `multi`, `text`, `image`, or `info` (`info` questions are context-only and need no response):
@@ -378,171 +317,31 @@ The parallel child's tool result preserves the raw reply text and includes `deta
 
 ## Workflow and Subagent Notifications
 
-Intercom is also the delivery channel for workflow run results and subagent control notices from [workflows](/workflows) and [subagents](/subagents).
+Moved to [Intercom operations](/intercom/operations#workflow-and-subagent-notifications).
 
 ### Workflow Delivery Modes
 
-Programmatic `workflow()` calls accept an `intercom` option that controls how asynchronous direct-run results and control notices reach a parent session:
-
-```typescript
-workflow({
-  tasks: [{ agent: "worker", task: "..." }],
-  intercom: { delivery: "result" },
-})
-```
-
-| Option | Values | Meaning |
-|--------|--------|---------|
-| `enabled` | boolean | `false` forces delivery off; `true` resolves to `control-and-result` |
-| `delivery` | `"off"` \| `"notify"` \| `"result"` \| `"control-and-result"` | Explicit delivery mode; wins over `enabled` |
-| `parentSession` | string | Target session for delivery; resolved from args or the Intercom port when omitted |
-| `notifyOn` | array | Control events to deliver: `"active_long_running"`, `"needs_attention"`, `"completed"`, `"failed"` |
-
-When neither `enabled` nor `delivery` is set, direct `parallel` runs default to `control-and-result` when Intercom is available; otherwise delivery is off. Treat Intercom payloads from direct runs as user-visible workflow output.
-
-While a workflow stage generation is open, incoming Intercom messages are admitted as priority input: the stage's current model call or cancellable tool is cancelled and the message is processed next in the same stage generation. Parallel child asks, sends, and supervisor requests use destination-side reservation and the exact-child probe/commit observation-yield handshake before that cancellation, so a child's own message releases the parent's foreground observation rather than cancelling the child, and terminal stage close cannot overtake an admitted delivery. A destination-side admission failure returns a correlated actionable error to a blocking asker instead of waiting for the 10-minute reply timeout. Claimed single-child parent handoffs remain source-side terminal handoffs.
+Moved to [Intercom operations](/intercom/operations#workflow-delivery-modes).
 
 ### Subagent Control Notices
 
-The `subagent` tool's `control` options select which control events notify the parent and over which channels:
-
-- **`notifyOn`** — defaults to `["active_long_running", "needs_attention"]`
-- **`notifyChannels`** — defaults to `["event", "intercom"]` (all that are available)
-
-Detached subagent result delivery over Intercom is confirmation-based and preserves a successful delivery phase across watcher replacement. Each delegated child gets a deterministic Intercom target derived from its run/agent/index identity, and run results report those targets ("Run intercom target" / "Previous intercom target"; targets may be inactive after completion). `intercom({ action: "status" })` reports connection state and every membership for the current session.
-
-If live peer coordination is needed, invoke `intercom({ action: "status" })` in the parent before launching; the child connects on its first ordinary Intercom call. A claimed single-child `contact_supervisor` decision or interview can yield before child broker connection because typed admission already identifies the launching parent. Fresh child sessions always receive the mandatory bundled Intercom wrapper, including when an explicit `extensions` allowlist is empty or omits it.
+Moved to [Intercom operations](/intercom/operations#subagent-control-notices).
 
 ### Delivery Ordering
 
-Parallel communication never cancels its batch: blocking asks and supervisor decisions/interviews wait only in their requesting child; send and progress updates remain nonblocking. The exact-child handshake releases foreground observations, including queued slots, without releasing running execution capacity or changing child identity. A correlated reply continues that same child. Targeted cancellation, explicit batch cancellation, and owner lifetime cleanup remain separate controls. Claimed single-child parent asks retain their terminal fresh-start handoff.
-
-For delegated children, queued messages and terminal lifecycle notices remain ordered per child, including owner-bound background tasks. Before publishing completion, the notification outbox drains already-queued ordinary messages from that child's trusted run and Intercom target. Other children and pending asks stay separate. Each earlier message keeps its own admission identity; the completion ID belongs only to the terminal notice. A failed message or terminal delivery remains retryable without changing the task's outcome or rerunning it. Restored completions without a live source binding still deliver normally rather than guessing a child identity. See [Subagents](/subagents) for the full coordination contract.
+Moved to [Intercom operations](/intercom/operations#delivery-ordering).
 
 ## Configuration
 
-Create `~/.atomic/agent/intercom/config.json`. The legacy `~/.pi/agent/intercom/config.json` fallback is read when the Atomic config is absent:
-
-```json
-{
-  "brokerCommand": "npx",
-  "brokerArgs": ["--no-install", "tsx"],
-  "confirmSend": false,
-  "replyHint": true,
-  "status": "researching",
-  "group": "default"
-}
-```
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `brokerCommand` | `"npx"` | Command used to start the local broker process; the default sentinel is hardened internally to avoid PATH lookup |
-| `brokerArgs` | `["--no-install", "tsx"]` | Arguments passed to `brokerCommand` before the broker script path |
-| `confirmSend` | `false` | Show a confirmation dialog before non-reply sends from an interactive session with UI |
-| `replyHint` | `true` | Include reply instruction in incoming messages |
-| `status` | — | Optional custom status suffix shown after the automatic lifecycle status, for example `thinking · researching` |
-| `group` | `"default"` | Home intercom group for this session (see [Groups](#groups)). Overridden by env `ATOMIC_INTERCOM_GROUP` / `PI_INTERCOM_GROUP` and by workflow/orchestrator per-session injection. |
-
-The default `npx --no-install tsx` pair is a compatibility sentinel: Intercom recognizes it and starts the broker through the current Atomic runtime (`process.execPath`). It never resolves or executes `tsx` — Node-based installs run the broker with Atomic's bundled `jiti` loader, which is dependency-free pure JavaScript; Bun source-checkout runs use the current Bun executable directly; standalone Atomic binaries re-enter the split launcher through a narrow internal broker handoff. Default startup therefore does not rely on `npx`, `tsx`, or `bun` being on `PATH`. Explicit custom broker commands still work — for example, to intentionally use Bun from `PATH`:
-
-```json
-{
-  "brokerCommand": "bun",
-  "brokerArgs": []
-}
-```
-
-Config validation is strict: every field is checked, and if the file is not valid JSON or any field has an invalid value, the whole config is rejected — an error is logged and all defaults are used.
-
-Intercom publishes live session status automatically: sessions register as `idle`, switch to `thinking` while the agent is running, show `tool:<name>` during tool execution, and return to `idle` on completion. A configured `status` is appended as context instead of replacing the lifecycle status.
-
-Activity is not reply capability. Session rows include `replyCapability: live` or `terminal` when the host supplies it; terminal noninteractive children cannot answer asks even if activity says `idle`. Closed workflow generations show `closed · reply: post-mortem only` when a late-message router is present, or `closed · reply: unavailable` without one. Post-mortem routing still validates the retained conversation and can return a bounded error if it is unavailable; it never resumes workflow execution. Missing capability metadata is not a guarantee that an ask can succeed. Invocation/subgroup visibility and stale-ID rejection are unchanged.
-
-For a retained post-mortem conversation, use its exact Intercom session ID or the previously listed canonical stage path, including its final-stage-name variant. Alternate materialized run-ID paths resolve active stages through the workflow owner; they are not retained aliases after the stage completes. A stage marked `reply: unavailable` rejects an ask with guidance to contact a live stage or start new work with explicit context.
+Moved to [Intercom reference](/intercom/reference#configuration).
 
 ## Keyboard Shortcuts
 
-| Key | Action |
-|-----|--------|
-| ALT+M | Open session list overlay |
-| ↑/↓ | Navigate session list |
-| Enter | Select session / Send message |
-| Escape | Cancel / Close overlay |
+Moved to [Intercom operations](/intercom/operations#keyboard-shortcuts).
 
 ## How It Works
 
-```mermaid
-graph TB
-    subgraph A["Atomic Session A"]
-        A1[Intercom Client]
-        A2[intercom tool]
-        A3[UI overlays]
-    end
-
-    subgraph Broker["Intercom Broker"]
-        B1[Session Registry]
-        B2[Message Router]
-    end
-
-    subgraph B["Atomic Session B"]
-        B3[Intercom Client]
-        B4[intercom tool]
-        B5[UI overlays]
-    end
-
-    A1 <-->|Local Socket/Pipe| B1
-    B1 --- B2
-    B2 <-->|Local Socket/Pipe| B3
-```
-
-The broker is a standalone process that manages session registration and message routing. It auto-spawns when the first session that invokes Intercom needs it and exits 5 seconds after it last has no registered sessions, including brokers that never received a connection and sockets that close before register; clients reconnect automatically if the broker restarts. A reconnect that fails schedules the next attempt on a bounded backoff (1s, 2s, 5s, 10s, then 30s) and keeps retrying until the session connects or shuts down, so recovery never waits for an explicit Intercom call. A failed explicit `intercom` or overlay connection surfaces its error to the caller and still leaves that background retry in place. A reconnect that fails after the broker already accepted it closes that connection first, so a session never appears twice in `intercom list`. A spawn lock keyed by PID and timestamp prevents duplicate brokers when multiple sessions start at once.
-
-A recoverable disconnect is only reported where someone is waiting on it. Work Intercom starts on its own — eager workflow-stage warm-up during `session_start`, the background subagent and pending-stage event relays, and the advisory supervisor-authorization request made before a child launches — does not surface such a disconnect as a stage error; the stage keeps running, and a launch proceeds with supervisor metadata omitted rather than aborting. Recovery still has an owner in every case. Once the heavy module exists, the bounded reconnect backoff above owns it. Warm-up is the one point where no heavy module exists yet to run that backoff, so the wrapper itself retries the warm-up on the same bounded schedule — which matters because a stage holding queued messages waits for that first successful delivery.
-
-When those warm-up attempts run out there is no owner left, and the stage decides its own outcome rather than the extension writing a diagnostic. The wrapper hands the stage's pending delivery a typed terminal reason through the `fail(reason)` member of `WorkflowPendingStageDelivery`; the workflow side turns it into a stage-scoped error naming the run, stage id, and stage name, so `pendingStageDelivery.ready()` settles exactly once instead of waiting forever and the stage ends `failed`. Nothing goes to the console, so no raw extension text reaches the root session's transcript. The queued messages are not consumed either: a delivery asked to drain after that point is a no-op, so the steering stays queued rather than being marked delivered to a stage that never read it. A stage with nothing queued is unaffected — `ready()` still short-circuits and the stage runs.
-
-`fail` is part of the delivery contract rather than an optional extra, because `ready()` has no timeout: a delivery nobody can settle is a stage parked forever. The stage lifecycle also refuses that failure as a model failure — no same-model retry is spent, no fallback candidate is walked, and no `[fallback]` warning blames a model — because a stage refused its queued instructions would be refused them by every candidate. That refusal is by error type, not by message text, so it holds even where the shared model-failure classifier would read the underlying transport error as a retryable network problem. The delivery owner's own reason is kept on the error's `reason` property rather than chained as `cause` for the same reason.
-
-Explicit `intercom` calls, `/intercom`, and the ALT+M overlay still fail visibly. Protocol, authentication, configuration, non-recoverable initialization, and terminal relay failures are reported on every path. An exhausted warm-up retry is terminal too, but it surfaces as the stage failure described above rather than as extension output. Classification is by the error type raised inside the broker client, not by message text, so an identically worded failure from anywhere else stays actionable. A drop that first surfaces as a socket error on an already-registered connection — `ECONNRESET`, `EPIPE`, and the rest — is a recoverable disconnect and enters the same bounded recovery, with the original transport error kept as the `cause` so the code is still there to read. A framing or protocol error keeps its own `Intercom protocol error: …` diagnosis even when a socket error follows it, and a failure before registration completes is never reclassified.
-
-For `send`, `ask`, and `reply`, the tool owns reconnect recovery. One invocation makes the initial attempt and up to three retries, waiting 1, 2, then 5 seconds between attempts. Retries preserve the original message ID, caller arguments, attachment order and presence, and reply thread. The model neither supplies nor receives a retry token. Every new invocation is a fresh intentional operation, even with identical text. Existing integrations must stop passing `retryToken`; caller-supplied tokens are refused without sending.
-
-Before delivery begins, lazy module initialization and startup replay have a separate limit of three reconnect retries on the same delay schedule. Exhaustion or cancellation there reports `outcome: "not_sent"`, since the heavy tool has not executed. This initialization wrapper never retries an already-executed delivery.
-
-Only typed recoverable disconnects start automatic recovery. After one occurs, intermediate nondelivery or uncertain/capacity-bound authority retains the same identity for the remaining attempts. Delivered or queued success ends recovery. An unrelated error ends it without further retries. Cancellation stops new attempts, and the original 11-minute operation deadline bounds retry waits and reply waiting without renewal. A successful receipt remains success even if cancellation arrives while the send is in flight. If recovery cannot establish the outcome, or an accepted ask ends without a reply, the tool returns a terminal error with `outcome: "unknown"` and warns against automatically repeating the operation: delivery may already have occurred. Check with the recipient before intentionally sending a new message. Initial nondelivery and unrelated pre-delivery errors retain their existing classification.
-
-Accepted-operation authority is stored for 12 minutes in `delivered-messages.sqlite`, but canonical payload signatures are never persisted. The broker stores only a fixed 32-byte keyed SHA-256 HMAC (hex encoded) and keeps its random key in the paired `delivered-messages.key`; this remains stable across broker replacement without exposing message or attachment text or enabling offline guesses for low-entropy payloads by users who cannot read the key. The Intercom directory is corrected to owner-only mode (`0700`) and the database, WAL, SHM, and key artifacts to `0600` on POSIX; Windows keeps its platform permission semantics. A missing/malformed database-key pair, malformed digest record, or truncated authority fails closed instead of starting empty.
-
-The broker durably reserves identity before forwarding, then marks it accepted after the confirmed write and before acknowledging the sender. A crash after forwarding and acceptance can therefore return retained success without another delivery; a pre-forward reservation is refused as uncertain. After a deduplicated ask retry, public `reply` first uses the exact recorded sender ID while it remains live, even if another live session shares its name. Only after that ID departs may reconnect-oriented name/stable-route resolution run, and ambiguity, changed stable endpoint or groups, payload, or message ID is refused without sending. An implicit reply retry retains the original sender/question route internally, so a later ask cannot redirect it. Explicit `to` remains caller-controlled and broker `requirePendingReply` authorization remains mandatory. Legacy frames without logical-target metadata keep their transport-target behavior.
-
-Both sides fail closed at memory or storage pressure instead of evicting authority that can still suppress a duplicate. A fresh client operation reserves one of 1,000 identity slots before consuming an ID, showing confirmation UI, resolving its target/reply route, or sending; existing internal retries remain available at full capacity. Confirmation occurs once per invocation. Client retry state is released when the invocation ends or its identity expires, without deleting broker acceptance records. The broker holds at most 10,000 live records and 64 MiB of digest and routing authority; it refuses new delivery until TTL cleanup makes room. The local subagent result relay also reserves before its chat side effect and accepts before positive acknowledgement, refusing its 10,001st live ID and uncertain replays without repeating delivery. SQLite transactions serialize concurrent broker access and stale rows are removed by TTL.
-
-On the broker side, a session is retired as soon as its socket stops being able to accept a frame, rather than only when the connection finally closes. A peer that half-closes, or one whose connection the broker itself ended after refusing a registration, can hold its read side open indefinitely; leaving it in the routing table meant every later broadcast wrote into a socket whose writable side was gone, which destroys that socket and floods `broker.log`. Every broker write now checks writability as part of the write itself. Delivery-producing sends also wait for the socket write callback, so an immediate asynchronous reset cannot be recorded as a successful delivery. A write that fails is answered `Session not found`, the message id stays retryable rather than being recorded as delivered, and no reply authorization is opened for a message that was not sent.
-
-Transport is local IPC only — a Unix domain socket on macOS/Linux or a named pipe on Windows — using length-prefixed JSON (4-byte length + payload) with request correlation for session listing, explicit delivery failures, and validation of malformed or out-of-order messages. `ask` stays client-side: the broker routes plain messages, and the client waits for the matching reply before returning it as the tool result.
-
-Custom hosts may declare an optional `recipientPurpose` on session registration and workflow-stage roster entries. Only `"agent"` and `"control"` are accepted; omission preserves legacy agent behavior. Invalid strings, `null`, and non-string values are rejected, not silently treated as controls. Session purpose is immutable after registration; presence updates cannot change it. Workflow roster-update completion waits for a broker round trip on the announcing connection so subsequent discovery does not race an unprocessed update.
-
-Runtime files live under the active agent directory — `~/.atomic/agent/intercom/` by default, or below `ATOMIC_CODING_AGENT_DIR` when set (the legacy `PI_CODING_AGENT_DIR` alias is honored when the Atomic variable is unset):
-
-- `broker.sock` — Unix domain socket (macOS/Linux; Windows uses a named pipe instead)
-- `broker-launch.vbs` — Windows helper script to launch the broker without a console window
-- `broker.pid` — Broker process ID
-- `broker.spawn.lock` — Short-lived lock used to avoid duplicate auto-spawns
-- `broker.log` — Broker stderr, truncated on every spawn and capped at 8 KiB by the broker itself
-- `delivered-messages.sqlite` — bounded 12-minute accepted-operation authority containing fixed keyed digests, never message or attachment text
-- `delivered-messages.key` — random owner-only HMAC key paired with the authority database
-- `config.json` — User configuration
-
-The broker runs as a detached subprocess, so it does not share the host session's module graph: every module it loads resolves from Node built-ins and Intercom's own files only. Standalone Atomic binaries run it through the internal broker handoff of the same executable, with no external runtime package to resolve.
-
-If the broker fails to start, its stderr is not lost. The parent hands the child an already-open descriptor on `broker.log` (a file, not a pipe, because the broker outlives the session that spawned it) and truncates the file on every spawn. Both the "exited before startup" error and the readiness-timeout error quote the log path and a bounded tail of that output, so `cat ~/.atomic/agent/intercom/broker.log` shows the same text after the fact. On Windows the hidden launcher appends the broker's stderr to the same file.
-
-The file cannot grow without limit. The parent exits while the broker keeps running, so the cap is applied inside the broker, by the entrypoint's very first import — ESM evaluates a module's static dependencies before the importer's own body, so anything installed later would leave those dependencies free to write first. Three routes reach the log and each is capped: `process.stderr.write`, `console.error` / `console.warn`, and the default fatal printing for an uncaught exception or an unhandled rejection. Patching the stream alone would not be enough — Bun's console writes to the file descriptor directly, and neither runtime routes a fatal error through the stream. Anything past 8 KiB is discarded rather than written, on the direct launch and the Windows redirect alike.
-
-What the cap cannot cover, stated plainly: diagnostics a runtime or loader emits before that first import evaluates, native code writing straight to file descriptor 2, a child process of the broker, and hard termination. The broker's own module graph contains no child-process or native-addon edge.
-
-Async extension work (startup, inbound flushes, reconnects, overlays, and relays) no-ops if the session shuts down or reloads before it settles.
+Moved to [Intercom operations](/intercom/operations#how-it-works).
 
 ## Intercom vs Shared-Room Messengers
 
@@ -558,11 +357,7 @@ Use a shared-room messenger for multi-agent swarms working on one shared task. U
 
 ## Limitations
 
-- **Same machine only** — Uses local sockets/pipes, no network support
-- **No dedicated intercom log** — Messages are kept in session history; there is no separate intercom transcript or inbox
-- **No attachments UI** — `file`, `snippet`, and `context` attachments are supported in the protocol, but not in the compose overlay
-- **Only connected sessions appear** — The list shows sessions that have connected to the broker, not every open Atomic process
-- **Broker lifecycle** — The broker auto-spawns on first use and exits when idle; sessions reconnect automatically if it restarts
+Moved to [Intercom operations](/intercom/operations#limitations).
 
 ## Related Docs
 

package/docs/json.md

@@ -1,3 +1,8 @@
+---
+title: "JSON event stream"
+description: "Run one prompt and parse Atomic's output as newline-delimited events."
+---
+
 # JSON Event Stream Mode
 
 ```bash
@@ -8,6 +13,18 @@ Outputs all session events as JSON lines to stdout. Useful for integrating Atomi
 
 If a complete saved provider/model default names a provider that remains unsupported after provider registration, JSON mode writes the generic configuration diagnostic to stderr and exits nonzero before sending the prompt. It writes no human diagnostic to stdout, so any stdout records remain valid JSONL. This differs from ordinary supported-provider model or authentication fallback, which retains normal automatic model selection.
 
+## Choosing an integration mode
+
+JSON mode is one of three ways to drive Atomic from your own software. Pick the smallest one that does the job.
+
+| You want | Use | Why |
+| --- | --- | --- |
+| One prompt, structured output, then exit | **JSON event stream mode** (this page) | One process, one prompt, newline-delimited events on stdout. Nothing to keep alive. |
+| A long-lived process you send more input to | [RPC mode](/rpc) | Send further prompts, interrupt, switch models, and answer tool permission prompts on a live process. |
+| Atomic embedded inside a Node.js application | [SDK](/sdk) | The same engine as a library, with programmatic control over extensions, skills, tools, and session storage. |
+
+If you need the event contract rather than a walkthrough, go to the [RPC protocol](/rpc/protocol) or the [SDK API reference](/sdk/reference). [Programmatic use](/programmatic) compares all three modes side by side.
+
 ## Event Types
 
 Events are defined in [`AgentSessionEvent`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/agent-session.ts#L152):

package/docs/llama-cpp.md

@@ -1,3 +1,8 @@
+---
+title: "Local models"
+description: "Run models locally with a llama.cpp server: discovery, load management, and downloads."
+---
+
 # llama.cpp
 
 Atomic supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router discovers multiple GGUF models and loads or unloads them on demand.

package/docs/models/artificial-analysis-index.md

@@ -0,0 +1,89 @@
+---
+title: "Benchmark Sources"
+description: "The external benchmarks that inform Atomic model selection — Artificial Analysis and DeepSWE — broken down per benchmark: what each measures and when to reference it."
+---
+
+# Benchmark Sources
+
+<Note>
+This is the historical benchmark snapshot retained from the September 3, 2026 documentation baseline. It is not current model-selection guidance. For the latest dated measurements, methodology, and task-specific recommendations, use [Evals](/models/evals) and [Model selection](/models/model-selection).
+</Note>
+
+Atomic's model-selection docs are keyed to two live external benchmark sources rather than a hand-maintained table of scores. This page lists each benchmark, what it measures, and **when to reference it** for a given workflow role — so the docs stay useful as new models ship without a manual rewrite every time.
+
+<Warning>
+No single benchmark is the source of truth. Use these as inputs and validate against Atomic's own workflow evals — public suites test different task distributions than real engineering loops. When Atomic's numbers disagree with a public index, Atomic's evals win. The DeepSWE snapshot used by the linked model-selection pages was updated September 3, 2026 and was re-read from the live source on **2026-09-03**. The Artificial Analysis sections below were **last reviewed 2026-09-01** and were not re-fetched in that pass.
+</Warning>
+
+## The two sources at a glance
+
+| Source | URL | What it is | Reference it for |
+| --- | --- | --- | --- |
+| DeepSWE | [deepswe.datacurve.ai](https://deepswe.datacurve.ai/) | Long-horizon, contamination-free software-engineering tasks (113 tasks, 91 repos, 5 languages), all run on `mini-swe-agent` for consistency | The primary signal for coding-agent routing: real `pass@1`, cost, output tokens, and agent steps on engineering-loop work |
+| Artificial Analysis | [artificialanalysis.ai](https://artificialanalysis.ai/) | Cross-provider intelligence, coding, and agentic indices plus per-capability breakdowns | Cross-domain intelligence, tool use, knowledge reliability, long context, and non-coding capabilities |
+
+## DeepSWE — coding-agent performance
+
+DeepSWE is the closest public proxy for what Atomic actually does. Tasks are written from scratch (not scraped from PRs), so no model has seen the solutions; solutions require substantially more code than SWE-bench-style suites; and verifiers test behavior rather than implementation.
+
+- **Current snapshot:** DeepSWE v1.1, 113 tasks across 91 repositories and 5 languages, updated September 3, 2026. The site reports 28 measured models and displays 21 leaderboard rows by default, out of 70 published model/effort configurations.
+- **Metric:** `pass@1`, plus average cost per task, output tokens, and agent steps.
+- **When to reference:** default weighting for debugger, worker, and any code-writing role. This is the table that drives [Model Selection](/models/model-selection) and [Pareto Efficiency](/models/pareto-efficiency).
+- **Watch:** cost and step count, not just score — a model that passes but takes 268 steps (e.g. sonnet-5) is a poor worker even at a good pass rate, and the two accuracy leaders sit at opposite ends of that axis: Gemini 3.8 Flash leads the highest-published-effort reading the linked pages use at 166 average steps, while the live default Best view's leader, GPT-6 Astra [xhigh], averages 29.
+
+## Artificial Analysis — intelligence and capability breakdown
+
+Artificial Analysis separates performance by benchmark, which lets a workflow pick the model that is strong at the *specific* thing a role needs. Reference the individual evaluations, not just the composite index.
+
+### Composite indices
+
+- **Intelligence Index (v4.1.1)** — composite of the nine evaluations below, weighted across four categories: Agents 34%, Coding 24%, Scientific Reasoning 24%, General 18%. Use as a first-pass filter when a new model appears.
+- **Coding Index** — coding-weighted sub-index. Cross-check against DeepSWE.
+- **Agentic Index** — tool use, planning, autonomy, complex problem solving. The best AA signal for orchestrator and reviewer roles.
+
+### Individual evaluations — what each measures and when to reference
+
+| Benchmark | Measures | Reference it for |
+| --- | --- | --- |
+| GDPval-AA v2 | Agentic real-world work tasks | Orchestrator / planner roles doing economically realistic work |
+| τ³-Banking | Agentic tool use | Tool-heavy workflows and function-calling reliability |
+| Terminal-Bench v2.1 | Agentic coding & terminal use | Debugger and shell-driven workers |
+| SciCode | Coding (scientific) | Code-writing roles in technical domains |
+| Humanity's Last Exam | Reasoning & knowledge | Hard planning / judgment gates |
+| GPQA Diamond | Scientific reasoning | Research roles in technical domains |
+| CritPt | Physics reasoning | Physics/engineering-heavy tasks |
+| AA-Omniscience | Knowledge accuracy & non-hallucination | Research and any role where a confident wrong answer is costly |
+| AA-LCR | Long-context reasoning | Large-codebase research and long-session work |
+
+### Capability indices
+
+Artificial Analysis also publishes per-domain capability indices — **Agentic, Coding, Finance & Accounting, Strategy & Ops, Legal, Healthcare & Medical, Engineering, Economics**. When a workflow is domain-specific, pick by the matching capability index rather than the general Intelligence Index.
+
+<a id="role-benchmark-map"></a>
+
+## Role → benchmark map
+
+A quick lookup for which benchmark to weight per role:
+
+| Role | Primary benchmark | Secondary |
+| --- | --- | --- |
+| Debugger | DeepSWE pass@1 | Terminal-Bench v2.1 |
+| Worker / cheap loop | DeepSWE cost & steps | — |
+| Reviewer / judgment gate | DeepSWE pass@1 | AA Agentic Index |
+| Planner / orchestrator | AA Agentic Index, GDPval-AA v2 | τ³-Banking (tool use) |
+| Research | AA-LCR (long context) | AA-Omniscience (reliability) |
+| Domain-specific work | Matching AA capability index | — |
+
+## Keeping the docs fresh
+
+flora131's guidance on this issue: point the model at the live benchmark URLs and describe what each measures and when to reference it, rather than hardcoding scores that go stale on every release.
+
+1. Treat the model-selection pages as timestamped snapshots that read *from* the live sources above.
+2. When a new model appears on DeepSWE or Artificial Analysis, add it by pulling its numbers from the source — the frontier may move (as the gpt-5.6 family did).
+3. Mark a model **unmeasured** only if it is absent from both sources; unmeasured models may still be operational defaults.
+4. Prefer generating the docs and any future routing policy from the same underlying data, so documentation and routing cannot drift apart.
+
+## Related
+
+- [Model Selection](/models/model-selection)
+- [Pareto Efficiency](/models/pareto-efficiency)

package/docs/models/evals.md

@@ -26,7 +26,7 @@ Practical workflow default: use `low` or `medium` for coding, and `high` or `xhi
 
 | Task type | Benchmark to read | Selected measured candidates | Cost-conscious alternative |
 | --- | --- | --- | --- |
-| Implementing features and fixing bugs | September 3 Datacurve DeepSWE | Astra xhigh, Gemini 3.8 Flash high and Opus 5 max display 74% | Luna max 67% / $0.61; GLM-5.3-Flash max 63% / $0.24 |
+| Implementing features and fixing bugs | September 3 Datacurve DeepSWE | Astra xhigh, Gemini 3.8 Flash high and Opus 5 max display 74% | Luna max 67% / \$0.61; GLM-5.3-Flash max 63% / \$0.24 |
 | Terminal work and shell debugging | Terminal-Bench v4.0 | Astra xhigh 60%, max 59%; Fable 5.1 xhigh with fallback 55% | GLM-5.3-Flash 33% at $0.25 per Index task; task-specific quality is materially lower |
 | Knowledge-work deliverables | AA-Briefcase / GDPval-AA v2, normalized Elo, not pass rates | Fable 5.1 max with fallback 58% / 63%; Opus 5 max 57% / 62% | GLM-5.3-Flash 48% / 58% at $0.25 per Index task |
 | SaaS workflows through REST APIs | AutomationBench-AA | Astra max 68%; Astra high and xhigh, Grok 4.6 high 67% | GLM-5.3-Flash 60%; Luna max 50% |
@@ -109,7 +109,7 @@ What the three charts say together:
 - **Accuracy is flat at the top.** Three models display 74% and a fourth 73%, all inside each other's confidence intervals. Choose among them on cost and steps, not score.
 - **The displayed 74% rows span about fivefold in cost.** Gemini 3.8 Flash [high] costs $2.36 and Opus 5 [max] $11.84. Luna [max] reaches 67% for $0.61. Sonnet 5 [max] costs $26.40 for 54% and 268 steps in this snapshot.
 - **Steps predict wall time and tool-call load.** Astra [xhigh] (29) and Sol [max] (61) finish in a third of the steps that Gemini 3.8 Flash [high] (166) or DeepSeek V4 Pro [max] (155) need. For a worker loop that pays per tool call or that a reviewer must audit, prefer the low-step row at the same accuracy.
-- **The cheap tier is honest about its ceiling.** GLM-5.3-Flash [max] 63% at $0.24 and DeepSeek V4 Flash [max] 53% at $0.46 are the only rows under $1 besides Luna; they are budget workers, not judgment gates.
+- **The cheap tier is honest about its ceiling.** GLM-5.3-Flash [max] 63% at \$0.24 and DeepSeek V4 Flash [max] 53% at \$0.46 are the only rows under \$1 besides Luna; they are budget workers, not judgment gates.
 
 ## Artificial Analysis: current measures