kward 0.79.0 → 0.80.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79174a2cb7441a44857a53568078c50b2c7735d7a8f7507ce6e8d1199f8b37fa
-  data.tar.gz: c83fda7c64aea1ad5f8af38c5ee0bb1d0c56a3c05efa3457c02fcd5b3049cb99
+  metadata.gz: e9128f608c2a864ad996598d285d4042758ea1bc1b3a76a1224984ef23129544
+  data.tar.gz: c9d718290398f95e1420e5e12225e43aaba6bf6c64c868fb6d175d5725aaf19d
 SHA512:
-  metadata.gz: 9088afe9fb4976a8a40ec08a0297ee99d075f9df756465f68e04482c55f5fbb1d5b0b8d5e20b880d258253d8e015ce91b745a1db57c3ce03374b912d4fc109fe
-  data.tar.gz: 7452c7d1674338e52b3216f648b798f9181cf421db840bc54a74270acebd40c1aa67aa1c2dbbfaea322908cd50344e34500a79cb68033bdfc1fa62642cefbf20
+  metadata.gz: 6b0e53fddfa2de055b11b6bbe0965496e2abc860162ed0888642bb353ae64e0e0fdbfbe14ed7412198c8c60583c1d55fd6d9cd7fec7a43eb37db456a494f5a1a
+  data.tar.gz: 2396aceedf67453422924616d92031160d3eee67ae448347d2f367a05d48a97d9ae39789b2100c3c47bdbc5925c85e4922146a50c72ee662d863f8ad597dacbd

data/.github/workflows/ci.yml

@@ -30,6 +30,12 @@ jobs:
       - name: Install sandbox test dependency
         run: sudo apt-get update && sudo apt-get install --yes bubblewrap
 
+      - name: Enable Bubblewrap namespaces
+        run: |
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+          sudo sysctl -w kernel.unprivileged_userns_clone=1
+          bwrap --ro-bind / / --unshare-net true
+
       - name: Check syntax
         run: find lib test -name '*.rb' -print0 | xargs -0 ruby -c
 

data/CHANGELOG.md

@@ -2,7 +2,64 @@
 
 All notable changes to Kward will be documented in this file.
 
