@octocodeai/freellama-mcp-server 0.9.0 → 0.12.0

package/docs/AGENT_CLI.md

@@ -0,0 +1,234 @@
+# Agent commands: `freellama run`, `chat`, `gateway`
+
+`freellama run` works like `ollama run`, with FreeLlama on every request:
+- a machine-calibrated Rust route when suitable evidence is available, otherwise a portable catalog pick
+- the job's documented prompts and options
+- the memory gate
+- `check:` lines that say what to verify
+
+`freellama gateway` serves the same workflows as models (`freellama/fix-bug`) to Ollama, OpenAI and
+Anthropic clients. [Every API](API.md) shows every surface.
+
+## Install
+
+```bash
+npm install -g @octocodeai/freellama     # one command: freellama
+```
+
+The npm launcher requires Node.js 22+ and installs a matching prebuilt platform package; no Rust
+compiler is needed. Source builds use Yarn and the pinned Rust toolchain instead; see
+[build from source](BUILD_AND_NOTES.md#build-from-source). Ollama and installed models are needed
+for Ollama-backed inference.
+
+| Command | Runs in | Needs |
+|---|---|---|
+| `freellama serve`, `doctor`, `init`, `catalog`, `task`, `jobs`, `bench-all`… | The prebuilt Rust binary | Node.js 22+ for the npm launcher; no Rust compiler |
+| `freellama run`, `chat`, `gateway`, `workflows`, `job`, `tool`, `tools` | Node, from `@octocodeai/freellama-mcp-server` (installed as a dependency) | Node.js 22+ |
+| `freellama status` | Human view on a terminal; JSON when piped or with `--json` | — |
+
+The agent commands ship in npm 0.11.0 and later. From a checkout, run `yarn install && yarn build`,
+then `node packages/cli/bin/freellama.js …`. A `cargo install freellama-cli` binary has the operator
+commands only.
+
+## Which command
+
+```mermaid
+flowchart TD
+    Q{"What do you want?"}
+    Q -->|"One answer, now"| R["freellama run"]
+    Q -->|"A conversation"| C["freellama chat NAME"]
+    Q -->|"An IDE, SDK or another agent<br/>to use the workflows"| G["freellama gateway"]
+    Q -->|"See the machine"| S["freellama status"]
+    Q -->|"A result from --defer"| J["freellama job ID --wait"]
+    Q -->|"Any MCP tool from a shell"| T["freellama tool NAME JSON"]
+    R --> W{"Know the model?"}
+    W -->|"no: name the work"| W1["-w WORKFLOW or -j JOB<br/>picks the model that fits"]
+    W -->|"yes"| W2["freellama run TAG"]
+```
+
+## First five minutes
+
+| Step | Command | You get |
+|---|---|---|
+| 1 | `freellama catalog` | Tested picks per job: installed, fits now |
+| 2 | `freellama workflows` | Each workflow and what it expects |
+| 3 | `git diff \| freellama run -w summarize-diff` | The summary on stdout |
+| 4 | Read stderr | `check:` lines: what to verify before you rely on the answer |
+| 5 | `freellama gateway`, then `OLLAMA_HOST=127.0.0.1:11437 ollama run freellama/explain-code` | The same workflow in the `ollama` chat |
+
+## `freellama run`
+
+```bash
+git diff | freellama run -w summarize-diff
+freellama run -w fix-bug -f path/to/parser.ts "The parser drops the last token"
+freellama run -j find-code -f 'path/to/src/**/*.ts' --top 3 "where are CLI flags parsed"
+freellama run --ask "Is a refund requested?" < ticket.txt
+freellama run --ask "Which team?" --choice billing="Payments" --choice technical="Software" < ticket.txt
+freellama run "Why is the sky blue?"                       # the chat pick that fits now
+freellama run bonsai-2:9b "Why?" --think=false             # a tag you choose
+echo "Invoice 2291, Acme, 1,240.50 EUR" | freellama run -w extract-json --schema "invoice_id, vendor, total float, currency"
+freellama run -w review-code --each -f 'src/*.ts'          # one answer per file
+```
+
+### How a run resolves
+
+```mermaid
+flowchart TD
+    A["freellama run …"] --> B{"-w, -j, -t or -m given?"}
+    B -->|"-w / -j"| P["Calibrated route or portable catalog pick<br/>+ workflow prompts and options"]
+    B -->|"-m TAG"| T["That tag"]
+    B -->|"no"| F{"First word an installed tag?"}
+    F -->|"yes"| T
+    F -->|"no, and nothing after it"| BP["It is the prompt"]
+    F -->|"no, and a prompt follows"| E(["Usage error, exit 2:<br/>did you mean …? (never pulls)"])
+    BP --> CP["Chat pick that fits now"]
+    T --> K{"Embedding model?"}
+    K -->|"yes"| V(["Prints the vector"])
+    K -->|"no"| X
+    P --> X{"Output goes to"}
+    CP --> X
+    X -->|"a terminal (or --stream)"| S["Tokens stream as Ollama generates them<br/>loaded window kept, cold load admitted"]
+    X -->|"a pipe (or --no-stream)"| M["One managed answer with its receipt"]
+    S --> O["stdout: the answer<br/>stderr: check: lines, stats with --verbose"]
+    M --> O
+```
+
+| Rule | Behavior |
+|---|---|
+| stdin | Piped or redirected input is read: the `state` of a decision, one item per line for an embedding job, else after the prompt. An agent harness's open socket never hangs the call; a socket is read only if data arrives within 250 ms |
+| Image path in the prompt | Attached as an image, as in `ollama run` |
+| `--ask` with no model | Runs on the `classify` job's tested pick; answers are named after the question (`refund-requested: true (p 0.89)`) |
+| Always managed | Decisions, embeddings, tools, batches (`--each`), `--defer`, `--preview`, `--save-as`, and explicit routing, placement or scheduling controls (`--objective`, `--prefer`, `--min-confidence`, `--priority`, `--timeout`, `--max-wait`, `--session`) |
+| serve | Started once in the background if nothing answers (log `~/.octocode/freellama/serve.log`, PID on stderr); `FREELLAMA_MCP_AUTOSTART_SERVE=0` turns it off |
+
+Job selection first asks the Rust router for a model with matching machine-local throughput
+evidence. Capable workflows also require task-quality evidence; OCR requires it too, and image
+search requires vision support. If calibration is missing, insufficient, refused or unavailable,
+selection uses the installed portable catalog picks and their live capability/memory preflight.
+The job's note identifies the choice. A throughput screen does not establish the job's accuracy:
+read `check:` lines and verify the answer. Generate calibration explicitly with
+`freellama bench-all` as described in [machine calibration](MODEL_SELECTION.md#turn-measurements-into-routing-evidence).
+Catalog ordering remains a starting point for unmeasured machines, rather than a machine-specific
+performance ranking.
+
+### Flags
+
+| Group | Flags |
+|---|---|
+| Same as `ollama run` | `--format json\|SCHEMA`, `--think[=true\|false\|LEVEL]`, `--hidethinking`, `--keepalive`, `--verbose`, `--ask` / `--choice` / `--level`, `--dimensions N`, `--nowordwrap`, `--insecure` |
+| Choose the work | `-w/--workflow`, `-j/--job`, `-m/--model`, `--fallback TAG` (repeatable: tried in order only after a refusal before running), `-t/--task`, `--objective`, `--prefer cpu\|gpu`, `--min-confidence` |
+| Inputs | `-f/--file PATH\|GLOB` (repeatable), `--image`, `-s/--system TEXT\|@FILE` (also preserved with `--suffix`), `--tools JSON\|@FILE`, `--suffix TEXT\|@FILE` (fill in the middle) |
+| Model controls | `-o/--option k=v`, `--ctx N`, `--top N` (embedding matches) |
+| Output | `--schema 'name, age int, tags list'\|JSON\|@FILE`, `-x/--extract` (first code block), `--json` (full receipt), `-q/--quiet`, `--stream` / `--no-stream` |
+| Scheduling | `--each`, `--defer`, `--idempotency-key KEY` (with `--defer`, on a serve with durable jobs), `--preview`, `--save-as NAME`, `--session`, `--priority`, `--timeout`, `--max-wait`, `--endpoint URL` |
+
+`freellama run --help` lists every flag. `--think=LEVEL` must be a level the model lists
+(`ollama show MODEL`). `--suffix` needs a model with Ollama's `insert` capability. `-x` extracts
+text; it is not a patch.
+
+Explicit managed controls remain effective with `--stream`; these requests return one managed
+answer. Fill-in-the-middle `--suffix` uses streamed completion instead and rejects managed-only
+controls, deferred/batch modes, `--json`, `--extract` and `--no-stream`; a preview still discards
+payload fields and executes nothing. A stream that ends without `done:true` exits 1 even if partial
+text has already reached stdout. Treat that partial text as incomplete.
+Buffered terminal and rewritten gateway responses share `FREELLAMA_MAX_REQUEST_BYTES` (64 MiB
+by default). It counts received bytes before decoding, including incomplete NDJSON/SSE records and
+error bodies. Overflow cancels the upstream read and fails without replay; a gateway stream that
+already started closes with an error. This per-response bound also covers buffered JSON replies;
+raw real-tag passthrough stays a pull-driven byte stream.
+
+### Exit codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | Answered | Read the `check:` lines |
+| 75 | Busy, short of memory or Ollama down | Retry; stderr gives `retry after Ns` when known |
+| 1 | Refused, failed, or an empty answer | Read stderr; an empty thinking answer says to use `--think=false` |
+| 2 | Usage error | Fix the command |
+| 130 | Interrupted (Ctrl-C cancels the running job) | — |
+
+### Embeddings and code search
+
+| Feature | How |
+|---|---|
+| Rank files by a question | `freellama run -j find-code -f GLOB --top N "question"` |
+| Persistent index | Each chunk's vector is kept in `$FREELLAMA_HOME/embedding-index/`, so a repeated search embeds only new or changed chunks (89 chunks: 7.3 s first, 0.28 s next). `FREELLAMA_EMBED_INDEX=0` turns it off |
+| Shorter vectors | `--dimensions N` on models trained for it (nomic v1.5, embeddinggemma) |
+
+## `freellama chat`, `status`, `job`, `tool`
+
+| Command | What it does |
+|---|---|
+| `freellama chat NAME` | The real `ollama` chat on a workflow (`review-code`), `freellama/auto` or a tag, through a gateway that lives as long as the chat; each answer ends with its `check:` lines |
+| `freellama status [--endpoint URL]` | On a terminal: memory, queues, usage, each loaded model (size, GPU or CPU, window, time until it unloads) and active jobs |
+| `freellama job ID [--wait\|--cancel] [--endpoint URL]` | A deferred task: `--wait` blocks until it ends and prints only the answer |
+| `freellama tool NAME [JSON\|@FILE\|-]` | Any FreeLlama MCP tool, with its own schema; `freellama tools` lists them, `freellama tool NAME --help` shows one. `tool sweep` with `start` or `resume` stays until the sweep ends |
+
+Approvals still apply: `freellama tool ollama_pull` needs the exact tag and its approved size, and
+`ollama_delete` the exact installed tag ([agent invariants](../AGENTS.md#agent-facing-invariants)).
+`freellama tool delegate_research` reads only workspaces under `FREELLAMA_MCP_ALLOWED_ROOTS`.
+
+## The gateway: workflows as models
+
+```bash
+freellama gateway                                      # 127.0.0.1:11437
+OLLAMA_HOST=127.0.0.1:11437 ollama run freellama/explain-code
+curl http://127.0.0.1:11437/v1/chat/completions -d '{"model":"freellama/review-code",
+  "messages":[{"role":"user","content":"def avg(xs): return sum(xs)/len(xs)"}]}'
+curl http://127.0.0.1:11437/v1/messages -H 'anthropic-version: 2023-06-01' -d '{"model":"freellama/explain-code",
+  "max_tokens":400,"thinking":{"type":"disabled"},"messages":[{"role":"user","content":"What does git rebase --onto do?"}]}'
+```
+
+| Model name | Runs |
+|---|---|
+| `freellama/<workflow>` | That workflow: `fix-bug`, `review-code`, `explain-code`, `summarize-log`, `extract-json`, `describe-screen`, … |
+| `freellama/<job>` | A chat-shaped job: `coding`, `summarize`, `ocr`, `image-recognition` (`summarize` uses the coding picks: `freellama catalog --job coding`) |
+| `freellama/auto` | The chat pick that fits now |
+| Any other tag | Passed through to Ollama via `serve`, with admission and telemetry |
+
+### How a request is handled
+
+```mermaid
+flowchart TD
+    R["Request to :11437"] --> O{"Origin and Host loopback?"}
+    O -->|"no"| X(["403"])
+    O -->|"yes"| V{"model is freellama/…?"}
+    V -->|"no"| PT["Passed through to serve, then Ollama"]
+    V -->|"yes"| K{"Streamed, or Anthropic / Responses?"}
+    K -->|"yes"| RW["Resolve: pick that fits, workflow prompt,<br/>options, think, loaded window, shift setting"]
+    RW --> AD{"Runner loaded with that profile?"}
+    AD -->|"yes"| FW["Forward to Ollama's own endpoint<br/>tokens and tool calls stream natively"]
+    AD -->|"no"| WM["Load through managed admission<br/>or memory assessment"]
+    WM -->|"no room"| N(["503 with the reason"])
+    WM -->|"admitted"| FW
+    K -->|"no: non-streamed Ollama or OpenAI chat"| MT["Managed run_task<br/>full receipt and checks, one chunk"]
+```
+
+| Endpoint | Clients | Virtual model |
+|---|---|---|
+| `POST /api/chat`, `/api/generate` | `ollama` CLI, Continue, Roo, Aider, Goose, Zed, Open WebUI, LangChain `ChatOllama` | Streamed by Ollama; `stream:false` is managed |
+| `POST /v1/chat/completions` | opencode, Cline, LangChain `ChatOpenAI`, Open WebUI, OpenAI SDKs | `stream:true` streamed by Ollama; otherwise managed |
+| `POST /v1/responses` | Codex (`wire_api = "responses"`), opencode | Streamed or not, by Ollama |
+| `POST /v1/messages` | Claude Code (`ANTHROPIC_BASE_URL`), Goose, Zed | Streamed or not, by Ollama |
+| `GET /api/tags`, `/v1/models`, `POST /api/show` | Model lists | Virtual models first, then installed tags |
+
+| Rule | Behavior |
+|---|---|
+| What the caller sends wins | A system message, think or reasoning setting, sampling and format stay; job mode fills only what is missing |
+| Thinking off | `reasoning_effort: "none"` (OpenAI), `thinking: {type: "disabled"}` (Anthropic), `think: false` (Ollama, Responses) |
+| Small `max_tokens` | A thinking model may spend it all: `finish_reason: "length"`, empty content |
+| Model name | Every response for a virtual model, streamed or not, names the requested virtual model (`freellama/review-code`) in the protocol's `model` field; the real tag is `freellama.model`. Real tags pass through unchanged |
+| Receipts | A `freellama` object (`model`, `checks`, `job`) that standard clients ignore. Ollama streams: on the `done` line, plus `num_ctx` and `context_source`; with `checks` in the content too for a person in a chat. OpenAI Chat streams: a top-level field on the last chunk before `data: [DONE]`. Responses streams: on the `response.completed` (or `response.incomplete`) event, beside `response`. Anthropic streams: on the `message_stop` event. Non-streamed responses: a top-level field (managed Ollama and OpenAI chats carry `job_profile` and `cached_prompt_tokens` instead of `job`). Checks cover the whole answer and its tool calls; on the OpenAI and Anthropic layers they never enter the content |
+| Security | Loopback only; non-loopback Origin or Host refused; no files read and no URLs fetched over HTTP (images must be base64) |
+| Errors | 503 when waiting can fix it (capacity, memory, Ollama, no pick that fits), else 500 |
+
+Set `FREELLAMA_AUTH_TOKEN_FILE` for a token-protected `serve`. Terminal streams, gateway discovery,
+residency/config reads and forwarded generation use this same credential as managed calls. A
+configured serve credential takes precedence over an incoming SDK placeholder bearer; without it,
+gateway forwarding retains the caller's headers. Forwarding stays on the configured serve origin,
+and authenticated fetches refuse redirects. Forwarded native requests refresh the server's
+context-shift policy within five seconds, including `ollama_default` after a runtime reload.
+
+The shipped workflows target bounded local-model tasks; their dated evaluation results do not
+qualify arbitrary models, hardware or long agent loops. Verify each answer using its checks.
+See [reliability evidence](RELIABILITY.md) for the measured workloads and limits.

package/docs/API.md

@@ -0,0 +1,160 @@
+# Every FreeLlama API
+
+FreeLlama exposes one Rust management core through several interfaces. Ollama has the complete
+managed API; an explicit local llama.cpp adapter supports bounded text tasks. Other configured
+OpenAI-compatible engines use passthrough. Pick the interface for your client, then check the
+[engine support limits](LLAMACPP.md#supported-contract-and-limits). This inventory was reviewed
+against the checkout on 2026-11-14.
+
+## Which one to use
+
+| You are | Use | Start with |
+|---|---|---|
+| An agent with MCP (Claude Code, Codex, Cursor…) | [MCP tools](#mcp-tools) | `models {view:"catalog", job}`, then `run_task {workflow}` |
+| An agent or script with only a shell | [Agent commands](#agent-commands) | `git diff \| freellama run -w summarize-diff` |
+| An Ollama, OpenAI or Anthropic client (Continue, opencode, Open WebUI, LangChain, an SDK) | [Gateway](#gateway-endpoints) | base URL `http://127.0.0.1:11437`, model `freellama/review-code` |
+| An operator | [`freellama` CLI](#freellama-commands) | `freellama init`, `freellama serve`, `freellama status` |
+| A program that wants receipts and routing | [Control API](#control-api) | `POST /_freellama/v1/tasks` |
+| An existing Ollama client that only needs admission and telemetry | [Passthrough](#ollama-compatible-passthrough) | `OLLAMA_HOST=127.0.0.1:11435` |
+
+```mermaid
+flowchart LR
+    MCP["MCP client"] --> H["MCP tool handlers<br/>(job mode, prompts, files, checks)"]
+    SH["freellama run / tool"] --> H
+    GW["freellama gateway :11437"] -->|"non-streaming chat"| H
+    GW -->|"streamed or Anthropic / Responses:<br/>rewritten with the pick and prompts"| PX
+    H --> API["serve control API<br/>/_freellama/v1/*"]
+    CLI["freellama CLI"] --> API
+    API --> O["Ollama :11434"]
+    API -->|"explicit bounded text task"| LC["Local llama.cpp"]
+    RAW["Ollama-compatible client"] --> PX["serve passthrough<br/>/api/*, /v1/*"]
+    PX --> O
+    PX -->|"configured /v1 model"| EXT["OpenAI-compatible upstream"]
+```
+
+Ports: Ollama `11434`, `freellama serve` `11435`, the CPU backend that `serve --spawn-cpu-backend`
+starts `11436`, and `freellama gateway` `11437`.
+
+## Agent commands
+
+`freellama run`, `chat`, `gateway`, `workflows`, `job`, `tool` and `tools` (and `status` on a terminal) are part of `@octocodeai/freellama`: its launcher runs them in Node from `@octocodeai/freellama-mcp-server`, a dependency ([install](AGENT_CLI.md#install)). See the [reference](AGENT_CLI.md) for flags and output rules.
+
+| Command | Does |
+|---|---|
+| `freellama run [MODEL] [PROMPT…]` | One task, streamed on a terminal. Takes `ollama run` flags plus `-w/--workflow`, `-j/--job`, `-f/--file`, `--each`, `--schema`, `-x`, `--json` and more |
+| `freellama chat [NAME]` | The real `ollama` REPL on a virtual model or a tag |
+| `freellama gateway [--port] [--endpoint]` | Serves the [gateway endpoints](#gateway-endpoints) |
+| `freellama workflows` | Workflows and jobs, with what each expects |
+| `freellama status` | On a terminal: memory, queues, loaded models, active jobs (piped or `--json`: the JSON receipt) |
+| `freellama job [ID] [--wait\|--cancel] [--endpoint URL]` | Lists deferred tasks, or gets, waits for or cancels one |
+| `freellama tool NAME [JSON\|@FILE\|-]` | Calls any [MCP tool](#mcp-tools) with its own schema. `freellama tools` lists them; `--help` shows a schema |
+
+## Gateway endpoints
+
+The gateway serves these virtual models:
+
+- `freellama/<workflow>`: fix-bug, review-code, explain-code, summarize-log, extract-json,
+  describe-screen and the rest.
+- `freellama/<job>`: coding, summarize, ocr, image-recognition.
+- `freellama/auto`: routing picks the model.
+
+Any other model name passes through to `serve`. The [reference](AGENT_CLI.md#the-gateway-workflows-as-models)
+explains the mapping.
+
+| Endpoint | Protocol | A virtual model… |
+|---|---|---|
+| `GET /api/tags`, `GET /v1/models` | Ollama, OpenAI | is listed first, before the installed tags |
+| `POST /api/show` | Ollama | is described, with capabilities |
+| `POST /api/chat`, `/api/generate` | Ollama | is streamed by Ollama (the default); with `stream:false` it runs as a managed task |
+| `POST /v1/chat/completions` | OpenAI Chat | with `stream:true` is streamed by Ollama; otherwise it runs as a managed task |
+| `POST /v1/responses` | OpenAI Responses (Codex) | is streamed or answered by Ollama |
+| `POST /v1/messages` | Anthropic Messages (Claude Code) | is streamed or answered by Ollama |
+| `GET`/`HEAD /` | Ollama heartbeat | |
+| anything else | | is proxied to `serve` |
+
+## MCP tools
+
+There are 13 tools, registered from [`tools/registrations.ts`](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/src/tools/registrations.ts).
+`freellama tool NAME` reaches every one of them.
+
+| Tool | Use it to |
+|---|---|
+| `doctor` | Check Ollama and FreeLlama health, live queues and limits (`view:"status"`), and token usage |
+| `session` | Keep related `run_task` calls on one model: create, kill, delete |
+| `models` | See catalog picks per job, installed and loaded models, one model's details, or search ollama.com and Hugging Face (`view:"library"`) |
+| `scope` | Keep chat history on the server, with revisions: create, get, fork, delete |
+| `run_task` | Run bounded work on a local model: `job` or `workflow` (built-in or [your own](PROMPTS.md#your-own-workflows)), `files`, decisions, embeddings with `nearest` (indexed, and `dimensions`), vision, tools, up to 64 batch items, `defer` (with `idempotencyKey` on a durable serve), `fallbackModels`, `preview`. Answers with text: the answer, `check:` lines and `response_file:` ([receipts](../packages/mcp/CONFIGURATION.md#where-an-answer-goes)) |
+| `task_jobs` | List, get, cancel or remove deferred work (text answers, like `run_task`) |
+| `ollama_pull` | Download one exact tag the user approved, at its reported size (`approvedSizeBytes`) |
+| `ollama_manage` | Load or free a model |
+| `ollama_delete` | Delete one exact tag the user names; it cannot be undone |
+| `delegate_research` | Answer a read-only question about a workspace or GitHub with a local agent (bash, octocode or github adapters; `coder` is opt-in) |
+| `audio` | Transcribe or translate a WAV, or speak text |
+| `sweep` | Judge a code tree, logs or a docs site chunk by chunk in the background, reporting only flagged or changed chunks |
+| `read_response` | Read a section or page of a saved `response_file` |
+
+The server also has 22 **prompts**: the 15 workflows (read-text, read-table, read-fields,
+answer-image, describe-screen, change-code, fix-bug, implement, write-tests, review-code,
+explain-code, summarize-log, summarize-text, summarize-diff, extract-json), plus classify,
+find-code, duplicates, research, github-research, sweep and `freellama`. **Resources** are
+`freellama://docs/<path>` for every bundled doc, with the index at `freellama://docs/index`.
+
+## `freellama` commands
+
+These are the operator commands of the Rust binary. The [CLI reference](CLI.md) covers flags and
+behavior.
+
+| Group | Commands |
+|---|---|
+| First run and health | `init`, `doctor`, `ready`, `machine`, `status`, `usage`, `config [--reload]` |
+| Run the service | `serve`, `proxy`, `auth-token` |
+| Models | `models`, `catalog`, `warm`, `unload` |
+| Work | `route`, `task`, `jobs`, `session`, `scope create\|get\|fork\|delete` |
+| Measure and tune | `bench-all`, `policy from-eval` |
+
+`init`, `doctor`, `catalog`, `auth-token`, `proxy`, `bench-all` and `policy` work without `serve`;
+the rest are clients of it.
+
+## Control API
+
+The control API lives at `/_freellama/v1/*` on `serve`
+([router](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/src/platform/mod.rs)).
+Every route needs the bearer token when one is configured, except `GET /_freellama/ui`.
+
+| Area | Routes |
+|---|---|
+| State | `GET health`, `GET ready`, `GET machine`, `GET models` |
+| Decide and run | `POST routes` (no inference), `POST tasks`, `POST task-batches` |
+| Affinity and history | `POST sessions`, `DELETE sessions/{id}`, `POST sessions/{id}/kill`; `POST scopes`, `GET scopes/{id}`, `DELETE scopes/{id}`, `POST scopes/{id}/fork` |
+| Residency | `POST warm`, `POST unload` |
+| Deferred jobs | `GET jobs`, `GET jobs/{id}` (`?wait_ms=N` long-polls up to 5 s: it answers when the job changes), `DELETE jobs/{id}`, `POST jobs/{id}/cancel` |
+| Monitoring | `GET metrics`, `GET status`, `GET usage`, `GET config`, `POST config/reload`, and the `GET /_freellama/ui` page |
+
+The catalog and general readiness endpoint remain Ollama-oriented. Explicit llama.cpp
+`routes` and `tasks` calls work without a reachable Ollama server, but its adapter refuses tools,
+images, embeddings, streaming and lifecycle operations. See [Managed llama.cpp](LLAMACPP.md).
+
+Request shapes are in [Architecture](ARCHITECTURE.md#request-shapes); monitoring fields are in
+[Monitoring](MONITORING.md). `POST tasks` with `"stream": true` answers with server-sent events
+(`route`, `admission`, `delta`, then `done` with the usual receipt) on supported Ollama tasks:
+
+```sh
+curl -N http://127.0.0.1:11435/_freellama/v1/tasks -H 'content-type: application/json' \
+  -d '{"task":"completion","model":"TAG","prompt":"Two sentences about llamas.","stream":true}'
+```
+
+## Ollama-compatible passthrough
+
+By default, paths outside `/_freellama/*` on `serve` are forwarded to the primary Ollama with
+byte-preserving streaming, raw admission, host-pressure holds and usage telemetry
+([sidecar](ARCHITECTURE.md#ollama-sidecar)). It covers Ollama's native `/api/*`, its
+OpenAI-compatible `/v1/*`, and the Anthropic-compatible `/v1/messages`. A few paths get special
+handling:
+
+- `/v1/*` requests go by model to the engines listed in `upstreams.toml`, and `GET /v1/models` is
+  merged across them.
+- `POST /v1/systemone` has its `assets` translated to `images`.
+- Pulls, pushes, copies, deletes and blob uploads skip the execution lock.
+- A request with `keep_alive:0` is treated as an unload.
+
+`freellama proxy` runs only this layer.