@bastani/atomic 0.8.13-0 → 0.8.14-0

package/docs/quickstart.md

@@ -2,14 +2,30 @@
 
 This page gets you from install to a useful first Atomic session.
 
+## Prerequisites
+
+- **Node.js 24 LTS or newer** — Atomic requires the latest Node LTS runtime. Check with `node --version`.
+- **A package manager** — use npm (included with Node), pnpm, Yarn, or Bun. Use Bun 1.3.14+ for Bun installs or workflow-authoring examples.
+- **Model-provider access** — bring an API key or sign in with `/login` after startup.
+- **A compatible terminal** — for the best TUI experience, use a terminal with Kitty keyboard protocol support. See [Terminal setup](terminal-setup.md). On Windows, use Git Bash or WSL.
+
 ## Install
 
-Atomic is distributed as an npm package:
+Atomic is distributed through npm-compatible package managers. Choose one:
 
 ```bash
+# npm
 npm install -g @bastani/atomic
+
+# Bun
+bun install -g @bastani/atomic
+
+# pnpm
+pnpm add -g @bastani/atomic
 ```
 
+Atomic does not require package install scripts. If you want to disable dependency lifecycle scripts during the Atomic install, you can add `--ignore-scripts` to the install command.
+
 Then start Atomic in the project directory you want it to work on:
 
 ```bash
@@ -46,7 +62,85 @@ See [Providers](providers.md) for all supported providers, environment variables
 
 ## First session
 
-Once Atomic starts, type a request and press Enter:
+Once Atomic starts, the fastest way to get value is to kick off a built-in workflow or invoke a skill — Atomic plans and executes multi-stage work for you.
+
+For an interactive tour any time, run `/atomic` inside the TUI; `/atomic overview`, `/atomic workflows`, and `/atomic example` walk through the same flow in more depth.
+
+### Try the built-in workflows
+
+Atomic ships with three 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 |
+|---|---|---|
+| `deep-research-codebase` | Broad, cross-cutting research before you decide what to change. Scout → research-history → parallel specialist waves → aggregator. | `/workflow deep-research-codebase prompt="How do payment retries work end to end?"` |
+| `ralph` | Larger implementation loops with built-in plan → orchestrate → simplify → parallel review iteration. | `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate the behavior" max_loops=5` |
+| `open-claude-design` | UI and design-system work with generation, critique, and refinement loops; renders a live `preview.html` you can iterate against. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy" output_type=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 `max_loops=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.
+
+You can also launch workflows with **natural language** — just describe the task in chat and ask Atomic to run the matching workflow:
+
+```text
+Run a deep codebase research workflow on how the rate limiter behaves under burst traffic.
+```
+
+Atomic picks the workflow, fills in inputs from the request, and confirms before launch.
+
+### Monitor and steer a run
+
+Named workflow runs execute in the background. After launch you get a run id; use it to inspect, attach, pause, or resume:
+
+```text
+/workflow status                  # list in-flight runs (add --all for ended runs)
+/workflow connect <run-id>        # open the graph viewer (F2 also opens the latest)
+/workflow attach <run-id> <stage> # chat with one stage
+/workflow interrupt <run-id>      # pause resumably
+/workflow resume <run-id> "go"    # send a steer message and resume
+/workflow kill <run-id>           # destructive abort
+```
+
+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. See [Workflows](workflows.md) for the full reference and authoring guide.
+
+### 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` | Tighten a vague prompt before a long run. | `/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 frontend and product UI. | `/skill:impeccable` |
+
+Use `/skill:research-codebase` for a focused area and `/workflow deep-research-codebase` when the answer spans the whole repo. A typical flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow ralph` to implement and validate.
+
+### Create your own workflow in natural language
+
+You do not have to write TypeScript to add a new workflow. Describe what you want in plain chat and Atomic will design and write it for you using the [Workflows](workflows.md) reference as the 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 `defineWorkflow(...).input(...).run(...).compile()`,
+- and reload so you can immediately run it with `/workflow <name>`.
+
+The same plain-chat approach works for editing or hardening an existing workflow — ask Atomic to add a stage, switch a model, save artifacts, or wire in a human approval gate. For the full authoring reference, see [Workflows](workflows.md).
+
+### 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.
@@ -136,6 +230,8 @@ Use `--mode json` for JSON event output or `--mode rpc` for process integration.
 ## Next steps
 
 - [Using Atomic](usage.md) - interactive mode, slash commands, sessions, context files, and CLI reference.
+- [Workflows](workflows.md) - run, inspect, and author multi-stage automation (including the three built-in workflows).
+- [Skills](skills.md) - reusable expert instructions invoked with `/skill:<name>`.
 - [Providers](providers.md) - authentication and model setup.
 - [Settings](settings.md) - global and project configuration.
 - [Keybindings](keybindings.md) - shortcuts and customization.

package/docs/rpc.md

@@ -2,7 +2,7 @@
 
 RPC mode enables headless operation of the coding agent via a JSON protocol over stdin/stdout. This is useful for embedding the agent in other applications, IDEs, or custom UIs.
 
-**Note for Node.js/TypeScript users**: If you're building a Node.js application, consider using `AgentSession` directly from `@bastani/atomic` instead of spawning a subprocess. See [`src/core/agent-session.ts`](../src/core/agent-session.ts) for the API. For a subprocess-based TypeScript client, see [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts).
+**Note for Node.js/TypeScript users**: If you're building a Node.js application, consider using `AgentSession` directly from `@bastani/atomic` instead of spawning a subprocess. See [`src/core/agent-session.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/core/agent-session.ts) for the API. For a subprocess-based TypeScript client, see [`src/modes/rpc/rpc-client.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts).
 
 ## Starting RPC Mode
 
@@ -209,7 +209,7 @@ Response:
 }
 ```
 
-Messages are `AgentMessage` objects (see [Message Types](#message-types)).
+Messages are `AgentMessage` objects (see [Types](#types)).
 
 ### Model
 
@@ -1200,10 +1200,10 @@ Parse errors:
 ## Types
 
 Source files:
-- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
-- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `AgentEvent`
-- [`src/core/messages.ts`](../src/core/messages.ts) - `BashExecutionMessage`
-- [`src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
+- [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
+- [`packages/agent/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts) - `AgentMessage`, `AgentEvent`
+- [`src/core/messages.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/core/messages.ts) - `BashExecutionMessage`
+- [`src/modes/rpc/rpc-types.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
 
 ### Model
 
@@ -1350,9 +1350,9 @@ for event in read_events():
 
 ## Example: Interactive Client (Node.js)
 
-See [`test/rpc-example.ts`](../test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts) for a typed client implementation.
+See [`test/rpc-example.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts) for a typed client implementation.
 
-For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](../examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](../examples/extensions/rpc-demo.ts) extension.
+For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/rpc-demo.ts) extension.
 
 ```javascript
 const { spawn } = require("child_process");

package/docs/sdk.md

@@ -11,7 +11,7 @@ The SDK provides programmatic access to atomic's agent capabilities. Use it to e
 - Build custom tools that spawn sub-agents
 - Test agent behavior programmatically
 
-See [examples/sdk/](../examples/sdk/) for working examples from minimal to full control.
+See [examples/sdk/](https://github.com/flora131/atomic/tree/main/packages/coding-agent/examples/sdk) for working examples from minimal to full control.
 
 ## Quick Start
 
@@ -39,10 +39,21 @@ await session.prompt("What files are in the current directory?");
 
 ## Installation
 
+Choose npm, Bun, or pnpm:
+
 ```bash
+# npm
 npm install @bastani/atomic
+
+# Bun
+bun add @bastani/atomic
+
+# pnpm
+pnpm add @bastani/atomic
 ```
 
+Atomic does not require package install scripts. If you want to disable dependency lifecycle scripts during the Atomic install, you can add `--ignore-scripts` to the install command.
+
 The SDK is included in the main package. No separate installation needed.
 
 ## Core Concepts
@@ -407,7 +418,7 @@ If no model is provided:
 2. Uses default from settings
 3. Falls back to first available model
 
-> See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
+> See [examples/sdk/02-custom-model.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/02-custom-model.ts)
 
 ### API Keys and OAuth
 
@@ -448,7 +459,7 @@ const { session } = await createAgentSession({
 const simpleRegistry = ModelRegistry.inMemory(authStorage);
 ```
 
-> See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
+> See [examples/sdk/09-api-keys-and-oauth.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/09-api-keys-and-oauth.ts)
 
 ### System Prompt
 
@@ -465,7 +476,7 @@ await loader.reload();
 const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
-> See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
+> See [examples/sdk/03-custom-prompt.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/03-custom-prompt.ts)
 
 ### Tools
 
@@ -513,7 +524,7 @@ const { session } = await createAgentSession({
 });
 ```
 
-> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
+> See [examples/sdk/05-tools.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/05-tools.ts)
 
 ### Custom Tools
 
@@ -547,7 +558,7 @@ Custom tools passed via `customTools` are combined with extension-registered too
 
 If you pass `tools`, include each custom or extension tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`.
 
-> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
+> See [examples/sdk/05-tools.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/05-tools.ts)
 
 ### Extensions
 
@@ -587,7 +598,7 @@ await loader.reload();
 eventBus.on("my-extension:status", (data) => console.log(data));
 ```
 
-> See [examples/sdk/06-extensions.ts](../examples/sdk/06-extensions.ts) and [docs/extensions.md](extensions.md)
+> See [examples/sdk/06-extensions.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/06-extensions.ts) and [docs/extensions.md](extensions.md)
 
 ### Skills
 
@@ -617,7 +628,7 @@ await loader.reload();
 const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
-> See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
+> See [examples/sdk/04-skills.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/04-skills.ts)
 
 ### Context Files
 
@@ -637,7 +648,7 @@ await loader.reload();
 const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
-> See [examples/sdk/07-context-files.ts](../examples/sdk/07-context-files.ts)
+> See [examples/sdk/07-context-files.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/07-context-files.ts)
 
 ### Slash Commands
 
@@ -666,7 +677,7 @@ await loader.reload();
 const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
-> See [examples/sdk/08-prompt-templates.ts](../examples/sdk/08-prompt-templates.ts)
+> See [examples/sdk/08-prompt-templates.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/08-prompt-templates.ts)
 
 ### Session Management
 
@@ -770,7 +781,7 @@ sm.branchWithSummary(id, "Summary...");  // Branch with context summary
 sm.createBranchedSession(leafId);       // Extract path to new file
 ```
 
-> See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [Session Format](session-format.md)
+> See [examples/sdk/11-sessions.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/11-sessions.ts) and [Session Format](session-format.md)
 
 ### Settings Management
 
@@ -821,7 +832,7 @@ Project overrides global. Nested objects merge keys. Setters modify global setti
 - Call `await settingsManager.flush()` when you need a durability boundary (for example, before process exit or before asserting file contents in tests).
 - `SettingsManager` does not print settings I/O errors. Use `settingsManager.drainErrors()` and report them in your app layer.
 
-> See [examples/sdk/10-settings.ts](../examples/sdk/10-settings.ts)
+> See [examples/sdk/10-settings.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/sdk/10-settings.ts)
 
 ## ResourceLoader
 

package/docs/sessions.md

@@ -62,7 +62,7 @@ Named sessions are easier to find in `/resume` and `atomic -r`.
 
 Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
 
-<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
+<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600" /></p>
 
 Example shape:
 

package/docs/skills.md

@@ -116,9 +116,16 @@ description: What this skill does and when to use it. Be specific.
 
 ## Setup
 
-Run once before first use:
+Run once before first use (choose one):
 ```bash
+# npm
 cd /path/to/skill && npm install
+
+# Bun
+cd /path/to/skill && bun install
+
+# pnpm
+cd /path/to/skill && pnpm install
 ```
 
 ## Usage
@@ -209,7 +216,14 @@ description: Web search and content extraction via Brave Search API. Use for sea
 ## Setup
 
 ```bash
+# npm
 cd /path/to/brave-search && npm install
+
+# Bun
+cd /path/to/brave-search && bun install
+
+# pnpm
+cd /path/to/brave-search && pnpm install
 ```
 
 ## Search

package/docs/termux.md

@@ -16,9 +16,17 @@ pkg update && pkg upgrade
 # Install dependencies
 pkg install nodejs termux-api git
 
-# Install Atomic
+# Install Atomic (choose one package manager available in Termux)
+# npm is installed by `pkg install nodejs`; Bun and pnpm must be installed separately before using those commands.
+# npm
 npm install -g @bastani/atomic
 
+# Bun
+bun install -g @bastani/atomic
+
+# pnpm
+pnpm add -g @bastani/atomic
+
 # Create config directory
 mkdir -p ~/.atomic/agent
 
@@ -26,6 +34,8 @@ mkdir -p ~/.atomic/agent
 atomic
 ```
 
+Atomic does not require package install scripts. If you want to disable dependency lifecycle scripts during the Atomic install, you can add `--ignore-scripts` to the install command.
+
 ## Clipboard Support
 
 Clipboard operations use `termux-clipboard-set` and `termux-clipboard-get` when running in Termux. The Termux:API app must be installed for these to work.

package/docs/themes.md

@@ -291,9 +291,9 @@ echo $COLORTERM  # Should output "truecolor" or "24bit"
 ## Examples
 
 See the built-in themes:
-- [dark.json](../src/modes/interactive/theme/dark.json)
-- [light.json](../src/modes/interactive/theme/light.json)
-- [catppuccin-frappe.json](../src/modes/interactive/theme/catppuccin-frappe.json)
-- [catppuccin-latte.json](../src/modes/interactive/theme/catppuccin-latte.json)
-- [catppuccin-macchiato.json](../src/modes/interactive/theme/catppuccin-macchiato.json)
-- [catppuccin-mocha.json](../src/modes/interactive/theme/catppuccin-mocha.json)
+- [dark.json](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/interactive/theme/dark.json)
+- [light.json](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/interactive/theme/light.json)
+- [catppuccin-frappe.json](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/interactive/theme/catppuccin-frappe.json)
+- [catppuccin-latte.json](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/interactive/theme/catppuccin-latte.json)
+- [catppuccin-macchiato.json](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/interactive/theme/catppuccin-macchiato.json)
+- [catppuccin-mocha.json](https://github.com/flora131/atomic/blob/main/packages/coding-agent/src/modes/interactive/theme/catppuccin-mocha.json)

package/docs/tui.md

@@ -175,7 +175,7 @@ await showMenu();  // First show
 await showMenu();  // "Back" = just call again
 ```
 
-See [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for comprehensive examples covering anchors, margins, stacking, responsive visibility, and animation.
+See [overlay-qa-tests.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/overlay-qa-tests.ts) for comprehensive examples covering anchors, margins, stacking, responsive visibility, and animation.
 
 ## Built-in Components
 
@@ -644,7 +644,7 @@ pi.registerCommand("pick", {
 });
 ```
 
-**Examples:** [preset.ts](../examples/extensions/preset.ts), [tools.ts](../examples/extensions/tools.ts)
+**Examples:** [preset.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/preset.ts), [tools.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/tools.ts)
 
 ### Pattern 2: Async Operation with Cancel (BorderedLoader)
 
@@ -676,7 +676,7 @@ pi.registerCommand("fetch", {
 });
 ```
 
-**Examples:** [qna.ts](../examples/extensions/qna.ts), [handoff.ts](../examples/extensions/handoff.ts)
+**Examples:** [qna.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/qna.ts), [handoff.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/handoff.ts)
 
 ### Pattern 3: Settings/Toggles (SettingsList)
 
@@ -720,7 +720,7 @@ pi.registerCommand("settings", {
 });
 ```
 
-**Examples:** [tools.ts](../examples/extensions/tools.ts)
+**Examples:** [tools.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/tools.ts)
 
 ### Pattern 4: Persistent Status Indicator
 
@@ -734,7 +734,7 @@ ctx.ui.setStatus("my-ext", ctx.ui.theme.fg("accent", "● active"));
 ctx.ui.setStatus("my-ext", undefined);
 ```
 
-**Examples:** [status-line.ts](../examples/extensions/status-line.ts), [plan-mode.ts](../examples/extensions/plan-mode.ts), [preset.ts](../examples/extensions/preset.ts)
+**Examples:** [status-line.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/status-line.ts), [plan-mode/index.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/plan-mode/index.ts), [preset.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/preset.ts)
 
 ### Pattern 4b: Working Indicator Customization
 
@@ -764,7 +764,7 @@ ctx.ui.setWorkingIndicator();
 
 This only affects the normal streaming working indicator. Compaction and retry loaders keep their built-in styling. Custom frames are rendered verbatim, so extensions must add their own colors when needed.
 
-**Examples:** [working-indicator.ts](../examples/extensions/working-indicator.ts)
+**Examples:** [working-indicator.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/working-indicator.ts)
 
 ### Pattern 5: Widgets Above/Below Editor
 
@@ -794,7 +794,7 @@ ctx.ui.setWidget("my-widget", (_tui, theme) => {
 ctx.ui.setWidget("my-widget", undefined);
 ```
 
-**Examples:** [plan-mode.ts](../examples/extensions/plan-mode.ts)
+**Examples:** [plan-mode/index.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/plan-mode/index.ts)
 
 ### Pattern 6: Custom Footer
 
@@ -816,7 +816,7 @@ ctx.ui.setFooter(undefined); // restore default
 
 Token stats available via `ctx.sessionManager.getBranch()` and `ctx.model`.
 
-**Examples:** [custom-footer.ts](../examples/extensions/custom-footer.ts)
+**Examples:** [custom-footer.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/custom-footer.ts)
 
 ### Pattern 7: Custom Editor (vim mode, etc.)
 
@@ -892,7 +892,7 @@ export default function (pi: ExtensionAPI) {
 - **Factory pattern**: `setEditorComponent` receives a factory function that gets `tui`, `theme`, and `keybindings`
 - **Pass `undefined`** to restore the default editor: `ctx.ui.setEditorComponent(undefined)`
 
-**Examples:** [modal-editor.ts](../examples/extensions/modal-editor.ts)
+**Examples:** [modal-editor.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/modal-editor.ts)
 
 ## Key Rules
 
@@ -908,12 +908,12 @@ export default function (pi: ExtensionAPI) {
 
 ## Examples
 
-- **Selection UI**: [examples/extensions/preset.ts](../examples/extensions/preset.ts) - SelectList with DynamicBorder framing
-- **Async with cancel**: [examples/extensions/qna.ts](../examples/extensions/qna.ts) - BorderedLoader for LLM calls
-- **Settings toggles**: [examples/extensions/tools.ts](../examples/extensions/tools.ts) - SettingsList for tool enable/disable
-- **Status indicators**: [examples/extensions/plan-mode.ts](../examples/extensions/plan-mode.ts) - setStatus and setWidget
-- **Working indicator**: [examples/extensions/working-indicator.ts](../examples/extensions/working-indicator.ts) - setWorkingIndicator
-- **Custom footer**: [examples/extensions/custom-footer.ts](../examples/extensions/custom-footer.ts) - setFooter with stats
-- **Custom editor**: [examples/extensions/modal-editor.ts](../examples/extensions/modal-editor.ts) - Vim-like modal editing
-- **Snake game**: [examples/extensions/snake.ts](../examples/extensions/snake.ts) - Full game with keyboard input, game loop
-- **Custom tool rendering**: [examples/extensions/todo.ts](../examples/extensions/todo.ts) - renderCall and renderResult
+- **Selection UI**: [examples/extensions/preset.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/preset.ts) - SelectList with DynamicBorder framing
+- **Async with cancel**: [examples/extensions/qna.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/qna.ts) - BorderedLoader for LLM calls
+- **Settings toggles**: [examples/extensions/tools.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/tools.ts) - SettingsList for tool enable/disable
+- **Status indicators**: [examples/extensions/plan-mode/index.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/plan-mode/index.ts) - setStatus and setWidget
+- **Working indicator**: [examples/extensions/working-indicator.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/working-indicator.ts) - setWorkingIndicator
+- **Custom footer**: [examples/extensions/custom-footer.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/custom-footer.ts) - setFooter with stats
+- **Custom editor**: [examples/extensions/modal-editor.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/modal-editor.ts) - Vim-like modal editing
+- **Snake game**: [examples/extensions/snake.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/snake.ts) - Full game with keyboard input, game loop
+- **Custom tool rendering**: [examples/extensions/todo.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/todo.ts) - renderCall and renderResult

package/docs/usage.md

@@ -4,7 +4,7 @@ This page collects day-to-day usage details that do not fit on the quickstart pa
 
 ## Interactive Mode
 
-<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600" /></p>
 
 The interface has four main areas: