kward 0.70.0 → 0.72.0

data/doc/authentication.md

@@ -12,7 +12,9 @@ Or inside interactive Kward:
 /login
 ```
 
-Use the provider you already have access to. You can change providers later.
+`/login` opens a provider picker; `kward login` accepts the provider as an argument.
+
+Use the provider you already have access to. You can change the active model later with `/model`.
 
 ## Choose a provider
 
@@ -34,8 +36,6 @@ kward login openrouter   # OpenRouter API key
 kward login github       # GitHub OAuth for experimental Copilot support
 ```
 
-From source, replace `kward` with `ruby lib/main.rb`.
-
 ## OpenAI / ChatGPT
 
 ```bash
@@ -58,6 +58,14 @@ If Kward asks for an OAuth client ID, add it to `~/.kward/config.json`:
 }
 ```
 
+Kward ships with a built-in client ID, so this is only needed if login fails or you want to use your own.
+
+For a single shell session without OAuth, you can set an access token directly:
+
+```bash
+OPENAI_ACCESS_TOKEN=... kward
+```
+
 ## Anthropic Claude Pro/Max
 
 ```bash
@@ -88,6 +96,37 @@ OPENROUTER_API_KEY=sk-or-v1-... kward
 
 Choose OpenRouter when you want access to its model catalog or want provider/model selection through an API key.
 
+### Refresh the OpenRouter model cache
+
+Kward's `/model` picker can show OpenRouter models that are available to your API key. Refresh the local cache after logging in:
+
+```bash
+kward openrouter refresh
+```
+
+This fetches text-capable OpenRouter models for the configured key and writes them to:
+
+```text
+~/.kward/cache/openrouter_models.json
+```
+
+If `KWARD_CONFIG_PATH` points at a custom config file, the cache is written beside that config file under `cache/openrouter_models.json`.
+
+Inspect the cached model ids with:
+
+```bash
+kward openrouter list
+```
+
+Use this when:
+
+- you added or changed your OpenRouter API key,
+- OpenRouter added new models,
+- your model picker does not show the model you expect,
+- you want Kward to use current context-window metadata from OpenRouter.
+
+After refreshing, start Kward and choose the model with `/model`.
+
 ## Experimental Copilot support
 
 ```bash
@@ -108,34 +147,29 @@ COPILOT_GITHUB_TOKEN=... kward
 
 Copilot support is experimental and uses direct HTTPS calls to the Copilot proxy API. It does not use the official Copilot CLI or SDK runtime.
 
-## Which credential wins?
+## Choose the active model
 
-If multiple credentials are available, Kward uses the configured provider.
+Authentication makes providers available. The active model is selected separately.
 
-Set it in `~/.kward/config.json`:
+Inside Kward, use:
 
