kward 0.68.0 → 0.69.0

data/doc/plugins.md

@@ -1,18 +1,25 @@
 # Plugins
 
-Plugins are Kward's trusted local extension system. They let you add project or personal workflow features without changing Kward itself.
+Plugins are trusted local Ruby extensions for Kward. Use them when you need behavior that prompts, skills, or instructions cannot provide.
 
-A plugin can:
+Good plugin use cases:
 
-- add interactive slash commands,
-- expose commands through the RPC backend,
-- render a custom terminal footer,
-- inject concise prompt context into future model requests,
-- observe live transcript events such as assistant output, tool calls, and retries.
+- add a slash command for a personal workflow,
+- show project/session status in the terminal footer,
+- add concise local context to prompts,
+- log or observe transcript events,
+- expose local commands to an RPC client.
 
-Plugins are plain Ruby files. They run inside the Kward process with your local user permissions, so install only plugins you trust.
+Plugins run inside the Kward process with your user permissions. Install only plugins you trust.
 
-Use a prompt template when reusable text is enough. Use a skill when you need reusable instructions. Use a plugin when you need local Ruby behavior, file or network integration, custom commands, or transcript observers.
+## When to use a plugin
+
+| Need | Better choice |
+| --- | --- |
+| Reusable prompt text | prompt template |
+| Reusable model instructions | skill |
+| Repository rules | `AGENTS.md` |
+| Local Ruby code or integration | plugin |
 
 ## Where plugins live
 
