kward 0.71.0 → 0.73.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c53686afdfbf5de822759d70cb696e911cae8c5ffc7b5ce63e07306dc4ffaac
-  data.tar.gz: '086c43642ad0149e3986277b7424b55f2dc50689a0e876c72e6bb9fd48e4272b'
+  metadata.gz: b3b7a272f3d5171660fc2669a486830e334910cfef50af203b1eeedb989b6289
+  data.tar.gz: 3fb9b4ede65361609b6a1c594431d20136bb83c57e205e4b1b32332db75b2fbb
 SHA512:
-  metadata.gz: 97ebbbf26feedc4dd46d53d7af8b900670edf861cb40f6103eff5ea8579d605517cab49751ea5fe46c4023fa7ba8ced367d31290b34af463fd0cc8f1a9a1087e
-  data.tar.gz: 424ac657d7efc70f2b87924914112c0910937deee7e4ec6521448ff4fe51967a58203de9693fb8989adea63fb23adef93668333c8bb5eb22963bff49e7420875
+  metadata.gz: 9dec61bbf302b69eb5501a130c29d8104b342266cac1489f53608051db1cb03fb44a5b3d47388f43e2f271673f1ba2b4744637dc108701d13a37abd322913657
+  data.tar.gz: 5d057f370c989e973b2cd2bbef8464932251f7b2ffcddcfff6c86d3ecb28db4c5a1241e3eda1f5fa3b7f460cddbd7938dde6396e3335d6bbe9fb1b131d81f9a4

data/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Check syntax
+        run: find lib test -name '*.rb' -print0 | xargs -0 ruby -c
+
+      - name: Run tests
+        run: bundle exec rake test

data/CHANGELOG.md

@@ -4,6 +4,99 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.73.0] - 2026-06-29
+
+### Added
+
+- Added persistent session-backed worker queue job metadata as the first step toward tab-based worker queues.
+- Added experimental `/queue add` and `/queue list` commands for enqueueing the current tab session into the worker queue.
+- Added a first session-backed worker queue runner that executes one queued job and marks it ready for review after committing changes.
+- Added clean-workspace blocking for queued workers so jobs do not start on top of existing local changes.
+- Added `/queue run` to manually drain queued tab worker jobs sequentially until the queue is empty or a job needs attention.
+- Added worker git stash helpers as groundwork for cooperative queue suspension.
+- Added explicit queue runner suspend/resume primitives that stash and restore a running job's workspace changes.
+- Added `/queue suspend <id>` and `/queue resume <id>` commands for manually parking and resuming queued worker jobs.
+- Added `/queue open <id>` to open a queued worker's session for review or follow-up.
+- Added `/diff` to open the chronological file changes recorded in the current session in the integrated diff viewer.
+- Added `/scratchpad [text|markdown|ruby]` for opening unsaved editor buffers, including Vibe `:w filename` save-as support and Ruby `:run`/Modern `Ctrl+R` output written after `__END__`.
+- Added `/pty <command>` and the `ekwsh` `pty <command>` built-in for explicit interactive PTY passthrough sessions, enabling terminal-owned tools such as pagers to run from Kward.
+- Added minimal PTY execution for external `ekwsh` commands so terminal-aware tools can detect a TTY and terminal width.
+- Added Ctrl+C cancellation for running `ekwsh` commands and preserved tab-switch actions while shell commands are active.
+- Added quoted path completion and cached `$PATH` executable completion for `ekwsh`.
+- Added streaming `ekwsh` command output in the TUI transcript while commands run.
+- Added separate workspace-scoped `ekwsh` command history so embedded shell input no longer shares normal prompt history.
+- Added structured RPC `runtime/updateSetting` `defaultModel` values so clients can send provider and model separately while keeping the existing string format.
+
+### Changed
+
+- Changed PTY-backed `ekwsh` commands to refresh terminal window size while running so long-lived commands can adapt to resizes.
+- Changed `ekwsh` to default `GIT_PAGER` to `cat`, while preserving user-provided values, so Git commands do not unexpectedly enter an interactive pager under PTY execution.
+- Improved `ekwsh` POSIX-oriented built-ins, including `exit [status]`, stricter `cd`/`pwd`, `export NAME`, assignment persistence, `unalias`, and shared alias-name validation.
+- Changed `ekwsh` configuration to prefer a POSIX `/bin/sh` default shell and validate runtime settings for command timeout, output cap, and shell history size.
+
+### Fixed
+
+- Normalized ordinary PTY line endings in `ekwsh` command output so transcripts avoid stray carriage returns.
+- Added `ekwsh` timeout and output-limit enforcement for external commands using the shared local command runner.
+- Consolidated workspace shell command execution on a shared local command runner with timeout, cancellation, bounded capture, and optional streaming support.
+- Fixed `ekwsh` shell output sanitization so unsafe terminal controls are stripped before command output is shown while SGR color is preserved.
+- Split Vibe editor insert/readline key handling into a focused mixin without changing editor behavior.
+- Consolidated compaction message-field reads through the shared message access helper.
+- Consolidated RPC transcript tool metadata normalization with tool event metadata so tool names, args, diffs, and changed files stay aligned.
+- Fixed RPC tool capabilities so `changedFiles` is advertised when emitted in tool results.
+- Removed a stale `count-tests` CLI branch that could crash instead of treating the input as a prompt.
+- Fixed tab failures and cancellations so red tab states always emit a runtime message explaining what happened.
+- Fixed model and reasoning changes from CLI/RPC settings so active session runtime metadata is persisted before the next turn.
+- Fixed `context_for_task` so candidate files with no task matches return a clear no-match message instead of only a header.
+- Fixed workspace file tools so expected filesystem permission and path-type errors are returned as tool errors instead of aborting a turn.
+- Fixed composer `Ctrl+C` so it no longer exits the app when no process is running.
+- Fixed the Git diff viewer so `Ctrl+C` and terminal-forwarded `Cmd+C` copy selected text.
+- Fixed pasted or dropped shell-escaped image paths so the composer hides the path text after adding the image badge.
+- Fixed `read_skill` tool transcript rendering so skill frontmatter starts on the line after the tool label.
+- Fixed built-in editor soft-wrap vertical movement so moving up or down preserves the visual column across wrapped visual rows and logical line boundaries.
+
+## [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
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.71.0)
+    kward (0.73.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.73.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`, `pty`, 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.