diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md
index 4f17a3e..57389f1 100644
--- a/doc/ARCHITECTURE.md
+++ b/doc/ARCHITECTURE.md
@@ -148,7 +148,27 @@ core := agent.NewAgentCore(agent.AgentCoreConfig{
 
 ## Session and Context
 
-`agent.Session` owns the message history. A `contextBuilder` enforces a rolling window to prevent unbounded prompt growth. When the window fills, older messages are either evicted (with a compaction notice injected) or proactively summarized via `/compact`.
+`agent.Session` owns the message history as a flat `[]backend.Message` slice. There is
+no rolling window or automatic eviction — the history grows unboundedly until compaction
+is explicitly triggered.
+
+**Compaction** is invoked via `/compact` (from `s/sh` or the `ctl` file) or by the
+agent itself. It makes a single LLM call to summarize the conversation, then replaces
+the history with a compact representation:
+
+1. All `system` messages are preserved verbatim.
+2. Recent `user` messages are preserved up to a ~20 000-token budget (newest first,
+   estimated at 4 chars/token).
+3. The LLM-generated summary is appended as a `user` message with a handoff prefix
+   so the next turn can resume seamlessly.
+
+Tool call/result pairs are flattened to plain text before the compaction request so no
+tool schemas are needed for the summarization call. Before compaction runs, a full
+snapshot of the pre-compaction history is written to
+`{sessionsDir}/{sessionID}.compaction.jsonl` for recovery.
+
+`/context` and `/usage` commands report the current message breakdown and token usage
+without modifying history.
 
 ## Sandboxing