-```json
-{
-  "provider": "anthropic"
-}
+```text
+/model
 ```
 
-Or for one command:
+The model picker is the normal way to switch between configured providers and models. You can keep credentials for multiple providers and choose the model you want for the current work.
 
-```bash
-KWARD_PROVIDER=openrouter kward
-```
+For one-off shell runs, `KWARD_PROVIDER` and provider-specific model environment variables remain available. See [Configuration](configuration.md) for the full list.
 
-Supported provider values:
+## Custom auth file locations
 
-```text
-codex
-anthropic
-openrouter
-copilot
-```
+Each auth file has an environment variable override, useful for isolated or multi-account setups. When unset, they default to the paths shown above under `~/.kward/`.
+
+- `KWARD_AUTH_PATH` — OpenAI OAuth credentials (`auth.json`)
+- `KWARD_ANTHROPIC_AUTH_PATH` — Anthropic OAuth credentials (`anthropic_auth.json`)
+- `KWARD_GITHUB_AUTH_PATH` — GitHub OAuth credentials (`github_auth.json`)
 
-Without an explicit provider, OpenAI/ChatGPT credentials are preferred when present.
+When `KWARD_CONFIG_PATH` points at a custom config file, the OpenRouter API key is stored in that file instead of `~/.kward/config.json`.
 
 ## Security notes
 
@@ -143,4 +177,5 @@ Without an explicit provider, OpenAI/ChatGPT credentials are preferred when pres
 - Do not commit `~/.kward/config.json` or auth files.
 - Prefer environment variables for temporary credentials.
 - `kward auth status` shows credential status without printing secrets.
-- `kward auth logout` removes saved credentials.
+- `kward auth logout` removes **all** saved credentials at once: every OAuth file (OpenAI, Anthropic, GitHub) and the stored OpenRouter API key. There is no per-provider logout; to remove a single provider, delete its auth file by hand.
+- `kward doctor` reports which credentials are currently configured alongside other local checks.

data/doc/code-search.md

@@ -31,6 +31,18 @@ The `code_search` tool can:
 
 Kward should use this when the best answer depends on how another project actually implemented something.
 
+## Supported ecosystems
+
+`package_search` and `github_search` accept an `ecosystem` parameter to narrow results:
+
+- `rubygems` — RubyGems
+- `npm` — npm registry
+- `pypi` — Python Package Index
+- `crates` — crates.io (Rust)
+- `go` — Go module documentation
+
+When omitted, `package_search` requires a `package` name and infers the registry from the ecosystem. `github_search` uses the ecosystem as an optional hint alongside the search query.
+
 ## Cache location
 
 Repositories are cached outside your workspace:
@@ -63,7 +75,7 @@ or:
 GH_TOKEN=...
 ```
 
-Tokens are used for GitHub API requests and are not included in tool output.
+Tokens are used for GitHub API requests and are not included in tool output. See [Configuration](configuration.md) for the full environment variable reference.
 
 ## Tool actions
 
@@ -80,4 +92,32 @@ The tool uses an `action` parameter:
 | `refresh_cache` | fetch updates for a cached repository. |
 | `clear_cache` | remove a cached repository. |
 
-Search and read results are bounded so Kward does not load large external repositories into context by accident. Oversized and binary files are skipped.
+### Action arguments
+
+| Action | Required arguments | Optional arguments |
+| --- | --- | --- |
+| `package_search` | `ecosystem`, `package` | — |
+| `github_search` | `query` | `ecosystem`, `max_results` |
+| `repo_clone` | `repo` | — |
+| `repo_search` | `repo`, `query` | `max_results`, `context_lines` |
+| `repo_read` | `repo`, `path` | `start_line`, `line_count` |
+| `list_cache` | — | — |
+| `refresh_cache` | `repo` | — |
+| `clear_cache` | `repo` | — |
+
+- `repo` is a GitHub URL or `owner/name`.
+- `query` is a plain-text search string (not regex). Matching is case-sensitive substring.
+- `start_line` is 1-indexed.
+- `context_lines` controls how many lines before and after a match are included in search snippets.
+
+## Limits
+
+Search and read results are bounded so Kward does not load large external repositories into context by accident:
+
+- Search results: default 10 per query, max 50.
+- Context lines in search snippets: default 2, max 5.
+- Lines returned by `repo_read`: default 200, max 400.
+- File size limit: 512 KB. Files larger than this are skipped during search and rejected on read.
+- Scanned files in `repo_search`: max 5,000 files per scan. Files in `.git` directories, symlinks, files outside the repo root, and oversized files are skipped. Binary files fail gracefully via encoding detection and are skipped.
+- Output truncation: 16 KB total per tool result.
+- HTTP timeout: 10 seconds for all network requests.

data/doc/configuration.md

@@ -2,7 +2,7 @@
 
 Kward reads user configuration from `~/.kward/config.json` by default. Most users do not need to edit this file by hand at first: use `/login`, `/model`, `/reasoning`, and `/settings` from inside Kward when possible.
 
