kward 0.79.0 → 0.80.0

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 |
 | --- | --- |
@@ -20,6 +22,8 @@ If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as
 | 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
@@ -46,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:
@@ -80,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
@@ -146,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
@@ -156,12 +192,14 @@ 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:
@@ -170,7 +208,10 @@ 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",
@@ -183,7 +224,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. `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.
 
@@ -226,8 +267,9 @@ 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`
@@ -242,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`
@@ -259,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
 
@@ -356,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
 {
@@ -401,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
 
@@ -579,7 +622,7 @@ Workspace guardrails are enabled by default. File tools such as `read_file`, `wr
 }
 ```
 
-This is not a sandbox setting. File guardrails constrain Kward file tools, not arbitrary shell commands. See [Command sandboxing](sandboxing.md) to apply an opt-in operating-system boundary to model-requested `run_shell_command` workers.
+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
 
@@ -598,7 +641,7 @@ When Kward cannot enforce a requested non-off mode, it denies the command rather
 
 ## 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
 

data/doc/editor.md

@@ -1,4 +1,8 @@
-# Integrated Editor
+# Integrated editor
+
+Kward includes a terminal editor with three modes: Modern, Emacs, and Vibe. It opens inside the chat composer, so you can jump into a file, make a change, save it, and return to the conversation without switching tools.
+
+The editor opens only files inside the current workspace, which keeps edits tied to the project where you started Kward.
 
 <quote>
 Three Modes for the Elven-kings under the sky,<br>
@@ -10,10 +14,6 @@ One Kward to bring them all and in the transcript bind them<br>
 In the Land of Ruby where the agents lie.<br>
 </quote>
 
-Kward includes a terminal editor with 3 editing modes to choose from: Modern, Emacs and Vibe. It opens inside the chat composer, so you can jump into a file, make a change, save it, and return to the conversation without switching tools.
-
-The editor is scoped to the current workspace. It only opens files inside that directory, which helps keep edits tied to the project you started Kward in.
-
 ## Quick start
 
 Open a file directly from your shell:
@@ -93,8 +93,8 @@ $doc/editor.md
 
 The editor is intentionally compact, but it covers the basics you need for quick changes:
 
-- Syntax highlighting for common languages, including 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. Unknown file types render as plain text.
-- Auto-indent, enabled by default. New lines inherit indentation, Tab jumps to the expected indentation or the next indentation stop, Shift+Tab moves indentation back, obvious closing tokens are re-indented, and Backspace in leading whitespace removes one indentation unit when possible. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword; Ctrl+Enter also works from the middle of the line in terminals that report modified Enter keys.
+- Syntax highlighting for common languages, including Ruby, ERB templates, 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. ERB highlights template HTML outside ERB tags and Ruby inside `<% ... %>` tags. Unknown file types render as plain text.
+- Auto-indent, enabled by default. New lines inherit indentation, Tab jumps to the expected indentation or the next indentation stop, Shift+Tab moves indentation back, obvious closing tokens are re-indented, and Backspace in leading whitespace removes one indentation unit when possible. ERB recognizes common inline Ruby control tags and HTML opening tags when calculating the next indentation. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword; Ctrl+Enter also works from the middle of the line in terminals that report modified Enter keys.
 - Undo and redo, with up to 100 history entries per buffer.
 - Incremental search forward and backward.
 - Selection, copy, cut, and paste. Copy and cut also write to the terminal clipboard through OSC 52 when the terminal supports it.

data/doc/extensibility.md

@@ -14,6 +14,7 @@ Start simple. Most users only need `PRINCIPLES.md`, workspace `AGENTS.md`, and m
 | Task-specific reusable instructions | skills |
 | Different tone or role | [personas](personas.md) |
 | Local Ruby behavior or integrations | plugins |
+| External messaging or event integration | transport plugins |
 | Deterministic runtime policy or automation | lifecycle hooks |
 
 Install the starter pack for a useful starting point:
@@ -68,35 +69,9 @@ By default, Kward adds a compact instruction telling the model that `AGENTS.md`
 
 ## Prompt templates
 
-Use prompt templates when you repeatedly type the same kind of request.
+Use prompt templates when you repeatedly type the same kind of request. Each Markdown file in `~/.kward/prompts/` becomes a slash command; its filename is the command name and `$ARGUMENTS` expands the text after the command.
 
-Create:
-
-```text
-~/.kward/prompts/review.md
-```
-
-Example:
-
-```markdown
----
-description: Review a change for correctness.
-argument-hint: <focus>
----
-
-Review the current diff for correctness, tests, and maintainability.
-Focus on: $ARGUMENTS
-```
-
-Then run inside Kward:
-
-```text
-/review auth edge cases
-```
-
-The `description` frontmatter field appears in the slash command list and completion overlay so you can find the template by purpose. `argument-hint` is shown as a usage hint. The `$ARGUMENTS` placeholder in the body is replaced with whatever you type after the command.
-
-Prompt templates are best for reusable text. They do not run local code.
+See [Prompt templates](prompt-templates.md) to create one, understand naming and reload behavior, and learn about the `/plan`, `/investigate`, `/research`, and `/codebase-review` templates installed by `kward init`.
 
 ## Skills
 
@@ -114,12 +89,15 @@ Hooks are deterministic automation and policy. They are not model instructions.
 
 Use plugins when text instructions are not enough and you need Ruby code to run locally.
 
-Plugins can add slash commands, prompt context, footer UI, transcript observers, and RPC-visible commands.
+Plugins can add slash commands, prompt context, footer UI, transcript observers, RPC-visible commands, and external transports. Transport plugins can connect external conversations to normal Kward sessions or explicitly transport-capable plugin chats; they remain distinct from plugin-owned tabs.
+
+Use `kward transport list` and `kward transport status` to inspect registered transports. Run a foreground transport with `kward transport run NAME`.
 
 Plugin files live in:
 
 ```text
 ~/.kward/plugins/*.rb
+~/.kward/plugins/*/plugin.rb
 ```
 
 Plugins are trusted local Ruby code. Install only plugins you trust. See [Plugins](plugins.md).

data/doc/files.md

@@ -12,7 +12,7 @@ From an interactive Kward session, run:
 /files
 ```
 
