kward 0.83.0 → 0.84.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 678c9e9bb188e6c3d065dfde6b97c9ec5c31b29b178b40d69b0397b5200eb2a8
-  data.tar.gz: 3e09cb3d11ff6018ecc75e3eb31e8745e72e534dba7a4c3711a488451d353fcc
+  metadata.gz: 10d9376091daae14fa22ee39099645cb78bbdb8ff8de89a5982ffe2929396d67
+  data.tar.gz: 633ec7446e83664c18fcac2a12fcdf686dcc81cf21fc33cf73026186b4765540
 SHA512:
-  metadata.gz: 7f4247a32300deff0906c95c10d7312aa6303108956596f16d9f2c6d2d4fc444b5ef377751f47dbd2157b041710d855c44a981a1a22f8a562c79203afe8b65ed
-  data.tar.gz: d93d09126d221c05d7ef0e931f46ccfaa4a84450e6eb5695dbea653d8b9de99bb27bc7fb070b323c74160477fd328f0be3cd972d544b45e3ea90ffbeb79cb087
+  metadata.gz: '01750111663180d8f89afe2e2bfc7e14ada0c5942621d0ac5cc74eddda07db81d164ea6b3c55fbb6d3082b9e76834cb74094807bba67ac1419f06c68453e595c'
+  data.tar.gz: f4e8e96278bd737a4912461325381e63477d52a4a1710ea53b0c08ce7aeb2caba88a2662f1a8a8d24b8d7e339d745f1ece1816626c4f7e142aeac9e0cdd0cc15

data/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.84.0] - 2026-08-30
+
+### Added
+
+- Added security reporting, contribution and conduct policies, structured issue and pull-request templates, and an explicit macOS/Linux/WSL/Windows support matrix.
+- Added Vibe multi-cursor editing with `Ctrl+D` occurrence selection from normal, insert, and characterwise visual modes, plus visual-mode `I`/`A` cursors at each selected line boundary.
+- Added `script/benchmark_composer` for repeatable draft-layout, history-search, and file-completion performance measurements.
+- Added Vibe visual and cursor-aware `:run` support plus `:run all` for executing runnable Markdown fenced language blocks and inserting or replacing their formatted `<output>` fields.
+- Added configurable editor runners under `editor.runners`, with Node, TypeScript, Python, Shell, Lua, Julia, Elixir, Crystal, Go, and Swift buffer execution alongside Ruby.
+- Added Vibe visual-mode `Ctrl+h`/`Ctrl+j`/`Ctrl+k`/`Ctrl+l` shortcuts to outdent, move down, move up, and indent selected lines while keeping visual mode active.
+- Added a live `source`/`.` shell builtin that applies declarative aliases and exports to the running `/shell` session without restarting Kward.
+- Added shell-agent provider, model, and reasoning-effort settings under `shell.agent`, editor-agent provider settings under `editor.agent`, and environment overrides for transient-agent provider selection.
+- Added shell-style `kwshrc` configuration files at `~/.kward/kwshrc` and `~/.kwshrc`, with ordered `alias`, `export`, and declarative `source` support.
+- Added the `open_editor` agent tool so interactive sessions, including explicit `/shell` `?` prompts, can open a requested workspace file in Kward's built-in editor.
+- Extended `/scratchpad` to open all 26 built-in syntax-highlighted languages through canonical names or familiar file-extension shortcuts, with `/scratchpad help` for discovery.
+- Added nested syntax highlighting, auto-indentation, and endwise behavior for recognized language tags inside fenced code blocks in Markdown editor buffers.
+
+### Changed
+
+- Smoothed interactive response streaming by pacing buffered provider events and rendering safe text before incomplete inline Markdown instead of delaying whole lines.
+- Replaced the busy Braille spinner with a calmer four-frame activity pulse in the interactive composer.
+- Added brief success, failure, and cancellation transitions to the interactive composer when an agent turn finishes.
+- Standardized terminal accents by meaning: cyan for agent activity, green for success, amber for caution, red for failure, purple for tools, and gray for metadata.
+- Added a brief, visual-only response-arrival flourish when the first assistant output reaches the interactive composer.
+- Made the composer activity label follow real turn states such as thinking, reasoning, responding, retrying, and the currently running tool.
+- Added unobtrusive elapsed-time feedback after two seconds, final turn duration in completion transitions, and provider-reported tool durations in result summaries.
+- Added stable `❯` user and `✦` assistant anchors to make transcript turn boundaries easier to scan without changing stored conversation content.
+- Added persistent background-tab status colors for running work, unread output, successful detached commands, questions, and failures without changing tab label widths.
+- Documentation checks now validate the curated public extension entry points without presenting aggregate internal-helper coverage as a product-quality metric.
+- The repository and documentation landing pages now use a focused coding-workflow visual, restrained project badges, and clearer product identity.
+- Updated RubyGems positioning and metadata to describe Kward's supported product surfaces and direct users to the documentation site while keeping source and issue links on GitHub.
+- Refined the documentation homepage with a concrete static message, direct getting-started navigation, branded browser and social metadata, canonical URLs, and a quieter generated-docs footer.
+- The composer now highlights `/` command and `@` file discovery, and the startup screen gives actionable guidance when no model provider is connected.
+- Grouped and aligned top-level help, condensed credential status with an opt-in `--all` view, and standardized doctor, hooks, and project-skill diagnostics with actionable summaries and exit statuses.
+- Pan now binds to `127.0.0.1` by default, accepts `KWARD_PAN_PASSWORD`, and warns whenever it is explicitly exposed over plain HTTP on a non-loopback address.
+- Vibe visual selections can now be used as line ranges for `:` commands, including `:s` substitutions and `:run` scratchpad execution.
+- Ruby scratchpad runs now preserve the source buffer and show captured output in a scrollable, cancellable lower-half output pane instead of appending it after `__END__`; mouse drag selection and `Ctrl+C`/`Cmd+C`/Vibe `y` copy clean output without pane borders.
+
+### Fixed
+
+- Restored Codex commentary as visible reasoning output during streaming and session replay instead of showing only the provider's short reasoning-summary headline.
+- Kept expected Git discovery failures, PTY fixtures, and release subprocess output inside their owning tests so successful suite and CI logs remain quiet.
+- Replaced one-shot authentication and runtime backtraces with concise, actionable CLI errors while retaining opt-in debug backtraces through `KWARD_DEBUG=1`.
+- Fixed composer cursor movement, deletion, wrapping, truncation, and border alignment for wide and multi-codepoint Unicode graphemes.
+- Reduced composer latency for long drafts, large file and slash-command lists, and prompt histories by eliminating repeated layout work, discovering project paths outside rendering, and reusing search results.
+- Fixed tab switching during shell commands so tab shortcuts take priority without aborting the command; detached commands continue in the originating tab's background and report their output when complete.
+
+### Removed
+
+- Removed legacy `kwsh.yml` shell configuration; shell aliases and exports now use the shell-style `kwshrc` files.
+
 ## [0.83.0] - 2026-08-28
 
 ### Added
@@ -14,6 +65,8 @@ All notable changes to Kward will be documented in this file.
 - Added current-buffer word completion to the integrated editor, with repeated Tab presses cycling nearby matches and existing smart indentation retained when no match exists.
 - Added Claude Opus 5 to the Anthropic model picker with its 1M context window and high-reasoning metadata.
 - Added an `i` toggle to the `/files` browser for showing Git-ignored files, which remain hidden by default.
+- Added `f`, `d`, and `r` actions to the `/files` browser for creating files, creating directories, and renaming entries from the composer prompt.
+- Added Backspace deletion to the `/files` browser with confirmation and an additional confirmation before recursively deleting non-empty directories.
 
 ### Changed
 
@@ -73,7 +126,7 @@ All notable changes to Kward will be documented in this file.
 - Displayed packaged plugins with their folder name in the startup plugin list, such as `folder/plugin.rb`.
 - Added a frozen composer display for line-oriented Git PTY commands while preserving the full-terminal handoff for full-screen programs.
 - Changed external `/shell` commands and one-shot `!command` input to use interactive PTY terminal handoff by default, while retaining `pty` and `/pty` for compatibility.
-- Made aliases configured in `ekwsh.yml` available to leading-`!` execution and command completion.
+- Made aliases configured in `kwshrc` available to leading-`!` execution and command completion.
 - Removed interactive PTY start and exit-status messages while retaining the submitted command echo.
 - Changed shell and leading-`!` completion so the candidate list appears in an interactive overlay while repeated Tab presses cycle through candidates in the composer.
 - Removed the `Tab` and `Shift+Tab` reasoning-effort shortcuts so the composer keeps its normal completion behavior.
@@ -328,27 +381,27 @@ All notable changes to Kward will be documented in this file.
 - Added `/queue open <id>` to open a queued worker's session for review or follow-up.
 - Added `/diff` to open the chronological file changes recorded in the current session in the integrated diff viewer.
 - Added `/scratchpad [text|markdown|ruby]` for opening unsaved editor buffers, including Vibe `:w filename` save-as support and Ruby `:run`/Modern `Ctrl+R` output written after `__END__`.
