kward 0.81.0 → 0.83.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2033aa9b07468c6668842a3b0ba51ef73cb0c1c58db95927c1159668129e345
-  data.tar.gz: 0f7c86a02ccf5e76f01adf3a8d654b3bd559ef27c93f6479dfd6724401427435
+  metadata.gz: 678c9e9bb188e6c3d065dfde6b97c9ec5c31b29b178b40d69b0397b5200eb2a8
+  data.tar.gz: 3e09cb3d11ff6018ecc75e3eb31e8745e72e534dba7a4c3711a488451d353fcc
 SHA512:
-  metadata.gz: 934c63dbcde19c9eba5dbdfb843a5cbb82a873d73371746d3db19c5698c27aa53ecef3820bb7099a928e077f05d04178190e4ddafef3ff8ed9e82aa7233c2d75
-  data.tar.gz: 05ac5a0a3a695f9b49c56059915e642511c85f0dcaa68e406f0b470763b589497a92950416a0f7eddb2a69b304c9b7f6bcef3bcbea49cedd8032b06871c3cfba
+  metadata.gz: 7f4247a32300deff0906c95c10d7312aa6303108956596f16d9f2c6d2d4fc444b5ef377751f47dbd2157b041710d855c44a981a1a22f8a562c79203afe8b65ed
+  data.tar.gz: d93d09126d221c05d7ef0e931f46ccfaa4a84450e6eb5695dbea653d8b9de99bb27bc7fb070b323c74160477fd328f0be3cd972d544b45e3ea90ffbeb79cb087

