kward 0.80.1 → 0.82.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dceefb01256daa642d6fe1d06d2e332cac1154c93072524b4aa5e98779a26807
-  data.tar.gz: cc8b3c0f226c0b58ea5704a613f84a39d93c5da3ae4d4b9769c891aad2d704d0
+  metadata.gz: e4e40d786a99770eef30a7eb7fec41470d927f9d889160d1c6db9f8fd1ebec39
+  data.tar.gz: 1cfaf680bf9b5ef313e0a0f71a3fb33ea394eb7bc2f5d19c5bfee4c38898ac49
 SHA512:
-  metadata.gz: 4e433643946a04c43fc833edb1a7a550d4333a4184e5c68e5a54b8ab8f24317821587176fc85337a5682fee8caa87cc0f404cf2717490338fc3d9f4988c6e3c4
-  data.tar.gz: 3ea451ab6978d7e726270de4d0e6bc14e1c5a5b6792bb00de551cc137d0e1875579da03437eb2687d8e1d8d93e099ba87a1bfd42fdd18070ddf215fc7ad88ed7
+  metadata.gz: efe8e4a599791fee93d0329c7d0ec4e87c9d45c9ad9f99165d9172d44410ccc83de8014802cc76481d37952e89427b80cac1022a2f7fc17d0bd3c05356d44391
+  data.tar.gz: 9b1ad11cfd582d78d4834cf5b6f168ca8e2f987abe99804678d5e58c2e3000fcff6ebbf30448a71aa1f0ca7a94e9e9585be7b0643d6c88e3ed931e3ab6f3eada

data/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to Kward will be documented in this file.
 
