docs: add compaction concept

docs/concepts/compaction.md

@@ -0,0 +1,43 @@
+---
+summary: "Context window + compaction: how Clawdbot keeps sessions under model limits"
+read_when:
+  - You want to understand auto-compaction and /compact
+  - You are debugging long sessions hitting context limits
+---
+# Context Window & Compaction
+
+Every model has a **context window** (max tokens it can see). Long-running chats accumulate messages and tool results; once the window is tight, Clawdbot **compacts** older history to stay within limits.
+
+## What compaction is
+Compaction **summarizes older conversation** into a compact summary entry and keeps recent messages intact. The summary is stored in the session history, so future requests use:
+- The compaction summary
+- Recent messages after the compaction point
+
+Compaction **persists** in the session’s JSONL history.
+
+## Auto-compaction (default on)
+When a session nears or exceeds the model’s context window, Clawdbot triggers auto-compaction and may retry the original request using the compacted context.
+
+You’ll see:
+- `🧹 Auto-compaction complete` in verbose mode
+- `/status` showing `🧹 Compactions: <count>`
+
+## Manual compaction
+Use `/compact` (optionally with instructions) to force a compaction pass:
+```
+/compact Focus on decisions and open questions
+```
+
+## Context window source
+Context window is model-specific. Clawdbot uses the model definition from the configured provider catalog to determine limits.
+
+## Compaction vs pruning
+- **Compaction**: summarises and **persists** in JSONL.
+- **Session pruning**: trims old **tool results** only, **in-memory**, per request.
+
+See [/concepts/session-pruning](/concepts/session-pruning) for pruning details.
+
+## Tips
+- Use `/compact` when sessions feel stale or context is bloated.
+- Large tool outputs are already truncated; pruning can further reduce tool-result buildup.
+- If you need a fresh slate, `/new` or `/reset` starts a new session id.

docs/concepts/session-pruning.md

@@ -48,7 +48,7 @@ Pruning uses an estimated context window (chars ≈ tokens × 4). The window siz
 
 ## Interaction with other limits
 - Built-in tools already truncate their own output; session pruning is an extra layer that prevents long-running chats from accumulating too much tool output in the model context.
-- Compaction is separate: compaction summarizes and persists, pruning is transient per request.
+- Compaction is separate: compaction summarizes and persists, pruning is transient per request. See [/concepts/compaction](/concepts/compaction).
 
 ## Defaults (when enabled)
 - `keepLastAssistants`: `3`

docs/concepts/session.md

@@ -85,7 +85,7 @@ Send these as standalone messages so they register.
 - `clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
 - Send `/status` as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
 - Send `/stop` as a standalone message to abort the current run.
-- Send `/compact` (optional instructions) as a standalone message to summarize older context and free up window space.
+- Send `/compact` (optional instructions) as a standalone message to summarize older context and free up window space. See [/concepts/compaction](/concepts/compaction).
 - JSONL transcripts can be opened directly to review full turns.
 
 ## Tips

docs/docs.json

@@ -545,6 +545,7 @@
           "concepts/agent-loop",
           "concepts/agent-workspace",
           "concepts/multi-agent",
+          "concepts/compaction",
           "concepts/session",
           "concepts/session-pruning",
           "concepts/sessions",

docs/start/faq.md

@@ -337,7 +337,7 @@ See [Groups](/concepts/groups) for details.
 
 ### How much context can Clawdbot handle?
 
-Context window depends on the model. Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit.
+Context window depends on the model. Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit. See [/concepts/compaction](/concepts/compaction).
 
 Practical tips:
 - Keep `AGENTS.md` focused, not bloated.

docs/start/hubs.md

@@ -36,6 +36,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Agent loop](https://docs.clawd.bot/concepts/agent-loop)
 - [Streaming + chunking](/concepts/streaming)
 - [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent)
+- [Compaction](https://docs.clawd.bot/concepts/compaction)
 - [Sessions](https://docs.clawd.bot/concepts/session)
 - [Sessions (alias)](https://docs.clawd.bot/concepts/sessions)
 - [Session pruning](https://docs.clawd.bot/concepts/session-pruning)

docs/tools/slash-commands.md

@@ -46,7 +46,7 @@ Text + native (when enabled):
 - `/queue <mode>` (plus options like `debounce:2s cap:25 drop:summarize`)
 
 Text-only:
-- `/compact [instructions]`
+- `/compact [instructions]` (see [/concepts/compaction](/concepts/compaction))
 
 ## Surface notes