@sammorrowdrums/mcpi 0.70.9 → 0.85.0

package/docs/security.md

@@ -0,0 +1,59 @@
+# Security
+
+mcpi is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
+
+## Project Trust
+
+Project trust controls whether mcpi loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
+
+mcpi considers a project to have resources that require trust when it finds any of these from the current working directory:
+
+- `.mcpi/settings.json`
+- `.mcpi/extensions`, `.mcpi/skills`, `.mcpi/prompts`, or `.mcpi/themes`
+- `.mcpi/SYSTEM.md` or `.mcpi/APPEND_SYSTEM.md`
+- project `.agents/skills` in the current directory or an ancestor directory
+
+A bare `.mcpi` directory does not count as a project resource that requires trust.
+
+When an interactive session starts in a project with resources that require trust and no saved decision for the current directory or a parent directory, mcpi follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in the config directory's `trust.json`, and the closest saved decision on the current or parent path applies before the global default.
+
+Trusting a project allows mcpi to load project resources that require trust, including:
+
+- `.mcpi/settings.json`
+- `.mcpi` resources such as extensions, skills, prompt templates, themes, and system prompt files
+- missing project packages configured through project settings
+- project-local extensions and project package-managed extensions
+
+Declining trust skips protected resources. Context files such as `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, mcpi only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
+
+Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+
+## No Built-in Sandbox
+
+mcpi does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the mcpi process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
+
+This is intentional. mcpi is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
+
+Project trust is only an input-loading guard. It prevents a repository from silently changing mcpi's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by mcpi.
+
+## Running Untrusted or Unmonitored Work
+
+For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run mcpi in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
+
+Common patterns are documented in [Containerization](containerization.md):
+
+- run the whole `mcpi` process inside a container/sandbox
+- run host mcpi while routing built-in tool execution into a Gondolin micro-VM
+- mount only the workspace paths the agent should access
+- avoid mounting host mcpi config and state directories unless the container should access host sessions, settings, and credentials
+- pass the minimum required API keys or use short-lived credentials
+- restrict network access when the task does not need it
+- review diffs and outputs before copying results back to trusted systems
+
+If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
+
+## Reporting Security Issues
+
+To report a security issue, follow the repository [Security Policy](https://github.com/SamMorrowDrums/mcpi/blob/main/SECURITY.md). Do not open a public issue for security-sensitive reports.
+
+Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how mcpi grants access that the local user did not already have.

package/docs/{session.md → session-format.md}

@@ -1,20 +1,20 @@
 # Session File Format
 
-Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with a `type` field. Session entries form a tree structure via `id`/`parentId` fields, enabling in-place branching without creating new files.
+Sessions are stored as JSONL (JSON Lines) files under the platform state directory's `sessions/` subdirectory. The state directory is `$XDG_STATE_HOME/mcpi` (fallback `~/.local/state/mcpi`) on Linux and macOS, and `%LOCALAPPDATA%\mcpi` on Windows. Each line is a JSON object with a `type` field. Session entries form a tree structure via `id`/`parentId` fields, enabling in-place branching without creating new files.
 
 ## File Location
 
 ```
