kward 0.82.0 → 0.84.0

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
 
-```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"
+    }
+  }
+}
 ```
 
-`env` values are applied when shell mode starts, after Kward's conservative color defaults. 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.
+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` 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 `ekwsh` 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. 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.
+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"
+```
+
+`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.
+
+`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.
 
@@ -248,7 +275,7 @@ Defaults:
 - Copilot: `gpt-5-mini`
 - Reasoning effort: `medium`
 
-The Anthropic model choices include `claude-fable-5`, but Fable availability depends on the logged-in account and organization. Selecting it without access returns an Anthropic provider error.
+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.
 
@@ -393,6 +420,22 @@ The built-in TUI file editor supports three keybinding modes. Modern is the defa
 
 `mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`. You can change this from `/settings` → Interface → Editor mode; newly opened editor buffers pick up the setting immediately.
 
+Vibe `:prompt` uses a dedicated transient editor agent. Configure its model and reasoning effort under `editor.agent` when it should differ from the active tab:
+
+```json
+{
+  "editor": {
+    "agent": {
+      "provider": "anthropic",
+      "model": "claude-sonnet-5",
+      "reasoning_effort": "medium"
+    }
+  }
+}
+```
+
+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:
 
 ```json
@@ -405,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:
@@ -517,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
 

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, `@` 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.
@@ -85,21 +90,26 @@ $doc/editor.md
 1. Type `$doc/editor.md` in the composer.
 2. Pick the file from the matching results, or press `Enter` if the path is already complete.
 3. Edit the file.
-4. Save with `Ctrl+S` in Modern mode, `C-x C-s` in Emacs mode, or `:w` in Vibe mode. For an unsaved scratchpad in Vibe mode, use `:w filename`.
-5. Quit with `Ctrl+Q`, `C-x C-c`, or `:q`.
-6. Continue chatting with Kward.
+4. In Vibe normal mode, use `:prompt <instruction>` to ask the agent to update the current in-memory buffer. In Modern mode, press `Ctrl+.` and type the instruction in the editor prompt line. For example, `write a HelloWorld class`.
+5. The editor stays visible while the agent works; its status line shows a spinner. Review the generated buffer and save with `Ctrl+S` in Modern mode, `C-x C-s` in Emacs mode, or `:w` in Vibe mode. For an unsaved scratchpad in Vibe mode, use `:w filename`.
+6. Quit with `Ctrl+Q`, `C-x C-c`, or `:q`.
+7. Continue chatting with Kward.
 
 ## What the editor supports
 
 The editor is intentionally compact, but it covers the basics you need for quick changes:
 
 - Syntax highlighting for common languages, including Ruby, ERB templates, 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. ERB highlights template HTML outside ERB tags and Ruby inside `<% ... %>` tags. Unknown file types render as plain text.
-- Auto-indent, enabled by default. New lines inherit indentation, Tab jumps to the expected indentation or the next indentation stop, Shift+Tab moves indentation back, obvious closing tokens are re-indented, and Backspace in leading whitespace removes one indentation unit when possible. ERB recognizes common inline Ruby control tags and HTML opening tags when calculating the next indentation. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword; Ctrl+Enter also works from the middle of the line in terminals that report modified Enter keys.
+- Current-buffer word completion. After a partial word, Tab completes from words elsewhere in the active buffer; repeated Tab presses cycle nearby matches. Completion is case-sensitive and recognizes letters, numbers, and underscores. No project files or external sources are searched.
+- Auto-indent, enabled by default. New lines inherit indentation. When word completion does not apply, Tab jumps to the expected indentation or the next indentation stop. Shift+Tab moves indentation back, obvious closing tokens are re-indented, and Backspace in leading whitespace removes one indentation unit when possible. ERB recognizes common inline Ruby control tags and HTML opening tags when calculating the next indentation. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword; Ctrl+Enter also works from the middle of the line in terminals that report modified Enter keys.
 - Undo and redo, with up to 100 history entries per buffer.
 - Incremental search forward and backward.
 - Selection, copy, cut, and paste. Copy and cut also write to the terminal clipboard through OSC 52 when the terminal supports it.
 - A line-number gutter and a status line that shows the current mode and prompts.
 - Soft-wrap, enabled by default so long lines wrap within the editor width instead of scrolling sideways. Disable it with `editor.soft_wrap: false`.
+- Vibe `:prompt <instruction>` and Modern `Ctrl+.` prompt lines send the complete current buffer and document metadata to a dedicated, transient editor agent. The agent can replace the in-memory buffer through an explicit editor tool; it does not save files automatically.
+- Editor prompts and their tool activity are not added to the normal chat transcript or session history.
+- The editor remains visible and locked for editing while the agent runs. Its status line displays progress and a spinner; `Ctrl+C` cancels the request.
 
 ## Choosing an editor mode
 
@@ -122,12 +132,16 @@ You can also configure it in `config.json`:
 ```json
 {
   "editor": {
-    "mode": "modern"
+    "mode": "modern",
+    "agent": {
+      "model": "gpt-5.5",
+      "reasoning_effort": "medium"
+    }
   }
 }
 ```
 
-`mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`.
+`mode` can be `modern`, `emacs`, or `vibe`. The optional `editor.agent.model` and `editor.agent.reasoning_effort` settings configure the dedicated Vibe editor agent. They use the active tab's provider. When either value is omitted, it falls back to the active tab's setting and then the client default. Editor-agent turns use a dedicated system prompt and are not persisted in the active tab transcript. The old `default` value is still accepted as an alias for `modern`.
 
 To disable auto-indent or auto-close pairs:
 
@@ -156,6 +170,7 @@ Modern mode is the default and is the easiest place to start. It uses common ter
 | --------------------- | ------------------------------------------------- |
 | `Ctrl+S`              | Save                                              |
 | `Ctrl+Q`              | Quit; press again to discard unsaved changes      |
+| `Ctrl+.`              | Open the editor-agent prompt line                 |
 | `/`                   | Search forward                                    |
 | `?`                   | Search backward                                   |
 | `Ctrl+C`              | Copy selection, or cancel search                  |
@@ -192,7 +207,7 @@ Modern mode is the default and is the easiest place to start. It uses common ter
 | `Home` / `End`        | Move to start / end of line                       |
 | `PageUp` / `PageDown` | Scroll                                            |
 | `Enter`               | Insert newline, or confirm search                 |
-| `Tab`                 | Smart-indent to the expected indentation or next stop |
+| `Tab`                 | Complete a buffer word, or smart-indent when no match exists |
 | `Shift+Tab`           | Move indentation back by one stop                 |
 | `Backspace`           | Delete before cursor                              |
 | `Delete`              | Delete character at cursor                        |
@@ -233,7 +248,7 @@ Emacs mode is for users who prefer classic Emacs-style non-modal editing. Save a
 | `Home` / `End`        | Move to start / end of line                  |
 | `PageUp` / `PageDown` | Scroll                                       |
 | `Enter`               | Insert newline, or confirm search            |
-| `Tab`                 | Smart-indent to the expected indentation or next stop |
+| `Tab`                 | Complete a buffer word, or smart-indent when no match exists |
 | `Shift+Tab`           | Move indentation back by one stop            |
 | `Backspace`           | Delete before cursor                         |
 | `Delete` / `C-d`      | Delete character at cursor                   |
@@ -242,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.
 
@@ -278,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                              |
@@ -344,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             |
@@ -370,7 +388,7 @@ Vibe insert mode also supports readline-style shortcuts for efficient editing wi
 | ---------------- | ---------------------------------------- |
 | type text        | Insert characters                        |
 | `Enter`          | Insert newline                           |
-| `Tab`            | Smart-indent to the expected indentation or next stop |
+| `Tab`            | Complete a buffer word, or smart-indent when no match exists |
 | `Shift+Tab`      | Move indentation back by one stop        |
 | `Backspace`      | Delete before cursor                     |
 | `Delete`         | Delete character at cursor               |
@@ -378,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                |
@@ -406,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                                     |
 | ------- | ------------------------------------------ |
@@ -416,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/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.
 
@@ -24,7 +24,7 @@ Inside a Git repository, `/files` uses Git's project view:
 git ls-files --cached --others --exclude-standard
 ```
 
