@knightcodeai/cli 0.17.3 → 0.18.0

package/docs/models.md

@@ -0,0 +1,221 @@
+# Choose a Model
+
+For a built-in provider, start with `/login`, then choose a model with `/model`. Use custom model configuration only when KnightCode does not already include the provider or endpoint you need.
+
+## Choose a connection
+
+| What you have | Recommended setup |
+|---|---|
+| A supported subscription | Sign in through `/login` |
+| A provider API key | Store it through `/login` or set its environment variable |
+| A local GGUF model | Connect KnightCode to the llama.cpp router |
+| An OpenAI-, Anthropic-, or Google-compatible endpoint | Add it to `models.json` |
+| A provider with a custom protocol or authentication flow | Build or install a provider extension |
+
+Browse the [model catalog](https://knightcode.dev/models) for current providers, model IDs, capabilities, context limits, and pricing. KnightCode starts with its bundled catalog and can overlay newer catalog data from knightcode.dev. Cached catalog data remains available offline; run `knightcode update --models` to force a refresh.
+
+## Authenticate
+
+Run `/login` and select a provider. KnightCode stores credentials in [`auth.json`](configuration.md#agent-directory). Run `/logout` to remove stored credentials for a provider.
+
+You can instead provide an API key through the provider's environment variable. This is useful in CI and other environments where KnightCode should not write credentials. [Providers](providers.md) lists the variables and provider-specific setup.
+
+When several credential sources are configured, KnightCode uses a runtime `--api-key` first, then a stored `auth.json` credential, an `apiKey` from `models.json`, and finally the provider's environment variables or ambient cloud credentials. Provider extensions can define their own authentication behavior.
+
+Keep `auth.json` and any credential commands private. Project settings and extensions can execute inside the KnightCode process after you trust a project. Review [Security](security.md) before loading configuration from an untrusted directory.
+
+## Select a model
+
+Run `/model` to search available models. The picker shows models whose providers have usable authentication. Press `Ctrl+S` (or `Ctrl+D`, if your terminal swallows `Ctrl+S`) on a model to save it as the default for new sessions.
+
+Run `/thinking` to select the thinking level for the current model. Press `Ctrl+S` or `Ctrl+D` there to save the startup level. KnightCode limits the choices to levels supported by the selected model.
+
+`Ctrl+P` cycles through available models. Use `/scoped-models` to control that cycle and save the selection, or configure model patterns through [Settings](settings.md#model-cycling).
+
+A session records model and thinking-level changes. Resuming the session restores them without changing defaults for new sessions.
+
+## Connect local models
+
+KnightCode integrates directly with the llama.cpp router. The router discovers GGUF files and loads models on demand. KnightCode's `/llama` command manages the router, while `/model` selects one of its loaded models.
+
+Follow [Local Models with llama.cpp](llama-cpp.md) for server startup, model layout, downloads, and connection troubleshooting.
+
+For Ollama, LM Studio, vLLM, SGLang, and other compatible servers, [configure a compatible endpoint](#configure-a-compatible-endpoint) in `models.json`.
+
+## Configure a compatible endpoint
+
+Use [`models.json`](configuration.md#agent-directory) when an endpoint speaks an API KnightCode already supports. This includes most Ollama, LM Studio, vLLM, SGLang, and proxy deployments.
+
+```json
+{
+  "$schema": "https://knightcode.dev/schemas/models.schema.json",
+  "providers": {
+    "ollama": {
+      "baseUrl": "http://localhost:11434/v1",
+      "api": "openai-completions",
+      "apiKey": "ollama",
+      "models": [
+        { "id": "qwen2.5-coder:7b" }
+      ]
+    }
+  }
+}
+```
+
+The dummy key makes the model available to KnightCode; Ollama ignores it. For an authenticated endpoint, `apiKey` and header values can use `$NAME` or `${NAME}` environment interpolation, a literal value, or a leading `!command`. `$$` and `$!` produce a literal `$` and `!`. Commands in `models.json` run at request time and are not cached by KnightCode.
+
+Opening `/model` reloads the file. A `models` entry adds or replaces a model with the same ID on that provider. Use `modelOverrides` to change metadata for an existing built-in or extension-provided model without replacing the provider's model list. Unknown override IDs are ignored.
+
+To route a built-in provider through a proxy, set only its `baseUrl`. Its models and authentication stay unchanged:
+
+```json
+{
+  "providers": {
+    "anthropic": { "baseUrl": "https://proxy.example.com/v1" }
+  }
+}
+```
+
+[Models Configuration](models-configuration.md) lists every field.
+
+### Describe model input and caching
+
+Use `inputLimits.images.resize` to control how KnightCode encodes new image attachments, `read` results, and tool-result images before storing them in conversation history:
+
+```json
+{
+  "id": "vision-model",
+  "input": ["text", "image"],
+  "inputLimits": {
+    "images": {
+      "resize": {
+        "maxWidth": 1568,
+        "maxHeight": 1568,
+        "maxBytes": 524288,
+        "jpegQuality": 75
+      }
+    }
+  }
+}
+```
+
+`maxBytes` limits the base64-encoded payload. Omitted resize fields use conservative defaults of 2000 by 2000 pixels, 4.5 MiB encoded, and JPEG quality 80. Images are encoded once; changing models does not rewrite historical images. The catalog can also describe hard request limits with `inputLimits.maxRequestBytes`, `images.maxPerMessage`, and `images.maxPerRequest`, but KnightCode does not yet rewrite or reject history based on them.
+
+<a id="prompt-cache-lifetimes"></a>
+
+Use `promptCache` to declare the provider's best-effort cache lifetime in seconds for the `short` or `long` retention tier:
+
+```json
+{ "id": "claude-sonnet-5", "promptCache": { "short": 300, "long": 3600 } }
+```
+
+Choose the conservative end of any published range. A model without a lifetime for the active tier is not eligible for cache warming. A `modelOverrides` entry can set `inputLimits` or `promptCache` for a built-in or extension model, including a model accessed through a validated proxy. See [`cacheWarming`](settings.md#model-and-thinking).
+
+### Configure sampling by thinking level
+
+OpenAI-compatible APIs support free-form `samplingParams` model defaults and `samplingParamsByThinkingLevel` overrides. The latter uses KnightCode thinking-level keys (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`), not provider values from `thinkingLevelMap`:
+
+```json
+{
+  "id": "qwen-thinking-model",
+  "reasoning": true,
+  "samplingParams": {
+    "temperature": 1.0,
+    "top_p": 0.95
+  },
+  "samplingParamsByThinkingLevel": {
+    "off": {
+      "temperature": 0.7,
+      "top_p": 0.8
+    },
+    "high": {
+      "top_k": 20
+    }
+  }
+}
+```
+
+KnightCode first clamps unsupported thinking levels, then merges model `samplingParams`, the effective level's override, and request-level `samplingParams` in that order. Later values win per key. Missing levels inherit the model defaults. `modelOverrides` merges per-level entries per key with the base model. These fields apply only to `openai-completions`, `openai-responses`, and `azure-openai-responses`; other APIs ignore them.
+
+Compatibility settings should describe verified differences in the endpoint's request or response behavior. Do not enable them based only on an endpoint advertising OpenAI or Anthropic compatibility.
+
+## Use classifier models
+
+Classifier models do not chat. They answer typed questions about JSON state: pick one of several choices, answer yes or no, or give a score, each with probabilities. KnightCode includes TypeSafe's Jev model from these providers, Cloudflare's Clef and Clef Flash models from Workers AI, and OpenAI's GPT-6 Luna through the [Decisions API](https://developers.openai.com/api/docs/guides/decisions):
+
+| Provider | Model IDs | Authentication |
+|---|---|---|
+| `typesafe` | `jev-latest` | `TYPESAFE_API_KEY` |
+| `openrouter` | `typesafe/jev-1.13`, `~typesafe/jev-latest` | `OPENROUTER_API_KEY` or `/login` |
+| `cloudflare-workers-ai` | `typesafe/jev`, `@cf/cloudflare/clef`, `@cf/cloudflare/clef-flash` | `CLOUDFLARE_API_KEY` and `CLOUDFLARE_ACCOUNT_ID` |
+| `vercel-ai-gateway` | `typesafe-ai/jev` | `AI_GATEWAY_API_KEY` |
+| `opencode` | `jev-1.13`, `jev-1.13-free` | `OPENCODE_API_KEY` |
+| `openai` | `gpt-6-luna` | `OPENAI_API_KEY` |
+
+A [llama.cpp router](llama-cpp.md#classification) lists decision models as native classifiers, and also lists each chat model as a classifier.
+
+OpenAI's Decisions API needs an API key. ChatGPT sign-in does not work with it, so `gpt-6-luna` is not listed as available while `openai` is logged in through `/login`, even when `OPENAI_API_KEY` is set; log out of `openai` to use the key. GPT-6 Luna also judges images passed in `images` (see [Codemode](codemode.md#classify)); other classifier models return an error for them. The API rejects inputs above 922K tokens, but requests that run longer than about five seconds, currently above roughly 600K input tokens, fail with a gateway timeout.
+
+Classifier models do not appear in `/model`. The [classifier gate](usage.md#classifier-gate) uses one to screen risky tool calls. The model reaches them through the [`codemode`](cli.md#enable-codemode) tool, which is off unless an MCP server turned it on. Enable it with `"defaultTools": ["+codemode"]` in [settings](settings.md#tools). Scripts then list classifier models with `models.getAvailableOfType("classifier")` and call `models.classify(model, { state, questions })`:
+
+```js
+const jev = await models.getModelOfType("classifier", "typesafe", "jev-latest");
+const result = await models.classify(jev, {
+  state: { message: "The change works, thanks." },
+  questions: {
+    approved: {
+      type: "bool",
+      instructions: "Does the user approve of the result?",
+      criteria: { true: "Approval", false: "No approval" },
+    },
+  },
+});
+return result.answers;
+```
+
+[Codemode](codemode.md#classify) describes the question and answer types.
+
+When the service reports token counts, as all System One services do, `result.usage` carries them with their cost. KnightCode adds the usage of a script's classifier calls to the `codemode` tool result, so it counts toward the session cost in the footer and `/session`. The cost uses the model's catalog price; models without one, such as TypeSafe's direct `jev-latest`, report tokens at no cost.
+
+Extensions call classifiers through `ctx.modelRegistry.classify()`, without codemode. [Virtual models](virtual-models.md#route-requests) can use them to route requests; see the `jev-router.ts` example.
+
+## Use image models
+
+Image models generate images from a prompt and optional input images. KnightCode lists OpenRouter's image models, such as `google/gemini-2.5-flash-image` and `black-forest-labs/flux.2-pro`, under the `openrouter` provider; they use the same `OPENROUTER_API_KEY` or `/login` credential as its chat models.
+
+Like classifier models, image models do not appear in `/model`; the model reaches them through the [`codemode`](cli.md#enable-codemode) tool. Scripts list them with `models.getAvailableOfType("image")` and call `models.generateImages(model, { input })`. The result's `output` holds base64 image blocks, which `image()` attaches to the `codemode` result so the model sees them:
+
+```js
+const painter = await models.getModelOfType("image", "openrouter", "google/gemini-2.5-flash-image");
+const result = await models.generateImages(painter, {
+  input: [{ type: "text", text: "A red fox in the snow, watercolor" }],
+});
+if (result.stopReason !== "stop") return result.errorMessage;
+for (const block of result.output) if (block.type === "image") image(block);
+```
+
+`input` can also contain `{ type: "image", data, mimeType }` blocks to edit or use as references. KnightCode adds the usage of a script's image calls to the `codemode` tool result, like classifier calls. Generated images are not saved to disk. [Codemode](codemode.md#generate-images) describes the full API.
+
+Extensions generate images through `ctx.modelRegistry.generateImages()`, without codemode.
+
+## Add a custom provider
+
+Use an extension when the provider needs custom streaming, model discovery, or authentication behavior. See [Custom Providers](custom-provider.md) for the extension workflow.
+
+## Troubleshooting
+
+### A model does not appear
+
+Confirm that its provider has usable authentication. Custom models can load from `models.json` but remain unavailable in `/model` until KnightCode can resolve credentials. For llama.cpp, only models currently loaded by the router appear.
+
+### Authentication works in one shell only
+
+Check whether the key came from an environment variable rather than `auth.json`. Environment variables must be present in the process that starts KnightCode.
+
+### Sign-in opens a browser on a remote machine
+
+Complete the provider's headless authentication flow when available. Some providers let you paste the final redirect URL or authorization code back into KnightCode. See [Authenticate interactively](providers.md#authenticate-interactively).
+
+### A compatible endpoint rejects requests
+
+Check its API type and compatibility settings in `models.json`. The upstream server must support the corresponding request fields and behavior.

package/docs/nvidia-rtx-llama-cpp.md

@@ -0,0 +1,96 @@
+# Run KnightCode with NVIDIA RTX and llama.cpp
+
+[NVIDIA Local AI Inference Recipes](https://nvidia.github.io/local-ai-inference-recipes/index.html) provides llama.cpp settings tuned for specific NVIDIA hardware and models. Each recipe gives a single-model `llama-server` command. KnightCode works with the llama.cpp router, which can serve and manage several models, so this guide converts the recipe command into a router preset.
+
+The examples below use Windows PowerShell. See [Local Models with llama.cpp](llama-cpp.md) for KnightCode's complete router and model-management reference.
+
+## Before you begin
+
+1. Open the [recipe catalog](https://nvidia.github.io/local-ai-inference-recipes/index.html), select your hardware, operating system, and model, then choose **llama.cpp**. Check the prerequisites and memory requirements. Keep the recipe's launch command for the conversion below.
+2. Install llama.cpp with the recipe's setup instructions. The recipe's settings depend on its build, for example CUDA support or speculative decoding options.
+3. Run `llama-server --help` and check that it lists `--models-preset`. Without it, the build cannot load the recipe as a router preset. Use a newer build that still meets the recipe's requirements.
+4. Install KnightCode with the [Quickstart](quickstart.md). On native Windows, also see [Run KnightCode on Windows](windows.md).
+
+## Convert the recipe to a preset
+
+A preset lists the settings for one or more models. Each section name becomes the model ID shown in KnightCode. Save the preset next to `llama-server`, or pass its full path when starting the router.
+
+Convert each option from the recipe command into one preset line:
+
+- Remove the leading dashes: `--ctx-size 65536` becomes `ctx-size = 65536`.
+- Write options without a value as `true`: `--jinja` becomes `jinja = true`.
+- Remove quotes and PowerShell line-continuation backticks around values.
+- Leave out `--host` and `--port`. They belong on the router command line.
+- Add `load-on-startup = true` so the router loads the model when it starts.
+- Replace short model-file options with their long preset keys:
+
+| Recipe option | Preset key |
+|---|---|
+| `-hf` | `hf-repo` |
+| `-hff` | `hf-file` |
+| `-hfrd` | `hf-repo-draft` |
+| `--spec-draft-model` | `spec-draft-model` |
+
+For example, this recipe command:
+
+```powershell
+llama-server.exe -hf "unsloth/Qwen3.8-27B-GGUF" `
+  -hff "Qwen3.8-27B-UD-Q4_K_M.gguf" `
+  -hfrd "z-lab/Qwen3.8-27B-DFlash2-GGUF" `
+  --spec-draft-model "Qwen3.8-27B-DFlash2-Q4_K_M.gguf" `
+  --no-mmproj `
+  --host 127.0.0.1 `
+  --port 9931 `
+  --batch-size 4096 `
+  --ubatch-size 1024 `
+  --ctx-size 65536 `
+  --parallel 1 `
+  -ngl 999 `
+  --jinja `
+  --chat-template-kwargs '{"preserve_thinking":true}' `
+  --spec-type draft-dflash `
+  --spec-draft-n-max 7 `
+  --spec-draft-backend-sampling
+```
+
+becomes `qwen3.8-27b.ini`:
+
+```ini
+version = 1
+
+[qwen3.8-27b]
+load-on-startup = true
+hf-repo = unsloth/Qwen3.8-27B-GGUF
+hf-file = Qwen3.8-27B-UD-Q4_K_M.gguf
+hf-repo-draft = z-lab/Qwen3.8-27B-DFlash2-GGUF
+spec-draft-model = Qwen3.8-27B-DFlash2-Q4_K_M.gguf
+no-mmproj = true
+batch-size = 4096
+ubatch-size = 1024
+ctx-size = 65536
+parallel = 1
+ngl = 999
+jinja = true
+chat-template-kwargs = {"preserve_thinking":true}
+spec-type = draft-dflash
+spec-draft-n-max = 7
+spec-draft-backend-sampling = true
+```
+
+## Start the router
+
+Open PowerShell in the llama.cpp folder and run:
+
+```powershell
+.\llama-server.exe --models-preset qwen3.8-27b.ini --host 127.0.0.1 --port 8080
+```
+
+If the recipe requires a Hugging Face token, set `$env:HF_TOKEN` in the same PowerShell window before starting the router. On its first start, the router downloads the model files.
+
+Use the [router health checks](llama-cpp.md#troubleshooting) to confirm that the server is ready. In Windows PowerShell, use `curl.exe` rather than `curl`, which PowerShell maps to a different command. The model is ready when `/models` lists `qwen3.8-27b` with the status `loaded`.
+
+## Use the model in KnightCode
+
+Follow [Configure KnightCode](llama-cpp.md#configure-knightcode) and connect to `http://127.0.0.1:8080`. The preset section name is the model ID, so select `qwen3.8-27b` in `/model` for this example.
+
+NVIDIA recipe memory settings assume that only the selected model uses the GPU. If `/llama` shows other loaded models, unload them before using the recipe model.

package/docs/packages.md

@@ -0,0 +1,129 @@
+# KnightCode Packages
+
+KnightCode packages install and distribute extensions, skills, prompt templates, and themes as one unit. Use a package when a customization should be shared through npm or git, or when several resources belong together.
+
+A package is an ordinary directory or npm package. It can expose conventional resource directories, declare explicit paths under the `knightcode` key in `package.json`, and carry its own runtime dependencies.
+
+## Install and manage packages
+
+Install from npm, git, or a local path:
+
+```bash
+knightcode install npm:@example/knightcode-tools@1.0.0
+knightcode install git:github.com/example/knightcode-tools@v1
+knightcode install ./local-package
+```
+
+`knightcode list` shows configured packages. Use `knightcode remove <source>` to remove one and `knightcode update --extensions` to reconcile package installations. See [Command Line](cli.md#package-commands) for every package command and option.
+
+Personal installs are written to `~/.knightcode/agent/settings.json`. Add `--local` or `-l` to write the package declaration to `.knightcode/settings.json`. KnightCode reads declarations from that file only after project trust is granted.
+
+Project packages are installed and loaded only after project trust is resolved. Packages can execute extension code and can include skills that instruct the model to run programs. Review third-party package source before installing it. Review project package declarations before granting project trust.
+
+Use `--extension` or `-e` to try a package for one invocation without adding it to settings:
+
+```bash
+knightcode -e npm:@example/knightcode-tools
+```
+
+## Choose a source
+
+| Source | Example | Behavior |
+|---|---|---|
+| npm | `npm:@example/knightcode-tools@1.0.0` | Installed under the KnightCode npm directory |
+| git | `git:github.com/example/knightcode-tools@v1` | Cloned and reconciled to the selected ref |
+| URL | `https://github.com/example/knightcode-tools` | Treated as a git source |
+| Local | `./knightcode-tools` | Loaded from the resolved path without copying |
+
+Versioned npm specifications are pinned. Git tags and commits are also pinned; package updates reconcile the checkout but do not move a configured ref.
+
+Relative local paths resolve from the settings file that contains them. A file path loads one extension. A directory follows normal package discovery rules.
+
+## Create a package
+
+The simplest package uses conventional directories:
+
+```text
+my-knightcode-package/
+├── package.json
+├── extensions/
+├── skills/
+├── prompts/
+└── themes/
+```
+
+Without a `knightcode` manifest, KnightCode discovers TypeScript and JavaScript extensions, skill directories, Markdown prompts, and JSON themes from those directories.
+
+Use an explicit manifest when resources live elsewhere or need filtering:
+
+```json
+{
+  "name": "my-knightcode-package",
+  "keywords": ["knightcode-package"],
+  "knightcode": {
+    "extensions": ["./src/extension.ts"],
+    "skills": ["./resources/skills"],
+    "prompts": ["./resources/prompts/*.md"],
+    "themes": ["./resources/themes/*.json"]
+  }
+}
+```
+
+Paths are relative to the package root. Arrays accept glob patterns and exclusions. List dot-prefixed or symlinked resource roots directly when traversal through a glob would not discover them.
+
+The `knightcode-package` keyword makes an npm package eligible for discovery in the [KnightCode package gallery](https://knightcode.dev/packages). Optional `knightcode.image` and `knightcode.video` fields add gallery previews.
+
+## Declare dependencies
+
+Put runtime packages imported by extensions in `dependencies`. KnightCode installs package dependencies when it installs an npm or git source.
+
+KnightCode supplies these packages to extensions and skills:
+
+- `@knightcode/ai`
+- `@knightcode/agent`
+- `@knightcodeai/cli`
+- `@knightcode/tui`
+- `typebox`
+
+Declare the host-provided packages listed above in `peerDependencies` with a `"*"` range and do not bundle them. KnightCode suppresses automatic peer installation for managed npm packages and git packages installed with npm, pnpm, or Bun. Local packages are not installed or modified, so their dependency tree remains the package author's responsibility.
+
+Do not list host-provided packages in `dependencies`. A physical copy can bypass KnightCode's extension module mapping in compiled ESM and create duplicate classes, registries, and initialization work. KnightCode reports an extension warning when it detects this manifest configuration. Other KnightCode packages used as dependencies must be included in the published tarball and referenced through their `node_modules` resource paths.
+
+Installed packages load with separate module roots. Do not rely on two packages sharing one dependency instance or one package resolving another package’s undeclared dependency.
+
+## Select package resources
+
+The object form in settings narrows which resources load from a package:
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@example/knightcode-tools",
+      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
+      "skills": [],
+      "prompts": ["prompts/review.md"]
+    }
+  ]
+}
+```
+
+For each resource type:
+
+- Omit the property to load everything allowed by the package.
+- Use `[]` to load none of that type.
+- Use `!pattern` to exclude glob matches.
+- Use `+path` to include one exact allowed path.
+- Use `-path` to exclude one exact path.
+
+Filters narrow the package manifest. They do not expose resources that the package itself did not declare.
+
+Run `knightcode config` to enable or disable discovered resources and knightcode's built-in extensions. It starts with personal configuration; press Tab to switch scope, or run `knightcode config --local` to start with project overrides.
+
+## Understand scope and identity
+
+The same package can appear in personal and project settings. A project entry normally replaces the personal entry. With `autoload: false`, the project entry instead acts as a filtering delta over the personal package.
+
+KnightCode identifies npm packages by package name, git packages by repository URL without the ref, and local packages by resolved absolute path. This prevents the same package from loading twice through equivalent declarations.
+
+Use [Extensions](extensions.md), [Skills](skills.md), [Prompt Templates](prompt-templates.md), and [Themes](themes.md) to design each resource before packaging it.

package/docs/plan-mode.md

@@ -0,0 +1,121 @@
+# Plan mode
+
+Plan mode separates investigation from implementation. Enter with `/plan`, or
+send a task with `/plan <task>`. The model explores, asks about unresolved
+trade-offs, and submits a complete Markdown plan. It cannot approve its own
+plan. Sessions that never use planning gain no planning instructions or tool
+declarations.
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `/plan` | Enter planning; when already planning, review the latest draft |
+| `/plan <task>` | Enter if needed and run the task as a planning prompt |
+| `/plan off` | Leave planning without discarding the draft |
+| `/plan approve [N [note]]` | Approve the latest revision, or exactly revision N, and implement in this session; a note after N is passed to the model |
+| `/plan approve fresh [N [note]]` | Approve and implement in a fresh CLI session linked to the planning transcript |
+| `--plan` | Enter planning on initial startup only, including when initially opening a saved session |
+
+All commands require an idle session without queued messages. Finish or
+interrupt the current turn and resolve pending input first. An explicit revision
+that is no longer current is refused; run `/plan` to review again.
+
+Without a draft, `/plan` reports “No plan submitted yet; send a task to continue
+planning.” It opens no picker and starts no model request. Approval without a
+draft reports “No plan to approve.” Typing a message while planning requests a
+revision; it is not approval.
+
+## What is enforced
+
+Planning permits model-issued calls to `read`, `grep`, `find`, `ls`, `webfetch`,
+`websearch`, `bash`, `powershell`, `ask_user`, and `submit_plan`. Entering plan
+mode turns on `webfetch` and `websearch` unless they are turned off with
+`/tools`; like the other planning tools, they stay on afterwards. Every other
+tool is blocked, including file edits, MCP tools regardless of their read-only
+hints, custom tools, subagents, codemode, and tool search. Nested tool calls
+pass through the same gate. The planning instructions name only the tools the
+session has.
+
+Shell commands are not checked. The model is told to run only commands that
+inspect, but a command can still change files. User-started `!` commands are
+not gated.
+
+This is not an operating-system sandbox. KnightCode still writes session data,
+and installed extensions remain trusted code that can access files directly.
+The planning gate runs before KnightCode's built-in classifier gate. User and project extensions load first, so their handlers may
+run before it. Another extension registering `/plan`, `--plan`, or either
+planning tool replaces the built-in implementation.
+
+## Questions, submission, and review
+
+Questions offer two to four choices, recommended first, plus a free-text answer.
+The TUI shows each option's description. RPC clients receive `select` and
+`input` dialogs. Cancelling a question interrupts the run, like aborting it.
+Without UI, the model takes the recommended choice and records the decision
+under Assumptions.
+
+A submitted plan contains the goal, specific changes and paths, verification
+commands, and assumptions. Each submission replaces the complete draft and
+increments its revision. Successful submission ends the run, including a mixed
+tool-call batch; executable sibling calls are blocked. Queued user input is
+preserved, not automatically run after submission.
+
+The plan appears once in the transcript, in the submission's tool card. The TUI
+then opens review below it, in the same picker as questions: Implement,
+Implement in a fresh session, Keep planning, or Exit planning, plus **Revise the
+plan**, which takes your feedback as the next planning message. Tab adds a note
+to the highlighted choice; on an implement choice it is sent with the
+approval, and on Keep planning it is sent as feedback. Escape keeps planning. Review does not open automatically on resume. Session replacement, tree navigation, or a new run cancels an open
+picker. An action rechecks the shown revision before changing state.
+
+RPC reports a submission notification; `/plan` opens its review selection.
+JSON mode adds no extra output:
+the submission tool-call events contain the Markdown.
+
+## Print mode
+
+```sh
+knightcode -p --plan "Investigate the cache invalidation bug"
+knightcode -p "/plan Investigate the cache invalidation bug"
+knightcode --session <path-or-id> -p "/plan approve"
+```
+
+A successful planning run prints exactly the submitted Markdown. There is no
+automatic headless approval. Command-triggered planning and implementation wait
+for the complete run before print mode exits. Notices and refusals use stderr,
+not stdout.
+
+Approval is saved before same-session implementation begins. If dispatch
+fails, the approval remains saved. Fresh handoff seeds the approved draft in a
+new session, preserves the selected model and reasoning level, and dispatches
+the complete plan through the replacement session's input handlers. Cancelling
+the switch leaves the original planning state untouched. The original
+transcript remains resumable.
+
+## Persistence and configuration
+
+Draft, mode, and approved revision follow the selected session branch. Exit and
+approval retain the draft. Entering a new planning cycle clears approval while
+retaining the previous draft; revisions continue on that branch. New sessions
+start off. Resume, reload, fork, and tree navigation restore saved state rather
+than reapplying `--plan`.
+
+Planning activates `ask_user`, `submit_plan`, and any available `read`,
+`grep`, `find`, and `ls` tools in one initialization checkpoint. The loadout is
+kept after exit or approval. Later transitions append messages without rewriting
+earlier instructions or changing the tool declarations.
+
+`--tools` must allow both planning tools; `--exclude-tools` must not exclude
+one, and `--no-tools` is incompatible. Codemode `only` mode with active codemode
+is also incompatible because it hides the direct read tools. Use
+`codemode.mode: "on"` instead. Entry refuses before changing state or tools.
+Restoring incompatible or malformed planning state fails closed: startup or
+reload reports an error and cannot make provider requests until corrected.
+An incompatible tree target is cancelled before navigation.
+
+Compaction appends a frozen recovery message containing the planning rules and
+current draft, or the pinned approved plan. Overflow retries temporarily append
+the same message at the request tail until it is persisted. Later revisions
+never rewrite that recovery. See [Session File Format](session-format.md) for
+the stored snapshots and messages.

package/docs/prompt-templates.md

@@ -0,0 +1,59 @@
+# Prompt Templates
+
+Prompt templates turn Markdown files into reusable `/` commands. Use one when you want to reuse the same prompt without adding executable behavior or a larger set of supporting instructions.
+
+A template can accept arguments and appear in command completion. KnightCode can load templates from personal configuration, project configuration, an explicit path, or a KnightCode package. Project configuration loads only after project trust is granted.
+
+## Create a template
+
+Create `~/.knightcode/agent/prompts/review.md`:
+
+```markdown
+---
+description: Review staged git changes
+argument-hint: "[focus]"
+---
+Review the staged changes. Focus on ${1:-correctness, security, and error handling}.
+```
+
+The filename becomes the command name, so this template is available as `/review`. The `description` appears in command completion. If it is omitted, KnightCode uses the first non-empty line.
+
+`argument-hint` is optional. Use `<angle brackets>` for required arguments and `[square brackets]` for optional arguments.
+
+Run `/reload` after adding or changing a template in an active session.
+
+<a id="invoke-a-template"></a>
+
+## Use a template
+
+Type the template command in the editor:
+
+```text
+/review
+/review concurrency
+```
+
+KnightCode expands the template before the resulting text enters the agent. Extensions receive the raw input first through the `input` event unless an extension command with the same name handles it.
+
+Templates support these substitutions:
+
+| Syntax | Result |
+|---|---|
+| `$1`, `$2`, … | One positional argument |
+| `$@` or `$ARGUMENTS` | All arguments joined with spaces |
+| `${1:-default}` | First argument, or a default value |
+| `${@:-default}` | All arguments, or a default value |
+| `${@:N}` | Arguments starting at position `N` |
+| `${@:N:L}` | `L` arguments starting at position `N` |
+
+Arguments follow shell-like quoting, so `/review "API compatibility"` supplies one argument containing a space.
+
+<a id="choose-where-it-loads"></a>
+
+## Add it to KnightCode
+
+Place the template in your user or project prompt directory. Conventional prompt directories load direct `.md` children only.
+
+Settings and packages can select nested Markdown files; a package manifest can narrow discovery with explicit paths and globs. See [Settings](settings.md#resources) and [KnightCode Packages](packages.md) for these options.
+
+Project templates become commands in the editor after trust is granted. Review their content before trusting an unfamiliar project. See [Security](security.md#understand-project-trust).