apex-code 0.4.0 → 0.5.1

package/docs/tmux.md

@@ -1,17 +1,31 @@
-# tmux Setup
+# Run Pi in tmux
 
 Apex Code works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `Shift+Enter` and `Ctrl+Enter` are usually indistinguishable from plain `Enter`.
 
-## Recommended Configuration
+## Check your tmux version
 
-Add to `~/.tmux.conf`:
+```bash
+tmux -V
+```
+
+For tmux 3.5 or newer, use the recommended CSI-u configuration below. For tmux 3.2 through 3.4, use the older-version configuration.
+
+## Enable extended keys in tmux 3.5 or newer
+
+Add these lines to `~/.tmux.conf`:
 
 ```tmux
 set -g extended-keys on
 set -g extended-keys-format csi-u
 ```
 
-Then restart tmux fully:
+Pi requests extended-key reporting when the terminal does not provide the Kitty keyboard protocol directly. CSI-u is the most reliable format for forwarding modified keys through tmux.
+
+## Restart tmux
+
+The configuration applies to the tmux server. To guarantee that it is active, close your tmux sessions and start a new server.
+
+If you choose to stop the server from the command line, save your work first. This command terminates every session managed by that server:
 
 ```bash
 tmux kill-server
@@ -20,15 +34,23 @@ tmux
 
 Apex Code requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration. The `extended-keys-format` option requires tmux 3.5 or later.
 
-## Why `csi-u` Is Recommended
+Start Pi inside the new tmux session and check that:
+
+1. `Shift+Enter` inserts a new line in the editor.
+2. `Enter` submits the prompt.
+3. `Alt+Enter` queues a follow-up on macOS and Linux. Windows and WSL use `Ctrl+Q` by default.
+
+If these keys still behave like plain `Enter`, verify that the terminal outside tmux can report modified keys. See [Configure your terminal](terminal-setup.md).
+
+## Use tmux 3.2 through 3.4
 
-With only:
+These versions support extended keys but not `extended-keys-format csi-u`. Add only:
 
 ```tmux
 set -g extended-keys on
 ```
 
-tmux defaults to `extended-keys-format xterm`. When an application requests extended key reporting, modified keys are forwarded in xterm `modifyOtherKeys` format such as:
+Pi supports the xterm `modifyOtherKeys` format used by these versions. Restart tmux and repeat the verification steps.
 
 - `Ctrl+C` → `\x1b[27;5;99~`
 - `Ctrl+D` → `\x1b[27;5;100~`

package/docs/tui.md

@@ -4,7 +4,7 @@
 
 Extensions and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
 
-**Source:** [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui)
+**Source:** [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi/tree/main/packages/tui)
 
 ## Component Interface
 
@@ -14,6 +14,7 @@ All components implement:
 interface Component {
   render(width: number): string[];
   handleInput?(data: string): void;
+  handleMouse?(event: TuiMouseEvent): TuiMouseEventResult | undefined;
   wantsKeyRelease?: boolean;
   invalidate(): void;
 }
@@ -23,6 +24,7 @@ interface Component {
 |--------|-------------|
 | `render(width)` | Return array of strings (one per line). Each line **must not exceed `width`**. |
 | `handleInput?(data)` | Receive keyboard input when component has focus. |
+| `handleMouse?(event)` | Receive normalized pointer input in fullscreen mode. |
 | `wantsKeyRelease?` | If true, component receives key release events (Kitty protocol). Default: false. |
 | `invalidate()` | Clear cached render state. Called on theme changes. |
 
@@ -52,7 +54,7 @@ When a `Focusable` component has focus, TUI:
 3. Positions the hardware terminal cursor at that location
 4. Shows the hardware cursor only when `showHardwareCursor` is enabled
 
-The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with `showHardwareCursor`, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The `Editor` and `Input` built-in components already implement this interface.
+The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the renderer's `showHardwareCursor` constructor argument or `setShowHardwareCursor(true)`. Pi also maps `PI_HARDWARE_CURSOR=1` to this setting before it creates its renderer. The `Editor` and `Input` built-in components already implement this interface.
 
 ### Container Components with Embedded Inputs
 
@@ -246,31 +248,24 @@ container.addChild(component2);
 container.removeChild(component1);
 ```
 
-### Spacer
+`@earendil-works/pi-tui` provides the terminal component system used by Pi. Extensions use it when built-in dialogs, notifications, status text, and widgets are not enough for the interaction they need.
 
-Empty vertical space.
+Start with `ctx.ui` methods from an [extension](extensions.md#interact-with-the-user). Build a custom component only when the UI needs its own rendering, keyboard or mouse input, focus, layout, or lifecycle.
 
-```typescript
-const spacer = new Spacer(2);  // 2 empty lines
-```
-
-### Markdown
+## Choose an integration point
 
-Renders markdown with syntax highlighting.
-
-```typescript
-const md = new Markdown(
-  "# Title\n\nSome **bold** text",
-  1,        // paddingX
-  1,        // paddingY
-  theme     // MarkdownTheme (see below)
-);
-md.setText("Updated markdown");
-```
+| Need | Use |
+|---|---|
+| Select, confirm, input, or multi-line editor | `ctx.ui.select()`, `confirm()`, `input()`, or `editor()` |
+| Non-blocking feedback | `ctx.ui.notify()` or `setStatus()` |
+| Persistent content near the editor | `ctx.ui.setWidget()` |
+| Replace the header, footer, or editor | The corresponding `ctx.ui` component factory |
+| Temporary interactive screen or overlay | `ctx.ui.custom()` |
+| Custom rendering for a tool or session entry | An extension renderer |
 
-### Image
+These APIs receive Pi’s active theme and keybindings where needed. Do not create a second terminal renderer inside an extension.
 
-Renders images in supported terminals (Kitty, iTerm2, Ghostty, WezTerm, Warp).
+## Understand the component model
 
 ```typescript
 const image = new Image(
@@ -307,6 +302,22 @@ handleInput(data: string) {
 - With modifiers: `Key.ctrl("c")`, `Key.shift("tab")`, `Key.alt("left")`, `Key.ctrlShift("p")`
 - String format also works: `"enter"`, `"ctrl+c"`, `"shift+tab"`, `"ctrl+shift+p"`
 
+## Mouse Input
+
+Fullscreen mode routes normalized press, release, click, move, drag, and wheel events to components and overlays. Return `{ handled: true }` to suppress default behavior, `capture: true` to retain drag/release ownership, `focus: true` to request keyboard focus, and `render: true` when a hover or release visibly changes the component. Press, click, drag, and wheel render by default; no-op move/release events do not.
+
+```typescript
+import { MouseRegion } from "@earendil-works/pi-tui";
+
+const clickable = new MouseRegion(content, (event) => {
+  if (event.type !== "click" || event.button !== "left") return undefined;
+  expanded = !expanded;
+  return { handled: true };
+});
+```
+
+Unhandled wheel input scrolls the nearest `ScrollView`; unhandled primary-button drags retain transcript selection. OSC 8 links take precedence over parent click regions. `Input`, `Editor`, `SelectList`, and `SettingsList` include fullscreen mouse behavior. Regular mode does not capture mouse input because the terminal owns its scrollback.
+
 ## Line Width
 
 **Critical:** Each line from `render()` must not exceed the `width` parameter.
@@ -507,107 +518,51 @@ Call `invalidate()` when state changes, then use the injected `tui.requestRender
 
 When the theme changes, the TUI calls `invalidate()` on all components to clear their caches. Components must properly implement `invalidate()` to ensure theme changes take effect.
 
-### The Problem
+Every rendered line must fit within the supplied width. Measure visible terminal columns rather than string length because ANSI escapes, wide characters, emoji, and combining characters change display width.
 
-If a component pre-bakes theme colors into strings (via `theme.fg()`, `theme.bg()`, etc.) and caches them, the cached strings contain ANSI escape codes from the old theme. Simply clearing the render cache isn't enough if the component stores the themed content separately.
+Use `visibleWidth()`, `truncateToWidth()`, `sliceByColumn()`, and `wrapTextWithAnsi()` instead of implementing terminal-width handling yourself. Pi resets styling and hyperlinks after every line, so reapply styles on each rendered line.
 
-**Wrong approach** (theme colors won't update):
+After changing component state, invalidate the affected component and call the injected `tui.requestRender()`. The TUI coalesces render requests and updates the terminal.
 
-```typescript
-class BadComponent extends Container {
-  private content: Text;
+## Compose built-in components
 
-  constructor(message: string, theme: Theme) {
-    super();
-    // Pre-baked theme colors stored in Text component
-    this.content = new Text(theme.fg("accent", message), 1, 0);
-    this.addChild(this.content);
-  }
-  // No invalidate override - parent's invalidate only clears
-  // child render caches, not the pre-baked content
-}
-```
+The package includes components for common layouts and controls:
 
-### The Solution
+- `Text`, `Markdown`, `Image`, and `TruncatedText` render content.
+- `Container`, `VStack`, `HStack`, `Box`, and `Spacer` compose layouts.
+- `Input` and `Editor` accept text.
+- `SelectList` and `SettingsList` implement searchable selection and settings flows.
+- `ScrollView` provides a bounded scrollable viewport.
+- `Loader` and `CancellableLoader` report ongoing work.
+- `MouseRegion` adds pointer behavior around another component.
 
-Components that build content with theme colors must rebuild that content when `invalidate()` is called:
+Prefer these components over rebuilding selection, scrolling, text editing, or width handling. The extension examples show how to combine them with Pi’s borders and themes.
 
-```typescript
-class GoodComponent extends Container {
-  private message: string;
-  private content: Text;
+## Handle keyboard input and focus
 
-  constructor(message: string) {
-    super();
-    this.message = message;
-    this.content = new Text("", 1, 0);
-    this.addChild(this.content);
-    this.updateDisplay();
-  }
+Use `matchesKey()` and `Key` for terminal keyboard input. The parser accounts for supported terminal protocols and key modifiers. Extension components should use the injected `KeybindingsManager` for configurable application actions.
 
-  private updateDisplay(): void {
-    // Rebuild content with current theme
-    this.content.setText(theme.fg("accent", this.message));
-  }
+A component that displays a text cursor should implement `Focusable` and place `CURSOR_MARKER` immediately before its visual cursor. The TUI uses that marker to position the hardware cursor for input method editors.
 
-  override invalidate(): void {
-    super.invalidate();  // Clear child caches
-    this.updateDisplay(); // Rebuild with new theme
-  }
-}
-```
+Containers that wrap an `Input` or `Editor` must propagate their `focused` state to that child. Without propagation, Chinese, Japanese, Korean, and other IME candidate windows can appear at the wrong screen position.
 
-### Pattern: Rebuild on Invalidate
+Extend Pi’s `CustomEditor` when replacing the main editor. It preserves application shortcuts and agent controls.
 
-For components with complex content:
+Forward keys your editor does not own to the base implementation, and restore the default by clearing the custom editor factory.
 
-```typescript
-class ComplexComponent extends Container {
-  private data: SomeData;
-
-  constructor(data: SomeData) {
-    super();
-    this.data = data;
-    this.rebuild();
-  }
+## Handle mouse input
 
-  private rebuild(): void {
-    this.clear();  // Remove all children
+Fullscreen mode routes normalized mouse events to components. A handler can mark an event handled, capture a drag sequence, request focus, or request a render.
 
-    // Build UI with current theme
-    this.addChild(new Text(theme.fg("accent", theme.bold("Title")), 1, 0));
-    this.addChild(new Spacer(1));
+Unhandled wheel events scroll the nearest `ScrollView`. Unhandled primary-button drags remain available for transcript selection. OSC 8 links take precedence over enclosing click regions.
 
-    for (const item of this.data.items) {
-      const color = item.active ? "success" : "muted";
-      this.addChild(new Text(theme.fg(color, item.label), 1, 0));
-    }
-  }
+Regular mode leaves mouse input to the terminal because the terminal owns scrollback. Design every interaction with a keyboard path even when fullscreen mouse input is available.
 
-  override invalidate(): void {
-    super.invalidate();
-    this.rebuild();
-  }
-}
-```
+## Use custom screens and overlays
 
-### When This Matters
+`ctx.ui.custom()` temporarily gives one component control of the interactive area and resolves when that component calls the supplied completion callback.
 
-This pattern is needed when:
-
-1. **Pre-baking theme colors** - Using `theme.fg()` or `theme.bg()` to create styled strings stored in child components
-2. **Syntax highlighting** - Using `highlightCode()` which applies theme-based syntax colors
-3. **Complex layouts** - Building child component trees that embed theme colors
-
-This pattern is NOT needed when:
-
-1. **Using theme callbacks** - Passing functions like `(text) => theme.fg("accent", text)` that are called during render
-2. **Simple containers** - Just grouping other components without adding themed content
-3. **Stateless render** - Computing themed output fresh in every `render()` call (no caching)
-
-## Common Patterns
-
-These patterns cover the most common UI needs in extensions. **Copy these patterns instead of building from scratch.**
+Pass `overlay: true` to draw above existing content. Overlay options control size, anchors, offsets, margins, and responsive visibility. An overlay handle can change focus or temporarily hide and show the overlay with `setHidden()` while the interaction remains active.
 
 ### Pattern 1: Selection Dialog (SelectList)
 
@@ -690,16 +645,9 @@ pi.registerCommand("fetch", {
       return loader;
     });
 
-    if (result === null) {
-      ctx.ui.notify("Cancelled", "info");
-    } else {
-      ctx.ui.setEditorText(result);
-    }
-  },
-});
-```
+Treat each custom component instance as belonging to one interaction. Create a new instance when starting that interaction again.
 
-**Examples:** [qna.ts](../examples/extensions/qna.ts), [handoff.ts](../examples/extensions/handoff.ts)
+Finish the interaction with the completion callback supplied to the component factory. It resolves the `ctx.ui.custom()` promise and disposes the component. Do not call `OverlayHandle.hide()` on an overlay created by `ctx.ui.custom()`.
 
 ### Pattern 3: Settings/Toggles (SettingsList)
 
@@ -745,19 +693,15 @@ pi.registerCommand("settings", {
 
 **Examples:** [tools.ts](../examples/extensions/tools.ts)
 
-### Pattern 4: Persistent Status Indicator
+## Apply themes correctly
 
-Show status in the footer that persists across renders. Good for mode indicators.
+Use the theme passed to the extension or component callback. Theme helpers produce ANSI-styled strings for semantic colors such as accent, muted text, success, warnings, errors, tool output, and Markdown.
 
-```typescript
-// Set status (shown in footer)
-ctx.ui.setStatus("my-ext", ctx.ui.theme.fg("accent", "● active"));
+Do not permanently store strings with theme colors unless `invalidate()` rebuilds them. A theme change clears render caches, but it cannot remove old ANSI colors embedded in application state.
 
-// Clear status
-ctx.ui.setStatus("my-ext", undefined);
-```
+Theme callbacks evaluated during rendering do not need special rebuilding. Stateless components can also calculate themed output on every render.
 
-**Examples:** [status-line.ts](../examples/extensions/status-line.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts)
+Use [Themes](themes.md) to create terminal palettes. Use Pi’s `getMarkdownTheme()` when rendering Markdown that should match the active application theme.
 
 ### Pattern 4b: Working Indicator Customization
 
@@ -912,6 +856,7 @@ export default function (pi: ExtensionAPI) {
 
 - **Extend `CustomEditor`** (not base `Editor`) to get app keybindings (escape to abort, ctrl+d to exit, model switching, etc.)
 - **Call `super.handleInput(data)`** for keys you don't handle
+- **Status spinners**: custom editors keep standalone status rows by default. Pass `{ embedWorkingStatus: true }` as the fourth `CustomEditor` constructor argument to embed working, compaction, branch summarization, and retry spinners in the editor border instead.
 - **Factory pattern**: `setEditorComponent` receives a factory function that gets `tui`, `theme`, and `keybindings`
 - **Pass `undefined`** to restore the default editor: `ctx.ui.setEditorComponent(undefined)`
 

package/docs/usage.md

@@ -1,38 +1,28 @@
 # Using Apex Code
 
-This page collects day-to-day usage details that do not fit on the quickstart page.
+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).
 
-## Interactive Mode
+Pi may ask whether you trust the working folder before loading its project resources. See [Project trust](security.md#understand-project-trust).
 
-<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+<p align="center"><img src="images/interactive-mode.png" alt="Pi interactive mode showing a conversation, editor, and status information" width="750"></p>
 
-The interface has four main areas:
+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.
 
-- **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.
+## Enter a prompt
 
-The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
+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.
 
-### Editor Features
+To include files or images:
 
-| 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 |
+- 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.
 
-See [Keybindings](keybindings.md) for all shortcuts and customization.
+## Follow Pi's work
 
-## Slash Commands
+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.
 
-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`.
+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.
 
 | Command | Description |
 |---------|-------------|
@@ -55,25 +45,28 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/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 Apex Code |
 
-## Message Queue
+## Change direction
 
-You can submit messages while the agent is still working:
+You can send more input while Pi is 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.
+| 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` |
 
 On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want Apex Code to receive the shortcut.
 
-Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+Windows Terminal reserves some Alt shortcuts. See [Terminal Setup](terminal-setup.md) for the Windows alternatives.
 
-## Sessions
+## Change the model or settings
 
 Sessions are saved automatically to `~/.apex-code/agent/sessions/`, organized by working directory.
 
@@ -86,17 +79,13 @@ apex-code --session <path|id> # Use a specific session file or session ID
 apex-code --fork <path|id>    # Fork a session into a new session file
 ```
 
-Useful session commands:
+Use `!!` when you want to run a command without sending its output to the model.
 
-- `/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.
+## Copy, export, or share results
 
-See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+Press `Ctrl+X` or run `/copy` to copy the last assistant response. Use `/export` to save the session as HTML or JSONL.
 
-## Context Files
+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.
 
 Apex Code loads `AGENTS.md` or `CLAUDE.md` at startup from:
 
@@ -106,9 +95,9 @@ Apex Code loads `AGENTS.md` or `CLAUDE.md` at startup from:
 
 If a directory contains `AGENTS.override.md`, Apex Code 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`.
+## Collect diagnostic information
 
-### System Prompt Files
+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).
 
 Replace the default system prompt with:
 