-- Added `/pty <command>` and the `ekwsh` `pty <command>` built-in for explicit interactive PTY passthrough sessions, enabling terminal-owned tools such as pagers to run from Kward.
-- Added minimal PTY execution for external `ekwsh` commands so terminal-aware tools can detect a TTY and terminal width.
-- Added Ctrl+C cancellation for running `ekwsh` commands and preserved tab-switch actions while shell commands are active.
-- Added quoted path completion and cached `$PATH` executable completion for `ekwsh`.
-- Added streaming `ekwsh` command output in the TUI transcript while commands run.
-- Added separate workspace-scoped `ekwsh` command history so embedded shell input no longer shares normal prompt history.
+- Added `/pty <command>` and the `kwsh` `pty <command>` built-in for explicit interactive PTY passthrough sessions, enabling terminal-owned tools such as pagers to run from Kward.
+- Added minimal PTY execution for external `kwsh` commands so terminal-aware tools can detect a TTY and terminal width.
+- Added Ctrl+C cancellation for running `kwsh` commands and preserved tab-switch actions while shell commands are active.
+- Added quoted path completion and cached `$PATH` executable completion for `kwsh`.
+- Added streaming `kwsh` command output in the TUI transcript while commands run.
+- Added separate workspace-scoped `kwsh` command history so embedded shell input no longer shares normal prompt history.
 - Added structured RPC `runtime/updateSetting` `defaultModel` values so clients can send provider and model separately while keeping the existing string format.
 
 ### Changed
 
-- Changed PTY-backed `ekwsh` commands to refresh terminal window size while running so long-lived commands can adapt to resizes.
-- Changed `ekwsh` to default `GIT_PAGER` to `cat`, while preserving user-provided values, so Git commands do not unexpectedly enter an interactive pager under PTY execution.
-- Improved `ekwsh` POSIX-oriented built-ins, including `exit [status]`, stricter `cd`/`pwd`, `export NAME`, assignment persistence, `unalias`, and shared alias-name validation.
-- Changed `ekwsh` configuration to prefer a POSIX `/bin/sh` default shell and validate runtime settings for command timeout, output cap, and shell history size.
+- Changed PTY-backed `kwsh` commands to refresh terminal window size while running so long-lived commands can adapt to resizes.
+- Changed `kwsh` to default `GIT_PAGER` to `cat`, while preserving user-provided values, so Git commands do not unexpectedly enter an interactive pager under PTY execution.
+- Improved `kwsh` POSIX-oriented built-ins, including `exit [status]`, stricter `cd`/`pwd`, `export NAME`, assignment persistence, `unalias`, and shared alias-name validation.
+- Changed `kwsh` configuration to prefer a POSIX `/bin/sh` default shell and validate runtime settings for command timeout, output cap, and shell history size.
 
 ### Fixed
 
-- Normalized ordinary PTY line endings in `ekwsh` command output so transcripts avoid stray carriage returns.
-- Added `ekwsh` timeout and output-limit enforcement for external commands using the shared local command runner.
+- Normalized ordinary PTY line endings in `kwsh` command output so transcripts avoid stray carriage returns.
+- Added `kwsh` timeout and output-limit enforcement for external commands using the shared local command runner.
 - Consolidated workspace shell command execution on a shared local command runner with timeout, cancellation, bounded capture, and optional streaming support.
-- Fixed `ekwsh` shell output sanitization so unsafe terminal controls are stripped before command output is shown while SGR color is preserved.
+- Fixed `kwsh` shell output sanitization so unsafe terminal controls are stripped before command output is shown while SGR color is preserved.
 - Split Vibe editor insert/readline key handling into a focused mixin without changing editor behavior.
 - Consolidated compaction message-field reads through the shared message access helper.
 - Consolidated RPC transcript tool metadata normalization with tool event metadata so tool names, args, diffs, and changed files stay aligned.
@@ -370,7 +423,7 @@ All notable changes to Kward will be documented in this file.
 
 - Added a built-in editor that can be opened from the TUI with `$` or directly from the CLI with `kward edit <filename>`, with modern, Emacs-style, and Vibe editing modes.
 - Added richer editor workflows including syntax highlighting, undo/redo, auto-indent, soft wrap, mouse support, multi-cursor editing, relative line numbers, and an expanded Vim-like Vibe mode with visual selections, text objects, registers, marks, macros, substitution, and Ruby navigation.
