kward 0.78.0 → 0.80.0

data/doc/authentication.md

@@ -1,181 +1,150 @@
 # Authentication
 
-Kward needs access to a model provider before it can answer prompts. The fastest path is:
+Kward can keep credentials for several model providers at once. First connect an account or API key, then use `/model` to choose the provider and model for your work. See [Model providers](providers.md) to compare providers and find their configuration names and environment variables.
 
-```bash
-kward login
-```
-
-Or inside interactive Kward:
+The easiest setup is inside interactive Kward:
 
 ```text
 /login
 ```
 
-`/login` opens a provider picker; `kward login` accepts the provider as an argument.
+Choose **API key** or **Subscription / OAuth**, then choose a provider. After login, open:
 
-Use the provider you already have access to. You can change the active model later with `/model`.
-
-## Choose a provider
-
-| Provider | Use it when... |
-| --- | --- |
-| OpenAI/ChatGPT | You want the default Codex backend with a ChatGPT account. |
-| Anthropic | You have Claude Pro/Max and want to use Claude through Kward. |
-| OpenRouter | You want to use an OpenRouter API key and choose from its model catalog. |
-| Copilot | You want to try experimental Copilot provider support. |
+```text
+/model
+```
 
-If you are unsure, start with `kward login` and choose OpenAI.
+## Supported authentication
 
-## Login commands
+| Provider | API key | Subscription / OAuth |
+| --- | --- | --- |
+| OpenAI | Yes, direct OpenAI API | Yes, ChatGPT/Codex |
+| Anthropic | Yes, direct Anthropic API | Yes, Claude Pro/Max |
+| Azure OpenAI | Yes; endpoint, deployment, and API version are also required | No |
+| Google Gemini | Yes | No |
+| Cerebras, DeepSeek, Fireworks AI, Groq, Mistral, NVIDIA NIM, Together AI | Yes | No |
+| OpenRouter | Yes | Not yet in Kward |
+| xAI | Yes | No supported third-party flow |
+| GitHub Copilot | No API-key mode | Yes |
 
-```bash
-kward login              # OpenAI/ChatGPT OAuth
-kward login anthropic    # Anthropic Claude Pro/Max OAuth
-kward login openrouter   # OpenRouter API key
-kward login github       # GitHub OAuth for experimental Copilot support
-```
+Direct OpenAI API credentials and ChatGPT/Codex OAuth are independent. You can keep both and switch between **OpenAI** and **Codex** in `/model`.
 
-## OpenAI / ChatGPT
+## API-key workflow
 
-```bash
-kward login
-```
-
-This opens a browser login and saves credentials to:
+From `/login`, choose **API key** and the provider. Kward validates providers with live model discovery before saving the key, then stores it in:
 
 ```text
-~/.kward/auth.json
+~/.kward/api_keys.json
 ```
 
-Kward uses the ChatGPT/Codex backend, not the OpenAI Platform API key flow.
+The file is private (`0600` when supported). It is separate from `config.json`, so normal config reads and RPC responses do not return keys.
 
-If Kward asks for an OAuth client ID, add it to `~/.kward/config.json`:
+For providers that do not also offer subscription login, the shell command is convenient:
 
-```json
-{
-  "openai_oauth_client_id": "your-client-id"
-}
+```bash
+kward login groq
+kward login gemini
+kward login openrouter
+kward login azure_openai
 ```
 
-Kward ships with a built-in client ID, so this is only needed if login fails or you want to use your own.
+Use the interactive `/login` method picker for direct OpenAI or Anthropic API keys because `kward login openai` and `kward login anthropic` retain their subscription-login behavior.
 
-For a single shell session without OAuth, you can set an access token directly:
+Environment variables override a stored key for that provider:
 
 ```bash
