mlx-bun 0.2.0 → 0.3.0

package/docs/reference/server-api.md

@@ -1,19 +1,111 @@
 # Server API
 
-`mlx-bun serve` exposes an OpenAI-compatible
-HTTP API on one model. The request's `model` field is ignored; the
-loaded model's id is echoed back. By default generation is serialized
-through a single queue (one GPU, batch = 1); `--batch N` switches the
-server into bf16 continuous batching.
-
-For the full set of start flags (`--port`, `--memory-budget`,
+`mlx-bun serve` exposes an OpenAI-compatible HTTP API on one model. The
+request's `model` field is ignored; the loaded model's id is echoed back.
+The default concurrency cap is eight. Eligible requests use continuous batching;
+`--batch 1` pins serial execution. Both use the shared generation session for
+output, cancellation and cleanup. Each model implementation supplies its own
+execution methods; protocol handlers do not select a concrete model class.
+Embedding execution also acquires the shared model/GPU lease, so it waits for
+active generation or model mutation before running.
+
+This is the canonical wire reference: every route the server registers is
+listed below, and every field documented here exists in the code that
+serves it (`src/server.ts`, `src/serve/*-routes.ts`, `src/serve/isolate.ts`,
+`src/pi-web.ts`). Start flags (`--port`, `--memory-budget`,
 `--prompt-cache`, `--batch`, `--kv-quant`, `--thinking`, sampling
-defaults, and the perf levers) and a compatibility matrix of which
-combinations compose, see [server-config.md](./server-config.md). This
-doc covers the request/response wire format. LoRA adapters are mounted at
-runtime via `POST /v1/adapters` (below), or at startup with
-`serve --adapter <dir>` (which also makes that adapter the default for
-requests that don't select one).
+defaults) and which combinations compose live in
+[server-config.md](./server-config.md); the CLI in [cli.md](./cli.md).
+
+## Route index
+
+Dispatch order matters only for `/ws/chat` (upgrade) and the static shell;
+every other path is unique. Unmatched paths return
+`404 {"error":{"message":"not found"}}`.
+
+| Method | Path | Section |
+| --- | --- | --- |
+| POST | `/v1/chat/completions` | [Chat completions](#post-v1chatcompletions) |
+| POST | `/v1/completions` | [Text completions](#post-v1completions-raw-text-completion) |
+| POST | `/v1/messages` | [Anthropic Messages](#post-v1messages-anthropic-messages-api) |
+| POST | `/v1/responses` | [OpenAI Responses](#post-v1responses-openai-responses-api) |
+| POST | `/v1/embeddings` | [Embeddings](#post-v1embeddings-openai-embeddings-api) |
+| GET | `/v1` | [API index](#get-v1) |
+| GET | `/v1/models`, `/v1/models/<id>` | [Models](#get-v1models) |
+| GET / POST | `/v1/adapters` | [Adapters](#adapters-lora-hot-swap) |
+| GET | `/v1/adapters/available` | [Adapters](#adapters-lora-hot-swap) |
+| DELETE | `/v1/adapters/<id>` | [Adapters](#adapters-lora-hot-swap) |
+| GET | `/health` | [Health](#get-health) |
+| GET | `/stats` | [Stats](#get-stats) |
+| GET | `/fit` | [Fit](#get-fit) |
+| GET | `/library` | [Library](#get-library) |
+| GET | `/downloads` | [Downloads](#get-downloads) |
+| POST | `/admin/cache/flush` | [SSD cache flush](#post-admincacheflush) |
+| GET | `/api/jobs`, `/api/jobs/<id>`, `/api/jobs/<id>/stream` | [Jobs](#jobs-apijobs) |
+| POST | `/api/finetune/submit`, `/inspect-dataset`, `/merge`, `/export` | [Fine-tune](#fine-tune-apifinetune) |
+| POST | `/api/quantize/inspect`, `/submit`, `/resolve-folder` | [Quantize](#quantize-apiquantize) |
+| GET / POST | `/api/dataset/templates`, `/api/dataset/submit` | [Dataset](#dataset-apidataset) |
+| POST | `/api/model/resolve-folder` | [Quantize](#quantize-apiquantize) |
+| POST | `/api/{quantize,finetune,dataset}/push` | [Push to Hub](#post-apiquantizefinetunedatasetpush) |
+| GET / POST | `/api/gc/plan`, `/api/gc/execute` | [GC](#get-apigcplan--post-apigcexecute) |
+| GET / POST | `/api/memory/*` | [Memory](#get-apimemory--post-apimemoryinit) |
+| GET | `/v1/memory/synthesize` | [Memory synthesis](#get-v1memorysynthesize) |
+| GET / POST / DELETE | `/api/settings/hf-token`, `/api/settings/tool-approvals` | [Settings](#settings-apisettings) |
+| GET / POST | `/api/hub/local`, `/search`, `/download`, `/serve` | [Model Hub](#model-hub-apihub) |
+| GET | `/api/sessions/search`, `/api/sessions/export` | [Sessions](#get-apisessionssearch--get-apisessionsexport) |
+| GET | `/`, `/assets/*`, `/manifest.webmanifest`, `/sw.js`, `/curves`, `/curve-terrain`, `/dag` | [Static](#web-app-static-routes--pwa-installability) |
+| GET | `/status`, `/chat`, `/quantize`, `/finetune`, `/dataset` | 302 to `/#<path>` ([Static](#web-app-static-routes--pwa-installability)) |
+| POST | `/signal`, `/generate` | [Curve Designer](#curve-designer-post-signal--post-generate) |
+| WS | `/ws/chat` | [Web chat WebSocket](#web-chat-websocket-wschat) |
+
+Internal routes (not part of the client contract):
+
+| Method | Path | Where | Notes |
+| --- | --- | --- | --- |
+| POST | `/admin/drain` | `src/server.ts` | Only registered when the server is bound to a unix socket (`--unix`, i.e. an `--isolate` engine child). Quiesces the gateway and demotes the whole prompt cache to the SSD tier; returns `{ "drained": true, "demotions": N }`. Never exposed on TCP. |
+| POST | `/admin/lease` | `src/server.ts` | Unix-socket workers only. Flushes durability, then holds the gateway's native execution lease while the response connection stays open. The isolation parent uses it for managed GPU jobs; disconnect releases the lease. Never exposed on TCP. |
+| GET | `/engine` | `src/serve/isolate.ts` | Only on the `--isolate` parent proxy: `{ isolated: true, pid, restarts, socket, response_store, pool?: { resident, default } }`. Worker fields describe the current default worker, or are `null` while it is evicted; inspection never loads it. |
+
+Under `--isolate`, the parent proxies everything to the engine child;
+`/ws/chat` is answered `501` there (web chat needs a non-isolated server),
+`/v1/chat/completions`, `/v1/completions`, `/v1/messages`, `/v1/responses`,
+and `/v1/embeddings` are routed by the body's `model` field when a
+`--model-pool` is configured, an unreachable child is
+`502 {"error":{"type":"engine_unavailable"}}`, and a client disconnect
+mid-proxy is `499`.
+
+## Diagnostics: `x-mlx-bun-trace-id` and `MLX_BUN_P2R_TRACE`
+
+`/v1/chat/completions` and `/v1/completions` read an optional
+`x-mlx-bun-trace-id` request header. With `MLX_BUN_P2R_TRACE=1` set on the
+server, each of those requests emits one JSON record to stderr, prefixed
+`[p2r] `, when it finishes (`src/serve/prompt-response-trace.ts`). Without
+the env var nothing is allocated and the header is ignored.
+
+```jsonc
+{
+  "version": 1,
+  "traceId": "<x-mlx-bun-trace-id, or the request id when absent>",
+  "requestId": "chatcmpl-…" | "cmpl-…",
+  "route": "/v1/chat/completions" | "/v1/completions",
+  "clock": "monotonic-ms",
+  "outcome": "success" | "error" | "abort",
+  "totalMs": 0.0,
+  "events": [                      // sorted by startMs
+    { "phase": "request.body_parse", "startMs": 0.0, "durationMs": 0.0,
+      "attributes": { /* optional string|number|boolean|null map */ } }
+  ],
+  "attributes": { "stage": "body_parse" | "prepare_completion" }  // on some errors
+}
+```
+
+Phases: `request.body_parse`, `request.prompt_prepare`, `completion.total`,
+`completion.placement`, `engine.admission_wait`, `cache.lookup_restore`,
+`prefill.total`, `prefill.batch_setup`, `prefill.chunk`,
+`prefill.kv_maintenance`, `token_zero.total`, `token_zero.forward`,
+`token_zero.head`, `token_zero.sample`, `response.first_write`,
+`response.final_write`. Marks (`response.first_write`,
+`response.final_write`) have `durationMs: 0`.
 
 ## POST /v1/chat/completions
 
@@ -23,7 +115,10 @@ Request body (OpenAI chat schema; unknown fields ignored):
 {
   "messages": [ /* role: system | user | assistant | tool */ ],
   "stream": false,
-  "max_tokens": 1024,            // or max_completion_tokens (wins)
+  "max_tokens": 1024,            // or max_completion_tokens (wins); unset =
+                                 // no cap — generate until EOS or the
+                                 // admitted context is exhausted (admission
+                                 // clamps; --max-tokens sets a server default)
   "temperature": 0.7,            // 0 = greedy
   "top_p": 0, "top_k": 0,        // 0 = off
   "seed": 1234,                  // omit for time-derived
@@ -48,7 +143,9 @@ Request body (OpenAI chat schema; unknown fields ignored):
                                  //   (token, logprob) pairs per position
   "stop": "\n\n",                // or ["###", "\n\n"] (spec: up to 4)
   "tools": [ /* OpenAI function tools */ ],
-  "tool_choice": "auto",         // "none" disables tools
+  "tool_choice": "auto",         // "none" disables tools; "auto" and the
+                                 //   {type:"function", function:{name}}
+                                 //   object are accepted and treated as auto
   "chat_template_kwargs": {      // forwarded to the chat template
     "enable_thinking": false,    // MiniCPM5 / Qwen3.5/3.8 / GLM-5.2: <think>
                                  // channel on/off (Qwen3.8 default: ON)
@@ -68,9 +165,7 @@ Request body (OpenAI chat schema; unknown fields ignored):
                                  // variable (Qwen3.8) the level also maps
                                  // into the template: minimal/low → low,
                                  // medium → medium, high/xhigh → xhigh.
-                                 // Any OTHER string is a 400 — a typo used
-                                 // to silently force thinking ON
-                                 // (Qwen3.8's default depth is xhigh).
+                                 // Any OTHER string is a 400.
   "hlg": {                       // HLG tone-curve sampling (per request).
     "enabled": true,             // merged over --hlg-sampling server defaults.
     "width": 4,                  // logit-width of the tone plateau
@@ -91,6 +186,13 @@ Sampling defaults follow the model author's `generation_config.json`
 when a field is omitted (optiq serve's gen_config behavior); explicit
 request values always win. MiniCPM5 defaults to the no-think direct
 answer mode unless `chat_template_kwargs.enable_thinking` is `true`.
+
+Assistant history accepts `reasoning` as an alias for `reasoning_content`,
+including Pi's reasoning on tool-call messages. An explicit `reasoning_content`
+string takes precedence, even when empty. Normalization preserves the original
+message and exposes the canonical field to templates, so Qwen's
+`preserve_thinking: true` retains that history across tool turns.
+
 GLM-5.2 also defaults to no-think: its generation primer is
 `<think></think>`. Enabling thinking renders `Reasoning Effort: Max` in the
 system turn and leaves an open `<think>` primer for generation. The same
@@ -105,20 +207,22 @@ and `finish_reason` is `"stop"`.
 Message `content` is a string or an array of parts:
 `{ "type": "text", "text": ... }` and
 `{ "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }`
-(http/https URLs also accepted; PNG, JPEG, HEIC, AVIF, WebP, TIFF, GIF,
-BMP via native OS codecs; requires a model with the vision sidecar).
+(`{ "type": "image", ... }` is accepted as an alias; http/https URLs also
+accepted; PNG, JPEG, HEIC, AVIF, WebP, TIFF, GIF, BMP via native OS codecs;
+requires a model with the vision sidecar).
 
 Remote (http/https) media URLs — image, audio, and video alike — go
-through a destination policy: **private/loopback/link-local hosts are
-refused by default** (the request URL is attacker-controlled input —
-SSRF), every redirect hop is re-validated, and the fetch has a **10 s
-timeout** and a **64 MB response cap** (video: **256 MB** — clips are
-legitimately larger; frame sampling truncates long clips server-side).
-Violations are clean `400`s
+through a destination policy (`src/media-fetch.ts`): **private/loopback/
+link-local hosts are refused by default** (the request URL is
+attacker-controlled input — SSRF), every redirect hop is re-validated, and
+the fetch has a **10 s timeout** and a **64 MB response cap** (video:
+**256 MB** — clips are legitimately larger; frame sampling truncates long
+clips server-side). Violations are clean `400`s
 (`prompt build failed: image url rejected: …`). Serving media from a LAN
 host (a NAS, another machine) is the opt-in
-[`--allow-private-media`](server-config.md#start-flags) flag. `data:`
-URLs are decoded locally and never policy-checked.
+[`--allow-private-media`](server-config.md#start-flags) flag (or
+`MLX_BUN_ALLOW_PRIVATE_MEDIA=1`). `data:` URLs are decoded locally and
+never policy-checked.
 
 ### Video input (Qwen3.5-family models)
 
@@ -133,11 +237,12 @@ The container decodes through macOS's own AVFoundation codecs (mp4/mov,
 H.264/HEVC/ProRes/… — whatever this macOS plays) via the
 `mlx-bun-frame-extract` helper that ships beside the binary and in the
 native pack; from a source tree it compiles on first use with the Xcode
-CLT. Frames are sampled at **2 fps, capped at 768 frames**, then run the
-gated Qwen3-VL video pipeline (temporal frame pairs, per-frame-group
-attention, 3D mRoPE positions). Qwen3.5-family models only; video never
-combines with audio parts, and a non-Qwen model answers video parts with
-a clean `400`.
+CLT. Frames are sampled at **2 fps, capped at 768 frames**
+(`src/vision/video-frames.ts`), then run the gated Qwen3-VL video pipeline
+(temporal frame pairs, per-frame-group attention, 3D mRoPE positions).
+Qwen3.5-family models only; video never combines with audio parts
+(`400 "video and audio content parts cannot be combined"`), and a non-Qwen
+model answers video parts with a `400` naming the model.
 
 ### Audio input
 
@@ -172,12 +277,13 @@ curl -s http://localhost:8080/v1/chat/completions \
   `400` naming the model — never a silent text-only answer.
 - **Formats**: WAV is decoded natively (PCM 16/24/32-bit + float32, any
   channel count / sample rate). mp3, m4a/AAC, FLAC, ogg(-CAF), AIFF and
-  anything else CoreAudio reads transcode via macOS `afconvert`;
-  undecodable bytes are a `400` (`audio transcode failed …`).
+  anything else CoreAudio reads transcode via macOS `afconvert`
+  (`src/audio/transcode.ts`); undecodable bytes are a `400`.
 - **Internal format**: 16 kHz mono — multi-channel input is mean-mixed,
   other rates resample. Clips truncate at **30 s** (the oracle
   processor's 480 000-sample cap); one clip costs
-  `ceil(duration_ms / 40)` prompt tokens, at most **750**.
+  `ceil(duration_ms / 40)` prompt tokens, at most **750**
+  (`src/audio/decode.ts`).
 - Multiple clips per message and **mixed image+audio** requests work;
   media splices in document order.
 - **Routing**: audio requests always run on the **serial lane** (never
@@ -198,12 +304,16 @@ Non-streaming response:
     "index": 0,
     "message": {
       "role": "assistant",
-      "content": "…",                      // "" when only tool calls
+      "content": "…",                      // null when the reply is ONLY tool calls
+      "reasoning": "…",                    // present only when the model emitted a
+                                           //   <think> channel (thinking-capable
+                                           //   templates with thinking on)
       "tool_calls": [{                     // present when the model called tools
         "id": "call_…", "type": "function",
         "function": { "name": "…", "arguments": "{…json…}" }
       }]
     },
+    "logprobs": { /* see below; only when requested */ },
     "finish_reason": "stop" | "length" | "tool_calls"
   }],
   "usage": {
@@ -211,14 +321,31 @@ Non-streaming response:
     "prompt_tokens_details": { "cached_tokens": 0 },  // prompt-cache reuse
     "lane": "serial",              // "serial" | "serial+spec" | "batched" —
                                     //   which execution lane served THIS
-                                    //   request (GenerationGateway.place
-                                    //   + whether a draft actually contributed
-                                    //   accepted tokens). Chat completions
-                                    //   only (streaming: final usage chunk).
+                                    //   request. Chat completions and text
+                                    //   completions (streaming: final usage
+                                    //   chunk).
     "speculation": {               // only when a draft source is mounted
       "drafted": 0,                //   draft tokens proposed
       "accepted": 0,               //   drafts accepted by the verify step
       "targetCalls": 0             //   target-model forward calls
+    },
+    "fill": {                      // only under MLX_BUN_FILL=strict, when a
+                                    //   fill table was armed for the request
+      "events": 0,                 //   injected spans
+      "injected": 0,               //   tokens appended by the engine
+      "strict": 0,                 //   …of those, from schema/template rows
+      "echo": 0,                   //   …from the echo index (MLX_BUN_FILL=echo)
+      "spanLens": [],              //   length of each span, in order
+      "wastedSamples": 0,          //   in-flight samples dropped at an ASSERT fill
+      "parseFallback": 0,          //   tool-call parses rejected after a fill
+      "indexTruncated": 0,         //   spans cut by EOS / delimiter / budget / span
+      "decodeSteps": 0,            //   tokens the model actually sampled
+      "verifyEvents": 0,           //   verify-policy spans that reached the forward
+      "verifyAccepted": 0,         //   …tokens the model's own argmax agreed with
+      "verifyRejected": 0,         //   …tokens dropped and rewound
+      "verifyUnsupported": 0,      //   verify spans dropped: caches cannot rewind
+      "checkpointMs": 0,           //   time in cache checkpoint / rollback
+      "branchStops": 0             //   echo spans stopped by a history fork
     }
   }
 }
@@ -231,18 +358,48 @@ contributed accepted draft tokens to this reply, `"serial"` otherwise. It
 rides the SAME usage block on both streaming (final chunk before `[DONE]`) and
 non-streaming responses.
 
+`usage.completion_tokens` counts the stopping EOS token in both native and
+speculative serial generation, matching mlx-lm. EOS is excluded from response
+content. An early callback stop or token budget does not count a later EOS
+that happened to be evaluated in the same speculative burst.
+An observed EOS reports `finish_reason: "stop"`, including when its counted
+position equals `max_tokens`.
+
 Speculative decoding is a **server-level mode** (`serve --draft-model`,
 or the model-free `serve --draft-kind ngram`, which mounts no draft
 model); there is no per-request draft field. The `speculation` usage
-extension
-appears on chat and text completions alike, non-streaming and on the
-final stream chunk. Spec-eligible requests are text-only on base weights
-(no adapter, no logprobs capture, bf16 KV); ineligible ones decode
-normally and omit the field. The spec path bypasses the prompt cache
-(`cached_tokens` 0), and while a draft is mounted every request routes
+extension appears on chat and text completions alike, non-streaming and on
+the final stream chunk. Spec-eligible requests are text-only on base weights
+(no adapter or logprobs capture, bf16 KV by default); experimental Qwen
+uniform KV4 start=0 can qualify through `MLX_BUN_QWEN_SPEC_KV4=1`.
+Ineligible requests decode normally and omit the field. The spec path bypasses
+the ordinary prompt cache. Qwen MTP with `MLX_BUN_MTP_PROMPT_CACHE=1` can reuse
+a paired target/draft RAM prefix, reported in `cached_tokens`; the default is
+zero. These prefixes do not persist across restarts. While a draft is mounted every request routes
 through the serial lane (mlx_lm.server parity: `is_batchable = draft is
 None`) — speculation and `--batch N` are different modes.
 
+`usage.fill` reports **token fast-forwarding** (`MLX_BUN_FILL=strict|echo`).
+Strict mode appends structural spans from the request's tools and chat
+template at qualified parser boundaries, with no draft, verification or
+rollback. The model advances its hidden states and caches through the span,
+using its qualified append chunk size, then resumes sampling
+(design: [speculative-decoding.md](../design/speculative-decoding.md) §"Token
+fast-forwarding"). Injected tokens are billed in `completion_tokens` like any
+other generated token; `decodeSteps` counts ordinary sampling steps, so
+`injected / (injected + decodeSteps)` is the share appended without sampling.
+Injected positions still run through the model layers. The field is absent when the feature is off or the
+request's shape refuses it (fixed `seed`, `logprobs`, structured output,
+media, a mounted draft model, quantized KV).
+
+Under `MLX_BUN_FILL=echo` a second, weaker source joins: spans copied from
+earlier in the same session, carried under policy `verify`. Those ride the same
+single forward, are checked against the argmax already in its logits, and have
+their rejected tail rewound — so `verifyAccepted + verifyRejected` is what the
+echo index proposed and `injected` is what survived. `wastedSamples` counts
+only ASSERT fills (a verify fill consumes the in-flight sample as its first
+position's check instead of discarding it).
+
 ### logprobs / top_logprobs
 
 With `"logprobs": true` and/or `"top_logprobs": k` (1–11), the
@@ -271,44 +428,68 @@ legacy `{tokens, token_logprobs}` text-completion shape).
 
 The distribution matches mlx-lm `generate_step` exactly: full-vocab
 log-softmax of the logits **after** logits processors (logit_bias,
-penalties), **before** the sampler's temperature/top-p/top-k/min-p/XTC
-(mlx_lm/generate.py L409–422). mlx-lm's top-k order is unspecified
-(argpartition); ours is sorted descending — the same set, so the entry
-is deterministically the argmax. Stream chunks never carry logprobs
-(mlx-lm's streaming responses don't either). Requests with logprobs
-run on the serial lane under `--batch N` (like the other mlx-lm
-sampler extensions). Invalid values are rejected with mlx-lm's exact
-messages (see Errors).
-
-Streaming (`"stream": true`) is SSE: `data: <chunk>\n\n` per event,
-terminated by `data: "[DONE]"`. Chunks are `chat.completion.chunk`
-objects whose `choices[0].delta` carries `{role}`, then `{content}`
-increments (multi-byte sequences are held back until decodable; text
-that could begin a `stop` sequence is held back until disambiguated,
-so no part of a stop sequence is ever streamed), then
-for tool calls a final `{tool_calls: [{index, id, type, function}]}`
-delta; the last chunk carries `finish_reason` and `usage`.
+penalties), **before** the sampler's temperature/top-p/top-k/min-p/XTC.
+mlx-lm's top-k order is unspecified (argpartition); ours is sorted
+descending — the same set, so the entry is deterministically the argmax.
+Stream chunks never carry logprobs (mlx-lm's streaming responses don't
+either). Requests with logprobs run on the serial lane under `--batch N`
+(like the other mlx-lm sampler extensions). Invalid values are rejected
+with mlx-lm's exact messages (see Errors).
+
+### Streaming
+
+`"stream": true` is SSE: `data: <chunk>\n\n` per event, terminated by
+`data: [DONE]`. Chunks are `chat.completion.chunk` objects whose
+`choices[0].delta` carries `{role: "assistant", content: ""}` first, then
+`{reasoning}` increments while the model is inside its `<think>` channel,
+then `{content}` increments (multi-byte sequences are held back until
+decodable; text that could begin a `stop` sequence is held back until
+disambiguated, so no part of a stop sequence is ever streamed), then for
+tool calls a `{tool_calls: [{index, id, type, function}]}` delta; the last
+chunk carries `finish_reason` and `usage`. A generation error mid-stream is
+sent as `data: {"error":{"message":…}}` and the stream closes. While a
+large tool-call body is buffered for parsing, the server sends SSE comment
+heartbeats (`: keep-alive`) so client idle timers do not terminate the call.
+
+### Tool calls
+
+Qwen's `<parameter=...>` values are raw text. The parser preserves HTML
+entities, indentation and JSON string escapes, removing only one framing
+newline at either end. Array/object parameters are JSON-decoded according to
+the tool schema. The outer Qwen markup is parsed before generic JSON repair,
+so a nested edit array is not mistaken for the tool-call envelope.
 
 Tool round-trip: send the assistant message with its `tool_calls` back,
 followed by `{ "role": "tool", "tool_call_id": …, "content": … }`
 messages; multi-turn prompt prefixes reuse the KV prompt cache
 automatically.
 
-Tool-call parsing is per model family. Gemma 4 uses its native
-`<|tool_call>`…`<tool_call|>` sentinel tokens. Qwen3.5 emits decoded
-text wrapped in `<tool_call><function=name><parameter=key>value` XML
-equals-style blocks. MiniCPM5 emits XML in decoded text
-(`<function name="…"><param name="…">…`, CDATA-wrapped values
-supported). For both Qwen3.5 and MiniCPM5 content before the tool
-markup still streams live, only the markup is withheld and converted to
-`tool_calls`. Argument values are decoded against the tool's JSON schema
-(string-typed params stay strings); markup that fails to parse falls
-back to plain content.
+Tool-call parsing is per model family (`selectToolStreamMode` in
+`src/server.ts`, parsers in `src/tool-call.ts`). Gemma 4 uses its native
+`<|tool_call>`…`<tool_call|>` sentinel tokens. Every other family parses
+**decoded text** once tools are active: OpenAI-JSON
+`<tool_call>{…}</tool_call>`, Qwen-style
+`<tool_call><function=name><parameter=key>value</parameter></function></tool_call>`,
+GLM-5.2's `name<arg_key>…<arg_value>…`, and MiniCPM5's
+`<function name="…"><param name="…">…</param></function>` (CDATA-wrapped
+values supported). Content before the tool markup still streams live; only
+the markup is withheld and converted to `tool_calls`. Argument values are
+decoded against the tool's JSON schema (string-typed params stay strings).
+
+When strict parsing fails, a repair pass runs before giving up: a
+```` ```json ```` fence or prose prefix is stripped, single quotes and
+trailing commas are fixed, truncated braces are closed, a function name
+that landed inside `arguments` is lifted into the envelope, and Python
+literals `True`/`False`/`None` **outside string values** are coerced to
+`true`/`false`/`null` (`pythonLiteralsToJson`, `src/tool-call.ts` — Qwen3.5
+in particular emits Python booleans). The repair is not reported on the
+wire; markup that still fails to parse falls back to plain content.
 
 ### Structured output (grammar-constrained decoding)
 
 Both `/v1/chat/completions` and `/v1/completions` accept the
-OpenAI/oMLX/vLLM structured-output fields (snake_case on the wire):
+OpenAI/oMLX/vLLM structured-output fields (snake_case on the wire; the
+field names are `GrammarRequest` in `src/grammar.ts`):
 
 ```jsonc
 {
@@ -330,9 +511,19 @@ OpenAI/oMLX/vLLM structured-output fields (snake_case on the wire):
 }
 ```
 
-Precedence when several are set mirrors oMLX: `guided_grammar` >
-`response_format` json_schema > json_object > `structured_outputs` >
-`guided_regex` > `guided_choice`.
+| Field | Compiles to (xgrammar) | Output |
+| --- | --- | --- |
+| `response_format: {type:"json_object"}` | builtin JSON grammar | any valid JSON |
+| `response_format: {type:"json_schema", json_schema:{name, schema, strict?, any_whitespace?}}` | `compileJSONSchema(schema)` | schema-conformant JSON |
+| `guided_grammar` | `Grammar.fromEBNF` | text matching the grammar |
+| `guided_regex` | EBNF-wrapped regex | text matching the regex subset |
+| `guided_choice` | `root ::= ("a" \| "b" \| …)` | exactly one of the strings |
+| `structured_outputs` | bare schema (alias for `json_schema.schema`) | schema-conformant JSON |
+
+Precedence when several are set (`resolveGrammarRequest`): `guided_grammar`
+> `response_format` json_schema > json_object > `structured_outputs` >
+`guided_regex` > `guided_choice`. `response_format: {type:"text"}` or no
+field at all means no constraint.
 
 Enforcement is a per-step token bitmask at the sampler (xgrammar):
 invalid next tokens are masked to −inf **after** the logits processors,
@@ -346,32 +537,45 @@ Degrade path — a grammar that fails to compile is never rejected (no
 requested JSON schema, raw grammar, regex, or choice constraint, and the
 response carries a `Warning` header (`grammar not enforced: …`);
 `/v1/completions` has no chat template to inject into, so it emits the
-`Warning` header only.
-`MLX_BUN_GRAMMAR=0` disables mask compilation but does not silently
-ignore a requested constraint: it uses this same degrade path (chat
-prompt injection plus `Warning`; raw completions `Warning` only).
-Design and fidelity notes:
-[structured-output.md](../design/structured-output.md).
+`Warning` header only. `MLX_BUN_GRAMMAR=0` disables mask compilation but
+does not silently ignore a requested constraint: it uses this same degrade
+path with the hint `grammar compilation disabled by MLX_BUN_GRAMMAR=0`.
+Design and fidelity notes: [docs/reference/server-api.md](./server-api.md).
 
 ### Errors
 
+Runtime memory pressure can fail a request even after prompt-length admission.
+The serial memory guard first reclaims older prompt-cache entries, persisting
+them to the SSD tier when configured. If insufficient GPU headroom remains,
+the normal request/stream error path reports the failure. Saved in-flight
+generation checkpoints remain available for an identical retry.
+
 All errors are `{ "error": { "message": …, ... } }`.
 
-- `400` — malformed JSON, empty `messages`, unknown adapter id, vision
-  request on a model without a sidecar, audio request on a model
-  without an audio tower (message names the model), audio transcode
-  failures, prompt build failures,
-  non-numeric `logit_bias` keys/values (`logit_bias must be a dict of
-  int to float`, mlx-lm's coercion error), invalid logprobs params
+- `400` — malformed JSON (`invalid JSON body`), empty `messages`
+  (`messages required`), unknown adapter id, vision request on a model
+  without a sidecar (`model has no vision sidecar`), audio request on a
+  model without an audio tower (message names the model), video on a
+  non-Qwen3.5 model or combined with audio, prompt build failures
+  (`prompt build failed: …`, which includes media fetch/transcode
+  errors), non-numeric `logit_bias` keys/values (`logit_bias must be a
+  dict of int to float`, mlx-lm's coercion error), invalid logprobs params
   (mlx-lm's exact validation: `logprobs must be of type bool`,
   `top_logprobs must be of type int` / `at least 0` / `at most 11`;
-  `top_logprobs: -1` is the accepted "unset" sentinel).
+  `top_logprobs: -1` is the accepted "unset" sentinel), invalid
+  `reasoning_effort` (`reasoning_effort must be one of 'none', 'minimal',
+  'low', 'medium', 'high', 'xhigh'`).
 - `400` with `"type": "memory_admission"`, `"code":
   "context_over_budget"` — the PROMPT itself leaves no generation slot
-  within the max safe context. A prompt that fits is never rejected for a
-  broad `max_tokens`: the upper bound is capped to the remaining room
-  (`max_tokens` is a ceiling, not a promise) and generation proceeds. The
-  ceiling is visible at `/stats`.
+  within the max safe context (`src/serve/request-plan.ts`). A prompt that
+  fits is never rejected for a broad `max_tokens`: the upper bound is
+  capped to the remaining room (`max_tokens` is a ceiling, not a promise)
+  and generation proceeds. The ceiling is visible at `/stats`.
+- `429` with `"type": "resource_admission"`, `"code": "queue_full"` when
+  a preparation or generation queue has 64 waiting requests. If SSE headers
+  are already sent, the stream emits its terminal error instead.
+- `500` — a generation failure after admission; the stack is logged
+  server-side, the body keeps only the message.
 
 ## POST /v1/completions (raw text completion)
 
@@ -383,17 +587,19 @@ and adapter selection as chat.
 
 ```jsonc
 {
-  "prompt": "Once upon a time",  // REQUIRED, string only (token arrays
-                                 // rejected, matching mlx_lm.server)
-  "max_tokens": 512,             // default 512 (mlx_lm.server's default) —
-                                 // NOT the chat lane's generous default
+  "prompt": "Once upon a time",  // REQUIRED, non-empty string only (token
+                                 // arrays rejected, matching mlx_lm.server)
+  "max_tokens": 512,             // unset = no cap: generate until EOS or the
+                                 // admitted context (DEVIATION: mlx_lm.server
+                                 // defaults 512 — pass --max-tokens 512 to
+                                 // reproduce); max_completion_tokens wins
   "stream": false,
   "stop": "\n\n",                // string or array, decoded-text matching
   // plus every sampling/penalty field from /v1/chat/completions:
   // temperature, top_p, top_k, seed, min_p, xtc_probability,
   // xtc_threshold, logit_bias, repetition_penalty,
   // repetition_context_size, presence_penalty, presence_context_size,
-  // frequency_penalty, frequency_context_size, adapter,
+  // frequency_penalty, frequency_context_size, hlg, adapter,
   // logprobs (BOOL, mlx-lm's type — not OpenAI's legacy int),
   // top_logprobs (0-11 or -1) — same response block as chat, see
   // "logprobs / top_logprobs" above (mlx-lm shares the builder),
@@ -411,9 +617,11 @@ Response is the OpenAI text-completion object:
 {
   "id": "cmpl-…", "object": "text_completion", "created": 1760000000,
   "model": "<loaded model id>",
-  "choices": [{ "index": 0, "text": "…", "finish_reason": "stop" | "length" }],
+  "choices": [{ "index": 0, "text": "…", "finish_reason": "stop" | "length",
+                "logprobs": { /* only when requested */ } }],
   "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0,
-             "prompt_tokens_details": { "cached_tokens": 0 } }
+             "prompt_tokens_details": { "cached_tokens": 0 },
+             "lane": "serial" }
              // + "speculation" under --draft-model, as on chat
 }
 ```
@@ -423,83 +631,102 @@ Streaming (`"stream": true`) is SSE: `text_completion` chunks whose
 `finish_reason` and `usage` (always attached — mlx-lm gates usage behind
 `stream_options.include_usage`; ours is an additive superset), then
 `data: [DONE]`. There is no `echo` parameter (mlx_lm.server has none).
+`400` on a missing/empty/non-string `prompt`, plus the same logit_bias,
+logprobs, and admission errors as chat.
 
 ## POST /v1/messages (Anthropic Messages API)
 
 Anthropic-protocol surface over the same engine — on by default, like
 `optiq serve`. Point any Anthropic-SDK tool at the server
 (`ANTHROPIC_BASE_URL=http://localhost:8080`, any `x-api-key`) — Claude
-Code works as a client this way.
+Code works as a client this way. Translation lives in `src/anthropic.ts`;
+the request funnels into the chat handler above.
 
 - `system` (string or text blocks), `messages` with string or
   content-block arrays; `tool_use` / `tool_result` blocks map to the
-  native gemma tool-calling path (better than the optiq shim, which
-  inlines them as text); `image` blocks (base64 or url source) hit the
-  vision path on sidecar models. The protocol has no audio input block;
-  audio-shaped blocks (`input_audio` / `audio` / `audio_url`) are
-  rejected with a `400` pointing to `/v1/chat/completions`.
+  native tool-calling path; `image` blocks (base64 or url source) hit the
+  vision path on sidecar models, including image blocks nested inside a
+  `tool_result` (the computer-use shape). Other image source types are a
+  `400`. The protocol has no audio input block; audio-shaped blocks
+  (`input_audio` / `audio` / `audio_url`) are rejected with a `400` pointing
+  to `/v1/chat/completions`. Prior-turn `thinking` blocks are dropped on
+  re-ingest.
 - `tools` (`{name, description, input_schema}`) map to function tools;
-  server-tool types (web_search, …) are dropped silently.
+  entries without `name` + `input_schema` (server-tool types such as
+  web_search) are dropped silently.
 - `max_tokens`, `temperature`, `top_p`, `top_k`, `stop_sequences`,
   `stream` as in the Anthropic spec. The mlx-lm sampler/penalty
   extensions (`min_p`, `xtc_probability`, `xtc_threshold`,
   `repetition_penalty`, `presence_penalty`, `frequency_penalty` + their
   `*_context_size` windows) pass through as extras; `logit_bias` does
   not exist in this protocol and is not accepted here.
-- Response: `{id: "msg_…", type: "message", content: [{type: "text"} |
-  {type: "tool_use"}…], stop_reason, usage: {input_tokens,
-  output_tokens, cache_read_input_tokens}}` —
-  `cache_read_input_tokens` comes from the prompt cache.
+- Response: `{id: "msg_…", type: "message", role: "assistant", content:
+  [{type: "text"} | {type: "tool_use"}…], stop_reason, stop_sequence,
+  usage: {input_tokens, output_tokens, cache_read_input_tokens?}}` —
+  `cache_read_input_tokens` is present when the prompt cache contributed.
 - Streaming follows the Anthropic event grammar exactly:
   `message_start → content_block_start/delta/stop (text_delta,
   input_json_delta) → message_delta (stop_reason + usage) →
   message_stop`. Errors are `event: error` frames.
 - Errors: `{type: "error", error: {type: "invalid_request_error" |
-  "api_error", message}}`.
+  "api_error", message}}` — the chat handler's `4xx`/`5xx` are re-wrapped
+  into this shape.
 
 ## POST /v1/responses (OpenAI Responses API)
 
 Responses-protocol surface (Codex, Cursor, Continue, Cline, and the
-OpenAI SDK speak this now). Oracle: optiq responses shim.
+OpenAI SDK speak this now). Oracle: optiq responses shim; port in
+`src/responses.ts`.
 
 - `input` (string or item array: `message`, `function_call`,
   `function_call_output`), `instructions` (merged with any
   system/developer items into one leading system message),
-  `max_output_tokens`, `temperature`, `top_p`, `top_k`, flat
-  `tools`/`tool_choice` (built-in tool types dropped), `stream`. The
-  mlx-lm sampler/penalty extensions (`min_p`, `xtc_probability`,
-  `xtc_threshold`, `logit_bias`, `repetition_penalty`,
-  `presence_penalty`, `frequency_penalty` + `*_context_size`) pass
-  through as extras.
+  `max_output_tokens` (or `max_tokens`), `temperature`, `top_p`, `top_k`,
+  flat `tools`/`tool_choice` (built-in tool types — web_search, file_search,
+  mcp, computer_use — dropped silently; `{type:"function", name}` maps to
+  the chat object form, `"auto"`/`"none"`/`"required"` pass through),
+  `stream`. The mlx-lm sampler/penalty extensions (`min_p`,
+  `xtc_probability`, `xtc_threshold`, `logit_bias`, `repetition_penalty`,
+  `presence_penalty`, `frequency_penalty` + `*_context_size`) pass through
+  as extras.
 - **`previous_response_id` resumption**: pass a prior response id
   instead of resending the conversation; the server splices the stored
-  input + output back in (instructions carry forward when omitted).
-  Store is per-process, 1 h TTL, 32 MiB byte-capped LRU — observable
-  at `GET /stats` (`response_store`). Unknown/expired id → 404.
+  input + output back in (instructions carry forward when omitted;
+  reasoning items are not replayed). Store is per-process, 1 h TTL,
+  32 MiB byte-capped LRU — observable at `GET /stats` (`response_store`).
+  Unknown/expired id → `404`.
 - Response: `{id: "resp_…", object: "response", status: "completed" |
-  "incomplete", output: [{type: "message"|"function_call"…}], usage}`.
+  "incomplete", output: [{type: "reasoning", summary: [{type:
+  "summary_text", text}]}?, {type: "message"}, {type: "function_call"}…],
+  usage: {input_tokens, output_tokens, total_tokens,
+  output_tokens_details: {reasoning_tokens}}, previous_response_id}`. A
+  `reasoning` item is present only when the model emitted a think channel.
 - Streaming event chain: `response.created → response.in_progress →
   response.output_item.added → response.content_part.added →
   response.output_text.delta… → response.output_text.done →
   response.content_part.done → response.output_item.done →
   response.completed` (+ `response.function_call_arguments.delta/.done`
-  for tool calls).
+  for tool calls; a reasoning output item precedes the message when the
+  model thinks).
+- Errors: `{error: {message, type: "invalid_request_error" |
+  "server_error", param: null, code: null}}`.
 
 ## POST /v1/embeddings (OpenAI Embeddings API)
 
 Text embeddings, available when the **served model is an embedding model**
 (plain Qwen3 / Qwen3-Embedding) — consistent with the single-model server:
 `mlx-bun serve mlx-community/Qwen3-Embedding-4B-4bit-DWQ`, then POST here. On
-any other served model the route returns `400 invalid_request_error`.
-
-- `input` (string or array of strings), `model` (ignored — the served model
-  is used), and a **non-standard** `instruction` (optional): applies
-  Qwen3-Embedding's query format `Instruct: {instruction}\nQuery:{text}`,
-  which steers *which* similarity axis the geometry reflects. Omit it for
-  plain document embeddings.
+any other served model the route returns `400 invalid_request_error`
+(`src/serve/model-admin-routes.ts`).
+
+- `input` (string or array of strings; anything else is a `400`), `model`
+  (ignored — the served model is used), and a **non-standard**
+  `instruction` (optional): applies Qwen3-Embedding's query format
+  `Instruct: {instruction}\nQuery:{text}`, which steers *which* similarity
+  axis the geometry reflects. Omit it for plain document embeddings.
 - Pooling is last-token + L2-normalization (the vectors are unit-length);
   similarity is the dot product. Bit-exact vs the mlx-lm `qwen3` reference
-  (`tests/qwen3-embed-parity.test.ts`).
+  (`tests/parity/qwen3-embed-parity.test.ts`).
 - Response: `{ "object": "list", "data": [{ "object": "embedding", "index":
   0, "embedding": [float…] }, …], "model": "<served id>", "usage": {
   "prompt_tokens": N, "total_tokens": N } }`. Embedding is a single forward
@@ -510,16 +737,31 @@ curl localhost:8080/v1/embeddings -H 'content-type: application/json' \
   -d '{"input": ["the cat sat on the mat", "a kitten by the window"]}'
 ```
 
+## GET /v1
+
+API index for discovery tooling:
+
+```jsonc
+{ "name": "mlx-bun", "version": "<package version>", "model": "<served model id>",
+  "endpoints": ["POST /v1/chat/completions", "POST /v1/completions", "POST /v1/messages",
+                "POST /v1/responses", "POST /v1/embeddings", "GET /v1/models",
+                "GET/POST/DELETE /v1/adapters", "GET /health", "GET /stats", "GET /fit",
+                "GET /library", "GET /downloads"] }
+```
+
+(The list is a curated subset; this document is the full inventory.)
+
 ## GET /v1/models
 
 `{ "object": "list", "data": [{ "id": "<model id>", "object": "model",
-"created": <unix s>, … }] }`
+"created": <unix s>, … }] }` — `created` is the server start time for every
+row.
 
 The served model is FIRST, with extra capability fields:
 
 ```jsonc
 {
-  "id": "<served model id>", "object": "model", "created": 0,
+  "id": "<served model id>", "object": "model", "created": 1760000000,
   "owned_by": "mlx-bun",
   "context_window": 32768,
   "reasoning": false,           // switchable thinking channel (gates the
@@ -560,7 +802,7 @@ architectures, one row per repo via `listCanonical()` — duplicate snapshots
 from upstream re-pushes are not separate entries):
 
 ```jsonc
-{ "id": "<repo id>", "object": "model", "created": 0,
+{ "id": "<repo id>", "object": "model", "created": 1760000000,
   "vision": false,               // visionCapable(): sidecar OR encoder-free
                                  //   unified vision config
   "tier": "targeted" | "generic" // supportTier(): dedicated/generated forward
@@ -596,7 +838,7 @@ vision/audio, adapters, and training are not emulated by the serving port.
   "server": { "owner": "serve" | "pi-session" | "embedded", "model": "...", "started_at": 0 },
   "prompt_cache": { "entries": 0, "bytes": 0, "max_bytes": 0, "hits": 0, "misses": 0 },
   "response_store": { "entries": 0, "bytes": 0, "max_bytes": 33554432, "ttl_ms": 3600000 },
-  "kv_quant": { "mode": "mixed (kv_config.json)" | "uniform-kv8" | "turbo k8v3" | "bf16",
+  "kv_quant": { "mode": "bf16" | "uniform-kv8" | "turbo k8v3" | "mixed (kv_config.json)",
                  "layers": { "kv4": 8, "bf16": 40 },     // turbo: { "turbo-k8v3": 8, "bf16": 40 }
                  "attention": { "global": 10, "sliding_window": 38 } },
   // present only when --ssd-cache is on:
@@ -626,18 +868,13 @@ vision/audio, adapters, and training are not emulated by the serving port.
     "resident_weight_bytes": 0,
     "main_expert_slab_bytes": 0,
     "mtp_expert_slab_bytes": 0,
-    "expert_runtime": {
+    "expert_runtime": {               // null when the expert runtime is off
       "main_residency": { "resident": 0, "pinned": 0, "working": 0,
                             "hits": 0, "misses": 0, "evictions": 0 },
-      "mtp_residency": { "resident": 0, "pinned": 0, "working": 0,
-                           "hits": 0, "misses": 0, "evictions": 0 },
-      "last_turn": {
-        "main": { "demand": { "hits": 0, "misses": 0,
-                                  "readBytes": 0 } },
-        "mtp": { "demand": { "hits": 0, "misses": 0,
-                                 "readBytes": 0 } },
-        "pilot": null
-      },
+      "mtp_residency": { /* same shape */ } | null,
+      "last_turn": { "main": { "demand": { "hits": 0, "misses": 0, "readBytes": 0 } },
+                     "mtp": { "demand": { "hits": 0, "misses": 0, "readBytes": 0 } },
+                     "pilot": null },
       "last_repin": []
     }
   },
@@ -655,16 +892,122 @@ vision/audio, adapters, and training are not emulated by the serving port.
 }
 ```
 
+`kv_quant.mode` reflects the `--kv-quant` flag the server was started
+with; the default is `bf16` (no KV quantization). `mixed (kv_config.json)`
+appears only when `--kv-quant config` was passed explicitly and the
+checkpoint ships a per-layer `kv_config.json` — per-layer KV quantization
+is never selected automatically.
+
 `pending_snapshots` counts prompt-cache entries scheduled for persistence but
 not yet confirmed by the atomic SSD store. `longest_durable_prefix_tokens` is
 the longest prefix already present in the SSD index, not merely queued.
 
+## GET /fit
+
+Fit assessment for the loaded model on this machine, plus a capability
+matrix across Apple SKUs. Used by the status page. Experts bytes come
+from the registry so MoE active-parameter predictions match the serve
+banner and `mlx-bun fit`. When the eval DB has a real measured decode
+rate for this model snapshot, it is included and takes precedence over
+the prediction.
+
+For the direct Colibri GLM-5.2 runtime this endpoint switches to the exact
+serve-time memory plan. The response separates the full streamed artifact on
+disk from resident weights, main/MTP expert slabs, KV, and other reserves.
+`measured_decode_tps` is the G5 warm quality-preserving measurement;
+`glm52.direct_oracle_warm_decode_tps` is the same-machine direct Colibri
+control, while `glm52.aspirational_decode_tps` is a target, not a release
+gate. The single-row SKU result describes the current machine because the
+generic all-resident SKU estimator is inapplicable
+(`report.predicted_decode_tps` is `null` there).
+
+```jsonc
+{
+  "machine": { "chip": "M4 Pro", "ram_bytes": 0, "bandwidth_gbs": 0.0 },
+  "context_tokens": 8192,          // current admission ceiling
+  "typical_context_tokens": 8192,  // min(8192, context_tokens)
+  "typical_decode_tps": 0.0,       // predicted at typical_context_tokens
+  "measured_decode_tps": null,     // real number from eval DB, or null
+  "measured_at": null,             // unix ms of measurement, or null
+  "report": {
+    "fits": true,
+    "weights_bytes": 0,
+    "kv_bytes": 0,
+    "transient_bytes": 0,
+    "total_bytes": 0,
+    "usable_bytes": 0,
+    "max_safe_context": 8192,
+    "predicted_decode_tps": 0.0
+  },
+  // GLM-5.2 only:
+  "glm52": {
+    "artifact_disk_bytes": 0,       // exact registry size; null if unavailable
+    "main_expert_slab_bytes": 0,
+    "mtp_expert_slab_bytes": 0,
+    "max_generation_tokens": 128,
+    "direct_oracle_warm_decode_tps": 0.27,
+    "aspirational_decode_tps": 2.0
+  },
+  "sku_matrix_ctx": 32768,
+  "sku_matrix": [{
+    "sku": "M4 Pro 24 GB", "ram_gb": 24,
+    "fits": true, "max_context": 32768, "decode_tps": 0.0
+  }]
+}
+```
+
+## Adapters (LoRA hot-swap)
+
+Routes in `src/serve/model-admin-routes.ts`; the manager is
+`AdapterManager` in `src/lora.ts`.
+
+- `GET /v1/adapters` — `{ adapters: [{ id, path, rank, scale, size_bytes,
+  mounted_layers, ram_bytes }] }` — currently-mounted adapters only.
+  `ram_bytes` is the actual resident size of the adapter's mounted
+  `lora_a`/`lora_b` arrays (summed `MlxArray.nbytes` — real RAM cost while
+  mounted, not a guess from the on-disk file size).
+- `GET /v1/adapters/available` — `{ adapters: [{ id, path, rank, scale,
+  base_model, mounted, compatible }] }` — every adapter found on disk
+  (`~/.cache/mlx-bun-finetunes`, `~/.cache/mlx-bun/adapters`), unfiltered.
+  `compatible` is true when the adapter's recorded base model matches the
+  currently-served model (compared by bare repo name) or the adapter
+  recorded no base at all; `mounted` is true when it's already loaded.
+  The web chat's adapter chip uses `compatible` to gray out entries it
+  won't let you select rather than hiding them.
+- `POST /v1/adapters` — `{ "id": "...", "path": "/dir" }` (both required,
+  else `400 "id and path required"`); mounts through the generation queue
+  (never races a forward pass). Response:
+  `{ id, mounted_layers, rank, scale, ram_bytes }`. `400` on shape/compat
+  mismatch — validation is all-or-nothing.
+- `DELETE /v1/adapters/<id>` — unmount; `{ id, removed_layers }` on
+  success, `404 {"error":{"message":"adapter <id> not mounted"}}` otherwise.
+
+Select per request with the `adapter` body field (chat, text completions;
+the Anthropic and Responses surfaces pass it through as an extra), which
+also accepts a composed spec — `"a+b"` (or `"a,b"`) stacks two mounted
+adapters, their LoRA residuals summed in order
+(`AdapterManager.resolveSpec` / `parseAdapterSpec` in `src/lora.ts`);
+every named id must already be mounted or the request 400s with the
+unknown id named. Prompt-cache entries are namespaced per adapter spec
+(including composed ones), so switching adapters — or switching which
+ones are stacked — never reuses another combination's KV.
+
+`serve --adapter <dir>` (alias `--adapter-path`, mlx_lm.server's
+spelling) mounts an adapter at startup through this same machinery and
+makes it the default for requests that send no `adapter` field; an
+explicit `adapter` (including `"none"`) always wins, and hot-swap via
+these endpoints is unchanged.
+
 ## POST /admin/cache/flush
 
 Forces every pending SSD prompt-cache snapshot through the serial write queue
 and waits for the atomic temp-file/fsync/rename boundary. The response is `200`
 only when no snapshot or spill remains pending and no write failed during this
 flush; otherwise it is `503` with the counters that explain why.
+A snapshot missing from both RAM and usable SSD coverage remains pending
+across repeated flushes. Retrying does not turn a missing snapshot into a
+successful durability result. Already-durable prefixes avoid another clone
+and write.
 
 ```jsonc
 {
@@ -685,13 +1028,16 @@ flush; otherwise it is `503` with the counters that explain why.
 The standard benchmark calls this endpoint before its restart leg and records
 the result. Normal `mlx-bun serve` shutdown on `SIGINT` or `SIGTERM` performs
 the same flush after active requests drain, with a 120-second default timeout.
+Without `--ssd-cache` the route still answers (`entries: 0`).
 
 ## GET /library
 
+`?refresh=1` bypasses the short response cache, including after a parent-managed job finishes.
+
 Returns all models found in the local HuggingFace hub cache (via the
 registry scan), each annotated with a fit assessment for this machine.
 Response is cached for 30 seconds (registry scan + config reads; no
-tensor bytes are read).
+tensor bytes are read). Handler: `src/serve/discovery-routes.ts`.
 
 ```jsonc
 {
@@ -720,6 +1066,203 @@ tensor bytes are read).
 One row per repo (`listCanonical()`; duplicate snapshots from upstream
 re-pushes surface only via the CLI's `mlx-bun ls --all-revisions`).
 
+## GET /downloads
+
+Snapshot of the last 5 model downloads (active, completed, or errored)
+initiated via `mlx-bun download`, the web library panel, or
+`POST /api/hub/download`.
+
+```jsonc
+{
+  "downloads": [{
+    "repo_id": "…",
+    "state": "active" | "done" | "error",
+    "current_file": "model.safetensors" | null,
+    "received_bytes": 0,
+    "total_bytes": 0,
+    "files_done": 0,
+    "files_total": 0,
+    "bytes_per_sec": 0,          // rolling ~5 s window
+    "started_at": 1760000000,
+    "finished_at": null,
+    "error": "…"                 // present on state "error"
+  }]
+}
+```
+
+## Jobs (`/api/jobs`)
+
+The web wizards (quantize, fine-tune, dataset) run as jobs: a SQLite row
+plus an NDJSON event log (`src/jobs/`). Submit routes return a `job_id`;
+these routes read progress. Loopback-served admin routes, no separate auth
+(same posture as every other `/api/*` route). Handler:
+`src/serve/admin-routes.ts`.
+
+`GET /api/jobs?limit=50&kind=quantize|finetune|dataset` — most recent
+jobs, newest first: `{ "ok": true, "jobs": [JobRow, …] }`.
+
+`GET /api/jobs/<id>` — one row, or `404 { "ok": false, "error": "job not
+found" }`:
+
+```jsonc
+{ "ok": true, "job": {
+  "id": "…", "kind": "quantize" | "finetune" | "dataset",
+  "status": "queued" | "running" | "done" | "failed" | "zombie",
+  "config_json": "{…}",          // the submit body as stored
+  "progress": 0.0,               // 0..1, from the latest stage/metric event
+  "message": "…" | null,
+  "log_path": "…", "output_path": "…" | null, "error": "…" | null,
+  "started_at": "<ISO>", "ended_at": "<ISO>" | null
+} }
+```
+
+`GET /api/jobs/<id>/stream` — EventSource-compatible SSE tail of the job's
+log: a `retry: 1500` line first, then one `data: <JobEvent>` frame per
+event, polling while the job is non-terminal, then `event: end` +
+`data: {}` and close. An unknown id streams a single `failed` event then
+`end`. Events:
+
+```jsonc
+{ "type": "started", "ts": 0 }
+{ "type": "log", "line": "…" }
+{ "type": "stage", "stage": "…", "progress": 0.5, "message": "…" }
+{ "type": "metric", "kind": "train" | "val", "step": 0, "loss": 0.0 }   // + grad_norm, learning_rate, tokens_per_sec, …
+{ "type": "done", "ts": 0, "output_dir": "…", "summary": { } }
+{ "type": "failed", "error": "…", "ts": 0 }
+```
+
+## Fine-tune (`/api/finetune/*`)
+
+The HTTP entry point to LoRA training (`src/serve/lab-routes.ts` →
+`src/train/job.ts`). It runs the same runner the CLI's `mlx-bun train`
+drives, as a subprocess job (crash isolation + one GPU lease across
+concurrent server requests). Data formats, every config knob, and the
+methodology are in [training.md](./training.md); this section is the wire
+shape.
+
+`POST /api/finetune/submit` — body is `FinetuneSubmit` (`src/train/job.ts`).
+`model_dir` and `data_dir` are required at the route (`400 "model_dir and
+data_dir required"`); `adapter_path` defaults to
+`~/.cache/mlx-bun/adapters/adapter-<timestamp>` when omitted. Everything
+else is optional and falls back to `DEFAULT_TRAIN_CONFIG`:
+
+```jsonc
+{
+  "model_dir": "/path/to/snapshot",       // required
+  "data_dir": "/path/to/dataset",         // required: train.jsonl (+ optional valid.jsonl)
+  "adapter_path": "/path/to/output",      // optional (default above)
+  "method": "sft" | "dpo" | "orpo",
+  "rank": 16, "scale": 20, "rank_scaling": "…", "target_modules": ["…"], "num_layers": 0,
+  "iters": 300, "learning_rate": 2e-4, "max_seq_length": 2048, "batch_size": 1,
+  "grad_accumulation_steps": 1, "seed": 0, "steps_per_report": 1, "steps_per_eval": 0,
+  "weight_decay": 0.0, "lora_dropout": 0.0, "rs_lora": false, "lora_plus_ratio": 1,
+  "grad_checkpoint": false, "mlp_split": false, "segment_size": 0,
+  "save_checkpoints": true, "grad_clip_norm": 0, "val_max_examples": 0,
+  "dpo_beta": 0.1, "dpo_warmup_iters": 0, "dpo_lr_schedule": "constant" | "cosine",
+  "orpo_lambda": 0.1, "orpo_warmup_iters": 0, "orpo_lr_schedule": "constant" | "cosine",
+  "orpo_chunk_size": 0, "orpo_fused_ce": true, "orpo_flash_ce": true, "orpo_prefix_shared": true,
+  "sft_scope": "full" | "response",
+  "warm_start_adapter": "/path/to/adapter"
+}
+```
+
+Response: `{ "ok": true, "job_id": "…", "adapter_path": "…" }`. Then
+follow `GET /api/jobs/<job_id>/stream` for `metric` events (`kind:
+"train"|"val"`, `step`, `loss`, …) and the terminal `done`/`failed`.
+Config validation errors (an invalid `sft_scope`, a missing `adapter_path`
+at the runner) surface as the job's `failed` event, not as a `4xx`.
+
+```bash
+curl -s localhost:8080/api/finetune/submit -X POST -H 'content-type: application/json' -d '{
+  "model_dir": "/path/to/snapshot", "data_dir": "/path/to/dataset",
+  "adapter_path": "/path/to/output-adapter",
+  "method": "sft", "rank": 16, "iters": 300, "learning_rate": 2e-4, "max_seq_length": 2048
+}'
+# → {"ok":true,"job_id":"…","adapter_path":"/path/to/output-adapter"}
+curl -N localhost:8080/api/jobs/<job_id>/stream
+```
+
+`POST /api/finetune/inspect-dataset` with `{"path": "<data_dir>"}` — probe
+a dataset directory before submitting: `{ "ok": true, "n_train": N,
+"n_valid": N, "format": "messages" | "prompt-completion" | "text" | "dpo" |
+"unknown" }`, or `{ "ok": false, …, "error": "<train.jsonl> not found" }`
+(HTTP 200 either way).
+
+`POST /api/finetune/merge` with `{"adapter_a": "/dir", "adapter_b":
+"/dir", "scales"?: [a, b]}` — fold two adapters into one (`mergeAdapters`
+in `src/train/merge.ts`; per-source scales default to each adapter's own
+config). Output goes to `~/.cache/mlx-bun/adapters/merged-<timestamp>`:
+`{ "ok": true, "merged_path": "…", "stats": { "layersMerged", "layersOnlyInOne",
+"totalKeysOut", "sources", "scales" } }`; `400 { "ok": false, "error" }` on
+a missing field or merge failure.
+
+`POST /api/finetune/export` with `{"base_model": "…", "adapter_path":
+"/dir", "method"?: "…"}` — writes a `manifest.json` describing the adapter
+into `~/.cache/mlx-bun/exports/export-<timestamp>`:
+`{ "ok": true, "export_path": "…", "manifest": { "version": 1, "base_model",
+"adapter_path", "method"?, "created_at" } }`; `400` on a missing field.
+
+## Quantize (`/api/quantize/*`)
+
+`POST /api/quantize/inspect` with `{"model_id": "<repo id | path>"}` —
+resolve a model through the registry and report whether the quantizer can
+walk it (`inspectModel`, `src/quantize/job.ts`): `{ "ok": true, "model_id",
+"arch": "<model_type>" | null, "support": true, "size_gb": 0.0 }`, or
+`{ "ok": false, …, "error" }` (HTTP 200 either way).
+
+`POST /api/quantize/submit` — starts a quantize job whose output lands in
+the HF hub cache as a synthetic repo `<org>/<name>-OptiQ-<suffix>`
+(`refs/main` written so the registry picks it up; `<suffix>` is
+`<bits>bit` or `mixed-<target_bpw>bpw`, plus `-rot<seed>` when rotating):
+
+```jsonc
+{
+  "model_id": "org/name | /path",   // required (400 "model_id required")
+  "bits": 4, "group_size": 64,
+  "target_bpw": 3.5,                // mixed-precision target; wins over bits in the name
+  "candidate_bits": [2, 3, 4, 8],
+  "reference": "…", "calibration_mix": "…", "n_calibration": 0,
+  "rotate_weights": false, "rotation_seed": 42
+}
+```
+
+Response: `{ "ok": true, "job_id": "…", "output_dir": "…" }`. The library
+cache is invalidated when the job completes.
+
+`POST /api/quantize/resolve-folder` and `POST /api/model/resolve-folder`
+(same handler) with `{"folder_name"?: "…", "rel_path"?: "…"}` — turn a
+folder the browser picked (a `models--org--name` hub dir, a snapshot hash
+dir, or a bare model dir under the hub cache / `~/.cache/mlx-bun`) into a
+servable path: `{ "ok": true, "path": "…", "repo_id"?: "…", "model_type"?:
+"…" }`, or `{ "ok": false, "error": "Couldn't locate this folder on disk —
+paste the path instead." }` (HTTP 200).
+
+## Dataset (`/api/dataset/*`)
+
+`GET /api/dataset/templates` — the dataset-builder template registry
+(`src/dataset/registry.ts`): `{ "templates": [{ "id", "label",
+"description", "output_format": "messages" | "prompt_completion" | "dpo" |
+"text", "needs_llm": bool, "fields": [{ "name", "type": "text" | "textarea" |
+"number", "label", "hint"?, "required"?, "default"? }] }] }`.
+
+`POST /api/dataset/submit` with `{"template_id": "…", "inputs": {…},
+"model_name"?: "…"}` — runs the template in-process as a job; LLM-backed
+templates call back into this server's own `/v1` (`api_url` =
+`http://127.0.0.1:<port>`). Output dir is
+`~/.cache/mlx-bun/datasets/dataset-<template>-<timestamp>`. Response:
+`{ "ok": true, "job_id": "…", "output_dir": "…" }`; `400 { "ok": false,
+"error": "unknown template …" }` for an unknown id.
+
+## POST /api/{quantize,finetune,dataset}/push
+
+Upload a job's output (or any folder) to the Hugging Face Hub with the
+saved write token (`src/hf-push.ts`). Body: `{"repo_id": "org/name",
+"job_id"?: "…", "source_path"?: "/dir", "private"?: false}` — `repo_id` is
+required; the source is `source_path`, else the job's `output_path`. The
+`dataset` variant pushes as a dataset repo, the others as model repos.
+Response `{ "ok": true, "url": "…" }`; `400 { "ok": false, "error" }` when
+no token is saved, no source directory resolves, or the upload fails.
+
 ## GET /api/gc/plan · POST /api/gc/execute
 
 Reclaim disk from superseded snapshots + orphaned blobs in the local HF
@@ -764,13 +1307,12 @@ Errors follow the same `{ "ok": false, "error": "…" }` shape as the other
 ## GET /api/memory/\* · POST /api/memory/init
 
 Thin loopback JSON wrappers over `src/memory/vault.ts` for the web chat's
-Memory panel (docs/design/web-chat-redesign.md §5.5) — same loopback-only
-admin-route posture as `/api/gc/*`, no separate auth. Handlers live in
-`src/memory/rest.ts`; they never touch the agent-tool surface
-(`src/memory/tools.ts`), which stays read-only and unchanged. Every route
-below degrades gracefully — a missing vault, an unknown article, or a bad
-param returns `{ "ok": false, ... }` (with an appropriate HTTP status), never
-a 500 or an unhandled throw.
+Memory panel — same loopback-only admin-route posture as `/api/gc/*`, no
+separate auth. Handlers live in `src/memory/rest.ts`; they never touch the
+agent-tool surface (`src/memory/tools.ts`), which stays read-only. Every
+route below degrades gracefully — a missing vault, an unknown article, or
+a bad param returns `{ "ok": false, ... }` (with an appropriate HTTP
+status), never a 500.
 
 When no vault exists yet, every `GET` route (except `/init`) returns:
 
@@ -792,25 +1334,23 @@ separate (mirrors `memory_list`):
 ```
 
 `GET /api/memory/search?q=<query>&scope=all|articles|reference&limit=50` —
-wraps `searchArticles`; same summaries/hits shape the `memory_search` tool
-formats from:
+wraps `searchArticles` (`limit` capped at 200; `400` without `q`); same
+summaries/hits shape the `memory_search` tool formats from:
 
 ```jsonc
 { "ok": true, "summaries": [{ "article": "…", "occurrences": 3, "matched_terms": ["…"] }], "hits": [{ "article": "…", "anchor": "…", "line": 10, "excerpt": "…" }] }
 ```
 
 `GET /api/memory/article?name=<article>` — rendered source plus the
-deterministic metadata the panel needs to render it (infobox, lead, series
-banner, section skeleton) without re-parsing client-side; 404s
-`{ "ok": false }` for an unknown name:
+deterministic metadata the panel needs (infobox, lead, series banner,
+section skeleton); `404 { "ok": false }` for an unknown name:
 
 ```jsonc
 { "ok": true, "name": "…", "path": "…", "content": "# …", "infobox": { "type": "…", "entityKind": "thing", "fields": [] }, "lead": "…", "series": null, "structure": [] }
 ```
 
 `GET /api/memory/links?name=<article>` — inbound/outbound wikilinks (same
-data `memory_links` resolves); articles only, not `Reference/*` (matching
-the tool's own scope):
+data `memory_links` resolves); articles only, not `Reference/*`:
 
 ```jsonc
 { "ok": true, "name": "…", "outbound": ["…"], "inbound": ["…"] }
@@ -818,7 +1358,7 @@ the tool's own scope):
 
 `GET /api/memory/history?name=<article>&limit=50` — the article's git log
 (read-only `git log` plumbing on the vault's own repo, via `Bun.spawn` —
-never a shell string):
+never a shell string; `limit` capped at 200):
 
 ```jsonc
 { "ok": true, "name": "…", "isGitRepo": true, "entries": [{ "hash": "…", "date": "YYYY-MM-DD", "subject": "…" }] }
@@ -827,99 +1367,78 @@ never a shell string):
 `GET /api/memory/diff?name=<article>&rev=<hash>` — that commit's diff for
 the article (`git show <rev> -- <path>`). `rev` must match
 `/^[0-9a-f]{4,40}$/` (a bare commit hash — never a ref expression like
-`HEAD~1` or `main^`) or the request 400s before touching git; `name` is
-resolved through the same existence-checked normalization `readArticle`
-uses, so a path-traversal or otherwise-invalid name 404s rather than
-reaching the `git` argv:
+`HEAD~1`) or the request 400s before touching git; an unknown `name` or a
+revision with no diff for it 404s:
 
 ```jsonc
 { "ok": true, "name": "…", "rev": "…", "diff": "diff --git a/articles/…" }
 ```
 
 `POST /api/memory/init` with optional body `{"path"?: string}` — the
-first-run consent-card backend. Delegates to the exact same `setupVault()`
-the CLI's `mlx-bun memory init` calls (idempotent: create dirs, write
-README + Meta pages only if missing, git init + initial commit); omits only
-the CLI's interactive extras (seed-from-existing-vault prompt, nightly
-schedule prompt), which stay TTY-only. `path`, if given, must resolve under
-the default vault root or the OS temp directory — `setupVault()` mkdir's
-into it and `git init`s it if it isn't already a repo, so anything outside
-those trees 400s before touching the filesystem rather than letting a
-caller redirect vault setup at an arbitrary directory:
+first-run consent-card backend. Delegates to the same `setupVault()` the
+CLI's `mlx-bun memory init` calls (idempotent: create dirs, write README +
+Meta pages only if missing, git init + initial commit); omits the CLI's
+interactive extras. `path`, if given, must resolve under the default vault
+root or the OS temp directory, else `400`:
 
 ```jsonc
 { "ok": true, "result": { "root": "…", "created": ["…"], "gitInitialized": true, "alreadySetUp": false }, "status": { "root": "…", "exists": true, "articleCount": 0, "referenceCount": 9, "isGitRepo": true, "recentArticles": [] } }
 ```
 
-## GET /api/settings/tool-approvals · DELETE /api/settings/tool-approvals
-
-The web chat's durable "always allow this tool" list for gated tools
-(`bash`/`edit`/`write`) — docs/design/web-chat-redesign.md §5.4/§6.5/§9
-Phase 2, risk #6. Backed by `~/.mlx-bun/tool-approvals.json`
-(`src/tool-approvals.ts`), a versioned `{version, allows}` file (same
-plain-JSON-at-0600 convention as `~/.mlx-bun/hf.json`) keyed by stable tool
-NAME, not per-call arguments — "always allow bash" means every future
-`bash` call skips the browser's approval card, on every chat and every
-browser tab, until forgotten. These two routes are read/forget only:
-granting an always-allow happens through the approval card itself (the
-`approval` WS frame on `/ws/chat`, `alwaysAllow: true`), never a bare
-settings-form POST.
+## GET /v1/memory/synthesize
 
-`GET /api/settings/tool-approvals`:
+Runs the memory synthesis pipeline (`runSynthesis`, `src/memory/pipeline.ts`
+— the same job `mlx-bun memory synthesize` runs) and streams its progress
+as SSE. `?dry=1` plans the stages without model calls or writes. This is a
+long GPU job over the whole store on a real run; it is registered under
+`/v1/` for historical reasons and is not part of the OpenAI surface.
 
-```jsonc
-{ "ok": true, "alwaysAllow": ["bash", "edit"] }
 ```
-
-`DELETE /api/settings/tool-approvals` with body `{"tool": "bash"}` —
-revokes one tool's always-allow (idempotent; forgetting an entry that
-isn't present is not an error). Returns the updated set:
-
-```jsonc
-{ "ok": true, "alwaysAllow": ["edit"] }
+data: {"type":"stage","stage":"ingest","message":"…"}
+data: {"type":"log","message":"…"}
+data: {"type":"done","message":"synthesis done — …"}
+data: {"type":"summary","implemented":true,"stages":["ingest","segment","extract","route","create","section-route","patch","link","wikify"],"note":"…"}
+data: [DONE]
 ```
 
-Separately, `GET /api/settings/hf-token` / `POST /api/settings/hf-token`
-manage the Hugging Face write token the same settings modal's other
-section uses (see the `upload` CLI command in [cli.md](./cli.md) for the
-push-to-hub flow this token drives).
+A failure emits `data: {"type":"error","message":"…"}` and closes without
+`[DONE]`.
 
-## GET /downloads
+## Settings (`/api/settings/*`)
 
-Snapshot of the last 5 model downloads (active, completed, or errored)
-initiated via `mlx-bun download` or the web library panel.
+`GET /api/settings/hf-token` → `{ "ok": true, "hasToken": bool }`;
+`POST /api/settings/hf-token` with `{"token": "hf_…"}` saves the Hugging
+Face write token to `~/.mlx-bun/hf.json` (mode 0600) →
+`{ "ok": true }`; `400 "token required"` when empty. The token drives the
+push routes above and the `upload` CLI command ([cli.md](./cli.md)).
+
+`GET /api/settings/tool-approvals` / `DELETE /api/settings/tool-approvals`
+— the web chat's durable "always allow this tool" list for gated tools
+(`bash`/`edit`/`write`), backed by `~/.mlx-bun/tool-approvals.json`
+(`src/tool-approvals.ts`), keyed by stable tool NAME, not per-call
+arguments. These two routes are read/forget only: granting an always-allow
+happens through the approval card itself (the `approval` WS frame on
+`/ws/chat` with `alwaysAllow: true`), never a bare settings POST.
 
 ```jsonc
-{
-  "downloads": [{
-    "repo_id": "…",
-    "state": "active" | "done" | "error",
-    "current_file": "model.safetensors" | null,
-    "received_bytes": 0,
-    "total_bytes": 0,
-    "files_done": 0,
-    "files_total": 0,
-    "bytes_per_sec": 0,          // rolling ~5 s window
-    "started_at": 1760000000,
-    "finished_at": null,
-    "error": "…"                 // present on state "error"
-  }]
-}
+// GET
+{ "ok": true, "alwaysAllow": ["bash", "edit"] }
+// DELETE with body {"tool": "bash"} — idempotent; returns the updated set
+{ "ok": true, "alwaysAllow": ["edit"] }
 ```
 
+`DELETE` without `tool` is `400 "tool required"`.
+
 ## Model Hub (`/api/hub/*`)
 
-The web chat's Model Hub panel (docs/design/web-chat-redesign.md §9 Phase 3,
-beat-matrix Axis 3): browse downloaded models, search Hugging Face, and kick
-off downloads — all loopback-served, no separate auth, same posture as
-`/api/gc/*` and `/api/memory/*`. Handlers live in `src/hub-rest.ts` (pure
-functions, no loaded-model dependency); route dispatch in `src/server.ts`
-just matches path + method.
+The web chat's Model Hub panel: browse downloaded models, search Hugging
+Face, and kick off downloads — all loopback-served, no separate auth.
+Handlers live in `src/hub-rest.ts` (pure functions, no loaded-model
+dependency).
 
 `GET /api/hub/local` — every model in the local registry (same source
 `/library` reads), each with a `/fit`-computed hardware verdict at a fixed
-8k context — the beat matrix's "real hardware verdict per row" that optiq's
-Hub lacks:
+8k context:
 
 ```jsonc
 {
@@ -939,11 +1458,10 @@ Hub lacks:
 ```
 
 `GET /api/hub/search?q=<query>` — server-side Hugging Face model search,
-filtered to the `mlx` library tag (the tag every mlx-community / MLX-format
-repo carries) so results are MLX-compatible by construction, normalized to
-the fields the Hub panel needs. Never downloads anything — search only.
-Degrades gracefully on any network failure (DNS, timeout, non-2xx) to an
-explicit offline state rather than a 500:
+filtered to the `mlx` library tag so results are MLX-compatible by
+construction. Never downloads anything. `400` without `q`. Degrades on any
+network failure (DNS, timeout, non-2xx) to an explicit offline state
+rather than a 500:
 
 ```jsonc
 { "ok": true, "offline": false, "results": [{ "id": "mlx-community/…", "downloads": 0, "likes": 0, "size_estimate": null }] }
@@ -953,69 +1471,51 @@ explicit offline state rather than a 500:
 { "ok": true, "offline": true, "error": "…", "results": [] }
 ```
 
-`size_estimate` is always `null` in v1 — the search endpoint doesn't return
-per-repo file sizes and a second per-repo call would slow the search down;
-the fit badge lands once a model is actually downloaded (`/api/hub/local`).
+`size_estimate` is always `null` — the search endpoint doesn't return
+per-repo file sizes; the fit badge lands once a model is actually
+downloaded (`/api/hub/local`).
 
 `POST /api/hub/download` with body `{"repo": "org/name"}` — starts a
-background download via the existing `downloadModel()` +
-`src/download.ts` process tracker and returns immediately; progress is
-already visible via [`GET /downloads`](#get-downloads). Refuses a duplicate
-kick-off for a repo that's already downloading:
+background download via `downloadModel()` and returns immediately;
+progress is visible via [`GET /downloads`](#get-downloads). Refuses a
+duplicate kick-off for a repo that's already downloading:
 
 ```jsonc
 { "ok": true, "repo": "org/name", "started": true }
 ```
 
 ```jsonc
-{ "ok": false, "error": "a download for org/name is already in progress" }
+{ "ok": false, "error": "a download for org/name is already in progress" }   // 409
 ```
-(409)
 
 `POST /api/hub/serve` with body `{"model": "org/name"}` — **always answers
-`restart_required`, never performs a live in-process swap.** Investigated
-against `docs/design/runtime-isolation.md`: the web chat's `/ws/chat` path
-is explicitly not proxied even under `--isolate` (`src/serve/isolate.ts`
-answers it 501), and `--isolate` itself is opt-in, not the default — so the
-process a web chat session is actually attached to always has exactly one
-model loaded with no drop-weights-and-reload seam reachable from that path.
-(The `--isolate` proxy's `ModelPool`, P2 of that doc, *is* a real
-spawn-overlap live-swap mechanism — it just lives entirely on the isolated
-`/v1/*` HTTP surface, not on `/ws/chat`.) Faking a swap here would leave the
-server in a half-state; the honest answer is the restart command:
+`restart_required`, never performs a live in-process swap.** The process a
+web chat session is attached to has exactly one model loaded and no
+drop-weights-and-reload seam reachable from `/ws/chat` (the `--isolate`
+proxy's `ModelPool` is a real spawn-overlap swap, but it lives on the
+isolated `/v1/*` surface only — `src/serve/isolate.ts`). The honest answer
+is the restart command (HTTP 200, `ok: false`):
 
 ```jsonc
 { "ok": false, "restart_required": true, "command": "mlx-bun serve org/name" }
 ```
 
-Wiring `/ws/chat` through the isolate proxy (or otherwise reaching
-`ModelPool`'s spawn-overlap swap from the web chat) is the Hub's live-swap
-follow-up, not yet scheduled.
-
 ## GET /api/sessions/search · GET /api/sessions/export
 
 Full-text search across web-chat session message **bodies** and chat
-export (docs/design/web-chat-redesign.md §9 Phase 3, beat-matrix Axis
-10/11's full-text-search BEAT: Claude's own session search is title-only —
-a widely-cited annoyance — and local storage removes any server-cost
-excuse to skip real body search). Same loopback-only, no-separate-auth
-posture as `/api/memory/*`/`/api/hub/*`. Handlers live in
-`src/serve/session-search.ts` (pure, read-only, no loaded-model
-dependency); route dispatch in `src/server.ts` just matches path + method.
-Both routes read the same session directory the web chat's `PiWebSession`
-writes to (`~/.mlx-bun/sessions`, pi's own JSONL-per-session format) and
-are JSONL-tolerant — a corrupt or mid-write line is skipped, never thrown.
-
-`GET /api/sessions/search?q=<query>` — case-insensitive substring scan (v1;
-no index — personal-chat-corpus scale, see the module header comment for
-the upgrade path if the corpus ever grows enough to matter) over every
-session file's user/assistant message text, capped at 50 matches total (10
-per session). Each match reports a plain-text ±60-char snippet plus the
-match's own `[start,end)` offsets **into that snippet** — offsets, not
-pre-rendered HTML highlighting, so the frontend escapes the snippet then
-inserts its own `<mark>` (the same escape-then-restore discipline the
-markdown renderer uses for code spans, applied here to search
-highlighting instead):
+export. Same loopback-only, no-separate-auth posture as `/api/memory/*`.
+Handlers live in `src/serve/session-search.ts` (pure, read-only, no
+loaded-model dependency). Both routes read the same session directory the
+web chat's `PiWebSession` writes to (`~/.mlx-bun/sessions`, pi's own
+JSONL-per-session format) and are JSONL-tolerant — a corrupt or mid-write
+line is skipped, never thrown.
+
+`GET /api/sessions/search?q=<query>` — case-insensitive substring scan (no
+index — personal-chat-corpus scale) over every session file's
+user/assistant message text, capped at 50 matches total (10 per session).
+Each match reports a plain-text ±60-char snippet plus the match's own
+`[start,end)` offsets **into that snippet** — offsets, not pre-rendered
+HTML, so the frontend escapes the snippet then inserts its own `<mark>`:
 
 ```jsonc
 {
@@ -1031,15 +1531,8 @@ highlighting instead):
 400s `{"ok": false, "error": "q is required"}` without a query.
 
 `GET /api/sessions/export?path=<session file>` — the raw session JSONL,
-parsed into an array of entries (one per line, in file order) — the
-frontend's Markdown/JSON export renders from this for a session that isn't
-the currently-open one (the open session's own history is already loaded
-client-side, but this endpoint is used uniformly for both cases so there's
-one code path, not two). `path` must resolve under the session directory —
-exactly the same guard shape as `PiWebSession`'s private
-`isUnderSessionDir` (the root itself, or a path prefixed by `root + "/"`)
-— reimplemented as a small standalone check in `session-search.ts` rather
-than exported from that class:
+parsed into an array of entries (one per line, in file order). `path` must
+resolve under the session directory:
 
 ```jsonc
 { "ok": true, "path": "…", "entries": [{ "type": "session", "id": "…", "cwd": "…" }, { "type": "message", "message": { "role": "user", "content": "…" } }] }
@@ -1050,153 +1543,118 @@ path inside the directory that doesn't exist on disk.
 
 ## Web app static routes + PWA installability
 
-The web chat (`GET /`) and everything it loads same-origin, no CDN, ever:
+The web chat (`GET /`) and everything it loads same-origin, no CDN, ever
+(`src/serve/static-routes.ts`; GET only):
 
 | Route | Content | Notes |
 | --- | --- | --- |
 | `GET /` | `src/web/app.html` | The unified SPA shell. |
-| `GET /assets/app.js` | `src/web/app.js` | GENERATED from `src/web/src/*.ts` by `bun scripts/build-web.ts` — see `tests/web-build.test.ts`'s freshness gate. |
-| `GET /assets/hljs.js`, `GET /assets/hljs.css` | `src/web/vendor/hljs*` | Vendored syntax highlighting, no CDN (see that dir's README). |
-| `GET /manifest.webmanifest` | `src/web/manifest.webmanifest` | PWA manifest — name/short_name/theme colors match the app's design tokens. |
-| `GET /assets/icon.svg` | `src/web/icon.svg` | A single inline SVG app icon. No binary PNGs are shipped (the hygiene gate forbids tracked binaries beyond its allowlist); some browsers don't render an SVG as an install icon — accepted, noted in [features-matrix.md](features-matrix.md). |
-| `GET /sw.js` | `src/web/sw.js` | Service worker, served `cache-control: no-store` at the root scope (required for a worker to control `/`). |
-
-**PWA scope (beat-matrix Axis 10 "PWA installability"):** the manifest +
-service worker exist for *installability and an instant static-shell
-paint* — "Add to Home Screen" / a browser "Install app" prompt, and the
-next visit's HTML/JS/CSS loading from cache while the WebSocket connects.
-This is explicitly **not** offline chat: `src/web/sw.js`'s fetch handler
-only intercepts the exact shell files listed above (`/`, `/assets/app.js`,
-`/assets/hljs.js`, `/assets/hljs.css`) and lets every dynamic route
-(`/api/*`, `/v1/*`, `/ws/chat`, `/downloads`, …) fall straight through to
-the network unconditionally — caching a chat API response would be
-actively misleading given the app is a thin client over a local model
-process that has to actually be running. Registration
-(`src/web/src/shell.ts`'s `initServiceWorker()`) is guarded to secure
-contexts: `https:` or `localhost`/`127.0.0.1`, matching the browser's own
-service-worker eligibility rule.
-
-## GET /fit
-
-Fit assessment for the loaded model on this machine, plus a capability
-matrix across Apple SKUs. Used by the status page. Experts bytes come
-from the registry so MoE active-parameter predictions match the serve
-banner and `mlx-bun fit`. When the eval DB has a real measured decode
-rate for this model snapshot, it is included and takes precedence over
-the prediction.
-
-For the direct Colibri GLM-5.2 runtime this endpoint switches to the exact
-serve-time memory plan. The response separates the full streamed artifact on
-disk from resident weights, main/MTP expert slabs, KV, and other reserves.
-`measured_decode_tps` is the G5 warm quality-preserving measurement;
-`glm52.direct_oracle_warm_decode_tps` is the same-machine direct Colibri
-control, while `glm52.aspirational_decode_tps` is a target, not a release
-gate. The single-row SKU result describes the current machine because the
-generic all-resident SKU estimator is inapplicable.
+| `GET /assets/app.js` | `src/web/app.js` | GENERATED from `src/web/src/*.ts` by `bun scripts/build-web.ts` — see `tests/using/web-build.test.ts`'s freshness gate. |
+| `GET /assets/hljs.js`, `GET /assets/hljs.css` | `src/web/vendor/hljs*` | Vendored syntax highlighting, no CDN. |
+| `GET /manifest.webmanifest` | `src/web/manifest.webmanifest` | PWA manifest. |
+| `GET /assets/icon.svg` | `src/web/icon.svg` | A single inline SVG app icon; no binary PNGs are shipped. |
+| `GET /sw.js` | `src/web/sw.js` | Service worker, served `cache-control: no-store` at the root scope. |
+| `GET /curves` | `src/lab/curve/curve-designer.html` | The HLG Curve Designer page (drives `/signal` + `/generate` below); read from disk when available, embedded copy in compiled binaries. `no-store`. |
+| `GET /curve-terrain` | `src/serve/assets/curve-terrain.html` | Curve terrain visualization; `404` when the artifact isn't on disk. |
+| `GET /dag` | `src/serve/assets/training-inference-map.html` | Training/inference DAG map; `404` when the artifact isn't on disk. |
+| `GET /status`, `/chat`, `/quantize`, `/finetune`, `/dataset` | — | Legacy page paths: `302` to `/#<path>` (the SPA's hash routes). |
+
+`/assets/*` and the manifest are served with `cache-control: public,
+max-age=3600`; `/sw.js`, `/curves`, `/curve-terrain`, `/dag` are `no-store`.
+
+**PWA scope:** the manifest + service worker exist for *installability and
+an instant static-shell paint* — "Add to Home Screen" / a browser "Install
+app" prompt, and the next visit's HTML/JS/CSS loading from cache while the
+WebSocket connects. This is explicitly **not** offline chat:
+`src/web/sw.js`'s fetch handler only intercepts the exact shell files
+(`/`, `/assets/app.js`, `/assets/hljs.js`, `/assets/hljs.css`) and lets
+every dynamic route (`/api/*`, `/v1/*`, `/ws/chat`, `/downloads`, …) fall
+straight through to the network unconditionally. Registration is guarded
+to secure contexts (`https:` or `localhost`/`127.0.0.1`).
+
+## Curve Designer: POST /signal · POST /generate
+
+Backends for the `/curves` page (HLG tone-curve sampling research tool,
+`src/lab/curve/curve-sampler.ts`). Both answer `OPTIONS` and send permissive CORS
+headers (`access-control-allow-origin: *`) so the page can be opened from
+a file or another origin. Both take the GPU lock (`gateway.runExclusive`)
+— they never interleave with a serving request.
+
+`POST /signal` with `{"prompt": "…"}` — one prefill forward of the prompt
+rendered as a single user turn; bins the next-token log-prob distribution
+into 80 buckets over the curve's x-axis so the editor can draw the signal
+under the curve: `{ "bins": [80 ints], "vocab": V }`. `400 {"error":
+"invalid JSON"}`; `500 {"error": "signal failed: …"}`.
+
+`POST /generate` with `{"prompt", "curve"?: {points: [...]}, "n"?: 3,
+"max_tokens"?: 80, "seed"?: 0, "default"?: false}` — samples `n` (1–8)
+completions of up to `max_tokens` (1–256) tokens. When `curve` has ≥2
+points and `default` is not `true`, the drawn log-prob transfer curve
+replaces temperature+softmax entirely; otherwise the model's default chat
+recipe (temperature/top-p/top-k) is used. A non-monotone curve is a `400`.
 
 ```jsonc
-{
-  "machine": { "chip": "M4 Pro", "ram_bytes": 0, "bandwidth_gbs": 0.0 },
-  "context_tokens": 8192,          // current admission ceiling
-  "typical_context_tokens": 8192,  // min(8192, context_tokens)
-  "typical_decode_tps": 0.0,       // predicted at typical_context_tokens
-  "measured_decode_tps": null,     // real number from eval DB, or null
-  "measured_at": null,             // unix ms of measurement, or null
-  "report": {
-    "fits": true,
-    "weights_bytes": 0,
-    "kv_bytes": 0,
-    "transient_bytes": 0,
-    "total_bytes": 0,
-    "usable_bytes": 0,
-    "max_safe_context": 8192,
-    "predicted_decode_tps": 0.0
-  },
-  // GLM-5.2 only:
-  "glm52": {
-    "artifact_disk_bytes": 0,       // exact registry size; null if unavailable
-    "main_expert_slab_bytes": 0,
-    "mtp_expert_slab_bytes": 0,
-    "max_generation_tokens": 128,
-    "direct_oracle_warm_decode_tps": 0.27,
-    "aspirational_decode_tps": 2.0
-  },
-  "sku_matrix_ctx": 32768,
-  "sku_matrix": [{
-    "sku": "M4 Pro 24 GB", "ram_gb": 24,
-    "fits": true, "max_context": 32768, "decode_tps": 0.0
-  }]
-}
+{ "mode": "curve" | "default",
+  "recipe": { "temperature": 0.7, "topP": 0, "topK": 0 },   // only in default mode
+  "n": 3, "seed": 0,
+  "samples": [{ "text": "…", "junk": false }] }             // junk = coherence heuristic tripped
 ```
 
-## Adapters (LoRA hot-swap)
-
-- `GET /v1/adapters` — `{ adapters: [{ id, path, rank, scale, size_bytes,
-  mounted_layers, ram_bytes }] }` — currently-mounted adapters only.
-  `ram_bytes` is the actual resident size of the adapter's mounted
-  `lora_a`/`lora_b` arrays (summed `MlxArray.nbytes` — real RAM cost while
-  mounted, not a guess from the on-disk file size); the web chat's adapter
-  routing table (§5.6 of `docs/design/web-chat-redesign.md`) shows this per
-  loaded adapter.
-- `GET /v1/adapters/available` — `{ adapters: [{ id, path, rank, scale,
-  base_model, mounted, compatible }] }` — every adapter found on disk
-  (`~/.cache/mlx-bun-finetunes`, `~/.cache/mlx-bun/adapters`), unfiltered.
-  `compatible` is true when the adapter's recorded base model matches the
-  currently-served model (compared by bare repo name) or the adapter
-  recorded no base at all; `mounted` is true when it's already loaded.
-  The web chat's adapter chip uses `compatible` to gray out entries it
-  won't let you select rather than hiding them.
-- `POST /v1/adapters` — `{ "id": "...", "path": "/dir" }`; mounts
-  through the generation queue (never races a forward pass). Response:
-  `{ id, mounted_layers, rank, scale, ram_bytes }`. 400 on shape/compat
-  mismatch — validation is all-or-nothing.
-- `DELETE /v1/adapters/<id>` — unmount; 404 if not mounted.
-
-Select per request with the `adapter` body field, which also accepts a
-composed spec — `"a+b"` (or `"a,b"`) stacks two mounted adapters, their
-LoRA residuals summed in order (`AdapterManager.resolveSpec` /
-`parseAdapterSpec` in `src/lora.ts`); every named id must already be
-mounted or the request 400s with the unknown id named. The web chat's
-adapter routing table exposes this as a "stack" action on top of the
-composer's single-select quick-switcher. Prompt-cache entries are
-namespaced per adapter spec (including composed ones), so switching
-adapters — or switching which ones are stacked — never reuses another
-combination's KV.
-
-`serve --adapter <dir>` (alias `--adapter-path`, mlx_lm.server's
-spelling) mounts an adapter at startup through this same machinery and
-makes it the default for requests that send no `adapter` field; an
-explicit `adapter` (including `"none"`) always wins, and hot-swap via
-these endpoints is unchanged.
-
-## App-aware assistant (`/ws/chat`)
-
-The web chat agent can see and act on the app it lives in —
-`docs/design/web-chat-redesign.md` §6.6, beat matrix Axis 12. No
-screenshots and no vision model are involved: the browser sends a
-structured DOM snapshot as a WS frame, and the model gets three tools that
-read/navigate/highlight that snapshot.
-
-Three tools join the web chat's tool allowlist unconditionally (same
-class as `web_search`/`read` — read-only-on-the-machine, never gated by
-the approval card, regardless of memory or `codingTools` state; see
-`APP_AWARE_TOOL_NAMES` in `src/pi-web.ts`):
+## Web chat WebSocket (`/ws/chat`)
+
+`GET /ws/chat` upgrades to a WebSocket (`426` when the upgrade header is
+missing; `501` under `--isolate`). It carries the web chat's pi
+`AgentSession` — the model is driven through pi, which calls back into
+this server's own loopback `/v1`. Frames are JSON objects with a `type`
+field; the exact TypeScript unions are `ClientMessage` and `ServerMessage`
+in `src/pi-web.ts` (the web frontend imports them type-only, so both ends
+are compile-checked).
+
+Client → server: `prompt {text, images?: [{data, mimeType}]}`, `abort`,
+`approval {callId, decision, editedArgs?, alwaysAllow?}`, `set_thinking
+{enabled}`, `set_coding_tools {enabled}`, `set_adapter {id | null}`,
+`set_sampling {scope?: "session" | "next_turn", temperature?, top_p?,
+top_k?, min_p?, xtc_probability?, xtc_threshold?, repetition_penalty?,
+repetition_context_size?, presence_penalty?, frequency_penalty?, seed?}`
+(null = server default), `set_system_prompt {text | null}`, `new_session`,
+`list_sessions`, `open_session {path}`, `fork_session {path}`,
+`delete_session {path}`, `regenerate`, `edit_resend {text}`,
+`switch_sibling {entryId}`, `context {context}` (app-aware assistant, below).
+
+Server → client: `ready {model, vision, audio, thinking, genDefaults}`,
+`turn_start`, `text_delta {delta}`, `thinking_delta {delta}`, `tool_start
+{callId, tool, args}`, `tool_approval_request {callId, tool, args}`,
+`tool_update {callId, chunk}`, `tool_end {callId, ok, result}`, `turn_end
+{lane?}` (the serving lane the turn ran on, from `usage.lane` via the lane
+registry — never guessed client-side), `queue_update {steering, followUp}`,
+`history {items}`, `sessions {items, activePath?}`, `siblings {entryId?,
+index, count, siblingIds}`, `context {tokens, contextWindow, percent}`
+(context-window usage — a different frame from the client→server
+`context`), `coding_tools {active, pending}`, `tool_approvals
+{alwaysAllow}`, `ui_navigate {route}`, `ui_spotlight {ref?, label?,
+selector?, target?, message?, route?}`, `error {message}`.
+
+### App-aware assistant
+
+The web chat agent can see and act on the app it lives in. No screenshots
+and no vision model are involved: the browser sends a structured DOM
+snapshot as a WS frame, and the model gets three tools that
+read/navigate/highlight that snapshot. The three tools are always in the
+web chat's tool allowlist (read-only-on-the-machine, never gated by the
+approval card; `APP_AWARE_TOOL_NAMES` in `src/pi-web.ts`):
 
 - **`get_current_app_context`** — returns the last context the browser
   pushed: `{ route, view?, step?, snapshot }`. `snapshot` is a capped
   (~120) list of visible interactive elements as `{ref, label, kind,
   role?, selector, spotlightId?}`, agent chrome excluded.
 - **`navigate_app({ route | page })`** — validates against the route
-  catalog (`chat`, `quantize`, `finetune`, `dataset`, `status`; unknown
-  routes 400 as a tool error, never silently sent to the browser) and
-  emits a `ui_navigate` frame. Reversible; no approval needed.
-- **`spotlight_ui({ ref | label | selector | target, route?, message?
-  })`** — emits a `ui_spotlight` frame; the browser resolves the target
-  (ref from its last snapshot, then live selector, then fuzzy label
-  match, then a curated catalog id) and shows a brief highlight. Never
-  blocks: the overlay traps no focus and passes clicks straight through
-  to the highlighted control, auto-dismisses in ~3s, and any keystroke,
-  click, or scroll dismisses it instantly.
+  catalog (`APP_ROUTE_IDS`: `chat`, `quantize`, `finetune`, `dataset`,
+  `status`; unknown routes are a tool error, never sent to the browser)
+  and emits a `ui_navigate` frame.
+- **`spotlight_ui({ ref | label | selector | target, route?, message? })`**
+  — emits a `ui_spotlight` frame; the browser resolves the target (ref
+  from its last snapshot, then live selector, then fuzzy label match, then
+  a curated catalog id) and shows a brief non-blocking highlight.
 
 Client → server WS frame (pushed by the browser on every route change and
 every wizard-step change, never on a timer):
@@ -1214,10 +1672,8 @@ Server → client frames the two action tools produce:
 
 The server also auto-prepends a compact one-line ambient context (e.g.
 `[user is on: Quantize · step 2/4]`) to the system prompt on every turn —
-never a full snapshot dump — so the model is never answering completely
-blind even when it doesn't call a tool. `ui_act` (approval-gated form-fill
-and job-start actions) is explicitly out of scope for this v1; only
-navigate/spotlight are wired.
+never a full snapshot dump. Approval-gated form-fill / job-start actions
+are not wired; only navigate/spotlight are.
 
 ## Client setup: pi
 
@@ -1258,3 +1714,8 @@ solve.
 
 Any OpenAI SDK works the same way: `baseURL: "http://127.0.0.1:8080/v1"`,
 any non-empty `apiKey`.
+
+Under `--isolate`, the parent owns Responses continuation history and exposes its
+bounded store counters in `GET /engine` as `response_store`. Model-worker restart
+or eviction preserves that history; restarting the parent clears it. Direct
+serving retains the same process-local TTL and byte limits.