docs(coding-agent): improve README structure and update session/compaction docs

- README-NEW.md: add Quick Start, Interactive Mode, Sessions sections
- session.md: add Message Types section, complete SessionManager API, fix source links to GitHub URLs
- compaction.md: rename hooks to extensions, fix source links to GitHub URLs
- keybindings.md: new file documenting all keyboard shortcuts

packages/coding-agent/README-NEW.md

@@ -49,7 +49,7 @@ pi
 /login  # Then select provider
 ```
 
-Then just talk to pi. Ask it to work on your codebase, run commands, or perform tasks for you.
+Then just talk to pi. By default, pi gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [pi packages](#pi-packages).
 
 **Platform notes:** [Windows](docs/windows.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 
@@ -91,16 +91,16 @@ See [docs/providers.md](docs/providers.md) for detailed setup instructions.
 
 ## Interactive Mode
 
-![Interactive Mode](docs/images/interactive-mode.png)
+<img src="docs/images/interactive-mode.png" alt="Interactive Mode" width="600">
 
 The interface from top to bottom:
 
 - **Startup header** - Shows shortcuts (`/hotkeys` for all), loaded AGENTS.md files, prompt templates, skills, and extensions
-- **Messages** - Your messages, assistant responses, tool calls and results, custom UI from extensions
+- **Messages** - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI
-- **Editor** - Where you type
+- **Editor** - Where you type; border color indicates thinking level
-- **Footer** - Working directory, token usage, cost, current model
+- **Footer** - Working directory, session name, total token/cache usage, cost, context usage, current model
 
-The editor can be temporarily replaced by other UI, like built-in `/settings` or custom UI from extensions (e.g., a Q&A tool that lets the user answer model questions in a structured format). Extensions can also replace the editor, add widgets above/below it, a status line, custom footer, or overlays.
+The editor can be temporarily replaced by other UI, like built-in `/settings` or custom UI from extensions (e.g., a Q&A tool that lets the user answer model questions in a structured format). [Extensions](#extensions) can also replace the editor, add widgets above/below it, a status line, custom footer, or overlays.
 
 ### Editor
 
@@ -110,58 +110,91 @@ The editor can be temporarily replaced by other UI, like built-in `/settings` or
 | Path completion | Tab to complete paths |
 | Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) |
 | Images | Ctrl+V to paste, or drag onto terminal |
-| Bash commands | Prefix with `!` (e.g., `!git status`) |
+| Bash commands | `!command` runs and sends output to LLM, `!!command` runs without sending |
+
+Standard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).
 
 ### Commands
 
-Type `/` in the editor to trigger commands. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
+Type `/` in the editor to trigger commands. [Extensions](#extensions) can register custom commands, [skills](#skills) are available as `/skill:name`, and [prompt templates](#prompt-templates) expand via `/templatename`.
 
 | Command | Description |
 |---------|-------------|
 | `/login`, `/logout` | OAuth authentication |
 | `/model` | Switch models |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Thinking level, theme, message delivery |
-| `/resume`, `/new` | Session management |
+| `/resume` | Pick from previous sessions |
-| `/tree`, `/fork` | Navigate and branch session history |
+| `/new` | Start a new session |
-| `/compact` | Manually compact context |
+| `/name <name>` | Set session display name |
-| `/export`, `/share` | Export to HTML or GitHub gist |
+| `/session` | Show session info (path, tokens, cost) |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from the current branch |
+| `/compact [prompt]` | Manually compact context, optional custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML file |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
 | `/reload` | Reload extensions, skills, prompts, themes |
 | `/hotkeys` | Show all keyboard shortcuts |
-
+| `/changelog` | Display version history |
-See [Customization](#customization) for skills, prompt templates, and extensions.
+| `/quit`, `/exit` | Quit pi |
 
 ### Keyboard Shortcuts
 
 See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).
 
-**Highlights:**
+**Commonly used:**
 
 | Key | Action |
 |-----|--------|
-| Ctrl+P | Cycle models |
+| Ctrl+C | Clear editor |
-| Ctrl+L | Open model selector |
+| Ctrl+C twice | Quit |
-| Shift+Tab | Cycle thinking level |
-| Ctrl+O | Toggle tool output |
-| Ctrl+T | Toggle thinking blocks |
 | Escape | Cancel/abort |
+| Escape twice | Open `/tree` |
+| Ctrl+L | Open model selector |
+| Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |
+| Shift+Tab | Cycle thinking level |
+| Ctrl+O | Collapse/expand tool output |
+| Ctrl+T | Collapse/expand thinking blocks |
 
 ---
 
 ## Sessions
 
-Sessions auto-save to `~/.pi/agent/sessions/` with tree structure for branching.
+Sessions are stored as JSONL files with a tree structure. Each entry has an `id` and `parentId`, enabling in-place branching without creating new files.
+
+### Management
+
+Sessions auto-save to `~/.pi/agent/sessions/` organized by working directory.
 
 ```bash
