@bastani/atomic 0.5.18 → 0.5.19

package/README.md

@@ -9,249 +9,145 @@
 [![Bun](https://img.shields.io/badge/Bun-Runtime-f9f1e1?logo=bun&logoColor=black)](./package.json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-Atomic is an open-source **TypeScript SDK** for building **any harness you want** around your coding agent — **Claude Code**, **OpenCode**, or **GitHub Copilot CLI**. Chain sessions into pipelines, add human-in-the-loop approval gates, plug in CI and notifications, dispatch **12 specialized sub-agents**, and tap **55 built-in skills** — then ship it as TypeScript your whole team runs.
+**An open-source TypeScript SDK for building harnesses around your coding agent** — Claude Code, OpenCode, or GitHub Copilot CLI. Chain agent sessions into deterministic pipelines, add human-in-the-loop approval gates, dispatch **12 specialized sub-agents**, and tap **55 built-in skills** — then ship it as TypeScript your whole team runs.
 
 > Define how your agent works. Start for yourself, scale to your team.
 
 ---
 
-## Why Atomic
-
-Coding agents keep getting more capable — better reasoning, larger context windows, more reliable tool use. But a more capable model doesn't reduce the need for structure around it. It **increases** it.
-
-The bottleneck is shifting from "can my agent write this code?" to "can my agent follow my process?" Every team has a process — how code gets reviewed, what checks run before merging, who approves deployments, how production gets monitored. That process lives in wikis nobody reads, in one senior engineer's head, or nowhere at all. A powerful agent without a defined process is just a faster way to ship unreviewed code.
-
-**Harnesses are what turn a capable agent into a reliable part of your engineering workflow.** A harness encodes your process — research, then implement, then review, then run CI, then create a PR, then notify the right person, then wait for approval, then merge. Without one, you're prompting manually and copy-pasting between terminal sessions. With one, you run a single command and the process executes itself.
+## Quick Start
 
-Better models make harnesses **more** important, not less. The more you can trust an agent to execute complex tasks, the more value you get from defining exactly **what** it should execute, in **what order**, with **what checks** along the way. The harness is the durable layer — models will keep improving underneath it, but your process stays the same.
+Install, generate context, try Ralph, then write your own workflow — four steps, a few minutes.
 
-Atomic gives you the SDK to build that harness:
+### Prerequisites
 
-- **Start for yourself.** Automate the repetitive parts of your own workflow — research a codebase, add monitoring, generate specs. One developer, one afternoon, one TypeScript file.
-- **Scale to your team.** Encode your team's review process, deployment gates, and quality checks as TypeScript that every team member runs identically. Your process becomes versioned, testable, and reproducible — not tribal knowledge.
-- **Work across agents.** Write a harness once, run it on Claude Code, OpenCode, or Copilot CLI with a flag change. The harness is the constant; the agent is swappable.
+- **At least one coding agent** installed and logged in:
+  - [Claude Code](https://code.claude.com/docs/en/quickstart) — run `claude` and authenticate
+  - [OpenCode](https://opencode.ai) — run `opencode` and authenticate
+  - [GitHub Copilot CLI](https://github.com/features/copilot/cli) — run `copilot` and authenticate
+- **Windows:** PowerShell 7+ ([install guide](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows))
 
-### What You Can Build
+### 1. Install
 
-**Add production monitoring to your codebase.** Build a harness that researches your current observability setup, identifies gaps in metrics, health checks, and alerting, implements the missing pieces, and reviews the changes — all in one run.
+The bootstrap script installs [Bun](https://bun.sh/), Atomic, and shell completions in one step:
 
 ```bash
-atomic workflow -n add-monitoring -a claude "add Prometheus metrics and health checks to all API endpoints"
-```
-
-**Automate your team's review-to-merge pipeline.** Encode your exact process: review code changes → run security scans and linting in parallel → create a PR → notify the team lead on Slack → wait for human approval → merge. The [human-in-the-loop gate](#workflow-sdk--build-your-own-deterministic-harness) pauses execution until the right person approves. New team members inherit the same pipeline on day one.
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
 
-```bash
-atomic workflow -n review-to-merge -a claude
+# Windows (PowerShell 7+)
+irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
 ```
 
-**Run parallel UX testing with 50 personas.** Spin up 50 agents — each with a distinct user persona (first-time user, power user, accessibility-dependent user, non-technical stakeholder) — each using [Playwright](#built-in-skills) to navigate your app and report usability issues from their perspective. Batch in groups, aggregate findings, and get feedback at a scale no manual process can match.
+Upgrade later with `bun update -g @bastani/atomic`.
+
+<details>
+<summary><b>Alternative: Already have Bun? Install directly from npm</b></summary>
 
 ```bash
-atomic workflow -n ux-personas -a claude
+bun install -g @bastani/atomic
 ```
 
-Each of these is a `.ts` file using Atomic's [Workflow SDK](#workflow-sdk--build-your-own-deterministic-harness). See [Build a Workflow](#4-build-a-workflow) for a working example, or read the full SDK reference below.
+This skips the Bun install step but doesn't set up shell completions — run `atomic completions <shell>` separately if you want them (see [Commands Reference](#atomic-completions--shell-completions)).
 
----
-
-## Table of Contents
+**Prerelease builds:** `bun install -g @bastani/atomic@next` (may contain breaking changes).
 
-- [Atomic](#atomic)
-  - [Why Atomic](#why-atomic)
-    - [What You Can Build](#what-you-can-build)
-  - [Table of Contents](#table-of-contents)
-  - [Quick Start](#quick-start)
-    - [Prerequisites](#prerequisites)
-    - [1. Install](#1-install)
-    - [2. Generate Context Files](#2-generate-context-files)
-    - [3. Managing Sessions](#3-managing-sessions)
-    - [4. Build a Workflow](#4-build-a-workflow)
-  - [Core Features](#core-features)
-    - [Multi-Agent Support](#multi-agent-support)
-    - [Workflow SDK — Build Your Own Deterministic Harness](#workflow-sdk--build-your-own-deterministic-harness)
-      - [Builder API](#builder-api)
-      - [WorkflowContext (`ctx`) — top-level orchestrator](#workflowcontext-ctx--top-level-orchestrator)
-      - [SessionContext (`s`) — inside each session callback](#sessioncontext-s--inside-each-session-callback)
-      - [Session Options (`SessionRunOptions`)](#session-options-sessionrunoptions)
-      - [Saving Transcripts](#saving-transcripts)
-      - [Per-Agent Session APIs](#per-agent-session-apis)
-      - [Key Rules](#key-rules)
-    - [Research Codebase](#research-codebase)
-    - [Autonomous Execution (Ralph)](#autonomous-execution-ralph)
-    - [Deep Research Codebase](#deep-research-codebase)
-    - [Containerized Execution](#containerized-execution)
-    - [Specialized Sub-Agents](#specialized-sub-agents)
-    - [Built-in Skills](#built-in-skills)
-    - [Workflow Orchestrator Panel](#workflow-orchestrator-panel)
-  - [Commands Reference](#commands-reference)
-    - [CLI Commands](#cli-commands)
-      - [Global Flags](#global-flags)
-      - [`atomic session` Subcommands](#atomic-session-subcommands)
-      - [`atomic chat` Flags](#atomic-chat-flags)
-      - [`atomic workflow` Flags](#atomic-workflow-flags)
-      - [`atomic completions` — Shell Completions](#atomic-completions--shell-completions)
-    - [Atomic-Provided Skills (invokable from any agent chat)](#atomic-provided-skills-invokable-from-any-agent-chat)
-  - [Configuration](#configuration)
-    - [`.atomic/settings.json`](#atomicsettingsjson)
-    - [Agent-Specific Files](#agent-specific-files)
-  - [Installation Options](#installation-options)
-    - [Bun (recommended)](#bun-recommended)
-    - [Devcontainer (recommended for autonomous agents)](#devcontainer-recommended-for-autonomous-agents)
-  - [Updating \& Uninstalling](#updating--uninstalling)
-    - [Update](#update)
-    - [Uninstall](#uninstall)
-  - [Troubleshooting](#troubleshooting)
-  - [FAQ](#faq)
-  - [Contributing](#contributing)
-  - [License](#license)
-  - [Credits](#credits)
-
----
-
-## Quick Start
-
-### Prerequisites
-
-- **macOS, Linux, or Windows** (PowerShell 7+ required on Windows — [install guide](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows))
-- **[Bun](https://bun.sh/)** runtime installed
-- **At least one coding agent installed and logged in:**
-  - [Claude Code](https://code.claude.com/docs/en/quickstart) — run `claude` and complete authentication
-  - [OpenCode](https://opencode.ai) — run `opencode` and complete authentication
-  - [GitHub Copilot CLI](https://github.com/features/copilot/cli) — run `copilot` and complete authentication
+</details>
 
-### 1. Install
+<details>
+<summary><b>Authenticated downloads (CI / enterprise)</b></summary>
 
-Atomic is distributed as a single npm package that exposes both the CLI binary and the Workflow SDK. You have three install paths depending on your environment.
+Set `GITHUB_TOKEN` to avoid GitHub API rate limits when running the bootstrap script in CI:
 
-**Option A — Devcontainer (recommended for safe autonomous execution):**
+```bash
+# macOS / Linux
+GITHUB_TOKEN=ghp_... curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
 
-> [!TIP]
-> Devcontainers isolate the coding agent from your host system, reducing the risk of destructive actions like unintended file deletions or misapplied shell commands. This is the safest way to run Atomic, especially for multi-hour autonomous sessions with Ralph.
->
-> Use the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) for VS Code or [DevPod](https://devpod.sh) to spawn and manage your devcontainers.
+# Windows PowerShell
+$env:GITHUB_TOKEN='ghp_...'; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
+```
 
-Add a single feature to your `.devcontainer/devcontainer.json` — this installs Atomic, the coding agent, GitHub CLI, and all dependencies automatically.
+</details>
 
-```
-your-project/
-├── .devcontainer/
-│   └── devcontainer.json   ← add the feature here
-├── src/
-└── ...
-```
+<details>
+<summary><b>Alternative: Devcontainer (recommended for autonomous workflows)</b></summary>
 
-On first run, Atomic automatically sets up all required tooling (Node.js, tmux, Playwright CLI, config files, skills, and agent configurations). This happens once and takes about a minute.
+> Devcontainers isolate the agent from your host, limiting the blast radius of destructive actions. This is the safest way to run workflows.
 
-| Feature              | Reference                            | Agent                                                |
-| -------------------- | ------------------------------------ | ---------------------------------------------------- |
-| Atomic + Claude Code | `ghcr.io/flora131/atomic/claude:1`   | [Claude Code](https://claude.ai)                     |
-| Atomic + OpenCode    | `ghcr.io/flora131/atomic/opencode:1` | [OpenCode](https://opencode.ai)                      |
-| Atomic + Copilot CLI | `ghcr.io/flora131/atomic/copilot:1`  | [Copilot CLI](https://github.com/github/copilot-cli) |
+Add one feature to `.devcontainer/devcontainer.json`:
 
-Each feature installs the Atomic CLI from npm, all shared dependencies (bun, playwright-cli), agent-specific configurations (agents, skills), and the agent CLI itself. Features are versioned in sync with Atomic CLI releases.
+| Feature                              | Agent                |
+| ------------------------------------ | -------------------- |
+| `ghcr.io/flora131/atomic/claude:1`   | Atomic + Claude Code |
+| `ghcr.io/flora131/atomic/opencode:1` | Atomic + OpenCode    |
+| `ghcr.io/flora131/atomic/copilot:1`  | Atomic + Copilot CLI |
 
-**Option B — Bun global install (simplest for local use):**
+Full `.devcontainer.json` templates per agent live in [`.devcontainer/`](./.devcontainer/). Each feature installs Atomic, bun, playwright-cli, agent configs, and the agent CLI itself. First run takes ~1 minute to warm up.
 
-If you already have [Bun](https://bun.sh) installed, a single command is enough:
+Minimal example (Claude + Rust):
 
-```bash
-bun install -g @bastani/atomic
+```jsonc
+{
+  "image": "mcr.microsoft.com/devcontainers/rust:latest",
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils": {},
+    "ghcr.io/flora131/atomic/claude:1": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "remoteEnv": {
+    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
+  }
+}
 ```
 
-This installs the `atomic` binary on your PATH. `bun update -g @bastani/atomic` upgrades to the latest release.
+Use the [Dev Containers VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or the [Dev Container CLI](https://github.com/devcontainers/cli#dev-container-cli) to start the container.
 
-**Option C — Bootstrap script (installs bun + atomic + shell completions in one step):**
+</details>
 
-For machines without Bun, the bootstrap scripts install Bun, Atomic, and shell completions together:
+<details>
+<summary><b>Migrating from the old standalone binary?</b></summary>
 
-macOS / Linux:
+Atomic used to ship as a standalone binary. It's now an npm package. One-time migration:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
-```
-
-Windows PowerShell 7+:
-
-```powershell
-irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
+atomic uninstall
+bun uninstall -g @bastani/atomic-workflows
+rm -rf ~/.atomic ~/.copilot/skills ~/.opencode/skills
+bun install -g @bastani/atomic
 ```
 
+</details>
 
-> [!IMPORTANT]
-> **Migrating from the old standalone binary?** The old version of Atomic was a standalone binary. It is now distributed as an npm package. To migrate:
->
-> 1. Uninstall the old binary: `atomic uninstall`
-> 2. Uninstall the old workflows package: `bun uninstall -g @bastani/atomic-workflows`
-> 3. Delete the old config directory: `rm -rf ~/.atomic`
-> 4. Remove legacy skill directories: `rm -rf ~/.copilot/skills ~/.opencode/skills`
-> 5. Re-install using any of the install options above
-
-### 2. Generate Context Files
-
-Start a chat session and run `/init` to generate `CLAUDE.md` and `AGENTS.md`:
+### 2. Generate context files
 
 ```bash
 atomic chat -a <claude|opencode|copilot>
 ```
 
-```
-/init
-```
-
-This explores your codebase using sub-agents and generates documentation that gives coding agents the context they need.
+Then type `/init`. Atomic explores your codebase with sub-agents and writes `CLAUDE.md` / `AGENTS.md` so every future session starts with the right context.
 
-### 3. Managing Sessions
+### 3. Try Ralph (autonomous coding)
 
-Atomic runs every chat and workflow session inside [tmux](https://github.com/tmux/tmux) on a dedicated socket, isolated from any personal tmux sessions you may have running. Use the built-in `session` commands to manage them:
+Ralph plans, implements, reviews, and debugs a task on its own — up to 10 iterations, exiting after 2 consecutive clean reviews.
 
 ```bash
-# List all running sessions
-atomic session list
-
-# List only chat sessions
-atomic chat session list
-
-# List only workflow sessions
-atomic workflow session list
-
-# Connect to a session by name
-atomic session connect <session-name>
-
-# Interactive session picker (fuzzy-search)
-atomic session connect
-
-# Kill a session by name (prompts for confirmation)
-atomic session kill <session-name>
-
-# Kill all sessions in scope (prompts for confirmation)
-atomic session kill
+atomic workflow -n ralph -a claude "Build a REST API for user management"
 ```
 
-Session names follow a predictable pattern:
+> ⚠️ Workflows run with agent permission checks **disabled** so pipelines don't block on prompts. Run them in a [devcontainer](#containerized-execution) or [git worktree](https://git-scm.com/docs/git-worktree), not on your host. See [Security](#security-workflow-permissions-model).
 
-| Session type | Name format                 | Example                    |
-| ------------ | --------------------------- | -------------------------- |
-| Chat         | `atomic-chat-<id>`          | `atomic-chat-a1b2c3d4`     |
-| Workflow     | `atomic-wf-<workflow>-<id>` | `atomic-wf-ralph-x9y8z7w6` |
+### 4. Build your own workflow
 
-> **Tip:** If your terminal disconnects or you accidentally close the window, your session is still alive — just run `atomic session connect <session-name>` to pick up where you left off.
-
-### 4. Build a Workflow
-
-Every team has a process. Atomic lets you encode it as TypeScript — chain agent sessions together, pass transcripts between them, and run the whole thing from the CLI.
-
-Create a workflow project, install the SDK, and add your workflow file:
+Every team has a process — code review, CI checks, PR creation, approval, merge. Encode it as TypeScript once; everyone runs the same pipeline.
 
 ```bash
 bun init && bun add @bastani/atomic
 mkdir -p .atomic/workflows/review-to-merge/claude
 ```
 
-Here's one of the [canonical use cases](#what-you-can-build) — a team pipeline that reviews code, runs checks in parallel, creates a PR, notifies on Slack, waits for human approval, and merges:
+Create `.atomic/workflows/review-to-merge/claude/index.ts`:
 
 ```ts
-// .atomic/workflows/review-to-merge/claude/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
 export default defineWorkflow({
@@ -259,60 +155,38 @@ export default defineWorkflow({
   description: "Review → CI → PR → Notify → Approve → Merge",
 }).for<"claude">()
   .run(async (ctx) => {
-    // Step 1: Review the changes
-    const review = await ctx.stage(
-      { name: "review", description: "Review code changes" },
-      {}, {},
-      async (s) => {
-        await s.session.query(
-          "Review all uncommitted changes. Flag issues with correctness, security, and style.",
-        );
-        s.save(s.sessionId);
-      },
-    );
+    // 1. Review
+    const review = await ctx.stage({ name: "review" }, {}, {}, async (s) => {
+      await s.session.query("Review uncommitted changes for correctness, security, style.");
+      s.save(s.sessionId);
+    });
 
-    // Step 2: Run security and CI checks in parallel
+    // 2. Run security + CI in parallel
     await Promise.all([
       ctx.stage({ name: "security-scan" }, {}, {}, async (s) => {
-        await s.session.query("Run `bun audit` and scan for leaked secrets or credentials.");
+        await s.session.query("Run `bun audit` and scan for leaked secrets.");
         s.save(s.sessionId);
       }),
       ctx.stage({ name: "ci-checks" }, {}, {}, async (s) => {
-        await s.session.query("Run `bun lint` and `bun test`. Report any failures.");
+        await s.session.query("Run `bun lint` and `bun test`. Report failures.");
         s.save(s.sessionId);
       }),
     ]);
 
-    // Step 3: Create a PR with the review summary
-    await ctx.stage({ name: "create-pr" }, {}, {}, async (s) => {
-      const transcript = await s.transcript(review);
-      await s.session.query(
-        `Read the review at ${transcript.path}. Create a pull request summarizing the changes.`,
-      );
-      s.save(s.sessionId);
-    });
-
-    // Step 4: Notify on Slack, then wait for human approval before merging.
-    // Stage callbacks are plain Bun code — fetch(), Bun.spawn(), and any
-    // Node API work here alongside agent session queries.
+    // 3. Open PR, then notify Slack + wait for human approval
     await ctx.stage({ name: "notify-and-merge" }, {}, {}, async (s) => {
+      const t = await s.transcript(review);
+      await s.session.query(`Read ${t.path}. Open a PR summarizing the changes.`);
+
       await fetch("https://slack.com/api/chat.postMessage", {
         method: "POST",
-        headers: {
-          Authorization: `Bearer ${process.env.SLACK_TOKEN}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          channel: "#code-review",
-          text: "New PR ready for review — please approve in GitHub.",
-        }),
+        headers: { Authorization: `Bearer ${process.env.SLACK_TOKEN}` },
+        body: JSON.stringify({ channel: "#code-review", text: "PR ready — please approve." }),
       });
 
-      // Human-in-the-loop: AskUserQuestion pauses the session until the
-      // user responds. The agent won't merge until approval is given.
+      // Human-in-the-loop: pauses until the user responds
       await s.session.query(
-        "The team has been notified on Slack. Ask the user to confirm the PR " +
-        "is approved, then merge it with `gh pr merge --squash`.",
+        "Ask the user to confirm approval, then merge with `gh pr merge --squash`.",
         { allowedTools: ["Bash", "Read", "AskUserQuestion"] },
       );
       s.save(s.sessionId);
@@ -327,9 +201,96 @@ Run it:
 atomic workflow -n review-to-merge -a claude
 ```
 
-This single file demonstrates multi-step pipelines, parallel stages (`Promise.all`), transcript passing between sessions, external API calls (`fetch`), and human-in-the-loop approval — all in plain TypeScript. Swap `-a claude` for `-a opencode` or `-a copilot` to run the same harness on a different agent. See [Workflow SDK — Build Your Own Harness](#workflow-sdk--build-your-own-deterministic-harness) for the full API and more examples.
+Swap `-a claude` for `-a opencode` or `-a copilot` — same harness, different agent. See [Workflow SDK](#workflow-sdk--build-your-own-deterministic-harness) for parallel stages, input schemas, headless stages, and the full API reference.
+
+### Managing sessions
+
+Every chat and workflow runs inside an isolated [tmux](https://github.com/tmux/tmux) session on a dedicated socket (your personal tmux is untouched). If your terminal disconnects, your session keeps running — reconnect anytime.
+
+```bash
+atomic session list              # all sessions
+atomic session connect           # interactive fuzzy picker
+atomic session connect <name>    # by name
+atomic session kill <name>       # kill one (or all, with confirmation)
+```
 
-> **Want something that works out of the box?** Atomic ships with `ralph`, a built-in workflow that plans, implements, reviews, and debugs autonomously — see [Autonomous Execution (Ralph)](#autonomous-execution-ralph).
+Session names follow `atomic-chat-<id>` or `atomic-wf-<workflow>-<id>`. Scope with `atomic chat session …` or `atomic workflow session …`.
+
+Need a workflow to run in the background while you do something else? Pass `-d` / `--detach`:
+
+```bash
+atomic workflow -n ralph -a claude -d "build the auth module"   # returns immediately
+atomic workflow session connect atomic-wf-claude-ralph-<id>      # attach later
+```
+
+Detached mode is what you want for scripted / CI automation and long-running tasks — the orchestrator keeps running on the atomic tmux socket regardless of your terminal.
+
+---
+
+## Why Atomic
+
+Better models make harnesses **more** important, not less. The more you trust an agent to execute complex tasks, the more value you get from defining exactly **what** it should execute, in **what order**, with **what checks** along the way. The harness is the durable layer — models keep improving underneath it, but your process stays the same.
+
+- **Start for yourself.** Automate the repetitive parts of your own workflow — research a codebase, add monitoring, generate specs. One TypeScript file, one afternoon.
+- **Scale to your team.** Encode your team's review process, deployment gates, and quality checks as TypeScript every member runs identically — versioned, testable, reproducible.
+- **Work across agents.** Write a harness once, run it on Claude Code, OpenCode, or Copilot CLI with a flag change.
+
+### Example use cases
+
+**Add production monitoring.** Research observability gaps, implement missing metrics and health checks, review the changes.
+
+```bash
+atomic workflow -n add-monitoring -a claude "add Prometheus metrics and health checks to all API endpoints"
+```
+
+**Parallel UX testing with 50 personas.** Spin up 50 agents, each with a distinct persona (power user, accessibility-dependent, non-technical stakeholder), each using [Playwright](#built-in-skills) to test your app.
+
+```bash
+atomic workflow -n ux-personas -a claude
+```
+
+**Review-to-merge pipeline.** The workflow from [step 4](#4-build-your-own-workflow) above — reviews code, runs CI in parallel, opens a PR, notifies Slack, waits for approval, merges.
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Why Atomic](#why-atomic)
+- [Security: Workflow Permissions Model](#security-workflow-permissions-model)
+- [Core Features](#core-features)
+  - [Multi-Agent Support](#multi-agent-support)
+  - [Workflow SDK](#workflow-sdk--build-your-own-deterministic-harness)
+  - [Research Codebase](#research-codebase)
+  - [Autonomous Execution (Ralph)](#autonomous-execution-ralph)
+  - [Deep Research Codebase](#deep-research-codebase)
+  - [Containerized Execution](#containerized-execution)
+  - [Specialized Sub-Agents](#specialized-sub-agents)
+  - [Built-in Skills](#built-in-skills)
+  - [Workflow Orchestrator Panel](#workflow-orchestrator-panel)
+- [Commands Reference](#commands-reference)
+- [Configuration](#configuration)
+- [Updating & Uninstalling](#updating--uninstalling)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [License](#license)
+- [Credits](#credits)
+
+---
+
+## Security: Workflow Permissions Model
+
+> [!CAUTION]
+> **Atomic workflows run coding agents with all permission checks disabled.** The agent can read, write, and delete files, execute arbitrary shell commands, and make network requests without prompting. This is required for unattended pipelines. **Run workflows in a [devcontainer](#containerized-execution), not on your host machine.**
+
+| Agent                  | How permissions are bypassed                                         | Key flags / settings                                                  |
+| ---------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| **Claude Code**        | CLI flag disables the interactive permission prompt entirely         | `--dangerously-skip-permissions`                                      |
+| **GitHub Copilot CLI** | CLI flag enables auto-execution; SDK auto-approves all tool requests | `--yolo`, `COPILOT_ALLOW_ALL=true`, `onPermissionRequest: approveAll` |
+| **OpenCode**           | Permissions handled programmatically through the event stream        | Permission requests auto-replied via SSE events                       |
+
+Defaults live in `src/services/config/definitions.ts` and `src/sdk/runtime/executor.ts`. Override per-project via `ProviderOverrides` in `.atomic/settings.json` — `chatFlags` replaces defaults entirely; `envVars` are merged.
 
 ---
 
@@ -337,7 +298,7 @@ This single file demonstrates multi-step pipelines, parallel stages (`Promise.al
 
 ### Multi-Agent Support
 
-Atomic works across **three production coding agents** — switch between them with a flag and your workflows, skills, and sub-agents carry over.
+Atomic works across **three production coding agents** — switch with a flag and your workflows, skills, and sub-agents carry over.
 
 | Agent              | Command                   |
 | ------------------ | ------------------------- |
@@ -345,23 +306,24 @@ Atomic works across **three production coding agents** — switch between them w
 | OpenCode           | `atomic chat -a opencode` |
 | GitHub Copilot CLI | `atomic chat -a copilot`  |
 
-Each agent gets its own configuration directory (`.claude/`, `.opencode/`, `.github/`), skills, and context files — all managed by Atomic. Write a workflow once, run it on any agent.
+Each agent gets its own configuration directory (`.claude/`, `.opencode/`, `.github/`), skills, and context files — all managed by Atomic.
 
 ### Workflow SDK — Build Your Own Deterministic Harness
 
-Every team has a process — triage bugs this way, ship features that way, review PRs with these checks. Most of it lives in a wiki nobody reads or in one senior engineer's head. The **Workflow SDK** (`@bastani/atomic/workflows`) lets you encode that process as TypeScript — spawn agent sessions dynamically with native control flow (`for`, `if`, `Promise.all()`), and watch them appear in a live graph as they execute.
+The Workflow SDK (`@bastani/atomic/workflows`) lets you encode your team's process as TypeScript — spawn agent sessions dynamically with native control flow (`for`, `if`, `Promise.all()`), and watch them appear in a live graph as they execute.
 
-Set up a workflow project (`bun init && bun add @bastani/atomic`), create a `.ts` file in `.atomic/workflows/<name>/<agent>/index.ts`, and run it:
+Set up a workflow project (`bun init && bun add @bastani/atomic`), create `.atomic/workflows/<name>/<agent>/index.ts`, and run it:
 
 ```bash
 atomic workflow -n my-workflow -a claude "describe this project"
 ```
 
+See [step 4 of Quick Start](#4-build-your-own-workflow) for a complete review-to-merge example. More examples and the full API reference below.
+
 <details>
-<summary>Example: Sequential workflow (describe -> summarize)</summary>
+<summary><b>Example: Sequential workflow (describe → summarize)</b></summary>
 
 ```ts
-// .atomic/workflows/my-workflow/claude/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
 export default defineWorkflow({
@@ -386,9 +348,7 @@ export default defineWorkflow({
       {}, {},
       async (s) => {
         const research = await s.transcript(describe);
-        await s.session.query(
-          `Read ${research.path} and summarize it in 2-3 bullet points.`,
-        );
+        await s.session.query(`Read ${research.path} and summarize in 2-3 bullets.`);
         s.save(s.sessionId);
       },
     );
@@ -399,7 +359,7 @@ export default defineWorkflow({
 </details>
 
 <details>
-<summary>Example: Parallel workflow (describe -> [summarize-a, summarize-b] -> merge)</summary>
+<summary><b>Example: Parallel workflow (describe → [summarize-a, summarize-b] → merge)</b></summary>
 
 ```ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
@@ -412,23 +372,20 @@ export default defineWorkflow({
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
-    const describe = await ctx.stage(
-      { name: "describe" }, {}, {},
-      async (s) => {
-        await s.session.query(prompt);
-        s.save(s.sessionId);
-      },
-    );
+    const describe = await ctx.stage({ name: "describe" }, {}, {}, async (s) => {
+      await s.session.query(prompt);
+      s.save(s.sessionId);
+    });
 
     const [summarizeA, summarizeB] = await Promise.all([
       ctx.stage({ name: "summarize-a" }, {}, {}, async (s) => {
         const research = await s.transcript(describe);
-        await s.session.query(`Read ${research.path} and summarize in 2-3 bullet points.`);
+        await s.session.query(`Read ${research.path} and summarize in 2-3 bullets.`);
         s.save(s.sessionId);
       }),
       ctx.stage({ name: "summarize-b" }, {}, {}, async (s) => {
         const research = await s.transcript(describe);
-        await s.session.query(`Read ${research.path} and summarize in a single sentence.`);
+        await s.session.query(`Read ${research.path} and summarize in one sentence.`);
         s.save(s.sessionId);
       }),
     ]);
@@ -448,12 +405,11 @@ export default defineWorkflow({
 </details>
 
 <details>
-<summary>Example: Structured-input workflow (declared schema + CLI flag validation)</summary>
+<summary><b>Example: Structured-input workflow (declared schema + CLI flag validation)</b></summary>
 
-Declare an `inputs` array on `defineWorkflow` and the CLI materialises one `--<field>=<value>` flag per entry. Required fields, enum membership, and unknown-flag rejection are all validated before any tmux session is spawned. The interactive picker (`atomic workflow -a <agent>`) renders the same schema as a form.
+Declare `inputs` on `defineWorkflow` and the CLI materialises one `--<field>=<value>` flag per entry. Required fields, enum membership, and unknown-flag rejection are validated before any tmux session spawns. The interactive picker renders the same schema as a form.
 
 ```ts
-// .atomic/workflows/gen-spec/claude/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
 export default defineWorkflow({
@@ -483,7 +439,6 @@ export default defineWorkflow({
   ],
 }).for<"claude">()
   .run(async (ctx) => {
-    // Read each declared field by name.
     const { research_doc, focus } = ctx.inputs;
     const notes = ctx.inputs.notes ?? "";
 
@@ -498,7 +453,7 @@ export default defineWorkflow({
   .compile();
 ```
 
-Run it either way:
+Run it:
 
 ```bash
 # Named + flags (scriptable; CI-friendly)
@@ -506,16 +461,16 @@ atomic workflow -n gen-spec -a claude \
   --research_doc=research/docs/2026-04-11-auth.md \
   --focus=standard
 
-# Picker (fuzzy-search the workflow list, then fill the form)
+# Picker (fuzzy-search workflows, fill the form)
 atomic workflow -a claude
 ```
 
 </details>
 
 <details>
-<summary>Example: Background (headless) stages for parallel data gathering</summary>
+<summary><b>Example: Headless (background) stages for parallel data gathering</b></summary>
 
-Stages can run in **headless mode** (`headless: true`) — they execute the provider SDK in-process instead of spawning a tmux window. Headless stages are invisible in the workflow graph but tracked via a background task counter in the statusline. Use them for parallel data-gathering tasks that don't need a visible TUI.
+Stages can run headlessly (`headless: true`) — they execute the provider SDK in-process instead of spawning a tmux window. Headless stages are invisible in the graph but tracked via a background counter in the statusline.
 
 ```ts
 import { defineWorkflow, extractAssistantText } from "@bastani/atomic/workflows";
@@ -528,10 +483,8 @@ export default defineWorkflow({
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
-    // Visible stage: generate seed data
     const seed = await ctx.stage(
-      { name: "seed", description: "Generate overview" },
-      {}, {},
+      { name: "seed", description: "Generate overview" }, {}, {},
       async (s) => {
         const result = await s.session.query(prompt);
         s.save(s.sessionId);
@@ -539,7 +492,6 @@ export default defineWorkflow({
       },
     );
 
-    // Three parallel headless stages — invisible in graph, tracked by counter
     const [pros, cons, uses] = await Promise.all([
       ctx.stage({ name: "pros", headless: true }, {}, {}, async (s) => {
         const r = await s.session.query(`List 3 pros:\n\n${seed.result}`);
@@ -558,10 +510,8 @@ export default defineWorkflow({
       }),
     ]);
 
-    // Visible stage: merge background results
     await ctx.stage(
-      { name: "merge", description: "Combine results" },
-      {}, {},
+      { name: "merge", description: "Combine results" }, {}, {},
       async (s) => {
         await s.session.query(
           `Combine:\n\n## Pros\n${pros.result}\n\n## Cons\n${cons.result}\n\n## Uses\n${uses.result}`,
@@ -581,38 +531,34 @@ The graph shows `seed → merge` — headless stages are transparent to the topo
 
 | Capability                         | Description                                                                                                                                                                      |
 | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Dynamic session spawning**       | Call `ctx.stage()` to spawn sessions at runtime — each gets its own tmux window and graph node                                                                                   |
-| **Native TypeScript control flow** | Use `for`, `if/else`, `Promise.all()`, `try/catch` — no framework DSL needed                                                                                                     |
+| **Dynamic session spawning**       | `ctx.stage()` spawns sessions at runtime — each gets its own tmux window and graph node                                                                                          |
+| **Native TypeScript control flow** | Use `for`, `if/else`, `Promise.all()`, `try/catch` — no framework DSL                                                                                                            |
 | **Session return values**          | Session callbacks can return data: `const h = await ctx.stage(...); h.result`                                                                                                    |
-| **Transcript passing**             | Access prior session output via handle (`s.transcript(handle)`) or name (`s.transcript("name")`)                                                                                 |
-| **Declared input schemas**         | Add an `inputs: [...]` array to `defineWorkflow()` and the CLI materialises `--<field>=<value>` flags with built-in validation (required fields, enum membership, unknown flags) |
-| **Interactive picker**             | `atomic workflow -a <agent>` launches a fuzzy-searchable picker that renders each workflow's input schema as a form — no flag-memorisation required                              |
-| **Nested sub-sessions**            | Call `s.stage()` inside a session callback to spawn child sessions — visible as nested nodes in the graph                                                                        |
-| **Auto-inferred graph**            | Graph topology auto-inferred from `await`/`Promise.all` patterns — no annotations needed                                                                                         |
-| **Provider-agnostic**              | Write raw SDK code for Claude, Copilot, or OpenCode inside each session callback                                                                                                 |
-| **Live graph visualization**       | Sessions appear in the TUI graph as they're spawned — loops and conditionals are visible in real time                                                                            |
-| **Background (headless) stages**   | Set `headless: true` on `ctx.stage()` to run stages in-process without a tmux window — invisible in graph, tracked by statusline counter, identical callback API                 |
+| **Transcript passing**             | Access prior output via handle (`s.transcript(handle)`) or name (`s.transcript("name")`)                                                                                         |
+| **Declared input schemas**         | Add an `inputs: [...]` array and the CLI materialises `--<field>=<value>` flags with built-in validation                                                                         |
+| **Interactive picker**             | `atomic workflow -a <agent>` renders input schemas as forms — no flag memorisation                                                                                               |
+| **Nested sub-sessions**            | `s.stage()` inside a callback spawns child sessions — visible as nested graph nodes                                                                                              |
+| **Auto-inferred graph**            | Topology derived from `await` / `Promise.all` patterns — no annotations                                                                                                          |
+| **Provider-agnostic**              | Write raw SDK code for Claude, Copilot, or OpenCode inside each callback                                                                                                         |
+| **Live graph visualization**       | Sessions appear in the TUI graph as they spawn — loops and conditionals visible in real time                                                                                     |
+| **Background (headless) stages**   | `headless: true` runs in-process without a tmux window — invisible in graph, tracked by statusline counter, identical callback API                                               |
 
 **Deterministic execution guarantees:**
 
-Workflows are deterministic by design — the same definition always produces the same execution order with the same data flow, regardless of when or where you run it.
+Workflows are deterministic by design — the same definition produces the same execution order with the same data flow, anywhere.
 
-- **Strict step ordering** — Steps execute sequentially. Step 2 never starts until Step 1 finishes. Parallel sessions within a step all complete (or fail fast) before the next step begins.
-- **Frozen definitions** — `.compile()` freezes the workflow structure. Once compiled, the step order, session names, and execution graph are immutable.
-- **Controlled transcript access** — Sessions can only read transcripts from *completed* upstream sessions. Parallel siblings are blocked from reading each other, eliminating race conditions on shared state.
-- **Isolated context windows** — Each session runs in its own tmux pane with a fresh context window. No session inherits stale state from another — data flows only through explicit `ctx.transcript()` and `ctx.getMessages()` calls.
-- **Persisted artifacts** — Every session writes its messages, transcript, and metadata to disk. The workflow produces a complete, inspectable execution record you can replay or debug after the fact.
+- **Strict step ordering** — Step 2 never starts until Step 1 finishes. Parallel sessions complete (or fail fast) before the next step begins.
+- **Frozen definitions** — `.compile()` freezes the workflow. Once compiled, step order, session names, and the execution graph are immutable.
+- **Controlled transcript access** — Sessions only read transcripts from *completed* upstream sessions; parallel siblings can't read each other.
+- **Isolated context windows** — Each session runs in its own tmux pane with a fresh context. Data flows only through explicit `ctx.transcript()` / `ctx.getMessages()` calls.
+- **Persisted artifacts** — Every session writes messages, transcript, and metadata to disk — a complete, inspectable execution record.
 
-This means you can run the same workflow on different machines, different agents, or at different times and get structurally identical execution — same steps, same data flow, same ordering. The only variance comes from the LLM's responses, not from the harness.
+Variance comes only from the LLM's responses, not from the harness.
 
-Set up a project (`bun init && bun add @bastani/atomic`), drop a `.ts` file in `.atomic/workflows/<name>/<agent>/index.ts`, and run it. You can also ask Atomic to create workflows for you:
-
-```
-Use your workflow-creator skill to create a workflow that plans, implements, and reviews a feature.
-```
+> Ask Atomic to build workflows for you: `Use your workflow-creator skill to create a workflow that plans, implements, and reviews a feature.`
 
 <details>
-<summary>Full Workflow SDK Reference</summary>
+<summary><b>Full Workflow SDK Reference</b></summary>
 
 #### Builder API
 
@@ -638,7 +584,7 @@ Use your workflow-creator skill to create a workflow that plans, implements, and
 | -------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `s.client`                                   | `ProviderClient<A>`         | Pre-created SDK client (auto-managed by runtime)                                                                                        |
 | `s.session`                                  | `ProviderSession<A>`        | Pre-created provider session (auto-managed by runtime)                                                                                  |
-| `s.inputs`                                   | `{ [K in N]?: string }`     | Same typed inputs as `ctx.inputs`, forwarded into every stage so session callbacks can read values without closing over the outer `ctx` |
+| `s.inputs`                                   | `{ [K in N]?: string }`     | Same typed inputs as `ctx.inputs`, forwarded into every stage so callbacks can read values without closing over the outer `ctx`         |
 | `s.agent`                                    | `AgentType`                 | Which agent is running                                                                                                                  |
 | `s.paneId`                                   | `string`                    | tmux pane ID for this session                                                                                                           |
 | `s.sessionId`                                | `string`                    | Session UUID                                                                                                                            |
@@ -656,7 +602,7 @@ Use your workflow-creator skill to create a workflow that plans, implements, and
 | `description` | `string?`  | Human-readable description shown in the graph                                                         |
 | `headless`    | `boolean?` | When `true`, run in-process without a tmux window — invisible in graph, tracked by background counter |
 
-The runtime auto-infers parent-child edges from execution order: sequential `await` creates a chain, while `Promise.all` creates parallel fan-out/fan-in — no annotations needed.
+The runtime auto-infers parent-child edges from execution order: sequential `await` creates a chain, `Promise.all` creates parallel fan-out/fan-in — no annotations needed.
 
 #### Saving Transcripts
 
@@ -680,73 +626,57 @@ The runtime auto-creates `s.client` and `s.session` — use them directly inside
 
 #### Key Rules
 
-1. Every workflow file must use `export default` with `.run()` and `.compile()`
+1. Every workflow file must `export default` a builder with `.run()` and `.compile()`
 2. Session names must be unique within a workflow run
 3. `transcript()` / `getMessages()` only access completed sessions (callback returned + saves flushed)
 4. Each session runs in its own tmux window with the chosen agent
-5. Workflows are organized per-workflow: `.atomic/workflows/<name>/<agent>/index.ts`
-6. Set up your workflow project with `bun init && bun add @bastani/atomic` — standard module resolution handles imports
+5. Workflows are organized as `.atomic/workflows/<name>/<agent>/index.ts`
+6. Set up your workflow project with `bun init && bun add @bastani/atomic`
 7. Background (headless) stages use the same callback API — `s.client`, `s.session`, `s.save()`, return values all work identically
 
-For the authoring walkthrough with worked examples, ask Atomic to use the `workflow-creator` skill or read the skill reference at `.agents/skills/workflow-creator/`.
+For the authoring walkthrough ask Atomic to use the `workflow-creator` skill or read `.agents/skills/workflow-creator/`.
 
 > [!TIP]
-> **Keeping workflows up to date:** When the Workflow SDK is updated (new return types, new options, deprecated patterns), you can ask the `workflow-creator` skill to migrate your existing workflows to the latest best practices. Just open your workflow file and ask: _"Update this workflow to use the latest SDK patterns."_ The skill stays current with the SDK and will apply the right changes automatically.
+> When the Workflow SDK is updated, ask the `workflow-creator` skill to migrate your workflows to the latest patterns: _"Update this workflow to use the latest SDK patterns."_
 
 </details>
 
 ### Research Codebase
 
-The `/research-codebase` command dispatches **specialized sub-agents in parallel** to analyze your codebase:
-
-- Understand how authentication flows work in an unfamiliar codebase
-- Track down root causes by analyzing code paths across dozens of files
-- Search through docs, READMEs, and inline documentation
-- Query external documentation via [DeepWiki MCP](https://deepwiki.com) integration
-- Get up to speed on a new project in minutes instead of hours
-
-**Research sub-agents:**
+The `/research-codebase` command dispatches **specialized sub-agents in parallel** to analyze your codebase — understand auth flows, trace root causes, query docs, and hit external sources via [DeepWiki MCP](https://deepwiki.com). Get up to speed on a new project in minutes instead of hours.
 
 | Sub-Agent                    | Model  | Purpose                                                                                   |
 | ---------------------------- | ------ | ----------------------------------------------------------------------------------------- |
 | `codebase-locator`           | Haiku  | Locate files, directories, and components relevant to the research topic                  |
-| `codebase-analyzer`          | Sonnet | Analyze implementation details, trace data flow, and explain technical workings           |
+| `codebase-analyzer`          | Sonnet | Analyze implementation details, trace data flow, explain technical workings               |
 | `codebase-pattern-finder`    | Haiku  | Find similar implementations, usage examples, and existing patterns to model after        |
-| `codebase-online-researcher` | Sonnet | Fetch up-to-date information from the web and repository-specific knowledge from DeepWiki |
+| `codebase-online-researcher` | Sonnet | Fetch up-to-date information from the web and repository knowledge from DeepWiki          |
 | `codebase-research-locator`  | Haiku  | Discover relevant documents in `research/` and `specs/` directories                       |
 | `codebase-research-analyzer` | Sonnet | Extract high-value insights, decisions, and technical details from research documents     |
 
-**Why specialized research agents instead of one general-purpose agent?**
+**Run parallel research sessions** to compare approaches:
 
-A single agent asked to "research the auth system" will try to search, read, analyze, and summarize — all within one context window. As that window fills with file contents, search results, and intermediate reasoning, the agent's ability to synthesize degrades. This is a fundamental constraint of transformer-based models: attention quality drops as context length grows.
+```bash
+# Terminal 1: LangChain approach
+atomic chat -a claude "/research-codebase Research GraphRAG using LangChain's graph retrieval."
 
-Atomic solves this by dispatching **purpose-built sub-agents** — a `codebase-locator` that only finds relevant files, a `codebase-analyzer` that only reads and analyzes implementation details, a `codebase-online-researcher` that only queries external documentation. Each agent operates in its own context window with only the tools it needs. The parent agent receives distilled findings from each sub-agent, keeping its own context clean for synthesis.
+# Terminal 2: Microsoft GraphRAG
+atomic chat -a claude "/research-codebase Research GraphRAG using microsoft/graphrag."
 
-This mirrors how effective engineering teams work: you don't send one person to simultaneously search the codebase, read the docs, and analyze the architecture. You parallelize. The result is faster research, higher-quality findings, and significantly less hallucination — because each agent is reasoning over a small, focused context rather than a bloated one.
+# Terminal 3: LlamaIndex approach
+atomic chat -a claude "/research-codebase Research GraphRAG using LlamaIndex's property graph."
+```
 
-**Run parallel research sessions** to evaluate competing approaches simultaneously:
+Then run `/create-spec` on each output, spin up git worktrees, and run `atomic workflow -n ralph` in each — wake up to three complete implementations on separate branches. Research persists in `research/` and specs in `specs/`, so every investigation compounds into future context.
 
-```bash
-# Terminal 1: Research LangChain approach
-atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
-  LangChain's graph retrieval patterns. Look up langchain-ai/langchain for \
-  graph store integrations."
-
-# Terminal 2: Research Microsoft's GraphRAG
-atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
-  Microsoft's GraphRAG library. Look up microsoft/graphrag for their \
-  community detection pipeline."
-
-# Terminal 3: Research LlamaIndex approach
-atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
-  LlamaIndex's property graph index. Look up run-llama/llama_index."
-```
+<details>
+<summary><i>Why specialized research agents instead of one general-purpose agent?</i></summary>
 
-Each agent spawns sub-agents that query DeepWiki, pull external documentation, and cross-reference with your codebase. Then run `/create-spec` on each research doc, spin up git worktrees, and run `atomic workflow -n ralph` in each — wake up to three complete implementations on separate branches.
+A single agent asked to "research the auth system" tries to search, read, analyze, and summarize within one context window. As that window fills with file contents, search results, and intermediate reasoning, synthesis degrades — this is a fundamental constraint of transformer attention, not a prompt-engineering problem.
 
-> Works identically with `atomic chat -a opencode` and `atomic chat -a copilot`.
+Atomic dispatches purpose-built sub-agents: a `codebase-locator` only finds relevant files, a `codebase-analyzer` only reads and analyzes implementations, a `codebase-online-researcher` only queries external docs. Each operates in its own context with only the tools it needs; the parent receives distilled findings. The result: faster research, higher-quality findings, less hallucination.
 
-Research outputs persist in your `research/` directory and specs persist in your `specs/` directory — both become context for future sessions, so every investigation and every specification compounds.
+</details>
 
 ### Autonomous Execution (Ralph)
 
@@ -754,15 +684,15 @@ Research outputs persist in your `research/` directory and specs persist in your
   <img src="assets/ralph-wiggum.jpg" alt="Ralph Wiggum" width="600">
 </p>
 
-The [Ralph Method](https://ghuntley.com/ralph/) enables **multi-hour autonomous coding sessions**. After approving your spec, let Ralph work in the background while you focus on other tasks.
+The [Ralph Method](https://ghuntley.com/ralph/) enables **multi-hour autonomous coding sessions**. Approve your spec, let Ralph work in the background, focus on other things.
 
 **How Ralph works:**
 
-1. **Task Decomposition** — A `planner` sub-agent breaks your spec into a structured task list with dependency tracking, stored in a SQLite database with WAL mode for parallel access
-2. **Orchestration** — An `orchestrator` sub-agent retrieves the task list, validates the dependency graph, and dispatches `worker` sub-agents for ready tasks with concurrent execution of independent tasks
-3. **Review & Debug** — A `reviewer` sub-agent audits the implementation with structured JSON output; if actionable findings exist (P0–P2 severity), a `debugger` sub-agent investigates root causes and produces a markdown report that feeds back to the planner on the next iteration
+1. **Task Decomposition** — A `planner` sub-agent breaks your spec into a task list with dependency tracking, stored in SQLite (WAL mode for parallel access).
+2. **Orchestration** — An `orchestrator` retrieves the task list, validates the dependency graph, and dispatches `worker` sub-agents for ready tasks.
+3. **Review & Debug** — A `reviewer` audits the implementation with structured JSON output; if P0–P2 findings exist, a `debugger` investigates root causes and feeds back to the planner on the next iteration.
 
-**Loop configuration:** Ralph runs up to **10 iterations** and exits early after **2 consecutive clean reviews** (zero actionable findings). P3 (minor) findings are filtered as non-actionable.
+**Loop config:** Up to **10 iterations**. Exits early after **2 consecutive clean reviews** (zero actionable findings). P3 (minor) findings are non-actionable.
 
 ```bash
 # From a prompt
@@ -772,7 +702,7 @@ atomic workflow -n ralph -a <claude|opencode|copilot> "Build a REST API for user
 atomic workflow -n ralph -a claude "specs/YYYY-MM-DD-my-feature.md"
 ```
 
-**Best practice:** Run Ralph in a separate [git worktree](https://git-scm.com/docs/git-worktree) to isolate autonomous execution:
+**Best practice:** run Ralph in a [git worktree](https://git-scm.com/docs/git-worktree) so autonomous changes stay isolated from your working tree:
 
 ```bash
 git worktree add ../my-project-ralph feature-branch
@@ -782,45 +712,29 @@ atomic workflow -n ralph -a claude "Build the auth module"
 
 ### Deep Research Codebase
 
-Atomic also ships with `deep-research-codebase`, a built-in workflow that performs **multi-agent parallel research** across your codebase. While `/research-codebase` is a single-shot command, the `deep-research-codebase` workflow is a full multi-stage pipeline:
+Atomic ships a `deep-research-codebase` workflow that performs **multi-agent parallel research** across your codebase — a full pipeline, not a single-shot command.
 
-1. **Scout** — A single agent scans the codebase structure and produces an architectural orientation
-2. **History** — A parallel agent surfaces prior research from `research/docs/`
-3. **Explorers** — Multiple parallel agents (count scaled by LOC) each investigate a partition of the codebase, writing findings to scratch files
-4. **Aggregator** — A final agent synthesizes all explorer reports + history into a dated research document at `research/docs/YYYY-MM-DD-<slug>.md`
+1. **Scout** — One agent scans the codebase structure and writes an architectural orientation.
+2. **History** — A parallel agent surfaces prior research from `research/docs/`.
+3. **Explorers** — Multiple parallel agents (count scaled by LOC) each investigate a partition.
+4. **Aggregator** — A final agent synthesizes all explorer reports + history into a dated research doc at `research/docs/YYYY-MM-DD-<slug>.md`.
 
 ```bash
 atomic workflow -n deep-research-codebase -a claude "How does the authentication system work?"
 ```
 
-The workflow produces a permanent research artifact that can be referenced by future runs, specs, or other workflows.
+The output is a permanent research artifact that future runs, specs, and workflows can reference.
 
 ### Containerized Execution
 
-Atomic ships as **devcontainer features** that bundle the CLI, agent, and all dependencies into isolated containers. This is the recommended way to run autonomous agents safely.
-
-```jsonc
-// .devcontainer/devcontainer.json
-{
-  "image": "mcr.microsoft.com/devcontainers/rust:latest",
-  "features": {
-    "ghcr.io/flora131/atomic/claude:1": {},
-    "ghcr.io/devcontainers/features/github-cli:1": {}
-  },
-  "remoteEnv": {
-    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
-  }
-}
-```
+Atomic ships as **devcontainer features** that bundle the CLI, agent, and all dependencies into isolated containers — the recommended way to run autonomous agents safely.
 
 **Why containerize?**
 
 - Agents run `rm`, `git reset --hard`, and arbitrary shell commands — containers limit blast radius
 - Reproducible environments across team members and CI
 - Pre-installed dependencies: bun, playwright-cli, agent CLI, GitHub CLI
-- Features are versioned in sync with Atomic releases
-
-Each feature installs Atomic + one agent. Mix and match across projects:
+- Features versioned in sync with Atomic releases
 
 | Feature                              | Installs             |
 | ------------------------------------ | -------------------- |
@@ -828,6 +742,8 @@ Each feature installs Atomic + one agent. Mix and match across projects:
 | `ghcr.io/flora131/atomic/opencode:1` | Atomic + OpenCode    |
 | `ghcr.io/flora131/atomic/copilot:1`  | Atomic + Copilot CLI |
 
+See [Quick Start → Devcontainer](#1-install) for a working `.devcontainer.json` and the [`.devcontainer/`](./.devcontainer/) directory for per-agent templates.
+
 ### Specialized Sub-Agents
 
 Atomic dispatches **purpose-built sub-agents**, each with scoped context, tools, and termination conditions:
@@ -837,7 +753,7 @@ Atomic dispatches **purpose-built sub-agents**, each with scoped context, tools,
 | `planner`                    | Decompose specs into structured task lists with dependency tracking    |
 | `worker`                     | Implement single focused tasks (multiple workers run in parallel)      |
 | `reviewer`                   | Audit implementations against specs and best practices                 |
-| `code-simplifier`            | Simplify and refine code for clarity, consistency, and maintainability |
+| `code-simplifier`            | Simplify and refine code for clarity, consistency, maintainability     |
 | `orchestrator`               | Coordinate complex multi-step workflows                                |
 | `codebase-analyzer`          | Analyze implementation details of specific components                  |
 | `codebase-locator`           | Locate files, directories, and components                              |
@@ -847,26 +763,30 @@ Atomic dispatches **purpose-built sub-agents**, each with scoped context, tools,
 | `codebase-research-locator`  | Find documents in `research/` directory                                |
 | `debugger`                   | Debug errors, test failures, and unexpected behavior                   |
 
-**Why specialize?**
+<details>
+<summary><i>Why specialize instead of using one general-purpose agent?</i></summary>
 
-LLMs have a core architectural limitation: the more context they hold, the harder it becomes to attend to the right information at the right time. A single agent juggling a spec, dozens of files, tool outputs, and its own reasoning chain will lose track of details, repeat work, or hallucinate connections between unrelated code. This isn't a solvable prompt-engineering problem — it's how attention mechanisms work.
+LLMs have an architectural limitation: the more context they hold, the harder it becomes to attend to the right information. A single agent juggling a spec, dozens of files, tool outputs, and its own reasoning will lose details, repeat work, or hallucinate connections. This isn't solvable via prompt engineering — it's how attention mechanisms work.
 
-Specialized sub-agents turn this limitation into an advantage:
+Specialized sub-agents turn the limitation into an advantage:
 
-- **Context isolation** — Each sub-agent gets a fresh, minimal context window scoped to exactly one job. A `codebase-locator` doesn't carry file contents; a `worker` doesn't carry the full spec. This keeps each agent reasoning over a small, high-signal context.
-- **Tool scoping** — Agents only see tools relevant to their role. A `reviewer` has read-only analysis tools and cannot edit files. A `worker` has edit tools but cannot spawn other workers. This eliminates entire categories of mistakes.
-- **Parallel execution** — Independent sub-agents run concurrently. While one worker implements a database migration, another writes the API handler, and a third generates tests — all in separate context windows, all at the same time.
-- **Composability** — Sub-agents can be combined into workflows or dispatched ad-hoc. The same `reviewer` agent used by Ralph is the one invoked when you ask for a code review in chat.
+- **Context isolation** — Fresh, minimal context scoped to one job. A `codebase-locator` doesn't carry file contents; a `worker` doesn't carry the full spec.
+- **Tool scoping** — Agents only see tools relevant to their role. A `reviewer` has read-only tools and can't edit files; a `worker` has edit tools but can't spawn other workers.
+- **Parallel execution** — Independent sub-agents run concurrently. One worker writes the migration, another writes the handler, a third generates tests — all at once.
+- **Composability** — Sub-agents combine into workflows or dispatch ad-hoc. The same `reviewer` used by Ralph is the one invoked when you ask for a code review in chat.
 
-The difference is measurable: a specialized `codebase-analyzer` reading three files produces more accurate analysis than a generalist agent that has already consumed 50,000 tokens of search results, tool calls, and prior reasoning. Specialization isn't a nice-to-have — it's how you get reliable output from LLMs on real-world codebases.
+A specialized `codebase-analyzer` reading three files produces more accurate output than a generalist that has already consumed 50,000 tokens of search results and prior reasoning.
+
+</details>
 
 Use `/agents` in any chat session to see all available sub-agents.
 
 ### Built-in Skills
 
-Skills are structured capability modules that give agents best practices and reusable workflows for specific tasks. Atomic ships 55 skills across eight categories; each lives at `.agents/skills/<name>/SKILL.md` and is auto-invoked when the agent detects a relevant trigger.
+Skills are structured capability modules that give agents best practices and reusable workflows. Atomic ships **55 skills** across eight categories; each lives at `.agents/skills/<name>/SKILL.md` and is auto-invoked when the agent detects a relevant trigger.
 
-**Development workflows:**
+<details>
+<summary><b>Development workflows</b></summary>
 
 | Skill                     | Description                                                                 |
 | ------------------------- | --------------------------------------------------------------------------- |
@@ -879,7 +799,10 @@ Skills are structured capability modules that give agents best practices and reu
 | `test-driven-development` | Write tests first; includes a testing anti-patterns guide                   |
 | `prompt-engineer`         | Create, improve, and optimize prompts using best practices                  |
 
-**Context engineering** — practical skills for working within (and around) LLM context limits:
+</details>
+
+<details>
+<summary><b>Context engineering</b> — working within (and around) LLM context limits</summary>
 
 | Skill                  | Description                                                           |
 | ---------------------- | --------------------------------------------------------------------- |
@@ -895,7 +818,10 @@ Skills are structured capability modules that give agents best practices and reu
 | `project-development`  | Validate task-model fit before building; cost estimation              |
 | `bdi-mental-states`    | Belief-desire-intention models for explainable agent reasoning        |
 
-**TypeScript & runtime:**
+</details>
+
+<details>
+<summary><b>TypeScript & runtime</b></summary>
 
 | Skill                       | Description                                                             |
 | --------------------------- | ----------------------------------------------------------------------- |
@@ -905,7 +831,10 @@ Skills are structured capability modules that give agents best practices and reu
 | `bun`                       | Build, test, deploy with Bun (runtime, package manager, bundler, tests) |
 | `opentui`                   | Build terminal UIs with OpenTUI (core, React, Solid reconcilers)        |
 
-**Frontend design & UI polish** — used by `impeccable` and invoked individually for targeted refinement:
+</details>
+
+<details>
+<summary><b>Frontend design & UI polish</b> — used by `impeccable` and invoked individually for targeted refinement</summary>
 
 | Skill                                          | Description                                                                    |
 | ---------------------------------------------- | ------------------------------------------------------------------------------ |
@@ -921,6 +850,11 @@ Skills are structured capability modules that give agents best practices and reu
 | `harden`                                       | Error handling, onboarding, empty states, i18n, overflow, edge-case resilience |
 | `optimize`                                     | Diagnose and fix loading, rendering, animation, bundle-size issues             |
 
+</details>
+
+<details>
+<summary><b>Evaluation, documents, git, meta</b></summary>
+
 **Evaluation:**
 
 | Skill                 | Description                                                         |
@@ -954,20 +888,22 @@ Skills are structured capability modules that give agents best practices and reu
 | --------------- | ------------------------------------------------------- |
 | `skill-creator` | Create, modify, evaluate, and benchmark your own skills |
 
-Skills are auto-invoked when relevant — `test-driven-development` activates before any test is written, `playwright-cli` activates for browser automation tasks, and the context-engineering skills activate whenever you're designing a workflow that'll push context limits. Run `ls .agents/skills/` for the complete, current list on disk.
+</details>
+
+Skills are auto-invoked when relevant. Run `ls .agents/skills/` for the complete, current list on disk.
 
 ### Workflow Orchestrator Panel
 
-During `atomic workflow` execution, Atomic renders a live orchestrator panel built on [OpenTUI](https://github.com/anomalyco/opentui) on top of the workflow's tmux session graph. It shows:
+During `atomic workflow` execution, Atomic renders a live orchestrator panel built on [OpenTUI](https://github.com/anomalyco/opentui) over the workflow's tmux session graph. It shows:
 
-- **Session graph** — Nodes for each `.stage()` call with status (pending, running, completed, failed) and edges for sequential / parallel dependencies
-- **Task list tracking** — Ralph's decomposed task list with dependency arrows, updated in real time as workers complete tasks
-- **Pane previews** — Thumbnail of each tmux pane so you can see what every agent is doing without switching contexts
-- **Transcript passing visibility** — Highlights `s.save()` / `s.transcript()` handoffs as they happen between sessions
+- **Session graph** — Nodes per `.stage()` with status (pending / running / completed / failed) and edges for sequential / parallel dependencies
+- **Task list tracking** — Ralph's decomposed task list with dependency arrows, updated in real time
+- **Pane previews** — Thumbnail of each tmux pane so you can see every agent without context-switching
+- **Transcript passing visibility** — Highlights `s.save()` / `s.transcript()` handoffs as they happen
 
-During `atomic chat`, there is no Atomic-owned TUI — `atomic chat -a <agent>` spawns the native agent CLI inside a tmux/psmux session, so all chat features (streaming, `@` mentions, `/slash-commands`, model selection, theme switching, keyboard shortcuts) come from the agent CLI itself. Atomic's role in chat mode is to handle config sync, tmux session management, and argument passthrough.
+During `atomic chat`, there is no Atomic-owned TUI — `atomic chat -a <agent>` spawns the native agent CLI inside a tmux session, so chat features (streaming, `@` mentions, `/slash-commands`, model selection, theme, keyboard shortcuts) come from the agent CLI itself. Atomic handles config sync, tmux session management, and argument passthrough.
 
-| Context                                | Who provides the UI                                         |
+| Context                                | UI provider                                                 |
 | -------------------------------------- | ----------------------------------------------------------- |
 | `atomic workflow -n <name> -a <agent>` | Atomic (orchestrator panel + tmux session graph)            |
 | `atomic chat -a <agent>`               | The native agent CLI (Claude Code / OpenCode / Copilot CLI) |
@@ -980,8 +916,8 @@ During `atomic chat`, there is no Atomic-owned TUI — `atomic chat -a <agent>`
 
 | Command                         | Description                                                           |
 | ------------------------------- | --------------------------------------------------------------------- |
-| `atomic chat`                   | Spawn the native agent CLI inside a tmux/psmux session                |
-| `atomic workflow`               | Run a multi-session agent workflow with the Atomic orchestrator panel |
+| `atomic chat`                   | Spawn the native agent CLI inside a tmux session                      |
+| `atomic workflow`               | Run a multi-session workflow with the Atomic orchestrator panel       |
 | `atomic workflow list`          | List available workflows, grouped by source                           |
 | `atomic session list`           | List all running sessions on the atomic tmux socket                   |
 | `atomic session connect [name]` | Attach to a session (interactive picker when no name given)           |
@@ -991,8 +927,6 @@ During `atomic chat`, there is no Atomic-owned TUI — `atomic chat -a <agent>`
 
 #### Global Flags
 
-These flags are available on all commands:
-
 | Flag            | Description                                |
 | --------------- | ------------------------------------------ |
 | `-y, --yes`     | Auto-confirm all prompts (non-interactive) |
@@ -1001,7 +935,7 @@ These flags are available on all commands:
 
 #### `atomic session` Subcommands
 
-The `session` command is available at three levels — scoped or global:
+Available at three levels — scoped or global:
 
 | Command                                  | Description                                           |
 | ---------------------------------------- | ----------------------------------------------------- |
@@ -1015,17 +949,17 @@ The `session` command is available at three levels — scoped or global:
 | `atomic workflow session connect [name]` | Attach to a workflow session                          |
 | `atomic workflow session kill [name]`    | Kill a workflow session, or all workflow sessions     |
 
-`list`, `connect`, and `kill` all accept `-a <agent>` (repeatable) to filter by agent backend. `kill` prompts for confirmation before terminating sessions.
+`list`, `connect`, and `kill` accept `-a <agent>` (repeatable) to filter by agent. `kill` prompts for confirmation.
 
 ```bash
-atomic session list                      # All sessions
-atomic session list -a claude            # Only Claude sessions
-atomic session connect my-session        # Attach by name
-atomic session connect                   # Interactive picker
-atomic chat session list -a copilot      # Chat sessions for Copilot only
-atomic session kill my-session           # Kill one session by name
-atomic session kill                      # Kill all sessions (with confirmation)
-atomic workflow session kill -a claude   # Kill all Claude workflow sessions
+atomic session list                      # all sessions
+atomic session list -a claude            # only Claude sessions
+atomic session connect my-session        # attach by name
+atomic session connect                   # interactive picker
+atomic chat session list -a copilot      # chat sessions for Copilot only
+atomic session kill my-session           # kill one session by name
+atomic session kill                      # kill all sessions (with confirmation)
+atomic workflow session kill -a claude   # kill all Claude workflow sessions
 ```
 
 #### `atomic chat` Flags
@@ -1034,12 +968,12 @@ atomic workflow session kill -a claude   # Kill all Claude workflow sessions
 | -------------------- | -------------------------------------- |
 | `-a, --agent <name>` | Agent: `claude`, `opencode`, `copilot` |
 
-All other arguments are forwarded directly to the native agent CLI. For example:
+All other arguments are forwarded directly to the native agent CLI:
 
 ```bash
-atomic chat -a claude "fix the bug"          # Initial prompt
-atomic chat -a copilot --model gpt-5.4       # Custom model
-atomic chat -a claude --verbose              # Forward --verbose to claude
+atomic chat -a claude "fix the bug"          # initial prompt
+atomic chat -a copilot --model gpt-5.4       # custom model
+atomic chat -a claude --verbose              # forward --verbose to claude
 ```
 
 #### `atomic workflow` Flags
@@ -1048,48 +982,80 @@ atomic chat -a claude --verbose              # Forward --verbose to claude
 | -------------------- | ------------------------------------------------------------------------------------------------- |
 | `-n, --name <name>`  | Workflow name (matches directory under `.atomic/workflows/<name>/`)                               |
 | `-a, --agent <name>` | Agent: `claude`, `opencode`, `copilot`                                                            |
+| `-d, --detach`       | Start the workflow in the background without attaching — ideal for scripted / CI runs; attach later with `atomic workflow session connect <name>` |
 | `--<field>=<value>`  | Structured input for workflows that declare an `inputs` schema (also accepts `--<field> <value>`) |
 | `[prompt...]`        | Positional prompt — requires the workflow to declare a `prompt` input                             |
 
-The workflow command supports four invocation shapes:
+Five invocation shapes:
 
 ```bash
-# 1. List every workflow available to you, grouped by source
+# 1. List every workflow available, grouped by source
 atomic workflow list
 atomic workflow list -a claude       # filter by agent
 
-# 2. Launch the interactive picker for an agent (no -n) — fuzzy-search
-#    the list, fill the form rendered from the workflow's declared inputs,
-#    and confirm with y/n
+# 2. Launch the interactive picker (no -n) — fuzzy-search, fill the form, confirm with y/n
 atomic workflow -a claude
 
-# 3. Run a workflow with a positional prompt (workflow must declare a "prompt" input)
+# 3. Run with a positional prompt (workflow must declare a "prompt" input)
 atomic workflow -n ralph -a claude "build a REST API for user management"
 
 # 4. Run a structured-input workflow with one --<field> flag per declared input
 atomic workflow -n gen-spec -a claude \
   --research_doc=research/docs/2026-04-11-auth.md \
   --focus=standard
+
+# 5. Run detached — orchestrator runs in the background; prints the session name
+#    and returns immediately. Attach any time with `atomic workflow session connect`.
+atomic workflow -n ralph -a claude -d "build a REST API for user management"
 ```
 
-Workflows that declare an `inputs: WorkflowInput[]` schema get CLI flag validation for free — missing required fields and invalid enum values are rejected before any tmux session is spawned, with error messages that spell out the expected flag set. Workflows that declare a `prompt` input accept a positional prompt on the command line, which the runtime stores under `ctx.inputs.prompt`. **Builtin workflows (like `ralph`) are reserved names** — a local or global workflow with the same name will not shadow a builtin at resolution time.
+Workflows that declare `inputs: WorkflowInput[]` get CLI flag validation for free. **Builtin workflows (e.g. `ralph`) are reserved** — a local/global workflow with the same name will not shadow a builtin.
 
 #### `atomic completions` — Shell Completions
 
-Atomic ships tab-completion for **bash**, **zsh**, **fish**, and **PowerShell**. The `atomic completions <shell>` command prints the completion script to stdout — pipe it into your shell's config to enable.
+Atomic ships tab-completion for **bash**, **zsh**, **fish**, and **PowerShell**. Cache the script once so new shells don't re-spawn the atomic binary on startup.
 
-| Shell      | One-liner (add to your rc file)                                           |
-| ---------- | ------------------------------------------------------------------------- |
-| Bash       | `eval "$(atomic completions bash)"`  — add to `~/.bashrc`                 |
-| Zsh        | `eval "$(atomic completions zsh)"`  — add to `~/.zshrc`                   |
-| Fish       | `atomic completions fish > ~/.config/fish/completions/atomic.fish`        |
-| PowerShell | `atomic completions powershell \| Invoke-Expression`  — add to `$PROFILE` |
+<details>
+<summary><b>Bash / Zsh / Fish / PowerShell setup</b></summary>
+
+**Bash**
+
+```bash
+mkdir -p ~/.atomic/completions
+atomic completions bash > ~/.atomic/completions/atomic.bash
+echo '[ -f "$HOME/.atomic/completions/atomic.bash" ] && source "$HOME/.atomic/completions/atomic.bash"' >> ~/.bashrc
+```
 
-> **Tip:** The bootstrap installer (`install.sh` / `install.ps1`) automatically installs completions for your detected shell.
+**Zsh**
+
+```zsh
+mkdir -p ~/.atomic/completions
+atomic completions zsh > ~/.atomic/completions/atomic.zsh
+echo '[ -f "$HOME/.atomic/completions/atomic.zsh" ] && source "$HOME/.atomic/completions/atomic.zsh"' >> ~/.zshrc
+```
+
+**Fish**
+
+```fish
+atomic completions fish > ~/.config/fish/completions/atomic.fish
+```
+
+**PowerShell**
+
+```powershell
+$cache = Join-Path $HOME '.atomic\completions\atomic.ps1'
+New-Item -ItemType Directory -Force -Path (Split-Path $cache) | Out-Null
+atomic completions powershell | Out-File -FilePath $cache -Encoding utf8
+Add-Content $PROFILE "`nif (Test-Path `"$cache`") { . `"$cache`" }"
+```
+
+</details>
+
+> The bootstrap installer (`install.sh` / `install.ps1`) sets this up automatically and migrates older `eval "$(atomic completions …)"` snippets to the cached form.
 
 ### Atomic-Provided Skills (invokable from any agent chat)
 
-Atomic ships skills — not slash commands. Skills are auto-discovered by Claude Code, OpenCode, and Copilot CLI and are invoked either by typing `/<skill-name>` (Claude Code) or by natural-language reference (OpenCode / Copilot CLI). The list below covers the headline workflow skills; see **Built-in Skills** below for the full catalog.
+Atomic ships skills — not slash commands. Skills are auto-discovered by Claude Code, OpenCode, and Copilot CLI, invoked by typing `/<skill-name>` (Claude Code) or by natural-language reference (OpenCode / Copilot CLI).
 
 | Skill               | Typical invocation                | Purpose                                                                       |
 | ------------------- | --------------------------------- | ----------------------------------------------------------------------------- |
@@ -1103,7 +1069,7 @@ Atomic ships skills — not slash commands. Skills are auto-discovered by Claude
 | `sl-submit-diff`    | `/sl-submit-diff`                 | Submit a Sapling commit as a Phabricator diff                                 |
 | `workflow-creator`  | natural language                  | Generate a multi-agent workflow file in `.atomic/workflows/`                  |
 
-Native slash commands like `/help`, `/clear`, `/compact`, `/model`, `/theme`, `/agents`, `/mcp`, and `/exit` are provided by the underlying agent CLI, not by Atomic — consult the Claude Code / OpenCode / Copilot CLI documentation for those.
+Native slash commands (`/help`, `/clear`, `/compact`, `/model`, `/theme`, `/agents`, `/mcp`, `/exit`) come from the underlying agent CLI, not Atomic.
 
 ---
 
@@ -1121,22 +1087,18 @@ Resolution order:
   "$schema": "https://raw.githubusercontent.com/flora131/atomic/main/assets/settings.schema.json",
   "version": 1,
   "scm": "github",
-  "lastUpdated": "2026-04-09T12:00:00.000Z",
-  "trustedPaths": [
-    { "workspacePath": "/home/you/project", "provider": "claude" }
-  ]
+  "lastUpdated": "2026-04-09T12:00:00.000Z"
 }
 ```
 
-| Field          | Type   | Description                                                                                               |
-| -------------- | ------ | --------------------------------------------------------------------------------------------------------- |
-| `$schema`      | string | JSON Schema URL for editor autocomplete                                                                   |
-| `version`      | number | Config schema version (currently `1`)                                                                     |
-| `scm`          | string | Source control: `github` or `sapling`                                                                     |
-| `lastUpdated`  | string | ISO 8601 timestamp of the last update                                                                     |
-| `trustedPaths` | array  | Workspaces that have completed provider onboarding; atomic skips re-prompting for these |
+| Field         | Type   | Description                               |
+| ------------- | ------ | ----------------------------------------- |
+| `$schema`     | string | JSON Schema URL for editor autocomplete   |
+| `version`     | number | Config schema version (currently `1`)     |
+| `scm`         | string | Source control: `github` or `sapling`     |
+| `lastUpdated` | string | ISO 8601 timestamp of the last update     |
 
-> **Note:** Model selection and reasoning effort are managed by each underlying agent CLI (e.g. Claude Code's `/model`), not by Atomic itself. Atomic's chat command spawns the agent's native TUI — use the agent's own controls to pick a model or adjust reasoning effort.
+> Model selection and reasoning effort are managed by each underlying agent CLI (e.g. Claude Code's `/model`), not Atomic. Atomic's chat command spawns the agent's native TUI — use the agent's own controls.
 
 ### Agent-Specific Files
 
@@ -1146,162 +1108,7 @@ Resolution order:
 | OpenCode       | `.opencode/` | `.agents/skills/`                               | `AGENTS.md`  |
 | GitHub Copilot | `.github/`   | `.agents/skills/`                               | `AGENTS.md`  |
 
-> **Note:** All three agents share the same skill set via `.agents/skills/`. Claude Code accesses them through a `.claude/skills/` symlink that points to `.agents/skills/`, so a single skill directory serves all agents.
-
----
-
-## Installation Options
-
-### Bun (recommended)
-
-```bash
-bun install -g @bastani/atomic
-```
-
-### Devcontainer (recommended for autonomous agents)
-
-> [!TIP]
-> Devcontainers isolate the coding agent from your host system, reducing the risk of destructive actions like unintended file deletions or misapplied shell commands. This makes them the safest way to run Atomic.
->
-> Use the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) for VS Code or [DevPod](https://devpod.sh) to spawn and manage your devcontainers.
-
-Add a single feature to your `.devcontainer/devcontainer.json`:
-
-```
-your-project/
-+-- .devcontainer/
-|   +-- devcontainer.json   <-- add the feature here
-+-- src/
-+-- ...
-```
-
-```jsonc
-{
-  "features": {
-    "ghcr.io/flora131/atomic/claude:1": {}   // or /opencode:1 or /copilot:1
-  }
-}
-```
-
-| Feature              | Reference                            | Agent                                                |
-| -------------------- | ------------------------------------ | ---------------------------------------------------- |
-| Atomic + Claude Code | `ghcr.io/flora131/atomic/claude:1`   | [Claude Code](https://claude.ai)                     |
-| Atomic + OpenCode    | `ghcr.io/flora131/atomic/opencode:1` | [OpenCode](https://opencode.ai)                      |
-| Atomic + Copilot CLI | `ghcr.io/flora131/atomic/copilot:1`  | [Copilot CLI](https://github.com/github/copilot-cli) |
-
-Each feature installs the Atomic CLI, all shared dependencies (bun, playwright-cli), agent-specific configurations (agents, skills), and the agent CLI itself. Features are versioned in sync with Atomic CLI releases.
-
-<details>
-<summary>Standalone binary (macOS / Linux)</summary>
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
-# or with wget:
-wget -qO- https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
-```
-
-</details>
-
-<details>
-<summary>Standalone binary (Windows PowerShell)</summary>
-
-```powershell
-irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
-```
-
-</details>
-
-<details>
-<summary>Install a specific version</summary>
-
-```bash
-bun install -g @bastani/atomic@0.5.0-4   # replace with desired version
-```
-
-List all published versions with `npm view @bastani/atomic versions`.
-
-> Don't have bun yet? Run the bootstrap installer first (it installs bun and the latest atomic), then re-run the command above to switch to your desired version.
-
-</details>
-
-<details>
-<summary>Install a prerelease version</summary>
-
-> **Warning:** Prerelease versions may contain breaking changes or bugs. Use for testing only.
-
-Prereleases are published under the `next` dist-tag on npm:
-
-```bash
-bun install -g @bastani/atomic@next
-```
-
-</details>
-
-<details>
-<summary>Authenticated downloads (CI / enterprise)</summary>
-
-Set `GITHUB_TOKEN` to use authenticated GitHub API requests, which avoids rate limits in CI/CD or enterprise environments:
-
-**macOS / Linux:**
-
-```bash
-GITHUB_TOKEN=ghp_... curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash
-```
-
-**Windows PowerShell:**
-
-```powershell
-$env:GITHUB_TOKEN='ghp_...'; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
-```
-
-</details>
-
-<details>
-<summary>Devcontainer examples</summary>
-
-**Atomic + Claude in a Rust project:**
-
-```jsonc
-{
-  "image": "mcr.microsoft.com/devcontainers/rust:latest",
-  "features": {
-    "ghcr.io/flora131/atomic/claude:1": {},
-    "ghcr.io/devcontainers/features/github-cli:1": {}
-  },
-  "remoteEnv": {
-    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
-  }
-}
-```
-
-**Atomic + Copilot in a Python project:**
-
-```jsonc
-{
-  "image": "mcr.microsoft.com/devcontainers/python:3.12",
-  "features": {
-    "ghcr.io/flora131/atomic/copilot:1": {},
-    "ghcr.io/devcontainers/features/github-cli:1": {}
-  },
-  "remoteEnv": {
-    "GH_TOKEN": "${localEnv:GH_TOKEN}"
-  }
-}
-```
-
-**Atomic + OpenCode in a Go project:**
-
-```jsonc
-{
-  "image": "mcr.microsoft.com/devcontainers/go:1.22",
-  "features": {
-    "ghcr.io/flora131/atomic/opencode:1": {},
-    "ghcr.io/devcontainers/features/github-cli:1": {}
-  }
-}
-```
-
-</details>
+All three agents share the same skill set via `.agents/skills/`. Claude Code accesses them through a `.claude/skills/` symlink.
 
 ---
 
@@ -1309,15 +1116,12 @@ $env:GITHUB_TOKEN='ghp_...'; irm https://raw.githubusercontent.com/flora131/atom
 
 ### Update
 
-Use Bun's package manager directly:
-
 ```bash
-bun update -g @bastani/atomic    # latest stable
-# or for prerelease builds:
-bun install -g @bastani/atomic@next
+bun update -g @bastani/atomic      # latest stable
+bun install -g @bastani/atomic@next # prerelease
 ```
 
-The first time you run `atomic` after upgrading, the CLI auto-syncs tooling deps (Node.js/npm) and global skills. No separate command needed.
+The first `atomic` run after upgrading auto-syncs tooling deps and global skills — no separate command needed.
 
 ### Uninstall
 
@@ -1325,47 +1129,14 @@ The first time you run `atomic` after upgrading, the CLI auto-syncs tooling deps
 bun remove -g @bastani/atomic
 ```
 
-That removes the `atomic` binary installed by `bun install -g`. If you used the bootstrap installer (`install.sh` / `install.ps1`) on a machine without Bun, the same `bun remove` command still works once Bun is on your PATH.
-
-<details>
-<summary>Clean up project config files</summary>
-
-> **Warning:** This deletes all project-specific settings, skills, and agents configured by Atomic for the current project.
-
-**macOS / Linux:**
-
-```bash
-rm -rf .claude/ CLAUDE.md              # Claude Code
-rm -rf .opencode/ AGENTS.md            # OpenCode
-rm -f .github/copilot-instructions.md  # Copilot CLI
-rm -rf .atomic/                        # Atomic local settings + workflows
-```
-
-**Windows PowerShell:**
-
-```powershell
-Remove-Item -Path ".claude" -Recurse -Force; Remove-Item "CLAUDE.md" -Force
-Remove-Item -Path ".opencode" -Recurse -Force; Remove-Item "AGENTS.md" -Force
-Remove-Item -Path ".github\copilot-instructions.md" -Force
-Remove-Item -Path ".atomic" -Recurse -Force
-```
-
-</details>
-
 <details>
-<summary>Clean up global config files</summary>
-
-> **Warning:** This deletes Atomic's global settings and cached agent configs.
-
-**macOS / Linux:**
+<summary><b>Also remove global config and cached agent configs</b></summary>
 
 ```bash
+# macOS / Linux
 rm -rf ~/.atomic/
-```
-
-**Windows PowerShell:**
 
-```powershell
+# Windows PowerShell
 Remove-Item -Path "$env:USERPROFILE\.atomic" -Recurse -Force
 ```
 
@@ -1373,11 +1144,10 @@ Remove-Item -Path "$env:USERPROFILE\.atomic" -Recurse -Force
 
 ---
 
-
 ## Troubleshooting
 
 <details>
-<summary>Git identity error</summary>
+<summary><b>Git identity error</b></summary>
 
 ```bash
 git config --global user.name "Your Name"
@@ -1387,43 +1157,22 @@ git config --global user.email "you@example.com"
 </details>
 
 <details>
-<summary>Windows command resolution</summary>
+<summary><b>Windows: agents fail to spawn</b></summary>
 
-If agents fail to spawn on Windows, ensure the agent CLI is in your PATH. Atomic uses `Bun.which()` which handles `.cmd`, `.exe`, and `.bat` extensions automatically.
+Ensure the agent CLI is in your PATH. Atomic uses `Bun.which()`, which handles `.cmd`, `.exe`, and `.bat` extensions automatically.
 
 </details>
 
-<details>
-<summary>Sub-agent tree stuck on "Initializing..."</summary>
-
-1. Update to the latest release (`bun install -g @bastani/atomic`) and retry
-2. Check for terminal progress events in verbose mode
-3. Press `Ctrl+F` twice to terminate stuck background agents, then resend your prompt
-4. If the issue persists, capture reproduction steps and [open an issue](https://github.com/flora131/atomic/issues)
-
-</details>
-
-<details>
-<summary>Shift+Enter not inserting newline</summary>
-
-- **VS Code terminal:** Keep `terminal.integrated.enableKittyKeyboardProtocol` enabled
-- **GNOME Terminal, xterm, Alacritty, WezTerm, iTerm2:** `modifyOtherKeys` mode is enabled automatically
-- **Universal fallback:** Use `Ctrl+J` for newline
-- **Last resort:** End line with `\` and press Enter
-
-</details>
-
-
 ---
 
 ## FAQ
 
 <details>
-<summary>How does Atomic differ from Spec-Kit?</summary>
+<summary><b>How does Atomic differ from Spec-Kit?</b></summary>
 
 [Spec Kit](https://github.com/github/spec-kit) is GitHub's toolkit for "Spec-Driven Development." Both improve AI-assisted development, but solve different problems:
 
-**In short:** Spec-Kit works well for greenfield projects where you start from a spec and use a single Copilot session to generate code. Atomic is built for the harder case — large existing codebases where you need to research what's already there before changing anything. It gives you multi-session pipelines with isolated context windows (so the agent doesn't degrade over long tasks), deterministic execution, and support for Claude Code, OpenCode, and Copilot CLI instead of just one agent. If you're starting a new project from scratch with Copilot, Spec-Kit is simpler. If you're working on an established codebase and need chained sessions, parallel research, or autonomous execution, that's what Atomic is for.
+**In short:** Spec-Kit works well for greenfield projects where you start from a spec and use a single Copilot session to generate code. Atomic is built for the harder case — large existing codebases where you need to research what's already there before changing anything. Atomic gives you multi-session pipelines with isolated context windows, deterministic execution, and support for Claude Code, OpenCode, and Copilot CLI instead of just one agent.
 
 | Aspect                   | Spec-Kit                                     | Atomic                                                                                              |
 | ------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
@@ -1442,11 +1191,11 @@ If agents fail to spawn on Windows, ensure the agent CLI is in your PATH. Atomic
 </details>
 
 <details>
-<summary>How does Atomic differ from DeerFlow?</summary>
+<summary><b>How does Atomic differ from DeerFlow?</b></summary>
 
 [DeerFlow](https://github.com/bytedance/deer-flow) is ByteDance's agent harness built on LangGraph/LangChain. Both are multi-agent orchestrators, but take different approaches:
 
-**In short:** DeerFlow is a general-purpose agent orchestrator — it handles research, report generation, and other tasks through a LangGraph DAG with a web UI. Atomic is narrowly focused on coding workflows. The key difference is that Atomic runs on top of production coding agents (Claude Code, OpenCode, Copilot CLI) rather than reimplementing coding tools through a generic API. You get each agent's native file editing, permissions, MCP integrations, and hooks out of the box. Atomic also gives you deterministic execution — same step order, same data flow every run — which matters when you're encoding a team's dev process and need it to be reproducible across people and CI. If you need a general-purpose agent pipeline with a web UI, DeerFlow is the better fit. If you need coding-specific workflows with strict execution guarantees, Atomic is more appropriate.
+**In short:** DeerFlow is a general-purpose agent orchestrator with a web UI. Atomic is narrowly focused on coding workflows. The key difference is that Atomic runs on top of production coding agents (Claude Code, OpenCode, Copilot CLI) rather than reimplementing coding tools through a generic API — you get each agent's native file editing, permissions, MCP integrations, and hooks out of the box. Atomic also gives you deterministic execution, which matters when encoding a team's dev process.
 
 | Aspect                  | DeerFlow                                        | Atomic                                                                                        |
 | ----------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
@@ -1466,11 +1215,11 @@ If agents fail to spawn on Windows, ensure the agent CLI is in your PATH. Atomic
 </details>
 
 <details>
-<summary>How does Atomic differ from Hermes Agent?</summary>
+<summary><b>How does Atomic differ from Hermes Agent?</b></summary>
 
 [Hermes Agent](https://github.com/NousResearch/hermes-agent) is Nous Research's general-purpose AI agent with a self-improving learning loop. Both are open-source agent frameworks, but serve different use cases:
 
-**In short:** Hermes Agent is a broad AI assistant that learns and improves across sessions, connects to messaging platforms, and works with any OpenAI-compatible model. Atomic is a coding-specific harness built for engineering teams. It lets you encode your development process as deterministic TypeScript workflows that run identically across team members, machines, and CI pipelines. Instead of reimplementing coding tools from scratch, Atomic inherits production-hardened tool ecosystems from Claude Code, OpenCode, and Copilot CLI — including their permission systems, MCP integrations, and hooks — giving you two independent security boundaries (devcontainer isolation + agent permissions) rather than one. Each workflow session runs in a fresh context window with only distilled transcripts passed forward, so output stays sharp over multi-hour coding tasks instead of degrading through lossy compression. And because skills are developer-authored and version-controlled, they don't drift or accumulate errors the way auto-generated skills can. Choose Hermes if you want a self-improving general-purpose agent with multi-platform messaging; choose Atomic if you want repeatable, auditable coding workflows with strict execution guarantees and production-grade isolation.
+**In short:** Hermes is a broad AI assistant that learns across sessions and connects to messaging platforms. Atomic is a coding-specific harness for engineering teams. It lets you encode your development process as deterministic TypeScript workflows that run identically across team members, machines, and CI. Atomic inherits production-hardened tools from Claude Code, OpenCode, and Copilot CLI — including their permission systems, MCP integrations, and hooks — giving you two independent security boundaries (devcontainer isolation + agent permissions). Fresh context per session keeps output sharp over multi-hour tasks. Developer-authored skills don't drift the way auto-generated ones can.
 
 | Aspect                    | Hermes Agent                                                                                 | Atomic                                                                                                                                       |
 | ------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |