local-lemonade 1.0.0

package/docs/llamacpp.md

@@ -0,0 +1,442 @@
+# llama.cpp-Specific API
+
+This page documents Lemonade's llama.cpp-specific compatibility surface.
+
+## Summary
+
+| Method | Endpoint | Description | Modality |
+|--------|----------|-------------|----------|
+| `POST` | [`/v1/rerank`](#post-v1rerank) | Reranking | query + documents -> relevance-scored documents |
+| `GET` | [`/v1/slots`](#get-v1slots) | Returns the current slots processing state | slots state |
+| `POST` | [`/v1/slots/{id}?action=save`](#post-v1slotsidactionsave) | Save the prompt cache of the specified slot to a file | prompt cache |
+| `POST` | [`/v1/slots/{id}?action=restore`](#post-v1slotsidactionrestore) | Restore the prompt cache of the specified slot from a file | prompt cache |
+| `POST` | [`/v1/slots/{id}?action=erase`](#post-v1slotsidactionerase) | Erase the prompt cache of the specified slot | prompt cache |
+| `POST` | [`/v1/tokenize`](#post-v1tokenize) | Tokenize a given text | tokenization |
+
+## `POST /v1/rerank`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Reranking API for llama.cpp-compatible reranker models. You provide a query and a list of documents, and receive relevance scores for each document. Lemonade will load the requested model automatically if it is not already loaded.
+
+> **Note:** This endpoint is part of Lemonade's llama.cpp compatibility layer. Internally, Lemonade forwards the request to llama.cpp's `/v1/rerank` endpoint.
+
+> **Note:** Lemonade also accepts `/reranking` and `/reranker` as aliases — all three route to the same handler and behave identically.
+
+> **Note:** The endpoint is available under all four path prefixes: `/api/v0/`, `/api/v1/`, `/v0/`, and `/v1/`.
+
+> **Note:** This endpoint is only available for reranker-specific models using the `llamacpp` recipe, such as `bge-reranker-v2-m3-GGUF`.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `query` | Yes | The search query text. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `documents` | Yes | Array of document strings to score against the query. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The reranking model to use. If not already loaded, Lemonade loads it before forwarding the request. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/rerank" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+        "model": "bge-reranker-v2-m3-GGUF",
+        "query": "What is the capital of France?",
+        "documents": [
+          "Paris is the capital of France.",
+          "Berlin is the capital of Germany.",
+          "Madrid is the capital of Spain."
+        ]
+      }' -UseBasicParsing
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/rerank \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "bge-reranker-v2-m3-GGUF",
+            "query": "What is the capital of France?",
+            "documents": [
+              "Paris is the capital of France.",
+              "Berlin is the capital of Germany.",
+              "Madrid is the capital of Spain."
+            ]
+          }'
+    ```
+
+### Response format
+
+```json
+{
+  "model": "bge-reranker-v2-m3-GGUF",
+  "object": "list",
+  "results": [
+    {
+      "index": 0,
+      "relevance_score": 8.60673713684082
+    },
+    {
+      "index": 1,
+      "relevance_score": -5.3886260986328125
+    },
+    {
+      "index": 2,
+      "relevance_score": -3.555561065673828
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 51,
+    "total_tokens": 51
+  }
+}
+```
+
+**Field Descriptions:**
+
+- `model` - Model identifier used for reranking
+- `object` - Type of response object, always `"list"`
+- `results` - Array of all input documents with relevance scores
+  - `index` - Original index of the document in the input array
+  - `relevance_score` - Relevance score assigned by the model; higher means more relevant
+- `usage` - Token usage statistics
+  - `prompt_tokens` - Number of tokens in the input
+  - `total_tokens` - Total tokens processed
+
+> **Note:** Results are returned in input order. To rank documents by relevance, sort `results` by `relevance_score` in descending order on the client side.
+
+## `GET /v1/slots`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Returns the current state of all processing slots in the llama.cpp server. Slots are parallel processing contexts that can handle multiple requests concurrently.
+
+> **Note:** This endpoint is part of Lemonade's llama.cpp compatibility layer. Internally, Lemonade forwards the request to llama.cpp's `/slots` endpoint.
+
+> **Note:** This endpoint is only available when a llama.cpp model is loaded.
+
+> **Note:** This endpoint supports all four path prefixes: `/api/v0/slots`, `/api/v1/slots`, `/v0/slots`, and `/v1/slots`.
+
+### Parameters
+
+This endpoint accepts no parameters.
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/slots" `
+      -Method GET -UseBasicParsing
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl http://localhost:13305/v1/slots
+    ```
+
+### Response format
+
+```json
+[
+  {
+    "id": 0,
+    "state": "idle",
+    "next_token": {
+      "has_next_token": false,
+      "n_remain": 0,
+      "n_decoded": 0
+    },
+    "task_id": -1,
+    "cache_tokens": 1024
+  },
+  {
+    "id": 1,
+    "state": "processing",
+    "next_token": {
+      "has_next_token": true,
+      "n_remain": 42,
+      "n_decoded": 15
+    },
+    "task_id": 123,
+    "cache_tokens": 512
+  }
+]
+```
+
+**Field Descriptions:**
+
+- `id` - Unique identifier for the slot
+- `state` - Current processing state ("idle", "processing", etc.)
+- `next_token` - Information about token generation state
+  - `has_next_token` - Whether more tokens are expected
+  - `n_remain` - Number of tokens remaining to generate
+  - `n_decoded` - Number of tokens already decoded
+- `task_id` - Identifier of the current task being processed (-1 if idle)
+- `cache_tokens` - Number of cached tokens in the slot's prompt cache
+
+## `POST /v1/slots/{id}?action=save`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Save the prompt cache of a specific slot to a file. This allows you to persist the current context state for later restoration.
+
+> **Note:** This endpoint is part of Lemonade's llama.cpp compatibility layer. Internally, Lemonade forwards the request to llama.cpp's `/slots/{id}?action=save` endpoint.
+
+> **Note:** The llama.cpp server must be started with the `--slot-save-path` argument for save operations to work. See [Server Configuration](../guide/configuration/README.md) for details on configuring backend arguments.
+>
+> Example configuration:
+> ```bash
+> lemonade config set llamacpp.args="--slot-save-path /path/to/slot/saves"
+> ```
+
+> **Note:** This endpoint supports all four path prefixes: `/api/v0/slots/{id}`, `/api/v1/slots/{id}`, `/v0/slots/{id}`, and `/v1/slots/{id}`.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `id` | Yes | The slot ID to save (path parameter). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `filename` | Yes | The filename where the slot cache should be saved (JSON body). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/slots/0?action=save" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{"filename": "my_conversation_cache.bin"}' -UseBasicParsing
+    ```
+
+=== "PowerShell (/api/v1)"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/api/v1/slots/0?action=save" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{"filename": "my_conversation_cache.bin"}' -UseBasicParsing
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST "http://localhost:13305/v1/slots/0?action=save" \
+      -H "Content-Type: application/json" \
+      -d '{"filename": "my_conversation_cache.bin"}'
+    ```
+
+### Response format
+
+```json
+{
+  "id_slot": 0,
+  "filename": "my_conversation_cache.bin",
+  "n_saved": 1024
+}
+```
+
+**Field Descriptions:**
+
+- `id_slot` - The slot ID that was saved
+- `filename` - The filename where the cache was saved
+- `n_saved` - Number of tokens saved to the cache file
+
+## `POST /v1/slots/{id}?action=restore`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Restore the prompt cache of a specific slot from a previously saved file. This allows you to resume a conversation or context from where you left off.
+
+> **Note:** This endpoint is part of Lemonade's llama.cpp compatibility layer. Internally, Lemonade forwards the request to llama.cpp's `/slots/{id}?action=restore` endpoint.
+
+> **Note:** The llama.cpp server must be started with the `--slot-save-path` argument for restore operations to work.
+
+> **Note:** This endpoint supports all four path prefixes: `/api/v0/slots/{id}`, `/api/v1/slots/{id}`, `/v0/slots/{id}`, and `/v1/slots/{id}`.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `id` | Yes | The slot ID to restore to (path parameter). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `filename` | Yes | The filename from which to restore the slot cache (JSON body). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/slots/0?action=restore" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{"filename": "my_conversation_cache.bin"}' -UseBasicParsing
+    ```
+
+=== "PowerShell (/api/v1)"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/api/v1/slots/0?action=restore" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{"filename": "my_conversation_cache.bin"}' -UseBasicParsing
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST "http://localhost:13305/v1/slots/0?action=restore" \
+      -H "Content-Type: application/json" \
+      -d '{"filename": "my_conversation_cache.bin"}'
+    ```
+
+### Response format
+
+```json
+{
+  "id_slot": 0,
+  "filename": "my_conversation_cache.bin",
+  "n_restored": 1024
+}
+```
+
+**Field Descriptions:**
+
+- `id_slot` - The slot ID that was restored
+- `filename` - The filename from which the cache was restored
+- `n_restored` - Number of tokens restored from the cache file
+
+## `POST /v1/slots/{id}?action=erase`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Erase (clear) the prompt cache of a specific slot. This removes all cached context from the slot, resetting it to an empty state.
+
+> **Note:** This endpoint is part of Lemonade's llama.cpp compatibility layer. Internally, Lemonade forwards the request to llama.cpp's `/slots/{id}?action=erase` endpoint.
+
+> **Note:** This endpoint supports all four path prefixes: `/api/v0/slots/{id}`, `/api/v1/slots/{id}`, `/v0/slots/{id}`, and `/v1/slots/{id}`.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `id` | Yes | The slot ID to erase (path parameter). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/slots/0?action=erase" `
+      -Method POST -UseBasicParsing
+    ```
+
+=== "PowerShell (/api/v1)"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/api/v1/slots/0?action=erase" `
+      -Method POST -UseBasicParsing
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST "http://localhost:13305/v1/slots/0?action=erase"
+    ```
+
+### Response format
+
+```json
+{
+  "id_slot": 0
+}
+```
+
+**Field Descriptions:**
+
+- `id_slot` - The slot ID that was erased
+
+> **Note:** If the server returns an error, it may indicate that the slot was not found or that the operation failed.
+
+## `POST /v1/tokenize`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Tokenize a given text. Does not count towards the current model's context window.
+
+> **Note:** This endpoint is part of Lemonade's llama.cpp compatibility layer. Internally, Lemonade forwards the request to llama.cpp's `/tokenize` endpoint.
+
+> **Note:** This endpoint supports all four path prefixes: `/api/v0/tokenize`, `/api/v1/tokenize`, `/v0/tokenize`, and `/v1/tokenize`.
+
+> **Note:** Actual response values may vary for the same string across different models if the models do not share the same tokenizer.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `content` | Yes | The text to tokenize. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `add_special` | No | Boolean indicating if special tokens, i.e. `BOS`, should be inserted. Default: `false` | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `parse_special` | No | Boolean indicating if special tokens should be tokenized. When `false` special tokens are treated as plaintext. Default: `true` | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `with_pieces` | No | Boolean indicating whether to return token pieces along with IDs. Default: `false` | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/tokenize" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{"content": "This is a string to tokenize"}' -UseBasicParsing
+    ```
+
+=== "PowerShell (/api/v1)"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/api/v1/tokenize" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{"content": "This is a string to tokenize"}' -UseBasicParsing
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST "http://localhost:13305/v1/tokenize" \
+      -H "Content-Type: application/json" \
+      -d '{"content": "This is a string to tokenize"}'
+    ```
+
+### Response format
+
+```json
+{
+  "tokens": [1919,369,264,886,310,74995]
+}
+```
+
+If `with_pieces` is `true`:
+
+```json
+{
+  "tokens": [
+    {"id": 123, "piece": "Hello"},
+    {"id": 456, "piece": " world"},
+    {"id": 789, "piece": "!"}
+  ]
+}
+```
+
+**Field Descriptions:**
+
+- `tokens` - Array of token IDs

package/docs/mcp.md

@@ -0,0 +1,199 @@
+# MCP Gateway
+
+Lemonade exposes its inference capabilities as a Model Context Protocol (MCP) server, so any MCP-compatible client (GitHub Copilot, Claude Desktop, MCP Inspector, Cursor, the `mcp` Python client, etc.) can call your locally running models as tools.
+
+The gateway implements the **MCP "Streamable HTTP" transport** (spec version `2025-06-18`) with the `tools` capability only. All traffic flows through a single endpoint:
+
+| Endpoint | Status | Notes |
+|----------|--------|-------|
+| `POST /mcp` | Supported | JSON-RPC 2.0 envelope. Accepts a single message or a batch array. |
+| `GET /mcp` | `405 Method Not Allowed` | Server-initiated SSE channel is not supported. |
+
+> **Why a single path?** The MCP specification mandates one endpoint URL per server, so `/mcp` is an intentional exception to Lemonade's quad-prefix convention.
+
+## Authentication
+
+`/mcp` is treated as a regular API route, so it honors `LEMONADE_API_KEY` exactly like `/api/v1/chat/completions`:
+
+```bash
+curl -s http://localhost:13305/mcp \
+    -H "Authorization: Bearer $LEMONADE_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
+```
+
+## Supported methods
+
+| Method | Purpose |
+|--------|---------|
+| `initialize` | Negotiate protocol version, return server identity and capabilities. |
+| `notifications/initialized` | Client acknowledgement; silently accepted. |
+| `tools/list` | Return the catalogue of callable tools (with JSON Schemas). |
+| `tools/call` | Invoke one of the tools below. |
+| `ping` | Liveness probe; returns `{}`. |
+
+## Tools
+
+All tools auto-load (and download, if missing) the requested model on first call, exactly like `POST /v1/chat/completions`. Errors are returned as MCP results with `"isError": true` rather than JSON-RPC errors, matching the spec's guidance for tool failures.
+
+### `lemonade_list_models`
+
+Discover what's loaded, what's downloaded, and what's recommended. Call this first if you don't already know the exact model name to pass to the other tools — passing a wrong name may trigger a multi-GB download.
+
+```json
+{
+  "name": "lemonade_list_models",
+  "arguments": {
+    "include_available": true,
+    "include_suggested": true
+  }
+}
+```
+
+Returns a summary text block plus a JSON-stringified text block with `{loaded, available, suggested_to_pull, recommended_chat_model}`.
+
+### `lemonade_chat`
+
+Chat completion against any LLM in the registry.
+
+```json
+{
+  "name": "lemonade_chat",
+  "arguments": {
+    "model": "Qwen3-1.7B-GGUF",
+    "messages": [
+      {"role": "system", "content": "You are concise."},
+      {"role": "user", "content": "Summarize MCP in one line."}
+    ],
+    "max_tokens": 64,
+    "temperature": 0.2
+  }
+}
+```
+
+Returns one text block with the assistant content. If the model emits tool calls, a second text block containing `tool_calls: <json>` is appended.
+
+Reasoning models (Qwen3, DeepSeek-R1, ...) have the `<think>` block disabled by default to keep small `max_tokens` budgets from being consumed by reasoning. Pass `"chat_template_kwargs": {"enable_thinking": true}` to opt back in.
+
+> **Picking a portable model.** The example above uses `Qwen3-1.7B-GGUF` because GGUF (llama.cpp) runs everywhere lemonade does — Windows, Linux/Docker, macOS, CPU and Vulkan/ROCm/Metal GPUs. Hybrid/NPU variants such as `*-Hybrid` (recipe `ryzenai-llm`, **Windows + AMD RyzenAI** only) or `*-FLM` (recipe `flm`, **AMD Ryzen AI NPU** only) are faster on supported hardware but unavailable on others. If your client picks one that isn't supported, the tool returns a structured error suggesting a portable alternative — prefer `lemonade_list_models` to discover what's actually available on the running server.
+
+### `lemonade_transcribe_audio`
+
+Transcribe a local audio file with a Whisper-class model. Prefer `audio_path` (the server runs on the same machine as the caller); use `audio_base64` only when you genuinely have bytes in memory.
+
+```json
+{
+  "name": "lemonade_transcribe_audio",
+  "arguments": {
+    "model": "Whisper-Large-v3-Turbo",
+    "audio_path": "C:/clips/meeting.wav",
+    "response_format": "verbose_json"
+  }
+}
+```
+
+Returns two text blocks: the bare transcript, followed by the full OpenAI-shaped response (for callers that need timestamps or segments).
+
+### `lemonade_generate_image`
+
+Generate one or more PNGs from a prompt. **Prefer writing to disk** via `output_path` (single image) or `output_dir` (one or more) — base64 image content blocks cost tens of thousands of tokens per image and some clients surface them as opaque resource URIs.
+
+```json
+{
+  "name": "lemonade_generate_image",
+  "arguments": {
+    "model": "SDXL-Turbo",
+    "prompt": "a lemon-shaped car driving across the moon",
+    "size": "512x512",
+    "output_path": "lemon-car.png"
+  }
+}
+```
+
+When disk paths are provided, returns text block(s) with the absolute path(s). Otherwise, returns one inline image content block per image (`{"type":"image", "data":"<base64>", "mimeType":"image/png"}`).
+
+**Sandboxed disk writes.** To prevent a cross-origin or unauthenticated caller from overwriting arbitrary files, `output_path` and `output_dir` are confined to a sandbox directory:
+
+- Default: `<cache_dir>/mcp-images`.
+- Override with the `LEMONADE_MCP_IMAGE_DIR` environment variable (absolute path).
+- Relative paths resolve against the sandbox root; absolute paths must stay within it. Paths that escape the sandbox (via `..` or symlinks) are rejected.
+- `output_dir` writes use auto-generated, unique filenames (`image_<token>_<i>.png`), so concurrent callers never clobber one another's images — the returned `paths` tell you the exact names. Use `output_path` when you need an exact, caller-chosen filename (it is written as named, replacing any existing file at that path).
+
+### `lemonade_omni`
+
+One-shot multimodal turn against a **Lemonade Omni collection** (a model bundle that pairs a planner LLM with an image model, an image-edit model, and a TTS voice under a single `collection.omni` recipe — see [the Omni docs](../dev/lemonade-omni.md)). The server runs the orchestrator's internal tool-calling loop, executes the collection's `generate_image` / `edit_image` / `text_to_speech` tools by routing to the bundled components, and returns the result as a text block plus native MCP `image` / `audio` content blocks — one per artifact, in the order they were produced.
+
+`model` is **optional** and defaults to `LMX-Omni-5.5B-Lite` (smaller and faster). Pass `model` explicitly to opt into a larger collection (e.g. `LMX-Omni-52B-Halo` on capable hardware) or any other `collection.omni` model surfaced by `lemonade_list_models`. The collection is downloaded on first use and may be multi-GB.
+
+Use `lemonade_chat` instead when you only need plain-text LLM output and don't want the planner-loop overhead.
+
+```json
+{
+  "name": "lemonade_omni",
+  "arguments": {
+    "messages": [
+      {"role": "user", "content": "Generate an image of a lemon car, then read out a one-line description."}
+    ],
+    "output_dir": "omni"
+  }
+}
+```
+
+**Disk vs. inline output.** A single Omni turn can produce both images and audio in arbitrary order. Pass an `output_dir` to write each artifact to disk under a unique auto-generated name (`omni_<token>_<i>.<ext>`) — the tool returns one text block per artifact with its absolute path, plus a JSON-stringified `paths` array. This is strongly preferred over inline base64 for the same reasons documented under `lemonade_generate_image` — and is the **only** way to get audio out on clients that don't render `audio` content blocks. Like `lemonade_generate_image`, `output_dir` is confined to the MCP image sandbox (see **Sandboxed disk writes** above): relative paths resolve against the sandbox root, paths escaping it are rejected, and unique filenames mean concurrent callers never clobber each other.
+
+When `output_dir` is omitted, artifacts are inlined as MCP content blocks: `{"type":"image", "data":"<base64>", "mimeType":"image/png"}` and `{"type":"audio", "data":"<base64>", "mimeType":"audio/mpeg"}`.
+
+If the planner emits app-defined tool calls (those you passed in via `tools`/`tool_choice`), an extra text block `tool_calls: <json>` is appended, matching `lemonade_chat`'s passthrough semantics.
+
+Passing a non-collection model (e.g. a plain LLM) returns `isError: true` with a hint to use `lemonade_chat`.
+
+### `lemonade_docs`
+
+Read the server's own API reference. Call with no arguments to list the pages this server ships, then pass `page` to read one as markdown. The pages are bundled with the server, so they match the running version and work offline.
+
+```json
+{
+  "name": "lemonade_docs",
+  "arguments": {
+    "page": "api/lemonade"
+  }
+}
+```
+
+The listing returns a summary text block plus a JSON-stringified block with `{pages: [{id, title, bytes}]}`. `page` takes an `id` from that listing; unknown pages return `"isError": true`. The same content is available over HTTP at [`GET /v1/docs`](./lemonade.md#get-v1docs).
+
+## Error model
+
+| Code | Meaning |
+|------|---------|
+| `-32700` | Body was not valid JSON. |
+| `-32600` | Request was not a JSON-RPC object (or batch was empty / missing `method`). |
+| `-32601` | Unknown JSON-RPC method (e.g. `resources/list`). |
+| `-32602` | Invalid `params` for a known method. |
+| `-32603` | Internal server error (an exception escaped a handler). |
+
+Tool-level failures (bad arguments, model load errors, backend exceptions) are returned as **successful** JSON-RPC results with `"isError": true` and a text content block describing the failure, so MCP-aware models can self-correct.
+
+## Limitations (MVP)
+
+- No server-initiated SSE (GET /mcp returns 405). Tools return their full result in the POST response.
+- No session resumption (`Mcp-Session-Id` header is not issued).
+- `resources/*` and `prompts/*` capabilities are not implemented.
+- Streaming chat output is not exposed via MCP — `stream=true` is ignored. Use `POST /v1/chat/completions` directly for streamed tokens.
+- Embeddings and text-to-speech are not currently exposed as MCP tools; use the OpenAI-compatible endpoints (`/v1/embeddings`, `/v1/audio/speech`) for those.
+
+## Quick test with curl
+
+```bash
+# 1. Initialize
+curl -s http://localhost:13305/mcp -H "Content-Type: application/json" \
+    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}'
+
+# 2. List tools
+curl -s http://localhost:13305/mcp -H "Content-Type: application/json" \
+    -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
+
+# 3. Call lemonade_chat
+curl -s http://localhost:13305/mcp -H "Content-Type: application/json" \
+    -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lemonade_chat","arguments":{"model":"Qwen3-1.7B-GGUF","messages":[{"role":"user","content":"hi"}],"max_tokens":16}}}'
+```

package/docs/ollama.md

@@ -0,0 +1,21 @@
+# Ollama-Compatible API
+
+Lemonade supports the [Ollama API](https://github.com/ollama/ollama/blob/main/docs/api.md), allowing applications built for Ollama to work with Lemonade without modification.
+
+To enable auto-detection by Ollama-integrated apps, configure the server to use the Ollama default port `11434`. See [Server Configuration](../guide/configuration/README.md#settings-reference) for how to change the port.
+
+| Endpoint | Status | Notes |
+|----------|--------|-------|
+| `POST /api/chat` | Supported | Streaming and non-streaming |
+| `POST /api/generate` | Supported | Text completion + image generation |
+| `GET /api/tags` | Supported | Lists downloaded models |
+| `POST /api/show` | Supported | Model details |
+| `DELETE /api/delete` | Supported | |
+| `POST /api/pull` | Supported | Download with progress |
+| `POST /api/embed` | Supported | New embeddings format |
+| `POST /api/embeddings` | Supported | Legacy embeddings |
+| `GET /api/ps` | Supported | Running models |
+| `GET /api/version` | Supported | |
+| `POST /api/create` | Not supported | Returns 501 |
+| `POST /api/copy` | Not supported | Returns 501 |
+| `POST /api/push` | Not supported | Returns 501 |