@bastani/atomic 0.8.13-0 → 0.8.14-0

package/docs/docs.json

@@ -1,152 +1,107 @@
 {
-  "navigation": [
-    {
-      "title": "Start here",
-      "items": [
-        {
-          "title": "Overview",
-          "path": "index.md"
-        },
-        {
-          "title": "Quickstart",
-          "path": "quickstart.md"
-        },
-        {
-          "title": "Using Atomic",
-          "path": "usage.md"
-        },
-        {
-          "title": "Providers",
-          "path": "providers.md"
-        },
-        {
-          "title": "Settings",
-          "path": "settings.md"
-        },
-        {
-          "title": "Keybindings",
-          "path": "keybindings.md"
-        },
-        {
-          "title": "Sessions",
-          "path": "sessions.md"
-        },
-        {
-          "title": "Compaction",
-          "path": "compaction.md"
-        }
-      ]
-    },
-    {
-      "title": "Customization",
-      "items": [
-        {
-          "title": "Extensions",
-          "path": "extensions.md"
-        },
-        {
-          "title": "Skills",
-          "path": "skills.md"
-        },
-        {
-          "title": "Atomic Workflows",
-          "path": "workflows.md"
-        },
-        {
-          "title": "Prompt Templates",
-          "path": "prompt-templates.md"
-        },
-        {
-          "title": "Themes",
-          "path": "themes.md"
-        },
-        {
-          "title": "Atomic Packages",
-          "path": "packages.md"
-        },
-        {
-          "title": "Custom Models",
-          "path": "models.md"
-        },
-        {
-          "title": "Custom Providers",
-          "path": "custom-provider.md"
-        }
-      ]
-    },
-    {
-      "title": "Reference",
-      "items": [
-        {
-          "title": "Session Format",
-          "path": "session-format.md"
-        }
-      ]
-    },
-    {
-      "title": "Programmatic Usage",
-      "items": [
-        {
-          "title": "SDK",
-          "path": "sdk.md"
-        },
-        {
-          "title": "RPC Mode",
-          "path": "rpc.md"
-        },
-        {
-          "title": "JSON Event Stream Mode",
-          "path": "json.md"
-        },
-        {
-          "title": "TUI Components",
-          "path": "tui.md"
-        }
-      ]
-    },
-    {
-      "title": "Platform Setup",
-      "items": [
-        {
-          "title": "Windows",
-          "path": "windows.md"
-        },
-        {
-          "title": "Termux on Android",
-          "path": "termux.md"
-        },
-        {
-          "title": "tmux",
-          "path": "tmux.md"
-        },
-        {
-          "title": "Terminal Setup",
-          "path": "terminal-setup.md"
-        },
-        {
-          "title": "Shell Aliases",
-          "path": "shell-aliases.md"
-        }
-      ]
-    },
-    {
-      "title": "Development",
-      "items": [
-        {
-          "title": "Development",
-          "path": "development.md"
-        }
-      ]
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Atomic",
+  "logo": "/logo.svg",
+  "favicon": "/favicon.svg",
+  "colors": {
+    "primary": "#2563EB",
+    "light": "#60A5FA",
+    "dark": "#1D4ED8"
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "Start here",
+        "pages": [
+          "index",
+          "quickstart",
+          "usage",
+          "providers",
+          "settings",
+          "keybindings",
+          "sessions",
+          "compaction"
+        ]
+      },
+      {
+        "group": "Customization",
+        "pages": [
+          "extensions",
+          "skills",
+          "workflows",
+          "prompt-templates",
+          "themes",
+          "packages",
+          "models",
+          "custom-provider"
+        ]
+      },
+      {
+        "group": "Reference",
+        "pages": [
+          "session-format"
+        ]
+      },
+      {
+        "group": "Programmatic Usage",
+        "pages": [
+          "sdk",
+          "rpc",
+          "json",
+          "tui"
+        ]
+      },
+      {
+        "group": "Platform Setup",
+        "pages": [
+          "windows",
+          "termux",
+          "tmux",
+          "terminal-setup",
+          "shell-aliases"
+        ]
+      },
+      {
+        "group": "Development",
+        "pages": [
+          "development"
+        ]
+      },
+      {
+        "group": "Changelog",
+        "pages": [
+          "changelog"
+        ]
+      }
+    ]
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/flora131/atomic"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Get started",
+      "href": "/quickstart"
+    }
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/flora131/atomic"
     }
-  ],
+  },
   "redirects": [
     {
-      "from": "session.md",
-      "to": "session-format.md"
+      "source": "/session",
+      "destination": "/session-format"
     },
     {
-      "from": "tree.md",
-      "to": "sessions.md"
+      "source": "/tree",
+      "destination": "/sessions"
     }
   ]
 }

package/docs/extensions.md

@@ -26,7 +26,7 @@ Extensions are TypeScript modules that extend Atomic's behavior. They can subscr
 - External integrations (file watchers, webhooks, CI triggers)
 - Games while you wait (see `snake.ts` example)
 
-See [examples/extensions/](../examples/extensions/) for working implementations.
+See [examples/extensions/](https://github.com/flora131/atomic/tree/main/packages/coding-agent/examples/extensions) for working implementations.
 
 ## Table of Contents
 
@@ -144,9 +144,22 @@ To share extensions via npm or git as Atomic packages, see [packages.md](package
 | `@earendil-works/pi-ai` | AI utilities (`StringEnum` for Google-compatible enums) |
 | `@earendil-works/pi-tui` | TUI components for custom rendering |
 
-npm dependencies work too. Add a `package.json` next to your extension (or in a parent directory), run `npm install`, and imports from `node_modules/` are resolved automatically.
+npm dependencies work too. Add a `package.json` next to your extension (or in a parent directory), then install dependencies with npm, Bun, or pnpm:
 
-For distributed Atomic packages installed with `atomic install` (npm or git), runtime deps must be in `dependencies`. Package installation uses production installs (`npm install --omit=dev`) by default, so `devDependencies` are not available at runtime; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers.
+```bash
+# npm
+npm install
+
+# Bun
+bun install
+
+# pnpm
+pnpm install
+```
+
+Imports from `node_modules/` are resolved automatically.
+
+For distributed Atomic packages installed with `atomic install` (npm or git), runtime deps must be in `dependencies`. Package installation uses production dependency installs by default, so `devDependencies` are not available at runtime; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers.
 
 Node.js built-ins (`node:fs`, `node:path`, etc.) are also available.
 
@@ -242,7 +255,7 @@ This pattern makes the fetched models available during normal startup and to `at
 └── my-extension/
     ├── package.json    # Declares dependencies and entry points
     ├── package-lock.json
-    ├── node_modules/   # After npm install
+    ├── node_modules/   # After dependency install
     └── src/
         └── index.ts
 ```
@@ -261,7 +274,7 @@ This pattern makes the fetched models available during normal startup and to `at
 }
 ```
 
-The manifest key is the app name from `package.json` (`atomic` here); the legacy `pi` key is still accepted as a compatibility shim. Run `npm install` in the extension directory, then imports from `node_modules/` work automatically.
+The manifest key is the app name from `package.json` (`atomic` here); the legacy `pi` key is still accepted as a compatibility shim. Run `npm install`, `bun install`, or `pnpm install` in the extension directory, then imports from `node_modules/` work automatically.
 
 ## Events
 
@@ -847,7 +860,7 @@ pi.on("input", async (event, ctx) => {
 - `transform` - modify text/images, then continue to expansion
 - `handled` - skip agent entirely (first handler to return this wins)
 
-Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts).
+Transforms chain across handlers. See [input-transform.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/input-transform.ts).
 
 ## ExtensionContext
 
@@ -1226,7 +1239,7 @@ Use `promptSnippet` to opt a custom tool into a one-line entry in `Available too
 
 **Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
 
-See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
+See [dynamic-tools.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/dynamic-tools.ts) for a full example.
 
 ```typescript
 import { Type } from "typebox";
@@ -1314,7 +1327,7 @@ pi.sendUserMessage("And then summarize", { deliverAs: "followUp" });
 
 When not streaming, the message is sent immediately and triggers a new turn. When streaming without `deliverAs`, throws an error.
 
-See [send-user-message.ts](../examples/extensions/send-user-message.ts) for a complete example.
+See [send-user-message.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/send-user-message.ts) for a complete example.
 
 ### pi.appendEntry(customType, data?)
 
@@ -1760,7 +1773,7 @@ pi.registerTool({
 
 **Signaling errors:** To mark a tool execution as failed (sets `isError: true` on the result and reports it to the LLM), throw an error from `execute`. Returning a value never sets the error flag regardless of what properties you include in the return object.
 
-**Early termination:** Return `terminate: true` from `execute()` to hint that the automatic follow-up LLM call should be skipped after the current tool batch. This only takes effect when every finalized tool result in that batch is terminating. See [examples/extensions/structured-output.ts](../examples/extensions/structured-output.ts) for a minimal example where the agent ends on a final structured-output tool call.
+**Early termination:** Return `terminate: true` from `execute()` to hint that the automatic follow-up LLM call should be skipped after the current tool batch. This only takes effect when every finalized tool result in that batch is terminating. See [examples/extensions/structured-output.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/structured-output.ts) for a minimal example where the agent ends on a final structured-output tool call.
 
 ```typescript
 // Correct: throw to signal an error
@@ -1836,7 +1849,7 @@ Alternatively, use `--no-builtin-tools` to start without any built-in tools whil
 atomic --no-builtin-tools -e ./my-extension.ts
 ```
 
-See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.ts) for a complete example that overrides `read` with logging and access control.
+See [examples/extensions/tool-override.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/tool-override.ts) for a complete example that overrides `read` with logging and access control.
 
 **Rendering:** Built-in renderer inheritance is resolved per slot. Execution override and rendering override are independent. If your override omits `renderCall`, the built-in `renderCall` is used. If your override omits `renderResult`, the built-in `renderResult` is used. If your override omits both, the built-in renderer is used automatically (syntax highlighting, diffs, etc.). This lets you wrap built-in tools for logging or access control without reimplementing the UI.
 
@@ -1900,7 +1913,7 @@ const bashTool = createBashTool(cwd, {
 });
 ```
 
-See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
+See [examples/extensions/ssh.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
 
 ### Output Truncation
 
@@ -1952,7 +1965,7 @@ async execute(toolCallId, params, signal, onUpdate, ctx) {
 - Always inform the LLM when output is truncated and where to find the full version
 - Document the truncation limits in your tool's description
 
-See [examples/extensions/truncated-tool.ts](../examples/extensions/truncated-tool.ts) for a complete example wrapping `rg` (ripgrep) with proper truncation.
+See [examples/extensions/truncated-tool.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/truncated-tool.ts) for a complete example wrapping `rg` (ripgrep) with proper truncation.
 
 ### Multiple Tools
 
@@ -2179,7 +2192,7 @@ if (confirmed) {
 }
 ```
 
-See [examples/extensions/timed-confirm.ts](../examples/extensions/timed-confirm.ts) for complete examples.
+See [examples/extensions/timed-confirm.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/timed-confirm.ts) for complete examples.
 
 ### Widgets, Status, and Footer
 
@@ -2322,7 +2335,7 @@ pi.on("session_start", (_event, ctx) => {
 });
 ```
 
-See [github-issue-autocomplete.ts](../examples/extensions/github-issue-autocomplete.ts) for a complete example that preloads the latest open GitHub issues with `gh issue list` and filters them locally for fast `#...` completion. It requires GitHub CLI (`gh`) and a GitHub repository checkout.
+See [github-issue-autocomplete.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/github-issue-autocomplete.ts) for a complete example that preloads the latest open GitHub issues with `gh issue list` and filters them locally for fast `#...` completion. It requires GitHub CLI (`gh`) and a GitHub repository checkout.
 
 ### Custom Components
 
@@ -2380,7 +2393,7 @@ const result = await ctx.ui.custom<string | null>(
 );
 ```
 
-See [tui.md](tui.md) for the full `OverlayOptions` API and [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for examples.
+See [tui.md](tui.md) for the full `OverlayOptions` API and [overlay-qa-tests.ts](https://github.com/flora131/atomic/blob/main/packages/coding-agent/examples/extensions/overlay-qa-tests.ts) for examples.
 
 ### Custom Editor
 
@@ -2516,7 +2529,7 @@ In non-interactive modes, check `ctx.hasUI` before using UI methods.
 
 ## Examples Reference
 
-All examples in [examples/extensions/](../examples/extensions/).
+All examples in [examples/extensions/](https://github.com/flora131/atomic/tree/main/packages/coding-agent/examples/extensions).
 
 | Example | Description | Key APIs |
 |---------|-------------|----------|

package/docs/favicon.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-labelledby="title desc">
+  <title id="title">Atomic favicon</title>
+  <desc id="desc">An upside-down block A in Atomic's Catppuccin Mocha terminal style.</desc>
+  <rect width="32" height="32" rx="7" fill="#1e1e2e" />
+  <path d="M1 8.5A7.5 7.5 0 0 1 8.5 1H23.5A7.5 7.5 0 0 1 31 8.5V23.5A7.5 7.5 0 0 1 23.5 31H8.5A7.5 7.5 0 0 1 1 23.5Z" fill="none" stroke="#313244" stroke-width="2" />
+
+  <!-- TUI-style drop shadow, matching the banner's dim offset cells. -->
+  <g fill="#45475a" opacity="0.72" shape-rendering="crispEdges">
+    <path d="M6 7H12L18 26H13Z" />
+    <path d="M22 7H28L21 26H16Z" />
+    <path d="M9 15H25L24 19H10Z" />
+    <path d="M13 24H21L19 28H15Z" />
+  </g>
+
+  <!-- Upside-down Atomic A / forall mark, adapted from the terminal banner. -->
+  <g fill="#89b4fa" shape-rendering="crispEdges">
+    <path d="M5 6H11L17 25H12Z" />
+    <path d="M21 6H27L20 25H15Z" />
+    <path d="M8 14H24L23 18H9Z" />
+    <path d="M12 23H20L18 27H14Z" />
+  </g>
+
+  <!-- Subtle block highlight for the same solid-cell texture as the TUI logo. -->
+  <g fill="#cdd6f4" opacity="0.18" shape-rendering="crispEdges">
+    <rect x="7" y="7" width="4" height="2" />
+    <rect x="21" y="7" width="4" height="2" />
+    <rect x="9" y="14" width="6" height="1" />
+  </g>
+</svg>

package/docs/index.md

@@ -4,12 +4,21 @@ Atomic is a minimal terminal coding harness. It is designed to stay small at the
 
 ## Quick start
 
-Install Atomic from npm:
+Install Atomic with npm, Bun, or pnpm:
 
 ```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.
+
 Or download an `atomic-*` archive from the Atomic GitHub Release for your platform.
 
 Then run it in a project directory:

package/docs/logo.svg

@@ -0,0 +1,59 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="648" height="160" viewBox="0 0 648 160" role="img" aria-labelledby="title desc">
+  <title id="title">Atomic</title>
+  <desc id="desc">Atomic wordmark with the blocky terminal favicon mark shown to the left of the title.</desc>
+  <defs>
+    <style>
+      .tile-bg { fill: #ffffff; }
+      .tile-border { stroke: #e5e7eb; }
+      .cell-shadow { fill: #cbd5e1; opacity: 0.42; }
+      .atomic-mark { fill: #2563eb; }
+      .cell-highlight { fill: #111827; opacity: 0.1; }
+      .wordmark { fill: #111827; }
+
+      @media (prefers-color-scheme: dark) {
+        .tile-bg { fill: #1e1e2e; }
+        .tile-border { stroke: #313244; }
+        .cell-shadow { fill: #45475a; opacity: 0.72; }
+        .atomic-mark { fill: #89b4fa; }
+        .cell-highlight { fill: #cdd6f4; opacity: 0.18; }
+        .wordmark { fill: #cdd6f4; }
+      }
+    </style>
+    <clipPath id="tile-clip">
+      <rect x="0" y="0" width="160" height="160" rx="35" />
+    </clipPath>
+  </defs>
+
+  <g clip-path="url(#tile-clip)">
+    <g transform="scale(5)">
+      <rect class="tile-bg" width="32" height="32" />
+      <path class="tile-border" d="M1 8.5A7.5 7.5 0 0 1 8.5 1H23.5A7.5 7.5 0 0 1 31 8.5V23.5A7.5 7.5 0 0 1 23.5 31H8.5A7.5 7.5 0 0 1 1 23.5Z" fill="none" stroke-width="2" />
+
+      <!-- TUI-style dim cell shadow, offset one block down and right. -->
+      <g class="cell-shadow" shape-rendering="crispEdges">
+        <path d="M6 7H12L18 26H13Z" />
+        <path d="M22 7H28L21 26H16Z" />
+        <path d="M9 15H25L24 19H10Z" />
+        <path d="M13 24H21L19 28H15Z" />
+        <rect x="14" y="22" width="7" height="2" />
+      </g>
+
+      <!-- Upside-down Atomic A / forall mark, matched to the favicon's Catppuccin blue. -->
+      <g class="atomic-mark" shape-rendering="crispEdges">
+        <path d="M5 6H11L17 25H12Z" />
+        <path d="M21 6H27L20 25H15Z" />
+        <path d="M8 14H24L23 18H9Z" />
+        <path d="M12 23H20L18 27H14Z" />
+      </g>
+
+      <!-- Solid-cell highlight to preserve the low-resolution terminal texture. -->
+      <g class="cell-highlight" shape-rendering="crispEdges">
+        <rect x="7" y="7" width="4" height="2" />
+        <rect x="21" y="7" width="4" height="2" />
+        <rect x="9" y="14" width="6" height="1" />
+      </g>
+    </g>
+  </g>
+
+  <text class="wordmark" x="208" y="110" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="96" font-weight="700" letter-spacing="-0.01em">Atomic</text>
+</svg>

package/docs/packages.md

@@ -64,7 +64,7 @@ npm:pkg
 ```
 
 - Versioned specs are pinned and skipped by package updates (`atomic update`, `atomic update --extensions`).
-- Global installs use `npm install -g`.
+- Global installs use the configured npm-compatible package-manager command (npm by default).
 - Project installs go under `.atomic/npm/`.
 - Set `npmCommand` in `settings.json` to pin npm package lookup and install operations to a specific wrapper command such as `mise` or `asdf`.
 
@@ -92,7 +92,7 @@ ssh://git@github.com/user/repo@v1
 - For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
 - Refs pin the package and skip package updates (`atomic update`, `atomic update --extensions`).
 - Cloned to `~/.atomic/agent/git/<host>/<path>` (global) or `.atomic/git/<host>/<path>` (project).
-- Runs `npm install` after clone or pull if `package.json` exists.
+- Runs the configured npm-compatible install command after clone or pull if `package.json` exists.
 
 **SSH examples:**
 ```bash
@@ -170,7 +170,7 @@ If no app manifest (`atomic`, or legacy `pi`) is present, Atomic auto-discovers
 
 ## Dependencies
 
-Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When Atomic installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When Atomic installs a package from npm or git, it runs the configured npm-compatible install command, so those dependencies are installed automatically.
 
 Atomic bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@bastani/atomic`, `@earendil-works/pi-tui`, `typebox`.
 

package/docs/providers.md

@@ -231,7 +231,7 @@ Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
 
 **Via models.json:** Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See [models.md](models.md).
 
-**Via extensions:** For providers that need custom API implementations or OAuth flows, create an extension. See [custom-provider.md](custom-provider.md) and [examples/extensions/custom-provider-gitlab-duo](../examples/extensions/custom-provider-gitlab-duo/).
+**Via extensions:** For providers that need custom API implementations or OAuth flows, create an extension. See [custom-provider.md](custom-provider.md) and [examples/extensions/custom-provider-gitlab-duo](https://github.com/flora131/atomic/tree/main/packages/coding-agent/examples/extensions/custom-provider-gitlab-duo).
 
 ## Resolution Order