-Kward opens the project file browser. Use the arrow keys to move through the tree, then press `Enter` on a file to open it in the integrated editor.
+Kward opens the project file browser. Use the arrow keys or `j`/`k` to move through the tree, then press `Enter` on a file to open it in the integrated editor.
 
 When you quit the editor, Kward returns to the file browser at the same position so you can keep browsing nearby files.
 
@@ -32,10 +32,10 @@ Outside Git, Kward scans the workspace directory and skips common noisy director
 
 | Key | Action |
 | --- | ------ |
-| `↑` / `↓` | Move the selection |
+| `↑` / `↓` or `j` / `k` | Move the selection down / up |
 | `Enter` | Open a file, or toggle a directory |
-| `←` | Collapse the selected directory, or jump to its parent |
-| `→` | Expand the selected directory |
+| `←` or `h` | Collapse the selected directory, or jump to its parent |
+| `→` or `l` | Expand the selected directory |
 | `Tab` | Start or stop search |
 | `/` | Start search |
 | `Backspace` | Delete the last search character |
@@ -55,7 +55,7 @@ For example:
 /agent
 ```
 
-Use `↑` and `↓` to choose a result, then press `Enter` to open it. Press `Esc` to return to the tree view.
+Use `↑` / `↓` or `j` / `k` to choose a result, then press `Enter` to open it. Press `Esc` to return to the tree view.
 
 ## Mention a file in chat
 
@@ -84,7 +84,7 @@ A typical workflow:
 5. Save and quit.
 6. Continue browsing files, or press `Esc` to return to chat.
 
-See [Integrated Editor](editor.md) for editor modes, save/quit keys, search, selection, and configuration.
+See [Integrated editor](editor.md) for editor modes, save/quit keys, search, selection, and configuration.
 
 ## Remembered state
 

data/doc/getting-started.md

@@ -57,7 +57,7 @@ Or from inside an interactive session:
 /login
 ```
 
-Kward supports OpenAI/ChatGPT, Anthropic Claude Pro/Max, OpenRouter, and experimental Copilot credentials. See [Authentication](authentication.md) when you need a specific provider.
+Kward supports subscription login, direct native APIs, OpenAI-compatible API-key providers, Copilot, OpenRouter, and local model servers. See [Model providers](providers.md) to choose one, then [Authentication](authentication.md) for its login flow.
 
 Confirm your credentials are saved:
 
