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

package/docs/compaction/reference.md

@@ -0,0 +1,267 @@
+---
+title: Compaction reference
+sidebarTitle: "Compaction internals"
+description: Compaction parameters, persistence, extension hooks, formats, settings, and historical formats.
+---
+
+# Compaction reference
+
+## Parameters
+
+The effective parameters appear in extension events and successful results:
+
+| Parameter | Default | Meaning |
+|---|---:|---|
+| `compression_ratio` | `0.5` | Fraction of compactable **lines to keep**, not a token ratio |
+| `preserve_recent` | `2` | Exact number of newest context-visible messages protected client-side |
+| `query` | Last visible user message | Relevance focus for deciding which older lines to retain |
+
+`preserve_recent` counts context-visible messages without aligning the boundary to a user turn. An assistant message or tool result may therefore begin the kept tail. Because such a tail can start or end mid-turn, the kept messages are not replayed as structured message blocks: they are serialized with the same transcript grammar as the compacted region and appended to the end of the boundary string, so the whole boundary reaches the provider as one message. Serialization of the kept tail is lossless — tool results keep their full text instead of being truncated at 16k characters, and images stay attached as image blocks rather than becoming `[image]` markers — so protected content is preserved, not merely summarized. A value of `0` protects no messages and makes the entire active transcript compactable. If `query` is absent, Atomic derives it from the last visible user message.
+
+One consequence is worth stating for Claude models that sign their reasoning. Because the kept tail is serialized into the boundary string rather than replayed as structured assistant messages, no `thinking` or `redacted_thinking` block survives a compaction boundary. Compaction therefore **intentionally resets the signed reasoning chain**: reasoning produced before a boundary is not carried across it. This is deliberate, and it is the first of the two remedies Anthropic documents for keep-tail compaction — carry the text and tool calls across, leave the thinking blocks behind — reached structurally rather than by a stripping pass. The tail's own content is unaffected: text, tool calls, and tool results cross the boundary losslessly. See [Preserved thinking and model switches](/models/reference#preserved-thinking-and-model-switches) for how Atomic handles prefix changes *between* boundaries, which is a separate mechanism.
+
+The query is used whole and is never truncated. This matters for structured prompts: a truncated query would make section order the retention policy, because only the leading section could influence what the planner kept, and a constraint stated later in the prompt could not. Long queries are safe — an oversized planner request surfaces as an explicit provider-overflow failure rather than silent truncation — but `keepContext` tags, not query length, are the way to guarantee a span survives.
+
+Configure defaults in `~/.atomic/agent/settings.json` or `.atomic/settings.json`:
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "compression_ratio": 0.5,
+    "preserve_recent": 2,
+    "query": "optional focus"
+  }
+}
+```
+
+`reserveTokens` controls the automatic threshold that decides when compaction runs; it is not converted into a classifier line ratio. Manual calls can pass parameter overrides through the SDK.
+
+### Per-model budgets
+
+Use `compaction.modelOverrides` to set `reserveTokens` and/or `preserve_recent` for an exact `"provider/modelId"` key. For example:
+
+```json
+{
+  "compaction": {
+    "reserveTokens": 16384,
+    "preserve_recent": 2,
+    "modelOverrides": {
+      "anthropic/claude-sonnet-4-5": { "reserveTokens": 32768, "preserve_recent": 4 }
+    }
+  }
+}
+```
+
+Each field falls back independently to the ordinary setting, then its built-in default. Keys are case-sensitive and do not support wildcards or reasoning suffixes. Both fields require non-negative safe integers. The active session model selects the budgets for manual, automatic, overflow, and post-tool compaction; switching models changes the next resolution, while borrowing a fallback planner does not. Explicit manual parameters take precedence over resolved defaults.
+
+Atomic intentionally differs from upstream pi: the recent-history override is an exact message count (`preserve_recent`), not a token budget (`keepRecentTokens`). Verbatim line reconstruction, `compression_ratio`, and `query` are unchanged; the latter two and `enabled` remain ordinary settings. See [Settings](/settings#compaction) for merge and validation details.
+
+## Persistence and resume
+
+A successful run appends the existing pi-style `type:"compaction"` entry shape:
+
+```json
+{
+  "type": "compaction",
+  "id": "c1",
+  "parentId": "m9",
+  "timestamp": "2026-07-13T10:00:00.000Z",
+  "summary": "[User]: fix the failing test\n(filtered 42 lines)\n[Assistant]: Fixed.",
+  "firstKeptEntryId": "m7",
+  "tokensBefore": 51234,
+  "details": {
+    "strategy": "verbatim-lines",
+    "promptVersion": 3,
+    "rung": "planned",
+    "parameters": {"compression_ratio": 0.5, "preserve_recent": 2, "query": "fix the failing test"},
+    "stats": {"linesBefore": 812, "linesDeleted": 417, "linesKept": 395, "rangeCount": 63, "tokensBefore": 51234, "tokensAfter": 24980, "percentReduction": 51.2}
+  }
+}
+```
+
+`details.rung` is one of `"planned"` (a model ranked the lines — the session model **or** a borrowed fallback, including silent partial recovery), `"extension"` (a `session_before_compact` override), or `"fresh"` (the compactable conversation was discarded and a new context window started). `details.plannerModel` is present **only** when a borrowed fallback model ranked the lines:
+
+```json
+"details": {
+  "strategy": "verbatim-lines",
+  "promptVersion": 3,
+  "rung": "planned",
+  "plannerModel": {"provider": "openai", "id": "gpt-5.1", "thinkingLevel": "high"}
+}
+```
+
+There is no format-version bump and no new entry type. Both `"fresh"` and `plannerModel` are additive: they are absent on every existing entry and on any compaction that used the session model, so old readers are unaffected. A `"fresh"` boundary that had to drop the `preserve_recent` tail persists `firstKeptEntryId: null`.
+
+A `compaction` entry is active only when `details.strategy === "verbatim-lines"`. On rebuild, Atomic emits one visible custom-role boundary message: the durable `summary` with the kept tail—the entries from `firstKeptEntryId` up to the boundary—serialized and concatenated onto its end. The tail is never restored as separate assistant/tool-result blocks, so a tail that starts or ends mid-turn cannot produce out-of-order provider blocks; images inside the tail ride along as image blocks on that same boundary message. When no pre-boundary context-visible message is retained—such as with `preserve_recent: 0`—`firstKeptEntryId` is `null` and the boundary carries the `summary` alone. Messages appended after the boundary are always replayed as real messages. The boundary is converted to a user-role provider message and shown in the TUI as a collapsible compaction card.
+
+Resume does not rerun planning or re-derive deletions: the exact compacted string and nullable tail boundary are already in JSONL. Existing records with a string `firstKeptEntryId` keep their original resume behavior. Legacy `context_compaction` logical-deletion records and old `compaction` summary records without the discriminator are inert archival data. Their historical omissions are not reapplied when an old session resumes.
+
+## Extension hooks
+
+### `session_before_compact`
+
+Extensions may cancel or provide a complete replacement for the prepared region:
+
+```typescript
+pi.on("session_before_compact", async (event) => {
+  const { reason, parameters, preparation, branchEntries, signal } = event;
+  if (signal.aborted) return { cancel: true };
+
+  // Optional offline override. It must contain non-whitespace text.
+  if (reason === "manual" && branchEntries.length > 100) {
+    return { compactedText: preparation.region.lines.slice(0, 40).join("\n") };
+  }
+});
+```
+
+`preparation` is a deep-frozen clone. An override changes only the compacted region text; Atomic retains the prepared boundary and persists the supplied text verbatim. Empty/whitespace text is rejected. The override path does not require provider credentials.
+
+### `session_compact`
+
+After persistence, Atomic emits an observe-only event:
+
+```typescript
+pi.on("session_compact", async (event) => {
+  console.log(event.result.rung, event.result.stats);   // rung: "planned" | "extension" | "fresh"
+  console.log(event.result.plannerModel);               // set only when a fallback model was borrowed
+  console.log(event.compactionEntry.details.strategy);  // "verbatim-lines"
+  console.log(event.fromExtension);
+});
+```
+
+Observer errors are isolated and cannot roll back the already-persisted boundary.
+
+### `session_compact_failed`
+
+A failed or cancelled manual, threshold, or overflow compaction emits an observe-only failure event:
+
+```typescript
+pi.on("session_compact_failed", async (event) => {
+  console.log(event.reason, event.errorMessage);
+  console.log(event.aborted, event.willRetry, event.fromExtension);
+});
+```
+
+`errorMessage` is absent for cancellation. `fromExtension` identifies failures after a `session_before_compact` handler supplied replacement text; no compaction boundary is persisted.
+
+## Branch Summary Format
+
+Branch summarization uses a structured format:
+
+```markdown
+## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+- [Requirements mentioned by user]
+
+## Progress
+### Done
+- [x] [Completed tasks]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues, if any]
+
+## Key Decisions
+- **[Decision]**: [Rationale]
+
+## Next Steps
+1. [What should happen next]
+
+## Critical Context
+- [Data needed to continue]
+
+<read-files>
+path/to/file1.ts
+path/to/file2.ts
+</read-files>
+
+<modified-files>
+path/to/changed.ts
+</modified-files>
+```
+
+### Message Serialization for Branch Summaries
+
+Before branch summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+
+```text
+[User]: What they said
+[Assistant thinking]: Internal reasoning
+[Assistant]: Response text
+[Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
+[Tool result]: Output from tool
+```
+
+This prevents the model from treating it as a conversation to continue.
+
+Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated.
+
+## Extension Hooks for Branch Summarization
+
+### session_before_tree
+
+Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
+
+```typescript
+pi.on("session_before_tree", async (event, ctx) => {
+  const { preparation, signal } = event;
+
+  // preparation.targetId - where we're navigating to
+  // preparation.oldLeafId - current position (being abandoned)
+  // preparation.commonAncestorId - shared ancestor
+  // preparation.entriesToSummarize - entries that would be summarized
+  // preparation.userWantsSummary - whether user chose to summarize
+
+  // Cancel navigation entirely:
+  return { cancel: true };
+
+  // Provide custom summary (only used if userWantsSummary is true):
+  if (preparation.userWantsSummary) {
+    return {
+      summary: {
+        summary: "Your summary...",
+        details: { /* custom data */ },
+      }
+    };
+  }
+});
+```
+
+See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
+
+## Settings
+
+Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json` (legacy `.pi` paths are also supported):
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | Enable automatic Verbatim Compaction. |
+| `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; threshold auto-compaction starts when completed-response usage or a prospective post-tool context exceeds the model's effective input budget minus this reserve. It is an **input-side** reserve only and never caps planner output. |
+
+Compaction has no configuration key of its own for fallback borrowing: it reuses `settings.fallbackModels`, the same ordered `provider/model[:thinkingLevel]` list that main-chat model fallback walks. With no `fallbackModels` configured, compaction behaves as before: one planner model, then either an honest failure (recoverable) or a fresh context window (load-bearing).
+
+Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
+
+## Historical formats
+
+Two old formats remain parseable but inactive:
+
+- `type:"context_compaction"` records store logical entry/content-block deletion targets from older versions. Those records are inert, so content they once hid can re-enter context when an old session resumes.
+- `type:"compaction"` without `details.strategy: "verbatim-lines"` stored generated summary prose. Those records also remain inert.
+
+Both are distinguished from active boundaries by the discriminated `details` on the shared `CompactionEntry` shape; the session format version is the same for all of them.

package/docs/compaction.md

@@ -1,9 +1,18 @@
+---
+title: "Context and compaction"
+description: "Verbatim line compaction, when it runs, planning rungs, and branch summarization."
+---
+
 # Compaction & Branch Summarization
 
 LLMs have finite context windows. Atomic reduces transcript context with **verbatim line compaction** while preserving an exact count of recent context-visible messages as ordinary messages. Branch summarization is a separate, intentionally lossy feature used only when navigating away from a branch.
 
 Compaction runs entirely locally; no external compaction service is involved. It normally uses the active session model. If that model cannot rank the lines — a rate limit, a quota exhaustion, a provider error, a context overflow, or an empty plan — Atomic *borrows* the next model from your configured `fallbackModels` for that one planner request. **A configured fallback model may therefore receive the compaction transcript**, and it is sent with that provider's own credentials. Borrowing never changes the session's model or thinking level. The model only selects which lines to delete — Atomic reconstructs the retained text mechanically, so surviving lines are never rewritten.
 
+## On this page and its reference
+
+This page covers the concepts and normal use of compaction and branch summarization. Parameters, persistence, extension hooks, formats, settings, and historical formats live in the [Compaction reference](/compaction/reference).
+
 ## Overview
 
 | Mechanism | Trigger | Model output | Durable result |
@@ -17,6 +26,8 @@ There is one context-compaction door: `compact`.
 
 ## Verbatim Line Compaction
 
+<a id="what-verbatim-means"></a>
+
 ### What "verbatim" means
 
 Atomic serializes the compactable part of the conversation into role-tagged lines:
@@ -78,55 +89,11 @@ Use it for role constraints, invariants, and anything whose loss would silently
 
 ## Parameters
 
-The effective parameters appear in extension events and successful results:
-
-| Parameter | Default | Meaning |
-|---|---:|---|
-| `compression_ratio` | `0.5` | Fraction of compactable **lines to keep**, not a token ratio |
-| `preserve_recent` | `2` | Exact number of newest context-visible messages protected client-side |
-| `query` | Last visible user message | Relevance focus for deciding which older lines to retain |
-
-`preserve_recent` counts context-visible messages without aligning the boundary to a user turn. An assistant message or tool result may therefore begin the kept tail. Because such a tail can start or end mid-turn, the kept messages are not replayed as structured message blocks: they are serialized with the same transcript grammar as the compacted region and appended to the end of the boundary string, so the whole boundary reaches the provider as one message. Serialization of the kept tail is lossless — tool results keep their full text instead of being truncated at 16k characters, and images stay attached as image blocks rather than becoming `[image]` markers — so protected content is preserved, not merely summarized. A value of `0` protects no messages and makes the entire active transcript compactable. If `query` is absent, Atomic derives it from the last visible user message.
-
-One consequence is worth stating for Claude models that sign their reasoning. Because the kept tail is serialized into the boundary string rather than replayed as structured assistant messages, no `thinking` or `redacted_thinking` block survives a compaction boundary. Compaction therefore **intentionally resets the signed reasoning chain**: reasoning produced before a boundary is not carried across it. This is deliberate, and it is the first of the two remedies Anthropic documents for keep-tail compaction — carry the text and tool calls across, leave the thinking blocks behind — reached structurally rather than by a stripping pass. The tail's own content is unaffected: text, tool calls, and tool results cross the boundary losslessly. See [Preserved thinking and model switches](/models#preserved-thinking-and-model-switches) for how Atomic handles prefix changes *between* boundaries, which is a separate mechanism.
-
-The query is used whole and is never truncated. This matters for structured prompts: a truncated query would make section order the retention policy, because only the leading section could influence what the planner kept, and a constraint stated later in the prompt could not. Long queries are safe — an oversized planner request surfaces as an explicit provider-overflow failure rather than silent truncation — but `keepContext` tags, not query length, are the way to guarantee a span survives.
-
-Configure defaults in `~/.atomic/agent/settings.json` or `.atomic/settings.json`:
-
-```json
-{
-  "compaction": {
-    "enabled": true,
-    "reserveTokens": 16384,
-    "compression_ratio": 0.5,
-    "preserve_recent": 2,
-    "query": "optional focus"
-  }
-}
-```
-
-`reserveTokens` controls the automatic threshold that decides when compaction runs; it is not converted into a classifier line ratio. Manual calls can pass parameter overrides through the SDK.
+Moved to [Compaction reference](/compaction/reference#parameters).
 
 ### Per-model budgets
 
-Use `compaction.modelOverrides` to set `reserveTokens` and/or `preserve_recent` for an exact `"provider/modelId"` key. For example:
-
-```json
-{
-  "compaction": {
-    "reserveTokens": 16384,
-    "preserve_recent": 2,
-    "modelOverrides": {
-      "anthropic/claude-sonnet-4-5": { "reserveTokens": 32768, "preserve_recent": 4 }
-    }
-  }
-}
-```
-
-Each field falls back independently to the ordinary setting, then its built-in default. Keys are case-sensitive and do not support wildcards or reasoning suffixes. Both fields require non-negative safe integers. The active session model selects the budgets for manual, automatic, overflow, and post-tool compaction; switching models changes the next resolution, while borrowing a fallback planner does not. Explicit manual parameters take precedence over resolved defaults.
-
-Atomic intentionally differs from upstream pi: the recent-history override is an exact message count (`preserve_recent`), not a token budget (`keepRecentTokens`). Verbatim line reconstruction, `compression_ratio`, and `query` are unchanged; the latter two and `enabled` remain ordinary settings. See [Settings](/settings#compaction) for merge and validation details.
+Moved to [Compaction reference](/compaction/reference#per-model-budgets).
 
 ## When compaction runs
 
@@ -244,91 +211,23 @@ Context thresholds and persisted token-reduction statistics use API-aware normal
 
 ## Persistence and resume
 
-A successful run appends the existing pi-style `type:"compaction"` entry shape:
-
-```json
-{
-  "type": "compaction",
-  "id": "c1",
-  "parentId": "m9",
-  "timestamp": "2026-07-13T10:00:00.000Z",
-  "summary": "[User]: fix the failing test\n(filtered 42 lines)\n[Assistant]: Fixed.",
-  "firstKeptEntryId": "m7",
-  "tokensBefore": 51234,
-  "details": {
-    "strategy": "verbatim-lines",
-    "promptVersion": 3,
-    "rung": "planned",
-    "parameters": {"compression_ratio": 0.5, "preserve_recent": 2, "query": "fix the failing test"},
-    "stats": {"linesBefore": 812, "linesDeleted": 417, "linesKept": 395, "rangeCount": 63, "tokensBefore": 51234, "tokensAfter": 24980, "percentReduction": 51.2}
-  }
-}
-```
-
-`details.rung` is one of `"planned"` (a model ranked the lines — the session model **or** a borrowed fallback, including silent partial recovery), `"extension"` (a `session_before_compact` override), or `"fresh"` (the compactable conversation was discarded and a new context window started). `details.plannerModel` is present **only** when a borrowed fallback model ranked the lines:
-
-```json
-"details": {
-  "strategy": "verbatim-lines",
-  "promptVersion": 3,
-  "rung": "planned",
-  "plannerModel": {"provider": "openai", "id": "gpt-5.1", "thinkingLevel": "high"}
-}
-```
-
-There is no format-version bump and no new entry type. Both `"fresh"` and `plannerModel` are additive: they are absent on every existing entry and on any compaction that used the session model, so old readers are unaffected. A `"fresh"` boundary that had to drop the `preserve_recent` tail persists `firstKeptEntryId: null`.
-
-A `compaction` entry is active only when `details.strategy === "verbatim-lines"`. On rebuild, Atomic emits one visible custom-role boundary message: the durable `summary` with the kept tail—the entries from `firstKeptEntryId` up to the boundary—serialized and concatenated onto its end. The tail is never restored as separate assistant/tool-result blocks, so a tail that starts or ends mid-turn cannot produce out-of-order provider blocks; images inside the tail ride along as image blocks on that same boundary message. When no pre-boundary context-visible message is retained—such as with `preserve_recent: 0`—`firstKeptEntryId` is `null` and the boundary carries the `summary` alone. Messages appended after the boundary are always replayed as real messages. The boundary is converted to a user-role provider message and shown in the TUI as a collapsible compaction card.
-
-Resume does not rerun planning or re-derive deletions: the exact compacted string and nullable tail boundary are already in JSONL. Existing records with a string `firstKeptEntryId` keep their original resume behavior. Legacy `context_compaction` logical-deletion records and old `compaction` summary records without the discriminator are inert archival data. Their historical omissions are not reapplied when an old session resumes.
+Moved to [Compaction reference](/compaction/reference#persistence-and-resume).
 
 ## Extension hooks
 
-### `session_before_compact`
-
-Extensions may cancel or provide a complete replacement for the prepared region:
+Moved to [Compaction reference](/compaction/reference#extension-hooks).
 
-```typescript
-pi.on("session_before_compact", async (event) => {
-  const { reason, parameters, preparation, branchEntries, signal } = event;
-  if (signal.aborted) return { cancel: true };
-
-  // Optional offline override. It must contain non-whitespace text.
-  if (reason === "manual" && branchEntries.length > 100) {
-    return { compactedText: preparation.region.lines.slice(0, 40).join("\n") };
-  }
-});
-```
+### `session_before_compact`
 
-`preparation` is a deep-frozen clone. An override changes only the compacted region text; Atomic retains the prepared boundary and persists the supplied text verbatim. Empty/whitespace text is rejected. The override path does not require provider credentials.
+Moved to [Compaction reference](/compaction/reference#session_before_compact).
 
 ### `session_compact`
 
-After persistence, Atomic emits an observe-only event:
-
-```typescript
-pi.on("session_compact", async (event) => {
-  console.log(event.result.rung, event.result.stats);   // rung: "planned" | "extension" | "fresh"
-  console.log(event.result.plannerModel);               // set only when a fallback model was borrowed
-  console.log(event.compactionEntry.details.strategy);  // "verbatim-lines"
-  console.log(event.fromExtension);
-});
-```
-
-Observer errors are isolated and cannot roll back the already-persisted boundary.
+Moved to [Compaction reference](/compaction/reference#session_compact).
 
 ### `session_compact_failed`
 
-A failed or cancelled manual, threshold, or overflow compaction emits an observe-only failure event:
-
-```typescript
-pi.on("session_compact_failed", async (event) => {
-  console.log(event.reason, event.errorMessage);
-  console.log(event.aborted, event.willRetry, event.fromExtension);
-});
-```
-
-`errorMessage` is absent for cancellation. `fromExtension` identifies failures after a `session_before_compact` handler supplied replacement text; no compaction boundary is persisted.
+Moved to [Compaction reference](/compaction/reference#session_compact_failed).
 
 ## Branch Summarization
 
@@ -415,92 +314,33 @@ See [`collectEntriesForBranchSummary()`](https://github.com/bastani-inc/atomic/b
 
 ## Branch Summary Format
 
-Branch summarization uses a structured format:
-
-```markdown
-## Goal
-[What the user is trying to accomplish]
-
-## Constraints & Preferences
-- [Requirements mentioned by user]
-
-## Progress
-### Done
-- [x] [Completed tasks]
+Moved to [Compaction reference](/compaction/reference#branch-summary-format).
 
-### In Progress
-- [ ] [Current work]
-
-### Blocked
-- [Issues, if any]
-
-## Key Decisions
-- **[Decision]**: [Rationale]
-
-## Next Steps
-1. [What should happen next]
-
-## Critical Context
-- [Data needed to continue]
-
-<read-files>
-path/to/file1.ts
-path/to/file2.ts
-</read-files>
+### Message Serialization for Branch Summaries
 
-<modified-files>
-path/to/changed.ts
-</modified-files>
-```
+Moved to [Compaction reference](/compaction/reference#message-serialization-for-branch-summaries).
 
-### Message Serialization for Branch Summaries
+## Extension Hooks for Branch Summarization
 
-Before branch summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+Moved to [Compaction reference](/compaction/reference#extension-hooks-for-branch-summarization).
 
-```text
-[User]: What they said
-[Assistant thinking]: Internal reasoning
-[Assistant]: Response text
-[Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
-[Tool result]: Output from tool
-```
+### session_before_tree
 
-This prevents the model from treating it as a conversation to continue.
+Moved to [Compaction reference](/compaction/reference#session_before_tree).
 
-Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated.
+## Branch Summaries
 
-## Extension Hooks for Branch Summarization
+When `/tree` switches away from one branch to another, Atomic can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
 
-### session_before_tree
+When prompted, choose one of:
 
-Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
+1. no summary
+2. summarize with the default prompt
+3. summarize with custom focus instructions
 
-```typescript
-pi.on("session_before_tree", async (event, ctx) => {
-  const { preparation, signal } = event;
-
-  // preparation.targetId - where we're navigating to
-  // preparation.oldLeafId - current position (being abandoned)
-  // preparation.commonAncestorId - shared ancestor
-  // preparation.entriesToSummarize - entries that would be summarized
-  // preparation.userWantsSummary - whether user chose to summarize
-
-  // Cancel navigation entirely:
-  return { cancel: true };
-
-  // Provide custom summary (only used if userWantsSummary is true):
-  if (preparation.userWantsSummary) {
-    return {
-      summary: {
-        summary: "Your summary...",
-        details: { /* custom data */ },
-      }
-    };
-  }
-});
-```
+Branch summaries are separate from `/compact`: branch navigation can generate summary prose (optionally with focus instructions), while Verbatim Compaction lets a model select numbered line ranges and reconstructs retained text mechanically.
 
-See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
+See [Compaction](/compaction) for Verbatim Compaction, branch summarization internals, and extension hooks.
 
 ## Summary request isolation
 
@@ -510,31 +350,8 @@ Verbatim planning and branch summarization are standalone provider requests. Eac
 
 ## Settings
 
-Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json` (legacy `.pi` paths are also supported):
-
-```json
-{
-  "compaction": {
-    "enabled": true,
-    "reserveTokens": 16384
-  }
-}
-```
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `enabled` | `true` | Enable automatic Verbatim Compaction. |
-| `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; threshold auto-compaction starts when completed-response usage or a prospective post-tool context exceeds the model's effective input budget minus this reserve. It is an **input-side** reserve only and never caps planner output. |
-
-Compaction has no configuration key of its own for fallback borrowing: it reuses `settings.fallbackModels`, the same ordered `provider/model[:thinkingLevel]` list that main-chat model fallback walks. With no `fallbackModels` configured, compaction behaves as before: one planner model, then either an honest failure (recoverable) or a fresh context window (load-bearing).
-
-Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
+Moved to [Compaction reference](/compaction/reference#settings).
 
 ## Historical formats
 
-Two old formats remain parseable but inactive:
-
-- `type:"context_compaction"` records store logical entry/content-block deletion targets from older versions. Those records are inert, so content they once hid can re-enter context when an old session resumes.
-- `type:"compaction"` without `details.strategy: "verbatim-lines"` stored generated summary prose. Those records also remain inert.
-
-Both are distinguished from active boundaries by the discriminated `details` on the shared `CompactionEntry` shape; the session format version is the same for all of them.
+Moved to [Compaction reference](/compaction/reference#historical-formats).

package/docs/computer-use.md

@@ -54,10 +54,15 @@ Prefer direct file automation for structured tasks such as assembling slides, fi
 | AppleScript or JavaScript for Automation through `osascript` | Create documents, address named app objects, export files, coordinate scriptable macOS apps. | macOS only. Each app defines its own scripting dictionary; some apps expose little or no scripting support. |
 | Office Scripts | Repeatable Excel workbook operations through the Automate tab, including supported Power Automate flows. | Excel only. Availability depends on the account, app version, and organization policy; it is not a general desktop-control API. |
 | PowerShell with COM automation | Drive installed Windows applications that expose COM, including desktop Office. | Windows-specific. Do not assume unattended service execution is supported or reuse the user's active app instance without permission. |
+| VBA in desktop Excel, Word, or PowerPoint | Format ranges, update charts, assemble slides, or automate document operations through Office's object models. | Requires a supporting desktop Office app and permitted macros. Windows and Mac APIs differ; VBA does not run in Office on the web. |
 | Application APIs, such as Blender's Python API | Generate geometry, set scene properties, apply repeated edits, and render or export. | Use the API and runtime for the installed app version. Some operations depend on an active document, selection, or editor context. |
 
 Before writing a script, identify the input format, required features, output path, and library or app version. Read the relevant API reference rather than guessing methods. Start with a read-only query or a disposable copy. Save to a new path and reopen the result to check its contents; use a compatible viewer or renderer when appearance matters. Scripts still need the same authorization as UI actions to overwrite, upload, or publish files.
 
+For scripts that operate an application, also keep these application-specific checks:
+
+Before writing a script, identify the target app/version, input document, object names, and output path. Read the application's API reference or scripting dictionary rather than guessing methods. Start with a read-only query or a disposable copy, and keep a record of which operations changed the document.
+
 ### macOS recipe: create a draft with osascript
 
 Open Script Editor and choose File > Open Dictionary to inspect an application's supported commands, objects, and properties. Apple's [scripting terminology guide](https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/AboutScriptingTerminology.html) explains how to read the dictionary. App scripting addresses document objects directly; `System Events` UI scripting instead drives accessible interface controls and needs Accessibility permission.
@@ -128,6 +133,36 @@ Reopen the saved deck to check slide count and text. Then view it in PowerPoint,
 
 For similar file-based tasks, use [python-docx](https://python-docx.readthedocs.io/en/latest/) for Word documents or [openpyxl](https://openpyxl.readthedocs.io/en/stable/) for Excel workbooks. Check feature support before editing a complex existing file. Use an app's own API when a library cannot make the required change, rather than forcing a lossy conversion. If an approved task requires macros, inspect the code and follow the organization's macro policy; never weaken security settings to run it.
 
+### Office recipe: format an Excel report with VBA
+
+For a desktop workbook, use [VBA](https://learn.microsoft.com/en-us/office/vba/library-reference/concepts/getting-started-with-vba-in-office) to change specific ranges instead of sending a long sequence of clicks. Try this on a trusted copy of a workbook with a worksheet named `Summary` and a report in `A1:D20`:
+
+1. Save the copy as an Excel Macro-Enabled Workbook, `.xlsm`, if you want to retain the macro.
+2. Open Developer > Visual Basic. In the copied workbook's project, choose Insert > Module and paste the macro below. If Developer is hidden, enable that tab through Excel's ribbon settings.
+3. Review the code and run `FormatSummary` through Developer > Macros, subject to your organization's macro policy.
+4. Inspect the header, number formatting, and column widths. Save only the reviewed copy.
+
+```vb
+Option Explicit
+
+Sub FormatSummary()
+    Dim report As Worksheet
+    Set report = ThisWorkbook.Worksheets("Summary")
+
+    report.Range("A1:D1").Font.Bold = True
+    report.Range("B2:D20").NumberFormat = "#,##0.00"
+    report.Range("A1:D20").Columns.AutoFit
+End Sub
+```
+
+`ThisWorkbook` is the workbook containing the macro, not whichever workbook happens to be active. Put the macro in the copied report's project, not a personal macro workbook. The example changes formatting only and does not save automatically. Its operations are documented in the [Excel VBA reference](https://learn.microsoft.com/en-us/office/vba/api/overview/excel).
+
+For other jobs, address workbook, worksheet, slide, shape, or document objects explicitly. A recorded macro can help discover operations, but replace dependence on `Selection`, `ActiveSheet`, or `ActivePresentation` with references to the intended objects before reusing it. For presentations, use PowerPoint's object model rather than treating Excel VBA as a universal Office API.
+
+Never enable all macros, weaken Trust Center settings, or enable programmatic access to the VBA project just to inject code. If policy blocks the macro, use an approved mechanism or report the restriction. VBA in a document can access more than that document, so inspect unfamiliar macros before opening or running them. If a script changes application-wide settings such as events or alerts, restore their previous values on success and error; do not suppress prompts to force a save.
+
+VBA support in desktop Excel, Word, and PowerPoint includes macOS, but Windows COM, ActiveX, and Win32-dependent code is not portable. Consult Microsoft's [Office for Mac guidance](https://learn.microsoft.com/en-us/office/vba/api/overview/office-mac) for sandbox and file-access differences. Saving as `.xlsx` cannot retain VBA; choose the output format deliberately.
+
 ### Office Scripts, app runtimes, and file tools
 
 For Excel on the web or a supported desktop installation with the Automate tab, consider Office Scripts. Record a small action or create a script there, then use the `ExcelScript` workbook API for repeatable edits. These TypeScript scripts are not VBA and do not run as ordinary Node.js scripts. Check [Office Scripts versus VBA](https://learn.microsoft.com/en-us/office/dev/scripts/resources/vba-differences) for platform, licensing, and API differences. Creating a Power Automate flow can introduce scheduled runs and cloud access; do so only when that automation is part of the request.