kward 0.67.1 → 0.69.0

data/doc/usage.md

@@ -1,214 +1,198 @@
 # Usage
 
-Kward's most common commands are:
+Kward has two main modes:
+
+- **Interactive chat** for ongoing work in a project.
+- **One-shot prompts** for quick questions, reviews, and summaries.
+
+Run Kward from the workspace you want it to inspect:
 
 ```bash
-kward                          # interactive chat
-kward help                     # command overview and examples
-kward "Explain this project"   # one-shot prompt
-kward init                     # optional first-time setup
-kward doctor                   # check local setup
-kward auth status              # show saved credential status
-kward pan                      # Pan mode web UI
-kward rpc                      # experimental JSON-RPC backend
+cd ~/code/project
+kward
 ```
 
 When running from source, replace `kward` with `ruby lib/main.rb`.
 
-## Starter pack
+## Common workflows
 
-Install Kward's starter prompts and base `AGENTS.md` into your config directory, usually `~/.kward`:
+### Understand a new project
 
-```bash
-kward init
+```text
+Explain the project structure and point out the main entry points.
 ```
 
-The installer downloads the pinned `kaiwood/kward-starter-pack` `v1.0.0` release, creates the config directory and base `config.json` if needed, and copies only starter-pack instruction/prompt files. It preserves the starter-pack layout in your config directory and skips files that already exist.
+Useful follow-ups:
 
-## Interactive chat
+```text
+Where is configuration loaded?
+Which files would I read first to understand authentication?
+Summarize the test strategy.
+```
 
-Interactive mode opens a terminal composer and saves the conversation as a per-workspace session. Use it when you want Kward to inspect files, make changes, run commands, or continue a conversation over time.
+### Review changes before committing
 
-The composer stays available while assistant and tool output streams. If you press Enter while a response is still running, Kward queues your next prompt and sends it after the current turn finishes. Press Ctrl+C while a response is running to stop the current turn and return to the composer.
+```bash
+git diff | kward "Review this diff for bugs, missing tests, and confusing naming"
+```
 
-Prefix input with `!` to run a local shell command from the workspace root without sending it to the model:
+For larger reviews, use interactive mode so Kward can inspect related files:
 
 ```text
-!git status --short
+Review the current git diff. If something looks risky, inspect the relevant files before recommending changes.
 ```
 
-## Shell commands
+### Make a small code change
 
-Use `kward help` or `kward --help` to print a colored overview of available commands and examples. Use `kward help <command>` or `<command> --help` for command-specific help. Use `kward version` or `kward --version` to print the installed version.
+```text
+Add a --json option to the status command. Keep the text output unchanged and add focused tests.
+```
 
-Use `kward doctor` to check local config, workspace, auth hints, Pan credentials, and writable directories. Use `kward auth status` to show saved credential status without printing secrets, or `kward auth logout` to remove saved OpenAI, GitHub, and OpenRouter credentials.
+Kward must read an existing file in the current conversation before editing it. This guardrail helps prevent accidental overwrites.
 
-Use `--working-directory PATH` with any mode to run Kward from a different workspace:
+### Run local checks
 
-```bash
-kward --working-directory ~/code/project
-kward --working-directory ~/code/project "Summarize this project"
-kward --working-directory ~/code/project pan
-kward --working-directory ~/code/project rpc
-```
+Inside interactive mode, ask Kward to run a command:
 
-## One-shot prompts
+```text
+Run the focused test for the CLI status command.
+```
 
-Command names take precedence. Invalid arguments for known commands show usage instead of becoming prompts. Anything else passed as command-line text is sent as a one-shot prompt:
+Or run a shell command yourself from the composer by prefixing it with `!`:
 
-```bash
-kward "Summarize the changes in this repository"
-kward Summarize the changes in this repository
+```text
+!git status --short
 ```
 
-Use `--` before the prompt when the prompt itself starts with a command name or contains option-like text:
+## Shell commands
+
+Useful shell commands:
 
 ```bash
-kward -- pan extra
-kward -- explain --working-directory option
+kward                          # start interactive chat
+kward "Explain this project"   # ask one question and exit
+kward help                     # show commands and examples
+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 rpc                      # start the experimental RPC backend
 ```
 
