kward 0.83.0 → 0.85.0

data/doc/transports.md

@@ -104,6 +104,13 @@ Plugin-chat drivers may accept a `context:` keyword on `submit`. Transport turns
 provide the authenticated actor there. Existing drivers that do not accept the
 keyword continue to work, but cannot use actor-specific context.
 
+The plugin-chat factory host reports `surface: :transport`, the stable chat type
+ID and scope key, immutable plugin configuration, scoped durable storage, secret
+lookup, logging, declared chat capabilities, and managed cleanup. Storage is
+isolated by plugin, chat type, and external conversation scope. Versioned chat
+contracts also reject attachments not declared by that chat type before calling
+the driver.
+
 Plugin-chat transport IDs, turn events, transcript storage, and authorization
 remain separate from normal workspace sessions. A plugin's `singleton: :global`
 setting also means that all transport conversations share that one plugin
@@ -119,6 +126,14 @@ API.
 Transports that cannot support interactive approvals must use an explicit
 configured fallback policy; they must not leave an agent turn waiting forever.
 
+Structured plugin UI requests use the same transport-neutral interaction path.
+Plugin `question`, `select`, `confirm`, and `input` calls arrive with matching
+interaction kinds, prompts, choices, and metadata, and answers are routed back to the
+waiting plugin handler. An adapter may support only a subset, but it must cancel
+or answer unsupported requests rather than leaving the turn blocked. Plugin
+notifications and progress remain local to the RPC/TUI UI bridge for now and
+are not transport interaction requests.
+
 ## Storage and routing
 
 Transport plugins receive namespaced durable storage for state such as:

data/doc/troubleshooting.md

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

data/doc/usage.md

@@ -66,7 +66,7 @@ Inside interactive mode, ask Kward to run a command:
 Run the focused test for the CLI status command.
 ```
 
-Or run an interactive PTY command yourself from the composer by prefixing it with `!`. Aliases configured in `ekwsh.yml` are expanded here too:
+Or run an interactive PTY command yourself from the composer by prefixing it with `!`. Aliases configured in `kwshrc` are expanded here too:
 
 ```text
 !git status --short
@@ -78,7 +78,7 @@ For several commands, enter the embedded Kward shell:
 /shell
 ```
 
-`/shell` opens `ekwsh`, a Kward-native command mode with one persistent local shell process. It preserves state such as the current directory, environment variables, functions, and aliases between commands. Prefix a line with `?` inside `/shell` to ask a transient shell assistant about the latest output, execute an explicit state change, or prepare a command without running it. External commands receive an interactive PTY by default, so `git log`, `less`, Vim, SSH, and REPLs work without a prefix. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, transcript-friendly output. See [Embedded shell](shell.md) for built-ins, completion, configuration, ANSI handling, PTY passthrough, and limitations.
+`/shell` opens `kwsh`, a Kward-native command mode with one persistent local shell process. It preserves state such as the current directory, environment variables, functions, and aliases between commands. Prefix a line with `?` inside `/shell` to ask a transient shell assistant about the latest output, execute an explicit state change, or prepare a command without running it. External commands receive an interactive PTY by default, so `git log`, `less`, Vim, SSH, and REPLs work without a prefix. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, transcript-friendly output. See [Embedded shell](shell.md) for built-ins, completion, configuration, ANSI handling, PTY passthrough, and limitations.
 
 ## Shell commands
 
@@ -136,11 +136,14 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/tab close` | close the active tab. |
 | `/tab new` | open a new tab. |
 | `/tab name <label>` | rename the active tab label. |
+| `/name <name>` | rename the active session and tab together; available while the tab's agent is running. |
 | `/tab worktree` | create or activate the active session tab's linked Git worktree. |
 | `/tab worktree activate` | explicitly create or activate the active session tab's linked Git worktree. |
 | `/tab worktree detach` | return to the original workspace while keeping the linked worktree and branch. |
 | `/tab worktree status` | inspect the active tab's worktree binding and changes. |
 | `/tab worktree merge` | merge a clean worktree branch into the branch checked out in its original workspace. |
+| `/tab worktree merge resolve` | ask the agent to resolve an in-progress merge in the original workspace from the same tab. |
+| `/tab worktree merge continue` | stage resolutions and complete an in-progress merge after confirmation. |
 | `/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. |
@@ -160,7 +163,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. |
@@ -191,7 +194,7 @@ Use sessions when work spans more than one terminal sitting, or when you want to
 Typical flow:
 
 ```text
-/rename oauth cleanup
+/name oauth cleanup
 # work with Kward
 /export oauth-notes.md
 /exit
@@ -263,13 +266,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/doc/workspace-tools.md

@@ -21,6 +21,15 @@ Important behavior:
 - Edits use exact text replacement, so accidental partial or fuzzy changes fail instead of guessing.
 - With sandboxing off (the default), shell commands run as your operating-system user from the workspace. Enable [command sandboxing](sandboxing.md) to apply an OS boundary to model-requested `run_shell_command` workers. Command output is capped at 128 KB.
 
+### Worktree targets
+
+In an active linked-worktree tab, `list_directory`, `read_file`, `write_file`, `edit_file`, `run_shell_command`, `summarize_file_structure`, and `context_for_task` also advertise an optional `target` argument:
+
+- `active` is the default linked worktree.
+- `origin` is the tab's verified original repository worktree.
+
+Kward supplies this fixed role map from the tab binding; the model cannot provide an arbitrary filesystem root. Selecting `origin` does not add a separate approval prompt, so the agent can complete a requested inspect/edit/test/commit workflow without interruption. The normal configured tool-permission policy still applies equally to both targets. Each target keeps its own path guard and strict shell sandbox.
+
 ## Reading the workspace
 
 ### `list_directory`

data/examples/plugins/space_invaders.rb

@@ -15,7 +15,7 @@
 # The game renders colored sprites and particle-burst explosions inside the
 # composer canvas region using the interactive mode API.
 
-Kward.plugin do |plugin|
+Kward.plugin(id: "com.kward.example.space-invaders", version: "1.0.0", api: 1) do |plugin|
   plugin.interactive_command "invaders", rows: 18, fps: 30, description: "Space Invaders arcade game" do |ui, ctx|
     game = SpaceInvadersGame.new(width: ui.width, height: ui.height)
     ui.on_tick { |ui| game.tick(ui) }

data/examples/plugins/stardate_footer.rb

@@ -1,6 +1,6 @@
 # Displays the current Federation stardate in Kward's interactive footer.
-Kward.plugin do |plugin|
-  plugin.footer do |_ctx|
+Kward.plugin(id: "com.kward.example.stardate-footer", version: "1.0.0", api: 1) do |plugin|
+  plugin.status "stardate", priority: :low do |_ctx|
     now = Time.now.utc
     reference = Time.utc(1987, 7, 15)
     stardate = 41_000 + ((now - reference) / (365.25 * 24 * 60 * 60) * 1_000)

data/examples/plugins/telegram/plugin.rb

@@ -1,6 +1,6 @@
 require_relative "telegram_transport"
 
