@mariozechner/pi-coding-agent 0.49.3 → 0.50.1

package/docs/development.md

@@ -0,0 +1,69 @@
+# Development
+
+See [AGENTS.md](../../../AGENTS.md) for additional guidelines.
+
+## Setup
+
+```bash
+git clone https://github.com/badlogic/pi-mono
+cd pi-mono
+npm install
+npm run build
+```
+
+Run from source:
+
+```bash
+./pi-test.sh
+```
+
+## Forking / Rebranding
+
+Configure via `package.json`:
+
+```json
+{
+  "piConfig": {
+    "name": "pi",
+    "configDir": ".pi"
+  }
+}
+```
+
+Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
+
+## Path Resolution
+
+Three execution modes: npm install, standalone binary, tsx from source.
+
+**Always use `src/config.ts`** for package assets:
+
+```typescript
+import { getPackageDir, getThemeDir } from "./config.js";
+```
+
+Never use `__dirname` directly for package assets.
+
+## Debug Command
+
+`/debug` (hidden) writes to `~/.pi/agent/pi-debug.log`:
+- Rendered TUI lines with ANSI codes
+- Last messages sent to the LLM
+
+## Testing
+
+```bash
+./test.sh                         # Run non-LLM tests (no API keys needed)
+npm test                          # Run all tests
+npm test -- test/specific.test.ts # Run specific test
+```
+
+## Project Structure
+
+```
+packages/
+  ai/           # LLM provider abstraction
+  agent/        # Agent loop and message types  
+  tui/          # Terminal UI components
+  coding-agent/ # CLI and interactive mode
+```

package/docs/extensions.md

@@ -4,6 +4,8 @@
 
 Extensions are TypeScript modules that extend pi's behavior. They can subscribe to lifecycle events, register custom tools callable by the LLM, add commands, and more.
 
+> **Placement for /reload:** Put extensions in `~/.pi/agent/extensions/` (global) or `.pi/extensions/` (project-local) for auto-discovery. Use `pi -e ./path.ts` only for quick tests. Extensions in auto-discovered locations can be hot-reloaded with `/reload`.
+
 **Key capabilities:**
 - **Custom tools** - Register tools the LLM can call via `pi.registerTool()`
 - **Event interception** - Block or modify tool calls, inject context, customize compaction
