docs: sweep CLAUDE.md, README, roadmap, guide for /compact

CLAUDE.md tree gains agent/compaction.rs, slash/compact.rs,
chat/blocks/compacted.rs and notes Entry::Compact alongside the other
JSONL variants. README slash-command list and the user-guide table both
gain /compact. The roadmap moves the manual half of context compression
from Current Focus to Working Today and renames the deferred half to
"Auto-Compaction" with the threshold-math notes.

Author: hakula139

CLAUDE.md

@@ -25,6 +25,7 @@ ox                                          # Start an interactive session
 .
 ├── agent.rs                                # Agent turn loop, stream accumulation, tool dispatch
 ├── agent/
+│   ├── compaction.rs                       # /compact driver: stripped-transcript summarization request + summary-prefix wrapping
 │   └── event.rs                            # AgentEvent, UserAction, AgentSink trait, StdioSink
 ├── client.rs                               # Client module root
 ├── client/
@@ -55,7 +56,7 @@ ox                                          # Start an interactive session
 │   ├── actor.rs                            # Session actor task body + SessionCmd protocol + receive-and-drain batching loop
 │   ├── chain.rs                            # ChainBuilder: UUID-DAG message-chain reconstruction (fork-aware tip pick + parent walk)
 │   ├── display.rs                          # Shared session-listing formatters (relative time, `id · when · N msgs · branch · project` line)
-│   ├── entry.rs                            # JSONL entry types (Header, Message, Title, Summary) and metadata structs
+│   ├── entry.rs                            # JSONL entry types (Header, Message, Title, Summary, Compact, ToolResultMetadata, FileSnapshot) and metadata structs
 │   ├── handle.rs                           # SessionHandle (cheap-to-clone async API), SharedState, start / resume / roll lifecycle
 │   ├── handle/
 │   │   └── testing.rs                      # Cfg-test SessionHandle constructors for sibling test modules (dead, acks_then_drops)
@@ -71,6 +72,7 @@ ox                                          # Start an interactive session
 ├── slash.rs                                # Slash-command surface root: re-exports + dispatch
 ├── slash/
 │   ├── clear.rs                            # /clear (new, reset) — forwards UserAction::Clear, resets ChatView, drops the AI title
+│   ├── compact.rs                          # /compact [<instructions>] — forwards UserAction::Compact; agent loop drives the summarization
 │   ├── config.rs                           # /config — opens a KvOverview modal of resolved config + layered file paths
 │   ├── confirm.rs                          # ConfirmDeleteSessionModal — destructive-action gate; runs the unlink synchronously on Y, sticky inline error on failure
 │   ├── context.rs                          # SlashContext (borrowed ChatView + LiveSessionInfo + modal slot) handed to each command's execute
@@ -107,6 +109,7 @@ ox                                          # Start an interactive session
 │   │   │   ├── blocks.rs                   # ChatBlock trait + RenderCtx + icon-prefix helpers
 │   │   │   └── blocks/
 │   │   │       ├── assistant.rs            # AssistantText + AssistantThinking
+│   │   │       ├── compacted.rs            # CompactedBlock — bordered surface; bold accent header (count + optional focus) + markdown summary body
 │   │   │       ├── error.rs                # ErrorBlock
 │   │   │       ├── git_diff.rs             # GitDiffBlock — unified-diff render reusing the Edit-tool `+` / `-` row-bg + line-number gutter
 │   │   │       ├── interrupted.rs          # InterruptedMarker — dim italic `(interrupted)` line on cancel

README.md

@@ -20,7 +20,7 @@ Early development. What works today:
 - Agent loop with extended thinking and tool-use round-trip
 - File and search tools: `read`, `write`, `edit`, `glob`, `grep`, `bash`
 - Turn interruption (Esc / Ctrl+C) plus mid-turn queued follow-up prompts that splice into the same turn between tool calls, with double-press Ctrl+C exit confirmation
-- Slash commands with `/`-triggered autocomplete (name and curated-arg modes): `/clear`, `/config`, `/delete`, `/diff`, `/effort`, `/help`, `/init`, `/model`, `/rename`, `/resume`, `/status`, `/theme`
+- Slash commands with `/`-triggered autocomplete (name and curated-arg modes): `/clear`, `/compact`, `/config`, `/delete`, `/diff`, `/effort`, `/help`, `/init`, `/model`, `/rename`, `/resume`, `/status`, `/theme`
 - `CLAUDE.md` / `AGENTS.md` instruction-file discovery
 - Session persistence with JSONL conversation logs, listing, and resume
 - Per-session file-change tracking with a Read-before-Edit gate and on-disk drift detection

docs/guide/slash-commands.md

@@ -9,6 +9,7 @@ For commands with curated arguments (`/model`, `/effort`, `/theme`), the popup s
 | Command                                     | Description                                                                          |
 | ------------------------------------------- | ------------------------------------------------------------------------------------ |
 | `/clear` (aliases `/new`, `/reset`)         | Start a fresh session. The previous one stays resumable via `ox -c`.                 |
+| `/compact [<instructions>]`                 | Compress the conversation into a summary; trailing text steers the focus.            |
 | `/config`                                   | Open the resolved configuration and its layered file paths in a read-only modal.     |
 | `/delete <id-prefix>`                       | Delete a saved session by id prefix, with a Y/N confirm modal before the unlink.     |
 | `/diff`                                     | Show `git diff HEAD` plus untracked files in chat, capped at 64 KB.                  |