-Kward.plugin do |plugin|
+Kward.plugin(id: "com.kward.telegram", version: "1.0.0", api: 1) do |plugin|
   capabilities = {
     inbound: %i[text],
     outbound: %i[text],

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

@@ -3,6 +3,7 @@ require_relative "model/chat_invocation"
 require_relative "compactor"
 require_relative "model/context_overflow"
 require_relative "conversation"
+require_relative "plugins/turn_request"
 require_relative "events"
 require_relative "deep_copy"
 require_relative "hooks"
@@ -28,10 +29,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
@@ -40,9 +42,9 @@ module Kward
 
     attr_reader :conversation, :tool_registry
 
-    # Adds a user message, compacts context when needed, and runs the turn.
+    # Adds user input or scopes a plugin system request, then runs a normal turn.
     #
-    # @param input [String] text sent to the model
+    # @param input [String, PluginTurnRequest] user text or host-staged system instructions
     # @param display_input [String, nil] alternate text kept for transcripts
     # @yieldparam event [Object] streamed turn event for frontends
     # @return [String] final assistant answer
@@ -51,19 +53,31 @@ module Kward
       status = "completed"
       error = nil
       cancellation&.raise_if_cancelled!
-      turn_start = run_hook("turn_start", payload: { input: input, display_input: display_input })
+      system_turn = input if input.is_a?(PluginTurnRequest)
+      display_input ||= system_turn.to_s if system_turn
+      input = system_turn.system if system_turn
+      turn_start = run_hook("turn_start", payload: { input: input, display_input: display_input, input_role: system_turn ? "system" : "user" })
       return hook_denied_answer(turn_start) if turn_start.denied?
 
       input = turn_start.payload[:input] || turn_start.payload["input"] || input
       display_input = turn_start.payload[:display_input] || turn_start.payload["display_input"] || display_input
-      @conversation.refresh_system_message_if_workspace_agents_changed!
-      @conversation.append_user(input, display_content: display_input)
-      run_hook("turn_context_build_before", payload: { message_count: @conversation.messages.length })
-      auto_compact_if_needed
-      run_hook("turn_context_build_after", payload: { message_count: @conversation.messages.length })
-      answer = run_turn(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry, &block)
-      run_hook("turn_end", payload: { input: input, answer: answer })
-      answer
+      if system_turn
+        system_turn = PluginTurnRequest.new(system: input, command: system_turn.command, plugin_id: system_turn.plugin_id, id: system_turn.id)
+      end
+      @conversation.with_system_turn(system_turn) do
+        @conversation.refresh_system_message_if_workspace_agents_changed!
+        if system_turn
+          @conversation.append_system_turn(system_turn)
+        else
+          @conversation.append_user(input, display_content: display_input)
+        end
+        run_hook("turn_context_build_before", payload: { message_count: @conversation.messages.length })
+        auto_compact_if_needed
+        run_hook("turn_context_build_after", payload: { message_count: @conversation.messages.length })
+        answer = run_turn(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry, &block)
+        run_hook("turn_end", payload: { input: input, answer: answer })
+        answer
+      end
     rescue StandardError => e
       status = "failed"
       error = e
@@ -241,7 +255,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?
@@ -261,7 +276,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 })

data/lib/kward/cli/auth_commands.rb

@@ -13,6 +13,8 @@ module Kward
         case arguments
         when ["status"]
           print_auth_status
+        when ["status", "--all"]
+          print_auth_status(show_all: true)
         when ["logout"]
           logout_auth
         else
@@ -21,23 +23,42 @@ module Kward
       end
 
       # Writes the auth status output for the terminal CLI flow.
-      def print_auth_status
-        store = api_key_store
-        store.migrate_openrouter_config_key!
-        lines = ["#{colored("Auth Status", :green, :bold)}", ""]
-        lines << auth_status_line("OpenAI OAuth", File.exist?(OpenAIOAuth.default_auth_path), OpenAIOAuth.default_auth_path)
-        lines << auth_status_line("Anthropic OAuth", File.exist?(AnthropicOAuth.default_auth_path), AnthropicOAuth.default_auth_path)
-        lines << auth_status_line("GitHub OAuth", File.exist?(GithubOAuth.default_auth_path), GithubOAuth.default_auth_path)
-        ProviderCatalog.api_key_providers.each do |provider|
-          lines << auth_status_line("#{provider.name} API key", store.configured?(provider.id), store.path)
+      def print_auth_status(show_all: false)
+        credentials = auth_credentials
+        configured, missing = credentials.partition { |credential| credential.fetch(:configured) }
+        lines = [colored("Authentication", :green, :bold), "", colored("Configured", :blue, :bold)]
+        lines.concat(auth_credential_lines(configured, status: :ok, empty_message: "None"))
+
+        if show_all
+          lines << ""
+          lines << colored("Not configured", :blue, :bold)
+          lines.concat(auth_credential_lines(missing, status: :optional, empty_message: "None"))
+        elsif missing.any?
+          lines << ""
+          lines << "#{missing.length} other provider#{missing.length == 1 ? " is" : "s are"} not configured. Run `kward auth status --all` for details."
         end