@@ -46,6 +48,7 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
 - [Custom UI](#custom-ui)
 - [Error Handling](#error-handling)
 - [Mode Behavior](#mode-behavior)
+- [Examples Reference](#examples-reference)
 
 ## Quick Start
 
@@ -102,6 +105,8 @@ pi -e ./my-extension.ts
 
 ## Extension Locations
 
+> **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
+
 Extensions are auto-discovered from:
 
 | Location | Scope |
@@ -115,47 +120,18 @@ Additional paths via `settings.json`:
 
 ```json
 {
-  "extensions": ["/path/to/extension.ts", "/path/to/extension/dir"]
-}
-```
-
-**Discovery rules:**
-
-1. **Direct files:** `extensions/*.ts` or `*.js` → loaded directly
-2. **Subdirectory with index:** `extensions/myext/index.ts` → loaded as single extension
-3. **Subdirectory with package.json:** `extensions/myext/package.json` with `"pi"` field → loads declared paths
-
-```
-~/.pi/agent/extensions/
-├── simple.ts                      # Direct file (auto-discovered)
-├── my-tool/
-│   └── index.ts                   # Subdirectory with index (auto-discovered)
-└── my-extension-pack/
-    ├── package.json               # Declares multiple extensions
-    ├── node_modules/              # Dependencies installed here
-    └── src/
-        ├── safety-gates.ts        # First extension
-        └── custom-tools.ts        # Second extension
-```
-
-```json
-// my-extension-pack/package.json
-{
-  "name": "my-extension-pack",
-  "dependencies": {
-    "zod": "^3.0.0"
-  },
-  "pi": {
-    "extensions": ["./src/safety-gates.ts", "./src/custom-tools.ts"]
-  }
+  "packages": [
+    "npm:@foo/bar@1.0.0",
+    "git:github.com/user/repo@v1"
+  ],
+  "extensions": [
+    "/path/to/local/extension.ts",
+    "/path/to/local/extension/dir"
+  ]
 }
 ```
 
-The `package.json` approach enables:
-- Multiple extensions from one package
-- Third-party npm dependencies (resolved via jiti)
-- Nested source structure (no depth limit within the package)
-- Deployment to and installation from npm
+To share extensions via npm or git as pi packages, see [packages.md](packages.md).
 
 ## Available Imports
 
@@ -303,6 +279,8 @@ exit (Ctrl+C, Ctrl+D)
 
 ### Session Events
 
+See [session.md](session.md) for session storage internals and the SessionManager API.
+
 #### session_start
 
 Fired on initial session load.
@@ -313,8 +291,6 @@ pi.on("session_start", async (_event, ctx) => {
 });
 ```
 
-**Examples:** [claude-rules.ts](../examples/extensions/claude-rules.ts), [custom-header.ts](../examples/extensions/custom-header.ts), [file-trigger.ts](../examples/extensions/file-trigger.ts), [status-line.ts](../examples/extensions/status-line.ts), [todo.ts](../examples/extensions/todo.ts), [tools.ts](../examples/extensions/tools.ts)
-
 #### session_before_switch / session_switch
 
 Fired when starting a new session (`/new`) or switching sessions (`/resume`).
@@ -336,8 +312,6 @@ pi.on("session_switch", async (event, ctx) => {
 });
 ```
 
-**Examples:** [confirm-destructive.ts](../examples/extensions/confirm-destructive.ts), [dirty-repo-guard.ts](../examples/extensions/dirty-repo-guard.ts), [status-line.ts](../examples/extensions/status-line.ts), [todo.ts](../examples/extensions/todo.ts)
-
 #### session_before_fork / session_fork
 
 Fired when forking via `/fork`.
@@ -355,8 +329,6 @@ pi.on("session_fork", async (event, ctx) => {
 });
 ```
 
-**Examples:** [confirm-destructive.ts](../examples/extensions/confirm-destructive.ts), [dirty-repo-guard.ts](../examples/extensions/dirty-repo-guard.ts), [git-checkpoint.ts](../examples/extensions/git-checkpoint.ts), [todo.ts](../examples/extensions/todo.ts), [tools.ts](../examples/extensions/tools.ts)
-
 #### session_before_compact / session_compact
 
 Fired on compaction. See [compaction.md](compaction.md) for details.
@@ -384,11 +356,9 @@ pi.on("session_compact", async (event, ctx) => {
 });
 ```
 
-**Examples:** [custom-compaction.ts](../examples/extensions/custom-compaction.ts), [trigger-compact.ts](../examples/extensions/trigger-compact.ts)
-
 #### session_before_tree / session_tree
 
-Fired on `/tree` navigation.
+Fired on `/tree` navigation. See [tree.md](tree.md) for tree navigation concepts.
 
 ```typescript
 pi.on("session_before_tree", async (event, ctx) => {
@@ -403,8 +373,6 @@ pi.on("session_tree", async (event, ctx) => {
 });
 ```
 
-**Examples:** [todo.ts](../examples/extensions/todo.ts), [tools.ts](../examples/extensions/tools.ts)
-
 #### session_shutdown
 
 Fired on exit (Ctrl+C, Ctrl+D, SIGTERM).
@@ -415,8 +383,6 @@ pi.on("session_shutdown", async (_event, ctx) => {
 });
 ```
 
-**Examples:** [auto-commit-on-exit.ts](../examples/extensions/auto-commit-on-exit.ts)
-
 ### Agent Events
 
 #### before_agent_start
@@ -442,8 +408,6 @@ pi.on("before_agent_start", async (event, ctx) => {
 });
 ```
 
-**Examples:** [claude-rules.ts](../examples/extensions/claude-rules.ts), [pirate.ts](../examples/extensions/pirate.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts), [ssh.ts](../examples/extensions/ssh.ts)
-
 #### agent_start / agent_end
 
 Fired once per user prompt.
@@ -456,8 +420,6 @@ pi.on("agent_end", async (event, ctx) => {
 });
 ```
 
-**Examples:** [chalk-logger.ts](../examples/extensions/chalk-logger.ts), [git-checkpoint.ts](../examples/extensions/git-checkpoint.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts)
-
 #### turn_start / turn_end
 
 Fired for each turn (one LLM response + tool calls).
@@ -472,11 +434,9 @@ pi.on("turn_end", async (event, ctx) => {
 });
 ```
 
-**Examples:** [git-checkpoint.ts](../examples/extensions/git-checkpoint.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [status-line.ts](../examples/extensions/status-line.ts)
-
 #### context
 
-Fired before each LLM call. Modify messages non-destructively.
+Fired before each LLM call. Modify messages non-destructively. See [session.md](session.md) for message types.
 
 ```typescript
 pi.on("context", async (event, ctx) => {
@@ -486,8 +446,6 @@ pi.on("context", async (event, ctx) => {
 });
 ```
 
-**Examples:** [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts)
-
 ### Model Events
 
 #### model_select
@@ -499,20 +457,18 @@ pi.on("model_select", async (event, ctx) => {
   // event.model - newly selected model
   // event.previousModel - previous model (undefined if first selection)
   // event.source - "set" | "cycle" | "restore"
-  
-  const prev = event.previousModel 
-    ? `${event.previousModel.provider}/${event.previousModel.id}` 
+
+  const prev = event.previousModel
+    ? `${event.previousModel.provider}/${event.previousModel.id}`
     : "none";
   const next = `${event.model.provider}/${event.model.id}`;
-  
+
   ctx.ui.notify(`Model changed (${event.source}): ${prev} -> ${next}`, "info");
 });
 ```
 
 Use this to update UI elements (status bars, footers) or perform model-specific initialization when the active model changes.
 
-**Examples:** [model-status.ts](../examples/extensions/model-status.ts)
-
 ### Tool Events
 
 #### tool_call
@@ -531,8 +487,6 @@ pi.on("tool_call", async (event, ctx) => {
 });
 ```
 
-**Examples:** [chalk-logger.ts](../examples/extensions/chalk-logger.ts), [permission-gate.ts](../examples/extensions/permission-gate.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [protected-paths.ts](../examples/extensions/protected-paths.ts)
-
 #### tool_result
 
 Fired after tool executes. **Can modify result.**
@@ -553,8 +507,6 @@ pi.on("tool_result", async (event, ctx) => {
 });
 ```
 
-**Examples:** [git-checkpoint.ts](../examples/extensions/git-checkpoint.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts)
-
 ### User Bash Events
 
 #### user_bash
@@ -575,8 +527,6 @@ pi.on("user_bash", (event, ctx) => {
 });
 ```
 
-**Examples:** [ssh.ts](../examples/extensions/ssh.ts), [interactive-shell.ts](../examples/extensions/interactive-shell.ts)
-
 ### Input Events
 
 #### input
@@ -643,7 +593,7 @@ Current working directory.
 
 ### ctx.sessionManager
 
-Read-only access to session state:
+Read-only access to session state. See [session.md](session.md) for the full SessionManager API and entry types.
 
 ```typescript
 ctx.sessionManager.getEntries()       // All entries
@@ -811,8 +761,6 @@ pi.registerTool({
 });
 ```
 
-**Examples:** [hello.ts](../examples/extensions/hello.ts), [question.ts](../examples/extensions/question.ts), [questionnaire.ts](../examples/extensions/questionnaire.ts), [todo.ts](../examples/extensions/todo.ts), [truncated-tool.ts](../examples/extensions/truncated-tool.ts)
-
 ### pi.sendMessage(message, options?)
 
 Inject a custom message into the session.
@@ -836,8 +784,6 @@ pi.sendMessage({
   - `"nextTurn"` - Queued for next user prompt. Does not interrupt or trigger anything.
 - `triggerTurn: true` - If agent is idle, trigger an LLM response immediately. Only applies to `"steer"` and `"followUp"` modes (ignored for `"nextTurn"`).
 
-**Examples:** [file-trigger.ts](../examples/extensions/file-trigger.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts)
-
 ### pi.sendUserMessage(content, options?)
 
 Send a user message to the agent. Unlike `sendMessage()` which sends custom messages, this sends an actual user message that appears as if typed by the user. Always triggers a turn.
@@ -883,8 +829,6 @@ pi.on("session_start", async (_event, ctx) => {
 });
 ```
 
-**Examples:** [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts), [snake.ts](../examples/extensions/snake.ts), [tools.ts](../examples/extensions/tools.ts)
-
 ### pi.setSessionName(name)
 
 Set the session display name (shown in session selector instead of first message).
@@ -954,15 +898,13 @@ pi.registerCommand("deploy", {
 });
 ```
 
-**Examples:** [custom-footer.ts](../examples/extensions/custom-footer.ts), [custom-header.ts](../examples/extensions/custom-header.ts), [handoff.ts](../examples/extensions/handoff.ts), [pirate.ts](../examples/extensions/pirate.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts), [qna.ts](../examples/extensions/qna.ts), [send-user-message.ts](../examples/extensions/send-user-message.ts), [snake.ts](../examples/extensions/snake.ts), [summarize.ts](../examples/extensions/summarize.ts), [todo.ts](../examples/extensions/todo.ts), [tools.ts](../examples/extensions/tools.ts)
-
 ### pi.registerMessageRenderer(customType, renderer)
 
 Register a custom TUI renderer for messages with your `customType`. See [Custom UI](#custom-ui).
 
 ### pi.registerShortcut(shortcut, options)
 
-Register a keyboard shortcut.
+Register a keyboard shortcut. See [keybindings.md](keybindings.md) for the shortcut format and built-in keybindings.
 
 ```typescript
 pi.registerShortcut("ctrl+shift+p", {
@@ -973,8 +915,6 @@ pi.registerShortcut("ctrl+shift+p", {
 });
 ```
 
-**Examples:** [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts)
-
 ### pi.registerFlag(name, options)
 
 Register a CLI flag.
@@ -992,8 +932,6 @@ if (pi.getFlag("--plan")) {
 }
 ```
 
-**Examples:** [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts)
-
 ### pi.exec(command, args, options?)
 
 Execute a shell command.
@@ -1003,8 +941,6 @@ const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
 // result.stdout, result.stderr, result.code, result.killed
 ```
 
-**Examples:** [auto-commit-on-exit.ts](../examples/extensions/auto-commit-on-exit.ts), [dirty-repo-guard.ts](../examples/extensions/dirty-repo-guard.ts), [git-checkpoint.ts](../examples/extensions/git-checkpoint.ts)
-
 ### pi.getActiveTools() / pi.getAllTools() / pi.setActiveTools(names)
 
 Manage active tools.
@@ -1016,11 +952,9 @@ const names = all.map(t => t.name);  // Just names if needed
 pi.setActiveTools(["read", "bash"]); // Switch to read-only
 ```
 
-**Examples:** [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts), [tools.ts](../examples/extensions/tools.ts)
-
 ### pi.setModel(model)
 
-Set the current model. Returns `false` if no API key is available for the model.
+Set the current model. Returns `false` if no API key is available for the model. See [models.md](models.md) for configuring custom models.
 
 ```typescript
 const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
@@ -1032,8 +966,6 @@ if (model) {
 }
 ```
 
-**Examples:** [preset.ts](../examples/extensions/preset.ts)
-
 ### pi.getThinkingLevel() / pi.setThinkingLevel(level)
 
 Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off").
@@ -1043,8 +975,6 @@ const current = pi.getThinkingLevel();  // "off" | "minimal" | "low" | "medium"
 pi.setThinkingLevel("high");
 ```
 
-**Examples:** [preset.ts](../examples/extensions/preset.ts)
-
 ### pi.events
 
 Shared event bus for communication between extensions:
@@ -1054,6 +984,70 @@ pi.events.on("my:event", (data) => { ... });
 pi.events.emit("my:event", { ... });
 ```
 
+### pi.registerProvider(name, config)
+
+Register or override a model provider dynamically. Useful for proxies, custom endpoints, or team-wide model configurations.
+
+```typescript
+// Register a new provider with custom models
+pi.registerProvider("my-proxy", {
+  baseUrl: "https://proxy.example.com",
+  apiKey: "PROXY_API_KEY",  // env var name or literal
+  api: "anthropic-messages",
+  models: [
+    {
+      id: "claude-sonnet-4-20250514",
+      name: "Claude 4 Sonnet (proxy)",
+      reasoning: false,
+      input: ["text", "image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 16384
+    }
+  ]
+});
+
+// Override baseUrl for an existing provider (keeps all models)
+pi.registerProvider("anthropic", {
+  baseUrl: "https://proxy.example.com"
+});
+
+// Register provider with OAuth support for /login
+pi.registerProvider("corporate-ai", {
+  baseUrl: "https://ai.corp.com",
+  api: "openai-responses",
+  models: [...],
+  oauth: {
+    name: "Corporate AI (SSO)",
+    async login(callbacks) {
+      // Custom OAuth flow
+      callbacks.onAuth({ url: "https://sso.corp.com/..." });
+      const code = await callbacks.onPrompt({ message: "Enter code:" });
+      return { refresh: code, access: code, expires: Date.now() + 3600000 };
+    },
+    async refreshToken(credentials) {
+      // Refresh logic
+      return credentials;
+    },
+    getApiKey(credentials) {
+      return credentials.access;
+    }
+  }
+});
+```
+
+**Config options:**
+- `baseUrl` - API endpoint URL. Required when defining models.
+- `apiKey` - API key or environment variable name. Required when defining models (unless `oauth` provided).
+- `api` - API type: `"anthropic-messages"`, `"openai-completions"`, `"openai-responses"`, etc.
+- `headers` - Custom headers to include in requests.
+- `authHeader` - If true, adds `Authorization: Bearer` header automatically.
+- `models` - Array of model definitions. If provided, replaces all existing models for this provider.
+- `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
+- `streamSimple` - Custom streaming implementation for non-standard APIs.
+
+See [custom-provider.md](custom-provider.md) for advanced topics: custom streaming APIs, OAuth details, model definition reference.
+
 ## State Management
 
 Extensions with state should store it in tool result `details` for proper branching support:
@@ -1214,6 +1208,7 @@ The built-in limit is **50KB** (~10k tokens) and **2000 lines**, whichever is hi
 import {
   truncateHead,      // Keep first N lines/bytes (good for file reads, search results)
   truncateTail,      // Keep last N lines/bytes (good for logs, command output)
+  truncateLine,      // Truncate a single line to maxBytes with ellipsis
   formatSize,        // Human-readable size (e.g., "50KB", "1.5MB")
   DEFAULT_MAX_BYTES, // 50KB
   DEFAULT_MAX_LINES, // 2000
@@ -1272,7 +1267,7 @@ export default function (pi: ExtensionAPI) {
 
 ### Custom Rendering
 
-Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API.
+Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how built-in tools render.
 
 Tool output is wrapped in a `Box` that handles padding and background. Your render methods return `Component` instances (typically `Text`).
 
@@ -1388,12 +1383,6 @@ const text = await ctx.ui.editor("Edit:", "prefilled text");
 ctx.ui.notify("Done!", "info");  // "info" | "warning" | "error"
 ```
 
-**Examples:**
-- `ctx.ui.select()`: [confirm-destructive.ts](../examples/extensions/confirm-destructive.ts), [dirty-repo-guard.ts](../examples/extensions/dirty-repo-guard.ts), [git-checkpoint.ts](../examples/extensions/git-checkpoint.ts), [permission-gate.ts](../examples/extensions/permission-gate.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [question.ts](../examples/extensions/question.ts), [questionnaire.ts](../examples/extensions/questionnaire.ts)
-- `ctx.ui.confirm()`: [confirm-destructive.ts](../examples/extensions/confirm-destructive.ts)
-- `ctx.ui.editor()`: [handoff.ts](../examples/extensions/handoff.ts)
-- `ctx.ui.setEditorText()`: [handoff.ts](../examples/extensions/handoff.ts), [qna.ts](../examples/extensions/qna.ts)
-
 #### Timed Dialogs with Countdown
 
 Dialogs support a `timeout` option that auto-dismisses with a live countdown display:
@@ -1481,7 +1470,7 @@ const current = ctx.ui.getEditorText();
 ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
 ctx.ui.setEditorComponent(undefined);  // Restore default editor
 
-// Theme management
+// Theme management (see themes.md for creating themes)
 const themes = ctx.ui.getAllThemes();  // [{ name: "dark", path: "/..." | undefined }, ...]
 const lightTheme = ctx.ui.getTheme("light");  // Load without switching
 const result = ctx.ui.setTheme("light");  // Switch by name
@@ -1492,14 +1481,6 @@ ctx.ui.setTheme(lightTheme!);  // Or switch by Theme object
 ctx.ui.theme.fg("accent", "styled text");  // Access current theme
 ```
 
-**Examples:**
-- `ctx.ui.setStatus()`: [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts), [status-line.ts](../examples/extensions/status-line.ts)
-- `ctx.ui.setWidget()`: [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts)
-- `ctx.ui.setFooter()`: [custom-footer.ts](../examples/extensions/custom-footer.ts)
-- `ctx.ui.setHeader()`: [custom-header.ts](../examples/extensions/custom-header.ts)
-- `ctx.ui.setEditorComponent()`: [modal-editor.ts](../examples/extensions/modal-editor.ts)
-- `ctx.ui.setTheme()`: [mac-system-theme.ts](../examples/extensions/mac-system-theme.ts)
-
 ### Custom Components
 
 For complex UI, use `ctx.ui.custom()`. This temporarily replaces the editor with your component until `done()` is called:
@@ -1558,8 +1539,6 @@ const result = await ctx.ui.custom<string | null>(
 
 See [tui.md](tui.md) for the full `OverlayOptions` API and [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for examples.
 
-**Examples:** [handoff.ts](../examples/extensions/handoff.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts), [qna.ts](../examples/extensions/qna.ts), [snake.ts](../examples/extensions/snake.ts), [summarize.ts](../examples/extensions/summarize.ts), [todo.ts](../examples/extensions/todo.ts), [tools.ts](../examples/extensions/tools.ts), [overlay-test.ts](../examples/extensions/overlay-test.ts)
-
 ### Custom Editor
 
 Replace the main input editor with a custom implementation (vim mode, emacs mode, etc.):
@@ -1601,8 +1580,6 @@ export default function (pi: ExtensionAPI) {
 
 See [tui.md](tui.md) Pattern 7 for a complete example with mode indicator.
 
-**Examples:** [modal-editor.ts](../examples/extensions/modal-editor.ts)
-
 ### Message Rendering
 
 Register a custom renderer for messages with your `customType`:
@@ -1636,7 +1613,7 @@ pi.sendMessage({
 
 ### Theme Colors
 
-All render functions receive a `theme` object:
+All render functions receive a `theme` object. See [themes.md](themes.md) for creating custom themes and the full color palette.
 
 ```typescript
 // Foreground colors
@@ -1654,6 +1631,19 @@ theme.italic(text)
 theme.strikethrough(text)
 ```
 
+For syntax highlighting in custom tool renderers:
+
+```typescript
+import { highlightCode, getLanguageFromPath } from "@mariozechner/pi-coding-agent";
+
+// Highlight code with explicit language
+const highlighted = highlightCode("const x = 1;", "typescript", theme);
+
+// Auto-detect language from file path
+const lang = getLanguageFromPath("/path/to/file.rs");  // "rust"
+const highlighted = highlightCode(code, lang, theme);
+```
+
 ## Error Handling
 
 - Extension errors are logged, agent continues
@@ -1665,7 +1655,81 @@ theme.strikethrough(text)
 | Mode | UI Methods | Notes |
 |------|-----------|-------|
 | Interactive | Full TUI | Normal operation |
-| RPC | JSON protocol | Host handles UI |
+| RPC (`--mode rpc`) | JSON protocol | Host handles UI, see [rpc.md](rpc.md) |
+| JSON (`--mode json`) | No-op | Event stream to stdout, see [json.md](json.md) |
 | Print (`-p`) | No-op | Extensions run but can't prompt |
 
-In print mode, check `ctx.hasUI` before using UI methods.
+In non-interactive modes, check `ctx.hasUI` before using UI methods.
+
+## Examples Reference
+
+All examples in [examples/extensions/](../examples/extensions/).
+
+| Example | Description | Key APIs |
+|---------|-------------|----------|
+| **Tools** |||
+| `hello.ts` | Minimal tool registration | `registerTool` |
+| `question.ts` | Tool with user interaction | `registerTool`, `ui.select` |
+| `questionnaire.ts` | Multi-step wizard tool | `registerTool`, `ui.custom` |
+| `todo.ts` | Stateful tool with persistence | `registerTool`, `appendEntry`, `renderResult`, session events |
+| `truncated-tool.ts` | Output truncation example | `registerTool`, `truncateHead` |
+| `tool-override.ts` | Override built-in read tool | `registerTool` (same name as built-in) |
+| **Commands** |||
+| `pirate.ts` | Modify system prompt per-turn | `registerCommand`, `before_agent_start` |
+| `summarize.ts` | Conversation summary command | `registerCommand`, `ui.custom` |
+| `handoff.ts` | Cross-provider model handoff | `registerCommand`, `ui.editor`, `ui.custom` |
+| `qna.ts` | Q&A with custom UI | `registerCommand`, `ui.custom`, `setEditorText` |
+| `send-user-message.ts` | Inject user messages | `registerCommand`, `sendUserMessage` |
+| `shutdown-command.ts` | Graceful shutdown command | `registerCommand`, `shutdown()` |
+| **Events & Gates** |||
+| `permission-gate.ts` | Block dangerous commands | `on("tool_call")`, `ui.confirm` |
+| `protected-paths.ts` | Block writes to specific paths | `on("tool_call")` |
+| `confirm-destructive.ts` | Confirm session changes | `on("session_before_switch")`, `on("session_before_fork")` |
+| `dirty-repo-guard.ts` | Warn on dirty git repo | `on("session_before_*")`, `exec` |
+| `input-transform.ts` | Transform user input | `on("input")` |
+| `model-status.ts` | React to model changes | `on("model_select")`, `setStatus` |
+| `claude-rules.ts` | Load rules from files | `on("session_start")`, `on("before_agent_start")` |
+| `file-trigger.ts` | File watcher triggers messages | `sendMessage` |
+| **Compaction & Sessions** |||
+| `custom-compaction.ts` | Custom compaction summary | `on("session_before_compact")` |
+| `trigger-compact.ts` | Trigger compaction manually | `compact()` |
+| `git-checkpoint.ts` | Git stash on turns | `on("turn_end")`, `on("session_fork")`, `exec` |
+| `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |
+| **UI Components** |||
+| `status-line.ts` | Footer status indicator | `setStatus`, session events |
+| `custom-footer.ts` | Replace footer entirely | `registerCommand`, `setFooter` |
+| `custom-header.ts` | Replace startup header | `on("session_start")`, `setHeader` |
+| `modal-editor.ts` | Vim-style modal editor | `setEditorComponent`, `CustomEditor` |
+| `rainbow-editor.ts` | Custom editor styling | `setEditorComponent` |
+| `widget-placement.ts` | Widget above/below editor | `setWidget` |
+| `overlay-test.ts` | Overlay components | `ui.custom` with overlay options |
+| `overlay-qa-tests.ts` | Comprehensive overlay tests | `ui.custom`, all overlay options |
+| `notify.ts` | Simple notifications | `ui.notify` |
+| `timed-confirm.ts` | Dialogs with timeout | `ui.confirm` with timeout/signal |
+| `mac-system-theme.ts` | Auto-switch theme | `setTheme`, `exec` |
+| **Complex Extensions** |||
+| `plan-mode/` | Full plan mode implementation | All event types, `registerCommand`, `registerShortcut`, `registerFlag`, `setStatus`, `setWidget`, `sendMessage`, `setActiveTools` |
+| `preset.ts` | Saveable presets (model, tools, thinking) | `registerCommand`, `registerShortcut`, `registerFlag`, `setModel`, `setActiveTools`, `setThinkingLevel`, `appendEntry` |
+| `tools.ts` | Toggle tools on/off UI | `registerCommand`, `setActiveTools`, `SettingsList`, session events |
+| **Remote & Sandbox** |||
+| `ssh.ts` | SSH remote execution | `registerFlag`, `on("user_bash")`, `on("before_agent_start")`, tool operations |
+| `interactive-shell.ts` | Persistent shell session | `on("user_bash")` |
+| `sandbox/` | Sandboxed tool execution | Tool operations |
+| `subagent/` | Spawn sub-agents | `registerTool`, `exec` |
+| **Games** |||
+| `snake.ts` | Snake game | `registerCommand`, `ui.custom`, keyboard handling |
+| `space-invaders.ts` | Space Invaders game | `registerCommand`, `ui.custom` |
+| `doom-overlay/` | Doom in overlay | `ui.custom` with overlay |
+| **Providers** |||
+| `custom-provider-anthropic/` | Custom Anthropic proxy | `registerProvider` |
+| `custom-provider-gitlab-duo/` | GitLab Duo integration | `registerProvider` with OAuth |
+| **Messages & Communication** |||
+| `message-renderer.ts` | Custom message rendering | `registerMessageRenderer`, `sendMessage` |
+| `event-bus.ts` | Inter-extension events | `pi.events` |
+| **Session Metadata** |||
+| `session-name.ts` | Name sessions for selector | `setSessionName`, `getSessionName` |
+| `bookmark.ts` | Bookmark entries for /tree | `setLabel` |
+| **Misc** |||
+| `antigravity-image-gen.ts` | Image generation tool | `registerTool`, Google Antigravity |
+| `inline-bash.ts` | Inline bash in tool calls | `on("tool_call")` |
+| `with-deps/` | Extension with npm dependencies | Package structure with `package.json` |