kward 0.70.0 → 0.71.0

data/doc/authentication.md

@@ -12,7 +12,7 @@ Or inside interactive Kward:
 /login
 ```
 
-Use the provider you already have access to. You can change providers later.
+Use the provider you already have access to. You can change the active model later with `/model`.
 
 ## Choose a provider
 
@@ -34,8 +34,6 @@ kward login openrouter   # OpenRouter API key
 kward login github       # GitHub OAuth for experimental Copilot support
 ```
 
-From source, replace `kward` with `ruby lib/main.rb`.
-
 ## OpenAI / ChatGPT
 
 ```bash
@@ -88,54 +86,70 @@ OPENROUTER_API_KEY=sk-or-v1-... kward
 
 Choose OpenRouter when you want access to its model catalog or want provider/model selection through an API key.
 
-## Experimental Copilot support
+### Refresh the OpenRouter model cache
+
+Kward's `/model` picker can show OpenRouter models that are available to your API key. Refresh the local cache after logging in:
 
 ```bash
-kward login github
+kward openrouter refresh
 ```
 
-This saves GitHub OAuth credentials to:
+This fetches text-capable OpenRouter models for the configured key and writes them to:
 
 ```text
-~/.kward/github_auth.json
+~/.kward/cache/openrouter_models.json
 ```
 
-You can also use a token for one run:
+If `KWARD_CONFIG_PATH` points at a custom config file, the cache is written beside that config file under `cache/openrouter_models.json`.
+
+Inspect the cached model ids with:
 
 ```bash
-COPILOT_GITHUB_TOKEN=... kward
+kward openrouter list
 ```
 
-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.
+Use this when:
 
-## Which credential wins?
+- 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.
 
-If multiple credentials are available, Kward uses the configured provider.
+After refreshing, start Kward and choose the model with `/model`.
 
-Set it in `~/.kward/config.json`:
+## Experimental Copilot support
 
-```json
-{
-  "provider": "anthropic"
-}
+```bash
+kward login github
+```
+
+This saves GitHub OAuth credentials to:
+
+```text
+~/.kward/github_auth.json
 ```
 
-Or for one command:
+You can also use a token for one run:
 
 ```bash
-KWARD_PROVIDER=openrouter kward
+COPILOT_GITHUB_TOKEN=... kward
 ```
 
-Supported provider values:
+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.
+
+## Choose the active model
+
+Authentication makes providers available. The active model is selected separately.
+
+Inside Kward, use:
 
 ```text
-codex
-anthropic
-openrouter
-copilot
+/model
 ```
 
-Without an explicit provider, OpenAI/ChatGPT credentials are preferred when present.
+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.
 
 ## Security notes
 

data/doc/configuration.md

@@ -83,7 +83,7 @@ Defaults:
 - Copilot: `gpt-5-mini`
 - Reasoning effort: `medium`
 
-The interactive `/model` picker prefers OpenRouter models available to the configured API key when Kward can fetch them. `/openrouter/catalog` and RPC `openrouter/catalog` list the full OpenRouter catalog separately.
+The interactive `/model` picker reads cached OpenRouter models when available. Run `kward openrouter refresh` to fetch text-capable models available to the configured OpenRouter API key and cache them under `~/.kward/cache/openrouter_models.json`. Run `kward openrouter list` to inspect the cached model ids.
 
 ## Environment overrides
 
@@ -148,20 +148,6 @@ Overlay settings control terminal picker/card layout:
 
 You can change these interactively with `/settings`.
 
-## Banner settings
-
-The interactive terminal banner shows the avatar Kward logo and the “State your business.” message by default. To hide the full banner:
-
-```json
-{
-  "banner": {
-    "enabled": false
-  }
-}
-```
-
-This only affects the interactive terminal UI.
-
 ## Composer settings
 
 The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:

data/doc/context-tools.md