-On first start, if the file does not exist, Kward creates a starter config with an active Kward persona, explicit disabled memory settings, and the default composer busy-help setting so you can inspect and edit them. Provider-specific model defaults are added only when you choose a provider/model. If `KWARD_CONFIG_PATH` is set, Kward uses that file instead and treats that file's directory as the config directory for prompts, skills, memory, logs, and caches.
+On first start, if the file does not exist, Kward creates a starter config with an active Kward persona, explicit disabled memory settings, and the default composer busy-help setting so you can inspect and edit them. Provider-specific model defaults are added only when you choose a provider/model. See [Personas](personas.md) for configuring persona selection by workspace, model, or reasoning effort. If `KWARD_CONFIG_PATH` is set, Kward uses that file instead and treats that file's directory as the config directory for prompts, skills, memory, logs, and caches.
 
 Small examples:
 
@@ -34,9 +34,31 @@ By default, Kward stores user data under `~/.kward`:
 ~/.kward/memory/
 ~/.kward/logs/
 ~/.kward/cache/
+~/.kward/plugins/
 ```
 
-When `KWARD_CONFIG_PATH=/path/to/config.json` is set, most config-related files live beside that file instead. User plugins are the exception: they are loaded only from `~/.kward/plugins`.
+When `KWARD_CONFIG_PATH=/path/to/config.json` is set, most config-related files live beside that file instead. User plugins are the exception: they are loaded only from `~/.kward/plugins`. See [Plugins](plugins.md) for writing and loading user plugins.
+
+## Embedded shell config
+
+The embedded Kward shell (`/shell`, internally `ekwsh`) reads optional global settings from `~/.kward/ekwsh.yml` or, when `KWARD_CONFIG_PATH` is set, from `ekwsh.yml` beside that config file.
+
+Example:
+
+```yaml
+env:
+  FORCE_COLOR: "1"
+  CLICOLOR_FORCE: "1"
+
+aliases:
+  ll: "ls -la"
+  gs: "git status --short"
+  gd: "git diff --color=always"
+```
+
+`env` values are applied when shell mode starts, after Kward's conservative color defaults. Keys must look like environment variable names (`A_Z`, digits after the first character, and underscores); invalid keys are ignored. Values are converted to strings.
+
+`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Built-in `ekwsh` commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, and `exit` take precedence over aliases. Run `alias` inside `ekwsh` to list configured aliases. Aliases are also included in command-name Tab completion.
 
 ## Provider and model settings
 
@@ -48,6 +70,8 @@ Set `provider` to choose the active backend:
 }
 ```
 
+When `provider` is unset, Kward infers the backend from available credentials, defaulting to OpenAI/Codex when OAuth credentials are present. Set `provider` or `KWARD_PROVIDER` to select another backend explicitly.
+
 Supported values are:
 
 - `codex` for the OpenAI/ChatGPT Codex backend.
@@ -73,7 +97,7 @@ Model settings:
 }
 ```
 
-`model` is a generic setting for the active provider. Provider-specific values such as `openai_model`, `anthropic_model`, `openrouter_model`, and `copilot_model` take precedence for their provider. `reasoning_effort` and `thinking_level` are generic reasoning settings. `openai_reasoning_effort`, `anthropic_reasoning_effort`, `openrouter_reasoning_effort`, and `copilot_reasoning_effort` are provider-specific forms.
+`model` is a generic setting for the active provider. Provider-specific values such as `openai_model`, `anthropic_model`, `openrouter_model`, and `copilot_model` take precedence for their provider. `reasoning_effort` and `thinking_level` are generic reasoning settings. `thinking_level` is an alias for `reasoning_effort` honored by all providers. For each provider, Kward resolves reasoning in this order: the provider-specific key (for example `openai_reasoning_effort`), then the generic `reasoning_effort`, then `thinking_level`, then the default `medium`. `openai_reasoning_effort`, `anthropic_reasoning_effort`, `openrouter_reasoning_effort`, and `copilot_reasoning_effort` are provider-specific forms.
 
 Defaults:
 
@@ -83,7 +107,7 @@ Defaults:
 - Copilot: `gpt-5-mini`
 - Reasoning effort: `medium`
 
