tau-coding-agent 0.4.6__tar.gz → 0.4.8__tar.gz

{tau_coding_agent-0.4.6/tau_coding_agent.egg-info → tau_coding_agent-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tau-coding-agent
-Version: 0.4.6
+Version: 0.4.8
 Summary: A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -26,8 +26,10 @@ Requires-Dist: pygments==2.20.0
 Requires-Dist: pathspec==1.1.1
 Requires-Dist: gitpython==3.1.50
 Requires-Dist: grapheme==0.6.0
+Requires-Dist: arrow==1.4.0
 Provides-Extra: tools
 Requires-Dist: ripgrep>=14.0.0; extra == "tools"
+Requires-Dist: ast-grep-cli>=0.44.0; extra == "tools"
 Dynamic: license-file
 
 # Tau (τ)

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/architecture.md

@@ -183,8 +183,9 @@ Extensions can react to lifecycle events:
 - `session_start` - Session begins
 - `turn_start` - New inference turn starts
 - `turn_end` - Turn completes (before rendering)
-- `tool_execute` - Tool is about to execute
-- `tool_complete` - Tool execution finished
+- `tool_call` - Tool call can be inspected, rewritten, or blocked
+- `tool_result` - Tool result can be inspected or rewritten
+- `tool_execution_start` / `tool_execution_end` - Tool handler lifecycle
 - `tui_ready` - TUI is ready for input
 - `tui_exit` - TUI is exiting
 - `compaction_start` - Compaction begins
@@ -194,12 +195,13 @@ Hooks allow extensions to inspect state, modify messages, or react to events.
 
 ## Provider Abstraction
 
-All LLM providers (Anthropic, OpenAI, Google, Mistral, Ollama, Azure) implement a common interface:
+Providers describe authentication, endpoints, and the API adapter used for a
+request. Adapters stream normalized `LLMEvent` objects:
 
 ```python
-class Provider:
-    async def call(messages, tools, model) -> Response
-    async def stream(messages, tools, model) -> AsyncIterator[Event]
+class BaseAPI:
+    async def stream(self, context, model, options) -> AsyncIterator[LLMEvent]:
+        ...
 ```
 
 The inference module handles provider-specific details (API keys, endpoints, format conversions).
@@ -289,9 +291,9 @@ React to lifecycle events:
 
 ```python
 def register(tau):
-    async def on_tool_complete(event):
+    async def on_tool_end(event, ctx):
         print(f"Tool {event.tool_name} finished")
-    tau.on_hook("tool_complete", on_tool_complete)
+    tau.on("tool_execution_end", on_tool_end)
 ```
 
 ### Dialogs

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/auth.md

@@ -6,7 +6,7 @@ Tau stores credentials for LLM providers in `~/.tau/auth.json`. This page explai
 
 For each provider, tau resolves credentials in this order:
 
-1. **Runtime override** — set via `--api-key` on the CLI (not persisted)
+1. **Runtime override** — set programmatically through `AuthManager` (not persisted)
 2. **Stored credential** — read from `~/.tau/auth.json`
 3. **Environment variable** — `{PROVIDER}_API_KEY` (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
 
@@ -69,13 +69,11 @@ export OPENAI_API_KEY="sk-..."
 
 No file is needed — tau picks these up automatically.
 
-### CLI flag (one-off override)
+### Runtime override
 
-```bash
-tau --api-key sk-ant-...
-```
-
-Not stored. Only applies to the current session.
+Embedding applications may call
+`auth_manager.set_runtime_api_key(provider, key)`. The main Tau CLI does not
+provide an `--api-key` flag.
 
 ### Auth file (direct edit)
 
@@ -91,7 +89,9 @@ Run `/login` from within a session. Tau asks which authentication type to use:
 
 ### `/logout` command
 
-Run `/logout` to open a list of providers that have credentials stored in `~/.tau/auth.json`. Select one to remove it. Environment variables and CLI `--api-key` flags are unaffected.
+Run `/logout` to open a list of providers that have credentials stored in
+`~/.tau/auth.json`. Select one to remove it. Environment variables and
+programmatic runtime overrides are unaffected.
 
 ## Auth File Format
 
@@ -120,7 +120,7 @@ From Python (e.g. in an extension):
 status = auth_manager.get_auth_status("anthropic")
 # status.configured  → True / False
 # status.source      → "stored" | "runtime" | "env" | None
-# status.label       → env var name or "--api-key" if runtime
+# status.label       → env var name or "runtime override"
 ```
 
 ## Security

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/cli-reference.md

@@ -3,7 +3,7 @@
 ## Usage
 
 ```bash
-tau [OPTIONS] [MESSAGE]
+tau [OPTIONS] COMMAND [ARGS]...
 ```
 
 Use `--prompt TEXT` for a non-interactive prompt. Piped stdin can supply or
@@ -13,14 +13,20 @@ augment it.
 
 | Option | Short | Description |
 |--------|-------|-------------|
+| `--version` | `-v` | Print the installed version |
+| `--debug` | `-d` | Enable debug logging |
+| `--cwd PATH` | `-c` | Set the working directory |
 | `--prompt` | `-p` | Run a non-interactive prompt |
+| `--output-format` | `-f` | Non-interactive output: `text` or `json` |
+| `--quiet` | `-q` | Hide the non-interactive spinner |
 | `--provider` | | Provider to use, e.g. `anthropic`, `openai`, `groq` |
 | `--model` | | Model ID, or `provider/model` shorthand (e.g. `groq/llama-3.3-70b-versatile`) |
-| `--theme` | `-t` | UI theme: `default`, `dracula`, `nord`, `gruvbox`, `catppuccin`, `ayu-dark`, `everforest`, `horizon`, `kanagawa`, `material-ocean`, `monokai`, `night-owl`, `one-dark`, `rose-pine`, `solarized-dark`, `tokyo-night`, or a custom name |
+| `--theme` | `-t` | UI theme: `dark`, `light`, or an installed custom theme |
 | `--resume [ID]` | `-r` | Resume the most recent or a specified session |
 | `--fork ID` | | Fork a specified session at startup |
 | `--session-dir PATH` | | Override session storage |
 | `--name NAME` | | Set the session display name at startup |
+| `--system TEXT` | `-s` | Replace the generated system prompt |
 | `--ephemeral` | `-e` | Don't save this session to disk |
 | `--approve` | `-a` | Trust project-local files (extensions, settings, context files) for this run |
 | `--no-approve` | `-na` | Don't trust project-local files for this run |
@@ -31,6 +37,13 @@ augment it.
 
 ## Run Modes
 
+## Interactive Commands
+
+`/watch <url> [question]` loads metadata and available English captions for a
+public video through `yt-dlp`, then sends them to the active model. Install
+`yt-dlp` separately and ensure it is available on `PATH`. Video frames and
+audio transcription are not performed.
+
 ### Interactive (default)
 
 Start the full terminal UI:
@@ -59,7 +72,7 @@ that order.
 Emit a JSON event stream on stdout:
 
 ```bash
-tau --mode json "Your prompt"
+tau --mode json --prompt "Your prompt"
 ```
 
 Each line is a JSON object representing a lifecycle event (`agent_start`, `message_end`, etc.).
@@ -338,8 +351,7 @@ An explicit `--provider` always overrides the inferred provider.
 
 ```bash
 tau --resume                                    # continue most recent session
-tau --session abc123                            # resume by session ID
-tau --session ~/.tau/sessions/proj/file.jsonl   # resume by file path
+tau --resume abc123                             # resume by session ID
 tau --ephemeral                                 # temporary session, nothing saved
 ```
 
@@ -353,13 +365,16 @@ Manage provider credentials.
 tau auth --help
 ```
 
+Package management is available through `tau install`, `tau remove`,
+`tau list`, and `tau update`.
+
 ## Environment Variables
 
 | Variable | Effect |
 |----------|--------|
 | `ANTHROPIC_API_KEY` | Anthropic API key |
 | `OPENAI_API_KEY` | OpenAI API key |
-| `GEMINI_API_KEY` | Google Gemini key |
+| `GOOGLE_API_KEY` | Google Gemini key |
 | `<PROVIDER>_API_KEY` | API key for any provider (uppercased provider name) |
 
 Provider and model can also be set permanently in `settings.json` — see [Settings](settings.md).

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/development.md

@@ -4,15 +4,15 @@ This page covers setting up a development environment for tau.
 
 ## Prerequisites
 
-- Python 3.13 or higher
+- Python 3.12 or higher
 - git
 - pip or uv (Python package manager)
 
 ## Clone the Repository
 
 ```bash
-git clone https://github.com/yourusername/tau.git
-cd tau
+git clone https://github.com/Jeomon/Tau.git
+cd Tau
 ```
 
 ## Install Dependencies
@@ -63,7 +63,7 @@ tau --theme dark
 ### Run with Debug Logging
 
 ```bash
-TAU_LOG_LEVEL=DEBUG tau
+tau --debug
 ```
 
 ### Run Tests
@@ -215,7 +215,7 @@ logger.error("Error message")
 Enable debug logging:
 
 ```bash
-TAU_LOG_LEVEL=DEBUG tau
+tau --debug
 ```
 
 ## IDE Setup

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/docs.json

@@ -43,6 +43,10 @@
         {
           "title": "Tools",
           "path": "tools.md"
+        },
+        {
+          "title": "Project Context",
+          "path": "project-context.md"
         }
       ]
     },
