mlx-bun 0.2.0 → 0.4.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
+                                 // an explicit operator limit is reached;
+                                 // --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,17 +358,73 @@ 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
-through the serial lane (mlx_lm.server parity: `is_batchable = draft is
-None`) — speculation and `--batch N` are different modes.
+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.
+In the unreleased shared executor, Qwen grouped MTP, prompt lookup and standalone drafting support logprobs and
+bf16, uniform KV4/KV8 or per-layer affine KV, or TurboQuant. Qwen MTP and prompt lookup also support
+positive library conversion thresholds for uniform KV4/KV8. Per-layer mixed KV and
+adapters remain incompatible with speculation. Strict legacy serial execution
+retains its narrower bf16/KV4 policy. The KV4 compatibility control is
+`MLX_BUN_QWEN_SPEC_KV4=0`.
+Ineligible requests decode normally and omit the field. Qwen MTP reuses paired
+target/draft prefill and completed decode state through the shared RAM/SSD cache by default in the
+unreleased source, reported in `cached_tokens`. Configured SSD persistence
+supports reuse after restart; `MLX_BUN_MTP_PROMPT_CACHE=0` disables reuse.
+Generated checkpoints cover processed tokens and use queued SSD persistence.
+Long-conversation performance acceptance remains open. Qwen prompt lookup also
+retains prefill and completed-output state in the common RAM/SSD cache, with
+its committed token history stored as a companion attachment. Standalone drafting
+on Qwen targets stores the draft model’s attention/recurrent state and pending
+last draft token as companion state, including restoration after restart. Qualified Qwen
+MTP, prompt lookup and standalone drafting use shared execution at one or several active rows and
+report `usage.lane: "batched"`. Supported full-attention and rotating targets, including
+Llama, MiniCPM and Gemma, use shared bf16, uniform KV4/KV8 or per-layer affine KV or TurboQuant lookup and standalone drafting, with
+logprobs and generated RAM/SSD checkpoints. Delayed and per-layer affine rotating speculation uses the same row lifecycle; positive conversion thresholds are a library setting, while served schemes default to zero. Gemma assistant drafting also shares execution with bf16, uniform KV4/KV8 or per-layer affine KV or TurboQuant target storage and stores its
+last true target hidden alongside generated RAM/SSD prefixes. Donor attention
+handles row validity independently of the draft graph. DeepSpec and DSpark also use these shared target layouts and the common RAM/SSD cache
+for projected context, with independent confidence-based proposal lengths.
+Other provider/target combinations still
+use the serial executor.
+Prompt-lookup concurrent performance acceptance remains open. Ineligible requests can use continuous ordinary execution
+when their features support it, even while a draft is mounted.
+
+`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).
+
+An explicit `seed` controls a request-local random stream and can use
+continuous execution. Repeating a request reproduces sampling at the same
+model arithmetic and batch composition. Different batch shapes can change
+floating-point results even with identical random draws; `--batch 1` retains
+the existing fixed-shape control. This differs from mlx-lm's policy of routing
+explicit seeds to its single-request generator.
 
 ### logprobs / top_logprobs
 
@@ -271,44 +454,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 can use ordinary continuous execution under
+`--batch N`; other feature exclusions still apply. 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 +537,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 +563,46 @@ 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
 
+Memory estimates do not reject or shorten requests by default. Actual runtime
+failures use the request/stream error path when recoverable; native Metal
+allocation failure can terminate the process. Saved 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 an explicitly configured context/budget limit (`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. This is opt-in via an operator budget/context cap
+  (or the fixed GLM-5.2 layout), never enforced from default fit estimates.
+  `/stats.admission.enforced_context_tokens` is null when no cap applies.
+- `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 +614,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
+                                 // an explicit operator limit (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 +644,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 +658,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 +764,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 +829,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 +865,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:
@@ -607,8 +876,9 @@ vision/audio, adapters, and training are not emulated by the serving port.
                  "pending_spill_bytes": 0, "dropped_spills": 0,
                  "failed_spills": 0, "longest_durable_prefix_tokens": 0 },
   "admission": {
-    "max_safe_context": 0,            // tokens; requests above this 400
-    "memory_budget_bytes": null,      // explicit budget, or null (machine default)
+    "max_safe_context": 0,            // advisory fit estimate, tokens
+    "enforced_context_tokens": null,  // explicit cap or fixed layout; null = none
+    "memory_budget_bytes": null,      // explicit budget, or null
     "usable_bytes": 0,
     "weights_bytes": 0
   },
@@ -626,18 +896,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 +920,126 @@ 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,          // estimated context capacity
+  "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`. Requests selecting the same ordered adapter
+set can share a continuous group. Different sets wait for the current group
+to finish and then use the same executor. Prefix-cache identity is resolved
+under the execution lease, so replacing an adapter while a request is queued
+cannot reuse state from its previous weights.
+
+- `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 +1060,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 +1098,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 +1339,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 +1366,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 +1390,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 +1399,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 +1490,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 +1503,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 +1563,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 +1575,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 +1704,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 +1746,30 @@ 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.
+
+
+Supported grouped TurboQuant drafting retains `usage.speculation`, seeded
+sampling, logprobs, structured output and generated RAM/SSD continuations.
+The cache codec does not select the scheduler or sampler implementation.
+Composition coverage: [batching design](../design/batching.md).
+
+With paged KV enabled, supported Gemma4 bf16 text requests report the batched lane when submitted through continuous scheduling. Seeded sampling, logprobs and grammar use the same interfaces. These requests bypass prompt-cache lookup/publication; paging does not provide SSD persistence.
+
+Ordinary adapter checkpoints are isolated by ordered adapter IDs and mounted
+content revisions. Base-model requests cannot restore or remove an adapter checkpoint.
+With generation checkpointing enabled, repeating an identical eligible request
+replays its saved completion prefix and resumes from the saved pending token.
+Cancellation retains queued snapshots; successful completion removes them.
+`POST /admin/cache/flush` drains both prompt spills and generation checkpoints,
+and its elapsed time and durability statistics include both queues. A hard
+process exit can lose snapshots that have not drained.
+
+For resumed generation checkpoints, `usage.prompt_tokens_details.cached_tokens`
+counts only the reused original prompt, bounded by `usage.prompt_tokens`. Saved
+completion tokens are replayed as completion output and do not increase that
+prompt-cache usage counter.