-The interactive `/model` picker prefers OpenRouter models available to the configured API key when Kward can fetch them. `/openrouter/catalog` and RPC `openrouter/catalog` list the full OpenRouter catalog separately.
+The interactive `/model` picker reads cached OpenRouter models when available. Run `kward openrouter refresh` to fetch text-capable models available to the configured OpenRouter API key and cache them under `~/.kward/cache/openrouter_models.json`. Run `kward openrouter list` to inspect the cached model ids.
 
 ## Environment overrides
 
@@ -148,33 +172,98 @@ Overlay settings control terminal picker/card layout:
 
 You can change these interactively with `/settings`.
 
-## Banner settings
+## Composer settings
 
-The interactive terminal banner shows the avatar Kward logo and the “State your business.” message by default. To hide the full banner:
+The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:
 
 ```json
 {
-  "banner": {
-    "enabled": false
+  "composer": {
+    "busy_help": false
   }
 }
 ```
 
-This only affects the interactive terminal UI.
+This only hides the hint text; Ctrl+C still stops the current running response.
 
-## Composer settings
+In the normal composer prompt, `Tab` cycles forward through the current model's reasoning efforts and `Shift+Tab` cycles backward. The shortcuts wrap around and update the persisted reasoning setting; file and slash-command completion overlays keep their existing `Tab` completion behavior.
 
-The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:
+`tab_keybindings` controls how the composer handles tab navigation shortcuts:
 
 ```json
 {
   "composer": {
-    "busy_help": false
+    "tab_keybindings": "auto"
   }
 }
 ```
 
-This only hides the hint text; Ctrl+C still stops the current running response.
+`auto` (default) detects terminal support, `ctrl` uses `Ctrl+Tab`/`Shift+Tab` to cycle suggestions and indent, `alt` uses `Alt+Tab` for terminals where `Ctrl+Tab` is swallowed.
+
+## Editor settings
+
+The built-in TUI file editor supports three keybinding modes. Modern is the default:
+
+```json
+{
+  "editor": {
+    "mode": "modern"
+  }
+}
+```
+
+`mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`. You can change this from `/settings` > Interface > Editor mode; newly opened editor buffers pick up the setting immediately.
+
+The editor automatically highlights Ruby, Crystal, Elixir, Julia, JavaScript, TypeScript, JSON, Markdown, YAML, Shell, Makefile, HTML, CSS, SCSS, Python, Go, Rust, Java, C#, C, C++, Swift, Kotlin, Lua, and SQL files when terminal color is enabled. Unknown file types and color-disabled terminals render plain text.
+
+Auto-indent is enabled by default. Pressing Enter copies the current line indentation, detects the file's indentation unit when possible, and applies lightweight syntax-based indentation for recognized file types. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword, and Ctrl+Enter can force that behavior from the middle of the line in terminals that report modified Enter keys. When auto-indent is enabled, typing obvious closing tokens such as `}`, Ruby/Lua `end`, and shell `fi`/`done`/`esac` re-indents the current line, and Backspace in leading indentation removes one detected indentation unit. To disable it:
+
+```json
+{
+  "editor": {
+    "auto_indent": false,
+    "auto_close_pairs": false
+  }
+}
+```
+
+`auto_indent` and `auto_close_pairs` both default to `true`. Set `auto_close_pairs` to `false` to disable automatic insertion of matching `()`, `[]`, `{}`, quotes, and backticks.
+
+Line numbers are absolute by default. Set `line_numbers` to `relative` to show distances from the cursor line in editable buffers while keeping the current cursor line absolute:
+
+```json
+{
+  "editor": {
+    "line_numbers": "relative"
+  }
+}
+```
+
+Soft-wrap is enabled by default so long lines wrap within the editor width instead of scrolling. To disable it:
+
+```json
+{
+  "editor": {
+    "soft_wrap": false
+  }
+}
+```
+
+Editable editor buffers request a vertical bar cursor by default. Terminals that do not support cursor-shape escape sequences ignore this. To keep the terminal's normal cursor shape while editing:
+
+```json
+{
+  "editor": {
+    "bar_cursor": false
+  }
+}
+```
+
+Modern mode uses composer-style keys: `Ctrl+S` saves, `Ctrl+Q` quits, `Ctrl+F` searches, Shift+Arrow selects text, `Ctrl+C` copies, `Ctrl+X` cuts, `Ctrl+V` pastes the editor kill buffer, `Ctrl+A`/`Ctrl+E` move to the start/end of the line, `Ctrl+B` moves left, `Ctrl+K` kills to end of line, `Ctrl+U` kills to start of line, and `Alt+B`/`Alt+F` move by word.
+
+Emacs mode uses Emacs-style non-modal keys: `Ctrl+X Ctrl+S` saves, `Ctrl+X Ctrl+C` quits, `Ctrl+S` searches forward, `Ctrl+R` searches backward, `Ctrl+Space` sets the mark, `Ctrl+W` kills the region or previous word, `Alt+W` copies the region, `Ctrl+K` kills to end of line, `Ctrl+Y` yanks, and `Alt+Y` cycles the per-buffer kill ring after a yank.
+
+Vibe mode opens files in normal mode and supports a compact classic-vibe subset: normal/insert/command modes, character and line visual modes with `v`/`V`, `h/j/k/l`, word and line movement, counts, simple `d`/`y` operator motions, `dd`, `yy`, `p`, `/` search, `u` undo, and `:w`, `:q`, `:q!`, `:wq`, `:x`, and `:number` commands. Yanks also copy to the terminal clipboard when OSC 52 is supported.
 
 ## Session settings
 

