my-durable 0.0.0-stage → 0.0.2

package/ai_docs/pi/skills.md

@@ -0,0 +1,97 @@
+> Source: [packages/coding-agent/docs/skills.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/skills.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# Skills
+
+Skills give Pi specialized instructions and supporting files for a particular kind of work. Pi advertises each available skill by name and description, then loads its full instructions only when the task calls for them.
+
+Use a skill when a workflow needs more context than a prompt template but does not need a new executable integration point. Skills can bundle scripts, references, and assets alongside their instructions.
+
+Pi implements the [Agent Skills specification](https://agentskills.io/specification). Most invalid fields produce warnings rather than stopping startup.
+
+## Create a skill
+
+A skill is a directory containing `SKILL.md`:
+
+```text
+pdf-tools/
+├── SKILL.md
+├── scripts/
+│   └── extract.sh
+├── references/
+│   └── formats.md
+└── assets/
+    └── template.json
+```
+
+Start `SKILL.md` with frontmatter followed by direct instructions:
+
+```markdown
+---
+name: pdf-tools
+description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
+---
+
+# PDF tools
+
+Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.
+```
+
+The description determines when the model considers loading the skill. State both what the skill does and when it applies. Avoid descriptions such as “Helps with PDFs,” which do not provide enough routing information.
+
+Use relative paths from the skill directory when referring to bundled files. Pi tells the model where the skill lives so it can resolve those paths.
+
+## Understand how skills load
+
+At startup, Pi scans configured skill locations and adds each skill’s name, description, and path to the system prompt. It does not add the full instructions.
+
+When a task matches, the model reads `SKILL.md` and follows its instructions. This keeps detailed guidance out of context until it is needed. A model might fail to load a relevant skill, so use `/skill:name` when you need to force it.
+
+Arguments after `/skill:name` are appended to the loaded instructions as a user request:
+
+```text
+/skill:pdf-tools extract report.pdf
+```
+
+Set `disable-model-invocation: true` in frontmatter when a skill should be available only through its explicit command. The `enableSkillCommands` [setting](settings.md) controls whether skill commands appear in interactive command discovery; manually entered `/skill:name` commands still work.
+
+<a id="choose-where-it-loads"></a>
+
+## Add it to Pi
+
+Place the skill in your user or project skills directory. Directories containing `SKILL.md` are discovered recursively.
+
+Pi also supports the Agent Skills locations `~/.agents/skills/` and `.agents/skills/`. Project `.agents/skills/` directories are discovered from the working directory through its ancestors, stopping at the repository root when one exists.
+
+Pi accepts some standalone Markdown skills, but a directory containing `SKILL.md` is the portable form and should be preferred. See [Settings](settings.md#resources) and [Pi Packages](packages.md) for additional locations.
+
+Project skills can instruct the model to run scripts or modify files. Review unfamiliar skills and their supporting files before granting project trust.
+
+## Write portable frontmatter
+
+The Agent Skills specification defines these fields:
+
+| Field | Purpose |
+|---|---|
+| `name` | Command and display name |
+| `description` | Routing description shown to the model |
+| `license` | License name or bundled license file |
+| `compatibility` | Environment requirements |
+| `metadata` | Additional key-value metadata |
+| `allowed-tools` | Experimental pre-approved tool list |
+| `disable-model-invocation` | Hide the skill from automatic model selection |
+
+Names use lowercase letters, numbers, and hyphens, with no leading, trailing, or consecutive hyphens. They can contain at most 64 characters; descriptions can contain at most 1024.
+
+Pi neither requires nor warns when the declared name differs from the parent directory. Other Agent Skills implementations may enforce that requirement, so matching names remain the portable choice.
+
+Malformed `SKILL.md` files and declared skills without descriptions are not loaded. Name collisions keep the first discovered skill and produce a warning.
+
+## Validate and share a skill
+
+Run Pi from a location where the skill is discoverable, then inspect the startup diagnostics and `/skill:name` command. Run `/reload` after editing a skill during an active session.
+
+Use a [Pi package](packages.md) to distribute one or more skills through npm or git. Keep environment setup inside the skill and declare any required runtime dependencies in the package.
+
+For examples, see the [Anthropic skills collection](https://github.com/anthropics/skills) and [Pi skills collection](https://github.com/badlogic/pi-skills).

package/ai_docs/pi/slash-commands.md

@@ -0,0 +1,64 @@
+> Source: [packages/coding-agent/docs/slash-commands.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/slash-commands.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# Slash commands
+
+Type `/` in Pi's terminal editor to search the commands available in the current session. This page lists the built-in commands in the current Pi release.
+
+Extensions, prompt templates, and skills can add commands. The command menu in Pi is therefore the exact reference for the resources loaded in your session.
+
+## Models and settings
+
+| Command | Description |
+|---|---|
+| `/settings` | Open settings |
+| `/model [provider/model]` | Select a model |
+| `/thinking [level]` | Set the thinking level |
+| `/scoped-models` | Configure the models used by interactive cycling |
+| `/login [provider]` | Add provider authentication |
+| `/logout` | Remove provider authentication |
+| `/llama` | Manage models on the configured llama.cpp router |
+
+## Sessions and context
+
+| Command | Description |
+|---|---|
+| `/new` | Start a new session |
+| `/resume` | Switch to another saved session |
+| `/name [name]` | Set the session display name, or show the current name when omitted |
+| `/session` | Show current session information and statistics |
+| `/tree` | Navigate the session tree |
+| `/fork` | Create a new session from an earlier user message |
+| `/clone` | Duplicate the current session at its current position |
+| `/compact [instructions]` | Compact the current context, optionally with custom instructions |
+| `/import <path>` | Import and resume a JSONL session |
+
+## Export and share
+
+| Command | Description |
+|---|---|
+| `/copy` | Copy the last assistant message |
+| `/export [path]` | Export the session as HTML or JSONL |
+| `/share` | Upload the session and return a viewer link |
+| `/bug [description]` | Prepare a private bug report for the Pi developers |
+
+Review a session before exporting or sharing it. Sessions can contain prompts, tool arguments, command output, file contents, and credentials exposed during the conversation.
+
+## Runtime and project
+
+| Command | Description |
+|---|---|
+| `/trust` | Save a project trust decision for future Pi processes |
+| `/reload` | Reload keybindings, extensions, skills, templates, themes, and context files |
+| `/hotkeys` | Show active keyboard shortcuts |
+| `/changelog` | Show changelog entries |
+| `/quit` | Quit Pi |
+
+## Commands added by resources
+
+- Extensions can register commands with their own arguments and completion behavior.
+- Each prompt template is available under its template name.
+- Skills are available as `/skill:name` when skill commands are enabled.
+
+Use `/reload` after adding or changing a discovered command resource. See [Extensions](extensions.md), [Prompt Templates](prompt-templates.md), and [Skills](skills.md) for their loading and naming rules.

package/ai_docs/pi/sources.md

@@ -0,0 +1,57 @@
+# Pi documentation sources
+
+46 official source documents fetched with Firecrawl on 2026-10-05.
+Repository snapshot: [`b78e6a9085343ec0f308c3d377da72528b4cf7ee`](https://github.com/earendil-works/pi/tree/b78e6a9085343ec0f308c3d377da72528b4cf7ee).
+
+Repository documents use the pinned source snapshot. Website pages are dated captures. Source text is retained with provenance headers and resolved relative Markdown links.
+
+Start with [the documentation index](index.md), [how Pi works](how-pi-works.md), and [the SDK](sdk.md). Supporting package references cover pi-ai, pi-agent-core, and Chord.
+
+| Local document | Official source |
+| --- | --- |
+| [@earendil-works/chord](chord.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/chord/README.md) |
+| [CLI Integration](cli-integration.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/cli-integration.md) |
+| [Command Line](cli.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/cli.md) |
+| [Codemode](codemode.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/codemode.md) |
+| [Compaction Reference](compaction.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/compaction.md) |
+| [Configuration](configuration.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/configuration.md) |
+| [Run Pi in an isolated environment](containerization.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/containerization.md) |
+| [Custom Providers](custom-provider.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/custom-provider.md) |
+| [Environment Variables](environment-variables.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/environment-variables.md) |
+| [Extensions](extensions.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/extensions.md) |
+| [How Pi Works](how-pi-works.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/how-pi-works.md) |
+| [Pi](index.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/index.md) |
+| [JSON Event Stream](json.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/json.md) |
+| [Keybindings Reference](keybindings.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/keybindings.md) |
+| [Local Models with llama.cpp](llama-cpp.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/llama-cpp.md) |
+| [MCP Servers](mcp.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/mcp.md) |
+| [Message Types](message-types.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/message-types.md) |
+| [Choose a Model](models.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/models.md) |
+| [overview](overview.md) | [Source](https://pi.dev/) |
+| [Pi Packages](packages.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/packages.md) |
+| [@earendil-works/pi-agent-core](pi-agent-core.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/agent/README.md) |
+| [@earendil-works/pi-ai](pi-ai.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/ai/README.md) |
+| [Prompt Templates](prompt-templates.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/prompt-templates.md) |
+| [Providers](providers.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/providers.md) |
+| [Quickstart](quickstart.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/quickstart.md) |
+| [Pi](readme.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/README.md) |
+| [RPC Commands](rpc-commands.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/rpc-commands.md) |
+| [RPC Extension UI](rpc-extension-ui.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/rpc-extension-ui.md) |
+| [RPC Mode](rpc.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/rpc.md) |
+| [SDK](sdk.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/sdk.md) |
+| [Run Pi safely](security.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/security.md) |
+| [Session File Format](session-format.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/session-format.md) |
+| [Sessions and Context](sessions.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/sessions.md) |
+| [Settings Reference](settings.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/settings.md) |
+| [Configure shell commands](shell-aliases.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/shell-aliases.md) |
+| [Skills](skills.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/skills.md) |
+| [Slash commands](slash-commands.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/slash-commands.md) |
+| [Configure your terminal](terminal-setup.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/terminal-setup.md) |
+| [Run Pi on Android with Termux](termux.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/termux.md) |
+| [Customize Pi with themes](themes.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/themes.md) |
+| [Run Pi in tmux](tmux.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/tmux.md) |
+| [Pi](toolkit.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/README.md) |
+| [Terminal UI](tui.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/tui.md) |
+| [Use Pi in the terminal](usage.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/usage.md) |
+| [Virtual Models](virtual-models.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/virtual-models.md) |
+| [Run Pi on Windows](windows.md) | [Source](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/windows.md) |

package/ai_docs/pi/terminal-setup.md

@@ -0,0 +1,223 @@
+> Source: [packages/coding-agent/docs/terminal-setup.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/terminal-setup.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# Configure your terminal
+
+Most modern terminals work with Pi without additional setup. Use this page when modified keys, scrolling, links, images, colors, or input-method editor (IME) positioning do not behave as expected.
+
+Pi uses extended-key protocols so terminals can distinguish combinations such as `Shift+Enter` and `Alt+Enter` from plain `Enter`. Terminal proxies, multiplexers, and built-in IDE terminals can change or discard that information.
+
+## Troubleshooting
+
+| Symptom | Start here |
+|---|---|
+| `Shift+Enter` submits instead of inserting a line | Your terminal's section below; for tmux, see [Run Pi in tmux](tmux.md) |
+| `Alt+Enter` does not queue a follow-up | [WezTerm](#wezterm), [Alacritty](#alacritty), or [Windows Terminal](#windows-terminal) |
+| Fullscreen scrolling is unusually slow | [iTerm2](#iterm2) |
+| Links work but show no hover preview | [Ghostty](#ghostty) |
+| Inline images or colors are not detected | [Override detected capabilities](#override-detected-capabilities) |
+| An IME candidate window appears in the wrong place | [WezTerm](#wezterm) or [IntelliJ IDEA](#intellij-idea-integrated-terminal) |
+| Modified keys fail only inside tmux | [Run Pi in tmux](tmux.md) |
+
+Use `/hotkeys` to inspect Pi's active shortcuts. See [Keybindings](keybindings.md) to change them.
+
+## Kitty
+
+Kitty supports the required keyboard protocol without additional configuration.
+
+## iTerm2
+
+Regular terminal mode works without additional configuration.
+
+### Fix slow fullscreen scrolling
+
+In fullscreen mode, Pi owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling native terminal history. Fast trackpad gestures can then move only about one line at a time.
+
+To change this behavior:
+
+1. Open **iTerm2 > Settings > Advanced**.
+2. Search for **Trackpad scrolls fast?**.
+3. Set it to **No**.
+
+This is an iTerm2-wide setting and can also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
+
+## Apple Terminal
+
+Pi enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, Pi uses a local macOS modifier fallback and treats it as `Shift+Enter`.
+
+The fallback works only when Pi runs on the same Mac as Terminal.app. It cannot inspect the local modifier state when Pi runs on another machine over SSH.
+
+## Ghostty
+
+Add this mapping to Ghostty's configuration if `Alt+Backspace` does not work:
+
+```text
+keybind = alt+backspace=text:\x1b\x7f
+```
+
+The configuration file is `~/Library/Application Support/com.mitchellh.ghostty/config` on macOS and `~/.config/ghostty/config` on Linux.
+
+Older Claude Code configurations may contain:
+
+```text
+keybind = shift+enter=text:\n
+```
+
+This sends a raw linefeed, which Pi cannot distinguish from `Ctrl+J`. Remove the mapping if an older Claude Code installation is the only reason you added it. Pi already binds `Ctrl+J` as a newline alternative, so the mapping may appear to work while still preventing Pi and tmux from receiving a real `Shift+Enter` event.
+
+### Open links in fullscreen mode
+
+Links remain clickable in fullscreen mode, but Ghostty does not show its normal hover underline or URL preview while Pi captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
+
+## WezTerm
+
+WezTerm normally reports `Shift+Enter` through xterm extended keys. To enable the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.enable_kitty_keyboard = true
+return config
+```
+
+### Forward Alt+Enter on macOS
+
+WezTerm binds `Option+Enter` to fullscreen by default on macOS. To use it for Pi's follow-up queue, add this entry to your `config.keys` table:
+
+```lua
+{
+  key = 'Enter',
+  mods = 'ALT',
+  action = wezterm.action.SendString('\x1b[13;3u'),
+}
+```
+
+A complete minimal configuration is:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.keys = {
+  {
+    key = 'Enter',
+    mods = 'ALT',
+    action = wezterm.action.SendString('\x1b[13;3u'),
+  },
+}
+return config
+```
+
+### Position an IME candidate window in WSL
+
+If CJK IME candidates do not follow Pi's text cursor in WSL, show the hardware cursor:
+
+```bash
+export PI_HARDWARE_CURSOR=1
+pi
+```
+
+You can instead set `showHardwareCursor` to `true` in Pi settings.
+
+## Alacritty
+
+Alacritty normally reports `Shift+Enter`. On macOS, `Option+Enter` can arrive as plain `Enter`. Add this to `~/.config/alacritty/alacritty.toml` to forward it to Pi:
+
+```toml
+[[keyboard.bindings]]
+key = "Enter"
+mods = "Alt"
+chars = "\u001b[13;3u"
+```
+
+Restart Alacritty after changing the file.
+
+## VS Code integrated terminal
+
+VS Code 1.109.5 and newer enable the Kitty keyboard protocol in the integrated terminal by default.
+
+For an older version, add a `Shift+Enter` terminal binding to `keybindings.json`:
+
+```json
+{
+  "key": "shift+enter",
+  "command": "workbench.action.terminal.sendSequence",
+  "args": { "text": "\u001b[13;2u" },
+  "when": "terminalFocus"
+}
+```
+
+The user `keybindings.json` file is normally located at:
+
+- macOS: `~/Library/Application Support/Code/User/keybindings.json`
+- Linux: `~/.config/Code/User/keybindings.json`
+- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
+
+## Zed integrated terminal
+
+Add these bindings to Zed's `keymap.json`:
+
+```json
+{
+  "context": "Terminal",
+  "bindings": {
+    "shift-enter": ["terminal::SendText", "\u001b[13;2u"],
+    "ctrl--": ["terminal::SendText", "\u001b[45;5u"],
+    "ctrl-alt-]": ["terminal::SendText", "\u001b[93;7u"]
+  }
+}
+```
+
+## Windows Terminal
+
+Windows Terminal uses Pi's Windows and WSL shortcut defaults. See [Keybindings](keybindings.md) for the complete list.
+
+### Forward Shift+Enter
+
+Open Windows Terminal's `settings.json` with `Ctrl+Shift+,` or **Settings > Open JSON file**. Add this object to its `actions` array:
+
+```json
+{
+  "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+  "keys": "shift+enter"
+}
+```
+
+Fully close and reopen Windows Terminal, then verify that `Shift+Enter` inserts a new line in Pi.
+
+### Use Alt+Enter for follow-ups
+
+Windows Terminal binds `Alt+Enter` to fullscreen by default. Pi therefore uses `Ctrl+Q` for follow-ups on Windows and WSL.
+
+To use `Alt+Enter` instead, configure Windows Terminal to forward the key and bind `app.message.followUp` to `alt+enter` in Pi's `keybindings.json`. See [Keybindings](keybindings.md#assign-keybindings).
+
+## xfce4-terminal and Terminator
+
+These terminals cannot reliably distinguish modified Enter keys from plain `Enter`. Custom bindings such as `Ctrl+Enter` or `Shift+Enter` therefore may not work.
+
+Use a terminal with modern extended-key support when you need those shortcuts, such as Kitty, Ghostty, WezTerm, iTerm2, Windows Terminal, or a compatible Alacritty build.
+
+## IntelliJ IDEA integrated terminal
+
+IntelliJ IDEA's built-in terminal cannot reliably distinguish `Shift+Enter` from plain `Enter`. Use `Ctrl+J` for a newline or run Pi in a terminal with modern extended-key support.
+
+If an IME candidate window does not follow the text cursor, show the hardware cursor:
+
+```bash
+export PI_HARDWARE_CURSOR=1
+pi
+```
+
+## Override detected capabilities
+
+Pi automatically detects OSC 8 hyperlinks, inline image protocols, and truecolor support. A terminal proxy or multiplexer can make that detection inaccurate.
+
+| Capability | Environment variable | Setting |
+|---|---|---|
+| Hyperlinks | `PI_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
+| Inline images | `PI_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
+| Truecolor | `PI_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
+
+Settings take precedence over environment variables. An unset value or `auto` preserves automatic detection.
+
+Only force a capability supported by the complete terminal path. Unsupported escape sequences can corrupt rendering. See [Environment Variables](environment-variables.md#pi-process-configuration) and [Settings](settings.md) for the canonical value definitions.

package/ai_docs/pi/termux.md

@@ -0,0 +1,121 @@
+> Source: [packages/coding-agent/docs/termux.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/termux.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 on Android with Termux
+
+Pi runs on Android through [Termux](https://termux.dev/), a terminal emulator and Linux environment. Text input, file tools, and shell commands are supported. Pi can copy and paste text through the Android clipboard with Termux:API. Clipboard image paste is not supported.
+
+## Before you begin
+
+Install Termux from [GitHub or F-Droid](https://github.com/termux/termux-app#installation). Do not use the deprecated Google Play build.
+
+[Termux:API](https://github.com/termux/termux-api#installation) is optional. Install it only when you want Pi to copy or paste Android clipboard text, or when shell commands need Android device APIs.
+
+## Install Pi
+
+1. Update Termux packages:
+
+   ```bash
+   pkg update && pkg upgrade
+   ```
+
+2. Install Node.js and Git:
+
+   ```bash
+   pkg install nodejs git
+   ```
+
+3. Install Pi:
+
+   ```bash
+   npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+   ```
+
+4. Verify the installation:
+
+   ```bash
+   pi --version
+   ```
+
+5. Open the folder you want to work in and start Pi:
+
+   ```bash
+   cd /path/to/working-folder
+   pi
+   ```
+
+Continue with the main [Quickstart](quickstart.md#3-choose-a-model) to connect a model and run your first task.
+
+## Access Android shared storage
+
+Termux cannot access shared Android storage until you grant permission. Run this once:
+
+```bash
+termux-setup-storage
+```
+
+After approval, Android shared storage is available under `/storage/emulated/0` and through the links Termux creates under `~/storage/`.
+
+Only grant this permission when Pi should be able to access those files. Commands and tools running in Termux use the same storage permissions as the Termux process.
+
+## Use clipboard commands
+
+Pi uses `termux-clipboard-set` to copy text and `termux-clipboard-get` for its clipboard-paste shortcut. Shell commands can use both commands directly. Install the Termux:API app and its command-line package:
+
+```bash
+pkg install termux-api
+```
+
+Verify the integration:
+
+```bash
+printf 'Pi clipboard test' | termux-clipboard-set
+termux-clipboard-get
+```
+
+The second command should print `Pi clipboard test`.
+
+The Termux clipboard API supports text only. Pi's clipboard-paste shortcut inserts that text into the editor but cannot attach clipboard images.
+
+## Add Termux-specific instructions
+
+Pi detects that it is running in Termux, but it cannot infer how you want it to interact with Android. Add only the environment details relevant to your work to `~/.pi/agent/AGENTS.md`:
+
+````markdown
+# Termux environment
+
+- Pi runs in Termux on Android.
+- Shared Android storage is under `/storage/emulated/0`.
+- Open URLs with `termux-open-url "https://example.com"`.
+- Open files with `termux-open <path>`.
+- Do not access shared storage unless the task requires it.
+````
+
+Run `/reload` after changing the file during an active session.
+
+## Troubleshooting
+
+### Clipboard integration fails
+
+Confirm that you installed both components:
+
+1. The Termux:API Android app from the same source as Termux
+2. The `termux-api` command-line package
+
+Then run the clipboard verification commands above outside Pi. If they fail there, fix the Termux:API installation before retrying Pi's copy command.
+
+### Shared storage reports permission denied
+
+Run `termux-setup-storage`, approve the Android permission request, and retry the path under `~/storage/` or `/storage/emulated/0`.
+
+### Pi is not found after installation
+
+Open a new Termux shell and run:
+
+```bash
+npm prefix -g
+command -v pi
+```
+
+Confirm that the global npm binary directory is on `PATH`, then reinstall Pi if the package is missing.