-Kward also accepts piped input:
+Use another workspace without changing directories:
 
 ```bash
-git diff | kward "Review this diff"
+kward --working-directory ~/code/project
+kward --working-directory ~/code/project "Summarize this repository"
 ```
 
-One-shot prompts do not use Kward memory.
+## Interactive slash commands
 
-## Workspace tools
+Use slash commands for local actions that should not go to the model:
 
-Kward can use these tools during a turn:
-
-- `list_directory` and `read_file` to inspect the workspace.
-- `write_file` and `edit_file` to create or change files.
-- `run_shell_command` to run confirmed local commands.
-- `web_search` to search the live web.
-- `code_search` to find packages, clone public GitHub repositories into cache, and read bounded source snippets.
-- `ask_user_question` to ask structured clarification questions.
-
-Safety rules:
-
-- Existing files must be read in the current conversation before Kward can write or edit them.
-- Every write, edit, and shell command asks for confirmation first.
-- Text file reads and edits are capped at 256 KiB per file.
-- When successful tool results include unified diffs, the composer status shows live session totals such as `+700|-572`.
-
-## Slash commands
-
-Use slash commands in interactive mode for local Kward actions:
-
-| Command | Purpose |
+| Command | Use it when you want to... |
 | --- | --- |
-| `/exit`, `/quit` | Leave the session. |
-| `/new` | Start a fresh session. |
-| `/resume [path]` | Resume a saved session, or pick one when no path is given. |
-| `/name [name]` | Name or clear the current session name. |
-| `/clone` | Duplicate the current session. |
-| `/copy [last\|transcript]` | Copy clean assistant text or the Markdown transcript to the clipboard. |
-| `/export [path]` | Export the transcript as Markdown. |
-| `/compact [instructions]` | Summarize older conversation into a checkpoint and keep recent context. |
-| `/model` | Choose or type the default model. |
-| `/openrouter/catalog` | List the full OpenRouter model catalog. |
-| `/reasoning` | Choose reasoning effort. |
-| `/settings` | Configure overlay alignment and width. |
-| `/login` | Log in from inside the session. |
-| `/status` | Show status and auto-compaction information. |
-| `/stats [range]` | Show local telemetry stats when logging is enabled. |
-| `/memory ...` | Manage opt-in memory. |
-| `/redraw` | Refresh the terminal after resize or drawing glitches. |
-
-Prompt templates can add more slash commands. Plugin commands can also appear when trusted local plugins are installed.
+| `/login` | sign in or save provider credentials. |
+| `/model` | choose the active model. |
+| `/reasoning` | choose reasoning effort. |
+| `/status` | see session, model, and context status. |
+| `/new` | start a fresh session. |
+| `/resume` | continue a previous session. |
+| `/name <name>` | name the current session. |
+| `/clone` | copy the current session into a new branch. |
+| `/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. |
+| `/memory ...` | manage opt-in memory. |
+| `/redraw` | fix terminal drawing after resize or glitches. |
+| `/exit` | leave Kward. |
+
+Prompt templates and plugins can add more slash commands.
 
 ## Sessions
 
-Interactive chats are stored as JSONL files under `~/.kward/sessions/`. Sessions are per workspace.
+Interactive chats are saved under:
 
-Useful session commands:
-
-- `/resume` opens a picker for recent sessions.
-- `/name <name>` gives the current session a human-readable name.
-- `/clone` creates a new independent copy. Cloned sessions remember their parent and appear in the recent session picker by modification time.
-- `/copy` and `/copy last` copy the latest assistant response without terminal borders or ANSI styling. `/copy transcript` copies the clean Markdown transcript. Mouse selection may still include terminal UI chrome.
-- `/export [path]` writes a Markdown transcript. Explicit paths are resolved relative to the current workspace and must stay inside the workspace or Kward session directory.
-- `/compact [instructions]` summarizes older conversation into a structured Ruby-aware checkpoint. Text after `/compact ` is freeform focus text, not parsed as flags.
+```text
+~/.kward/sessions/
+```
 
-After compaction, Kward may need to re-read files before future edits because compacting clears remembered read-file state.
+Sessions are scoped to the workspace. Use them when work spans more than one terminal sitting.
 
-## Auto-compaction
+Typical flow:
 
-Auto-compaction is enabled by default when Kward can determine the active context window. It reserves part of the model context so conversations can continue longer without suddenly exceeding the limit.
+```text
+/name oauth cleanup
+# work with Kward
+/export oauth-notes.md
+/exit
+```
 
-Configure it in `config.json`:
+Later:
 
-```json
-{
-  "compaction": {
-    "enabled": true,
-    "reserve_tokens": 16384,
-    "keep_recent_tokens": 20000
-  }
-}
+```text
+/resume
 ```
 
