kward 0.78.0 → 0.80.0

data/doc/editor.md

@@ -1,4 +1,8 @@
-# Integrated Editor
+# Integrated editor
+
+Kward includes a terminal editor with three modes: Modern, Emacs, and Vibe. It opens inside the chat composer, so you can jump into a file, make a change, save it, and return to the conversation without switching tools.
+
+The editor opens only files inside the current workspace, which keeps edits tied to the project where you started Kward.
 
 <quote>
 Three Modes for the Elven-kings under the sky,<br>
@@ -10,10 +14,6 @@ One Kward to bring them all and in the transcript bind them<br>
 In the Land of Ruby where the agents lie.<br>
 </quote>
 
-Kward includes a terminal editor with 3 editing modes to choose from: Modern, Emacs and Vibe. It opens inside the chat composer, so you can jump into a file, make a change, save it, and return to the conversation without switching tools.
-
-The editor is scoped to the current workspace. It only opens files inside that directory, which helps keep edits tied to the project you started Kward in.
-
 ## Quick start
 
 Open a file directly from your shell:
@@ -93,8 +93,8 @@ $doc/editor.md
 
 The editor is intentionally compact, but it covers the basics you need for quick changes:
 
-- Syntax highlighting for common languages, including Ruby, 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. 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. 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.
+- 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.
 - 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.

data/doc/extensibility.md

@@ -14,6 +14,7 @@ Start simple. Most users only need `PRINCIPLES.md`, workspace `AGENTS.md`, and m
 | Task-specific reusable instructions | skills |
 | Different tone or role | [personas](personas.md) |
 | Local Ruby behavior or integrations | plugins |
+| External messaging or event integration | transport plugins |
 | Deterministic runtime policy or automation | lifecycle hooks |
 
 Install the starter pack for a useful starting point:
@@ -43,6 +44,8 @@ If `KWARD_CONFIG_PATH` is set, `PRINCIPLES.md` lives beside that config file.
 
 If `PRINCIPLES.md` is absent, Kward also reads `~/.kward/AGENTS.md` (or the equivalent beside a custom config path) as a legacy alias. New setups should use `PRINCIPLES.md`. See [Configuration](configuration.md) for details.
 
+For a small local model, set `system_prompt.include_principles` to `false` to keep Kward's normal prompt without global principles. Set `system_prompt.file` only when you want the file to replace the entire assembled system prompt; replacement mode also omits personas, skills, memory, plugins, and workspace guidance. See [Local models](local-models.md) for a complete setup.
+
 ## Project instructions: `AGENTS.md`
 
 Put repository-specific rules in the workspace root:
@@ -66,35 +69,9 @@ By default, Kward adds a compact instruction telling the model that `AGENTS.md`
 
 ## Prompt templates
 
-Use prompt templates when you repeatedly type the same kind of request.
-
-Create:
-
-```text
-~/.kward/prompts/review.md
-```
-
-Example:
-
-```markdown
----
-description: Review a change for correctness.
-argument-hint: <focus>
----
-
-Review the current diff for correctness, tests, and maintainability.
-Focus on: $ARGUMENTS
-```
-
-Then run inside Kward:
-
-```text
-/review auth edge cases
-```
+Use prompt templates when you repeatedly type the same kind of request. Each Markdown file in `~/.kward/prompts/` becomes a slash command; its filename is the command name and `$ARGUMENTS` expands the text after the command.
 
-The `description` frontmatter field appears in the slash command list and completion overlay so you can find the template by purpose. `argument-hint` is shown as a usage hint. The `$ARGUMENTS` placeholder in the body is replaced with whatever you type after the command.
-
-Prompt templates are best for reusable text. They do not run local code.
+See [Prompt templates](prompt-templates.md) to create one, understand naming and reload behavior, and learn about the `/plan`, `/investigate`, `/research`, and `/codebase-review` templates installed by `kward init`.
 
 ## Skills
 