-That means tracked files and normal untracked files appear, while ignored files stay out of the list.
+That means tracked files and normal untracked files appear by default, while ignored files stay out of the list. Press `i` in the tree view to show or hide Git-ignored files; Kward remembers this choice for the workspace.
 
 Outside Git, Kward scans the workspace directory and skips common noisy directories such as `.git`, `.yardoc`, `_yardoc`, `node_modules`, `rdoc`, `tmp`, and `vendor/bundle`.
 
@@ -39,7 +39,12 @@ Outside Git, Kward scans the workspace directory and skips common noisy director
 | `Tab` | Start or stop search |
 | `/` | Start search |
 | `Backspace` | Delete the last search character |
-| `Esc` | Leave search; press again to close the browser |
+| `i` | Show or hide Git-ignored files |
+| `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 |
@@ -90,9 +95,9 @@ See [Integrated editor](editor.md) for editor modes, save/quit keys, search, sel
 
 ## Remembered state
 
-Kward remembers the expanded folders and selected path for each workspace. The next time you open `/files` in the same project, it restores the browser close to where you left it.
+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
 
@@ -102,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.
-- Ignored Git files are intentionally hidden when Git can provide the file list.
+- 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/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.
@@ -142,8 +146,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

@@ -176,6 +176,7 @@ The policy runs before Kward dispatches a model-requested tool. It does not cons
 - a permitted shell command can access files, processes, credentials, and network services available to your user account;
 - command-text rules are useful review controls, not a reliable way to enforce network destinations or all subprocess behavior;
 - direct commands that you type yourself—`!command`, `/capture`, `/shell`, and `/pty`—are treated as your actions and are outside this first policy scope;
+- commands run by the transient `?` shell assistant go through the normal permission and hook checks but deliberately use the user-owned `/shell` process, so the command sandbox cannot contain them;
 - plugins, hooks, and MCP servers are trusted local extensions with their own process access.
 
 For sensitive work, use a restricted operating-system account, container, virtual machine, or disposable checkout. [Command sandboxing](sandboxing.md) is a separate, opt-in operating-system boundary for model-requested `run_shell_command` workers. It can add filesystem and child-network restrictions, but does not cover Kward's host process, extensions, or direct interactive commands.

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.