@@ -0,0 +1,70 @@
+# Context tools
+
+Context tools help Kward load reusable instructions, recover compacted tool output, and ask structured clarification questions. These tools usually run in the background as part of a turn rather than as commands you type directly.
+
+## `read_skill`
+
+`read_skill` loads configured skill instructions when a task matches a known skill.
+
+Arguments:
+
+- `name`: skill name.
+- `path`: optional path inside the skill, default `SKILL.md`.
+
+Skills are reusable instruction bundles stored in the Kward config directory. Kward advertises available skills by name and description, then reads the full skill only when it becomes relevant. That saves tokens because every skill does not need to be injected into every request.
+
+Typical uses:
+
+- loading test-writing guidance before changing tests,
+- loading security guidance before editing auth, secrets, cookies, uploads, or personal data handling,
+- loading language-specific style guidance before refactoring code.
+
+See [Extensibility](extensibility.md) for how skills fit with prompts, personas, and project instructions.
+
+## `retrieve_tool_output`
+
+`retrieve_tool_output` reopens original output that was compacted out of the model-facing context.
+
+Arguments:
+
+- `id`: tool output artifact id, such as `toolout_abc123`.
+- `offset`: optional 1-indexed line offset.
+- `limit`: optional maximum lines to return, default 120.
+- `query`: optional case-insensitive text search within the original output.
+
+Kward may compact large shell, search, fetch, or file outputs before sending them back to the model. The compacted result includes enough summary to continue, plus an artifact id when the original output is worth preserving. If later work needs details, Kward can retrieve a focused slice of the original output instead of asking the tool to repeat the whole operation.
+
+This saves tokens in two ways:
+
+- repeated large outputs are not resent to the model,
+- follow-up reads can target only matching lines or a bounded line range.
+
+## `ask_user_question`
+
+`ask_user_question` asks one to four structured clarification questions through an interactive frontend.
+
+Arguments:
+
+- `questions`: array of one to four questions.
+- each question has:
+  - `header`: short label shown in the overlay,
+  - `question`: the question text,
+  - `options`: two to four selectable answers with labels and descriptions.
+
+This tool is advertised only when the active frontend supports structured questions. In terminal use, it lets Kward ask concise multiple-choice questions instead of guessing requirements. In RPC clients, the same question flow is bridged through UI events.
+
+Good uses:
+
+- choosing between safe implementation approaches,
+- confirming an ambiguous scope,
+- selecting a provider, model, or behavior when no default is obvious.
+
+Kward should not use this tool for every small uncertainty. It is best when an answer materially changes the implementation or avoids a risky assumption.
+
+## Availability
+
+`Kward::ToolRegistry` only advertises context tools when they are usable:
+
+- `read_skill` requires configured skills,
+- `ask_user_question` requires frontend support,
+- `retrieve_tool_output` is available in normal sessions so compacted artifacts can be inspected later.

data/doc/plugins.md

@@ -53,7 +53,7 @@ end
 Start Kward and run:
 
 ```text
-/hello Kai
+/hello World
 ```
 
 ## Add a slash command
@@ -161,7 +161,7 @@ RPC clients can:
 
 - list plugin commands through `commands/list`,
 - run plugin commands through `commands/run`,
-- run plugin slash commands through `turns/start` input such as `/hello Kai`.
+- run plugin slash commands through `turns/start` input such as `/hello World`.
 
 Plugin command output is emitted through normal turn events without calling the model.
 

data/doc/releasing.md

@@ -10,23 +10,32 @@ Release steps before publishing:
    bundle exec rake test
    ```
 
-4. Generate documentation:
+4. Preview docs locally if you changed documentation or public APIs:
+
+   ```bash
+   bundle exec rake docs:serve
+   ```
+
+   The preview builds `_yardoc/`, serves it with WEBrick, and rebuilds in a fresh process when documentation sources, library code, or templates change. Refresh your browser after rebuilds.
+
+5. Generate and check documentation:
 
    ```bash
    bundle exec rake rdoc
    bundle exec rake docs:build
+   bundle exec rake docs:check
    ```
 
-   Pushes to `main` deploy the generated YARD site to GitHub Pages.
+   `docs:check` validates generated internal links, images, and scripts. Pushes to `main` deploy the generated YARD site to GitHub Pages.
 
-5. Build the gem locally:
+6. Build the gem locally:
 
    ```bash
    gem build kward.gemspec
    ```
 
-6. Inspect the packaged files and confirm no local config, sessions, logs, or secrets are included.
-7. Install the built gem locally and smoke test the `kward` executable.
+7. Inspect the packaged files and confirm no local config, sessions, logs, or secrets are included.
+8. Install the built gem locally and smoke test the `kward` executable.
 
 Publish the built gem from the release checkout:
 

data/doc/rpc.md

@@ -1,5 +1,7 @@
 # Kward RPC Protocol
 
+<div class="kward-no-toc"></div>
+
 Kward RPC is an experimental backend protocol for UI clients. It is versioned as protocol version `1`, but method names and payloads may still change while the UI integration is built.
 
 This page is for people building UI clients or integrations. If you use Kward from the terminal, you can skip it.
@@ -10,12 +12,6 @@ This page is for people building UI clients or integrations. If you use Kward fr
 kward rpc
 ```
 
