@relay-harness/coding-agent 0.0.0-stage → 1.0.3

package/docs/themes.md

@@ -0,0 +1,136 @@
+# Customize Relay with themes
+
+Themes control the colors Relay uses in interactive mode and HTML exports. Relay 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 Relay's colors from your terminal's theme, so Relay matches the terminal instead of bringing its own palette:
+
+- Relay queries the terminal's default foreground and background colors and its 16 ANSI colors.
+- Each Relay color takes its hue from one ANSI color, for example errors from red and links from blue.
+- Relay 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, Relay 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 | Relay'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. |
+
+Relay asks the terminal for its colors when it starts. Terminals usually answer within a few milliseconds, and Relay waits at most 100 ms before showing the startup header. If the terminal does not answer in time, Relay 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, Relay uses `system`.
+
+Automatic mode stores the light theme first and the dark theme second:
+
+```json
+{
+  "theme": "light/dark"
+}
+```
+
+Relay decides whether the terminal is light or dark from its reported background and foreground colors. If the terminal does not report its background, Relay 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, Relay changes themes when the terminal reports an appearance change. Theme names cannot contain `/` because Relay reserves it for this setting format.
+
+Use `--use-theme` to choose the initial theme for one invocation without changing the saved setting:
+
+```bash
+relay --use-theme light
+relay --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/eltonssouza/relay-harness/tree/main/packages/coding-agent/src/modes/interactive/theme) or create a new JSON file conforming to the [schema](https://github.com/eltonssouza/relay-harness/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 `~/.relay/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. Relay 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 Relay'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. Relay 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 Relay 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.
+
+Relay resolves chained variable references. A missing variable or circular reference makes the theme invalid. Relay 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/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json) for the exact properties, required colors, and accepted value types.
+
+Relay 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, Relay derives HTML page and panel backgrounds from `userMessageBg`.
+
+## Load a theme from a project or package
+
+Place a project theme in `.relay/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 Relay package. See [Configuration](configuration.md), [Settings](settings.md#resources), and [Relay Packages](packages.md).
+
+Each loaded theme must have a unique name. Relay reports duplicate names as resource collisions.

package/docs/tmux.md

@@ -0,0 +1,55 @@
+# Run Relay in tmux
+
+Relay works inside tmux, but tmux can report `Shift+Enter`, `Ctrl+Enter`, and plain `Enter` as the same key. Enable extended keys so Relay 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
+```
+
+Relay 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 Relay 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
+```
+
+Relay supports the xterm `modifyOtherKeys` format used by these versions. Restart tmux and repeat the verification steps.
+
+For older versions, upgrade tmux or use Relay outside tmux rather than relying on modified Enter shortcuts.

package/docs/tui.md

@@ -0,0 +1,125 @@
+# Terminal UI
+
+`@relay-harness/tui` provides the terminal component system used by Relay. Extensions use it when built-in dialogs, notifications, status text, and widgets are not enough for the interaction they need.
+
+Start with `ctx.ui` methods from an [extension](extensions.md#interact-with-the-user). Build a custom component only when the UI needs its own rendering, keyboard or mouse input, focus, layout, or lifecycle.
+
+## Choose an integration point
+
+| Need | Use |
+|---|---|
+| Select, confirm, input, or multi-line editor | `ctx.ui.select()`, `confirm()`, `input()`, or `editor()` |
+| Non-blocking feedback | `ctx.ui.notify()` or `setStatus()` |
+| Persistent content near the editor | `ctx.ui.setWidget()` |
+| Replace the header, footer, or editor | The corresponding `ctx.ui` component factory |
+| Temporary interactive screen or overlay | `ctx.ui.custom()` |
+| Custom rendering for a tool or session entry | An extension renderer |
+
+These APIs receive Relay’s active theme and keybindings where needed. Do not create a second terminal renderer inside an extension.
+
+## Understand the component model
+
+A component renders an array of terminal lines for an available width. It can optionally handle keyboard and mouse input, and it must invalidate cached output when its state or theme-dependent content changes.
+
+Every rendered line must fit within the supplied width. Measure visible terminal columns rather than string length because ANSI escapes, wide characters, emoji, and combining characters change display width.
+
+Use `visibleWidth()`, `truncateToWidth()`, `sliceByColumn()`, and `wrapTextWithAnsi()` instead of implementing terminal-width handling yourself. Relay resets styling and hyperlinks after every line, so reapply styles on each rendered line.
+
+After changing component state, invalidate the affected component and call the injected `tui.requestRender()`. The TUI coalesces render requests and updates the terminal.
+
+## Compose built-in components
+
+The package includes components for common layouts and controls:
+
+- `Text`, `Markdown`, `Image`, and `TruncatedText` render content.
+- `Container`, `VStack`, `HStack`, `Box`, and `Spacer` compose layouts.
+- `Input` and `Editor` accept text.
+- `SelectList` and `SettingsList` implement searchable selection and settings flows.
+- `ScrollView` provides a bounded scrollable viewport.
+- `Loader` and `CancellableLoader` report ongoing work.
+- `MouseRegion` adds pointer behavior around another component.
+
+Prefer these components over rebuilding selection, scrolling, text editing, or width handling. The extension examples show how to combine them with Relay’s borders and themes.
+
+## Handle keyboard input and focus
+
+Use `matchesKey()` and `Key` for terminal keyboard input. The parser accounts for supported terminal protocols and key modifiers. Extension components should use the injected `KeybindingsManager` for configurable application actions.
+
+A component that displays a text cursor should implement `Focusable` and place `CURSOR_MARKER` immediately before its visual cursor. The TUI uses that marker to position the hardware cursor for input method editors.
+
+Containers that wrap an `Input` or `Editor` must propagate their `focused` state to that child. Without propagation, Chinese, Japanese, Korean, and other IME candidate windows can appear at the wrong screen position.
+
+Extend Relay’s `CustomEditor` when replacing the main editor. It preserves application shortcuts and agent controls.
+
+Forward keys your editor does not own to the base implementation, and restore the default by clearing the custom editor factory.
+
+## Handle mouse input
+
+Fullscreen mode routes normalized mouse events to components. A handler can mark an event handled, capture a drag sequence, request focus, or request a render.
+
+Unhandled wheel events scroll the nearest `ScrollView`. Unhandled primary-button drags remain available for transcript selection. OSC 8 links take precedence over enclosing click regions.
+
+Regular mode leaves mouse input to the terminal because the terminal owns scrollback. Design every interaction with a keyboard path even when fullscreen mouse input is available.
+
+## Use custom screens and overlays
+
+`ctx.ui.custom()` temporarily gives one component control of the interactive area and resolves when that component calls the supplied completion callback.
+
+Pass `overlay: true` to draw above existing content. Overlay options control size, anchors, offsets, margins, and responsive visibility. An overlay handle can change focus or temporarily hide and show the overlay with `setHidden()` while the interaction remains active.
+
+Focused overlays retain input ownership across ordinary renders. If another component should receive input while an overlay remains visible, explicitly release or redirect focus through the handle.
+
+Treat each custom component instance as belonging to one interaction. Create a new instance when starting that interaction again.
+
+Finish the interaction with the completion callback supplied to the component factory. It resolves the `ctx.ui.custom()` promise and disposes the component. Do not call `OverlayHandle.hide()` on an overlay created by `ctx.ui.custom()`.
+
+See [`overlay-qa-tests.ts`](../examples/extensions/overlay-qa-tests.ts) for positioning, stacking, focus, responsive visibility, and animation behavior.
+
+## Apply themes correctly
+
+Use the theme passed to the extension or component callback. Theme helpers produce ANSI-styled strings for semantic colors such as accent, muted text, success, warnings, errors, tool output, and Markdown.
+
+Use `theme.style()` to combine foreground and background colors with text attributes:
+
+```typescript
+return new Text(
+  theme.style("Done!", {
+    fg: "success",
+    bg: "toolSuccessBg",
+    bold: true,
+  }),
+  0,
+  0,
+);
+```
+
+A style color can be a semantic theme token or a concrete `Color`. Foreground tokens are accepted as `fg` and background tokens as `bg`; to use a token's color in the other position, pass its concrete color, for example `{ fg: theme.colors.userMessageBg }`. Access concrete colors through `theme.colors` and use utilities such as `mixColors()` from `@relay-harness/tui` when color math is needed. Tokens that a theme sets to the terminal default render with the terminal's own color; `theme.colors` reports the color the terminal announced for them, or a guess when it did not. Use `theme.appearance` (`"dark"` or `"light"`) to decide, for example, whether to lighten or darken a color. Relay converts the result to truecolor or 256-color output based on terminal capabilities. Theme tokens are converted once per theme; compute concrete colors outside the render path when possible.
+
+The existing `theme.fg()` and `theme.bg()` helpers remain available for applying one semantic color.
+
+Do not permanently store strings with theme colors unless `invalidate()` rebuilds them. A theme change clears render caches, but it cannot remove old ANSI colors embedded in application state.
+
+Theme callbacks evaluated during rendering do not need special rebuilding. Stateless components can also calculate themed output on every render.
+
+Use [Themes](themes.md) to create terminal palettes. Use Relay’s `getMarkdownTheme()` when rendering Markdown that should match the active application theme.
+
+## Keep rendering responsive
+
+Rendering runs on the interactive path. Cache expensive layout and highlighting work by width and content, then clear that cache from `invalidate()`.
+
+Keep the default view compact and reveal detail through expansion or a dedicated screen. For custom tool rendering, handle partial results and reuse the previous component when it can be updated safely.
+
+Use `RELAY_TUI_WRITE_LOG` to capture the raw ANSI stream when diagnosing rendering problems. Test narrow widths, wide characters, resize events, theme changes, focus transitions, and both regular and fullscreen modes.
+
+## Examples and source
+
+The checked extension examples cover the main patterns:
+
+- [`preset.ts`](../examples/extensions/preset.ts) and [`tools.ts`](../examples/extensions/tools.ts) use selection and settings lists.
+- [`qna.ts`](../examples/extensions/qna.ts) uses cancellable asynchronous UI.
+- [`modal-editor.ts`](../examples/extensions/modal-editor.ts) replaces the editor.
+- [`custom-footer.ts`](../examples/extensions/custom-footer.ts) replaces the footer.
+- [`widget-placement.ts`](../examples/extensions/widget-placement.ts) places persistent content around the editor.
+- [`doom-overlay/`](../examples/extensions/doom-overlay/) demonstrates a continuously rendered overlay.
+
+The public exports are defined in [`packages/tui/src/index.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/tui/src/index.ts). See [Extensions](extensions.md) for extension lifecycle, state, tools, events, and mode behavior.