@@ -27,14 +28,24 @@ Double the leading slash. Typing `//etc` sends the literal `/etc`.
 
 ## Mid-Turn Behavior
 
-State-mutating commands (`/clear`, `/delete`, `/init`, and the typed-arg forms of `/effort`, `/model`, `/rename`, `/resume`, `/theme`) wait for the current turn to finish. Read-only commands and the bare modal-opening forms run anytime.
+State-mutating commands (`/clear`, `/compact`, `/delete`, `/init`, and the typed-arg forms of `/effort`, `/model`, `/rename`, `/resume`, `/theme`) wait for the current turn to finish. Read-only commands and the bare modal-opening forms run anytime.
 
 ## Model and Effort
 
 Bare `/model` and `/effort` open pickers; both apply on Enter, cancel on Esc.
 
 `/model <id>` accepts aliases (`opus`, `sonnet`, `haiku` — append `[1m]` for the 1M-context variants), full ids, or any unique suffix or substring. Haiku has no effort tier, so `/effort` on Haiku errors with a recovery hint. See [Configuration](configuration.md) for tier defaults.
 
+## Compaction
+
+`/compact` streams a one-shot summarization request through the live model, then replaces the in-memory transcript with a single boundary block: a header (`Compacted N messages → 1 summary`) plus the rendered summary. The next prompt continues from the summary rather than the full prior chat.
+
+`/compact <instructions>` appends free-text focus instructions to the rubric (e.g., `/compact focus on the build error and how we fixed it`). Useful when only a slice of the work matters going forward.
+
+The summary lands in the JSONL as a `compact` boundary entry plus a synthetic continuation message. Resuming the session via `ox -c` shows only the post-compact tail; the pre-compact transcript stays on disk for archival but is not replayed in chat. The file-change tracker resets on compact, so any `Edit` after a `/compact` requires a fresh `Read`. Queued prompts survive the compaction.
+
+`/compact` refuses on sessions with fewer than 4 messages, when the model returns an empty summary, or while a turn is in flight (it waits for the current reply to finish first).
+
 ## Sessions
 
 `/rename` opens a modal pre-filled with the current title; `/rename <title>` sets it directly. The chosen title sticks and replaces the auto-generated AI title for the rest of the session.

docs/roadmap.md

@@ -63,12 +63,18 @@ The direction is simple:
 
 ### Slash Commands
 
-- Built-in: `/clear` (aliases `/new`, `/reset`), `/config`, `/delete`, `/diff`, `/effort`, `/help`, `/init`, `/model`, `/rename`, `/resume` (alias `/continue`), `/status`, `/theme`. See the [user guide](guide/slash-commands.md).
+- Built-in: `/clear` (aliases `/new`, `/reset`), `/compact`, `/config`, `/delete`, `/diff`, `/effort`, `/help`, `/init`, `/model`, `/rename`, `/resume` (alias `/continue`), `/status`, `/theme`. See the [user guide](guide/slash-commands.md).
 - Autocomplete popup on typing `/`, with ranked filter, Tab completion, and arg-mode completion for commands with curated rosters (`/model`, `/effort`, `/theme`).
 - Mid-session swaps (`/model`, `/effort`, `/rename`, `/resume`, `/theme`) are session-only, and no slash command writes user config files.
 - Destructive ops (`/delete <id-prefix>`, or Ctrl+D / Delete inside the `/resume` picker) gate behind a Y/N confirm modal. Only finalized sessions can be deleted.
 - Modal UI primitive: focus-grabbing overlays above the input for picker, slider, editor, and read-only kv-overview forms; nested modals layer cleanly. Esc / Ctrl+C cancels any modal.
 
+### Context Compression
+
+- Manual `/compact [instructions]` streams a one-shot summarization through the live model and replaces the in-memory transcript with a synthetic continuation. Optional trailing instructions steer the focus.
+- Persisted as a dedicated `compact` JSONL boundary plus the synthetic post-compact message; resume sees only the post-compact tail.
+- File tracker resets on compact — Edits after `/compact` require a fresh Read.
+
 ### Authentication & Configuration
 
 - Anthropic API key via `ANTHROPIC_API_KEY` or config file.
@@ -83,15 +89,15 @@ The direction is simple:
 - Project-level allowlists to auto-approve trusted commands.
 - Plan mode: read-only review of the agent's proposed changes before any tool runs.
 
-### Context Compression
+### Auto-Compaction
 
-- Summarize older messages when approaching the context limit so long sessions keep responding.
+- Fire `/compact` automatically when the running token usage approaches the model's context window. Threshold math (effective context window minus reserved-output buffer), per-turn check at sampling boundaries, single-turn circuit breaker, and a config knob for opt-out.
 
 ### Slash Commands (continuation)
 
 Remaining surface beyond Working Today:
 
-- Deferred: `/compact`, `/cost`, `/login` / `/logout`, custom user commands, `/init` multi-phase flow.
+- Deferred: `/cost`, `/login` / `/logout`, custom user commands, `/init` multi-phase flow.
 
 Persistence stance: `/model`, `/effort`, and `/theme` mutate session state only, and restart returns to user-declared config. Cross-session persistence will land as an **explicit subcommand** writing to a user-opted-in path, never as a silent merge into a `~/.claude.json`-style mega-file.