kward 0.83.0 → 0.84.0

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/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/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/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.

data/doc/security.md

@@ -2,7 +2,7 @@
 
 Kward can read code, edit files, run commands, call model and search providers, and load local extensions. That makes it useful, but it also means you should treat it like a developer tool running with your account—not like a sandbox.
 
-This guide explains the trust boundaries and gives you a safe way to start work in an unfamiliar repository.
+This guide explains the trust boundaries and gives you a safe way to start work in an unfamiliar repository. Report suspected vulnerabilities privately through the [security policy](https://github.com/kaiwood/kward/blob/main/SECURITY.md).
 
 ## The short version
 
@@ -56,7 +56,8 @@ Kward's built-in file tools normally resolve paths inside the active workspace.
 
 These protections reduce accidental edits. They do not contain the whole process:
 
-- With `sandbox.mode: off` (the default), `run_shell_command`, `!command`, `/capture`, `/shell`, and `/pty` run with your user permissions.
+- With `sandbox.mode: off` (the default), `run_shell_command`, `!command`, `/capture`, `/shell`, `/pty`, and editor buffer runners run with your user permissions.
+- Editor buffer runners are user-directed and execute the current in-memory buffer, including normal files and scratchpads, through the configured `editor.runners` binary without a shell. They are not covered by the command sandbox.
 - A non-off [command sandbox](sandboxing.md) restricts only model-requested `run_shell_command` workers and their descendants. It does not cover `!command`, `/capture`, `/shell`, or `/pty`, including commands that the transient `?` shell assistant runs through the user's persistent `/shell` process.
 - External `/shell` commands, `!command`, and `/pty` receive an interactive PTY. Kward forwards a conservative set of line-oriented controls into the inline region, then grants full-terminal passthrough when a child emits screen-oriented or unknown controls. Full passthrough bypasses transcript control-sequence sanitization, so run only commands you trust with terminal access. `capture <command>` and `/capture <command>` sanitize their captured output.
 - Plugins, command hooks, and MCP servers are local processes with the same general operating-system access.

data/doc/shell.md

@@ -23,13 +23,12 @@ The command runs from the active workspace root and begins in an inline PTY regi
 
 When an inline command exits without reading input, safe output is mirrored into the transient transcript view so a repaint cannot hide it. Carriage-return and horizontal-cursor progress redraws are reduced to their final visible lines, while an unterminated synchronized-output update is closed before Kward redraws. If the child reads input, Kward retains only output captured before the first forwarded input byte; this prevents echoed passwords, OTPs, or other input from entering tab state. Output from one-off commands is never added to the AI conversation or sent to the model.
 
-Shell output can leave transient text in the transcript area. **After the command finishes, press Ctrl+L to redraw the durable conversation and clear that transient `!command` output.** While an interactive command is still running, the composer remains frozen and keyboard input—including Ctrl+L and Kward's tab shortcuts—belongs to the child process.
+Shell output can leave transient text in the transcript area. **After the command finishes, press Ctrl+L to redraw the durable conversation and clear that transient `!command` output.** While an interactive command owns the terminal, the composer remains frozen and ordinary keyboard input belongs to the child process. Kward's tab shortcuts are intercepted separately; switching tabs detaches the command and lets it continue in the originating tab's bounded background state.
 
-Configured `ekwsh.yml` aliases also work after `!`:
+Configured `kwshrc` aliases also work after `!`:
 
-```yaml
-aliases:
-  glog: "git log --decorate --stat --graph"
+```sh
+alias glog='git log --decorate --stat --graph'
 ```
 
 ```text
@@ -38,9 +37,8 @@ aliases:
 
 An alias that resolves to `kward edit <filename>` opens Kward's integrated editor in the current session instead of starting a nested Kward process:
 
-```yaml
-aliases:
-  vibe: "kward edit"
+```sh
+alias vibe='kward edit'
 ```
 
 ```text
@@ -112,6 +110,8 @@ If you explicitly ask the assistant to change shell state, it can use the active
 
 For a suggestion or prepared command, the assistant uses `prepare_shell_command`. The command is placed in the shell composer but is not run until you press `Enter`. Running a command directly and preparing one are deliberately separate actions.
 
+If you explicitly ask it to open an existing workspace file, the assistant uses `open_editor` to open Kward's integrated editor. Opening the editor does not modify or save the file.
+
 The shell assistant cannot safely run commands that require terminal input. Ask it to prepare those commands instead. The local `/shell` session keeps one interactive shell process alive, so directory changes, variables, functions, aliases, and other shell state persist between commands. The one-off `!command` and `/capture` workflows remain separate. SSH remains available through the normal interactive PTY handoff, but shell-agent prompting resumes after that SSH session exits.
 
 ## Interactive and captured commands
@@ -131,13 +131,13 @@ Use `capture` inside `/shell` when you want ordinary, readable output in Kward's
 
 ```sh
 capture git status --short
-capture bundle exec ruby -Itest test/test_ekwsh.rb
+capture bundle exec ruby -Itest test/test_kwsh.rb
 ```
 
-An `ekwsh` `capture` command:
+An `kwsh` `capture` command:
 
 - does not receive keyboard input,
-- uses the timeout and output-size limit from `ekwsh.yml`,
+- uses kwsh's built-in timeout and output-size limits,
 - preserves safe color and styling,
 - strips controls that could corrupt Kward's TUI,
 - can be cancelled with Ctrl+C.
@@ -163,9 +163,9 @@ Each Kward tab owns its `/shell` state. Switching away and back restores that ta
 - runtime aliases,
 - shell prompt and transcript view.
 
-Shell commands use a separate, workspace-scoped history rather than the normal chat-prompt history. Configure its size with `history_limit` in `ekwsh.yml`.
+Shell commands use a separate, workspace-scoped history rather than the normal chat-prompt history. The shell-history limit is a built-in kwsh default.
 
-Kward's tab shortcuts work at the shell prompt and while a captured command is running. During an interactive command, the child owns every key; exit or interrupt it before switching Kward tabs. Bounded output from shell-agent `?` turns is also retained in the tab's transient runtime view, so it is restored when you switch away and back without being added to session history. Ctrl+L clears this transient shell and shell-agent output.
+Kward's tab shortcuts work at the shell prompt and while a shell command is running. Switching tabs detaches the running command instead of interrupting it; bounded output and completion state remain owned by the originating tab and are restored when you return. While detached, the command no longer receives terminal input. Explicit cancellation or shutdown still terminates detached work. Bounded output from shell-agent `?` turns is also retained in the tab's transient runtime view, so it is restored when you switch away and back without being added to session history. Ctrl+L clears this transient shell and shell-agent output.
 
 ## Completion
 
@@ -210,6 +210,7 @@ The persistent `/shell` process handles these commands in-session so their state
 | `cd [dir]` | Change the shell directory. Supports `cd`, `cd -`, and relative paths. |
 | `pwd` | Print the shell directory. |
 | `export KEY[=value]` | Set an environment variable. `export` and `export -p` list variables. |
+| `source <file>` / `. <file>` | Parse and apply aliases and exports from an rc file immediately. |
 | `unset KEY` | Remove an environment variable. |
 | `alias [name]` | List, inspect, or create aliases. |
 | `unalias name` / `unalias -a` | Remove aliases. |
@@ -220,39 +221,56 @@ The persistent `/shell` process handles these commands in-session so their state
 
 Built-ins take precedence over aliases and executables.
 
-## Configure ekwsh
+## Configure kwsh
 
-Global shell configuration lives at:
+Global shell configuration lives in these optional rc files, loaded in order:
 
 ```text
-~/.kward/ekwsh.yml
+~/.kward/kwshrc
+~/.kwshrc
 ```
 
-When `KWARD_CONFIG_PATH` selects another main config file, Kward reads `ekwsh.yml` from the same directory.
+When `KWARD_CONFIG_PATH` selects another main config file, Kward reads the first file beside that config file instead. The later file overrides earlier aliases and exported variables with the same names. The rc format currently supports declarative `alias`, `export`, and `source` directives:
 
-A practical configuration might look like this:
+```sh
+alias ll='ls -la'
+alias gs="git status --short"
+export BUNDLE_WITHOUT=production
+export PATH="$HOME/bin:$PATH"
+source ~/.kward/kwsh-aliases
+```
 
-```yaml
-shell: /bin/sh
-timeout_seconds: 300
-max_output_bytes: 1048576
-history_limit: 1000
+`source` reads another rc file without executing it; relative paths in rc-file directives are resolved from the file containing the directive. When entered as a `/shell` builtin, the path is resolved from the current shell directory and its aliases and exports are applied immediately, without restarting Kward. Unsupported shell scripting is ignored for now.
 
-env:
-  FORCE_COLOR: "1"
-  BUNDLE_WITHOUT: "production"
-  RAILS_ENV: "test"
+The transient shell assistant normally follows the active conversation's model and reasoning effort. Configure it in the main JSON file:
 
-aliases:
-  ll: "ls -la"
-  gs: "git status --short"
-  gd: "git diff --color=always"
-  glog: "git log --decorate --stat --graph"
-  be: "bundle exec"
-  t: "bundle exec ruby -Itest"
+```json
+{
+  "shell": {
+    "agent": {
+      "provider": "openrouter",
+      "model": "openai/gpt-5.6-sol",
+      "reasoning_effort": "none"
+    }
+  }
+}
 ```
 
-### Settings
+The optional `provider` uses the lowercase configuration IDs listed in [Model providers](providers.md). When omitted, the shell assistant follows the active conversation. If a provider is explicitly configured without a model or reasoning effort, Kward uses that provider's defaults instead of inheriting the active conversation's values.
+
+Override those settings with environment variables:
+
+```sh
+export KWSH_PROVIDER="openrouter"
+export KWSH_MODE="openai/gpt-5.6-sol"
+export KWSH_REASONING="none"
+```
+
+Environment variables take precedence over the JSON settings, and empty values are ignored.
+
+### Runtime defaults
+
+These runtime settings are built into kwsh and are not configurable through rc files:
 
 | Setting | Default | What it does |
 | --- | --- | --- |
@@ -265,14 +283,14 @@ Invalid or relative `shell` paths fall back to `/bin/sh`. These timeout and outp
 
 ### Environment
 
-Configured `env` values are applied when `/shell` starts. Keys must be valid environment-variable names; nil values and invalid keys are ignored, and other values are converted to strings.
+`export` values from rc files are applied when `/shell` starts 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.
 
 Kward also supplies conservative terminal defaults:
 
 ```sh
-CLICOLOR=1
-COLORTERM=truecolor
-TERM=xterm-256color  # only when TERM is missing or dumb
+export CLICOLOR=1
+export COLORTERM=truecolor
+export TERM=xterm-256color  # only when TERM is missing or dumb
 ```
 
 It does not force color. Set `FORCE_COLOR`, `CLICOLOR_FORCE`, or a command-specific option such as `--color=always` when needed.
@@ -283,18 +301,17 @@ When rbenv is available, Kward adds its shims and bin directories to `PATH` and
 
 Aliases replace the first command word once and append any remaining arguments:
 
-```yaml
-aliases:
-  ll: "ls -la"
-  t: "bundle exec ruby -Itest"
+```sh
+alias ll='ls -la'
+alias t='bundle exec ruby -Itest'
 ```
 
 ```sh
 ll lib
 # runs: ls -la lib
 
-t test/test_ekwsh.rb
-# runs: bundle exec ruby -Itest test/test_ekwsh.rb
+t test/test_kwsh.rb
+# runs: bundle exec ruby -Itest test/test_kwsh.rb
 ```
 
 Configured aliases work inside `/shell` and after `!`. Aliases created with the `alias` built-in belong only to the current `/shell` session and are not shared with one-shot `!command` input.

data/doc/troubleshooting.md

@@ -10,14 +10,24 @@ This page covers common issues and how to diagnose them. When something is not w
 kward doctor
 ```
 
-It checks that your config file is readable and valid JSON, that the config and session directories are writable, that the workspace exists, which provider and model are active, and which credentials are configured. Use it as the first diagnostic step for any unexpected behavior.
+It checks that your config file is readable and valid JSON, that the config and session directories are writable, that the workspace exists, which provider and model are active, and which credentials are configured. Core check failures produce a nonzero exit status, so the command can also guard setup scripts. Optional features such as Pan are reported separately and do not make an otherwise healthy setup fail.
 
-`kward auth status` gives a focused view of credentials only, also without printing secrets:
+`kward auth status` gives a focused view of configured credentials only, also without printing secrets:
 
 ```bash
 kward auth status
 ```
 
+Use `kward auth status --all` when you also want to see every unconfigured provider.
+
+Kward keeps normal command failures concise. To include a Ruby backtrace while diagnosing an unexpected failure, rerun the command with debug errors enabled:
+
+```bash
+KWARD_DEBUG=1 kward "Repeat the failing task"
+```
+
+Backtraces can include local paths and implementation details. Review them before sharing them publicly.
+
 ## Authentication errors and token expiration
 
 OAuth tokens expire. Kward refreshes access tokens automatically when a refresh token is available, but if the refresh token is missing or expired, requests fail with a provider-specific error:

data/doc/usage.md

@@ -66,7 +66,7 @@ Inside interactive mode, ask Kward to run a command:
 Run the focused test for the CLI status command.
 ```
 
-Or run an interactive PTY command yourself from the composer by prefixing it with `!`. Aliases configured in `ekwsh.yml` are expanded here too:
+Or run an interactive PTY command yourself from the composer by prefixing it with `!`. Aliases configured in `kwshrc` are expanded here too:
 
 ```text
 !git status --short
@@ -78,7 +78,7 @@ For several commands, enter the embedded Kward shell:
 /shell
 ```
 
-`/shell` opens `ekwsh`, a Kward-native command mode with one persistent local shell process. It preserves state such as the current directory, environment variables, functions, and aliases between commands. Prefix a line with `?` inside `/shell` to ask a transient shell assistant about the latest output, execute an explicit state change, or prepare a command without running it. External commands receive an interactive PTY by default, so `git log`, `less`, Vim, SSH, and REPLs work without a prefix. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, transcript-friendly output. See [Embedded shell](shell.md) for built-ins, completion, configuration, ANSI handling, PTY passthrough, and limitations.
+`/shell` opens `kwsh`, a Kward-native command mode with one persistent local shell process. It preserves state such as the current directory, environment variables, functions, and aliases between commands. Prefix a line with `?` inside `/shell` to ask a transient shell assistant about the latest output, execute an explicit state change, or prepare a command without running it. External commands receive an interactive PTY by default, so `git log`, `less`, Vim, SSH, and REPLs work without a prefix. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, transcript-friendly output. See [Embedded shell](shell.md) for built-ins, completion, configuration, ANSI handling, PTY passthrough, and limitations.
 
 ## Shell commands
 
@@ -160,7 +160,7 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/skill <name>` | activate a configured skill explicitly for the current session. |
 | `/stats [range]` | summarize enabled local telemetry. |
 | `/hooks ...` | inspect, diagnose, trust, or untrust lifecycle hooks. |
-| `/scratchpad [text|markdown|ruby]` | open an unsaved editor buffer. |
+| `/scratchpad [language|help]` | open an unsaved, syntax-highlighted editor buffer; `/scratchpad` alone opens plain text. |
 | `/redraw` | fix terminal drawing after resize or glitches. |
 | `/reload` | reload installed plugins. |
 | `/exit` | leave Kward. |
@@ -263,13 +263,13 @@ This screenshot shows the broken layout. Find the likely CSS issue.
 
 ## Pan mode
 
-Pan mode starts a mobile-friendly LAN web UI:
+Pan mode starts a mobile-friendly local web UI:
 
 ```bash
 kward --working-directory ~/code/project pan
 ```
 
-Use it only on trusted networks. It exposes file, shell, web, and configured extension tools through a browser UI and requires credentials configured in `config.json`. Pan saves conversations to the normal workspace session store; its session drawer can create, resume, rename, and delete sessions. Session changes are disabled while turns are active or queued. See [Pan mode](pan.md) for setup, browser workflows, security, and limitations.
+Pan binds to loopback by default. Exposing it to a trusted LAN requires an explicit host setting and prints a warning because Pan uses plain HTTP. It exposes file, shell, web, and configured extension tools through a browser UI and requires a configured username plus a config or environment password. Pan saves conversations to the normal workspace session store; its session drawer can create, resume, rename, and delete sessions. Session changes are disabled while turns are active or queued. See [Pan mode](pan.md) for setup, browser workflows, security, and limitations.
 
 ## RPC backend