-OPENAI_ACCESS_TOKEN=... kward
+OPENAI_API_KEY=... kward
+GEMINI_API_KEY=... kward
+GROQ_API_KEY=... kward
 ```
 
-## Anthropic Claude Pro/Max
+Other supported variables are listed in [Configuration](configuration.md#Environment_overrides).
 
-```bash
-kward login anthropic
-```
+### Azure OpenAI
 
-This saves credentials to:
+Azure setup asks for three non-secret values after the key:
 
-```text
-~/.kward/anthropic_auth.json
-```
+- an HTTPS endpoint, such as `https://example.openai.azure.com`;
+- a deployment name;
+- an API version, such as `2025-04-01-preview`.
 
-Use this when you want Kward to use your Claude Pro/Max subscription. Kward refreshes the access token when a refresh token is available.
+Kward rejects endpoint credentials, query strings, fragments, and unsafe deployment/version characters. The deployment is the model shown in `/model`; Kward does not claim to discover Azure deployments from an inference key.
 
-## OpenRouter
+## ChatGPT / Codex OAuth
 
 ```bash
-kward login openrouter
+kward login
 ```
 
-This stores your API key in `~/.kward/config.json`.
+Credentials are saved to `~/.kward/auth.json`. This uses the ChatGPT/Codex backend, not `OPENAI_API_KEY` or the public OpenAI API endpoint.
 
-For a single shell session, you can avoid saving the key:
+For one shell session, you can provide the Codex access token directly:
 
 ```bash
-OPENROUTER_API_KEY=sk-or-v1-... kward
+OPENAI_ACCESS_TOKEN=... 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
+`OPENAI_ACCESS_TOKEN` continues to mean Codex OAuth. `OPENAI_API_KEY` means direct OpenAI API access; neither replaces the other.
 
-Kward's `/model` picker can show OpenRouter models that are available to your API key. Refresh the local cache after logging in:
+## Anthropic Claude Pro/Max
 
 ```bash
-kward openrouter refresh
-```
-
-This fetches text-capable OpenRouter models for the configured key and writes them to:
-
-```text
-~/.kward/cache/openrouter_models.json
+kward login anthropic
 ```
 
-If `KWARD_CONFIG_PATH` points at a custom config file, the cache is written beside that config file under `cache/openrouter_models.json`.
+OAuth credentials are saved to `~/.kward/anthropic_auth.json`. Kward refreshes the access token when a refresh token is available. Choose **API key** in `/login` instead when you want direct Anthropic API billing.
 
-Inspect the cached model ids with:
+## GitHub Copilot
 
 ```bash
-kward openrouter list
+kward login github
 ```
 
-Use this when:
+Credentials are saved to `~/.kward/github_auth.json`. For one run, use `COPILOT_GITHUB_TOKEN`. General `GH_TOKEN` and `GITHUB_TOKEN` values are not treated as Copilot credentials.
 
-- 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`.
+## OpenRouter
 
-## Experimental Copilot support
+API-key login is supported, including model refresh:
 
 ```bash
-kward login github
+kward login openrouter
+kward openrouter refresh
+kward openrouter list
 ```
 
-This saves GitHub OAuth credentials to:
+The cache lives at `<config-dir>/cache/openrouter_models.json`. `/model` can also refresh the active provider directly.
 
