kward 0.83.0 → 0.85.0

data/doc/configuration.md

@@ -2,7 +2,7 @@
 
 Kward reads user configuration from `~/.kward/config.json` by default. Most users should start with `/settings`, `/login`, `/model`, or `/reasoning` inside Kward. Edit JSON directly when you need an advanced setting, an integration, or a reproducible configuration.
 
-On first start, Kward creates the file when it does not exist. The starter config records defaults for personas, memory, the composer, editor, overlays, web search, update checks, sessions, skills, MCP, and workspace guardrails. Provider-specific model defaults are added only when you choose a provider or model.
+On first start, Kward creates the file when it does not exist. The starter config records defaults for personas, memory, the composer, editor, overlays, web search, update checks, sessions, skills, MCP, plugins, and workspace guardrails. Provider-specific model defaults are added only when you choose a provider or model.
 
 If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as the config directory for prompts, skills, memory, logs, and caches.
 
@@ -50,6 +50,27 @@ Add trusted local Model Context Protocol servers under `mcpServers`:
 
 See [MCP servers](mcp.md) for setup, supported fields, and security notes.
 
+### Plugin configuration
+
+Identified plugins read immutable configuration from the `plugins` object under
+their stable ID:
+
+```json
+{
+  "plugins": {
+    "com.example.issues": {
+      "endpoint": "https://issues.example.com"
+    }
+  }
+}
+```
+
+Plugin-managed state is stored privately under `plugin_state/<plugin-id>` in the
+active config directory. Credentials can come from private plugin config or the
+plugin's documented environment variables; do not commit them to shared config
+files. See [Plugins](plugins.md#Plugin_identity_and_host_services) for the host
+API, secret lookup order, and storage example.
+
 ### Transport plugins
 
 Transport plugin settings live under `transports` and are scoped by the
@@ -128,7 +149,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 +190,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
 
-```yaml
-env:
-  FORCE_COLOR: "1"
-  CLICOLOR_FORCE: "1"
+The transient shell assistant normally follows the active conversation's model and reasoning effort. Override those defaults in the main JSON configuration:
 
-aliases:
-  ll: "ls -la"
-  gs: "git status --short"
-  gd: "git diff --color=always"
+```json
+{
+  "shell": {
+    "agent": {
+      "provider": "openrouter",
+      "model": "openai/gpt-5.6-sol",
+      "reasoning_effort": "none"
+    }
+  }
+}
+```
+
+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.
+
+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.
 
-`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.
+`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.
+
+`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 +284,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.
 
@@ -248,6 +296,8 @@ Defaults:
 - Copilot: `gpt-5-mini`
 - Reasoning effort: `medium`
 
+The OpenAI/Codex and Copilot model choices include `gpt-6-astra`. GPT-6 Astra has a 1,050,000-token context window and supports `low`, `medium`, `high`, `xhigh`, and `max` reasoning effort; it does not support `none`.
+
 The Anthropic model choices include `claude-fable-5`, `claude-opus-5`, and `claude-sonnet-5`. Fable and Opus availability depends on the logged-in account and organization. Selecting a model without access returns an Anthropic provider error. Kward keeps Sonnet 5 as its default because it supports both Pro and Max subscriptions; select Opus 5 explicitly when it is available on the account.
 
 The interactive `/model` picker reads cached OpenRouter models when available. Run `kward openrouter refresh` to fetch text-capable models available to the configured OpenRouter API key and cache them under `~/.kward/cache/openrouter_models.json`. Run `kward openrouter list` to inspect the cached model ids.
@@ -399,14 +449,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 +471,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 +604,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
 
@@ -681,9 +751,9 @@ Available modes are:
 
 | Mode | Behavior |
 | --- | --- |
-| `ask` | Read-only tools run normally; file changes, shell commands, web tools, and MCP tools need approval. |
-| `workspace-write` | File changes within `write_scopes` run without approval; shell and network tools still need approval. |
-| `read-only` | Denies file changes, shell commands, web tools, and MCP tools. |
+| `ask` | Read-only tools run normally; file changes, shell commands, web tools, MCP tools, and plugin tools need approval. |
+| `workspace-write` | File changes within `write_scopes` run without approval; shell, network, MCP, and plugin tools still need approval. |
+| `read-only` | Denies file changes, shell commands, web tools, MCP tools, and plugin tools. |
 | `deny-by-default` | Denies risky tools unless an `allow` rule matches. |
 
 `allow`, `ask`, and `deny` rules are arrays of objects matching `tool`, `path`, `host`, `command`, or `source`. Deny rules always take precedence, then ask, then allow. Use `write_scopes` to restrict writes in `workspace-write` mode:

data/doc/editor.md

@@ -23,7 +23,7 @@ cd ~/code/my-project
 kward edit lib/kward/agent.rb
 ```
 
-Kward uses the current directory as the workspace, opens the file in the integrated editor, and exits when you close the editor. Use `--working-directory` when the file belongs to another workspace:
+Kward uses the current directory as the workspace, opens the file in the integrated editor, and exits when you close the editor. During an interactive chat session, you can also ask Kward to open a workspace file for you; it uses the `open_editor` tool when that capability is available. Opening the editor does not change or save the file unless you choose to do so. Use `--working-directory` when the file belongs to another workspace:
 
 ```bash
 kward --working-directory ~/code/my-project edit lib/kward/agent.rb
@@ -43,18 +43,23 @@ For a nested project tree, run:
 /files
 ```
 
-In the tree browser, use `↑`/`↓` to move, `←`/`→` to collapse or expand directories, `Enter` to toggle a directory or open a file, `Tab` or `/` to search, `i` to show or hide Git-ignored files, `@` to insert the selected file as an `@path` mention, and `Esc` to close. When you open a file from `/files`, quitting the editor returns to the browser at the same position.
+In the tree browser, use `↑`/`↓` to move, `←`/`→` to collapse or expand directories, `Enter` to toggle a directory or open a file, `Tab` or `/` to search, `i` to show or hide Git-ignored files, `f` to create a file, `d` to create a directory, `r` to rename the selected entry, `Backspace` to delete after confirmation, `@` to insert the selected file as an `@path` mention, and `Esc` to close. Create and rename names are entered in the prompt and must be single entry names. When you open a file from `/files`, quitting the editor returns to the browser at the same position.
 
 For an unsaved buffer, open a scratchpad:
 
 ```text
 /scratchpad
 /scratchpad markdown
-/scratchpad ruby
+/scratchpad js
+/scratchpad python
+/scratchpad help
 ```
 
-Scratchpads start as virtual editor buffers named `scratchpad.txt`, `scratchpad.md`, or `scratchpad.rb`. In Vibe mode, save one to a real file with `:w filename`.
-Ruby scratchpads can run with `:run` in Vibe mode or `Ctrl+R` in Modern mode; Kward executes the buffer and writes combined output after `__END__`, replacing any previous output there.
+Scratchpads accept canonical language names and familiar file-extension shortcuts. For example, `js` selects JavaScript, `py` selects Python, `rb` selects Ruby, `yml` selects YAML, `cs` selects C#, and `cpp` selects C++. Use `/scratchpad help` to print the complete list of names and aliases.
+
+All 26 built-in syntax-highlighted languages are available: Ruby, ERB, Crystal, Elixir, Julia, JavaScript, TypeScript, JSON, Markdown, YAML, Shell, Makefile, HTML, CSS, SCSS, Python, Go, Rust, Java, C#, C, C++, Swift, Kotlin, Lua, and SQL. Markdown buffers also apply the tagged language highlighter, auto-indentation, and endwise behavior inside fenced code blocks, such as a fence tagged `ruby` or `js`; unknown tags remain readable as plain text. Scratchpads use a matching virtual filename such as `scratchpad.js` or `scratchpad.py`; in Vibe mode, save one to a real file with `:w filename`.
+
+Supported editable buffers can run with `:run` in Vibe mode or `Ctrl+R` in Modern mode. This works for both scratchpads and normal editor files. Kward runs the current in-memory buffer, including unsaved changes, without saving the file automatically. It opens a read-only output pane in the lower half of the editor with the captured output, exit status, and duration. Drag with the mouse to make a virtual selection inside the output, then press `Ctrl+C` or `Cmd+C` to copy it (`y` in Vibe mode). Only the selected output text is copied; pane borders are excluded. `Cmd+C` requires the terminal to forward the Command key to Kward. Press `Esc` to return to editing, use the arrow or page keys to scroll, and press `Ctrl+C` without a selection to cancel a running buffer. Runnable languages are Ruby, JavaScript, TypeScript, Python, Shell, Lua, Julia, Elixir, Crystal, Go, and Swift; other languages currently provide editing and highlighting only.
 
 ```ruby
 puts "foo"
@@ -63,14 +68,14 @@ __END__
 foo
 ```
 
-The next run receives the current `__END__` section as Ruby `DATA`, then replaces it with the new output.
+The next run receives the current `__END__` section as Ruby `DATA`; the output window is refreshed without changing the source buffer.
 
 You can also type a relative path yourself and press `Enter`. If the file does not exist, Kward asks whether to create it.
 
 A few things to know:
 
 - `$` only opens the editor when it is the first character in the composer.
-- `/scratchpad` opens a plain-text scratchpad; pass `markdown` or `ruby` to pick another mode.
+- `/scratchpad` opens a plain-text scratchpad; pass a language name or shortcut to select syntax highlighting. `/scratchpad help` lists the available choices.
 - Once a file or scratchpad opens, the composer becomes the editor.
 - Save or quit to return to normal chat.
 - If the file changed on disk while you were editing, Kward asks before overwriting it.
@@ -252,7 +257,7 @@ Emacs mode is for users who prefer classic Emacs-style non-modal editing. Save a
 
 Vibe mode is a modal editor built for Kward, inspired by classic Vi and Vim. If you already know Vim, you will feel at home here. Files open in normal mode, where keys run commands. Press `i`, `a`, `o`, or another insert command to type text, then press `Esc` to return to normal mode.
 
-It supports a compact but practical modal-editing set: counts, operators with motions, visual selections, visual block edits, marks, registers, macros, search, repeat (`.`), Ruby-aware navigation, and `:` commands. It is not a full Vim clone — there are no splits or ex-mode scripting — but it covers everyday keyboard editing inside the conversation.
+It supports a compact but practical modal-editing set: counts, operators with motions, visual selections, multi-cursor and visual block edits, marks, registers, macros, search, repeat (`.`), Ruby-aware navigation, and `:` commands. It is not a full Vim clone — there are no splits or ex-mode scripting — but it covers everyday keyboard editing inside the conversation.
 
 The status line always shows the current mode (`NORMAL`, `INSERT`, `VISUAL`, `REPLACE`, or `:`) so you never lose track of where you are.
 
@@ -288,7 +293,7 @@ Use normal mode for movement, operators, marks, registers, macros, search, and c
 | `Ctrl+K`                | Move up by indentation level                    |
 | `Ctrl+F`                | Page down                                       |
 | `Ctrl+B`                | Page up                                         |
-| `Ctrl+D`                | Half page down                                  |
+| `Ctrl+D`                | Select the next occurrence and enter insert mode |
 | `Ctrl+U`                | Half page up                                    |
 | `Ctrl+E`                | Scroll down one line                            |
 | `Ctrl+Y`                | Scroll up one line                              |
@@ -354,17 +359,20 @@ Use normal mode for movement, operators, marks, registers, macros, search, and c
 
 ### Visual mode
 
-Visual mode uses the same motion language as normal mode where practical. Start characterwise visual mode with `v`, linewise mode with `V`, or visual block mode with `Ctrl+V`.
+Visual mode uses the same motion language as normal mode where practical. Arrow keys and plain `h`/`j`/`k`/`l` extend the selection. Start characterwise visual mode with `v`, linewise mode with `V`, or visual block mode with `Ctrl+V`.
 
 | Key                     | Action                                          |
 | ----------------------- | ----------------------------------------------- |
 | `o`                     | Switch active end of visual selection           |
+| `Ctrl+h` / `Ctrl+l`     | Outdent / indent selected lines                 |
+| `Ctrl+j` / `Ctrl+k`     | Move selected lines down / up                   |
 | `G` / `gg` / `N`motion  | Extend visual selection with counts/motions     |
 | `%`, `f`/`F`/`t`/`T`    | Extend visual selection with advanced motions   |
 | `iw` / `a(` / `ip`      | Select visual text objects                      |
 | `>` / `<`               | Indent / outdent selected lines                 |
 | `=`                     | Reindent selected lines                         |
-| `I` / `A`               | Insert / append text across visual block lines  |
+| `I` / `A`               | Insert cursors at the start / end of each selected line |
+| `Ctrl+D`                | Add the next occurrence of a characterwise selection |
 | `J`                     | Join selected lines                             |
 | `~` / `u` / `U`         | Swapcase / lowercase / uppercase selection      |
 | `/` / `?` / `n` / `N`   | Extend visual selection with search             |
@@ -388,7 +396,7 @@ Vibe insert mode also supports readline-style shortcuts for efficient editing wi
 | `Ctrl+E`         | Move to end of line                      |
 | `Ctrl+B`         | Move left                                |
 | `Ctrl+F`         | Move right                               |
-| `Ctrl+D`         | Delete character at cursor               |
+| `Ctrl+D`         | Select the next occurrence                |
 | `Ctrl+K`         | Kill to end of line                      |
 | `Ctrl+U`         | Kill to start of line                    |
 | `Ctrl+W`         | Delete word before cursor                |
@@ -416,7 +424,7 @@ Typing an opening bracket (`(`, `[`, `{`) or quote (`"`, `'`, `` ` ``) in visual
 
 ### Command mode
 
-Enter command mode with `:` from normal mode. Type a command and press `Enter`. Press `Esc` or `Ctrl+C` to cancel.
+Enter command mode with `:` from normal mode. Type a command and press `Enter`. Press `Esc` or `Ctrl+C` to cancel. From visual mode, `:` starts the command with the selected line range (`'<,'>`), as in Vim.
 
 | Command | Action                                     |
 | ------- | ------------------------------------------ |
@@ -426,6 +434,13 @@ Enter command mode with `:` from normal mode. Type a command and press `Enter`.
 | `:wq`   | Save and quit                              |
 | `:x`    | Save if changed, then quit                 |
 | `:N`    | Go to line `N`                             |
+| `:run`  | Run the complete current supported editor buffer; inside a Markdown fence, run that block into its `<output>` field |
+| `:run all` | Run every runnable Markdown fenced block sequentially into its `<output>` field |
+| `:prompt instruction` | Ask the editor agent to update the buffer |
+| `:s/a/b/g` | Substitute `a` with `b`                   |
+| `:'<,'>s/a/b/g` | Substitute only across the visual selection |
+
+Visual line ranges apply to `:s` and `:run`. For `:run`, select the body or complete fence of one Markdown code block with a runnable language, or place the cursor inside that block without making a selection; Kward runs that block and inserts or replaces a formatted `<output>` field without opening the output pane. `:run all` executes every runnable fenced block in document order, skips unlabeled or unsupported fences, continues after failures, and writes each runner error into that block's output field. An existing output field is searched for after the block until the next code fence, so inline fields are reformatted too. Without a matching output field, one is inserted directly below the block with one blank line. Other commands retain their normal save, navigation, file, and quit behavior.
 
 ### Vibe design notes
 

data/doc/extensibility.md

@@ -14,6 +14,7 @@ Start simple. Most users only need `PRINCIPLES.md`, workspace `AGENTS.md`, and m
 | Task-specific reusable instructions | skills |
 | Different tone or role | [personas](personas.md) |
 | Local Ruby behavior or integrations | plugins |
+| Slash commands that run a turn with system-level instructions | [plugin model-turn requests](plugins.md) |
 | External messaging or event integration | transport plugins |
 | Deterministic runtime policy or automation | lifecycle hooks |
 
@@ -89,7 +90,7 @@ Hooks are deterministic automation and policy. They are not model instructions.
 
 Use plugins when text instructions are not enough and you need Ruby code to run locally.
 
-Plugins can add slash commands, prompt context, footer UI, transcript observers, RPC-visible commands, and external transports. Transport plugins can connect external conversations to normal Kward sessions or explicitly transport-capable plugin chats; they remain distinct from plugin-owned tabs.
+Plugins can add legacy or schema-typed slash commands, namespaced typed RPC actions, model-callable tools, structured frontend-neutral UI, prompt context, footer UI, transcript observers, plugin-owned tabs, and external transports. Identified plugins also receive namespaced configuration, private durable storage, secret lookup, logging, lifecycle callbacks, cooperative background tasks, and managed cleanup through a shared host. Transport plugins can connect external conversations to normal Kward sessions or explicitly transport-capable plugin chats; they remain distinct from plugin-owned tabs.
 
 Use `kward transport list` and `kward transport status` to inspect registered transports. Run a foreground transport with `kward transport run NAME`.
 

data/doc/files.md

@@ -12,7 +12,7 @@ From an interactive Kward session, run:
 /files
 ```
 
-Kward opens the project file browser. Use the arrow keys or `j`/`k` to move through the tree, then press `Enter` on a file to open it in the integrated editor. Supported images (PNG, JPEG, GIF, and WebP) open as read-only inline previews when the terminal supports Kitty or iTerm2 image sequences.
+Kward opens the project file browser. Use the arrow keys or `j`/`k` to move through the tree, then press `Enter` on a file to open it in the integrated editor. Supported images (PNG, JPEG, GIF, and WebP) open as read-only inline previews when the terminal supports Kitty or iTerm2 image sequences. Use `f` for a new file, `d` for a new directory, or `r` to rename the selected file or directory; type the single entry name in the prompt and press `Enter`.
 
 When you quit the editor or close an image preview, Kward returns to the file browser at the same position so you can keep browsing nearby files.
 
@@ -40,7 +40,11 @@ Outside Git, Kward scans the workspace directory and skips common noisy director
 | `/` | Start search |
 | `Backspace` | Delete the last search character |
 | `i` | Show or hide Git-ignored files |
-| `Esc` | Leave search; press again to close the browser |
+| `f` | Create a file beneath the selected directory, or beside the selected file |
+| `d` | Create a directory beneath the selected directory, or beside the selected file |
+| `r` | Rename the selected file or directory; the prompt starts with its current name |
+| `Backspace` | Start deletion confirmation for the selected file or directory |
+| `Esc` | Leave search or name entry; cancel deletion; press again to close the browser |
 | `Q` | Close an image preview |
 | `+` / `-` | Zoom an image preview in / out |
 | `@` | Insert the selected file as an `@path` mention |
@@ -93,7 +97,7 @@ See [Integrated editor](editor.md) for editor modes, save/quit keys, search, sel
 
 Kward remembers the expanded folders, selected path, and Git-ignored file visibility for each workspace. The next time you open `/files` in the same project, it restores the browser close to where you left it.
 
-Search itself is temporary. Closing search returns to the normal tree, and closing the browser leaves your chat session intact.
+Search itself is temporary. Closing search returns to the normal tree, and closing the browser leaves your chat session intact. Create and rename operations reject existing names rather than replacing them; name entry accepts only one file or directory name, not a path. Backspace requires confirmation before deleting. Non-empty directories display an additional warning and require a second confirmation before recursive deletion.
 
 ## Image previews
 
@@ -103,5 +107,5 @@ Image previews are read-only and replace the file-list overlay while leaving the
 
 - `/files` is only available in the interactive prompt.
 - It opens files inside the current workspace.
-- It is a focused project browser, not a full file manager: it does not rename, move, copy, or delete files.
+- It is a focused project browser, not a full file manager: it does not move or copy files.
 - Ignored Git files are hidden by default when Git can provide the file list; press `i` in the tree view to show them.

data/doc/getting-started.md

@@ -7,6 +7,7 @@ This page gets you from install to a first useful chat.
 ## Requirements
 
 - Ruby 3.4 or newer.
+- macOS or Linux. WSL is best effort; native Windows is not currently supported. See [Platform support](platform-support.md).
 - Credentials for one model provider. The easiest setup is `kward login` or `/login` inside Kward.
 - Bundler only if you run Kward from a source checkout.
 
@@ -96,6 +97,8 @@ Find where user authentication is implemented and summarize the flow.
 
 Kward can read files, suggest edits, apply changes, and run commands from the workspace. Existing files must be read in the current conversation before Kward can edit them.
 
+The composer footer highlights the two main discovery shortcuts: type `/` to browse commands and `@` to find and mention project files. If no model provider is connected, the startup screen points directly to `/login` and `/model` before you submit a prompt.
+
 ## Ask one question and exit
 
 For quick tasks, pass the prompt directly:

data/doc/git.md

@@ -111,7 +111,9 @@ If the working tree is clean when you run `/git`, the overlay shows `No uncommit
 
 When an active worktree tab receives an explicit request to commit, the agent can use the model-facing `git_commit` tool. It runs Git in the trusted host process so linked-worktree metadata can be updated without granting arbitrary shell commands write access to shared `.git` metadata.
 
-The tool requires a commit message and can receive an optional list of workspace-relative paths. If paths are omitted, all current changes in the active worktree are included. Generic `run_shell_command` Git commands remain sandboxed and cannot replace this operation. It is exposed only for active interactive worktree tabs; RPC sessions do not currently support worktree bindings.
+The tool requires a commit message and can receive an optional list of paths relative to its selected worktree. It uses the active linked worktree by default. In an active worktree tab, `target: "origin"` selects the verified original repository worktree, allowing the same agent to finish a conflicted merge or commit explicitly requested origin changes without switching tabs. If paths are omitted, all current changes in the selected worktree are included.
+
+Selecting `origin` does not add a separate approval prompt; the normal configured tool-permission policy applies exactly as it does for `active`. Generic `run_shell_command` Git commands remain sandboxed and cannot replace `git_commit`. The tool is exposed only for active interactive worktree tabs; RPC sessions do not currently support worktree bindings.
 
 ## Notes and limitations
 

data/doc/pan.md

@@ -8,39 +8,41 @@ Use it when you want to work from another browser or device on a trusted network
 
 Pan is a small local HTTP server, not a hosted service. The machine running Kward performs model requests, reads and edits workspace files, runs tools, and stores sessions.
 
-Pan requires HTTP Basic Auth. Add credentials to `~/.kward/config.json`:
+Pan requires HTTP Basic Auth. Add a username and password to `~/.kward/config.json`:
 
 ```json
 {
   "pan_mode": {
-    "host": "0.0.0.0",
-    "port": 8765,
     "username": "kward",
     "password": "choose-a-long-private-password"
   }
 }
 ```
 
-The defaults are:
+Pan listens on `127.0.0.1:8765` by default, so only browsers on the same machine can connect. Kward refuses to start Pan unless a username and password are available.
+
+To keep the password out of `config.json`, omit `password` and provide it when starting Pan:
 
-- `host`: `0.0.0.0`, which listens on all network interfaces.
-- `port`: `8765`.
+```bash
+KWARD_PAN_PASSWORD="choose-a-long-private-password" kward pan
+```
 
-Kward refuses to start Pan unless both `username` and `password` are configured. The password is stored as plaintext in your config file, so do not reuse an important password or share the file.
+When stored in `config.json`, the password is plaintext. Do not reuse an important password or share the file. Environment variables avoid config-file storage but may still be visible to processes or shell-history tooling on your machine.
 
-For access from the same machine only, bind to loopback instead:
+To use Pan from another device on a trusted LAN, explicitly listen on all interfaces:
 
 ```json
 {
   "pan_mode": {
-    "host": "127.0.0.1",
+    "host": "0.0.0.0",
     "port": 8765,
-    "username": "kward",
-    "password": "choose-a-long-private-password"
+    "username": "kward"
   }
 }
 ```
 
+Then start Pan with `KWARD_PAN_PASSWORD` or add the password to that configuration. Kward prints a plain-HTTP exposure warning whenever Pan binds to a non-loopback address.
+
 ## Start Pan
 
 Run Pan from the project it should control:
@@ -56,12 +58,14 @@ Or select the workspace explicitly:
 kward --working-directory ~/code/my-project pan
 ```
 
-Kward prints the listening URL, workspace, and initial session path. With the default LAN binding, it detects and prints the machine's routed LAN address when available. Open port `8765` at that address, for example:
+Kward prints the listening URL, workspace, and initial session path. With the default loopback binding, open:
 
 ```text
-http://192.168.1.25:8765/
+http://127.0.0.1:8765/
 ```
 
+With an explicit `0.0.0.0` LAN binding, Kward detects and prints the machine's routed LAN address when available, such as `http://192.168.1.25:8765/`.
+
 Your browser asks for the configured Basic Auth username and password.
 
 Press `Ctrl+C` in the server terminal to stop Pan. Closing a browser tab does not stop the server or an active turn.
@@ -83,6 +87,12 @@ Press Return to send. Use Shift+Return for a new line. The composer grows with m
 
 Prompts are accepted while another turn is running. Pan puts them into a single queue and executes them sequentially. The status below the composer shows whether Kward is working and how many prompts remain queued.
 
+Plugin slash commands that request model turns (such as `/iddqd`) are not
+supported in Pan: its composer submits ordinary prompts, not plugin commands.
+Use the interactive TUI or RPC `turns/start` for these commands. The `/transcript`
+response reports `capabilities.pluginCommandTurns.supported: false` so browser
+clients can make this limitation explicit.
+
 ## Work with sessions
 
 Pan saves conversations through the same workspace-scoped session store as the interactive CLI. The session sidebar shows up to 50 recent sessions with their title, modified time, and message count.
@@ -142,8 +152,8 @@ Pan exposes powerful agent tools through ordinary HTTP. Basic Auth protects ever
 
 Use these precautions:
 
-- Run it only on a network and machine you trust.
-- Prefer `127.0.0.1` when remote access is unnecessary.
+- Keep the default `127.0.0.1` binding when remote access is unnecessary.
+- Bind to `0.0.0.0` only on a network and machine you trust.
 - Do not expose the port directly to the public internet.
 - Do not put Pan behind a public tunnel unless you provide a properly secured TLS/authentication boundary and understand the risk.
 - Use a unique password and protect `config.json`.

data/doc/permissions.md

@@ -22,7 +22,7 @@ In `ask` mode, Kward allows ordinary read-only tools and asks before the agent:
 - writes or edits a workspace file,
 - runs `run_shell_command`,
 - searches or fetches content on the web,
-- calls an MCP tool.
+- calls an MCP or model-callable plugin tool.
 
 When Kward needs approval in the interactive CLI, it shows the complete tool arguments in an overlay. For example, a write request includes the file path and content.
 
@@ -75,8 +75,8 @@ Set `permissions.mode` to one of these values:
 
 | Mode | Good for | Default behavior |
 | --- | --- | --- |
-| `ask` | Interactive supervised work | Asks before file changes, shell commands, web tools, and MCP tools. |
-| `workspace-write` | Routine edits in selected paths | Allows file changes in `write_scopes`; still asks before shell, web, and MCP tools. |
+| `ask` | Interactive supervised work | Asks before file changes, shell commands, web tools, MCP tools, and plugin tools. |
+| `workspace-write` | Routine edits in selected paths | Allows file changes in `write_scopes`; still asks before shell, web, MCP, and plugin tools. |
 | `read-only` | Code review and investigation | Denies risky tools by default. |
 | `deny-by-default` | Automation or tightly controlled runs | Denies risky tools unless an `allow` rule matches. |
 
@@ -110,7 +110,7 @@ Use `allow`, `ask`, and `deny` arrays to describe exceptions. A rule can match t
 - `path` — the file-tool path supplied by the model;
 - `command` — the requested shell command text;
 - `host` — the host in a `fetch_content` or `fetch_raw` URL;
-- `source` — currently useful for `mcp` tools.
+- `source` — currently useful for `mcp` and `plugin` tools.
 
 Patterns support `*` within a path segment and `**` across directories. Rule matching is case-sensitive.
 

data/doc/platform-support.md

@@ -0,0 +1,48 @@
+# Platform support
+
+Kward is a terminal application built around Ruby, PTYs, filesystem tools, and operating-system command boundaries. The core agent works across Unix-like systems, while a few terminal and sandbox features depend on the host platform.
+
+## Support matrix
+
+| Platform | Support level | Notes |
+| --- | --- | --- |
+| macOS | Supported | Primary support for the interactive TUI, PTY handoff, editor, shell, Pan, RPC, and Seatbelt command sandboxing. |
+| Linux | Supported | Interactive TUI, PTY handoff, editor, shell, Pan, and RPC are supported. Bubblewrap is required for OS-enforced command sandboxing. |
+| WSL | Best effort | Core CLI behavior should work under a current WSL environment. Clipboard, browser launch, inline images, PTY controls, and host integration vary by terminal and Windows configuration. |
+| Native Windows | Unsupported | Kward currently depends on Unix-style PTY and process behavior. Use WSL rather than a native Windows Ruby installation. |
+
+Kward requires Ruby 3.4 or newer. CI exercises Ruby 3.4 and the current Ruby release on Linux. Releases are developed and used on macOS as well.
+
+## Terminal expectations
+
+Use a modern UTF-8 terminal with ANSI control-sequence support. Basic chat works without optional graphics protocols. Some features depend on terminal capabilities:
+
+- modified keys such as Shift+Return and Ctrl+Tab may be intercepted by the terminal;
+- inline images require iTerm2 or a recognized Kitty-compatible terminal;
+- full-screen child applications temporarily own the terminal through PTY handoff;
+- Nerd Font project-file icons are opt-in because Kward cannot detect the configured font.
+
+See [Interactive composer](composer.md) for keyboard fallbacks and [Embedded shell](shell.md) for PTY behavior.
+
+## Sandboxing
+
+Command sandboxing is opt-in and platform-specific:
+
+- macOS uses Seatbelt profiles;
+- Linux uses Bubblewrap and requires a host configuration that permits unprivileged namespaces;
+- WSL support depends on the Linux distribution and host namespace policy;
+- native Windows has no supported command sandbox backend.
+
+When Kward cannot enforce a requested non-off sandbox mode, it fails closed rather than silently running the model-requested command without that boundary. See [Command sandboxing](sandboxing.md) for setup and exact limits.
+
+## Reporting a platform problem
+
+Run these commands first:
+
+```bash
+ruby --version
+kward --version
+kward doctor
+```
+
+When opening a bug report, include the operating system, terminal, Ruby version, Kward version, and the smallest reproduction. Remove credentials, private paths, repository content, and sensitive command output before posting logs.