@@ -112,12 +89,15 @@ Hooks are deterministic automation and policy. They are not model instructions.
 
 Use plugins when text instructions are not enough and you need Ruby code to run locally.
 
-Plugins can add slash commands, prompt context, footer UI, transcript observers, and RPC-visible commands.
+Plugins can add slash commands, prompt context, footer UI, transcript observers, RPC-visible commands, and external transports. Transport plugins can connect external conversations to normal Kward sessions or explicitly transport-capable plugin chats; they remain distinct from plugin-owned tabs.
+
+Use `kward transport list` and `kward transport status` to inspect registered transports. Run a foreground transport with `kward transport run NAME`.
 
 Plugin files live in:
 
 ```text
 ~/.kward/plugins/*.rb
+~/.kward/plugins/*/plugin.rb
 ```
 
 Plugins are trusted local Ruby code. Install only plugins you trust. See [Plugins](plugins.md).

data/doc/files.md

@@ -12,7 +12,7 @@ From an interactive Kward session, run:
 /files
 ```
 
-Kward opens the project file browser. Use the arrow keys 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.
 
 When you quit the editor, Kward returns to the file browser at the same position so you can keep browsing nearby files.
 
@@ -32,10 +32,10 @@ Outside Git, Kward scans the workspace directory and skips common noisy director
 
 | Key | Action |
 | --- | ------ |
-| `↑` / `↓` | Move the selection |
+| `↑` / `↓` or `j` / `k` | Move the selection down / up |
 | `Enter` | Open a file, or toggle a directory |
-| `←` | Collapse the selected directory, or jump to its parent |
-| `→` | Expand the selected directory |
+| `←` or `h` | Collapse the selected directory, or jump to its parent |
+| `→` or `l` | Expand the selected directory |
 | `Tab` | Start or stop search |
 | `/` | Start search |
 | `Backspace` | Delete the last search character |
@@ -55,7 +55,7 @@ For example:
 /agent
 ```
 
-Use `↑` and `↓` to choose a result, then press `Enter` to open it. Press `Esc` to return to the tree view.
+Use `↑` / `↓` or `j` / `k` to choose a result, then press `Enter` to open it. Press `Esc` to return to the tree view.
 
 ## Mention a file in chat
 
@@ -84,7 +84,7 @@ A typical workflow:
 5. Save and quit.
 6. Continue browsing files, or press `Esc` to return to chat.
 
-See [Integrated Editor](editor.md) for editor modes, save/quit keys, search, selection, and configuration.
+See [Integrated editor](editor.md) for editor modes, save/quit keys, search, selection, and configuration.
 
 ## Remembered state
 

data/doc/getting-started.md

@@ -6,7 +6,7 @@ This page gets you from install to a first useful chat.
 
 ## Requirements
 
-- Ruby 3.2 or newer.
+- Ruby 3.4 or newer.
 - Credentials for one model provider. The easiest setup is `kward login` or `/login` inside Kward.
 - Bundler only if you run Kward from a source checkout.
 
@@ -57,7 +57,7 @@ Or from inside an interactive session:
 /login
 ```
 
-Kward supports OpenAI/ChatGPT, Anthropic Claude Pro/Max, OpenRouter, and experimental Copilot credentials. See [Authentication](authentication.md) when you need a specific provider.
+Kward supports subscription login, direct native APIs, OpenAI-compatible API-key providers, Copilot, OpenRouter, and local model servers. See [Model providers](providers.md) to choose one, then [Authentication](authentication.md) for its login flow.
 
 Confirm your credentials are saved:
 
@@ -65,7 +65,7 @@ Confirm your credentials are saved:
 kward auth status
 ```
 
-If your provider offers multiple models, choose one inside Kward with `/model`.
+Choose a model inside Kward with `/model`. The picker can refresh provider catalogs, switch providers, show all returned entries, or accept a manual model/deployment ID.
 
 ## Start an interactive chat
 

