kward 0.67.1 → 0.69.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d03a2b137c3ef3a1bc27e44b2629de49a41c70c3044088f9bd0c162cf50e3387
-  data.tar.gz: 241753e7eca9acb6ff94cae50afa7ea43ea2e4c13a8d22eb5031d399ae7fad5a
+  metadata.gz: a84b87d1fd620a0008222c1f7cf6efd3fb7d019818e6674f75e3160ad738d2b3
+  data.tar.gz: 297fc5bd96d88356731b659cd6d43da8349e5711e50f1419a11afdab82192d57
 SHA512:
-  metadata.gz: ac0d8465faa573ac9878c4bf5b83327145a7810cbe375b64ce8019531ba00ea3be779a82ed912825de2372ba18917dc56137f67f60161d3234e396b6ec82f3a2
-  data.tar.gz: 3e50a23badb84faf825a75cec5f9d0f4b62cc2bb0c76d643ac8bfb41d99a97c0cbc95268508e4b8a0c2e172249d105f3246b8b0e6a44c81725eae52db71235e6
+  metadata.gz: 1f7614a284acdd69deeeb8ae509ca42b093e7e9e55eac47d4c23d63d30ca0ccb4079c5fc21f747863097d1c938084627d6576b32b12cdecc7754c5cecff558db
+  data.tar.gz: ccc2a3e15276ef03d50b4d52ccdc1b1977c1555b3f367d152b8d889ee518d315645a910a6d1940a94e7fb5e378bf5a614bfe87189b8e723505e7eba3aaf13c0d

data/.github/workflows/pages.yml

@@ -0,0 +1,48 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+
+      - name: Build documentation
+        run: bundle exec rake docs:build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _yardoc
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.yardopts

@@ -1,6 +1,7 @@
 --readme README.md
 --output-dir _yardoc
 --markup markdown
+--template-path templates
 lib/**/*.rb
 -
 README.md

data/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.69.0] - 2026-06-17
+
+### Added
+
+- Added a `docs:build` Rake task for building the YARD documentation site.
+- Reworked core guide documentation around developer workflows, setup, authentication, memory, personas, extensibility, plugins, web search, and code search.
+- Added `fetch_content` and `fetch_raw` web tools for reading specific URLs after search discovery.
+- Added `enforce_workspace_agents_file` config support for forcing full workspace `AGENTS.md` injection.
+- Added config-directory `PRINCIPLES.md` as the preferred global principles file, with `AGENTS.md` kept as a legacy alias.
+- Added `kward sysprompt` for inspecting the effective system prompt, with `--raw` for unannotated prompt content.
+
+### Changed
+
+- Changed workspace `AGENTS.md` handling to inject a compact read-when-relevant instruction by default instead of the full file.
+- Changed interactive runtime command/status messages to use a `Runtime>` transcript label instead of the assistant label.
+- Changed terminal tool transcript rendering to show a single `Tool>` block containing the tool invocation summary and result summary.
+- Changed transcript label colors to a quieter palette, with failed tool calls rendered in red.
+- Separated conversation system prompt state from durable transcript messages; provider request context still includes the current system prompt on every model request.
+- Persisted system prompt snapshots as session audit metadata when the prompt changes, without adding them to transcript messages.
+
+### Fixed
+
+- Fixed custom `ask_user_question` answers so trailing spaces remain visible while typing.
+- Fixed inferred soft memory learning to canonicalize user preferences and avoid storing near-duplicate memories with slightly different wording.
+- Fixed in-flight steering messages so they appear in the interactive transcript as `You>` entries.
+- Fixed interactive plugin slash commands and OAuth login so they show the running spinner while executing.
+- Fixed `/reload` so terminal plugin footers use the newly loaded plugin renderer without restarting Kward.
+- Fixed Codex GPT-5.5 RPC model metadata to report a 400k context window instead of the upstream OpenAI API context window.
+- Fixed a bug that prevented proper context window calculation whenever an image is attached to a session
+- Fixed persona selection so workspace and model personas override the default base persona instead of appending duplicate base personas.
+- Fixed Codex Responses streaming to preserve ordered response items, replay assistant phase metadata, and keep commentary/tool-planning text out of visible assistant output.
+- Fixed Codex multi-turn requests with `store: false` by not replaying server-assigned response item ids.
+- Fixed RPC session listing to include each session's persisted provider, model, and reasoning effort so pickers can show session-specific runtime state.
+
+## [0.68.0] - 2026-06-14
+
+In this release, most changes are under the hood, as it included massive refactors to have an even more robust way forward.
+
+### Added
+
+- Added Anthropic Claude Pro/Max subscription provider support with OAuth login, static Claude model choices, and Anthropic Messages streaming.
+
+### Changed
+
+- Changed known context windows and reasoning effort choices to use provider/model-specific metadata for Codex, OpenRouter, Copilot, and Anthropic models.
+- Changed the default Anthropic model to Claude Sonnet 4.6 and expanded direct Anthropic model choices to include newer Claude Opus/Sonnet releases.
+- Changed resumed sessions to restore the session's last-used provider, model, and reasoning effort without rewriting default config.
+- Documented the tool contract: schemas define strict generated/returned payloads, while runtime accepts tolerant incoming tool-call input for compatibility.
+- Expanded RDoc coverage past 50% across message compatibility, tool-call normalization, session persistence, session tree helpers, model/client boundaries, config paths, workspace operations, telemetry, RPC, plugins, memory, auth, compaction, search internals, CLI mixins, and prompt interface components.
+
+### Fixed
+
+- Fixed session tree editing and RPC fork text so prompt-template turns use the original visible slash command instead of expanded model content.
+
 ## [0.67.1] - 2026-06-14
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.67.1)
+    kward (0.69.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -22,6 +22,8 @@ GEM
       prism (~> 1.5)
     nokogiri (1.19.3-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-linux-gnu)
+      racc (~> 1.4)
     pastel (0.8.0)
       tty-color (~> 0.5)
     prism (1.9.0)
@@ -36,6 +38,7 @@ GEM
       tsort
     stringio (3.2.0)
     tiktoken_ruby (0.0.16-arm64-darwin)
+    tiktoken_ruby (0.0.16-x86_64-linux)
     tsort (0.2.0)
     tty-color (0.6.0)
     tty-cursor (0.7.1)
@@ -53,6 +56,7 @@ GEM
 PLATFORMS
   arm64-darwin
   arm64-darwin-25
+  x86_64-linux
 
 DEPENDENCIES
   kward!
@@ -66,9 +70,10 @@ CHECKSUMS
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
-  kward (0.67.1)
+  kward (0.69.0)
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
   nokogiri (1.19.3-arm64-darwin) sha256=71b9bd424b1b7abc18b05052a1a3cfd3627abdca62be280854cc411791357e42
+  nokogiri (1.19.3-x86_64-linux-gnu) sha256=2f5078620fe12e83669b5b17311b32532a8153d02eee7ad06948b926d6080976
   pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   psych (5.4.0) sha256=14f72d69a611af663d7d70e4a7b67d9eb1f3ae9f8d916b478961d5a0075ba5b7
@@ -77,6 +82,7 @@ CHECKSUMS
   rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   tiktoken_ruby (0.0.16-arm64-darwin) sha256=3da6fe850bf920d08c7eb736673f50bc9d08e8f2e17d34904ad3185a73fc9da7
+  tiktoken_ruby (0.0.16-x86_64-linux) sha256=4d970b8e68a86972ec81799306116480b33a558c06bb4fe0092852280a4b76b2
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   tty-color (0.6.0) sha256=6f9c37ca3a4e2367fb2e6d09722762647d6f455c111f05b59f35730eeb24332a
   tty-cursor (0.7.1) sha256=79534185e6a777888d88628b14b6a1fdf5154a603f285f80b1753e1908e0bf48

data/README.md

@@ -2,11 +2,32 @@
 
 Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run confirmed shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.
 
-It currently supports the OpenAI/ChatGPT Codex backend, OpenRouter, and experimental Copilot provider support.
+It currently supports the OpenAI/ChatGPT Codex backend, Anthropic Claude Pro/Max subscription, OpenRouter, and experimental Copilot provider support.
+
+## Why use Kward?
+
+Kward is designed for working with real projects, not isolated prompts.
+
+Typical workflows include:
+
+- 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"
+```
 
 ## Install
 
-Kward is being prepared for a RubyGems release. Once published, install it with:
+Install Kward from RubyGems:
 
 ```bash
 gem install kward
@@ -18,7 +39,7 @@ Optionally install the starter pack after installation:
 kward init
 ```
 
-This downloads Kward's default prompts and base `AGENTS.md` into your config directory. It is useful for a first setup, but safe to skip if you prefer to create your own instructions. Existing files are left untouched.
+This downloads Kward's default prompts and base `PRINCIPLES.md` into your config directory. It is useful for a first setup, but safe to skip if you prefer to create your own instructions. Existing files are left untouched.
 
 Then start Kward and sign in when needed:
 
@@ -33,29 +54,11 @@ kward --working-directory ~/code/project "Explain this project"
 
 See [Authentication](doc/authentication.md) for more details about sign-in options and provider credentials.
 
-## Run from source
-
-If you are working from a checkout:
-
-```bash
-bundle install
-ruby lib/main.rb login                    # sign in or save provider credentials
-ruby lib/main.rb                          # start an interactive chat
-ruby lib/main.rb help                     # show available commands and examples
-ruby lib/main.rb "Explain this project"   # run one prompt and exit
-```
-
-You can also use the executable directly after installing dependencies:
-
-```bash
-exe/kward
-```
-
 ## What Kward can do
 
 - Keep a multi-turn coding conversation in your terminal.
-- Read, write, and edit workspace files with confirmation before changes.
-- Run shell commands after confirmation.
+- 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.
@@ -69,13 +72,14 @@ Start here:
 - [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, OpenRouter API keys, and Copilot/GitHub setup.
+- [Authentication](doc/authentication.md): OpenAI OAuth, Anthropic OAuth, OpenRouter API keys, and Copilot/GitHub setup.
 - [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
 
 Feature guides:
 
 - [Memory](doc/memory.md): opt-in core, soft, and session memory.
-- [Extensibility](doc/extensibility.md): `AGENTS.md`, personas, skills, and prompt templates.
+- [Personas](doc/personas.md): configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
+- [Extensibility](doc/extensibility.md): `PRINCIPLES.md`, workspace `AGENTS.md`, skills, prompt templates, and extension choices.
 - [Plugins](doc/plugins.md): trusted Ruby plugins for commands, footer UI, prompt context, transcript events, and RPC clients.
 - [Web search](doc/web-search.md): live search providers and network behavior.
 - [Code search](doc/code-search.md): package lookup, GitHub repository cache, and external source reading.
@@ -85,21 +89,24 @@ Advanced/reference:
 - [RPC protocol](doc/rpc.md): experimental JSON-RPC backend mode for UI clients.
 - [Releasing](doc/releasing.md): release checklist for RubyGems publishing.
 
-## Run tests
+## Development
+
+Run tests:
 
 ```bash
 bundle exec rake test
 ```
 
-Equivalent direct command:
+Build the YARD documentation site:
 
 ```bash
-ruby -Itest -e 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }'
+bundle exec rake docs:build
 ```
 
-## Generate API documentation
+The generated site is written to `_yardoc/`. Pushes to `main` deploy that directory to GitHub Pages.
+
+Generate the RDoc API documentation:
 
 ```bash
 bundle exec rake rdoc