-```text
-~/.kward/github_auth.json
-```
+OpenRouter documents an official [OAuth PKCE flow](https://openrouter.ai/docs/guides/overview/auth/oauth), but Kward does not implement that flow yet. It remains unavailable in CLI and RPC capabilities rather than exposing an unverified partial login.
 
-You can also use a token for one run:
+xAI's public inference documentation currently directs clients to API keys (see the [xAI quickstart](https://docs.x.ai/developers/quickstart)); Kward does not expose an xAI subscription OAuth flow.
 
-```bash
-COPILOT_GITHUB_TOKEN=... kward
-```
+## Model selection
 
-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.
+The provider-aware `/model` picker offers:
 
-## Choose the active model
+- **Refresh model list**;
+- **Enter model ID manually**;
+- **Show all models**;
+- **Change provider**.
 
-Authentication makes providers available. The active model is selected separately.
+By default, Kward hides entries when provider metadata proves they are not generation/tool models. It keeps entries whose metadata is incomplete. **Show all models** and manual IDs remain available for previews, private deployments, and incomplete catalogs.
 
-Inside Kward, use:
+## Status and logout
 
-```text
-/model
+```bash
+kward auth status
+kward auth logout
 ```
 
-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.
-
-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/`.
+Status reports only whether credentials exist and where they came from; it never prints credential values. CLI logout removes all saved OAuth and API-key credentials. Environment variables remain active until you unset them.
 
-- `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`)
+RPC clients can list catalog providers, inspect sanitized method availability, save/remove individual API keys, and remove a specific provider/auth method. See [RPC](rpc.md#Config_and_auth_methods).
 
-When `KWARD_CONFIG_PATH` points at a custom config file, the OpenRouter API key is stored in that file instead of `~/.kward/config.json`.
+## Custom locations
 
-## Security notes
+- `KWARD_CONFIG_PATH` moves `config.json`, `api_keys.json`, caches, and most other Kward state to that file's directory.
+- `KWARD_AUTH_PATH` overrides ChatGPT/Codex OAuth storage.
+- `KWARD_ANTHROPIC_AUTH_PATH` overrides Anthropic OAuth storage.
+- `KWARD_GITHUB_AUTH_PATH` overrides GitHub Copilot OAuth storage.
 
-- 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 **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.
+Never commit credential files. For temporary credentials, prefer environment variables and unset them when finished.

data/doc/code-search.md

@@ -29,7 +29,7 @@ The `code_search` tool can:
 4. search cached files,
 5. read bounded line ranges from cached files.
 
-Kward should use this when the best answer depends on how another project actually implemented something.
+Kward uses code search when the best answer depends on how another project actually implemented something.
 
 ## Supported ecosystems
 

data/doc/composer.md

@@ -99,7 +99,7 @@ The `$` token must begin at the first character of the composer. Use Up/Down to
 
 A successful `$path` open is saved in prompt history using the resolved workspace-relative path. It opens the editor instead of sending a model prompt.
 
-See [Integrated Editor](editor.md) for editing modes, save and quit keys, scratchpads, and conflict handling.
+See [Integrated editor](editor.md) for editing modes, save and quit keys, scratchpads, and conflict handling.
 
 ## Reuse prompt history
 

data/doc/configuration.md

@@ -6,7 +6,9 @@ On first start, Kward creates the file when it does not exist. The starter confi
 
 If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as the config directory for prompts, skills, memory, logs, and caches.
 
-## Common changes
+## Choose a configuration path
+
+Use the interactive controls for ordinary changes. Edit `config.json` when you need a setting that is not exposed there or when you want to share a reproducible setup.
 
 | Goal | Recommended path |
 | --- | --- |
@@ -15,10 +17,13 @@ If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as
 | Change editor, diff, overlay, or session UI behavior | `/settings` → Interface |
 | Enable memory | `/settings` → Memory |
 | Configure web search or trust project skills | `/settings` → Tools & Search |
+| Contain model-requested shell commands | `/sandbox` for mode and child-network access; edit config for additional writable roots |
 | Tune compaction | `/settings` → Context & Compaction |
 | Configure personas | `/settings` → Personalization; see [Personas](personas.md) |
 | Add MCP servers, lifecycle hooks, or environment-specific paths | Edit `config.json` directly |
 
+For the complete reference, jump to [provider and model settings](#Provider_and_model_settings), [terminal interface settings](#Overlay_settings), [sessions and memory](#Session_settings), [web search](#Web_search), [workspace safety](#Tool_workspace_guardrails), or [logging](#Logging_and_stats). See [Model providers](providers.md) to compare providers and find their configuration names.
+
 Here is a minimal direct provider configuration:
 
 ```json
@@ -45,6 +50,35 @@ Add trusted local Model Context Protocol servers under `mcpServers`:
 
 See [MCP servers](mcp.md) for setup, supported fields, and security notes.
 
+### Transport plugins
+
+Transport plugin settings live under `transports` and are scoped by the
+transport's stable ID:
+
+```json
+{
+  "transports": {
+    "com.kward.telegram": {
+      "workspace": "/Users/me/src/project",
+      "allowed_user_ids": [123456789],
+      "allowed_chat_ids": [123456789],
+      "poll_timeout_seconds": 25
+    }
+  }
+}
+```
+
+Transport plugins are trusted local Ruby code. Keep credentials in environment
+variables or another private secret mechanism provided by the plugin rather
+than committing them to `config.json`. Transport state, including external
+conversation bindings and idempotency keys, is stored privately under the
+transport's namespace in `~/.kward/transports/`.
+
+Run `kward transport list` to inspect registrations, `kward transport status`
+to inspect runtime state, and `kward transport run NAME` to run a transport in
+the foreground. See [Telegram transport](telegram.md) for the first-party
+long-polling adapter and setup instructions.
+
 ### Project skills
 
 Kward loads user-level skills but skips project-level skills by default. Enable them only for repositories you trust, either through `/settings` → Tools & Search → Trust project skills or with:
@@ -79,6 +113,7 @@ By default, Kward stores user data under `~/.kward`. Common files and directorie
 
 ```text
 ~/.kward/config.json
+~/.kward/api_keys.json
 ~/.kward/auth.json
 ~/.kward/anthropic_auth.json
 ~/.kward/github_auth.json
@@ -145,6 +180,8 @@ aliases:
 
 ## Provider and model settings
 
+The [Model providers](providers.md) guide lists every provider ID, model key, credential variable, catalog source, and request API. This section explains the underlying config pattern.
+
 Set `provider` to choose the active backend:
 
 ```json
@@ -155,12 +192,15 @@ 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:
+Common values are:
 
-- `codex` for the OpenAI/ChatGPT Codex backend.
-- `anthropic` for Anthropic Claude Pro/Max subscription support.
-- `openrouter` for OpenRouter.
-- `copilot` for experimental Copilot provider support.
+- `codex` for the ChatGPT/Codex OAuth backend;
+- `openai_api` for direct OpenAI API access;
+- `anthropic`, `openrouter`, and `copilot` for those providers;
+- `gemini` for Google Gemini;
+- `azure_openai` for a configured Azure deployment;
+- `cerebras`, `deepseek`, `fireworks`, `groq`, `mistral`, `nvidia`, `together`, or `xai` for API-key providers;
+- `local` for an OpenAI-compatible Ollama, LM Studio, or llama.cpp server. See [Local models](local-models.md).
 
 Model settings:
 
@@ -168,9 +208,13 @@ Model settings:
 {
   "model": "gpt-5.6-sol",
   "openai_model": "gpt-5.6-sol",
+  "openai_api_model": "gpt-5.4-mini",
   "openrouter_model": "openai/gpt-5.6-sol",
+  "gemini_model": "gemini-2.5-flash",
+  "groq_model": "provider-model-id",
   "anthropic_model": "claude-sonnet-5",
   "copilot_model": "gpt-5-mini",
+  "local_model": "qwen2.5-coder:7b",
   "reasoning_effort": "medium",
   "openai_reasoning_effort": "medium",
   "openrouter_reasoning_effort": "medium",
@@ -180,11 +224,11 @@ 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. `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.
+`model` is a legacy generic fallback. Provider-specific values take precedence. Catalog providers use `<runtime-id>_model`; for example, direct OpenAI uses `openai_api_model`, Gemini uses `gemini_model`, and Groq uses `groq_model`. Codex keeps `openai_model`. `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.
 
 Set `codex_show_raw_reasoning` to `true` to display raw Codex `reasoning_text` when the API does not provide reasoning summary text. It defaults to `false`; raw reasoning can include internal or unstable model output, so enable it only when you explicitly want to inspect that stream.
 
-`stream_idle_timeout_seconds` limits how long a streamed Codex or Anthropic response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
+`stream_idle_timeout_seconds` limits how long a streamed Codex, Anthropic, or Local response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
 
 Defaults:
 
@@ -198,6 +242,24 @@ The Anthropic model choices include `claude-fable-5`, but Fable availability dep
 
 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.
 
+### Local model server
+
+The `local` provider uses OpenAI-compatible Chat Completions and model-list endpoints. Configure a running local server with a model id and its actual context window:
+
+```json
+{
+  "provider": "local",
+  "local_backend": "ollama",
+  "local_base_url": "http://127.0.0.1:11434/v1",
+  "local_model": "qwen2.5-coder:7b",
+  "local_context_window": 32768
+}
+```
+
+`local_backend` selects a convenience default: `ollama`, `lm_studio`, or `llama_cpp`. Their default base URLs are `http://127.0.0.1:11434/v1`, `http://127.0.0.1:1234/v1`, and `http://127.0.0.1:8080/v1`, respectively. Set `local_base_url` to use a custom endpoint. `local_api_key` is optional and is sent as a bearer token only when configured.
+
+Set `local_context_window` to the context length configured for the loaded model. Kward does not infer this safely from an arbitrary local model name; without it, automatic context budgeting cannot report a reliable limit. Local providers do not expose Kward reasoning or image controls by default.
+
 ## Environment overrides
 
 Use environment variables for one-off runs or local secrets that you do not want in config.
@@ -205,10 +267,16 @@ Use environment variables for one-off runs or local secrets that you do not want
 Provider and model:
 
 - `KWARD_PROVIDER`
-- `OPENAI_MODEL`
-- `OPENAI_REASONING_EFFORT`
+- `OPENAI_MODEL` and `OPENAI_REASONING_EFFORT` for Codex
+- `OPENAI_API_MODEL` and `OPENAI_API_REASONING_EFFORT` for direct OpenAI
+- `<PROVIDER>_MODEL` for catalog providers such as `GEMINI_MODEL`, `GROQ_MODEL`, and `XAI_MODEL`
 - `OPENROUTER_MODEL`
 - `OPENROUTER_REASONING_EFFORT`
+- `KWARD_LOCAL_BACKEND`
+- `KWARD_LOCAL_BASE_URL`
+- `KWARD_LOCAL_MODEL`
+- `KWARD_LOCAL_CONTEXT_WINDOW`
+- `KWARD_LOCAL_API_KEY`
 - `ANTHROPIC_MODEL`
 - `ANTHROPIC_REASONING_EFFORT`
 - `COPILOT_MODEL`
@@ -216,7 +284,11 @@ Provider and model:
 
 Credentials:
 
-- `OPENAI_ACCESS_TOKEN`
+- `OPENAI_ACCESS_TOKEN` for ChatGPT/Codex OAuth
+- `OPENAI_API_KEY` for direct OpenAI
+- `ANTHROPIC_API_KEY`
+- `AZURE_OPENAI_API_KEY`
+- `CEREBRAS_API_KEY`, `DEEPSEEK_API_KEY`, `FIREWORKS_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `NVIDIA_API_KEY` (or `NGC_API_KEY`), `TOGETHER_API_KEY`, and `XAI_API_KEY`
 - `OPENROUTER_API_KEY`
 - `COPILOT_GITHUB_TOKEN`
 - `GITHUB_TOKEN` or `GH_TOKEN` for authenticated GitHub API requests in `code_search`
@@ -233,16 +305,9 @@ Color and logging environment variables are covered below.
 
 The friendliest way to configure credentials is `/login` inside Kward, or `kward login` from your shell. See [Authentication](authentication.md) for the full provider flow.
 
-Credential settings can also live in config:
-
-```json
-{
-  "openai_oauth_client_id": "your-client-id",
-  "openrouter_api_key": "sk-or-v1-..."
-}
-```
+API keys are not stored in `config.json`. `/login` writes them to the private `<config-dir>/api_keys.json` file; environment variables take precedence for one-off runs. `openrouter_api_key` is a legacy setting that Kward migrates to the private store.
 
-Use environment variables for temporary or local-only secrets when possible. If multiple credentials are available, OpenAI OAuth is used by default unless `provider` or `KWARD_PROVIDER` selects another backend such as `anthropic`, `openrouter`, or `copilot`.
+Non-secret authentication setup, such as `openai_oauth_client_id` and Azure endpoint/deployment/API-version values, remains in config. If multiple credentials are available, set `provider`, use `/model`, or use `KWARD_PROVIDER` to choose explicitly.
 
 ## Overlay settings
 
@@ -330,9 +395,9 @@ The integrated Git and session diff viewers support unified and side-by-side lay
 
 `diff_view` can be `auto`, `unified`, or `side_by_side`. In `auto` mode, Kward uses side-by-side output when the terminal is at least 120 columns wide and unified output in narrower terminals. Change it with `/settings` → Interface → Diff view.
 
-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.
+The editor includes syntax highlighting, automatic indentation, and matching-pair insertion for common languages. Unknown file types and color-disabled terminals use plain text. See [Integrated editor](editor.md#What_the_editor_supports) for the supported languages and detailed editing behavior.
 
-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:
+Auto-indent and matching-pair insertion are enabled by default. To disable either feature:
 
 ```json
 {
@@ -375,11 +440,15 @@ Editable editor buffers request a vertical bar cursor by default. Terminals that
 }
 ```
 
-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.
+Choose the mode that matches how you already edit:
 
-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.
+| Mode | Best fit |
+| --- | --- |
+| `modern` | Familiar shortcuts such as `Ctrl+S` to save and `Ctrl+Q` to quit. |
+| `emacs` | Non-modal Emacs-style movement, selection, kill, and yank keys. |
+| `vibe` | A focused Vim-style experience with normal, insert, command, and visual modes. |
 
-Vibe mode opens files in normal mode and supports a compact Vim-style subset: normal/insert/command modes, character, line, and block visual modes, `h/j/k/l`, word and WORD movement, counts, `d`/`y`/`c` operators, line yanks and indentation, case operators, marks, macros, jump-list navigation, linewise paste, search, undo/redo, and common `:w`, `:q`, `:q!`, `:wq`, `:x`, `:e`, substitution, and `:number` commands. Yanks also copy to the terminal clipboard when OSC 52 is supported.
+See [Integrated editor](editor.md#Choosing_an_editor_mode) for complete keymaps and mode-specific behavior.
 
 ## Session settings
 
@@ -502,6 +571,31 @@ Do not put shared or published API keys in this file.
 
 Put global engineering principles in `PRINCIPLES.md` beside your config file, usually `~/.kward/PRINCIPLES.md`. Kward appends this file to its built-in system instructions when present. Existing config-directory `AGENTS.md` files are still read as a legacy alias when `PRINCIPLES.md` is absent.
 
+## Replacement system prompt
+
+Set `system_prompt.file` to use a file as the entire system prompt. In replacement mode Kward does not append its built-in instructions, global principles, memory context, personas, plugin context, skills, or workspace `AGENTS.md` guidance.
+
+```json
+{
+  "system_prompt": {
+    "file": "prompts/local-minimal.md",
+    "include_principles": false
+  }
+}
+```
+
+Relative paths are resolved beside `config.json`. The file is sent to the configured model and can be recorded in session prompt snapshots, so do not place secrets in it. Use `kward sysprompt` to inspect the exact active prompt.
+
+To retain Kward's normal prompt while omitting only global `PRINCIPLES.md` (and its legacy config-directory `AGENTS.md` fallback), configure:
+
+```json
+{
+  "system_prompt": {
+    "include_principles": false
+  }
+}
+```
+
 ## Workspace AGENTS.md
 
 By default, Kward does not inject the full workspace `AGENTS.md` into every request. When a workspace `AGENTS.md` exists, Kward injects a compact instruction telling the model to read it for repository-related tasks before analyzing or modifying project files.
@@ -528,11 +622,26 @@ Workspace guardrails are enabled by default. File tools such as `read_file`, `wr
 }
 ```
 
-This is not a sandbox setting. Shell commands already run as your OS user from the workspace directory and can access anything that user can access.
+Workspace guardrails limit Kward file tools; they are not an operating-system sandbox and do not constrain arbitrary shell commands. See [Command sandboxing](sandboxing.md) to apply an opt-in operating-system boundary to model-requested `run_shell_command` workers.
+
+## Command sandboxing
+
+Sandboxing is off by default. Use `/sandbox` to inspect or change the mode and child-network access. For additional writable roots or Git metadata protection, edit the `sandbox` config directly. `sandbox.mode` accepts `off`, `read_only`, or `workspace_write`; `sandbox.network` defaults to `deny`, and `sandbox.protect_git_metadata` defaults to `true`.
+
+```json
+{
+  "sandbox": {
+    "mode": "workspace_write",
+    "network": "deny"
+  }
+}
+```
+
+When Kward cannot enforce a requested non-off mode, it denies the command rather than running it unrestricted. Current support and limits are documented in [Command sandboxing](sandboxing.md).
 
 ## Permissions
 
-Permissions are off by default. When enabled, Kward evaluates model-requested tools before execution. This is a permission policy, not an operating-system sandbox: permitted shell commands still run with your user account's access.
+Permissions are off by default. When enabled, the permission policy decides whether a model-requested tool can start. It is not an operating-system sandbox: permitted shell commands still run with your user account's access.
 
 ```json
 {

data/doc/context-budgeting.md

@@ -1,8 +1,8 @@
 # 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.
+Kward handles context budgeting automatically. Instead of reading whole files and pasting every byte of command output 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.
+This guide explains why Kward sometimes reads an outline or a small section before opening a whole file, how it handles large tool output, and how you can inspect the resulting token savings.
 
 ## Why this matters
 
@@ -14,9 +14,9 @@ Kward's goal is not to build a heavyweight semantic index. It is to stay lightwe
 find likely files -> inspect outlines/previews -> read exact ranges -> read full files only when needed
 ```
 
-## The current workflow
+## How Kward gathers context
 
-When Kward needs code context, it should usually start with one of these tools:
+When Kward needs code context, it usually starts with one of these tools:
 
 - `context_for_task` for a compact task-shaped bundle.
 - `summarize_file_structure` for a source outline of one file.
@@ -27,11 +27,11 @@ 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.
+This happens automatically during normal work; you do not need to choose the tools or modes yourself.
 
 ## 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:
+`context_for_task` gives Kward a focused starting point. It accepts a task and, optionally, a set of paths and a byte budget, then returns a compact bundle with:
 
 - ranked candidate files (by term-matching score),
 - source outlines for each file,

data/doc/context-tools.md

@@ -64,7 +64,7 @@ Constraints:
 - 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.
+The question picker is available only in frontends that support structured questions. In the terminal, it lets Kward ask a concise multiple-choice question instead of guessing. RPC clients receive the same flow through UI events; see the [RPC question bridge](rpc.md) for notification and response details.
 
 Good uses:
 
@@ -72,7 +72,7 @@ Good uses:
 - 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.
+Structured questions are most useful when the answer would materially change the implementation or avoid a risky assumption—not for every small uncertainty.
 
 ## Availability