kward 0.66.0

data/doc/configuration.md

@@ -0,0 +1,310 @@
+# Configuration
+
+Kward reads user configuration from `~/.kward/config.json` by default. Most users do not need to edit this file by hand at first: use `/login`, `/model`, `/reasoning`, and `/settings` from inside Kward when possible.
+
+On first start, if the file does not exist, Kward creates a starter config with an active Kward persona, explicit disabled memory settings, and the default composer busy-help setting so you can inspect and edit them. Provider-specific model defaults are added only when you choose a provider/model. If `KWARD_CONFIG_PATH` is set, Kward uses that file instead and treats that file's directory as the config directory for prompts, skills, memory, logs, and caches.
+
+Small examples:
+
+```json
+{
+  "provider": "openrouter",
+  "openrouter_model": "openai/gpt-5.5"
+}
+```
+
+```json
+{
+  "memory": {
+    "enabled": true
+  }
+}
+```
+
+## Config directory
+
+By default, Kward stores user data under `~/.kward`:
+
+```text
+~/.kward/config.json
+~/.kward/auth.json
+~/.kward/github_auth.json
+~/.kward/sessions/
+~/.kward/memory/
+~/.kward/logs/
+~/.kward/cache/
+```
+
+When `KWARD_CONFIG_PATH=/path/to/config.json` is set, most config-related files live beside that file instead. User plugins are the exception: they are loaded only from `~/.kward/plugins`.
+
+## Provider and model settings
+
+Set `provider` to choose the active backend:
+
+```json
+{
+  "provider": "codex"
+}
+```
+
+Supported values are:
+
+- `codex` for the OpenAI/ChatGPT Codex backend.
+- `openrouter` for OpenRouter.
+- `copilot` for experimental Copilot provider support.
+
+Model settings:
+
+```json
+{
+  "model": "gpt-5.5",
+  "openai_model": "gpt-5.5",
+  "openrouter_model": "openai/gpt-5.5",
+  "copilot_model": "gpt-5-mini",
+  "reasoning_effort": "medium",
+  "openai_reasoning_effort": "medium",
+  "openrouter_reasoning_effort": "medium",
+  "copilot_reasoning_effort": "medium",
+  "thinking_level": "medium"
+}
+```
+
+`model` is a generic setting for the active provider. Provider-specific values such as `openai_model`, `openrouter_model`, and `copilot_model` take precedence for their provider. `reasoning_effort` and `thinking_level` are generic reasoning settings. `openai_reasoning_effort`, `openrouter_reasoning_effort`, and `copilot_reasoning_effort` are provider-specific forms.
+
+Defaults:
+
+- OpenAI/Codex: `gpt-5.5`
+- OpenRouter: `openai/gpt-5.5`
+- Copilot: `gpt-5-mini`
+- Reasoning effort: `medium`
+
+The interactive `/model` picker prefers OpenRouter models available to the configured API key when Kward can fetch them. `/openrouter/catalog` and RPC `openrouter/catalog` list the full OpenRouter catalog separately.
+
+## Environment overrides
+
+Use environment variables for one-off runs or local secrets that you do not want in config.
+
+Provider and model:
+
+- `KWARD_PROVIDER`
+- `OPENAI_MODEL`
+- `OPENAI_REASONING_EFFORT`
+- `OPENROUTER_MODEL`
+- `OPENROUTER_REASONING_EFFORT`
+- `COPILOT_MODEL`
+- `COPILOT_REASONING_EFFORT`
+
+Credentials:
+
+- `OPENAI_ACCESS_TOKEN`
+- `OPENROUTER_API_KEY`
+- `COPILOT_GITHUB_TOKEN`
+- `GITHUB_TOKEN` or `GH_TOKEN` for authenticated GitHub API requests in `code_search`
+
+Web search:
+
+- `EXA_API_KEY`
+- `PERPLEXITY_API_KEY`
+- `GEMINI_API_KEY`
+
+Color and logging environment variables are covered below.
+
+## Authentication settings
+
+The friendliest way to configure credentials is `/login` inside Kward, or `kward login` from your shell. See [Authentication](authentication.md) for the full provider flow.
+
+Credential settings can also live in config:
+
+```json
+{
+  "openai_oauth_client_id": "your-client-id",
+  "openrouter_api_key": "sk-or-v1-..."
+}
+```
+
+Use environment variables for temporary or local-only secrets when possible. If both OpenAI and OpenRouter credentials are available, OpenAI OAuth is used by default unless `provider` or `KWARD_PROVIDER` selects another backend.
+
+## Overlay settings
+
+Overlay settings control terminal picker/card layout:
+
+```json
+{
+  "overlay": {
+    "alignment": "center",
+    "width": "maximum"
+  }
+}
+```
+
+`alignment` can be `left`, `center`, or `right`. `width` can be `maximum` to match the composer width or `capped` for a compact card.
+
+You can change these interactively with `/settings`.
+
+## Composer settings
+
+The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:
+
+```json
+{
+  "composer": {
+    "busy_help": false
+  }
+}
+```
+
+This only hides the hint text; Ctrl+C still stops the current running response.
+
+## Memory
+
+Memory is off by default. Enabling it writes:
+
+```json
+{
+  "memory": {
+    "enabled": true
+  }
+}
+```
+
+Memory auto-summary can also be enabled:
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "auto_summary": true
+  }
+}
+```
+
+Memory files live under `<config-dir>/memory`, usually `~/.kward/memory`. See [Memory](memory.md).
+
+## Compaction
+
+Auto-compaction is enabled by default when Kward can determine the active context window. You can tune or disable it:
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserve_tokens": 16384,
+    "keep_recent_tokens": 20000
+  }
+}
+```
+
+Manual `/compact [instructions]` works even when auto-compaction is disabled.
+
+## Pan mode
+
+`--pan-mode` starts a LAN-reachable web UI and requires HTTP Basic Auth. Configure credentials before starting it:
+
+```json
+{
+  "pan_mode": {
+    "host": "0.0.0.0",
+    "port": 8765,
+    "username": "kward",
+    "password": "choose-a-private-password"
+  }
+}
+```
+
+`host` defaults to `0.0.0.0` and `port` defaults to `8765`. Kward fails to start pan mode unless `username` and `password` are configured.
+
+These credentials are stored in plaintext config. Use a private, user-specific password and do not share the config file. Pan mode exposes the agent's file, shell, and web tools to anyone on the LAN who has the credentials, so use it only on trusted networks.
+
+## Web search
+
+Web search works without an API key through Exa's public MCP endpoint and is advertised to the model by default. To hide the tool:
+
+```json
+{
+  "web_search": {
+    "enabled": false
+  }
+}
+```
+
+For higher limits or alternate providers, add user-specific keys. Model-backed auto fallback to Perplexity/Gemini stays off unless `allow_model_providers` is true; direct provider requests still work when the matching key is configured.
+
+```json
+{
+  "web_search": {
+    "enabled": true,
+    "provider": "auto",
+    "allow_model_providers": false,
+    "exa_api_key": "exa-...",
+    "perplexity_api_key": "pplx-...",
+    "gemini_api_key": "AIza...",
+    "gemini_model": "gemini-2.5-flash",
+    "perplexity_model": "sonar"
+  }
+}
+```
+
+Do not put shared or published API keys in this file.
+
+## Logging and stats
+
+Local telemetry logs are off by default. Enable logging with the master flag and each category you want:
+
+```json
+{
+  "logging": {
+    "enabled": true,
+    "tokens": true,
+    "performance": true,
+    "tools": true,
+    "errors": true
+  }
+}
+```
+
+Environment variables override config for a single run:
+
+- `KWARD_LOGGING`
+- `KWARD_LOGGING_TOKENS`
+- `KWARD_LOGGING_PERFORMANCE`
+- `KWARD_LOGGING_TOOLS`
+- `KWARD_LOGGING_ERRORS`
+
+Values `1`, `true`, `yes`, and `on` enable a flag. Values `0`, `false`, `no`, and `off` disable it.
+
+Logs are JSON Lines files in `<config-dir>/logs`, usually `~/.kward/logs`. Files rotate after 10 MB using numbered suffixes, and Kward does not delete old rotated logs.
+
+Logged data is redacted metadata only. Kward does not intentionally log prompts, assistant text, tool arguments, tool outputs, file contents, shell command text, API keys, or OAuth tokens. Logged fields can include provider/model names, token counts, byte counts, durations, retry attempts, tool names, statuses, and redacted error messages.
+
+Use `/stats [range]` in interactive mode to summarize enabled telemetry categories. The range defaults to `1 week` and accepts values such as `5 hours`, `10 minutes`, `2 days`, or `1 year`.
+
+Export token usage as CSV with:
+
+```bash
+kward stats tokens [range] [--bucket second|minute|hour|day|week|month|year] [--output path]
+```
+
+Example:
+
+```bash
+kward stats tokens 5 hours --bucket hour --output token-usage.csv
+```
+
+## Color output
+
+ANSI colors are enabled automatically on TTY output.
+
+Disable colors:
+
+```bash
+NO_COLOR=1 kward
+CLICOLOR=0 kward
+KWARD_COLOR=never kward
+```
+
+Force colors:
+
+```bash
+KWARD_COLOR=always kward
+FORCE_COLOR=1 kward
+```