-bundle exec yard doc
 ```

data/Rakefile

@@ -1,3 +1,4 @@
+require "fileutils"
 require "rdoc/task"
 require "yard"
 require "yard/rake/yardoc_task"
@@ -16,5 +17,17 @@ end
 
 YARD::Rake::YardocTask.new do |yard|
   yard.files = ["lib/**/*.rb", "-", "README.md", "CHANGELOG.md", "LICENSE", "doc/**/*.md"]
-  yard.options = ["--readme", "README.md", "--output-dir", "_yardoc", "--markup", "markdown"]
+  yard.options = [
+    "--readme", "README.md",
+    "--output-dir", "_yardoc",
+    "--markup", "markdown",
+    "--template-path", "templates"
+  ]
+end
+
+namespace :docs do
+  desc "Build the YARD documentation site"
+  task build: :yard do
+    FileUtils.touch("_yardoc/.nojekyll")
+  end
 end

data/doc/authentication.md

@@ -1,54 +1,56 @@
 # Authentication
 
-Kward needs credentials for a model provider before it can answer prompts. The easiest path is to start Kward and run `/login`.
+Kward needs access to a model provider before it can answer prompts. The fastest path is:
 
-Kward supports:
-
-- OpenAI/ChatGPT OAuth for the Codex backend.
-- OpenRouter API keys.
-- GitHub OAuth or `COPILOT_GITHUB_TOKEN` for experimental Copilot provider support.
-
-If you installed the gem, use `kward` in the examples below. When running from source, use `ruby lib/main.rb` instead.
-
-## Quick login
+```bash
+kward login
+```
 
-Inside an interactive session:
+Or inside interactive Kward:
 
 ```text
 /login
 ```
 
-Kward opens a provider picker and saves the selected credentials.
+Use the provider you already have access to. You can change providers later.
+
+## 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. |
 
-From your shell, you can also run:
+If you are unsure, start with `kward login` and choose OpenAI.
+
+## Login commands
 
 ```bash
 kward login              # OpenAI/ChatGPT OAuth
