@knightcodeai/cli 0.17.3 → 0.18.0

package/docs/custom-provider.md

@@ -0,0 +1,173 @@
+# Custom Providers
+
+A provider extension connects KnightCode to a model service that needs custom authentication, model discovery, request handling, or streaming. If the service already speaks a supported API, configure it in `models.json` instead.
+
+Provider extensions run inside KnightCode and can inspect credentials, prompts, tool definitions, model responses, and usage. Treat them as trusted code and avoid logging secrets or provider payloads.
+
+## Choose the smallest integration
+
+| Requirement | Use |
+|---|---|
+| Add models behind a supported API | [`models.json`](models.md#configure-a-compatible-endpoint) |
+| Change an existing provider endpoint or headers | `models.json` or a small provider extension |
+| Discover models dynamically | A provider with `refreshModels` |
+| Add a `/login` flow | A provider with native or legacy OAuth configuration |
+| Implement an unsupported wire protocol | A provider with `stream` or `streamSimple` |
+
+A provider extension is an [extension](extensions.md), so it follows the same loading, trust, reload, and error behavior.
+
+## Register a provider
+
+Call `knightcode.registerProvider()` from the extension factory. KnightCode waits for asynchronous factories before startup continues, so providers registered there are available to startup model selection and `knightcode --list-models`.
+
+There are two registration forms:
+
+- Register a complete `Provider` from `@knightcode/ai` for native authentication, filtering, discovery, refresh, and streaming behavior.
+- Register a provider name with `ProviderConfig` for the legacy configuration form used by existing extensions.
+
+Prefer a complete provider for new integrations that own more than static endpoint and model metadata. KnightCode composes `models.json` overrides above a registered native provider.
+
+Registering only `baseUrl` or `headers` for an existing provider preserves its built-in models. Supplying `models` in the legacy form replaces that provider's models across chat, image, and classifier operations. An omitted `type` means `"chat"`; image and classifier models require explicit discriminants and implementations keyed by their `api` values through the `images` and `classifiers` fields.
+
+For example, a mixed-operation provider can register non-chat models and their implementations together:
+
+```typescript
+knightcode.registerProvider("media-tools", {
+  apiKey: "$MEDIA_TOOLS_API_KEY",
+  models: [
+    {
+      type: "image",
+      id: "image-v1",
+      name: "Image V1",
+      api: "media-images",
+      baseUrl: "https://media.example.com/v1",
+      input: ["text"],
+      output: ["image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    },
+    {
+      type: "classifier",
+      id: "classifier-v1",
+      name: "Classifier V1",
+      api: "media-classifier",
+      baseUrl: "https://media.example.com/v1",
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 64000,
+    },
+  ],
+  images: {
+    "media-images": { generateImages: async (model, context, options) => result },
+  },
+  classifiers: {
+    "media-classifier": { classify: async (model, context, options) => result },
+  },
+});
+```
+
+Model-level `baseUrl` values take precedence over the provider endpoint. If no `models` list is supplied, built-in models of every operation remain registered. Equal model IDs in different operations remain distinct, including their model-specific headers.
+
+Calls made after initial extension loading take effect immediately. Use `knightcode.unregisterProvider()` to remove the dynamic provider and restore built-in behavior that it replaced.
+
+See the checked [GitLab Duo provider](../examples/extensions/custom-provider-gitlab-duo/) for a complete registration that delegates streaming to built-in API implementations.
+
+## Provide authentication
+
+Static providers can resolve an API key from a literal, environment interpolation, or a command. These values use the same syntax as `models.json`:
+
+- `$NAME` and `${NAME}` read environment variables.
+- A leading `!command` uses command output.
+- `$$` emits a literal `$`.
+- `$!` emits a literal leading `!`.
+
+Use native provider authentication when the integration needs stored credentials, custom resolution, provider-scoped environment, or multiple login methods.
+
+An OAuth provider supplies a display name, login flow, token refresh, and access-token resolution. After registration it appears in `/login`, and KnightCode stores returned credentials in `~/.knightcode/agent/auth.json`.
+
+OAuth callbacks are UI-neutral. They can open an authorization URL, show a device code, report progress, request input, or ask the user to choose a login method. Honor cancellation and the supplied abort signal during network requests.
+
+Never write access tokens, refresh tokens, authorization headers, or complete provider responses to ordinary logs.
+
+## Supply and refresh models
+
+Every model needs an ID, display name, input capabilities, and cost metadata. Chat and classifier models also need a context window; chat models need an output limit and reasoning support; image models declare their output modalities. Choose the API implementation at the provider level unless one model requires an override.
+
+Set `promptCache.short` or `promptCache.long` to the provider's best-effort cache lifetime in seconds when KnightCode should keep an idle prompt cache warm. Leave them unset to disable cache warming for that retention tier.
+
+Compatibility flags describe verified differences in an otherwise supported API. Do not enable them based only on an endpoint claiming compatibility.
+
+Confirm the request fields and response behavior against the actual server.
+
+Use `refreshModels` when the available catalog comes from a live service. Pass `context.signal` to blocking I/O so callers can cancel refreshes.
+
+The two registration forms have different refresh contracts:
+
+- A complete `Provider` returns nothing. It calls `context.publish({ update })` to install provider-owned model state, after which its synchronous `getModels()` exposes the latest list.
+- Legacy `ProviderConfig.refreshModels` returns mixed-operation model definitions. KnightCode replaces that registration’s live models with the returned list and applies any requested persistence.
+
+Publish persisted catalog data only when it should survive across runs. A live service such as llama.cpp can update its in-memory list without persisting it; a remote catalog can retain a snapshot for offline startup.
+
+## Reuse a supported streaming API
+
+Use one of KnightCode AI’s API implementations whenever the provider protocol matches it.
+
+Supported implementations cover Anthropic Messages, OpenAI Chat Completions and Responses, Google Generative AI and Vertex, Azure OpenAI Responses, Mistral Conversations, and Bedrock Converse.
+
+The provider can still customize authentication, base URLs, headers, model filtering, and discovery while delegating request conversion and streaming to an existing API implementation.
+
+This is safer than copying a stream implementation because it preserves KnightCode’s message conversion, tool handling, usage accounting, cancellation, and compatibility behavior.
+
+## Implement custom streaming
+
+Implement `streamSimple` only when no existing API implementation can represent the service. Study the implementations under [`packages/ai/src/api`](https://github.com/KnightCodeAI/knightcode/tree/main/packages/ai/src/api) first.
+
+The stream receives a normalized `TranscriptContext`. System prompts and tool declarations live in transcript system messages, so read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` rather than expecting `context.systemPrompt` or `context.tools`. A model that supports mid-conversation system messages can receive them in place; otherwise call `collapseSystemMessages(context)` to fold later system messages into the leading one.
+
+A custom stream must:
+
+1. Create an assistant message with provider, model, timestamp, pending stop reason, content, and zeroed usage.
+2. After request setup succeeds, emit one `start` event before content events.
+3. Update the message while emitting balanced text, thinking, and tool-call events.
+4. Finalize usage, cost, content, and stop reason.
+5. Emit exactly one terminal `done` or `error` event and close the stream.
+6. Convert cancellation into an aborted result.
+
+Request setup can fail before `start`; in that case the stream can terminate directly with `error`. Missing request authentication may also throw synchronously before a stream is returned.
+
+Content indexes refer to blocks in the assistant message. Update each block before emitting the event whose `partial` field exposes that state. Tool-call arguments must contain valid parsed input by `toolcall_end`.
+
+The stream must also honor request instrumentation supplied through `SimpleStreamOptions`:
+
+- Call `options.onPayload` before sending the provider request and use any replacement payload it returns.
+- Call `options.onResponse` after receiving the response but before consuming its body.
+- Await `options.onProviderStreamEvent?.(providerEvent, model)` for each parsed provider event before normalizing it.
+- Pass through the abort signal and provider-scoped environment.
+
+These hooks power extension request inspection, response-header events, and provider-stream observation. Omitting them makes the provider behave differently from KnightCode’s built-in providers.
+
+## Report failures and usage
+
+Set a concrete terminal stop reason. Error and aborted messages need an `errorMessage`; successful messages need accurate input, output, cache, total-token, and cost values.
+
+KnightCode can compact and retry after recognized context-overflow errors. If the service uses an unknown message, normalize only that provider’s overflow response to `context_length_exceeded` in a guarded `message_end` handler.
+
+Do not rewrite rate limits or transient provider failures as context overflow. Those failures use KnightCode’s normal retry behavior instead.
+
+## Test the integration
+
+Test at least:
+
+- ordinary and empty text responses
+- tool calls and tool results
+- image input and image tool results when supported
+- usage and cost accounting
+- abort behavior
+- context overflow
+- malformed or partial streams
+- Unicode boundaries
+- cross-provider session handoff
+- authentication refresh and cancellation
+
+The provider tests under [`packages/ai/test`](https://github.com/KnightCodeAI/knightcode/tree/main/packages/ai/test) define the behavior expected from built-in providers. Adapt the relevant suites rather than relying only on manual prompts.
+
+Run the extension directly while developing, then move it to a discovered extension location or distribute it through a [KnightCode package](packages.md). Use `/reload` after changing a discovered provider extension in an active session.

package/docs/desktop.md

@@ -0,0 +1,73 @@
+# Desktop App
+
+The KnightCode desktop app is an Electron window over the [app server](app-server.md). It
+runs one `knightcode app-server` process and every window talks to it, so the desktop and
+the terminal share sessions, settings, credentials and extensions. Nothing about the agent
+is configured in the app itself: models, approval defaults and extensions come from your
+`settings.json`, the same file the terminal reads.
+
+The app is in development and not yet published. Phase S1 (threads, transcript, composer,
+approvals) is usable from a source checkout.
+
+## Running from source
+
+```sh
+bun install
+cd apps/desktop
+bun run start
+```
+
+In a source checkout the app starts the server with `bun packages/cli/src/bun/cli.ts
+app-server`. Set `KNIGHTCODE_DESKTOP_SERVER` to run a different command (for example an
+installed `knightcode`); `app-server` is appended. The value is split on whitespace with no
+quoting, so a path containing spaces (`C:\Program Files\...`) cannot be named; put its folder
+on `PATH` and give the bare name. A packaged build ignores it and runs only its bundled binary.
+
+Server output goes to `app-server.log` in the app's logs folder (`%APPDATA%\KnightCode\logs`
+on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on Linux).
+
+## What works
+
+- Projects: add folders to the sidebar; their threads list under them. Threads from other
+  folders appear under Recents. Pin threads to keep them at the top. The project list and
+  pins are desktop-only state in `desktop-state.json`; removing a project leaves its threads
+  on disk.
+- Threads: open any saved thread, including ones started in the terminal. A thread open in
+  a terminal session is locked there; the app says so and offers to fork it. The thread
+  menu renames, pins, forks, compacts, copies the transcript, and archives. Long threads
+  load older messages on request.
+- Composer: Enter sends, Shift+Enter adds a line (or the reverse, in Settings). While a turn
+  runs, Send queues the message to start its own turn when this one ends, and Ctrl+Enter
+  (Cmd+Enter on macOS) steers the running turn instead; Settings can swap the two. Queued
+  messages can be removed until they start. Escape on an empty composer stops the turn.
+  `@` finds files in the project, `/` lists commands, prompt templates and skills, and
+  images can be pasted or added from the `+` menu.
+- Model and thinking level per thread, from the models you are signed in to. A new thread
+  uses your default model, which Settings can change for the terminal too.
+- Approval modes: Ask for approval, Auto-edit and Full access. In Ask mode a request shows
+  a card with the decisions the server offers; Enter allows once, Escape denies, and Deny
+  can tell KnightCode why. Full access asks once per thread, and Settings can hide it.
+- Settings: send key, queue or steer, theme (System, Light, Dark), default model, signing
+  in to and out of providers, keyboard shortcuts, versions and logs.
+- Archived threads: search, unarchive, or delete for good.
+- Command palette (Ctrl+K): actions and threads in one search.
+- Quitting while threads run asks first.
+
+## Keyboard shortcuts
+
+| Action | Default |
+| --- | --- |
+| Command palette | Ctrl+K, Ctrl+Shift+P |
+| New thread | Ctrl+N |
+| Add a project folder | Ctrl+O |
+| Settings | Ctrl+, |
+| Toggle the sidebar | Ctrl+B |
+| Back / forward | Alt+Left / Alt+Right |
+| Archive the thread | Ctrl+Shift+A |
+| Send | Enter |
+| New line | Shift+Enter |
+| Steer the running turn | Ctrl+Enter |
+| Stop the running turn | Escape (empty composer) |
+| Allow / deny an approval | Enter / Escape (card focused) |
+
+On macOS, Ctrl is Cmd. Settings › Keyboard shortcuts lists every binding.

package/docs/docs.json

@@ -0,0 +1,236 @@
+{
+  "navigation": [
+    {
+      "title": "Get Started",
+      "items": [
+        {
+          "title": "Overview",
+          "path": "index.md"
+        },
+        {
+          "title": "Quickstart",
+          "path": "quickstart.md"
+        },
+        {
+          "title": "How KnightCode Works",
+          "path": "how-knightcode-works.md"
+        }
+      ]
+    },
+    {
+      "title": "Guides",
+      "items": [
+        {
+          "title": "Run KnightCode",
+          "items": [
+            {
+              "title": "Use KnightCode in the Terminal",
+              "path": "usage.md"
+            },
+            {
+              "title": "Use the Desktop App",
+              "path": "desktop.md"
+            },
+            {
+              "title": "Plan Before Implementing",
+              "path": "plan-mode.md"
+            },
+            {
+              "title": "Choose a Model",
+              "path": "models.md"
+            },
+            {
+              "title": "Manage Sessions and Context",
+              "path": "sessions.md"
+            },
+            {
+              "title": "Use Remote Sessions",
+              "path": "remote.md"
+            },
+            {
+              "title": "Run KnightCode Safely",
+              "path": "security.md"
+            },
+            {
+              "title": "Isolate KnightCode",
+              "path": "containerization.md"
+            },
+            {
+              "title": "Run Local Models",
+              "path": "llama-cpp.md"
+            },
+            {
+              "title": "Run Local Models on NVIDIA RTX",
+              "path": "nvidia-rtx-llama-cpp.md"
+            },
+            {
+              "title": "Configure Your Terminal",
+              "path": "terminal-setup.md"
+            },
+            {
+              "title": "Configure Shell Commands",
+              "path": "shell-aliases.md"
+            },
+            {
+              "title": "Run KnightCode in tmux",
+              "path": "tmux.md"
+            },
+            {
+              "title": "Run KnightCode on Windows",
+              "path": "windows.md"
+            },
+            {
+              "title": "Run KnightCode on Android",
+              "path": "termux.md"
+            }
+          ]
+        },
+        {
+          "title": "Customize KnightCode",
+          "items": [
+            {
+              "title": "Configure KnightCode",
+              "path": "configuration.md"
+            },
+            {
+              "title": "Create Prompt Templates",
+              "path": "prompt-templates.md"
+            },
+            {
+              "title": "Add Skills",
+              "path": "skills.md"
+            },
+            {
+              "title": "Create Themes",
+              "path": "themes.md"
+            },
+            {
+              "title": "Use KnightCode Packages",
+              "path": "packages.md"
+            },
+            {
+              "title": "Connect MCP Servers",
+              "path": "mcp.md"
+            }
+          ]
+        },
+        {
+          "title": "Build on KnightCode",
+          "items": [
+            {
+              "title": "Build Extensions",
+              "path": "extensions.md"
+            },
+            {
+              "title": "Add Custom Providers",
+              "path": "custom-provider.md"
+            },
+            {
+              "title": "Route with Virtual Models",
+              "path": "virtual-models.md"
+            },
+            {
+              "title": "Build Terminal UI Components",
+              "path": "tui.md"
+            },
+            {
+              "title": "Integrate with the CLI",
+              "path": "cli-integration.md"
+            },
+            {
+              "title": "Use the SDK",
+              "path": "sdk.md"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Reference",
+      "items": [
+        {
+          "title": "CLI",
+          "path": "cli.md"
+        },
+        {
+          "title": "Codemode",
+          "path": "codemode.md"
+        },
+        {
+          "title": "Slash Commands",
+          "path": "slash-commands.md"
+        },
+        {
+          "title": "Settings",
+          "path": "settings.md"
+        },
+        {
+          "title": "Models Configuration",
+          "path": "models-configuration.md"
+        },
+        {
+          "title": "Environment Variables",
+          "path": "environment-variables.md"
+        },
+        {
+          "title": "Keybindings",
+          "path": "keybindings.md"
+        },
+        {
+          "title": "Providers",
+          "path": "providers.md"
+        },
+        {
+          "title": "Session File Format",
+          "path": "session-format.md"
+        },
+        {
+          "title": "Compaction and Branch Summaries",
+          "path": "compaction.md"
+        },
+        {
+          "title": "JSON Event Stream",
+          "path": "json.md"
+        },
+        {
+          "title": "RPC Protocol",
+          "path": "rpc.md"
+        },
+        {
+          "title": "RPC Commands",
+          "path": "rpc-commands.md"
+        },
+        {
+          "title": "RPC Extension UI",
+          "path": "rpc-extension-ui.md"
+        },
+        {
+          "title": "App Server Protocol",
+          "path": "app-server.md"
+        },
+        {
+          "title": "Message Types",
+          "path": "message-types.md"
+        }
+      ]
+    }
+  ],
+  "redirects": [
+    {
+      "from": "development.md",
+      "to": "index.md"
+    },
+    {
+      "from": "session.md",
+      "to": "session-format.md"
+    },
+    {
+      "from": "tree.md",
+      "to": "sessions.md"
+    },
+    {
+      "from": "process-integration.md",
+      "to": "cli-integration.md"
+    }
+  ]
+}

package/docs/environment-variables.md

@@ -0,0 +1,138 @@
+# Environment Variables
+
+KnightCode uses environment variables in three ways:
+
+- Variables such as `KNIGHTCODE_OFFLINE` configure the KnightCode process.
+- KnightCode sets process markers so child processes can identify KnightCode as the launching agent.
+- Commands run by the LLM-callable shell tools receive `KNIGHTCODE_*` variables describing the current session.
+
+Provider API-key variables are documented separately in [Providers](providers.md#use-an-api-key-from-the-environment).
+
+## Process Marker
+
+The CLI and RPC entry points set two process markers:
+
+- `AI_AGENT=knightcode` is a generic marker that lets tooling identify KnightCode as the agent that launched the process.
+- `KNIGHTCODE_CODING_AGENT=true` is KnightCode-specific and lets child processes detect that they run inside KnightCode.
+
+Child processes inherit both markers. They are not session-specific and are not set automatically when KnightCode is embedded through the SDK.
+
+## Shell Tool Session Environment
+
+Commands run by the `bash` and `powershell` tools receive the current KnightCode session state:
+
+| Variable | Description |
+|----------|-------------|
+| `KNIGHTCODE_SESSION_ID` | Current session ID |
+| `KNIGHTCODE_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
+| `KNIGHTCODE_PROVIDER` | Currently selected model provider |
+| `KNIGHTCODE_MODEL` | Currently selected model ID |
+| `KNIGHTCODE_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
+
+The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next shell command without restarting KnightCode. `KNIGHTCODE_PROVIDER` and `KNIGHTCODE_MODEL` identify the selected KnightCode model, not a different upstream model that a router may choose internally.
+
+When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
+
+```bash
+printf '%s/%s\n' "$KNIGHTCODE_PROVIDER" "$KNIGHTCODE_MODEL"
+printf 'reasoning=%s session=%s\n' "$KNIGHTCODE_REASONING_LEVEL" "$KNIGHTCODE_SESSION_ID"
+```
+
+The session file can be inspected directly when the session is persistent:
+
+```bash
+if [ -n "$KNIGHTCODE_SESSION_FILE" ]; then
+  tail -n 1 "$KNIGHTCODE_SESSION_FILE"
+fi
+```
+
+These variables are injected into the LLM-callable `bash` and `powershell` tools. They are not injected into user-entered `!` or `!!` commands.
+
+### Custom Shell Tools
+
+Tools created with `createBashTool()` or `createPowerShellTool()` expose the session environment by default when registered with KnightCode. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
+
+```typescript
+const bashTool = createBashTool(cwd, {
+  spawnHook: (ctx) => ({
+    ...ctx,
+    env: { ...ctx.env, CI: "1" },
+  }),
+});
+```
+
+Disable session metadata independently of the spawn hook:
+
+```typescript
+const powershellTool = createPowerShellTool(cwd, {
+  exposeSessionEnvironment: false,
+  spawnHook: (ctx) => ctx,
+});
+```
+
+When disabled, KnightCode removes inherited values for these variables so nested KnightCode processes do not expose stale parent-session metadata.
+
+## KnightCode Process Configuration
+
+These variables are read by KnightCode itself:
+
+| Variable | Description |
+|----------|-------------|
+| `KNIGHTCODE_CODING_AGENT_DIR` | Override the config directory; default is `~/.knightcode/agent` |
+| `KNIGHTCODE_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
+| `KNIGHTCODE_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
+| `KNIGHTCODE_OFFLINE` | Disable automatic network activity, including model catalog refreshes |
+| `KNIGHTCODE_DISABLE_FILE_CHECKPOINTS` | Set to `1`, `true`, or `yes` to stop backing up files before edits; `/undo` then rewinds the conversation only. See [Sessions](sessions.md#file-restore) |
+| `KNIGHTCODE_SKIP_VERSION_CHECK` | Disable automatic version checks and downloads; explicit `knightcode update` still works |
+| `KNIGHTCODE_DISABLE_AUTO_UPDATE` | Set to `1` to disable automatic update downloads while retaining update notices, overriding the user-level [`autoUpdate` setting](settings.md#disable-automatic-updates); explicit `knightcode update` still works |
+| `KNIGHTCODE_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
+| `KNIGHTCODE_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
+| `KNIGHTCODE_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
+| `KNIGHTCODE_BUG_ENDPOINT` | Override the origin `/bug` uploads go to; default is `https://remote.knightcode.dev` |
+| `KNIGHTCODE_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
+| `KNIGHTCODE_CLIPBOARD_OSC52` | Set to `1` to also send copied text to the terminal with OSC 52 after the local clipboard write, as KnightCode does over SSH. Use it when a remote client reaches KnightCode without SSH variables, such as a multiplexer attached from another machine or a remote IDE daemon |
+| `KNIGHTCODE_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
+| `KNIGHTCODE_PROGRAM_STATUS` | Override OSC 7501 program status detection: `1` always reports, `0` never reports; otherwise KnightCode reports only after the terminal confirms support. See [Terminal setup](terminal-setup.md#program-status) |
+| `KNIGHTCODE_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
+| `KNIGHTCODE_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
+| `KNIGHTCODE_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
+| `BRAVE_API_KEY` | Brave Search key for `websearch` when none is stored with `/tools`; see [Web tools](usage.md#web-tools) |
+| `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
+| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
+
+### Update controls
+
+Automatic updates are on by default. For a persistent preference without
+environment variables, open `/settings` and set **Automatic updates** to `false`,
+or set `"autoUpdate": false` in your user-level `settings.json`; see
+[Disable automatic updates](settings.md#disable-automatic-updates) for file locations
+and an example.
+
+To use an environment variable instead, set it before launching KnightCode.
+For the current PowerShell terminal:
+
+```powershell
+$env:KNIGHTCODE_DISABLE_AUTO_UPDATE = "1"
+knightcode
+```
+
+To persist it for your Windows user:
+
+```powershell
+[Environment]::SetEnvironmentVariable("KNIGHTCODE_DISABLE_AUTO_UPDATE", "1", "User")
+```
+
+Then restart your terminal app or IDE so new KnightCode processes inherit it.
+On macOS or Linux, add this line to your shell profile (`~/.zshrc` or `~/.bashrc`),
+then open a new terminal:
+
+```bash
+export KNIGHTCODE_DISABLE_AUTO_UPDATE=1
+```
+
+This variable overrides `autoUpdate: true`. Any non-empty value disables automatic
+downloads, including `0`; unset it to return control to `settings.json`. To suppress
+update notices and checks too, use `KNIGHTCODE_SKIP_VERSION_CHECK=1` instead.
+Explicit `knightcode update` remains available with either variable.
+
+Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and provider-specific configuration are listed in [Providers](providers.md#use-an-api-key-from-the-environment).