kward 0.77.0 → 0.79.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a18a2a0c800780596999ee897ed61afcef22c964012f2b2ed3f51a3a66239c5
-  data.tar.gz: 83badb23b87cae5e3198e00c65f0c53acbe2e0561f00164c4e5b40aacb3d10d4
+  metadata.gz: 79174a2cb7441a44857a53568078c50b2c7735d7a8f7507ce6e8d1199f8b37fa
+  data.tar.gz: c83fda7c64aea1ad5f8af38c5ee0bb1d0c56a3c05efa3457c02fcd5b3049cb99
 SHA512:
-  metadata.gz: 5c4bd15eb61a2b62b5165b46d393fa60608dc702b773cbb0596bdd64deed1799332f22a5b271c146142f8f1f2769111e3e0075db34626818a71c4e502a14b49d
-  data.tar.gz: 9953137b41415eff742904f3a4f4d63a610da01351000d5b08d4191ad180bfbdff5c001315513bbf4fabd1918843a6c214712f9af737c0025c5494e6c84494f8
+  metadata.gz: 9088afe9fb4976a8a40ec08a0297ee99d075f9df756465f68e04482c55f5fbb1d5b0b8d5e20b880d258253d8e015ce91b745a1db57c3ce03374b912d4fc109fe
+  data.tar.gz: 7452c7d1674338e52b3216f648b798f9181cf421db840bc54a74270acebd40c1aa67aa1c2dbbfaea322908cd50344e34500a79cb68033bdfc1fa62642cefbf20

data/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.2', 'ruby']
+        ruby-version: ['3.4', 'ruby']
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -27,11 +27,16 @@ jobs:
           ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
 
+      - name: Install sandbox test dependency
+        run: sudo apt-get update && sudo apt-get install --yes bubblewrap
+
       - name: Check syntax
         run: find lib test -name '*.rb' -print0 | xargs -0 ruby -c
 
       - name: Check runtime warnings
-        run: ruby -w -Ilib -e 'require "kward"'
+        run: bundle exec ruby -w -Ilib -e 'require "kward"'
 
       - name: Run tests
+        env:
+          KWARD_RUN_BUBBLEWRAP_TESTS: "1"
         run: bundle exec rake test

data/.github/workflows/pages.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.3'
+          ruby-version: '3.4'
           bundler-cache: true
 
       - name: Build documentation

