my-durable 0.0.0-stage → 0.0.2

package/ai_docs/pi/themes.md

@@ -0,0 +1,140 @@
+> Source: [packages/coding-agent/docs/themes.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/themes.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# Customize Pi with themes
+
+Themes control the colors Pi uses in interactive mode and HTML exports. Pi includes the `system`, `dark`, and `light` themes. You can select one theme, follow your terminal's light or dark appearance, or create your own palette.
+
+## Use your terminal's colors
+
+The `system` theme is the default. It builds Pi's colors from your terminal's theme, so Pi matches the terminal instead of bringing its own palette:
+
+- Pi queries the terminal's default foreground and background colors and its 16 ANSI colors.
+- Each Pi color takes its hue from one ANSI color, for example errors from red and links from blue.
+- Pi sets each color's lightness so that it stands out from the background by a minimum contrast. Body text keeps at least a 4.5:1 WCAG contrast ratio on the background and every panel.
+- When the terminal switches between light and dark, Pi queries the colors again and rebuilds the theme.
+
+The theme adapts to what the terminal reports:
+
+| Terminal reports | Result |
+|---|---|
+| Background and ANSI colors | Colors from the terminal palette, placed for the actual background. |
+| Background only | Pi's own hues, placed for the actual background. |
+| Nothing | ANSI color indices and the terminal's default colors, which the terminal renders itself. Secondary text is faint, and panels have no background color. |
+
+Pi asks the terminal for its colors when it starts. Terminals usually answer within a few milliseconds, and Pi waits at most 100 ms before showing the startup header. If the terminal does not answer in time, Pi uses the ANSI color fallback, and it still applies the colors if they arrive later, for example over a slow SSH connection. `system` is a reserved name: a custom theme with that name is ignored.
+
+<a id="selecting-a-theme"></a>
+
+## Choose a theme
+
+Open `/settings` and select **Theme**. You can use one theme for every terminal appearance or choose separate themes for light and dark terminals.
+
+The selection is saved as the `theme` [setting](settings.md#terminal-and-display):
+
+```json
+{
+  "theme": "dark"
+}
+```
+
+Without a `theme` setting, Pi uses `system`.
+
+Automatic mode stores the light theme first and the dark theme second:
+
+```json
+{
+  "theme": "light/dark"
+}
+```
+
+Pi decides whether the terminal is light or dark from its reported background and foreground colors. If the terminal does not report its background, Pi uses the terminal's light/dark notification, then the `COLORFGBG` environment variable, then dark. The same decision picks the theme of a light/dark pair and the appearance of `system`. When automatic mode is active, Pi changes themes when the terminal reports an appearance change. Theme names cannot contain `/` because Pi reserves it for this setting format.
+
+Use `--use-theme` to choose the initial theme for one invocation without changing the saved setting:
+
+```bash
+pi --use-theme light
+pi --use-theme light/dark
+```
+
+See [CLI resources](cli.md#resources) for the command-line option.
+
+## Create a custom theme
+
+Copy one of the [built-in themes](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/src/modes/interactive/theme) or create a new JSON file conforming to the [schema](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json). The built-in themes use OKHSL colors, with variables for colors that several roles share, so you can adjust a hue, saturation, or lightness directly.
+
+1. Save the file as `<agent-dir>/themes/my-theme.json`. The agent directory defaults to `~/.pi/agent`.
+2. Set its `name` to `my-theme`.
+3. Change values in `vars` and `colors`.
+4. Select `my-theme` through `/settings`.
+
+Use the theme name as the filename. Pi hot-reloads the active user theme only from `<agent-dir>/themes/<name>.json`. Run `/reload` after adding or changing a theme from any other source.
+
+## Understand the theme file
+
+| Property | Required | Responsibility |
+|---|---|---|
+| `$schema` | No | Enables editor validation and completion against Pi's published schema. |
+| `name` | Yes | Identifies the theme in selectors and settings. It must be unique, cannot contain `/`, and cannot be `system`. |
+| `appearance` | No | `"dark"` or `"light"`: the background the theme is designed for. Pi detects it from the theme colors when omitted. |
+| `vars` | No | Defines reusable color values. Variables can reference other variables. |
+| `colors` | Yes | Assigns colors to terminal UI roles. The schema identifies required and optional roles. |
+| `export` | No | Overrides page and panel backgrounds in HTML exports. |
+
+A color can be written in six forms:
+
+| Form | Example | Meaning |
+|---|---|---|
+| RGB hexadecimal | `"#0af"` or `"#00aaff"` | A three- or six-digit sRGB color. |
+| OKLCH | `"oklch(62% 0.1 200)"` | Perceptual lightness, chroma, and hue. |
+| OKHSL | `"okhsl(250 60% 55%)"` | Hue, saturation, and lightness. Saturation is relative to the most the sRGB gamut allows at that hue and lightness, so every value is in gamut and equal saturation looks equally colorful. |
+| 256-color index | `39` | An ANSI palette index from `0` through `255`. |
+| Variable reference | `"primary"` | The value of an entry in `vars`. |
+| Terminal default | `""` | The terminal's default foreground or background color. |
+
+Terminal default colors render as the terminal's own colors. Where Pi needs a concrete value, such as HTML export or extension color math, it uses the default colors the terminal reports, or a black or white guess based on the theme's appearance.
+
+Pi resolves chained variable references. A missing variable or circular reference makes the theme invalid. Pi uses truecolor when available, gamut-maps OKLCH to sRGB, and approximates colors for 256-color terminals. HTML exports convert OKHSL values to hexadecimal because CSS does not support them. If colors differ from their source values, check your terminal's truecolor detection and contrast settings. See [Configure Your Terminal](terminal-setup.md#override-detected-capabilities).
+
+Use the [theme JSON schema](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json) for the exact properties, required colors, and accepted value types.
+
+Pi reports invalid theme files during startup and `/reload`.
+
+## Find the color to change
+
+Theme colors describe interface roles rather than individual components. Use these groups to find the relevant part of the schema:
+
+| Area | Color names |
+|---|---|
+| General interface | `accent`, `border*`, `text`, `muted`, `dim`, `success`, `error`, `warning` |
+| Selection and fullscreen | `selectedBg`, `searchMatch*`, `scrollbar*` |
+| Messages | `userMessage*`, `customMessage*`, `thinkingText` |
+| Tool execution | `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `toolTitle`, `toolOutput` |
+| Markdown | `md*` |
+| Tool diffs | `toolDiff*` |
+| Syntax highlighting | `syntax*` |
+| Editor modes | `thinking*`, `bashMode` |
+| HTML export | `export.pageBg`, `export.cardBg`, `export.infoBg` |
+
+The schema is the format reference. The built-in themes provide complete values that you can copy and adjust.
+
+Five colors are optional and inherit another color when omitted:
+
+| Optional color | Fallback |
+|---|---|
+| `scrollbarTrack` | `muted` |
+| `scrollbarThumb` | `text` |
+| `searchMatchBg` | `selectedBg` |
+| `searchMatchText` | `text` |
+| `thinkingMax` | `thinkingXhigh` |
+
+If `export` colors are omitted, Pi derives HTML page and panel backgrounds from `userMessageBg`.
+
+## Load a theme from a project or package
+
+Place a project theme in `.pi/themes/`. Project themes load only after [project trust](security.md#understand-project-trust) is granted.
+
+You can also load theme files and directories through the `themes` setting or distribute them in a Pi package. See [Configuration](configuration.md), [Settings](settings.md#resources), and [Pi Packages](packages.md).
+
+Each loaded theme must have a unique name. Pi reports duplicate names as resource collisions.

package/ai_docs/pi/tmux.md

@@ -0,0 +1,59 @@
+> Source: [packages/coding-agent/docs/tmux.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/tmux.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# Run Pi in tmux
+
+Pi works inside tmux, but tmux can report `Shift+Enter`, `Ctrl+Enter`, and plain `Enter` as the same key. Enable extended keys so Pi can distinguish them.
+
+## Check your tmux version
+
+```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
+```
+
+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
+tmux
+```
+
+## Verify modified keys
+
+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
+
+These versions support extended keys but not `extended-keys-format csi-u`. Add only:
+
+```tmux
+set -g extended-keys on
+```
+
+Pi supports the xterm `modifyOtherKeys` format used by these versions. Restart tmux and repeat the verification steps.
+
+For older versions, upgrade tmux or use Pi outside tmux rather than relying on modified Enter shortcuts.

package/ai_docs/pi/toolkit.md

@@ -0,0 +1,168 @@
+> Source: [README.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/README.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+<p align="center">
+  <a href="https://pi.dev">
+    <img alt="pi logo" src="https://pi.dev/logo-auto.svg" width="128">
+  </a>
+</p>
+<p align="center">
+  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
+  <a href="https://www.npmjs.com/package/@earendil-works/pi-coding-agent"><img alt="npm" src="https://img.shields.io/npm/v/@earendil-works/pi-coding-agent?style=flat-square" /></a>
+</p>
+
+> New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See [CONTRIBUTING.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/CONTRIBUTING.md).
+
+# Pi
+
+Pi is a minimal, extensible agent harness that you can make your own.
+
+Adapt Pi to your workflows, not the other way around. Customize Pi with [extensions](extensions.md), [skills](skills.md), [prompt templates](prompt-templates.md), and [themes](themes.md). Bundle them as [Pi packages](packages.md) and share via npm or git.
+
+Pi ships with powerful defaults but skips features like sub-agents and plan mode. Ask Pi to build what you want, or install a package that does it your way.
+
+Use Pi [interactively](usage.md), automate it in [print or JSON mode](cli.md), control it over [RPC](rpc.md), or build apps with the [Pi TypeScript SDK](sdk.md). See [OpenClaw](https://github.com/OpenClaw/OpenClaw) for a real-world integration.
+
+## Getting started
+
+Install the command-line interface:
+
+```bash
+curl -fsSL https://pi.dev/install.sh | sh
+```
+
+On Windows:
+
+```shell
+powershell -c "irm https://pi.dev/install.ps1 | iex"
+```
+
+The installer pins all dependencies and updates Pi with `pi update`. Alternatively, install directly with npm, which does not pin transitive dependencies:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+Pi requires Node.js 22.19 or newer. The macOS, Linux, and Windows installers can install it if needed. Pi does not require dependency lifecycle scripts for a normal npm installation.
+
+Start Pi in the directory where you want it to work:
+
+```bash
+cd /path/to/project
+pi
+```
+
+For a built-in AI provider, run `/login` inside Pi to connect a subscription or API key. Then give Pi a task.
+
+See the [documentation](https://pi.dev/docs/latest) for full setup and usage instructions, or [visit pi.dev](https://pi.dev) for demos.
+
+## Run with Nix
+
+```bash
+nix run github:earendil-works/pi/stable
+```
+
+`stable` points at the latest release. Install it with `nix profile add github:earendil-works/pi/stable` and update with `nix profile upgrade pi`. Use a release tag such as `github:earendil-works/pi/v1.0.0` to pin a version, or `github:earendil-works/pi` for unreleased changes on `main`. Nix builds Pi from source.
+
+Supports ARM64 and x86-64 on Linux and macOS. Use `nix build .` or `nix run .` to build or run your checkout.
+
+Nix builds are offline, so the bundled model data comes from a pi.dev model catalog revision pinned in `nix/model-catalog.json`. At runtime, Pi still overlays newer catalog data from pi.dev as usual. The Nix workflow replaces the pin on `main` when it no longer matches the checkout, for example after a provider is added or gains a new model type. To refresh it by hand:
+
+```bash
+npm run update:model-catalog-pin
+```
+
+## Packages
+
+This monorepo contains the Pi CLI and its supporting libraries.
+
+| Package | Description |
+|---------|-------------|
+| **[@earendil-works/chord](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/chord)** | Standalone application-composition runtime for services, replicated state, RPC, and plugins |
+| **[@earendil-works/pi-telemetry](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/telemetry)** | Vendor-neutral telemetry contracts, reference adapter, conformance tests, and typed schemas |
+| **[@earendil-works/pi-ai](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/ai)** | Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.) |
+| **[@earendil-works/pi-durable](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/durable)** | Durable conversation, task, and document runtime |
+| **[@earendil-works/pi-agent-core](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/agent)** | Agent runtime with tool calling and state management |
+| **[@earendil-works/pi-coding-agent](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent)** | Interactive coding agent CLI |
+| **[@earendil-works/pi-tui](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/tui)** | Terminal UI library with differential rendering |
+
+For Slack/chat automation and workflows see [earendil-works/pi-chat](https://github.com/earendil-works/pi-chat).
+
+## Permissions & Containerization
+
+Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it.
+
+If you need stronger boundaries, containerize or sandbox Pi. See [packages/coding-agent/docs/containerization.md](containerization.md) for three patterns:
+
+- **Gondolin extension**: keep `pi` and provider auth on the host while routing built-in tools and `!` commands into a local Linux micro-VM.
+- **Plain Docker**: run the whole `pi` process in a local container for simple isolation.
+- **OpenShell**: run the whole `pi` process in a policy-controlled sandbox.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/CONTRIBUTING.md) for contribution guidelines and [AGENTS.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/AGENTS.md) for project-specific rules (for both humans and agents).  Longer term plans for Pi can also be found in [RFCs](https://rfc.earendil.com/keyword/pi/).
+
+## Development
+
+```bash
+npm install --ignore-scripts  # Install all dependencies without running lifecycle scripts
+npm run build         # Refresh model data, then build all packages
+npm run build:offline # Rebuild using existing model data without network access
+npm run check         # Lint, format, and type check
+./test.sh            # Run tests (skips LLM-dependent tests without API keys)
+./pi-test.sh         # Run pi from sources (can be run from any directory)
+```
+
+## Building standalone binaries from release source
+
+GitHub releases include a versioned source archive covered by the release's `SHA256SUMS` file. Extract it and run the same build script used for the official standalone binaries:
+
+```bash
+VERSION="<release-version>"
+tar -xzf "pi-${VERSION}-source.tar.gz"
+cd "pi-${VERSION}"
+./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out"
+```
+
+The archive includes release model data and native prebuilds. `--offline-model-data` uses that model data without refreshing provider catalogs. The script installs dependencies and builds the executable with its runtime assets; pass `--skip-install` if dependencies are already provided.
+
+## Supply-chain hardening
+
+We treat npm dependency changes as reviewed code changes.
+
+- Direct external dependencies are pinned to exact versions. Internal workspace packages remain version-ranged.
+- `.npmrc` sets `save-exact=true` and `min-release-age=2` to avoid same-day dependency releases during npm resolution.
+- `package-lock.json` is the dependency ground truth. Pre-commit blocks accidental lockfile commits unless `PI_ALLOW_LOCKFILE_CHANGE=1` is set.
+- `npm run check` verifies pinned direct deps, native TypeScript import compatibility, and the generated coding-agent install lock.
+- The pi.dev installer installs from `packages/coding-agent/install-lock/`, generated from the root lockfile, to pin transitive deps. The npm package does not pin transitive deps.
+- Release smoke tests use `npm run release:local` to build, pack, and create isolated npm and Bun installs outside the repo before tagging a release.
+- Local release installs, documented npm installs, and `pi update --self` use `--ignore-scripts` where supported.
+- CI installs with `npm ci --ignore-scripts`, and a scheduled GitHub workflow runs `npm audit --omit=dev` plus `npm audit signatures --omit=dev`.
+- Install lock generation has an explicit allowlist for dependency lifecycle scripts; new lifecycle-script deps fail checks until reviewed.
+
+## Share your OSS coding agent sessions
+
+If you use Pi or other coding agents for open source work, please share your sessions.
+
+Public OSS session data helps improve coding agents with real-world tasks, tool use, failures, and fixes instead of toy benchmarks.
+
+For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).
+
+To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`.
+
+You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.
+
+I regularly publish my own `pi-mono` work sessions here:
+
+- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)
+
+## License
+
+MIT
+
+<p align="center">
+  <a href="https://pi.dev">pi.dev</a> domain graciously donated by
+  <br /><br />
+  <a href="https://exe.dev"><img src="https://raw.githubusercontent.com/earendil-works/pi/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
+</p>

package/ai_docs/pi/tui.md

@@ -0,0 +1,129 @@
+> Source: [packages/coding-agent/docs/tui.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/tui.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# Terminal UI
+
+`@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.
+
+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.
+
+## Choose an integration point
+
+| 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 |
+
+These APIs receive Pi’s active theme and keybindings where needed. Do not create a second terminal renderer inside an extension.
+
+## Understand the component model
+
+A component renders an array of terminal lines for an available width. It can optionally handle keyboard and mouse input, and it must invalidate cached output when its state or theme-dependent content changes.
+
+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.
+
+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.
+
+After changing component state, invalidate the affected component and call the injected `tui.requestRender()`. The TUI coalesces render requests and updates the terminal.
+
+## Compose built-in components
+
+The package includes components for common layouts and controls:
+
+- `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.
+
+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.
+
+## Handle keyboard input and focus
+
+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.
+
+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.
+
+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.
+
+Extend Pi’s `CustomEditor` when replacing the main editor. It preserves application shortcuts and agent controls.
+
+Forward keys your editor does not own to the base implementation, and restore the default by clearing the custom editor factory.
+
+## Handle mouse input
+
+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.
+
+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.
+
+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.
+
+## Use custom screens and overlays
+
+`ctx.ui.custom()` temporarily gives one component control of the interactive area and resolves when that component calls the supplied completion callback.
+
+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.
+
+Focused overlays retain input ownership across ordinary renders. If another component should receive input while an overlay remains visible, explicitly release or redirect focus through the handle.
+
+Treat each custom component instance as belonging to one interaction. Create a new instance when starting that interaction again.
+
+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()`.
+
+See [`overlay-qa-tests.ts`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/overlay-qa-tests.ts) for positioning, stacking, focus, responsive visibility, and animation behavior.
+
+## Apply themes correctly
+
+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.
+
+Use `theme.style()` to combine foreground and background colors with text attributes:
+
+```typescript
+return new Text(
+  theme.style("Done!", {
+    fg: "success",
+    bg: "toolSuccessBg",
+    bold: true,
+  }),
+  0,
+  0,
+);
+```
+
+A style color can be a semantic theme token or a concrete `Color`. Foreground tokens are accepted as `fg` and background tokens as `bg`; to use a token's color in the other position, pass its concrete color, for example `{ fg: theme.colors.userMessageBg }`. Access concrete colors through `theme.colors` and use utilities such as `mixColors()` from `@earendil-works/pi-tui` when color math is needed. Tokens that a theme sets to the terminal default render with the terminal's own color; `theme.colors` reports the color the terminal announced for them, or a guess when it did not. Use `theme.appearance` (`"dark"` or `"light"`) to decide, for example, whether to lighten or darken a color. Pi converts the result to truecolor or 256-color output based on terminal capabilities. Theme tokens are converted once per theme; compute concrete colors outside the render path when possible.
+
+The existing `theme.fg()` and `theme.bg()` helpers remain available for applying one semantic color.
+
+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.
+
+Theme callbacks evaluated during rendering do not need special rebuilding. Stateless components can also calculate themed output on every render.
+
+Use [Themes](themes.md) to create terminal palettes. Use Pi’s `getMarkdownTheme()` when rendering Markdown that should match the active application theme.
+
+## Keep rendering responsive
+
+Rendering runs on the interactive path. Cache expensive layout and highlighting work by width and content, then clear that cache from `invalidate()`.
+
+Keep the default view compact and reveal detail through expansion or a dedicated screen. For custom tool rendering, handle partial results and reuse the previous component when it can be updated safely.
+
+Use `PI_TUI_WRITE_LOG` to capture the raw ANSI stream when diagnosing rendering problems. Test narrow widths, wide characters, resize events, theme changes, focus transitions, and both regular and fullscreen modes.
+
+## Examples and source
+
+The checked extension examples cover the main patterns:
+
+- [`preset.ts`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/preset.ts) and [`tools.ts`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/tools.ts) use selection and settings lists.
+- [`qna.ts`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/qna.ts) uses cancellable asynchronous UI.
+- [`modal-editor.ts`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/modal-editor.ts) replaces the editor.
+- [`custom-footer.ts`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/custom-footer.ts) replaces the footer.
+- [`widget-placement.ts`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/widget-placement.ts) places persistent content around the editor.
+- [`doom-overlay/`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/extensions/doom-overlay) demonstrates a continuously rendered overlay.
+
+The public exports are defined in [`packages/tui/src/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/tui/src/index.ts). See [Extensions](extensions.md) for extension lifecycle, state, tools, events, and mode behavior.

package/ai_docs/pi/usage.md

@@ -0,0 +1,98 @@
+> Source: [packages/coding-agent/docs/usage.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/usage.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# Use Pi in the terminal
+
+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).
+
+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="https://raw.githubusercontent.com/earendil-works/pi/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/images/interactive-mode.png" alt="Pi interactive mode showing a conversation, editor, and status information" width="750"></p>
+
+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.
+
+## Enter a prompt
+
+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.
+
+To include files or images:
+
+- 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
+
+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.
+
+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.
+
+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).
+
+## Change direction
+
+You can send more input while Pi is working:
+
+| 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` |
+
+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.
+
+Windows Terminal reserves some Alt shortcuts. See [Terminal Setup](terminal-setup.md) for the Windows alternatives.
+
+## Change the model or settings
+
+Type `/` to search the available commands. The commands you will use most often are:
+
+- `/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.
+
+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).
+
+## Continue or start over
+
+Pi saves sessions automatically unless session persistence is disabled.
+
+- `/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.
+
+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.
+
+After leaving Pi, run `pi --continue` from the same folder to resume its most recent session.
+
+## Run a terminal command
+
+Prefix a command with `!` to run it and include its output in the conversation:
+
+```text
+!git status
+```
+
+Use `!!` when you want to run a command without sending its output to the model.
+
+## Copy, export, or share results
+
+Press `Ctrl+X` or run `/copy` to copy the last assistant response. Use `/export` to save the session as HTML or JSONL.
+
+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.
+
+## Adjust the terminal
+
+Fullscreen mode, the default, keeps the editor and status area fixed while the transcript scrolls within the terminal window. Regular mode uses the terminal's normal scrollback. Choose a mode through `/settings` or `--tui-mode`.
+
+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.
+
+## Collect diagnostic information
+
+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).
+
+Review this file before sharing it. It can contain prompts, model responses, tool output, file contents, and terminal data.