@@ -57,6 +61,10 @@
           "title": "Extensions",
           "path": "extensions.md"
         },
+        {
+          "title": "Extension Settings",
+          "path": "extension-settings.md"
+        },
         {
           "title": "Themes",
           "path": "themes.md"
@@ -76,6 +84,10 @@
         {
           "title": "Authentication",
           "path": "auth.md"
+        },
+        {
+          "title": "HTTP Proxy",
+          "path": "http-proxy.md"
         }
       ]
     },

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/extensions.md

@@ -487,6 +487,34 @@ def register(tau):
 | `input` | `text`, `source` | `InputEventResult` | New user message received. `source`: `interactive \| rpc \| extension \| queue`. Return `action="transform"` with `text=` to replace, or `action="handled"` to suppress |
 | `context` | `messages` | `ContextEventResult` | Full message history about to be sent to LLM. Return `messages=` to rewrite it |
 
+For dynamic browser or computer-use state that must be refreshed before every
+LLM request without being persisted, return `ephemeral_messages` from a
+`context` handler:
+
+```python
+from tau.hooks import ContextEventResult
+from tau.message.types import UserMessage
+
+def register(tau):
+    @tau.on("context")
+    async def inject_state(event, ctx):
+        screenshot = await capture_screen()
+        return ContextEventResult(
+            ephemeral_messages=[
+                UserMessage.with_images(
+                    "Current browser state",
+                    images=[screenshot],
+                )
+            ]
+        )
+```
+
+The hook runs before every inference, including after tool execution.
+`ephemeral_messages` must contain only `UserMessage` objects. They are appended
+only to the provider request, are not persisted, and are excluded from
+Anthropic prompt-cache breakpoints. Use `messages=` in the same result to
+replace the stable request context.
+
 **Streaming & messages**
 
 | Event | Payload fields | Result type | Description |