@@ -277,7 +266,7 @@ apex-code "List all .ts files in src/"
 apex-code -p "Summarize this codebase"
 
 # Prompt beginning with a dash
-pi -p -- "- Summarize these points"
+apex-code -p -- "- Summarize these points"
 
 # Non-interactive with piped stdin
 cat README.md | apex-code -p "Summarize this text"

package/docs/windows.md

@@ -1,4 +1,4 @@
-# Windows Setup
+# Run Pi on Windows
 
 Apex Code uses Git Bash by default on Windows. Checked locations (in order):
 
@@ -6,34 +6,62 @@ Apex Code uses Git Bash by default on Windows. Checked locations (in order):
 2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
 3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
 
-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 `~/.apex-code/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 `~/.apex-code/agent/settings.json`:
 
 ```json
 {
-  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
+  "defaultTools": ["read", "powershell", "edit", "write"]
 }
 ```
 
-The `!` and `!!` editor commands still use Bash.
+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
+npx tsx examples/rpc-client.ts "Explain this repository"
+```
 
 ## Directories
 
@@ -18,8 +28,12 @@ Example extensions demonstrating:
 - External integrations (SSH, file watchers, system theme sync)
 - Custom providers (Anthropic with custom streaming, GitLab Duo)
 
+### [plugins/pi-example-plugin/](plugins/pi-example-plugin/)
+An experimental plugin package that Pi automatically builds into separate Session-worker and TUI Chord facets.
+
 ## 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

@@ -36,7 +36,6 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
 | `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
 | `dynamic-tools.ts` | Register tools after startup (`session_start`) and at runtime via command, with prompt snippets and tool-specific prompt guidelines |
-| `kimi-deferred-tools.ts` | Search for and progressively activate tools for Kimi's deferred-tool loading protocol |
 | `structured-output.ts` | Final structured-output tool that returns `terminate: true` so the agent can end on the tool call |
 | `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |