kward 0.70.0 → 0.72.0

data/doc/troubleshooting.md

@@ -1,6 +1,74 @@
 # Troubleshooting
 
-This page collects environment-specific issues that can affect Kward but are not caused by Kward itself.
+This page covers common issues and how to diagnose them. When something is not working, start with `kward doctor` — it checks your config, directories, workspace, model, and auth status in one pass.
+
+## Run `kward doctor` first
+
+`kward doctor` reports the state of your local setup without printing secrets:
+
+```bash
+kward doctor
+```
+
+It checks that your config file is readable and valid JSON, that the config and session directories are writable, that the workspace exists, which provider and model are active, and which credentials are configured. Use it as the first diagnostic step for any unexpected behavior.
+
+`kward auth status` gives a focused view of credentials only, also without printing secrets:
+
+```bash
+kward auth status
+```
+
+## Authentication errors and token expiration
+
+OAuth tokens expire. Kward refreshes access tokens automatically when a refresh token is available, but if the refresh token is missing or expired, requests fail with a provider-specific error:
+
+- OpenAI: `No OpenAI OAuth login found.`
+- Anthropic: `No Anthropic OAuth login found.`
+- Copilot: `No GitHub Copilot OAuth login found.`
+- OpenRouter: `No OpenRouter API key found.`
+
+Re-run login for the affected provider:
+
+```bash
+kward login              # OpenAI
+kward login anthropic    # Anthropic
+kward login openrouter   # OpenRouter
+kward login github       # Copilot
+```
+
+Or use `/login` inside Kward. See [Authentication](authentication.md) for the full provider flow.
+
+## Provider usage limits and billing errors
+
+Kward detects non-retryable quota and billing errors from providers, including messages such as `quota exceeded`, `insufficient_quota`, `out of credits`, and `monthly usage limit reached`. These are not retried — the request fails immediately.
+
+If you see one of these errors:
+
+- Check your provider dashboard for usage or billing limits.
+- For OpenRouter, verify your account balance at [openrouter.ai](https://openrouter.ai).
+- For OpenAI, check your organization's usage and billing settings.
+- Switch to a different provider or model with `/model` if you have alternative credentials.
+
+## Rate limiting and transient server errors
+
+Kward automatically retries transient failures: HTTP 429 (rate limit) and 5xx server errors. It makes up to 3 attempts total with short backoff delays. Network errors such as timeouts and connection resets are also retried.
+
+If requests fail after retries, you will see a message like `request failed after 3 attempts`. Common causes:
+
+- You are hitting the provider's rate limit. Wait a moment and retry, or reduce request frequency.
+- The provider is experiencing an outage. Check the provider's status page.
+- Your session context is very large, making each request slower and more likely to time out. Use `/compact` to reduce context.
+
+## Context overflow errors
+
+When a conversation exceeds the model's context window, the provider returns an error such as `prompt is too long` or `exceeds the context window`. Kward detects these and does not retry them.
+
+To resolve context overflow:
+
+- Run `/compact` to summarize and reduce the conversation context.
+- Start a new session with `/new` if the current one is no longer needed.
+- Enable auto-compaction if it is off — see [Configuration](configuration.md).
+- Switch to a model with a larger context window via `/model`.
 
 ## `gem install kward` succeeds, but `kward` is not found with rbenv
 
@@ -53,3 +121,11 @@ kward --help
 ```
 
 This stale `.rbenv-shim` file can be left behind by an interrupted `rbenv rehash` or gem installation. It is local rbenv state, not a Kward packaging issue.
+
+## Still stuck?
+
+If none of the above resolves your issue:
+
+1. Run `kward doctor` and `kward auth status` to gather diagnostics.
+2. Check the [Authentication](authentication.md) and [Configuration](configuration.md) docs.
+3. Search or report issues at the [Kward issue tracker](https://github.com/kaiwood/kward/issues).

data/doc/usage.md

@@ -12,7 +12,7 @@ cd ~/code/project
 kward
 ```
 
-When running from source, replace `kward` with `ruby lib/main.rb`.
+When running from source, replace `kward` with `ruby lib/main.rb`. See [Getting started](getting-started.md) for install and sign-in.
 
 ## Common workflows
 
@@ -42,6 +42,14 @@ For larger reviews, use interactive mode so Kward can inspect related files:
 Review the current git diff. If something looks risky, inspect the relevant files before recommending changes.
 ```
 
+To review and commit changes interactively, use `/git`:
+
+```text
+/git
+```
+
+It opens a staging overlay where you can stage or unstage files, preview diffs, and write a commit message without leaving Kward.
+
 ### Make a small code change
 
 ```text
@@ -64,6 +72,14 @@ Or run a shell command yourself from the composer by prefixing it with `!`:
 !git status --short
 ```
 
+For several commands, enter the embedded Kward shell:
+
+```text
+/shell
+```
+
+`/shell` opens `ekwsh`, a Kward-native command mode. Kward keeps the tab bar, composer editing, and transcript rendering while each command runs through your configured shell. Built-ins such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, and `exit` maintain shell-mode state between commands. Plain Tab completes built-in command names, configured aliases, executables from `$PATH`, and file paths from the shell's current directory; `cd` completion suggests directories only. `ekwsh` preserves safe ANSI SGR color/style output while stripping terminal-control sequences that could corrupt the TUI, and sets conservative color-friendly environment defaults such as `CLICOLOR=1`, `COLORTERM=truecolor`, and `TERM=xterm-256color` when needed. It does not force color by default; set `FORCE_COLOR`, `CLICOLOR_FORCE`, or command-specific flags such as `--color=always` if you want more aggressive color output. You can set global shell env vars and aliases in `~/.kward/ekwsh.yml`; see [Configuration](configuration.md). It is intended for command output, not full-screen interactive programs such as editors or pagers.
+
 ## Shell commands
 
 Useful shell commands:
@@ -72,10 +88,12 @@ Useful shell commands:
 kward                          # start interactive chat
 kward "Explain this project"   # ask one question and exit
 kward help                     # show commands and examples
+kward version                  # show the installed version
 kward doctor                   # check local setup
 kward login                    # sign in or save credentials
 kward auth status              # show credential status without secrets
 kward sysprompt                # inspect assembled instructions
+kward stats tokens             # export local token telemetry as CSV
 kward rpc                      # start the experimental RPC backend
 ```
 
@@ -88,45 +106,67 @@ kward --working-directory ~/code/project "Summarize this repository"
 
 ## Interactive slash commands
 
-Use slash commands for local actions that should not go to the model:
+Slash commands run local actions in the current session. Most do not send a prompt to the model; exceptions like `/git` and `/workers` orchestrate local flows that may then trigger model work.
 
 | Command | Use it when you want to... |
 | --- | --- |
 | `/login` | sign in or save provider credentials. |
 | `/model` | choose the active model. |
 | `/reasoning` | choose reasoning effort. |
+| `/git` | review uncommitted changes, stage files, and commit. |
+| `/files` | browse project files in a nested tree and open them in the editor. |
+| `/shell` | run workspace commands in the embedded Kward shell. |
+| `/settings` | configure prompt overlays. |
 | `/status` | see session, model, and context status. |
-| `/new` | start a fresh session. |
+| `/new` | start a fresh session in the current tab. |
+| `/tab 2` | switch to tab 2. |
+| `/tab move 1` | move the active tab to position 1. |
+| `/tab move left` | move the active tab one position left. |
+| `/tab move right` | move the active tab one position right. |
+| `/tab close` | close the active tab. |
+| `/tab new` | open a new tab. |
+| `/tab name <label>` | rename the active tab label. |
 | `/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. |
 | `/copy last` | copy the latest assistant answer. |
 | `/copy transcript` | copy the transcript as Markdown. |
 | `/export notes.md` | write the transcript to a Markdown file. |
-| `/compact [focus]` | summarize older context so a long chat can continue. |
+| `/compact [instructions]` | summarize older context so a long chat can continue. |
 | `/memory ...` | manage opt-in memory. |
 | `/redraw` | fix terminal drawing after resize or glitches. |
+| `/reload` | reload installed plugins. |
+| `/workers` | open the experimental worker pipeline (`new`, `do <task>`, or `list`). |
 | `/exit` | leave Kward. |
 
 Prompt templates and plugins can add more slash commands.
 
+## Prompt history
+
+In interactive mode, Kward keeps prompt history per workspace under `~/.kward/history/`. Press Up/Down to recall previous prompts across restarts.
+
+Press `Ctrl-R` to search history. Type a fuzzy query in the composer, use Up/Down to choose a result from the overlay, then press Enter to place it back in the composer for editing or resubmission. Press Esc or Ctrl-C to cancel the search and restore the draft.
+
+`$path` editor-open commands are also saved after a file opens successfully, using the resolved workspace-relative path.
+
 ## 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 +178,9 @@ Later:
 /sessions
 ```
 
-`/resume` remains available as an alias.
-
-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.
+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 `/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
 
@@ -150,11 +188,18 @@ One-shot prompts are best for short tasks that do not need session history:
 
 ```bash
 kward "What does this repository do?"
+cat error.log | kward
+```
+
+When stdin and a prompt are both present, Kward runs in filter mode: stdin is the input, the prompt is the instruction, and stdout contains only the transformed result. You can also force this with `--filter` or `--mode filter`.
+
+```bash
 git diff | kward "Review this diff"
-cat error.log | kward "Explain the likely cause"
+echo "Hello" | kward --filter "Translate to German"
+kward --mode filter "Indent this JSON" < unindented.json
 ```
 
-Use `--` when your prompt starts with something that could be parsed as a command or option:
+Use `--mode chat`, `--mode oneshot`, or `--mode filter` to override automatic mode detection. Use `--` when your prompt starts with something that could be parsed as a command or option:
 
 ```bash
 kward -- explain --working-directory
@@ -182,7 +227,7 @@ Important guardrails:
 
 ## Images
 
-If the active model supports images, Kward can attach image paths, Markdown image links, `file://` URLs, or image data URLs pasted into the composer.
+If the active model supports images, Kward can attach image paths, Markdown image links, `file://` URLs, or image data URLs pasted into the composer. Supported formats are GIF, JPEG, PNG, and WebP, up to 20 MB per image.
 
 Use this for tasks such as:
 

data/doc/web-search.md

@@ -36,16 +36,18 @@ Kward should search first, then fetch important pages before relying on them.
 
 ## Network behavior
 
-Web tools are advertised to the model by default. Queries and fetched URLs are sent over the network to the selected provider or target host.
+Web tools are advertised to the model by default. Queries and fetched URLs are sent over the network to the selected provider or target host. See [Configuration](configuration.md) for the full `web_search` config reference including API key storage and the `provider` config setting.
 
 In automatic mode, provider fallback is:
 
 1. Exa API when `EXA_API_KEY` is configured, otherwise keyless Exa MCP.
-2. Perplexity API when configured and model-provider fallback is allowed.
-3. Gemini API with Google Search grounding when configured and model-provider fallback is allowed.
+2. Perplexity API when `PERPLEXITY_API_KEY` is configured and model-provider fallback is allowed.
+3. Gemini API with Google Search grounding when `GEMINI_API_KEY` is configured and model-provider fallback is allowed.
 4. DuckDuckGo HTML search, then bundled public SearXNG instances.
 
-You do not need an API key for basic web search, but keys can improve limits or provider choice.
+You do not need an API key for basic web search, but keys can improve limits or provider choice. The default provider can also be set in config as `web_search.provider`; the tool argument overrides it for a single call.
+
+Search output is capped at 8 KB total, with excerpts up to 300 characters and answer text up to 2,000 characters. HTTP requests use a 10-second timeout.
 
 ## Disable web tools
 
@@ -83,6 +85,10 @@ Arguments:
 - `max_bytes`: default 16384, capped at 131072.
 - `extract`: optional `auto`, `text`, or `markdown`.
 
+In `auto` mode (default), Kward detects HTML content and extracts readable text by stripping scripts, styles, navigation, and forms, preserving headings, paragraphs, lists, code blocks, and blockquotes. Non-HTML content is returned as cleaned text. Use `markdown` to format extracted headings and code blocks as Markdown, or `text` for plain text without formatting.
+
+Fetches follow up to 5 redirects and use a 10-second HTTP timeout.
+
 ### `fetch_raw`
 
 Reads a specific HTTP or HTTPS resource without readability extraction. Use it for JSON, YAML, XML, RSS, OpenAPI specs, and plain text.
@@ -92,3 +98,5 @@ Arguments:
 - `url`
 - `max_bytes`: default 16384, capped at 131072.
 - `accept`: optional HTTP `Accept` header.
+
+Fetches follow up to 5 redirects and use a 10-second HTTP timeout.

data/doc/workspace-tools.md

@@ -0,0 +1,144 @@
+# 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. Guardrails can be disabled with the `tools.workspace_guardrails` setting — see [Configuration](configuration.md). When disabled, file tools can access paths outside the workspace, but shell commands are unaffected since they already run as your OS user.
+
+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. Files larger than 256 KB cannot be read or edited. Read output is capped at 50 KB or 2,000 lines, whichever comes first.
+- 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. Command output is capped at 128 KB.
+
+## 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. The tool also supports explicit context modes so Kward can start cheap and widen only when needed.
+
+Arguments:
+
+- `path`: workspace-relative file path.
+- `offset`: optional 1-indexed start line.
+- `limit`: optional maximum number of lines.
+- `mode`: optional context mode:
+  - `preview`: read a short preview slice, defaulting to 120 lines when `limit` is omitted.
+  - `outline`: return only the source declaration outline.
+  - `range`: read the requested `offset`/`limit` slice.
+  - `full`: read from `offset` until Kward's read caps stop the response.
+- `max_bytes`: optional per-call byte budget, capped by Kward's workspace read limit.
+
+A successful read marks the resolved file path as read for the conversation, allowing later edits to that file.
+
+When called without `offset`, `limit`, or `mode` on a file that exceeds 2,000 lines or 50 KB, Kward returns a structure outline (classes, modules, methods) plus the first 120 lines instead of truncating blindly. This helps identify relevant entry points before requesting specific line ranges.
+
+Binary files (detected by null bytes) return an error instead of content.
+
+### `context_budget_stats`
+
+Returns approximate context-budget savings for the current active conversation since it was opened in this process. The report compares each raw tool result size with the model-facing result after compaction or duplicate replacement, includes per-tool totals, and estimates saved tokens using roughly four bytes per token.
+
+Arguments: none.
+
+These numbers are intentionally approximate runtime stats. They are useful for seeing whether Kward's budgeting is helping the current conversation, not for billing, and they are not reconstructed when a saved session is resumed.
+
+### `context_for_task`
+
+Builds a compact, task-shaped context bundle from likely workspace files. It ranks files by task terms, includes source outlines, and adds short matching excerpts while respecting an approximate byte budget. This is intentionally lightweight: it does not maintain a persistent index or semantic graph.
+
+Arguments:
+
+- `task`: required task or question to gather context for.
+- `paths`: optional files or directories to focus. Defaults to the workspace root.
+- `budget`: optional approximate byte budget, default 4,000 and capped at 20,000.
+
+Use this when Kward needs orientation for a bug, review, implementation, or explanation before deciding which exact file ranges to read.
+
+### `summarize_file_structure`
+
+Returns a compact outline of recognizable declarations in a source file, including line ranges and declaration kind where Kward can infer them. 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`. The outline is capped at 80 entries and recognizes common Ruby, JavaScript/TypeScript, Go, Rust, Java, and C#-style declarations with lightweight pattern matching rather than a full parser. Binary files (detected by null bytes) return an error instead of content.
+
+## 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`.
+
+The result includes a unified diff of the changes, capped at 8 KB with a summary of additions and deletions when truncated.
+
+### `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. Empty `old_text`, multiple matches, and no-op edits (where the result is identical) are all rejected with an error.
+
+The result includes a unified diff of the changes, capped at 8 KB with a summary of additions and deletions when truncated.
+
+## 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 at 128 KB and may be compacted before it is sent back into model context, while the original output remains available in the session record.
+
+The output format is `Exit status: N` followed by `STDOUT:` and `STDERR:` sections. On timeout, Kward sends SIGTERM then SIGKILL after 0.2 seconds and returns a timeout error. Commands support cooperative cancellation when the session is cancelled.
+
+## Token behavior
+
+Workspace tools are intentionally incremental:
+
+1. list directories to find likely files,
+2. use `read_file` with `mode: "outline"` or `summarize_file_structure` before reading everything,
+3. read focused line ranges with `mode: "range"`, `offset`, `limit`, and optional `max_bytes`,
+4. widen to `mode: "full"` only when focused context is insufficient,
+5. make exact edits,
+6. 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.
+
+For details on how tool outputs are compacted, deduplicated, and retrieved, see [Agent tools](agent-tools.md).