data/doc/extensibility.md

@@ -0,0 +1,186 @@
+# Extensibility
+
+Kward can be customized at several levels:
+
+- `AGENTS.md` for coding guidance and repository rules.
+- Prompt templates for reusable slash-command prompts.
+- Skills for reusable agent instructions the model can load on demand.
+- Personas for assistant personality and communication style.
+- Plugins for trusted Ruby extensions that add commands, footer UI, prompt context, transcript-event observers, and RPC-visible behavior.
+
+Prompts, skills, personas, and config-directory `AGENTS.md` live beside the config file. By default this is `~/.kward`; if `KWARD_CONFIG_PATH` is set, Kward uses that file's directory instead.
+
+Plugins are different: user plugins are loaded only from `~/.kward/plugins`, regardless of `KWARD_CONFIG_PATH` or the current project directory. See the dedicated [Plugins guide](plugins.md).
+
+## Which extension point should I use?
+
+- Use `AGENTS.md` when you want Kward to follow coding rules, project conventions, or review expectations.
+- Use prompt templates when you want reusable slash commands such as `/plan <task>` or `/review <diff>`.
+- Use skills when you want reusable instructions that Kward can load only when a task needs them.
+- Use personas when you want to change tone, role, or communication style.
+- Use plugins when you need Ruby code to run locally, add commands, observe transcript events, or integrate with another tool.
+
+The optional starter pack installs a useful base `AGENTS.md` and prompt templates. You can install it with:
+
+```bash
+kward --install-starter-pack
+```
+
+## Agent instructions
+
+Kward separates repository guidance from workspace-specific agent personality.
+
+- Config-directory `AGENTS.md`: global coding guidance appended to Kward's built-in system instructions when present.
+- Workspace `AGENTS.md`: repository guidance loaded from the active workspace root when present.
+
+Use `AGENTS.md` for engineering instructions such as coding rules, project conventions, testing requirements, review expectations, and workflow guidance. Avoid putting personality, roleplay, or communication style there; configure those as personas instead.
+
+Workspace `AGENTS.md` is injected once when a conversation starts. Kward refreshes it only when the file changes or when the agent edits the workspace `AGENTS.md`. Config-directory and workspace `AGENTS.md` files are skipped with a warning if they exceed 32 KiB, because they are injected into every model request.
+
+## Prompt templates
+
+Prompt templates create user-invocable slash commands for reusable prompts.
+
+Create a template at:
+
+```text
+<config-dir>/prompts/<command>.md
+```
+
+For example, `prompts/plan.md` becomes `/plan` in interactive mode. Templates support `$ARGUMENTS`, replaced by the text after the command.
+
+Built-in commands such as `/exit`, `/new`, `/resume`, `/name`, `/clone`, `/export`, `/redraw`, and `/status` are reserved.
+
+Example prompt template:
+
+```markdown
+---
+description: Create an implementation plan.
+argument-hint: <task>
+---
+
+Plan this implementation request:
+
+$ARGUMENTS
+```
+
+## Skills
+
+Skills are reusable instruction packs the assistant can load when a task matches their description. They are useful when an instruction is too specific to include in every conversation, but important enough to keep around.
+
+Create a skill at:
+
+```text
+<config-dir>/skills/<skill-name>/SKILL.md
+```
+
+A skill is listed in the system instructions by its frontmatter `name` and `description`. The assistant can then call `read_skill` to load `SKILL.md` or related files inside that skill folder.
+
+Example skill:
+
+```markdown
+---
+name: planner
+description: Helps plan implementation work.
+---
+
+# Planner
+
+Use this when planning a code change.
+```
+
+## Personas
+
+Personas configure personality, role, and communication style without modifying repository files. New configs include a single active `kward` character by default; edit or remove `personas.default` to change the first-run experience. `personas.crew` is still accepted as an alias for `personas.characters`.
+
+A small persona config looks like this:
+
+```json
+{
+  "personas": {
+    "characters": [
+      {
+        "key": "kward",
+        "label": "Kward",
+        "instruction": "Be concise, practical, and friendly. Prefer small, safe changes."
+      }
+    ],
+    "default": "kward"
+  }
+}
+```
+
+You can also target personas by workspace, model, reasoning effort, time of day, or weekday:
+
+```json
+{
+  "personas": {
+    "characters": [
+      {
+        "key": "reviewer",
+        "label": "Reviewer",
+        "instruction": "Be skeptical and focus on correctness, tests, and maintainability."
+      },
+      {
+        "key": "coach",
+        "label": "Coach",
+        "instruction": "Explain tradeoffs and teach as you go."
+      }
+    ],
+    "default": "reviewer",
+    "workspaces": {
+      "/Users/kwood/Repositories/github.com/kaiwood/tauren": "coach"
+    },
+    "models": {
+      "gpt-5.5": "reviewer"
+    },
+    "persona_modifiers": {
+      "reasoning": {
+        "high": "Think strategically before answering."
+      },
+      "suffix": "Act like it."
+    }
+  }
+}
+```
+
+Persona evaluation order is:
+
+1. `personas.default`
+2. Matching `personas.workspaces` entry, using normalized workspace paths
+3. Matching `personas.models` entry for the current model
+4. Matching `persona_modifiers.reasoning` entry for the current reasoning effort
+5. Matching `persona_modifiers.time_of_day` entry for local time: `morning` 05:00-10:59, `before_lunch` 11:00-11:59, `late_evening` 21:00-04:59
+6. Matching `persona_modifiers.weekday` entry for the local weekday
+7. `persona_modifiers.suffix`
+
+Prompt assembly order is:
+
+1. Kward built-in base prompt
+2. Config-directory `AGENTS.md`
+3. Evaluated persona text
+4. Plugin prompt context
+5. Skills listing
+6. Workspace `AGENTS.md`
+
+If no persona entries match, Kward simply omits that part. Conversation compaction uses a neutral prompt without workspace personality, so summaries stay continuation-focused and machine-oriented.
+
+## Plugins
+
+Plugins are Kward's trusted Ruby extension layer. Use them when you need behavior rather than just instructions or reusable prompts.
+
+Plugins can add:
+
+- slash commands,
+- one custom terminal footer,
+- prompt context,
+- live transcript-event observers,
+- command behavior exposed to RPC clients.
+
+Plugin files live in:
+
+```text
+~/.kward/plugins/*.rb
+```
+
+See [Plugins](plugins.md) for the full plugin API, examples, and security model.

