@knightcodeai/cli-linux-arm64 0.9.1 → 0.9.3

package/bin/docs/themes.md

@@ -1,322 +1,110 @@
-> knightcode can create themes. Ask it to build one for your setup.
+# Customize KnightCode with themes
 
-# Themes
+Themes control the colors KnightCode uses in interactive mode and HTML exports. KnightCode includes `dark` and `light` themes. You can select one theme, follow your terminal's light or dark appearance, or create your own palette.
 
-Themes are JSON files that define colors for the TUI.
+<a id="selecting-a-theme"></a>
 
-## Table of Contents
+## Choose a theme
 
-- [Locations](#locations)
-- [Selecting a Theme](#selecting-a-theme)
-- [Creating a Custom Theme](#creating-a-custom-theme)
-- [Theme Format](#theme-format)
-- [Color Tokens](#color-tokens)
-- [Color Values](#color-values)
-- [Tips](#tips)
+Open `/settings` and select **Theme**. You can use one theme for every terminal appearance or choose separate themes for light and dark terminals.
 
-## Locations
+The selection is saved as the `theme` [setting](settings.md#terminal-and-display):
 
-KnightCode loads themes from:
-
-- Built-in: `dark`, `light`
-- Global: `~/.knightcode/agent/themes/*.json`
-- Project: `.knightcode/themes/*.json` (only after the project is trusted)
-- Packages: `themes/` directories or `knightcode.themes` entries in `package.json`
-- Settings: `themes` array with files or directories
-- CLI: `--theme <path>` (repeatable)
-
-Disable discovery with `--no-themes`.
-
-## Selecting a Theme
+```json
+{
+  "theme": "dark"
+}
+```
 
-Select a theme via `/settings` or in `settings.json`:
+Automatic mode stores the light theme first and the dark theme second:
 
 ```json
 {
-  "theme": "my-theme"
+  "theme": "light/dark"
 }
 ```
 
-On first run, knightcode detects your terminal background and defaults to `dark` or `light`.
+When automatic mode is active, KnightCode changes themes when the terminal reports an appearance change. Theme names cannot contain `/` because KnightCode reserves it for this setting format.
 
-### Initial Theme
-
-Start an interactive run with a theme without changing the saved setting:
+Use `--use-theme` to choose the initial theme for one invocation without changing the saved setting:
 
 ```bash
 knightcode --use-theme light
-```
-
-To follow terminal appearance, use `lightTheme/darkTheme` syntax:
-
-```bash
 knightcode --use-theme light/dark
 ```
 
-The CLI value is the initial theme for that run. Choosing another theme later in `/settings` applies it immediately
-and saves it normally.
-
-## Creating a Custom Theme
-
-1. Create a theme file:
-
-```bash
-mkdir -p ~/.knightcode/agent/themes
-vim ~/.knightcode/agent/themes/my-theme.json
-```
-
-2. Define the theme with all required colors (see [Color Tokens](#color-tokens)):
+See [CLI resources](cli.md#resources) for the command-line option.
 
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/KnightCodeAI/knightcode/main/packages/cli/src/modes/interactive/theme/theme-schema.json",
-  "name": "my-theme",
-  "vars": {
-    "primary": "#00aaff",
-    "secondary": 242
-  },
-  "colors": {
-    "accent": "primary",
-    "border": "primary",
-    "borderAccent": "#00ffff",
-    "borderMuted": "secondary",
-    "success": "#00ff00",
-    "error": "#ff0000",
-    "warning": "#ffff00",
-    "muted": "secondary",
-    "dim": 240,
-    "text": "",
-    "thinkingText": "secondary",
-    "selectedBg": "#2d2d30",
-    "scrollbarTrack": "secondary",
-    "scrollbarThumb": "",
-    "searchMatchBg": "#2d2d30",
-    "searchMatchText": "",
-    "userMessageBg": "#2d2d30",
-    "userMessageText": "",
-    "customMessageBg": "#2d2d30",
-    "customMessageText": "",
-    "customMessageLabel": "primary",
-    "toolPendingBg": "#1e1e2e",
-    "toolSuccessBg": "#1e2e1e",
-    "toolErrorBg": "#2e1e1e",
-    "toolTitle": "primary",
-    "toolOutput": "",
-    "mdHeading": "#ffaa00",
-    "mdLink": "primary",
-    "mdLinkUrl": "secondary",
-    "mdCode": "#00ffff",
-    "mdCodeBlock": "",
-    "mdCodeBlockBorder": "secondary",
-    "mdQuote": "secondary",
-    "mdQuoteBorder": "secondary",
-    "mdHr": "secondary",
-    "mdListBullet": "#00ffff",
-    "toolDiffAdded": "#00ff00",
-    "toolDiffRemoved": "#ff0000",
-    "toolDiffContext": "secondary",
-    "syntaxComment": "secondary",
-    "syntaxKeyword": "primary",
-    "syntaxFunction": "#00aaff",
-    "syntaxVariable": "#ffaa00",
-    "syntaxString": "#00ff00",
-    "syntaxNumber": "#ff00ff",
-    "syntaxType": "#00aaff",
-    "syntaxOperator": "primary",
-    "syntaxPunctuation": "secondary",
-    "thinkingOff": "secondary",
-    "thinkingMinimal": "primary",
-    "thinkingLow": "#00aaff",
-    "thinkingMedium": "#00ffff",
-    "thinkingHigh": "#ff00ff",
-    "thinkingXhigh": "#ff0000",
-    "thinkingMax": "#ff0088",
-    "bashMode": "#ffaa00"
-  }
-}
-```
+## Create a custom theme
 
-3. Select the theme via `/settings`.
+Copy one of the [built-in themes](https://github.com/KnightCodeAI/knightcode/tree/main/packages/cli/src/modes/interactive/theme) or create a new JSON file conforming to the [schema](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/modes/interactive/theme/theme-schema.json).
 
-**Hot reload:** When you edit the currently active custom theme file, knightcode reloads it automatically for immediate visual feedback.
+1. Save the file as `<agent-dir>/themes/my-theme.json`. The agent directory defaults to `~/.knightcode/agent`.
+2. Set its `name` to `my-theme`.
+3. Change values in `vars` and `colors`.
+4. Select `my-theme` through `/settings`.
 
-## Theme Format
+Use the theme name as the filename. KnightCode hot-reloads the active user theme only from `<agent-dir>/themes/<name>.json`. Run `/reload` after adding or changing a theme from any other source.
 
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/KnightCodeAI/knightcode/main/packages/cli/src/modes/interactive/theme/theme-schema.json",
-  "name": "my-theme",
-  "vars": {
-    "blue": "#0066cc",
-    "gray": 242
-  },
-  "colors": {
-    "accent": "blue",
-    "muted": "gray",
-    "text": "",
-    ...
-  }
-}
-```
+## Understand the theme file
 
-- `name` is required, must be unique, and must not contain `/`.
-- `vars` is optional. Define reusable colors here, then reference them in `colors`.
-- `colors` must define all 53 required tokens. `thinkingMax` and the two search highlight tokens are optional and use the fallbacks listed below.
-
-The `$schema` field enables editor auto-completion and validation.
-
-## Color Tokens
-
-Every theme must define all 53 required color tokens. The optional tokens preserve compatibility with existing themes: `thinkingMax` falls back to `thinkingXhigh`, `searchMatchBg` falls back to `selectedBg`, and `searchMatchText` falls back to `text`. Other search matches use `searchMatchText` on `searchMatchBg` with an underline; the current match reverses that foreground/background pair and uses bold text.
-
-### Core UI (13 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `accent` | Primary accent (logo, selected items, cursor) |
-| `border` | Normal borders |
-| `borderAccent` | Highlighted borders |
-| `borderMuted` | Subtle borders (editor) |
-| `success` | Success states |
-| `error` | Error states |
-| `warning` | Warning states |
-| `muted` | Secondary text |
-| `dim` | Tertiary text |
-| `text` | Default text (usually `""`) |
-| `thinkingText` | Thinking block text |
-| `scrollbarTrack` | Fullscreen scrollbar track foreground |
-| `scrollbarThumb` | Fullscreen scrollbar thumb foreground, shared by normal and expanded states |
-
-### Backgrounds & Content (11 required, 2 optional)
-
-| Token | Purpose |
-|-------|---------|
-| `selectedBg` | Selected line background |
-| `searchMatchBg` | Transcript search match background and current-match text; optional, falls back to `selectedBg` |
-| `searchMatchText` | Transcript search match text and current-match background; optional, falls back to `text` |
-| `userMessageBg` | User message background |
-| `userMessageText` | User message text |
-| `customMessageBg` | Extension message background |
-| `customMessageText` | Extension message text |
-| `customMessageLabel` | Extension message label |
-| `toolPendingBg` | Tool box (pending) |
-| `toolSuccessBg` | Tool box (success) |
-| `toolErrorBg` | Tool box (error) |
-| `toolTitle` | Tool title |
-| `toolOutput` | Tool output text |
-
-### Markdown (10 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `mdHeading` | Headings |
-| `mdLink` | Link text |
-| `mdLinkUrl` | Link URL |
-| `mdCode` | Inline code |
-| `mdCodeBlock` | Code block content |
-| `mdCodeBlockBorder` | Code block fences |
-| `mdQuote` | Blockquote text |
-| `mdQuoteBorder` | Blockquote border |
-| `mdHr` | Horizontal rule |
-| `mdListBullet` | List bullets |
-
-### Tool Diffs (3 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `toolDiffAdded` | Added lines |
-| `toolDiffRemoved` | Removed lines |
-| `toolDiffContext` | Context lines |
-
-### Syntax Highlighting (9 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `syntaxComment` | Comments |
-| `syntaxKeyword` | Keywords |
-| `syntaxFunction` | Function names |
-| `syntaxVariable` | Variables |
-| `syntaxString` | Strings |
-| `syntaxNumber` | Numbers |
-| `syntaxType` | Types |
-| `syntaxOperator` | Operators |
-| `syntaxPunctuation` | Punctuation |
-
-### Thinking Level Borders (6 required, 1 optional)
-
-Editor border colors indicating thinking level (visual hierarchy from subtle to prominent):
-
-| Token | Purpose |
-|-------|---------|
-| `thinkingOff` | Thinking off |
-| `thinkingMinimal` | Minimal thinking |
-| `thinkingLow` | Low thinking |
-| `thinkingMedium` | Medium thinking |
-| `thinkingHigh` | High thinking |
-| `thinkingXhigh` | Extra high thinking |
-| `thinkingMax` | Maximum thinking; optional, falls back to `thinkingXhigh` |
-
-### Bash Mode (1 color)
-
-| Token | Purpose |
-|-------|---------|
-| `bashMode` | Editor border in bash mode (`!` prefix) |
-
-### HTML Export (optional)
-
-The `export` section controls colors for `/export` HTML output. If omitted, colors are derived from `userMessageBg`.
+| Property | Required | Responsibility |
+|---|---|---|
+| `$schema` | No | Enables editor validation and completion against KnightCode's published schema. |
+| `name` | Yes | Identifies the theme in selectors and settings. It must be unique and cannot contain `/`. |
+| `vars` | No | Defines reusable color values. Variables can reference other variables. |
+| `colors` | Yes | Assigns colors to terminal UI roles. The schema identifies required and optional roles. |
+| `export` | No | Overrides page and panel backgrounds in HTML exports. |
 
-```json
-{
-  "export": {
-    "pageBg": "#18181e",
-    "cardBg": "#1e1e24",
-    "infoBg": "#3c3728"
-  }
-}
-```
+A color can be written in four forms:
 
-## Color Values
+| Form | Example | Meaning |
+|---|---|---|
+| RGB hexadecimal | `"#00aaff"` | A six-digit RGB color. |
+| 256-color index | `39` | An ANSI palette index from `0` through `255`. |
+| Variable reference | `"primary"` | The value of an entry in `vars`. |
+| Terminal default | `""` | The terminal's default foreground or background color. |
 
-Four formats are supported:
+KnightCode resolves chained variable references. A missing variable or circular reference makes the theme invalid. Hexadecimal colors use truecolor when supported and are approximated in terminals limited to 256 colors. If colors differ from their hexadecimal values, check your terminal's truecolor detection and contrast settings. See [Configure Your Terminal](terminal-setup.md#override-detected-capabilities).
 
-| Format | Example | Description |
-|--------|---------|-------------|
-| Hex | `"#ff0000"` | 6-digit hex RGB |
-| 256-color | `39` | xterm 256-color palette index (0-255) |
-| Variable | `"primary"` | Reference to a `vars` entry |
-| Default | `""` | Terminal's default color |
+Use the [theme JSON schema](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/modes/interactive/theme/theme-schema.json) for the exact properties, required colors, and accepted value types.
 
-### 256-Color Palette
+KnightCode reports invalid theme files during startup and `/reload`.
 
-- `0-15`: Basic ANSI colors (terminal-dependent)
-- `16-231`: 6×6×6 RGB cube (`16 + 36×R + 6×G + B` where R,G,B are 0-5)
-- `232-255`: Grayscale ramp
+## Find the color to change
 
-### Terminal Compatibility
+Theme colors describe interface roles rather than individual components. Use these groups to find the relevant part of the schema:
 
-KnightCode uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, knightcode falls back to the nearest approximation.
-
-Check truecolor support:
-
-```bash
-echo $COLORTERM  # Should output "truecolor" or "24bit"
-```
+| Area | Color names |
+|---|---|
+| General interface | `accent`, `border*`, `text`, `muted`, `dim`, `success`, `error`, `warning` |
+| Selection and fullscreen | `selectedBg`, `searchMatch*`, `scrollbar*` |
+| Messages | `userMessage*`, `customMessage*`, `thinkingText` |
+| Tool execution | `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `toolTitle`, `toolOutput` |
+| Markdown | `md*` |
+| Tool diffs | `toolDiff*` |
+| Syntax highlighting | `syntax*` |
+| Editor modes | `thinking*`, `bashMode` |
+| HTML export | `export.pageBg`, `export.cardBg`, `export.infoBg` |
 
-## Tips
+The schema is the format reference. The built-in themes provide complete values that you can copy and adjust.
 
-**Dark terminals:** Use bright, saturated colors with higher contrast.
+Five colors are optional and inherit another color when omitted:
 
-**Light terminals:** Use darker, muted colors with lower contrast.
+| Optional color | Fallback |
+|---|---|
+| `scrollbarTrack` | `muted` |
+| `scrollbarThumb` | `text` |
+| `searchMatchBg` | `selectedBg` |
+| `searchMatchText` | `text` |
+| `thinkingMax` | `thinkingXhigh` |
 
-**Color harmony:** Start with a base palette (Nord, Gruvbox, Tokyo Night), define it in `vars`, and reference consistently.
+If `export` colors are omitted, KnightCode derives HTML page and panel backgrounds from `userMessageBg`.
 
-**Testing:** Check your theme with different message types, tool states, markdown content, and long wrapped text.
+## Load a theme from a project or package
 
-**VS Code:** Set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
+Place a project theme in `.knightcode/themes/`. Project themes load only after [project trust](security.md#understand-project-trust) is granted.
 
-## Examples
+You can also load theme files and directories through the `themes` setting or distribute them in a KnightCode package. See [Configuration](configuration.md), [Settings](settings.md#resources), and [KnightCode Packages](packages.md).
 
-See the built-in themes:
-- [dark.json](../src/modes/interactive/theme/dark.json)
-- [light.json](../src/modes/interactive/theme/light.json)
+Each loaded theme must have a unique name. KnightCode reports duplicate names as resource collisions.

package/bin/docs/tmux.md

@@ -1,63 +1,55 @@
-# tmux Setup
+# Run KnightCode in tmux
 
-KnightCode works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `Shift+Enter` and `Ctrl+Enter` are usually indistinguishable from plain `Enter`.
+KnightCode works inside tmux, but tmux can report `Shift+Enter`, `Ctrl+Enter`, and plain `Enter` as the same key. Enable extended keys so KnightCode can distinguish them.
 
-## Recommended Configuration
-
-Add to `~/.tmux.conf`:
-
-```tmux
-set -g extended-keys on
-set -g extended-keys-format csi-u
-```
-
-Then restart tmux fully:
+## Check your tmux version
 
 ```bash
-tmux kill-server
-tmux
+tmux -V
 ```
 
-KnightCode requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration. The `extended-keys-format` option requires tmux 3.5 or later.
+For tmux 3.5 or newer, use the recommended CSI-u configuration below. For tmux 3.2 through 3.4, use the older-version configuration.
 
-## Why `csi-u` Is Recommended
+## Enable extended keys in tmux 3.5 or newer
 
-With only:
+Add these lines to `~/.tmux.conf`:
 
 ```tmux
 set -g extended-keys on
+set -g extended-keys-format csi-u
 ```
 
-tmux defaults to `extended-keys-format xterm`. When an application requests extended key reporting, modified keys are forwarded in xterm `modifyOtherKeys` format such as:
+KnightCode requests extended-key reporting when the terminal does not provide the Kitty keyboard protocol directly. CSI-u is the most reliable format for forwarding modified keys through tmux.
 
-- `Ctrl+C` → `\x1b[27;5;99~`
-- `Ctrl+D` → `\x1b[27;5;100~`
-- `Ctrl+Enter` → `\x1b[27;5;13~`
+## Restart tmux
 
-With `extended-keys-format csi-u`, the same keys are forwarded as:
+The configuration applies to the tmux server. To guarantee that it is active, close your tmux sessions and start a new server.
 
-- `Ctrl+C` → `\x1b[99;5u`
-- `Ctrl+D` → `\x1b[100;5u`
-- `Ctrl+Enter` → `\x1b[13;5u`
+If you choose to stop the server from the command line, save your work first. This command terminates every session managed by that server:
 
-KnightCode supports both formats, but `csi-u` is the recommended tmux setup.
+```bash
+tmux kill-server
+tmux
+```
+
+## Verify modified keys
 
-## What This Fixes
+Start KnightCode inside the new tmux session and check that:
 
-Without tmux extended keys, modified Enter keys collapse to legacy sequences:
+1. `Shift+Enter` inserts a new line in the editor.
+2. `Enter` submits the prompt.
+3. `Alt+Enter` queues a follow-up on macOS and Linux. Windows and WSL use `Ctrl+Q` by default.
 
-| Key | Without extkeys | With `csi-u` |
-|-----|-----------------|--------------|
-| Enter | `\r` | `\r` |
-| Shift+Enter | `\r` | `\x1b[13;2u` |
-| Ctrl+Enter | `\r` | `\x1b[13;5u` |
-| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |
+If these keys still behave like plain `Enter`, verify that the terminal outside tmux can report modified keys. See [Configure your terminal](terminal-setup.md).
 
-This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newline) and any custom keybindings using modified Enter.
+## Use tmux 3.2 through 3.4
 
-## Requirements
+These versions support extended keys but not `extended-keys-format csi-u`. Add only:
+
+```tmux
+set -g extended-keys on
+```
 
-- tmux 3.5 or later for `extended-keys-format csi-u` (run `tmux -V` to check)
-- A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)
+KnightCode supports the xterm `modifyOtherKeys` format used by these versions. Restart tmux and repeat the verification steps.
 
-With tmux 3.2 through 3.4, omit `extended-keys-format csi-u`; KnightCode still supports tmux's default xterm `modifyOtherKeys` format.
+For older versions, upgrade tmux or use KnightCode outside tmux rather than relying on modified Enter shortcuts.