data/doc/context-budgeting.md

@@ -0,0 +1,136 @@
+# Context budgeting and token savings
+
+Kward tries to keep the model's context focused. Instead of reading whole files and pasting every byte of command output back into the conversation, it gathers evidence in small steps, compacts noisy output, and keeps the original data available when needed.
+
+This page summarizes the token-saving work in Kward: what existed before, what the newer focused-context tools add, and how those pieces fit together during normal agent work.
+
+## Why this matters
+
+Coding agents spend a lot of tokens just finding the right code. A single broad file read, failed test run, or web fetch can add thousands of tokens to the next model call. That makes sessions slower, more expensive, and more likely to lose the useful details in noise.
+
+Kward's goal is not to build a heavyweight semantic index. It is to stay lightweight and local while giving the agent a disciplined path:
+
+```text
+find likely files -> inspect outlines/previews -> read exact ranges -> read full files only when needed
+```
+
+## The current workflow
+
+When Kward needs code context, it should usually start with one of these tools:
+
+- `context_for_task` for a compact task-shaped bundle.
+- `summarize_file_structure` for a source outline of one file.
+- `read_file` with `mode: "outline"` or `mode: "preview"`.
+
+Then it can escalate only as needed:
+
+- `read_file` with `mode: "range"`, `offset`, and `limit` for exact sections.
+- `read_file` with `mode: "full"` only when focused context is not enough.
+
+The built-in system prompt tells Kward to follow that escalation path, so these tools are part of normal agent behavior rather than hidden manual features.
+
+## Focused task context
+
+`context_for_task` is the highest-level context-budgeting tool. Give it a task and, optionally, focused paths and a byte budget. It returns a compact text bundle with:
+
+- ranked candidate files (by term-matching score),
+- source outlines for each file,
+- matching excerpts around task terms (2 lines of context),
+- a header with the task, budget, and search terms used.
+
+Tool arguments:
+
+```json
+{
+  "task": "debug token validation failure",
+  "paths": ["lib"],
+  "budget": 4000
+}
+```
+
+- `task` is required.
+- `paths` is optional; defaults to the workspace root. Each entry is a file or directory.
+- `budget` is optional; defaults to 4,000 bytes, max 20,000.
+
+Limits: at most 8 ranked files are returned, with up to 8 matching excerpts per file. Up to 64 files are scanned. Skipped directories include `.git`, `node_modules`, `vendor`, `tmp`, `log`, `coverage`, `dist`, `build`, `.bundle`, `.yardoc`, and `_yardoc`. Only files with known extensions (`.rb`, `.js`, `.ts`, `.py`, `.go`, `.rs`, `.java`, `.cs`, `.md`, `.yml`, `.json`, etc.) plus `Gemfile` are considered.
+
+This is useful when Kward needs orientation before choosing exact files or line ranges. It is intentionally lightweight: no daemon, no database, no persistent graph, and no semantic/vector index.
+
+## Budgeted file reads
+
+`read_file` supports explicit context modes:
+
+| Mode | Use it when |
+| --- | --- |
+| `outline` | You need a source declaration outline (classes, modules, methods, functions) with line numbers before reading code. Capped at 80 entries. |
+| `preview` | You want a short first look. Defaults to 120 lines when no `limit` is given. Respects `offset` and `limit` if provided. |
+| `range` | You know the relevant line range. Uses `offset` and `limit` to read a specific section. |
+| `full` | You need the full file content up to Kward's read caps. Functionally identical to `range` but signals full-read intent. |
+
+`range` and `full` behave the same: both read a bounded slice using `offset`, `limit`, and `max_bytes`. The difference is semantic — use `full` when you want everything up to the cap, use `range` when you are targeting a section.
+
+`read_file` also accepts `max_bytes`, which lets Kward request a smaller per-call byte budget. This can only reduce the output below the workspace default (50 KB); it cannot increase it.
+
+Large source files still get special handling when read without a mode: Kward returns an outline plus the first 120 lines instead of blindly flooding context. See [Workspace tools](workspace-tools.md) for the full `read_file` argument reference and read limits.
+
+## Source outlines
+
+`summarize_file_structure` and `read_file` with `mode: "outline"` return compact source outlines. These include recognizable declarations, declaration kind, indentation, and approximate line ranges.
+
+The outline recognizer is deliberately simple. It uses lightweight patterns for common Ruby, JavaScript/TypeScript, Go, Rust, Java, and C#-style declarations. It is not a compiler or LSP replacement, but it is fast and dependency-free. See [Workspace tools](workspace-tools.md) for argument details.
+
+## Output compaction
+
+Kward also saves tokens after tools run.
+
+When a tool output is large enough, Kward compacts it before sending it back into model context. The original output is kept in the session record and can be reopened with `retrieve_tool_output`, including after resuming a saved session that contains the original tool execution record.
+
+The compactor preserves:
+
+- the first 40 lines,
+- the last 40 lines,
+- error, failure, test, search-result, URL, and heading context,
+- separate STDOUT/STDERR sections for shell commands.
+
+This is especially useful for commands like test runs, linters, package installs, and large fetches. The model sees the useful parts first, but the full output is not lost. See [Agent tools](agent-tools.md) for the full compaction strategy and artifact retrieval details.
+
+## Duplicate output reuse
+
+If the same tool output appears again, Kward does not repeat it in model context. Instead, it inserts a short reference to the already-stored artifact.
+
+That helps when commands or searches are retried and return the same large result.
+
+## Session compaction
+
+Kward also supports conversation/session compaction. This is separate from tool-output compaction: instead of trimming one tool result, it summarizes older conversation state so a long session can continue with less context pressure.
+
+Session compaction keeps the working conversation manageable while preserving the session history on disk. Run `/compact` manually, or enable auto-compaction in config — see [Session management](session-management.md) and [Configuration](configuration.md).
+
+## Measuring savings
+
+Use `context_budget_stats` to see approximate savings for the current active conversation since it was opened in this process. These runtime stats are not reconstructed when a saved session is resumed.
+
+It reports:
+
+- tool calls counted,
+- original bytes,
+- model-facing returned bytes,
+- saved bytes,
+- estimated tokens saved,
+- per-tool breakdown with `calls`, `savedBytes`, `returnedBytes`, and `originalBytes` for each tool.
+
+The token estimate is intentionally rough, using about four bytes per token. It is meant to show whether context budgeting is helping, not to match provider billing exactly. See [Workspace tools](workspace-tools.md) for the tool reference.
+
+## Practical example
+
+A good debugging flow looks like this:
+
+```text
+User: Debug why auth token validation fails.
+Kward: context_for_task(task: "debug auth token validation", paths: ["lib", "test"], budget: 5000)
+Kward: read_file(path: "lib/auth.rb", mode: "range", offset: 40, limit: 80)
+Kward: run_shell_command(command: "ruby -Itest test/test_auth.rb")
+Kward: retrieve_tool_output(...) only if the compacted test output omitted something important.
+```
+
+That gives the model enough evidence to work without reading the whole repository or stuffing every command byte into the next request.