-pi -c              # Continue most recent
+pi -c                  # Continue most recent session
-pi -r              # Browse and select
+pi -r                  # Browse and select from past sessions
-pi --no-session    # Ephemeral mode
+pi --no-session        # Ephemeral mode (don't save)
+pi --session <path>    # Use specific session file or ID
 ```
 
-**Branching:** Use `/tree` to navigate history in-place, or `/fork` to create a new session from any point.
+### Branching
 
-**Compaction:** Long sessions can exhaust context. Use `/compact` manually or enable auto-compaction in `/settings`.
+**`/tree`** - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.
 
-See [docs/sessions.md](docs/sessions.md) for file format and branching details.
+- Search by typing, page with ←/→
+- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
+- Press `l` to label entries as bookmarks
+
+**`/fork`** - Create a new session file from the current branch. Opens a selector, copies history up to the selected point, and places that message in the editor for modification.
+
+### Compaction
+
+Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.
+
+**Manual:** `/compact` or `/compact <custom instructions>`
+
+**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.
+
+Compaction is lossy. The full history remains in the JSONL file; use `/tree` to revisit. Customize compaction behavior via [extensions](#extensions).
+
+See [docs/session.md](docs/session.md) for file format and [docs/compaction.md](docs/compaction.md) for internals.
 
 ---
 

packages/coding-agent/docs/compaction.md

@@ -2,12 +2,14 @@
 
 LLMs have limited context windows. When conversations grow too long, pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
 
-**Source files:**
+**Source files** ([pi-mono](https://github.com/badlogic/pi-mono)):
-- [`src/core/compaction/compaction.ts`](../src/core/compaction/compaction.ts) - Auto-compaction logic
+- [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Auto-compaction logic
-- [`src/core/compaction/branch-summarization.ts`](../src/core/compaction/branch-summarization.ts) - Branch summarization
+- [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
-- [`src/core/compaction/utils.ts`](../src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
+- [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
-- [`src/core/session-manager.ts`](../src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
-- [`src/core/hooks/types.ts`](../src/core/hooks/types.ts) - Hook event types
+- [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
+
+For TypeScript definitions in your project, inspect `node_modules/@mariozechner/pi-coding-agent/dist/`.
 
 ## Overview
 
@@ -108,13 +110,13 @@ Valid cut points are:
 - User messages
 - Assistant messages
 - BashExecution messages
-- Hook messages (custom_message, branch_summary)
+- Custom messages (custom_message, branch_summary)
 
 Never cut at tool results (they must stay with their tool call).
 
 ### CompactionEntry Structure
 
-Defined in [`src/core/session-manager.ts`](../src/core/session-manager.ts):
+Defined in [`session-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts):
 
 ```typescript
 interface CompactionEntry<T = unknown> {
@@ -125,8 +127,8 @@ interface CompactionEntry<T = unknown> {
   summary: string;
   firstKeptEntryId: string;
   tokensBefore: number;
-  fromHook?: boolean;  // true if hook provided the compaction
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
-  details?: T;         // hook-specific data
+  details?: T;         // implementation-specific data
 }
 
 // Default compaction uses this for details (from compaction.ts):
@@ -136,9 +138,9 @@ interface CompactionDetails {
 }
 ```
 
-Hooks can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom compaction hooks can use their own structure.
+Extensions can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom extension implementations can use their own structure.
 
-See [`prepareCompaction()`](../src/core/compaction/compaction.ts) and [`compact()`](../src/core/compaction/compaction.ts) for the implementation.
+See [`prepareCompaction()`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) for the implementation.
 
 ## Branch Summarization
 
@@ -181,7 +183,7 @@ This means file tracking accumulates across multiple compactions or nested branc
 
 ### BranchSummaryEntry Structure
 