data/doc/getting-started.md

@@ -0,0 +1,127 @@
+# Getting started
+
+Kward is a Ruby CLI coding agent for local projects. It can answer questions, inspect files, propose and apply edits, run confirmed commands, search the web, and keep session history.
+
+This page gets you to a first working chat. For day-to-day features after that, see [Usage](usage.md).
+
+## Requirements
+
+- Ruby 3.2 or newer.
+- Bundler when running from source.
+- Credentials for at least one model provider. You can add them with `/login` inside Kward or with `kward login` from your shell.
+
+## Install
+
+Kward is being prepared for a RubyGems release. Once published:
+
+```bash
+gem install kward
+```
+
+Optionally install the starter pack:
+
+```bash
+kward --install-starter-pack
+```
+
+The starter pack adds useful default prompts and a base `AGENTS.md` to your config directory. It is helpful for a first setup, but safe to skip if you want to write your own instructions. Existing files are not overwritten.
+
+Until the gem is published, run Kward from a repository checkout:
+
+```bash
+bundle install
+ruby lib/main.rb --install-starter-pack   # optional
+```
+
+## Start Kward and sign in
+
+Start an interactive session:
+
+```bash
+kward
+```
+
+From source:
+
+```bash
+ruby lib/main.rb
+```
+
+When Kward needs credentials, sign in from inside the session:
+
+```text
+/login
+```
+
+You can also sign in from your shell before starting a chat:
+
+```bash
+kward login
+```
+
+From source:
+
+```bash
+ruby lib/main.rb login
+```
+
+For provider-specific login options, such as OpenRouter API keys or experimental Copilot support, see [Authentication](authentication.md).
+
+## Ask one question and exit
+
+Pass a prompt as command-line text:
+
+```bash
+kward "Explain this project"
+```
+
+From source:
+
+```bash
+ruby lib/main.rb "Explain this project"
+```
+
+You can also pipe input:
+
+```bash
+git diff | kward "Review this diff"
+```
+
+One-shot prompts do not use Kward memory.
+
+## Useful first commands
+
+Inside an interactive session:
+
+```text
+/login              sign in or save provider credentials
+/status             show current session and compaction status
+/model              choose the default model
+/reasoning          choose reasoning effort
+/resume             resume a saved session
+/export notes.md    export the current session as Markdown
+/exit               leave the session
+```
+
+Kward saves interactive sessions under `~/.kward/sessions/`.
+
+## Safety basics
+
+- Kward must read an existing file in the current conversation before it can edit or overwrite it.
+- File writes and edits ask for confirmation first.
+- Shell commands ask for confirmation before running.
+- Tool reads are bounded so large files are not accidentally loaded into context.
+
+## Run tests
+
+If you are developing Kward itself:
+
+```bash
+bundle exec rake test
+```
+
+Equivalent direct command:
+
+```bash
+ruby -Itest -e 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }'
+```