-Manual `/compact` still works when auto-compaction is disabled.
+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.
 
-## Memory
-
-Memory is disabled by default and only applies to interactive sessions.
+## One-shot prompts
 
-Common commands:
+One-shot prompts are best for short tasks that do not need session history:
 
-```text
-/memory enable
-/memory core <text>
-/memory add <text>
-/memory list
-/memory why
-/memory promote <id>
-/memory relax <id>
-/memory forget <id>
-/memory disable
+```bash
+kward "What does this repository do?"
+git diff | kward "Review this diff"
+cat error.log | kward "Explain the likely cause"
 ```
 
-See [Memory](memory.md) for storage locations, safety rules, auto-summary, and RPC methods.
+Use `--` when your prompt starts with something that could be parsed as a command or option:
 
-## Composer keys
+```bash
+kward -- explain --working-directory
+```
 
-- Enter sends.
-- Shift+Enter inserts a newline.
-- Up/Down browse prompt history.
-- Ctrl+D exits from an empty prompt.
-- Ctrl+C stops the current response while assistant or tool output is running.
-- Backspace at the beginning of the prompt removes the most recent image attachment.
+One-shot prompts do not use Kward memory.
 
-Multiline input grows the composer up to a capped height.
+## Workspace tools
 
-## Image attachments
+During a turn, Kward can inspect and change the workspace with tools for:
 
-Kward can attach images when the active model supports images. It detects:
+- listing and reading files,
+- creating and editing files,
+- running shell commands,
+- searching the web,
+- fetching specific URLs,
+- inspecting public source repositories,
+- asking structured clarification questions.
 
-- pasted image file paths,
-- Markdown image links,
-- `file://` image URLs,
-- image data URLs.
+Important guardrails:
 
-In the interactive composer, pasted image references appear as attachment badges instead of editable filename or base64 text. Transcripts show attachment badges and render the image inline when the terminal advertises a supported inline image protocol, such as iTerm2 or Kitty/WezTerm.
+- Existing files must be read before Kward can edit or overwrite them.
+- File reads and edits are bounded to avoid loading very large files by accident.
+- Shell commands run from the workspace and should be treated like commands you run yourself.
 
-## Pan mode
+## Images
 
-Pan mode starts a minimal LAN web UI with a prompt textarea and transcript:
+If the active model supports images, Kward can attach image paths, Markdown image links, `file://` URLs, or image data URLs pasted into the composer.
 
-```bash
-kward --working-directory="/path/to/workspace" pan
+Use this for tasks such as:
+
+```text
+This screenshot shows the broken layout. Find the likely CSS issue.
 ```
 
-From source:
+## Pan mode
+
+Pan mode starts a simple LAN web UI:
 
 ```bash
