@knightcodeai/cli-linux-x64 0.9.0 → 0.9.2

package/bin/docs/termux.md

@@ -1,126 +1,117 @@
-# Termux (Android) Setup
+# Run KnightCode on Android with Termux
 
-KnightCode runs on Android via [Termux](https://termux.dev/), a terminal emulator and Linux environment for Android.
+KnightCode runs on Android through [Termux](https://termux.dev/), a terminal emulator and Linux environment. Text input, file tools, and shell commands are supported. KnightCode can copy and paste text through the Android clipboard with Termux:API. Clipboard image paste is not supported.
 
-## Prerequisites
+## Before you begin
 
-1. Install [Termux](https://github.com/termux/termux-app#installation) from GitHub or F-Droid (not Google Play, that version is deprecated)
-2. Install [Termux:API](https://github.com/termux/termux-api#installation) from GitHub or F-Droid for clipboard and other device integrations
+Install Termux from [GitHub or F-Droid](https://github.com/termux/termux-app#installation). Do not use the deprecated Google Play build.
 
-## Installation
+[Termux:API](https://github.com/termux/termux-api#installation) is optional. Install it only when you want KnightCode to copy or paste Android clipboard text, or when shell commands need Android device APIs.
 
-```bash
-# Update packages
-pkg update && pkg upgrade
+## Install KnightCode
 
-# Install dependencies
-pkg install nodejs termux-api git
+1. Update Termux packages:
 
-# Install knightcode
-npm install -g --ignore-scripts @knightcodeai/cli
+   ```bash
+   pkg update && pkg upgrade
+   ```
 
-# Create config directory
-mkdir -p ~/.knightcode/agent
+2. Install Node.js and Git:
 
-# Run knightcode
-knightcode
-```
+   ```bash
+   pkg install nodejs git
+   ```
 
-## Clipboard Support
+3. Install KnightCode:
 
-Clipboard operations use `termux-clipboard-set` and `termux-clipboard-get` when running in Termux. The Termux:API app must be installed for these to work.
+   ```bash
+   npm install -g --ignore-scripts @knightcodeai/cli
+   ```
 
-Image clipboard is not supported on Termux (the `ctrl+v` image paste feature will not work).
+4. Verify the installation:
 
-## Example AGENTS.md for Termux
+   ```bash
+   knightcode --version
+   ```
 
-Create `~/.knightcode/agent/AGENTS.md` to help the agent understand the Termux environment:
+5. Open the folder you want to work in and start KnightCode:
 
-````markdown
-# Agent Environment: Termux on Android
+   ```bash
+   cd /path/to/working-folder
+   knightcode
+   ```
 
-## Location
-- **OS**: Android (Termux terminal emulator)
-- **Home**: `/data/data/com.termux/files/home`
-- **Prefix**: `/data/data/com.termux/files/usr`
-- **Shared storage**: `/storage/emulated/0` (Downloads, Documents, etc.)
+Continue with the main [Quickstart](quickstart.md#3-choose-a-model) to connect a model and run your first task.
 
-## Opening URLs
-```bash
-termux-open-url "https://example.com"
-```
+## Access Android shared storage
 
-## Opening Files
-```bash
-termux-open file.pdf          # Opens with default app
-termux-open --chooser image.jpg      # Choose app
-```
+Termux cannot access shared Android storage until you grant permission. Run this once:
 
-## Clipboard
 ```bash
-termux-clipboard-set "text"   # Copy
-termux-clipboard-get          # Paste
+termux-setup-storage
 ```
 
-## Notifications
-```bash
-termux-notification -t "Title" -c "Content"
-```
+After approval, Android shared storage is available under `/storage/emulated/0` and through the links Termux creates under `~/storage/`.
 
-## Device Info
-```bash
-termux-battery-status         # Battery info
-termux-wifi-connectioninfo    # WiFi info
-termux-telephony-deviceinfo   # Device info
-```
+Only grant this permission when KnightCode should be able to access those files. Commands and tools running in Termux use the same storage permissions as the Termux process.
+
+## Use clipboard commands
+
+KnightCode uses `termux-clipboard-set` to copy text and `termux-clipboard-get` for its clipboard-paste shortcut. Shell commands can use both commands directly. Install the Termux:API app and its command-line package:
 
-## Sharing
 ```bash
-termux-share -a send file.txt # Share file
+pkg install termux-api
 ```
 
-## Other Useful Commands
+Verify the integration:
+
 ```bash
-termux-toast "message"        # Quick toast popup
-termux-vibrate                # Vibrate device
-termux-tts-speak "hello"      # Text to speech
-termux-camera-photo out.jpg   # Take photo
+printf 'KnightCode clipboard test' | termux-clipboard-set
+termux-clipboard-get
 ```
 
-## Notes
-- Termux:API app must be installed for `termux-*` commands
-- Use `pkg install termux-api` for the command-line tools
-- Storage permission needed for `/storage/emulated/0` access
-````
+The second command should print `KnightCode clipboard test`.
+
+The Termux clipboard API supports text only. KnightCode's clipboard-paste shortcut inserts that text into the editor but cannot attach clipboard images.
+
+## Add Termux-specific instructions
+
+KnightCode detects that it is running in Termux, but it cannot infer how you want it to interact with Android. Add only the environment details relevant to your work to `~/.knightcode/agent/AGENTS.md`:
 
-## Limitations
+````markdown
+# Termux environment
+
+- KnightCode runs in Termux on Android.
+- Shared Android storage is under `/storage/emulated/0`.
+- Open URLs with `termux-open-url "https://example.com"`.
+- Open files with `termux-open <path>`.
+- Do not access shared storage unless the task requires it.
+````
 
-- **No image clipboard**: Termux clipboard API only supports text
-- **Storage access**: To access files in `/storage/emulated/0` (Downloads, etc.), run `termux-setup-storage` once to grant permissions
+Run `/reload` after changing the file during an active session.
 
 ## Troubleshooting
 
-### Clipboard not working
+### Clipboard integration fails
 
-Ensure both apps are installed:
-1. Termux (from GitHub or F-Droid)
-2. Termux:API (from GitHub or F-Droid)
+Confirm that you installed both components:
 
-Then install the CLI tools:
-```bash
-pkg install termux-api
-```
+1. The Termux:API Android app from the same source as Termux
+2. The `termux-api` command-line package
 
-### Permission denied for shared storage
+Then run the clipboard verification commands above outside KnightCode. If they fail there, fix the Termux:API installation before retrying KnightCode's copy command.
 
-Run once to grant storage permissions:
-```bash
-termux-setup-storage
-```
+### Shared storage reports permission denied
+
+Run `termux-setup-storage`, approve the Android permission request, and retry the path under `~/storage/` or `/storage/emulated/0`.
 
-### Node.js installation issues
+### KnightCode is not found after installation
+
+Open a new Termux shell and run:
 
-If npm fails, try clearing the cache:
 ```bash
-npm cache clean --force
+npm prefix -g
+command -v knightcode
 ```
+
+Confirm that the global npm binary directory is on `PATH`, then reinstall KnightCode if the package is missing.

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.