better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/index.md

@@ -0,0 +1,89 @@
+<!--
+source: https://pi.dev/docs/latest
+fetched: 2026-09-06
+-->
+
+# Pi Documentation
+
+Pi is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and pi packages.
+
+## Quick start
+
+Install Pi with npm:
+
+```
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+`--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.
+
+On Linux or macOS, you can also use the installer:
+
+```
+curl -fsSL https://pi.dev/install.sh | sh
+```
+
+To uninstall pi itself, use npm for curl and npm installs:
+
+```
+npm uninstall -g @earendil-works/pi-coding-agent
+```
+
+For pnpm, Yarn, or Bun installs, use the matching global remove command: `pnpm remove -g @earendil-works/pi-coding-agent`, `yarn global remove @earendil-works/pi-coding-agent`, or `bun uninstall -g @earendil-works/pi-coding-agent`.
+
+Then run it in a project directory:
+
+```
+pi
+```
+
+Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting pi.
+
+For the full first-run flow, see [Quickstart](/docs/latest/quickstart).
+
+## Start here
+
+- [Quickstart](/docs/latest/quickstart) - install, authenticate, and run a first session.
+- [Using Pi](/docs/latest/usage) - interactive mode, slash commands, context files, and CLI reference.
+- [Providers](/docs/latest/providers) - subscription and API-key setup for built-in providers.
+- [llama.cpp](/docs/latest/llama-cpp) - run a local router and manage models with `/llama`.
+- [Security](/docs/latest/security) - project trust, sandbox boundaries, and vulnerability reporting.
+- [Containerization](/docs/latest/containerization) - sandbox pi with Gondolin, Docker, or OpenShell.
+- [Settings](/docs/latest/settings) - global and project settings.
+- [Keybindings](/docs/latest/keybindings) - default shortcuts and custom keybindings.
+- [Sessions](/docs/latest/sessions) - session management, branching, and tree navigation.
+- [Compaction](/docs/latest/compaction) - context compaction and branch summarization.
+
+## Customization
+
+- [Extensions](/docs/latest/extensions) - TypeScript modules for tools, commands, events, and custom UI.
+- [Skills](/docs/latest/skills) - Agent Skills for reusable on-demand capabilities.
+- [Prompt templates](/docs/latest/prompt-templates) - reusable prompts that expand from slash commands.
+- [Themes](/docs/latest/themes) - built-in and custom terminal themes.
+- [Pi packages](/docs/latest/packages) - bundle and share extensions, skills, prompts, and themes.
+- [Custom models](/docs/latest/models) - add model entries for supported provider APIs.
+- [Custom providers](/docs/latest/custom-provider) - implement custom APIs and OAuth flows.
+
+## Programmatic usage
+
+- [SDK](/docs/latest/sdk) - embed pi in Node.js applications.
+- [RPC mode](/docs/latest/rpc) - integrate over stdin/stdout JSONL.
+- [JSON event stream mode](/docs/latest/json) - print mode with structured events.
+- [TUI components](/docs/latest/tui) - build custom terminal UI for extensions.
+
+## Reference
+
+- [Environment variables](/docs/latest/environment-variables) - Pi process configuration and session metadata available to bash tools.
+- [Session format](/docs/latest/session-format) - JSONL session file format, entry types, and SessionManager API.
+
+## Platform setup
+
+- [Windows](/docs/latest/windows)
+- [Termux on Android](/docs/latest/termux)
+- [tmux](/docs/latest/tmux)
+- [Terminal setup](/docs/latest/terminal-setup)
+- [Shell aliases](/docs/latest/shell-aliases)
+
+## Development
+
+- [Development](/docs/latest/development) - local setup, project structure, and debugging.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/json.md

@@ -0,0 +1,105 @@
+<!--
+source: https://pi.dev/docs/latest/json
+fetched: 2026-09-06
+-->
+
+# JSON Event Stream Mode
+
+```
+pi --mode json "Your prompt"
+```
+
+Outputs all session events as JSON lines to stdout. Useful for integrating pi into other tools or custom UIs.
+
+## Event Types
+
+Wire events use `JsonAgentSessionEvent`. It matches
+[`AgentSessionEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/agent-session.ts)
+except that streaming message updates omit cumulative snapshots:
+
+```
+type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
+
+type JsonAssistantMessageEvent<T> = T extends { type: "toolcall_start"; partial: unknown }
+  ? WithoutPartial<T> & { id: string; toolName: string }
+  : WithoutPartial<T>;
+
+type JsonAgentSessionEvent =
+  | Exclude<AgentSessionEvent, { type: "message_update" }>
+  | {
+      type: "message_update";
+      usage: Usage;
+      assistantMessageEvent: JsonAssistantMessageEvent<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/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts):
+
+```
+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/earendil-works/pi-mono/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/earendil-works/pi-mono/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:
+
+```
+{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
+```
+
+Followed by events as they occur:
+
+```
+{"type":"agent_start"}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"assistant","content":[],...}}
+{"type":"message_update","usage":{...},"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. The top-level `usage` field contains
+the latest cumulative provider-reported usage and may remain zero when a provider only reports
+usage at completion. Use `contentIndex` and `delta` to assemble live text, thinking, or tool-call
+arguments if needed. A `toolcall_start` event also includes the constant-sized `id` and `toolName`
+fields. `message_end` contains the final authoritative message.
+
+## Example
+
+```
+pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
+```

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/keybindings.md

@@ -0,0 +1,244 @@
+<!--
+source: https://pi.dev/docs/latest/keybindings
+fetched: 2026-09-06
+-->
+
+# Keybindings
+
+All keyboard shortcuts can be customized via `~/.pi/agent/keybindings.json`. Each action can be bound to one or more keys.
+
+The config file uses the same namespaced keybinding ids that pi 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 pi 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+-` (`ctrl+z` on Windows; `alt+z` on WSL) | 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. While the transcript is scrolled up, a clickable "Jump to latest message" label on its bottom row shows the `tui.altScreen.bottom` shortcut. See [Terminal setup](/docs/latest/terminal-setup) for terminal-specific mouse and trackpad behavior.
+
+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.
+
+The transcript search panel shows the configured previous/next shortcuts and clickable arrow controls. Press `tui.altScreen.search` again, or use `tui.altScreen.searchClose`, to close it.
+
+| 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 half-page steps, or bind `tui.altScreen.lineUp` and `tui.altScreen.lineDown` for single-line steps. 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.lineUp` | *(none)* | Scroll the transcript up by one line |
+| `tui.altScreen.lineDown` | *(none)* | Scroll the transcript down by one line |
+| `tui.altScreen.previousPrompt` | `ctrl+shift+up`, `ctrl+up` (`ctrl+up` only on Windows and WSL) | Jump to the previous marked message |
+| `tui.altScreen.nextPrompt` | `ctrl+shift+down`, `ctrl+down` (`ctrl+down` only on Windows and WSL) | Jump to the next marked message |
+| `tui.altScreen.search` | `ctrl+shift+f` (`ctrl+f` on Windows and WSL) | Search the rendered transcript |
+| `tui.altScreen.searchNext` | `enter`, `ctrl+g` | Select the next search match while searching |
+| `tui.altScreen.searchPrevious` | `shift+enter`, `ctrl+shift+g` | Select the previous search match while searching |
+| `tui.altScreen.searchClose` | `escape` | Close transcript search |
+| `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 and WSL) | 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 |
+
+### Models and Thinking
+
+| Keybinding id | Default | Description |
+| --- | --- | --- |
+| `app.model.select` | `ctrl+l` | Open model selector |
+| `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
+| `app.model.cycleBackward` | `shift+ctrl+p` (`alt+p` on Windows and WSL) | Cycle to previous model |
+| `app.models.save` | `ctrl+s` | Save the selected default model or scoped model configuration to settings |
+| `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
+| `app.thinking.save` | `ctrl+s` | Save current thinking level to settings |
+| `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
+
+### 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 selected message in `/tree`; otherwise copy the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
+| `app.message.followUp` | `alt+enter` (`ctrl+q` on Windows and WSL) | Queue follow-up message |
+| `app.message.dequeue` | `alt+up` (`alt+q` on Windows and WSL) | 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 |
+
+### Scoped Models Selector
+
+Used inside the scoped models selector (opened via `/scoped-models`).
+
+| Keybinding id | Default | Description |
+| --- | --- | --- |
+| `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 `~/.pi/agent/keybindings.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, pi shows a status message instead of suspending. In WSL, the normal Linux `ctrl+z`/`fg` behavior still applies.
+
+### Emacs Example
+
+```
+{
+  "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
+
+```
+{
+  "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/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/llama-cpp.md

@@ -0,0 +1,106 @@
+<!--
+source: https://pi.dev/docs/latest/llama-cpp
+fetched: 2026-09-06
+-->
+
+# llama.cpp
+
+Pi 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.
+
+```
+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:
+
+```
+~/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 Pi
+
+Start Pi and configure the provider:
+
+```
+/login llama.cpp
+```
+
+Enter the router URL and optional API key. The default URL is `http://127.0.0.1:8080`.
+
+If you start the router with `--no-models-autoload`, `/login llama.cpp` only stores the connection. Run `/llama` to load a model, then `/model` to select the loaded model for the current session.
+
+Environment variables can configure the same values without `/login`:
+
+```
+export LLAMA_BASE_URL=http://127.0.0.1:8080
+export LLAMA_API_KEY=optional-secret
+pi
+```
+
+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:
+
+```
+/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. Pi 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, Pi asks whether to unload them first or keep them loaded. Pi 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 Pi 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:
+
+```
+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`.