@knightcodeai/cli 0.17.4 → 0.18.1

package/docs/extensions.md

@@ -0,0 +1,420 @@
+# Extensions
+
+Extensions are TypeScript modules that add executable behavior to KnightCode. Use one when a workflow needs tools, commands, event handlers, model providers, session state, or terminal UI rather than instructions alone.
+
+An extension runs inside the KnightCode process with the same operating-system permissions. It can inspect prompts, tool calls, files, credentials, and session history, so load extensions only from sources you trust.
+
+Typical extensions add an agent tool, protect paths, confirm dangerous commands, react to session events, modify context, expose a command, or display persistent status.
+
+<a id="quick-start"></a>
+<a id="writing-an-extension"></a>
+<a id="create-an-extension"></a>
+
+## Create and load an extension
+
+An extension exports a default factory that receives `ExtensionAPI`. The factory registers capabilities for the current extension runtime.
+
+Create `~/.knightcode/agent/extensions/hello.ts`:
+
+```typescript
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+export default function (knightcode: ExtensionAPI) {
+  knightcode.registerCommand("hello", {
+    description: "Show a greeting",
+    handler: async (name, ctx) => {
+      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
+    },
+  });
+}
+```
+
+Start KnightCode and run `/hello`. During development, load a file directly:
+
+```bash
+knightcode --extension ./hello.ts
+```
+
+KnightCode uses `jiti`, so local TypeScript extensions do not need a separate compilation step. Use [KnightCode packages](packages.md) for distributed extensions and dependencies.
+
+<a id="extension-locations"></a>
+<a id="available-imports"></a>
+<a id="choose-where-it-loads"></a>
+
+## Add it to KnightCode
+
+Place the extension in your user or project extensions directory. KnightCode loads direct TypeScript or JavaScript files and subdirectories containing an `index.ts` or `index.js` entry point.
+
+Use a single file for a small extension and a directory for a multi-file implementation. Put npm dependencies in a nearby `package.json`. See [Configuration](configuration.md) for conventional locations and [Settings](settings.md#resources) for additional paths.
+
+Reload replaces the extension runtime, so code after `await ctx.reload()` must not reuse state from the old runtime. Only personal and explicit command-line extensions can participate in the `project_trust` event that runs before project extensions load.
+
+<a id="understand-the-lifecycle"></a>
+
+## Understand the runtime lifecycle
+
+The factory can be synchronous or asynchronous. KnightCode waits for an asynchronous factory before startup continues, allowing it to fetch configuration or register providers needed during startup.
+
+Do not start processes, sockets, watchers, or timers in the factory because some invocations load extensions without starting a session.
+Start long-lived resources from `session_start` or from the command or tool that needs them.
+Close session-scoped resources from an idempotent `session_shutdown` handler.
+
+A normal prompt follows this hook sequence:
+
+```mermaid
+flowchart TD
+    Input["input"] --> Before["before_agent_start"]
+    Before --> AgentStart["agent_start"]
+    AgentStart --> TurnStart["turn_start"]
+    TurnStart --> Context["context"]
+    Context --> ContextSystem["context_with_system"]
+    ContextSystem --> Headers["before_provider_headers"]
+    Headers --> Request["before_provider_request"]
+    Request --> Response["after_provider_response"]
+    Response --> Stream["provider_stream_event and assistant message events"]
+    Stream --> ToolDecision{"Assistant requested tools?"}
+    ToolDecision -->|yes| ToolStart["tool_execution_start"]
+    ToolStart --> ToolCall["tool_call"]
+    ToolCall --> Execute["execute and tool_execution_update"]
+    Execute --> ToolResult["tool_result"]
+    ToolResult --> ToolEnd["tool_execution_end"]
+    ToolEnd --> TurnEnd["turn_end"]
+    ToolDecision -->|no| TurnEnd
+    TurnEnd --> MoreTurns{"Another model turn required?"}
+    MoreTurns -->|yes| TurnStart
+    MoreTurns -->|no| AgentEnd["agent_end"]
+    AgentEnd --> MoreRuns{"Retry, recovery, compaction retry, or queued work?"}
+    MoreRuns -->|yes| AgentStart
+    MoreRuns -->|no| BeforeSettle["agent_before_settle"]
+    BeforeSettle --> Continue{"Continuation requested?"}
+    Continue -->|yes| AgentStart
+    Continue -->|no| Settled["agent_settled"]
+```
+
+The lifecycle involves these event groups:
+
+| Area | Events |
+|---|---|
+| Input preparation | `input`, `before_agent_start` |
+| Agent run | `agent_start`, `agent_end` |
+| Model turn | `turn_start`, `context`, `context_with_system`, `turn_end` |
+| Provider call | `before_provider_headers`, `before_provider_request`, `after_provider_response`, `provider_stream_event` |
+| Message lifecycle | `message_start`, `message_update`, `message_end` |
+| Tool execution | `tool_execution_start`, `tool_call`, `tool_execution_update`, `tool_result`, `tool_execution_end` |
+| Settlement | `agent_before_settle`, `agent_settled` |
+
+KnightCode counts as busy while a run starts, including the compaction check and `before_agent_start`, so messages sent meanwhile go into the starting run. Message lifecycle events also cover user and tool-result messages; the diagram places only the assistant stream where it occurs in each model turn.
+
+Tool hooks run for each tool call, and one assistant response can start another turn by returning tool calls. Provider hooks run only when that transport exposes the corresponding stage. See the exported declarations in [`extensions/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/extensions/types.ts) for exact event payloads and result types.
+
+Session startup and replacement follow a separate lifecycle:
+
+```mermaid
+flowchart TD
+    Startup["Process startup"] --> Trust["project_trust when needed"]
+    Trust --> SessionStart["session_start"]
+    Switch["/new or /resume"] --> BeforeSwitch["session_before_switch"]
+    Fork["/fork or /clone"] --> BeforeFork["session_before_fork"]
+    BeforeSwitch --> Shutdown["session_shutdown"]
+    BeforeFork --> Shutdown
+    Reload["reload"] --> Shutdown
+    Shutdown --> Replacing{"Replacing the runtime?"}
+    Replacing -->|yes| Replacement["load replacement extension runtime"]
+    Replacement --> SessionStart
+    Replacing -->|no| Stop["process exits"]
+    SessionStart --> Discover["resources_discover"]
+```
+
+`project_trust` runs before trusted project resources load and can run again when session replacement enters a new working directory. Retries, recovery, compaction, and queued messages can start another agent run after `agent_end`, so `agent_end` is not a final-idle signal. Reload and session replacement invalidate the old runtime. Code after `await ctx.reload()` still belongs to the old runtime and must not reuse its session-bound state.
+
+### Choose an event by intent
+
+| Goal | Event |
+|---|---|
+| Inspect, transform, or consume raw user input | `input` |
+| Change prompt sections, active tools, or add context before a run | `before_agent_start` |
+| Observe one low-level agent run | `agent_start`, `agent_end` |
+| Act after one model response and its tool calls | `turn_end` |
+| Filter conversation messages for one provider request | `context` |
+| Transform the complete transcript, including system messages | `context_with_system` |
+| Change request headers or the serialized provider payload | `before_provider_headers`, `before_provider_request` |
+| Observe provider response metadata or parsed stream events | `after_provider_response`, `provider_stream_event` |
+| Authorize or modify a tool call | `tool_call` |
+| Redact, annotate, or replace a tool result | `tool_result` |
+| Append final entries or request one last continuation | `agent_before_settle` |
+| Run notification work after automatic processing has stopped | `agent_settled` |
+| Initialize or release session-scoped resources | `session_start`, `session_shutdown` |
+
+<a id="agent_start--agent_end--agent_before_settle--agent_settled"></a>
+
+Use `agent_before_settle` when an extension must append entries or request one final continuation. Use `agent_settled` for notification-only work that should run after KnightCode has no automatic continuation remaining.
+
+<a id="extensionapi-methods"></a>
+
+## Choose an integration point
+
+| Capability | Main API |
+|---|---|
+| Observe or modify lifecycle behavior | `knightcode.on()` |
+| Add a model-callable operation | `knightcode.registerTool()` |
+| Add a `/` command | `knightcode.registerCommand()` |
+| Add a shortcut or CLI flag | `knightcode.registerShortcut()` or `knightcode.registerFlag()` |
+| Send user or custom messages | `knightcode.sendUserMessage()` or `knightcode.sendMessage()` |
+| Persist non-context session data | `knightcode.appendEntry()` |
+| Change active tools, model, or thinking level | Session control methods on `knightcode` |
+| Add a model provider | `knightcode.registerProvider()` |
+| Add an MCP server | `knightcode.registerMcpServer()` |
+| Route each request to a model | [`knightcode.registerVirtualModel()`](virtual-models.md) |
+| Add terminal rendering | Renderer registration and `ctx.ui` |
+| Communicate with another extension | `knightcode.events` |
+
+Use the exported declarations in [`extensions/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/extensions/types.ts) for exact event, context, tool, and result types.
+
+## Follow the extension contracts
+
+<a id="events"></a>
+<a id="work-with-events"></a>
+
+### Events and concurrency
+
+Handlers run in extension load and registration order. `knightcode.on()` returns a function that unsubscribes that registration; changes do not affect a dispatch already in progress.
+Some events notify; others transform data, replace results, or cancel an operation.
+Use each event’s declared result type rather than assuming every return value has an effect.
+
+Events cover resource discovery, sessions, agent and message lifecycle, providers, tools, and raw input.
+
+#### Understand handler composition
+
+| Pattern | Behavior |
+|---|---|
+| Notification | Return values are ignored. Use the event for observation only. |
+| In-place mutation | Later handlers see changes to values such as `before_provider_headers.headers`, `before_agent_start.systemPromptOptions`, and `tool_call.input`. |
+| Chained transformation | Later handlers receive the value returned by earlier `input`, `context`, `context_with_system`, `message_end`, `tool_result`, and `before_provider_request` handlers. |
+| Gate | A handled input, blocked tool call, cancelled session operation, or handled `user_bash` command stops that operation's normal fallback path. |
+| Actionable boundary | Each `turn_end` or `agent_before_settle` handler sees the entries and continuation decision proposed so far. |
+| Last override | The last `cache_warming_decision` handler that returns an action wins. |
+
+Notification handlers should not perform slow work on a streaming event. Transform handlers should preserve fields they do not intentionally own, and gate handlers should fail closed when their safety decision cannot be made.
+
+`before_agent_start` exposes both the current prompt and its structured `systemPromptOptions`. `event.messageType` says what started the run: `"user"` for a prompt or `knightcode.sendUserMessage()`, with `prompt` and `images`; `"custom"` for `knightcode.sendMessage(..., { triggerTurn: true })`, with the starting `message` and no `prompt`. A returned `message` is added to either kind of run; check `messageType` to skip runs started by custom messages. Prefer changing prompt sections, selected tools, or guidelines so KnightCode can append a transcript delta. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt for that run while the transcript continues recording the structured sections. Providers receive the forced text as their leading system prompt.
+
+`message_end` can replace a finalized message while preserving its role. `tool_call` can mutate input or block execution. `tool_result` handlers compose, with each handler seeing prior changes.
+
+<a id="provider_stream_event"></a>
+
+`provider_stream_event` fires for each parsed provider stream event before KnightCode normalizes it. The event identifies the provider, API, and model; `event.data` is the earliest structured value available to KnightCode, not necessarily the original HTTP bytes or SSE frame. Treat it as read-only because mutation can affect normalization. The event is notification-only and is not persisted.
+
+Handlers are awaited in stream order, so slow handlers delay stream consumption. Handler errors are reported without changing the provider response. See [`debug-provider.ts`](../examples/extensions/debug-provider.ts) for an opt-in viewer that groups raw events by assistant message.
+
+<a id="context_with_system"></a>
+
+`context` transforms conversation messages without prompt and tool system messages; KnightCode restores that state afterward. Use `context_with_system` only when a request-local transformation must own the complete transcript, and keep a system message at index zero.
+
+`turn_end` and `agent_before_settle` are actionable boundaries. Their handlers can chain proposed `custom`, `custom_message`, `context_edit`, or `compaction` entries and return `continue: true` for one next model request. Returning `end: true` ends the owning run after valid entries are committed; it overrides continuation and does not drain queued user input. `event.end` exposes the accumulated end request, which later handlers cannot undo. Guard continuation conditions because an unconditional continuation can loop. Use the exported event declarations for the complete validation and ordering contract.
+
+<a id="cache_warming_decision"></a>
+
+`cache_warming_decision` can override an idle prompt-cache refresh with `{ action: "warm" }` or `{ action: "stop" }`. The last handler that returns an action wins.
+
+Tool calls from one assistant message can run in parallel.
+Do not assume a sibling call or result exists when another tool event runs.
+Use `ctx.signal` for nested work owned by an active turn; commands and idle session events often have no operation signal.
+
+A `user_bash` handler that returns `undefined` passes the command to the next handler and then to local execution if no handler handles it. Returning `operations` or `result` stops propagation. A handler failure blocks the command rather than falling through to local execution.
+
+<a id="custom-tools"></a>
+<a id="register-tools"></a>
+
+### Tools
+
+A custom tool defines a name, model-facing description, TypeBox parameter schema, and `execute()` function.
+Its result requires model-facing `content` and a `details` field for rendering or state reconstruction.
+Use `details: undefined` when there are no structured details. If the tool makes nested model calls, include their `usage` in the result so session totals remain accurate.
+
+Throw from `execute()` to produce a failed tool result.
+Returning an object does not mark it as an error.
+Return `terminate: true` only when the agent should skip its automatic follow-up after every completed tool in that batch agrees to terminate.
+
+Use sequential execution when tools share mutable in-memory state.
+File-mutating tools should wrap the complete read-modify-write operation with `withFileMutationQueue()`.
+Truncate large model-facing results and tell the model where to read the complete output.
+
+Declare `outputSchema` and return a matching `structuredContent` when the result is data. The model still receives `content`; programmatic callers such as codemode scripts receive `structuredContent` instead of the text. Tools without `outputSchema` are passed to scripts as their text content. To report a failure that still carries data, return the result with `isError: true` instead of throwing: the model sees an error, and scripts still receive `structuredContent`.
+
+A tool can run other tools with `ctx.executeTool(name, args, { signal, onUpdate })`. Nested calls go through argument validation and the `tool_call` and `tool_result` handlers like model-issued calls, and emit `tool_execution_start`, `tool_execution_update`, and `tool_execution_end`; all of these events carry `parentToolCallId`, and their `toolCallId` is assigned by knightcode as `<parent id>/<n>`. These ids do not appear as tool calls or tool results in the transcript. Nested calls do not add transcript entries: their results only reach the calling tool, which reports them itself, for example through `onUpdate` and `details`. The session keeps a bounded record of them (name, arguments, status, duration, error; never results) as `nestedCalls` on the calling tool's result message. It is used for compaction file lists and shown in HTML exports. Arguments over 8 KiB per call or 32 KiB per tool result are omitted, at most 256 calls are kept, and `complete: false` marks a record that lost anything. The `usage` of nested results, at every depth, is added to the calling tool's result `usage`, so a tool reports only its own usage, not that of the tools it called. `ctx.tools` lists the tools `ctx.executeTool()` can call. `tool_result` handlers that redact `content` should also replace `structuredContent`; replacing only `content` drops it.
+
+See [`hello.ts`](../examples/extensions/hello.ts), [`todo.ts`](../examples/extensions/todo.ts), [`dynamic-tools.ts`](../examples/extensions/dynamic-tools.ts), and [`truncated-tool.ts`](../examples/extensions/truncated-tool.ts).
+
+### Tool exposure
+
+`exposure` controls how the model reaches a tool. "Callable" means callable from other tools through `ctx.executeTool()` (`ctx.tools`), as the `codemode` tool's scripts do:
+
+- `direct` (default): declared to the model while active, and callable while active.
+- `model-only`: declared to the model while active, never callable. Use it for tools that orchestrate other tools or ask the user.
+- `codemode`: callable whenever registered, and listed by the `codemode` tool. Not declared to the model unless activated explicitly.
+- `deferred`: like `codemode`, but codemode tools do not list it; `tool_search` can find and activate it.
+- `hidden`: registered but unreachable. Re-register a tool with `exposure: "hidden"` to withdraw it, since tools cannot be unregistered.
+
+`namespace: { name, aliases, description, instructions }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading with its `description`. `instructions` holds longer usage guidance; it is not listed, and codemode scripts read it with `describeNamespace(name)`. `aliases` are other names scripts may look the namespace up by, for example the server name `docs` for `mcp__docs`; a name and the same name as a script identifier (`my-docs`, `my_docs`) match alike.
+
+Registering a `direct` or `model-only` tool activates it unless `defaultActive: false` keeps it optional; the other exposures are not activated on registration. The active set (`knightcode.getActiveTools()`, `knightcode.setActiveTools()`) is the set of tools declared to the model. `knightcode.getAllTools()` reports each tool's `exposure`, `namespace`, `annotations`, and `reachesTools`.
+
+`annotations` are hints about what a tool does, with the meaning of MCP tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. MCP tools carry the hints their server declares. Missing hints take the MCP defaults: a tool is not read-only, and may be destructive and reach an open world. The hints are not verified, but a permission extension can use them to decide which calls to confirm. This confirms the calls Codex asks approval for:
+
+```typescript
+knightcode.on("tool_call", async (event, ctx) => {
+  const hints = knightcode.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
+  const needsApproval =
+    hints?.destructiveHint === true ||
+    (!hints?.readOnlyHint && ((hints?.destructiveHint ?? true) || (hints?.openWorldHint ?? true)));
+  if (needsApproval && !(await ctx.ui.confirm("Allow tool call?", event.toolName))) {
+    return { block: true, reason: `${event.toolName} was not approved` };
+  }
+});
+```
+
+A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure, namespace, and prompt guidelines. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. The default system prompt leaves hidden tools out of its tool list and rules, and names no tool in the skills hint when the file reader is hidden, so the orchestrating tool should present their guidelines itself. `codemode` uses only this hook, `exposure`, `reachesTools`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+
+A tool that reaches other tools declares which ones a call may reach with `reachesTools(input)`: `"all"`, or the words of the input that may name them, where a word refers to every tool or namespace whose name it contains. `codemode` returns `"all"` for scripts that search or list tools and the words of the script otherwise; `tool_search` always returns `"all"`. Extensions that register tools late use it from their `tool_call` handler to finish registering the tools a call needs before it runs, as the MCP extension does for servers that are still connecting. The MCP extension also activates `codemode` or `tool_search` for MCP tools only when the tool of that name declares `reachesTools`.
+
+### Activate tools dynamically
+
+Register every tool first, keep optional tools inactive, and use `knightcode.setActiveTools()` from a loader tool to select the desired active tools. Names must already be registered; unknown names are ignored.
+
+KnightCode records the initial prompt and tool set in the transcript's first system message, then appends tool and prompt changes before the next model request. Providers that cannot represent the transition receive a complete transcript checkpoint, which can invalidate the cached prefix.
+
+### Tool rendering
+
+A tool's `renderCall` and `renderResult` draw its calls in the interactive transcript and in HTML exports. `knightcode.registerToolRenderer((toolName, next) => renderers)` chooses renderers for calls to any tool, including tools that are not registered yet, such as MCP tools in a resumed session before their server connected. `next()` returns what the remaining resolvers (in extension load order), then the registered tool, would use, so `next() ?? mine` only fills in.
+
+### MCP servers
+
+`knightcode.registerMcpServer(name, config)` adds an MCP server for the current session. `config` has the shape of an `mcpServers` entry in [`mcp.json`](mcp.md): `command`, `args`, `env`, and `cwd` for stdio servers, `url`, `headers`, and `oauth` for HTTP servers, plus `exposure`, `toolExposure`, `description`, `enabled`, and `timeout`.
+
+```typescript
+knightcode.registerMcpServer("jira", { url: "https://mcp.example.com/jira", exposure: "codemode" });
+knightcode.unregisterMcpServer("jira");
+```
+
+Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `knightcode.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
+
+The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `knightcode.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
+
+<a id="extensioncontext"></a>
+<a id="extensioncommandcontext"></a>
+<a id="use-extension-context"></a>
+
+### Context and session changes
+
+`ExtensionContext` provides the working directory, mode, UI, session manager, model runtime, abort signal, context usage, and controls for compaction and shutdown.
+Use `ctx.modelRegistry.streamSimple()` for provider-neutral nested model calls.
+Use `ctx.modelRegistry.getAvailableClassifiers()` and `ctx.modelRegistry.classify()` to ask a classifier model structured questions, as the built-in [classifier gate](usage.md#classifier-gate) does.
+
+Command handlers receive `ExtensionCommandContext`, which adds operations for waiting until idle, reloading, tree navigation, and session replacement.
+These operations are command-only because calling them from lifecycle handlers can deadlock the runtime.
+
+Use `await ctx.sendUserMessage(content, options)` in a command when completion
+must include the dispatched run. It rejects dispatch or preflight failures and
+resolves after command handling or complete agent settlement. During an active
+run, a message sent with `deliverAs` is only queued: the promise resolves once
+it is queued, not when that run settles. The replacement context's method has
+the same contract. The originating prompt receives the nested dispatch's
+acceptance once, before settlement; command-only completion reports `handled`. Command-handler failures are reported and rethrown rather
+than acknowledged as successful. `knightcode.sendUserMessage()` remains
+fire-and-forget; waiting for idle after calling it is not equivalent because
+asynchronous preflight may still be running.
+
+`ctx.newSession({ preserveModel: true, setup, withSession })` optionally keeps
+the outgoing model and reasoning level instead of the host defaults. Capture
+plain data before replacement and dispatch through `withSession`'s context.
+
+Session replacement invalidates the old context. Capture only plain data before switching, then use the fresh context supplied to `withSession` for session-bound work.
+
+<a id="state-management"></a>
+<a id="persist-state"></a>
+
+### State
+
+Module-level variables are shared by every session in the process that loads
+the extension, and so are the providers it registers: one session calling
+`unregisterProvider` removes the provider for all of them. The desktop app's
+app server runs many sessions in one process, so keep per-session state inside
+the factory closure, not at module level. Virtual models are the exception:
+each session keeps its own route. Active cached factories are pinned; up to
+256 inactive factories remain. Eviction or `/reload` can re-evaluate a module
+on a future load, so module globals are not persistent storage. Eviction
+never tears down a live session's extension.
+
+Choose storage based on how state participates in the conversation:
+
+| State | Storage |
+|---|---|
+| Tool state that follows the active branch | Tool-result `details` |
+| Durable data excluded from model context | `knightcode.appendEntry()` |
+| Custom content stored and sent to the model | `knightcode.sendMessage()` |
+| Data outside one session | External storage |
+
+Reconstruct branch-sensitive state from `ctx.sessionManager.getBranch()` during `session_start`.
+Do not rebuild it from every file entry because abandoned branches represent alternative histories.
+Register an entry or message renderer when custom stored content should appear in the transcript.
+
+<a id="custom-ui"></a>
+<a id="mode-behavior"></a>
+<a id="interact-with-the-user"></a>
+<a id="account-for-each-mode"></a>
+
+### UI and modes
+
+`ctx.ui` provides dialogs, notifications, status text, widgets, titles, editor access, and custom components.
+Use `ctx.ui.custom()` only when the interaction needs its own rendering and input.
+See [Terminal UI](tui.md) for component, focus, overlay, theme, and performance guidance.
+
+Extensions load in interactive, RPC, JSON, print, and desktop modes.
+Desktop mode currently has no extension UI (`hasUI` is false); terminal
+components remain unavailable even when desktop dialogs are added.
+Interactive mode provides the complete terminal UI. The [DOOM overlay example](../examples/extensions/doom-overlay/) uses a custom overlay component to render a game frame by frame:
+
+<p align="center"><img src="images/doom-extension.png" alt="The DOOM overlay example running over a KnightCode session" width="750"></p>
+
+RPC can forward supported dialogs and notifications through the [RPC Extension UI protocol](rpc-extension-ui.md), but not custom terminal components; JSON and print modes have no UI.
+Guard terminal-only behavior with `ctx.mode === "tui"` and use `ctx.hasUI` for interactions supported by interactive and RPC clients.
+
+Keep tool and event behavior independent from rendering so non-interactive modes remain functional.
+
+<a id="error-handling"></a>
+<a id="handle-errors-and-shutdown"></a>
+
+### Errors and cleanup
+
+KnightCode reports handler errors and continues where possible. A `tool_call` handler failure blocks the tool as a fail-safe; a tool execution failure becomes an error result for the model.
+
+Throw the exported `ExtensionStartupError` from `session_start` when an unsafe
+runtime must refuse initialization. Binding or reload propagates it to the
+host, and the failed session cannot prompt a provider, compact, or run
+extension commands until successful startup/reload clears the failure. Ordinary
+handler errors remain nonfatal.
+
+Release resources in `session_shutdown` even when normal operation attempted cleanup.
+Keep cleanup idempotent because cancellation, reload, session replacement, and process exit can converge on the same path.
+Use `ctx.shutdown()` to request an orderly process shutdown.
+
+<a id="examples-reference"></a>
+<a id="use-examples-as-the-implementation-reference"></a>
+
+## Examples and reference
+
+The checked [extension examples](../examples/extensions/) are the implementation reference. Start with the smallest example matching the behavior you need:
+
+| Goal | Start with | Why |
+|---|---|---|
+| Confirm or block tool calls | [`permission-gate.ts`](../examples/extensions/permission-gate.ts) | Combines `tool_call`, mode-aware UI, and fail-closed behavior. |
+| Modify prompt sections for a run | [`prompt-customizer.ts`](../examples/extensions/prompt-customizer.ts) | Uses structured prompt options instead of replacing the complete prompt. |
+| Keep branch-aware tool state | [`todo.ts`](../examples/extensions/todo.ts) | Reconstructs state from persisted entries and renders it in the TUI. |
+| Register tools after startup | [`dynamic-tools.ts`](../examples/extensions/dynamic-tools.ts) | Shares registration logic between lifecycle and command handlers. |
+| Run cancellable model work from a command | [`qna.ts`](../examples/extensions/qna.ts) | Combines nested model calls, cancellation, and custom UI. |
+| Replace the main editor | [`modal-editor.ts`](../examples/extensions/modal-editor.ts) | Extends `CustomEditor` while preserving application controls. |
+| Run finalization at shutdown | [`auto-commit-on-exit.ts`](../examples/extensions/auto-commit-on-exit.ts) | Uses the session shutdown hook for finalization work. |
+| Route built-in tools to another machine | [`ssh.ts`](../examples/extensions/ssh.ts) | Reuses tool operation interfaces instead of recreating tool contracts. |
+| Add OAuth and provider-specific streaming | [`custom-provider-gitlab-duo/`](../examples/extensions/custom-provider-gitlab-duo/) | Shows a complete provider integration while delegating supported protocols. |
+
+Use [Custom Providers](custom-provider.md) for model-service integrations, [Terminal UI](tui.md) for custom components, and [KnightCode Packages](packages.md) to install or distribute extensions with other resources. Use the exported declarations for exact signatures, payloads, and result schemas; this guide focuses on lifecycle choices, composition, and durable implementation patterns.

package/docs/how-knightcode-works.md

@@ -0,0 +1,49 @@
+# How KnightCode Works
+
+KnightCode coordinates model requests, tool execution, context assembly, and session storage. A session is KnightCode's record of a conversation, including messages, tool calls and results, model changes, compactions, and other events.
+
+Messages and events in a session form a tree. Each path through that tree is a branch. The branch ending at the current entry is the active branch and supplies the history for the next model request.
+
+## Agent loop
+
+A submitted message is added to the active branch. KnightCode builds a model request from the system prompt, active branch, available tools, and model settings, then sends it through the selected provider.
+
+The provider streams an assistant response, which can contain text and tool calls. KnightCode records the response, executes each tool call, and records the results. That completes one turn. If tool results or queued messages require another model request, KnightCode starts another turn. Otherwise, the run ends.
+
+Steering messages enter after the current assistant turn. Follow-up messages enter after the agent has finished its pending work. Aborting stops the current run and returns queued messages to the editor.
+
+## Context
+
+The active branch supplies conversation history. KnightCode converts its session entries into model-compatible user, assistant, and tool-result messages.
+
+KnightCode builds the system prompt from its base instructions and discovered context files. The request also carries tool definitions and skill descriptions.
+
+Full skill instructions are loaded on demand. Extensions can add instructions or transform context.
+
+Prompt templates expand editor input before it becomes a user message. Selected files, images, pasted text, and shell output can become message content.
+
+## Sessions
+
+Persistent sessions are JSONL files. Each tree entry has an ID and refers to its parent. The current entry identifies the active branch.
+
+Continuing from an earlier entry creates another branch in the same file. Forking and cloning copy selected history into a new session file.
+
+Model context is reconstructed from the active branch. Compaction inserts a summary entry that replaces older messages in subsequent model requests. The original entries remain in the session tree.
+
+## Interfaces
+
+Interactive mode renders session and agent events in the terminal. Print mode runs a prompt and writes the final response. JSON mode writes agent events as JSONL.
+
+RPC mode accepts JSONL commands on stdin and writes responses and events to stdout. The TypeScript SDK creates and controls agent sessions in process.
+
+All interfaces use the same agent and session mechanisms.
+
+## Extensions and resources
+
+Extensions are TypeScript modules loaded into the KnightCode process. Their factory functions register tools, commands, shortcuts, providers, event handlers, renderers, and terminal UI.
+
+Skills provide on-demand instructions and supporting files. Prompt templates provide reusable message text. Themes provide terminal colors. KnightCode packages distribute these resources through npm or git.
+
+## Trust and permissions
+
+KnightCode resolves project trust before loading project settings and resources. After the trust decision and project-resource loading, KnightCode loads context files. Enabled tools use the operating-system permissions of the KnightCode process. Extensions execute inside that process.

package/docs/index.md

@@ -0,0 +1,39 @@
+# KnightCode
+
+KnightCode is an extensible AI agent that works from your terminal. Give it a goal and a working folder, and it can inspect files, run commands, edit content, and work through multi-step tasks.
+
+Use KnightCode for software development, research notes, writing projects, data files, or hobby work. You can use KnightCode as is, prompt it to adapt itself to your workflow, or build other applications powered by KnightCode using the SDK.
+
+## Start using KnightCode
+
+New to KnightCode? Follow the [Quickstart](quickstart.md) to install KnightCode, connect a model, and complete your first task.
+
+If KnightCode is already installed, choose what you want to do:
+
+- [Use KnightCode interactively](usage.md) to add files, run commands, direct ongoing work, and export results.
+- [Choose a model](models.md) or connect a subscription, API key, local model, or compatible endpoint.
+- [Continue or branch a session](sessions.md) to resume work or explore another approach without losing history.
+- [Configure KnightCode](configuration.md) for your preferences, working folders, instructions, and reusable resources.
+- [Understand how KnightCode works](how-knightcode-works.md), including tools, context, sessions, and the agent loop.
+
+## Customize KnightCode
+
+KnightCode can reuse prompts, load specialized instructions, add executable integrations, change its terminal interface, connect model services, and distribute these resources as packages.
+Use the [Quickstart customization chooser](quickstart.md#choose-how-to-customize-knightcode) to select the smallest mechanism that meets your need.
+
+## Automate or embed KnightCode
+
+- Use [print mode](cli.md#invocation-and-output) for one-off and scripted tasks.
+- Use [JSON event stream mode](json.md) to consume structured events from one run.
+- Use [RPC mode](rpc.md) to control a separate KnightCode process.
+- Use the [TypeScript SDK](sdk.md) to run KnightCode inside an application.
+
+## Find reference and setup information
+
+Use the reference pages to look up [CLI options](cli.md), [settings](settings.md), [providers](providers.md), [keybindings](keybindings.md), and [environment variables](environment-variables.md).
+
+For platform-specific help, see [Terminal Setup](terminal-setup.md), [Windows](windows.md), [tmux](tmux.md), [Termux on Android](termux.md), or [Containerization](containerization.md).
+
+## Work safely
+
+KnightCode's tools and extensions run with the permissions of the KnightCode process. Project trust controls which project resources KnightCode loads, but it does not sandbox tool calls. Review [Security](security.md) before using untrusted files, repositories, extensions, or unattended automation.