@bastani/atomic 0.9.18 → 0.9.19-alpha.10

package/docs/themes.md

@@ -4,14 +4,18 @@
 
 Themes are JSON files that define colors for the TUI.
 
+## On this page and its reference
+
+This page covers selecting a theme and authoring your first one. The theme file format, every color token, and the accepted color values live in the [Theme reference](/themes/reference).
+
 ## Table of Contents
 
 - [Locations](#locations)
 - [Selecting a Theme](#selecting-a-theme)
 - [Creating a Custom Theme](#creating-a-custom-theme)
-- [Theme Format](#theme-format)
-- [Color Tokens](#color-tokens)
-- [Color Values](#color-values)
+- [Theme Format](/themes/reference#theme-format)
+- [Color Tokens](/themes/reference#color-tokens)
+- [Color Values](/themes/reference#color-values)
 - [Tips](#tips)
 
 ## Locations
@@ -41,6 +45,10 @@ Use `"theme": "light-theme/dark-theme"` for automatic mode. Atomic chooses the f
 
 On first run, Atomic detects your terminal background and defaults to `dark` or `light`.
 
+Main chat, attached workflow-stage chat, and the workflow graph canvas use the terminal's default background, including terminal transparency. Graph node interiors share that background; headers, footers, focused title tabs, and tool cards retain their theme colors.
+
+Truncated workflow-node labels keep the focused tab's fill, text color, and weight through the ellipsis. The surrounding border and node body retain their own styling.
+
 ### Initial Theme
 
 Start an interactive run with a theme without changing the saved setting:
@@ -66,7 +74,7 @@ mkdir -p ~/.atomic/agent/themes
 vim ~/.atomic/agent/themes/my-theme.json
 ```
 
-2. Define the theme with all required colors (see [Color Tokens](#color-tokens)):
+2. Define the theme with all required colors (see [Color Tokens](/themes/reference#color-tokens)):
 
 ```json
 {
@@ -139,173 +147,55 @@ vim ~/.atomic/agent/themes/my-theme.json
 
 ## Theme Format
 
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
-  "name": "my-theme",
-  "vars": {
-    "blue": "#0066cc",
-    "gray": 242
-  },
-  "colors": {
-    "accent": "blue",
-    "muted": "gray",
-    "text": "",
-    ...
-  },
-  "workingIndicator": {
-    "dark": "#70759f",
-    "lift": "#7f849c",
-    "muted": "#789bd0",
-    "accent": "blue",
-    "bright": "#b8d2ff",
-    "peak": "#eef4ff"
-  }
-}
-```
-
-- `name` is required, must be unique, and must not contain `/`.
-- `vars` is optional. Define reusable colors here, then reference them in `colors` or `workingIndicator`.
-- `colors` must define all 51 required tokens. `scrollbarThumb` is optional and falls back to `selectedBg` when omitted. `searchMatchBg` and `searchMatchText` remain accepted for older theme files but are unused.
-- `workingIndicator` is optional and may override any subset of the six tones in the outward half of the ordinary `∀` ramp; Atomic derives omitted tones from selected background, accent, and text roles, then mirrors the palette back after `peak`. Explicit numeric values from 0 through 255 remain exact terminal palette indices. When a numeric index from 0 through 15 seeds an omitted tone, Atomic mixes from its built-in approximation of the common ANSI RGB value; the terminal still controls the actual appearance of the explicit index. Both explicit and derived tones update on theme hot reload.
-
-The `$schema` field enables editor auto-completion and validation.
+Moved to [Theme reference](/themes/reference#theme-format).
 
 ## Color Tokens
 
-Every theme must define all 51 required color tokens. The optional tokens preserve compatibility with themes written before they existed: `scrollbarThumb` and unused `searchMatchBg` fall back to `selectedBg`, and unused `searchMatchText` falls back to `text`.
+Moved to [Theme reference](/themes/reference#color-tokens).
 
 ### Core UI (11 colors)
 
-| Token | Purpose |
-|-------|---------|
-| `accent` | Primary accent (logo, selected items, cursor) |
-| `border` | Normal borders |
-| `borderAccent` | Highlighted borders |
-| `borderMuted` | Subtle borders (editor) |
-| `success` | Success states |
-| `error` | Error states |
-| `warning` | Warning states |
-| `muted` | Secondary text |
-| `dim` | Tertiary text |
-| `text` | Default text (usually `""`) |
-| `thinkingText` | Thinking block text |
+Moved to [Theme reference](/themes/reference#core-ui-11-colors).
 
 ### Backgrounds & Content (11 required, 3 optional)
 
-| Token | Purpose |
-|-------|---------|
-| `selectedBg` | Selected line background |
-| `scrollbarThumb` | Fullscreen scrollbar thumb background; optional, falls back to `selectedBg` |
-| `searchMatchBg` | Unused leftover token; optional, falls back to `selectedBg` |
-| `searchMatchText` | Unused leftover token; optional, falls back to `text` |
-| `userMessageBg` | User message background |
-| `userMessageText` | User message text |
-| `customMessageBg` | Extension message background |
-| `customMessageText` | Extension message text |
-| `customMessageLabel` | Extension message label |
-| `toolPendingBg` | Tool box (pending) |
-| `toolSuccessBg` | Tool box (success) |
-| `toolErrorBg` | Tool box (error) |
-| `toolTitle` | Tool title |
-| `toolOutput` | Tool output text |
+Moved to [Theme reference](/themes/reference#backgrounds-&-content-11-required-3-optional).
 
 ### Markdown (10 colors)
 
-| Token | Purpose |
-|-------|---------|
-| `mdHeading` | Headings |
-| `mdLink` | Link text |
-| `mdLinkUrl` | Link URL |
-| `mdCode` | Inline code |
-| `mdCodeBlock` | Code block content |
-| `mdCodeBlockBorder` | Code block fences |
-| `mdQuote` | Blockquote text |
-| `mdQuoteBorder` | Blockquote border |
-| `mdHr` | Horizontal rule |
-| `mdListBullet` | List bullets |
+Moved to [Theme reference](/themes/reference#markdown-10-colors).
 
 ### Tool Diffs (3 colors)
 
-| Token | Purpose |
-|-------|---------|
-| `toolDiffAdded` | Added lines |
-| `toolDiffRemoved` | Removed lines |
-| `toolDiffContext` | Context lines |
+Moved to [Theme reference](/themes/reference#tool-diffs-3-colors).
 
 ### Syntax Highlighting (9 colors)
 
-| Token | Purpose |
-|-------|---------|
-| `syntaxComment` | Comments |
-| `syntaxKeyword` | Keywords |
-| `syntaxFunction` | Function names |
-| `syntaxVariable` | Variables |
-| `syntaxString` | Strings |
-| `syntaxNumber` | Numbers |
-| `syntaxType` | Types |
-| `syntaxOperator` | Operators |
-| `syntaxPunctuation` | Punctuation |
+Moved to [Theme reference](/themes/reference#syntax-highlighting-9-colors).
 
 ### Thinking Level Borders (6 colors)
 
-Editor border colors indicating thinking level (visual hierarchy from subtle to prominent):
-
-| Token | Purpose |
-|-------|---------|
-| `thinkingOff` | Thinking off |
-| `thinkingMinimal` | Minimal thinking |
-| `thinkingLow` | Low thinking |
-| `thinkingMedium` | Medium thinking |
-| `thinkingHigh` | High thinking |
-| `thinkingXhigh` | Extra high thinking |
+Moved to [Theme reference](/themes/reference#thinking-level-borders-6-colors).
 
 ### Bash Mode (1 color)
 
-| Token | Purpose |
-|-------|---------|
-| `bashMode` | Editor border in bash mode (`!` prefix) |
+Moved to [Theme reference](/themes/reference#bash-mode-1-color).
 
 ### HTML Export (optional)
 
-The `export` section controls colors for `/export` HTML output. If omitted, colors are derived from `userMessageBg`.
-
-```json
-{
-  "export": {
-    "pageBg": "#18181e",
-    "cardBg": "#1e1e24",
-    "infoBg": "#3c3728"
-  }
-}
-```
+Moved to [Theme reference](/themes/reference#html-export-optional).
 
 ## Color Values
 
-Four formats are supported:
-
-| Format | Example | Description |
-|--------|---------|-------------|
-| Hex | `"#ff0000"` | 6-digit hex RGB |
-| 256-color | `39` | xterm 256-color palette index (0-255) |
-| Variable | `"primary"` | Reference to a `vars` entry |
-| Default | `""` | Terminal's default color |
+Moved to [Theme reference](/themes/reference#color-values).
 
 ### 256-Color Palette
 
-- `0-15`: Basic ANSI colors (terminal-dependent)
-- `16-231`: 6×6×6 RGB cube (`16 + 36×R + 6×G + B` where R,G,B are 0-5)
-- `232-255`: Grayscale ramp
+Moved to [Theme reference](/themes/reference#256-color-palette).
 
 ### Terminal Compatibility
 
-Atomic uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, Atomic falls back to the nearest approximation.
-
-Check truecolor support:
-
-```bash
-echo $COLORTERM  # Should output "truecolor" or "24bit"
-```
+Moved to [Theme reference](/themes/reference#terminal-compatibility).
 
 ## Tips
 

package/docs/tmux.md

@@ -1,7 +1,14 @@
+---
+title: "tmux"
+description: "Run Atomic inside tmux, including image paste and key forwarding."
+---
+
 # tmux Setup
 
 Atomic works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `SHIFT+Enter` and `CTRL+Enter` are usually indistinguishable from plain `Enter`.
 
+For terminal automation, prefer Herdr when eligible, with tmux or native Windows psmux as fallbacks. See [Computer use](/computer-use#terminal-automation-with-herdr) for tool selection and safe session control. This page covers Atomic's keyboard setup inside tmux.
+
 ## Recommended Configuration
 
 Add to `~/.tmux.conf`:

package/docs/tools/edit.md

@@ -1,3 +1,8 @@
+---
+title: "edit"
+description: "The edit tool's hashline patch format, operations, and failure modes."
+---
+
 # `edit`
 
 > Applies source edits to existing files with Atomic's hashline patch language, supplied as one `input` string.

package/docs/tools.md

@@ -1,6 +1,25 @@
+---
+title: "Built-in tools"
+description: "The tools Atomic gives the model by default."
+---
+
 # Built-in tools
 
-Atomic enables these coding tools in normal sessions by default: `read`, `write`, `edit`, `bash`, `find`, and `search`.
+Atomic enables these coding tools in normal sessions by default: `read`, `write`, `edit`, `bash`, `kill`, `find`, and `search`.
+
+## `code_search`
+
+The bundled web-access extension provides `code_search` for questions about code, architecture, and APIs in a public GitHub repository. It uses DeepWiki MCP at `https://mcp.deepwiki.com/mcp` without an API key or local MCP configuration.
+
+```typescript
+code_search({ repoName: "facebook/react", query: "How does useEffect cleanup work?" })
+```
+
+Both `repoName` and `query` are required. Supply one repository in `owner/repo` format, not a GitHub URL or list, and a nonempty question. Existing query-only calls must add `repoName`. Questions are sent verbatim to DeepWiki's `ask_question` tool.
+
+Optional `maxTokens` defaults to 5000 and accepts integers from 1000 to 50000. It is a best-effort output bound of roughly four characters per token, plus a truncation notice, not a limit on DeepWiki's generation. Requests have a 60-second deadline and honor cancellation.
+
+Answers depend on DeepWiki's repository indexing and availability. Check the repository name when a question fails. Errors and empty responses do not fall back to Exa; use `web_search` for broader discovery or unavailable repositories. `web_search` retains its existing Exa and other provider support.
 
 ## Hashline editing anchors
 
@@ -24,18 +43,42 @@ insert tail:
 
 Block operations resolve through Atomic's native Rust tree-sitter primitive, with the brace/indent heuristic only as a fallback when the native binding is unavailable. See the [`edit` hashline specification](/tools/edit) for every operation, verified tolerated input shape, output and recovery behavior, limits, worked examples, literal error messages, and warnings.
 
+If a file or its parent directory becomes inaccessible after `edit` prepares a patch, the edit is refused with `FILE_MUTATION_CONFLICT:target_unreadable` and the filesystem error code, such as `EACCES`. No changes are written. Restore access, then read the file again before retrying.
+
+## `write`
+
+`write` overwriting an existing file requires this session to have already observed exactly the content it is replacing, checked under the same per-file mutation queue that serializes the write itself. Creating a new file is unaffected, and so is overwriting a file this session read, wrote, or edited earlier. Where a session has no version of its own, the refusal is `no_prior_observation`; where it has one that no longer matches what is on disk, it is `changed_since_observation` and names the first diverging line, what the session assumed was there, and what the file holds instead. Both carry the same `FILE_MUTATION_CONFLICT` code and requester identity as an `edit` conflict, so a `write` that would have silently discarded another agent's file is reported rather than performed. Snapshots are per session, so a file read by a different session or a previous run does not authorize an overwrite here either. A write whose result is aborted after the bytes have already reached disk still records its snapshot, so retrying it is not mistaken for overwriting a stranger's file.
+
+Standalone `createWriteToolDefinition(cwd)` and `createWriteTool(cwd)` instances retain their own observations across `local://` writes, just as they do for plain paths, even when no `hashlineStore` is supplied. Separate instances still need an explicitly shared store to share observations.
+
+Creating a file claims the path exclusively. `write` asks the filesystem for create-or-fail semantics (`O_EXCL`) whenever it has just observed the path as absent, so a file that appears in the window between that check and the write is reported as `target_exists` with a description of what is there now, rather than being silently truncated. Overwrites do not request exclusivity, since they are replacing a file the session has already accounted for.
+
+`WriteOperations` carries the read `write` performs before every write. Custom implementations must supply it, and it must report absence as `undefined` while rejecting for anything else: a path that exists but cannot be read is not a free path, and reporting it as absent would present it as a fresh create and truncate it. Such a rejection surfaces as `target_unreadable`, including the filesystem error code when the backend supplies one. Routing the read through `WriteOperations` is what lets a remote or sandboxed implementation have these checks run against the filesystem its writes actually land on, instead of against local disk. An implementation that cannot express exclusive create may ignore that request and overwrite; it then loses only the race against writers outside Atomic, since the mutation queue already excludes writers inside it.
+
 ## `bash` and `bashInterceptor`
 
 The `bash` tool executes shell commands in the session workspace, with optional PTY handling. When `pty: true` is requested, local execution uses the bundled Rust-backed PTY session; if the native PTY package is unavailable, Atomic degrades to normal pipe execution. Set `PI_NO_PTY=1` or `ATOMIC_NO_PTY=1` to force normal pipe execution. Foreground results include oh-my-pi-style `timeoutSeconds`, `requestedTimeoutSeconds`, `wallTimeMs`, and non-zero `exitCode` metadata, and preserve overflow output in a temporary `fullOutputPath` when output is truncated.
 
 When explicitly enabled in settings, built-in bash interceptor rules block common shell substitutes for first-class tools (`cat`/`grep`/`find`/in-place `sed`/redirection, etc.) only when the corresponding tool is available. Enabled bash tool calls are also offered to `user_bash` extension handlers before local execution. Atomic checks the original command, the internal-URL-expanded command, configured-prefix forms, `spawnHook`-rewritten commands, and a leading `cd path && command` or `cd path; command`-stripped form only when structured `cwd` was omitted, so interceptors can route commands by effective working directory without overriding explicit `cwd`. The bash schema accepts `cwd`, `env`, `timeout`, and `pty`; `cwd` and `env` are honored by the local executor. Omitting `timeout` uses the 300-second default. An explicit timeout must be finite, greater than zero, and no more than Atomic's deliberate 3600-second ceiling; invalid values fail before execution instead of being defaulted or clamped. Valid fractional values are rounded down with a one-second floor. `bashInterceptor.enabled` defaults to `false`; interception is not auto-enabled.
 
+Shell internal-URL expansion is intentionally conservative: commands containing a resolved URL must use only plain unquoted words, spaces/tabs, and basic `;`, `|`, or `&` operators. For example, `printf %s local://notes.txt` is supported and the resolved path is shell-quoted automatically, including paths containing spaces or shell metacharacters. Quotes anywhere in such a command, substitutions, escapes, newlines, redirections and heredocs are rejected before execution; use a filesystem path instead for those forms. Commands without resolved internal URLs retain normal shell syntax. URL expansion in structured `cwd` and `env` values is unchanged.
+
+The `powershell` tool uses PowerShell single-quoted literals for resolved paths, doubling both ASCII apostrophes and PowerShell's smart single-quote delimiters (U+2018–U+201B). Bash keeps POSIX quoting, including when Bash runs on Windows. SDK adapters using `createBashToolDefinition` with custom PowerShell operations can set `shellDialect: "powershell"` for generated path literals; this option does not select the executable or rewrite deliberate shell code.
+
+Configured command prefixes and SDK `spawnHook` rewrites remain executable shell syntax, not a sandbox. Balanced setup commands such as quoted exports remain supported. A prefix that leaves a quote, substitution, or heredoc open across the following command can invalidate the generated path quoting; automatic URL expansion does not validate that composed shell context. Do not combine URL expansion with such wrappers. Use structured `cwd` and `env` for path data instead.
+
 ```json
 {
   "bashInterceptor": { "enabled": true }
 }
 ```
 
+## `kill`
+
+`kill({ id: taskId })` stops an owned background shell task launched by `bash` or `powershell`, including a command that automatically yielded. Pass its returned task ID verbatim, not a PID. The tool is owner-scoped in main and workflow-stage chat and does not cancel subagents or another owner's work.
+
+The result reports the cancellation decision and current execution and cleanup states. A request is not confirmation of termination. Repeated requests preserve the original cancellation decision; already-completed work retains its outcome. Cleanup failures are reported explicitly. See [Background tasks](/background-tasks#stop-a-shell-task-from-a-tool-call) for states, retained output, and `/tasks` controls.
+
 ## `find` and `search`
 
 `find` finds filesystem paths by glob; use `search` when you need content matches instead of path matches. `find.paths` is required and accepts file, directory (including a filesystem root), internal URL, or glob paths; copied quoted paths are normalized, exact filesystem paths with spaces/commas/semicolons are preserved before delimiter expansion, comma/semicolon-joined paths are split when at least one part resolves, whitespace-joined paths are split only when every part resolves, hidden files are included by default, `.gitignore` is respected by default (including nested `.gitignore` files outside a Git checkout), broad scans keep `node_modules`/`.git` pruned even with `gitignore:false` unless `node_modules` is explicitly present in the requested path or glob, results are capped at 200 by default, and timeout defaults to 5 seconds. Local `find` prefers the bundled Rust native `glob` implementation derived from oh-my-pi, falling back to the packaged `fd` helper only when native bindings are unavailable. Results include `scopePath`, `fileCount`, `files`, truncation/missing-path metadata, and streamed `onUpdate` snapshots during long scans.
@@ -46,6 +89,29 @@ Directory `read` output renders an oh-my-pi-style depth-2 tree sorted by most-re
 
 Plain URL reads follow oh-my-pi's fetch-pipeline truncation contract: unselected URL output shows the first 300 rendered lines (capped at 50 KiB), preserves full-output artifact/truncation metadata when available, and does not hard-block solely because the rendered URL body is large. By default Atomic rejects private, localhost, cloud-metadata, numeric/short-form private-IP URL targets (for example `2130706433`, octal/hex dotted forms, and `127.1`), IPv4-compatible and IPv4-mapped IPv6, NAT64, 6to4 private-address forms, and the full IPv6 link-local `fe80::/10` range, revalidates each manual redirect, pins DNS-validated addresses for outbound fetches, and caps streamed URL bodies; `ATOMIC_ALLOW_PRIVATE_URL_READS=1` is a dev-only escape hatch for trusted local tests and must not be set from untrusted project configuration. Local text reads use the shared 3,000-line/50 KiB output cap, while search match/context lines use the upstream 512-character cap before emitting a truncation notice.
 
+## `ask_user_question`
+
+When `ask_user_question` or an equivalent question tool is available, all questions to the user must use that tool instead of plain text. This includes clarifications, preferences, confirmations, approvals, and permission to proceed, not just ambiguous requirements. Prefer `ask_user_question` when available; otherwise follow the equivalent tool's supported schema. In these sessions, do not end a progress update or final response with a prose-only "Proceed?".
+
+Ask only when a decision is needed. Do not ask again for already-authorized work. Group related questions in one call, up to four questions with two to four options each. For confirmations, state the concrete action and scope in the question and offer explicit proceed and decline options. For example, when this action needs approval, call `ask_user_question` with:
+
+```json
+{
+  "questions": [{
+    "header": "Merge approval",
+    "question": "Remove the stack grouping, then admin-merge the same seven PRs in dependency order without changing repository protections?",
+    "options": [
+      { "label": "Proceed", "description": "Remove the grouping and admin-merge those seven PRs in dependency order. Leave repository protections unchanged." },
+      { "label": "Do not proceed", "description": "Leave the grouping and PRs unchanged." }
+    ]
+  }]
+}
+```
+
+In a real confirmation, identify the target PRs in the question or immediately preceding context. This example explains question routing; it does not authorize merging any PRs.
+
+A cancelled or unanswered question is not approval. If no usable question tool is available, continue autonomously using best judgment and state evidence-backed assumptions rather than stopping just because the tool is missing. Preserve safety, authorization, and explicit approval gates. Workflow-authored `ctx.ui` gates and `workflow answer` for relaying actual user responses remain supported.
+
 ## Persisted tool output
 
 Output that does not fit in a tool result is written to a file, and the result points at it — `Full output: <path>` for `bash`, `Full output saved to: <path>` for any tool result that crosses the persistence threshold. Those files are storage, so Atomic bounds where they go, how large they get, and how long they live.