-## [Unreleased]
+## [0.80.0] - 2026-07-27
+
+### Added
+
+- Added HTML/Ruby syntax highlighting and common-block auto-indentation for `.erb` files in the integrated editor.
+- Added catalog-based API-key login and model selection for OpenAI, Anthropic, Azure OpenAI, Gemini, Cerebras, DeepSeek, Fireworks AI, Groq, Mistral, NVIDIA NIM, OpenRouter, Together AI, and xAI, with private credential storage and live/cached/curated model catalogs.
+- Added native streaming runtimes for the OpenAI Responses API, Google Gemini, and Azure OpenAI, including tool calls, usage metadata, retries, cancellation, and secret redaction.
+- Added RPC parity for provider/auth-method discovery, sanitized credential status, API-key login/logout, model refresh, and provider/model selection.
+- Added a dedicated model-provider guide with the canonical provider list, runtime IDs, authentication, model configuration, discovery behavior, and limitations.
+- Added a prompt-template guide, including template creation, slash-command expansion, and the starter templates installed by `kward init`.
+- Added a Stardate footer plugin example for the interactive CLI.
+- Added a general transport plugin API with normalized messages and events, persistent transport state, policy checks, managed lifecycle, foreground CLI commands, and RPC capability/status reporting.
+- Added a first-party Telegram long-polling transport example with fixed-workspace routing, numeric allowlists, idempotent updates, message chunking, and interactive approval/question buttons.
+- Added packaged plugin entrypoints under `~/.kward/plugins/*/plugin.rb` for multi-file trusted plugins.
+- Added generic transport execution profiles and an isolated Telegram chat transport with no tools, plugin commands, memory, attachments, or interactions.
+- Added a shared scoped plugin-chat runtime and `Transport::Host#plugin_chats` for explicitly transport-capable plugin chats, including actor context, event replay, cancellation, and separate transport/RPC access.
+- Added transport-only plugin chats with `local: false`, keeping externally targeted plugin chats out of local tab opening and restoration.
+- Added Git worktree bindings for normal interactive session tabs. `/tab worktree` can move a tab into a strict linked-worktree workspace after research, preserve its transcript, warn about dirty origin changes, and keep the branch available when explicitly detached.
+- Added the active worktree `git_commit` model tool, allowing explicitly requested agent commits through the trusted host-side Git workflow without widening the shell sandbox.
+- Added `/tab worktree merge` for explicitly merging a clean worktree branch into the branch checked out in its original workspace, plus `/tab worktree merge abort` for conflicted merges.
+- Added `j`/`k` keyboard navigation to the `/files` project browser.
+- Added `h`/`l` keyboard navigation for collapsing and expanding `/files` directories.
+- Added `j`/`k` keyboard navigation to the `/git` changed-file overlay.
+
+### Changed
+
+- Avoided copying bounded transcript buffers into idle tab snapshots while preserving intentional full-conversation scrollback replay when those tabs are revisited.
+- Kept the TUI transcript buffer under its existing limit while trimming to a safe low watermark instead of copying the full buffer after every appended character.
+- Reduced integrated-editor layout work by caching line starts and calculating the cursor line once per rendered frame.
+- Limited interactive plugin footer evaluation to its authoritative one-second refresh interval and reused the cached value between refreshes.
+- Made interactive plugin canvases publish only complete frames submitted with `ui.render`, skip unpublished ticks, and follow terminal width changes.
+- Avoided rebuilding and flushing the TUI composer when tab labels and selection have not changed.
+- Reduced interactive streaming overhead by writing each labeled TUI delta in one synchronized prompt transaction.
+- Highlighted the current editor line number in white while keeping the rest of the line-number gutter green.
+- Made `/model` provider-aware with refresh, manual model IDs, capability-filtered defaults, Show all, and provider switching while preserving Codex, Copilot, OpenRouter, and local models.
+- Kept direct OpenAI API credentials (`openai_api`) separate from ChatGPT/Codex OAuth so both can be configured at once.
+- Azure OpenAI setup now validates HTTPS endpoints, deployment names, and API versions, and treats the configured deployment as the selectable model.
+- Updated current documentation to describe Copilot and the JSON-RPC backend as supported features rather than experimental ones.
+- Clarified the distinct roles of workspace guardrails, tool permissions, and command sandboxing.
+- Reorganized the README documentation index and clarified generated Ruby API support boundaries.
+- Added task-oriented navigation to the RPC and configuration references.
+- Standardized MCP support and limitation wording across the user and RPC guides.
+- Reframed the README introduction around Kward as an Agentic Development Environment (ADE) with opt-in safety controls.
+- Moved the local-model setup guide to the generated documentation Integrate navigation.
+- Added the Telegram transport deployment guide to the generated documentation navigation.
+- Replaced implicit `/tab worktree` detachment with explicit `/tab worktree detach`; running `/tab worktree` again now leaves an active worktree enabled.
+- Added workspace overrides for foreground transports via `kward transport run NAME WORKSPACE` and the global `--working-directory` option.
+- The `/files` project-browser now uses full terminal height if there are enough files to fill that space
+
+### Fixed
+
+- Prevented a stopped tab live-view thread from resuming against a newly active tab after a slow render.
+- Kept `@`/`$` completion, `/files`, prompt history, and the integrated editor rooted in the active worktree tab instead of the original checkout.
+- Fixed HTML and ERB editor highlighting so tag names, attributes, values, and tag fragments retain consistent colors across embedded Ruby expressions.
+- Refreshed composer diff and context usage status immediately when switching session tabs.
+- Prevented `/reload` from retaining stale prompt templates, so new and edited prompt files refresh slash-command completion and expansion.
+- Prevented session-picker rename input from filtering the visible session list.
+- Fixed session listing timestamps and ordering to ignore system-prompt and other metadata writes during session restoration.
 
 ## [0.79.0] - 2026-07-19
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.79.0)
+    kward (0.80.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -146,7 +146,7 @@ CHECKSUMS
   html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
   io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
   json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  kward (0.79.0)
+  kward (0.80.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/README.md

@@ -1,29 +1,16 @@
 # Kward
 
-Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run local shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.
+Kward is a coding agent for your terminal. It can inspect and edit a project, run commands, research problems, and save your work in sessions you can resume later.
 
-It supports the OpenAI/ChatGPT Codex backend, Anthropic Claude Pro/Max subscription, OpenRouter, experimental Copilot provider support, and OpenAI-compatible local servers such as Ollama, LM Studio, and llama.cpp.
+Use Kward from the terminal, its local browser interface, or a trusted JSON-RPC client. It works with ChatGPT/Codex and Claude subscriptions, hosted model APIs, GitHub Copilot, OpenRouter, and local servers such as Ollama, LM Studio, and llama.cpp.
 
-## Why use Kward?
+## Why Kward?
 
-Kward is designed for working with real projects, not isolated prompts.
+Software work rarely fits into one chat. A project can span days of research, implementation, debugging, review, and decisions worth keeping.
 
-Typical workflows include:
+Kward treats that work as an ongoing workspace rather than a disposable conversation. You can resume earlier sessions, split work across tabs and Git worktrees, and keep project guidance close to the code. Optional permissions, command sandboxing, and workspace boundaries give you more control when a task needs it.
 
-- Understanding an unfamiliar codebase
-- Investigating bugs
-- Reviewing changes
-- Refactoring code
-- Automating repetitive development tasks
-- Building custom agent workflows through plugins
-
-Examples:
-
-```bash
-kward "Explain this project"
-kward "Review this diff"
-kward "Find performance problems in this codebase"
-```
+Start with a normal coding conversation. If your workflow grows, you can add memory, reusable prompts and skills, local plugins, lifecycle hooks, MCP servers, transports, or a custom RPC client.
 
 ## Install
 
@@ -52,57 +39,63 @@ kward "Explain this project"   # run one prompt and exit
 kward --working-directory ~/code/project "Explain this project"
 ```
 
-From inside Kward, `/login` opens the same provider picker.
+From inside Kward, `/login` lets you choose API-key or subscription authentication across supported providers. `/model` then switches providers, refreshes model catalogs, or accepts a manual model/deployment ID. Direct OpenAI API credentials and ChatGPT/Codex OAuth can coexist.
 
-See [Authentication](doc/authentication.md) for more details about sign-in options and provider credentials.
+See [Model providers](doc/providers.md) to choose a backend and [Authentication](doc/authentication.md) for credential storage and login flows.
 
-## What Kward can do
+## Common ways to use Kward
 
-- Keep a multi-turn coding conversation in your terminal.
-- Read, write, and edit workspace files with read-before-write guardrails.
-- Run local shell commands from the workspace.
-- Search the live web and inspect cached public GitHub repositories.
-- Save, resume, clone, compact, and export sessions.
-- Extend the Agent with trusted Ruby plugins for custom commands, footer UI, prompt context, and transcript-event observers.
-- Use optional memory, personas, prompt templates, and skills.
-- Serve a JSON-RPC backend for trusted local UI clients.
+- Explore an unfamiliar codebase and keep useful discoveries for later sessions.
+- Investigate a bug, make a focused change, and run the related tests.
+- Review a diff, inspect the surrounding code, and commit from the terminal UI.
+- Work on several tasks at once with tabs, branches, and linked Git worktrees.
+- Teach Kward your project conventions with `AGENTS.md`, skills, prompt templates, and optional memory.
+- Add trusted local behavior through plugins, lifecycle hooks, MCP servers, transports, or JSON-RPC integrations.
 
 ## Documentation
 
-Start here:
+New to Kward:
 
 - [Getting started](doc/getting-started.md): first run, authentication choices, and basic commands.
 - [Usage](doc/usage.md): interactive chat, slash commands, sessions, tools, images, and Pan mode.
 - [Configuration](doc/configuration.md): config files, providers, models, web search, logging, and color output.
-- [Authentication](doc/authentication.md): OpenAI OAuth, Anthropic OAuth, OpenRouter API keys, and Copilot/GitHub setup.
+- [Authentication](doc/authentication.md): multi-provider API keys, OpenAI/Anthropic subscription OAuth, Azure setup, and credential safety.
+- [Model providers](doc/providers.md): compare providers and find their runtime IDs, model keys, environment variables, discovery behavior, and limitations.
+
+Work safely:
+
 - [Security and trust](doc/security.md): local permissions, external data flow, trusted extensions, and safe work in unfamiliar repositories.
 - [Permissions](doc/permissions.md): opt-in tool approval, write scopes, policy rules, and current limits.
 - [Command sandboxing](doc/sandboxing.md): opt-in OS-enforced boundaries for model-requested shell commands.
 - [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
 
-Feature guides:
+Everyday workflows:
 
 - [Sessions](doc/session-management.md): resume, clone, fork, rewind, compact, and navigate saved work.
 - [Interactive composer](doc/composer.md): use multiline input, completion, history, files, reasoning shortcuts, busy input, and images.
 - [Tabs](doc/tabs.md): keep several conversations open and run work in another tab.
 - [Project files](doc/files.md): browse, search, mention, open, and edit workspace files.
-- [Integrated Editor](doc/editor.md): open files from the shell or composer, edit in-place, and choose editor keybindings.
+- [Integrated editor](doc/editor.md): open files from the shell or composer, edit in-place, and choose editor keybindings.
 - [Git](doc/git.md): review changes, use the diff viewer, stage files, and commit from the interactive TUI.
 - [Shell](doc/shell.md): use `/shell`, the embedded Kward shell with aliases, completion, and per-tab state.
 - [Memory](doc/memory.md): opt-in core, soft, and session memory.
 - [Personas](doc/personas.md): configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
 - [Skills](doc/skills.md): add reusable instructions that load only for matching tasks.
+- [Prompt templates](doc/prompt-templates.md): create reusable slash prompts and use the starter templates installed by `kward init`.
 - [MCP servers](doc/mcp.md): connect trusted local Model Context Protocol tool servers.
 - [Pan mode](doc/pan.md): use the mobile-friendly browser interface on a trusted local network.
 - [Local models](doc/local-models.md): connect Ollama, LM Studio, or llama.cpp and use a minimal replacement prompt.
 
-Advanced:
+Extend and integrate:
 
-- [Extensibility](doc/extensibility.md): `PRINCIPLES.md`, workspace `AGENTS.md`, skills, prompt templates, and extension choices.
+- [Extensibility](doc/extensibility.md): choose between `PRINCIPLES.md`, workspace `AGENTS.md`, skills, prompt templates, and other extension points.
 - [Plugins](doc/plugins.md): trusted Ruby plugins for commands, footer UI, prompt context, transcript events, and RPC clients.
 - [Lifecycle hooks](doc/lifecycle-hooks.md): deterministic runtime hooks for policy, approvals, automation, and command-hook integrations.
 - [RPC protocol](doc/rpc.md): JSON-RPC backend mode for trusted local UI clients.
 - [Releasing](doc/releasing.md): release checklist for RubyGems publishing.
+
+Reference guides:
+
 - [Agent tools](doc/agent-tools.md): overview of model-callable tools, token-saving behavior, and tool categories.
 - [Workspace tools](doc/workspace-tools.md): local file, edit, and shell command tools.
 - [Context budgeting](doc/context-budgeting.md): focused context gathering, budgeted reads, output compaction, and token-saving history.
@@ -110,9 +103,9 @@ Advanced:
 - [Code search](doc/code-search.md): package lookup, GitHub repository cache, and external source reading for the code search agent tool.
 - [Context tools](doc/context-tools.md): skills, compacted output retrieval, and structured clarification questions.
 
-API reference:
+Generated Ruby API:
 
-- [API reference](doc/api.md): generated Ruby API entry points, indexes, and public API expectations.
+- [API reference](doc/api.md): generated Ruby API entry points, indexes, and supported API expectations.
 
 ## Development
 

data/doc/agent-tools.md

@@ -2,14 +2,13 @@
 
 Agent tools are the model-callable operations Kward uses to inspect projects, change files, run commands, search outside sources, and ask for clarification. Most users do not call these tools directly. You ask for an outcome in natural language, and Kward decides which tools are needed.
 
-Tools are part of Kward's safety and context-management boundary:
+Tools also enforce important boundaries:
 
-- schemas describe what the model is allowed to call,
-- Ruby tool objects validate and execute those calls,
-- workspace tools stay inside the active workspace by default (see [Configuration](configuration.md) for the guardrail setting),
-- file-changing tools require the file to be read first,
-- large outputs are bounded or compacted before they enter model context,
-- full tool outputs are kept in the session record for later inspection.
+- Kward validates every tool call before running it.
+- Workspace tools stay inside the active workspace by default (see [Configuration](configuration.md) for the guardrail setting).
+- File-changing tools require the file to be read first.
+- Large outputs are bounded or compacted before they enter model context.
+- Full tool outputs remain available in the session record for later inspection.
 
 ## Tool categories
 
@@ -22,7 +21,7 @@ Tools are part of Kward's safety and context-management boundary:
 
 ## How tools save tokens
 
-Kward tries to keep tool context useful without flooding the model. The built-in prompt tells Kward to start with focused context tools and escalate from outlines/previews to exact ranges before full-file reads:
+Kward tries to gather enough evidence without flooding the conversation. It usually starts with focused context tools, then moves from outlines and previews to exact ranges or full files only when needed:
 
 - `read_file` reads bounded line ranges, supports continuation with `offset` and `limit`, and accepts explicit `preview`, `outline`, `range`, and `full` modes with optional per-call byte budgets.
 - `context_for_task` builds a task-shaped bundle from ranked files, outlines, and matching excerpts within a caller-supplied byte budget.
@@ -32,9 +31,9 @@ Kward tries to keep tool context useful without flooding the model. The built-in
 - Repeated identical tool output is replaced with a short reference instead of being sent again.
 - Compacted outputs are stored as artifacts that can be reopened with `retrieve_tool_output`, including after resuming a saved session that contains the original tool execution record.
 
-When a tool output exceeds 12 KB, Kward compacts it before sending it to the model. The compactor preserves the first 40 and last 40 lines, keeps lines matching error, test, or search-result patterns with 2 lines of surrounding context, and replaces omitted sections with `[... omitted lines ...]` markers. Shell command output is section-aware: STDOUT and STDERR sections are compacted separately. Compacted outputs include a header with the original and compacted byte counts and the artifact ID for retrieval. Error outputs under 8 KB are left intact so failure details stay visible.
+When output exceeds 12 KB, Kward keeps the most useful sections in context and stores the original output for later retrieval. The compacted result includes an artifact ID, so Kward can reopen an exact section without repeating the tool call. Error output under 8 KB stays intact so useful failure details are not lost.
 
-This lets the assistant reason from focused evidence while preserving access to original outputs when needed. For a fuller overview of Kward's context budgeting and token-saving work, see [Context budgeting](context-budgeting.md).
+See [Context budgeting](context-budgeting.md) for the full compaction strategy, limits, and token-saving workflow.
 
 ## How tools are exposed
 

data/doc/api.md

@@ -1,8 +1,8 @@
 # API reference
 
-Kward's generated Ruby API documentation is mainly for contributors, plugin authors, tool authors, and people building RPC or editor integrations.
+Kward's generated Ruby API documentation is for contributors, plugin authors, tool authors, and people building RPC or editor integrations.
 
-If you use Kward from the terminal, start with the [user guides](file.README.html#Documentation) instead. The API reference exposes many internal classes because it is generated from the source tree; not every documented class is a stable extension API.
+If you use Kward from the terminal, start with the [user guides](file.README.html#Documentation). This reference also includes internal classes and methods that may change. Treat the behavior described in the guides, the Plugin DSL, and the methods in the [RPC protocol](rpc.md) as Kward's supported public interfaces.
 
 ## Start here
 
@@ -84,7 +84,7 @@ The generated comments focus on these supported extension boundaries rather than
 
 ## Public API expectations
 
-Kward is still evolving. The generated reference is useful for understanding the codebase, but it should not be read as a promise that every class, method, or constructor is public and stable.
+The generated reference is useful for understanding the codebase, but it does not make every class, method, or constructor a supported public API.
 
 Prefer the documented guides for supported extension behavior. Use generated class and method pages when you need implementation detail, are contributing to Kward itself, or are coordinating a frontend integration with the current codebase.
 

data/doc/authentication.md

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

data/doc/code-search.md

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

data/doc/composer.md

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