data/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.83.0] - 2026-08-28
+
+### Added
+
+- Added `?` shell prompts for transient, context-aware assistance inside `/shell`, including shared shell-state commands and prepare-without-execute command drafts.
+- Added `Ctrl+.` in Modern editor mode to open an in-editor prompt line for communicating with the dedicated editor agent.
+- Added Vibe `:prompt <instruction>` support, allowing the agent to inspect and replace the active in-memory editor buffer without saving it automatically.
+- Added current-buffer word completion to the integrated editor, with repeated Tab presses cycling nearby matches and existing smart indentation retained when no match exists.
+- Added Claude Opus 5 to the Anthropic model picker with its 1M context window and high-reasoning metadata.
+- Added an `i` toggle to the `/files` browser for showing Git-ignored files, which remain hidden by default.
+
+### Changed
+
+- `/shell` now keeps one persistent local shell process per tab so shell variables, functions, aliases, and directory changes are shared by user and agent commands.
+- Shell-agent turns use a transient per-tab context and receive only bounded, sanitized output after an explicit `?` request; ordinary shell output remains outside model context.
+- Shell-agent transcript output is now retained as bounded, tab-local runtime state so it survives tab switches without entering session history.
+- Vibe editor-agent turns now use an isolated, configurable model/reasoning context, remain visible with a status-line spinner, and stay out of normal chat transcripts and session history.
+- Removed the obsolete GPT-5.6 Luna Responses Lite compatibility workaround so Luna requests retain Kward's identity and standard Codex payload.
+
+### Fixed
+
+- Made persistent shell command cancellation and timeouts recover by restarting an unresponsive embedded shell, and stabilized raw-input coverage across platforms.
+- Restored full-screen Git pagers and immediate key/Ctrl+C forwarding for interactive `/shell` commands by removing Kward's ambient `GIT_PAGER=cat` default and putting host input in raw mode during persistent-shell handoff, while keeping paging suppressed for captured and shell-agent commands.
+- Fixed Claude subscription OAuth authorization and token-exchange requests by removing unsupported subscription scopes and the nonstandard `code` query parameter, and by forwarding the OAuth state to the token endpoint.
+- Installed and enabled Bubblewrap during release verification so Linux worktree tests use the same sandbox setup as normal CI, added manual recovery for existing release tags, and made publication wait for and attach the canonical RubyGems artifact after trusted-publishing attestation.
+- Fixed automatic context compaction so Codex response items are included in token estimates and long tool-call turns are checked before each model request.
+
+## [0.82.0] - 2026-08-23
+
+### Added
+
+- Added `script/release` for validated, one-command release preparation from an argument or standard input, including changelog/version updates, preflight checks, an annotated tag, and an atomic push.
+- Added a tag-triggered GitHub Actions release workflow using RubyGems trusted publishing, published-artifact checksum verification, changelog-based GitHub Releases, and safe reruns after partial publication.
+- Added `+` and `-` controls for resizing inline `/files` image previews within the available overlay space.
+- Added inline read-only previews for PNG, JPEG, GIF, and WebP files opened from `/files` in terminals that support Kitty or iTerm2 image sequences, with local conversion for Kitty-compatible terminals when needed.
+
+### Changed
+
+- Excluded GitHub workflow and local release-script files from packaged gems and added explicit release metadata and package-content checks.
+- Changed interactive PTY handoff to render conservative line/progress output above a frozen composer, with a permanent switch to exclusive full-terminal passthrough when the child emits screen-oriented or unknown controls.
+- Kept safe, normalized shell output as explicit tab-local transient state so completed `/shell` and `!command` output can be reconstructed after tab switches without entering session history or model context.
+
+### Fixed
+
+- Made the test environment explicitly disable terminal color and made unified diff-viewer tests select that mode explicitly, keeping release preflight assertions deterministic across terminal capabilities and widths.
+- Kept `/files` image previews bounded within a fully cleared, bordered file-list overlay above the visible composer and preserved their aspect ratio in Kitty-compatible terminals.
+- Fixed inline image protocol detection and viewer handoff for Ghostty and other Kitty-compatible terminals by retrying inconclusive probes, honoring recognized Kitty hints, suppressing Kitty acknowledgements, and using valid, chunked graphics sequences.
+- Kept synchronized-output updates such as Homebrew downloads in the inline PTY region instead of resetting the cursor through an unnecessary exclusive handoff.
+- Retained the final visible state of carriage-return and horizontal-cursor progress output from commands such as `git push` and Homebrew when reconstructing the transcript after PTY handback.
+- Cached rebuildable session-list summaries so opening `/session` no longer reparses every unchanged conversation log, while retaining automatic fallback for existing, changed, or corrupt session data.
+- Refreshed composer status immediately after model runtime changes and `/git` returns, so selected model details and Git dirty-state color do not remain stale until another input.
+- Kept echoed passwords, OTPs, and other child input out of transient tab state by stopping safe PTY output retention before the first forwarded input byte.
+- Reconstructed safe transient shell output as part of the PTY ownership handback frame, avoiding an extra clear and redraw after commands such as `ls`.
+- Preserved the active `/shell` prompt and composer when Ctrl+L clears transient shell output, and avoided a redundant preliminary redraw.
+- Reconstructed the complete Kward screen after interactive PTY handoff, including failure paths, instead of relying on the child process cursor position.
+
 ## [0.81.0] - 2026-08-20
 
 ### Added
@@ -62,6 +118,7 @@ All notable changes to Kward will be documented in this file.
 - Added Git worktree bindings for normal interactive session tabs. `/tab worktree` can move a tab into a strict linked-worktree workspace after research, preserve its transcript, warn about dirty origin changes, and keep the branch available when explicitly detached.
 - Added the active worktree `git_commit` model tool, allowing explicitly requested agent commits through the trusted host-side Git workflow without widening the shell sandbox.
 - Added `/tab worktree merge` for explicitly merging a clean worktree branch into the branch checked out in its original workspace, plus `/tab worktree merge abort` for conflicted merges.
+- Added `/worktree` as a concise alias for `/tab worktree` on the active tab.
 - Added `j`/`k` keyboard navigation to the `/files` project browser.
 - Added `h`/`l` keyboard navigation for collapsing and expanding `/files` directories.
 - Added `j`/`k` keyboard navigation to the `/git` changed-file overlay.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.81.0)