+
+        lines << ""
+        lines << colored("Credential directory", :blue, :bold)
+        lines << "  #{ConfigFiles.config_dir}"
         @prompt.say lines.join("\n")
       end
 
-      def auth_status_line(label, configured, location)
-        status = configured ? :ok : :warning
-        message = configured ? "configured" : "not configured"
-        "#{doctor_mark(status)} #{label}: #{message} (#{location})"
+      def auth_credentials
+        store = api_key_store
+        store.migrate_openrouter_config_key!
+        credentials = [
+          { label: "OpenAI OAuth", configured: File.exist?(OpenAIOAuth.default_auth_path) },
+          { label: "Anthropic OAuth", configured: File.exist?(AnthropicOAuth.default_auth_path) },
+          { label: "GitHub OAuth", configured: File.exist?(GithubOAuth.default_auth_path) }
+        ]
+        credentials.concat ProviderCatalog.api_key_providers.map { |provider| { label: "#{provider.name} API key", configured: store.configured?(provider.id) } }
+      end
+
+      def auth_credential_lines(credentials, status:, empty_message:)
+        return ["  #{empty_message}"] if credentials.empty?
+
+        credentials.map { |credential| "  #{doctor_mark(status)} #{credential.fetch(:label)}" }
       end
 
       def logout_auth

data/lib/kward/cli/commands.rb

@@ -38,67 +38,88 @@ module Kward
 
       # Writes the help output for the terminal CLI flow.
       def print_help
-        command = ->(text) { colored(text, :green, :bold) }
-        option = ->(text) { colored(text, :cyan) }
         heading = ->(text) { colored(text, :blue, :bold) }
+        lines = ["#{colored("Kward", :green, :bold)} - an extensible CLI coding agent", ""]
 
