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

package/docs/packages.md

@@ -178,6 +178,8 @@ Atomic bundles core packages for extensions and skills. If you import any of the
 
 Workflow packages should author workflow files with `import { defineWorkflow, Type } from "@bastani/workflows"` and export definitions produced by `defineWorkflow(...).compile()`. Do not use the removed `runWorkflow` object-form API, and do not hand-roll objects with `__piWorkflow: true`; discovery accepts only compiled definitions. `@bastani/workflows` is not a separate npm package: its types resolve through `@bastani/atomic`, so list `@bastani/atomic` and `typebox` in `peerDependencies` (the workflow SDK's emitted types reference `typebox`). A pure workflow-only package also adds the one-line ambient opt-in noted above; a package that imports `@bastani/atomic` elsewhere picks the types up automatically.
 
+Package-authored workflows should follow the same guiding principles as project workflows mentioned in docs/workflows.md.
+
 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:

package/docs/providers.md

@@ -57,6 +57,7 @@ atomic
 | OpenAI | `OPENAI_API_KEY` | `openai` |
 | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
 | Google Gemini | `GEMINI_API_KEY` | `google` |
+| Google Vertex AI | `GOOGLE_CLOUD_API_KEY` | `google-vertex` |
 | Mistral | `MISTRAL_API_KEY` | `mistral` |
 | Groq | `GROQ_API_KEY` | `groq` |
 | Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
@@ -74,12 +75,14 @@ atomic
 | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
 | MiniMax | `MINIMAX_API_KEY` | `minimax` |
 | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
+| Moonshot AI | `MOONSHOT_API_KEY` | `moonshotai` |
+| Moonshot AI (China) | `MOONSHOT_API_KEY` | `moonshotai-cn` |
 | Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
 | Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` | `xiaomi-token-plan-cn` |
 | Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
 | Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
 
-Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/env-api-keys.ts).
+Reference for environment variables and `auth.json` keys: `findEnvKeys()` / `getEnvApiKey()` in the installed `@earendil-works/pi-ai` dependency (`node_modules/@earendil-works/pi-ai/dist/env-api-keys.d.ts`). The private provider map those functions use is in `node_modules/@earendil-works/pi-ai/dist/env-api-keys.js`; Atomic does not include a separate `packages/ai` source directory in this monorepo.
 
 #### Auth File
 

package/docs/quickstart.md

@@ -4,23 +4,16 @@ 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.
+- **Node.js 20.6 or newer** — required when running Atomic from the published npm package. Check with `node --version`.
+- **Bun 1.3.14 or newer** — use Bun for installation, Atomic repository development, validation commands, and workflow-authoring examples.
 - **Model-provider access** — Use `/login` after startup. Supports provider subscriptions and APIs.
 
 ## Install
 
-Atomic is distributed through npm-compatible package managers. Choose one:
+Install the published package with Bun:
 
 ```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.
@@ -174,7 +167,7 @@ Atomic loads context files at startup. Add an `AGENTS.md` file to tell it how to
 ```markdown
 # Project Instructions
 
-- Run `npm run check` after code changes.
+- Run `bun run typecheck` after code changes.
 - Do not run production migrations locally.
 - Keep responses concise.
 ```
@@ -204,7 +197,7 @@ Images can be pasted with CTRL+V (ALT+V on Windows) or dragged into supported te
 In interactive mode:
 
 ```text
-!npm run lint
+!bun run lint
 ```
 
 The command output is sent to the model. Use `!!command` to run a command without adding its output to the model context.

package/docs/rpc.md

@@ -352,17 +352,12 @@ Response:
 
 #### compact
 
-Manually compact conversation context to reduce token usage.
+Run Atomic's default Verbatim Compaction to reduce token usage. This command has no prompt/config fields; send no custom instructions. Atomic asks the selected model for deletion targets using a fixed internal prompt, validates them, appends a `context_compaction` entry, and rebuilds active context with surviving entries/content blocks reused verbatim. This deletion-only Context Compaction approach is informed by Morph's article: <https://www.morphllm.com/context-compaction>.
 
 ```json
 {"type": "compact"}
 ```
 
-With custom instructions:
-```json
-{"type": "compact", "customInstructions": "Focus on code changes"}
-```
-
 Response:
 ```json
 {
@@ -370,10 +365,18 @@ Response:
   "command": "compact",
   "success": true,
   "data": {
-    "summary": "Summary of conversation...",
-    "firstKeptEntryId": "abc123",
-    "tokensBefore": 150000,
-    "details": {}
+    "promptVersion": 1,
+    "deletedTargets": [{ "kind": "entry", "entryId": "abc123" }],
+    "protectedEntryIds": ["user-task-entry"],
+    "stats": {
+      "objectsBefore": 20,
+      "objectsAfter": 19,
+      "objectsDeleted": 1,
+      "tokensBefore": 150000,
+      "tokensAfter": 120000,
+      "percentReduction": 20
+    },
+    "backupPath": "/path/to/session.jsonl.2026-06-06T00-00-00-000Z.compact.bak"
   }
 }
 ```
@@ -455,7 +458,7 @@ If output was truncated, includes `fullOutputPath`:
     "exitCode": 0,
     "cancelled": false,
     "truncated": true,
-    "fullOutputPath": "/tmp/pi-bash-abc123.log"
+    "fullOutputPath": "/tmp/atomic-bash-abc123.log"
   }
 }
 ```
@@ -756,8 +759,10 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | `tool_execution_update` | Tool execution progress (streaming output) |
 | `tool_execution_end` | Tool completes |
 | `queue_update` | Pending steering/follow-up queue changed |
-| `compaction_start` | Compaction begins |
-| `compaction_end` | Compaction completes |
+| `compaction_start` | Default Verbatim Compaction begins |
+| `compaction_end` | Default Verbatim Compaction completes |
+| `context_compaction_start` | Legacy context-compaction RPC begins |
+| `context_compaction_end` | Legacy context-compaction RPC completes |
 | `auto_retry_start` | Auto-retry begins (after transient error) |
 | `auto_retry_end` | Auto-retry completes (success or final failure) |
 | `extension_error` | Extension threw an error |
@@ -907,7 +912,7 @@ Emitted whenever the pending steering or follow-up queue changes.
 
 ### compaction_start / compaction_end
 
-Emitted when compaction runs, whether manual or automatic.
+Emitted when default Verbatim Compaction runs, whether manual or automatic. The result records deletion targets and stats rather than a generated summary.
 
 ```json
 {"type": "compaction_start", "reason": "threshold"}