+    kward (0.83.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -146,7 +146,7 @@ CHECKSUMS
   html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
   io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
   json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  kward (0.81.0)
+  kward (0.83.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/README.md

@@ -92,7 +92,7 @@ Extend and integrate:
 - [Plugins](doc/plugins.md): trusted Ruby plugins for commands, footer UI, prompt context, transcript events, and RPC clients.
 - [Lifecycle hooks](doc/lifecycle-hooks.md): deterministic runtime hooks for policy, approvals, automation, and command-hook integrations.
 - [RPC protocol](doc/rpc.md): JSON-RPC backend mode for trusted local UI clients.
-- [Releasing](doc/releasing.md): release checklist for RubyGems publishing.
+- [Releasing](doc/releasing.md): prepare a version and publish it through RubyGems and GitHub Releases.
 
 Reference guides:
 

data/Rakefile

@@ -1,5 +1,7 @@
+require "bundler/gem_tasks"
 require "fileutils"
 require "html-proofer"
+require "open3"
 require "rdoc/task"
 require "rubygems/package"
 require "webrick"
@@ -33,6 +35,36 @@ def packaged_gem_files(gem_name)
   gem.spec.files.sort
 end
 
+def verify_release_metadata
+  version = Kward::VERSION
+  tag = "v#{version}"
+  changelog = File.read("CHANGELOG.md")
+  abort("CHANGELOG.md is missing a [#{version}] release heading") unless changelog.match?(/^## \[#{Regexp.escape(version)}\] - \d{4}-\d{2}-\d{2}$/)
+
+  if ENV["GITHUB_REF_TYPE"] == "tag" && ENV["GITHUB_REF_NAME"] != tag
+    abort("GitHub tag #{ENV["GITHUB_REF_NAME"]} does not match gem version #{version}")
+  end
+
+  tag_commit, tag_status = Open3.capture2e("git", "rev-parse", "--verify", "#{tag}^{commit}")
+  return unless tag_status.success?
+
+  head_commit = `git rev-parse HEAD`.strip
+  abort("Tag #{tag} does not point at HEAD") unless tag_commit.strip == head_commit
+end
+
+def verify_packaged_gem(gem_name)
+  files = packaged_gem_files(gem_name)
+  required = ["exe/kward", "lib/kward/version.rb"]
+  missing = required - files
+  abort("Packaged gem is missing: #{missing.join(", ")}") unless missing.empty?
+
+  forbidden_prefixes = [".github/", "script/", "test/", "plan/"]
+  forbidden = files.select { |file| forbidden_prefixes.any? { |prefix| file.start_with?(prefix) } }
+  abort("Packaged gem includes development files: #{forbidden.join(", ")}") unless forbidden.empty?
+
+  files
+end
+
 def rewrite_yard_markdown_links
   guide_names = Dir.glob("doc/*.md").map { |path| File.basename(path, ".md") }
 
@@ -75,15 +107,23 @@ YARD::Rake::YardocTask.new do |yard|
 end
 
 namespace :release do
+  desc "Verify the version, changelog, and release tag agree"
+  task :verify do
+    verify_release_metadata
+  end
+
   desc "Run release checks and build a local gem"
-  task preflight: [:test, "docs:check"] do
-    gem_name = "kward-#{Kward::VERSION}.gem"
+  task preflight: ["release:verify", :test, "docs:check"] do
+    gem_name = File.join("pkg", "kward-#{Kward::VERSION}.gem")
     FileUtils.rm_f(gem_name)
-    sh "gem", "build", "kward.gemspec"
-    puts packaged_gem_files(gem_name)
+    Rake::Task["build"].invoke
+    puts verify_packaged_gem(gem_name)
   end
 end
 
+Rake::Task["release:source_control_push"].enhance(["release:verify"])
+Rake::Task["release:rubygem_push"].enhance(["release:verify"])
+
 namespace :docs do
   desc "Serve the built YARD documentation site locally and rebuild on changes"
   task serve: :build do

data/doc/agent-tools.md

@@ -15,6 +15,7 @@ Tools also enforce important boundaries:
 | Category | Tools | Guide |
 | --- | --- | --- |
 | Workspace tools | `list_directory`, `read_file`, `context_for_task`, `context_budget_stats`, `summarize_file_structure`, `write_file`, `edit_file`, `run_shell_command` | [Workspace tools](workspace-tools.md) |
+| Shell prompt tools | `run_shell_command`, `prepare_shell_command` (available only to the transient `?` shell assistant) | [Embedded shell](shell.md) |
 | Web tools | `web_search`, `fetch_content`, `fetch_raw` | [Web search](web-search.md) |
 | Code search | `code_search` | [Code search](code-search.md) |
 | Context and interaction tools | `read_skill`, `retrieve_tool_output`, `ask_user_question` | [Context tools](context-tools.md) |

data/doc/composer.md

@@ -186,7 +186,7 @@ Example:
 
 If the cursor is at the start of an otherwise empty draft, Backspace removes the most recently added pending attachment. Submitting the draft clears its pending attachments.
 
-The active model must support image input. iTerm2 and Kitty-compatible terminals can render submitted images inline; other terminals still show attachment badges and send the image to the model without an inline preview.
+The active model must support image input. iTerm2 and Kitty-compatible terminals can render submitted images inline; Kward uses active Kitty capability detection when running on a real TTY and falls back to conservative terminal hints otherwise. Other terminals still show attachment badges and send the image to the model without an inline preview.
 
 ## Understand composer status
 
@@ -213,4 +213,4 @@ If rendering becomes corrupted after resize or after an external program writes
 
 You can also press `Ctrl+L`; it rebuilds the durable current-tab view without deleting the conversation transcript, removing transient shell output. If a shortcut never reaches Kward, prefer its slash-command equivalent or change `composer.tab_keybindings` in `/settings`.
 
-External commands inside `/shell` and one-shot `!command` input receive an interactive PTY by default, so full-screen programs such as Vim or `less` temporarily own the terminal. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer when output should remain in Kward's transcript instead.
+External commands inside `/shell` and one-shot `!command` input receive an interactive PTY by default. They begin inline above a frozen composer, then switch to full-terminal passthrough if they emit screen-oriented or unknown terminal controls; full-screen programs such as Vim or `less` can therefore temporarily own the terminal. While Kward owns the shell composer, a leading `?` asks the transient shell assistant; it receives only bounded, sanitized output from the latest command. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, sanitized transcript output.

data/doc/configuration.md

@@ -184,9 +184,9 @@ aliases:
   gd: "git diff --color=always"
 ```
 
-`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.
+`env` values are applied when shell mode starts, after Kward's conservative color defaults. `/shell` keeps one persistent local interactive shell process per tab. Keys must look like environment variable names (`A_Z`, digits after the first character, and underscores); invalid keys are ignored. Values are converted to strings.
 
-`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.
+`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Configured aliases are available both inside `/shell` and after the normal composer's `!` prefix, including command-name Tab completion. Built-in shell commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. Prefix a submitted line with `?` inside `/shell` to ask the transient shell assistant about the current command output or state. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `ekwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current `/shell` session and are not available to `!command` input.
 
 ## Provider and model settings
 
@@ -248,7 +248,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 +393,21 @@ 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": {
+      "model": "gpt-5.5",
+      "reasoning_effort": "medium"
+    }
+  }
+}
+```
+
+These settings use the active tab's provider. If either value is omitted, Kward falls back to the active tab's value and then the client default. Editor-agent prompts and tool activity are kept out of the normal transcript and session history; the editor remains visible with a spinner while the transient turn runs.
+
 The integrated Git and session diff viewers support unified and side-by-side layouts:
 
 ```json

