kward 0.79.0 → 0.80.1

data/doc/plugins.md

@@ -21,16 +21,21 @@ Plugins run inside the Kward process with your user permissions. Install only pl
 | Repository rules | `AGENTS.md` |
 | Local Ruby code or integration | plugin |
 
-See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order.
+See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations.
 
 ## Where plugins live
 
-Kward loads top-level Ruby files from:
+Kward loads trusted Ruby plugin entrypoints from:
 
 ```text
 ~/.kward/plugins/*.rb
+~/.kward/plugins/*/plugin.rb
 ```
 
+For a larger plugin, use a directory with `plugin.rb` as its entry point. Kward
+loads only that file automatically, so use `require_relative` there to load any
+sibling files.
+
 Plugins are not loaded from the current workspace or a custom `KWARD_CONFIG_PATH` directory. This prevents a project checkout from silently adding executable Ruby code to Kward.
 
 ## A first plugin
@@ -58,7 +63,7 @@ Start Kward and run:
 /hello World
 ```
 
-When developing plugins, use `/reload` inside Kward to reload all plugin files without restarting. This picks up changes to existing plugins and registers new ones, then rebuilds the system message.
+When developing plugins or prompt templates, use `/reload` inside Kward to reload configured prompt files and all plugin files without restarting. This picks up prompt edits, changes to existing plugins, and new plugin registrations, then refreshes slash-command completion and rebuilds the system message.
 
 ## Add a slash command
 
@@ -111,7 +116,7 @@ Kward.plugin do |plugin|
 end
 ```
 
-Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning.
+Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning. Kward evaluates the active footer at most once per second and reuses its last value between refreshes.
 
 ## Add an interactive command
 
@@ -132,6 +137,7 @@ Kward.plugin do |plugin|
       x = (x + 1) % ui.width
       key = ui.poll_key
       return :exit if key == :ctrl_c || key == "q"
+      ui.render
     end
   end
 end
@@ -162,6 +168,8 @@ Keys are returned as symbols (`:left`, `:right`, `:up`, `:down`, `:return`,
 without a named mapping. Ctrl+C always exits the loop immediately.
 
 The tick callback runs at the configured frame rate (1–120 fps, default 30).
+Calls to `put` and `clear_frame` stage canvas changes; call `render` after the
+frame is complete to publish it. Kward skips ticks that do not publish a frame.
 Returning `:exit` from the tick callback ends the loop, same as calling
 `ui.exit`.
 
@@ -219,6 +227,7 @@ The observer context exposes the plugin tab's `messages` through
 - `messages` — renderable transcript messages;
 - `submit(input, display_input:, cancellation:, steering:)` — a turn method
   that returns the final response and yields stream events;
+- optionally `submit(..., context:)` — trusted actor context for transport turns;
 - `descriptor` — the durable tab descriptor;
 - `supports_steering?` and `assistant_label`.
 
@@ -234,6 +243,32 @@ plugin.tab_type "example", id: "com.example.chat", rpc: true do |host, descripto
 end
 ```
 
+Set `transport: true` separately when an external transport may target the
+plugin chat. Do not use `rpc: true` as an implicit external-access permission:
+
+```ruby
+plugin.tab_type "example", id: "com.example.chat", rpc: true, transport: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+Set `local: false` for a transport-only plugin chat. It remains available to
+transports when `transport: true`, but `/tab open` and local tab restoration do
+not expose it:
+
+```ruby
+plugin.tab_type "telegram", id: "com.example.telegram", local: false, transport: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+Transport-created plugin chats receive a descriptor containing a stable scoped
+key, transport identity, external conversation, and actor metadata. Use the
+scope to select separate transcript and memory roots. The driver may accept a
+`context:` keyword on `submit` to receive the authenticated actor for each
+turn; access decisions must still be enforced by the transport and plugin code,
+not by model instructions.
+
 RPC clients discover opted-in types through `initialize.capabilities.pluginChats`, open a chat with `pluginChats/open`, and must explicitly subscribe before receiving live `pluginChat/event` notifications. See [RPC](rpc.md) for the protocol. Plugin tabs remain CLI-only unless they opt in.
 
 ## Observe transcript events

data/doc/prompt-templates.md

@@ -0,0 +1,105 @@
+# Prompt templates
+
+Prompt templates turn a repeated request into a slash command. Keep one when you regularly ask Kward to plan before coding, investigate without changing files, or review a particular part of a project in the same way.
+
+Templates are reusable **user prompts**, not always-on instructions. Kward expands the selected template when you run its slash command, then sends the expanded text as your request.
+
+Use [skills](skills.md) for task guidance the model can load when relevant, `PRINCIPLES.md` for preferences that apply broadly, and `AGENTS.md` for repository rules.
+
+## Create a template
+
+By default, put one Markdown file per command in:
+
+```text
+~/.kward/prompts/
+```
+
+For example, create `~/.kward/prompts/review.md`:
+
+```markdown
+---
+description: Review a change for correctness.
+argument-hint: <focus>
+---
+
+Review the current diff for correctness, tests, and maintainability.
+Focus on: $ARGUMENTS
+Do not edit files; report findings first.
+```
+
+Restart Kward, or use `/reload` in an already-running session. The filename becomes the command name:
+
+```text
+/review authentication edge cases
+```
+
+Kward expands `$ARGUMENTS` everywhere it appears in the body with the text after `/review`. In this example, the model receives `Focus on: authentication edge cases`. If the template does not contain `$ARGUMENTS`, supplied arguments are not added automatically.
+
+The `description` and `argument-hint` frontmatter fields are optional, but useful: Kward shows them in slash-command completion. The rest of the file is the prompt body. Add as much Markdown structure and instruction text as the workflow needs.
+
+## Naming and discovery
+
+Kward reads `*.md` files directly inside the prompts directory, in filename order. It ignores subdirectories. A filename must produce a command containing only letters, numbers, `_`, and `-`, and must begin with a letter or number:
+
+```text
+~/.kward/prompts/
+├── review.md          # /review
+├── release-check.md   # /release-check
+└── api_v2.md          # /api_v2
+```
+
+A template cannot replace a built-in slash command such as `/settings`, `/skill`, or `/reload`; Kward warns and skips it. It also warns and skips files with invalid Markdown frontmatter or command names.
+
+`~/.kward/prompts` is the default. When `KWARD_CONFIG_PATH` points to another config file, templates live in the `prompts/` directory beside that file instead. See [Configuration](configuration.md#Config_directory).
+
+## Starter templates from `kward init`
+
+After installing Kward, run:
+
+```bash
+kward init
+```
+
+The starter pack downloads template files into `~/.kward/prompts/` without overwriting files that already exist. It currently installs these four commands:
+
+| Command | Use it for | What it asks Kward to do |
+| --- | --- | --- |
+| `/plan <task-or-change>` | Agree on an approach before coding | Clarify important requirements, produce a concise plan, and wait for confirmation before implementation. |
+| `/investigate <bug-or-behavior>` | Diagnose a bug or surprising result | Gather evidence, identify the root cause or strongest hypothesis, suggest the smallest safe fix, and make no edits. |
+| `/research <question-or-topic>` | Answer a question that needs current or external evidence | Prefer primary sources, separate facts from recommendations, cite sources and caveats, and make no changes. |
+| `/codebase-review [scope-or-focus]` | Assess a repository or area for practical cleanup | Report concrete maintainability, correctness, duplication, ownership, testing, and hot-path findings without refactoring. |
+
+For example:
+
+```text
+/plan Add rate limiting to the public API
+/investigate The session picker occasionally shows the wrong title
+/research Which OAuth scopes does this provider require?
+/codebase-review lib/kward/model
+```
+
+The starter templates deliberately favor report- or plan-first workflows. They do not make Kward edit files until you follow up with an explicit implementation request. Edit the installed files to fit your own process, or add new files alongside them.
+
+`kward init` also installs a base `PRINCIPLES.md` and starter skills. It needs network access to fetch the versioned [starter pack](https://github.com/kaiwood/kward-starter-pack) and leaves existing destination files untouched.
+
+## Practical patterns
+
+Keep templates specific enough to set a workflow, but short enough that the request remains easy to adapt. For example, a release-check prompt might take a version as an argument:
+
+```markdown
+---
+description: Prepare release notes and verification for a version.
+argument-hint: <version>
+---
+
+Prepare the release checklist for version $ARGUMENTS.
+Inspect the changelog and version files. Do not publish or tag a release.
+```
+
+Then run:
+
+```text
+/release-check 1.4.0
+```
+
+Templates only expand text; they do not execute local code, grant permissions, or bypass Kward's tool and workspace safeguards.

data/doc/providers.md

@@ -0,0 +1,140 @@
+# Model providers
+
+Kward can keep credentials for several model providers and switch between them without changing your conversation. Use this guide to compare authentication options, see where each provider's model list comes from, and find the names used in configuration.
+
+For login steps and credential storage, see [Authentication](authentication.md). For every config key and environment override, see [Configuration](configuration.md#Provider_and_model_settings).
+
+## Quick start
+
+Inside interactive Kward:
+
+```text
+/login
+/model
+```
+
+`/login` connects a provider. `/model` chooses the active provider and model. The model picker can refresh the available models, accept a manual model ID, show models normally hidden by compatibility filters, or switch providers.
+
+For example, direct OpenAI API access and ChatGPT/Codex OAuth can coexist:
+
+1. Run `kward login` for ChatGPT/Codex.
+2. Open `/login`, choose **API key**, then **OpenAI**.
+3. Open `/model` and choose either **Codex** or **OpenAI**.
+
+## Provider overview
+
+Kward normally uses the same provider name for authentication and configuration. Direct OpenAI is the exception: authentication and private API-key storage use `openai`, while config uses `openai_api` so it cannot be confused with Codex. RPC clients also use the authentication ID.
+
+| Provider shown in Kward | Catalog/auth ID | `provider` value | Authentication | Model source | Request API |
+| --- | --- | --- | --- | --- | --- |
+| Codex | — | `codex` | ChatGPT OAuth or `OPENAI_ACCESS_TOKEN` | Curated choices | ChatGPT Codex Responses, streaming |
+| OpenAI | `openai` | `openai_api` | API key | Live cache with curated/manual fallback | OpenAI Responses, streaming |
+| Anthropic | `anthropic` | `anthropic` | API key or Claude subscription OAuth | Curated/manual choices | Anthropic Messages, streaming |
+| Azure OpenAI | `azure_openai` | `azure_openai` | API key plus Azure setup | Configured deployment | Deployment-specific Chat Completions, streaming |
+| Google Gemini | `gemini` | `gemini` | API key | Live cache with curated/manual fallback | Native Gemini, streaming |
+| Cerebras | `cerebras` | `cerebras` | API key | Live cache or manual ID | OpenAI-compatible Chat Completions |
+| DeepSeek | `deepseek` | `deepseek` | API key | Live cache with curated/manual fallback | OpenAI-compatible Chat Completions |
+| Fireworks AI | `fireworks` | `fireworks` | API key | Live cache or manual ID | OpenAI-compatible Chat Completions |
+| Groq | `groq` | `groq` | API key | Live cache or manual ID | OpenAI-compatible Chat Completions |
+| Mistral | `mistral` | `mistral` | API key | Live cache with curated/manual fallback | OpenAI-compatible Chat Completions |
+| NVIDIA NIM | `nvidia` | `nvidia` | API key | Live cache or manual ID | OpenAI-compatible Chat Completions |
+| OpenRouter | `openrouter` | `openrouter` | API key | Account-specific cache or manual ID | OpenAI-compatible Chat Completions |
+| Together AI | `together` | `together` | API key | Live cache or manual ID | OpenAI-compatible Chat Completions |
+| xAI | `xai` | `xai` | API key | Live cache with curated/manual fallback | OpenAI-compatible Chat Completions |
+| GitHub Copilot | `copilot` | `copilot` | GitHub OAuth or `COPILOT_GITHUB_TOKEN` | Live choices with curated fallback | Copilot Responses or Chat Completions, streaming |
+| Local | — | `local` | Usually none; optional local bearer key | Local server `/models` endpoint or manual ID | OpenAI-compatible Chat Completions, streaming |
+
+“OpenAI-compatible” means Kward sends the provider's documented Chat Completions shape. It does not imply that every provider supports every OpenAI feature. Model availability, tools, images, reasoning, context limits, and billing remain provider- and model-specific.
+
+## IDs, model keys, and environment variables
+
+| Provider | Model config key | Model environment variable | Credential environment variable |
+| --- | --- | --- | --- |
+| Codex | `openai_model` | `OPENAI_MODEL` | `OPENAI_ACCESS_TOKEN` |
+| OpenAI | `openai_api_model` | `OPENAI_API_MODEL` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic_model` | `ANTHROPIC_MODEL` | `ANTHROPIC_API_KEY` for direct API access |
+| Azure OpenAI | `azure_openai_model` | `AZURE_OPENAI_MODEL` | `AZURE_OPENAI_API_KEY` |
+| Google Gemini | `gemini_model` | `GEMINI_MODEL` | `GEMINI_API_KEY` |
+| Cerebras | `cerebras_model` | `CEREBRAS_MODEL` | `CEREBRAS_API_KEY` |
+| DeepSeek | `deepseek_model` | `DEEPSEEK_MODEL` | `DEEPSEEK_API_KEY` |
+| Fireworks AI | `fireworks_model` | `FIREWORKS_MODEL` | `FIREWORKS_API_KEY` |
+| Groq | `groq_model` | `GROQ_MODEL` | `GROQ_API_KEY` |
+| Mistral | `mistral_model` | `MISTRAL_MODEL` | `MISTRAL_API_KEY` |
+| NVIDIA NIM | `nvidia_model` | `NVIDIA_MODEL` | `NVIDIA_API_KEY` or `NGC_API_KEY` |
+| OpenRouter | `openrouter_model` | `OPENROUTER_MODEL` | `OPENROUTER_API_KEY` |
+| Together AI | `together_model` | `TOGETHER_MODEL` | `TOGETHER_API_KEY` |
+| xAI | `xai_model` | `XAI_MODEL` | `XAI_API_KEY` |
+| GitHub Copilot | `copilot_model` | `COPILOT_MODEL` | `COPILOT_GITHUB_TOKEN` |
+| Local | `local_model` | `KWARD_LOCAL_MODEL` | `KWARD_LOCAL_API_KEY` when needed |
+
+Saved API keys live in private `<config-dir>/api_keys.json`; they do not belong in the model configuration. Environment credentials take precedence over saved API keys. OAuth files and their location overrides are documented in [Authentication](authentication.md#Custom_locations).
+
+## Choosing between similar providers
+
+### Codex or direct OpenAI
+
+Choose **Codex** when you want ChatGPT subscription authentication and the ChatGPT Codex backend. Choose **OpenAI** when you want an OpenAI Platform API key, public `api.openai.com` billing, and the Responses API. Their credentials and model settings are intentionally separate.
+
+### Anthropic API or Claude subscription
+
+Both appear as **Anthropic**. If an Anthropic API key is configured, Kward uses it before subscription OAuth. Remove or unset the API key when you specifically want the OAuth-backed subscription path.
+
+### OpenRouter or a direct provider
+
+OpenRouter is useful when you want one key and its cross-provider model catalog. A direct provider is useful when you want that provider's own billing, endpoint, or native runtime. Refresh OpenRouter with `/model` or:
+
+```bash
+kward openrouter refresh
+kward openrouter list
+```
+
+### Cloud or Local
+
+Choose **Local** for Ollama, LM Studio, llama.cpp, or another trusted OpenAI-compatible server. You must set the real context window yourself when the server cannot report it safely. See [Local models](local-models.md).
+
+## Azure OpenAI setup
+
+Azure requires:
+
+```json
+{
+  "provider": "azure_openai",
+  "azure_openai_endpoint": "https://example.openai.azure.com",
+  "azure_openai_model": "production-gpt",
+  "azure_openai_api_version": "2025-04-01-preview"
+}
+```
+
+The endpoint must use HTTPS and cannot contain URL credentials, a query, or a fragment. The model value is the Azure deployment name. Kward does not attempt deployment discovery using an inference key.
+
+## Model discovery and filtering
+
+Kward combines several sources so a temporary catalog failure does not lock you out:
+
+1. refreshed live metadata, when the provider exposes model discovery;
+2. the last private local cache;
+3. conservative curated choices, where Kward has them;
+4. the currently configured model;
+5. a manual ID entered in `/model`.
+
+When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others. Empty or incomplete metadata stays visible. Use **Show all models** for embedding, preview, private, or unusually described models.
+
+Model discovery proves that an ID exists; it does not guarantee account access, tool support, image support, context size, pricing, or regional availability. Provider errors remain authoritative.
+
+## OAuth availability
+
+Kward supports browser OAuth for ChatGPT/Codex and Anthropic, plus interactive GitHub login for Copilot. RPC can initiate OpenAI and Anthropic OAuth; Copilot OAuth remains CLI-only.
+
+OpenRouter documents an official [OAuth PKCE flow](https://openrouter.ai/docs/guides/overview/auth/oauth), but Kward has not implemented it. xAI's public [API quickstart](https://docs.x.ai/developers/quickstart) documents API keys rather than a stable third-party subscription OAuth flow. Kward reports both limitations explicitly instead of presenting a login that cannot be completed safely.
+
+## RPC clients
+
+RPC clients should discover providers rather than hard-code this table:
+
+- `auth/providers` returns catalog providers and supported authentication methods;
+- `auth/status` returns sanitized configured/source state;
+- `models/list` returns known model entries;
+- `models/refresh` refreshes a provider when supported;
+- `models/set` selects the provider and model.
+
+See the [RPC protocol](rpc.md#Config_and_auth_methods) for request shapes and unsupported OAuth capability reporting.

data/doc/releasing.md

@@ -1,8 +1,12 @@
 # Releasing Kward
 
+## Before you begin
+
 Kward requires Ruby >= 3.4 (`spec.required_ruby_version` in `kward.gemspec`). If you develop with a newer Ruby, verify tests pass against the minimum supported version before releasing.
 
-Release steps before publishing:
+## Prepare the release
+
+Before publishing:
 
 1. Update `CHANGELOG.md` for the version. Move `[Unreleased]` entries under a new version heading.
 2. Update `Kward::VERSION` in `lib/kward/version.rb`.
@@ -41,7 +45,9 @@ Release steps before publishing:
 
 8. Install the built gem locally and smoke test the `kward` executable in a clean workspace.
 
-Commit the version bump and create a git tag:
+## Tag and publish
+
+Commit the version bump and create a Git tag:
 
 ```bash
 git commit -am "Bump to VERSION"
@@ -57,6 +63,8 @@ gem push kward-VERSION.gem
 
 RubyGems MFA is required for publishing. Prefer RubyGems trusted publishing for automated releases if CI publishing is added later, so long-lived API keys do not need to be stored in CI secrets.
 
+## If you need to yank a release
+
 If a published gem has a serious problem, you can yank it within 24 hours of pushing:
 
 ```bash

data/doc/rpc.md

@@ -1,12 +1,25 @@
-# Kward RPC Protocol
+# Kward RPC protocol
 
 <div class="kward-no-toc"></div>
 
-Kward RPC is a JSON-RPC backend protocol for trusted local UI clients. It is versioned as protocol version `1`: new methods and fields may be added in compatible releases, and clients should ignore unknown fields. Removing or changing existing methods or field meanings requires a protocol version bump. Individual capability groups may still report unsupported status in `initialize.capabilities`.
+Use Kward RPC to build a trusted local interface around Kward's sessions, models, tools, and streaming turns. This page is for people building UI clients or integrations; if you use Kward only from the terminal, you can skip it.
 
-This page is for people building UI clients or integrations. If you use Kward from the terminal, you can skip it.
+The protocol uses JSON-RPC and is currently version `1`. Compatible releases may add methods and fields, so clients should ignore fields they do not recognize. Removing a method or changing the meaning of an existing field requires a protocol version bump. Individual capability groups may still report that they are unsupported in `initialize.capabilities`.
 
-Prompt history search is a CLI terminal feature only. RPC clients own their composer/input UX and Kward does not currently expose prompt-history read, append, or search methods over RPC.
+## Build a client
+
+A typical client launches the server, sends `initialize`, creates or resumes a session, starts a turn, and renders `turn/event` notifications. Use these sections for the next step:
+
+| You need to... | Start here |
+| --- | --- |
+| Connect and negotiate capabilities | [Launch](#Launch), [Framing](#Framing), and [Initialization](#Initialization) |
+| Open, resume, branch, or export a conversation | [Session methods](#Session_methods) |
+| Send input and render a response | [Turn methods](#Turn_methods) and [Turn notifications](#Turn_notifications) |
+| Handle tool approval or structured questions | [Tool approval bridge](#Tool_approval_bridge) and [UI question bridge](#UI_question_bridge) |
+| Show model, runtime, auth, or configuration controls | [Runtime methods](#Runtime_methods), [Model methods](#Model_methods), and [Config and auth methods](#Config_and_auth_methods) |
+| Discover tools, MCP servers, prompts, skills, or plugins | [Tool and prompt methods](#Tool_and_prompt_methods) |
+
+Prompt history search is a CLI terminal feature only. RPC clients own their composer/input UX and Kward does not expose prompt-history read, append, or search methods over RPC.
 
 ## Launch
 
@@ -47,31 +60,31 @@ Result fields:
 - `experimental`: `false`.
 - `capabilities`: includes frontend-neutral capability groups.
 
-Detailed capability fields include:
+Read `capabilities` at runtime instead of assuming every feature is available. Its groups describe:
 
 - `transcript`: Kward transcript format support, including normalized messages, image/tool support, compaction summaries, and restored assistant reasoning as Pi-compatible `thinking` content blocks.
-- `sessions`: explicit RPC session mode, JSONL persistence, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, active live-session discovery, supported linear-session fork methods, supported compaction, supported tree navigation with labels and branch summarization, explicit unsupported import support, and unsupported live session updates reported with `notification: "session/updated"`.
-- `turns`: async turn mode, per-session concurrency, active/recent turn listing, provider-gated native busy-input steering, queued follow-up input, best-effort cancellation, recent in-memory event replay behavior, per-turn options for model/reasoning/tool scope/tool approval, and structured client context for editor integrations.
-- `pluginChats`: optional plugin-owned chats. The capability lists opted-in chat types and methods. Clients must explicitly subscribe before receiving `pluginChat/event` notifications; plugin chats are independent from workspace sessions.
-- `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, tool update/result events, diff result support, configured workspace guardrail status, focused context and context-budget stats tool support, and explicit unsupported shell changed-file detection/session update flags.
+- `sessions`: explicit RPC session mode, JSONL persistence, and methods for listing, auto-resume, live-session discovery, linear forking, compaction, and labeled tree navigation with branch summaries. Import is unsupported. Live session updates are also unsupported but reserve the `session/updated` notification name. Git worktree bindings are reported as interactive-TUI-only.
+- `turns`: asynchronous turns, per-session concurrency, active and recent turn lists, busy-input steering when the provider supports it, queued follow-ups, best-effort cancellation, and recent in-memory event replay. Per-turn options cover model, reasoning, tool scope, and tool approval, with structured client context for editor integrations.
+- `pluginChats`: optional plugin-owned chats. The capability lists opted-in chat types and methods. Clients must explicitly subscribe before receiving `pluginChat/event` notifications; plugin chats are independent from workspace sessions. A type may also report `transport: true` when a trusted external transport is allowed to target it; RPC opt-in and external transport opt-in remain separate.
+- `events`: the `turn/event` contract, assistant and reasoning events, normalized tool metadata, tool updates and results, diff support, workspace guardrail status, focused-context and context-budget statistics tools, and explicitly unsupported shell changed-file and session-update flags.
 - `attachments`: supported input attachment contract for `turns/start`, with accepted base64 image MIME types and a stable max byte value.
-- `models`: model/reasoning RPC methods, explicit OpenRouter catalog listing, exposed model fields, and no scoped model support.
-- `runtime`: supported state/stats methods with message-count stats and OpenAI/Codex context usage. Cumulative token and cost stats are not computed.
+- `models`: model listing, refresh, selection, and exposed metadata across providers. Scoped model selection is not supported.
+- `runtime`: runtime state, message-count statistics, and OpenAI/Codex context usage. Kward does not yet compute cumulative token or cost statistics.
 - `lifecycleHooks`: supported lifecycle hook events, decisions, command/plugin/workspace/HTTP/async hook availability, audit log path, hook approval routing through tool approval, and hook notifications (`hook/event`, `hook/message`).
 - `runtimeSettings`: live `runtime/updateSetting` support for `defaultModel` and `defaultThinkingLevel`, plus `runtime/reload`.
-- `auth`: Kward auth provider format, OpenAI and Anthropic OAuth, OpenRouter API-key login, GitHub/Copilot status reporting, and provider logout for stored credentials. GitHub OAuth login is CLI-only; RPC reports `supported: false` for the GitHub provider with a reason string.
+- `auth`: available providers and authentication methods, private API-key storage, sanitized status, and logout. OpenAI and Anthropic OAuth are supported; Copilot OAuth is CLI-only, OpenRouter PKCE is not implemented, and xAI has no supported stable third-party flow.
 - `memory`: opt-in structured memory support, interactive prompt injection only, JSON/JSONL local storage, and dedicated `memory/*` methods.
 - `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns.
 - `skillCapture`: capture a reviewed personal `SKILL.md` from any saved session’s active branch through `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`.
-- `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns and advertises discovery with `methods: ["tools/list", "mcp/status"]`, `toolMetadata: true`, and `serverStatus: true`. MCP resources, prompts, sampling, and Streamable HTTP are explicitly unsupported for now.
+- `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns and advertises discovery with `methods: ["tools/list", "mcp/status"]`, `toolMetadata: true`, and `serverStatus: true`. It does not support MCP resources, prompts, sampling, or Streamable HTTP.
 - `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
 - `extensionUi`: question bridge support via `ui/question` and `ui/answerQuestion`, plus plugin footer updates via `ui/footer`; other UI primitives are explicitly unsupported.
 - `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access.
-- `security`: trusted-local behavior with optional per-turn tool approval. By default there is no workspace mutation guard or tool approval and shell/file mutation can run. File-tool workspace guardrails are reported under `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`. `security.sandbox` reports the configured command-worker sandbox mode, enforcement backend, filesystem/network capability, and explicitly unsupported session pinning and one-time elevation. See [Command sandboxing](sandboxing.md) for its scope and limits.
+- `security`: trusted-local behavior and optional per-turn tool approval. By default, RPC turns have no workspace mutation guard or tool approval, so shell commands and file changes can run. Clients can inspect file-tool guardrails through `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`. `security.sandbox` reports the command sandbox mode, enforcement backend, and filesystem and network capabilities; session pinning and one-time elevation are unsupported. See [Command sandboxing](sandboxing.md) for the boundary and its limits.
 - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
 - `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
 - `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell` is the local embedded TUI shell.
-- `logging`: local redacted telemetry logging support, the log directory, enabled categories, `methods: ["logging/stats", "logging/tokenCsv"]`, `usageCsv` sub-capability with bucket support, JSONL format, rotation (10 MB, manual retention), config key `logging`, env prefix `KWARD_LOGGING`, and redacted-metadata-only content.
+- `logging`: local redacted telemetry, its directory and enabled categories, `logging/stats` and `logging/tokenCsv`, bucketed `usageCsv` support, JSONL storage, and 10 MB rotation with manual retention. Logs contain redacted metadata only. Configuration uses the `logging` key and `KWARD_LOGGING` environment prefix.
 
 ### `shutdown`
 
@@ -120,7 +133,7 @@ Params:
 - `name`: optional session name.
 - `resumeLast`: optional boolean. Defaults to the configured `sessions.auto_resume` behavior when omitted by clients that use `sessions/create` for startup. `false` forces a fresh session.
 
-Creates a persisted Kward session and returns session metadata. The response includes `activePersonaLabel` so clients can render the correct avatar immediately. When `resumeLast` is enabled, no `name` is provided, and `sessions.auto_resume` is `true`, Kward resumes the remembered last session for the workspace instead of creating a fresh file; that auto-resume response also includes `resumed: true` and normalized `messages` so clients do not need to briefly render a fresh avatar while fetching transcript state.
+Creates a persisted Kward session and returns its metadata. The response includes `activePersonaLabel` so clients can render the correct avatar immediately. If `resumeLast` and `sessions.auto_resume` are both enabled and no `name` is provided, Kward resumes the last session remembered for the workspace. That response includes `resumed: true` and normalized `messages`, allowing clients to render the restored transcript immediately.
 
 ### `sessions/resume`
 
@@ -171,7 +184,7 @@ Returns:
 ```json
 {
   "summary": "Compaction summary",
-  "firstKeptEntryId": "message:2",
+  "firstKeptEntryId": "a13f8c42b7d94e10c5f8a3b6d2e9f401",
   "tokensBefore": 1234,
   "details": {
     "read_files": [],
@@ -193,12 +206,12 @@ Returns forkable user-message entries for the active session:
 ```json
 {
   "messages": [
-    { "entryId": "message:0", "text": "User message text" }
+    { "entryId": "a13f8c42b7d94e10c5f8a3b6d2e9f401", "text": "User message text" }
   ]
 }
 ```
 
-`entryId` values are stable message-index IDs within the linear session. `text` is compact display text.
+`entryId` values are opaque, stable persisted tree-entry IDs. Clients must use the IDs returned by Kward rather than constructing them. `text` is compact display text.
 
 ### `sessions/fork`
 
@@ -549,7 +562,7 @@ Refreshes config-backed runtime state and returns `{ "ok": true, "message": "Res
 
 ## Logging methods
 
-The `logging` capability reports local redacted telemetry logging support, the log directory, enabled categories, `methods: ["logging/stats", "logging/tokenCsv"]`, `usageCsv` sub-capability with bucket support, JSONL format with 10 MB rotation and manual retention, config key `logging`, env prefix `KWARD_LOGGING`, and redacted-metadata-only content. Logging methods require logging to be enabled by config or environment for at least one category.
+Check the `logging` capability to see whether local redacted telemetry is available. It reports the log directory, enabled categories, supported methods, bucketed CSV support, JSONL storage, and 10 MB rotation with manual retention. Logs contain redacted metadata only. Configure logging with the `logging` key or `KWARD_LOGGING` environment prefix, and enable at least one category before calling these methods.
 
 ### `logging/stats`
 
@@ -559,7 +572,7 @@ Params:
 
 Accepted units are minutes, hours, days, weeks, months, and years. Ranges use UTC calendar periods: `1 month` means the current calendar month so far, and `2 months` means the previous month plus the current month so far. Invalid ranges return an invalid-params error with usage text.
 
-Returns structured stats for enabled categories only, including the requested range, log directory, record counts by category/event, `usageStats` token totals, performance duration summaries, tool call summaries, and error counts by event/class/provider/code. Error messages are not included in the stats response.
+Returns statistics for enabled categories over the requested range. The response includes the log directory, record counts by category and event, `usageStats` token totals, performance durations, tool call summaries, and error counts by event, class, provider, and code. It does not include error messages.
 
 ### `logging/tokenCsv`
 
@@ -682,7 +695,15 @@ Returns `{ "memories": [] }`.
 
 ### `models/list`
 
-Returns known model entries from the current client/config backend. OpenRouter entries come from the local OpenRouter model cache when present; otherwise Kward falls back to defaults/currently configured options. Refresh the cache with the CLI-only `kward openrouter refresh` command. Entries use `{ "provider", "id", "name", "reasoning", "reasoningEffort", "contextWindow", "current" }`.
+Returns known model entries from configured provider catalogs, including cached and curated fallbacks. Entries use `{ "provider", "id", "name", "reasoning", "reasoningEffort", "contextWindow", "current" }`.
+
+### `models/refresh`
+
+Params:
+
+- `provider`: optional configured provider name. Defaults to the active provider.
+
+Refreshes that provider's live model catalog when discovery is supported and returns the complete sanitized model list. Providers without live discovery retain configured or curated choices.
 
 ### `models/current`
 
@@ -693,7 +714,7 @@ Returns the current model entry with `provider`, `id`, `name`, `reasoning`, `rea
 Params:
 
 - `model`: model ID string.
-- `provider`: optional provider hint, currently `Codex` or `OpenRouter`; defaults to the active provider.
+- `provider`: optional provider name or catalog ID; defaults to the active provider.
 
 Updates the config-backed provider model and returns the current model payload.
 
@@ -793,30 +814,32 @@ Params:
 
 - `values`: object of config keys and values.
 
-Updates config, including secret values, and returns a redacted config object. The stored file contains the supplied values.
+Updates non-secret config and returns a redacted config object. Provider API-key fields are rejected; use `auth/loginWithApiKey` so keys go to private credential storage.
 
 ### `auth/status`
 
-Returns whether OpenAI OAuth, Anthropic OAuth, OpenAI access token env, and OpenRouter API key env/config are available.
+Returns sanitized status plus catalog provider entries. It reports configured/source booleans but never credential values.
 
 ### `auth/providers`
 
-Returns frontend-neutral provider cards for OpenAI OAuth, Anthropic OAuth, OpenRouter API-key auth, and GitHub/Copilot status. Provider cards report whether credentials are configured, whether they came from stored config or environment variables, and whether stored credentials can be removed.
+Returns every catalog provider with `runtimeId`, `configured`, `source`, `canLogout`, and `authMethods`. Each auth method reports `id` (`api_key` or `oauth`), `supported`, `configured`, optional `source`, callback support, and an explicit reason when unsupported. Clients should discover this response dynamically; [Model providers](providers.md) is the corresponding human-readable reference.
 
 ### `auth/loginWithApiKey`
 
 Params:
 
-- `providerId`: currently `openrouter`.
-- `apiKey`: API key secret.
+- `providerId`: any catalog provider that accepts API keys;
+- `apiKey`: API key secret;
+- `configuration`: required for Azure OpenAI, with `endpoint`, `deployment`, and `apiVersion`.
 
-Stores the API key with `0600` file permissions, refreshes client config, and returns a redacted message payload. Secret values are not returned.
+Stores the key in private `<config-dir>/api_keys.json`, refreshes client config, and returns only provider/method/status metadata. Keys and raw sensitive provider responses are never returned.
 
 ### `auth/logoutProvider`
 
 Params:
 
-- `providerId`: `openai`, `anthropic`, or `openrouter`.
+- `providerId`: catalog provider ID;
+- `authMethod`: optional `api_key` or `oauth`; omitting it removes all stored methods Kward can remove for that provider.
 
 Removes stored credentials only. Environment variables remain active and are still reported by `auth/providers`.
 
@@ -827,7 +850,7 @@ Params:
 - `providerId`: currently `openai` or `anthropic`.
 - `timeoutSeconds`: optional callback wait timeout.
 
-Provider-scoped wrapper around the OpenAI or Anthropic OAuth flow. The result includes `providerId`, `loginId`, `authorizationUrl`, `redirectUri`, and `status`.
+Provider-scoped wrapper around the OpenAI or Anthropic OAuth flow. The result includes `providerId`, `loginId`, `authorizationUrl`, `redirectUri`, and `status`. Copilot is reported as CLI-only. OpenRouter's official PKCE flow is not yet implemented by Kward, and xAI has no supported stable third-party OAuth flow; both return explicit sanitized unsupported errors.
 
 ### `auth/startOpenAILogin`
 

data/doc/sandboxing.md

@@ -63,6 +63,28 @@ Changes apply to newly created sessions and tabs. Existing turns keep the
 workspace and command runner they started with, so start a new session or tab
 after changing the mode.
 
+## Worktree tabs
+
+An active worktree-backed tab uses a strict `workspace_write` policy for its
+model-requested command workers, regardless of the global `sandbox.mode` or
+`tools.workspace_guardrails` settings. The writable root is exactly the linked
+worktree and no configured additional writable roots are carried into the tab.
+The configured child-network setting is preserved.
+
+If the current platform cannot provide filesystem enforcement, Kward refuses to
+activate the worktree instead of falling back to an unrestricted command
+worker. The strict agent also disables configured MCP clients and lifecycle
+hooks because they run in the Kward host process rather than inside the command
+sandbox.
+
+This does not contain the interactive `/shell`, `!command`, or `/pty` features;
+those are user-directed host-process operations. Generic model-requested shell
+commands still cannot write Git metadata. Active worktree tabs additionally
+expose a narrow `git_commit` tool for explicit agent-requested commits; it runs
+through the trusted host-side Git workflow rather than widening the shell
+sandbox. The interactive `/git` flow remains available for manual review and
+commit.
+
 ## Platform support
 
 | Platform | Backend | Status |