@knightcodeai/cli-linux-x64 0.9.1 → 0.9.3

package/bin/docs/usage.md

@@ -1,342 +1,135 @@
-# Using KnightCode
-
-This page collects day-to-day usage details that do not fit on the quickstart page.
-
-## Interactive Mode
-
-<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
-
-The interface has four main areas:
-
-- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
-- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
-- **Editor** - where you type; border color indicates the current thinking level
-- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
-
-The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
-
-### Editor Features
-
-| Feature | How |
-|---------|-----|
-| File reference | Type `@` to fuzzy-search project files |
-| Path completion | Press Tab to complete paths |
-| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
-| Copy response | Ctrl+X copies the selected message in `/tree`; otherwise it copies the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled, falling back to the last assistant message |
-| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
-| Shell command | `!command` runs and sends output to the model |
-| Hidden shell command | `!!command` runs without sending output to the model |
-| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
-
-See [Keybindings](keybindings.md) for all shortcuts and customization.
-
-## Slash Commands
-
-Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
-
-| Command | Description |
-|---------|-------------|
-| `/login`, `/logout` | Manage OAuth or API-key credentials |
-| [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
-| `/model` | Switch models; Ctrl+S or Ctrl+D in the picker saves the startup default |
-| `/thinking` | Switch thinking level; Ctrl+S or Ctrl+D in the picker saves the startup default |
-| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
-| `/settings` | Theme, message delivery, transport, and other preferences |
-| [`/tools`](#web-tools) | Turn `webfetch` and `websearch` off, on for this session, or on by default; pick the search provider and store its key |
-| `/resume` | Pick from previous sessions |
-| `/new` | Start a new session |
-| `/name <name>` | Set session display name |
-| `/session` | Show session file, ID, messages, tokens, and cost |
-| `/tree` | Jump to any point in the session and continue from there |
-| `/undo` | Go back to an earlier user message; optionally restore the files edited after it |
-| `/trust` | Save project trust decision for future sessions |
-| `/fork` | Create a new session from a previous user message |
-| `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
-| `/copy` | Copy last assistant message to clipboard |
-| `/export [file]` | Export session to HTML or JSONL |
-| `/import <file>` | Import and resume a session from a JSONL file |
-| `/share` | Upload as private GitHub gist with shareable HTML link |
-| `/bug [description]` | Report a bug to the KnightCode developers; see [Sessions](sessions.md#reporting-bugs) |
-| `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
-| `/hotkeys` | Show all keyboard shortcuts |
-| `/changelog` | Display version history |
-| `/quit` | Quit knightcode |
+# Use KnightCode in the terminal
 
-## Web Tools
-
-Two tools give the agent read access to the web. Both ship disabled; turn them on with `/tools`.
-
-| Tool | What it does |
-|------|--------------|
-| `webfetch` | Fetches a URL and returns the page as markdown, 400 lines at a time. The agent pages with `offset`/`limit` like `read`, or passes `grep` to get only matching lines. Responses are cached for 15 minutes, capped at 5 MB, and time out after 30 seconds. Private, loopback, and link-local addresses are refused. |
-| `websearch` | Searches the web and returns up to 10 results (default 5) as title, URL, and snippet. DuckDuckGo needs no key but may rate-limit; Brave Search needs an API key. |
-
-`/tools` lists each tool with its current state; pick one to open its settings panel. **Status** cycles through three states:
-
-| State | Effect |
-|-------|--------|
-| Disabled | The tool is not offered to the model |
-| Enabled for this session | On until knightcode exits, including across `/new`, `/resume`, and `/fork`; nothing is written to disk |
-| Enabled by default | On in every session |
-
-The `websearch` panel adds two rows: **Provider** (`duckduckgo` or `brave`) and **Brave API key**. Choosing Brave without a stored key opens the key prompt at once. Get a key at https://brave.com/search/api/; the free plan is enough. The key is also read from `BRAVE_API_KEY` when none is stored, but the provider only switches to Brave when you pick it. Keys show masked in the panel.
-
-The same changes work without the panel:
-
-```bash
-/tools websearch on        # this session
-/tools webfetch always     # every session
-/tools webfetch off
-```
+Run `knightcode` from the folder you want to work in. KnightCode uses that folder to discover files, instructions, and configuration, and to group saved sessions. If you have not installed KnightCode or chosen a model yet, follow the [Quickstart](quickstart.md).
 
-Settings are stored in `~/.knightcode/agent/tools.json`, owner-readable only because it can hold the Brave key. `--tools` and `--exclude-tools` still apply: a tool excluded on the command line stays off whatever `/tools` says.
-
-Fetched pages and search results are marked as untrusted in the tool output so the model treats instructions inside them as data, but treat the tools like any other network access: a fetched page can still influence what the agent does next.
+KnightCode may ask whether you trust the working folder before loading its project resources. See [Project trust](security.md#understand-project-trust).
 
-## Message Queue
+<p align="center"><img src="images/interactive-mode.png" alt="KnightCode interactive mode showing a conversation, editor, and status information" width="750"></p>
 
-You can submit messages while the agent is still working:
+The transcript shows your prompts, KnightCode's responses, tool calls, results, and errors. You write prompts and commands in the editor. The footer shows the current folder, session, model, context usage, and accumulated usage and cost.
 
-- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
-- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
-- **Escape** aborts and restores queued messages to the editor.
-- **Alt+Up** retrieves queued messages back to the editor.
+## Enter a prompt
 
-On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want knightcode to receive the shortcut.
-
-Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
-
-## Sessions
-
-Sessions are saved automatically to `~/.knightcode/agent/sessions/`, organized by working directory.
-
-```bash
-knightcode -c                  # Continue most recent session
-knightcode -r                  # Browse and select a session
-knightcode --no-session        # Ephemeral mode; do not save
-knightcode --name "my task"    # Set session display name at startup
-knightcode --session <path|id> # Use a specific session file or session ID
-knightcode --fork <path|id>    # Fork a session into a new session file
-```
-
-Useful session commands:
-
-- `/session` shows the current session file and ID.
-- `/tree` navigates the in-file session tree and can summarize abandoned branches.
-- `/undo` goes back to an earlier user message and can restore the files edited after it.
-- `/fork` creates a new session from an earlier user message.
-- `/clone` duplicates the current active branch into a new session file.
-- `/compact` summarizes older messages to free context.
+Type a request and press `Enter` to send it. Use `Shift+Enter` to add a line, or press `Ctrl+G` to work on a longer prompt in your configured external editor.
 
-See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+To include files or images:
 
-## Context Files
+- Type `@` to search for a file and add it to your prompt.
+- Press `Tab` to complete a path.
+- Paste an image or drag it into a compatible terminal.
 
-KnightCode loads `AGENTS.md` or `CLAUDE.md` at startup from:
+## Follow KnightCode's work
 
-- `~/.knightcode/agent/AGENTS.md` for global instructions
-- parent directories, walking up from the current working directory
-- the current directory
+KnightCode shows each tool call and result while it works. Press `Ctrl+O` to expand or collapse tool output. Press `Ctrl+T` to show or hide thinking blocks.
 
-If a directory contains `AGENTS.override.md`, KnightCode loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
+The startup header lists the instructions and resources KnightCode loaded. The editor border indicates the current thinking level. The footer updates as the model uses context and reports usage.
 
-Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+KnightCode does not ask before every tool call. Review commands and changed files, and use a sandbox for untrusted or unattended work. See [Security](security.md).
 
-### System Prompt Files
+## Change direction
 
-Replace the default system prompt with:
+You can send more input while KnightCode is working:
 
-- `.knightcode/SYSTEM.md` for a project
-- `~/.knightcode/agent/SYSTEM.md` globally
+| What you want | Action |
+|---|---|
+| Adjust the current task | Type a message and press `Enter` |
+| Add work after the current task | Type a message and press `Alt+Enter` |
+| Return queued messages to the editor | Press `Alt+Up` |
+| Stop the current task | Press `Escape` |
 
-Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+A message sent with `Enter` waits until the current response and its tool calls finish, then guides the next response. A follow-up sent with `Alt+Enter` waits until KnightCode finishes the current task. Aborting returns queued messages to the editor.
 
-### Project Trust
+Windows Terminal reserves some Alt shortcuts. See [Terminal Setup](terminal-setup.md) for the Windows alternatives.
 
-On interactive startup, knightcode asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.knightcode/agent/trust.json`. Trusting a project allows knightcode to load `.knightcode/settings.json` and `.knightcode` resources, install missing project packages, and execute project extensions.
+## Change the model or settings
 
-Before the trust decision, knightcode loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
+Type `/` to search the available commands. The commands you will use most often are:
 
-Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+- `/model` selects a model. Press `Ctrl+L` to open the same selector.
+- `/thinking` selects how much reasoning the current model uses. Press `Shift+Tab` to cycle through supported levels.
+- `/login` and `/logout` manage provider access.
+- `/settings` changes common preferences.
+- `/tools` turns the [web tools](#web-tools) and the [scratchpad](#scratchpad) off, on for this session, or on by default.
 
-If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.knightcode/agent/settings.json`, or change it with `/settings`.
+Prompt templates, skills, and extensions can add more commands to the same menu. See [Choose a Model](models.md), [Configuration](configuration.md), or the complete [Slash Commands reference](slash-commands.md).
 
-`knightcode config` and package commands use the same project trust flow, except `knightcode update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
+## Continue or start over
 
-Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.knightcode/agent/trust.json` only; the current session is not reloaded, so restart knightcode for changes to take effect.
+KnightCode saves sessions automatically unless session persistence is disabled.
 
+- `/new` starts a new session.
+- `/resume` opens another saved session.
+- `/name` gives the current session a recognizable name.
+- `/session` shows its file, ID, message count, token usage, and cost.
+- `/undo` goes back to an earlier user message and can restore the files edited after it.
 
-## Exporting and Sharing Sessions
-
-Use `/export [file]` to write a session to HTML.
-
-Use `/share` to upload a private GitHub gist with a shareable HTML link.
-
-## CLI Reference
-
-```bash
-knightcode [options] [--] [@files...] [messages...]
-```
-
-### Package Commands
-
-```bash
-knightcode install <source> [-l]     # Install package, -l for project-local
-knightcode remove <source> [-l]      # Remove package
-knightcode uninstall <source> [-l]   # Alias for remove
-knightcode update [source|self|knightcode]   # Update knightcode only, or one package source
-knightcode update --all              # Update knightcode and packages; reconcile pinned git refs
-knightcode update --extensions       # Update packages only; reconcile pinned git refs
-knightcode update --models           # Refresh model catalogs only
-knightcode update --self             # Update knightcode only
-knightcode update --extension <src>  # Update one package
-knightcode list                      # List installed packages
-knightcode config                    # Enable/disable package resources
-```
-
-These commands manage knightcode packages and `knightcode update` can update the knightcode CLI installation. To uninstall knightcode itself, see [Quickstart](quickstart.md#uninstall). `knightcode config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `knightcode update` never prompts for project trust.
-
-See [KnightCode Packages](packages.md) for package sources and security notes.
+Use `/tree`, `/fork`, or `/clone` when you want to explore another approach without losing existing work. Use `/compact` to reduce the conversation history sent to the model. See [Sessions and Context](sessions.md) for these workflows.
 
-### Modes
+After leaving KnightCode, run `knightcode --continue` from the same folder to resume its most recent session.
 
-| Flag | Description |
-|------|-------------|
-| default | Interactive mode |
-| `-p`, `--print` | Print response and exit |
-| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
-| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
-| `--export <in> [out]` | Export a session to HTML |
+## Run a terminal command
 
-In print mode, knightcode also reads piped stdin and merges it into the initial prompt:
+Prefix a command with `!` to run it and include its output in the conversation:
 
-```bash
-cat README.md | knightcode -p "Summarize this text"
+```text
+!git status
 ```
 
-### Model Options
-
-| Option | Description |
-|--------|-------------|
-| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
-| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
-| `--api-key <key>` | API key, overriding environment variables |
-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
-| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
-| `--list-models [search]` | List available models |
-
-### Session Options
-
-| Option | Description |
-|--------|-------------|
-| `-c`, `--continue` | Continue the most recent session |
-| `-r`, `--resume` | Browse and select a session |
-| `--session <path\|id>` | Use a specific session file or partial UUID |
-| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
-| `--session-dir <dir>` | Custom session storage directory |
-| `--no-session` | Ephemeral mode; do not save |
-| `--name <name>`, `-n <name>` | Set session display name at startup |
-
-### Tool Options
-
-| Option | Description |
-|--------|-------------|
-| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
-| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, extension, and custom tools |
-| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
-| `--no-tools`, `-nt` | Disable all tools |
-
-Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`. The [web tools](#web-tools) `webfetch` and `websearch` are off until enabled with `/tools`.
-
-### Resource Options
-
-| Option | Description |
-|--------|-------------|
-| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
-| `--no-extensions` | Disable extension discovery |
-| `--skill <path>` | Load a skill; repeatable |
-| `--no-skills` | Disable skill discovery |
-| `--prompt-template <path>` | Load a prompt template; repeatable |
-| `--no-prompt-templates` | Disable prompt template discovery |
-| `--theme <path>` | Load a theme; repeatable |
-| `--no-themes` | Disable theme discovery |
-| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
-
-Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+Use `!!` when you want to run a command without sending its output to the model.
 
-```bash
-knightcode --no-extensions -e ./my-extension.ts
-```
+## Web Tools
 
-### Other Options
+Two tools give the agent read access to the web. Both ship disabled; turn them on with `/tools`.
 
-| Option | Description |
-|--------|-------------|
-| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
-| `--append-system-prompt <text>` | Append to system prompt |
-| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
-| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
-| `--verbose` | Force verbose startup |
-| `-a`, `--approve` | Trust project-local files for this run |
-| `-na`, `--no-approve` | Ignore project-local files for this run |
-| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
-| `-h`, `--help` | Show help |
-| `-v`, `--version` | Show version |
+| Tool | What it does |
+|------|--------------|
+| `webfetch` | Fetches a URL and returns the page as markdown, 400 lines at a time. The agent pages with `offset`/`limit` like `read`, or passes `grep` to get only matching lines. Responses are cached for 15 minutes, capped at 5 MB, and time out after 30 seconds. Private, loopback, and link-local addresses are refused. |
+| `websearch` | Searches the web and returns up to 10 results (default 5) as title, URL, and snippet. DuckDuckGo needs no key but may rate-limit; Brave Search needs an API key. |
 
-In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, knightcode uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. Text selection differs between the two modes: fullscreen captures the mouse and owns selection, so dragging copies to the clipboard on release, while regular mode never captures the mouse and leaves both selecting and copying to the terminal emulator. See [Text selection and copy](terminal-setup.md#text-selection-and-copy) for the per-terminal shortcuts, and [Terminal setup](terminal-setup.md) for other terminal-specific settings and workarounds.
+`/tools` lists each tool with its current state; pick one to open its settings panel. **Status** cycles through three states:
 
-Set **TUI mode** in `/settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
+| State | Effect |
+|-------|--------|
+| Disabled | The tool is not offered to the model |
+| Enabled for this session | On until knightcode exits, including across `/new`, `/resume`, and `/fork`; nothing is written to disk |
+| Enabled by default | On in every session |
 
-### File Arguments
+The `websearch` panel adds two rows: **Provider** (`duckduckgo` or `brave`) and **Brave API key**. Choosing Brave without a stored key opens the key prompt at once. Get a key at https://brave.com/search/api/; the free plan is enough. The key is also read from `BRAVE_API_KEY` when none is stored, but the provider only switches to Brave when you pick it. Keys show masked in the panel.
 
-Prefix files with `@` to include them in the message:
+The same changes work without the panel:
 
 ```bash
-knightcode @prompt.md "Answer this"
-knightcode -p @screenshot.png "What's in this image?"
-knightcode @code.ts @test.ts "Review these files"
+/tools websearch on        # this session
+/tools webfetch always     # every session
+/tools webfetch off
 ```
 
-### Examples
+Settings are stored in `~/.knightcode/agent/tools.json`, owner-readable only because it can hold the Brave key. `--tools` and `--exclude-tools` still apply: a tool excluded on the command line stays off whatever `/tools` says.
 
-```bash
-# Interactive with initial prompt
-knightcode "List all .ts files in src/"
+Fetched pages and search results are marked as untrusted in the tool output so the model treats instructions inside them as data, but treat the tools like any other network access: a fetched page can still influence what the agent does next.
 
-# Non-interactive
-knightcode -p "Summarize this codebase"
+## Scratchpad
 
-# Prompt beginning with a dash
-knightcode -p -- "- Summarize these points"
+`/tools scratchpad on` gives each session a private working directory under the system temp directory (`<tmp>/knightcode-<uid>/scratchpad/<session-id>`, or `<tmp>\knightcode\scratchpad\<session-id>` on Windows). The system prompt names it and asks the agent to put throwaway scripts and intermediate output there instead of in your project.
 
-# Non-interactive with piped stdin
-cat README.md | knightcode -p "Summarize this text"
+The agent keeps its working notes there in `notes.md`: task list, decisions, `file:line` facts, next steps. After each compaction the first 8 KB of `notes.md` is put back into the context once, so those notes outlive the summary. Open the file to see what the agent is tracking.
 
-# Named one-shot session
-knightcode --name "release audit" -p "Audit this repository"
+The scratchpad is off by default. When on, it adds about 60 tokens to the system prompt, which is cached; the notes cost tokens only after a compaction. It is not a tool, so `--tools` and `--exclude-tools` do not affect it. `/fork` starts a new, empty directory, and the operating system clears old ones with the rest of its temp files. If `<tmp>/knightcode-<uid>` already exists but is not a private directory you own, as when another user on a shared machine created it first, the scratchpad stays off and KnightCode reports why.
 
-# Different model
-knightcode --provider openai --model gpt-4o "Help me refactor"
+## Copy, export, or share results
 
-# Model with provider prefix
-knightcode --model openai/gpt-4o "Help me refactor"
+Press `Ctrl+X` or run `/copy` to copy the last assistant response. Use `/export` to save the session as HTML or JSONL.
 
-# Model with thinking level shorthand
-knightcode --model sonnet:high "Solve this complex problem"
+Use `/share` to upload the session and get a viewer link. With Radius authentication, the artifact is visible to your Radius organization. Otherwise, KnightCode creates a private GitHub gist through the GitHub CLI. Review the session first because it can contain prompts, tool output, file contents, and credentials exposed during the conversation.
 
-# Limit model cycling
-knightcode --models "claude-*,gpt-4o"
+## Adjust the terminal
 
-# Read-only mode
-knightcode --tools read,grep,find,ls -p "Review the code"
+Regular mode uses the terminal's normal scrollback. Fullscreen mode keeps the editor and status area fixed while the transcript scrolls within the terminal window. Choose a mode through `/settings` or `--tui-mode`.
 
-# Disable one extension or built-in tool while keeping the rest available
-knightcode --exclude-tools ask_question
-```
+Terminal support for mouse input, keyboard shortcuts, and inline images varies. See [Terminal Setup](terminal-setup.md) for platform-specific configuration and [Keybindings](keybindings.md) for every configurable shortcut. Run `/hotkeys` to inspect the shortcuts active in your current session.
 
-## Design Principles
+## Collect diagnostic information
 
-KnightCode keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+When troubleshooting terminal rendering or conversation state, run `/debug`. KnightCode writes the rendered terminal lines and current session messages to `knightcode-debug.log` in your [agent directory](configuration.md#agent-directory).
 
-It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+Review this file before sharing it. It can contain prompts, model responses, tool output, file contents, and terminal data.

package/bin/docs/windows.md

@@ -1,39 +1,65 @@
-# Windows Setup
+# Run KnightCode on Windows
 
-KnightCode uses Git Bash by default on Windows. Checked locations (in order):
+Run KnightCode either as a native Windows process or inside Windows Subsystem for Linux (WSL). Native Windows uses Git Bash by default for Bash commands and can optionally expose PowerShell to the model. KnightCode inside WSL uses the Linux environment and its Bash installation.
 
-1. Custom path from `~/.knightcode/agent/settings.json`
-2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
-3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+Follow the main [Quickstart](quickstart.md) to install and authenticate KnightCode. Use this page to choose and configure its command environment.
 
-For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+## Choose native Windows or WSL
 
-## PowerShell Tool
+| Environment | Command environment | Use it when |
+|---|---|---|
+| Native Windows with Git Bash | Git Bash for the built-in `bash` tool and `!` commands | Your files and development tools primarily live on Windows |
+| Native Windows with the `powershell` tool | PowerShell for model tool calls; Bash remains available for `!` commands | The task depends on PowerShell modules or Windows-native commands |
+| WSL | Linux Bash and tools inside the selected WSL distribution | Your files and toolchain already live in Linux or WSL |
 
-The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+## Use Git Bash on native Windows
 
-Use `defaultTools` to replace the model-facing `bash` tool:
+For most native Windows users, installing [Git for Windows](https://git-scm.com/download/win) is sufficient.
 
-```json
-{
-  "defaultTools": ["read", "powershell", "edit", "write"]
-}
+KnightCode resolves Bash in this order:
+
+1. `shellPath` from `~/.knightcode/agent/settings.json`
+2. Git Bash under `Program Files` or `Program Files (x86)`
+3. `bash.exe` on `PATH`, including Cygwin, MSYS2, or legacy WSL Bash
+
+Start KnightCode and enter this command to verify the shell:
+
+```text
+!printf 'Bash is working\n'
 ```
 
-Or enable both while comparing behavior:
+If KnightCode cannot find Bash, it reports the locations it checked. Install Git for Windows, put another Bash executable on `PATH`, or configure `shellPath`.
+
+## Let the model use PowerShell
+
+The optional `powershell` tool runs commands through `pwsh.exe` when available, then falls back to Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+
+To replace the model-facing `bash` tool with `powershell`, add this to `~/.knightcode/agent/settings.json`:
 
 ```json
 {
-  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
+  "defaultTools": ["read", "powershell", "edit", "write"]
 }
 ```
 
-The `!` and `!!` editor commands still use Bash.
+Restart KnightCode, then ask it to run a harmless PowerShell command. The `!` and `!!` editor commands continue to use Bash. The `powershell` tool is available only when KnightCode runs as a native Windows process.
+
+See [Settings](settings.md#tools) for other tool combinations.
+
+## Use a custom Bash executable
 
-## Custom Bash Path
+Set `shellPath` when Bash is installed somewhere KnightCode does not discover automatically:
 
 ```json
 {
   "shellPath": "C:\\cygwin64\\bin\\bash.exe"
 }
 ```
+
+JSON uses backslashes for escape sequences. When you write a Windows path with backslashes, write each backslash twice, as shown above.
+
+See [Configure shell commands](shell-aliases.md) for command prefixes, aliases, and the complete shell-resolution behavior.
+
+## Configure Windows Terminal
+
+Windows Terminal reserves or rewrites some modified keys. See [Windows Terminal](terminal-setup.md#windows-terminal) to configure `Shift+Enter` and `Alt+Enter`, and [Keybindings](keybindings.md) for KnightCode's Windows and WSL shortcut defaults.

package/bin/export-html/template.js

@@ -357,6 +357,9 @@
           case 'thinking_level_change':
             parts.push('thinking', entry.thinkingLevel);
             break;
+          case 'context_edit':
+            parts.push('context edit', entry.replacement === null ? 'omit' : 'replace', entry.targetId);
+            break;
         }
 
         return parts.join(' ').toLowerCase();
@@ -385,7 +388,7 @@
           }
 
           // Apply filter mode
-          const isSettingsEntry = ['label', 'custom', 'model_change', 'thinking_level_change'].includes(entry.type);
+          const isSettingsEntry = ['label', 'custom', 'context_edit', 'model_change', 'thinking_level_change'].includes(entry.type);
           let passesFilter = true;
 
           switch (filterMode) {
@@ -696,6 +699,8 @@
             return labelHtml + `<span class="tree-muted">[model: ${escapeHtml(entry.modelId)}]</span>`;
           case 'thinking_level_change':
             return labelHtml + `<span class="tree-muted">[thinking: ${escapeHtml(entry.thinkingLevel)}]</span>`;
+          case 'context_edit':
+            return labelHtml + `<span class="tree-muted">[context ${entry.replacement === null ? 'omit' : 'replace'}: ${escapeHtml(entry.targetId)}]</span>`;
           default:
             return labelHtml + `<span class="tree-muted">[${escapeHtml(entry.type)}]</span>`;
         }

package/bin/knightcode

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/knightcode
-size: 117581290 bytes
-sha256: 55b9ab58d9aa29d2bc21f39a279a44e92cb0f78d4b37bdd91f7907734d5a6d4b
+size: 117790736 bytes
+sha256: e9c9096d0b519543704dee054a87424bf55ea7feddbffc01ba03e06e172e3ff3

package/bin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "KnightCode — a local, BYOK terminal coding agent powered by OpenRouter.",
   "type": "module",
   "repository": {
@@ -37,11 +37,11 @@
     "test": "vitest --run"
   },
   "optionalDependencies": {
-    "@knightcodeai/cli-linux-x64": "0.9.1",
-    "@knightcodeai/cli-linux-arm64": "0.9.1",
-    "@knightcodeai/cli-darwin-x64": "0.9.1",
-    "@knightcodeai/cli-darwin-arm64": "0.9.1",
-    "@knightcodeai/cli-win32-x64": "0.9.1"
+    "@knightcodeai/cli-linux-x64": "0.9.3",
+    "@knightcodeai/cli-linux-arm64": "0.9.3",
+    "@knightcodeai/cli-darwin-x64": "0.9.3",
+    "@knightcodeai/cli-darwin-arm64": "0.9.3",
+    "@knightcodeai/cli-win32-x64": "0.9.3"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "1.4.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli-linux-x64",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "license": "MIT",
   "repository": {
     "type": "git",