data/doc/git.md

@@ -30,7 +30,7 @@ Use the overlay to review and shape the commit:
 
 | Key | Action |
 | --- | --- |
-| `↑` / `↓` | Move between changed files. |
+| `↑` / `↓` or `j` / `k` | Move between changed files. |
 | `Enter` | Open the selected file in the diff viewer. |
 | `s` | Stage or unstage the selected file. |
 | `Tab` | Switch to commit-message entry. |
@@ -61,7 +61,7 @@ Useful keys in the diff viewer:
 
 After you close the viewer, Kward returns to the Git overlay with the file list refreshed.
 
-The diff viewer is read-only. It is meant for checking what changed, not editing. If you spot something you want to fix, close the viewer, return to chat, and ask Kward to make the change or open the file with the built-in editor using `$path/to/file`. See [Integrated Editor](editor.md) for editor workflows and keybindings.
+The diff viewer is read-only. It is meant for checking what changed, not editing. If you spot something you want to fix, close the viewer, return to chat, and ask Kward to make the change or open the file with the built-in editor using `$path/to/file`. See [Integrated editor](editor.md) for editor workflows and keybindings.
 
 ## Example workflow
 
@@ -107,6 +107,12 @@ This is just a lightweight status hint. Use `/git` when you want to review or co
 
 If the working tree is clean when you run `/git`, the overlay shows `No uncommitted changes.` and there is nothing to stage or commit.
 
+## Agent commits in worktree tabs
+
+When an active worktree tab receives an explicit request to commit, the agent can use the model-facing `git_commit` tool. It runs Git in the trusted host process so linked-worktree metadata can be updated without granting arbitrary shell commands write access to shared `.git` metadata.
+
+The tool requires a commit message and can receive an optional list of workspace-relative paths. If paths are omitted, all current changes in the active worktree are included. Generic `run_shell_command` Git commands remain sandboxed and cannot replace this operation. It is exposed only for active interactive worktree tabs; RPC sessions do not currently support worktree bindings.
+
 ## Notes and limitations
 
 - `/git` is available in the interactive terminal UI, not in one-shot prompts or the RPC backend.

data/doc/lifecycle-hooks.md

@@ -1,8 +1,8 @@
 # Lifecycle hooks
 
-Lifecycle hooks are deterministic runtime callbacks around Kward's agent workflow. Use them when something must happen because of an event, not because the model remembered an instruction.
+Lifecycle hooks let you run a rule or action whenever something happens in Kward—for example, before a command runs, after a turn finishes, or when a tool needs approval. Use a hook when the action must happen reliably rather than depending on the model to remember an instruction.
 
-Hooks can observe events and return structured decisions to allow, deny, ask for approval, modify supported payloads, warn, retry, or defer. They are currently exposed through trusted Ruby plugins and through command hooks configured in `config.json`.
+A hook can observe an event, allow or deny an operation, ask for approval, adjust supported data, or trigger follow-up work. You can add hooks through trusted Ruby plugins or configure command hooks in `config.json`.
 
 Hooks run as local code with your user permissions. Do not install hooks you do not trust, and do not put secrets in hook output.
 
@@ -34,7 +34,8 @@ When multiple hooks match one event, they run by ascending `order`. A `deny` sto
 
 ## Ruby plugin hooks
 