@@ -65,7 +65,7 @@ Confirm your credentials are saved:
 kward auth status
 ```
 
-If your provider offers multiple models, choose one inside Kward with `/model`.
+Choose a model inside Kward with `/model`. The picker can refresh provider catalogs, switch providers, show all returned entries, or accept a manual model/deployment ID.
 
 ## Start an interactive chat
 

data/doc/git.md

@@ -30,7 +30,7 @@ Use the overlay to review and shape the commit:
 
 | Key | Action |
 | --- | --- |
-| `↑` / `↓` | Move between changed files. |
+| `↑` / `↓` or `j` / `k` | Move between changed files. |
 | `Enter` | Open the selected file in the diff viewer. |
 | `s` | Stage or unstage the selected file. |
 | `Tab` | Switch to commit-message entry. |
@@ -61,7 +61,7 @@ Useful keys in the diff viewer:
 
 After you close the viewer, Kward returns to the Git overlay with the file list refreshed.
 
-The diff viewer is read-only. It is meant for checking what changed, not editing. If you spot something you want to fix, close the viewer, return to chat, and ask Kward to make the change or open the file with the built-in editor using `$path/to/file`. See [Integrated Editor](editor.md) for editor workflows and keybindings.
+The diff viewer is read-only. It is meant for checking what changed, not editing. If you spot something you want to fix, close the viewer, return to chat, and ask Kward to make the change or open the file with the built-in editor using `$path/to/file`. See [Integrated editor](editor.md) for editor workflows and keybindings.
 
 ## Example workflow
 
@@ -107,6 +107,12 @@ This is just a lightweight status hint. Use `/git` when you want to review or co
 
 If the working tree is clean when you run `/git`, the overlay shows `No uncommitted changes.` and there is nothing to stage or commit.
 
+## Agent commits in worktree tabs
+
+When an active worktree tab receives an explicit request to commit, the agent can use the model-facing `git_commit` tool. It runs Git in the trusted host process so linked-worktree metadata can be updated without granting arbitrary shell commands write access to shared `.git` metadata.
+
+The tool requires a commit message and can receive an optional list of workspace-relative paths. If paths are omitted, all current changes in the active worktree are included. Generic `run_shell_command` Git commands remain sandboxed and cannot replace this operation. It is exposed only for active interactive worktree tabs; RPC sessions do not currently support worktree bindings.
+
 ## Notes and limitations
 
 - `/git` is available in the interactive terminal UI, not in one-shot prompts or the RPC backend.

data/doc/lifecycle-hooks.md

@@ -1,8 +1,8 @@
 # Lifecycle hooks
 
-Lifecycle hooks are deterministic runtime callbacks around Kward's agent workflow. Use them when something must happen because of an event, not because the model remembered an instruction.
+Lifecycle hooks let you run a rule or action whenever something happens in Kward—for example, before a command runs, after a turn finishes, or when a tool needs approval. Use a hook when the action must happen reliably rather than depending on the model to remember an instruction.
 
-Hooks can observe events and return structured decisions to allow, deny, ask for approval, modify supported payloads, warn, retry, or defer. They are currently exposed through trusted Ruby plugins and through command hooks configured in `config.json`.
+A hook can observe an event, allow or deny an operation, ask for approval, adjust supported data, or trigger follow-up work. You can add hooks through trusted Ruby plugins or configure command hooks in `config.json`.
 
 Hooks run as local code with your user permissions. Do not install hooks you do not trust, and do not put secrets in hook output.
 
@@ -34,7 +34,8 @@ When multiple hooks match one event, they run by ascending `order`. A `deny` sto
 
 ## Ruby plugin hooks
 
-Register hooks from trusted plugin files in `~/.kward/plugins/*.rb`:
+Register hooks from trusted plugin files in `~/.kward/plugins/*.rb` or a
+package entrypoint at `~/.kward/plugins/*/plugin.rb`:
 
 ```ruby
 Kward.plugin do |plugin|
@@ -363,7 +364,7 @@ Unknown selector keys match same-named payload fields.
 
 ## Security notes
 
-- Plugin hooks are trusted Ruby code loaded only from `~/.kward/plugins/*.rb`.
+- Plugin hooks are trusted Ruby code loaded only from `~/.kward/plugins/*.rb` or package entrypoints at `~/.kward/plugins/*/plugin.rb`.
 - Command hooks run local commands with your user permissions.
 - Workspace hook files are loaded only after `/hooks trust`, and trust is invalidated when `.kward/hooks.json` changes.
 - Hook payloads are intentionally bounded and metadata-oriented; avoid logging raw event JSON if your hook receives prompt or command data.

data/doc/local-models.md

@@ -1,8 +1,8 @@
 # Local models
 
-Kward can connect to a local model server that provides OpenAI-compatible Chat Completions. This is useful when you want offline development, control over model selection, or a smaller prompt for a local coding model.
+If you already run Ollama, LM Studio, or llama.cpp, Kward can use it as a local model provider. This can be useful for offline work, tighter control over model selection, or a smaller prompt tuned for a local coding model. The server must provide OpenAI-compatible Chat Completions.
 
