apex-code 0.5.0 → 0.5.1

package/docs/terminal-setup.md

@@ -1,39 +1,42 @@
-# Terminal Setup
+# Configure your terminal
 
 Apex Code uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
 
-## Capability Overrides
+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.
 
-Pi auto-detects OSC 8 hyperlinks, inline image protocols, and truecolor. If detection fails behind a terminal proxy or multiplexer, use these advanced overrides:
+## Troubleshooting
 
-| Capability | Environment variable | JSON setting |
-|------------|----------------------|--------------|
-| OSC 8 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"` |
+| 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) |
 
-Settings take precedence over environment variables; unset or `auto` preserves detection. Only force capabilities supported by the complete terminal path, since unsupported escape sequences can corrupt rendering.
+Use `/hotkeys` to inspect Pi's active shortcuts. See [Keybindings](keybindings.md) to change them.
 
 ## Kitty
 
-Works out of the box.
+Kitty supports the required keyboard protocol without additional configuration.
 
 ## iTerm2
 
-### Regular TUI mode
+Regular terminal mode works without additional configuration.
 
-Works out of the box.
-
-### Fullscreen TUI mode
+### Fix slow fullscreen scrolling
 
-Pi owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling its native scrollback. With iTerm2's default fast-trackpad behavior, those reports can lose most of an accelerated wheel delta, making fullscreen scrolling much slower than regular 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.
 
-If fast mouse-wheel gestures move only about one line at a time in fullscreen mode:
+To change this behavior:
 
-1. Open **iTerm2 → Settings → Advanced**.
-2. Search for **Trackpad scrolls fast?** and set it to **No**.
+1. Open **iTerm2 > Settings > Advanced**.
+2. Search for **Trackpad scrolls fast?**.
+3. Set it to **No**.
 
-This is an iTerm2-wide workaround and may also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
+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
 
@@ -43,21 +46,23 @@ This fallback only works when Apex Code runs on the same Mac as Terminal.app. It
 
 ## Ghostty
 
-Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
+Add this mapping to Ghostty's configuration if `Alt+Backspace` does not work:
 
-```
+```text
 keybind = alt+backspace=text:\x1b\x7f
 ```
 
-Older Claude Code versions may have added this Ghostty mapping:
+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
 ```
 
 That mapping sends a raw linefeed byte. Inside Apex Code, that is indistinguishable from `Ctrl+J`, so tmux and Apex Code no longer see a real `shift+enter` key event.
 
-If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.
+### Open links in fullscreen mode
 
 Apex Code binds `Ctrl+J` as a default newline alias, so `Shift+Enter` keeps working in tmux via that remap without extra apex-code configuration.
 
@@ -67,7 +72,7 @@ In fullscreen mode, links remain clickable, but Ghostty does not show its hover
 
 ## WezTerm
 
-WezTerm usually works out of the box for `Shift+Enter` via xterm modifyOtherKeys. To use the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
+WezTerm normally reports `Shift+Enter` through xterm extended keys. To enable the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
 
 ```lua
 local wezterm = require 'wezterm'
@@ -91,7 +96,7 @@ config.keys = {
 return config
 ```
 
-If you already have a `config.keys` table, add the entry to it.
+### Position an IME candidate window in WSL
 
 On WSL, WezTerm may require a visible hardware cursor for IME candidate window positioning. If CJK IME candidates do not follow the text cursor, set `APEX_CODE_HARDWARE_CURSOR=1` before running Apex Code or set `showHardwareCursor` to `true` in settings. The temporary `PI_HARDWARE_CURSOR` alias also works.
 
@@ -106,27 +111,41 @@ mods = "Alt"
 chars = "\u001b[13;3u"
 ```
 
-Restart Alacritty after changing the config.
+Restart Alacritty after changing the file.
+
+## VS Code integrated terminal
 
-## VS Code (Integrated Terminal)
+VS Code 1.109.5 and newer enable the Kitty keyboard protocol in the integrated terminal by default.
 
-VS Code 1.109.5 and newer enable Kitty keyboard protocol in the integrated terminal by default, so `Shift+Enter` should work out of the box.
+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"
+}
+```
 