-ruby lib/main.rb --working-directory="/path/to/workspace" pan
+kward --working-directory ~/code/project pan
 ```
 
-Pan mode streams assistant output and tool calls, queues prompts submitted while a turn is running, and saves the conversation as a normal per-workspace session.
+Use it only on trusted networks. It exposes the same file, shell, and web tools through a browser UI and requires credentials configured in `config.json`. See [Configuration](configuration.md).
+
+## RPC backend
 
-Configure `pan_mode.username` and `pan_mode.password` before starting it; see [Configuration](configuration.md). Pan mode is reachable on the LAN, so use it only on trusted networks.
+`kward rpc` starts the experimental JSON-RPC backend for UI clients and editor integrations. Terminal users can ignore it. Integration authors should read [RPC protocol](rpc.md).

data/doc/web-search.md

@@ -1,28 +1,94 @@
 # Web search
 
-Web search lets the agent search the live web. Use it when you need current facts, official docs, release notes, bug reports, pricing pages, or recent announcements.
+Use web search when the answer depends on current or external information:
+
+- current framework or dependency docs,
+- release notes and migration guides,
+- security advisories,
+- pricing or provider pages,
+- bug reports and issue discussions,
+- a specific URL you want Kward to inspect.
 
 Example prompts:
 
 ```text
-Research the current Rails release notes and summarize migration risks.
+Check the current Rails release notes and summarize migration risks for this project.
 Find the official OpenRouter docs for model configuration.
 Check whether this dependency has a recent security advisory.
+Read this URL and explain the setup steps: https://example.com/docs
+```
+
+## How Kward researches
+
+Kward has three web tools:
+
+1. `web_search` finds candidate sources.
+2. `fetch_content` reads human-readable pages.
+3. `fetch_raw` reads machine-readable files such as JSON, YAML, XML, RSS, OpenAPI specs, or plain text.
+
+A good research flow is:
+
+```text
+Search for the official docs, fetch the relevant page, then answer with the source URL.
+```
+
+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.
+
+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.
+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.
+
+## Disable web tools
+
+Hide all web tools:
+
+```json
+{
+  "web_search": {
+    "enabled": false
+  }
+}
 ```
 
-The `web_search` tool is advertised by default so the agent can use current sources when needed. In `auto` mode the provider fallback order is:
+Use this when working on private projects where no prompt should trigger external lookup.
+
+## Tool details
+
+### `web_search`
+
+Finds candidate sources. Arguments:
+
+- `queries`: one to four search strings.
+- `max_results`: results per query, default 5, capped at 20.
+- `provider`: optional `auto`, `exa`, `perplexity`, `gemini`, or `duckduckgo`.
+- `recency_filter`: optional `day`, `week`, `month`, or `year`.
+- `domain_filter`: optional domains to include, or domains prefixed with `-` to exclude.
+
+### `fetch_content`
+
+Reads a specific HTTP or HTTPS page and extracts readable text. Use it for docs pages, articles, issues, and release notes.
+
+Arguments:
+
+- `url`
+- `max_bytes`: default 16384, capped at 131072.
+- `extract`: optional `auto`, `text`, or `markdown`.
 
-1. Exa API when `EXA_API_KEY` is configured, otherwise keyless Exa MCP (`https://mcp.exa.ai/mcp`)
-2. Perplexity API when configured and `allow_model_providers` is true
-3. Gemini API with Google Search grounding when configured and `allow_model_providers` is true
-4. Legacy DuckDuckGo HTML search, then bundled public SearXNG instances
+### `fetch_raw`
 
-Queries are sent over the network to the selected provider. API keys are never bundled with Kward; configure your own keys only if you want higher limits or alternate providers. Set `web_search.enabled` to `false` to hide the tool. Direct `provider: perplexity` or `provider: gemini` requests still use those providers when keys are configured.
+Reads a specific HTTP or HTTPS resource without readability extraction. Use it for JSON, YAML, XML, RSS, OpenAPI specs, and plain text.
 
-Supported arguments:
+Arguments:
 
-- `queries`: one to four search strings
-- `max_results`: results per query, default 5, capped at 20
-- `provider`: optional `auto`, `exa`, `perplexity`, `gemini`, `legacy`, or `duckduckgo`
-- `recency_filter`: optional `day`, `week`, `month`, or `year`
-- `domain_filter`: optional list of included domains, or excluded domains prefixed with `-`
+- `url`
+- `max_bytes`: default 16384, capped at 131072.
+- `accept`: optional HTTP `Accept` header.

data/exe/kward