@@ -628,6 +656,19 @@ def register(tau):
 
 ## Keyboard shortcuts
 
+`register_shortcut` takes a literal key combination. Tau compares extension
+shortcuts with the effective `KeyMap`.
+Safety-critical editor and application bindings are reserved and cannot be
+replaced by extensions. An extension may replace a non-reserved global
+application binding, with a warning. If multiple extensions register the same
+key, the last loaded extension wins and Tau reports a warning.
+
+Some low-level editor operations that are not exposed as `KeyMap` actions,
+such as cursor movement, are still consumed directly by the focused editor.
+Registering an extension shortcut does not replace those operations. See
+[Customising keybindings](keybindings.md#customising-keybindings) for the
+available actions.
+
 ```python
 def register(tau):
     @tau.register_shortcut("ctrl+g", "Open greeter")
@@ -816,7 +857,7 @@ def register(tau):
 | `tau.register_tool(tool)` | Add a tool the agent can call |
 | `tau.register_command(name, desc, handler, aliases=[], get_argument_completions=None, argument_hint=None, requires_idle=True)` | Add a `/name` slash command; set `requires_idle=False` only for UI-only or read-only handlers safe during an active turn |
 | `tau.on(event, handler)` / `@tau.on(event)` | Subscribe to a lifecycle event |
-| `tau.register_shortcut(key, desc, handler)` | Bind a keyboard shortcut |
+| `tau.register_shortcut(key, desc, handler)` | Bind a literal keyboard shortcut |
 | `tau.append_prompt(text)` | Append text to the system prompt |
 | `tau.register_theme(name, theme)` | Add a named theme to the picker |
 | `tau.register_message_renderer(type, fn)` | Render custom message types in the TUI |

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/http-proxy.md

@@ -378,4 +378,4 @@ OAuth login/refresh operations (e.g., GitHub Copilot, OpenAI, Anthropic) also re
 
 - [Settings](settings.md) — Main settings reference
 - [Extensions](extensions.md) — Extensions can also use proxy settings via SettingsManager
-- [Providers](providers.md) — Model provider configuration (some may have custom proxy handling)
+- [Inference Providers](inference-providers.md) — Model provider configuration

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/index.md

@@ -6,7 +6,7 @@ Tau is a Python CLI framework for building interactive agent applications. It pr
 
 Tau allows you to:
 - Chat with LLMs (Claude, GPT, Gemini, Mistral, Ollama) in a terminal UI
-- Execute tools (terminal commands, read/write files, fetch web content) within conversations
+- Execute tools (terminal commands, file operations, search) within conversations
 - Save and resume sessions with branching and forking
 - Extend Tau with custom tools, commands, themes, and skills
 - Embed Tau in Python applications as a library
@@ -27,6 +27,7 @@ Tau allows you to:
 - [Sessions](sessions.md) - Session persistence, branching, compaction, JSONL format
 - [Inference Providers](inference-providers.md) - Supported LLMs and provider setup
 - [Tools](tools.md) - Tool registry, built-in tools, execution model
+- [Project Context Files](project-context.md) - Repository-specific agent instructions
 - [CLI Reference](cli-reference.md) - All command-line options and run modes
 
 ## Configuration & Customization
@@ -52,14 +53,13 @@ Tau allows you to:
 
 - [Project Structure](project-structure.md) - Codebase organization and module breakdown
 - [Development Setup](development.md) - Local development environment and testing
-- [Implementation Summary](IMPLEMENTATION_SUMMARY.md) - Recent changes and features
 
 ## Reference
 
 - [CLI Reference](cli-reference.md) - All flags, modes (interactive/print/json/rpc)
 - [Settings Reference](settings.md) - Complete settings schema
 - [Session Format](sessions.md) - JSONL file format and structure
-- [Hooks & Events](extensions.md#hooks) - All available hooks and events
+- [Hooks & Events](extensions.md#event-hooks) - All available hooks and events
 
 ---
 

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/inference-providers.md

@@ -6,22 +6,22 @@ This page documents all supported LLM inference providers and their setup.
 
 Tau supports the following inference providers:
 
-| Provider | Auth Type | Free Tier | Setup |
-|----------|-----------|-----------|-------|
-| Anthropic | API Key | Limited | [Link](#anthropic) |
-| OpenAI | API Key | No | [Link](#openai) |
-| Google Gemini | API Key | Yes | [Link](#google-gemini) |
-| Mistral AI | API Key | Limited | [Link](#mistral-ai) |
-| Fireworks AI | API Key | No | [Link](#fireworks-ai) |
-| Ollama | None | Yes | [Link](#ollama-local) |
-| Azure OpenAI | API Key | No | [Link](#azure-openai) |
+Built-in API-key providers are `openai`, `anthropic`, `google`, `nvidia`,
+`groq`, `openrouter`, `perplexity`, `xai`, `bedrock`, `kimi`, `minimax`,
+`cerebras`, `deepseek`, `kilocode`, `fireworks`, and `mistral`.
+
+Tau also includes local `ollama`, Google/Anthropic/OpenAI-compatible Vertex AI
+providers, and OAuth providers for OpenAI Codex, Claude Code, GitHub Copilot,
+and Google Antigravity. Extensions can register additional providers.
+
+The model picker is the authoritative model catalogue. Built-in model metadata
+changes more frequently than this guide, so model IDs and pricing are not
+enumerated here.
 
 ## Anthropic
 
 Anthropic provides Claude models with best-in-class reasoning and code generation.
 
-**Models**: `claude-3-5-sonnet`, `claude-3-opus`, `claude-3-haiku`, `claude-3-5-haiku`
-
 ### Setup
 
 1. Create an account at [Anthropic Console](https://console.anthropic.com)
@@ -42,8 +42,6 @@ tau --model anthropic/claude-3-5-sonnet -p "Say hello"
 
 OpenAI provides GPT models optimized for a wide range of tasks.
 
-**Models**: `gpt-4`, `gpt-4-turbo`, `gpt-4o`, `gpt-3.5-turbo`
-
 ### Setup
 
 1. Create an account at [OpenAI Platform](https://platform.openai.com)
@@ -64,8 +62,6 @@ tau --model openai/gpt-4o -p "Say hello"
 
 Google provides Gemini models with multimodal capabilities.
 
-**Models**: `gemini-2.0-flash`, `gemini-1.5-pro`, `gemini-1.5-flash`
-
 ### Setup
 
 1. Visit [Google AI Studio](https://aistudio.google.com)
@@ -73,7 +69,7 @@ Google provides Gemini models with multimodal capabilities.
 3. Set the environment variable:
 
 ```bash
-export GEMINI_API_KEY=...
+export GOOGLE_API_KEY=...
 ```
 
 ### Verify
@@ -86,8 +82,6 @@ tau --model google/gemini-2.0-flash -p "Say hello"
 
 Mistral offers efficient open-source-based models.
 
-**Models**: `mistral-large`, `mistral-medium`, `mistral-small`
-
 ### Setup
 
 1. Create an account at [Mistral Console](https://console.mistral.ai)
@@ -108,21 +102,6 @@ tau --model mistral/mistral-large -p "Say hello"
 
 Fireworks AI provides fast, cost-efficient inference for open-source models including Llama, DeepSeek, Qwen, and Mixtral — with OpenAI-compatible APIs.
 
-**Text models**:
-
-| Model | Context | Pricing (in/out per M tokens) |
-|-------|---------|-------------------------------|
-| `accounts/fireworks/models/llama-v3p3-70b-instruct` | 131K | $0.90 / $0.90 |
-| `accounts/fireworks/models/llama-v3p1-405b-instruct` | 131K | $3.00 / $3.00 |
-| `accounts/fireworks/models/deepseek-r1` *(thinking)* | 160K | $3.00 / $7.00 |
-| `accounts/fireworks/models/deepseek-v3` | 131K | $0.90 / $0.90 |
-| `accounts/fireworks/models/qwen3-235b-a22b` *(thinking)* | 131K | $0.22 / $0.88 |
-| `accounts/fireworks/models/qwen3-30b-a3b` *(thinking)* | 131K | $0.15 / $0.60 |
-| `accounts/fireworks/models/mixtral-8x22b-instruct` | 65K | $0.90 / $0.90 |
-| `accounts/fireworks/models/gemma2-9b-it` | 8K | $0.20 / $0.20 |
-
-**Image models**: Flux 1 Schnell FP8, Flux 1 Dev FP8
-
 ### Setup
 
 1. Create an account at [Fireworks AI](https://fireworks.ai)
@@ -148,8 +127,6 @@ tau --model fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct -p "Say
 
 Run open-source models locally without API keys or internet.
 
-**Models**: `llama2`, `mistral`, `neural-chat`, `qwen3.5:cloud` (262K context, thinking), and [others](https://ollama.ai/library)
-
 ### Setup
 
 1. Install [Ollama](https://ollama.ai)
@@ -165,11 +142,7 @@ ollama pull mistral
 ollama serve
 ```
 
-4. Set the endpoint (default works if running locally):
-
-```bash
-export OLLAMA_BASE_URL=http://localhost:11434
-```
+Tau connects to `http://localhost:11434` by default.
 
 ### Verify
 
@@ -177,30 +150,6 @@ export OLLAMA_BASE_URL=http://localhost:11434
 tau --model ollama/mistral -p "Say hello"
 ```
 
-## Azure OpenAI
-
-Use OpenAI models hosted on Azure infrastructure.
-
-**Models**: Same as OpenAI (gpt-4, gpt-3.5-turbo, etc.)
-
-### Setup
-
-1. Create an Azure OpenAI resource in the Azure Portal
-2. Deploy a model (e.g., gpt-4)
-3. Set environment variables:
-
-```bash
-export AZURE_OPENAI_API_KEY=...
-export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
-export AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4
-```
-
-### Verify
-
-```bash
-tau --model azure/gpt-4 -p "Say hello"
-```
-
 ## Switching Providers
 
 ### Command Line

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/installation.md

@@ -4,7 +4,7 @@ This page covers installation and authentication setup for Tau and its inference
 
 ## Prerequisites
 
-- Python 3.13 or higher
+- Python 3.12 or higher
 - pip, uv, or another Python package manager
 - An API key or subscription from at least one inference provider
 
@@ -60,7 +60,7 @@ Get your API key from [OpenAI's platform](https://platform.openai.com/account/ap
 ### Google Gemini
 
 ```bash
-export GEMINI_API_KEY=...
+export GOOGLE_API_KEY=...
 ```
 
 Create a key at [Google AI Studio](https://aistudio.google.com).
@@ -75,13 +75,8 @@ Get your key from [Mistral's console](https://console.mistral.ai).
 
 ### Ollama (Local)
 
-If running Ollama locally, set the endpoint:
-
-```bash
-export OLLAMA_BASE_URL=http://localhost:11434
-```
-
-Ollama does not require an API key.
+Ollama uses `http://localhost:11434` by default and does not require an API
+key. Configure a different endpoint through a provider extension.
 
 ## Configure Authentication
 
@@ -103,7 +98,7 @@ Store credentials in `~/.tau/auth.json`:
 {
   "anthropic": { "type": "api_key", "key": "sk-ant-..." },
   "openai": { "type": "api_key", "key": "sk-..." },
-  "gemini": { "type": "api_key", "key": "..." }
+  "google": { "type": "api_key", "key": "..." }
 }
 ```
 
@@ -182,7 +177,7 @@ If using Ollama, ensure the service is running:
 ollama serve
 ```
 
-And verify the endpoint matches your `OLLAMA_BASE_URL` setting.
+Tau currently expects the service at `http://localhost:11434`.
 
 ## Next Steps
 

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.8}/docs/keybindings.md

