kward 0.71.0 → 0.72.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c53686afdfbf5de822759d70cb696e911cae8c5ffc7b5ce63e07306dc4ffaac
-  data.tar.gz: '086c43642ad0149e3986277b7424b55f2dc50689a0e876c72e6bb9fd48e4272b'
+  metadata.gz: 32f9966cff49fb90d0c11f20277e77186fe439ede174a3d151a2a3dfdcddc726
+  data.tar.gz: ebcdfd83477ce0e90857019a67f8bfdf57f2f2e9cb4e7accdd89b790d6002b5c
 SHA512:
-  metadata.gz: 97ebbbf26feedc4dd46d53d7af8b900670edf861cb40f6103eff5ea8579d605517cab49751ea5fe46c4023fa7ba8ced367d31290b34af463fd0cc8f1a9a1087e
-  data.tar.gz: 424ac657d7efc70f2b87924914112c0910937deee7e4ec6521448ff4fe51967a58203de9693fb8989adea63fb23adef93668333c8bb5eb22963bff49e7420875
+  metadata.gz: 9c625a36cf64cb7348f1ff14a07bd27e6b311bcd2d5b219669885d105118977143f17d1321d0acfefddc81469c0a11311868b8e8905d2d5a68339065dddf0513
+  data.tar.gz: 7de5e8b2887d654d57bd2032fa86b4fad7b3c0859d74d323e4d9f44cd682b7f7b616a11858e5e20bb4f2cc5a829d3746f94576fb114a35504581a45a66adbb16

data/CHANGELOG.md

@@ -2,7 +2,47 @@
 
 All notable changes to Kward will be documented in this file.
 