-Kward connects to an already-running server. It does not install runtimes, download models, choose GPU settings, or load models for you.
+Kward connects to an already-running server; it does not install a runtime, download or load models, or choose GPU settings. For a comparison with hosted providers, see [Model providers](providers.md#Choosing_between_similar_providers).
 
 ## Choose and start a runtime
 

data/doc/mcp.md

@@ -1,8 +1,8 @@
 # MCP servers
 
-Kward can connect to local [Model Context Protocol](https://modelcontextprotocol.io/) servers and expose their tools to the model alongside Kward's built-in workspace tools.
+Kward can connect to local [Model Context Protocol](https://modelcontextprotocol.io/) servers and use their tools alongside its built-in workspace tools.
 
-This is useful when another app ships an MCP server for something Kward should be able to inspect or control. For example, Safari Technology Preview includes a Safari MCP server that lets agents inspect pages, console output, network activity, screenshots, and other browser state.
+Use MCP when another app exposes something you want Kward to inspect or control. For example, Safari Technology Preview includes an MCP server for inspecting pages, console output, network activity, screenshots, and other browser state.
 
 ## Configure a local MCP server
 
@@ -66,7 +66,7 @@ Example with an environment variable and custom timeout:
 
 ## Notes and limitations
 
-- Kward currently supports local stdio MCP servers.
-- Kward currently exposes MCP tools. MCP resources, prompts, sampling, and Streamable HTTP are not implemented yet.
-- MCP tool results are returned to the model as text. Structured content is included as JSON. Image, audio, and resource results are summarized as placeholders for now.
+- Kward supports local stdio MCP servers and exposes their tools to the model.
+- It does not support MCP resources, prompts, sampling, or Streamable HTTP.
+- MCP tool results are returned to the model as text. Structured content is included as JSON. Image, audio, and resource results are summarized as placeholders.
 - MCP servers can expose sensitive local application state. Only configure servers you trust, especially browser automation servers that can read page content or screenshots.

data/doc/permissions.md

@@ -1,8 +1,8 @@
 # Permissions
 
-Kward's permission policy lets you put a human decision between a model-requested tool call and its side effect. It is useful when you want the agent to inspect a project freely, but want to confirm edits, commands, web requests, or MCP calls as they arise.
+Turn on permissions when you want Kward to ask before it edits files, runs commands, accesses the web, or calls an MCP tool. In the usual `ask` mode, read-only work continues normally while you decide which side effects to allow.
 
-Permissions are **off by default**. Enabling them does not sandbox Kward or its subprocesses: an allowed shell command still runs with your operating-system user permissions unless you separately enable [command sandboxing](sandboxing.md) for model-requested shell commands.
+Permissions are **off by default**. They are not an operating-system sandbox: an allowed shell command still runs with your operating-system user permissions unless you separately enable [command sandboxing](sandboxing.md) for model-requested shell commands.
 
 ## Start with approval mode
 
@@ -24,7 +24,16 @@ In `ask` mode, Kward allows ordinary read-only tools and asks before the agent:
 - searches or fetches content on the web,
 - calls an MCP tool.
 
-When approval is required in the interactive CLI, Kward opens a modal overlay. It shows the complete tool arguments, so an approval for `read_skill` includes the requested skill name and relative path, and an approval for a write includes its path and content. Choose **Allow once** to run that one call, **Allow this tool for this session** to allow later calls to the same tool in the current Kward session, or **Deny** to stop it. Pressing `Esc`, cancelling the overlay, or losing the approval bridge denies the call.
+When Kward needs approval in the interactive CLI, it shows the complete tool arguments in an overlay. For example, a write request includes the file path and content.
+
+Choose:
+
+- **Allow once** to run this call.
+- **Allow this tool for this session** to allow later calls to the same tool in the current session.
+- **Deny** to stop the call.
+- **Type something** to stop the call and tell Kward what to do instead.
+
+Pressing `Esc`, closing the overlay, or losing the frontend connection denies the call.
 
 ### Steer the agent with `Type something`
 
@@ -91,7 +100,7 @@ With this configuration, the agent may edit `lib/` and `test/` without asking. A
 
 `write_scopes` narrows the policy's default workspace-write behavior; it does not broaden Kward's built-in workspace boundary. File tools still stay inside the active workspace by default, and existing files must still be read before Kward can edit them. See [Workspace tools](workspace-tools.md) for those guardrails.
 
-An empty `write_scopes` array permits no default workspace writes. Omit `write_scopes` if you want the `workspace-write` mode to cover the normal workspace file-tool boundary.
+An empty `write_scopes` array permits no default workspace writes. Omit `write_scopes` if you want the `workspace-write` mode to cover the normal workspace file-tool boundary. The active worktree `git_commit` tool is treated as a mutating tool: it asks for approval in the default `ask` mode and is denied by read-only or deny-by-default modes unless explicitly allowed.
 
 ## Rules and precedence