-Register hooks from trusted plugin files in `~/.kward/plugins/*.rb`:
+Register hooks from trusted plugin files in `~/.kward/plugins/*.rb` or a
+package entrypoint at `~/.kward/plugins/*/plugin.rb`:
 
 ```ruby
 Kward.plugin do |plugin|
@@ -363,7 +364,7 @@ Unknown selector keys match same-named payload fields.
 
 ## Security notes
 
-- Plugin hooks are trusted Ruby code loaded only from `~/.kward/plugins/*.rb`.
+- Plugin hooks are trusted Ruby code loaded only from `~/.kward/plugins/*.rb` or package entrypoints at `~/.kward/plugins/*/plugin.rb`.
 - Command hooks run local commands with your user permissions.
 - Workspace hook files are loaded only after `/hooks trust`, and trust is invalidated when `.kward/hooks.json` changes.
 - Hook payloads are intentionally bounded and metadata-oriented; avoid logging raw event JSON if your hook receives prompt or command data.

data/doc/local-models.md

@@ -0,0 +1,130 @@
+# Local models
+
+If you already run Ollama, LM Studio, or llama.cpp, Kward can use it as a local model provider. This can be useful for offline work, tighter control over model selection, or a smaller prompt tuned for a local coding model. The server must provide OpenAI-compatible Chat Completions.
+
+Kward connects to an already-running server; it does not install a runtime, download or load models, or choose GPU settings. For a comparison with hosted providers, see [Model providers](providers.md#Choosing_between_similar_providers).
+
+## Choose and start a runtime
+
+Use one of these local servers:
+
+| Runtime | Default Kward base URL |
+| --- | --- |
+| Ollama | `http://127.0.0.1:11434/v1` |
+| LM Studio | `http://127.0.0.1:1234/v1` |
+| llama.cpp `llama-server` | `http://127.0.0.1:8080/v1` |
+
+Start the server and load a chat model before starting Kward. Then confirm that it reports models:
+
+```bash
+curl http://127.0.0.1:11434/v1/models
+```
+
+Use the equivalent configured port for LM Studio or llama.cpp.
+
+## Configure Kward
+
+Add a Local provider configuration to `~/.kward/config.json`:
+
+```json
+{
+  "provider": "local",
+  "local_backend": "ollama",
+  "local_model": "qwen2.5-coder:7b",
+  "local_context_window": 32768
+}
+```
+
+`local_backend` supplies a default endpoint for `ollama`, `lm_studio`, or `llama_cpp`. Set `local_base_url` when the server uses another host, port, path, Docker address, reverse proxy, or TLS endpoint:
+
+```json
+{
+  "provider": "local",
+  "local_base_url": "http://127.0.0.1:1234/v1",
+  "local_model": "loaded-model-id",
+  "local_context_window": 32768
+}
+```
+
+Set `local_context_window` to the context length actually configured for the loaded model. Kward cannot reliably infer it from a local model name. The value lets Kward report meaningful context usage and make safe auto-compaction decisions.
+
+If your local proxy requires a token, set `local_api_key` or `KWARD_LOCAL_API_KEY`. Kward sends it as a bearer token only for Local requests.
+
+You can also choose **Local** from `/settings` → **Model & Reasoning** → **Provider**, then select a model with `/model`.
+
+## Use a minimal replacement prompt
+
+Smaller models often work better with a short, direct prompt. Create a file beside your Kward config, for example `~/.kward/prompts/local-minimal.md`:
+
+```markdown
+You are a coding assistant.
+Use the provided tools when needed.
+Inspect relevant files before changing them.
+Make only requested changes and report what changed.
+```
+
+Configure it as Kward's replacement system prompt:
+
+```json
+{
+  "system_prompt": {
+    "file": "prompts/local-minimal.md",
+    "include_principles": false
+  }
+}
+```
+
+This file is the entire system prompt. Kward does not add its built-in instructions, `PRINCIPLES.md`, memory context, personas, plugin context, skills, or workspace `AGENTS.md` guidance in replacement mode.
+
+If you want Kward's normal prompt but do not want global principles sent on every turn, omit the `file` and disable only principles:
+
+```json
+{
+  "system_prompt": {
+    "include_principles": false
+  }
+}
+```
+
+Check the exact result before relying on it:
+
+```bash
+kward sysprompt
+kward sysprompt --raw
+```
+
+Do not put secrets in a replacement prompt. Its contents are sent to the model and may be stored as a session prompt snapshot.
+
+## Verify tool calling
+
+A coding agent needs more than ordinary chat: the model must request tools with valid arguments and use their results. Start with a safe read-only task:
+
+```text
+Read README.md and summarize the project's test command. Do not modify files.
+```
+
+Choose a model trained for tool or function calling. If it responds with prose instead of tool calls, use a tool-capable model or make the replacement prompt's tool guidance more explicit.
+
+## Security and limits
+
+The default endpoints use loopback addresses. If you configure another host, Kward can send prompts, workspace-derived content, attachments, and tool results over that connection. Use TLS and authentication for any endpoint outside your machine or trusted private network.
+
+Local model support uses the OpenAI-compatible Chat Completions interface, including streaming text and function/tool calls. Kward does not promise reasoning controls or image support for arbitrary local models.
+
+## Troubleshooting
+
+**No models appear in `/model`**
+
+Confirm the server is running, a model is loaded, and `GET /v1/models` succeeds. You can still set `local_model` manually when discovery is unavailable.
+
+**The model stops early or Kward compacts too soon**
+
+Check `local_context_window`. It must match the server's loaded-model context setting, not just the model's advertised training context.
+
+**Tool calls are malformed or missing**
+
+Use a tool-trained model and a compatible chat template. Test with a read-only task before allowing writes or shell commands.
+
+**The server is slow**
+
+Reduce the model size, reduce context length, verify GPU acceleration in the local runtime, or raise `stream_idle_timeout_seconds` if the server has long silent intervals.