-Defined in [`src/core/session-manager.ts`](../src/core/session-manager.ts):
+Defined in [`session-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts):
 
 ```typescript
 interface BranchSummaryEntry<T = unknown> {
@@ -191,8 +193,8 @@ interface BranchSummaryEntry<T = unknown> {
   timestamp: number;
   summary: string;
   fromId: string;      // Entry we navigated from
-  fromHook?: boolean;  // true if hook provided the summary
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
-  details?: T;         // hook-specific data
+  details?: T;         // implementation-specific data
 }
 
 // Default branch summarization uses this for details (from branch-summarization.ts):
@@ -202,9 +204,9 @@ interface BranchSummaryDetails {
 }
 ```
 
-Same as compaction, hooks can store custom data in `details`.
+Same as compaction, extensions can store custom data in `details`.
 
-See [`collectEntriesForBranchSummary()`](../src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](../src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](../src/core/compaction/branch-summarization.ts) for the implementation.
+See [`collectEntriesForBranchSummary()`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) for the implementation.
 
 ## Summary Format
 
@@ -248,7 +250,7 @@ path/to/changed.ts
 
 ### Message Serialization
 
-Before summarization, messages are serialized to text via [`serializeConversation()`](../src/core/compaction/utils.ts):
+Before summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
 
 ```
 [User]: What they said
@@ -260,9 +262,9 @@ Before summarization, messages are serialized to text via [`serializeConversatio
 
 This prevents the model from treating it as a conversation to continue.
 
-## Custom Summarization via Hooks
+## Custom Summarization via Extensions
 
-Hooks can intercept and customize both compaction and branch summarization. See [`src/core/hooks/types.ts`](../src/core/hooks/types.ts) for event type definitions.
+Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
 
 ### session_before_compact
 
@@ -332,7 +334,7 @@ pi.on("session_before_compact", async (event, ctx) => {
 });
 ```
 
-See [examples/hooks/custom-compaction.ts](../examples/hooks/custom-compaction.ts) for a complete example using a different model.
+See [custom-compaction.ts](../examples/extensions/custom-compaction.ts) for a complete example using a different model.
 
 ### session_before_tree
 

packages/coding-agent/docs/keybindings.md

@@ -0,0 +1,162 @@
+# Keybindings
+
+All keyboard shortcuts can be customized via `~/.pi/agent/keybindings.json`. Each action can be bound to one or more keys.
+
+## Key Format
+
+`modifier+key` where modifiers are `ctrl`, `shift`, `alt` (combinable) and keys are:
+
+- **Letters:** `a-z`
+- **Special:** `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`, `up`, `down`, `left`, `right`
+- **Function:** `f1`-`f12`
+- **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
+
+Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, etc.
+
+## All Actions
+
+### Cursor Movement
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `cursorUp` | `up` | Move cursor up |
+| `cursorDown` | `down` | Move cursor down |
+| `cursorLeft` | `left` | Move cursor left |
+| `cursorRight` | `right` | Move cursor right |
+| `cursorWordLeft` | `alt+left`, `ctrl+left` | Move cursor word left |
+| `cursorWordRight` | `alt+right`, `ctrl+right` | Move cursor word right |
+| `cursorLineStart` | `home`, `ctrl+a` | Move to line start |
+| `cursorLineEnd` | `end`, `ctrl+e` | Move to line end |
+| `pageUp` | `pageUp` | Scroll up by page |
+| `pageDown` | `pageDown` | Scroll down by page |
+
+### Deletion
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `deleteCharBackward` | `backspace` | Delete character backward |
+| `deleteCharForward` | `delete` | Delete character forward |
+| `deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
+| `deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
+| `deleteToLineStart` | `ctrl+u` | Delete to line start |
+| `deleteToLineEnd` | `ctrl+k` | Delete to line end |
+
+### Text Input
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `newLine` | `shift+enter` | Insert new line |
+| `submit` | `enter` | Submit input |
+| `tab` | `tab` | Tab / autocomplete |
+
+### Kill Ring
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `yank` | `ctrl+y` | Paste most recently deleted text |
+| `yankPop` | `alt+y` | Cycle through deleted text after yank |
+| `undo` | `ctrl+-` | Undo last edit |
+
+### Clipboard
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `copy` | `ctrl+c` | Copy selection |
+| `pasteImage` | `ctrl+v` | Paste image from clipboard |
+
+### Application
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `interrupt` | `escape` | Cancel / abort |
+| `clear` | `ctrl+c` | Clear editor |
+| `exit` | `ctrl+d` | Exit (when editor empty) |
+| `suspend` | `ctrl+z` | Suspend to background |
+| `externalEditor` | `ctrl+g` | Open in external editor (`$VISUAL` or `$EDITOR`) |
+
+### Models & Thinking
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `selectModel` | `ctrl+l` | Open model selector |
+| `cycleModelForward` | `ctrl+p` | Cycle to next model |
+| `cycleModelBackward` | `shift+ctrl+p` | Cycle to previous model |
+| `cycleThinkingLevel` | `shift+tab` | Cycle thinking level |
+
+### Display
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `expandTools` | `ctrl+o` | Collapse/expand tool output |
+| `toggleThinking` | `ctrl+t` | Collapse/expand thinking blocks |
+
+### Message Queue
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `followUp` | `alt+enter` | Queue follow-up message |
+| `dequeue` | `alt+up` | Restore queued messages to editor |
+
+### Selection (Lists, Pickers)
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `selectUp` | `up` | Move selection up |
+| `selectDown` | `down` | Move selection down |
+| `selectPageUp` | `pageUp` | Page up in list |
+| `selectPageDown` | `pageDown` | Page down in list |
+| `selectConfirm` | `enter` | Confirm selection |
+| `selectCancel` | `escape`, `ctrl+c` | Cancel selection |
+
+### Session Picker
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `toggleSessionPath` | `ctrl+p` | Toggle path display |
+| `toggleSessionSort` | `ctrl+s` | Toggle sort mode |
+| `renameSession` | `ctrl+r` | Rename session |
+| `deleteSession` | `ctrl+d` | Delete session |
+| `deleteSessionNoninvasive` | `ctrl+backspace` | Delete session (when query empty) |
+
+## Custom Configuration
+
+Create `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "cursorUp": ["up", "ctrl+p"],
+  "cursorDown": ["down", "ctrl+n"],
+  "deleteWordBackward": ["ctrl+w", "alt+backspace"]
+}
+```
+
+Each action can have a single key or an array of keys. User config overrides defaults.
+
+### Emacs Example
+
+```json
+{
+  "cursorUp": ["up", "ctrl+p"],
+  "cursorDown": ["down", "ctrl+n"],
+  "cursorLeft": ["left", "ctrl+b"],
+  "cursorRight": ["right", "ctrl+f"],
+  "cursorWordLeft": ["alt+left", "alt+b"],
+  "cursorWordRight": ["alt+right", "alt+f"],
+  "deleteCharForward": ["delete", "ctrl+d"],
+  "deleteCharBackward": ["backspace", "ctrl+h"],
+  "newLine": ["shift+enter", "ctrl+j"]
+}
+```
+
+### Vim Example
+
+```json
+{
+  "cursorUp": ["up", "alt+k"],
+  "cursorDown": ["down", "alt+j"],
+  "cursorLeft": ["left", "alt+h"],
+  "cursorRight": ["right", "alt+l"],
+  "cursorWordLeft": ["alt+left", "alt+b"],
+  "cursorWordRight": ["alt+right", "alt+w"]
+}
+```

packages/coding-agent/docs/session.md

@@ -26,11 +26,147 @@ Sessions have a version field in the header:
 
 Existing sessions are automatically migrated to the current version (v3) when loaded.
 
-## Type Definitions
+## Source Files
 
-- [`src/core/session-manager.ts`](../src/core/session-manager.ts) - Session entry types
+Source on GitHub ([pi-mono](https://github.com/badlogic/pi-mono)):
-- [`packages/agent-core/src/types.ts`](../../agent-core/src/types.ts) - `AgentMessage`
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
-- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `UserMessage`, `AssistantMessage`, `ToolResultMessage`, `Usage`, `ToolCall`, `ImageContent`, `TextContent`
+- [`packages/coding-agent/src/core/messages.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
+- [`packages/ai/src/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
+- [`packages/agent/src/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
+
+For TypeScript definitions in your project, inspect `node_modules/@mariozechner/pi-coding-agent/dist/` and `node_modules/@mariozechner/pi-ai/dist/`.
+
+## Message Types
+
+Session entries contain `AgentMessage` objects. Understanding these types is essential for parsing sessions and writing extensions.
+
+### Content Blocks
+
+Messages contain arrays of typed content blocks:
+
+```typescript
+interface TextContent {
+  type: "text";
+  text: string;
+}
+
+interface ImageContent {
+  type: "image";
+  data: string;      // base64 encoded
+  mimeType: string;  // e.g., "image/jpeg", "image/png"
+}
+
+interface ThinkingContent {
+  type: "thinking";
+  thinking: string;
+}
+
+interface ToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, any>;
+}
+```
+
+### Base Message Types (from pi-ai)
+
+```typescript
+interface UserMessage {
+  role: "user";
+  content: string | (TextContent | ImageContent)[];
+  timestamp: number;  // Unix ms
+}
+
+interface AssistantMessage {
+  role: "assistant";
+  content: (TextContent | ThinkingContent | ToolCall)[];
+  api: string;
+  provider: string;
+  model: string;
+  usage: Usage;
+  stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
+  errorMessage?: string;
+  timestamp: number;
+}
+
+interface ToolResultMessage {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  content: (TextContent | ImageContent)[];
+  details?: any;      // Tool-specific metadata
+  isError: boolean;
+  timestamp: number;
+}
+
+interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+```
+
+### Extended Message Types (from pi-coding-agent)
+
+```typescript
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output: string;
+  exitCode: number | undefined;
+  cancelled: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  excludeFromContext?: boolean;  // true for !! prefix commands
+  timestamp: number;
+}
+
+interface CustomMessage {
+  role: "custom";
+  customType: string;            // Extension identifier
+  content: string | (TextContent | ImageContent)[];
+  display: boolean;              // Show in TUI
+  details?: any;                 // Extension-specific metadata
+  timestamp: number;
+}
+
+interface BranchSummaryMessage {
+  role: "branchSummary";
+  summary: string;
+  fromId: string;                // Entry we branched from
+  timestamp: number;
+}
+
+interface CompactionSummaryMessage {
+  role: "compactionSummary";
+  summary: string;
+  tokensBefore: number;
+  timestamp: number;
+}
+```
+
+### AgentMessage Union
+
+```typescript
+type AgentMessage =
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage
+  | BashExecutionMessage
+  | CustomMessage
+  | BranchSummaryMessage
+  | CompactionSummaryMessage;
+```
 
 ## Entry Base
 
@@ -96,8 +232,8 @@ Created when context is compacted. Stores a summary of earlier messages.
 ```
 
 Optional fields:
-- `details`: Compaction-implementation specific data (e.g., file operations for default implementation, or custom data for extension implementations)
+- `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
 
 ### BranchSummaryEntry
 
@@ -108,8 +244,8 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 ```
 
 Optional fields:
-- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default implementation, arbitrary for custom implementation
+- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
-- `fromHook`: `true` if generated by an extension
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
 
 ### CustomEntry
 
@@ -224,15 +360,25 @@ for (const line of lines) {
 
 ## SessionManager API
 
-Key methods for working with sessions programmatically:
+Key methods for working with sessions programmatically.
 
-### Creation
+### Static Creation Methods
 - `SessionManager.create(cwd, sessionDir?)` - New session
-- `SessionManager.open(path, sessionDir?)` - Open existing
+- `SessionManager.open(path, sessionDir?)` - Open existing session file
 - `SessionManager.continueRecent(cwd, sessionDir?)` - Continue most recent or create new
 - `SessionManager.inMemory(cwd?)` - No file persistence
+- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
 
-### Appending (all return entry ID)
+### Static Listing Methods
+- `SessionManager.list(cwd, sessionDir?, onProgress?)` - List sessions for a directory
+- `SessionManager.listAll(onProgress?)` - List all sessions across all projects
+
+### Instance Methods - Session Management
+- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
+- `setSessionFile(path)` - Switch to a different session file
+- `createBranchedSession(leafId)` - Extract branch to new session file
+
+### Instance Methods - Appending (all return entry ID)
 - `appendMessage(message)` - Add message
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendModelChange(provider, modelId)` - Record model change
@@ -242,7 +388,7 @@ Key methods for working with sessions programmatically:
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
 - `appendLabelChange(targetId, label)` - Set/clear label
 
-### Tree Navigation
+### Instance Methods - Tree Navigation
 - `getLeafId()` - Current position
 - `getLeafEntry()` - Get current leaf entry
 - `getEntry(id)` - Get entry by ID
@@ -254,8 +400,13 @@ Key methods for working with sessions programmatically:
 - `resetLeaf()` - Reset leaf to null (before any entries)
 - `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
 
-### Context
+### Instance Methods - Context & Info
-- `buildSessionContext()` - Get messages for LLM
+- `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
 - `getEntries()` - All entries (excluding header)
-- `getHeader()` - Session metadata
+- `getHeader()` - Session header metadata
 - `getSessionName()` - Get display name from latest session_info entry
+- `getCwd()` - Working directory
+- `getSessionDir()` - Session storage directory
+- `getSessionId()` - Session UUID
+- `getSessionFile()` - Session file path (undefined for in-memory)
+- `isPersisted()` - Whether session is saved to disk