data/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.79.0] - 2026-07-19
+
+### Added
+
+- Added a Local OpenAI-compatible model provider for Ollama, LM Studio, and llama.cpp, including model discovery, streamed tool calls, configurable context windows, CLI/RPC model selection, and a local-model setup guide.
+- Added replacement system-prompt files and an option to omit global principles for smaller-model prompt budgets.
+- Added skill capture from saved session branches. Review model-generated personal `SKILL.md` drafts in the CLI or Pan, or use the equivalent RPC workflow before explicitly saving them.
+- Added opt-in OS-enforced sandboxing for model-requested shell commands. macOS uses Seatbelt and Linux uses Bubblewrap when available; requested sandboxing fails closed when no supported backend can enforce it. The interactive `/sandbox` command reports and updates the global policy.
+
+### Changed
+
+- Clarified command-sandbox configuration, platform setup, and limits across the security, permissions, workspace-tools, RPC, and configuration guides.
+- Sandboxed command workers now receive a sanitized environment with a private home and temporary directory; the macOS backend also blocks reads from common credential directories.
+- Improved built-in tool guidance so agents use only tools advertised for the current turn and select code search, compacted-output retrieval, and structured clarification when appropriate.
+- Raised the minimum supported Ruby version from 3.2 to 3.4.
+
+### Fixed
+
+- Reject duplicate discovered tool names instead of silently replacing one MCP tool with another.
+- Fixed an RPC race where follow-up input could queue instead of steering a turn immediately after it began.
+- Prevented the RPC server from loading trusted Ruby plugins separately for plugin chats and workspace sessions, eliminating duplicate constant-definition warnings during startup.
+- Prevented `/reload` and RPC runtime reloads from emitting duplicate constant-definition warnings for plugin-defined constants.
+- Wrapped long side-by-side diff cells when editor soft wrap is enabled instead of clipping their contents.
+
+## [0.78.0] - 2026-07-15
+
+### Added
+
+- Added opt-in transcript-observer delivery for plugin-owned tabs, including RPC plugin chats, so local integrations such as text-to-speech can receive permitted streamed replies.
+- Added opt-in RPC support for plugin-owned chats, including explicit subscriptions, transcript snapshots, attachment-capable turns, event replay, and cancellation. Plugins remain disabled from this surface unless their tab type explicitly opts in.
+- Added plugin-owned tab types, opened with `/tab open <plugin-tab>`, with typed tab persistence and the normal interactive composer, transcript, streaming, and image-input behavior. Plugin tabs are CLI-only in this release and own their own storage rather than Kward sessions.
+- Added an opt-in permission policy for model-requested tools, with allow/ask/deny rules, read-only and workspace-write modes, write scopes, and interactive approval overlays. Permissions remain disabled by default and are not an OS sandbox.
+- Added a custom-response path to permission approval overlays: choosing `Type something` denies the requested tool call and returns the entered guidance to the agent.
+
+### Changed
+
+- Plugin-chat transcript RPC supports optional bounded, cursor-based pages for plugin drivers that opt in, avoiding full-history payloads for long-lived chats.
+- Code search now synchronizes mutable repository refs before every read and search, reports the resolved commit, and accepts GitHub blob URLs as file inputs.
+- Web and code research tools now cooperate with turn cancellation between requests, provider attempts, redirects, and repository scan files.
+- Kward-owned HTTP requests now identify themselves with `User-Agent: Kward/<version>`.
+
+### Fixed
+
+- Fixed `fetch_content` site navigation by preferring semantic main content over nested article cards, preserving inline and standalone link destinations, listing bounded discovered navigation links, and extracting ordered lists and simple tables.
+- Prevented duplicate session-backed tabs from restoring as mirrored conversations after restart.
+- Fixed `fetch_content` on documentation pages with large scripts or metadata before the main content by separating bounded page downloads from extracted output limits; plain-text extraction now parses HTML instead of returning cleaned markup.
+- Fixed raw fetches so their response limit is enforced while reading the network body.
+- Fixed stale code-search reads and searches by treating cached repositories as reusable local storage rather than authoritative snapshots.
+- Restored GPT-5.6 Luna requests through Codex with a scoped Responses Lite compatibility workaround; normal Codex requests retain Kward's own identity.
+
 ## [0.77.0] - 2026-07-11
 
 ### Added

data/Gemfile.lock

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

data/README.md

@@ -1,8 +1,8 @@
 # Kward
 
-Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run confirmed shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.
+Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run local shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.
 
-It currently supports the OpenAI/ChatGPT Codex backend, Anthropic Claude Pro/Max subscription, OpenRouter, and experimental Copilot provider support.
+It supports the OpenAI/ChatGPT Codex backend, Anthropic Claude Pro/Max subscription, OpenRouter, experimental Copilot provider support, and OpenAI-compatible local servers such as Ollama, LM Studio, and llama.cpp.
 
 ## Why use Kward?
 
@@ -76,6 +76,8 @@ Start here:
 - [Configuration](doc/configuration.md): config files, providers, models, web search, logging, and color output.
 - [Authentication](doc/authentication.md): OpenAI OAuth, Anthropic OAuth, OpenRouter API keys, and Copilot/GitHub setup.
 - [Security and trust](doc/security.md): local permissions, external data flow, trusted extensions, and safe work in unfamiliar repositories.