-        @prompt.say <<~HELP.rstrip
-          #{colored("Kward", :green, :bold)} - an extendable CLI coding agent
-
-          #{heading.call("Usage")}
-            #{command.call("kward")}                              Start an interactive chat
-            #{command.call("kward")} #{option.call('"Explain this project"')}       Run a one-shot prompt
-            #{command.call("kward --filter")} #{option.call('"Translate"')}          Filter stdin with an instruction
-            #{command.call("kward login")}                        Sign in or save provider credentials
-            #{command.call("kward auth status")}                  Show saved credential status
-            #{command.call("kward init")}                         Install starter prompts and PRINCIPLES.md
-            #{command.call("kward doctor")}                       Check local Kward setup
-            #{command.call("kward hooks doctor")}                 Inspect lifecycle hook setup
-            #{command.call("kward skills status")}                 Inspect project skill trust
-            #{command.call("kward edit")} #{option.call("<filename>")}              Open a file in the integrated editor
-            #{command.call("kward sysprompt")}                    Inspect the effective system prompt
-            #{command.call("kward openrouter refresh")}           Refresh cached OpenRouter models
-            #{command.call("kward pan")}                          Start Pan mode web UI
-            #{command.call("kward rpc")}                          Start the JSON-RPC backend
-            #{command.call("kward transport")}                    Manage transport plugins
-
-          #{heading.call("Commands")}
-            #{command.call("help")}                               Show this help
-            #{command.call("version")}                            Show the installed Kward version
-            #{command.call("login")} [anthropic|openrouter|github] Sign in with OpenAI, Anthropic, OpenRouter, or GitHub
-            #{command.call("auth status|logout")}                 Show or clear saved credentials
-            #{command.call("init")}                               Install starter prompts and PRINCIPLES.md
-            #{command.call("doctor")}                             Check local Kward setup
-            #{command.call("hooks list|events|logs|doctor|trust|untrust")} Inspect lifecycle hooks
-            #{command.call("skills status|trust|untrust|review")}  Manage project skill trust
-            #{command.call("edit")} #{option.call("<filename>")}                  Open a file in the integrated editor
-            #{command.call("sysprompt")} [--raw]                  Inspect the effective system prompt
-            #{command.call("stats tokens")} [range] [options]      Export local token telemetry as CSV
-            #{command.call("openrouter refresh|list")}             Refresh or list cached OpenRouter models
-            #{command.call("pan")}                                Start Pan mode web UI
-            #{command.call("rpc")}                                Run the JSON-RPC backend for UI clients
-            #{command.call("transport list|status|run")}            Manage transport plugins
-
-          #{heading.call("Options")}
-            #{option.call("--working-directory=PATH")}             Run Kward from PATH
-            #{option.call("--mode=MODE")}                          Execution mode: auto, chat, oneshot, filter
-            #{option.call("--filter")}                              Shortcut for --mode filter
-            #{option.call("--skip-config")}                         Ignore the main config file for this run
-            #{option.call("--help")}, #{option.call("-h")}                         Show this help
-            #{option.call("--version")}, #{option.call("-v")}                      Show the installed version
-
-          #{heading.call("Examples")}
-            #{command.call("kward")}
-            #{command.call("kward")} #{option.call('"Explain this project"')}
-            #{command.call("git diff | kward")} #{option.call('"Summarize the main changes"')}
-            #{command.call("echo Hello | kward --filter")} #{option.call('"Translate to German"')}
-            #{command.call("kward login openrouter")}
-            #{command.call("kward edit lib/main.rb")}
-            #{command.call("kward openrouter refresh")}
-            #{command.call("kward stats tokens today --bucket hour")}
-
-          Command names take precedence. Anything else is sent as a one-shot prompt.
-        HELP
+        help_sections.each do |title, entries|
+          lines << heading.call(title)
+          lines.concat formatted_help_rows(entries, color: :green, bold: true)
+          lines << ""
+        end
+
+        lines << heading.call("Options")
+        lines.concat formatted_help_rows(help_options, color: :cyan)
+        lines << ""
+        lines << heading.call("Examples")
+        lines.concat help_examples.map { |example| "  #{colored(example, :green, :bold)}" }
+        lines << ""
+        lines << "Command names take precedence. Anything else is sent as a one-shot prompt."
+        @prompt.say lines.join("\n")
+      end
+
+      def help_sections
+        {
+          "Getting started" => [
+            ["kward", "Start an interactive chat"],
+            ["kward login [PROVIDER]", "Sign in or save provider credentials"],
+            ["kward doctor", "Check local Kward setup"],
+            ["kward init", "Install starter prompts and PRINCIPLES.md"]
+          ],
+          "Work" => [
+            ["kward \"PROMPT\"", "Run a one-shot prompt"],
+            ["kward --filter \"INSTRUCTION\"", "Filter standard input"],
+            ["kward edit <filename>", "Open a file in the integrated editor"],
+            ["kward sysprompt [--raw]", "Inspect the effective system prompt"]
+          ],
+          "Manage" => [
+            ["kward auth status [--all]", "Show saved credential status"],
+            ["kward hooks <command>", "Inspect lifecycle hooks"],
+            ["kward skills <command>", "Manage project skill trust"],
+            ["kward openrouter <command>", "Manage cached OpenRouter models"],
+            ["kward stats tokens [range] [options]", "Export local token telemetry as CSV"]
+          ],
+          "Integrate" => [
+            ["kward pan", "Start the local Pan web UI"],
+            ["kward rpc", "Start the JSON-RPC backend"],
+            ["kward transport <command>", "Manage transport plugins"]
+          ],
+          "Reference" => [
+            ["kward help [command]", "Show help"],
+            ["kward version", "Show the installed version"]
+          ]
+        }
+      end
+
+      def help_options
+        [
+          ["--working-directory=PATH", "Run Kward from PATH"],
+          ["--mode=MODE", "Execution mode: auto, chat, oneshot, filter"],
+          ["--filter", "Shortcut for --mode filter"],
+          ["--skip-config", "Ignore the main config file for this run"],
+          ["--help, -h", "Show help"],
+          ["--version, -v", "Show the installed version"]
+        ]
+      end
+
+      def help_examples
+        [
+          "kward",
+          "kward \"Explain this project\"",
+          "git diff | kward \"Summarize the main changes\"",
+          "echo Hello | kward --filter \"Translate to German\"",
+          "kward login openrouter",
+          "kward edit lib/main.rb",
+          "kward stats tokens today --bucket hour"
+        ]
+      end
+
+      def formatted_help_rows(entries, color:, bold: false)
+        width = entries.map { |label, _description| label.length }.max
+        styles = [color]
+        styles << :bold if bold
+        entries.map do |label, description|
+          "  #{colored(label.ljust(width), *styles)}  #{description}"
+        end
       end
 
       def command_help