-From source:
-
-```bash
-ruby lib/main.rb rpc
-```
-
 The process uses stdin/stdout exclusively for protocol messages. Diagnostics are written to stderr.
 
 ## Framing
@@ -507,11 +503,7 @@ Returns `{ "memories": [] }`.
 
 ### `models/list`
 
-Returns known model entries from the current client/config backend. OpenRouter entries prefer models available to the configured OpenRouter API key when they can be fetched; otherwise Kward falls back to defaults/currently configured options. Entries use `{ "provider", "id", "name", "reasoning", "reasoningEffort", "contextWindow", "current" }`.
-
-### `openrouter/catalog`
-
-Returns the full OpenRouter model catalog as model entries. This is separate from `models/list`, which prefers models available to the configured API key. Models returned here may still fail at request time if the active OpenRouter key cannot access them.
+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" }`.
 
 ### `models/current`
 

data/doc/session-management.md

@@ -0,0 +1,220 @@
+# Sessions
+
+Sessions are Kward's way of keeping real work alive across time. An interactive chat is not just a scrollback buffer: it is saved as a session with messages, tool calls, tool results, compaction checkpoints, branches, and enough metadata for Kward to resume the work later.
+
+Think of sessions as **context management**. They let you decide which conversation context Kward should use next.
+
+Think of rewinding and forking as **context time travel**. You can go back to an earlier prompt, try a different path, and keep both versions instead of losing the original work.
+
+## Where sessions live
+
+Interactive sessions are saved under:
+
+```text
+~/.kward/sessions/
+```
+
+Sessions are scoped to the workspace. If you run Kward in two different projects, each project has its own recent sessions.
+
+One-shot prompts such as `kward "Explain this project"` do not use session history. Start interactive Kward when you want ongoing context:
+
+```bash
+cd ~/code/project
+kward
+```
+
+## A normal session workflow
+
+Start a chat and give it a useful name:
+
+```text
+/rename oauth cleanup
+```
+
+Work normally:
+
+```text
+Find the OAuth callback code and explain how errors are handled.
+Add a focused test for the missing expired-token case.
+Run the related test file.
+```
+
+Leave when you are done for now:
+
+```text
+/exit
+```
+
+Later, resume the work:
+
+```text
+/sessions
+```
+
+The session picker shows recent sessions for the current workspace. Choose one to restore its transcript and continue with the same context.
+
+`/resume` is an alias for `/sessions`.
+
+## The sessions picker
+
+Open it with:
+
+```text
+/sessions
+```
+
+Inside the picker you can:
+
+| Key | Action |
+| --- | --- |
+| `Enter` | resume the highlighted session. |
+| `r` | rename the highlighted session. |
+| `c` | clone the highlighted session. |
+| `f` | fork the highlighted session from an earlier prompt. |
+| `d d` | delete the highlighted session after confirmation. |
+
+Use names generously. A session named `oauth cleanup` or `release checklist` is much easier to find later than a timestamp.
+
+## Clone a session
+
+Clone when you want an exact copy of the current conversation and then continue in a separate branch.
+
+From inside the active session:
+
+```text
+/clone
+```
+
+Or from `/sessions`, highlight a session and press `c`.
+
+A clone keeps the same conversation so far, but future messages are written to the new session file. The original session remains unchanged.
+
+Good uses:
+
+- try a risky refactor while preserving the safe version,
+- continue a review with a different strategy,
+- keep a checkpoint before asking Kward to make broad changes,
+- split one investigation into two independent paths.
+
+Mental model: **clone copies the whole timeline and starts a new future from now.**
+
+## Fork from an earlier prompt
+
+Fork when you want to go back to a specific user prompt and create a new independent session from before that prompt.
+
+From inside the active session:
+
+```text
+/fork
+```
+
+Or from `/sessions`, highlight a session and press `f`.
+
+Kward shows earlier user prompts. Choose the prompt where the new path should begin. Kward creates a new session containing the conversation before that prompt, then pre-fills the selected prompt so you can edit or resubmit it.
+
+Good uses:
+
+- you asked the wrong question and want to rephrase it,
+- Kward solved the right problem in the wrong style,
+- you want to try a smaller implementation after a larger one,
+- you want two alternative designs starting from the same point.
+
+Mental model: **fork cuts the timeline before a selected prompt and starts a new session there.**
+
+## Rewind within the current session
+
+Rewind is the fastest way to revisit an earlier prompt in the current session:
+
+```text
+/rewind
+```
+
+Kward shows previous user prompts from the active branch. Choose one, edit it if needed, and continue from that point. Future messages become a new branch in the same session history.
+
+Use rewind when you are still working inside one session and want to quickly try a different direction.
+
+Good uses:
+
+- undo a bad turn without throwing away the whole session,
+- retry an earlier request with tighter instructions,
+- branch from a known-good point after a tool result revealed something new,
+- jump back after realizing the current path is too broad.
+
+When available, `/rewind` also offers a return option so you can go back to where you were before rewinding.
+
+Mental model: **rewind moves the active point inside the same session timeline.**
+
+## Inspect the full tree
+
+Use `/tree` when you need the technical view of a session's history:
+
+```text
+/tree
+```
+
+The session tree includes more than the friendly `/rewind` list. It can show branches, assistant entries, tool calls, tool results, compaction checkpoints, and the current active leaf. Choose an entry to move the active session position there.
+
+Most users should reach for `/rewind` first. Use `/tree` when you need to understand or navigate the full branching structure.
+
+Good uses:
+
+- inspect where a branch split,
+- return to a specific tool-heavy checkpoint,
+- understand what happened after multiple rewinds,
+- navigate a long session with several alternative paths.
+
+Mental model: **`/tree` is the map; `/rewind` is the friendly time machine.**
+
+## Compact long sessions
+
+Long sessions can outgrow the model's useful context window. Use compacting to keep going:
+
+```text
+/compact
+```
+
+You can add focus instructions:
+
+```text
+/compact preserve the API docs navigation decisions and current failing checks
+```
+
+Compaction summarizes older conversation into a checkpoint and keeps recent context active. Historical messages remain in the session file for audit, export, and tree navigation, but the live model context becomes smaller.
+
+After compaction, Kward may need to re-read files before editing them again. That is normal: read-before-edit guardrails apply to the current live context.
+
+Compaction is also context management. It trades detailed old conversation for a concise working summary so Kward can spend tokens on the next task.
+
+## Export a session
+
+Export when you want notes outside Kward:
+
+```text
+/export notes.md
+```
+
+Exports are useful for handoff notes, review summaries, release records, or saving a human-readable transcript before deleting old sessions.
+
+## Which command should I use?
+
+| Need | Use |
+| --- | --- |
+| Continue earlier work | `/sessions` or `/resume` |
+| Give the current session a better name | `/rename <name>` |
+| Keep the current state but try another future | `/clone` |
+| Start a separate session from before an earlier prompt | `/fork` |
+| Quickly retry an earlier prompt in this session | `/rewind` |
+| Inspect or navigate the full branch structure | `/tree` |
+| Reduce old context so a long session can continue | `/compact` |
+| Save a readable transcript | `/export <path>` |
+
+## Practical habits
+
+- Rename sessions early when work becomes important.
+- Clone before risky or broad changes.
+- Fork when the earlier prompt was the wrong starting point.
+- Rewind when you want a fast alternate attempt inside the same session.
+- Use `/tree` only when the friendly commands are not enough.
+- Compact when the conversation gets long, but keep the focus instruction specific.
+
+Sessions make Kward less like a single chat box and more like a workspace timeline. You can preserve context, branch it, compress it, and return to it when the work needs another pass.

