@knightcodeai/cli 0.17.4 → 0.18.1

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).

package/docs/providers.md

@@ -0,0 +1,282 @@
+# Providers
+
+Most hosted providers support one or both of these authentication methods:
+
+- Sign in through a browser or device flow backed by OAuth.
+- Provide an API key.
+
+Use `/login [provider]` to see the methods supported by a provider. Amazon Bedrock and Google Vertex AI can also use ambient cloud credentials.
+
+## Authenticate interactively
+
+Run `/login` and select a provider. KnightCode guides you through its OAuth or API-key flow and saves the resulting credential in [`auth.json`](configuration.md#agent-directory).
+
+On a remote or headless machine, an OAuth callback may not reach the local process. When prompted, paste the final redirect URL or authorization code back into KnightCode.
+
+Run `/logout` and select a provider to remove its stored credential. This does not unset environment variables, remove authentication from `models.json`, or revoke the credential at the provider.
+
+`auth.json` can contain API keys and OAuth tokens. Keep it private and do not commit it.
+
+## Check subscription usage
+
+Run `/usage` in the interactive terminal to see remaining allowance and reset
+times reported by connected Claude (`anthropic`), OpenAI Codex (legacy)
+(`openai-codex`) and Grok (`xai`) subscription sign-ins. For Grok, run `/login xai`
+and choose "Sign in with SuperGrok or X Premium". The figures cover the whole
+account, not just the current KnightCode session. Other subscription sign-ins,
+including the current `openai` ChatGPT sign-in, are listed as unsupported.
+
+Claude shows extra usage first. KnightCode draws from extra usage rather than
+Claude's plan limits. The extra-usage percentage is account-wide and includes
+usage outside KnightCode; it does not measure this client's consumption alone.
+The plan windows are shown only for reference. Codex windows describe the plan
+allowance. Accounts with purchased credits can keep working at 0% remaining.
+
+Grok shows the weekly or monthly credit pool and, when reported, the Grok Build
+and API shares. These product lines are shares of the same pool, not separate
+allowances. Accounts with purchased credits or pay-as-you-go can keep working
+at 0% remaining. An xAI API key is billed separately and is not shown.
+
+`unavailable` means the provider did not report a valid value. A window whose
+reset has passed asks you to run `/usage` again instead of assuming the allowance
+has refilled. Each opening fetches once; there is no polling or Refresh key.
+Rate-limited providers are not requested again until their cooldown expires.
+
+The panel is read-only: it never buys credits or changes provider settings.
+It is available only in the interactive terminal, not RPC, print, JSON, or IDE
+engine sessions. It uses your configured credential store and the existing
+OAuth refresh path. Usage requests go only to the providers' fixed usage
+endpoints, not a configured model endpoint.
+
+Disable it with `"extensions": ["-builtin:usage"]` in settings, or disable all
+extensions with `--no-extensions`.
+
+## Use an API key from the environment
+
+Environment variables are useful in CI and anywhere KnightCode should not store the key. Set the variable before starting KnightCode:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+knightcode
+```
+
+This table covers providers with a single primary API-key variable. Providers that need additional configuration or support ambient credentials are covered under [Provider Specific Config](#provider-specific-config).
+
+| Provider | Environment variable |
+|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` |
+| AgentRouter | `AGENTROUTER_API_KEY` |
+| Ant Ling | `ANT_LING_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| NVIDIA NIM | `NVIDIA_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| GitHub Copilot | `COPILOT_GITHUB_TOKEN` |
+| Mistral | `MISTRAL_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| Cerebras | `CEREBRAS_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
+| ZAI Coding Plan (Global) | `ZAI_API_KEY` |
+| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` |
+| OpenCode Zen and Go | `OPENCODE_API_KEY` |
+| Radius | `RADIUS_API_KEY` |
+| TypeSafe ([classifier models](models.md#use-classifier-models)) | `TYPESAFE_API_KEY` |
+| Hugging Face | `HF_TOKEN` |
+| Fireworks | `FIREWORKS_API_KEY` |
+| Together AI | `TOGETHER_API_KEY` |
+| Baseten | `BASETEN_API_KEY` |
+| Kimi For Coding | `KIMI_API_KEY` |
+| Meta | `META_API_KEY` |
+| MiniMax | `MINIMAX_API_KEY` |
+| MiniMax (China) | `MINIMAX_CN_API_KEY` |
+| Moonshot AI (Global and China) | `MOONSHOT_API_KEY` |
+| Qwen Token Plan and Individual | `QWEN_TOKEN_PLAN_API_KEY` |
+| Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` |
+| Xiaomi MiMo | `XIAOMI_API_KEY` |
+| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` |
+| Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` |
+| Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` |
+
+Anthropic also recognizes `ANTHROPIC_OAUTH_TOKEN` as an API credential and `ANTHROPIC_AUTH_TOKEN` as bearer authentication.
+
+With no key or token set, Anthropic uses workload identity federation when `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID` and `ANTHROPIC_IDENTITY_TOKEN_FILE` are set: the Anthropic SDK exchanges the identity token for a short-lived access token and refreshes it itself (re-reading the identity token file, so keep that file fresh for long sessions). `ANTHROPIC_SERVICE_ACCOUNT_ID` and `ANTHROPIC_WORKSPACE_ID` are passed through when set.
+
+## Load an API key from a command
+
+To use a secret manager without writing the resolved key to disk, set a provider's `key` in `auth.json` to a command prefixed with `!`:
+
+```json
+{
+  "anthropic": {
+    "type": "api_key",
+    "key": "!security find-generic-password -ws 'anthropic'"
+  }
+}
+```
+
+KnightCode runs the command when the key is first needed and caches its standard output for the process lifetime. Empty output, a timeout, or a nonzero exit leaves the key unresolved until KnightCode restarts.
+
+## Provider Specific Config
+
+The providers below have additional setup, need additional settings, or can use credentials supplied by their platform.
+
+A stored API-key credential can include an `env` object. Its values take priority over the process environment for that provider:
+
+```json
+{
+  "cloudflare-workers-ai": {
+    "type": "api_key",
+    "key": "...",
+    "env": {
+      "CLOUDFLARE_ACCOUNT_ID": "account-id"
+    }
+  }
+}
+```
+
+### Radius
+
+Radius is a service crafted for KnightCode by the builders of KnightCode, Earendil Works. It provides a customizable AI gateway with organization-level controls and analytics built in, and artifacts for sharing what you create with KnightCode.
+
+To get started, run `/login radius` in KnightCode. This adds Radius as a provider, and its models appear in `/model` like any other provider's.
+
+Radius also has an MCP server, so KnightCode can manage Radius for you.
+
+Radius is currently in early alpha and evolving quickly. See [radius.earendil.com](https://radius.earendil.com) for more.
+
+Radius authentication uses its gateway catalog and caches refreshed model metadata for later offline startup. A custom Radius gateway configured in `models.json` uses its own catalog rather than inheriting the public `radius.pi.dev` catalog.
+
+### OpenRouter
+
+Authenticate with `/login openrouter` or `OPENROUTER_API_KEY`.
+
+With a key, KnightCode lists only the OpenRouter chat models that key may use, with the key's context size, max output, and prices. These come from OpenRouter's `/models/user` endpoint and reflect guardrails and provider restrictions set in OpenRouter. Image and classifier models are not filtered.
+
+KnightCode refreshes the list in the background at startup in interactive mode, when `/model` opens, after `/login`, and on `knightcode update --models`. The last list is saved and used offline and in `knightcode -p` and RPC mode. After switching keys outside `/login`, the previous key's list stays until the next refresh.
+
+Regional endpoints filter models to their region. To use one, set the base URL in [`models.json`](models.md#configure-a-compatible-endpoint):
+
+```json
+{
+  "providers": {
+    "openrouter": { "baseUrl": "https://us.openrouter.ai/api/v1" }
+  }
+}
+```
+
+If the base URL rejects the key at `/models/user` or does not have that endpoint, for example a proxy configured as the OpenRouter base URL, KnightCode lists every OpenRouter model.
+
+### Azure OpenAI
+
+The provider ID is `azure` (formerly `azure-openai-responses`). Use it as the key in `auth.json`, `models.json`, and `settings.json`, and in model references such as `--model azure/gpt-5.4`.
+
+The `azure` provider serves OpenAI models through the Responses API and Microsoft Foundry models through Chat Completions, such as `azure/deepseek-v4-pro`.
+
+Set an API key plus either a base URL or resource name:
+
+```bash
+export AZURE_OPENAI_API_KEY=...
+export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
+# Or:
+export AZURE_OPENAI_RESOURCE_NAME=your-resource
+```
+
+Resource root URLs under `ai.azure.com`, `cognitiveservices.azure.com`, and `openai.azure.com` are normalized to the OpenAI API path.
+
+KnightCode sends the model ID as the deployment name. If a deployment has a different name, map it with `AZURE_OPENAI_DEPLOYMENT_NAME_MAP`. The map applies to both the Responses API and Foundry Chat Completions:
+
+```bash
+export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-5.4=my-gpt-deployment,deepseek-v4-pro=my-deepseek
+```
+
+`AZURE_OPENAI_API_VERSION` overrides the API version for OpenAI models (default `v1`).
+
+To use a Foundry model that KnightCode does not include, add it under `azure` in [`models.json`](models.md#configure-a-compatible-endpoint) with `api: "openai-completions"`. Custom models require a `baseUrl`; `AZURE_OPENAI_BASE_URL` and `AZURE_OPENAI_RESOURCE_NAME` take priority over it when set:
+
+```json
+{
+  "providers": {
+    "azure": {
+      "baseUrl": "https://your-resource.services.ai.azure.com",
+      "models": [
+        { "id": "your-deployment", "api": "openai-completions" }
+      ]
+    }
+  }
+}
+```
+
+### Amazon Bedrock
+
+Bedrock can use a bearer token or an ambient AWS credential source:
+
+```bash
+# Named profile
+export AWS_PROFILE=your-profile
+
+# IAM keys
+export AWS_ACCESS_KEY_ID=AKIA...
+export AWS_SECRET_ACCESS_KEY=...
+# Required for temporary credentials
+export AWS_SESSION_TOKEN=...
+
+# Bedrock bearer token
+export AWS_BEARER_TOKEN_BEDROCK=...
+
+# Region, when not supplied by the profile or AWS SDK configuration
+export AWS_REGION=us-west-2
+# AWS_DEFAULT_REGION is also supported
+```
+
+KnightCode also supports ECS task credentials and IRSA through the standard `AWS_CONTAINER_CREDENTIALS_*` and `AWS_WEB_IDENTITY_TOKEN_FILE` variables.
+
+### Cloudflare AI Gateway
+
+The gateway requires a token, account ID, and gateway ID:
+
+```bash
+export CLOUDFLARE_API_KEY=...
+export CLOUDFLARE_ACCOUNT_ID=...
+export CLOUDFLARE_GATEWAY_ID=...
+```
+
+The account and gateway IDs can come from the process environment or the credential's `env` object in `auth.json`.
+
+`CLOUDFLARE_API_KEY` authenticates KnightCode to the gateway. Upstream access can use Cloudflare unified billing, credentials stored in the gateway, or an `Authorization` header configured for the provider in `models.json`.
+
+### Cloudflare Workers AI
+
+Workers AI requires a token and account ID:
+
+```bash
+export CLOUDFLARE_API_KEY=...
+export CLOUDFLARE_ACCOUNT_ID=...
+```
+
+The account ID can also be stored in the credential's `env` object.
+
+### Google Vertex AI
+
+Use a Google Cloud API key:
+
+```bash
+export GOOGLE_CLOUD_API_KEY=...
+```
+
+To use Application Default Credentials, configure a project and location:
+
+```bash
+export GOOGLE_CLOUD_PROJECT=your-project
+# GCLOUD_PROJECT is also supported
+export GOOGLE_CLOUD_LOCATION=us-central1
+```
+
+Then authenticate:
+
+```bash
+gcloud auth application-default login
+```
+
+To use a service-account key file instead, set `GOOGLE_APPLICATION_CREDENTIALS` along with the project and location.

package/docs/quickstart.md

@@ -0,0 +1,128 @@
+# Quickstart
+
+KnightCode runs in your terminal and works with files on your machine. To use it, you need access to a model through a supported provider. This can be a subscription, an API key, or a local model.
+
+For native Windows setup, read [Windows Setup](windows.md). For Android, read [Termux Setup](termux.md).
+
+## 1. Install KnightCode
+
+On macOS or Linux, you can use the installer. It installs Node.js 22.19 or newer if Node is missing or older, then installs KnightCode for your user:
+
+```bash
+curl -fsSL https://knightcode.dev/install.sh | sh
+```
+
+Alternatively, install KnightCode from npm. This requires Node.js 22.19 or newer:
+
+```bash
+npm install -g --ignore-scripts @knightcodeai/cli
+```
+
+KnightCode does not require dependency lifecycle scripts for a normal npm installation.
+
+Verify the installation:
+
+```bash
+knightcode --version
+```
+
+Supported installations download updates in the background during interactive
+sessions. When the green **Restart for vX.Y.Z** notice appears above the input,
+exit and relaunch when convenient. You can also run `knightcode update` manually. See
+[Updating KnightCode](cli.md#update-knightcode-or-packages) for supported installs
+and how to disable automatic downloads.
+
+## 2. Start KnightCode
+
+Change to the folder you want KnightCode to work with, then start it:
+
+```bash
+cd /path/to/folder
+knightcode
+```
+
+The working folder helps KnightCode discover relevant files, instructions, and configuration. KnightCode also uses it to group saved sessions.
+
+<p align="center"><img src="images/interactive-mode.png" alt="KnightCode running in a terminal with a conversation, input editor, and status footer" width="750"></p>
+
+The interface shows your conversation, an editor for prompts and commands, and a footer with the current folder, model, and session status. See [Use KnightCode in the terminal](usage.md) to learn how to add files, run commands, direct ongoing work, and manage results.
+
+## 3. Choose a model
+
+A **model** generates KnightCode's responses. A **provider** is the service or account KnightCode uses to access that model.
+
+In KnightCode, run:
+
+```text
+/login
+```
+
+Choose a provider, then follow the prompts to use a subscription or store an API key. Run `/model` afterward if you want to select a different available model.
+
+See [Choose a model and provider](models.md) for supported providers, environment-variable authentication, local models, and custom endpoints.
+
+## 4. Give KnightCode a task
+
+KnightCode shows each file read, search, command, and edit it performs. It does not ask before every tool call.
+
+Enter a task that matches your work, for example:
+
+```text
+Summarize @meeting-notes.md and save the action items to action-items.md.
+```
+
+```text
+Explain how this repository is structured and how to run its checks.
+```
+
+```text
+Compare @previous.csv with @current.csv and summarize the important changes.
+```
+
+Type `@` in the editor to search for a file instead of entering its full path. When KnightCode finishes, review its response and any changed files. Use version control or backups for important work. For untrusted or unattended work, use a container or another sandbox. See [Security](security.md).
+
+## Continue later
+
+KnightCode saves sessions automatically. Exit KnightCode, then resume the most recent session for the same working folder with:
+
+```bash
+knightcode --continue
+```
+
+Use `/resume` to choose another saved session. See [Continue or branch a session](sessions.md) for session naming, branching, compaction, export, and sharing.
+
+## Next steps
+
+- [Use KnightCode interactively](usage.md) to learn input, commands, shortcuts, and queued messages.
+- [Add instructions](configuration.md#context-files) that KnightCode should follow whenever it works in a folder.
+- [Choose a model and provider](models.md).
+
+### Choose how to customize KnightCode
+
+Start with the least powerful mechanism that meets your need:
+
+| Need | Start with |
+|---|---|
+| Give KnightCode persistent instructions for a folder | [`AGENTS.md`](configuration.md#context-files) |
+| Reuse a prompt from the `/` menu | [Prompt template](prompt-templates.md) |
+| Add task-specific instructions and supporting files | [Skill](skills.md) |
+| Add executable tools, commands, or event handlers | [Extension](extensions.md) |
+| Build a custom terminal component | [Terminal UI](tui.md) |
+| Connect an unsupported model service | [Custom provider](custom-provider.md) |
+| Install or distribute several resources | [KnightCode package](packages.md) |
+
+## Uninstall KnightCode
+
+If you installed KnightCode with npm, run:
+
+```bash
+npm uninstall -g @knightcodeai/cli
+```
+
+If you used the installer, run it again and choose **Uninstall KnightCode**:
+
+```bash
+curl -fsSL https://knightcode.dev/install.sh | sh
+```
+
+Neither method removes configuration, credentials, sessions, or installed KnightCode packages from `~/.knightcode/agent/`.

package/docs/remote.md

@@ -0,0 +1,87 @@
+# Remote sessions
+
+`/remote` publishes the session running in your terminal to the web, so you can
+watch it and reply from another device. The terminal keeps working normally.
+
+## Getting started
+
+Run `/remote`. The first time, a sign-in screen opens your browser on the
+approval page and shows an eight-character code: sign in with GitHub, check the
+page shows the same code, and approve. Escape cancels. The credential is stored
+in `~/.knightcode/remote-auth.json` and reused afterwards, and the screen also
+prints the URL for a headless box where nothing launched. Once the browser
+approves, the screen confirms it and continues on enter, or by itself a few
+seconds later.
+
+Once signed in, `/remote` prints a link. You do not have to copy it: open
+<https://remote.knightcode.dev> on your phone and the session appears in the
+list.
+
+## The web app
+
+The list shows every session you have published, newest first, with its state:
+**Working** while a turn is running in the terminal, **Connected** while the
+terminal is attached and idle, **Disconnected** once it has gone. Filter it to
+active or past sessions from the menu on the right.
+
+Open a session to read the transcript. Runs of tool calls are folded into one
+line such as _Ran 2 commands, created a file_; tap it to list the calls, and
+tap a call to see what it did — the command and its output, the file and its
+content, the diff an edit made.
+
+The composer sends replies to the terminal. Type `/` to list the slash commands
+the terminal can run from a message: extension commands, skills and prompt
+templates. Built-in commands that open a terminal UI, such as `/model`, are not
+offered.
+
+The menu in the session's top-right corner copies the link or deletes the
+session from the relay.
+
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `/remote` | Toggle publishing: start and print the link, or pause. Pausing keeps the room readable, and the next `/remote` resumes the same link |
+| `/remote status` | Show the link and how many viewers are connected |
+| `/remote stop` | Stop publishing and delete the room |
+| `/remote logout` | Revoke the stored account credential and delete it locally |
+
+`/remote` runs in the interactive terminal only. In `--print`, RPC and JSON
+modes it reports that and does nothing.
+
+## What the remote can and cannot do
+
+A viewer can read the transcript, send prompts, run the slash commands listed
+above, and stop the current turn. Prompts arrive as ordinary user messages and
+appear in your terminal; `/remote` itself is never offered to a viewer.
+
+A viewer cannot end your session, quit KnightCode, switch sessions, or change
+model. Closing the browser tab, losing signal, or losing the relay does nothing
+to the terminal. Your session ends only when you end it.
+
+If the relay becomes unreachable the command does not fail: it reconnects with
+backoff indefinitely, the footer shows `remote retrying`, and the agent carries
+on working.
+
+## Privacy and retention
+
+Room contents pass through and are briefly stored by the relay so a device that
+reconnects can catch up. That includes tool output, which can contain secrets if
+a command prints them. Nothing is redacted: anything visible in your terminal is
+visible in the room while it lives. Only the account that created a room can
+read it.
+
+A room stays readable as a past session for 30 days after the terminal
+disconnects, and is deleted then, on `/remote stop`, or when you delete it from
+the web app. Stored history is capped at 8 MB per room; older content is
+dropped as the session grows. Images are not mirrored in either direction — an
+image in the transcript appears as a placeholder recording its type and size.
+
+## Configuration
+
+| Environment variable | Default | Effect |
+| --- | --- | --- |
+| `KNIGHTCODE_REMOTE_RELAY` | `https://remote.knightcode.dev` | Relay origin to publish to |
+| `KNIGHTCODE_REMOTE_CONFIG_DIR` | `~/.knightcode` | Directory holding `remote-auth.json` |
+
+`/remote` refuses to start when `KNIGHTCODE_OFFLINE` is set.