@@ -27,7 +27,7 @@
 
 | Shortcut | Action |
 |----------|--------|
-| Escape | Abort current turn; restore queued messages |
+| Escape | Abort the active operation; double-press while idle to clear TUI messages |
 | Ctrl+C | Abort turn; double-press to quit |
 | Ctrl+D | Quit (on empty input) |
 | Ctrl+O | Toggle expand/collapse for thinking and tool-result blocks |
@@ -56,11 +56,10 @@ Pass a `KeyMap` to `App.create()` at startup:
 from tau.tui import KeyMap
 
 overrides: KeyMap = {
-    "tui.app.quit": ["ctrl+q"],
-    "tui.input.submit": ["enter"],
-    "app.message.followup": ["alt+enter"],
-    "app.details.toggle": ["ctrl+o"],
-    "app.invocations.toggle": ["ctrl+e"],
+    "app.details.toggle": ["ctrl+t"],
+    "app.invocations.toggle": ["ctrl+r"],
+    "tui.select.up": ["up", "ctrl+k"],
+    "tui.select.down": ["down", "ctrl+j"],
 }
 
 app = await App.create(runtime, keybindings=overrides)
@@ -81,7 +80,7 @@ A `KeyMap` is `dict[str, list[str]]` — action name → list of key combos that
 | `app.details.toggle` | `ctrl+o` | Toggle thinking and tool-result previews |
 | `app.invocations.toggle` | `ctrl+e` | Toggle template and skill blocks |
 | `tui.app.quit` | `ctrl+c`, `ctrl+d` | Quit tau |
