@subimpact/e 0.0.0-stage → 0.99.2

package/docs/skills.md

@@ -0,0 +1,93 @@
+# 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/docs/slash-commands.md

@@ -0,0 +1,60 @@
+# 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/docs/terminal-setup.md

@@ -0,0 +1,219 @@
+# 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/docs/termux.md

@@ -0,0 +1,117 @@
+# 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.

package/docs/themes.md

@@ -0,0 +1,136 @@
+# 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/docs/tmux.md

@@ -0,0 +1,55 @@
+# 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.