@bastani/atomic 0.9.19-alpha.6 → 0.9.19-alpha.8

package/docs/quickstart.md

@@ -1,7 +1,20 @@
 # Quickstart
 
+**Outcome:** Atomic is installed, authenticated, and has completed one useful task in your repository.
+
 This page gets you from install to a useful first Atomic session. Atomic is the loop engine for all engineering work: it runs reliable coding-agent loops with stages, tools, artifacts, verification, subagents, review gates, checkpoints, and human approvals.
 
+It is the ordered onboarding hub: each step below links to a focused page that carries the full detail. Work through them in order.
+
+## Onboarding path
+
+1. **[Install Atomic](/getting-started/installation)** — package manager or self-contained release archive.
+2. **[Authenticate](/getting-started/authentication)** — subscription login or API key.
+3. **[Run your first session](/getting-started/first-session)** — start Atomic, run a task, invoke a built-in workflow, and steer the run.
+4. **[Add project instructions](/getting-started/project-instructions)** — teach Atomic your repository's conventions with `AGENTS.md`.
+
+Then come back here for [common things to try](#common-things-to-try) and [next steps](#next-steps).
+
 ## Prerequisites
 
 - **Package install:** Node.js 22.19 or newer plus npm, pnpm, Yarn, or Bun. Use Bun 1.4.2+ for Bun installs or workflow-authoring examples.
@@ -10,306 +23,97 @@ This page gets you from install to a useful first Atomic session. Atomic is the
 
 ## Install
 
-### Package managers
-
-Install with npm:
-
-```bash
-npm install -g @bastani/atomic
-```
-
-With pnpm:
-
-```bash
-pnpm add -g @bastani/atomic
-```
+The install commands and every installer knob, default path, and platform note now live on the installation page.
 
-With Bun:
+Moved to [Installation](/getting-started/installation#install).
 
-```bash
-bun add -g @bastani/atomic
-```
+### Package managers
 
-Atomic does not require package install scripts. Add `--ignore-scripts` if you want to disable dependency lifecycle scripts during a package install.
+Moved to [Installation](/getting-started/installation#package-managers).
 
-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.
+Full detail: package manager commands and the `--ignore-scripts` note.
 
 ### 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.
+Moved to [Installation](/getting-started/installation#release-archive).
 
-The installer accepts these environment variables:
+Full detail: version pinning, `ATOMIC_VERSION`, `ATOMIC_INSTALL_DIR`, `ATOMIC_BIN_DIR`, `GITHUB_TOKEN`/`GH_TOKEN`, default paths, and PATH guidance.
 
 #### 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.
+Moved to [Installation](/getting-started/installation#atomic_version).
 
 #### 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.
+Moved to [Installation](/getting-started/installation#atomic_install_dir).
 
 #### 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.
+Moved to [Installation](/getting-started/installation#atomic_bin_dir).
 
 #### 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.
+Moved to [Installation](/getting-started/installation#github_token-/-gh_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.
+Moved to [Installation](/getting-started/installation#which-runtime-runs-your-workflows).
 
 ### 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
-```
+Moved to [Installation](/getting-started/installation#alpine-and-musl-linux-archives).
 
 ## 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.
+Moved to [Installation](/getting-started/installation#uninstall).
 
-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.
+Full detail: removing the install root, the launcher, and the PATH entry on every platform.
 
 ## Authenticate
 
-Atomic can use subscription providers through `/login`, or API-key providers through environment variables or the auth file.
-
-### Option 1: subscription login
+Moved to [Authentication](/getting-started/authentication#authenticate).
 
-Start Atomic and run:
+Full detail: `/login` subscription providers and API-key environment variables.
 
-```text
-/login
-```
+### Option 1: subscription login
 
-Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot.
+Moved to [Authentication](/getting-started/authentication#option-1-subscription-login).
 
 ### Option 2: API key
 
-Set an API key before launching Atomic:
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-atomic
-```
-
-You can also run `/login` and select an API-key provider to store the key in `~/.atomic/agent/auth.json`.
-
-See [Providers](/providers) for all supported providers, environment variables, and cloud-provider setup.
+Moved to [Authentication](/getting-started/authentication#option-2-api-key).
 
 ## 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.
+Moved to [First session](/getting-started/first-session#first-session-2).
 
-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.
+Full detail: starting Atomic, the built-in workflows, monitoring and steering a run, top skills, creating a workflow in natural language, and the default tools and prompts.
 
 ### 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.
+Moved to [First session](/getting-started/first-session#try-the-built-in-workflows).
 
 ### 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.
+Moved to [First session](/getting-started/first-session#monitor-and-steer-a-run).
 
 ### 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.
+Moved to [First session](/getting-started/first-session#top-skills-to-invoke-directly).
 
 ### 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`.
+Moved to [First session](/getting-started/first-session#create-your-own-workflow-in-natural-language).
 
 ### 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
-- `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
-
-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.
+Moved to [First session](/getting-started/first-session#default-tools-and-prompts).
 
 ## 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
+Moved to [Project instructions](/getting-started/project-instructions#give-atomic-project-instructions).
 
-An `AGENTS.override.md` file replaces the other context files in its directory. Restart Atomic, or run `/reload`, after changing context files.
+Full detail: `AGENTS.md` discovery, precedence, and what to put in it.
 
 ## Common things to try
 
@@ -372,5 +176,7 @@ Use `--mode json` for JSON event output or `--mode rpc` for process integration.
 - [Settings](/settings) - global and project configuration.
 - [Keybindings](/keybindings) - shortcuts and customization.
 - [Atomic Packages](/packages) - install shared extensions, skills, prompts, and themes.
+- [Security](/security) - project trust, what Atomic is allowed to touch, and how to report a vulnerability. Read this before you trust a project or install someone else's skills, extensions, or packages.
+- [Containerization](/containerization) - run Atomic or its tools inside an isolated environment.
 
 Platform notes: [Windows](/windows), [Termux](/termux), [tmux](/tmux), [Terminal setup](/terminal-setup), [Shell aliases](/shell-aliases).

package/docs/reference/cli.md

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