-| `tui.app.abort` | `ctrl+c` | Abort the current turn |
+| `tui.app.abort` | `escape`, `ctrl+c` | Abort the current turn |
 | `tui.select.up` | `up`, `ctrl+p` | Move selection up |
 | `tui.select.down` | `down`, `ctrl+n` | Move selection down |
 | `tui.select.page_up` | `page_up` | Move up a page |
@@ -90,6 +89,20 @@ A `KeyMap` is `dict[str, list[str]]` — action name → list of key combos that
 | `tui.select.bottom` | `end` | Jump to bottom |
 | `tui.select.confirm` | `enter`, `tab` | Confirm selection |
 | `tui.select.dismiss` | `escape` | Dismiss picker |
+| `tui.scroll.up` | `page_up` | Scroll messages up one page |
+| `tui.scroll.down` | `page_down` | Scroll messages down one page |
+| `tui.scroll.top` | `home` | Scroll to the first message |
+| `tui.scroll.bottom` | `end` | Scroll to the latest message |
+
+The `tui.select.*` actions apply to components built on Tau's reusable
+`SelectList` and to the corresponding navigation operations in specialized
+pickers. A specialized picker may not support every operation; for example, a
+compact autocomplete list only supports up and down.
+
+Extension shortcuts are literal key combinations rather than `KeyMap` actions.
+Tau checks them against the effective map and prevents extensions from
+replacing reserved editor and application bindings. See
+[Keyboard shortcuts](extensions.md#keyboard-shortcuts).
 
 ### Key notation
 
@@ -125,7 +138,10 @@ If a binding doesn't work, choose a different combination.
 
 ## Reloading
 
-Keybinding overrides are applied at startup. To pick up changes, restart tau or run `/reload`.
+`App.create(keybindings=...)` applies overrides at startup. Because these
+overrides are supplied by the embedding application rather than loaded from a
+settings file, `/reload` does not change them. Restart the application with a
+new `KeyMap` to apply different overrides.
 
 ---