-~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
+<state-directory>/sessions/--<path>--/<timestamp>_<uuid>.jsonl
 ```
 
 Where `<path>` is the working directory with `/` replaced by `-`.
 
 ## Deleting Sessions
 
-Sessions can be removed by deleting their `.jsonl` files under `~/.pi/agent/sessions/`.
+Sessions can be removed by deleting their `.jsonl` files under the state directory's `sessions/` subdirectory.
 
-Pi also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, pi uses the `trash` CLI to avoid permanent deletion.
+mcpi also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, mcpi uses the `trash` CLI to avoid permanent deletion.
 
 ## Session Version
 
@@ -28,13 +28,13 @@ Existing sessions are automatically migrated to the current version (v3) when lo
 
 ## Source Files
 
-Source on GitHub ([pi-mono](https://github.com/badlogic/pi-mono)):
-- [`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/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
+Source on GitHub ([mcpi](https://github.com/SamMorrowDrums/mcpi)):
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/SamMorrowDrums/mcpi/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
+- [`packages/coding-agent/src/core/messages.ts`](https://github.com/SamMorrowDrums/mcpi/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
+- [`packages/ai/src/types.ts`](https://github.com/SamMorrowDrums/mcpi/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
+- [`packages/agent/src/types.ts`](https://github.com/SamMorrowDrums/mcpi/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/`.
+For TypeScript definitions in your project, inspect `node_modules/@sammorrowdrums/mcpi/dist/` and `node_modules/@sammorrowdrums/mcpi-ai/dist/`.
 
 ## Message Types
 
@@ -96,6 +96,7 @@ interface ToolResultMessage {
   toolName: string;
   content: (TextContent | ImageContent)[];
   details?: any;      // Tool-specific metadata
+  usage?: Usage;      // Nested LLM work performed by the tool
   isError: boolean;
   timestamp: number;
 }
@@ -116,7 +117,9 @@ interface Usage {
 }
 ```
 
-### Extended Message Types (from pi-coding-agent)
+The exported pi-ai `StopReason` type also includes `"pending"`, but that value is reserved for partial messages in streaming events. Terminal `done`/`error` messages replace it with a completion reason before mcpi persists the assistant message, so `"pending"` should never appear in session JSONL.
+
+### Extended Message Types (from mcpi)
 
 ```typescript
 interface BashExecutionMessage {
@@ -231,9 +234,18 @@ Created when context is compacted. Stores a summary of earlier messages.
 {"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
 ```
 
+Newer harness-generated compactions embed the retained post-compaction context directly on the entry, instead of `firstKeptEntryId`:
+
+```json
+{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","tokensBefore":50000,"retainedTail":[{"role":"user","content":"latest request"},{"role":"assistant","content":[{"type":"text","text":"latest reply"}],"provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}]}
+```
+
 Optional fields:
+- `usage`: LLM usage from generating the summary; included in session token and cost totals
+- `retainedTail`: Materialized `AgentMessage[]` kept after compaction. This is optional only for backward compatibility with older sessions. Newer harness-generated compactions include it so we can rebuild context from this checkpoint without walking older entries before the compaction entry.
 - `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 (legacy field name)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if mcpi-generated (legacy field name)
+- `firstKeptEntryId`: for compatibility with old entry format.
 
 ### BranchSummaryEntry
 
@@ -244,8 +256,9 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 ```
 
 Optional fields:
+- `usage`: LLM usage from generating the summary; included in session token and cost totals
 - `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if mcpi-generated (legacy field name)
 
 ### CustomEntry
 
@@ -255,7 +268,7 @@ Extension state persistence. Does NOT participate in LLM context.
 {"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
 ```
 
-Use `customType` to identify your extension's entries on reload.
+Use `customType` to identify your extension's entries on reload. Interactive mode can render custom entries via `pi.registerEntryRenderer(customType, renderer)`, but they still do not participate in LLM context.
 
 ### CustomMessageEntry
 
@@ -282,7 +295,7 @@ Set `label` to `undefined` to clear a label.
 
 ### SessionInfoEntry
 
-Session metadata (e.g., user-defined display name). Set via `/name` command or `pi.setSessionName()` in extensions.
+Session metadata (e.g., user-defined display name). Set via `/name`, `--name` / `-n`, or `pi.setSessionName()` in extensions.
 
 ```json
 {"type":"session_info","id":"k1l2m3n4","parentId":"j0k1l2m3","timestamp":"2024-12-03T14:35:00.000Z","name":"Refactor auth module"}
@@ -306,15 +319,27 @@ Entries form a tree:
 
 ## Context Building
 
-`buildSessionContext()` walks from the current leaf to the root, producing the message list for the LLM:
+`buildContextEntries()` walks from the current leaf to the root, producing the active entry list while honoring compaction:
 
 1. Collects all entries on the path
-2. Extracts current model and thinking level settings
-3. If a `CompactionEntry` is on the path:
-   - Emits the summary first
-   - Then messages from `firstKeptEntryId` to compaction
-   - Then messages after compaction
-4. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
+2. If a `CompactionEntry` is on the path:
+   - Includes the compaction entry first
+   - If `retainedTail` is present, it acts as a self-contained checkpoint and entries after the compaction are included
+   - Otherwise entries from `firstKeptEntryId` to the compaction are included
+   - Then entries after compaction are included
+3. Preserves non-message entries in the selected range so interactive mode can render them
+
+`buildSessionContext()` builds on that entry list to produce the message list for the LLM:
+
+1. Extracts current model and thinking level settings from the full path
+2. Converts selected entries to messages:
+   - `message` -> stored `AgentMessage`
+   - `compaction` -> `compactionSummary` plus `retainedTail` when present
+   - `branch_summary` -> `branchSummary`
+   - `custom_message` -> `CustomMessage`
+   - `custom` -> no context message
+
+This makes newer compactions act like self-contained checkpoints. `retainedTail` is optional only so older sessions that only store `firstKeptEntryId` continue to load correctly.
 
 ## Parsing Example
 
@@ -401,6 +426,7 @@ Key methods for working with sessions programmatically.
 - `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
 
 ### Instance Methods - Context & Info
+- `buildContextEntries()` - Get active branch entries with compaction applied
 - `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
 - `getEntries()` - All entries (excluding header)
 - `getHeader()` - Session header metadata

package/docs/sessions.md

@@ -0,0 +1,145 @@
+# Sessions
+
+mcpi saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
+
+## Session Storage
+
+Sessions auto-save to the state directory's `sessions/` subdirectory, organized by working directory. Each session is a JSONL file with a tree structure.
+
+```bash
+mcpi -c                  # Continue most recent session
+mcpi -r                  # Browse and select from past sessions
+mcpi --no-session        # Ephemeral mode; do not save
+mcpi --name "my task"    # Set session display name at startup
+mcpi --session <path|id> # Use a specific session file or partial session ID
+mcpi --fork <path|id>    # Fork a session file or partial session ID into a new session
+```
+
+Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
+
+For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
+
+## Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `/resume` | Browse and select previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set the current session display name |
+| `/session` | Show session info |
+| `/tree` | Navigate the current session tree |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
+| `/export [file]` | Export session to HTML |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+
+## Resuming and Deleting Sessions
+
+`/resume` opens an interactive session picker for the current project. `mcpi -r` opens the same picker at startup.
+
+In the picker you can:
+
+- search by typing
+- toggle path display with Ctrl+P
+- toggle sort mode with Ctrl+S
+- filter to named sessions with Ctrl+N
+- rename with Ctrl+R
+- delete with Ctrl+D, then confirm
+
+When available, mcpi uses the `trash` CLI for deletion instead of permanently removing files.
+
+## Naming Sessions
+
+Use `/name <name>` to set a human-readable session name:
+
+```text
+/name Refactor auth module
+```
+
+Set the name at startup with `--name` or `-n`:
+
+```bash
+mcpi --name "Refactor auth module"
+mcpi --name "CI audit" -p "Review this build failure"
+```
+
+Named sessions are easier to find in `/resume` and `mcpi -r`.
+
+## Branching with `/tree`
+
+Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
+
+<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
+
+Example shape:
+
+```text
+├─ user: "Hello, can you help..."
+│  └─ assistant: "Of course! I can..."
+│     ├─ user: "Let's try approach A..."
+│     │  └─ assistant: "For approach A..."
+│     │     └─ user: "That worked..."  ← active
+│     └─ user: "Actually, approach B..."
+│        └─ assistant: "For approach B..."
+```
+
+### Tree Controls
+
+| Key | Action |
+|-----|--------|
+| ↑/↓ | Navigate visible entries |
+| ←/→ | Page up/down |
+| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
+| Shift+L | Set or clear a label on the selected entry |
+| Shift+T | Toggle label timestamps |
+| Enter | Select entry |
+| Escape/Ctrl+C | Cancel |
+| Ctrl+O | Cycle filter mode |
+
+Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with `treeFilterMode` in [Settings](settings.md).
+
+### Selection Behavior
+
+Selecting a user or custom message:
+
+1. Moves the leaf to the selected message's parent.
+2. Places the selected message text in the editor.
+3. Lets you edit and resubmit, creating a new branch.
+
+Selecting an assistant, tool, compaction, or other non-user entry:
+
+1. Moves the leaf to that entry.
+2. Leaves the editor empty.
+3. Lets you continue from that point.
+
+Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
+
+## `/tree`, `/fork`, and `/clone`
+
+| Feature | `/tree` | `/fork` | `/clone` |
+|---------|---------|---------|----------|
+| Output | Same session file | New session file | New session file |
+| View | Full tree | User-message selector | Current active branch |
+| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
+| Summary | Optional branch summary | None | None |
+
+Use `/tree` when you want to keep alternatives together. Use `/fork` or `/clone` when you want a separate session file.
+
+## Branch Summaries
+
+When `/tree` switches away from one branch to another, mcpi can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
+
+When prompted, choose one of:
+
+1. no summary
+2. summarize with the default prompt
+3. summarize with custom focus instructions
+
+See [Compaction](compaction.md) for branch summarization internals and extension hooks.
+
+## Session Format
+
+Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
+
+For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](session-format.md).

package/docs/settings.md

@@ -1,14 +1,26 @@
 # Settings
 
-Pi uses JSON settings files with project settings overriding global settings.
+mcpi uses JSON settings files with project settings overriding global settings.
 
 | Location | Scope |
 |----------|-------|
-| `~/.pi/agent/settings.json` | Global (all projects) |
-| `.pi/settings.json` | Project (current directory) |
+| `$XDG_CONFIG_HOME/mcpi/settings.json` (fallback `~/.config/mcpi/settings.json`; `%APPDATA%\mcpi\settings.json` on Windows) | Global (all projects) |
+| `.mcpi/settings.json` | Project (current directory) |
 
 Edit directly or use `/settings` for common options.
 
+## Project Trust
+
+On interactive startup, mcpi asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in the global config `trust.json`. Trusting a project allows mcpi to load `.mcpi/settings.json` and `.mcpi` resources, install missing project packages, and execute project extensions.
+
+Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+
+If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in the global config `settings.json`, or change it with `/settings`.
+
+`mcpi config` and package commands use the same project trust flow, except `mcpi update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
+
+Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes the global config `trust.json` only; the current session is not reloaded, so restart mcpi for changes to take effect.
+
 ## All Settings
 
 ### Model & Thinking
@@ -17,8 +29,9 @@ Edit directly or use `/settings` for common options.
 |---------|------|---------|-------------|
 | `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
 | `defaultModel` | string | - | Default model ID |
-| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
+| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` |
 | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
+| `showCacheMissNotices` | boolean | `false` | Show transcript notices for significant prompt-cache misses |
 | `thinkingBudgets` | object | - | Custom token budgets per thinking level |
 
 #### thinkingBudgets
@@ -39,14 +52,62 @@ Edit directly or use `/settings` for common options.
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
+| `externalEditor` | string | `$VISUAL`, then `$EDITOR`, then Notepad on Windows or `nano` elsewhere | Command for Ctrl+G external editor; takes precedence over environment variables |
 | `quietStartup` | boolean | `false` | Hide startup header |
+| `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
 | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
-| `enableInstallTelemetry` | boolean | `true` | Send an anonymous version/update ping after changelog-detected updates |
+| `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
+| `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`MCPI_EXPERIMENTAL=1`) |
+| `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
 | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
 | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
 | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
+| `outputPad` | number | `1` | Horizontal padding for user messages, assistant messages, and thinking (0 or 1) |
 | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
-| `showHardwareCursor` | boolean | `false` | Show terminal cursor |
+| `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
+| `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` or experimental `"fullscreen"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
+| `fullscreenExitOutput` | string | `"transcript"` | Fullscreen exit output: `"transcript"` prints the final transcript and resume hint, while `"resume-hint"` restores the previous screen and prints only the resume hint. Has no effect in regular TUI mode |
+| `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
+
+For VS Code, include `--wait` so mcpi resumes after the editor exits:
+
+```json
+{
+  "externalEditor": "code --wait"
+}
+```
+
+### Telemetry and update checks
+
+mcpi sends no telemetry. `enableInstallTelemetry` only controls optional provider attribution headers for OpenRouter, Cloudflare, and direct NVIDIA NIM requests. Update checks read the mcpi GitHub releases feed and are unaffected by this setting.
+
+Set `MCPI_SKIP_VERSION_CHECK=1` to disable the version update check. Use `--offline` or `MCPI_OFFLINE=1` to disable all startup network operations described here, including update checks and package update checks.
+
+### Network
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `httpProxy` | string | - | HTTP proxy URL applied as `HTTP_PROXY` and `HTTPS_PROXY`. Global setting only. |
+
+```json
+{
+  "httpProxy": "http://127.0.0.1:7890"
+}
+```
+
+### Warnings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `warnings.anthropicExtraUsage` | boolean | `true` | Show a warning when Anthropic subscription auth may use paid extra usage |
+
+```json
+{
+  "warnings": {
+    "anthropicExtraUsage": false
+  }
+}
+```
 
 ### Compaction
 
@@ -77,12 +138,16 @@ Edit directly or use `/settings` for common options.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `retry.enabled` | boolean | `true` | Enable automatic retry on transient errors |
-| `retry.maxRetries` | number | `3` | Maximum retry attempts |
-| `retry.baseDelayMs` | number | `2000` | Base delay for exponential backoff (2s, 4s, 8s) |
-| `retry.maxDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
+| `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
+| `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts |
+| `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff (2s, 4s, 8s) |
+| `retry.provider.timeoutMs` | number | SDK default | Provider/SDK request timeout in milliseconds |
+| `retry.provider.maxRetries` | number | `0` | Provider/SDK retry attempts |
+| `retry.provider.maxRetryDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
 
-When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's "quota will reset after 5h"), the request fails immediately with an informative error instead of waiting silently. Set to `0` to disable the cap.
+When a provider requests a retry delay longer than `retry.provider.maxRetryDelayMs`, the request fails immediately with an informative error instead of waiting silently. Set it to `0` to disable the limit.
+
+Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed. Setting it above `0` can make SDK/provider retries handle out-of-usage-limit errors before mcpi sees them, which may block the agent until the provider quota resets in some circumstances.
 
 ```json
 {
@@ -90,7 +155,11 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
     "enabled": true,
     "maxRetries": 3,
     "baseDelayMs": 2000,
-    "maxDelayMs": 60000
+    "provider": {
+      "timeoutMs": 3600000,
+      "maxRetries": 0,
+      "maxRetryDelayMs": 60000
+    }
   }
 }
 ```
@@ -101,7 +170,9 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
 |---------|------|---------|-------------|
 | `steeringMode` | string | `"one-at-a-time"` | How steering messages are sent: `"all"` or `"one-at-a-time"` |
 | `followUpMode` | string | `"one-at-a-time"` | How follow-up messages are sent: `"all"` or `"one-at-a-time"` |
-| `transport` | string | `"sse"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, or `"auto"` |
+| `transport` | string | `"auto"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` |
+| `httpIdleTimeoutMs` | number | `300000` | HTTP header/body idle timeout in milliseconds, also used by providers with explicit stream idle timeouts. Set to `0` to disable. |
+| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connect/open handshake timeout in milliseconds for providers that support WebSocket transports. Set to `0` to disable. |
 
 ### Terminal & Images
 
@@ -110,24 +181,54 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
 | `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
 | `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
-| `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max |
+| `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max. Applies to `@file` attachments, `read`, and images returned by tools |
 | `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
 
 ### Shell
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows) |
+| `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows); supports a leading `~` for the home directory |
 | `shellCommandPrefix` | string | - | Prefix for every bash command (e.g., `"shopt -s expand_aliases"`) |
 | `npmCommand` | string[] | - | Command argv used for npm package lookup/install operations (e.g., `["mise", "exec", "node@20", "--", "npm"]`) |
 
+Windows paths in JSON must use forward slashes or escaped backslashes:
+
+```json
+{
+  "shellPath": "C:/Program Files/Git/bin/bash.exe"
+}
+```
+
+```json
+{
+  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
+}
+```
+
 ```json
 {
   "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
 }
 ```
 
-`npmCommand` is used for all npm package-manager operations, including `npm root -g`, installs, uninstalls, and dependency installs inside git packages. Use argv-style entries exactly as the process should be launched. When `npmCommand` is configured, git package dependency installs use plain `install` to avoid npm-specific flags in wrappers or alternate package managers.
+`npmCommand` is used for all npm package-manager operations, including installs, uninstalls, and dependency installs inside git packages. User-scoped npm packages install under `$XDG_CACHE_HOME/mcpi/npm/` (fallback `~/.cache/mcpi/npm/`; `%LOCALAPPDATA%\mcpi\npm\` on Windows); project-scoped npm packages install under `.mcpi/npm/`. Use argv-style entries exactly as the process should be launched. When `npmCommand` is configured, git package dependency installs use plain `install` to avoid npm-specific flags in wrappers or alternate package managers.
+
+### Tools
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `defaultTools` | string[] | - | Built-in tools enabled initially. When omitted, mcpi uses its standard defaults |
+
+`defaultTools` selects the built-in tools enabled at startup. Extension and SDK custom tools remain enabled:
+
+```json
+{
+  "defaultTools": ["bash", "edit", "write"]
+}
+```
+
+An empty array starts with no built-in tools while preserving extension and SDK custom tools. `--tools` replaces this behavior with a strict allowlist for all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array.
 
 ### Sessions
 
@@ -136,10 +237,10 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
 | `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths, plus `~`. |
 
 ```json
-{ "sessionDir": ".pi/sessions" }
+{ "sessionDir": ".mcpi/sessions" }
 ```
 
-When multiple sources specify a session directory, `--session-dir` CLI flag takes precedence over `sessionDir` in settings.json.
+When multiple sources specify a session directory, precedence is `--session-dir`, `MCPI_CODING_AGENT_SESSION_DIR`, then `sessionDir` in settings.json.
 
 ### Model Cycling
 
@@ -158,12 +259,13 @@ When multiple sources specify a session directory, `--session-dir` CLI flag take
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `markdown.codeBlockIndent` | string | `"  "` | Indentation for code blocks |
+| `markdown.mermaid` | string | `"streaming"` | Mermaid rendering mode: `"off"`, `"final"`, or `"streaming"` |
 
 ### Resources
 
 These settings define where to load extensions, skills, prompts, and themes from.
 
-Paths in `~/.pi/agent/settings.json` resolve relative to `~/.pi/agent`. Paths in `.pi/settings.json` resolve relative to `.pi`. Absolute paths and `~` are supported.
+Paths in the global config `settings.json` resolve relative to the config directory. Paths in `.mcpi/settings.json` resolve relative to `.mcpi`. Absolute paths and `~` are supported.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
@@ -182,7 +284,7 @@ String form loads all resources from a package:
 
 ```json
 {
-  "packages": ["pi-skills", "@org/my-extension"]
+  "packages": ["mcpi-skills", "@org/my-extension"]
 }
 ```
 
@@ -192,7 +294,7 @@ Object form filters which resources to load:
 {
   "packages": [
     {
-      "source": "pi-skills",
+      "source": "mcpi-skills",
       "skills": ["brave-search", "transcribe"],
       "extensions": []
     }
@@ -220,22 +322,25 @@ See [packages.md](packages.md) for package management details.
     "maxRetries": 3
   },
   "enabledModels": ["claude-*", "gpt-4o"],
-  "packages": ["pi-skills"]
+  "warnings": {
+    "anthropicExtraUsage": true
+  },
+  "packages": ["mcpi-skills"]
 }
 ```
 
 ## Project Overrides
 
-Project settings (`.pi/settings.json`) override global settings. Nested objects are merged:
+Project settings (`.mcpi/settings.json`) override global settings. Nested objects are merged:
 
 ```json
-// ~/.pi/agent/settings.json (global)
+// $XDG_CONFIG_HOME/mcpi/settings.json (global)
 {
   "theme": "dark",
   "compaction": { "enabled": true, "reserveTokens": 16384 }
 }
 
-// .pi/settings.json (project)
+// .mcpi/settings.json (project)
 {
   "compaction": { "reserveTokens": 8192 }
 }