-kward login openrouter   # save an OpenRouter API key
+kward login anthropic    # Anthropic Claude Pro/Max OAuth
+kward login openrouter   # OpenRouter API key
 kward login github       # GitHub OAuth for experimental Copilot support
 ```
 
-## OpenAI OAuth
-
-OpenAI OAuth is the default provider path when credentials are available. It uses your ChatGPT account and sends requests to the ChatGPT/Codex backend (`chatgpt.com/backend-api/codex/responses`), not the OpenAI Platform API.
+From source, replace `kward` with `ruby lib/main.rb`.
 
-To start the browser login from your shell:
+## OpenAI / ChatGPT
 
 ```bash
 kward login
 ```
 
-In an interactive session, run `/login` and choose OpenAI.
-
-Complete the browser redirect flow. Tokens are saved to:
+This opens a browser login and saves credentials to:
 
 ```text
 ~/.kward/auth.json
 ```
 
-The auth file is written with file mode `0600`.
+Kward uses the ChatGPT/Codex backend, not the OpenAI Platform API key flow.
 
-OpenAI OAuth requires an OAuth client ID in `~/.kward/config.json`:
+If Kward asks for an OAuth client ID, add it to `~/.kward/config.json`:
 
 ```json
 {
@@ -56,50 +58,89 @@ OpenAI OAuth requires an OAuth client ID in `~/.kward/config.json`:
 }
 ```
 
-If it is missing, Kward tells you which config file to update.
+## Anthropic Claude Pro/Max
 
-## OpenRouter API key
+```bash
+kward login anthropic
+```
 
-OpenRouter uses an API key rather than OAuth. To save it from your shell:
+This saves credentials to:
+
+```text
+~/.kward/anthropic_auth.json
+```
+
+Use this when you want Kward to use your Claude Pro/Max subscription. Kward refreshes the access token when a refresh token is available.
+
+## OpenRouter
 
 ```bash
 kward login openrouter
 ```
 
-In an interactive session, run `/login` and choose OpenRouter.
+This stores your API key in `~/.kward/config.json`.
 
-Kward saves the key as `openrouter_api_key` in `~/.kward/config.json`. You can also set `OPENROUTER_API_KEY` for a single run without saving it.
+For a single shell session, you can avoid saving the key:
 
-## GitHub OAuth for Copilot provider support
+```bash
+OPENROUTER_API_KEY=sk-or-v1-... kward
+```
 
-Kward can use a GitHub token for experimental Copilot provider support.
+Choose OpenRouter when you want access to its model catalog or want provider/model selection through an API key.
 
-The GitHub device flow uses a built-in default client ID unless you set `GITHUB_OAUTH_CLIENT_ID` or add `github_oauth_client_id` to `~/.kward/config.json`. To log in:
+## Experimental Copilot support
 
 ```bash
 kward login github
 ```
 
-Tokens are saved to:
+This saves GitHub OAuth credentials to:
 
 ```text
 ~/.kward/github_auth.json
 ```
 
-The auth file is written with file mode `0600`.
+You can also use a token for one run:
+
+```bash
+COPILOT_GITHUB_TOKEN=... kward
+```
+
+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.
+
+## Which credential wins?
+
+If multiple credentials are available, Kward uses the configured provider.
+
+Set it in `~/.kward/config.json`:
+
+```json
+{
+  "provider": "anthropic"
+}
+```
+
+Or for one command:
 
-You can also run `/login` in an interactive session and choose GitHub, or provide `COPILOT_GITHUB_TOKEN` for a single run.
+```bash
+KWARD_PROVIDER=openrouter kward
+```
 
-Important: Kward's Copilot provider follows Pi Agent's direct HTTPS approach. It exchanges the GitHub OAuth token for a Copilot internal token and sends chat requests to the Copilot proxy API. It does not use the official Copilot CLI or SDK runtime.
+Supported provider values:
 
-## Fallback and provider selection
+```text
+codex
+anthropic
+openrouter
+copilot
+```
 
-Credential priority is provider-aware:
+Without an explicit provider, OpenAI/ChatGPT credentials are preferred when present.
 
-- OpenAI OAuth is used by default after login, even when `OPENROUTER_API_KEY` or `openrouter_api_key` is also present.
-- `OPENAI_ACCESS_TOKEN` can be used as an OpenAI environment fallback.
-- `OPENROUTER_API_KEY` is a fallback only when no OpenAI OAuth/access token exists.
-- `COPILOT_GITHUB_TOKEN` can be used as a Copilot environment fallback.
-- If `provider` in config or `KWARD_PROVIDER` in the environment is set to `codex`, `openrouter`, or `copilot`, Kward uses that provider and does not fall through to another provider.
+## Security notes
 
-See [Configuration](configuration.md) for model and provider settings.
+- 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 saved credentials.

data/doc/code-search.md

@@ -1,56 +1,83 @@
 # Code search
 
-Kward exposes a `code_search` tool so the agent can inspect public open-source code for implementation guidance.
+Code search lets Kward inspect public open-source repositories while working on your project.
 
-Use code search when you want Kward to learn from real packages before changing your project. It is useful for checking library APIs, finding examples, comparing implementation patterns, or understanding how another project solved a similar problem.
+Use it when examples from real packages would make an answer better:
+
+- checking how a library API is actually used,
+- finding test patterns before adding tests,
+- comparing implementation approaches,
+- reading source for a dependency,
+- investigating a public bug fix or release.
 
 Example prompts:
 
 ```text
 Look up how tty-prompt handles key bindings before changing our composer.
 Find examples of Faraday retry middleware usage.