data/doc/context-tools.md

@@ -0,0 +1,83 @@
+# Context tools
+
+Context tools help Kward load reusable instructions, recover compacted tool output, and ask structured clarification questions. These tools usually run in the background as part of a turn rather than as commands you type directly.
+
+## `read_skill`
+
+`read_skill` loads configured skill instructions when a task matches a known skill.
+
+Arguments:
+
+- `name`: skill name.
+- `path`: optional path inside the skill, default `SKILL.md`.
+
+Skill file paths must be relative and stay inside the skill folder. Absolute paths and path traversal are rejected. Files larger than 100 KB are also rejected.
+
+Skills are reusable instruction bundles stored in the Kward config directory. Kward advertises available skills by name and description, then reads the full skill only when it becomes relevant. That saves tokens because every skill does not need to be injected into every request.
+
+Typical uses:
+
+- loading test-writing guidance before changing tests,
+- loading security guidance before editing auth, secrets, cookies, uploads, or personal data handling,
+- loading language-specific style guidance before refactoring code.
+
+See [Extensibility](extensibility.md) for how skills fit with prompts, personas, and project instructions.
+
+## `retrieve_tool_output`
+
+`retrieve_tool_output` reopens original output that was compacted out of the model-facing context.
+
+Arguments:
+
+- `id`: tool output artifact id, such as `toolout_abc123`.
+- `offset`: optional 1-indexed line offset.
+- `limit`: optional maximum lines to return, default 120.
+- `query`: optional case-insensitive text search within the original output.
+
+Kward may compact large shell, search, fetch, or file outputs before sending them back to the model. The compacted result includes enough summary to continue, plus an artifact id when the original output is worth preserving. If later work needs details, Kward can retrieve a focused slice of the original output instead of asking the tool to repeat the whole operation, including after resuming a saved session that contains the original tool execution record.
+
+This saves tokens in two ways:
+
+- repeated large outputs are not resent to the model,
+- follow-up reads can target only matching lines or a bounded line range.
+
+When a `query` is provided, matching lines are returned with 1-indexed line numbers prefixed. The result includes a header with the artifact id, query, and line range. When there are more results than the limit, a continuation notice with the next `offset` is included.
+
+For details on how tool outputs are compacted and when artifacts are created, see [Agent tools](agent-tools.md).
+
+## `ask_user_question`
+
+`ask_user_question` asks one to four structured clarification questions through an interactive frontend.
+
+Arguments:
+
+- `questions`: array of one to four questions.
+- each question has:
+  - `header`: short label shown in the overlay,
+  - `question`: the question text,
+  - `options`: two to four selectable answers with `label` and `description`.
+
+Constraints:
+
+- `multiSelect` is unsupported; questions are single-select.
+- `preview` on options is unsupported.
+- Each option requires both `label` and `description`.
+- In terminal use, the picker also accepts custom typed answers beyond the provided options, so the user is not limited to the listed choices.
+
+This tool is advertised only when the active frontend supports structured questions. In terminal use, it lets Kward ask concise multiple-choice questions instead of guessing requirements. In RPC clients, the same question flow is bridged through UI events — see the [RPC question bridge](rpc.md) for notification and response details.
+
+Good uses:
+
+- choosing between safe implementation approaches,
+- confirming an ambiguous scope,
+- selecting a provider, model, or behavior when no default is obvious.
+
+Kward should not use this tool for every small uncertainty. It is best when an answer materially changes the implementation or avoids a risky assumption.
+
+## Availability
+
+`Kward::ToolRegistry` only advertises context tools when they are usable:
+
+- `read_skill` requires configured skills,
+- `ask_user_question` requires frontend support,
+- `retrieve_tool_output` is available in normal sessions so compacted artifacts can be inspected later.