@kingingwang/pi-windows-arm64 1.1.0 → 1.2.0

package/bin/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## [1.2.0] - 2026-10-12
+
+### New Features
+
+- **Per-key OpenRouter model lists**: with an OpenRouter key, Pi lists only the models that key may use, with the key's context size, max output, and prices, including regional endpoints set in `models.json`. See [OpenRouter](docs/providers.md#openrouter).
+- **Published configuration schemas**: add `$schema` to `settings.json`, `models.json`, keybindings, and themes for editor validation and completion. See [Settings](docs/settings.md), [Models](docs/models.md), [Keybindings](docs/keybindings.md), and [Themes](docs/themes.md).
+- **Clipboard copies over remote sessions**: `PI_CLIPBOARD_OSC52=1` sends copied text to a remote client's clipboard when Pi cannot detect the remote session, such as a multiplexer attached from another machine. See [Pi Process Configuration](docs/environment-variables.md#pi-process-configuration).
+- **Codemode improvements**: tool declarations show input constraints such as integer, minimum/maximum, and default, and codemode rows show elapsed and total time. See [Codemode](docs/codemode.md).
+- **`before_agent_start` for extension-triggered runs**: runs started by `pi.sendMessage(..., { triggerTurn: true })` go through the same setup as prompts. See [Events and concurrency](docs/extensions.md#events-and-concurrency).
+
+### Breaking Changes
+
+- Published generated configuration schemas for models, settings, keybindings, and themes at `https://pi.dev/schemas/*.schema.json`. The theme schema moved to `https://pi.dev/schemas/theme.schema.json`; themes loaded during startup now receive the same schema validation as later reloads. Update theme `$schema` references, define reusable colors under `vars`, and remove unsupported metadata ([#9880](https://github.com/earendil-works/pi/pull/9880), [#10751](https://github.com/earendil-works/pi/pull/10751) by [@christianklotz](https://github.com/christianklotz))
+- Changed `before_agent_start` to also fire for runs started by `pi.sendMessage(..., { triggerTurn: true })` while idle. `BeforeAgentStartEvent` is now a union on `messageType`: `"user"` events carry `prompt` and `images`, and `"custom"` events carry the starting `message` and no `prompt`. Messages returned by handlers are added to both kinds of run, and pending `deliverAs: "nextTurn"` messages are delivered with the custom-message run. Handlers that should act only on user prompts must check `event.messageType === "user"` ([#10267](https://github.com/earendil-works/pi/issues/10267), [#5581](https://github.com/earendil-works/pi/issues/5581), [#10739](https://github.com/earendil-works/pi/pull/10739) by [@davidbrai](https://github.com/davidbrai))
+- Changed the session to count as busy while a run starts, including during `before_agent_start` handlers: `ctx.isIdle()` is false, `pi.sendMessage()` queues into the starting run instead of starting a second run that failed with "Agent is already processing", `pi.sendUserMessage()` requires `deliverAs`, and an abort requested meanwhile aborts the run once it starts ([#10739](https://github.com/earendil-works/pi/pull/10739) by [@davidbrai](https://github.com/davidbrai))
+- Changed `pi mcp list --json` to report `resources: true` for servers that offer resources instead of `resources` and `resourceTemplates` counts; Pi no longer lists resources when connecting ([#10526](https://github.com/earendil-works/pi/issues/10526))
+
+### Added
+
+- Added `reachesTools` to tool definitions, so tools that reach other tools (such as `codemode` and `tool_search`) declare which tools a call may reach; the MCP extension uses it to wait for the servers a call needs and to decide whether a replacement `codemode` or `tool_search` tool can reach MCP tools
+- Added `aliases` to tool namespaces; codemode's `describeNamespace()` and the `namespace` option of `searchTools()` match them, and MCP namespaces use the server name
+- Added per-key OpenRouter model lists: with an OpenRouter key, Pi lists only the chat models that key may use, with the key's context size, max output, and prices, including guardrails and regional endpoints set as the base URL in `models.json`. The list is saved and used offline ([#10353](https://github.com/earendil-works/pi/issues/10353), [#10672](https://github.com/earendil-works/pi/pull/10672) by [@davidbrai](https://github.com/davidbrai))
+- Added `PI_CLIPBOARD_OSC52=1` to send copied text to the terminal with OSC 52 after the local clipboard write, so copies reach a remote client's clipboard when Pi cannot detect the remote session, such as multiplexer attaches from another machine or remote IDE daemons ([#10826](https://github.com/earendil-works/pi/issues/10826), [#10835](https://github.com/earendil-works/pi/issues/10835), [#10114](https://github.com/earendil-works/pi/issues/10114))
+- Added elapsed time while a codemode script runs and its total time once finished to the codemode tool row, like bash rows ([#10708](https://github.com/earendil-works/pi/issues/10708))
+
+### Changed
+
+- Changed the `showHardwareCursor` setting to use only the terminal cursor instead of also drawing Pi's reverse-video cursor
+- Changed codemode tool declarations to show input constraints such as integer, minimum/maximum, length, pattern, and default as `@` tags on property comments, so scripts see them without the tool repeating them in descriptions ([#10707](https://github.com/earendil-works/pi/issues/10707))
+- Changed codemode declarations of MCP tools to spell out the result type (`content`, `structuredContent`, `isError`) instead of referring to `CallToolResult<T>`, which `describeTool()`, `searchTools()`, and `ALL_TOOLS` showed without defining it; the codemode description no longer includes the shared MCP types
+- Changed `serializeConversation()` (compaction, branch summaries, bug reports) to omit thinking blocks; replayed thinking is often not in the live context, so including it could make a summarization request larger than the context it summarizes and fail
+
+### Fixed
+
+- Fixed codemode ignoring a `// @options:` line that is not the first line of the script, which ran the script without the requested `timeout_ms`; the call now fails with an error before the script runs ([#10631](https://github.com/earendil-works/pi/issues/10631))
+- Fixed Mistral streams being aborted mid-generation (e.g. during long thinking) after the request timeout; the timeout now applies only to waiting for response headers ([#10609](https://github.com/earendil-works/pi/issues/10609))
+- Fixed a symlinked `AGENTS.md` in a git worktree nested inside its main repo causing no project context file to load ([#10681](https://github.com/earendil-works/pi/issues/10681))
+- Fixed the code mode tool description claiming every failed tool call rejects; a tool that declares an output schema resolves with its value on failure too (e.g. `bash` with a nonzero exit)
+- Fixed runs started by `pi.sendMessage(..., { triggerTurn: true })` removing system prompt sections added in `before_agent_start` after their first tool call, which changed the prompt mid-run and broke the provider prompt cache twice per run ([#10267](https://github.com/earendil-works/pi/issues/10267), [#10739](https://github.com/earendil-works/pi/pull/10739) by [@davidbrai](https://github.com/davidbrai))
+- Fixed codemode blocking the process for seconds to minutes after scripts with many `text()` calls; joining the output items was quadratic ([#10678](https://github.com/earendil-works/pi/issues/10678))
+- Fixed print mode (`-p`) exiting 0 without a warning when the final response was cut off at the model's output token limit; it now prints the partial text, writes a warning to stderr, and exits 1 ([#10799](https://github.com/earendil-works/pi/issues/10799))
+- Fixed `pi mcp login --help` and the CLI docs describing `--timeout` as only the wait for the browser; it limits the whole sign-in ([#10636](https://github.com/earendil-works/pi/issues/10636))
+- Fixed `~` not being expanded in `!pattern`, `+path`, and `-path` entries of the `extensions`, `skills`, `prompts`, and `themes` settings, so entries like `!~/skills/pdf` matched nothing ([#10765](https://github.com/earendil-works/pi/issues/10765))
+- Fixed MCP servers with resources registering no tools until every resource was listed; Pi no longer lists resources when connecting, so `/mcp` and `pi mcp list` show that a server offers resources instead of counting them ([#10526](https://github.com/earendil-works/pi/issues/10526))
+- Fixed MCP tool calls failing when the server returns structured content that is not an object (an array, `null`, or a primitive, as MCP 2026-07-28 allows); codemode declarations of MCP tools without an output schema now type `structuredContent` as `unknown` instead of an object ([#10416](https://github.com/earendil-works/pi/issues/10416))
+- Fixed reading or writing `auth.json` on Windows failing with `EPERM` when the previous lock folder was still being deleted; Pi now retries briefly before reporting the error ([#10801](https://github.com/earendil-works/pi/issues/10801))
+- Fixed OpenRouter router models such as `openrouter/auto` showing a cost of -$1,000,000 per 1M tokens; OpenRouter's negative placeholder prices are now 0 ([#10672](https://github.com/earendil-works/pi/pull/10672) by [@davidbrai](https://github.com/davidbrai))
+- Fixed Anthropic requests failing when the provider rejects the strict tool set for grammar size, tool count, or union limits; Pi now retries once with preferred tools non-strict ([#10409](https://github.com/earendil-works/pi/issues/10409))
+- Fixed "The upstream provider returned an error" not being retried as a transient provider error ([#10842](https://github.com/earendil-works/pi/issues/10842))
+- Fixed focused fullscreen overlays blocking mouse-wheel scrolling of the transcript ([#10769](https://github.com/earendil-works/pi/issues/10769))
+- Fixed fragmented terminal color replies leaking hex values into the prompt and opening the external editor (related reports: [#10256](https://github.com/earendil-works/pi/issues/10256), [#10657](https://github.com/earendil-works/pi/issues/10657))
+- Fixed inline images not rendering in Herdr since 1.1.0 ([#10774](https://github.com/earendil-works/pi/pull/10774) by [@ogulcancelik](https://github.com/ogulcancelik))
+- Fixed key bindings that name a shifted symbol, such as `+` or `ctrl++`, not matching under the Kitty keyboard protocol or modifyOtherKeys ([#9880](https://github.com/earendil-works/pi/pull/9880) by [@christianklotz](https://github.com/christianklotz))
+- Fixed the compaction status indicator embedded in a custom editor using the default muted colors instead of the editor border or thinking-level color, as the working indicator does ([#10809](https://github.com/earendil-works/pi/issues/10809), [#10810](https://github.com/earendil-works/pi/pull/10810) by [@Jay-Madden](https://github.com/Jay-Madden))
+- Fixed MCP tool calls that were cancelled or timed out while waiting for an OAuth refresh still being sent to the server once the refresh finished ([#10598](https://github.com/earendil-works/pi/issues/10598))
+- Fixed MCP OAuth sign-in accepting an authorization response with an `iss` parameter that could not be checked because no authorization server metadata was discovered; sign-in now fails with an issuer mismatch. Reported by [@AizenvoltPrime](https://github.com/AizenvoltPrime)
+- Fixed codemode failing with a broken bridge error when Pi runs under `node --watch` on Node 24 or 26 ([#10725](https://github.com/earendil-works/pi/issues/10725))
+
+### Removed
+
+- Removed the unreleased experimental server, client, and plugin stack (`src/experimental`, `src/cli/experimental`) and its source-only `./client` and `./experimental/plugin` exports; none of it was part of the published package. The `@earendil-works/pi-client`, `@earendil-works/pi-protocol`, and `@earendil-works/pi-server` packages it used are removed and no longer released
+- Removed the dependency on `@earendil-works/chord`
+
 ## [1.1.0] - 2026-10-07
 
 ### New Features

package/bin/docs/cli-integration.md

@@ -27,7 +27,7 @@ pi --print "Summarize the changes in this repository"
 
 Use print mode when only the final text is needed, including command substitution, pipelines, and one-shot jobs. Intermediate events are not exposed.
 
-Print mode writes errors to stderr. A final assistant response with an `error` or `aborted` stop reason produces a nonzero exit status.
+Print mode writes errors to stderr. A final assistant response with an `error` or `aborted` stop reason produces a nonzero exit status. A response cut off at the model's output token limit (`length` stop reason) still prints its partial text to stdout, writes a warning to stderr, and produces a nonzero exit status.
 
 When no mode is selected explicitly, non-TTY stdin or stdout also selects print mode. This allows piped input and output without adding `--print`.
 

package/bin/docs/cli.md

@@ -325,7 +325,7 @@ These commands work outside a session, so agents can run them through `bash`. Se
 | `pi mcp add <server> [options] --url <url>` | Add or replace a streamable HTTP server; `--header KEY=VALUE` (repeatable), `--bearer-token-env-var <NAME>` (sends `Authorization: Bearer ${NAME}`), `--oauth-client-id`, `--oauth-client-secret`, `--oauth-callback-port`, and `--oauth-client-name` configure authentication |
 | `pi mcp remove <server>` | Remove a server from `mcp.json`; stored OAuth credentials are kept |
 | `pi mcp list [--json]` | Connect to every enabled server and print its state, tools, and errors; exit with `1` when a config entry is invalid or an enabled server is not connected |
-| `pi mcp login <server> [--timeout <seconds>]` | Sign in to an OAuth server: open the authorization page and wait for the browser (default 300 seconds); a terminal also accepts the pasted redirect URL |
+| `pi mcp login <server> [--timeout <seconds>]` | Sign in to an OAuth server: open the authorization page and wait for the browser; a terminal also accepts the pasted redirect URL. `--timeout` limits the whole sign-in, including requests to the authorization server (default 300 seconds) |
 | `pi mcp logout <server>` | Delete the stored OAuth credentials of a server |
 
 `add` and `remove` change `~/.pi/agent/mcp.json`, or `.pi/mcp.json` in the current directory with `--local` (`-l`). `add` also takes `--exposure <mode>` (see [Exposure](mcp.md#exposure)) and `--description <text>` and does not connect; run `pi mcp list` to check the server.

package/bin/docs/codemode.md

@@ -6,7 +6,7 @@ The `codemode` tool lets the model write a JavaScript script that calls pi's oth
 
 The tool input is raw JavaScript source, not JSON and not a markdown code fence. It runs as the body of an async function in a QuickJS sandbox, so top-level `await` and `return` work. The sandbox has no Node APIs, file system, network, or timers; scripts reach the outside world only through tools and `models`.
 
-A script may start with an options line:
+A script may start with an options line. It must be the first line; an options line anywhere else fails the call before the script runs:
 
 ```js
 // @options: {"max_output_tokens": 2000, "timeout_ms": 60000}

package/bin/docs/compaction.md

@@ -279,7 +279,6 @@ Before summarization, messages are serialized to text via [`serializeConversatio
 
 ```
 [User]: What they said
-[Assistant thinking]: Internal reasoning
 [Assistant]: Response text
 [Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
 [Tool result]: Output from tool
@@ -287,6 +286,8 @@ Before summarization, messages are serialized to text via [`serializeConversatio
 
 This prevents the model from treating it as a conversation to continue.
 
+Thinking blocks are omitted. Providers return summaries of the real reasoning, and replayed thinking is often not part of the model's live context, so including it could make the summarization request larger than the context it summarizes.
+
 Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated. This keeps summarization requests within reasonable token budgets, since tool results (especially from `read` and `bash`) are typically the largest contributors to context size.
 
 ## Custom Summarization via Extensions
@@ -346,7 +347,6 @@ pi.on("session_before_compact", async (event, ctx) => {
   );
   // Returns:
   // [User]: message text
-  // [Assistant thinking]: thinking content
   // [Assistant]: response text
   // [Assistant tool calls]: read(path="..."); bash(command="...")
   // [Tool result]: output text

package/bin/docs/environment-variables.md

@@ -86,8 +86,9 @@ These variables are read by Pi itself:
 | `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
 | `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
 | `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
-| `PI_RADIUS_GATEWAY` | Override the Radius gateway origin used by `/bug` uploads and Radius relay connections |
+| `PI_RADIUS_GATEWAY` | Override the Radius gateway origin used by `/bug` uploads |
 | `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
+| `PI_CLIPBOARD_OSC52` | Set to `1` to also send copied text to the terminal with OSC 52 after the local clipboard write, as Pi does over SSH. Use it when a remote client reaches Pi without SSH variables, such as a multiplexer attached from another machine or a remote IDE daemon |
 | `PI_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
 | `PI_PROGRAM_STATUS` | Override OSC 7501 program status detection: `1` always reports, `0` never reports; otherwise Pi reports only after the terminal confirms support. See [Terminal setup](terminal-setup.md#program-status) |
 | `PI_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |

package/bin/docs/extensions.md

@@ -60,6 +60,7 @@ Start long-lived resources from `session_start` or from the command or tool that
 Close session-scoped resources from an idempotent `session_shutdown` handler.
 
 A run proceeds from input and `before_agent_start`, through model, message, and tool events, to `agent_end`.
+Pi counts as busy while a run starts, including the compaction check and `before_agent_start`, so messages sent meanwhile go into the starting run.
 Automatic retries, recovery, compaction, or queued work can continue afterward.
 <a id="agent_start--agent_end--agent_before_settle--agent_settled"></a>
 
@@ -100,7 +101,7 @@ Use each event’s declared result type rather than assuming every return value
 
 Events cover resource discovery, sessions, agent and message lifecycle, providers, tools, and raw input.
 
-`before_agent_start` exposes both the current prompt and its structured `systemPromptOptions`. Prefer changing prompt sections, selected tools, or guidelines so Pi can append a transcript delta. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt for that run while the transcript continues recording the structured sections. Providers receive the forced text as their leading system prompt.
+`before_agent_start` exposes both the current prompt and its structured `systemPromptOptions`. `event.messageType` says what started the run: `"user"` for a prompt or `pi.sendUserMessage()`, with `prompt` and `images`; `"custom"` for `pi.sendMessage(..., { triggerTurn: true })`, with the starting `message` and no `prompt`. A returned `message` is added to either kind of run; check `messageType` to skip runs started by custom messages. Prefer changing prompt sections, selected tools, or guidelines so Pi can append a transcript delta. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt for that run while the transcript continues recording the structured sections. Providers receive the forced text as their leading system prompt.
 
 `message_end` can replace a finalized message while preserving its role. `tool_call` can mutate input or block execution. `tool_result` handlers compose, with each handler seeing prior changes.
 
@@ -159,9 +160,9 @@ See [`hello.ts`](../examples/extensions/hello.ts), [`todo.ts`](../examples/exten
 - `deferred`: like `codemode`, but codemode tools do not list it; `tool_search` can find and activate it.
 - `hidden`: registered but unreachable. Re-register a tool with `exposure: "hidden"` to withdraw it, since tools cannot be unregistered.
 
-`namespace: { name, description, instructions }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading with its `description`. `instructions` holds longer usage guidance; it is not listed, and codemode scripts read it with `describeNamespace(name)`.
+`namespace: { name, aliases, description, instructions }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading with its `description`. `instructions` holds longer usage guidance; it is not listed, and codemode scripts read it with `describeNamespace(name)`. `aliases` are other names scripts may look the namespace up by, for example the server name `docs` for `mcp__docs`; a name and the same name as a script identifier (`my-docs`, `my_docs`) match alike.
 
-Registering a `direct` or `model-only` tool activates it; the other exposures are not activated on registration. The active set (`pi.getActiveTools()`, `pi.setActiveTools()`) is the set of tools declared to the model. `pi.getAllTools()` reports each tool's `exposure`, `namespace`, and `annotations`.
+Registering a `direct` or `model-only` tool activates it; the other exposures are not activated on registration. The active set (`pi.getActiveTools()`, `pi.setActiveTools()`) is the set of tools declared to the model. `pi.getAllTools()` reports each tool's `exposure`, `namespace`, `annotations`, and `reachesTools`.
 
 `annotations` are hints about what a tool does, with the meaning of MCP tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. MCP tools carry the hints their server declares. Missing hints take the MCP defaults: a tool is not read-only, and may be destructive and reach an open world. The hints are not verified, but a permission extension can use them to decide which calls to confirm. This confirms the calls Codex asks approval for:
 
@@ -177,7 +178,9 @@ pi.on("tool_call", async (event, ctx) => {
 });
 ```
 
-A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure, namespace, and prompt guidelines. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. The default system prompt leaves hidden tools out of its tool list and rules, and names no tool in the skills hint when the file reader is hidden, so the orchestrating tool should present their guidelines itself. `codemode` uses only this hook, `exposure`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure, namespace, and prompt guidelines. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. The default system prompt leaves hidden tools out of its tool list and rules, and names no tool in the skills hint when the file reader is hidden, so the orchestrating tool should present their guidelines itself. `codemode` uses only this hook, `exposure`, `reachesTools`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+
+A tool that reaches other tools declares which ones a call may reach with `reachesTools(input)`: `"all"`, or the words of the input that may name them, where a word refers to every tool or namespace whose name it contains. `codemode` returns `"all"` for scripts that search or list tools and the words of the script otherwise; `tool_search` always returns `"all"`. Extensions that register tools late use it from their `tool_call` handler to finish registering the tools a call needs before it runs, as the MCP extension does for servers that are still connecting. The MCP extension also activates `codemode` or `tool_search` for MCP tools only when the tool of that name declares `reachesTools`.
 
 ### Activate tools dynamically
 

package/bin/docs/keybindings.md

@@ -12,6 +12,7 @@ Map each action identifier to one key or a list of keys:
 
 ```json
 {
+  "$schema": "https://pi.dev/schemas/keybindings.schema.json",
   "app.session.new": "ctrl+shift+n",
   "app.session.tree": ["ctrl+shift+t", "alt+shift+t"]
 }

package/bin/docs/mcp.md

@@ -265,7 +265,7 @@ Changes to enabled state or exposure apply only to the current session. A file-c
 
 An installed extension that registers `/mcp`, such as `pi-mcp-adapter`, replaces the built-in MCP support for sessions. Pi then does not read `mcp.json` or connect its servers in a session, and `/mcp` belongs to the extension. Remove the extension to restore the built-in behavior. To disable built-in MCP support without a replacement, disable `mcp` under Built-in in `pi config`, or set `"extensions": ["-builtin:mcp"]` in [settings](settings.md#resources). `--no-mcp` disables it for one run.
 
-An extension that registers `codemode` or `tool_search` similarly replaces the built-in tool with that name. Shell-level `pi mcp` commands always use the built-in implementation.
+An extension that registers `codemode` or `tool_search` similarly replaces the built-in tool with that name. Pi activates the replacement for MCP servers and waits for the servers its calls need only when it declares [`reachesTools`](extensions.md#tool-exposure). Shell-level `pi mcp` commands always use the built-in implementation.
 
 ### Use MCP from the SDK
 

package/bin/docs/models.md

@@ -48,6 +48,7 @@ Use [`models.json`](configuration.md#agent-directory) when an endpoint speaks an
 
 ```json
 {
+  "$schema": "https://pi.dev/schemas/models.schema.json",
   "providers": {
     "ollama": {
       "baseUrl": "http://localhost:11434/v1",

package/bin/docs/providers.md

@@ -113,6 +113,26 @@ Radius is currently in early alpha and evolving quickly. See [radius.earendil.co
 
 Radius authentication uses its gateway catalog and caches refreshed model metadata for later offline startup. A custom Radius gateway configured in `models.json` uses its own catalog rather than inheriting the public `radius.pi.dev` catalog.
 
+### OpenRouter
+
+Authenticate with `/login openrouter` or `OPENROUTER_API_KEY`.
+
+With a key, Pi lists only the OpenRouter chat models that key may use, with the key's context size, max output, and prices. These come from OpenRouter's `/models/user` endpoint and reflect guardrails and provider restrictions set in OpenRouter. Image and classifier models are not filtered.
+
+Pi refreshes the list in the background at startup in interactive mode, when `/model` opens, after `/login`, and on `pi update --models`. The last list is saved and used offline and in `pi -p` and RPC mode. After switching keys outside `/login`, the previous key's list stays until the next refresh.
+
+Regional endpoints filter models to their region. To use one, set the base URL in [`models.json`](models.md#configure-a-compatible-endpoint):
+
+```json
+{
+  "providers": {
+    "openrouter": { "baseUrl": "https://us.openrouter.ai/api/v1" }
+  }
+}
+```
+
+If the base URL rejects the key at `/models/user` or does not have that endpoint, for example a proxy configured as the OpenRouter base URL, Pi lists every OpenRouter model.
+
 ### Azure OpenAI
 
 The provider ID is `azure` (formerly `azure-openai-responses`). Use it as the key in `auth.json`, `models.json`, and `settings.json`, and in model references such as `--model azure/gpt-5.4`.

package/bin/docs/settings.md

@@ -2,6 +2,8 @@
 
 This reference lists user-configurable settings, their types, defaults, and purposes. Project settings override agent-directory settings. Resource lists are combined. See [Configuration](configuration.md) for file locations and trust behavior.
 
+Add `"$schema": "https://pi.dev/schemas/settings.schema.json"` to `settings.json` for editor validation and completion.
+
 ## Model and thinking
 
 <a id="model-cycling"></a>
@@ -99,7 +101,7 @@ See [Compaction Reference](compaction.md) for trigger, summarization, and valida
 | `editorPaddingX` | number | `0` | Horizontal editor padding from 0 to 3 cells. |
 | `outputPad` | `0 \| 1` | `1` | Horizontal transcript padding for messages, tool output, `!` command output, and summary blocks. |
 | `autocompleteMaxVisible` | number | `5` | Visible autocomplete entries, from 3 to 20. |
-| `showHardwareCursor` | boolean | `false` | Show the terminal cursor while Pi positions it for input methods. |
+| `showHardwareCursor` | boolean | `false` | Use the terminal cursor instead of Pi's drawn cursor. Pi still positions it for input methods. |
 | `terminal.showImages` | boolean | `true` | Display inline images when supported. |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells. |
 | `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when rendered content shrinks. |

package/bin/docs/themes.md

@@ -58,7 +58,7 @@ 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.
+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://pi.dev/schemas/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`.
@@ -78,6 +78,8 @@ Use the theme name as the filename. Pi hot-reloads the active user theme only fr
 | `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. |
 
+Theme objects are strict: only documented top-level fields and color tokens are accepted. Define reusable custom colors under `vars`; custom keys under `colors` or `export` and additional top-level metadata are rejected.
+
 A color can be written in six forms:
 
 | Form | Example | Meaning |
@@ -93,7 +95,7 @@ Terminal default colors render as the terminal's own colors. Where Pi needs a co
 
 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.
+Use the [theme JSON schema](https://pi.dev/schemas/theme.schema.json) for the exact properties, required colors, and accepted value types.
 
 Pi reports invalid theme files during startup and `/reload`.
 

package/bin/docs/tui.md

@@ -45,7 +45,7 @@ Prefer these components over rebuilding selection, scrolling, text editing, or w
 
 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.
+A component that displays a text cursor should implement `Focusable` and place `CURSOR_MARKER` immediately before its visual cursor. Wrap the cursor cell in `renderFakeCursor()` so the TUI draws it in reverse video, or hides it after `CURSOR_MARKER` when the hardware cursor is shown. The TUI uses the 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.
 

package/bin/examples/README.md

@@ -28,9 +28,6 @@ Example extensions demonstrating:
 - External integrations (SSH, file watchers, system theme sync)
 - Custom providers (Anthropic with custom streaming, GitLab Duo)
 
-### [plugins/pi-example-plugin/](plugins/pi-example-plugin/)
-An experimental plugin package that Pi automatically builds into separate Session-worker and TUI Chord facets.
-
 ## Documentation
 
 - [SDK Examples](sdk/README.md)

package/bin/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/bin/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/bin/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/bin/examples/extensions/dynamic-resources/dynamic.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"$schema": "https://pi.dev/schemas/theme.schema.json",
 	"name": "dynamic-resources",
 	"vars": {
 		"cyan": "#00d7ff",

package/bin/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "1.1.0",
+			"version": "1.2.0",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/bin/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-gondolin",
 	"private": true,
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/bin/examples/extensions/overlay-test.ts

@@ -9,7 +9,7 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
-import { CURSOR_MARKER, type Focusable, matchesKey, visibleWidth } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, type Focusable, matchesKey, renderFakeCursor, visibleWidth } from "@earendil-works/pi-tui";
 
 export default function (pi: ExtensionAPI) {
 	pi.registerCommand("overlay-test", {
@@ -131,7 +131,7 @@ class OverlayTestComponent implements Focusable {
 					const after = inputDisplay.slice(item.cursor + 1);
 					// Emit hardware cursor marker for IME support when focused
 					const marker = this.focused ? CURSOR_MARKER : "";
-					inputDisplay = `${before}${marker}\x1b[7m${cursorChar}\x1b[27m${after}`;
+					inputDisplay = `${before}${marker}${renderFakeCursor(cursorChar)}${after}`;
 				}
 				content = `${prefix + label} ${inputDisplay}`;
 			} else {

package/bin/examples/extensions/plan-mode/index.ts

@@ -197,8 +197,12 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		};
 	});
 
-	// Inject plan/execution context before agent starts
-	pi.on("before_agent_start", async () => {
+	// Inject plan/execution context before a user prompt. Runs started by custom messages, such as
+	// background task notifications, skip it: the context from the last prompt is still in the
+	// conversation, and adding it again on every notification would only repeat it.
+	pi.on("before_agent_start", async (event) => {
+		if (event.messageType !== "user") return;
+
 		if (planModeEnabled) {
 			return {
 				message: {

package/bin/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.1.0",
+			"version": "1.2.0",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/bin/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/bin/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/bin/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/bin/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@earendil-works/pi-coding-agent",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -18,21 +18,13 @@
 		},
 		"./rpc-entry": {
 			"import": "./dist/bundle/rpc-entry.js"
-		},
-		"./client": {
-			"source": "./src/client/index.ts"
-		},
-		"./experimental/plugin": {
-			"source": "./src/experimental/plugin.ts"
 		}
 	},
 	"files": [
 		"dist",
-		"!dist/client",
-		"!dist/experimental",
-		"!dist/cli/experimental",
 		"docs",
 		"examples",
+		"schemas",
 		"containerization.md",
 		"CHANGELOG.md"
 	],
@@ -40,19 +32,19 @@
 		"clean": "shx rm -rf dist",
 		"build": "npm run build:unbundled && node ../../scripts/build-coding-agent-bundle.mjs",
 		"build:unbundled": "tsc -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
-		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm --prefix ../protocol run build && npm --prefix ../client run build && npm run build && bun build --compile --no-compile-autoload-bunfig --no-compile-autoload-dotenv ./dist/bun/cli.js ./src/utils/image-resize-worker.ts ./src/extensions/codemode/worker.ts --outfile dist/pi && npm run copy-binary-assets",
+		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm run build && bun build --compile --no-compile-autoload-bunfig --no-compile-autoload-dotenv ./dist/bun/cli.js ./src/utils/image-resize-worker.ts ./src/extensions/codemode/worker.ts --outfile dist/pi && npm run copy-binary-assets",
 		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/",
 		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
 		"test": "vitest --run",
+		"generate:schemas": "node --import ./src/experimental/source-resolver.ts scripts/generate-schemas.ts",
 		"prepublishOnly": "npm run clean && npm run build"
 	},
 	"dependencies": {
-		"@earendil-works/chord": "^1.1.0",
-		"@earendil-works/pi-agent-core": "^1.1.0",
-		"@earendil-works/pi-ai": "^1.1.0",
-		"@earendil-works/pi-codemode": "^1.1.0",
-		"@earendil-works/pi-mcp": "^1.1.0",
-		"@earendil-works/pi-tui": "^1.1.0",
+		"@earendil-works/pi-agent-core": "^1.2.0",
+		"@earendil-works/pi-ai": "^1.2.0",
+		"@earendil-works/pi-codemode": "^1.2.0",
+		"@earendil-works/pi-mcp": "^1.2.0",
+		"@earendil-works/pi-tui": "^1.2.0",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"brace-expansion": "5.0.12",
 		"chalk": "6.0.0",
@@ -75,9 +67,6 @@
 		"protobufjs": "7.6.6"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-client": "^1.1.0",
-		"@earendil-works/pi-protocol": "^1.1.0",
-		"@earendil-works/pi-server": "^1.1.0",
 		"@types/cross-spawn": "6.0.6",
 		"@types/hosted-git-info": "3.0.5",
 		"@types/node": "22.19.19",

package/bin/pi.exe

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/pi.exe
-size: 107966976 bytes
-sha256: d9f8bb9964cbe655f94c0f316b0d44d83c3600c33811921af1838cb8168f8448
+size: 108142080 bytes
+sha256: 0d8ebac9354d1e795b628ae67937c10cd12fc22b53c4e4d4bfd846229d1b5710

package/bin/theme/dark.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"$schema": "https://pi.dev/schemas/theme.schema.json",
 	"name": "dark",
 	"appearance": "dark",
 	"vars": {

package/bin/theme/light.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"$schema": "https://pi.dev/schemas/theme.schema.json",
 	"name": "light",
 	"appearance": "light",
 	"vars": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kingingwang/pi-windows-arm64",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Pi standalone binary for windows-arm64 (fork distribution)",
   "license": "MIT",
   "os": [

package/bin/examples/plugins/pi-example-plugin/README.md

@@ -1,38 +0,0 @@
-# `@earendil-works/pi-example-plugin`
-
-This package provides conventional `session` and `tui` Chord facets. The Session-worker facet provides a remote greeting service. The TUI facet contributes `/hello` and calls that service.
-
-The package needs no build script. Pi asks Chord to discover `src/session.ts` and `src/tui.ts`, builds both entries into its server-owned plugin cache, and sends the TUI artifact to clients.
-
-From the repository root:
-
-```bash
-PI_EXPERIMENTAL=1 ./pi-test.sh server \
-  -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
-```
-
-Alternatively, a client can select the plugin for the Session it creates or resumes on one local server:
-
-```bash
-PI_EXPERIMENTAL=1 ./pi-test.sh client \
-  -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
-```
-
-Repeat `-e` to select multiple plugin packages. Client paths are resolved locally and sent only to a Unix server; Radius clients cannot select server filesystem paths. The Session and matching TUI facets are stored with that Session, so later server generations and clients can resume it without plugin arguments. Other Sessions and their workers are unaffected. An active Session rejects a different package selection instead of being restarted.
-
-`server -e` establishes the server profile's default Session and TUI facets. Starting an explicit foreground server without `-e` clears that default. Client selection never changes the server's root facet generation.
-
-Run `/hello Armin` in the TUI. After editing a facet, run `/reload`. The server atomically rebuilds the package, reloads the attached Session-worker generation, updates the current TUI generation, and serves the new artifact to future clients.
-
-Package metadata can override or disable conventional entries:
-
-```json
-{
-  "chord": {
-    "facets": {
-      "session": "./src/worker.ts",
-      "tui": false
-    }
-  }
-}
-```

package/bin/examples/plugins/pi-example-plugin/package.json

@@ -1,10 +0,0 @@
-{
-	"name": "@earendil-works/pi-example-plugin",
-	"version": "1.0.0",
-	"private": true,
-	"type": "module",
-	"peerDependencies": {
-		"@earendil-works/chord": "^0.84.4",
-		"@earendil-works/pi-coding-agent": "^0.84.4"
-	}
-}

package/bin/examples/plugins/pi-example-plugin/src/contract.ts

@@ -1,13 +0,0 @@
-import { type Context, defineService, type ReplicatedState } from "@earendil-works/chord";
-
-export interface ExampleFacetReply {
-	readonly message: string;
-	readonly workerActivations: number;
-}
-
-export interface ExampleFacetService {
-	readonly workerActivations: ReplicatedState<{ count: number }>;
-	greet(input: { readonly name: string }, context: Context): Promise<ExampleFacetReply>;
-}
-
-export const ExampleFacetService = defineService<ExampleFacetService>("pi.example-plugin.greeting");

package/bin/examples/plugins/pi-example-plugin/src/session.ts

@@ -1,24 +0,0 @@
-import { defineFacet } from "@earendil-works/chord";
-import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
-import { ExampleFacetService } from "./contract.ts";
-
-export default defineFacet({
-	id: "@earendil-works/pi-example-plugin/session",
-	setup(env) {
-		const workerActivations = env.replicatedState({ count: 0 });
-		env.provide(ExampleFacetService, {
-			workerActivations,
-			async greet({ name }) {
-				return {
-					message: `Hello ${name} from the bundled Session worker facet!!!`,
-					workerActivations: workerActivations.value.count,
-				};
-			},
-		});
-		env.onActivate(() => {
-			workerActivations.change(BACKGROUND_CONTEXT, (draft) => {
-				draft.count += 1;
-			});
-		});
-	},
-});

package/bin/examples/plugins/pi-example-plugin/src/tui.ts

@@ -1,31 +0,0 @@
-import { defineFacet } from "@earendil-works/chord";
-import { AgentController, PresentationUI, SlashCommands } from "@earendil-works/pi-coding-agent/experimental/plugin";
-import { ExampleFacetService } from "./contract.ts";
-
-export default defineFacet({
-	id: "@earendil-works/pi-example-plugin/tui",
-	setup(env) {
-		const example = env.use(ExampleFacetService);
-		const commands = env.use(SlashCommands);
-		const controller = env.use(AgentController);
-		const ui = env.use(PresentationUI);
-		env.onActivate(() => {
-			env.own(
-				commands.replace({
-					name: "hello",
-					description: "Call the bundled Session worker facet",
-					argumentHint: "<name>",
-					async run(args, context) {
-						const message = args.length === 0 ? "from the TUI" : args;
-						const reply = await example.greet({ name: message }, context);
-						ui.showStatus(
-							`We got this: ${reply.message} Worker activations: ${reply.workerActivations}.`,
-							context,
-						);
-						return controller.prompt({ message: `pong: ${message}`, images: null }, context);
-					},
-				}),
-			);
-		});
-	},
-});

package/bin/theme/theme-schema.json

@@ -1,361 +0,0 @@
-{
-	"$schema": "http://json-schema.org/draft-07/schema#",
-	"title": "Pi Coding Agent Theme",
-	"description": "Theme schema for Pi coding agent",
-	"type": "object",
-	"required": ["name", "colors"],
-	"properties": {
-		"$schema": {
-			"type": "string",
-			"description": "JSON schema reference"
-		},
-		"name": {
-			"type": "string",
-			"pattern": "^[^/]+$",
-			"description": "Theme name. Must not contain '/' because it is reserved for automatic light/dark theme settings."
-		},
-		"appearance": {
-			"type": "string",
-			"enum": ["dark", "light"],
-			"description": "Background the theme is designed for. Detected from the theme colors when omitted."
-		},
-		"vars": {
-			"type": "object",
-			"description": "Reusable color variables",
-			"additionalProperties": {
-				"oneOf": [
-					{
-						"type": "string",
-						"description": "Hex color (#RGB or #RRGGBB), OKLCH or OKHSL color, variable reference, or empty string for terminal default"
-					},
-					{
-						"type": "integer",
-						"minimum": 0,
-						"maximum": 255,
-						"description": "256-color palette index (0-255)"
-					}
-				]
-			}
-		},
-		"colors": {
-			"type": "object",
-			"description": "Theme color definitions (scrollbar, thinkingMax, and search highlight colors are optional and use compatible fallbacks)",
-			"required": [
-				"accent",
-				"border",
-				"borderAccent",
-				"borderMuted",
-				"success",
-				"error",
-				"warning",
-				"muted",
-				"dim",
-				"text",
-				"thinkingText",
-				"selectedBg",
-				"userMessageBg",
-				"userMessageText",
-				"customMessageBg",
-				"customMessageText",
-				"customMessageLabel",
-				"toolPendingBg",
-				"toolSuccessBg",
-				"toolErrorBg",
-				"toolTitle",
-				"toolOutput",
-				"mdHeading",
-				"mdLink",
-				"mdLinkUrl",
-				"mdCode",
-				"mdCodeBlock",
-				"mdCodeBlockBorder",
-				"mdQuote",
-				"mdQuoteBorder",
-				"mdHr",
-				"mdListBullet",
-				"toolDiffAdded",
-				"toolDiffRemoved",
-				"toolDiffContext",
-				"syntaxComment",
-				"syntaxKeyword",
-				"syntaxFunction",
-				"syntaxVariable",
-				"syntaxString",
-				"syntaxNumber",
-				"syntaxType",
-				"syntaxOperator",
-				"syntaxPunctuation",
-				"thinkingOff",
-				"thinkingMinimal",
-				"thinkingLow",
-				"thinkingMedium",
-				"thinkingHigh",
-				"thinkingXhigh",
-				"bashMode"
-			],
-			"properties": {
-				"accent": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Primary accent color (logo, selected items, cursor)"
-				},
-				"border": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Normal borders"
-				},
-				"borderAccent": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Highlighted borders"
-				},
-				"borderMuted": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Subtle borders"
-				},
-				"success": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Success states"
-				},
-				"error": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Error states"
-				},
-				"warning": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Warning states"
-				},
-				"muted": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Secondary/dimmed text"
-				},
-				"dim": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Very dimmed text (more subtle than muted)"
-				},
-				"text": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Default text color (usually empty string)"
-				},
-				"thinkingText": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking block text color"
-				},
-				"selectedBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Selected item background"
-				},
-				"scrollbarTrack": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Fullscreen scrollbar track foreground (falls back to muted when omitted)"
-				},
-				"scrollbarThumb": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Fullscreen scrollbar thumb foreground (falls back to text when omitted)"
-				},
-				"searchMatchBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Transcript search match background and current-match text (falls back to selectedBg when omitted)"
-				},
-				"searchMatchText": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Transcript search match text and current-match background (falls back to text when omitted)"
-				},
-				"userMessageBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "User message background"
-				},
-				"userMessageText": {
-					"$ref": "#/$defs/colorValue",
-					"description": "User message text color"
-				},
-				"customMessageBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Custom message background (hook-injected messages)"
-				},
-				"customMessageText": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Custom message text color"
-				},
-				"customMessageLabel": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Custom message type label color"
-				},
-				"toolPendingBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Tool execution box (pending state)"
-				},
-				"toolSuccessBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Tool execution box (success state)"
-				},
-				"toolErrorBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Tool execution box (error state)"
-				},
-				"toolTitle": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Tool execution box title color"
-				},
-				"toolOutput": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Tool execution box output text color"
-				},
-				"mdHeading": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown heading text"
-				},
-				"mdLink": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown link text"
-				},
-				"mdLinkUrl": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown link URL"
-				},
-				"mdCode": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown inline code"
-				},
-				"mdCodeBlock": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown code block content"
-				},
-				"mdCodeBlockBorder": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown code block fences"
-				},
-				"mdQuote": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown blockquote text"
-				},
-				"mdQuoteBorder": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown blockquote border"
-				},
-				"mdHr": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown horizontal rule"
-				},
-				"mdListBullet": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Markdown list bullets/numbers"
-				},
-				"toolDiffAdded": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Added lines in tool diffs"
-				},
-				"toolDiffRemoved": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Removed lines in tool diffs"
-				},
-				"toolDiffContext": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Context lines in tool diffs"
-				},
-				"syntaxComment": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: comments"
-				},
-				"syntaxKeyword": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: keywords"
-				},
-				"syntaxFunction": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: function names"
-				},
-				"syntaxVariable": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: variable names"
-				},
-				"syntaxString": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: string literals"
-				},
-				"syntaxNumber": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: number literals"
-				},
-				"syntaxType": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: type names"
-				},
-				"syntaxOperator": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: operators"
-				},
-				"syntaxPunctuation": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Syntax highlighting: punctuation"
-				},
-				"thinkingOff": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking level border: off"
-				},
-				"thinkingMinimal": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking level border: minimal"
-				},
-				"thinkingLow": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking level border: low"
-				},
-				"thinkingMedium": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking level border: medium"
-				},
-				"thinkingHigh": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking level border: high"
-				},
-				"thinkingXhigh": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking level border: xhigh"
-				},
-				"thinkingMax": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Thinking level border: max (falls back to thinkingXhigh when omitted)"
-				},
-				"bashMode": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Editor border color in bash mode"
-				}
-			},
-			"additionalProperties": false
-		},
-		"export": {
-			"type": "object",
-			"description": "Optional colors for HTML export (defaults derived from userMessageBg if not specified)",
-			"properties": {
-				"pageBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Page background color"
-				},
-				"cardBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Card/container background color"
-				},
-				"infoBg": {
-					"$ref": "#/$defs/colorValue",
-					"description": "Info sections background (system prompt, notices)"
-				}
-			},
-			"additionalProperties": false
-		}
-	},
-	"additionalProperties": false,
-	"$defs": {
-		"colorValue": {
-			"oneOf": [
-				{
-					"type": "string",
-					"description": "Hex color (#RGB or #RRGGBB), OKLCH or OKHSL color, variable reference, or empty string for terminal default"
-				},
-				{
-					"type": "integer",
-					"minimum": 0,
-					"maximum": 255,
-					"description": "256-color palette index (0-255)"
-				}
-			]
-		}
-	}
-}