-- Added `/shell`, an embedded Kward shell (`ekwsh`) for running workspace commands without leaving the TUI, including command/path completion, safe color output, optional global `ekwsh.yml` configuration, and rbenv shim autodetection.
+- Added `/shell`, an embedded Kward shell (`kwsh`) for running workspace commands without leaving the TUI, including command/path completion, safe color output, optional global `kwshrc` configuration, and rbenv shim autodetection.
 - Added `/files`, a searchable project file browser that can open files in the editor and remembers cursor and folder expansion state per workspace.
 - Added persistent TUI tabs for session-backed conversations, plus tab commands, shortcuts, status colors, and restoration across restarts.
 - Added `/git` workflows for reviewing changes, viewing diffs, staging or unstaging files, and writing commit messages from inside the TUI.

data/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to Kward
+
+Thank you for helping improve Kward. Small, focused changes with clear tests are the easiest to review and release.
+
+## Before you start
+
+- Search existing issues and pull requests for related work.
+- Open an issue before a large feature, new dependency, protocol change, or broad restructuring.
+- Report security concerns privately through [the security policy](SECURITY.md), not in a public issue.
+
+## Set up the project
+
+Kward requires Ruby 3.4 or newer.
+
+```bash
+git clone https://github.com/kaiwood/kward.git
+cd kward
+bundle install
+bundle exec rake test
+```
+
+Run the CLI from the checkout with:
+
+```bash
+ruby lib/main.rb
+ruby lib/main.rb "Explain this project"
+```
+
+See [Platform support](doc/platform-support.md) for operating-system and terminal expectations.
+
+## Make a change
+
+1. Keep the patch limited to one problem.
+2. Follow the existing Ruby style and ownership boundaries.
+3. Add focused Minitest coverage for behavior changes.
+4. Update user documentation when commands, configuration, tools, protocols, or workflows change.
+5. Add user-facing changes to the `[Unreleased]` section of `CHANGELOG.md`.
+
+Avoid unrelated refactors, formatting-only churn, generated-file commits, and new dependencies unless they are necessary for the change.
+
+## Verify the change
+
+Run the smallest relevant test first, then the full suite before opening a pull request:
+
+```bash
+ruby -Itest test/test_cli.rb
+bundle exec rake test
+```
+
+For documentation changes, also run:
+
+```bash
+bundle exec rake docs:check
+```
+
+The release preflight combines tests, documentation checks, package validation, and release metadata checks:
+
+```bash
+bundle exec rake release:preflight
+```
+
+Release preflight expects the current version and tag state to be ready for a release, so contributors normally do not need to run it for ordinary pull requests.
+
+## Open a pull request
+
+Describe:
+
+- the user-visible problem;
+- the chosen solution;
+- tests and checks run;
+- security, compatibility, or documentation implications;
+- screenshots for visible UI changes.
+
+A pull request should be understandable one commit at a time. Maintainers may ask for commits to be combined or reorganized before merge when that makes the final history clearer.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.83.0)
+    kward (0.84.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -9,6 +9,7 @@ PATH
       tty-prompt
       tty-reader
       tty-screen
+      unicode-display_width
 
 GEM
   remote: https://rubygems.org/
@@ -104,6 +105,9 @@ GEM
     tty-screen (0.8.2)
     typhoeus (1.6.0)
       ethon (>= 0.18.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
     webrick (1.9.2)
     wisper (2.0.1)
     yard (0.9.44)
@@ -146,7 +150,7 @@ CHECKSUMS
   html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
   io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
   json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  kward (0.83.0)
+  kward (0.84.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
@@ -174,6 +178,8 @@ CHECKSUMS
   tty-reader (0.9.0) sha256=c62972c985c0b1566f0e56743b6a7882f979d3dc32ff491ed490a076f899c2b1
   tty-screen (0.8.2) sha256=c090652115beae764336c28802d633f204fb84da93c6a968aa5d8e319e819b50
   typhoeus (1.6.0) sha256=bacc41c23e379547e29801dc235cd1699b70b955a1ba3d32b2b877aa844c331d
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
   wisper (2.0.1) sha256=ce17bc5c3a166f241a2e6613848b025c8146fce2defba505920c1d1f3f88fae6
   yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28

data/README.md

@@ -1,5 +1,17 @@
+<p align="center">
+  <img src="templates/default/fulldoc/html/images/kward_logo.png" width="150" alt="Kward logo">
+</p>
+
 # Kward
 
+<p align="center"><strong>An extensible Ruby coding agent for your terminal.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/kaiwood/kward/actions/workflows/ci.yml"><img src="https://github.com/kaiwood/kward/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://rubygems.org/gems/kward"><img src="https://badge.fury.io/rb/kward.svg" alt="RubyGems version"></a>
+  <a href="https://kaiwood.github.io/kward/"><img src="https://img.shields.io/badge/docs-kaiwood.github.io-9caf35" alt="Documentation"></a>
+</p>
+
 Kward is a coding agent for your terminal. It can inspect and edit a project, run commands, research problems, and save your work in sessions you can resume later.
 
 Use Kward from the terminal, its local browser interface, or a trusted JSON-RPC client. It works with ChatGPT/Codex and Claude subscriptions, hosted model APIs, GitHub Copilot, OpenRouter, and local servers such as Ollama, LM Studio, and llama.cpp.
@@ -12,6 +24,10 @@ Kward treats that work as an ongoing workspace rather than a disposable conversa
 
 Start with a normal coding conversation. If your workflow grows, you can add memory, reusable prompts and skills, local plugins, lifecycle hooks, MCP servers, transports, or a custom RPC client.
 
+<p align="center">
+  <img src="templates/default/fulldoc/html/images/kward_workflow.svg" width="1000" alt="Kward completing a focused coding change and test run">
+</p>
+
 ## Install
 
 Install Kward from RubyGems:
@@ -65,6 +81,8 @@ New to Kward:
 Work safely:
 
 - [Security and trust](doc/security.md): local permissions, external data flow, trusted extensions, and safe work in unfamiliar repositories.
+- [Security policy](https://github.com/kaiwood/kward/blob/main/SECURITY.md): privately report suspected vulnerabilities and understand supported security-fix versions.
+- [Platform support](doc/platform-support.md): macOS, Linux, WSL, native Windows, terminal, and sandbox support expectations.
 - [Permissions](doc/permissions.md): opt-in tool approval, write scopes, policy rules, and current limits.
 - [Command sandboxing](doc/sandboxing.md): opt-in OS-enforced boundaries for model-requested shell commands.
 - [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
@@ -83,7 +101,7 @@ Everyday workflows:
 - [Skills](doc/skills.md): add reusable instructions that load only for matching tasks.
 - [Prompt templates](doc/prompt-templates.md): create reusable slash prompts and use the starter templates installed by `kward init`.
 - [MCP servers](doc/mcp.md): connect trusted local Model Context Protocol tool servers.
-- [Pan mode](doc/pan.md): use the mobile-friendly browser interface on a trusted local network.
+- [Pan mode](doc/pan.md): use the mobile-friendly local browser interface or explicitly expose it to a trusted LAN.
 - [Local models](doc/local-models.md): connect Ollama, LM Studio, or llama.cpp and use a minimal replacement prompt.
 
 Extend and integrate:
@@ -109,6 +127,8 @@ Generated Ruby API:
 
 ## Development
 
+Read [Contributing to Kward](https://github.com/kaiwood/kward/blob/main/CONTRIBUTING.md) before preparing a pull request. Participation is governed by the [Code of conduct](https://github.com/kaiwood/kward/blob/main/CODE_OF_CONDUCT.md).
+
 Run tests:
 
 ```bash

data/Rakefile

@@ -1,8 +1,10 @@
 require "bundler/gem_tasks"
 require "fileutils"
+Warning[:experimental] = false if Warning.respond_to?(:[]=)
 require "html-proofer"
 require "open3"
 require "rdoc/task"
+require "rbconfig"
 require "rubygems/package"
 require "webrick"
 require "yard"
@@ -65,6 +67,44 @@ def verify_packaged_gem(gem_name)
   files
 end
 
+def verify_docs_branding
+  homepage = File.read("_yardoc/index.html")
+  required = [
+    "<title>Kward — Ruby Coding Agent for Your Terminal</title>",
+    '<meta name="description"',
+    '<link rel="canonical" href="https://kaiwood.github.io/kward/">',
+    '<link rel="icon" type="image/png"',
+    'href="file.getting-started.html">Get Started'
+  ]
+  missing = required.reject { |content| homepage.include?(content) }
+  abort("Generated documentation is missing branded homepage metadata: #{missing.join(", ")}") if missing.any?
+
+  getting_started = File.read("_yardoc/file.getting-started.html")
+  guide_required = [
+    "<title>Getting started | Kward Docs</title>",
+    '<link rel="canonical" href="https://kaiwood.github.io/kward/file.getting-started.html">'
+  ]
+  missing = guide_required.reject { |content| getting_started.include?(content) }
+  abort("Generated guide metadata is incorrect: #{missing.join(", ")}") if missing.any?
+end
+
+def verify_public_api_docs
+  api_page = File.read("_yardoc/file.api.html")
+  required_links = [
+    "Kward.html#plugin-class_method",
+    "Kward/PluginRegistry/DSL.html",
+    "Kward/PluginRegistry/Context.html",
+    "Kward/Tools/Base.html",
+    "Kward/ToolRegistry.html",
+    "Kward/RPC/Server.html",
+    "Kward/Prompts.html",
+    "Kward/Skills/Registry.html",
+    "Kward/ConfigFiles.html"
+  ]
+  missing = required_links.reject { |link| api_page.include?(%(href="#{link}")) }
+  abort("Generated public API landing page is missing supported entry points: #{missing.join(", ")}") if missing.any?
+end
+
 def rewrite_yard_markdown_links
   guide_names = Dir.glob("doc/*.md").map { |path| File.basename(path, ".md") }
 
@@ -87,7 +127,8 @@ task default: :test
 
 desc "Run the full test suite"
 task :test do
-  ruby "-Itest", "-e", 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }'
+  success = system(RbConfig.ruby, "-Itest", "-e", 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }')
+  abort("Test suite failed") unless success
 end
 
 RDoc::Task.new do |rdoc|
@@ -102,7 +143,8 @@ YARD::Rake::YardocTask.new do |yard|
     "--readme", "README.md",
     "--output-dir", "_yardoc",
     "--markup", "markdown",
-    "--template-path", "templates"
+    "--template-path", "templates",
+    "--no-stats"
   ]
 end
 
@@ -183,5 +225,7 @@ namespace :docs do
     }
 
     HTMLProofer.check_directory("_yardoc", options).run
+    verify_docs_branding
+    verify_public_api_docs
   end
 end

data/SECURITY.md

@@ -0,0 +1,31 @@
+# Security policy
+
+Kward can read files, edit workspaces, run commands, call external providers, and load trusted local extensions. Security reports are taken seriously, especially when they involve credential exposure, workspace-boundary bypasses, command execution, authentication, or remote access.
+
+## Supported versions
+
+Security fixes are made against the latest released version and the `main` branch. Upgrade to the newest Kward release before reporting behavior that may already have been fixed.
+
+## Report a vulnerability privately
+
+Do not open a public issue for a suspected vulnerability.
+
+Use GitHub's private vulnerability reporting form:
+
+<https://github.com/kaiwood/kward/security/advisories/new>
+
+Include, when available:
+
+- the affected Kward version and platform;
+- a concise description of the impact;
+- reproducible steps or a minimal proof of concept;
+- the expected security boundary;
+- any suggested mitigation.
+
+Do not include real API keys, OAuth tokens, customer data, private repository content, or other secrets. Use clearly fake fixtures and redact local paths when they are not relevant.
+
+The maintainer will aim to acknowledge a complete report within seven days, validate its impact, coordinate a fix, and agree on disclosure timing. Complex reports may take longer to investigate.
+
+## Security model
+
+Before reporting expected behavior as a vulnerability, review [Security and trust](doc/security.md), [Permissions](doc/permissions.md), and [Command sandboxing](doc/sandboxing.md). Kward's host process, user-directed shell features, and trusted extensions normally run with the current user's permissions; workspace guardrails and command-worker sandboxing have narrower documented boundaries.

data/doc/api.md

@@ -82,6 +82,10 @@ Generated entry points:
 
 The generated comments focus on these supported extension boundaries rather than trying to make every internal orchestration helper public. When a generated method lacks guide coverage, treat it as internal unless the page explicitly marks it as a public API.
 
+## Documentation checks
+
+`bundle exec rake docs:check` validates links, images, scripts, branded metadata, guide canonical URLs, and the curated plugin, tool, RPC, prompt, skill, and configuration entry points listed above. The generated site intentionally includes implementation detail for contributors, so aggregate documentation coverage across every internal constant and helper is not used as a release-quality signal.
+
 ## Public API expectations
 
 The generated reference is useful for understanding the codebase, but it does not make every class, method, or constructor a supported public API.

data/doc/composer.md

@@ -28,7 +28,7 @@ The composer supports familiar line-editing keys:
 
 | Key | Action |
 | --- | --- |
-| `Left` / `Right` | Move by character |
+| `Left` / `Right` | Move by visible character (Unicode grapheme) |
 | `Home` / `Ctrl+A` | Move to the start of the current line |
 | `End` / `Ctrl+E` | Move to the end of the current line |
 | `Ctrl+B` / `Ctrl+F` | Move left or right |

data/doc/configuration.md

@@ -128,7 +128,7 @@ By default, Kward stores user data under `~/.kward`. Common files and directorie
 ~/.kward/anthropic_auth.json
 ~/.kward/github_auth.json
 ~/.kward/PRINCIPLES.md
-~/.kward/ekwsh.yml
+~/.kward/kwshrc
 ~/.kward/prompts/
 ~/.kward/skills/
 ~/.kward/plugins/
@@ -169,24 +169,51 @@ Project-local hooks can also live in `.kward/hooks.json`, but Kward loads them o
 
 ## Embedded shell config
 
-The embedded Kward shell (`/shell`, internally `ekwsh`) reads optional global settings from `~/.kward/ekwsh.yml` or, when `KWARD_CONFIG_PATH` is set, from `ekwsh.yml` beside that config file.
+The embedded Kward shell (`/shell`, internally `kwsh`) reads the shell-style rc files `~/.kward/kwshrc` and `~/.kwshrc`, in that order. When `KWARD_CONFIG_PATH` is set, the first path is beside that config file instead. Later rc entries override earlier aliases and exported variables.
 
-Example:
+Example rc file:
+
+```sh
+alias ll='ls -la'
+alias gs="git status --short"
+export BUNDLE_WITHOUT=production
+export PATH="$HOME/bin:$PATH"
+source ~/.kward/kwsh-aliases
+```
+
+Only declarative `alias`, `export`, and `source` (or `.`) directives are handled. `source` parses the referenced file without executing it, resolving relative paths from the containing rc file. Other shell scripting is ignored for now.
+
+### Shell-agent model
+
+The transient shell assistant normally follows the active conversation's model and reasoning effort. Override those defaults in the main JSON configuration:
+
+```json
+{
+  "shell": {
+    "agent": {
+      "provider": "openrouter",
+      "model": "openai/gpt-5.6-sol",
+      "reasoning_effort": "none"
+    }
+  }
+}
+```
 
-```yaml
-env:
-  FORCE_COLOR: "1"
-  CLICOLOR_FORCE: "1"
+The optional `provider` selects a different backend for the transient shell assistant. Use the lowercase configuration IDs listed in [Model providers](providers.md). When it is omitted, the shell assistant follows the active conversation's provider, model, and reasoning effort. If a provider is explicitly configured without a model or reasoning effort, Kward uses that provider's defaults rather than inheriting values from the active conversation.
 
-aliases:
-  ll: "ls -la"
-  gs: "git status --short"
-  gd: "git diff --color=always"
+Environment variables take precedence over the JSON settings:
+
+```sh
+export KWSH_PROVIDER="openrouter"
+export KWSH_MODE="openai/gpt-5.6-sol"
+export KWSH_REASONING="none"
 ```
 
-`env` values are applied when shell mode starts, after Kward's conservative color defaults. `/shell` keeps one persistent local interactive shell process per tab. Keys must look like environment variable names (`A_Z`, digits after the first character, and underscores); invalid keys are ignored. Values are converted to strings.
+`KWSH_PROVIDER` selects the shell-agent provider, `KWSH_MODE` selects its model, and `KWSH_REASONING` selects its reasoning effort. Empty values are ignored.
+
+`export` values are applied when shell mode starts, after Kward's conservative color defaults, and are also available to leading-`!` commands. Keys must be valid environment-variable names; invalid keys are ignored. Values support shell quoting and simple `$VAR`/`${VAR}` expansion. `/shell` keeps one persistent local interactive shell process per tab.
 
-`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Configured aliases are available both inside `/shell` and after the normal composer's `!` prefix, including command-name Tab completion. Built-in shell commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. Prefix a submitted line with `?` inside `/shell` to ask the transient shell assistant about the current command output or state. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `ekwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current `/shell` session and are not available to `!command` input.
+`alias` entries expand the first word of a command once. For example, `alias ll='ls -la'` makes `ll lib` run `ls -la lib`. Configured aliases are available both inside `/shell` and after the normal composer's `!` prefix, including command-name Tab completion. Built-in shell commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. Prefix a submitted line with `?` inside `/shell` to ask the transient shell assistant about the current command output or state. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `kwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current `/shell` session and are not available to `!command` input.
 
 ## Provider and model settings
 
@@ -236,7 +263,7 @@ Model settings:
 
 `model` is a legacy generic fallback. Provider-specific values take precedence. Catalog providers use `<runtime-id>_model`; for example, direct OpenAI uses `openai_api_model`, Gemini uses `gemini_model`, and Groq uses `groq_model`. Codex keeps `openai_model`. `reasoning_effort` and `thinking_level` are generic reasoning settings. `thinking_level` is an alias for `reasoning_effort` honored by all providers. For each provider, Kward resolves reasoning in this order: the provider-specific key (for example `openai_reasoning_effort`), then the generic `reasoning_effort`, then `thinking_level`, then the default `medium`. `openai_reasoning_effort`, `anthropic_reasoning_effort`, `openrouter_reasoning_effort`, and `copilot_reasoning_effort` are provider-specific forms.
 
-Set `codex_show_raw_reasoning` to `true` to display raw Codex `reasoning_text` when the API does not provide reasoning summary text. It defaults to `false`; raw reasoning can include internal or unstable model output, so enable it only when you explicitly want to inspect that stream.
+OpenAI-hosted models do not expose their raw reasoning tokens. Kward displays the reasoning summaries and visible Codex commentary they provide. Set `codex_show_raw_reasoning` to `true` only for a backend that emits raw Codex `reasoning_text`; it defaults to `false` because raw reasoning can include internal or unstable model output.
 
 `stream_idle_timeout_seconds` limits how long a streamed Codex, Anthropic, or Local response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
 
@@ -399,14 +426,15 @@ Vibe `:prompt` uses a dedicated transient editor agent. Configure its model and
 {
   "editor": {
     "agent": {
-      "model": "gpt-5.5",
+      "provider": "anthropic",
+      "model": "claude-sonnet-5",
       "reasoning_effort": "medium"
     }
   }
 }
 ```
 
-These settings use the active tab's provider. If either value is omitted, Kward falls back to the active tab's value and then the client default. Editor-agent prompts and tool activity are kept out of the normal transcript and session history; the editor remains visible with a spinner while the transient turn runs.
+The optional `provider` selects a different backend for the transient editor assistant. Use the lowercase configuration IDs listed in [Model providers](providers.md). When it is omitted, the editor assistant follows the active tab's provider, model, and reasoning effort. `KWARD_EDITOR_PROVIDER` can override the JSON provider for one-off runs. If a provider is explicitly configured without a model or reasoning effort, Kward uses that provider's defaults rather than inheriting values from the active tab. Editor-agent prompts and tool activity are kept out of the normal transcript and session history; the editor remains visible with a spinner while the transient turn runs.
 
 The integrated Git and session diff viewers support unified and side-by-side layouts:
 
@@ -420,6 +448,27 @@ The integrated Git and session diff viewers support unified and side-by-side lay
 
 `diff_view` can be `auto`, `unified`, or `side_by_side`. In `auto` mode, Kward uses side-by-side output when the terminal is at least 120 columns wide and unified output in narrower terminals. Change it with `/settings` → Interface → Diff view.
 
+### Editor runners
+
+The editor can run the current in-memory buffer for supported scratchpad languages and normal files. It never saves a normal file automatically before running. Configure runner binaries under `editor.runners`; omitted entries use the built-in defaults.
+
+```json
+{
+  "editor": {
+    "runners": {
+      "node": { "binary": "node" },
+      "python": { "binary": ".venv/bin/python" },
+      "shell": { "binary": "/bin/bash" },
+      "go": { "binary": "/usr/local/go/bin/go" }
+    }
+  }
+}
+```
+
+`binary` may be an executable name resolved through `PATH`, an absolute path, or a relative path resolved from the active workspace. JavaScript and TypeScript use the `node` runner. TypeScript `.ts` buffers require a Node version with built-in TypeScript support; Node strips erasable types but does not type-check the buffer or read `tsconfig.json`. Node's built-in support does not run `.tsx` buffers. Runner processes execute directly without a shell.
+
+The initial runnable languages are Ruby, JavaScript, TypeScript, Python, Shell, Lua, Julia, Elixir, Crystal, Go, and Swift. Other highlighted languages remain editor-only until they have a suitable execution model.
+
 The editor includes syntax highlighting, automatic indentation, and matching-pair insertion for common languages. Unknown file types and color-disabled terminals use plain text. See [Integrated editor](editor.md#What_the_editor_supports) for the supported languages and detailed editing behavior.
 
 Auto-indent and matching-pair insertion are enabled by default. To disable either feature:
@@ -532,22 +581,20 @@ Manual `/compact [instructions]` works even when auto-compaction is disabled.
 
 ## Pan mode
 
-`kward pan` starts a LAN-reachable web UI and requires HTTP Basic Auth. Configure credentials before starting it:
+`kward pan` starts a local 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.
+`host` defaults to `127.0.0.1` and `port` defaults to `8765`. Set `host` to `0.0.0.0` only when you intentionally want access from another device on a trusted LAN. Kward prints a warning for every non-loopback binding because Pan uses plain HTTP without TLS.
 
-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, web, and configured extension tools to anyone on the LAN who has the credentials, so use it only on trusted networks. See [Pan mode](pan.md) for the full browser workflow, session behavior, security guidance, and limitations.
+Kward fails to start Pan unless `username` and either `password` or the `KWARD_PAN_PASSWORD` environment variable are configured. Config-file credentials are stored in plaintext; use a unique password and do not share the file. Pan exposes the agent's file, shell, web, and configured extension tools to anyone who can connect and authenticate. See [Pan mode](pan.md) for the full browser workflow, session behavior, security guidance, and limitations.
 
 ## Web search