kward 0.82.0 → 0.84.0

data/doc/releasing.md

@@ -60,13 +60,21 @@ If preparation fails before the commit, the command restores the version, lockfi
 A pushed `v*` tag starts `.github/workflows/release.yml`. The workflow:
 
 1. Checks that the tag, gem version, and changelog heading agree.
-2. Runs the full test suite and generated-documentation checks against Ruby 3.4.
+2. Installs and enables Bubblewrap, then runs the full test suite and generated-documentation checks against Ruby 3.4 using the same Linux sandbox setup as normal CI.
 3. Builds the gem and verifies its packaged files.
 4. Publishes through RubyGems trusted publishing.
-5. Verifies the local gem checksum against the artifact served by RubyGems.org.
-6. Creates `Kward VERSION` as a GitHub Release using that version's changelog section and attaches the verified gem.
+5. Downloads the canonical published gem from RubyGems.org, waiting for propagation when necessary, and verifies its checksum against the RubyGems API.
+6. Creates `Kward VERSION` as a GitHub Release using that version's changelog section and attaches the verified RubyGems artifact.
 
-The publishing job uses the protected `release` environment. If RubyGems.org already has the version after a partially completed workflow, a rerun rebuilds the gem and verifies that it exactly matches the published checksum before continuing. For an existing GitHub Release, the workflow downloads and compares the gem, uploads it when missing, and publishes an unfinished draft. This makes normal workflow reruns safe without silently replacing mismatched artifacts.
+The publishing job uses the protected `release` environment. If RubyGems.org already has the version after a partially completed workflow, a rerun downloads and verifies the canonical published gem before continuing. This also accommodates trusted-publishing attestations that can change the published gem bytes. For an existing GitHub Release, the workflow downloads and compares the gem, uploads it when missing, and publishes an unfinished draft. This makes normal workflow reruns safe without silently replacing mismatched artifacts.
+
+If the workflow itself needs a fix after a tag has already been pushed, commit and push the fix to `main`, then recover the existing tag with the updated workflow:
+
+```bash
+gh workflow run Release --ref main -f tag=v0.82.0
+```
+
+Manual recovery still checks out and verifies the tagged source before publishing. The `release` environment permits automatic version-tag runs and manual recovery runs from `main` only.
 
 Follow the run from the repository's **Actions → Release** page. Installation can be checked after publication with:
 

data/doc/rpc.md

@@ -80,11 +80,11 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
 - `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns and advertises discovery with `methods: ["tools/list", "mcp/status"]`, `toolMetadata: true`, and `serverStatus: true`. It does not support MCP resources, prompts, sampling, or Streamable HTTP.
 - `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
 - `extensionUi`: question bridge support via `ui/question` and `ui/answerQuestion`, plus plugin footer updates via `ui/footer`; other UI primitives are explicitly unsupported.
-- `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access.
+- `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access. Vibe editor prompts are unsupported over RPC (`composer.editorPrompt.supported: false`) because RPC has no live integrated editor buffer.
 - `security`: trusted-local behavior and optional per-turn tool approval. By default, RPC turns have no workspace mutation guard or tool approval, so shell commands and file changes can run. Clients can inspect file-tool guardrails through `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`. `security.sandbox` reports the command sandbox mode, enforcement backend, and filesystem and network capabilities; session pinning and one-time elevation are unsupported. See [Command sandboxing](sandboxing.md) for the boundary and its limits.
 - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
 - `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
-- `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell`, `!command`, `/capture`, and PTY handoff require the local TUI. Model-requested `run_shell_command` tools remain bounded, captured, and noninteractive over RPC.
+- `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell`, its transient `?` shell assistant, `!command`, `/capture`, and PTY handoff require the local TUI. Model-requested `run_shell_command` tools remain bounded, captured, and noninteractive over RPC.
 - `logging`: local redacted telemetry, its directory and enabled categories, `logging/stats` and `logging/tokenCsv`, bucketed `usageCsv` support, JSONL storage, and 10 MB rotation with manual retention. Logs contain redacted metadata only. Configuration uses the `logging` key and `KWARD_LOGGING` environment prefix.
 
 ### `shutdown`

data/doc/sandboxing.md

@@ -106,12 +106,16 @@ this interface.
 ## Boundaries and limits
 
 The current implementation protects **model-requested command workers only**.
+The transient `?` shell assistant is intentionally not one of those workers: its
+`run_shell_command` calls use the active user-owned `/shell` process so shell
+state can persist.
+
 It does not sandbox:
 
 - the Kward Ruby host process;
 - model-provider, search-provider, or RPC traffic;
 - trusted Ruby plugins;
-- MCP servers, lifecycle hooks, `/shell`, `!command`, `/capture`, or `/pty`.
+- MCP servers, lifecycle hooks, `/shell`, `?` shell-agent commands, `!command`, `/capture`, or `/pty`.
 
 Sandboxed command workers receive a minimal environment: Kward preserves only
 basic terminal, locale, and path variables, then supplies a private `HOME` and

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,8 +56,9 @@ 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.
-- 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`.
+- 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.
 - Read-before-edit applies to Kward's file tools, not to arbitrary shell commands or extension code.

data/doc/shell.md

@@ -4,6 +4,7 @@ Kward lets you run your own shell commands without leaving the interactive TUI.
 
 - **For one quick command, use `!command`.** It runs from the active workspace and returns you to the normal composer when it finishes.
 - **For a longer stretch of shell work, use `/shell`.** It keeps its directory, environment, aliases, and history between commands.
+- **To ask Kward for help from inside `/shell`, prefix the request with `?`.** It can inspect the latest shell output, run an explicitly requested state change, or prepare a command in the shell prompt for your confirmation.
 - **For bounded output in the transcript view, use `/capture <command>`.** Inside `/shell`, use `capture <command>` for the same kind of readable output while keeping the shell's current state.
 
 Ordinary `!command` input and external commands inside `/shell` receive an interactive PTY. Pagers, Vim, SSH, REPLs, password prompts, and other interactive tools therefore work without a `pty` prefix.
@@ -20,15 +21,14 @@ Prefix a command with `!` in the normal composer:
 
 The command runs from the active workspace root and begins in an inline PTY region above a frozen composer. Line-oriented output, single-line carriage-return progress, and synchronized-output update brackets scroll the transcript area naturally while keyboard input belongs to the child process. If the child emits alternate-screen, clear-screen, absolute cursor, or unknown terminal controls, Kward conservatively hides the composer and switches permanently to full-terminal passthrough for the rest of that command. Pagers and full-screen applications therefore retain the complete terminal without relying on a command-name allowlist.
 
-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. Shell output is never added to the AI conversation or sent to the model.
+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
@@ -37,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
@@ -90,6 +89,31 @@ Leave shell mode with `exit`, `logout`, or Ctrl+D on an empty prompt.
 
 `cd` changes only the embedded shell's directory. It does not change Kward's workspace root or the directory used by the model's other tools.
 
+## Ask the shell agent
+
+While `/shell` is active, start a submitted line with `?` to ask the transient shell assistant:
+
+```text
+? why did the last command fail?
+? show me which process is listening on port 3000
+? prepare a command to find Ruby files changed today
+```
+
+The assistant receives the current shell directory, the last command, its exit status, and bounded output from that command. Output is sent to the model only because you explicitly asked with `?`; it is sanitized and bounded before being included, and shell-agent turns are not added to the normal session history.
+
+If you explicitly ask the assistant to change shell state, it can use the active shell session:
+
+```text
+? cd into test
+? set RAILS_ENV to test
+```
+
+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
 
 External commands inside `/shell` are interactive by default:
@@ -101,19 +125,19 @@ ruby
 ssh example.com
 ```
 
-Kward gives each command the terminal, forwards keyboard input, and restores the shell prompt when the command exits. It prints the submitted command but no PTY start message or exit-status summary. The line-oriented Git commands `git fetch`, `git ls-remote`, `git push`, `git remote`, and `git status` keep the shell prompt visible as a frozen display. Safe, line-oriented output from commands that did not read keyboard input is kept in the transient transcript view; full-screen and genuinely interactive output stays terminal-owned.
+Kward gives each command the terminal, forwards keyboard input, and restores the shell prompt when the command exits. Interactive commands inherit your normal pager configuration, so commands such as `git log` can open `less` in full-screen mode. Kward suppresses Git paging only for noninteractive shell-agent and `capture` executions. It prints the submitted command but no PTY start message or exit-status summary. The line-oriented Git commands `git fetch`, `git ls-remote`, `git push`, `git remote`, and `git status` keep the shell prompt visible as a frozen display. Safe, line-oriented output from commands that did not read keyboard input is kept in the transient transcript view; full-screen and genuinely interactive output stays terminal-owned.
 
 Use `capture` inside `/shell` when you want ordinary, readable output in Kward's transcript area instead of direct terminal control:
 
 ```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.
@@ -139,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.
+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
 
@@ -179,13 +203,14 @@ When several candidates match, repeated Tab presses cycle through them and wrap
 
 ## Built-ins
 
-`ekwsh` handles a small set of commands itself so their state can persist:
+The persistent `/shell` process handles these commands in-session so their state can persist:
 
 | Built-in | What it does |
 | --- | --- |
 | `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. |
@@ -196,81 +221,97 @@ When several candidates match, repeated Tab presses cycle through them and wrap
 
 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 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:
+
+```sh
+alias ll='ls -la'
+alias gs="git status --short"
+export BUNDLE_WITHOUT=production
+export PATH="$HOME/bin:$PATH"
+source ~/.kward/kwsh-aliases
 ```
 
-When `KWARD_CONFIG_PATH` selects another main config file, Kward reads `ekwsh.yml` from the same directory.
+`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.
 
-A practical configuration might look like this:
+The transient shell assistant normally follows the active conversation's model and reasoning effort. Configure it in the main JSON file:
 
-```yaml
-shell: /bin/sh
-timeout_seconds: 300
-max_output_bytes: 1048576
-history_limit: 1000
+```json
+{
+  "shell": {
+    "agent": {
+      "provider": "openrouter",
+      "model": "openai/gpt-5.6-sol",
+      "reasoning_effort": "none"
+    }
+  }
+}
+```
+
+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.
 
-env:
-  FORCE_COLOR: "1"
-  BUNDLE_WITHOUT: "production"
-  RAILS_ENV: "test"
+Override those settings with environment variables:
 
-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"
+```sh
+export KWSH_PROVIDER="openrouter"
+export KWSH_MODE="openai/gpt-5.6-sol"
+export KWSH_REASONING="none"
 ```
 
-### Settings
+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 |
 | --- | --- | --- |
-| `shell` | `/bin/sh` | POSIX-compatible shell used with `-c`. It must be an absolute executable path. |
-| `timeout_seconds` | `300` | Maximum runtime for one captured command. |
-| `max_output_bytes` | `1048576` | Maximum output retained for one captured command. |
+| `shell` | `/bin/sh` | Absolute executable path for the persistent `/shell` process and interactive shell commands. |
+| `timeout_seconds` | `300` | Maximum runtime for one captured or shell-agent command. |
+| `max_output_bytes` | `1048576` | Maximum output retained for one captured or shell-agent command. |
 | `history_limit` | `1000` | Maximum shell-history entries per workspace. |
 
-Invalid or relative `shell` paths fall back to `/bin/sh`. These timeout and output limits apply only to `capture` inside `/shell`, not interactive commands or the separate `/capture` slash command.
+Invalid or relative `shell` paths fall back to `/bin/sh`. These timeout and output limits apply to `capture` inside `/shell` and shell-agent commands, not user-owned interactive commands or the separate `/capture` slash command.
 
 ### 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.
 
-When rbenv is available, Kward adds its shims and bin directories to `PATH` and supplies `RBENV_ROOT` if it was missing. This lets `ruby`, `bundle`, and `./exe/kward` use the selected Ruby without sourcing shell startup files.
+When rbenv is available, Kward adds its shims and bin directories to `PATH` and supplies `RBENV_ROOT` if it was missing before starting `/shell`. The configured interactive shell may also load its normal startup files.
 
 ### Aliases
 
 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.
@@ -281,17 +322,17 @@ Aliases are intentionally simple: they do not expand recursively and are not she
 
 ## Terminal output and safety
 
-Interactive commands write directly to your terminal so full-screen tools can work. When a command does not read keyboard input and emits only line-oriented text plus safe color sequences, Kward mirrors that output into the transient transcript view after the command exits. Other interactive output is not sanitized and may contain terminal control sequences, so run only commands you trust with terminal access.
+Interactive commands write directly to your terminal so full-screen tools can work. When a command does not read keyboard input and emits only line-oriented text plus safe color sequences, Kward mirrors that output into the transient transcript view after the command exits. Other interactive output is not sanitized and may contain terminal control sequences, so run only commands you trust with terminal access. Safe bounded output is included in a shell-agent request only when you explicitly use `?`; it is never sent to the model for ordinary shell commands.
 
 Commands run with `capture` inside `/shell` preserve safe ANSI color and style sequences while removing cursor movement, clear-screen controls, title changes, alternate-screen controls, and similar sequences that could damage the TUI transcript.
 
 ## Limitations
 
-`ekwsh` manages shell-like state, but it is not a persistent login shell or terminal emulator:
+The local `/shell` session is persistent, but it is not a complete terminal emulator or a remote-shell protocol:
 
-- each external command runs separately through the configured shell,
-- there is no job control; a stopped child is terminated rather than leaving the terminal stranded,
-- shell functions do not persist and shell startup files are not sourced,
-- there is no login-shell readline integration,
+- the one-off `!command` and `/capture` workflows do not share `/shell` state,
+- shell state is held by the live process and is not serialized across Kward restarts,
+- a stopped or unresponsive command can still require Ctrl+C or shell-session cleanup,
 - full-screen terminal state is not retained after an interactive command exits,
-- safe line-oriented output may remain in the transient TUI transcript, but full-screen terminal state is not retained and no shell output becomes part of the AI conversation.
+- while an interactive SSH session owns the terminal, Kward cannot safely intercept `?` or provide remote cwd/completion context; shell-agent prompting resumes after SSH exits,
+- safe line-oriented output may remain in the transient TUI transcript; only bounded safe output from an explicit `?` request enters the transient shell-agent context and none of it is added to the normal session history.

data/doc/tabs.md

@@ -39,6 +39,8 @@ A normal session tab can be activated in a linked Git worktree after you have re
 
 ```text
 /tab worktree
+# or
+/worktree
 ```
 
 When enabled, Kward keeps the same tab and transcript but rebuilds its agent against a new worktree. The tab label includes the worktree branch. The worktree is created from `HEAD`, so Kward warns when the original workspace is dirty and leaves those existing changes in the original checkout; it does not copy them automatically. `/tab worktree activate` is an explicit alias for the same action.
@@ -98,6 +100,7 @@ Tabs keep the conversations separate, so context from one tab does not automatic
 | `/tab worktree merge` | Merge the current worktree branch into the branch checked out in its original workspace |
 | `/tab worktree merge abort` | Abort a conflicted worktree merge in the original workspace |
 | `/tab worktree remove` | Remove a clean linked worktree and keep its branch |
+| `/worktree …` | Alias for `/tab worktree …` on the active tab |
 | `/tab move left` | Move the current tab one slot left |
 | `/tab move right` | Move the current tab one slot right |
 | `/tab move <number>` | Move the current tab to a numbered position |

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 that preserves state such as the current directory, environment variables, and aliases between commands. 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
 
@@ -123,7 +123,7 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/git` | review uncommitted changes, stage files, and commit. |
 | `/diff` | open the file changes recorded in the current session. |
 | `/files` | browse project files in a nested tree and open them in the editor. |
-| `/shell` | run stateful workspace commands with interactive PTY support. |
+| `/shell` | run stateful workspace commands with interactive PTY support and ask the shell agent with `?`. |
 | `/capture <command>` | run a bounded one-shot command and retain its output in the transcript. |
 | `/pty <command>` | explicitly hand the terminal to an interactive command; retained for compatibility with existing workflows. |
 | `/settings` | configure models, accounts, memory, interface, tools, context, personalization, and logging. |
