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

package/docs/packages/authoring.md

@@ -0,0 +1,88 @@
+---
+title: Creating packages
+description: Create an Atomic package, lay out its structure, and declare dependencies.
+---
+
+# Creating packages
+
+## Creating an Atomic Package
+
+Add an app manifest to `package.json` or use conventional directories. The manifest key is the configured app name (`atomic` here, from `atomicConfig.name`; legacy `piConfig.name` is also read). The legacy `pi` key remains supported as a backwards-compatible shim. Include the `atomic-package` keyword for discoverability.
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["atomic-package"],
+  "atomic": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"],
+    "workflows": ["./workflows"]
+  }
+}
+```
+
+Paths are relative to the package root. Arrays support glob patterns and `!exclusions`.
+
+### Gallery Metadata
+
+The package gallery currently recognizes legacy `pi-package` metadata, while new Atomic packages should also include `atomic-package`. Add `video` or `image` fields to show a preview:
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["atomic-package", "pi-package"],
+  "atomic": {
+    "extensions": ["./extensions"],
+    "video": "https://example.com/demo.mp4",
+    "image": "https://example.com/screenshot.png"
+  }
+}
+```
+
+- **video**: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
+- **image**: PNG, JPEG, GIF, or WebP. Displayed as a static preview.
+
+If both are set, video takes precedence.
+
+## Package Structure
+
+### Convention Directories
+
+If no app manifest (`atomic`, or legacy `pi`) is present, Atomic auto-discovers resources from these directories:
+
+- `extensions/` loads `.ts` and `.js` files
+- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
+- `prompts/` loads `.md` files
+- `themes/` loads `.json` files
+- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export the definition returned by `workflow({ ... })`. TypeScript resolves the published `@bastani/atomic/workflows` specifier through the `@bastani/atomic` package. Atomic resolves that workflow specifier and the supported TypeBox root, `typebox/compile`, `typebox/value`, and legacy `@sinclair/typebox` aliases to in-memory host modules when it loads the workflow at runtime. See [Programmatic usage](/workflows/api-reference#programmatic-usage).
+
+When a package manifest exists, declared resource arrays normally define what loads. Workflows are the exception: if `atomic.workflows` / legacy `pi.workflows` is omitted, Atomic still checks conventional `workflows/` and `workflow/` directories.
+
+## Dependencies
+
+Third-party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, themes, or workflows 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: `@bastani/pi-ai`, `@earendil-works/pi-agent-core`, `@bastani/atomic`, `@earendil-works/pi-tui`, `typebox`.
+
+Workflow packages import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export definitions returned by `workflow({ ... })`. List `@bastani/atomic` and `typebox` in `peerDependencies` so package consumers receive the workflow SDK and schema library.
+
+Package-authored workflows should follow the same [guiding principles](/workflows/authoring#guiding-principles) as project workflows.
+
+Other Atomic packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Atomic loads packages with separate module roots, so separate installs do not collide or share modules.
+
+Example:
+
+```json
+{
+  "dependencies": {
+    "shitty-extensions": "^1.0.1"
+  },
+  "bundledDependencies": ["shitty-extensions"],
+  "atomic": {
+    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
+    "skills": ["skills", "node_modules/shitty-extensions/skills"]
+  }
+}
+```

package/docs/packages/reference.md

@@ -0,0 +1,43 @@
+---
+title: Package reference
+description: Package filtering, scope, and deduplication contracts.
+---
+
+# Package reference
+
+## Package Filtering
+
+Filter what a package loads using the object form in settings:
+
+```json
+{
+  "packages": [
+    "npm:simple-pkg",
+    {
+      "source": "npm:my-package",
+      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
+      "skills": [],
+      "prompts": ["prompts/review.md"],
+      "themes": ["+themes/legacy.json"],
+      "workflows": ["workflows/*.ts"]
+    }
+  ]
+}
+```
+
+`+path` and `-path` are exact paths relative to the package root.
+
+- Omit a key to load all of that type.
+- Use `[]` to load none of that type.
+- `!pattern` excludes matches.
+- `+path` force-includes an exact path.
+- `-path` force-excludes an exact path.
+- Filters layer on top of the manifest. They narrow down what is already allowed.
+
+## Scope and Deduplication
+
+Packages can appear in both global and project settings. The project entry normally wins. A project entry with `autoload: false` instead acts as a delta over the global entry: it starts with no newly auto-discovered resources while explicit include/exclude patterns adjust the inherited package resources. Identity is determined by:
+
+- npm: package name
+- git: repository URL without ref
+- local: resolved absolute path

package/docs/packages.md

@@ -1,9 +1,21 @@
+---
+title: "Atomic packages"
+description: "Install, manage, and share Atomic packages that bundle extensions, skills, prompt templates, themes, and workflows."
+---
+
 > Atomic can help you create packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
 
 # Atomic Packages
 
 Atomic packages bundle extensions, skills, prompt templates, themes, and workflow definitions so you can share them through npm or git. Declare resources in `package.json` under the `atomic` key, or use conventional directories.
 
+## Where to go next
+
+Atomic packages bundle and distribute extensions, skills, prompts, themes, and workflows. Read this page to install and manage them, then continue:
+
+- [Creating packages](/packages/authoring) — create a package, lay out its structure, and declare dependencies.
+- [Package reference](/packages/reference) — filtering, scope, and deduplication contracts.
+
 ## Table of Contents
 
 - [Atomic Packages](#atomic-packages)
@@ -13,14 +25,14 @@ Atomic packages bundle extensions, skills, prompt templates, themes, and workflo
     - [npm](#npm)
     - [git](#git)
     - [Local Paths](#local-paths)
-  - [Creating an Atomic Package](#creating-an-atomic-package)
-    - [Gallery Metadata](#gallery-metadata)
-  - [Package Structure](#package-structure)
-    - [Convention Directories](#convention-directories)
-  - [Dependencies](#dependencies)
-  - [Package Filtering](#package-filtering)
+  - [Creating an Atomic Package](/packages/authoring#creating-an-atomic-package)
+    - [Gallery Metadata](/packages/authoring#gallery-metadata)
+  - [Package Structure](/packages/authoring#package-structure)
+    - [Convention Directories](/packages/authoring#convention-directories)
+  - [Dependencies](/packages/authoring#dependencies)
+  - [Package Filtering](/packages/reference#package-filtering)
   - [Enable and Disable Resources](#enable-and-disable-resources)
-  - [Scope and Deduplication](#scope-and-deduplication)
+  - [Scope and Deduplication](/packages/reference#scope-and-deduplication)
 
 ## Install and Manage
 
@@ -45,7 +57,7 @@ atomic update npm:@foo/bar      # update one package
 atomic update --extension npm:@foo/bar
 ```
 
-These commands manage Atomic packages and `atomic update` can update the Atomic CLI installation. To uninstall Atomic itself, see [Quickstart](/quickstart#uninstall).
+These commands manage Atomic packages and `atomic update` can update the Atomic CLI installation. To uninstall Atomic itself, see [Quickstart](/getting-started/installation#uninstall).
 
 Self-update resolves an exact advertised package/version target and installs that pinned spec, so the update cannot drift to a newer registry release during installation. Any release note supplied by the update service is shown before installation. Atomic only updates installations it can verify are writable and managed by the detected global package manager; otherwise it prints a manual command. On Windows, loaded native dependencies are temporarily quarantined during replacement and stale quarantine directories are cleaned on later update attempts.
 
@@ -128,114 +140,27 @@ Local paths point to files or directories on disk and are added to settings with
 
 ## Creating an Atomic Package
 
-Add an app manifest to `package.json` or use conventional directories. The manifest key is the configured app name (`atomic` here, from `atomicConfig.name`; legacy `piConfig.name` is also read). The legacy `pi` key remains supported as a backwards-compatible shim. Include the `atomic-package` keyword for discoverability.
-
-```json
-{
-  "name": "my-package",
-  "keywords": ["atomic-package"],
-  "atomic": {
-    "extensions": ["./extensions"],
-    "skills": ["./skills"],
-    "prompts": ["./prompts"],
-    "themes": ["./themes"],
-    "workflows": ["./workflows"]
-  }
-}
-```
-
-Paths are relative to the package root. Arrays support glob patterns and `!exclusions`.
+Moved to [Creating packages](/packages/authoring#creating-an-atomic-package).
 
 ### Gallery Metadata
 
-The package gallery currently recognizes legacy `pi-package` metadata, while new Atomic packages should also include `atomic-package`. Add `video` or `image` fields to show a preview:
-
-```json
-{
-  "name": "my-package",
-  "keywords": ["atomic-package", "pi-package"],
-  "atomic": {
-    "extensions": ["./extensions"],
-    "video": "https://example.com/demo.mp4",
-    "image": "https://example.com/screenshot.png"
-  }
-}
-```
-
-- **video**: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
-- **image**: PNG, JPEG, GIF, or WebP. Displayed as a static preview.
-
-If both are set, video takes precedence.
+Moved to [Creating packages](/packages/authoring#gallery-metadata).
 
 ## Package Structure
 
-### Convention Directories
+Moved to [Creating packages](/packages/authoring#package-structure).
 
-If no app manifest (`atomic`, or legacy `pi`) is present, Atomic auto-discovers resources from these directories:
-
-- `extensions/` loads `.ts` and `.js` files
-- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
-- `prompts/` loads `.md` files
-- `themes/` loads `.json` files
-- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export the definition returned by `workflow({ ... })`. TypeScript resolves the published `@bastani/atomic/workflows` specifier through the `@bastani/atomic` package. Atomic resolves that workflow specifier and the supported TypeBox root, `typebox/compile`, `typebox/value`, and legacy `@sinclair/typebox` aliases to in-memory host modules when it loads the workflow at runtime. See [Programmatic usage](/workflows/api-reference#programmatic-usage).
+### Convention Directories
 
-When a package manifest exists, declared resource arrays normally define what loads. Workflows are the exception: if `atomic.workflows` / legacy `pi.workflows` is omitted, Atomic still checks conventional `workflows/` and `workflow/` directories.
+Moved to [Creating packages](/packages/authoring#convention-directories).
 
 ## Dependencies
 
-Third-party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, themes, or workflows 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: `@bastani/pi-ai`, `@earendil-works/pi-agent-core`, `@bastani/atomic`, `@earendil-works/pi-tui`, `typebox`.
-
-Workflow packages import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export definitions returned by `workflow({ ... })`. List `@bastani/atomic` and `typebox` in `peerDependencies` so package consumers receive the workflow SDK and schema library.
-
-Package-authored workflows should follow the same [guiding principles](/workflows/authoring#guiding-principles) as project workflows.
-
-Other Atomic packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Atomic loads packages with separate module roots, so separate installs do not collide or share modules.
-
-Example:
-
-```json
-{
-  "dependencies": {
-    "shitty-extensions": "^1.0.1"
-  },
-  "bundledDependencies": ["shitty-extensions"],
-  "atomic": {
-    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
-    "skills": ["skills", "node_modules/shitty-extensions/skills"]
-  }
-}
-```
+Moved to [Creating packages](/packages/authoring#dependencies).
 
 ## Package Filtering
 
-Filter what a package loads using the object form in settings:
-
-```json
-{
-  "packages": [
-    "npm:simple-pkg",
-    {
-      "source": "npm:my-package",
-      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
-      "skills": [],
-      "prompts": ["prompts/review.md"],
-      "themes": ["+themes/legacy.json"],
-      "workflows": ["workflows/*.ts"]
-    }
-  ]
-}
-```
-
-`+path` and `-path` are exact paths relative to the package root.
-
-- Omit a key to load all of that type.
-- Use `[]` to load none of that type.
-- `!pattern` excludes matches.
-- `+path` force-includes an exact path.
-- `-path` force-excludes an exact path.
-- Filters layer on top of the manifest. They narrow down what is already allowed.
+Moved to [Package reference](/packages/reference#package-filtering).
 
 ## Enable and Disable Resources
 
@@ -243,8 +168,4 @@ Use `atomic config` to enable or disable extensions, skills, prompt templates, a
 
 ## Scope and Deduplication
 
-Packages can appear in both global and project settings. The project entry normally wins. A project entry with `autoload: false` instead acts as a delta over the global entry: it starts with no newly auto-discovered resources while explicit include/exclude patterns adjust the inherited package resources. Identity is determined by:
-
-- npm: package name
-- git: repository URL without ref
-- local: resolved absolute path
+Moved to [Package reference](/packages/reference#scope-and-deduplication).

package/docs/programmatic.md

@@ -0,0 +1,29 @@
+---
+title: Programmatic use
+description: Choose between JSON event stream mode, RPC mode, the SDK, and the TUI component APIs, then follow one minimal integration.
+---
+
+# Programmatic use
+
+Atomic exposes three integration modes plus a component API for interactive extension interfaces. Pick one mode, complete its minimal example, then continue to its reference.
+
+## Choose a mode
+
+| You want | Use | Start at |
+| --- | --- | --- |
+| A one-shot run whose output you parse as structured events | [JSON event stream mode](/json) | `atomic --mode json` |
+| A long-lived process you drive with commands and read events from | [RPC mode](/rpc) | `atomic --mode rpc` |
+| Atomic embedded inside a Node.js application, with its resources and lifecycle in-process | [SDK](/sdk) | `@bastani/atomic` |
+
+JSON mode is the smallest surface: one process, one prompt, a stream of newline-delimited events, then exit. RPC mode keeps the process alive so you can send more input, interrupt, switch models, and answer tool permission prompts. The SDK gives you the same engine as a library, with programmatic control over extensions, skills, tools, and session storage.
+
+## Then continue to the contracts
+
+- [RPC protocol](/rpc/protocol) — every command, event, and type.
+- [RPC extension UI protocol](/rpc/extension-ui) — drive extension-rendered UI over RPC.
+- [RPC client examples](/rpc/examples) — additional client implementations.
+- [SDK API reference](/sdk/reference) — options, loaders, return values, run modes, and exports.
+
+## Build interactive extension interfaces
+
+[TUI components](/tui) covers writing a first component and the common interaction patterns; [TUI API reference](/tui/reference) holds the component, focusable, input, and rendering contracts.

package/docs/prompt-templates.md

@@ -4,6 +4,10 @@
 
 Prompt templates are Markdown snippets that expand into full prompts. Type `/name` in the editor to invoke a template, where `name` is the filename without `.md`.
 
+**Prerequisites:** Atomic installed and running in a project — see the [Quickstart](/quickstart). No code and no build step are required.
+
+**When to use this:** prompt templates are the lightest customization mechanism Atomic ships. Reach for them when you repeat the same instructions and want a slash command for them. If the agent should decide on its own when to load the instructions, use a [skill](/skills) instead; if you need to run code, use an [extension](/extensions).
+
 ## Locations
 
 Atomic loads prompt templates from:
@@ -94,3 +98,10 @@ Usage: `/component Button "onClick handler" "disabled support"`
 
 - Template discovery in `prompts/` is non-recursive.
 - If you want templates in subdirectories, add them explicitly via `prompts` settings or a package manifest.
+
+## Next steps
+
+- [Skills](/skills) — instructions the agent loads on its own when a task matches, instead of on an explicit slash command.
+- [Subagents](/subagents) — delegate a focused, bounded task to a child agent.
+- [Atomic packages](/packages) — bundle your prompt templates with skills, themes, and extensions and share them.
+- [Build with Atomic](/build) — compare every customization mechanism.

package/docs/providers/reference.md

@@ -0,0 +1,23 @@
+---
+title: Provider reference
+description: Provider stop reasons and credential resolution order.
+---
+
+# Provider reference
+
+## Stop Reasons
+
+Every provider reports why it ended a turn. Atomic stores one of `stop`, `length`, `toolUse`, `error`, or `aborted`; the provider's own string (`end_turn`, `MAX_TOKENS`, `tool_calls`, and so on) is mapped onto it.
+
+A terminal reason the mapping does not recognise is now reported as a **provider error** naming the raw value, instead of being reported as an ordinary successful stop. The turn fails visibly rather than looking like a model that chose to stop early, which matters most for a truncation or safety stop a new provider version invents. Reasons that already mapped to a successful stop are unchanged, and a provider that stops on its own safety or refusal signal still surfaces the raw reason in the error text (for example `Provider stopped with: SAFETY`).
+
+While a response is still streaming the partial message carries the reason `pending`. It is replaced by the terminal reason before the message is finished, so `pending` is not a state a completed turn can be left in: a stream that ends while still `pending` is a provider error. See [Custom providers](/custom-provider) for what this requires of a provider you implement yourself.
+
+## Resolution Order
+
+When resolving credentials for a provider:
+
+1. CLI `--api-key` flag
+2. `auth.json` entry (API key or OAuth token)
+3. Environment variable
+4. Custom provider keys from `models.json`

package/docs/providers.md

@@ -2,6 +2,10 @@
 
 Atomic supports subscription-based providers via OAuth and API-key providers via environment variables or the auth file. Built-in catalogs ship with Atomic; configured and native providers may refresh newer catalogs independently and cache them in `~/.atomic/agent/models-store.json` for offline use.
 
+## On this page and its reference
+
+This page is provider setup: subscriptions, API keys, cloud providers, and local llama.cpp. The exact contracts — provider stop reasons and credential resolution order — live in the [Provider reference](/providers/reference).
+
 ## Table of Contents
 
 - [Subscriptions](#subscriptions)
@@ -9,9 +13,9 @@ Atomic supports subscription-based providers via OAuth and API-key providers via
 - [API Keys](#api-keys)
 - [Auth File](#auth-file)
 - [Cloud Providers](#cloud-providers)
-- [llama.cpp](#llamacpp)
-- [Stop Reasons](#stop-reasons)
-- [Resolution Order](#resolution-order)
+- [llama.cpp](#llama-cpp)
+- [Stop Reasons](/providers/reference#stop-reasons)
+- [Resolution Order](/providers/reference#resolution-order)
 - [Custom Providers](#custom-providers)
 
 ## Subscriptions
@@ -142,7 +146,7 @@ After a successful API-key or OAuth login, Atomic persists the credential and im
 
 On a remote or headless machine, paste the authorization code or final redirect URL into the login prompt when the provider offers manual entry. A completed exchange must either return to the editor or show an error; it does not require deleting `~/.atomic`. Existing OAuth credentials use the same `auth.json` schema after the pi-ai model-runtime migration and are loaded in place.
 
-Remote pi.dev catalogs persist their ETag and are revalidated with `If-None-Match`; an empty `304` keeps the cached models and counts as a successful check. Atomic renders the cached snapshot immediately, preserves each provider's last usable catalog on refresh failure, and prefers newer bundled data over stale remote overlays. See [Custom Models](/models#catalog-freshness-and-precedence).
+Remote pi.dev catalogs persist their ETag and are revalidated with `If-None-Match`; an empty `304` keeps the cached models and counts as a successful check. Atomic renders the cached snapshot immediately, preserves each provider's last usable catalog on refresh failure, and prefers newer bundled data over stale remote overlays. See [Custom Models](/models/reference#catalog-freshness-and-precedence).
 
 | Provider                           | Environment Variable                                                      | `auth.json` key              |
 | ---------------------------------- | ------------------------------------------------------------------------- | ---------------------------- |
@@ -481,17 +485,8 @@ For router-mode discovery, load/unload management, and Hugging Face downloads wi
 
 ## Stop Reasons
 
-Every provider reports why it ended a turn. Atomic stores one of `stop`, `length`, `toolUse`, `error`, or `aborted`; the provider's own string (`end_turn`, `MAX_TOKENS`, `tool_calls`, and so on) is mapped onto it.
-
-A terminal reason the mapping does not recognise is now reported as a **provider error** naming the raw value, instead of being reported as an ordinary successful stop. The turn fails visibly rather than looking like a model that chose to stop early, which matters most for a truncation or safety stop a new provider version invents. Reasons that already mapped to a successful stop are unchanged, and a provider that stops on its own safety or refusal signal still surfaces the raw reason in the error text (for example `Provider stopped with: SAFETY`).
-
-While a response is still streaming the partial message carries the reason `pending`. It is replaced by the terminal reason before the message is finished, so `pending` is not a state a completed turn can be left in: a stream that ends while still `pending` is a provider error. See [Custom providers](/custom-provider) for what this requires of a provider you implement yourself.
+Moved to [Provider reference](/providers/reference#stop-reasons).
 
 ## Resolution Order
 
-When resolving credentials for a provider:
-
-1. CLI `--api-key` flag
-2. `auth.json` entry (API key or OAuth token)
-3. Environment variable
-4. Custom provider keys from `models.json`
+Moved to [Provider reference](/providers/reference#resolution-order).