-Inspect how Rails structures this kind of generator test.
+Inspect how Rails structures generator tests.
+Check the source for this gem before recommending an API call.
 ```
 
-The tool can:
+## How it works
+
+The `code_search` tool can:
+
+1. find package metadata from registries,
+2. discover likely GitHub repositories,
+3. clone public repositories into a local cache,
+4. search cached files,
+5. read bounded line ranges from cached files.
 
-- look up packages from RubyGems, npm, PyPI, crates.io, and Go package documentation
-- find public GitHub source repositories from package metadata
-- fall back to GitHub repository search when registry metadata has no source URL
-- clone public GitHub repositories into Kward's cache
-- search cached repository files and return bounded snippets with paths and line numbers
-- read bounded line ranges from cached repository files
-- list, refresh, and clear cached repositories
+Kward should use this when the best answer depends on how another project actually implemented something.
 
-## Cache
+## Cache location
 
-Repositories are cloned under:
+Repositories are cached outside your workspace:
 
 ```text
 ~/.kward/cache/code_search
 ```
 
-If `KWARD_CONFIG_PATH` points at another config location, the cache is stored next to that config directory under `cache/code_search`.
+If `KWARD_CONFIG_PATH` points elsewhere, the cache lives beside that config directory under:
+
+```text
+cache/code_search
+```
 
-The tool keeps cloned repositories outside the current workspace. It uses safe cache keys derived from GitHub `owner/name` identifiers and rejects absolute paths or path traversal when reading files.
+The cache is intentionally separate from your project. Kward uses GitHub `owner/name` cache keys and rejects absolute paths or path traversal when reading cached files.
 
 ## GitHub access
 
-`code_search` uses live network access and the local `git` executable. GitHub authentication is optional. If either `GITHUB_TOKEN` or `GH_TOKEN` is set, the token is sent to GitHub API requests. Without a token, GitHub requests are unauthenticated and may hit lower rate limits.
+Code search uses live network access and the local `git` executable.
+
+GitHub authentication is optional. To raise rate limits, set either:
+
+```bash
+GITHUB_TOKEN=...
+```
+
+or:
+
+```bash
+GH_TOKEN=...
+```
 
-Tokens are not included in tool output.
+Tokens are used for GitHub API requests and are not included in tool output.
 
-## Actions
+## Tool actions
 
-The tool has one schema with an `action` parameter:
+The tool uses an `action` parameter:
 
-- `package_search` - find package metadata and likely source repository
-- `github_search` - search public GitHub repositories
-- `repo_clone` - clone a GitHub repository into cache if needed
-- `repo_search` - search cached repository files for text
-- `repo_read` - read a bounded line range from a cached repository file
-- `list_cache` - list cached repositories
-- `refresh_cache` - fetch updates for a cached repository
-- `clear_cache` - remove one cached repository
+| Action | Use it to... |
+| --- | --- |
+| `package_search` | find package metadata and likely source repositories. |
+| `github_search` | search public GitHub repositories. |
+| `repo_clone` | clone a GitHub repository into cache. |
+| `repo_search` | search files in a cached repository. |
+| `repo_read` | read a bounded line range from a cached file. |
+| `list_cache` | show cached repositories. |
+| `refresh_cache` | fetch updates for a cached repository. |
+| `clear_cache` | remove a cached repository. |
 
-Search and read output is bounded to avoid loading excessive external source into context. Oversized and binary files are skipped.
+Search and read results are bounded so Kward does not load large external repositories into context by accident. Oversized and binary files are skipped.