-## [Unreleased]
+## [0.72.0] - 2026-06-28
+
+### Added
+
+- Added a built-in editor that can be opened from the TUI with `$` or directly from the CLI with `kward edit <filename>`, with modern, Emacs-style, and Vibe editing modes.
+- Added richer editor workflows including syntax highlighting, undo/redo, auto-indent, soft wrap, mouse support, multi-cursor editing, relative line numbers, and an expanded Vim-like Vibe mode with visual selections, text objects, registers, marks, macros, substitution, and Ruby navigation.
+- Added `/shell`, an embedded Kward shell (`ekwsh`) for running workspace commands without leaving the TUI, including command/path completion, safe color output, optional global `ekwsh.yml` configuration, and rbenv shim autodetection.
+- Added `/files`, a searchable project file browser that can open files in the editor and remembers cursor and folder expansion state per workspace.
+- Added persistent TUI tabs for session-backed conversations, plus tab commands, shortcuts, status colors, and restoration across restarts.
+- Added `/git` workflows for reviewing changes, viewing diffs, staging or unstaging files, and writing commit messages from inside the TUI.
+- Added TUI composer improvements including `@` file mentions, persistent workspace prompt history with Ctrl+R search, and Tab/Shift+Tab reasoning-effort cycling.
+- Added CLI execution modes via `--mode auto|chat|oneshot|filter` and `--filter` for transforming piped input.
+- Added context-budgeting tools and workflows, including `read_file` modes, richer source outlines, `context_for_task`, `context_budget_stats`, and restored compacted tool-output inspection.
+- Added interactive plugin commands backed by a Kward-driven canvas render loop.
+- Added experimental agent-worker support behind the existing experimental workflow.
+- Added new and expanded guides for editor usage, tabs, project files, Git workflows, agent tools, context budgeting, workspace tools, web search, code search, plugins, RPC, authentication, memory, sessions, troubleshooting, and releasing.
+
+### Changed
+
+- Changed the built-in editor to use the modern editing mode by default, with smarter indentation and improved keyboard handling across terminal encodings.
+- Improved TUI interaction polish across pickers, tabs, editor rendering, Git workflows, composer refresh behavior, mouse handling, and modal input isolation.
+- Improved embedded shell environment handling so Kward-managed environment values are preserved while workspace shell conveniences still work.
+- Improved RPC and session internals around steering events, session cleanup, worker metadata, session-tree traversal, and config updates.
+- Improved tool-output context budgeting so agents start with focused context, preserve inspectable originals, and report active-conversation savings more accurately.
+- Expanded documentation and generated-doc navigation to better reflect current workflows and configuration options.
+
+### Fixed
+
+- Fixed embedded-shell completion, environment preservation, and rbenv handling issues.
+- Fixed editor and TUI input edge cases involving shifted keys, CSI-u encodings, Command/Ctrl shortcuts, selection preservation, mouse scrolling, tab switching, modal questions, and commit-message editing.
+- Fixed many built-in editor behaviors around selection rendering, cursor movement, soft wrap, indentation, deletion/change operations, undo/search behavior, macro recording, registers, text objects, visual mode, and viewport positioning.
+- Fixed Git overlay staging and commit-message behavior.
+- Fixed session, tab, and worker state issues including tab restoration, session cleanup, worker handoff, foreground write locks, and plugin/test isolation.
+- Fixed RPC steering, tool-output restoration, context-budget statistics, and session-manager lifecycle behavior.
+- Fixed documentation rendering, navigation, tables, quote styling, and generated guide layout issues.
+- Fixed persona time-of-day handling to use the current local time.
+
+### Removed
+
+- Removed the placeholder message from `/status` output.
+- Removed unused RPC session helpers and temporarily hid worker labels behind the experimental worker flow.
 
 ## [0.71.0] - 2026-06-21
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.71.0)
+    kward (0.72.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -146,7 +146,7 @@ CHECKSUMS
   html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
   io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
   json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  kward (0.71.0)
+  kward (0.72.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/README.md

@@ -78,6 +78,9 @@ Start here:
 Feature guides:
 
 - [Sessions](doc/session-management.md): resume, clone, fork, rewind, compact, and navigate saved work.
+- [Integrated Editor](doc/editor.md): open files from the composer, edit in-place, and choose editor keybindings.
+- [Git](doc/git.md): review changes, use the diff viewer, stage files, and commit from the interactive TUI.
+- [Shell](doc/shell.md): use `/shell`, the embedded Kward shell with aliases, completion, and per-tab state.
 - [Memory](doc/memory.md): opt-in core, soft, and session memory.
 - [Personas](doc/personas.md): configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
 
@@ -89,6 +92,7 @@ Advanced:
 - [Releasing](doc/releasing.md): release checklist for RubyGems publishing.
 - [Agent tools](doc/agent-tools.md): overview of model-callable tools, token-saving behavior, and tool categories.
 - [Workspace tools](doc/workspace-tools.md): local file, edit, and shell command tools.
+- [Context budgeting](doc/context-budgeting.md): focused context gathering, budgeted reads, output compaction, and token-saving history.
 - [Web search](doc/web-search.md): live search providers and network behavior for the web search agent tool.
 - [Code search](doc/code-search.md): package lookup, GitHub repository cache, and external source reading for the code search agent tool.
 - [Context tools](doc/context-tools.md): skills, compacted output retrieval, and structured clarification questions.

data/doc/agent-tools.md

@@ -6,8 +6,9 @@ Tools are part of Kward's safety and context-management boundary:
 
 - schemas describe what the model is allowed to call,
 - Ruby tool objects validate and execute those calls,
-- workspace tools stay inside the active workspace by default,
+- workspace tools stay inside the active workspace by default (see [Configuration](configuration.md) for the guardrail setting),
 - file-changing tools require the file to be read first,
+- mutation tools (`edit_file`, `write_file`, `run_shell_command`) are gated by a write lock when agent workers are active, so only one worker can change the workspace at a time,
 - large outputs are bounded or compacted before they enter model context,
 - full tool outputs are kept in the session record for later inspection.
 
@@ -15,22 +16,26 @@ Tools are part of Kward's safety and context-management boundary:
 
 | Category | Tools | Guide |
 | --- | --- | --- |
-| Workspace tools | `list_directory`, `read_file`, `summarize_file_structure`, `write_file`, `edit_file`, `run_shell_command` | [Workspace tools](workspace-tools.md) |
+| Workspace tools | `list_directory`, `read_file`, `context_for_task`, `context_budget_stats`, `summarize_file_structure`, `write_file`, `edit_file`, `run_shell_command` | [Workspace tools](workspace-tools.md) |
 | Web tools | `web_search`, `fetch_content`, `fetch_raw` | [Web search](web-search.md) |
 | Code search | `code_search` | [Code search](code-search.md) |
 | Context and interaction tools | `read_skill`, `retrieve_tool_output`, `ask_user_question` | [Context tools](context-tools.md) |
 
 ## How tools save tokens
 
-Kward tries to keep tool context useful without flooding the model:
+Kward tries to keep tool context useful without flooding the model. The built-in prompt tells Kward to start with focused context tools and escalate from outlines/previews to exact ranges before full-file reads:
 
-- `read_file` reads bounded line ranges and supports continuation with `offset` and `limit`.
+- `read_file` reads bounded line ranges, supports continuation with `offset` and `limit`, and accepts explicit `preview`, `outline`, `range`, and `full` modes with optional per-call byte budgets.
+- `context_for_task` builds a task-shaped bundle from ranked files, outlines, and matching excerpts within a caller-supplied byte budget.
+- `context_budget_stats` reports approximate active-conversation bytes and estimated tokens saved by compaction and duplicate output replacement.
 - `summarize_file_structure` returns a compact outline for large source files before reading all code.
 - Search, fetch, and shell outputs are capped or compacted before model ingestion.
 - Repeated identical tool output is replaced with a short reference instead of being sent again.
-- Compacted outputs are stored as artifacts that can be reopened with `retrieve_tool_output`.
+- Compacted outputs are stored as artifacts that can be reopened with `retrieve_tool_output`, including after resuming a saved session that contains the original tool execution record.
 
-This lets the assistant reason from focused evidence while preserving access to original outputs when needed.
+When a tool output exceeds 12 KB, Kward compacts it before sending it to the model. The compactor preserves the first 40 and last 40 lines, keeps lines matching error, test, or search-result patterns with 2 lines of surrounding context, and replaces omitted sections with `[... omitted lines ...]` markers. Shell command output is section-aware: STDOUT and STDERR sections are compacted separately. Compacted outputs include a header with the original and compacted byte counts and the artifact ID for retrieval. Error outputs under 8 KB are left intact so failure details stay visible.
+
+This lets the assistant reason from focused evidence while preserving access to original outputs when needed. For a fuller overview of Kward's context budgeting and token-saving work, see [Context budgeting](context-budgeting.md).
 
 ## How tools are exposed
 
@@ -40,4 +45,8 @@ This lets the assistant reason from focused evidence while preserving access to
 - `read_skill` is advertised only when skills are available,
 - `ask_user_question` is advertised only when the frontend can display structured questions.
 
+When agent workers are active, the registry can scope each worker to a subset of tools via an allowed-tool-names filter, so workers only see the tools they need.
+
+When `write_file` or `edit_file` changes an `AGENTS.md` file in the workspace root, Kward automatically rebuilds the system message so the model picks up the new instructions without a restart.
+
 Unknown tool calls are recorded as tool results instead of crashing the session, so the model can recover and choose an advertised tool on the next turn.

data/doc/authentication.md

@@ -12,6 +12,8 @@ Or inside interactive Kward:
 /login
 ```
 
+`/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
@@ -56,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
@@ -151,10 +161,21 @@ The model picker is the normal way to switch between configured providers and mo
 
 For one-off shell runs, `KWARD_PROVIDER` and provider-specific model environment variables remain available. See [Configuration](configuration.md) for the full list.
 
+## Custom auth file locations
+
+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`)
+
+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
 
 - Auth files are written with file mode `0600` when possible.
 - 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:
 
@@ -162,6 +186,85 @@ The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:
 
 This only hides the hint text; Ctrl+C still stops the current running response.
 
+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.
+
+`tab_keybindings` controls how the composer handles tab navigation shortcuts:
+
+```json
+{
+  "composer": {
+    "tab_keybindings": "auto"
+  }
+}
+```
+
+`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
 
 Interactive CLI and RPC clients start fresh by default. To automatically resume the last active session for the current workspace:

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

@@ -11,6 +11,8 @@ 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:
@@ -32,13 +34,17 @@ Arguments:
 - `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.
+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.
@@ -49,9 +55,16 @@ Arguments:
 - each question has:
   - `header`: short label shown in the overlay,
   - `question`: the question text,
-  - `options`: two to four selectable answers with labels and descriptions.
+  - `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.
+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: