kward 0.78.0 → 0.80.0

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
 
-Kward requires Ruby >= 3.2 (`spec.required_ruby_version` in `kward.gemspec`). If you develop with a newer Ruby, verify tests pass against the minimum supported version before releasing.
+## Before you begin
 
-Release steps before publishing:
+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.
+
+## 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,30 +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.
-- `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.
+- `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`. 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`: 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`
 
@@ -119,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`
 
@@ -170,7 +184,7 @@ Returns:
 ```json
 {
   "summary": "Compaction summary",
-  "firstKeptEntryId": "message:2",
+  "firstKeptEntryId": "a13f8c42b7d94e10c5f8a3b6d2e9f401",
   "tokensBefore": 1234,
   "details": {
     "read_files": [],
@@ -192,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`
 
@@ -548,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`
 
@@ -558,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`
 
@@ -681,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`
 
@@ -692,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.
 
@@ -745,6 +767,16 @@ Params:
 
 Returns frontend-neutral slash command metadata for configured prompt templates, skills, and plugins. Prompt command names omit the leading slash. Skill command names use `skill:<name>`. Plugin command names omit the leading slash and include `executable: true`. Builtin terminal-only commands are omitted. Prompt commands can be submitted directly to `turns/start` as slash commands or expanded first with `prompts/expand`; plugin commands can be submitted to `turns/start` or run explicitly with `commands/run`.
 
+### `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`
+
+Use this two-step workflow to capture a personal skill from a saved session:
+
+1. Call `skills/captureSessions` to list available persisted session sources.
+2. Call `skills/captureDraft` with `sessionPath`. Kward sends the selected active branch, including available raw tool output, to the active model provider and returns an editable `SKILL.md` draft. It rejects a source that exceeds the active model context rather than truncating it.
+3. Review and edit `content`, then call `skills/saveCapturedDraft`. Set `overwrite: true` only after explicitly confirming replacement of an existing personal skill.
+
+Captured skills are saved under the Kward config directory, are not activated automatically, and no file is written until the final save call succeeds.
+
 ### `resources/startup`
 
 Params:
@@ -782,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`.
 
@@ -816,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

@@ -0,0 +1,142 @@
+# Command sandboxing
+
+Kward can optionally apply an operating-system sandbox to model-requested
+`run_shell_command` calls. The sandbox is a technical boundary for the command
+and every process it starts; it is separate from Kward's [permission
+policy](permissions.md), which decides whether Kward should start a tool at all.
+
+Sandboxing is **off by default**. When you request a non-off mode and Kward
+cannot enforce it on the current platform, the command is denied rather than
+run without the requested boundary.
+
+## Configure a command sandbox
+
+Add a `sandbox` section to your user config, normally `~/.kward/config.json`:
+
+```json
+{
+  "sandbox": {
+    "mode": "workspace_write",
+    "network": "deny",
+    "writable_roots": [],
+    "protect_git_metadata": true
+  }
+}
+```
+
+Available modes are:
+
+| Mode | Command filesystem writes |
+| --- | --- |
+| `off` | Existing unrestricted command behavior. |
+| `read_only` | Workspace writes are denied. Kward gives the command a private temporary directory for command-local scratch files. |
+| `workspace_write` | Writes are allowed in the active workspace and the private command temporary directory. |
+
+`writable_roots` lets you grant additional, existing host paths to commands in
+`workspace_write` mode—for example, a known local build cache. Configure these
+paths only in your user config. Do not add a path merely because a repository
+instruction or model response asks for it. `protect_git_metadata` defaults to
+`true`; this prevents sandboxed commands from changing `.git`, including
+staging and committing changes.
+
+`network` controls child-process network access:
+
+| Value | Child-process network access |
+| --- | --- |
+| `deny` | Denied by the operating-system backend. This is the default. |
+| `allow` | Allowed with the same network reachability as your user account. |
+
+## Interactive controls
+
+Use `/sandbox` in the terminal UI to inspect or update the global policy:
+
+```text
+/sandbox status
+/sandbox read_only
+/sandbox workspace_write
+/sandbox off
+/sandbox network deny
+/sandbox network allow
+```
+
+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 |
+| --- | --- | --- |
+| macOS | Seatbelt through `/usr/bin/sandbox-exec` | Supported for command workers. Kward checks availability at runtime. |
+| Linux | Bubblewrap | Supported when `bwrap` can create the required namespaces. |
+| Windows | None | Unsupported. A requested non-off policy fails closed. |
+
+On Debian or Ubuntu, install Bubblewrap with `sudo apt install bubblewrap`; on
+Fedora, use `sudo dnf install bubblewrap`. A present `bwrap` executable can
+still be prevented from creating namespaces by host policy. In that case,
+Kward fails the command closed instead of running it unrestricted.
+
+The macOS `sandbox-exec` utility is deprecated by Apple. Kward therefore treats
+it as a capability-detected backend and verifies enforcement with platform
+integration tests. It is not a promise that future macOS releases will retain
+this interface.
+
+## Boundaries and limits
+
+The current implementation protects **model-requested command workers only**.
+It does not sandbox:
+
+- the Kward Ruby host process;
+- model-provider, search-provider, or RPC traffic;
+- trusted Ruby plugins;
+- MCP servers, lifecycle hooks, `/shell`, `!command`, or `/pty`.
+
+Sandboxed command workers receive a minimal environment: Kward preserves only
+basic terminal, locale, and path variables, then supplies a private `HOME` and
+temporary directory. Credentials and runtime-injection variables are not
+inherited. On macOS, Seatbelt also denies reads from common credential locations
+under the host home directory, including `.kward`, `.ssh`, `.aws`, `.gnupg`, and
+selected cloud/CLI configuration directories.
+
+This is defense in depth, not complete secret-file read isolation: commands
+still receive system and development-tool reads needed for normal local work.
+On Linux, Bubblewrap provides a read-only view of the host filesystem outside
+its explicitly writable paths; it does not hide every file your account can
+read. For sensitive repositories, use a disposable checkout, VM, or container
+in addition to Kward's command sandbox.
+
+The RPC `initialize.capabilities.security.sandbox` payload reports the active
+mode, backend, and whether filesystem and child-network enforcement are active.
+It also reports unsupported features, including session pinning and one-time
+sandbox elevation; those are not available yet.
+
+## Related guides
+
+- [Security and trust](security.md) explains Kward's broader trust boundaries.
+- [Permissions](permissions.md) controls whether Kward starts a model-requested
+  tool; it does not constrain a command after it starts.
+- [Configuration](configuration.md#Command_sandboxing) covers the full config
+  section, while [Workspace tools](workspace-tools.md) explains the separate
+  file-tool guardrails.