From ea16af8b7230caf5eb5c9fa24bda044e5f75ec67 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Wed, 24 Dec 2025 12:48:16 +0100
Subject: [PATCH] Add ASCII diagram to compaction docs

---
 packages/coding-agent/docs/hooks.md | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/packages/coding-agent/docs/hooks.md b/packages/coding-agent/docs/hooks.md
index a88fd57e..8881e802 100644
--- a/packages/coding-agent/docs/hooks.md
+++ b/packages/coding-agent/docs/hooks.md
@@ -183,10 +183,31 @@ For `before_branch` and `branch` events, `event.targetTurnIndex` contains the en
 The `before_compact` event lets you implement custom compaction strategies. Understanding the data model:
 
 **How default compaction works:**
-1. When context exceeds the threshold, pi finds a "cut point" that keeps ~20k tokens of recent turns
-2. Messages before the cut point are summarized and discarded
-3. Messages after the cut point are kept verbatim
-4. The summary + kept messages become the new context
+
+When context exceeds the threshold, pi finds a "cut point" that keeps ~20k tokens of recent turns:
+
+```
+Session entries (before compaction):
+┌─────────────────────────────────────────────────────────────────┐
+│ [header] [prev compaction] [msg] [msg] [msg] [msg] [msg] [msg]  │
+│                   ↑          └─────┬─────┘   └───────┬───────┘  │
+│           previousSummary    messagesToSummarize  messagesToKeep│
+│                              (will be discarded)  (kept as-is)  │
+│                                         ↑                       │
+│                              cutPoint.firstKeptEntryIndex       │
+└─────────────────────────────────────────────────────────────────┘
+
+After compaction:
+┌─────────────────────────────────────────────────────────────────┐
+│ [header] [prev compaction] [NEW compaction] [msg] [msg] [msg]   │
+│                             └──────┬──────┘ └───────┬───────┘   │
+│                               summary of      messagesToKeep    │
+│                            messagesToSummarize  (unchanged)     │
+│                            + previousSummary                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+The new compaction entry's `firstKeptEntryIndex` tells the session loader where to start reading messages after the summary.
 
 **Event fields:**