@bastani/atomic 0.8.26-alpha.7 → 0.8.26-alpha.9

package/docs/compaction.md

@@ -1,30 +1,32 @@
 # Compaction & Branch Summarization
 
-LLMs have limited context windows. When conversations grow too long, Atomic uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
+LLMs have limited context windows. When conversations grow too long, Atomic uses a deletion-only form of Context Compaction called **Verbatim Compaction**: it deletes safe older transcript objects while preserving every retained object byte-for-byte. This page covers auto-compaction, manual compaction, and branch summarization.
+
+Atomic's default compaction design and terminology are informed by Morph's Context Compaction work: [Morph's Context Compaction](https://www.morphllm.com/context-compaction). In particular, Atomic follows the same core idea that coding agents benefit from deleting low-signal context instead of rewriting high-signal details like file paths, line numbers, and error strings into a lossy summary.
 
 **Source files** ([atomic](https://github.com/bastani-inc/atomic)):
 - [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Summary compaction logic
-- [`packages/coding-agent/src/core/compaction/context-compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction.ts) - Deletion-only context compaction
+- [`packages/coding-agent/src/core/compaction/context-compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction.ts) - Verbatim context compaction
 - [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
 - [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`ContextCompactionEntry`, `CompactionEntry`, `BranchSummaryEntry`)
 - [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
 
 For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/`.
 
 ## Overview
 
-Atomic has two compaction/summarization mechanisms:
+Atomic has three compaction/summarization mechanisms:
 
 | Mechanism | Trigger | Purpose |
 |-----------|---------|---------|
-| Summary compaction | Context exceeds threshold, or `/compact [instructions]` | Summarize old messages to free up context |
-| Context compaction | `/context-compact` | Delete safe old transcript objects while retaining surviving content verbatim |
+| Default context compaction (Verbatim Compaction) | Context exceeds threshold, context overflow, or `/compact` | Delete safe old transcript objects while retaining surviving content verbatim |
+| Summary compaction internals | Core APIs and legacy extension hooks | Summarize old messages into replacement context |
 | Branch summarization | `/tree` navigation | Preserve context when switching branches |
 
-Summary compaction and branch summarization use the same structured summary format and track file operations cumulatively. `/context-compact` is separate: it has no user-facing arguments, uses a fixed internal prompt, validates model-proposed deletion targets locally, and stores logical deletions in a `context_compaction` entry.
+`/compact` has no user-facing arguments. It uses a fixed internal prompt, validates model-proposed deletion targets locally, and stores logical deletions in a `context_compaction` entry. Auto-compaction uses the same deletion-only path.
 
-## Compaction
+## Default Context Compaction (Verbatim Compaction)
 
 ### When It Triggers
 
@@ -36,18 +38,66 @@ contextTokens > contextWindow - reserveTokens
 
 By default, `reserveTokens` is 16384 tokens. Configure it in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json`; legacy `.pi` paths are also supported. This leaves room for the LLM's response.
 
-You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
+You can also trigger manually with `/compact`. Custom summary instructions are no longer accepted because retained transcript content stays verbatim.
 
 ### How It Works
 
-1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` is reached. The default is 20k tokens; configure it in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json`. Legacy `.pi` paths are also supported.
-2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
-3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
-4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
-5. **Reload**: Session reloads, using summary + messages from `firstKeptEntryId` onwards
+1. Build a compactable transcript for the active branch with stable entry IDs and content-block indexes.
+2. Ask the selected model, with a fixed internal prompt, for JSON deletion targets only.
+3. Validate the plan locally: unknown IDs, protected user messages, recent operations, unresolved errors, and tool-call/tool-result orphaning fail closed.
+4. Write a backup snapshot for persisted sessions.
+5. Append a `context_compaction` entry containing validated logical deletion targets and stats.
+6. Rebuild active LLM context by filtering those targets. Retained entries/content blocks are reused unchanged.
+
+Tradeoff: compaction performs logical deletion during session rebuild instead of physically rewriting JSONL. The full raw history remains in the session file and backup, while the active LLM context is reduced.
+
+### Verbatim Compaction Diagram
+
+Unlike legacy summary compaction, Verbatim Compaction does not add a generated summary or rewrite retained messages. It appends a `context_compaction` entry that records exactly which older transcript objects should be hidden from future active context rebuilds.
 
 ```
-Before compaction:
+Before verbatim compaction:
+
+  entry:  0     1     2      3      4     5      6      7
+        ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass  │ tool │ ass │
+        └─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┘
+                    │      │            │      │
+                    └──────┴────────────┴──────┘
+                    planner may mark low-signal old objects
+
+Validated deletion plan:
+
+  delete entry 2        (older assistant text)
+  delete entry 3        (superseded tool output)
+  keep   entries 0,1,4,5,6,7 unchanged
+
+After compaction (new entry appended; JSONL remains append-only):
+
+  entry:  0     1     2      3      4     5      6      7      8
+        ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass  │ tool │ ass │ ctx │
+        └─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┴─────┘
+                    ╳      ╳                                      ↑
+             logical deletions                       context_compaction entry
+
+What the LLM sees after rebuild:
+
+  ┌────────┬─────┬─────┬──────┬──────┬─────┐
+  │ system │ usr │ usr │ ass  │ tool │ ass │
+  └────────┴─────┴─────┴──────┴──────┴─────┘
+            entry 1 entry 4 entry 5 entry 6 entry 7
+
+No generated summary is inserted. Every surviving entry/content block is reused
+verbatim; deleted objects are simply omitted from the active LLM context.
+```
+
+## Summary Compaction Internals
+
+The older summarization pipeline still exists in the core compaction module and for legacy extension hook types, but `/compact` and auto-compaction no longer use it by default.
+
+```
+Before summary compaction:
 
   entry:  0     1     2     3      4     5     6      7      8     9
         ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┐
@@ -80,23 +130,6 @@ What the LLM sees:
 
 On repeated compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Atomic also recalculates `tokensBefore` from the rebuilt session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced.
 
-## Context Compaction (`/context-compact`)
-
-`/context-compact` is a fixed no-argument command for deletion-only compaction. Unlike `/compact [prompt]`, it never accepts custom instructions and never asks the model to write replacement context.
-
-How it works in this first iteration:
-
-1. Build a compactable transcript for the active branch with stable entry IDs and content-block indexes.
-2. Ask the selected model, with a fixed internal prompt, for JSON deletion targets only.
-3. Validate the plan locally: unknown IDs, protected user messages, recent operations, unresolved errors, and tool-call/tool-result orphaning fail closed.
-4. Write a backup snapshot for persisted sessions.
-5. Append a `context_compaction` entry containing validated logical deletion targets and stats.
-6. Rebuild active LLM context by filtering those targets. Retained entries/content blocks are reused unchanged.
-
-`/context-compact anything` is invalid in the main interactive UI and trailing text is not treated as a prompt. Workflow-stage chat consumes extra text without invoking compaction so it is not sent to the model.
-
-Tradeoff: this iteration performs logical deletion during session rebuild instead of physically rewriting JSONL. The full raw history remains in the session file and backup, while the active LLM context is reduced.
-
 ### Split Turns
 
 A "turn" starts with a user message and includes all assistant responses and tool calls until the next user message. Normally, compaction cuts at turn boundaries.
@@ -152,14 +185,14 @@ interface CompactionEntry<T = unknown> {
   details?: T;         // implementation-specific data
 }
 
-// Default compaction uses this for details (from compaction.ts):
+// Legacy summary compaction uses this for details (from compaction.ts):
 interface CompactionDetails {
   readFiles: string[];
   modifiedFiles: string[];
 }
 ```
 
-Extensions can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom extension implementations can use their own structure.
+Extensions can store any JSON-serializable data in `details`. The legacy summary compaction pipeline tracks file operations, but custom extension implementations can use their own structure.
 
 See [`prepareCompaction()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) for the implementation.
 
@@ -287,11 +320,11 @@ Tool results are truncated to 2000 characters during serialization. Content beyo
 
 ## Custom Summarization via Extensions
 
-Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
+Extensions can still customize the legacy summary compaction pipeline and branch summarization. Default `/compact` and auto-compaction use deletion-only context compaction and do not call summary customization hooks. See [`extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
 
 ### session_before_compact
 
-Fired before auto-compaction or `/compact`. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
+Fired before legacy summary compaction. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
@@ -406,8 +439,8 @@ Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomi
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `enabled` | `true` | Enable auto-compaction |
+| `enabled` | `true` | Enable automatic Verbatim Compaction |
 | `reserveTokens` | `16384` | Tokens to reserve for LLM response |
-| `keepRecentTokens` | `20000` | Recent tokens to keep (not summarized) |
+| `keepRecentTokens` | `20000` | Recent tokens to protect from deletion |
 
 Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.

package/docs/extensions.md

@@ -322,6 +322,9 @@ user sends another prompt ◄─────────────────
   └─► resources_discover { reason: "startup" }
 
 /compact or auto-compaction
+  └─► compaction_start / compaction_end (deletion-only context compaction)
+
+legacy summary compaction APIs
   ├─► session_before_compact (can cancel or customize)
   └─► session_compact
 
@@ -413,7 +416,7 @@ Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `
 
 #### session_before_compact / session_compact
 
-Fired on compaction. See [Compaction](/compaction) for details.
+Fired by the legacy summary compaction pipeline. `/compact` and auto-compaction now use deletion-only context compaction by default, so extensions should not rely on these events for default compaction. See [Compaction](/compaction) for details.
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
@@ -947,13 +950,12 @@ if (usage && usage.tokens > 100_000) {
 
 ### ctx.compact()
 
-Trigger compaction without awaiting completion. Use `onComplete` and `onError` for follow-up actions.
+Trigger Atomic's default Verbatim Compaction without awaiting completion. This is deletion-only Context Compaction: retained transcript content stays unchanged, and older low-signal objects are omitted by validated logical deletion. The approach is informed by Morph's Context Compaction write-up: [Morph's Context Compaction](https://www.morphllm.com/context-compaction). Use `onComplete` and `onError` for follow-up actions.
 
 ```typescript
 ctx.compact({
-  customInstructions: "Focus on recent changes",
   onComplete: (result) => {
-    ctx.ui.notify("Compaction completed", "info");
+    ctx.ui.notify(`Compaction deleted ${result.stats.objectsDeleted} objects`, "info");
   },
   onError: (error) => {
     ctx.ui.notify(`Compaction failed: ${error.message}`, "error");
@@ -961,6 +963,8 @@ ctx.compact({
 });
 ```
 
+`customInstructions` is deprecated and ignored for default compaction because Verbatim Compaction never asks the model to write a custom summary.
+
 ### ctx.getSystemPrompt()
 
 Returns Atomic's current system prompt string.
@@ -2568,7 +2572,7 @@ All examples in [examples/extensions/](https://github.com/bastani-inc/atomic/tre
 | `prompt-customizer.ts` | Add context-aware tool guidance using `systemPromptOptions` | `on("before_agent_start")`, `BuildSystemPromptOptions` |
 | `file-trigger.ts` | File watcher triggers messages | `sendMessage` |
 | **Compaction & Sessions** |||
-| `custom-compaction.ts` | Custom compaction summary | `on("session_before_compact")` |
+| `custom-compaction.ts` | Legacy custom compaction summary | `on("session_before_compact")` |
 | `trigger-compact.ts` | Trigger compaction manually | `compact()` |
 | `git-checkpoint.ts` | Git stash on turns | `on("turn_start")`, `on("session_before_fork")`, `exec` |
 | `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |

package/docs/index.md

@@ -9,10 +9,24 @@ Atomic is a minimal terminal coding harness. It is designed to stay small at the
 
 ## Quick start
 
-Install Atomic with Bun:
+Install Atomic globally with npm, pnpm, or Bun:
+
+With npm:
+
+```bash
+npm install -g @bastani/atomic
+```
+
+With pnpm:
+
+```bash
+pnpm add -g @bastani/atomic
+```
+
+With Bun:
 
 ```bash
-bun install -g @bastani/atomic
+bun 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.
@@ -37,7 +51,7 @@ For the full first-run flow, see [Quickstart](/quickstart).
 - [Settings](/settings) - global and project settings.
 - [Keybindings](/keybindings) - default shortcuts and custom keybindings.
 - [Sessions](/sessions) - session management, branching, and tree navigation.
-- [Compaction](/compaction) - context compaction and branch summarization.
+- [Compaction](/compaction) - Verbatim Compaction, context management, and branch summarization.
 
 ## Customization
 

package/docs/json.md

@@ -18,12 +18,12 @@ type AgentSessionEvent =
   | { type: "session_info_changed"; name: string | undefined }
   | { type: "model_changed"; model: Model<Api>; previousModel: Model<Api> | undefined; source: "set" | "cycle" | "restore" }
   | { type: "thinking_level_changed"; level: ThinkingLevel }
-  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
+  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: ContextCompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
   | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
   | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string };
 ```
 
-`queue_update` emits the full pending steering and follow-up queues whenever they change. `session_info_changed`, `model_changed`, and `thinking_level_changed` report interactive session metadata changes. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
+`queue_update` emits the full pending steering and follow-up queues whenever they change. `session_info_changed`, `model_changed`, and `thinking_level_changed` report interactive session metadata changes. `compaction_start` and `compaction_end` cover both manual and automatic Verbatim Compaction, Atomic's deletion-only Context Compaction approach inspired by [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
 
 Base events come from `AgentEvent` in `@earendil-works/pi-agent-core` (installed as an Atomic dependency):
 

package/docs/quickstart.md

@@ -4,16 +4,30 @@ This page gets you from install to a useful first Atomic session.
 
 ## Prerequisites
 
-- **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.
+- **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** — Use `/login` after startup. Supports provider subscriptions and APIs.
 
 ## Install
 
-Install the published package with Bun:
+Install the published package globally with npm, pnpm, or Bun:
+
+With npm:
+
+```bash
+npm install -g @bastani/atomic
+```
+
+With pnpm:
+
+```bash
+pnpm add -g @bastani/atomic
+```
+
+With Bun:
 
 ```bash
-bun install -g @bastani/atomic
+bun 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.

package/docs/rpc.md

@@ -352,46 +352,18 @@ 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: [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
 
 ```json
 {"type": "compact"}
 ```
 
-With custom instructions:
-```json
-{"type": "compact", "customInstructions": "Focus on code changes"}
-```
-
 Response:
 ```json
 {
   "type": "response",
   "command": "compact",
   "success": true,
-  "data": {
-    "summary": "Summary of conversation...",
-    "firstKeptEntryId": "abc123",
-    "tokensBefore": 150000,
-    "details": {}
-  }
-}
-```
-
-#### context_compact
-
-Run deletion-only context compaction. 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.
-
-```json
-{"type": "context_compact"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "context_compact",
-  "success": true,
   "data": {
     "promptVersion": 1,
     "deletedTargets": [{ "kind": "entry", "entryId": "abc123" }],
@@ -404,7 +376,7 @@ Response:
       "tokensAfter": 120000,
       "percentReduction": 20
     },
-    "backupPath": "/path/to/session.jsonl.2026-06-06T00-00-00-000Z.context-compact.bak"
+    "backupPath": "/path/to/session.jsonl.2026-06-06T00-00-00-000Z.compact.bak"
   }
 }
 ```
@@ -787,10 +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` | Summary compaction begins |
-| `compaction_end` | Summary compaction completes |
-| `context_compaction_start` | Deletion-only context compaction begins |
-| `context_compaction_end` | Deletion-only context 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 |
@@ -940,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"}
@@ -953,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
@@ -971,7 +950,7 @@ If compaction failed (e.g., API quota exceeded), `result` is `null`, `aborted` i
 
 ### context_compaction_start / context_compaction_end
 
-Emitted for `/context-compact` and RPC `context_compact`. The shape mirrors manual compaction events, but `reason` is always `"manual"` and the `result` contains `deletedTargets`, `protectedEntryIds`, `stats`, `promptVersion`, and optional `backupPath` instead of a summary.
+Legacy RPC `context_compact` emits these events. The result contains `deletedTargets`, `protectedEntryIds`, `stats`, `promptVersion`, and optional `backupPath`.
 
 ### auto_retry_start / auto_retry_end
 

package/docs/sdk.md

@@ -39,7 +39,21 @@ await session.prompt("What files are in the current directory?");
 
 ## Installation
 
-Install the SDK package with Bun:
+Install `@bastani/atomic` as a project dependency with npm, pnpm, or Bun:
+
+With npm:
+
+```bash
+npm install @bastani/atomic
+```
+
+With pnpm:
+
+```bash
+pnpm add @bastani/atomic
+```
+
+With Bun:
 
 ```bash
 bun add @bastani/atomic
@@ -47,7 +61,7 @@ bun 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.
+The SDK is included in the main package. No separate SDK package is needed.
 
 ## Core Concepts
 
@@ -109,8 +123,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

@@ -223,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}
@@ -235,10 +235,10 @@ Optional fields:
 
 ### ContextCompactionEntry
 
-Created by `/context-compact`. Stores validated logical deletion targets, not replacement text. During `buildSessionContext()`, matching entries/content blocks are filtered from active LLM context while retained content remains verbatim.
+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 [Morph's Context Compaction](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.context-compact.bak"}
+{"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.

package/docs/sessions.md

@@ -29,8 +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) |
-| `/context-compact` | Apply validated deletion-only logical compaction; no arguments |
+| `/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 |
 
@@ -129,7 +128,7 @@ 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
 

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/termux.md

@@ -20,7 +20,7 @@ pkg install nodejs termux-api git
 npm install -g @bastani/atomic
 
 # If you have installed Bun separately in Termux, you can use Bun instead:
-# bun install -g @bastani/atomic
+# bun add -g @bastani/atomic
 
 # Create config directory
 mkdir -p ~/.atomic/agent

package/docs/usage.md

@@ -48,8 +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 |
-| `/context-compact` | Delete safe older transcript objects verbatim; no arguments |
+| `/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 |
@@ -90,8 +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.
-- `/context-compact` uses a fixed no-argument deletion-only planner and applies only validated logical deletions; trailing text is not used as a prompt.
+- `/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: [Morph's Context Compaction](https://www.morphllm.com/context-compaction).
 
 See [Sessions](/sessions) and [Compaction](/compaction) for details.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.8.26-alpha.7",
+  "version": "0.8.26-alpha.9",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {