@earendil-works/pi-coding-agent 0.87.0 → 0.99.0

package/docs/usage.md

@@ -1,312 +1,94 @@
-# Using Pi
-
-This page collects day-to-day usage details that do not fit on the quickstart page.
-
-## Interactive Mode
-
-<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
-
-The interface has four main areas:
-
-- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
-- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
-- **Editor** - where you type; border color indicates the current thinking level
-- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
-
-The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
-
-### Editor Features
-
-| Feature | How |
-|---------|-----|
-| File reference | Type `@` to fuzzy-search project files |
-| Path completion | Press Tab to complete paths |
-| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
-| Copy response | Ctrl+X copies the selected message in `/tree`; otherwise it copies the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
-| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
-| Shell command | `!command` runs and sends output to the model |
-| Hidden shell command | `!!command` runs without sending output to the model |
-| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
-
-See [Keybindings](keybindings.md) for all shortcuts and customization.
-
-## Slash Commands
-
-Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
-
-| Command | Description |
-|---------|-------------|
-| `/login`, `/logout` | Manage OAuth or API-key credentials |
-| [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
-| `/model` | Switch models; Ctrl+S in the picker saves the startup default |
-| `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
-| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
-| `/settings` | Theme, message delivery, transport, and other preferences |
-| `/resume` | Pick from previous sessions |
-| `/new` | Start a new session |
-| `/name <name>` | Set session display name |
-| `/session` | Show session file, ID, messages, tokens, and cost |
-| `/tree` | Jump to any point in the session and continue from there |
-| `/trust` | Save project trust decision for future sessions |
-| `/fork` | Create a new session from a previous user message |
-| `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
-| `/copy` | Copy last assistant message to clipboard |
-| `/export [file]` | Export session to HTML or JSONL |
-| `/import <file>` | Import and resume a session from a JSONL file |
-| `/share` | Upload as private GitHub gist with shareable HTML link |
-| `/bug [description]` | Report a bug to the Pi developers; see [Sessions](sessions.md#reporting-bugs) |
-| `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
-| `/hotkeys` | Show all keyboard shortcuts |
-| `/changelog` | Display version history |
-| `/quit` | Quit pi |
-
-## Message Queue
-
-You can submit messages while the agent is still working:
-
-- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
-- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
-- **Escape** aborts and restores queued messages to the editor.
-- **Alt+Up** retrieves queued messages back to the editor.
-
-On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want pi to receive the shortcut.
-
-Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
-
-## Sessions
-
-Sessions are saved automatically to `~/.pi/agent/sessions/`, organized by working directory.
-
-```bash
-pi -c                  # Continue most recent session
-pi -r                  # Browse and select a session
-pi --no-session        # Ephemeral mode; do not save
-pi --name "my task"    # Set session display name at startup
-pi --session <path|id> # Use a specific session file or session ID
-pi --fork <path|id>    # Fork a session into a new session file
-```
-
-Useful session commands:
-
-- `/session` shows the current session file and ID.
-- `/tree` navigates the in-file session tree and can summarize abandoned branches.
-- `/fork` creates a new session from an earlier user message.
-- `/clone` duplicates the current active branch into a new session file.
-- `/compact` summarizes older messages to free context.
-
-See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
-
-## Context Files
-
-Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
-
-- `~/.pi/agent/AGENTS.md` for global instructions
-- parent directories, walking up from the current working directory
-- the current directory
-
-If a directory contains `AGENTS.override.md`, Pi loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
-
-Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
-
-### System Prompt Files
-
-Replace the default system prompt with:
-
-- `.pi/SYSTEM.md` for a project
-- `~/.pi/agent/SYSTEM.md` globally
+# Use Pi in the terminal
 
-Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+Run `pi` from the folder you want to work in. Pi uses that folder to discover files, instructions, and configuration, and to group saved sessions. If you have not installed Pi or chosen a model yet, follow the [Quickstart](quickstart.md).
 
-### Project Trust
+Pi may ask whether you trust the working folder before loading its project resources. See [Project trust](security.md#understand-project-trust).
 
-On interactive startup, pi 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 `~/.pi/agent/trust.json`. Trusting a project allows pi to load `.pi/settings.json` and `.pi` resources, install missing project packages, and execute project extensions.
+<p align="center"><img src="images/interactive-mode.png" alt="Pi interactive mode showing a conversation, editor, and status information" width="750"></p>
 
-Before the trust decision, pi loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
+The transcript shows your prompts, Pi's responses, tool calls, results, and errors. You write prompts and commands in the editor. The footer shows the current folder, session, model, context usage, and accumulated usage and cost.
 
-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.
+## Enter a prompt
 
-If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.pi/agent/settings.json`, or change it with `/settings`.
+Type a request and press `Enter` to send it. Use `Shift+Enter` to add a line, or press `Ctrl+G` to work on a longer prompt in your configured external editor.
 
-`pi config` and package commands use the same project trust flow, except `pi update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
+To include files or images:
 
-Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.pi/agent/trust.json` only; the current session is not reloaded, so restart pi for changes to take effect.
+- Type `@` to search for a file and add it to your prompt.
+- Press `Tab` to complete a path.
+- Paste an image or drag it into a compatible terminal.
 
+## Follow Pi's work
 
-## Exporting and Sharing Sessions
+Pi shows each tool call and result while it works. Press `Ctrl+O` to expand or collapse tool output. Press `Ctrl+T` to show or hide thinking blocks.
 
-Use `/export [file]` to write a session to HTML.
+The startup header lists the instructions and resources Pi loaded. The editor border indicates the current thinking level. The footer updates as the model uses context and reports usage.
 
-Use `/share` to upload a private GitHub gist with a shareable HTML link.
+Pi does not ask before every tool call. Review commands and changed files, and use a sandbox for untrusted or unattended work. See [Security](security.md).
 
-If you use pi for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets.
+## Change direction
 
-## CLI Reference
+You can send more input while Pi is working:
 
-```bash
-pi [options] [--] [@files...] [messages...]
-```
-
-### Package Commands
-
-```bash
-pi install <source> [-l]     # Install package, -l for project-local
-pi remove <source> [-l]      # Remove package
-pi uninstall <source> [-l]   # Alias for remove
-pi update [source|self|pi]   # Update pi only, or one package source
-pi update --all              # Update pi and packages; reconcile pinned git refs
-pi update --extensions       # Update packages only; reconcile pinned git refs
-pi update --models           # Refresh model catalogs only
-pi update --self             # Update pi only
-pi update --extension <src>  # Update one package
-pi list                      # List installed packages
-pi config                    # Enable/disable package resources
-```
+| What you want | Action |
+|---|---|
+| Adjust the current task | Type a message and press `Enter` |
+| Add work after the current task | Type a message and press `Alt+Enter` |
+| Return queued messages to the editor | Press `Alt+Up` |
+| Stop the current task | Press `Escape` |
 
-These commands manage pi packages and `pi update` can update the pi CLI installation. To uninstall pi itself, see [Quickstart](quickstart.md#uninstall). `pi config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `pi update` never prompts for project trust.
+A message sent with `Enter` waits until the current response and its tool calls finish, then guides the next response. A follow-up sent with `Alt+Enter` waits until Pi finishes the current task. Aborting returns queued messages to the editor.
 
-See [Pi Packages](packages.md) for package sources and security notes.
+Windows Terminal reserves some Alt shortcuts. See [Terminal Setup](terminal-setup.md) for the Windows alternatives.
 
-### Modes
+## Change the model or settings
 
-| Flag | Description |
-|------|-------------|
-| default | Interactive mode |
-| `-p`, `--print` | Print response and exit |
-| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
-| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
-| `--export <in> [out]` | Export a session to HTML |
+Type `/` to search the available commands. The commands you will use most often are:
 
-In print mode, pi also reads piped stdin and merges it into the initial prompt:
+- `/model` selects a model. Press `Ctrl+L` to open the same selector.
+- `/thinking` selects how much reasoning the current model uses. Press `Shift+Tab` to cycle through supported levels.
+- `/login` and `/logout` manage provider access.
+- `/settings` changes common preferences.
 
-```bash
-cat README.md | pi -p "Summarize this text"
-```
+Prompt templates, skills, and extensions can add more commands to the same menu. See [Choose a Model](models.md), [Configuration](configuration.md), or the complete [Slash Commands reference](slash-commands.md).
 
-### Model Options
-
-| Option | Description |
-|--------|-------------|
-| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
-| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
-| `--api-key <key>` | API key, overriding environment variables |
-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
-| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
-| `--list-models [search]` | List available models |
-
-### Session Options
-
-| Option | Description |
-|--------|-------------|
-| `-c`, `--continue` | Continue the most recent session |
-| `-r`, `--resume` | Browse and select a session |
-| `--session <path\|id>` | Use a specific session file or partial UUID |
-| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
-| `--session-dir <dir>` | Custom session storage directory |
-| `--no-session` | Ephemeral mode; do not save |
-| `--name <name>`, `-n <name>` | Set session display name at startup |
-
-### Tool Options
-
-| Option | Description |
-|--------|-------------|
-| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
-| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, extension, and custom tools |
-| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
-| `--no-tools`, `-nt` | Disable all tools |
-
-Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
-
-### Resource Options
-
-| Option | Description |
-|--------|-------------|
-| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
-| `--no-extensions` | Disable extension discovery |
-| `--skill <path>` | Load a skill; repeatable |
-| `--no-skills` | Disable skill discovery |
-| `--prompt-template <path>` | Load a prompt template; repeatable |
-| `--no-prompt-templates` | Disable prompt template discovery |
-| `--theme <path>` | Load a theme; repeatable |
-| `--no-themes` | Disable theme discovery |
-| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
-
-Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
-
-```bash
-pi --no-extensions -e ./my-extension.ts
-```
+## Continue or start over
 
-### Other Options
+Pi saves sessions automatically unless session persistence is disabled.
 
-| Option | Description |
-|--------|-------------|
-| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
-| `--append-system-prompt <text>` | Append to system prompt |
-| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
-| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
-| `--verbose` | Force verbose startup |
-| `-a`, `--approve` | Trust project-local files for this run |
-| `-na`, `--no-approve` | Ignore project-local files for this run |
-| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
-| `-h`, `--help` | Show help |
-| `-v`, `--version` | Show version |
+- `/new` starts a new session.
+- `/resume` opens another saved session.
+- `/name` gives the current session a recognizable name.
+- `/session` shows its file, ID, message count, token usage, and cost.
 
-In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, pi uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. See [Terminal setup](terminal-setup.md) for terminal-specific settings and workarounds.
+Use `/tree`, `/fork`, or `/clone` when you want to explore another approach without losing existing work. Use `/compact` to reduce the conversation history sent to the model. See [Sessions and Context](sessions.md) for these workflows.
 
-Set **TUI mode** in `/settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
+After leaving Pi, run `pi --continue` from the same folder to resume its most recent session.
 
-### File Arguments
+## Run a terminal command
 
-Prefix files with `@` to include them in the message:
+Prefix a command with `!` to run it and include its output in the conversation:
 
-```bash
-pi @prompt.md "Answer this"
-pi -p @screenshot.png "What's in this image?"
-pi @code.ts @test.ts "Review these files"
+```text
+!git status
 ```
 
-### Examples
-
-```bash
-# Interactive with initial prompt
-pi "List all .ts files in src/"
+Use `!!` when you want to run a command without sending its output to the model.
 
-# Non-interactive
-pi -p "Summarize this codebase"
+## Copy, export, or share results
 
-# Prompt beginning with a dash
-pi -p -- "- Summarize these points"
+Press `Ctrl+X` or run `/copy` to copy the last assistant response. Use `/export` to save the session as HTML or JSONL.
 
-# Non-interactive with piped stdin
-cat README.md | pi -p "Summarize this text"
+Use `/share` to upload the session and get a viewer link. With Radius authentication, the artifact is visible to your Radius organization. Otherwise, Pi creates a private GitHub gist through the GitHub CLI. Review the session first because it can contain prompts, tool output, file contents, and credentials exposed during the conversation.
 
-# Named one-shot session
-pi --name "release audit" -p "Audit this repository"
+## Adjust the terminal
 
-# Different model
-pi --provider openai --model gpt-4o "Help me refactor"
-
-# Model with provider prefix
-pi --model openai/gpt-4o "Help me refactor"
-
-# Model with thinking level shorthand
-pi --model sonnet:high "Solve this complex problem"
-
-# Limit model cycling
-pi --models "claude-*,gpt-4o"
-
-# Read-only mode
-pi --tools read,grep,find,ls -p "Review the code"
-
-# Disable one extension or built-in tool while keeping the rest available
-pi --exclude-tools ask_question
-```
+Regular mode uses the terminal's normal scrollback. Fullscreen mode keeps the editor and status area fixed while the transcript scrolls within the terminal window. Choose a mode through `/settings` or `--tui-mode`.
 
-## Design Principles
+Terminal support for mouse input, keyboard shortcuts, and inline images varies. See [Terminal Setup](terminal-setup.md) for platform-specific configuration and [Keybindings](keybindings.md) for every configurable shortcut. Run `/hotkeys` to inspect the shortcuts active in your current session.
 
-Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+## Collect diagnostic information
 
-It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+When troubleshooting terminal rendering or conversation state, run `/debug`. Pi writes the rendered terminal lines and current session messages to `pi-debug.log` in your [agent directory](configuration.md#agent-directory).
 
-For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).
+Review this file before sharing it. It can contain prompts, model responses, tool output, file contents, and terminal data.

package/docs/virtual-models.md

@@ -0,0 +1,114 @@
+# Virtual Models
+
+A virtual model is a selectable model that picks a physical model for each request. Use one to route by task, cost, or conversation state. For example, a router can send quick questions to a small model and hard problems to a large one, while the user selects a single model.
+
+Register virtual models from an [extension](extensions.md). They appear in `/model`, `--model`, scoped models, and settings like any other model. A virtual model can be listed under any provider, including one with physical models, such as `openai-codex/auto`.
+
+## Selection and dispatch
+
+A virtual model selects a model and a thinking level. A router maps that pair to a physical pair for each request:
+
+```
+selected (virtual model, virtual level)  ->  dispatched (physical model, physical level)
+jev/auto:low                             ->  anthropic/claude-sonnet-4-5:high
+```
+
+The virtual thinking level is an input to the router. Its meaning is up to the router; it need not correspond to a reasoning budget.
+
+Pi keeps the two pairs apart:
+
+| | Selection | Dispatch |
+|---|---|---|
+| Recorded in | `model_change` and `thinking_level_change` entries | Each assistant message: `provider`, `api`, `model`, `thinkingLevel` |
+| Visible as | `ctx.model`, `ctx.thinkingLevel`, `PI_MODEL`, `PI_REASONING_LEVEL`, `/model` | The assistant message of each response |
+
+Providers only receive physical models. Assistant messages name the physical model, so replaying a conversation across different physical models works the same as after a manual model switch. Resuming a session restores the virtual selection from its latest `model_change` entry. If the virtual model is no longer registered, Pi falls back to the physical model that answered last.
+
+In interactive mode, the footer shows the routed model next to the selection, for example `auto • high → gpt-5.6-luna • medium`. `/session` lists the cost for each physical model.
+
+Context usage uses the limits of the physical model that produced the latest response, even if that response came before switching to the virtual model. Without such a response, it uses the limits declared on the virtual model, if any. Compaction checks the same limits, and again the limits of the model each request is routed to. If that model's context window is too small for the conversation, Pi compacts before sending the request; the route stays as the router chose it.
+
+## Register a virtual model
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerVirtualModel({
+    provider: "router",
+    id: "auto",
+    name: "Auto",
+    thinkingLevels: ["low", "high"],
+    route(request, ctx) {
+      // Tool follow-ups and retries stay on the model that handled the turn.
+      const sticky = request.failed ?? request.previous;
+      if (request.reason !== "user" && sticky) {
+        return { model: sticky.model, thinkingLevel: sticky.thinkingLevel ?? "medium" };
+      }
+      const id = request.thinkingLevel === "high" ? "claude-sonnet-4-5" : "claude-haiku-4-5";
+      return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium" };
+    },
+  });
+}
+```
+
+- `provider` is the provider the model is listed under. It can be any provider ID. A provider can list several virtual models next to its physical ones. On a physical provider, the virtual model is available when that provider has credentials. Under an ID that no provider uses, it is always available.
+- `id` must not be the ID of a physical model of that provider. If a catalog refresh later adds a physical model with the same ID, the virtual model hides it.
+- `thinkingLevels` lists the levels offered for selection. It defaults to `["off"]`.
+- `contextWindow` and `maxTokens` are shown before the first response. Unset limits are unknown.
+- `input` lists the input types offered for selection. It defaults to text and images; physical models without image support receive placeholders.
+
+Registration follows the same queuing and reload rules as `pi.registerProvider()`. Registering the same provider and ID again replaces the virtual model. `pi.unregisterVirtualModel(provider, id)` removes it; `pi.unregisterProvider()` does not. SDK code can register one without an extension: `modelRuntime.registerVirtualModel(definition)`.
+
+## Route requests
+
+`route(request, ctx)` runs before every request made with the virtual model and returns `{ model, thinkingLevel }`. The model can be any physical model in the catalog whose provider has credentials; look it up with `ctx.modelRegistry`. A virtual model cannot route to another virtual model. Pi clamps the thinking level to the returned model.
+
+| Field | Meaning |
+|---|---|
+| `model`, `thinkingLevel` | The selected virtual model and level |
+| `reason` | Why the request is made, see below |
+| `previous` | Physical model and thinking level of the latest successful response in `messages` |
+| `failed` | For `retry`: physical model, thinking level, and assistant `message` of the failed request, which `messages` no longer contains. The message carries `stopReason` and `errorMessage`. Absent when routing itself failed |
+| `state` | Router state last returned on this session branch, see below |
+| `messages` | The conversation for this request, including system messages |
+| `signal` | Abort signal of the request |
+
+| `reason` | Request |
+|---|---|
+| `user` | First request after a message the user wrote, including steering and follow-up messages |
+| `continuation` | Any other request in the agent loop, such as after tool results or extension messages |
+| `retry` | Automatic retry after a failed request, including after compaction for a context overflow |
+| `direct` | Request made outside the agent loop, such as a compaction summary or an extension calling `ctx.modelRegistry.streamSimple()` |
+
+Returning `previous` for `continuation` and `failed` for `retry` keeps prompt caches and thinking signatures valid. Switching models between turns is allowed but loses the prompt cache. A retry can also switch to another model, for example when `failed.message.errorMessage` reports that a provider is overloaded or the context overflowed.
+
+If `route()` throws, or returns a virtual model or a model without credentials, the request ends with an error response.
+
+## Keep routing state
+
+`route()` can return `state` next to the model. Pi stores it on the session branch and passes it back as `request.state` on later requests. Use it for decisions the transcript does not record, such as classifier results or a routing phase:
+
+```typescript
+pi.registerVirtualModel<{ phase: "plan" | "build" }>({
+  provider: "router",
+  id: "phased",
+  name: "Phased",
+  route(request, ctx) {
+    const state = request.state ?? { phase: "plan" };
+    const id = state.phase === "plan" ? "claude-opus-4-5" : "claude-haiku-4-5";
+    return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium", state };
+  },
+});
+```
+
+- State must be JSON-serializable. Returning `undefined` or `request.state` itself keeps the current state.
+- Pi stores any other returned object as new state, before the request is sent, even when it equals the current state. Return a new object only when the state changes. The state stays stored if the request later fails.
+- State follows the session tree, so forks and `/tree` navigation see the state of their branch. It survives compaction.
+- `direct` requests have no state, and Pi ignores state they return.
+
+The transcript already records the selection and every dispatched model, and `ctx.sessionManager.getBranch()` exposes both.
+
+Routers can call other models through `ctx.modelRegistry`, for example `ctx.modelRegistry.classify()` with a classifier model from `ctx.modelRegistry.findOfType("classifier", provider, id)`. The call adds latency before the first token of the turn.
+
+See [`jev-router.ts`](../examples/extensions/jev-router.ts) for a complete router. It plans on a strong OpenAI Codex model chosen by the Jev classifier, lets that model make the first edit, and then switches once to a cheaper model, accepting a single prompt-cache miss. It keeps the phase as router state.

package/docs/windows.md

@@ -1,39 +1,67 @@
-# Windows Setup
+# Run Pi on Windows
 
-Pi uses Git Bash by default on Windows. Checked locations (in order):
+Run Pi either as a native Windows process or inside Windows Subsystem for Linux (WSL). Native Windows uses Git Bash by default for Bash commands and can optionally expose PowerShell to the model. Pi inside WSL uses the Linux environment and its Bash installation.
 
-1. Custom path from `~/.pi/agent/settings.json`
-2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
-3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+Follow the main [Quickstart](quickstart.md) to install and authenticate Pi. Use this page to choose and configure its command environment.
 
-For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+## Choose native Windows or WSL
 
-## PowerShell Tool
+| Environment | Command environment | Use it when |
+|---|---|---|
+| Native Windows with Git Bash | Git Bash for the built-in `bash` tool and `!` commands | Your files and development tools primarily live on Windows |
+| Native Windows with the `powershell` tool | PowerShell for model tool calls; Bash remains available for `!` commands | The task depends on PowerShell modules or Windows-native commands |
+| WSL | Linux Bash and tools inside the selected WSL distribution | Your files and toolchain already live in Linux or WSL |
 
-The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+## Use Git Bash on native Windows
 
-Use `defaultTools` to replace the model-facing `bash` tool:
+For most native Windows users, installing [Git for Windows](https://git-scm.com/download/win) is sufficient.
 
-```json
-{
-  "defaultTools": ["read", "powershell", "edit", "write"]
-}
+Pi resolves Bash in this order:
+
+1. `shellPath` from `~/.pi/agent/settings.json`
+2. Git Bash under `Program Files` or `Program Files (x86)`
+3. `bash.exe` on `PATH`, including Cygwin, MSYS2, or legacy WSL Bash
+
+Start Pi and enter this command to verify the shell:
+
+```text
+!printf 'Bash is working\n'
 ```
 
-Or enable both while comparing behavior:
+If Pi cannot find Bash, it reports the locations it checked. Install Git for Windows, put another Bash executable on `PATH`, or configure `shellPath`.
+
+## Let the model use PowerShell
+
+The optional `powershell` tool runs commands through `pwsh.exe` when available, then falls back to Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+
+To replace the model-facing `bash` tool with `powershell`, add this to `~/.pi/agent/settings.json`:
 
 ```json
 {
-  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
+  "defaultTools": ["read", "powershell", "edit", "write"]
 }
 ```
 
-The `!` and `!!` editor commands still use Bash.
+`["-bash", "+powershell"]` does the same while keeping any other default tools you configured.
+
+Restart Pi, then ask it to run a harmless PowerShell command. The `!` and `!!` editor commands continue to use Bash. The `powershell` tool is available only when Pi runs as a native Windows process.
+
+See [Settings](settings.md#tools) for other tool combinations.
+
+## Use a custom Bash executable
 
-## Custom Bash Path
+Set `shellPath` when Bash is installed somewhere Pi does not discover automatically:
 
 ```json
 {
   "shellPath": "C:\\cygwin64\\bin\\bash.exe"
 }
 ```
+
+JSON uses backslashes for escape sequences. When you write a Windows path with backslashes, write each backslash twice, as shown above.
+
+See [Configure shell commands](shell-aliases.md) for command prefixes, aliases, and the complete shell-resolution behavior.
+
+## Configure Windows Terminal
+
+Windows Terminal reserves or rewrites some modified keys. See [Windows Terminal](terminal-setup.md#windows-terminal) to configure `Shift+Enter` and `Alt+Enter`, and [Keybindings](keybindings.md) for Pi's Windows and WSL shortcut defaults.

package/examples/README.md

@@ -1,6 +1,16 @@
 # Examples
 
-Example code for pi-coding-agent SDK and extensions.
+Example code for the pi-coding-agent SDK, process integration, and extensions.
+
+## CLI integration
+
+[`rpc-client.ts`](rpc-client.ts) uses the typed `RpcClient` to run Pi in a child process, stream events, and wait for the run to settle.
+
+Build the coding-agent package before running it from a repository checkout:
+
+```bash
+node examples/rpc-client.ts "Explain this repository"
+```
 
 ## Directories
 
@@ -23,6 +33,7 @@ An experimental plugin package that Pi automatically builds into separate Sessio
 
 ## Documentation
 
-- [SDK Reference](sdk/README.md)
+- [SDK Examples](sdk/README.md)
+- [CLI Integration](../docs/cli-integration.md)
 - [Extensions Documentation](../docs/extensions.md)
 - [Skills Documentation](../docs/skills.md)

package/examples/extensions/README.md

@@ -113,6 +113,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 |-----------|-------------|
 | `message-renderer.ts` | Custom message rendering with colors and expandable details via `registerMessageRenderer` |
 | `entry-renderer.ts` | TUI-only session entry rendering via `appendEntry` and `registerEntryRenderer` |
+| `debug-provider.ts` | Toggle raw provider stream capture with `/debug-provider` and inspect each assistant message in a TUI-only session entry |
 | `event-bus.ts` | Inter-extension communication via `pi.events` |
 
 ### Session Metadata
@@ -128,6 +129,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 |-----------|-------------|
 | `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
 | `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
+| `jev-router.ts` | Virtual model via `registerVirtualModel` that plans on Codex Sol or Terra (picked by the Jev classifier) and switches to Luna after the first edit |
 
 ### External Dependencies
 

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.87.0",
+  "version": "0.99.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.87.0",
+      "version": "0.99.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }