kward 0.71.0 → 0.73.0

data/doc/tabs.md

@@ -0,0 +1,122 @@
+# Tabs
+
+Use tabs when you want more than one Kward conversation open in the same interactive terminal session.
+
+Each tab has its own session-backed conversation, transcript, composer state, and running agent turn. That makes tabs useful for splitting work without losing your place: one tab can investigate a bug, another can draft docs, and a third can wait on a long-running answer.
+
+## Quick start
+
+Open a new tab:
+
+```text
+/tab new
+```
+
+Switch to tab 1, 2, or another visible tab number:
+
+```text
+/tab 1
+/tab 2
+```
+
+Rename the current tab:
+
+```text
+/tab name Docs
+```
+
+Close the current tab:
+
+```text
+/tab close
+```
+
+The tab bar appears at the bottom of the composer. The active tab is framed, and each tab label starts with its number.
+
+## Common workflow
+
+A typical multi-tab flow looks like this:
+
+1. Start Kward interactively in your project.
+2. Use the main tab for the current implementation task.
+3. Run `/tab new` to open a clean conversation.
+4. Ask a separate question, such as:
+
+   ```text
+   Review the current API docs structure and suggest where a Tabs guide belongs.
+   ```
+
+5. Switch back with `/tab 1` while the other answer runs.
+6. Return to the second tab with `/tab 2` when it is ready.
+
+Tabs keep the conversations separate, so context from one tab does not automatically spill into another.
+
+## Slash commands
+
+| Command | Action |
+| ------- | ------ |
+| `/tab new` | Open a new tab with a fresh conversation |
+| `/tab 1` through `/tab 9` | Switch to a numbered tab |
+| `/tab close` | Close the current tab |
+| `/tab name <label>` | Rename the current tab |
+| `/tab rename <label>` | Same as `/tab name` |
+| `/tab move left` | Move the current tab one slot left |
+| `/tab move right` | Move the current tab one slot right |
+| `/tab move <number>` | Move the current tab to a numbered position |
+
+If you close the only remaining tab, Kward exits the interactive session. A running tab cannot be closed until it finishes or is cancelled.
+
+## Keyboard shortcuts
+
+Kward supports two tab shortcut families. You can choose one in `/settings` or with `composer.tab_keybindings` in `config.json`.
+
+`Ctrl+Tab` and `Ctrl+Shift+Tab` switch tabs when your terminal sends those keys:
+
+| Key | Action |
+| --- | ------ |
+| `Ctrl+Tab` | Next tab |
+| `Ctrl+Shift+Tab` | Previous tab |
+
+When `composer.tab_keybindings` is `ctrl`:
+
+| Key | Action |
+| --- | ------ |
+| `Ctrl+T` | New tab |
+| `Ctrl+W` | Close tab |
+| `Ctrl+1` through `Ctrl+9` | Switch to a numbered tab, if your terminal reports modified number keys |
+
+When `composer.tab_keybindings` is `alt`:
+
+| Key | Action |
+| --- | ------ |
+| `Alt+T` | New tab |
+| `Alt+Right` | Next tab |
+| `Alt+Left` | Previous tab |
+| `Alt+1` through `Alt+9` | Switch to a numbered tab |
+
+`auto` is the default. On macOS it prefers the Ctrl family; elsewhere it prefers the Alt family, because many terminals reserve or swallow Ctrl-based tab shortcuts.
+
+## Running work in another tab
+
+A tab can keep running while you switch away. Kward marks tab labels by status:
+
+- Yellow: running or queued.
+- Green: waiting for your answer to an interactive question, or unread output is ready in a background tab.
+- Red: failed or cancelled.
+
+If you type into a busy tab, Kward queues normal prompts until the current turn finishes. Some running turns also support steering input, so short follow-up guidance may be delivered to the active run instead of waiting for the next turn.
+
+Slash commands such as `/tab` still work while a tab is busy, so you can switch tabs, open a new tab, or move around without waiting.
+
+## Persistence
+
+Tabs are backed by normal Kward sessions. Kward stores the open tab list, labels, and active tab per workspace, then restores them the next time you start interactive Kward in that workspace.
+
+The tab layout is stored in Kward's config directory under `tabs/`. Session transcripts stay in the normal sessions directory. See [Sessions](session-management.md) for session naming, resuming, forking, exporting, and cleanup.
+
+## Notes and limitations
+
+- Tabs are available in the interactive TUI.
+- Each tab has its own conversation context; use explicit file mentions or summaries when you want to carry information between tabs.
+- A running tab cannot be closed until it is idle.
+- Terminal support for modified keys varies. If shortcuts do not arrive, use the `/tab` slash commands or switch `composer.tab_keybindings` between `ctrl` and `alt`.

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`, `pty`, 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. Use `pty git log` or `/pty git log` when you intentionally want to hand the terminal to an interactive tool such as `less` or `vim`. You can set global shell env vars and aliases in `~/.kward/ekwsh.yml`; see [Configuration](configuration.md).
+
 ## 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,15 +106,28 @@ 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. |
+| `/diff` | open the file changes recorded in the current session. |
+| `/files` | browse project files in a nested tree and open them in the editor. |
+| `/shell` | run workspace commands in the embedded Kward shell. |
+| `/pty <command>` | hand the terminal to an interactive command such as `git log`/`less` or `vim`. |
+| `/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 or clear the current session. |
@@ -107,13 +138,47 @@ Use slash commands for local actions that should not go to the model:
 | `/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`). |