@@ -920,10 +925,17 @@ The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.
   "type": "compaction_end",
   "reason": "threshold",
   "result": {
-    "summary": "Summary of conversation...",
-    "firstKeptEntryId": "abc123",
-    "tokensBefore": 150000,
-    "details": {}
+    "promptVersion": 1,
+    "deletedTargets": [{ "kind": "entry", "entryId": "abc123" }],
+    "protectedEntryIds": ["user-task-entry"],
+    "stats": {
+      "objectsBefore": 20,
+      "objectsAfter": 19,
+      "objectsDeleted": 1,
+      "tokensBefore": 150000,
+      "tokensAfter": 120000,
+      "percentReduction": 20
+    }
   },
   "aborted": false,
   "willRetry": false
@@ -936,6 +948,10 @@ If compaction was aborted, `result` is `null` and `aborted` is `true`.
 
 If compaction failed (e.g., API quota exceeded), `result` is `null`, `aborted` is `false`, and `errorMessage` contains the error description.
 
+### context_compaction_start / context_compaction_end
+
+Legacy RPC `context_compact` emits these events. The result contains `deletedTargets`, `protectedEntryIds`, `stats`, `promptVersion`, and optional `backupPath`.
+
 ### auto_retry_start / auto_retry_end
 
 Emitted when automatic retry is triggered after a transient error (overloaded, rate limit, 5xx).
@@ -1199,9 +1215,9 @@ Parse errors:
 
 ## Types
 
