@astralyn/pi 0.83.0 → 0.84.1

package/docs/bundled/extensions/router.md

@@ -22,23 +22,24 @@ Providers are registered at extension load via `pi.registerProvider` (config for
 ```
 API relays                  ← relays first; add / reload at bottom
  └─ Relay · {id}            ← models · base URL · API key · remove
-     └─ Models              ← Fetch catalog + one row per configured model
-         └─ {model id}      ← display name · thinking levels
+     └─ Models              ← searchable model list + fetch / manual add
+         └─ {model id}      ← display name · thinking levels · remove
 ```
 
-Edits **auto-save** to `router.json` and re-register the provider. There is no separate Save step — Back never discards committed field or model changes.
+Edits **auto-save** to `router.json` and re-register the provider. Text fields save when confirmed; model and thinking toggles save immediately. There is no Save or Apply step, and Back never discards a completed change.
 
-Nested multi-select (catalog) and the thinking-level editor require **Ctrl+S to apply** that screen's working set. If you press Esc with unsaved toggles, the footer warns once; pressing Esc again discards that screen only.
+Model search follows Pi's `/model` behavior: the search field is always visible, typing fuzzy-filters results, arrows wrap around the list, Enter opens the highlighted item, and Esc goes back. Catalog checkboxes use Space to toggle live; Enter or Esc returns to the model list. The model currently used by the session is protected and must be changed with `/model` before it can be disabled or removed.
 
 ### Add flow
 
 1. **Name** — provider id (e.g. `my-relay`); appears as `my-relay/gpt-5.6-sol` in `/model`
 2. **Base URL** — usually ends with `/v1`
 3. **API key** — literal `sk-…` or `$ENV_VAR`
-4. **Fetch models** — `GET {baseUrl}/models`
-5. **Select** — Space to toggle, Ctrl+S to apply (TUI); the relay is then written immediately
+4. The relay connection is written immediately, even before models are fetched.
+5. **Fetch models** — `GET {baseUrl}/models`
+6. **Select** — Space toggles each model immediately. If fetching fails, retry or add model ids manually.
 
-Each selected model gets these defaults:
+A failed or cancelled catalog fetch does not lose the relay. Each selected model gets these defaults:
 
 | Field | Default |
 |:-:|:-:|
@@ -47,14 +48,15 @@ Each selected model gets these defaults:
 | `input` | `text` + `image` |
 | `contextWindow` | 272000 |
 | `maxTokens` | 128000 |
-| `thinkingLevelMap` | off…medium hidden; high / xhigh / max on |
+| `thinkingLevelMap` | `off` / `minimal` hidden; `low` / `medium` / `high` / `xhigh` / `max` enabled |
 
 ### Customize models
 
 Relay → **Models** → pick a model:
 
-- **Display name** — optional label (e.g. `Luna`). Leave empty to show the id. Saved on confirm.
-- **Thinking levels** — toggle each Pi level between **on** and **hidden** (`null`). Ctrl+S applies, then auto-saves the relay.
+- **Display name** — optional label (e.g. `Luna`). Leave empty to show the id. Saved on input confirmation.
+- **Thinking levels** — router models expose only `low`, `medium`, `high`, `xhigh`, and `max`. All five start enabled; toggle any one to hide or re-enable it. `off` and `minimal` are never shown.
+- **Remove model** — confirms and immediately removes the model from the relay. The model currently used by the session must be changed with `/model` first.
 
 ---
 
@@ -78,8 +80,8 @@ Relay → **Models** → pick a model:
           "thinkingLevelMap": {
             "off": null,
             "minimal": null,
-            "low": null,
-            "medium": null,
+            "low": "low",
+            "medium": "medium",
             "high": "high",
             "xhigh": "xhigh",
             "max": "max"
@@ -99,7 +101,7 @@ Relay → **Models** → pick a model:
 }
 ```
 
-There is **no migration** from any older models-manager config. Add relays with `/router add` (or edit `router.json` and run `/router reload`).
+There is **no migration** from any older models-manager config, and Pi updates do not overwrite `~/.pi/agent/router.json`. Existing router thinking maps are not automatically rewritten. At runtime, omitted thinking levels are filled from the five-level GPT Gateway defaults while explicit `null` values remain hidden. Legacy `off` / `minimal` entries are ignored at runtime and remain hidden; newly added models use the same five-level defaults.
 
 ---
 
@@ -112,7 +114,11 @@ There is **no migration** from any older models-manager config. Add relays with
 - Replayed optional top-level `ResponseItem.id` identity fields are omitted from stateless requests, matching Codex CLI 0.145's default `store: false` wire behavior. Required semantic references such as `item_reference.id`, plus `call_id` and encrypted reasoning content, remain intact.
 - Same relay + same model: tool/reasoning multi-turn matches Codex-style Responses. Switching model or provider mid-session may normalize tool-call ids more strictly (upstream allow-list); this is not worked around here.
 - Interactive `/router` requires a TUI (`ctx.hasUI`); otherwise a warning is shown and no dialog opens.
-- Catalog multi-select and thinking editor are apply-on-Ctrl+S screens; only those screens can be discarded with double Esc.
+- Router models are GPT Gateway models: only `low`, `medium`, `high`, `xhigh`, and `max` are exposed. `off` and `minimal` are disabled.
+- Catalog selection and thinking changes are live and auto-saved; Esc only returns to the previous screen.
+- The active model and its provider cannot be disabled or removed; switch with `/model` first.
+- If a catalog does not return an already configured model, the model remains listed as unavailable instead of being silently removed.
+- A catalog probe does not send an unresolved environment or command-based key anonymously; it explains the local key problem and offers manual model entry.
 
 ## Implementation notes
 

package/docs/bundled/extensions/statusline.md

@@ -48,13 +48,15 @@ CTX 2.1%/1.0M                    ↑13k ↓13k R440k CH99.4% $0.074
 
 **Middle (optional)**
 
-- Extension status text from `ctx.ui.setStatus()` is sorted by key and centered
-  in the gap between context and usage when space permits; otherwise it is
-  dropped so CTX and usage stay readable. Plain text is muted; strings that
-  already carry ANSI color are left unchanged.
+- Extension status text from `ctx.ui.setStatus()` is sorted by key and pinned
+  to the center of the line — anchored to the absolute line center so it does
+  not drift as the usage cluster grows, falling back to balancing the free
+  space when the side zones collide with the center anchor. When space runs
+  out it is dropped so CTX and usage stay readable. Plain text is muted;
+  strings that already carry ANSI color are left unchanged.
 
 Zero-value usage fields are omitted. Before the first assistant response, the
-right side of line 2 is empty (or holds extension status only).
+right side of line 2 is empty; extension status stays centered either way.
 
 ## Narrow-width drop order
 

package/docs/custom-provider.md

@@ -228,8 +228,8 @@ async function login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>
   return exchangeAuthorizationCode(code, callbacks.signal);
 }
 
-async function refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
-  return refreshAuthorization(credentials.refresh);
+async function refreshToken(credentials: OAuthCredentials, signal: AbortSignal): Promise<OAuthCredentials> {
+  return refreshAuthorization(credentials.refresh, signal);
 }
 
 export default function (pi: ExtensionAPI) {
@@ -479,3 +479,124 @@ At minimum, cover:
 - one interactive request with the selected provider, including a tool call if the provider claims tool support.
 
 The two example extensions above cover the two main test seams: direct custom event production and delegation to Pi AI's public streaming APIs.
+
+## Config Reference
+
+```typescript
+interface ProviderConfig {
+  /** Display name for the provider in UI such as /login. */
+  name?: string;
+
+  /** API endpoint URL. Required when defining models. */
+  baseUrl?: string;
+
+  /** API key literal, env interpolation ($ENV_VAR or ${ENV_VAR}), or !command. Required when defining models (unless oauth). */
+  apiKey?: string;
+
+  /** API type for streaming. Required at provider or model level when defining models. */
+  api?: Api;
+
+  /** Custom streaming implementation for non-standard APIs. */
+  streamSimple?: (
+    model: Model<Api>,
+    context: Context,
+    options?: SimpleStreamOptions
+  ) => AssistantMessageEventStream;
+
+  /** Custom headers to include in requests. Values use the same resolution syntax as apiKey. */
+  headers?: Record<string, string>;
+
+  /** If true, adds Authorization: Bearer header with the resolved API key. */
+  authHeader?: boolean;
+
+  /** Models to register. If provided, replaces all existing models for this provider. */
+  models?: ProviderModelConfig[];
+
+  /** OAuth provider for /login support. */
+  oauth?: {
+    name: string;
+    login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+    refreshToken(credentials: OAuthCredentials, signal: AbortSignal): Promise<OAuthCredentials>;
+    getApiKey(credentials: OAuthCredentials): string;
+  };
+}
+```
+
+## Model Definition Reference
+
+```typescript
+interface ProviderModelConfig {
+  /** Model ID (e.g., "claude-sonnet-4-20250514"). */
+  id: string;
+
+  /** Display name (e.g., "Claude 4 Sonnet"). */
+  name: string;
+
+  /** API type override for this specific model. */
+  api?: Api;
+
+  /** API endpoint URL override for this specific model. */
+  baseUrl?: string;
+
+  /** Whether the model supports extended thinking. */
+  reasoning: boolean;
+
+  /** Maps pi thinking levels to provider/model-specific values; null marks a level unsupported. */
+  thinkingLevelMap?: Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", string | null>>;
+
+  /** Supported input types. */
+  input: ("text" | "image")[];
+
+  /** Cost per million tokens (for usage tracking). */
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+
+  /** Maximum context window size in tokens. */
+  contextWindow: number;
+
+  /** Maximum output tokens. */
+  maxTokens: number;
+
+  /** Custom headers for this specific model. */
+  headers?: Record<string, string>;
+
+  /** Compatibility settings for the selected API. */
+  compat?: {
+    // openai-completions
+    supportsStore?: boolean;
+    supportsDeveloperRole?: boolean;
+    supportsReasoningEffort?: boolean;
+    supportsUsageInStreaming?: boolean;
+    supportsFinishReason?: boolean;
+    supportsStrictMode?: boolean;
+    supportsOpenAIGrammarTools?: boolean; // openai-completions/openai-responses; false falls back to normal function tools
+    maxTokensField?: "max_completion_tokens" | "max_tokens";
+    requiresToolResultName?: boolean;
+    requiresAssistantAfterToolResult?: boolean;
+    requiresThinkingAsText?: boolean;
+    requiresReasoningContentOnAssistantMessages?: boolean;
+    thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "baseten" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
+    chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
+    chatTemplateArgs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
+    cacheControlFormat?: "anthropic";
+    sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
+    sendSessionAffinityHeaders?: boolean;
+
+    // anthropic-messages
+    supportsEagerToolInputStreaming?: boolean;
+    supportsLongCacheRetention?: boolean;
+    sendSessionAffinityHeaders?: boolean;
+    supportsCacheControlOnTools?: boolean;
+    forceAdaptiveThinking?: boolean;
+    allowEmptySignature?: boolean;
+    supportsStrictTools?: boolean;
+  };
+}
+```
+
+`openrouter` sends `reasoning: { effort }`. `deepseek` sends `thinking: { type: "enabled" | "disabled" }` and `reasoning_effort` when enabled. `together` sends `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` is for DashScope-style top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`. Use `chat-template` for configurable `chat_template_kwargs`, for example DeepSeek V3.x behind vLLM with `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }`. Use `thinkingFormat: "baseten"` with `chatTemplateArgs` when the provider expects toggle values under `chat_template_args` and optionally supports top-level `reasoning_effort`.
+`cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content.

package/docs/development.md

@@ -0,0 +1,83 @@
+# Development
+
+This repository is the standalone distribution of `@astralyn/pi`. It publishes one package and the `pi` executable; runtime source lives under `src/**`.
+
+## Requirements
+
+- Node.js `>=22.19`
+- npm
+
+The package consumes the published `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, and `@earendil-works/pi-tui` dependencies. It does not recreate the upstream monorepo or vendor those packages.
+
+## Install and run
+
+Install dependencies without running lifecycle scripts:
+
+```bash
+npm install --ignore-scripts
+```
+
+Run the CLI directly from TypeScript source:
+
+```bash
+npm run dev
+```
+
+To run without provider credentials from the current environment:
+
+```bash
+npm run dev -- --no-env
+```
+
+Build the distributable package and assets:
+
+```bash
+npm run build
+```
+
+The compiled CLI is `dist/cli.js`. The package's executable is `pi`.
+
+## Verification
+
+Run the repository checks after code changes:
+
+```bash
+npm run check
+```
+
+This runs Biome, dependency and import checks, documentation-link validation, and TypeScript checks for source and examples.
+
+Run focused tests for changed behavior:
+
+```bash
+npx vitest run test/<changed-file>.test.ts
+```
+
+Run all tests in an isolated home and configuration directory:
+
+```bash
+npm run test:isolated
+```
+
+Validate the exact upstream release baseline and local deviations:
+
+```bash
+npm run diff:upstream -- --check
+```
+
+For interactive changes, also test in a real TTY, including pending and settled tool output, collapsed and expanded states, and relevant `/reload` or `/tree` flows.
+
+## Repository layout
+
+- `src/**` - runtime source
+- `src/extensions/**` - bundled extensions using the public Extension API
+- `test/**` - focused Vitest tests and fixtures
+- `docs/**` - published user and API documentation
+- `maintainers/**` - repository-only maintainer runbooks
+- `scripts/**` - development, verification, and release helpers
+
+## Boundaries
+
+Keep the upstream runtime contracts intact. Do not vendor or patch the AI, Agent core, or TUI dependencies. Preserve tool schemas, execution protocols, and result structures when changing display-only behavior. Keep direct dependencies pinned and regenerate `npm-shrinkwrap.json` intentionally when dependency metadata changes.
+
+Read the repository contract in `AGENTS.md` and the maintainer architecture and release guidance in `maintainers/README.md` before making changes.

package/docs/docs.json

@@ -39,13 +39,13 @@
           "title": "Keybindings",
           "path": "keybindings.md"
         },
-        {
-          "title": "Sessions",
-          "path": "sessions.md"
-        },
         {
           "title": "Compaction",
           "path": "compaction.md"
+        },
+        {
+          "title": "Development",
+          "path": "development.md"
         }
       ]
     },
@@ -56,6 +56,10 @@
           "title": "Overview",
           "path": "bundled/README.md"
         },
+        {
+          "title": "Biu",
+          "path": "bundled/extensions/biu.md"
+        },
         {
           "title": "DeepWiki",
           "path": "bundled/extensions/deepwiki.md"

package/docs/extensions.md

@@ -778,7 +778,8 @@ Behavior guarantees:
 - Mutations to `event.input` affect the actual tool execution
 - Later `tool_call` handlers see mutations made by earlier handlers
 - No re-validation is performed after your mutation
-- Return values from `tool_call` only control blocking via `{ block: true, reason?: string }`
+- Return values from `tool_call` control blocking via `{ block: true, reason?: string, terminate?: boolean }`
+- `terminate` only applies to a blocked call; the agent stops early only when every finalized result in the batch is terminating
 
 ```typescript
 import { isToolCallEventType } from "@astralyn/pi";
@@ -794,7 +795,7 @@ pi.on("tool_call", async (event, ctx) => {
     event.input.command = `source ~/.profile\n${event.input.command}`;
 
     if (event.input.command.includes("rm -rf")) {
-      return { block: true, reason: "Dangerous command" };
+      return { block: true, reason: "Dangerous command", terminate: true };
     }
   }
 
@@ -1584,6 +1585,27 @@ mode and would not execute if sent via `prompt`.
 
 Register a custom TUI renderer for custom messages with your `customType`. Custom messages are created with `pi.sendMessage()` and participate in LLM context. See [Custom UI](#custom-ui).
 
+### pi.registerMarkdownTransformer(transformer)
+
+Register a transformer for the Markdown in normal user text, assistant text, and thinking blocks. Transformers run in extension load order, and each transformer receives the Markdown returned by the previous transformer. After the chain finishes, Pi renders the transformed content with its built-in renderer.
+
+The transformer receives the Markdown string and a context with:
+
+- `messageType` — `"user"`, `"assistant"`, or `"assistant-thinking"`
+- `isStreaming` — `true` for partial assistant updates; `false` for user, finalized assistant, and restored messages
+- `availableWidth` — exact terminal columns available for the transformed Markdown content
+
+Return the transformed Markdown:
+
+```typescript
+pi.registerMarkdownTransformer((markdown, { messageType, isStreaming }) => {
+  if (isStreaming || messageType === "assistant-thinking") return markdown;
+  return markdown.replaceAll("-->", "→");
+});
+```
+
+If a transformer throws, Pi keeps the Markdown produced so far and continues with the next transformer. The hook is display-only: the original message remains unchanged in the session and model context. It runs for new user messages, assistant streaming updates, restored session messages, and terminal width changes, so transformers should remain synchronous and inexpensive.
+
 ### pi.registerEntryRenderer(customType, renderer)
 
 Register a custom TUI renderer for custom entries with your `customType`. Custom entries are created with `pi.appendEntry()` and do not participate in LLM context.
@@ -1708,7 +1730,9 @@ Register or override a model provider dynamically. Useful for proxies, custom en
 
 Calls made during the extension factory function are queued and applied once the runner initialises. Calls made after that — for example from a command handler following a user setup flow — take effect immediately without requiring a `/reload`.
 
-Dynamic providers can implement `refreshModels`. Pi calls it during model refresh, publishes the returned list synchronously through the provider, and passes the canonical credential/store/network/signal context. The extension decides whether to persist the catalog through `context.store`; live servers such as llama.cpp can ignore it.
+Dynamic providers can implement `refreshModels`. Pi calls it during model refresh, publishes the returned list synchronously through the provider, and passes the canonical credential/stored-catalog/network/signal context. The extension decides whether to persist catalog metadata through generation-checked `context.publish({ persist: entry })`; live servers such as llama.cpp can return models without persisting them.
+
+`context.signal` is always a concrete signal and provider callbacks must pass it to blocking I/O. Public `ModelRuntime.refresh()` and `ModelRegistry.refresh()` calls accept an optional signal and are unbounded when it is omitted; extensions and applications choose their own deadlines. Cancellation stops the caller waiting even if a provider ignores the signal, but cooperation is still required to stop the underlying work.
 
 Extensions that need native provider auth, filtering, refresh, or stream behavior can register a complete `Provider` from `@earendil-works/pi-ai`. The provider becomes the composition base and `models.json` overrides still apply above it.
 
@@ -1798,7 +1822,8 @@ pi.registerProvider("corporate-ai", {
       const code = await callbacks.onPrompt({ message: "Enter code:" });
       return { refresh: code, access: code, expires: Date.now() + 3600000 };
     },
-    async refreshToken(credentials) {
+    async refreshToken(credentials, signal) {
+      signal.throwIfAborted();
       // Refresh logic
       return credentials;
     },
@@ -1819,7 +1844,7 @@ The object form accepts a complete pi-ai `Provider`, including native `auth`, `g
 - `headers` - Custom headers to include in requests.
 - `authHeader` - If true, adds `Authorization: Bearer` header automatically.
 - `models` - Array of model definitions. If provided, replaces all existing models for this provider. Model definitions can set `baseUrl` to override the provider endpoint for that model.
-- `refreshModels` - Async dynamic discovery callback. Its returned models replace extension-provided models. Use the scoped `context.store` only when results should persist.
+- `refreshModels` - Async dynamic discovery callback. Its returned models replace extension-provided models. `context.stored` contains the persisted provider snapshot; use generation-checked `context.publish({ persist: entry })` only when updated catalog data should persist. Use `persist: null` to delete that snapshot.
 - `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
 - `streamSimple` - Custom streaming implementation for non-standard APIs.
 

package/docs/json.md

@@ -8,7 +8,20 @@ Outputs all session events as JSON lines to stdout. Useful for integrating pi in
 
 ## Event Types
 
-Events are defined by `AgentSessionEvent`, exported from [`@astralyn/pi`](https://www.npmjs.com/package/@astralyn/pi):
+Wire events use `JsonAgentSessionEvent`, exported from [`@astralyn/pi`](https://www.npmjs.com/package/@astralyn/pi). It matches `AgentSessionEvent` except that streaming message updates omit cumulative snapshots:
+
+```typescript
+type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
+
+type JsonAgentSessionEvent =
+  | Exclude<AgentSessionEvent, { type: "message_update" }>
+  | {
+      type: "message_update";
+      assistantMessageEvent: WithoutPartial<AssistantMessageEvent>;
+    };
+```
+
+Session events are defined by `AgentSessionEvent`:
 
 ```typescript
 type AgentSessionEvent =
@@ -29,6 +42,7 @@ type AgentSessionEvent =
   | { type: "summarization_retry_finished" }
   | { type: "bash_execution_update"; id?: string; delta: string };
 ```
+```
 
 `queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
 
@@ -79,12 +93,17 @@ Followed by events as they occur:
 {"type":"agent_start"}
 {"type":"turn_start"}
 {"type":"message_start","message":{"role":"assistant","content":[],...}}
-{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
+{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
 {"type":"message_end","message":{...}}
 {"type":"turn_end","message":{...},"toolResults":[]}
 {"type":"agent_end","messages":[...],"willRetry":false}
 ```
 
+`message_update` records are delta-only. They omit both the cumulative `message` field and
+`assistantMessageEvent.partial` to keep stream size linear. Use `contentIndex` and `delta`
+to assemble live text, thinking, or tool-call arguments if needed. `message_end` contains
+the final authoritative message.
+
 ## Example
 
 ```bash

package/docs/keybindings.md

@@ -10,7 +10,7 @@ After editing `keybindings.json`, run `/reload` in pi to apply the changes witho
 
 ## Key Format
 
-`modifier+key` where modifiers are `ctrl`, `shift`, `alt` (combinable) and keys are:
+`modifier+key` where modifiers are `ctrl`, `shift`, `alt`, `super` (combinable) and keys are:
 
 - **Letters:** `a-z`
 - **Digits:** `0-9`
@@ -18,7 +18,9 @@ After editing `keybindings.json`, run `/reload` in pi to apply the changes witho
 - **Function:** `f1`-`f12`
 - **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
 
-Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1`, etc.
+Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, `ctrl+1`, etc.
+
+`super` bindings require a terminal that reports the modifier separately, typically through the Kitty keyboard protocol. They may not work in terminals without that support.
 
 ## All Actions
 
@@ -26,18 +28,22 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
-| `tui.editor.cursorUp` | `up` | Move cursor up |
-| `tui.editor.cursorDown` | `down` | Move cursor down |
+| `tui.editor.cursorUp` | `up` | Move cursor up, browsing older history at the top |
+| `tui.editor.cursorDown` | `down` | Move cursor down, browsing newer history at the bottom |
+| `tui.editor.historyPrevious` | *(none)* | Select the previous prompt history entry |
+| `tui.editor.historyNext` | *(none)* | Select the next prompt history entry |
 | `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
 | `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
 | `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
 | `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | Move cursor word right |
-| `tui.editor.cursorLineStart` | `home`, `ctrl+a` | Move to line start |
-| `tui.editor.cursorLineEnd` | `end`, `ctrl+e` | Move to line end |
+| `tui.editor.cursorLineStart` | `home`, `ctrl+home`, `ctrl+a` | Move to line start |
+| `tui.editor.cursorLineEnd` | `end`, `ctrl+end`, `ctrl+e` | Move to line end |
 | `tui.editor.jumpForward` | `ctrl+]` | Jump forward to character |
 | `tui.editor.jumpBackward` | `ctrl+alt+]` | Jump backward to character |
-| `tui.editor.pageUp` | `pageUp` | Scroll up by page |
-| `tui.editor.pageDown` | `pageDown` | Scroll down by page |
+| `tui.editor.pageUp` | `pageUp`, `ctrl+pageUp` | Scroll up by page |
+| `tui.editor.pageDown` | `pageDown`, `ctrl+pageDown` | Scroll down by page |
+
+The dedicated history actions always change history entries, regardless of the cursor position in a multiline prompt. Explicit history bindings take precedence over application actions while the main editor is focused, so binding `tui.editor.historyPrevious` to `ctrl+p` overrides model cycling in that context without changing `Ctrl+P` in selectors.
 
 ### TUI Editor Deletion
 
@@ -78,16 +84,42 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
 | `tui.select.confirm` | `enter` | Confirm selection |
 | `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
 
+### TUI Fullscreen Viewport
+
+These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content.
+
+Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
+
+| Key | Default mode | Fullscreen mode |
+|-----|--------------|-----------------|
+| `home`, `end` | Editor | Transcript |
+| `ctrl+home`, `ctrl+end` | Editor | Editor |
+| `pageUp`, `pageDown` | Editor | Transcript |
+| `ctrl+pageUp`, `ctrl+pageDown` | Editor | Editor |
+
+This routing remains configurable through the ordinary action bindings. For example, `"tui.altScreen.pageUp": "ctrl+pageUp"` makes `pageUp` control the editor and `ctrl+pageUp` control the transcript in fullscreen mode. Bind `tui.altScreen.halfPageUp` and `tui.altScreen.halfPageDown` for smaller transcript steps while keeping the full-page bindings. Setting `"tui.altScreen.pageUp": []` disables that transcript shortcut entirely. User bindings replace the defaults for that action.
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.altScreen.pageUp` | `pageUp` | Scroll the transcript up by one page |
+| `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
+| `tui.altScreen.halfPageUp` | *(none)* | Scroll the transcript up by half a page |
+| `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
+| `tui.altScreen.previousPrompt` | `ctrl+shift+up` | Jump to the previous marked message |
+| `tui.altScreen.nextPrompt` | `ctrl+shift+down` | Jump to the next marked message |
+| `tui.altScreen.top` | `home` | Scroll to the beginning of the transcript |
+| `tui.altScreen.bottom` | `end` | Scroll to the transcript end and follow new output |
+
 ### Application
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
 | `app.interrupt` | `escape` | Cancel / abort |
-| `app.clear` | `ctrl+c` | Clear editor |
+| `app.clear` | `ctrl+c` | Clear editor (first) / exit (second) |
 | `app.exit` | `ctrl+d` | Exit (when editor empty) |
 | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
 | `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
-| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image from clipboard |
+| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image or text from clipboard |
 
 ### Sessions
 
@@ -158,8 +190,8 @@ Create `~/.pi/agent/keybindings.json`:
 
 ```json
 {
-  "tui.editor.cursorUp": ["up", "ctrl+p"],
-  "tui.editor.cursorDown": ["down", "ctrl+n"],
+  "tui.editor.historyPrevious": "ctrl+p",
+  "tui.editor.historyNext": "ctrl+n",
   "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
 }
 ```
@@ -172,8 +204,8 @@ On native Windows, `app.suspend` has no default binding because Windows terminal
 
 ```json
 {
-  "tui.editor.cursorUp": ["up", "ctrl+p"],
-  "tui.editor.cursorDown": ["down", "ctrl+n"],
+  "tui.editor.historyPrevious": "ctrl+p",
+  "tui.editor.historyNext": "ctrl+n",
   "tui.editor.cursorLeft": ["left", "ctrl+b"],
   "tui.editor.cursorRight": ["right", "ctrl+f"],
   "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],