package/docs/usage.md

@@ -0,0 +1,94 @@
+# Use Relay in the terminal
+
+Run `relay` from the folder you want to work in. Relay uses that folder to discover files, instructions, and configuration, and to group saved sessions. If you have not installed Relay or chosen a model yet, follow the [Quickstart](quickstart.md).
+
+Relay may ask whether you trust the working folder before loading its project resources. See [Project trust](security.md#understand-project-trust).
+
+<p align="center"><img src="images/interactive-mode.png" alt="Relay interactive mode showing a conversation, editor, and status information" width="750"></p>
+
+The transcript shows your prompts, Relay's responses, tool calls, results, and errors. You write prompts and commands in the editor. The footer shows the current folder, session, model, context usage, and accumulated usage and cost.
+
+## Enter a prompt
+
+Type a request and press `Enter` to send it. Use `Shift+Enter` to add a line, or press `Ctrl+G` to work on a longer prompt in your configured external editor.
+
+To include files or images:
+
+- Type `@` to search for a file and add it to your prompt.
+- Press `Tab` to complete a path.
+- Paste an image or drag it into a compatible terminal.
+
+## Follow Relay's work
+
+Relay shows each tool call and result while it works. Press `Ctrl+O` to expand or collapse tool output. Press `Ctrl+T` to show or hide thinking blocks.
+
+The startup header lists the instructions and resources Relay loaded. The editor border indicates the current thinking level. The footer updates as the model uses context and reports usage.
+
+Relay does not ask before every tool call. Review commands and changed files, and use a sandbox for untrusted or unattended work. See [Security](security.md).
+
+## Change direction
+
+You can send more input while Relay is working:
+
+| What you want | Action |
+|---|---|
+| Adjust the current task | Type a message and press `Enter` |
+| Add work after the current task | Type a message and press `Alt+Enter` |
+| Return queued messages to the editor | Press `Alt+Up` |
+| Stop the current task | Press `Escape` |
+
+A message sent with `Enter` waits until the current response and its tool calls finish, then guides the next response. A follow-up sent with `Alt+Enter` waits until Relay finishes the current task. Aborting returns queued messages to the editor.
+
+Windows Terminal reserves some Alt shortcuts. See [Terminal Setup](terminal-setup.md) for the Windows alternatives.
+
+## Change the model or settings
+
+Type `/` to search the available commands. The commands you will use most often are:
+
+- `/model` selects a model. Press `Ctrl+L` to open the same selector.
+- `/thinking` selects how much reasoning the current model uses. Press `Shift+Tab` to cycle through supported levels.
+- `/login` and `/logout` manage provider access.
+- `/settings` changes common preferences.
+
+Prompt templates, skills, and extensions can add more commands to the same menu. See [Choose a Model](models.md), [Configuration](configuration.md), or the complete [Slash Commands reference](slash-commands.md).
+
+## Continue or start over
+
+Relay saves sessions automatically unless session persistence is disabled.
+
+- `/new` starts a new session.
+- `/resume` opens another saved session.
+- `/name` gives the current session a recognizable name.
+- `/session` shows its file, ID, message count, token usage, and cost.
+
+Use `/tree`, `/fork`, or `/clone` when you want to explore another approach without losing existing work. Use `/compact` to reduce the conversation history sent to the model. See [Sessions and Context](sessions.md) for these workflows.
+
+After leaving Relay, run `relay --continue` from the same folder to resume its most recent session.
+
+## Run a terminal command
+
+Prefix a command with `!` to run it and include its output in the conversation:
+
+```text
+!git status
+```
+
+Use `!!` when you want to run a command without sending its output to the model.
+
+## Copy, export, or share results
+
+Press `Ctrl+X` or run `/copy` to copy the last assistant response. Use `/export` to save the session as HTML or JSONL.
+
+Use `/share` to upload the session as a private GitHub gist through the GitHub CLI and get the gist URL. Review the session first because it can contain prompts, tool output, file contents, and credentials exposed during the conversation.
+
+## Adjust the terminal
+
+Fullscreen mode, the default, keeps the editor and status area fixed while the transcript scrolls within the terminal window. Regular mode uses the terminal's normal scrollback. Choose a mode through `/settings` or `--tui-mode`.
+
+Terminal support for mouse input, keyboard shortcuts, and inline images varies. See [Terminal Setup](terminal-setup.md) for platform-specific configuration and [Keybindings](keybindings.md) for every configurable shortcut. Run `/hotkeys` to inspect the shortcuts active in your current session.
+
+## Collect diagnostic information
+
+When troubleshooting terminal rendering or conversation state, run `/debug`. Relay writes the rendered terminal lines and current session messages to `relay-debug.log` in your [agent directory](configuration.md#agent-directory).
+
+Review this file before sharing it. It can contain prompts, model responses, tool output, file contents, and terminal data.

package/docs/virtual-models.md

@@ -0,0 +1,114 @@
+# Virtual Models
+
+A virtual model is a selectable model that picks a physical model for each request. Use one to route by task, cost, or conversation state. For example, a router can send quick questions to a small model and hard problems to a large one, while the user selects a single model.
+
+Register virtual models from an [extension](extensions.md). They appear in `/model`, `--model`, scoped models, and settings like any other model. A virtual model can be listed under any provider, including one with physical models, such as `openai-codex/auto`.
+
+## Selection and dispatch
+
+A virtual model selects a model and a thinking level. A router maps that pair to a physical pair for each request:
+
+```
+selected (virtual model, virtual level)  ->  dispatched (physical model, physical level)
+jev/auto:low                             ->  anthropic/claude-sonnet-4-5:high
+```
+
+The virtual thinking level is an input to the router. Its meaning is up to the router; it need not correspond to a reasoning budget.
+
+Relay keeps the two pairs apart:
+
+| | Selection | Dispatch |
+|---|---|---|
+| Recorded in | `model_change` and `thinking_level_change` entries | Each assistant message: `provider`, `api`, `model`, `thinkingLevel` |
+| Visible as | `ctx.model`, `ctx.thinkingLevel`, `RELAY_MODEL`, `RELAY_REASONING_LEVEL`, `/model` | The assistant message of each response |
+
+Providers only receive physical models. Assistant messages name the physical model, so replaying a conversation across different physical models works the same as after a manual model switch. Resuming a session restores the virtual selection from its latest `model_change` entry. If the virtual model is no longer registered, Relay falls back to the physical model that answered last.
+
+In interactive mode, the footer shows the routed model next to the selection, for example `auto • high → gpt-5.6-luna • medium`. `/session` lists the cost for each physical model.
+
+Context usage uses the limits of the physical model that produced the latest response, even if that response came before switching to the virtual model. Without such a response, it uses the limits declared on the virtual model, if any. Compaction checks the same limits, and again the limits of the model each request is routed to. If that model's context window is too small for the conversation, Relay compacts before sending the request; the route stays as the router chose it.
+
+## Register a virtual model
+
+```typescript
+import type { ExtensionAPI } from "@relay-harness/coding-agent";
+
+export default function (relay: ExtensionAPI) {
+  relay.registerVirtualModel({
+    provider: "router",
+    id: "auto",
+    name: "Auto",
+    thinkingLevels: ["low", "high"],
+    route(request, ctx) {
+      // Tool follow-ups and retries stay on the model that handled the turn.
+      const sticky = request.failed ?? request.previous;
+      if (request.reason !== "user" && sticky) {
+        return { model: sticky.model, thinkingLevel: sticky.thinkingLevel ?? "medium" };
+      }
+      const id = request.thinkingLevel === "high" ? "claude-sonnet-4-5" : "claude-haiku-4-5";
+      return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium" };
+    },
+  });
+}
+```
+
+- `provider` is the provider the model is listed under. It can be any provider ID. A provider can list several virtual models next to its physical ones. On a physical provider, the virtual model is available when that provider has credentials. Under an ID that no provider uses, it is always available.
+- `id` must not be the ID of a physical model of that provider. If a catalog refresh later adds a physical model with the same ID, the virtual model hides it.
+- `thinkingLevels` lists the levels offered for selection. It defaults to `["off"]`.
+- `contextWindow` and `maxTokens` are shown before the first response. Unset limits are unknown.
+- `input` lists the input types offered for selection. It defaults to text and images; physical models without image support receive placeholders.
+
+Registration follows the same queuing and reload rules as `relay.registerProvider()`. Registering the same provider and ID again replaces the virtual model. `relay.unregisterVirtualModel(provider, id)` removes it; `relay.unregisterProvider()` does not. SDK code can register one without an extension: `modelRuntime.registerVirtualModel(definition)`.
+
+## Route requests
+
+`route(request, ctx)` runs before every request made with the virtual model and returns `{ model, thinkingLevel }`. The model can be any physical model in the catalog whose provider has credentials; look it up with `ctx.modelRegistry`. A virtual model cannot route to another virtual model. Relay clamps the thinking level to the returned model.
+
+| Field | Meaning |
+|---|---|
+| `model`, `thinkingLevel` | The selected virtual model and level |
+| `reason` | Why the request is made, see below |
+| `previous` | Physical model and thinking level of the latest successful response in `messages` |
+| `failed` | For `retry`: physical model, thinking level, and assistant `message` of the failed request, which `messages` no longer contains. The message carries `stopReason` and `errorMessage`. Absent when routing itself failed |
+| `state` | Router state last returned on this session branch, see below |
+| `messages` | The conversation for this request, including system messages |
+| `signal` | Abort signal of the request |
+
+| `reason` | Request |
+|---|---|
+| `user` | First request after a message the user wrote, including steering and follow-up messages |
+| `continuation` | Any other request in the agent loop, such as after tool results or extension messages |
+| `retry` | Automatic retry after a failed request, including after compaction for a context overflow |
+| `direct` | Request made outside the agent loop, such as a compaction summary or an extension calling `ctx.modelRegistry.streamSimple()` |
+
+Returning `previous` for `continuation` and `failed` for `retry` keeps prompt caches and thinking signatures valid. Switching models between turns is allowed but loses the prompt cache. A retry can also switch to another model, for example when `failed.message.errorMessage` reports that a provider is overloaded or the context overflowed.
+
+If `route()` throws, or returns a virtual model or a model without credentials, the request ends with an error response.
+
+## Keep routing state
+
+`route()` can return `state` next to the model. Relay stores it on the session branch and passes it back as `request.state` on later requests. Use it for decisions the transcript does not record, such as classifier results or a routing phase:
+
+```typescript
+relay.registerVirtualModel<{ phase: "plan" | "build" }>({
+  provider: "router",
+  id: "phased",
+  name: "Phased",
+  route(request, ctx) {
+    const state = request.state ?? { phase: "plan" };
+    const id = state.phase === "plan" ? "claude-opus-4-5" : "claude-haiku-4-5";
+    return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium", state };
+  },
+});
+```
+
+- State must be JSON-serializable. Returning `undefined` or `request.state` itself keeps the current state.
+- Relay stores any other returned object as new state, before the request is sent, even when it equals the current state. Return a new object only when the state changes. The state stays stored if the request later fails.
+- State follows the session tree, so forks and `/tree` navigation see the state of their branch. It survives compaction.
+- `direct` requests have no state, and Relay ignores state they return.
+
+The transcript already records the selection and every dispatched model, and `ctx.sessionManager.getBranch()` exposes both.
+
+Routers can call other models through `ctx.modelRegistry`, for example `ctx.modelRegistry.classify()` with a classifier model from `ctx.modelRegistry.findOfType("classifier", provider, id)`. The call adds latency before the first token of the turn.
+
+See [`jev-router.ts`](../examples/extensions/jev-router.ts) for a complete router. It plans on a strong OpenAI Codex model chosen by the Jev classifier, lets that model make the first edit, and then switches once to a cheaper model, accepting a single prompt-cache miss. It keeps the phase as router state.

package/docs/windows.md

@@ -0,0 +1,67 @@
+# Run Relay on Windows
+
+Run Relay either as a native Windows process or inside Windows Subsystem for Linux (WSL). Native Windows uses Git Bash by default for Bash commands and can optionally expose PowerShell to the model. Relay inside WSL uses the Linux environment and its Bash installation.
+
+Follow the main [Quickstart](quickstart.md) to install and authenticate Relay. Use this page to choose and configure its command environment.
+
+## Choose native Windows or WSL
+
+| Environment | Command environment | Use it when |
+|---|---|---|
+| Native Windows with Git Bash | Git Bash for the built-in `bash` tool and `!` commands | Your files and development tools primarily live on Windows |
+| Native Windows with the `powershell` tool | PowerShell for model tool calls; Bash remains available for `!` commands | The task depends on PowerShell modules or Windows-native commands |
+| WSL | Linux Bash and tools inside the selected WSL distribution | Your files and toolchain already live in Linux or WSL |
+
+## Use Git Bash on native Windows
+
+For most native Windows users, installing [Git for Windows](https://git-scm.com/download/win) is sufficient.
+
+Relay resolves Bash in this order:
+
+1. `shellPath` from `~/.relay/agent/settings.json`
+2. Git Bash under `Program Files` or `Program Files (x86)`
+3. `bash.exe` on `PATH`, including Cygwin, MSYS2, or legacy WSL Bash
+
+Start Relay and enter this command to verify the shell:
+
+```text
+!printf 'Bash is working\n'
+```
+
+If Relay cannot find Bash, it reports the locations it checked. Install Git for Windows, put another Bash executable on `PATH`, or configure `shellPath`.
+
+## Let the model use PowerShell
+
+The optional `powershell` tool runs commands through `pwsh.exe` when available, then falls back to Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+
+To replace the model-facing `bash` tool with `powershell`, add this to `~/.relay/agent/settings.json`:
+
+```json
+{
+  "defaultTools": ["read", "powershell", "edit", "write"]
+}
+```
+
+`["-bash", "+powershell"]` does the same while keeping any other default tools you configured.
+
+Restart Relay, then ask it to run a harmless PowerShell command. The `!` and `!!` editor commands continue to use Bash. The `powershell` tool is available only when Relay runs as a native Windows process.
+
+See [Settings](settings.md#tools) for other tool combinations.
+
+## Use a custom Bash executable
+
+Set `shellPath` when Bash is installed somewhere Relay does not discover automatically:
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```
+
+JSON uses backslashes for escape sequences. When you write a Windows path with backslashes, write each backslash twice, as shown above.
+
+See [Configure shell commands](shell-aliases.md) for command prefixes, aliases, and the complete shell-resolution behavior.
+
+## Configure Windows Terminal
+
+Windows Terminal reserves or rewrites some modified keys. See [Windows Terminal](terminal-setup.md#windows-terminal) to configure `Shift+Enter` and `Alt+Enter`, and [Keybindings](keybindings.md) for Relay's Windows and WSL shortcut defaults.

package/examples/README.md

@@ -0,0 +1,39 @@
+# Examples
+
+Example code for the relay-coding-agent SDK, process integration, and extensions.
+
+## CLI integration
+
+[`rpc-client.ts`](rpc-client.ts) uses the typed `RpcClient` to run Relay in a child process, stream events, and wait for the run to settle.
+
+Build the coding-agent package before running it from a repository checkout:
+
+```bash
+node examples/rpc-client.ts "Explain this repository"
+```
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
+
+### [extensions/](extensions/)
+Example extensions demonstrating:
+- Lifecycle event handlers (tool interception, safety gates, context modifications)
+- Custom tools (todo lists, questions, subagents, output truncation)
+- Commands and keyboard shortcuts
+- Custom UI (footers, headers, editors, overlays)
+- Git integration (checkpoints, auto-commit)
+- System prompt modifications and custom compaction
+- External integrations (SSH, file watchers, system theme sync)
+- Custom providers (Anthropic with custom streaming, GitLab Duo)
+
+### [plugins/relay-example-plugin/](plugins/relay-example-plugin/)
+An experimental plugin package that Relay automatically builds into separate Session-worker and TUI Chord facets.
+
+## Documentation
+
+- [SDK Examples](sdk/README.md)
+- [CLI Integration](../docs/cli-integration.md)
+- [Extensions Documentation](../docs/extensions.md)
+- [Skills Documentation](../docs/skills.md)