data/doc/editor.md

@@ -43,7 +43,7 @@ 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, `@` 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.
 
 For an unsaved buffer, open a scratchpad:
 
@@ -85,21 +85,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 +127,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 +165,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 +202,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 +243,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                   |
@@ -370,7 +380,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               |

data/doc/files.md

@@ -12,9 +12,9 @@ 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.
+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.
 
-When you quit the editor, Kward returns to the file browser at the same position so you can keep browsing nearby files.
+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.
 
 ## What appears in the browser
 
@@ -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,10 @@ 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 |
+| `i` | Show or hide Git-ignored files |
 | `Esc` | Leave search; 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 |
 
 Directories use `▸` and `▾` markers to show collapsed and expanded state. Files are shown under their containing directory with indentation. File-type icons are off by default; users with a compatible Nerd Font can enable them under Interface in `/settings`. See [Configuration](configuration.md#project-browser-icons).
@@ -88,13 +91,17 @@ 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.
 
+## Image previews
+
+Image previews are read-only and replace the file-list overlay while leaving the prompt composer and tabs visible. Press `+` or `-` to make the image larger or smaller within the available overlay space. Press `Esc` or `Q` to return to `/files`. Kward probes Kitty-compatible terminals when it has a real interactive TTY, uses recognized terminal identity hints when probing is inconclusive, and retries transient detection failures. Terminals without reachable Kitty or iTerm2 inline-image support keep the selection in the browser and show a status message instead of opening binary data in the text editor. Kitty-compatible terminals use PNG data; JPEG, GIF, and WebP previews require an available local image converter.
+
 ## Notes and limitations
 
 - `/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.
+- 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/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/releasing.md

@@ -1,74 +1,115 @@
 # Releasing Kward
 
-## Before you begin
+Kward releases are prepared locally and published by GitHub Actions. The local command updates the version and changelog, runs every release check, creates the release commit and annotated tag, then pushes both atomically. The tag-triggered workflow publishes the gem to RubyGems.org and creates a GitHub Release with the same gem attached.
 
-Kward requires Ruby >= 3.4 (`spec.required_ruby_version` in `kward.gemspec`). If you develop with a newer Ruby, verify tests pass against the minimum supported version before releasing.
+## One-time setup
 
-## Prepare the release
+Kward publishes through [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/), so the repository does not need a long-lived RubyGems API key.
 
-Before publishing:
+Before the first automated release:
 
-1. Update `CHANGELOG.md` for the version. Move `[Unreleased]` entries under a new version heading.
-2. Update `Kward::VERSION` in `lib/kward/version.rb`.
-3. Run the release preflight:
+1. In the GitHub repository, create an Actions environment named `release`. Add required reviewers if releases should have a manual approval gate.
+2. On the RubyGems.org page for the `kward` gem, add a trusted publisher with:
+   - Repository owner: `kaiwood`
+   - Repository name: `kward`
+   - Workflow filename: `release.yml`
+   - Environment: `release`
+3. Confirm GitHub Actions can write repository contents. The release job requests only `contents: write` for the GitHub Release and `id-token: write` for RubyGems OIDC authentication.
 
-   ```bash
-   bundle exec rake release:preflight
-   ```
+GitHub Packages is intentionally not used. RubyGems.org remains the canonical package registry; the built `.gem` is also attached to each GitHub Release.
 
-   This runs the full test suite, builds and checks the generated docs, builds a local gem, and prints the packaged file list for review.
+## Prepare a release
 
-4. Run focused tests for any areas you changed during the release prep itself (docs, config, etc.):
+Keep notable changes under the appropriate `Added`, `Changed`, `Fixed`, or `Removed` heading in the `[Unreleased]` section of `CHANGELOG.md`. Do not add the version heading by hand.
 
-   ```bash
-   ruby -Itest test/test_cli.rb
-   ```
+Before releasing, make sure `main` is clean, pushed, and synchronized with `origin/main`. Then run:
 
-5. Preview docs locally if you changed documentation or public APIs:
+```bash
+script/release 0.82.0
+```
+
+The version can also come from standard input:
+
+```bash
+printf '0.82.0\n' | script/release
+```
+
+The command fails closed unless:
+
+- The version is a valid RubyGems version newer than `Kward::VERSION`.
+- The working tree is clean and checked out on `main`.
+- Local `main` exactly matches `origin/main`.
+- The tag does not exist locally or on GitHub.
+- RubyGems.org does not already contain the version.
+- `[Unreleased]` contains at least one changelog entry.
+
+If validation succeeds, it:
 
-   ```bash
-   bundle exec rake docs:serve
-   ```
+1. Updates `Kward::VERSION` in `lib/kward/version.rb`.
+2. Refreshes `Gemfile.lock` with `bundle lock --local`.
+3. Moves the unreleased changelog entries under a dated version heading.
+4. Runs `bundle exec rake release:preflight`.
+5. Commits the three release files as `Release v0.82.0`.
+6. Creates an annotated `v0.82.0` tag.
+7. Atomically pushes `main` and the tag to `origin`.
 
-   The preview builds `_yardoc/`, serves it with WEBrick, and rebuilds in a fresh process when documentation sources, library code, or templates change. Refresh your browser after rebuilds.
+If preparation fails before the commit, the command restores the version, lockfile, and changelog. If tagging or pushing fails after the commit, it leaves the release commit in place and prints the failed command; inspect the repository before retrying rather than creating another release commit.
 
-6. If you want to run the documentation check separately:
+## What the release workflow does
 
-   ```bash
-   bundle exec rake docs:build
-   bundle exec rake docs:check
-   ```
+A pushed `v*` tag starts `.github/workflows/release.yml`. The workflow:
 
-   `docs:check` validates generated internal links, images, and scripts. Pushes to `main` deploy the generated YARD site to GitHub Pages. You can also run `bundle exec rake rdoc` to generate a separate RDoc site as a sanity check, but it is not deployed.
+1. Checks that the tag, gem version, and changelog heading agree.
+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. 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.
 
-7. Inspect the packaged files printed by `release:preflight` and confirm no local config, sessions, logs, or secrets are included. The gemspec uses `git ls-files` and excludes `test/`, `plan/`, `.ruby-lsp/`, `.gitignore`, and `AGENTS.md`.
+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.
 
-8. Install the built gem locally and smoke test the `kward` executable in a clean workspace.
+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:
 
-## Tag and publish
+```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.
 
-Commit the version bump and create a Git tag:
+Follow the run from the repository's **Actions → Release** page. Installation can be checked after publication with:
 
 ```bash
-git commit -am "Bump to VERSION"
-git tag vVERSION
-git push && git push --tags
+gem install kward --version 0.82.0
+kward --version
 ```
 
-Publish the built gem from the release checkout:
+## Run checks without releasing
+
+After updating to an unreleased version, run the complete preflight directly with:
+
+```bash
+bundle exec rake release:preflight
+```
+
+This verifies release metadata, runs tests, builds and checks the generated documentation, builds `pkg/kward-VERSION.gem`, rejects development-only packaged files, and prints the final gem contents.
+
+Individual checks remain available:
 
 ```bash
-gem push kward-VERSION.gem
+bundle exec rake test
+bundle exec rake docs:check
+bundle exec rake release:verify
+bundle exec rake build
 ```
 
-RubyGems MFA is required for publishing. Prefer RubyGems trusted publishing for automated releases if CI publishing is added later, so long-lived API keys do not need to be stored in CI secrets.
+Use `bundle exec rake docs:serve` to preview documentation locally.
 
 ## If you need to yank a release
 
-If a published gem has a serious problem, you can yank it within 24 hours of pushing:
+If a published gem has a serious problem, yank it within 24 hours of pushing:
 
 ```bash
 gem yank kward --version VERSION
 ```
 
-Yanking removes the gem from the default install index but does not delete the version entirely. After yanking, fix the issue, bump the version, and release again.
+Yanking removes the gem from the default install index but does not delete the version. Fix the issue, choose a new version, and run the normal release command again. Never move or reuse a published version tag.

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