data/doc/mcp.md

@@ -1,8 +1,8 @@
 # MCP servers
 
-Kward can connect to local [Model Context Protocol](https://modelcontextprotocol.io/) servers and expose their tools to the model alongside Kward's built-in workspace tools.
+Kward can connect to local [Model Context Protocol](https://modelcontextprotocol.io/) servers and use their tools alongside its built-in workspace tools.
 
-This is useful when another app ships an MCP server for something Kward should be able to inspect or control. For example, Safari Technology Preview includes a Safari MCP server that lets agents inspect pages, console output, network activity, screenshots, and other browser state.
+Use MCP when another app exposes something you want Kward to inspect or control. For example, Safari Technology Preview includes an MCP server for inspecting pages, console output, network activity, screenshots, and other browser state.
 
 ## Configure a local MCP server
 
@@ -66,7 +66,7 @@ Example with an environment variable and custom timeout:
 
 ## Notes and limitations
 
-- Kward currently supports local stdio MCP servers.
-- Kward currently exposes MCP tools. MCP resources, prompts, sampling, and Streamable HTTP are not implemented yet.
-- MCP tool results are returned to the model as text. Structured content is included as JSON. Image, audio, and resource results are summarized as placeholders for now.
+- Kward supports local stdio MCP servers and exposes their tools to the model.
+- It does not support MCP resources, prompts, sampling, or Streamable HTTP.
+- MCP tool results are returned to the model as text. Structured content is included as JSON. Image, audio, and resource results are summarized as placeholders.
 - MCP servers can expose sensitive local application state. Only configure servers you trust, especially browser automation servers that can read page content or screenshots.

data/doc/permissions.md

@@ -1,8 +1,8 @@
 # Permissions
 
-Kward's permission policy lets you put a human decision between a model-requested tool call and its side effect. It is useful when you want the agent to inspect a project freely, but want to confirm edits, commands, web requests, or MCP calls as they arise.
+Turn on permissions when you want Kward to ask before it edits files, runs commands, accesses the web, or calls an MCP tool. In the usual `ask` mode, read-only work continues normally while you decide which side effects to allow.
 
-Permissions are **off by default**. Enabling them does not sandbox Kward or its subprocesses: an allowed shell command still runs with your operating-system user permissions.
+Permissions are **off by default**. They are not an operating-system sandbox: an allowed shell command still runs with your operating-system user permissions unless you separately enable [command sandboxing](sandboxing.md) for model-requested shell commands.
 
 ## Start with approval mode
 
@@ -24,7 +24,16 @@ In `ask` mode, Kward allows ordinary read-only tools and asks before the agent:
 - searches or fetches content on the web,
 - calls an MCP tool.
 
-When approval is required in the interactive CLI, Kward opens a modal overlay. It shows the complete tool arguments, so an approval for `read_skill` includes the requested skill name and relative path, and an approval for a write includes its path and content. Choose **Allow once** to run that one call, **Allow this tool for this session** to allow later calls to the same tool in the current Kward session, or **Deny** to stop it. Pressing `Esc`, cancelling the overlay, or losing the approval bridge denies the call.
+When Kward needs approval in the interactive CLI, it shows the complete tool arguments in an overlay. For example, a write request includes the file path and content.
+
+Choose:
+
+- **Allow once** to run this call.
+- **Allow this tool for this session** to allow later calls to the same tool in the current session.
+- **Deny** to stop the call.
+- **Type something** to stop the call and tell Kward what to do instead.
+
+Pressing `Esc`, closing the overlay, or losing the frontend connection denies the call.
 
 ### Steer the agent with `Type something`
 
@@ -91,7 +100,7 @@ With this configuration, the agent may edit `lib/` and `test/` without asking. A
 
 `write_scopes` narrows the policy's default workspace-write behavior; it does not broaden Kward's built-in workspace boundary. File tools still stay inside the active workspace by default, and existing files must still be read before Kward can edit them. See [Workspace tools](workspace-tools.md) for those guardrails.
 
-An empty `write_scopes` array permits no default workspace writes. Omit `write_scopes` if you want the `workspace-write` mode to cover the normal workspace file-tool boundary.
+An empty `write_scopes` array permits no default workspace writes. Omit `write_scopes` if you want the `workspace-write` mode to cover the normal workspace file-tool boundary. The active worktree `git_commit` tool is treated as a mutating tool: it asks for approval in the default `ask` mode and is denied by read-only or deny-by-default modes unless explicitly allowed.
 
 ## Rules and precedence
 
@@ -169,11 +178,12 @@ The policy runs before Kward dispatches a model-requested tool. It does not cons
 - direct commands that you type yourself—`!command`, `/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. A future OS-enforced sandbox may provide stronger filesystem and network isolation; it is not part of the current permissions feature.
+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.
 
 ## Related guides
 
 - [Security and trust](security.md): trust boundaries, extensions, and safe work in unfamiliar repositories.
 - [Configuration](configuration.md#Permissions): the complete configuration reference.
+- [Command sandboxing](sandboxing.md): configure the separate OS boundary for model-requested shell commands.
 - [Lifecycle hooks](lifecycle-hooks.md): add trusted local policy or automation around Kward events.
 - [RPC protocol](rpc.md#Tool_approval_bridge): implement the approval bridge in an RPC client.

data/doc/plugins.md

@@ -21,16 +21,21 @@ Plugins run inside the Kward process with your user permissions. Install only pl
 | Repository rules | `AGENTS.md` |
 | Local Ruby code or integration | plugin |
 
-See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order.
+See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations.
 
 ## Where plugins live
 
-Kward loads top-level Ruby files from:
+Kward loads trusted Ruby plugin entrypoints from:
 
 ```text
 ~/.kward/plugins/*.rb
+~/.kward/plugins/*/plugin.rb
 ```
 
+For a larger plugin, use a directory with `plugin.rb` as its entry point. Kward
+loads only that file automatically, so use `require_relative` there to load any
+sibling files.
+
 Plugins are not loaded from the current workspace or a custom `KWARD_CONFIG_PATH` directory. This prevents a project checkout from silently adding executable Ruby code to Kward.
 
 ## A first plugin
@@ -58,7 +63,7 @@ Start Kward and run:
 /hello World
 ```
 
-When developing plugins, use `/reload` inside Kward to reload all plugin files without restarting. This picks up changes to existing plugins and registers new ones, then rebuilds the system message.
+When developing plugins or prompt templates, use `/reload` inside Kward to reload configured prompt files and all plugin files without restarting. This picks up prompt edits, changes to existing plugins, and new plugin registrations, then refreshes slash-command completion and rebuilds the system message.
 
 ## Add a slash command
 
@@ -111,7 +116,7 @@ Kward.plugin do |plugin|
 end
 ```
 
-Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning.
+Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning. Kward evaluates the active footer at most once per second and reuses its last value between refreshes.
 
 ## Add an interactive command
 
@@ -132,6 +137,7 @@ Kward.plugin do |plugin|
       x = (x + 1) % ui.width
       key = ui.poll_key
       return :exit if key == :ctrl_c || key == "q"
+      ui.render
     end
   end
 end
@@ -162,6 +168,8 @@ Keys are returned as symbols (`:left`, `:right`, `:up`, `:down`, `:return`,
 without a named mapping. Ctrl+C always exits the loop immediately.
 
 The tick callback runs at the configured frame rate (1–120 fps, default 30).
+Calls to `put` and `clear_frame` stage canvas changes; call `render` after the
+frame is complete to publish it. Kward skips ticks that do not publish a frame.
 Returning `:exit` from the tick callback ends the loop, same as calling
 `ui.exit`.
 
@@ -219,6 +227,7 @@ The observer context exposes the plugin tab's `messages` through
 - `messages` — renderable transcript messages;
 - `submit(input, display_input:, cancellation:, steering:)` — a turn method
   that returns the final response and yields stream events;
+- optionally `submit(..., context:)` — trusted actor context for transport turns;
 - `descriptor` — the durable tab descriptor;
 - `supports_steering?` and `assistant_label`.
 
@@ -234,6 +243,32 @@ plugin.tab_type "example", id: "com.example.chat", rpc: true do |host, descripto
 end
 ```
 
+Set `transport: true` separately when an external transport may target the
+plugin chat. Do not use `rpc: true` as an implicit external-access permission:
+
+```ruby
+plugin.tab_type "example", id: "com.example.chat", rpc: true, transport: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+Set `local: false` for a transport-only plugin chat. It remains available to
+transports when `transport: true`, but `/tab open` and local tab restoration do
+not expose it:
+
+```ruby
+plugin.tab_type "telegram", id: "com.example.telegram", local: false, transport: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+Transport-created plugin chats receive a descriptor containing a stable scoped
+key, transport identity, external conversation, and actor metadata. Use the
+scope to select separate transcript and memory roots. The driver may accept a
+`context:` keyword on `submit` to receive the authenticated actor for each
+turn; access decisions must still be enforced by the transport and plugin code,
+not by model instructions.
+
 RPC clients discover opted-in types through `initialize.capabilities.pluginChats`, open a chat with `pluginChats/open`, and must explicitly subscribe before receiving live `pluginChat/event` notifications. See [RPC](rpc.md) for the protocol. Plugin tabs remain CLI-only unless they opt in.
 
 ## Observe transcript events

data/doc/prompt-templates.md

@@ -0,0 +1,105 @@
+# Prompt templates
+
+Prompt templates turn a repeated request into a slash command. Keep one when you regularly ask Kward to plan before coding, investigate without changing files, or review a particular part of a project in the same way.
+
+Templates are reusable **user prompts**, not always-on instructions. Kward expands the selected template when you run its slash command, then sends the expanded text as your request.
+
+Use [skills](skills.md) for task guidance the model can load when relevant, `PRINCIPLES.md` for preferences that apply broadly, and `AGENTS.md` for repository rules.
+
+## Create a template
+
+By default, put one Markdown file per command in:
+
+```text
+~/.kward/prompts/
+```
+
+For example, create `~/.kward/prompts/review.md`:
+
+```markdown
+---
+description: Review a change for correctness.
+argument-hint: <focus>
+---
+
+Review the current diff for correctness, tests, and maintainability.
+Focus on: $ARGUMENTS
+Do not edit files; report findings first.
+```
+
+Restart Kward, or use `/reload` in an already-running session. The filename becomes the command name:
+
+```text
+/review authentication edge cases
+```
+
+Kward expands `$ARGUMENTS` everywhere it appears in the body with the text after `/review`. In this example, the model receives `Focus on: authentication edge cases`. If the template does not contain `$ARGUMENTS`, supplied arguments are not added automatically.
+
+The `description` and `argument-hint` frontmatter fields are optional, but useful: Kward shows them in slash-command completion. The rest of the file is the prompt body. Add as much Markdown structure and instruction text as the workflow needs.
+
+## Naming and discovery
+
+Kward reads `*.md` files directly inside the prompts directory, in filename order. It ignores subdirectories. A filename must produce a command containing only letters, numbers, `_`, and `-`, and must begin with a letter or number:
+
+```text
+~/.kward/prompts/
+├── review.md          # /review
+├── release-check.md   # /release-check
+└── api_v2.md          # /api_v2
+```
+
+A template cannot replace a built-in slash command such as `/settings`, `/skill`, or `/reload`; Kward warns and skips it. It also warns and skips files with invalid Markdown frontmatter or command names.
+
+`~/.kward/prompts` is the default. When `KWARD_CONFIG_PATH` points to another config file, templates live in the `prompts/` directory beside that file instead. See [Configuration](configuration.md#Config_directory).
+
+## Starter templates from `kward init`
+
+After installing Kward, run:
+
+```bash
+kward init
+```
+
+The starter pack downloads template files into `~/.kward/prompts/` without overwriting files that already exist. It currently installs these four commands:
+
+| Command | Use it for | What it asks Kward to do |
+| --- | --- | --- |
+| `/plan <task-or-change>` | Agree on an approach before coding | Clarify important requirements, produce a concise plan, and wait for confirmation before implementation. |
+| `/investigate <bug-or-behavior>` | Diagnose a bug or surprising result | Gather evidence, identify the root cause or strongest hypothesis, suggest the smallest safe fix, and make no edits. |
+| `/research <question-or-topic>` | Answer a question that needs current or external evidence | Prefer primary sources, separate facts from recommendations, cite sources and caveats, and make no changes. |
+| `/codebase-review [scope-or-focus]` | Assess a repository or area for practical cleanup | Report concrete maintainability, correctness, duplication, ownership, testing, and hot-path findings without refactoring. |
+
+For example:
+
+```text
+/plan Add rate limiting to the public API
+/investigate The session picker occasionally shows the wrong title
+/research Which OAuth scopes does this provider require?
+/codebase-review lib/kward/model
+```
+
+The starter templates deliberately favor report- or plan-first workflows. They do not make Kward edit files until you follow up with an explicit implementation request. Edit the installed files to fit your own process, or add new files alongside them.
+
+`kward init` also installs a base `PRINCIPLES.md` and starter skills. It needs network access to fetch the versioned [starter pack](https://github.com/kaiwood/kward-starter-pack) and leaves existing destination files untouched.
+
+## Practical patterns
+
+Keep templates specific enough to set a workflow, but short enough that the request remains easy to adapt. For example, a release-check prompt might take a version as an argument:
+
+```markdown
+---
+description: Prepare release notes and verification for a version.
+argument-hint: <version>
+---
+
+Prepare the release checklist for version $ARGUMENTS.
+Inspect the changelog and version files. Do not publish or tag a release.
+```
+
+Then run:
+
+```text
+/release-check 1.4.0
+```
+
+Templates only expand text; they do not execute local code, grant permissions, or bypass Kward's tool and workspace safeguards.