@@ -143,6 +143,7 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/tab worktree merge` | merge a clean worktree branch into the branch checked out in its original workspace. |
 | `/tab worktree merge abort` | abort a conflicted worktree merge in the original workspace. |
 | `/tab worktree remove` | remove a clean linked worktree while keeping its branch. |
+| `/worktree …` | alias for `/tab worktree …` on the active tab. |
 | `/session` | open the saved sessions picker or continue a previous session by path. |
 | `/resume` | alias for `/session`. |
 | `/session name <name>` | name or clear the current session. |
@@ -159,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. |
@@ -262,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
 

data/kward.gemspec

@@ -6,16 +6,16 @@ Gem::Specification.new do |spec|
   spec.authors = ["Kai Wood"]
   spec.email = ["kai.wood@icloud.com"]
 
-  spec.summary = "An extendable Ruby CLI coding agent."
-  spec.description = "Kward is a Ruby CLI coding agent with local workspace tools, configurable prompts, web search, sessions, and an experimental JSON-RPC backend."
-  spec.homepage = "https://github.com/kaiwood/kward"
+  spec.summary = "An extensible Ruby coding agent for your terminal."
+  spec.description = "Kward is an extensible Ruby coding agent with workspace tools, resumable sessions, multiple model providers, a local browser UI, and JSON-RPC integrations."
+  spec.homepage = "https://kaiwood.github.io/kward/"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.4"
 
   spec.metadata["rubygems_mfa_required"] = "true"
   spec.metadata["source_code_uri"] = "https://github.com/kaiwood/kward"
   spec.metadata["changelog_uri"] = "https://github.com/kaiwood/kward/blob/main/CHANGELOG.md"
-  spec.metadata["documentation_uri"] = "https://github.com/kaiwood/kward#readme"
+  spec.metadata["documentation_uri"] = "https://kaiwood.github.io/kward/"
   spec.metadata["bug_tracker_uri"] = "https://github.com/kaiwood/kward/issues"
 
   spec.files = Dir.chdir(__dir__) do
@@ -34,4 +34,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "tty-prompt"
   spec.add_dependency "tty-reader"
   spec.add_dependency "tty-screen"
+  spec.add_dependency "unicode-display_width"
 end

data/lib/kward/agent.rb

@@ -28,10 +28,11 @@ module Kward
   # lowest layer that owns the behavior, and use `Agent` only for cross-step turn
   # coordination.
   class Agent
-    def initialize(client:, tool_registry: ToolRegistry.new, conversation: Conversation.new, telemetry_logger: nil, warning_sink: nil, hook_manager: nil, hook_context: nil)
+    def initialize(client:, tool_registry: ToolRegistry.new, conversation: Conversation.new, telemetry_logger: nil, warning_sink: nil, hook_manager: nil, hook_context: nil, strict_provider: false)
       @client = client
       @tool_registry = tool_registry
       @conversation = conversation
+      @strict_provider = strict_provider == true
       @warning_sink = warning_sink
       @telemetry_logger = telemetry_logger || TelemetryLogger.new(warning_sink: warning_sink)
       @hook_manager = hook_manager
@@ -84,6 +85,7 @@ module Kward
       end
       loop do
         cancellation&.raise_if_cancelled!
+        auto_compact_if_needed
         begin
           message = chat(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry) do |event|
             yield event if block_given?
@@ -240,7 +242,8 @@ module Kward
         tools: registry.schemas,
         provider: options[:provider] || @conversation.provider,
         model: options[:model] || @conversation.model,
-        reasoning: options[:reasoning] || @conversation.reasoning_effort
+        reasoning: options[:reasoning] || @conversation.reasoning_effort,
+        provider_required: @strict_provider
       }
       before = run_hook("model_request_before", payload: request)
       request = DeepCopy.merge(request, before.payload) if before.decision.modify?
@@ -260,7 +263,8 @@ module Kward
           steering: steering,
           provider: request[:provider] || request["provider"],
           model: request[:model] || request["model"],
-          reasoning: request[:reasoning] || request["reasoning"]
+          reasoning: request[:reasoning] || request["reasoning"],
+          provider_required: request[:provider_required] || request["provider_required"]
         }
       )
       run_hook("model_response_after_parse", payload: { message: response })