+| `/queue` | manage the experimental tab-backed worker queue (`add`, `list`, `open <id>`, `run`, `suspend <id>`, or `resume <id>`). |
 | `/exit` | leave Kward. |
 
 Prompt templates and plugins can add more slash commands.
 
+### Experimental tab-backed worker queue
+
+Start Kward with `--experimental-workers` to try the tab-backed worker queue. The queue is an MVP for turning an existing tab/session into implementation work that can be reviewed later.
+
+Typical flow:
+
+```text
+/plan Add retry handling to webhook delivery
+/queue add
+/queue run
+/queue open <id>
+```
+
+`/queue add` stores the current tab session as a queued worker job. `/queue run` drains queued jobs one at a time. Each job continues its saved session as an implementation worker, starts only from a clean git workspace, commits any resulting changes, and then becomes `ready_for_review`. Use `/queue open <id>` to inspect the worker session, test the feature yourself, and continue the same session if a follow-up fix is needed.
+
+Current MVP limitations:
+
+- The queue is manual: run it with `/queue run` when you want it to work.
+- Jobs run sequentially and stop when one becomes `blocked` or `failed`.
+- A job will not start if the workspace is dirty; clean, commit, or stash your changes first.
+- `/queue suspend <id>` and `/queue resume <id>` provide explicit stash-based parking primitives, but automatic foreground-tool-triggered yielding is not wired yet.
+- The queue is experimental and stores metadata locally in Kward's config directory.
+
+## 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 as workspace-scoped sessions under:
@@ -149,11 +214,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
@@ -181,7 +253,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

@@ -12,14 +12,14 @@ Kward normally chooses these tools itself. You do not need to know their exact n
 
 ## 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.
+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.
+- 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.
+- 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
 
@@ -33,25 +33,55 @@ Arguments:
 
 ### `read_file`
 
-Reads a workspace text file. Output is capped, and Kward can continue with line offsets when it needs more detail.
+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 classes, modules, methods, and functions in a source file. Kward uses it when a file may be too large to read fully at first.
+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`.
+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
 
@@ -66,6 +96,8 @@ Arguments:
 
 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.
@@ -77,7 +109,9 @@ Arguments:
   - `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.
+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
 
@@ -90,16 +124,21 @@ 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.
+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. summarize large source files before reading everything,
-3. read focused line ranges,
-4. make exact edits,
-5. run focused verification commands.
+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).