+## [Unreleased]
+
+## [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
+
+- Added `capture <command>` inside `/shell` and `/capture <command>` in the normal composer for bounded, sanitized, transcript-friendly command execution.
+- Added Tab completion for shell commands and paths when the normal interactive prompt input begins with `!`.
+- Added workspace-scoped, digest-aware project skill trust decisions with interactive Allow, Deny, and Review prompts plus `/skills` and `kward skills` management commands.
+
+### Changed
+
+- Displayed packaged plugins with their folder name in the startup plugin list, such as `folder/plugin.rb`.
+- Added a frozen composer display for line-oriented Git PTY commands while preserving the full-terminal handoff for full-screen programs.
+- Changed external `/shell` commands and one-shot `!command` input to use interactive PTY terminal handoff by default, while retaining `pty` and `/pty` for compatibility.
+- Made aliases configured in `ekwsh.yml` available to leading-`!` execution and command completion.
+- Removed interactive PTY start and exit-status messages while retaining the submitted command echo.
+- Changed shell and leading-`!` completion so the candidate list appears in an interactive overlay while repeated Tab presses cycle through candidates in the composer.
+- Removed the `Tab` and `Shift+Tab` reasoning-effort shortcuts so the composer keeps its normal completion behavior.
+
+### Fixed
+
+- Refreshed composer status immediately after reasoning selection and interactive PTY commands, so reasoning levels and Git branch state no longer remain stale until the next input.
+- Prevented composer flicker during interactive prompt, bang-command, and slash-command submission by deferring the submitted composer's repaint to the next command state.
+- Preserved the busy composer while writing normal-turn transcript output so user-submission rendering does not clear it.
+- Bound CSI-u `Ctrl+Q` input to close the read-only `/git diff` viewer, matching the existing raw-key binding and ESC behavior.
+- Routed leading-`!` commands and aliases resolving to `kward edit <filename>` into the integrated editor instead of spawning a nested Kward process.
+- Preserved safe, line-oriented PTY output such as `ls` by redrawing it into the transient transcript when returning from `/shell`, `!command`, or `/pty`, while leaving full-screen and keyboard-driven sessions terminal-owned.
+- Removed legacy `pty` and `capture` mode markers from configured aliases expanded by `!command`, preventing valid aliases such as `glog: pty git log` from failing with status 127.
+- Hardened interactive PTY cleanup, final-output draining, input EOF handling, resize propagation, and stopped-child recovery so terminal handoff reliably returns control to Kward.
+- Normalized binary-tagged UTF-8 shell output before transcript rendering, preventing interactive `!` commands such as `tree` from crashing the composer.
+- Deferred interactive warning output until startup transcript replay completes, keeping Runtime diagnostics visible instead of immediately overwriting them with the replayed transcript.
+
 ## [0.80.1] - 2026-07-27
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.80.1)
+    kward (0.82.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.80.1)
+  kward (0.82.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/README.md

@@ -72,7 +72,7 @@ Work safely:
 Everyday workflows:
 
 - [Sessions](doc/session-management.md): resume, clone, fork, rewind, compact, and navigate saved work.
-- [Interactive composer](doc/composer.md): use multiline input, completion, history, files, reasoning shortcuts, busy input, and images.
+- [Interactive composer](doc/composer.md): use multiline input, completion, history, files, reasoning selection, busy input, and images.
 - [Tabs](doc/tabs.md): keep several conversations open and run work in another tab.
 - [Project files](doc/files.md): browse, search, mention, open, and edit workspace files.
 - [Integrated editor](doc/editor.md): open files from the shell or composer, edit in-place, and choose editor keybindings.
@@ -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/composer.md

@@ -38,7 +38,7 @@ The composer supports familiar line-editing keys:
 | `Alt+D` | Delete the word after the cursor |
 | `Ctrl+U` / `Ctrl+K` | Kill from the cursor to the start or end of the line |
 | `Ctrl+Y` | Yank the most recently killed composer text |
-| `Ctrl+L` | Redraw the terminal UI |
+| `Ctrl+L` | Redraw the terminal UI and remove transient current-view output |
 | `Ctrl+D` | Delete at the cursor, or exit when the composer is empty |
 
 These are composer bindings. The integrated editor, shell, Git view, file browser, and plugin interfaces have their own keymaps.
@@ -115,15 +115,12 @@ History survives restarts. It contains submitted prompt text and successful `$pa
 
 ## Change reasoning effort
 
-When no slash or file picker is open, Tab cycles forward through reasoning efforts supported by the current model. Shift+Tab cycles backward. The selection wraps and is persisted for later turns.
+The composer status line shows the current provider, model, and reasoning effort. Use `/reasoning` or `/model` to choose the reasoning effort explicitly.
 
-The composer status line shows the current provider, model, and reasoning effort. Use `/reasoning` or `/model` when you prefer the explicit picker.
-
-Tab is context-sensitive:
+Tab follows the normal completion behavior:
 
 - in slash or `@path` completion, it accepts the selected match,
 - in `$path` completion, it opens the selected file,
-- otherwise, it changes reasoning effort,
 - in other modal interfaces, it follows that interface's own controls.
 
 ## Work with tabs
@@ -189,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
 
@@ -214,6 +211,6 @@ If rendering becomes corrupted after resize or after an external program writes
 /redraw
 ```
 
-You can also press `Ctrl+L`. If a shortcut never reaches Kward, prefer its slash-command equivalent or change `composer.tab_keybindings` in `/settings`.
+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`.
 
-For full-screen interactive programs such as Vim or `less`, use `/pty <command>` or `pty <command>` inside `/shell` so the program temporarily owns the terminal instead of fighting the composer.
+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. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, sanitized transcript output.

data/doc/configuration.md

@@ -81,7 +81,17 @@ long-polling adapter and setup instructions.
 
 ### Project skills
 
-Kward loads user-level skills but skips project-level skills by default. Enable them only for repositories you trust, either through `/settings` → Tools & Search → Trust project skills or with:
+Kward loads user-level skills automatically. Project-level skills require an explicit workspace trust decision. In the interactive TUI, Kward asks when a new or changed skill appears; use `/skills status`, `/skills trust`, `/skills untrust`, and `/new` to inspect, manage, and activate decisions.
+
+For non-interactive use:
+
+```bash
+kward --working-directory /path/to/project skills status
+kward --working-directory /path/to/project skills review
+kward --working-directory /path/to/project skills trust
+```
+
+Trust records are stored in `~/.kward/trusted_project_skills.json`. The legacy global override remains available:
 
 ```json
 {
@@ -176,7 +186,7 @@ aliases:
 
 `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.
 
-`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Built-in `ekwsh` commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, `pty`, and `exit` take precedence over aliases. Run `alias` inside `ekwsh` to list configured aliases. Aliases are also included in command-name Tab completion.
+`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.
 
 ## Provider and model settings
 
@@ -355,7 +365,7 @@ The busy composer shows a short Ctrl+C cancellation hint by default. To hide it:
 
 This only hides the hint text; Ctrl+C still stops the current running response.
 
-In the normal composer prompt, `Tab` cycles forward through the current model's reasoning efforts and `Shift+Tab` cycles backward. The shortcuts wrap around and update the persisted reasoning setting; file and slash-command completion overlays keep their existing `Tab` completion behavior.
+In the normal composer prompt, choose reasoning effort with `/reasoning` or `/model`; `Tab` keeps its normal file and slash-command completion behavior.
 
 `tab_keybindings` controls how the composer handles tab navigation shortcuts:
 

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
 
@@ -40,6 +40,8 @@ Outside Git, Kward scans the workspace directory and skips common noisy director
 | `/` | Start search |
 | `Backspace` | Delete the last search character |
 | `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).
@@ -92,6 +94,10 @@ Kward remembers the expanded folders and selected path for each workspace. The n
 
 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.

data/doc/permissions.md

@@ -175,7 +175,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`, `/shell`, and `/pty`—are treated as your actions and are outside this first policy scope;
+- direct commands that you type yourself—`!command`, `/capture`, `/shell`, and `/pty`—are treated as your actions and are outside this first policy scope;
 - 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,107 @@
 # 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:
 
-   ```bash
-   bundle exec rake docs:serve
-   ```
+- 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.
 
-   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 validation succeeds, it:
 
-6. If you want to run the documentation check separately:
+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`.
 
-   ```bash
-   bundle exec rake docs:build
-   bundle exec rake docs:check
-   ```
+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.
 
-   `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.
+## What the release workflow does
 
-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`.
+A pushed `v*` tag starts `.github/workflows/release.yml`. The workflow:
 
-8. Install the built gem locally and smoke test the `kward` executable in a clean workspace.
+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.
+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.
 
-## Tag and publish
+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.
 
-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

@@ -76,6 +76,7 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
 - `memory`: opt-in structured memory support, interactive prompt injection only, JSON/JSONL local storage, and dedicated `memory/*` methods.
 - `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns.
 - `skillCapture`: capture a reviewed personal `SKILL.md` from any saved session’s active branch through `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`.
+- `projectSkillTrust`: explicitly unsupported over RPC. RPC clients cannot answer the interactive Allow/Deny/Review decision, so project skills remain skipped unless the global `skills.trust_project` override is enabled.
 - `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.
@@ -83,7 +84,7 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
 - `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` is the local embedded TUI 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.
 - `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

@@ -77,9 +77,9 @@ worker. The strict agent also disables configured MCP clients and lifecycle
 hooks because they run in the Kward host process rather than inside the command
 sandbox.
 
-This does not contain the interactive `/shell`, `!command`, or `/pty` features;
-those are user-directed host-process operations. Generic model-requested shell
-commands still cannot write Git metadata. Active worktree tabs additionally
+This does not contain the user-directed `/shell`, `!command`, `/capture`, or
+`/pty` features; those are user-directed host-process operations. Generic
+model-requested shell commands still cannot write Git metadata. Active worktree tabs additionally
 expose a narrow `git_commit` tool for explicit agent-requested commits; it runs
 through the trusted host-side Git workflow rather than widening the shell
 sandbox. The interactive `/git` flow remains available for manual review and
@@ -111,7 +111,7 @@ 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`, or `/pty`.
+- MCP servers, lifecycle hooks, `/shell`, `!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

@@ -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`, `/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`, `/shell`, or `/pty`.
+- 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`.
+- 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.
 
@@ -67,7 +68,7 @@ You can disable the file boundary with `tools.workspace_guardrails: false`, but
 
 A worktree-backed tab uses its linked worktree as the active workspace and requires an OS-enforced `workspace_write` command sandbox. If the platform cannot provide filesystem enforcement, Kward refuses to activate the worktree rather than running model-requested shell commands unrestricted.
 
-The strict worktree agent disables configured MCP clients and lifecycle hooks for that tab because those extensions run outside the command-worker sandbox. The interactive `/shell`, `!command`, and `/pty` features remain host-process features and are not covered by the worktree boundary. Use them only when you intentionally want to run a user-directed command outside the model command sandbox.
+The strict worktree agent disables configured MCP clients and lifecycle hooks for that tab because those extensions run outside the command-worker sandbox. The interactive `/shell`, `!command`, `/capture`, and `/pty` features remain host-process features and are not covered by the worktree boundary. Use them only when you intentionally want to run a user-directed command outside the model command sandbox.
 
 Git worktrees share repository metadata. Kward keeps Git metadata protection enabled for generic model-requested commands. Active worktree tabs provide a narrow host-side `git_commit` tool for explicit agent commits; the interactive `/git` flow remains the manual review, staging, and commit path.
 
@@ -95,13 +96,9 @@ A repository-level `AGENTS.md` is guidance for the model, not executable code. K
 
 ### Project skills
 
-Project skills under `.kward/skills/` and `.agents/skills/` are skipped by default. Enable them only after reviewing their `SKILL.md` instructions and supporting files:
+Project skills under `.kward/skills/` and `.agents/skills/` require an explicit trust decision. In the interactive TUI, Kward asks for `Allow`, `Deny`, or `Review` when a new or changed skill appears. Review shows bounded `SKILL.md` content and lists referenced resources without executing them. Decisions are stored per canonical workspace and skill digest in `~/.kward/trusted_project_skills.json`, so changes require another review.
 
-```text
-/settings → Tools & Search → Trust project skills
-```
-
-This setting trusts project skills generally; it is not a per-repository digest. A skill's `allowed-tools` metadata does not grant permissions or constrain tools in Kward.
+Use `/skills status`, `/skills trust`, `/skills untrust`, or the non-interactive `kward skills` command to manage the records. The legacy `skills.trust_project` setting remains a global override. A skill's `allowed-tools` metadata does not grant permissions or constrain tools in Kward.
 
 ### Workspace hooks