@@ -1,5 +1,7 @@
 #!/usr/bin/env ruby
 
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
 require "kward"
 
 Kward::CLI.new.run

data/kward.gemspec

@@ -13,6 +13,10 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.2"
 
   spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["source_code_uri"] = "https://github.com/kaiwood/kward"
+  spec.metadata["changelog_uri"] = "https://github.com/kaiwood/kward/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://github.com/kaiwood/kward#readme"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/kaiwood/kward/issues"
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |file|

data/lib/kward/agent.rb

@@ -8,9 +8,21 @@ require_relative "steering"
 require_relative "telemetry/logger"
 require_relative "tools/registry"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Runs model turns, handles context compaction, dispatches tool calls, and
   # streams high-level events back to CLI and RPC callers.
+  #
+  # `Agent` is the main turn orchestrator. It should know what a turn means:
+  # append the user's input, call the model, persist assistant/tool messages,
+  # retry once after recoverable context overflow, apply in-flight steering, and
+  # emit frontend-neutral `Events::*` objects. It should not know terminal or RPC
+  # rendering details; callers translate events into their own UI protocol.
+  #
+  # Tool implementations own local side effects. `Client` owns provider HTTP
+  # details. `Conversation` owns transcript state. Keep future changes in the
+  # lowest layer that owns the behavior, and use `Agent` only for cross-step turn
+  # coordination.
   class Agent
     def initialize(client:, tool_registry: ToolRegistry.new, conversation: Conversation.new, telemetry_logger: TelemetryLogger.new)
       @client = client
@@ -67,6 +79,7 @@ module Kward
           overflow_retried = true
           next
         end
+        update_conversation_runtime(message)
         yield Events::AssistantMessage.new(message: message) if block_given?
         @conversation.append_assistant(message)
         steered_after_message = append_steering_events(steering_state)
@@ -200,18 +213,32 @@ module Kward
       end
       ChatInvocation.call(
         @client,
-        @conversation.messages,
+        @conversation.context_messages,
         {
           tools: @tool_registry.schemas,
           on_reasoning_delta: reasoning_delta,
           on_assistant_delta: assistant_delta,
           on_retry: retry_callback,
           cancellation: cancellation,
-          steering: steering
+          steering: steering,
+          provider: @conversation.provider,
+          model: @conversation.model,
+          reasoning: @conversation.reasoning_effort
         }
       )
     end
 
+    def update_conversation_runtime(message)
+      return unless message.is_a?(Hash)
+
+      provider = message["provider"] || message[:provider]
+      model = message["model"] || message[:model]
+      return if provider.to_s.empty? || model.to_s.empty?
+
+      @conversation.update_runtime_context!(provider: provider, model: model, reasoning_effort: @conversation.reasoning_effort)
+      @conversation.persist_runtime_context!
+    end
+
     def safe_answer(content)
       text = content.to_s
       return text unless claims_file_edit?(text)
@@ -222,7 +249,7 @@ module Kward
     end
 
     def claims_file_edit?(text)
-      text.match?(/\b(I|I've|I have)\s+(changed|updated|modified|edited|created|deleted|wrote)\b/i)
+      text.match?(/\b(?:I|I've|I have)\s+(?:changed|updated|modified|edited|created|deleted|wrote)\s+(?:the\s+)?(?:file|files|[\w.\/-]+\.[\w-]+)\b/i)
     end
 
     def last_file_change_succeeded?

data/lib/kward/ansi.rb

@@ -1,4 +1,6 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # ANSI color and terminal capability helpers.
   module ANSI
     ESCAPE_PATTERN = /\e\[[0-9;?]*[ -\/]*[@-~]/.freeze
     SGR_PATTERN = /\e\[[0-9;:]*m/.freeze
@@ -125,6 +127,7 @@ module Kward
       rendered.join("\n") + (string.end_with?("\n") ? "\n" : "")
     end
 
+    # String wrapper that strips ANSI escape sequences while preserving visible text operations.
     class MarkdownStream
       def initialize(enabled: ANSI.enabled?)
         @enabled = enabled