-Source files:
-- [`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`
+Source files and installed definitions:
+- `node_modules/@earendil-works/pi-ai/dist/types.d.ts` - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
+- `node_modules/@earendil-works/pi-agent-core/dist/types.d.ts` - `AgentMessage`, `AgentEvent`
 - [`src/core/messages.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/messages.ts) - `BashExecutionMessage`
 - [`src/modes/rpc/rpc-types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
 
@@ -1233,8 +1249,7 @@ Source files:
 {
   "role": "user",
   "content": "Hello!",
-  "timestamp": 1733234567890,
-  "attachments": []
+  "timestamp": 1733234567890
 }
 ```
 

package/docs/sdk.md

@@ -39,17 +39,10 @@ await session.prompt("What files are in the current directory?");
 
 ## Installation
 
-Choose npm, Bun, or pnpm:
+Install the SDK package with Bun:
 
 ```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.
@@ -116,8 +109,8 @@ interface AgentSession {
   // In-place tree navigation within the current session file
   navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean }>;
 
-  // Compaction
-  compact(customInstructions?: string): Promise<CompactionResult>;
+  // Verbatim Compaction (deletion-only Context Compaction)
+  compact(): Promise<ContextCompactionResult>;
   abortCompaction(): void;
 
   // Abort current operation

package/docs/session-format.md

@@ -28,13 +28,11 @@ Existing sessions are automatically migrated to the current version (v3) when lo
 
 ## Source Files
 
-Source on GitHub ([pi-mono](https://github.com/earendil-works/pi-mono)):
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
-- [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
-- [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
-- [`packages/agent/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
+Source on GitHub ([atomic](https://github.com/bastani-inc/atomic)):
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
+- [`packages/coding-agent/src/core/messages.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
 
-For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/` and `node_modules/@earendil-works/pi-ai/dist/`.
+Base message and agent event types are provided by Atomic's installed runtime dependencies (`@earendil-works/pi-ai` and `@earendil-works/pi-agent-core`), not by separate `packages/ai` or `packages/agent` directories in this monorepo. For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/`, `node_modules/@earendil-works/pi-ai/dist/`, and `node_modules/@earendil-works/pi-agent-core/dist/`.
 
 ## Message Types
 
@@ -69,7 +67,7 @@ interface ToolCall {
 }
 ```
 
-### Base Message Types (from pi-ai)
+### Base Message Types (from `@earendil-works/pi-ai`)
 
 ```typescript
 interface UserMessage {
@@ -116,7 +114,7 @@ interface Usage {
 }
 ```
 
-### Extended Message Types (from pi-coding-agent)
+### Extended Message Types (from Atomic coding-agent)
 
 ```typescript
 interface BashExecutionMessage {
@@ -225,7 +223,7 @@ Emitted when the user changes the thinking/reasoning level.
 
 ### CompactionEntry
 
-Created when context is compacted. Stores a summary of earlier messages.
+Legacy summary-compaction entry. Stores a generated summary of earlier messages for older APIs and extension hooks. Default `/compact` and auto-compaction now create `ContextCompactionEntry` records instead.
 
 ```json
 {"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
@@ -233,7 +231,17 @@ Created when context is compacted. Stores a summary of earlier messages.
 
 Optional fields:
 - `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if Atomic-generated (legacy field name)
+
+### ContextCompactionEntry
+
+Created by `/compact` and auto-compaction. Stores Atomic's default **Verbatim Compaction** data: validated logical deletion targets, not replacement text. During `buildSessionContext()`, matching entries/content blocks are filtered from active LLM context while retained content remains verbatim. This deletion-only Context Compaction approach is informed by Morph's write-up at <https://www.morphllm.com/context-compaction>.
+
+```json
+{"type":"context_compaction","id":"ctx12345","parentId":"f6g7h8i9","timestamp":"2024-12-03T14:12:00.000Z","promptVersion":1,"deletedTargets":[{"kind":"entry","entryId":"b2c3d4e5"}],"protectedEntryIds":["a1b2c3d4"],"stats":{"objectsBefore":20,"objectsAfter":19,"objectsDeleted":1,"tokensBefore":50000,"tokensAfter":43000,"percentReduction":14},"backupPath":"/path/session.jsonl.2024-12-03T14-12-00-000Z.compact.bak"}
+```
+
+`deletedTargets` entries are either whole entries (`{ kind: "entry", entryId }`) or content blocks (`{ kind: "content_block", entryId, blockIndex }`). The JSONL file remains append-only; this is logical deletion for active context rebuild.
 
 ### BranchSummaryEntry
 
@@ -245,7 +253,7 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 
 Optional fields:
 - `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if Atomic-generated (legacy field name)
 
 ### CustomEntry
 
@@ -314,7 +322,8 @@ Entries form a tree:
    - Emits the summary first
    - Then messages from `firstKeptEntryId` to compaction
    - Then messages after compaction
-4. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
+4. Applies `ContextCompactionEntry` logical deletions recorded after the latest summary compaction
+5. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
 
 ## Parsing Example
 
@@ -336,6 +345,9 @@ for (const line of lines) {
     case "compaction":
       console.log(`[${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized`);
       break;
+    case "context_compaction":
+      console.log(`[${entry.id}] Context compaction: ${entry.stats.objectsDeleted} objects deleted`);
+      break;
     case "branch_summary":
       console.log(`[${entry.id}] Branch from ${entry.fromId}`);
       break;
@@ -382,7 +394,8 @@ Key methods for working with sessions programmatically.
 - `appendMessage(message)` - Add message
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendModelChange(provider, modelId)` - Record model change
-- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add compaction
+- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add summary compaction
+- `appendContextCompaction(deletedTargets, protectedEntryIds, stats, backupPath?)` - Add logical deletion compaction
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)

package/docs/sessions.md

@@ -29,7 +29,7 @@ For the JSONL file format and SessionManager API, see [Session Format](/session-
 | `/tree` | Navigate the current session tree |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Summarize older context; see [Compaction](/compaction) |
+| `/compact` | Apply Verbatim Compaction with validated logical deletions; see [Compaction](/compaction) |
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 
@@ -128,10 +128,10 @@ When prompted, choose one of:
 2. summarize with the default prompt
 3. summarize with custom focus instructions
 
-See [Compaction](/compaction) for branch summarization internals and extension hooks.
+See [Compaction](/compaction) for Verbatim Compaction, branch summarization internals, and extension hooks.
 
 ## Session Format
 
-Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
+Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, summary compactions, context compactions, branch summaries, and extension entries.
 
 For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](/session-format).

package/docs/settings.md

@@ -90,9 +90,9 @@ Set `ATOMIC_SKIP_VERSION_CHECK=1` to disable the Atomic version update check. Us
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `compaction.enabled` | boolean | `true` | Enable auto-compaction |
+| `compaction.enabled` | boolean | `true` | Enable automatic Verbatim Compaction |
 | `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
-| `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
+| `compaction.keepRecentTokens` | number | `20000` | Recent tokens to protect from deletion |
 
 ```json
 {

package/docs/skills.md

@@ -116,16 +116,9 @@ description: What this skill does and when to use it. Be specific.
 
 ## Setup
 
-Run once before first use (choose one):
+Run once before first use:
 ```bash
-# npm
-cd /path/to/skill && npm install
-
-# Bun
 cd /path/to/skill && bun install
-
-# pnpm
-cd /path/to/skill && pnpm install
 ```
 
 ## Usage
@@ -216,14 +209,7 @@ 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,16 +16,11 @@ pkg update && pkg upgrade
 # Install dependencies
 pkg install nodejs termux-api git
 
-# 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
+# Install Atomic with npm (included with Termux's nodejs package)
 npm install -g @bastani/atomic
 
-# Bun
-bun install -g @bastani/atomic
-
-# pnpm
-pnpm add -g @bastani/atomic
+# If you have installed Bun separately in Termux, you can use Bun instead:
+# bun install -g @bastani/atomic
 
 # Create config directory
 mkdir -p ~/.atomic/agent
@@ -129,9 +124,13 @@ Run once to grant storage permissions:
 termux-setup-storage
 ```
 
-### Node.js installation issues
+### Package installation issues
+
+Termux does not currently provide an official `pkg install bun` package. On a fresh Termux install, use npm from the `nodejs` package; use Bun only if you installed it separately for your device.
+
+If npm fails, try clearing the cache before retrying:
 
-If npm fails, try clearing the cache:
 ```bash
 npm cache clean --force
+npm install -g @bastani/atomic
 ```

package/docs/themes.md

@@ -52,7 +52,7 @@ vim ~/.atomic/agent/themes/my-theme.json
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
   "name": "my-theme",
   "vars": {
     "primary": "#00aaff",
@@ -122,7 +122,7 @@ vim ~/.atomic/agent/themes/my-theme.json
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
   "name": "my-theme",
   "vars": {
     "blue": "#0066cc",

package/docs/tmux.md

@@ -1,6 +1,6 @@
 # tmux Setup
 
-Pi works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `SHIFT+Enter` and `CTRL+Enter` are usually indistinguishable from plain `Enter`.
+Atomic works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `SHIFT+Enter` and `CTRL+Enter` are usually indistinguishable from plain `Enter`.
 
 ## Recommended Configuration
 
@@ -18,7 +18,7 @@ tmux kill-server
 tmux
 ```
 
-Pi requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration.
+Atomic requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration.
 
 ## Why `csi-u` Is Recommended
 
@@ -40,7 +40,7 @@ With `extended-keys-format csi-u`, the same keys are forwarded as:
 - `CTRL+D` → `\x1b[100;5u`
 - `CTRL+Enter` → `\x1b[13;5u`
 
-Pi supports both formats, but `csi-u` is the recommended tmux setup.
+Atomic supports both formats, but `csi-u` is the recommended tmux setup.
 
 ## What This Fixes
 

package/docs/tui.md

@@ -4,7 +4,7 @@
 
 Extensions and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
 
-**Source:** [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui)
+**Source:** TUI components are provided by Atomic's installed `@earendil-works/pi-tui` runtime dependency (`node_modules/@earendil-works/pi-tui/dist/`).
 
 ## Component Interface
 
@@ -86,27 +86,18 @@ Without this propagation, typing with an IME (Chinese, Japanese, Korean, etc.) w
 
 ## Using Components
 
-**In extensions** via `ctx.ui.custom()`:
+Use `ctx.ui.custom()` with a component factory. The factory receives `done(result)`, and `ctx.ui.custom()` resolves with that result when the component finishes:
 
 ```typescript
 pi.on("session_start", async (_event, ctx) => {
-  const handle = ctx.ui.custom(myComponent);
-  // handle.requestRender() - trigger re-render
-  // handle.close() - restore normal UI
+  const result = await ctx.ui.custom((tui, theme, keybindings, done) => {
+    return new MyComponent(done);
+  });
+  ctx.ui.notify(`Selected: ${result}`, "info");
 });
 ```
 
-**In custom tools** via `pi.ui.custom()`:
-
-```typescript
-async execute(toolCallId, params, onUpdate, ctx, signal) {
-  const handle = pi.ui.custom(myComponent);
-  // ...
-  handle.close();
-}
-```
-
-Pass `{ signal }` to `ctx.ui.custom()` when the UI belongs to an abortable tool or operation. If the signal aborts, Atomic dismisses the custom UI and rejects the returned promise with the signal reason.
+Pass `{ signal }` to `ctx.ui.custom()` when the UI belongs to an abortable operation. If the signal aborts, Atomic dismisses the custom UI and rejects the returned promise with the signal reason. For overlays, use `options.onHandle` to receive an overlay handle for programmatic visibility control.
 
 ## Overlays
 
@@ -371,20 +362,15 @@ pi.registerCommand("pick", {
     const items = ["Option A", "Option B", "Option C"];
     const selector = new MySelector(items);
     
-    let handle: { close: () => void; requestRender: () => void };
-    
-    await new Promise<void>((resolve) => {
-      selector.onSelect = (item) => {
-        ctx.ui.notify(`Selected: ${item}`, "info");
-        handle.close();
-        resolve();
-      };
-      selector.onCancel = () => {
-        handle.close();
-        resolve();
-      };
-      handle = ctx.ui.custom(selector);
+    const selected = await ctx.ui.custom<string | undefined>((_tui, _theme, _keybindings, done) => {
+      selector.onSelect = (item) => done(item);
+      selector.onCancel = () => done(undefined);
+      return selector;
     });
+
+    if (selected) {
+      ctx.ui.notify(`Selected: ${selected}`, "info");
+    }
   }
 });
 ```
@@ -450,10 +436,11 @@ interface MyTheme {
 Set `PI_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
 
 ```bash
-# Upstream pi-tui debug env example
-PI_TUI_WRITE_LOG=/tmp/tui-ansi.log bunx tsx packages/tui/test/chat-simple.ts
+PI_TUI_WRITE_LOG=/tmp/tui-ansi.log atomic
 ```
 
+Atomic vendors TUI components through the installed `@earendil-works/pi-tui` dependency; this monorepo does not include the upstream TUI test source tree.
+
 ## Performance
 
 Cache rendered output when possible:
@@ -480,7 +467,7 @@ class CachedComponent {
 }
 ```
 
-Call `invalidate()` when state changes, then `handle.requestRender()` to trigger re-render.
+Call `invalidate()` when state changes, then `ctx.ui.requestRender()` from the extension context or `tui.requestRender()` from a `ctx.ui.custom()` factory to trigger re-render.
 
 ## Invalidation and Theme Changes
 

package/docs/usage.md

@@ -48,7 +48,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/tree` | Jump to any point in the session and continue from there |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/compact` | Run Verbatim Compaction by deleting safe older transcript objects |
 | `/copy` | Copy last assistant message to clipboard |
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
@@ -89,7 +89,7 @@ Useful session commands:
 - `/tree` navigates the in-file session tree and can summarize abandoned branches.
 - `/fork` creates a new session from an earlier user message.
 - `/clone` duplicates the current active branch into a new session file.
-- `/compact` summarizes older messages to free context.
+- `/compact` uses Verbatim Compaction: a fixed no-argument deletion-only planner applies only validated logical deletions; retained transcript content stays verbatim. Atomic's approach is informed by Morph's Context Compaction article: <https://www.morphllm.com/context-compaction>.
 
 See [Sessions](/sessions) and [Compaction](/compaction) for details.