-VS Code versions older than 1.109.5 need an explicit terminal keybinding for `Shift+Enter`.
+The user `keybindings.json` file is normally located at:
 
-`keybindings.json` locations:
 - macOS: `~/Library/Application Support/Code/User/keybindings.json`
 - Linux: `~/.config/Code/User/keybindings.json`
 - Windows: `%APPDATA%\\Code\\User\\keybindings.json`
 
-Add to `keybindings.json`:
+## Zed integrated terminal
+
+Add these bindings to Zed's `keymap.json`:
 
 ```json
 {
-  "key": "shift+enter",
-  "command": "workbench.action.terminal.sendSequence",
-  "args": { "text": "\u001b[13;2u" },
-  "when": "terminalFocus"
+  "context": "Terminal",
+  "bindings": {
+    "shift-enter": ["terminal::SendText", "\u001b[13;2u"],
+    "ctrl--": ["terminal::SendText", "\u001b[45;5u"],
+    "ctrl-alt-]": ["terminal::SendText", "\u001b[93;7u"]
+  }
 }
 ```
 
@@ -140,16 +159,12 @@ Apex Code uses Windows-style keybindings when running natively on Windows or in
 - `Ctrl+Z` undoes editing on native Windows; WSL uses `Alt+Z` so `Ctrl+Z` can suspend Apex Code.
 - `Ctrl+Q` queues a follow-up message and `Alt+Q` restores queued messages.
 
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward `Shift+Enter` for inserting a new line:
+Open Windows Terminal's `settings.json` with `Ctrl+Shift+,` or **Settings > Open JSON file**. Add this object to its `actions` array:
 
 ```json
 {
-  "actions": [
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
-      "keys": "shift+enter"
-    }
-  ]
+  "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+  "keys": "shift+enter"
 }
 ```
 
@@ -157,23 +172,39 @@ Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward
 - Windows Terminal binds `Alt+Enter` to fullscreen by default. That prevents Apex Code from receiving `Alt+Enter` for follow-up queueing.
 - Remapping `Alt+Enter` to `sendInput` forwards the real key chord to Apex Code instead, or configure Windows Terminal to send the key and bind `app.message.followUp` to `alt+enter` in Apex Code to use it instead of the `Ctrl+Q` default.
 
-If you already have an `actions` array, add the object to it. Fully close and reopen Windows Terminal after changing its settings.
+### Use Alt+Enter for follow-ups
 
-## xfce4-terminal, terminator
+Windows Terminal binds `Alt+Enter` to fullscreen by default. Pi therefore uses `Ctrl+Q` for follow-ups on Windows and WSL.
 
-These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.
+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).
 