@@ -119,9 +140,9 @@ module Kward
             examples: ["kward login", "kward login anthropic", "kward login openrouter", "kward login github"]
           },
           "auth" => {
-            usage: "kward auth status|logout",
+            usage: "kward auth status [--all]|logout",
             description: "Show or clear saved provider credentials without printing secrets.",
-            examples: ["kward auth status", "kward auth logout"]
+            examples: ["kward auth status", "kward auth status --all", "kward auth logout"]
           },
           "init" => {
             usage: "kward init",
@@ -165,7 +186,7 @@ module Kward
           },
           "pan" => {
             usage: "kward pan",
-            description: "Start Pan mode, a mobile-friendly LAN web UI with persistent sessions.",
+            description: "Start Pan mode, a mobile-friendly local web UI with persistent sessions.",
             examples: ["kward pan", "kward --working-directory ~/code/project pan"]
           },
           "rpc" => {

data/lib/kward/cli/compaction.rb

@@ -6,7 +6,7 @@ module Kward
     module CompactionCommands
       private
 
-      def compact_context(agent, argument)
+      def compact_context(agent, argument, cancellation: nil)
         before = run_lifecycle_hook("session_compact_before", conversation: agent.conversation, payload: { instructions: argument.to_s })
         if before.denied? || before.approval_required?
           runtime_output("Declined: #{before.decision.message || "session compaction denied"}")
@@ -17,16 +17,22 @@ module Kward
           conversation: agent.conversation,
           client: @client,
           tool_result_summarizer: lambda { |tool_call, content| tool_result_summary(tool_call, content) }
-        ).compact(custom_instructions: argument)
+        ).compact(custom_instructions: argument, cancellation: cancellation)
         run_lifecycle_hook("session_compact_after", conversation: agent.conversation, payload: { old_message_count: result.old_message_count, new_message_count: result.new_message_count })
         runtime_output("Compacted context: #{result.old_message_count} messages -> #{result.new_message_count} messages.")
-        render_transcript_block("Assistant", result.summary)
+        result.summary
       rescue Compactor::NothingToCompact, Compactor::AlreadyCompacted, Compactor::EmptySummary => e
         runtime_output(e.message)
+      rescue Cancellation::CancelledError
+        raise
       rescue StandardError => e
         runtime_output("Compaction error: #{e.message}")
       end
 
+      def render_compaction_summary(summary)
+        render_transcript_block("Assistant", summary)
+      end
+
     end
   end
 end