@diffexai/diffex 0.2.3 → 0.2.5

package/docs/installation.md

@@ -1,118 +0,0 @@
-# Install, update, and remove Diffex
-
-Diffex is distributed through npmjs.org as `@diffexai/diffex`.
-Use Node.js 22.19.0 or newer and npm on macOS or Linux, on arm64 or x64.
-Windows, Android/Termux, standalone binaries, and additional installation channels are not accepted release targets.
-The hosted runtime image is for the cloud service.
-
-## Install and verify
-
-```sh
-node --version
-npm --version
-npm install -g --ignore-scripts --registry=https://registry.npmjs.org @diffexai/diffex
-diffex --version
-diffex --help
-diffex --list-models
-```
-
-Only the CLI package is needed; its internal Diffex modules are included.
-`--ignore-scripts` disables dependency installation scripts.
-Npm verifies downloaded package bytes against registry integrity metadata.
-For a reproducible installation, replace the package argument with `@diffexai/diffex@<verified-version>`, using an exact version you have checked on npmjs.org.
-
-The executable directory is `$(npm prefix -g)/bin` on supported platforms.
-If `diffex` is not found, add that directory to your shell's PATH:
-
-```sh
-export PATH="$(npm prefix -g)/bin:$PATH"
-command -v diffex
-diffex --version
-```
-
-Persist the PATH setting in your shell configuration if necessary.
-Use a Node version manager or a user-writable npm prefix when the global directory is not writable.
-Changing Node installations can change the npm prefix; check `command -v diffex` after switching.
-
-Start `diffex` in your project directory, use `/login` to configure your provider, and send a short prompt.
-See [Quickstart](quickstart.md) and [Providers](providers.md) for authentication and execution.
-
-## Upgrade
-
-```sh
-diffex update --self
-diffex --version
-```
-
-Self-update validates the response from `https://api.diffex.ai/api/latest-version` and installs exactly `@diffexai/diffex@<verified-version>` using the detected package manager.
-It rejects malformed metadata, foreign package names, redirects, and unavailable discovery before starting installation.
-`--force` permits reinstalling a verified release; it does not bypass identity checks.
-The discovery service can report no generally announced release even when a bootstrap package exists on npm.
-
-To install a reviewed npm version directly, including when discovery has no release:
-
-```sh
-npm install -g --ignore-scripts --registry=https://registry.npmjs.org '@diffexai/diffex@<verified-version>'
-diffex --version
-```
-
-Replace `<verified-version>` before running the command.
-Use your original npm prefix if it differs from the active default.
-Legacy clients that still trust Pi cannot migrate just by contacting the Diffex endpoint.
-Install the canonical package directly with the command above, then verify `command -v diffex` and `diffex --version`.
-
-## Recover an interrupted installation
-
-Npm owns replacement of an npm installation.
-If an update was interrupted or `diffex` no longer starts, repeat the pinned npm install command with the same verified version and prefix, then check `diffex --version` and `diffex --help`.
-Do not remove your user-data directory to repair an executable installation.
-Npm can begin filesystem replacement before a download finishes.
-If retrying reports `ENOTEMPTY` while renaming to a `.diffex-...` backup, move that reported backup directory aside.
-If npm instead reports `ENOTEMPTY` while removing a dependency inside `$(npm root -g)/@diffexai/diffex`, move that complete CLI installation directory aside.
-This preserves the partially installed package and lets npm install into an empty destination.
-Use a separate backup directory and retry:
-
-```sh
-DIFFEX_RECOVERY_FROM='/exact/affected/CLI/installation/or/backup'
-DIFFEX_RECOVERY_DIR="$(mktemp -d)"
-mv "$DIFFEX_RECOVERY_FROM" "$DIFFEX_RECOVERY_DIR/"
-npm install -g --ignore-scripts --registry=https://registry.npmjs.org '@diffexai/diffex@<verified-version>'
-diffex --version
-diffex --help
-```
-
-Replace both placeholders with the affected Diffex installation or backup path and the verified version.
-Move only the `@diffexai/diffex` package directory or its reported `.diffex-...` backup, preserving it until the repaired installation works.
-Do not move the global prefix, its shared `node_modules`, or another package.
-This procedure does not move or delete your settings or sessions.
-
-## Remove
-
-```sh
-npm uninstall -g --ignore-scripts @diffexai/diffex
-command -v diffex
-```
-
-Use the npm prefix that installed the executable.
-The final command should find no executable unless another installation remains on PATH.
-If your shell caches command locations, open a new terminal or refresh its command cache.
-
-Removal retains settings, credentials, sessions, installed extensions, and harness data under `~/.diffex/agent/`, or the directory selected by `DIFFEX_CODING_AGENT_DIR`.
-Project `.diffex` directories and any separately configured session directory are also retained.
-Keep this data for reinstallation; delete it separately only if you intend to erase it.
-
-## Bun package installations
-
-The same npm package can also be installed by Bun while running on Node:
-
-```sh
-bun install -g --ignore-scripts @diffexai/diffex
-diffex --version
-diffex update --self
-bun uninstall -g @diffexai/diffex
-```
-
-Use `bun pm bin -g` to locate Bun's global executable directory and add it to PATH.
-Pin direct upgrades to the reviewed `@diffexai/diffex@<verified-version>` in the install command.
-Use the manager that owns the installation for repair and removal.
-User data follows the same retention policy.

package/docs/json.md

@@ -1,91 +0,0 @@
-# JSON Event Stream Mode
-
-```bash
-diffex --mode json "Your prompt"
-```
-
-Outputs all session events as JSON lines to stdout. Useful for integrating Diffex into other tools or custom UIs.
-
-## Event Types
-
-Wire events use `JsonAgentSessionEvent`. It matches
-[`AgentSessionEvent`](https://github.com/diffexai/diffex/blob/main/packages/coding-agent/src/core/agent-session.ts)
-except that streaming message updates omit cumulative snapshots:
-
-```typescript
-type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
-
-type JsonAgentSessionEvent =
-  | Exclude<AgentSessionEvent, { type: "message_update" }>
-  | {
-      type: "message_update";
-      assistantMessageEvent: WithoutPartial<AssistantMessageEvent>;
-    };
-```
-
-`queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
-
-Other base events come from
-[`AgentEvent`](https://github.com/diffexai/diffex/blob/main/packages/agent/src/types.ts):
-
-```typescript
-type AgentEvent =
-  // Agent lifecycle
-  | { type: "agent_start" }
-  | { type: "agent_end"; messages: AgentMessage[] }
-  // Turn lifecycle
-  | { type: "turn_start" }
-  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
-  // Message lifecycle
-  | { type: "message_start"; message: AgentMessage }
-  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
-  | { type: "message_end"; message: AgentMessage }
-  // Tool execution
-  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
-  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
-  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
-```
-
-## Message Types
-
-Base messages from [`packages/ai/src/types.ts`](https://github.com/diffexai/diffex/blob/main/packages/ai/src/types.ts#L134):
-- `UserMessage` (line 134)
-- `AssistantMessage` (line 140)
-- `ToolResultMessage` (line 152)
-
-Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/diffexai/diffex/blob/main/packages/coding-agent/src/core/messages.ts#L29):
-- `BashExecutionMessage` (line 29)
-- `CustomMessage` (line 46)
-- `BranchSummaryMessage` (line 55)
-- `CompactionSummaryMessage` (line 62)
-
-## Output Format
-
-Each line is a JSON object. The first line is the session header:
-
-```json
-{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
-```
-
-Followed by events as they occur:
-
-```json
-{"type":"agent_start"}
-{"type":"turn_start"}
-{"type":"message_start","message":{"role":"assistant","content":[],...}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
-{"type":"message_end","message":{...}}
-{"type":"turn_end","message":{...},"toolResults":[]}
-{"type":"agent_end","messages":[...]}
-```
-
-`message_update` records are delta-only. They omit both the cumulative `message` field and
-`assistantMessageEvent.partial` to keep stream size linear. Use `contentIndex` and `delta`
-to assemble live text, thinking, or tool-call arguments if needed. `message_end` contains
-the final authoritative message.
-
-## Example
-
-```bash
-diffex --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
-```

package/docs/keybindings.md

@@ -1,241 +0,0 @@
-# Keybindings
-
-All keyboard shortcuts can be customized via `~/.diffex/agent/keybindings.json`. Each action can be bound to one or more keys.
-
-The config file uses the same namespaced keybinding ids that Diffex uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
-
-Older configs using pre-namespaced ids such as `cursorUp` or `expandTools` are migrated automatically to the namespaced ids on startup.
-
-After editing `keybindings.json`, run `/reload` in Diffex to apply the changes without restarting the session.
-
-## Key Format
-
-`modifier+key` where modifiers are `ctrl`, `shift`, `alt`, `super` (combinable) and keys are:
-
-- **Letters:** `a-z`
-- **Digits:** `0-9`
-- **Special:** `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`, `up`, `down`, `left`, `right`
-- **Function:** `f1`-`f12`
-- **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
-
-Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, `ctrl+1`, etc.
-
-`super` bindings require a terminal that reports the modifier separately, typically through the Kitty keyboard protocol. They may not work in terminals without that support.
-
-## All Actions
-
-### TUI Editor Cursor Movement
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.editor.cursorUp` | `up` | Move cursor up, browsing older history at the top |
-| `tui.editor.cursorDown` | `down` | Move cursor down, browsing newer history at the bottom |
-| `tui.editor.historyPrevious` | *(none)* | Select the previous prompt history entry |
-| `tui.editor.historyNext` | *(none)* | Select the next prompt history entry |
-| `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
-| `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
-| `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
-| `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | Move cursor word right |
-| `tui.editor.cursorLineStart` | `home`, `ctrl+home`, `ctrl+a` | Move to line start |
-| `tui.editor.cursorLineEnd` | `end`, `ctrl+end`, `ctrl+e` | Move to line end |
-| `tui.editor.jumpForward` | `ctrl+]` | Jump forward to character |
-| `tui.editor.jumpBackward` | `ctrl+alt+]` | Jump backward to character |
-| `tui.editor.pageUp` | `pageUp`, `ctrl+pageUp` | Scroll up by page |
-| `tui.editor.pageDown` | `pageDown`, `ctrl+pageDown` | Scroll down by page |
-
-The dedicated history actions always change history entries, regardless of the cursor position in a multiline prompt. Explicit history bindings take precedence over application actions while the main editor is focused, so binding `tui.editor.historyPrevious` to `ctrl+p` overrides model cycling in that context without changing `Ctrl+P` in selectors.
-
-### TUI Editor Deletion
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.editor.deleteCharBackward` | `backspace` | Delete character backward |
-| `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete character forward |
-| `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
-| `tui.editor.deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
-| `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to line start |
-| `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to line end |
-
-### TUI Input
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert new line |
-| `tui.input.submit` | `enter` | Submit input |
-| `tui.input.tab` | `tab` | Tab / autocomplete |
-
-### TUI Kill Ring
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
-| `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
-| `tui.editor.undo` | `ctrl+-` | Undo last edit |
-
-### TUI Clipboard and Selection
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.input.copy` | `ctrl+c` | Copy selection |
-| `tui.select.up` | `up` | Move selection up |
-| `tui.select.down` | `down` | Move selection down |
-| `tui.select.pageUp` | `pageUp` | Page up in list |
-| `tui.select.pageDown` | `pageDown` | Page down in list |
-| `tui.select.confirm` | `enter` | Confirm selection |
-| `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
-
-### TUI Fullscreen Viewport
-
-These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content.
-
-Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
-
-| Key | Default mode | Fullscreen mode |
-|-----|--------------|-----------------|
-| `home`, `end` | Editor | Transcript |
-| `ctrl+home`, `ctrl+end` | Editor | Editor |
-| `pageUp`, `pageDown` | Editor | Transcript |
-| `ctrl+pageUp`, `ctrl+pageDown` | Editor | Editor |
-
-This routing remains configurable through the ordinary action bindings. For example, `"tui.altScreen.pageUp": "ctrl+pageUp"` makes `pageUp` control the editor and `ctrl+pageUp` control the transcript in fullscreen mode. Bind `tui.altScreen.halfPageUp` and `tui.altScreen.halfPageDown` for smaller transcript steps while keeping the full-page bindings. Setting `"tui.altScreen.pageUp": []` disables that transcript shortcut entirely. User bindings replace the defaults for that action.
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.altScreen.pageUp` | `pageUp` | Scroll the transcript up by one page |
-| `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
-| `tui.altScreen.halfPageUp` | *(none)* | Scroll the transcript up by half a page |
-| `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
-| `tui.altScreen.previousPrompt` | `ctrl+shift+up` | Jump to the previous marked message |
-| `tui.altScreen.nextPrompt` | `ctrl+shift+down` | Jump to the next marked message |
-| `tui.altScreen.top` | `home` | Scroll to the beginning of the transcript |
-| `tui.altScreen.bottom` | `end` | Scroll to the transcript end and follow new output |
-
-### Application
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `app.interrupt` | `escape` | Cancel / abort |
-| `app.clear` | `ctrl+c` | Clear editor (first) / exit (second) |
-| `app.exit` | `ctrl+d` | Exit (when editor empty) |
-| `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
-| `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
-| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image or text from clipboard |
-
-### Sessions
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `app.session.new` | *(none)* | Start a new session (`/new`) |
-| `app.session.tree` | *(none)* | Open session tree navigator (`/tree`) |
-| `app.session.fork` | *(none)* | Fork current session (`/fork`) |
-| `app.session.resume` | *(none)* | Open session resume picker (`/resume`) |
-| `app.session.togglePath` | `ctrl+p` | Toggle path display |
-| `app.session.toggleSort` | `ctrl+s` | Toggle sort mode |
-| `app.session.toggleNamedFilter` | `ctrl+n` | Toggle named-only filter |
-| `app.session.rename` | `ctrl+r` | Rename session |
-| `app.session.delete` | `ctrl+d` | Delete session |
-| `app.session.deleteNoninvasive` | `ctrl+backspace` | Delete session when query is empty |
-
-### Collaboration Modes, Models, and Thinking
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `app.mode.toggle` | `shift+tab` | Toggle Default and Plan collaboration modes |
-| `app.model.select` | `ctrl+l` | Open model selector |
-| `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
-| `app.model.cycleBackward` | `shift+ctrl+p` | Cycle to previous model |
-| `app.thinking.cycle` | *(none)* | Cycle thinking level |
-| `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
-
-Shift+Tab enters or leaves interactive Plan mode. Select a model through `/model` or Ctrl+L to choose its thinking level; bind `app.thinking.cycle` explicitly if you also want a shortcut for cycling it.
-
-### Display and Message Queue
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
-| `app.message.copy` | `ctrl+x` | Copy the last assistant message, or the selected message in `/tree` |
-| `app.message.followUp` | `alt+enter` | Queue follow-up message |
-| `app.message.dequeue` | `alt+up` | Restore queued messages to editor |
-
-### Tree Navigation
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `app.tree.foldOrUp` | `ctrl+left`, `alt+left` | Fold current branch segment, or jump to the previous segment start |
-| `app.tree.unfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
-| `app.tree.editLabel` | `shift+l` | Edit the label on the selected tree node |
-| `app.tree.toggleLabelTimestamp` | `shift+t` | Toggle label timestamps in the tree |
-| `app.tree.filter.default` | `ctrl+d` | Set tree filter to default view |
-| `app.tree.filter.noTools` | `ctrl+t` | Toggle tree filter that hides tool results |
-| `app.tree.filter.userOnly` | `ctrl+u` | Toggle tree filter that shows only user messages |
-| `app.tree.filter.labeledOnly` | `ctrl+l` | Toggle tree filter that shows only labeled entries |
-| `app.tree.filter.all` | `ctrl+a` | Toggle tree filter that shows all entries |
-| `app.tree.filter.cycleForward` | `ctrl+o` | Cycle tree filter forward |
-| `app.tree.filter.cycleBackward` | `shift+ctrl+o` | Cycle tree filter backward |
-
-### Skills Selector
-
-Used inside the skill picker opened via `/skills`.
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `app.skills.toggle` | `space` | Enable or disable the current skill without closing the selector |
-
-### Scoped Models Selector
-
-Used inside the scoped models selector (opened via `/scoped-models`).
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `app.models.save` | `ctrl+s` | Save current model selection to settings |
-| `app.models.enableAll` | `ctrl+a` | Enable all models (or all matching the current search) |
-| `app.models.clearAll` | `ctrl+x` | Clear all models (or all matching the current search) |
-| `app.models.toggleProvider` | `ctrl+p` | Toggle all models for the current provider |
-| `app.models.reorderUp` | `alt+up` | Move the selected model up in the cycle order |
-| `app.models.reorderDown` | `alt+down` | Move the selected model down in the cycle order |
-
-## Custom Configuration
-
-Create `~/.diffex/agent/keybindings.json`:
-
-```json
-{
-  "tui.editor.historyPrevious": "ctrl+p",
-  "tui.editor.historyNext": "ctrl+n",
-  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
-}
-```
-
-Each action can have a single key or an array of keys. User config overrides defaults.
-
-On native Windows, `app.suspend` has no default binding because Windows terminals do not support Unix job control. If you bind it manually, Diffex shows a status message instead of suspending. In WSL, the normal Linux `ctrl+z`/`fg` behavior still applies.
-
-### Emacs Example
-
-```json
-{
-  "tui.editor.historyPrevious": "ctrl+p",
-  "tui.editor.historyNext": "ctrl+n",
-  "tui.editor.cursorLeft": ["left", "ctrl+b"],
-  "tui.editor.cursorRight": ["right", "ctrl+f"],
-  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
-  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
-  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
-  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
-  "tui.input.newLine": ["shift+enter", "ctrl+j"]
-}
-```
-
-### Vim Example
-
-```json
-{
-  "tui.editor.cursorUp": ["up", "alt+k"],
-  "tui.editor.cursorDown": ["down", "alt+j"],
-  "tui.editor.cursorLeft": ["left", "alt+h"],
-  "tui.editor.cursorRight": ["right", "alt+l"],
-  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
-  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
-}
-```

package/docs/llama-cpp.md

@@ -1,99 +0,0 @@
-# llama.cpp
-
-Diffex supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router discovers multiple GGUF models and loads or unloads them on demand.
-
-Use a current llama.cpp build with router support. Follow the [build instructions](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md) or install a [prebuilt release](https://github.com/ggml-org/llama.cpp/releases) for your platform.
-
-## Start the router
-
-Start `llama-server` without `--model` or `-m`. Passing a model starts single-model mode instead of router mode.
-
-```bash
-llama-server \
-  --models-dir ~/models \
-  --no-models-autoload \
-  --jinja \
-  --host 127.0.0.1 \
-  --port 8080 \
-  -ngl 999 \
-  -c 32768
-```
-
-Important options:
-
-- `--models-dir ~/models` discovers local GGUF files.
-- `--no-models-autoload` keeps loading explicit through `/llama`.
-- `--jinja` enables compatible chat templates and tool calling.
-- `-ngl 999` offloads as many layers as possible to the GPU.
-- `-c 32768` sets the context window for each loaded model. Omit it to use the model's native context, which may require substantially more memory.
-
-A single-file model can sit directly in the model directory. Put multimodal and multi-shard models in separate subdirectories:
-
-```text
-~/models/
-├── llama-3.2-1b-Q4_K_M.gguf
-├── gemma-3-4b-it-Q4_K_M/
-│   ├── gemma-3-4b-it-Q4_K_M.gguf
-│   └── mmproj-F16.gguf
-└── large-model-Q4_K_M/
-    ├── large-model-Q4_K_M-00001-of-00003.gguf
-    ├── large-model-Q4_K_M-00002-of-00003.gguf
-    └── large-model-Q4_K_M-00003-of-00003.gguf
-```
-
-Restart the router after manually adding files. For per-model context sizes and other options, use [llama.cpp model presets](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md#model-presets).
-
-## Configure Diffex
-
-Start Diffex and configure the provider:
-
-```text
-/login llama.cpp
-```
-
-Enter the router URL and optional API key. The default URL is `http://127.0.0.1:8080`.
-
-Environment variables can configure the same values without `/login`:
-
-```bash
-export LLAMA_BASE_URL=http://127.0.0.1:8080
-export LLAMA_API_KEY=optional-secret
-diffex
-```
-
-If the server uses an API key, start `llama-server` with the matching `--api-key` value. Keep `--host 127.0.0.1` for local-only access.
-
-## Manage models
-
-Run:
-
-```text
-/llama
-```
-
-- Select an unloaded model to load it.
-- Select a loaded model to unload it.
-- Select **Download model…**, search Hugging Face, then choose a repository and quantization. Exact `owner/repository[:quant]` values also work.
-- Press Escape during a load or download to confirm cancellation.
-
-Hugging Face search uses `HF_TOKEN` when set, then checks `$HF_TOKEN_PATH`, `$HF_HOME/token`, `$XDG_CACHE_HOME/huggingface/token`, and `~/.cache/huggingface/token`. Search also works without authentication, subject to lower rate limits. Diffex warns before downloading gated repositories and links to their access page. The llama.cpp server performs the download, so its process must also have `HF_TOKEN` when the selected repository requires access.
-
-If other models are loaded, Diffex asks whether to unload them first or keep them loaded. Diffex does not silently unload models and never deletes model files. The router may be shared with other clients, so `/llama` always displays the router's current state.
-
-Only loaded models appear in `/model`. After loading a model, run `/model` to select it for the current Diffex session.
-
-If the router disconnects, `/llama` shows **Retry** and **Close**. Retry reconnects and refreshes model state without replaying the interrupted operation.
-
-## Troubleshooting
-
-Check that the router is reachable:
-
-```bash
-curl http://127.0.0.1:8080/health
-curl http://127.0.0.1:8080/models
-```
-
-- **No models in `/llama`:** Check `--models-dir`, the directory layout, and restart the router.
-- **Model missing from `/model`:** Load it with `/llama` first.
-- **Load fails or uses too much memory:** Lower `-c` or unload another model.
-- **Server is not in router mode:** Start it without `--model`, `-m`, or `-hf`.