kward 0.70.0 → 0.71.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12e9e888bceffd64f87f36ea3aa79e4108901e92a193db7c86e588abef789f04
-  data.tar.gz: 4b69dcc0fca28d026931ec809bba3f2b64ad12b37930df51454ad80003104ac0
+  metadata.gz: 2c53686afdfbf5de822759d70cb696e911cae8c5ffc7b5ce63e07306dc4ffaac
+  data.tar.gz: '086c43642ad0149e3986277b7424b55f2dc50689a0e876c72e6bb9fd48e4272b'
 SHA512:
-  metadata.gz: d372a52d9eb15695e33f6723d060ea051a8cda166e3692c5b3f634a1d7ca5cd7b533dc8afc41f88f39228af095af049c8b767c3d9696e846fb99b58218fdae5f
-  data.tar.gz: 7ff32c27130676339ab62bccbbc2777c5a382c8adf66f4d1fec525d4c12ecea0aa8d563814c331f409f8c030f0236cc3dd727405955c4bedcb96705c94d42aec
+  metadata.gz: 97ebbbf26feedc4dd46d53d7af8b900670edf861cb40f6103eff5ea8579d605517cab49751ea5fe46c4023fa7ba8ced367d31290b34af463fd0cc8f1a9a1087e
+  data.tar.gz: 424ac657d7efc70f2b87924914112c0910937deee7e4ec6521448ff4fe51967a58203de9693fb8989adea63fb23adef93668333c8bb5eb22963bff49e7420875

data/.github/workflows/pages.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
+          ruby-version: '3.3'
           bundler-cache: true
 
       - name: Build documentation

data/CHANGELOG.md

@@ -4,15 +4,61 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
-## [0.70.0] - 2026-06-18
+## [0.71.0] - 2026-06-21
+
+### Fixed
+
+- Fixed generated YARD guide links so doc-to-doc Markdown links point at the generated `file.*.html` pages.
+- Fixed web-tool results with BINARY/ASCII-8BIT response bodies so RPC tool events and TUI rendering receive UTF-8-safe content.
+
+### Changed
+
+- Changed transcript rendering so assistant, reasoning, and tool output starts on the same line as its label.
+- Changed the interactive startup screen to an info block.”
+- Changed shell command output capture to allow larger raw output for Kward's own compactor, preserving stdout/stderr structure and test failure summaries before model-context trimming.
+- Tightened the built-in system prompt wording to reduce repeated instruction tokens.
+- Changed generated runtime system prompts to use a stable timestamp anchor so time-based persona modifiers do not churn provider cache prefixes each turn.
+- Changed tool schema properties to be emitted in deterministic key order for more stable provider request payloads.
+- Changed large source-file reads to return an outline plus a short preview before requiring offset/limit continuation.
+- Changed large search and fetched-content tool results to preserve file, line, URL, and heading anchors during model-context compaction.
+- Changed large tool results to be compacted before they enter model context while preserving full originals in session tool-execution records, reusing existing artifact ids for repeated outputs, avoiding storage for verbatim outputs, preserving short errors exactly, reverting automatically when compaction would not reduce context, and teaching conversation compaction to preserve tool artifact ids.
+- Changed model context-window resolution to prefer cached OpenRouter metadata, infer matching provider models from that metadata when possible, and use conservative fallbacks for unknown selected models.
+- Updated the authentication guide to describe model picker selection and OpenRouter model cache refresh/list commands.
+
+### Removed
+
+- Removed the `banner.enabled` config setting and `/settings` toggle for hiding the interactive startup screen.
+- Removed the generated table of contents and source-checkout launch snippet from the RPC protocol guide.
+
+### Added
+
+- Added a Sessions guide covering saved sessions, cloning, forking, rewinding, tree navigation, compaction, and exports.
+- Added Agent Tools documentation pages covering workspace tools, context tools, and token-saving tool-output behavior.
+- Added an API reference overview page and API docs navigation dropdown for generated Ruby indexes and key namespaces.
+- Added Turbolinks-style navigation to the generated documentation site for same-origin HTML links.
+- Added a `docs:check` Rake task and HTMLProofer development dependency for checking generated documentation links, images, and scripts.
+- Added a `docs:serve` Rake task and WEBrick development dependency for previewing the built YARD documentation site locally with automatic rebuilds.
+- Added optional `compaction` telemetry logging for tool-output context savings.
+- Added a `summarize_file_structure` tool for compact source-file outlines before reading full files.
+- Added a `retrieve_tool_output` tool for inspecting original outputs that were compacted out of model context.
+- Added `kward openrouter refresh` and `kward openrouter list` for caching key-scoped text-capable OpenRouter models in the Kward cache directory.
+- Added `/fork` for creating a new session from an earlier prompt and pre-filling that prompt for editing.
+- Added `f` in the `/sessions` picker to open the fork prompt selector for the selected session.
+- Added `/rename <name>` for renaming the current interactive session.
+- Added `r` in the `/sessions` picker to rename the selected session without closing the picker.
+- Added `c` in the `/sessions` picker to clone the selected session and open the new clone, with a cloning spinner while it runs.
+- Added `d d` in the `/sessions` picker to delete the selected session after an inline confirmation.
+
+## [0.70.0] - 2026-06-19
 
 ### Added
 