data/doc/usage.md

@@ -99,7 +99,8 @@ Use slash commands for local actions that should not go to the model:
 | `/new` | start a fresh session. |
 | `/sessions` | open the saved sessions picker or continue a previous session by path. |
 | `/resume` | alias for `/sessions`. |
-| `/name <name>` | name the current session. |
+| `/name <name>` | name or clear the current session. |
+| `/rename <name>` | rename the current session. |
 | `/clone` | copy the current session into a new branch. |
 | `/rewind` | revisit an earlier prompt and try a different direction. |
 | `/tree` | inspect and navigate the full technical session tree. |
@@ -115,18 +116,18 @@ Prompt templates and plugins can add more slash commands.
 
 ## Sessions
 
-Interactive chats are saved under:
+Interactive chats are saved as workspace-scoped sessions under:
 
 ```text
 ~/.kward/sessions/
 ```
 
-Sessions are scoped to the workspace. Use them when work spans more than one terminal sitting.
+Use sessions when work spans more than one terminal sitting, or when you want to branch a conversation and try another direction.
 
 Typical flow:
 
 ```text
-/name oauth cleanup
+/rename oauth cleanup
 # work with Kward
 /export oauth-notes.md
 /exit
@@ -138,11 +139,9 @@ Later:
 /sessions
 ```
 
