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

package/docs/getting-started/authentication.md

@@ -0,0 +1,55 @@
+---
+title: Authentication
+description: Connect Atomic to a provider with a subscription login or an API key.
+---
+
+# Authentication
+
+**Outcome:** Atomic can reach a model provider and `/model` lists models you can select.
+
+**Prerequisites:** [Installation](/getting-started/installation) is complete.
+
+## Authenticate
+
+Atomic can use subscription providers through `/login`, or API-key providers through environment variables or the auth file.
+
+### Option 1: subscription login
+
+Start Atomic and run:
+
+```text
+/login
+```
+
+Choose **Use a subscription**, then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot.
+
+### Option 2: API key
+
+Set an API key before launching Atomic:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+atomic
+```
+
+You can also run `/login`, choose **Use an API key**, then select a provider to store the key in `~/.atomic/agent/auth.json`.
+
+See [Providers](/providers) for all supported providers, environment variables, and cloud-provider setup.
+
+## Verify authentication
+
+Start Atomic in any directory and run:
+
+```text
+/model
+```
+
+Expected result: the model picker opens and lists selectable models for the provider you just configured, with the active one marked. If it opens empty, or Atomic reports that no provider is configured, re-run `/login`, or confirm the API-key environment variable is exported in the same shell you launched Atomic from.
+
+`/login` opens **Select authentication method:**. Choose **Use a subscription** or **Use an API key** to see the corresponding provider picker and credential-configuration status. That status can reflect stored, environment, runtime, or configuration credentials; it does not test connectivity or prove that a provider will accept a request.
+
+Select a model with `/model`, then send a short prompt such as `Reply with hello.` A successful response confirms access for that request. If it fails, check the reported authentication, quota, model-access, or network error before retrying. A configured credential or a listed model alone does not prove access.
+
+## Next step
+
+Continue to [First session](/getting-started/first-session).

package/docs/getting-started/first-session.md

@@ -0,0 +1,172 @@
+---
+title: First session
+description: Start Atomic, run a first task, invoke a built-in workflow, and steer a run.
+---
+
+# First session
+
+**Outcome:** You complete one interactive task and know how to monitor and steer it.
+
+**Prerequisites:** [Authentication](/getting-started/authentication) is complete.
+
+## First session
+
+On a fresh install with no prior Atomic startup state, Atomic shows a one-time first-run explanation after any What's New notes and directly above the input box describing Atomic as a verifiable coding agent runtime for building and running agent workflows you can feel confident in. Returning users with prior startup state are marked onboarded automatically and continue directly into the normal chat UI; stored credentials by themselves do not skip the first-run explanation. The composer is the normal Atomic input from the start: type a message, run `/login` first if no provider is connected, or launch a workflow command without a special onboarding transition.
+
+Once Atomic starts, default to a workflow for non-trivial work and for requests with inherent structure plus a verifiable objective. Implementation, build, debugging, bug fixes, migrations, features, scoped multi-file edits, validation/review work, and loop-shaped requests are workflow candidates; reserve direct chat for tiny deterministic low-risk answers or edits where tracking clearly adds more overhead than value.
+
+Workflow-first is not builtin-only or monolithic. Atomic can discover and run named builtin, project, user, and package workflows; author a rich custom TypeScript `workflow({...})` inline; and compositionally import reusable workflow definitions—including builtins from `@bastani/atomic/workflows/builtin`—into parent workflows with `ctx.workflow(...)`. Nested children can nest again within `maxDepth`, so custom graphs can combine proven research, implementation, design, verification, and approval workflows instead of copying them. They can also classify and branch, dynamically fan out and synthesize artifacts, run adversarial repair cycles, tournament-rank candidates, and loop until checks pass with explicit bounds.
+
+Atomic turns repeatable engineering loops into executable stages with inspectable evidence instead of relying on a markdown checklist the model may or may not follow.
+
+## Verify the session
+
+Run one bounded task and watch it complete. In a repository you know, type:
+
+```text
+List the top-level directories in this repository and say what each one holds.
+```
+
+Expected result: Atomic streams a response, calls `read` on a directory, `find`, or `bash` at least once — each tool call is shown inline as it runs — and finishes with a summary naming directories that actually exist in your checkout. A response that names nothing from your repository means the session started outside the directory you meant; quit, `cd` to the right place, and start Atomic again.
+
+Then confirm the session was recorded:
+
+```bash
+atomic -r
+```
+
+Expected result: the session picker lists the run you just finished. That session is what `atomic -c` resumes.
+
+## Go further
+
+With a session working, these are the fuller capabilities to reach for next. None of them is required for a first successful session.
+
+### Try the built-in workflows
+
+Atomic ships with nine workflows you can run immediately. Use `/workflow list` to see them and `/workflow inputs <name>` to inspect their inputs in your environment.
+
+| Workflow | When to use | Example |
+|---|---|---|
+| `classify-and-act` | Route requests through structured classification and low-confidence human fallback. | `/workflow classify-and-act prompt="Triage and handle this request"` |
+| `fan-out-and-synthesize` | Partition independent slices, including repository-focused research, and synthesize their artifact evidence. | `/workflow fan-out-and-synthesize prompt="Map payment retries by subsystem and synthesize cited findings"` |
+| `adversarial-verification` | Challenge a candidate with fresh verifiers and bounded repair. | `/workflow adversarial-verification task="Verify the migration patch"` |
+| `generate-and-filter` | Generate, dedupe, filter, optionally judge, and shortlist candidates. | `/workflow generate-and-filter prompt="Propose names for the new command"` |
+| `tournament` | Compare whole solutions through balanced pairwise judging. | `/workflow tournament prompt="Design the retry strategy"` |
+| `loop-until-done` | Iterate with a durable ledger until completion or bound exhaustion. | `/workflow loop-until-done prompt="Repair failures until the test suite passes"` |
+| `goal` | Autonomous work that needs a durable ledger, bounded sub-agent orchestration, receipts, and reviewer-gated completion. | `/workflow goal objective="Update the CLI docs, add one example, and validate the docs build"` |
+| `ralph` | Research-first autonomous work with prompt refinement, delegated implementation, and iterative multi-model review. | `/workflow ralph prompt="Implement specs/rate-limit.md and validate burst traffic"` |
+| `open-claude-design` | UI and design-system work with one generated preview, one live review session, and export. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |
+
+<p align="center"><img src="../images/workflow-list.png" alt="Workflow List" width="600" /></p>
+
+Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=5`, `flag=true`, and `prompt="multi word value"` preserve useful types. If you call `/workflow <name>` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it. Goal and Ralph support `git_worktree_dir` only when you explicitly want a reusable worktree, and skip PR creation unless you set `create_pr=true` for the post-approval final stage.
+
+You can also launch workflows with **natural language** — describe the task in chat and ask Atomic to run a matching installed workflow or author a task-specific one:
+
+```text
+Fan out repository research by subsystem, save cited findings as artifacts, and synthesize the evidence.
+```
+
+```text
+Create a worker → fresh verifier → reducer workflow that updates the CLI docs, runs the docs build, and repairs evidence-backed findings until it passes or reaches a bounded stop.
+```
+
+```text
+Use goal to update the CLI docs, include one example, run the docs build, and finish only when reviewers approve the evidence.
+```
+
+```text
+Use ralph to research and implement specs/rate-limit.md, then review and repair it within three loops.
+```
+
+Atomic chooses a complete execution shape, fills inputs from the request, and confirms before launch. Use Goal when a durable ledger and receipt-backed reviewer gate fit the task. Use Ralph when the job benefits from a research-first implementation/review loop. For exact domain contracts that either builtin does not cover, author a custom graph with deterministic checks and bounded repairs.
+
+### Monitor and steer a run
+
+Named workflow runs execute in the background. After launch you get the full run id; user-facing workflow surfaces show that complete UUID. You can still type the full id or a unique short prefix to inspect, connect, pause, quit, or resume a run. Ambiguous prefixes are reported rather than selecting a run arbitrarily.
+
+```text
+/workflow status <run-id>         # inspect one run's progress
+/workflow status                  # list this session's active and terminal runs
+/workflow connect <run-id>        # see agents working; chat with or steer each stage (F2 also opens latest)
+/workflow attach <run-id> <stage> # chat with one stage
+/workflow pause <run-id>          # pause resumably
+/workflow resume <run-id> "go"    # send a steer message and resume
+/workflow quit <run-id>           # pause gracefully and keep the run resumable
+```
+
+The below-editor `BACKGROUND` panel uses two lines per card at 80 columns and wider: the status glyph and full id are on the first line, and the workflow name plus mode/progress/elapsed metadata are on the second. Below 80 columns it collapses to a count-only line. In chat surfaces, a full id wraps onto continuation lines at narrow widths instead of being cut, and the surrounding border remains intact.
+
+Human-in-the-loop prompts (`ctx.ui.input`, `confirm`, `select`, `editor`) surface in the graph viewer, not as chat modals — connect to the run to answer them.
+
+Atomic also posts main-chat lifecycle notices when a run completes, fails, or awaits input. If you answer a workflow prompt in the graph or attached stage chat, the main chat receives a display-only answer summary for audit; it does not wake the model, enter LLM context, or answer later prompts. See [Workflow Operations](/workflows/operations) for the full run-control reference.
+
+### Top skills to invoke directly
+
+Skills are reusable expert instructions. Trigger one with `/skill:<name>` followed by a request:
+
+| Skill | When to use | Example |
+|---|---|---|
+| `research-codebase` | Scoped research that writes a grounded artifact for one subsystem or question. | `/skill:research-codebase how the rate limiter works in src/middleware/` |
+| `create-spec` | Turn research into an implementation-ready plan. | `/skill:create-spec from research/docs/2026-03-rate-limit.md` |
+| `prompt-engineer` | Write, evaluate, migrate, or troubleshoot GPT and Claude prompts using separate model guides. | `/skill:prompt-engineer Draft a sharper repo-research prompt for payment retries end to end.` |
+| `tdd` | Test-first feature or bug work. | `/skill:tdd` |
+| `impeccable` | Critique or refine web/native frontend and product UI; includes detector hooks, framework-aware live review, and mount-failure recovery. | `/skill:impeccable` |
+| `playwright-cli` | Drive a real browser for end-to-end UI checks, screenshots, and reviewable proof videos. | `/skill:playwright-cli` |
+| `qlty` | Lint, auto-format, and measure code quality — complexity, duplication, and code smells — through one CLI across the repository's languages. | `/skill:qlty check this branch before I hand it off` |
+| `liteparse` | Pull text, tables, or values out of PDF, DOCX, PPTX, XLSX, and image files locally. | `/skill:liteparse` |
+| `show-me` | Explain a topic visually with concise diagrams, code-shape sketches, or focused HTML artifacts. HumanLayer, MIT licensed. | `/skill:show-me` |
+
+Impeccable 4.1.1 resolves Live sessions to the selected app root, supports SvelteKit, Nuxt, TanStack Start, Astro, Next.js, Vite, and static HTML injection, and rejects absolute, traversing, or symlinked configured write targets. Its concept roll may contact `impeccable.style`; set `IMPECCABLE_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to disable the anonymous choice ping. The image fallback runs only with `OPENAI_API_KEY`, sends prompts and optional reference images to OpenAI, and spends that account's API credit. Generated image prompts are embedded in the image or a sidecar, so do not include secrets.
+
+Use `/skill:research-codebase` for a focused subsystem or question. For repository-wide research, use `fan-out-and-synthesize` with distinct repository partitions and an artifact synthesis barrier. Use Goal for ledger-backed bounded orchestration and Ralph for research-first delegated implementation with iterative review; task size alone does not select either workflow.
+
+### Create your own workflow in natural language
+
+Named workflows may be builtin, project, user, or package supplied. You do not have to hand-write TypeScript to add a new workflow. Describe what you want in plain chat and Atomic will design and write it for you using [Builtins and Dynamic Workflows](/workflows/builtins) and the [Custom Workflow Authoring](/workflows/authoring) reference as its source of truth:
+
+```text
+Create a reusable Atomic workflow called review-changes. It takes one
+required text input `target` (a diff, PR, or review focus). Run two reviewers
+in parallel with fresh context — one for correctness and missing tests, one
+for edge cases and maintainability — then a synthesis stage that
+consolidates findings into blockers vs. suggestions and returns
+{ consolidated_review, decision }.
+```
+
+Atomic will:
+
+- ask clarifying questions if stage purpose, inputs, models, or handoffs are ambiguous,
+- write a `.atomic/workflows/<name>.ts` definition that uses `workflow({ ... })` and imports `Type` from `typebox`,
+- run `/workflow reload` so the generated workflow is rediscovered and can be launched with `/workflow <name>`,
+- then report the generated workflow folder so you can inspect the code it wrote, using `Custom workflow created. You can inspect its code at: <workflow-folder-path>` (for example, `.atomic/workflows/`); Atomic does this only for newly created custom workflows, never builtin or pre-existing workflows.
+
+The same plain-chat approach works for editing or hardening an existing workflow. For the full authoring reference, see [Custom Workflow Authoring](/workflows/authoring), including composition with user-defined workflows and all nine builtins from `@bastani/atomic/workflows/builtin`.
+
+### Default tools and prompts
+
+If you'd rather start with a plain prompt, just type a request and press Enter:
+
+```text
+Summarize this repository and tell me how to run its checks.
+```
+
+By default, Atomic gives the model these tools:
+
+- `read` - read files
+- `bash` - run shell commands
+- `kill` - cancel owned background shell tasks by task ID
+- `edit` - patch files
+- `write` - create or overwrite files
+- `find` - discover files by glob pattern
+- `search` - search file contents
+- `ask_user_question` - ask structured questions in the TUI
+- `todo` - manage file-based todos
+
+On native Windows, `powershell` is also enabled when a PowerShell executable is available.
+
+Normal coding sessions include file discovery and content search through `find` and `search` in addition to `read`, `bash`, `edit`, and `write`. Atomic runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.
+
+## Next step
+
+Continue to [Project instructions](/getting-started/project-instructions).

package/docs/getting-started/installation.md

@@ -0,0 +1,154 @@
+---
+title: Installation
+description: Install Atomic with a package manager or a release archive, and uninstall it cleanly.
+---
+
+# Installation
+
+**Outcome:** Atomic is on your `PATH` and `atomic --version` prints a version.
+
+**Prerequisites:** A supported shell. See [Prerequisites](/quickstart#prerequisites).
+
+## Install
+
+### Package managers
+
+Install with npm:
+
+```bash
+npm install -g @bastani/atomic
+```
+
+With pnpm:
+
+```bash
+pnpm add -g @bastani/atomic
+```
+
+With Bun:
+
+```bash
+bun add -g @bastani/atomic
+```
+
+Atomic does not require package install scripts. Add `--ignore-scripts` if you want to disable dependency lifecycle scripts during a package install.
+
+Embedded PostgreSQL is available without install scripts or a first-run download on Linux x64/ARM64 (glibc and musl), macOS x64/ARM64, and Windows x64/ARM64. npm-compatible package managers select the matching `@bastani/atomic-natives` leaf containing the runtime; standalone archives carry a target-selected runtime and resolve its binaries directly from the extracted installation. Keep the complete archive directory, including `node_modules`, libraries and licenses. Older upstream optional packages may also remain in npm installations for compatibility, but the native leaf takes precedence. Windows ARM64 uses Windows x64 PostgreSQL under Windows 11's x64 emulation, not native PostgreSQL ARM64, and requires the Microsoft Visual C++ x64 v14 Redistributable. Windows 10 on ARM cannot run this x64 runtime; Windows ARM64 execution still needs hardware validation.
+
+### Release archive
+
+Alternatively, install the self-contained release archive, which needs no Node.js or package manager.
+
+On macOS or Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bastani-inc/atomic/main/install.sh | sh
+```
+
+On Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/bastani-inc/atomic/main/install.ps1 | iex
+```
+
+The installer downloads only the matching GitHub Release archive and `SHA256SUMS`, verifies the checksum, and keeps the complete payload in a versioned directory.
+
+On macOS or Linux, the default paths are `~/.local/share/atomic` for versioned payloads and `~/.local/bin/atomic` for the launcher. The installer prints a paste-safe `export PATH=...` command if needed.
+
+On Windows, the defaults are `%LOCALAPPDATA%\atomic` for payloads and `%LOCALAPPDATA%\atomic\bin\atomic.cmd` for the launcher. The installer updates the User PATH and current process, then asks you to restart the terminal.
+
+The installer accepts these environment variables:
+
+#### ATOMIC_VERSION
+
+Pin an exact release tag instead of the latest release, or pass a flag that overrides it. On macOS or Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bastani-inc/atomic/main/install.sh | sh -s -- --ref 0.9.11
+```
+
+On Windows PowerShell:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/bastani-inc/atomic/main/install.ps1))) -Ref 0.9.11
+```
+
+Pins use Atomic's `MAJOR.MINOR.PATCH` or `MAJOR.MINOR.PATCH-alpha.REVISION` release tag form and are honored literally: if GitHub answers with a different release tag, the installer stops before downloading anything rather than installing a version you did not ask for.
+
+#### ATOMIC_INSTALL_DIR
+
+Override the install root that holds the versioned payloads (default `~/.local/share/atomic` on macOS/Linux, `%LOCALAPPDATA%\atomic` on Windows). On macOS/Linux, a relative value resolves against the physical directory where the installer starts and is used exactly as given, including any trailing whitespace or newline. The install root cannot equal or sit inside the launcher path (`ATOMIC_BIN_DIR/atomic`); impossible layouts fail before any download or filesystem change.
+
+#### ATOMIC_BIN_DIR
+
+Override the launcher directory (default `~/.local/bin` on macOS/Linux, `%LOCALAPPDATA%\atomic\bin` on Windows). Relative values resolve the same way as `ATOMIC_INSTALL_DIR`. It cannot sit inside the install root's `current` or `versions` directories, which the installer replaces on every install. A Unix value containing `:` cannot be one PATH entry, so the installer prints direct-run guidance instead of editing PATH.
+
+#### GITHUB_TOKEN / GH_TOKEN
+
+Optional; raises GitHub API limits on shared networks. Curl and GNU Wget keep the token in a protected temporary file instead of process arguments. BusyBox Wget remains supported without a token, and with a token when the latest-release redirect avoids the API; if an authenticated API fallback is needed, install curl or GNU Wget rather than exposing the token.
+
+### Which runtime runs your workflows
+
+How you install Atomic decides which runtime hosts it: a package-manager install runs under Node, while the standalone binaries are Bun-compiled and run under Bun. Authored workflows execute inside whichever host is active, so a workflow that reaches for a `Bun.*` global runs only under the standalone binary and fails with `Bun is not defined` under an npm install. Installing Bun separately does not change that — the npm install still runs on Node. Write workflow code against APIs both hosts provide, such as `node:child_process` and `node:fs`; see [Custom Workflow Authoring](/workflows/authoring) for the rule and worked examples.
+
+### Alpine and musl Linux archives
+
+The shell installer detects Alpine and selects `atomic-linux-x64-musl.tar.gz` or `atomic-linux-arm64-musl.tar.gz`. Each archive includes its matching native search and PTY bindings plus payload-local `libgcc` and `libstdc++` runtimes, so stock Alpine needs no runtime package install.
+
+Two features work differently on musl:
+
+- **Clipboard:** the musl archives omit a clipboard native binding because `@mariozechner/clipboard` 0.3.9 publishes metadata-only musl stubs without a `.node` payload; Atomic uses Linux clipboard commands and OSC52 fallback instead.
+- **Durable workflows:** the archives omit the glibc-linked `@embedded-postgres/*` binary packages and instead carry a checksum-pinned Alpine/musl PostgreSQL 18.6 runtime, so durable workflows provision offline without external Postgres or Docker. If no durable backend can be provisioned at all, Atomic still uses a loud non-durable in-memory fallback.
+
+Then start Atomic in the project directory you want it to work on:
+
+```bash
+cd /path/to/project
+atomic
+```
+
+## Uninstall
+
+On macOS or Linux, for a default archive install, remove `~/.local/share/atomic` and the `~/.local/bin/atomic` link.
+
+On Windows, remove `%LOCALAPPDATA%\atomic`. If you set `ATOMIC_BIN_DIR`, also remove `atomic.cmd` and the `atomic-current` junction from that directory, then remove the directory from your User PATH.
+
+For a package install, remove the global package with the same package manager. With npm:
+
+```bash
+npm uninstall -g @bastani/atomic
+```
+
+With pnpm:
+
+```bash
+pnpm remove -g @bastani/atomic
+```
+
+With Bun:
+
+```bash
+bun remove -g @bastani/atomic
+```
+
+These commands remove the CLI only. User configuration, auth, sessions, and packages remain under `~/.atomic/agent/` unless you delete that directory yourself.
+
+## Verify the install
+
+Run:
+
+```bash
+atomic --version
+```
+
+Expected output is a single version line, for example:
+
+```text
+0.9.14-alpha.2
+```
+
+If the shell reports `command not found`, the launcher directory is not on your `PATH` yet. Open a new shell, or add the bin directory the installer printed to your `PATH` and try again.
+
+## Next step
+
+Continue to [Authentication](/getting-started/authentication).

package/docs/getting-started/project-instructions.md

@@ -0,0 +1,43 @@
+---
+title: Project instructions
+description: Give Atomic durable, repository-specific instructions with AGENTS.md.
+---
+
+# Project instructions
+
+**Outcome:** Atomic loads your repository's conventions automatically in every session.
+
+**Prerequisites:** [First session](/getting-started/first-session) is complete.
+
+## Give Atomic project instructions
+
+Atomic loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project:
+
+```markdown
+# Project Instructions
+
+- Run `bun run typecheck` after code changes.
+- Do not run production migrations locally.
+- Keep responses concise.
+```
+
+Atomic loads:
+
+- `~/.atomic/agent/AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` for global instructions (legacy `~/.pi/agent/` also works)
+- `AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` from parent directories and the current directory
+
+An `AGENTS.override.md` file replaces the other context files in its directory. Restart Atomic, or run `/reload`, after changing context files.
+
+## Verify Atomic loaded them
+
+With `AGENTS.md` saved, run `/reload` (or restart Atomic), then ask:
+
+```text
+What project instructions are you following in this repository?
+```
+
+Expected result: the answer restates your own rules — the `bun run typecheck` line above, or whatever you wrote — rather than generic advice. A generic answer means the file was not picked up: confirm it is named `AGENTS.md`, that it sits in the directory you started Atomic from or one of its parents, and that no `AGENTS.override.md` in the same directory is replacing it.
+
+## Next step
+
+Continue to [Interactive use](/usage), then [Configuration](/guides/configuration).

package/docs/guides/configuration.md

@@ -0,0 +1,65 @@
+---
+title: Configure Atomic
+description: Write your first settings file and override settings per project.
+---
+
+# Configure Atomic
+
+**Outcome:** A working `settings.json` and, where you need one, a project-scoped override.
+
+**Prerequisites:** [First session](/getting-started/first-session) is complete.
+
+## Example
+
+```json
+{
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-20250514",
+  "defaultThinkingLevel": "medium",
+  "theme": "dark",
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "compression_ratio": 0.5,
+    "preserve_recent": 2
+  },
+  "retry": {
+    "enabled": true,
+    "maxRetries": 3
+  },
+  "httpIdleTimeoutMs": 300000,
+  "enabledModels": ["claude-*", "gpt-4o"],
+  "warnings": {
+    "anthropicExtraUsage": true
+  },
+  "packages": ["pi-skills"],
+  "workflows": ["./workflows/*.ts"]
+}
+```
+
+## Project Overrides
+
+Project settings (`.atomic/settings.json`) override global settings. Nested objects merge recursively; arrays and scalar values replace global values:
+
+```json
+// ~/.atomic/agent/settings.json (global)
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 16384 }
+}
+
+// .atomic/settings.json (project)
+{
+  "compaction": { "reserveTokens": 8192 }
+}
+
+// Result
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 8192 }
+}
+```
+
+## Next step
+
+Every field is listed in the [Settings reference](/settings).

package/docs/guides/intercom.md

@@ -0,0 +1,24 @@
+---
+title: "Intercom"
+description: "What Intercom is, when sessions should talk to each other, and where the full Intercom guide lives."
+---
+
+# Intercom
+
+Intercom is a message channel between agent sessions running on the same machine. Sessions in the same group can send each other messages, ask questions and wait for an answer, and coordinate without going through you.
+
+## When to use one
+
+Use it when two sessions are working on related things and one knows something the other needs: a planner handing work to a worker, a long-running session reporting a finding, or steering a workflow stage while it runs. You do not need it for a single session working alone.
+
+## What you get
+
+- Send, ask-and-wait, and reply between live sessions in your group.
+- Groups that keep unrelated sessions isolated from each other.
+- Delivery to workflow stages, including stages that have not started yet.
+
+## Next steps
+
+- [Intercom](/intercom) — the full guide, including groups and addressing.
+- [Operations](/intercom/operations) — observable states and recovery actions.
+- [Subagents](/guides/subagents) — when delegation is a better fit than coordination.

package/docs/guides/non-interactive.md

@@ -0,0 +1,33 @@
+---
+title: "Non-interactive use"
+description: "Orientation for running Atomic without the interactive TUI: print mode, the JSON event stream, and RPC."
+---
+
+# Non-interactive use
+
+Atomic does not need a terminal UI. The same session engine backs three non-interactive entry points, and each one is documented in full elsewhere — this page only helps you pick.
+
+| You want | Use | Read |
+| --- | --- | --- |
+| One prompt, one answer, then exit | Print mode (`-p`, `--print`) | [CLI reference](/reference/cli#modes) |
+| A machine-readable stream of everything the session does | JSON event stream | [JSON event stream](/json) |
+| A long-lived session another program drives | RPC | [RPC](/rpc) |
+| To embed Atomic in your own TypeScript program | SDK | [SDK](/sdk) |
+
+## Print mode
+
+`atomic --print "..."` runs a single turn and exits. It also reads piped stdin and merges it into the prompt, so it composes with ordinary shell pipelines. Flags, exit codes, and the stdin merge rules are in the [CLI reference](/reference/cli).
+
+## JSON events
+
+When you need to observe a run rather than read it, the JSON event stream emits one structured record per message, tool call, and result. Use it for logging, CI annotations, or piping into another tool. The event shapes are in [JSON event stream](/json).
+
+## RPC
+
+RPC keeps a session alive and lets another process send prompts, answer prompts, and receive events over a protocol. Use it when a single request/response is not enough — editors, bots, and long-running services. Start at [RPC](/rpc) and the [RPC protocol](/rpc/protocol).
+
+## Next steps
+
+- [CLI reference](/reference/cli) for every flag and exit code.
+- [Programmatic use](/programmatic) for choosing between the SDK, RPC, and the event stream.
+- [Background and parallel work](/background-tasks) if the work should continue while you keep chatting interactively.

package/docs/guides/subagents.md

@@ -0,0 +1,24 @@
+---
+title: "Subagents"
+description: "What subagents are, when delegation helps, and where the full subagent guide lives."
+---
+
+# Subagents
+
+A subagent is a second agent session your main session launches for a focused piece of work. It has its own context window, so a noisy investigation does not crowd out your conversation.
+
+## When to use one
+
+Delegate when the work is bounded and separable: searching an unfamiliar area of the codebase, reproducing a failure, reviewing a change with fresh eyes, or several independent tasks that can run at once. Keep work in your own session when it is small, or when it depends on context the subagent would have to rediscover.
+
+## What you get
+
+- Single or parallel runs, with results returned to your session.
+- Fresh or forked context, so a delegate can start clean or inherit what you know.
+- Background execution — launch, keep chatting, and collect results later.
+
+## Next steps
+
+- [Subagents](/subagents) — the full guide, including builtin agents and execution modes.
+- [Authoring](/subagents/authoring) — define your own agents.
+- [Background and parallel work](/background-tasks) — inspect, wait on, and stop delegated work.

package/docs/guides/workflows.md

@@ -0,0 +1,27 @@
+---
+title: "Workflows"
+description: "What workflows are, when to reach for one, and where the full authoring and operations guides live."
+---
+
+# Workflows
+
+A workflow runs a multi-stage job for you: each stage is a tracked unit of work with its own prompt, tools, and outputs, and the stages form a graph rather than one long chat.
+
+## When to use one
+
+Reach for a workflow when the task has structure and a finish line you can check — an implementation with review, a migration with verification, a "keep fixing until the checks pass" loop. Stay in normal chat for a single edit or a quick question, where the tracking costs more than it gives you.
+
+## What you get
+
+- Stages that run in order or in parallel, with their own models and tool access.
+- Durable runs you can pause, resume, inspect, and steer while they work.
+- Explicit stop conditions and evidence, instead of a transcript you have to re-read.
+
+Run one with the `workflow` tool, or from chat with `/workflow`. Connect to a live run with `/workflow connect <run>` to watch stages and talk to them.
+
+## Next steps
+
+- [Workflows](/workflows) — the full guide, including builtins and the run lifecycle.
+- [Builtins](/workflows/builtins) — the workflows that ship with Atomic.
+- [Authoring](/workflows/authoring) — write your own workflow in TypeScript.
+- [Operations](/workflows/operations) — run control, prompts, and troubleshooting.

package/docs/guides.md

@@ -0,0 +1,41 @@
+---
+title: Guides
+description: "Task guides for everyday work with Atomic: interactive use, sessions, context, providers, local models, security, and containers."
+---
+
+# Guides
+
+Guides answer "how do I do this task with Atomic" once Atomic is installed and authenticated.
+
+New to Atomic? Start with the ordered onboarding path in the [Quickstart](/quickstart) instead — it installs Atomic, authenticates a provider, runs a first session, and adds project instructions. Come back here when you want to go deeper on one task.
+
+Looking to extend or embed Atomic? Go to [Build with Atomic](/build). Looking up an exact flag, setting, event, or type? Go to the [Reference index](/reference).
+
+## Recommended order
+
+1. [Interactive use](/usage) — the interactive loop, slash commands, and context files.
+2. [Configure Atomic](/guides/configuration) — write a settings file and override it per project.
+3. [Sessions](/sessions) — save, resume, name, and branch sessions.
+4. [Context and compaction](/compaction) — keep long sessions inside the context window.
+5. [Providers](/providers) — subscription logins, API keys, and cloud providers.
+6. [Local models](/llama-cpp) — run models locally with llama.cpp.
+7. [Security](/security) — project trust and sandbox boundaries.
+8. [Containerization](/containerization) — run Atomic inside a container.
+
+For work that continues while you chat, follow [Background tasks](/background-tasks) to launch, inspect, and stop agents or shells. If you use Herdr panes, [Herdr](/herdr) explains Atomic's status indicators and troubleshooting.
+
+## Start here
+
+- [Quickstart](/quickstart) - install, authenticate, and run a first session.
+- [Using Atomic](/usage) - interactive mode, slash commands, context files, and CLI reference.
+- [Computer use](/computer-use) - work in desktop apps, browsers, and terminals across macOS, Linux, and Windows.
+- [Providers](/providers) - subscription and API-key setup for built-in providers.
+- [Environment variables](/environment-variables) - Atomic/Pi aliases, provider credentials, and bash session metadata.
+- [Security](/security) - project trust, sandbox boundaries, and vulnerability reporting.
+- [Containerization](/containerization) - sandbox Atomic with OpenShell, Gondolin, or Docker.
+- [Settings](/settings) - global and project settings.
+- [Keybindings](/keybindings) - default shortcuts and custom keybindings.
+- [Sessions](/sessions) - session management, branching, and tree navigation.
+- [Compaction](/compaction) - Verbatim Compaction, context management, and branch summarization.
+- [Background tasks](/background-tasks) - run work in the background, inspect results, and stop owned tasks.
+- [Herdr](/herdr) - report Atomic's working, blocked, and idle states in Herdr panes.