-- Added `z-ai/glm-5.2` to the static OpenRouter model choices.
 - Added `/rewind` for revisiting earlier user prompts and continuing from there as a branch, while `/tree` remains the advanced full session tree navigator.
 
 ### Changed
 
+- Changed TUI selection search to start only after pressing `/`, hiding the composer cursor until search mode is active and supporting shell-style editing keys while searching.
+- Changed the `/sessions` picker to show right-aligned relative timestamps like `/rewind`.
 - Changed TUI list navigation to keep long `/sessions` and `/tree` pickers centered while scrolling, and removed wrap-around at list edges.
 - Changed the saved session picker slash command to `/sessions`, with `/resume` kept as an alias.
 

data/Gemfile

@@ -2,7 +2,9 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "html-proofer"
 gem "minitest"
 gem "rake"
 gem "rdoc"
+gem "webrick"
 gem "yard"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.69.1)
+    kward (0.71.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -13,10 +13,50 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    Ascii85 (2.0.1)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    afm (1.0.0)
+    async (2.39.0)
+      console (~> 1.29)
+      fiber-annotation
+      io-event (~> 1.11)
+      metrics (~> 0.12)
+      traces (~> 0.18)
     base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (3.3.1)
+    console (1.36.0)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
     date (3.5.1)
     drb (2.2.3)
     erb (6.0.4)
+    ethon (0.18.0)
+      ffi (>= 1.15.0)
+      logger
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
+    hashery (2.1.2)
+    html-proofer (5.2.1)
+      addressable (~> 2.3)
+      async (~> 2.1)
+      benchmark (~> 0.5)
+      nokogiri (~> 1.13)
+      pdf-reader (~> 2.11)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
+    io-event (1.16.2)
+    json (2.19.9)
+    logger (1.7.0)
+    metrics (0.15.0)
     minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
@@ -26,20 +66,32 @@ GEM
       racc (~> 1.4)
     pastel (0.8.0)
       tty-color (~> 0.5)
+    pdf-reader (2.15.1)
+      Ascii85 (>= 1.0, < 3.0, != 2.0.0)
+      afm (>= 0.2.1, < 2)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
     prism (1.9.0)
     psych (5.4.0)
       date
       stringio
+    public_suffix (7.0.5)
     racc (1.8.1)
+    rainbow (3.1.1)
     rake (13.3.1)
     rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
+    ruby-rc4 (0.1.5)
     stringio (3.2.0)
     tiktoken_ruby (0.0.16-arm64-darwin)
     tiktoken_ruby (0.0.16-x86_64-linux)
+    traces (0.18.2)
     tsort (0.2.0)
+    ttfunk (1.8.0)
+      bigdecimal (~> 3.1)
     tty-color (0.6.0)
     tty-cursor (0.7.1)
     tty-prompt (0.23.1)
@@ -50,8 +102,13 @@ GEM
       tty-screen (~> 0.8)
       wisper (~> 2.0)
     tty-screen (0.8.2)
+    typhoeus (1.6.0)
+      ethon (>= 0.18.0)
+    webrick (1.9.2)
     wisper (2.0.1)
     yard (0.9.44)
+    yell (2.2.2)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   arm64-darwin
@@ -59,38 +116,69 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  html-proofer
   kward!
   minitest
   rake
   rdoc
+  webrick
   yard
 
 CHECKSUMS
+  Ascii85 (2.0.1) sha256=15cb5d941808543cbb9e7e6aea3c8ec3877f154c3461e8b3673e97f7ecedbe5a
+  addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+  afm (1.0.0) sha256=5bd4d6f6241e7014ef090985ec6f4c3e9745f6de0828ddd58bc1efdd138f4545
+  async (2.39.0) sha256=df18730073f2bbb45788077dfa20cb365ecc1b9453969f44de6796b5191a00aa
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
+  bigdecimal (3.3.1) sha256=eaa01e228be54c4f9f53bf3cc34fe3d5e845c31963e7fcc5bedb05a4e7d52218
+  console (1.36.0) sha256=45599ea906cf80a73d8941f03abf873fe66a6a954e0bac5bc1c01e2cdc406f07
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
-  kward (0.69.1)
+  ethon (0.18.0) sha256=b598afc9f30448cb068b850714b7d6948e941476095d04f90a4ac65b8d6efcb2
+  ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
+  ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
+  fiber-annotation (0.2.0) sha256=7abfadf1d119f508867d4103bf231c0354d019cc39a5738945dec2edadaf6c03
+  fiber-local (1.1.0) sha256=c885f94f210fb9b05737de65d511136ea602e00c5105953748aa0f8793489f06
+  fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
+  hashery (2.1.2) sha256=d239cc2310401903f6b79d458c2bbef5bf74c46f3f974ae9c1061fb74a404862
+  html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
+  io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
+  json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
+  kward (0.71.0)
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   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
+  pdf-reader (2.15.1) sha256=18c6a986a84a3117fa49f4279fc2de51f5d2399b71833df5d2bccd595c7068ce
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   psych (5.4.0) sha256=14f72d69a611af663d7d70e4a7b67d9eb1f3ae9f8d916b478961d5a0075ba5b7
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
   rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
   rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
+  ruby-rc4 (0.1.5) sha256=00cc40a39d20b53f5459e7ea006a92cf584e9bc275e2a6f7aa1515510e896c03
   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
+  traces (0.18.2) sha256=80f1649cb4daace1d7174b81f3b3b7427af0b93047759ba349960cb8f315e214
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  ttfunk (1.8.0) sha256=a7cbc7e489cc46e979dde04d34b5b9e4f5c8f1ee5fc6b1a7be39b829919d20ca
   tty-color (0.6.0) sha256=6f9c37ca3a4e2367fb2e6d09722762647d6f455c111f05b59f35730eeb24332a
   tty-cursor (0.7.1) sha256=79534185e6a777888d88628b14b6a1fdf5154a603f285f80b1753e1908e0bf48
   tty-prompt (0.23.1) sha256=fcdbce905238993f27eecfdf67597a636bc839d92192f6a0eef22b8166449ec8
   tty-reader (0.9.0) sha256=c62972c985c0b1566f0e56743b6a7882f979d3dc32ff491ed490a076f899c2b1
   tty-screen (0.8.2) sha256=c090652115beae764336c28802d633f204fb84da93c6a968aa5d8e319e819b50
+  typhoeus (1.6.0) sha256=bacc41c23e379547e29801dc235cd1699b70b955a1ba3d32b2b877aa844c331d
+  webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
   wisper (2.0.1) sha256=ce17bc5c3a166f241a2e6613848b025c8146fce2defba505920c1d1f3f88fae6
   yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28
+  yell (2.2.2) sha256=1d166f3cc3b6dc49a59778ea7156ed6d8de794c15106d48ffd6cbb061b9b26bc
+  zeitwerk (2.8.2) sha256=7212a61311083c604184b1ea2574b9aa05cd14f855a0841c06985cabe9181d12
 
 BUNDLED WITH
   4.0.6

data/README.md

@@ -77,17 +77,25 @@ Start here:
 
 Feature guides:
 
+- [Sessions](doc/session-management.md): resume, clone, fork, rewind, compact, and navigate saved work.
 - [Memory](doc/memory.md): opt-in core, soft, and session memory.
 - [Personas](doc/personas.md): configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
-- [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.
 
-Advanced/reference:
+Advanced:
 
+- [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.
 - [RPC protocol](doc/rpc.md): experimental JSON-RPC backend mode for UI clients.
 - [Releasing](doc/releasing.md): release checklist for RubyGems publishing.
+- [Agent tools](doc/agent-tools.md): overview of model-callable tools, token-saving behavior, and tool categories.
+- [Workspace tools](doc/workspace-tools.md): local file, edit, and shell command tools.
+- [Web search](doc/web-search.md): live search providers and network behavior for the web search agent tool.
+- [Code search](doc/code-search.md): package lookup, GitHub repository cache, and external source reading for the code search agent tool.
+- [Context tools](doc/context-tools.md): skills, compacted output retrieval, and structured clarification questions.
+
+API reference:
+
+- [API reference](doc/api.md): generated Ruby API entry points, indexes, and public API expectations.
 
 ## Development
 
@@ -97,7 +105,15 @@ Run tests:
 bundle exec rake test
 ```
 
-Build the YARD documentation site:
+Preview the built YARD documentation site locally with automatic rebuilds:
+
+```bash
+bundle exec rake docs:serve
+```
+
+The preview builds `_yardoc/`, serves it with WEBrick using `Cache-Control: no-store`, and rebuilds in a fresh process when documentation sources, library code, or templates change. Generated HTML, images, CSS, and JavaScript match the published site. Open <http://localhost:8808/> and refresh your browser after rebuilds. Use `PORT=4000 bundle exec rake docs:serve` to choose another port.
+
+Build the static YARD documentation site for publishing:
 
 ```bash
 bundle exec rake docs:build
@@ -105,6 +121,14 @@ bundle exec rake docs:build
 
 The generated site is written to `_yardoc/`. Pushes to `main` deploy that directory to GitHub Pages.
 
+Check generated documentation links, images, and scripts:
+
+```bash
+bundle exec rake docs:check
+```
+
+External link checks are disabled by default for stable local runs. Enable them with `DOCS_CHECK_EXTERNAL=1 bundle exec rake docs:check`.
+
 Generate the RDoc API documentation:
 
 ```bash

data/Rakefile

@@ -1,8 +1,49 @@
 require "fileutils"
+require "html-proofer"
 require "rdoc/task"
+require "webrick"
 require "yard"
 require "yard/rake/yardoc_task"
 
+DOCS_WATCH_GLOBS = [
+  ".yardopts",
+  "CHANGELOG.md",
+  "LICENSE",
+  "README.md",
+  "doc/**/*.md",
+  "lib/**/*.rb",
+  "templates/**/*"
+].freeze
+
+def docs_watch_snapshot
+  DOCS_WATCH_GLOBS.flat_map { |pattern| Dir.glob(pattern) }
+                  .select { |path| File.file?(path) }
+                  .uniq
+                  .to_h { |path| [path, File.mtime(path)] }
+end
+
+def rebuild_docs
+  system({ "DOCS_SERVE_REBUILD" => "1" }, "bundle", "exec", "rake", "docs:build") || abort("Documentation rebuild failed")
+end
+
+def rewrite_yard_markdown_links
+  guide_names = Dir.glob("doc/*.md").map { |path| File.basename(path, ".md") }
+
+  Dir.glob("_yardoc/**/*.html").each do |path|
+    html = File.read(path)
+    rewritten = html.gsub(/href=(["'])(?:(?:\.\.\/)?doc\/)?([a-z0-9-]+)\.md(#[^"']*)?\1/) do |match|
+      quote = Regexp.last_match(1)
+      guide_name = Regexp.last_match(2)
+      anchor = Regexp.last_match(3).to_s
+      next match unless guide_names.include?(guide_name)
+
+      "href=#{quote}file.#{guide_name}.html#{anchor}#{quote}"
+    end
+
+    File.write(path, rewritten) unless rewritten == html
+  end
+end
+
 task default: :test
 
 task :test do
@@ -26,8 +67,63 @@ YARD::Rake::YardocTask.new do |yard|
 end
 
 namespace :docs do
+  desc "Serve the built YARD documentation site locally and rebuild on changes"
+  task serve: :build do
+    port = Integer(ENV.fetch("PORT", "8808"))
+    server = WEBrick::HTTPServer.new(
+      BindAddress: "127.0.0.1",
+      DocumentRoot: File.expand_path("_yardoc", __dir__),
+      Port: port
+    )
+
+    server.mount_proc "/" do |request, response|
+      WEBrick::HTTPServlet::FileHandler.new(server, File.expand_path("_yardoc", __dir__)).service(request, response)
+      response["Cache-Control"] = "no-store"
+    end
+
+    watcher = Thread.new do
+      snapshot = docs_watch_snapshot
+
+      loop do
+        sleep 1
+        current_snapshot = docs_watch_snapshot
+        next if current_snapshot == snapshot
+
+        snapshot = current_snapshot
+        puts "Documentation changed; rebuilding _yardoc/. Refresh your browser when it finishes."
+        rebuild_docs
+        puts "Documentation rebuilt."
+      rescue StandardError => error
+        warn "Documentation rebuild failed: #{error.class}: #{error.message}"
+      end
+    end
+
+    trap("INT") { server.shutdown }
+    trap("TERM") { server.shutdown }
+
+    puts "Serving documentation at http://localhost:#{port}/"
+    puts "Watching documentation sources for changes. Refresh your browser after rebuilds."
+    server.start
+  ensure
+    watcher&.kill
+  end
+
   desc "Build the YARD documentation site"
   task build: :yard do
+    rewrite_yard_markdown_links
     FileUtils.touch("_yardoc/.nojekyll")
   end
+
+  desc "Check generated documentation links and images"
+  task check: :build do
+    options = {
+      checks: ["Images", "Links", "Scripts"],
+      allow_missing_href: true,
+      disable_external: ENV["DOCS_CHECK_EXTERNAL"] != "1",
+      enforce_https: false,
+      ignore_urls: [/^$/]
+    }
+
+    HTMLProofer.check_directory("_yardoc", options).run
+  end
 end

data/doc/agent-tools.md

@@ -0,0 +1,43 @@
+# Agent tools
+
+Agent tools are the model-callable operations Kward uses to inspect projects, change files, run commands, search outside sources, and ask for clarification. Most users do not call these tools directly. You ask for an outcome in natural language, and Kward decides which tools are needed.
+
+Tools are part of Kward's safety and context-management boundary:
+
+- schemas describe what the model is allowed to call,
+- Ruby tool objects validate and execute those calls,
+- workspace tools stay inside the active workspace by default,
+- file-changing tools require the file to be read first,
+- large outputs are bounded or compacted before they enter model context,
+- full tool outputs are kept in the session record for later inspection.
+
+## Tool categories
+
+| Category | Tools | Guide |
+| --- | --- | --- |
+| Workspace tools | `list_directory`, `read_file`, `summarize_file_structure`, `write_file`, `edit_file`, `run_shell_command` | [Workspace tools](workspace-tools.md) |
+| Web tools | `web_search`, `fetch_content`, `fetch_raw` | [Web search](web-search.md) |
+| Code search | `code_search` | [Code search](code-search.md) |
+| Context and interaction tools | `read_skill`, `retrieve_tool_output`, `ask_user_question` | [Context tools](context-tools.md) |
+
+## How tools save tokens
+
+Kward tries to keep tool context useful without flooding the model:
+
+- `read_file` reads bounded line ranges and supports continuation with `offset` and `limit`.
+- `summarize_file_structure` returns a compact outline for large source files before reading all code.
+- Search, fetch, and shell outputs are capped or compacted before model ingestion.
+- Repeated identical tool output is replaced with a short reference instead of being sent again.
+- Compacted outputs are stored as artifacts that can be reopened with `retrieve_tool_output`.
+
+This lets the assistant reason from focused evidence while preserving access to original outputs when needed.
+
+## How tools are exposed
+
+`Kward::ToolRegistry` builds the available tool objects and the schemas advertised to the model. Some tools are always available in normal CLI/RPC sessions, while others depend on configuration or frontend capability:
+
+- web tools can be hidden with web search configuration,
+- `read_skill` is advertised only when skills are available,
+- `ask_user_question` is advertised only when the frontend can display structured questions.
+
+Unknown tool calls are recorded as tool results instead of crashing the session, so the model can recover and choose an advertised tool on the next turn.

data/doc/api.md

@@ -0,0 +1,92 @@
+# API reference
+
+Kward's generated Ruby API documentation is mainly for contributors, plugin authors, tool authors, and people building RPC or editor integrations.
+
+If you use Kward from the terminal, start with the [user guides](file.README.html#Documentation) instead. The API reference exposes many internal classes because it is generated from the source tree; not every documented class is a stable extension API.
+
+## Start here
+
+- [Classes and modules](class_list.html): searchable index of generated Ruby constants.
+- [Methods](method_list.html): searchable index of generated Ruby methods.
+- [Files](file_list.html): generated file index.
+- [Top-level Kward namespace](Kward.html): root namespace for the generated reference.
+
+## Start by role
+
+### Plugin authors
+
+Use plugins when you need trusted local Ruby code for slash commands, prompt context, footer UI, transcript events, or RPC-visible commands.
+
+Read first:
+
+- [Plugins](plugins.md)
+- [Extensibility](extensibility.md)
+
+Generated entry points:
+
+- [`Kward.plugin`](Kward.html#plugin-class_method)
+- [`Kward::PluginRegistry`](Kward/PluginRegistry.html)
+- [`Kward::PluginRegistry::DSL`](Kward/PluginRegistry/DSL.html)
+- [`Kward::PluginRegistry::Context`](Kward/PluginRegistry/Context.html)
+
+### Tool authors and contributors
+
+Built-in tools are Ruby classes registered with Kward's tool registry. They expose schemas to the model and execute bounded local operations.
+
+Read first:
+
+- [Usage](usage.md#Workspace_tools)
+- [Web search](web-search.md)
+- [Code search](code-search.md)
+
+Generated entry points:
+
+- [`Kward::Tools`](Kward/Tools.html)
+- [`Kward::Tools::Base`](Kward/Tools/Base.html)
+- [`Kward::ToolRegistry`](Kward/ToolRegistry.html)
+
+### RPC and frontend authors
+
+The RPC protocol is the supported integration surface for UI clients. Prefer the protocol guide before reading implementation classes.
+
+Read first:
+
+- [RPC protocol](rpc.md)
+
+Generated entry points:
+
+- [`Kward::RPC`](Kward/RPC.html)
+- [`Kward::RPC::Server`](Kward/RPC/Server.html)
+- [`Kward::RPC::SessionManager`](Kward/RPC/SessionManager.html)
+- [`Kward::RPC::ToolEventNormalizer`](Kward/RPC/ToolEventNormalizer.html)
+
+### Prompt, skill, and configuration contributors
+
+Prompt templates, skills, personas, and project instructions are user-facing extension points. Prefer the guides for supported behavior, then use the API reference to inspect implementation details.
+
+Read first:
+
+- [Extensibility](extensibility.md)
+- [Personas](personas.md)
+- [Configuration](configuration.md)
+
+Generated entry points:
+
+- [`Kward::Prompts`](Kward/Prompts.html)
+- [`Kward::Prompts::Templates`](Kward/Prompts/Templates.html)
+- [`Kward::Skills`](Kward/Skills.html)
+- [`Kward::Skills::Registry`](Kward/Skills/Registry.html)
+- [`Kward::ConfigFiles`](Kward/ConfigFiles.html)
+
+## Public API expectations
+
+Kward is still evolving. The generated reference is useful for understanding the codebase, but it should not be read as a promise that every class, method, or constructor is public and stable.
+
+Prefer the documented guides for supported extension behavior. Use generated class and method pages when you need implementation detail, are contributing to Kward itself, or are coordinating a frontend integration with the current codebase.
+
+As a rule of thumb:
+
+- Guide-documented behavior is the supported user-facing surface.
+- Plugin DSL methods are intended extension points.
+- RPC JSON-RPC methods documented in [RPC protocol](rpc.md) are the integration contract for frontend clients.
+- Generated classes without guide coverage may be internal implementation details.