+- [Permissions](doc/permissions.md): opt-in tool approval, write scopes, policy rules, and current limits.
+- [Command sandboxing](doc/sandboxing.md): opt-in OS-enforced boundaries for model-requested shell commands.
 - [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
 
 Feature guides:
@@ -92,6 +94,7 @@ Feature guides:
 - [Skills](doc/skills.md): add reusable instructions that load only for matching tasks.
 - [MCP servers](doc/mcp.md): connect trusted local Model Context Protocol tool servers.
 - [Pan mode](doc/pan.md): use the mobile-friendly browser interface on a trusted local network.
+- [Local models](doc/local-models.md): connect Ollama, LM Studio, or llama.cpp and use a minimal replacement prompt.
 
 Advanced:
 

data/doc/agent-tools.md

@@ -38,7 +38,7 @@ This lets the assistant reason from focused evidence while preserving access to
 
 ## How tools are exposed
 
-`Kward::ToolRegistry` builds the available tool objects and the schemas advertised to the model. Some tools are always available in normal CLI/RPC sessions, while others depend on configuration or frontend capability:
+`Kward::ToolRegistry` builds the available tool objects and the schemas advertised to the model. Kward instructs models to call only tools advertised for the current turn; a restricted RPC turn therefore receives schemas only for its selected set. Some tools are always available in normal CLI/RPC sessions, while others depend on configuration or frontend capability:
 
 - web tools can be hidden with web search configuration,
 - `read_skill` is advertised only when skills are available,

data/doc/code-search.md

@@ -85,9 +85,9 @@ The tool uses an `action` parameter:
 | --- | --- |
 | `package_search` | find package metadata and likely source repositories. |
 | `github_search` | search public GitHub repositories. |
-| `repo_clone` | clone a GitHub repository into cache. |
-| `repo_search` | search files in a cached repository. |
-| `repo_read` | read a bounded line range from a cached file. |
+| `repo_clone` | prewarm the local Git repository store. |
+| `repo_search` | synchronize and search files in a repository. |
+| `repo_read` | synchronize and read a bounded line range from a file. |
 | `list_cache` | show cached repositories. |
 | `refresh_cache` | fetch updates for a cached repository. |
 | `clear_cache` | remove a cached repository. |
@@ -99,13 +99,16 @@ The tool uses an `action` parameter:
 | `package_search` | `ecosystem`, `package` | — |
 | `github_search` | `query` | `ecosystem`, `max_results` |
 | `repo_clone` | `repo` | — |
-| `repo_search` | `repo`, `query` | `max_results`, `context_lines` |
-| `repo_read` | `repo`, `path` | `start_line`, `line_count` |
+| `repo_search` | `repo`, `query` | `ref`, `max_results`, `context_lines` |
+| `repo_read` | `repo` | `path`, `ref`, `start_line`, `line_count` |
 | `list_cache` | — | — |
 | `refresh_cache` | `repo` | — |
 | `clear_cache` | `repo` | — |
 
-- `repo` is a GitHub URL or `owner/name`.
+- `repo` is a GitHub URL or `owner/name`. A GitHub `blob` URL can supply the file path and ref for `repo_read`.
+- `ref` selects a branch, tag, or commit. Mutable refs are fetched before every read or search; without `ref`, Kward synchronizes the remote default branch.
+- Successful reads and searches report the exact commit revision used. The local Git store reduces repeated downloads but is never silently treated as current source.
+- If synchronization fails, Kward returns an error instead of silently answering from stale files.
 - `query` is a plain-text search string (not regex). Matching is case-sensitive substring.
 - `start_line` is 1-indexed.
 - `context_lines` controls how many lines before and after a match are included in search snippets.

data/doc/configuration.md

@@ -15,6 +15,7 @@ If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as
 | Change editor, diff, overlay, or session UI behavior | `/settings` → Interface |
 | Enable memory | `/settings` → Memory |
 | Configure web search or trust project skills | `/settings` → Tools & Search |
+| Contain model-requested shell commands | `/sandbox` for mode and child-network access; edit config for additional writable roots |
 | Tune compaction | `/settings` → Context & Compaction |
 | Configure personas | `/settings` → Personalization; see [Personas](personas.md) |
 | Add MCP servers, lifecycle hooks, or environment-specific paths | Edit `config.json` directly |
@@ -161,6 +162,7 @@ Supported values are:
 - `anthropic` for Anthropic Claude Pro/Max subscription support.
 - `openrouter` for OpenRouter.
 - `copilot` for experimental Copilot provider support.
+- `local` for an OpenAI-compatible Ollama, LM Studio, or llama.cpp server. See [Local models](local-models.md).
 
 Model settings:
 
@@ -171,6 +173,7 @@ Model settings:
   "openrouter_model": "openai/gpt-5.6-sol",
   "anthropic_model": "claude-sonnet-5",
   "copilot_model": "gpt-5-mini",
+  "local_model": "qwen2.5-coder:7b",
   "reasoning_effort": "medium",
   "openai_reasoning_effort": "medium",
   "openrouter_reasoning_effort": "medium",
@@ -184,6 +187,8 @@ Model settings:
 
 Set `codex_show_raw_reasoning` to `true` to display raw Codex `reasoning_text` when the API does not provide reasoning summary text. It defaults to `false`; raw reasoning can include internal or unstable model output, so enable it only when you explicitly want to inspect that stream.
 
+`stream_idle_timeout_seconds` limits how long a streamed Codex, Anthropic, or Local response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
+
 Defaults:
 
 - OpenAI/Codex: `gpt-5.6-sol`
@@ -196,6 +201,24 @@ The Anthropic model choices include `claude-fable-5`, but Fable availability dep
 
 The interactive `/model` picker reads cached OpenRouter models when available. Run `kward openrouter refresh` to fetch text-capable models available to the configured OpenRouter API key and cache them under `~/.kward/cache/openrouter_models.json`. Run `kward openrouter list` to inspect the cached model ids.
 
+### Local model server
+
+The `local` provider uses OpenAI-compatible Chat Completions and model-list endpoints. Configure a running local server with a model id and its actual context window:
+
+```json
+{
+  "provider": "local",
+  "local_backend": "ollama",
+  "local_base_url": "http://127.0.0.1:11434/v1",
+  "local_model": "qwen2.5-coder:7b",
+  "local_context_window": 32768
+}
+```
+
+`local_backend` selects a convenience default: `ollama`, `lm_studio`, or `llama_cpp`. Their default base URLs are `http://127.0.0.1:11434/v1`, `http://127.0.0.1:1234/v1`, and `http://127.0.0.1:8080/v1`, respectively. Set `local_base_url` to use a custom endpoint. `local_api_key` is optional and is sent as a bearer token only when configured.
+
+Set `local_context_window` to the context length configured for the loaded model. Kward does not infer this safely from an arbitrary local model name; without it, automatic context budgeting cannot report a reliable limit. Local providers do not expose Kward reasoning or image controls by default.
+
 ## Environment overrides
 
 Use environment variables for one-off runs or local secrets that you do not want in config.
@@ -207,6 +230,11 @@ Provider and model:
 - `OPENAI_REASONING_EFFORT`
 - `OPENROUTER_MODEL`
 - `OPENROUTER_REASONING_EFFORT`
+- `KWARD_LOCAL_BACKEND`
+- `KWARD_LOCAL_BASE_URL`
+- `KWARD_LOCAL_MODEL`
+- `KWARD_LOCAL_CONTEXT_WINDOW`
+- `KWARD_LOCAL_API_KEY`
 - `ANTHROPIC_MODEL`
 - `ANTHROPIC_REASONING_EFFORT`
 - `COPILOT_MODEL`
@@ -500,6 +528,31 @@ Do not put shared or published API keys in this file.
 
 Put global engineering principles in `PRINCIPLES.md` beside your config file, usually `~/.kward/PRINCIPLES.md`. Kward appends this file to its built-in system instructions when present. Existing config-directory `AGENTS.md` files are still read as a legacy alias when `PRINCIPLES.md` is absent.
 
+## Replacement system prompt
+
+Set `system_prompt.file` to use a file as the entire system prompt. In replacement mode Kward does not append its built-in instructions, global principles, memory context, personas, plugin context, skills, or workspace `AGENTS.md` guidance.
+
+```json
+{
+  "system_prompt": {
+    "file": "prompts/local-minimal.md",
+    "include_principles": false
+  }
+}
+```
+
+Relative paths are resolved beside `config.json`. The file is sent to the configured model and can be recorded in session prompt snapshots, so do not place secrets in it. Use `kward sysprompt` to inspect the exact active prompt.
+
+To retain Kward's normal prompt while omitting only global `PRINCIPLES.md` (and its legacy config-directory `AGENTS.md` fallback), configure:
+
+```json
+{
+  "system_prompt": {
+    "include_principles": false
+  }
+}
+```
+
 ## Workspace AGENTS.md
 
 By default, Kward does not inject the full workspace `AGENTS.md` into every request. When a workspace `AGENTS.md` exists, Kward injects a compact instruction telling the model to read it for repository-related tasks before analyzing or modifying project files.
@@ -526,7 +579,59 @@ Workspace guardrails are enabled by default. File tools such as `read_file`, `wr
 }
 ```
 
-This is not a sandbox setting. Shell commands already run as your OS user from the workspace directory and can access anything that user can access.
+This is not a sandbox setting. File guardrails constrain Kward file tools, not arbitrary shell commands. See [Command sandboxing](sandboxing.md) to apply an opt-in operating-system boundary to model-requested `run_shell_command` workers.
+
+## Command sandboxing
+
+Sandboxing is off by default. Use `/sandbox` to inspect or change the mode and child-network access. For additional writable roots or Git metadata protection, edit the `sandbox` config directly. `sandbox.mode` accepts `off`, `read_only`, or `workspace_write`; `sandbox.network` defaults to `deny`, and `sandbox.protect_git_metadata` defaults to `true`.
+
+```json
+{
+  "sandbox": {
+    "mode": "workspace_write",
+    "network": "deny"
+  }
+}
+```
+
+When Kward cannot enforce a requested non-off mode, it denies the command rather than running it unrestricted. Current support and limits are documented in [Command sandboxing](sandboxing.md).
+
+## Permissions
+
+Permissions are off by default. When enabled, Kward evaluates model-requested tools before execution. This is a permission policy, not an operating-system sandbox: permitted shell commands still run with your user account's access.
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "ask"
+  }
+}
+```
+
+Available modes are:
+
+| Mode | Behavior |
+| --- | --- |
+| `ask` | Read-only tools run normally; file changes, shell commands, web tools, and MCP tools need approval. |
+| `workspace-write` | File changes within `write_scopes` run without approval; shell and network tools still need approval. |
+| `read-only` | Denies file changes, shell commands, web tools, and MCP tools. |
+| `deny-by-default` | Denies risky tools unless an `allow` rule matches. |
+
+`allow`, `ask`, and `deny` rules are arrays of objects matching `tool`, `path`, `host`, `command`, or `source`. Deny rules always take precedence, then ask, then allow. Use `write_scopes` to restrict writes in `workspace-write` mode:
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "workspace-write",
+    "write_scopes": ["lib/**", "test/**"],
+    "deny": [{ "tool": "run_shell_command", "command": "git push*" }]
+  }
+}
+```
+
+The interactive CLI presents an approval overlay for an `ask` decision. RPC clients can use their existing `approvalMode: "ask"` bridge. Frontends without an approval bridge, including Pan, fail closed for policy approvals.
 
 ## Logging and stats
 

data/doc/extensibility.md

@@ -43,6 +43,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:

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.
 

data/doc/local-models.md

@@ -0,0 +1,130 @@
+# Local models
+
+Kward can connect to a local model server that provides OpenAI-compatible Chat Completions. This is useful when you want offline development, control over model selection, or a smaller prompt for a local coding model.
+
+Kward connects to an already-running server. It does not install runtimes, download models, choose GPU settings, or load models for you.
+
+## 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.