@knightcodeai/cli-linux-x64 0.9.0 → 0.9.2

package/bin/docs/skills.md

@@ -1,231 +1,93 @@
-> knightcode can create skills. Ask it to build one for your use case.
-
 # Skills
 
-Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.
-
-KnightCode implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. KnightCode allows skill names to differ from their parent directory even though the standard disallows it; that rule is suboptimal for shared skill directories used across multiple agent harnesses.
-
-## Table of Contents
-
-- [Locations](#locations)
-- [How Skills Work](#how-skills-work)
-- [Skill Commands](#skill-commands)
-- [Skill Structure](#skill-structure)
-- [Frontmatter](#frontmatter)
-- [Validation](#validation)
-- [Example](#example)
-- [Skill Repositories](#skill-repositories)
-
-## Locations
-
-> **Security:** Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.
-
-KnightCode loads skills from:
-
-- Global:
-  - `~/.knightcode/agent/skills/`
-  - `~/.agents/skills/`
-- Project (only after the project is trusted):
-  - `.knightcode/skills/`
-  - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
-- Packages: `skills/` directories or `knightcode.skills` entries in `package.json`
-- Settings: `skills` array with files or directories
-- CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
-
-Discovery rules:
-- In `~/.knightcode/agent/skills/` and `.knightcode/skills/`, direct root `.md` files are discovered as individual skills when they have valid skill frontmatter with a non-empty `description`
-- In all skill locations, directories containing `SKILL.md` are discovered recursively
-- In `~/.agents/skills/` and project `.agents/skills/`, root `.md` files are ignored, but nested `.md` files in grouping folders are discovered when they declare skill frontmatter
-- Root Markdown files other than `SKILL.md` that do not look like skills are ignored silently
-
-Disable discovery with `--no-skills` (explicit `--skill` paths still load).
-
-### Using Skills from Other Harnesses
-
-To use skills from Claude Code or OpenAI Codex, add their directories to settings:
-
-```json
-{
-  "skills": [
-    "~/.claude/skills",
-    "~/.codex/skills"
-  ]
-}
-```
-
-For project-level Claude Code skills, add to `.knightcode/settings.json`:
-
-```json
-{
-  "skills": ["../.claude/skills"]
-}
-```
-
-## How Skills Work
-
-1. At startup, knightcode scans skill locations and extracts names and descriptions
-2. The system prompt includes available skills in XML format per the [specification](https://agentskills.io/integrate-skills)
-3. When a task matches, the agent uses `read`, or `bash` when `read` is unavailable, to load the full SKILL.md (models don't always do this; use prompting or `/skill:name` to force it)
-4. The agent follows the instructions, using relative paths to reference scripts and assets
-
-This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
-
-## Skill Commands
-
-Skills register as `/skill:name` commands:
-
-```bash
-/skill:brave-search           # Load and execute the skill
-/skill:pdf-tools extract      # Load skill with arguments
-```
-
-Arguments after the command are appended to the skill content as `User: <args>`.
+Skills give KnightCode specialized instructions and supporting files for a particular kind of work. KnightCode advertises each available skill by name and description, then loads its full instructions only when the task calls for them.
 
-Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
+Use a skill when a workflow needs more context than a prompt template but does not need a new executable integration point. Skills can bundle scripts, references, and assets alongside their instructions.
 
-```json
-{
-  "enableSkillCommands": true
-}
-```
+KnightCode implements the [Agent Skills specification](https://agentskills.io/specification). Most invalid fields produce warnings rather than stopping startup.
 
-## Skill Structure
+## Create a skill
 
-A skill is a directory with a `SKILL.md` file. Everything else is freeform.
+A skill is a directory containing `SKILL.md`:
 
-```
-my-skill/
-├── SKILL.md              # Required: frontmatter + instructions
-├── scripts/              # Helper scripts
-│   └── process.sh
-├── references/           # Detailed docs loaded on-demand
-│   └── api-reference.md
+```text
+pdf-tools/
+├── SKILL.md
+├── scripts/
+│   └── extract.sh
+├── references/
+│   └── formats.md
 └── assets/
     └── template.json
 ```
 
-### SKILL.md Format
+Start `SKILL.md` with frontmatter followed by direct instructions:
 
-````markdown
+```markdown
 ---
-name: my-skill
-description: What this skill does and when to use it. Be specific.
+name: pdf-tools
+description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
 ---
 
-# My Skill
+# PDF tools
 
-## Setup
-
-Run once before first use:
-```bash
-cd /path/to/skill && npm install
+Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.
 ```
 
-## Usage
-
-```bash
-./scripts/process.sh <input>
-```
-````
-
-Use relative paths from the skill directory:
-
-```markdown
-See [the reference guide](references/REFERENCE.md) for details.
-```
-
-## Frontmatter
-
-Per the [Agent Skills specification](https://agentskills.io/specification#frontmatter-required):
+The description determines when the model considers loading the skill. State both what the skill does and when it applies. Avoid descriptions such as “Helps with PDFs,” which do not provide enough routing information.
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. Unlike the standard, KnightCode does not require this to match the parent directory because that standard requirement is suboptimal for shared skill directories. |
-| `description` | Yes | Max 1024 chars. What the skill does and when to use it. |
-| `license` | No | License name or reference to bundled file. |
-| `compatibility` | No | Max 500 chars. Environment requirements. |
-| `metadata` | No | Arbitrary key-value mapping. |
-| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
-| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name`. |
+Use relative paths from the skill directory when referring to bundled files. KnightCode tells the model where the skill lives so it can resolve those paths.
 
-### Name Rules
+## Understand how skills load
 
-- 1-64 characters
-- Lowercase letters, numbers, hyphens only
-- No leading/trailing hyphens
-- No consecutive hyphens
-KnightCode does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories used by multiple tools.
+At startup, KnightCode scans configured skill locations and adds each skill’s name, description, and path to the system prompt. It does not add the full instructions.
 
-Valid: `pdf-processing`, `data-analysis`, `code-review`
-Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
+When a task matches, the model reads `SKILL.md` and follows its instructions. This keeps detailed guidance out of context until it is needed. A model might fail to load a relevant skill, so use `/skill:name` when you need to force it.
 
-### Description Best Practices
+Arguments after `/skill:name` are appended to the loaded instructions as a user request:
 
-The description determines when the agent loads the skill. Be specific.
-
-Good:
-```yaml
-description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
-```
-
-Poor:
-```yaml
-description: Helps with PDFs.
+```text
+/skill:pdf-tools extract report.pdf
 ```
 
-## Validation
+Set `disable-model-invocation: true` in frontmatter when a skill should be available only through its explicit command. The `enableSkillCommands` [setting](settings.md) controls whether skill commands appear in interactive command discovery; manually entered `/skill:name` commands still work.
 
-KnightCode validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:
+<a id="choose-where-it-loads"></a>
 
-- Name exceeds 64 characters or contains invalid characters
-- Name starts/ends with hyphen or has consecutive hyphens
-- Description exceeds 1024 characters
+## Add it to KnightCode
 
-Unknown frontmatter fields are ignored.
+Place the skill in your user or project skills directory. Directories containing `SKILL.md` are discovered recursively.
 
-Declared skills with missing descriptions are not loaded. Malformed `SKILL.md` files and `SKILL.md` files without a description produce warnings and are not loaded. Other Markdown files without valid skill frontmatter are ignored.
+KnightCode also supports the Agent Skills locations `~/.agents/skills/` and `.agents/skills/`. Project `.agents/skills/` directories are discovered from the working directory through its ancestors, stopping at the repository root when one exists.
 
-Name collisions (same name from different locations) warn and keep the first skill found.
+KnightCode accepts some standalone Markdown skills, but a directory containing `SKILL.md` is the portable form and should be preferred. See [Settings](settings.md#resources) and [KnightCode Packages](packages.md) for additional locations.
 
-## Example
-
-```
-brave-search/
-├── SKILL.md
-├── search.js
-└── content.js
-```
+Project skills can instruct the model to run scripts or modify files. Review unfamiliar skills and their supporting files before granting project trust.
 
-**SKILL.md:**
-````markdown
----
-name: brave-search
-description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
----
+## Write portable frontmatter
 
-# Brave Search
+The Agent Skills specification defines these fields:
 
-## Setup
+| Field | Purpose |
+|---|---|
+| `name` | Command and display name |
+| `description` | Routing description shown to the model |
+| `license` | License name or bundled license file |
+| `compatibility` | Environment requirements |
+| `metadata` | Additional key-value metadata |
+| `allowed-tools` | Experimental pre-approved tool list |
+| `disable-model-invocation` | Hide the skill from automatic model selection |
 
-```bash
-cd /path/to/brave-search && npm install
-```
+Names use lowercase letters, numbers, and hyphens, with no leading, trailing, or consecutive hyphens. They can contain at most 64 characters; descriptions can contain at most 1024.
 
-## Search
+KnightCode neither requires nor warns when the declared name differs from the parent directory. Other Agent Skills implementations may enforce that requirement, so matching names remain the portable choice.
 
-```bash
-./search.js "query"              # Basic search
-./search.js "query" --content    # Include page content
-```
+Malformed `SKILL.md` files and declared skills without descriptions are not loaded. Name collisions keep the first discovered skill and produce a warning.
 
-## Extract Page Content
+## Validate and share a skill
 
-```bash
-./content.js https://example.com
-```
-````
+Run KnightCode from a location where the skill is discoverable, then inspect the startup diagnostics and `/skill:name` command. Run `/reload` after editing a skill during an active session.
 
-## Skill Repositories
+Use a [KnightCode package](packages.md) to distribute one or more skills through npm or git. Keep environment setup inside the skill and declare any required runtime dependencies in the package.
 
-- [Anthropic Skills](https://github.com/anthropics/skills) - Document processing (docx, pdf, pptx, xlsx), web development
+For examples, see the [Anthropic skills collection](https://github.com/anthropics/skills).

package/bin/docs/slash-commands.md

@@ -0,0 +1,63 @@
+# Slash commands
+
+Type `/` in KnightCode's terminal editor to search the commands available in the current session. This page lists the built-in commands in the current KnightCode release.
+
+Extensions, prompt templates, and skills can add commands. The command menu in KnightCode is therefore the exact reference for the resources loaded in your session.
+
+## Models and settings
+
+| Command | Description |
+|---|---|
+| `/settings` | Open settings |
+| `/model [provider/model]` | Select a model |
+| `/thinking [level]` | Set the thinking level |
+| `/scoped-models` | Configure the models used by interactive cycling |
+| `/login [provider]` | Add provider authentication |
+| `/logout` | Remove provider authentication |
+| `/tools` | Turn `webfetch`, `websearch`, and the [scratchpad](usage.md#scratchpad) off, on for this session, or on by default; pick the search provider and store its key |
+| `/llama` | Manage models on the configured llama.cpp router |
+
+## Sessions and context
+
+| Command | Description |
+|---|---|
+| `/new` | Start a new session |
+| `/resume` | Switch to another saved session |
+| `/name [name]` | Set the session display name, or show the current name when omitted |
+| `/session` | Show current session information and statistics |
+| `/tree` | Navigate the session tree |
+| `/fork` | Create a new session from an earlier user message |
+| `/clone` | Duplicate the current session at its current position |
+| `/undo` | Go back to an earlier user message; optionally restore the files edited after it |
+| `/compact [instructions]` | Compact the current context, optionally with custom instructions |
+| `/import <path>` | Import and resume a JSONL session |
+
+## Export and share
+
+| Command | Description |
+|---|---|
+| `/copy` | Copy the last assistant message |
+| `/export [path]` | Export the session as HTML or JSONL |
+| `/share` | Upload the session and return a viewer link |
+| `/remote` | Publish this session to a live web link; see [Remote sessions](remote.md) |
+| `/bug [description]` | Prepare a private bug report for the KnightCode developers |
+
+Review a session before exporting or sharing it. Sessions can contain prompts, tool arguments, command output, file contents, and credentials exposed during the conversation.
+
+## Runtime and project
+
+| Command | Description |
+|---|---|
+| `/trust` | Save a project trust decision for future KnightCode processes |
+| `/reload` | Reload keybindings, extensions, skills, templates, themes, and context files |
+| `/hotkeys` | Show active keyboard shortcuts |
+| `/changelog` | Show changelog entries |
+| `/quit` | Quit KnightCode |
+
+## Commands added by resources
+
+- Extensions can register commands with their own arguments and completion behavior.
+- Each prompt template is available under its template name.
+- Skills are available as `/skill:name` when skill commands are enabled.
+
+Use `/reload` after adding or changing a discovered command resource. See [Extensions](extensions.md), [Prompt Templates](prompt-templates.md), and [Skills](skills.md) for their loading and naming rules.

package/bin/docs/terminal-setup.md

@@ -1,22 +1,27 @@
-# Terminal Setup
+# Configure your terminal
 
-KnightCode uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
+Most modern terminals work with KnightCode without additional setup. Use this page when modified keys, scrolling, links, images, colors, or input-method editor (IME) positioning do not behave as expected.
 
-## Capability Overrides
+KnightCode uses extended-key protocols so terminals can distinguish combinations such as `Shift+Enter` and `Alt+Enter` from plain `Enter`. Terminal proxies, multiplexers, and built-in IDE terminals can change or discard that information.
 
-KnightCode auto-detects OSC 8 hyperlinks, inline image protocols, and truecolor. If detection fails behind a terminal proxy or multiplexer, use these advanced overrides:
+## Troubleshooting
 
-| Capability | Environment variable | JSON setting |
-|------------|----------------------|--------------|
-| OSC 8 hyperlinks | `KNIGHTCODE_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
-| Inline images | `KNIGHTCODE_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
-| Truecolor | `KNIGHTCODE_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
+| Symptom | Start here |
+|---|---|
+| `Shift+Enter` submits instead of inserting a line | Your terminal's section below; for tmux, see [Run KnightCode in tmux](tmux.md) |
+| `Alt+Enter` does not queue a follow-up | [WezTerm](#wezterm), [Alacritty](#alacritty), or [Windows Terminal](#windows-terminal) |
+| Fullscreen scrolling is unusually slow | [iTerm2](#iterm2) |
+| Dragging does not copy text, or copies it unexpectedly | [Text Selection and Copy](#text-selection-and-copy) |
+| Links work but show no hover preview | [Ghostty](#ghostty) |
+| Inline images or colors are not detected | [Override detected capabilities](#override-detected-capabilities) |
+| An IME candidate window appears in the wrong place | [WezTerm](#wezterm) or [IntelliJ IDEA](#intellij-idea-integrated-terminal) |
+| Modified keys fail only inside tmux | [Run KnightCode in tmux](tmux.md) |
 
-Settings take precedence over environment variables; unset or `auto` preserves detection. Only force capabilities supported by the complete terminal path, since unsupported escape sequences can corrupt rendering.
+Use `/hotkeys` to inspect KnightCode's active shortcuts. See [Keybindings](keybindings.md) to change them.
 
 ## Text Selection and Copy
 
-Which side owns a mouse drag depends on the [TUI mode](usage.md#other-options).
+Which side owns a mouse drag depends on the [TUI mode](usage.md#adjust-the-terminal).
 
 In `fullscreen` mode, knightcode enables mouse reporting and owns text selection itself. Dragging with the primary button selects, and the selection is copied to the clipboard on release. Set `fullscreenCopyOnSelect` to `false` to keep the selection highlighted and copy it with `Ctrl+X` instead. To reach the terminal's own selection while knightcode captures the mouse, hold the terminal's bypass modifier — usually `Shift`, `Option` in iTerm2, and `Shift+Command`/`Shift+Ctrl` in Ghostty.
 
@@ -24,58 +29,55 @@ In `regular` mode, knightcode never enables mouse reporting, so a drag is the te
 
 ## Kitty
 
-Works out of the box.
+Kitty supports the required keyboard protocol without additional configuration.
 
 ## iTerm2
 
-### Regular TUI mode
-
-Works out of the box.
+Regular terminal mode works without additional configuration.
 
-### Fullscreen TUI mode
+### Fix slow fullscreen scrolling
 
-KnightCode owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling its native scrollback. With iTerm2's default fast-trackpad behavior, those reports can lose most of an accelerated wheel delta, making fullscreen scrolling much slower than regular scrolling.
+In fullscreen mode, KnightCode owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling native terminal history. Fast trackpad gestures can then move only about one line at a time.
 
-If fast mouse-wheel gestures move only about one line at a time in fullscreen mode:
+To change this behavior:
 
-1. Open **iTerm2 → Settings → Advanced**.
-2. Search for **Trackpad scrolls fast?** and set it to **No**.
+1. Open **iTerm2 > Settings > Advanced**.
+2. Search for **Trackpad scrolls fast?**.
+3. Set it to **No**.
 
-This is an iTerm2-wide workaround and may also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
+This is an iTerm2-wide setting and can also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
 
 ## Apple Terminal
 
-KnightCode enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, knightcode uses a local macOS modifier fallback to treat that Return as `Shift+Enter`.
+KnightCode enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, KnightCode uses a local macOS modifier fallback and treats it as `Shift+Enter`.
 
-This fallback only works when knightcode runs on the same Mac as Terminal.app. It cannot detect the local keyboard over remote SSH.
+The fallback works only when KnightCode runs on the same Mac as Terminal.app. It cannot inspect the local modifier state when KnightCode runs on another machine over SSH.
 
 ## Ghostty
 
-Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
+Add this mapping to Ghostty's configuration if `Alt+Backspace` does not work:
 
-```
+```text
 keybind = alt+backspace=text:\x1b\x7f
 ```
 
-Older Claude Code versions may have added this Ghostty mapping:
+The configuration file is `~/Library/Application Support/com.mitchellh.ghostty/config` on macOS and `~/.config/ghostty/config` on Linux.
 
-```
+Older Claude Code configurations may contain:
+
+```text
 keybind = shift+enter=text:\n
 ```
 
-That mapping sends a raw linefeed byte. Inside knightcode, that is indistinguishable from `Ctrl+J`, so tmux and knightcode no longer see a real `shift+enter` key event.
-
-If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.
-
-KnightCode binds `Ctrl+J` as a default newline alias, so `Shift+Enter` keeps working in tmux via that remap without extra knightcode configuration.
+This sends a raw linefeed, which KnightCode cannot distinguish from `Ctrl+J`. Remove the mapping if an older Claude Code installation is the only reason you added it. KnightCode already binds `Ctrl+J` as a newline alternative, so the mapping may appear to work while still preventing KnightCode and tmux from receiving a real `Shift+Enter` event.
 
-### Fullscreen TUI mode
+### Open links in fullscreen mode
 
-In fullscreen mode, links remain clickable, but Ghostty does not show its hover underline or lower-left URL preview while knightcode captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
+Links remain clickable in fullscreen mode, but Ghostty does not show its normal hover underline or URL preview while KnightCode captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
 
 ## WezTerm
 
-WezTerm usually works out of the box for `Shift+Enter` via xterm modifyOtherKeys. To use the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
+WezTerm normally reports `Shift+Enter` through xterm extended keys. To enable the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
 
 ```lua
 local wezterm = require 'wezterm'
@@ -84,7 +86,19 @@ config.enable_kitty_keyboard = true
 return config
 ```
 
-On macOS, WezTerm binds `Option+Enter` to fullscreen by default. To use `Option+Enter` for knightcode follow-up queueing, add this key override:
+### Forward Alt+Enter on macOS
+
+WezTerm binds `Option+Enter` to fullscreen by default on macOS. To use it for KnightCode's follow-up queue, add this entry to your `config.keys` table:
+
+```lua
+{
+  key = 'Enter',
+  mods = 'ALT',
+  action = wezterm.action.SendString('\x1b[13;3u'),
+}
+```
+
+A complete minimal configuration is:
 
 ```lua
 local wezterm = require 'wezterm'
@@ -99,13 +113,20 @@ config.keys = {
 return config
 ```
 
-If you already have a `config.keys` table, add the entry to it.
+### Position an IME candidate window in WSL
 
-On WSL, WezTerm may require a visible hardware cursor for IME candidate window positioning. If CJK IME candidates do not follow the text cursor, set `KNIGHTCODE_HARDWARE_CURSOR=1` before running knightcode or set `showHardwareCursor` to `true` in settings.
+If CJK IME candidates do not follow KnightCode's text cursor in WSL, show the hardware cursor:
+
+```bash
+export KNIGHTCODE_HARDWARE_CURSOR=1
+knightcode
+```
+
+You can instead set `showHardwareCursor` to `true` in KnightCode settings.
 
 ## Alacritty
 
-Alacritty usually works out of the box for `Shift+Enter`. On macOS, `Option+Enter` may arrive as plain `Enter`. To use `Option+Enter` for knightcode follow-up queueing, add to `~/.config/alacritty/alacritty.toml`:
+Alacritty normally reports `Shift+Enter`. On macOS, `Option+Enter` can arrive as plain `Enter`. Add this to `~/.config/alacritty/alacritty.toml` to forward it to KnightCode:
 
 ```toml
 [[keyboard.bindings]]
@@ -114,20 +135,13 @@ mods = "Alt"
 chars = "\u001b[13;3u"
 ```
 
-Restart Alacritty after changing the config.
-
-## VS Code (Integrated Terminal)
+Restart Alacritty after changing the file.
 
-VS Code 1.109.5 and newer enable Kitty keyboard protocol in the integrated terminal by default, so `Shift+Enter` should work out of the box.
+## VS Code integrated terminal
 
-VS Code versions older than 1.109.5 need an explicit terminal keybinding for `Shift+Enter`.
+VS Code 1.109.5 and newer enable the Kitty keyboard protocol in the integrated terminal by default.
 
-`keybindings.json` locations:
-- macOS: `~/Library/Application Support/Code/User/keybindings.json`
-- Linux: `~/.config/Code/User/keybindings.json`
-- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
-
-Add to `keybindings.json`:
+For an older version, add a `Shift+Enter` terminal binding to `keybindings.json`:
 
 ```json
 {
@@ -138,9 +152,15 @@ Add to `keybindings.json`:
 }
 ```
 
-## Zed (Integrated Terminal)
+The user `keybindings.json` file is normally located at:
+
+- macOS: `~/Library/Application Support/Code/User/keybindings.json`
+- Linux: `~/.config/Code/User/keybindings.json`
+- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
 
-Add these key bindings to your Zed `keymap.json`:
+## Zed integrated terminal
+
+Add these bindings to Zed's `keymap.json`:
 
 ```json
 {
@@ -155,46 +175,54 @@ Add these key bindings to your Zed `keymap.json`:
 
 ## Windows Terminal
 
-KnightCode uses Windows-style keybindings when running natively on Windows or in WSL:
+Windows Terminal uses KnightCode's Windows and WSL shortcut defaults. See [Keybindings](keybindings.md) for the complete list.
 
-- `Alt+V` pastes an image or clipboard text.
-- `Ctrl+F` searches the transcript in fullscreen mode, and `Ctrl+Up`/`Ctrl+Down` jump between marked messages.
-- `Alt+P` cycles to the previous model.
-- `Ctrl+Z` undoes editing on native Windows; WSL uses `Alt+Z` so `Ctrl+Z` can suspend knightcode.
-- `Ctrl+Q` queues a follow-up message and `Alt+Q` restores queued messages.
+### Forward Shift+Enter
 
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward `Shift+Enter` for inserting a new line:
+Open Windows Terminal's `settings.json` with `Ctrl+Shift+,` or **Settings > Open JSON file**. Add this object to its `actions` array:
 
 ```json
 {
-  "actions": [
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
-      "keys": "shift+enter"
-    }
-  ]
+  "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+  "keys": "shift+enter"
 }
 ```
 
-Windows Terminal binds `Alt+Enter` to fullscreen by default. To use it instead of knightcode's `Ctrl+Q` default for follow-up queueing, configure Windows Terminal to send the key and bind `app.message.followUp` to `alt+enter` in knightcode.
+Fully close and reopen Windows Terminal, then verify that `Shift+Enter` inserts a new line in KnightCode.
+
+### Use Alt+Enter for follow-ups
 
-If you already have an `actions` array, add the object to it. Fully close and reopen Windows Terminal after changing its settings.
+Windows Terminal binds `Alt+Enter` to fullscreen by default. KnightCode therefore uses `Ctrl+Q` for follow-ups on Windows and WSL.
 
-## xfce4-terminal, terminator
+To use `Alt+Enter` instead, configure Windows Terminal to forward the key and bind `app.message.followUp` to `alt+enter` in KnightCode's `keybindings.json`. See [Keybindings](keybindings.md#assign-keybindings).
 
-These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.
+## xfce4-terminal and Terminator
 
-For the best experience, use a terminal that supports the Kitty keyboard protocol:
-- [Kitty](https://sw.kovidgoyal.net/kitty/)
-- [Ghostty](https://ghostty.org/)
-- [WezTerm](https://wezfurlong.org/wezterm/)
-- [iTerm2](https://iterm2.com/)
-- [Alacritty](https://github.com/alacritty/alacritty) (requires compilation with Kitty protocol support)
+These terminals cannot reliably distinguish modified Enter keys from plain `Enter`. Custom bindings such as `Ctrl+Enter` or `Shift+Enter` therefore may not work.
 
-## IntelliJ IDEA (Integrated Terminal)
+Use a terminal with modern extended-key support when you need those shortcuts, such as Kitty, Ghostty, WezTerm, iTerm2, Windows Terminal, or a compatible Alacritty build.
 
-The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
+## IntelliJ IDEA integrated terminal
+
+IntelliJ IDEA's built-in terminal cannot reliably distinguish `Shift+Enter` from plain `Enter`. Use `Ctrl+J` for a newline or run KnightCode in a terminal with modern extended-key support.
+
+If an IME candidate window does not follow the text cursor, show the hardware cursor:
+
+```bash
+export KNIGHTCODE_HARDWARE_CURSOR=1
+knightcode
+```
+
+## Override detected capabilities
+
+KnightCode automatically detects OSC 8 hyperlinks, inline image protocols, and truecolor support. A terminal proxy or multiplexer can make that detection inaccurate.
+
+| Capability | Environment variable | Setting |
+|---|---|---|
+| Hyperlinks | `KNIGHTCODE_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
+| Inline images | `KNIGHTCODE_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
+| Truecolor | `KNIGHTCODE_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
 
-If you want the hardware cursor visible, set `KNIGHTCODE_HARDWARE_CURSOR=1` before running knightcode (disabled by default for compatibility).
+Settings take precedence over environment variables. An unset value or `auto` preserves automatic detection.
 
-Consider using a dedicated terminal emulator for the best experience.
+Only force a capability supported by the complete terminal path. Unsupported escape sequences can corrupt rendering. See [Environment Variables](environment-variables.md#knightcode-process-configuration) and [Settings](settings.md) for the canonical value definitions.