@@ -22,7 +29,7 @@ Kward loads top-level Ruby files from:
 ~/.kward/plugins/*.rb
 ```
 
-Plugins are intentionally **not** loaded from the current workspace, from a project repository, or from a custom `KWARD_CONFIG_PATH` directory. This keeps plugin loading tied to the local user account rather than to whatever project Kward is currently inspecting.
+Plugins are not loaded from the current workspace or a custom `KWARD_CONFIG_PATH` directory. This prevents a project checkout from silently adding executable Ruby code to Kward.
 
 ## A first plugin
 
@@ -32,12 +39,12 @@ Create the plugin directory:
 mkdir -p ~/.kward/plugins
 ```
 
-Then create `~/.kward/plugins/hello.rb`:
+Create `~/.kward/plugins/hello.rb`:
 
 ```ruby
 Kward.plugin do |plugin|
   plugin.command "hello", description: "Say hello", argument_hint: "[name]" do |args, ctx|
-    name = args.strip.empty? ? "captain" : args.strip
+    name = args.strip.empty? ? "there" : args.strip
     ctx.say("Hello, #{name}.")
   end
 end
@@ -49,41 +56,28 @@ Start Kward and run:
 /hello Kai
 ```
 
-Plugin commands appear in interactive slash completion and in RPC command listings.
-
-## Slash commands
+## Add a slash command
 
-Register a command with `plugin.command`:
+Use plugin commands for local actions that should not call the model.
 
 ```ruby
 Kward.plugin do |plugin|
   plugin.command "session-info", description: "Show session details" do |_args, ctx|
     ctx.say("Session: #{ctx.session_name || ctx.session_id || 'unnamed'}")
-    ctx.say("Path: #{ctx.session_path || 'not saved'}")
     ctx.say("Workspace: #{ctx.workspace_root}")
   end
 end
 ```
 
-Command names:
-
-- do not include the leading `/`,
-- must start with a letter or number,
-- may contain letters, numbers, `_`, and `-`,
-- cannot replace built-in commands or prompt-template commands.
-
-If a plugin command conflicts with a reserved or duplicate command, Kward skips it and prints a warning.
-
-Command handlers receive:
+Command names do not include `/`. They must start with a letter or number and may contain letters, numbers, `_`, and `-`.
 
-- `args`: the raw text after the command name,
-- `ctx`: a plugin context object.
+A plugin command cannot replace a built-in command or prompt-template command.
 
-Use `ctx.say(message)` for user-visible output.
+## Add prompt context
 
-## Prompt context
+Prompt context is short text injected into future model requests.
 
-Plugins can add concise context to future system prompts:
+Use it for stable facts the model should know, not for large files or secrets.
 
 ```ruby
 Kward.plugin do |plugin|
@@ -95,37 +89,29 @@ Kward.plugin do |plugin|
 end
 ```
 
-Prompt context is injected after personas and before skills/workspace instructions. Keep it short and stable. Long or noisy prompt context will be sent repeatedly to the model and can reduce useful context space.
-
-If plugin state changes and the active conversation should rebuild its system message, call:
+If plugin state changes and Kward should rebuild the active system message, call:
 
 ```ruby
 ctx.refresh_system_message!
 ```
 
-from a command or event handler.
-
-## Custom footer
+## Add a footer
 
-A plugin can render one custom footer for the terminal UI:
+A footer can show compact local status in the terminal UI:
 
 ```ruby
 Kward.plugin do |plugin|
   plugin.footer do |ctx|
-    name = ctx.session_name || "unnamed"
-    messages = ctx.transcript.messages.length
-    "#{name} • #{messages} messages"
+    "#{ctx.session_name || 'unnamed'} • #{ctx.transcript.messages.length} messages"
   end
 end
 ```
 
-Only one footer renderer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning.
-
-Footer errors are caught and printed as warnings so they do not break the session.
+Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning.
 
-## Transcript events
+## Observe transcript events
 
-Plugins can observe live transcript stream events:
+Use transcript events when you need to log or react to live activity:
 
 ```ruby
 Kward.plugin do |plugin|
@@ -139,7 +125,9 @@ Kward.plugin do |plugin|
 end
 ```
 
-Supported event types include:
+Event payloads are read-only copies. Handler errors are caught and printed as warnings.
+
+Common event types include:
 
 - `reasoning_delta`
 - `assistant_delta`
@@ -150,28 +138,24 @@ Supported event types include:
 - `tool_result`
 - `answer`
 
-Event payloads are deep-frozen copies. Treat them as read-only.
-
-Transcript-event handler errors are caught and printed as warnings.
+## Plugin context
 
-## Plugin context API
+Handlers receive a `ctx` object. Common methods:
 
-Plugin handlers receive a `ctx` object with:
+- `ctx.workspace_root`
+- `ctx.args`
+- `ctx.say(message)`
+- `ctx.transcript.messages`
+- `ctx.session_id`
+- `ctx.session_name`
+- `ctx.session_path`
+- `ctx.refresh_system_message!`
 
-- `ctx.args` - raw command arguments for contexts that have them.
-- `ctx.workspace_root` - active workspace path.
-- `ctx.transcript.messages` - deep-frozen copy of active conversation messages.
-- `ctx.say(message)` - emit output to the active frontend when available.
-- `ctx.session_id` - current persisted session ID when available.
-- `ctx.session_name` - current session name when available.
-- `ctx.session_path` - current session file path when available.
-- `ctx.refresh_system_message!` - rebuild the active conversation system message.
-
-The transcript is read-only by design. Plugins should use Kward APIs exposed through the context rather than mutating conversation internals.
+The transcript is read-only. Use context methods instead of mutating Kward internals.
 
 ## RPC support
 
-Plugins are available to both the CLI and the experimental RPC backend.
+Plugins are available in the CLI and experimental RPC backend.
 
 RPC clients can:
 
@@ -179,43 +163,17 @@ RPC clients can:
 - run plugin commands through `commands/run`,
 - run plugin slash commands through `turns/start` input such as `/hello Kai`.
 
-When a plugin command is run as a turn, Kward emits command output through normal turn events without calling the model.
+Plugin command output is emitted through normal turn events without calling the model.
 
-## Security model
+## Security
 
-Plugins are trusted local Ruby code. A plugin can read and write files, run commands, make network requests, and access process environment variables just like any Ruby code running as your user.
+Plugins are local Ruby code. They can read files, write files, run commands, make network requests, and read environment variables as your user.
 
 Recommended practices:
 
 - Install plugins only from sources you trust.
 - Keep plugins in your personal `~/.kward/plugins` directory.
-- Do not place secrets directly in plugin files if they will be shared.
-- Prefer user-specific config or environment variables for credentials.
-- Keep prompt context concise and avoid injecting secrets into model prompts.
-- Be careful when writing transcript observers that persist conversation content.
-
-## Complete example
-
-```ruby
-Kward.plugin do |plugin|
-  plugin.command "last-message", description: "Show transcript size" do |_args, ctx|
-    ctx.say("Messages: #{ctx.transcript.messages.length}")
-  end
-
-  plugin.footer do |ctx|
-    "#{ctx.session_name || 'unnamed'} • #{ctx.transcript.messages.length} messages"
-  end
-
-  plugin.prompt_context do |_ctx|
-    "Project background: prefer small, focused changes."
-  end
-
-  plugin.on_transcript_event do |event, ctx|
-    next unless event.type == "assistant_delta"
-
-    File.open(File.join(ctx.workspace_root, ".assistant-stream.log"), "a") do |file|
-      file.write(event.payload[:delta])
-    end
-  end
-end
-```
+- Do not put secrets in shared plugin files.
+- Prefer environment variables or private config for credentials.
+- Keep prompt context short and never inject secrets into model prompts.
+- Be careful with transcript observers that persist conversation content.

data/doc/releasing.md

@@ -14,9 +14,11 @@ Release steps before publishing:
 
    ```bash
    bundle exec rake rdoc
-   bundle exec yard doc
+   bundle exec rake docs:build
    ```
 
+   Pushes to `main` deploy the generated YARD site to GitHub Pages.
+
 5. Build the gem locally:
 
    ```bash

data/doc/rpc.md

@@ -554,7 +554,7 @@ Params:
 
 - `sessionId`: active RPC session ID.
 
-Returns stable startup sections for configured context (`AGENTS.md`), skills, prompt templates, and plugin slash commands.
+Returns stable startup sections for configured context (`PRINCIPLES.md`, or legacy `AGENTS.md`), skills, prompt templates, and plugin slash commands.
 
 ### `prompts/list`
 

data/doc/usage.md

@@ -1,217 +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 local commands from the workspace.
-- `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.
-- Text file reads and edits are capped at 256 KiB per file.
-- Tool schemas are the official contract for generated tool calls and returned tool payloads.
-- At runtime, Kward accepts tolerant incoming tool-call input for compatibility: extra fields are ignored, and existing legacy-compatible input shapes remain supported.
-- Required fields and invalid required values still return explicit tool errors.
-- Tool output payloads are kept schema-clean so future model calls and restored transcripts do not depend on accidental extra fields.
-- 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).