-`/resume` remains available as an alias.
+In the sessions picker, press `r` to rename the highlighted session, `c` to clone it, `f` to fork from an earlier prompt, or `d` twice to delete it. `/resume` remains available as an alias for `/sessions`.
 
-Use `/rewind` when you want to go back to an earlier prompt and try a different direction. Kward shows user prompts from the current session, lets you edit a prior prompt, and continues from that point as a branch. Use `/tree` when you need the full technical session tree, including branches, assistant entries, tool calls, and tool results.
-
-Use `/compact` when a conversation gets long. Kward summarizes older context and keeps recent context active. After compaction, it may need to re-read files before editing them again.
+For the full guide to context management, cloning, forking, rewinding, `/tree`, compaction, and exports, read [Sessions](session-management.md).
 
 ## One-shot prompts
 

data/doc/workspace-tools.md

@@ -0,0 +1,105 @@
+# Workspace tools
+
+Workspace tools let Kward inspect and change the local project. They are the tools behind prompts such as:
+
+```text
+Find where configuration is loaded.
+Add a focused test for this behavior.
+Run the related test file.
+```
+
+Kward normally chooses these tools itself. You do not need to know their exact names to use them, but understanding the boundaries helps explain why Kward sometimes reads before editing or asks before running broad checks.
+
+## Guardrails
+
+Workspace tools use the active workspace as their boundary. File paths are workspace-relative by default, and file tools are guarded so Kward does not edit arbitrary unread files.
+
+Important behavior:
+
+- Existing files must be read in the current conversation before `write_file` or `edit_file` can change them.
+- Reads are bounded to avoid pulling very large files into context by accident.
+- Edits use exact text replacement, so accidental partial or fuzzy changes fail instead of guessing.
+- Shell commands run as your operating-system user from the workspace. They are powerful and should be treated like commands you run yourself.
+
+## Reading the workspace
+
+### `list_directory`
+
+Lists entries in a workspace-relative directory. Kward uses it to discover project structure before reading specific files.
+
+Arguments:
+
+- `path`: workspace-relative directory.
+
+### `read_file`
+
+Reads a workspace text file. Output is capped, and Kward can continue with line offsets when it needs more detail.
+
+Arguments:
+
+- `path`: workspace-relative file path.
+- `offset`: optional 1-indexed start line.
+- `limit`: optional maximum number of lines.
+
+A successful read marks the resolved file path as read for the conversation, allowing later edits to that file.
+
+### `summarize_file_structure`
+
+Returns a compact outline of classes, modules, methods, and functions in a source file. Kward uses it when a file may be too large to read fully at first.
+
+Arguments:
+
+- `path`: workspace-relative source file path.
+
+This tool saves tokens by letting Kward identify relevant entry points before requesting exact line ranges with `read_file`.
+
+## Changing files
+
+### `write_file`
+
+Writes complete file content. Existing files must be read first. New files can be created when the path is inside the workspace.
+
+Arguments:
+
+- `path`: workspace-relative file path.
+- `content`: complete file content.
+
+Use full writes when replacing generated content or creating a new file. For small edits to existing files, Kward should usually prefer `edit_file`.
+
+### `edit_file`
+
+Applies one or more exact replacements to a file that has already been read.
+
+Arguments:
+
+- `path`: workspace-relative file path.
+- `edits`: array of replacements:
+  - `old_text`: unique exact text to replace.
+  - `new_text`: replacement text.
+
+Each `old_text` must match exactly once, and replacements must not overlap. This keeps edits deterministic and avoids broad fuzzy rewriting.
+
+## Running commands
+
+### `run_shell_command`
+
+Runs a shell command from the workspace root.
+
+Arguments:
+
+- `command`: command to run.
+- `timeout_seconds`: optional timeout, default 30 seconds.
+
+Kward uses shell commands for tests, linters, build checks, and simple repository inspection. Command output is bounded and may be compacted before it is sent back into model context, while the original output remains available in the session record.
+
+## Token behavior
+
+Workspace tools are intentionally incremental:
+
+1. list directories to find likely files,
+2. summarize large source files before reading everything,
+3. read focused line ranges,
+4. make exact edits,
+5. run focused verification commands.
+
+This keeps the model's context window focused on relevant evidence instead of flooding it with entire repositories or long command output.