-For the best experience, use a terminal that supports the Kitty keyboard protocol:
-- [Kitty](https://sw.kovidgoyal.net/kitty/)
-- [Ghostty](https://ghostty.org/)
-- [WezTerm](https://wezfurlong.org/wezterm/)
-- [iTerm2](https://iterm2.com/)
-- [Alacritty](https://github.com/alacritty/alacritty) (requires compilation with Kitty protocol support)
+## xfce4-terminal and Terminator
 
-## IntelliJ IDEA (Integrated Terminal)
+These terminals cannot reliably distinguish modified Enter keys from plain `Enter`. Custom bindings such as `Ctrl+Enter` or `Shift+Enter` therefore may not work.
 
-The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
+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.
 
 If you want the hardware cursor visible, set `APEX_CODE_HARDWARE_CURSOR=1` before running Apex Code (disabled by default for compatibility; the temporary `PI_HARDWARE_CURSOR` alias also works).
 
-Consider using a dedicated terminal emulator for the best experience.
+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

@@ -1,20 +1,16 @@
-# Termux (Android) Setup
+# Run Pi on Android with Termux
 
 Apex Code runs on Android via [Termux](https://termux.dev/), a terminal emulator and Linux environment for Android.
 
-## Prerequisites
+## Before you begin
 
-1. Install [Termux](https://github.com/termux/termux-app#installation) from GitHub or F-Droid (not Google Play, that version is deprecated)
-2. Install [Termux:API](https://github.com/termux/termux-api#installation) from GitHub or F-Droid for clipboard and other device integrations
+Install Termux from [GitHub or F-Droid](https://github.com/termux/termux-app#installation). Do not use the deprecated Google Play build.
 
-## Installation
+[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.
 
-```bash
-# Update packages
-pkg update && pkg upgrade
+## Install Pi
 
-# Install dependencies
-pkg install nodejs termux-api git
+1. Update Termux packages:
 
 # Install Apex Code
 npm install -g --ignore-scripts apex-code
@@ -26,102 +22,96 @@ mkdir -p ~/.apex-code/agent
 apex-code
 ```
 
-## Clipboard Support
+3. Install Pi:
 
-Clipboard operations use `termux-clipboard-set` and `termux-clipboard-get` when running in Termux. The Termux:API app must be installed for these to work.
+   ```bash
+   npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+   ```
 
-Image clipboard is not supported on Termux (the `ctrl+v` image paste feature will not work).
+4. Verify the installation:
 
-## Example AGENTS.md for Termux
+   ```bash
+   apex-code --version
+   ```
 
 Create `~/.apex-code/agent/AGENTS.md` to help the agent understand the Termux environment:
 
-````markdown
-# Agent Environment: Termux on Android
+   ```bash
+   cd /path/to/working-folder
+   pi
+   ```
 
-## Location
-- **OS**: Android (Termux terminal emulator)
-- **Home**: `/data/data/com.termux/files/home`
-- **Prefix**: `/data/data/com.termux/files/usr`
-- **Shared storage**: `/storage/emulated/0` (Downloads, Documents, etc.)
+Continue with the main [Quickstart](quickstart.md#3-choose-a-model) to connect a model and run your first task.
 
-## Opening URLs
-```bash
-termux-open-url "https://example.com"
-```
+## Access Android shared storage
 
-## Opening Files
-```bash
-termux-open file.pdf          # Opens with default app
-termux-open --chooser image.jpg      # Choose app
-```
+Termux cannot access shared Android storage until you grant permission. Run this once:
 
-## Clipboard
 ```bash
-termux-clipboard-set "text"   # Copy
-termux-clipboard-get          # Paste
+termux-setup-storage
 ```
 
-## Notifications
-```bash
-termux-notification -t "Title" -c "Content"
-```
+After approval, Android shared storage is available under `/storage/emulated/0` and through the links Termux creates under `~/storage/`.
 
-## Device Info
-```bash
-termux-battery-status         # Battery info
-termux-wifi-connectioninfo    # WiFi info
-termux-telephony-deviceinfo   # Device info
-```
+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:
 
-## Sharing
 ```bash
-termux-share -a send file.txt # Share file
+pkg install termux-api
 ```
 
-## Other Useful Commands
+Verify the integration:
+
 ```bash
-termux-toast "message"        # Quick toast popup
-termux-vibrate                # Vibrate device
-termux-tts-speak "hello"      # Text to speech
-termux-camera-photo out.jpg   # Take photo
+printf 'Pi clipboard test' | termux-clipboard-set
+termux-clipboard-get
 ```
 
-## Notes
-- Termux:API app must be installed for `termux-*` commands
-- Use `pkg install termux-api` for the command-line tools
-- Storage permission needed for `/storage/emulated/0` access
-````
+The second command should print `Pi clipboard test`.
 
-## Limitations
+The Termux clipboard API supports text only. Pi's clipboard-paste shortcut inserts that text into the editor but cannot attach clipboard images.
 
-- **No image clipboard**: Termux clipboard API only supports text
-- **No native binaries**: Some optional native dependencies (like the clipboard module) are unavailable on Android ARM64 and are skipped during installation
-- **Storage access**: To access files in `/storage/emulated/0` (Downloads, etc.), run `termux-setup-storage` once to grant permissions
+## Add Termux-specific instructions
+
+Apex Code 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 `~/.apex-code/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 not working
+### Clipboard integration fails
 
-Ensure both apps are installed:
-1. Termux (from GitHub or F-Droid)
-2. Termux:API (from GitHub or F-Droid)
+Confirm that you installed both components:
 
-Then install the CLI tools:
-```bash
-pkg install termux-api
-```
+1. The Termux:API Android app from the same source as Termux
+2. The `termux-api` command-line package
 
-### Permission denied for shared storage
+Then run the clipboard verification commands above outside Pi. If they fail there, fix the Termux:API installation before retrying Pi's copy command.
 
-Run once to grant storage permissions:
-```bash
-termux-setup-storage
-```
+### Shared storage reports permission denied
 
-### Node.js installation issues
+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:
 
-If npm fails, try clearing the cache:
 ```bash
-npm cache clean --force
+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

@@ -1,18 +1,12 @@
 > Apex Code can create themes. Ask it to build one for your setup.
 
-# Themes
+Themes control the colors Pi uses in interactive mode and HTML exports. Pi includes `dark` and `light` themes. You can select one theme, follow your terminal's light or dark appearance, or create your own palette.
 
-Themes are JSON files that define colors for the TUI.
+<a id="selecting-a-theme"></a>
 
-## Table of Contents
+## Choose a theme
 
-- [Locations](#locations)
-- [Selecting a Theme](#selecting-a-theme)
-- [Creating a Custom Theme](#creating-a-custom-theme)
-- [Theme Format](#theme-format)
-- [Color Tokens](#color-tokens)
-- [Color Values](#color-values)
-- [Tips](#tips)
+Open `/settings` and select **Theme**. You can use one theme for every terminal appearance or choose separate themes for light and dark terminals.
 
 ## Locations
 
@@ -33,39 +27,39 @@ Select a theme via `/settings` or in `settings.json`:
 
 ```json
 {
-  "theme": "my-theme"
+  "theme": "dark"
 }
 ```
 
 On first run, Apex Code detects your terminal background and defaults to `dark` or `light`.
 
-### Initial Theme
-
-Start an interactive run with a theme without changing the saved setting:
-
-```bash
-pi --use-theme light
+```json
+{
+  "theme": "light/dark"
+}
 ```
 
-To follow terminal appearance, use `lightTheme/darkTheme` syntax:
+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/dark
+apex-code --use-theme light
+apex-code --use-theme light/dark
 ```
 
-The CLI value is the initial theme for that run. Choosing another theme later in `/settings` applies it immediately
-and saves it normally.
+See [CLI resources](cli.md#resources) for the command-line option.
 
-## Creating a Custom Theme
+## Create a custom theme
 
-1. Create a theme file:
+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).
 
 ```bash
 mkdir -p ~/.apex-code/agent/themes
 vim ~/.apex-code/agent/themes/my-theme.json
 ```
 
-2. Define the theme with all required colors (see [Color Tokens](#color-tokens)):
+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.
 
 ```json
 {
@@ -88,7 +82,8 @@ vim ~/.apex-code/agent/themes/my-theme.json
     "text": "",
     "thinkingText": "secondary",
     "selectedBg": "#2d2d30",
-    "scrollbarThumb": "#555566",
+    "scrollbarTrack": "secondary",
+    "scrollbarThumb": "",
     "searchMatchBg": "#2d2d30",
     "searchMatchText": "",
     "userMessageBg": "#2d2d30",
@@ -135,11 +130,22 @@ vim ~/.apex-code/agent/themes/my-theme.json
 }
 ```
 
-3. Select the theme via `/settings`.
+| 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 and cannot contain `/`. |
+| `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. |
 
 **Hot reload:** When you edit the currently active custom theme file, Apex Code reloads it automatically for immediate visual feedback.
 
-## Theme Format
+| Form | Example | Meaning |
+|---|---|---|
+| RGB hexadecimal | `"#00aaff"` | A six-digit RGB color. |
+| 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. |
 
 ```json
 {
@@ -158,73 +164,45 @@ vim ~/.apex-code/agent/themes/my-theme.json
 }
 ```
 
-- `name` is required, must be unique, and must not contain `/`.
-- `vars` is optional. Define reusable colors here, then reference them in `colors`.
-- `colors` must define all 51 required tokens. `thinkingMax`, `scrollbarThumb`, and the two search highlight tokens are optional and use the fallbacks listed below.
+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.
 
-The `$schema` field enables editor auto-completion and validation.
+Pi reports invalid theme files during startup and `/reload`.
 
-## Color Tokens
+## Find the color to change
 
-Every theme must define all 51 required color tokens. The optional tokens preserve compatibility with existing themes: `thinkingMax` falls back to `thinkingXhigh`, `scrollbarThumb` and `searchMatchBg` fall back to `selectedBg`, and `searchMatchText` falls back to `text`. Other search matches use `searchMatchText` on `searchMatchBg` with an underline; the current match reverses that foreground/background pair and uses bold text.
+Theme colors describe interface roles rather than individual components. Use these groups to find the relevant part of the schema:
 
-### Core UI (11 colors)
+| 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` |
 
-| Token | Purpose |
-|-------|---------|
-| `accent` | Primary accent (logo, selected items, cursor) |
-| `border` | Normal borders |
-| `borderAccent` | Highlighted borders |
-| `borderMuted` | Subtle borders (editor) |
-| `success` | Success states |
-| `error` | Error states |
-| `warning` | Warning states |
-| `muted` | Secondary text |
-| `dim` | Tertiary text |
-| `text` | Default text (usually `""`) |
-| `thinkingText` | Thinking block text |
-
-### Backgrounds & Content (11 required, 3 optional)
+The schema is the format reference. The built-in themes provide complete values that you can copy and adjust.
 
-| Token | Purpose |
-|-------|---------|
-| `selectedBg` | Selected line background |
-| `scrollbarThumb` | Fullscreen scrollbar thumb background; optional, falls back to `selectedBg` |
-| `searchMatchBg` | Transcript search match background and current-match text; optional, falls back to `selectedBg` |
-| `searchMatchText` | Transcript search match text and current-match background; optional, falls back to `text` |
-| `userMessageBg` | User message background |
-| `userMessageText` | User message text |
-| `customMessageBg` | Extension message background |
-| `customMessageText` | Extension message text |
-| `customMessageLabel` | Extension message label |
-| `toolPendingBg` | Tool box (pending) |
-| `toolSuccessBg` | Tool box (success) |
-| `toolErrorBg` | Tool box (error) |
-| `toolTitle` | Tool title |
-| `toolOutput` | Tool output text |
-
-### Markdown (10 colors)
+Five colors are optional and inherit another color when omitted:
 
-| Token | Purpose |
-|-------|---------|
-| `mdHeading` | Headings |
-| `mdLink` | Link text |
-| `mdLinkUrl` | Link URL |
-| `mdCode` | Inline code |
-| `mdCodeBlock` | Code block content |
-| `mdCodeBlockBorder` | Code block fences |
-| `mdQuote` | Blockquote text |
-| `mdQuoteBorder` | Blockquote border |
-| `mdHr` | Horizontal rule |
-| `mdListBullet` | List bullets |
-
-### Tool Diffs (3 colors)
+| Optional color | Fallback |
+|---|---|
+| `scrollbarTrack` | `muted` |
+| `scrollbarThumb` | `text` |
+| `searchMatchBg` | `selectedBg` |
+| `searchMatchText` | `text` |
+| `thinkingMax` | `thinkingXhigh` |
 
-| Token | Purpose |
-|-------|---------|
-| `toolDiffAdded` | Added lines |
-| `toolDiffRemoved` | Removed lines |
-| `toolDiffContext` | Context lines |
+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 `.apex-code/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).
 
 ### Syntax Highlighting (9 colors)