mlx-bun 0.0.8 → 0.0.10

package/src/cli.ts

@@ -4,11 +4,13 @@
 //   mlx-bun get <org/repo> [--revision main]   resumable verified download
 //   mlx-bun scan                          index the HF cache
 //   mlx-bun ls [--vision] [--max-size 10GB] [query]
-//   mlx-bun fit <query> [--ctx 32768] [--skus]
-//   mlx-bun serve [query] [--port 8090] [--memory-budget GB]
+//   mlx-bun fit <query> [--ctx 8192] [--skus]
+//   mlx-bun serve [query] [--port 8080] [--memory-budget GB]
 //   mlx-bun evals                         recent benchmark runs
 //   mlx-bun harness pi [--base-url <url>] [--remove]   connect your own pi to the local server
 
+import { existsSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
 import { Registry } from "./registry";
 import { loadModelConfig } from "./config";
 import { fit, skuMatrix, thisMachine } from "./fit";
@@ -37,12 +39,20 @@ Commands:
   serve      Start the OpenAI/Anthropic-compatible server + status page
   get        Download a model from Hugging Face (resumable, verified)
   ls         List downloaded models
+  gc         Reclaim superseded model snapshots + dead blobs from the HF cache
   fit        Will a model fit this machine? Memory + speed assessment
   scan       Re-index the Hugging Face cache
   harness    Connect your own pi install to the local mlx-bun server
   train      Fine-tune a LoRA adapter (SFT / DPO / ORPO) on your data
+  train-watch Live dashboard for a training run (tails metrics.jsonl)
+  fuse       Merge a LoRA adapter into the base weights (standalone model)
+  convert    Quantize an HF model into a local MLX snapshot
+  upload     Push a local model directory to the Hugging Face Hub
+  perplexity Perplexity of a model over a local text/JSONL dataset
   memory     Set up + manage your local AI's personal wiki memory
+  generate   One-shot raw text generation from a local model (no server)
   benchmark  Measure decode/prefill speed of OUR stack on this machine
+  embed      Text embeddings from a local embedding model (Qwen3-Embedding)
   evals      Show recent benchmark runs (all stacks)
   help       Show help for a command (also: mlx-bun <command> --help)
 
@@ -53,27 +63,48 @@ Options:
 Examples:
   mlx-bun                          # download (first run) + serve + open the chat UI
   mlx-bun pi                       # start (download if needed) and chat with an agent
-  mlx-bun serve 12B                # serve the 12B; status page at http://localhost:8090/
+  mlx-bun serve 12B                # serve the 12B; status page at http://localhost:8080/
   mlx-bun train e4b --data ./prefs # ORPO LoRA fine-tune on {prompt,chosen,rejected} data
   mlx-bun get mlx-community/gemma-4-12B-it-OptiQ-4bit`;
 
 const SERVER_FLAGS = `Server options:
-  --host <addr>             Interface to bind  [default: all interfaces;
-                            use 127.0.0.1 for loopback-only]
-  --port <n>                Listen port  [default: 8090]
+  --model <path|query>      Explicit model override (mlx_lm.server spelling):
+                            a directory containing config.json loads from that
+                            path; anything else resolves like the positional
+                            query. Wins over the positional and auto-pick.
+  --host <addr>             Interface to bind  [default: 127.0.0.1, loopback
+                            only; use 0.0.0.0 to expose on your network]
+  --port <n>                Listen port  [default: 8080]
   --memory-budget <GB>      Admission-control memory budget; requests that
                             cannot fit are rejected instead of crashing the
                             GPU  [default: machine RAM × 0.75, check-only]
-  --prompt-cache <GB>       Prompt (KV) cache byte cap  [default: 2 GB]
+  --prompt-cache <GB>       Prompt (KV) cache byte cap  [default: 2 GB;
+                            --prompt-cache 0 disables the cache]
+  --ssd-cache <dir>         SSD cold tier for the prompt cache: prefix KV
+                            spills to disk on eviction and persists across
+                            restarts (long-context agent TTFT drops from a
+                            full re-prefill to a zero-copy mmap restore).
+                            Off unless set.
+  --ssd-cache-max <GB>      SSD tier byte cap  [default: 32 GB]
+  --ssd-cache-verify        Verify tensor hashes on every restore (reads all
+                            bytes eagerly — integrity paranoia only)
   --batch <n>               Max concurrent requests batched through the
                             mlx-lm-parity engine  [default: 1 = serial].
                             >1 opts the whole server into bf16 continuous
                             batching (= mlx-lm B=N); see --kv-quant.
+                            --decode-concurrency is accepted as the
+                            mlx_lm.server alias (semantics differ; see
+                            docs/reference/server-config.md)
   --no-open                 Don't open the chat UI in your browser on start.
                             By default an interactive terminal opens
                             http://<host>:<port>/#/chat once the server is up.
 
 Model & quality:
+  --adapter <dir>           Mount a LoRA adapter at startup and use it as the
+                            default for requests that don't select one (a
+                            request's \`adapter\` field, incl. "none", wins).
+                            --adapter-path is accepted as the mlx_lm.server
+                            alias. Hot-swap via POST /v1/adapters unchanged.
   --kv-quant <mode>         KV cache quantization: config (per-layer
                             kv_config.json when the model ships one), off
                             (bf16), or 4 / 8 (uniform bits)
@@ -86,8 +117,14 @@ Model & quality:
                             [default: the model's own, false for CPM]
   --temperature <n>         Server-wide sampling defaults; a per-request field
   --top-p <n>               still overrides them, and the browser chat (which
-  --top-k <n>               sends none) inherits them
+  --top-k <n>               sends none) inherits them. --temp is accepted as
+                            an alias for --temperature (mlx_lm.server compat;
+                            NOTE mlx_lm.server defaults temperature to 0.0 —
+                            pass --temp 0 for its unset-request behavior)
                             [default: the model's generation_config.json]
+  --max-tokens <n>          Completion cap when a request omits max_tokens
+                            (mlx_lm.server flag; its default is 512 there)
+                            [default: 65536 chat / 512 raw completion]
   --hlg-sampling on|off     Piecewise tone-curve sampling (HLG): rolls off the
                             top, boosts the mids, gentles the tail. Gain folds
                             from --temperature. [default: off]
@@ -97,10 +134,21 @@ Model & quality:
   --hlg-toe <nats>          HLG shadow rolloff scale  [default: 6]
   --hlg-pivot-offset <nats> HLG pivot: nats below the top token  [default: 6]
 
+Parity tier (sets the whole decode route; a per-fork flag below overrides):
+  --l1                      Bit-for-bit IDENTICAL to mlx-lm (bf16 KV, unfused)
+  --l2                      Bit-for-bit IDENTICAL to mlx-optiq (quantized KV +
+                            fused prefill SDPA, stock unfused decode — the
+                            optiq-golden composition; perf-kernel stays OFF)
+  --l3                      Best performance, no bit-exact oracle (KL + test
+                            gated; adds the envelope-gated perf kernel).
+                            No tier given = the per-flag defaults below,
+                            which equal --l3 today.
+
 Performance levers (A/B levers; defaults are the measured winners):
   --compiled-decode on|off  Compiled decode graphs  [default: on]
-  --perf-kernel on|off      Fused quantized-KV decode-SDPA Metal kernel
-                            (perf side of the compat A/B)  [default: on]
+  --perf-kernel on|off      Fused quantized-KV decode-SDPA Metal kernel —
+                            NOT bit-exact, envelope-gated (an L3 lever; the
+                            perf side of the compat A/B)  [default: on]
   --fused-decode on|off     Fused-decode experiment lever  [default: off]
   --fused-sdpa on|off       Fused SDPA path  [default: on]
   --force-wire              Wire weights into memory at load
@@ -141,42 +189,73 @@ Already use pi? Connect your own pi to this local model instead:
 Usage: mlx-bun serve [query] [options]
 
   [query]              Registry query (e.g. "12B", "e4b", a repo substring).
-                       Omitted: serves e4b (the default), else the largest
-                       downloaded model that fits. Fresh install: downloads a
-                       small starter model first, then e4b in the background
+                       --query <q> is accepted for the positional. Omitted:
+                       serves e4b (the default), else the largest downloaded
+                       model that fits. Fresh install: downloads a small
+                       starter model first, then e4b in the background
                        (default on next run).
 
 ${SERVER_FLAGS}
 
-Endpoints: /v1/chat/completions, /v1/messages, /v1/responses, /v1/models,
-/v1/adapters, /stats, /fit, /library, /downloads — status page at /,
-browser chat at /chat`,
+Endpoints: /v1/chat/completions, /v1/completions, /v1/messages, /v1/responses,
+/v1/models, /v1/adapters, /health, /stats, /fit, /library, /downloads —
+status page at /, browser chat at /chat`,
 
   get: `mlx-bun get — download a model from Hugging Face
 
-Usage: mlx-bun get <org/repo> [options]
+Usage: mlx-bun get <org/repo | substring> [options]
+
+  <org/repo>           Full repo id (e.g. mlx-community/gemma-4-12B-it-OptiQ-4bit)
+  <substring>          No "/" = a registry query over already-downloaded repos
+                       (e.g. \`mlx-bun get 12B\` re-gets/refreshes the match)
 
 Options:
   --revision <rev>     Git revision  [default: main]
 
 Resumable (Range requests against partial blobs) and verified (sha256
 for LFS blobs). Re-running after an interruption continues where it
-stopped. Uses HF_TOKEN / hf auth login credentials when present.`,
+stopped. Uses HF_TOKEN / hf auth login credentials when present.
+When upstream pushed a new revision, the previous snapshot stays on
+disk — \`mlx-bun gc\` reclaims it.`,
 
   ls: `mlx-bun ls — list downloaded models
 
 Usage: mlx-bun ls [query] [options]
 
+One row per repo (the canonical revision: refs/main). The HF cache keeps
+a snapshot dir per downloaded revision — superseded ones are hidden here
+and reclaimed by \`mlx-bun gc\`.
+
+Options:
+  --vision             Only vision-capable models (SigLIP sidecar or the
+                       unified encoder-free tower)
+  --max-size <size>    Filter by weight size (e.g. 10GB, 800MB)
+  --all-revisions      One row per cached snapshot (canonical marked *)`,
+
+  gc: `mlx-bun gc — reclaim superseded snapshots + dead blobs
+
+Usage: mlx-bun gc [options]
+
+Every \`get\` that follows an upstream push creates a NEW
+snapshots/<commit> dir; the old one (and any blobs only it references)
+stays on disk forever. gc keeps the snapshots refs/* point at, deletes
+the rest, then deletes blobs no surviving snapshot links to.
+
+Without --yes it only prints what would be deleted (per-repo reclaim).
+
 Options:
-  --vision             Only models with a vision sidecar
-  --max-size <size>    Filter by weight size (e.g. 10GB, 800MB)`,
+  --yes                Actually delete (destructive; default prints only)
+  --dry-run            Print the plan and never delete, even with --yes
+  --force              Also prune superseded snapshots that contain files
+                       the canonical revision lacks (normally skipped with
+                       a warning — deleting them loses the only copy)`,
 
   fit: `mlx-bun fit — will this model fit on this machine?
 
 Usage: mlx-bun fit <query> [options]
 
 Options:
-  --ctx <tokens>       Context size to assess  [default: 32768]
+  --ctx <tokens>       Context size to assess  [default: 8192]
   --skus               Also print the Apple silicon SKU matrix
 
 Solves weights + KV growth + prefill transient against wired memory and
@@ -199,7 +278,7 @@ local model. (To just chat now with no setup, use \`mlx-bun pi\` — the
 built-in agent.)
 
 Options:
-  --base-url <url>     Server base URL  [default: http://localhost:8090/v1]
+  --base-url <url>     Server base URL  [default: http://127.0.0.1:8080/v1]
   --remove             Disconnect (delete the extension)
 
 Installs a small discovery extension into ~/.pi/agent/extensions that
@@ -216,9 +295,13 @@ result to the eval DB. For quotable, cross-stack numbers use
 ./benchmark.sh from the repo — it preflight-gates on an idle machine
 and runs the mlx-lm/optiq comparison legs.
 
-  [query]              Model to benchmark  [default: auto-pick]
+  [query]              Model to benchmark (--query <q> is accepted for the
+                       positional)  [default: auto-pick]
 
 Options:
+  --model <path|query> Explicit model override: a directory containing
+                       config.json loads from that path; anything else
+                       resolves like the positional query. Wins over both.
   --tokens <n>         Tokens to decode per run  [default: 256]
   --runs <n>           Runs (median reported)  [default: 3]
   --prompt-tokens <n>  Pad the prompt to ~n tokens (long-context decode)
@@ -228,6 +311,61 @@ Options:
 Performance levers (--compiled-decode, --perf-kernel, --fused-decode,
 --fused-sdpa) apply to the run — A/B by running twice.`,
 
+  embed: `mlx-bun embed — text embeddings from a local embedding model
+
+Usage: mlx-bun embed [query] --text "…" [options]
+       mlx-bun embed [query] "…"        (text as a positional)
+       echo -e "line one\\nline two" | mlx-bun embed [query]
+
+Embeds text with a local Qwen3-Embedding model (last-token pooled,
+L2-normalized — bit-exact vs mlx-lm). One text per --text, or one per
+line on stdin. Prints one JSON array (the vector) per input line.
+
+  [query]              Embedding model (--query <q> is accepted for the
+                       positional)  [default: the first downloaded
+                       embedding model; errors with an mlx-bun get
+                       suggestion when none is downloaded]
+
+Options:
+  --text "…"           Text to embed (omit to read lines from stdin)
+  --instruct "…"       Query instruction (Qwen3-Embedding query format);
+                       steers WHICH similarity axis the geometry reflects.
+                       Omit for plain document embeddings.
+  --json               Emit one OpenAI-style {object:"list",data:[…]} object
+                       instead of bare vector arrays
+
+For a server endpoint use \`mlx-bun serve <embedding-model>\` then
+POST /v1/embeddings.`,
+
+  generate: `mlx-bun generate — one-shot raw text generation (no server)
+
+Usage: mlx-bun generate [query] --prompt "…" [options]
+       mlx-bun generate [query] "…"          (prompt as a positional)
+
+A direct one-shot entry point: load the model, generate, print, exit —
+no server, no chat UI. By default the prompt is rendered through the
+model's chat template; --raw feeds it verbatim.
+
+  [query]              Model (registry query; --query is accepted for the
+                       positional)  [default: auto-pick]
+
+Options:
+  --prompt "…"         The prompt (or pass it as the positional)
+  --raw                Skip the chat template (verbatim prompt)
+  --max-tokens <n>     Completion cap  [default: 256]
+  --temperature <n>    Sampling temperature (--temp is accepted as an alias)
+  --top-p <n>          Nucleus sampling
+  --top-k <n>          Top-k sampling
+  --seed <n>           Sampler seed (reproducible runs)
+
+Decode-path levers mirror serve: --l1/--l2/--l3 and the per-fork flags
+(--perf-kernel/--fused-sdpa/--compiled-decode/--fused-decode/--kv-quant).
+The tier's KV scheme applies here too (--l2/--l3 = the model's kv_config,
+same tokens as serve); with no tier/--kv-quant the KV cache stays bf16
+(the bit-exact mlx-lm greedy path). mlx-lm compat = --l1.
+
+Aliases: mlx-bun gen`,
+
   evals: `mlx-bun evals — recent benchmark runs
 
 Usage: mlx-bun evals [options]
@@ -261,7 +399,15 @@ Options:
   --scale <f>          LoRA scale  [default: orpo 2.0 · else 1.0]
   --seq <n>            Max sequence length  [default: gemma 8192 · else 4096]
   --batch <n>          Batch size  [default: 1]
+  --grad-accum <n>     Gradient accumulation steps (effective batch =
+                       batch × grad-accum at batch-size-1 memory)  [default: 1]
+  --grad-clip <f>      Gradient-norm clip (0 = off)  [default: 1.0]
+  --seed <n>           Data-shuffle / init seed  [default: 0]
+  --val-size <n>       Max validation examples per eval  [default: 256]
   --lambda <f>         ORPO odds-ratio weight  [default: 0.1]
+  --sft-scope <s>      ORPO chosen-NLL scope: full (paper/TRL-faithful,
+                       prompt+response) | response (pre-2026-07 runs,
+                       bit-exact)  [default: full]
   --seg <n>            Layers per segment (segmented backward; orpo default 2)
   --save-every <n>     Crash-safe mountable checkpoint every n steps
   --resume <dir>       Warm-start LoRA weights from a checkpoint/adapter dir
@@ -274,7 +420,125 @@ ORPO defaults run the full stack: the [M,vocab]-free flash-CCE head +
 prefix-sharing + segmented backward (each falls back + logs if a row's
 preconditions aren't met). Gemma/e4b sets its required training env flags
 automatically. Adapters are mountable directly (mlx-bun serve --adapter).
-Run long jobs detached from your own shell:  nohup mlx-bun train … &`,
+Run long jobs detached from your own shell:  nohup mlx-bun train … &
+Watch a run live from another tab:  mlx-bun train-watch <adapter-dir>`,
+
+  "train-watch": `mlx-bun train-watch — live dashboard for a training run
+
+Usage: mlx-bun train-watch [adapter-dir]
+
+Tails <adapter-dir>/metrics.jsonl (written by mlx-bun train and the web
+fine-tune tile) and renders a live loss/speed/memory dashboard. Point it
+at the same --adapter directory the training run uses.
+
+  [adapter-dir]        Adapter directory to watch; --adapter <dir> is
+                       accepted for the positional
+                       [default: ~/.cache/mlx-bun/mlx-bun-finetunes/orpo-cpm5]`,
+  fuse: `mlx-bun fuse — merge a LoRA adapter into the base weights
+
+Usage: mlx-bun fuse <model-query-or-path> --adapter <dir> [options]
+
+Folds the adapter's low-rank deltas into the base weights and writes a
+standalone, loadable model snapshot (weights + config + tokenizer). A
+quantized base keeps its exact quantization layout: fused modules are
+dequantized, updated, and re-quantized with their own per-module spec.
+
+  <model>              Base model (registry query or a snapshot path);
+                       --model is accepted as the mlx_lm.fuse spelling
+
+Options:
+  --adapter <dir>      Adapter directory (adapters.safetensors +
+                       adapter_config.json). --adapter-path is accepted
+                       as the mlx_lm.fuse alias  [default: adapters]
+  --save-path <dir>    Output model directory  [default: fused_model]
+
+Not supported (mlx_lm.fuse flags we don't implement — the command exits
+with an error rather than guessing): --de-quantize, --export-gguf,
+--gguf-path, --upload-repo.
+
+Serve the result:  mlx-bun serve <save-path>`,
+
+  convert: `mlx-bun convert — quantize an HF model into a local MLX snapshot
+
+Usage: mlx-bun convert --hf-path <repo-or-path> -q [options]
+       mlx-bun convert <repo-or-path> -q [options]   (positional source)
+
+Wraps mlx-bun's native quantize pipeline (the same engine as the web
+/api/quantize). The source may be a local model directory, a downloaded
+model (registry query), or a Hugging Face repo id — an un-downloaded
+repo is fetched first (resumable, verified; can be many GB).
+
+Options:
+  --hf-path <src>      Source model: local path, downloaded model, or HF
+                       repo id (--model and the bare positional are
+                       accepted as aliases)
+  --mlx-path <dir>     Output directory  [default: mlx_model; must not
+                       already exist, matching mlx_lm.convert]
+  -q, --quantize       Quantize the model (uniform affine)
+  --q-bits <n>         Bits per weight: 4 or 8  [default: 4]
+  --q-group-size <n>   Quantization group size: 32 or 64  [default: 64]
+  --upload-repo <id>   Push the converted model to this Hugging Face repo
+                       after converting (mlx_lm.convert parity; same engine
+                       as \`mlx-bun upload\`, needs a write token)
+
+Mixed precision (the mlx-bun differentiator — OptiQ sensitivity sweep +
+knapsack per-layer bit allocation; implies quantization, no -q needed):
+  --target-bpw <f>     Target bits-per-weight (e.g. 4.5). Runs
+                       calibration → per-layer KL sensitivity → greedy
+                       knapsack; writes per-module bits into config.json
+  --candidate-bits <l> Comma list the knapsack may pick from [default: 4,8]
+  --calibration-mix <m> "optiq" or a JSONL path  [default: optiq]
+  --n-calibration <n>  Calibration samples  [default: 2]
+
+Not supported (mlx_lm.convert flags we don't implement — the command
+exits with an error rather than guessing): --dtype, -d/--dequantize,
+--q-mode other than affine, and the mlx-lm --quant-predicate recipes
+(use --target-bpw instead). Plain non-quantizing conversion is also not
+supported: pass -q or --target-bpw.`,
+
+  upload: `mlx-bun upload — push a local model directory to the Hugging Face Hub
+
+Usage: mlx-bun upload --path <model-dir> --upload-repo <org/repo> [options]
+
+Native push-to-hub, no Python (src/hf-push.ts — the same engine as the
+web UI's push buttons): creates the repo if needed (idempotent), uploads
+weights via the git-LFS batch protocol, and commits. Flag names match
+mlx_lm.upload.
+
+Options:
+  --path <dir>         Local model directory to upload  [default: mlx_model]
+  --upload-repo <id>   Hub repo id, org/name or bare name  (required)
+  --private            Create the repo as private (mlx-bun extension)
+
+Auth: needs a Hugging Face WRITE token, resolved from ~/.mlx-bun/hf.json
+(web UI Settings → Hugging Face), $HF_TOKEN, or ~/.cache/huggingface/token
+(hf auth login). Errors before uploading anything if none is found.
+
+Convert + push in one step:  mlx-bun convert … --upload-repo <org/repo>`,
+
+  perplexity: `mlx-bun perplexity — perplexity over a local text/JSONL dataset
+
+Usage: mlx-bun perplexity <model-query-or-path> --data-path <file> [options]
+
+mlx_lm.perplexity methodology, exactly: samples are visited in a seeded
+random order, tokenized, concatenated, and cut into NON-OVERLAPPING rows
+of --sequence-length tokens; per batch the model scores rows[:, :-1]
+against rows[:, 1:] in f32 (every position counts); reported as
+ppl = exp(mean CE) ± the delta-method standard error. The one deliberate
+difference: the data source is a LOCAL file (never a Hugging Face
+dataset download).
+
+  <model>              Model (registry query or snapshot path);
+                       --model (mlx_lm spelling) and --query are accepted
+                       for the positional
+
+Options:
+  --data-path <file>   .jsonl ({"text": …} rows) or plain .txt  (required)
+  --sequence-length <n> Tokens per row  [default: 512]
+  --num-samples <n>    Rows to score (-1 = all available)  [default: 256]
+  --batch-size <n>     Rows per forward  [default: 8]
+  --seed <n>           Sample-shuffle seed  [default: 123]`,
+
   memory: `mlx-bun memory — your local AI's personal wiki
 
 Usage: mlx-bun memory <subcommand>
@@ -301,8 +565,16 @@ Subcommands:
                      Print one article section
   links <article>    Show resolved outbound + inbound wikilinks
   read <article>     Print an article (stem, e.g. Archie_Project)
-  synthesize         Run the synthesis pipeline now (--since, --model,
-                     --dry-run). STUBBED — a no-op until M1 lands.
+  synthesize         Run the FULL synthesis DAG now (--since, --model,
+                     --dry-run); also: pipeline, all
+  segment | extract | route | synthesize-stage
+                     Run ONE decomposed stage worker (--limit N —
+                     segment/extract/synthesize-stage only; --convs a,b).
+                     Each pulls its eligible work from the DB by state, walks
+                     oldest-conversation-first, persists, and exits — resumable,
+                     and runnable as separate concurrent processes on slices.
+  link               Deterministic cross-linking stage: inline-link first
+                     mentions + rebuild ## See also (--limit N; no model)
   schedule           Install the nightly launchd job (--at HH:MM [03:00])
   unschedule         Remove the nightly launchd job
 
@@ -310,12 +582,13 @@ The read path is live: the assistant reads a wiki you set up by hand or
 import during \`memory init\`. Ask the assistant to "open my memory" or run
 \`mlx-bun memory open\` to browse it in Obsidian/Finder, or
 \`mlx-bun memory open <article>\` to jump to a specific page. Synthesis
-(conversations → articles) is stubbed; scheduling is real, so the nightly
-job is wired and ready and starts producing articles the moment synthesis
-lands.`,
+(conversations → articles) runs the full local pipeline via
+\`mlx-bun memory synthesize\` (or per-stage: segment/extract/route/
+synthesize-stage/link); the nightly job runs it on a schedule.`,
 };
 
 HELP.bench = HELP.benchmark!;
+HELP.gen = HELP.generate!;
 HELP.setup = HELP.memory!;
 
 function printHelp(topic?: string): never {
@@ -454,11 +727,16 @@ function openChatUi(url: string, hostPort: string): void {
  *  Each tier is a GUARANTEE about which reference you reproduce bit-for-bit:
  *    --l1  bit-for-bit IDENTICAL to mlx-lm    — drop-in replacement for mlx-lm
  *    --l2  bit-for-bit IDENTICAL to mlx-optiq — drop-in replacement for mlx-optiq.
- *          optiq SHIPS the fused quantized decode (the quant-KV goldens track
- *          perf-kernel ON), so L2 turns it ON — not the unfused reference.
+ *          The optiq-golden decode composition (scripts/regen-kvq-goldens.ts) is
+ *          fused N-tiled SDPA for L>1 + STOCK unfused L=1 decode, so L2 = fused-sdpa
+ *          ON, perf-kernel OFF. The perf kernel is an mlx-bun ORIGINAL Metal kernel,
+ *          envelope-gated (≥56/64 teacher-forced argmax vs OUR OWN frozen compat
+ *          trajectory, tests/perf-kernel-oracle.test.ts) — an L3 node, never the
+ *          bare-L2 default. (Commit f1bf5cc put it in L2 claiming the goldens track
+ *          it; they don't — reverted 2026-07-01 with the evidence above.)
  *    --l3  best performance, NO bit-exact guarantee — correct, but gated by KL +
  *          tests, because mlx-optiq has no analogy for what L3 does.
- *  L2 ⊂ L3 (L3 = L2 + compiled). L1 is a separate target (bf16, unfused). */
+ *  L2 ⊂ L3 (L3 = L2 + perf kernel). L1 is a separate target (bf16, unfused). */
 function applyDecodeRoute(): { kvQuant?: "off" | "config" | number } {
   const onOff = (name: string): boolean | null => {
     const v = opt(name); if (v == null) return null;
@@ -471,15 +749,18 @@ function applyDecodeRoute(): { kvQuant?: "off" | "config" | number } {
     // A tier is the GUARANTEE; within it we default to the FAST kernel that still
     // holds it, and expose the slow one as an opt-in. compiled-decode is BIT-EXACT
     // with uncompiled (compiled-decode.test: on==off) → free speed, so it's ON in
-    // EVERY tier (--compiled-decode off is the slow, same-tier opt-in). perf-kernel
-    // + fused-sdpa match OPTIQ (not the unfused reference; fused-sdpa.test) and are
-    // quantized-KV only → they're the L2 bridge, no-ops on L1's bf16. NOTE: for the
-    // DECODE path L2 == L3 — every decode kernel matches mlx-lm OR optiq. L3's real
-    // territory is the no-oracle FEATURES (HLG sampler, expert offload, batched
-    // mixed-precision) gated by KL+tests, which live off this decode axis.
+    // EVERY tier (--compiled-decode off is the slow, same-tier opt-in). fused-sdpa
+    // matches OPTIQ bit-for-bit (tier-a goldens, fused-sdpa.test) and is
+    // quantized-KV only → it's the L2 bridge, a no-op on L1's bf16. perf-kernel is
+    // NOT: it's an original flash-decoding kernel, envelope-gated against our own
+    // frozen trajectory (perf-kernel-oracle.test) — bare --l2 must ship the
+    // optiq-golden decode composition (stock unfused L=1), so perf-kernel is
+    // L3/explicit-only (--perf-kernel on opts a tier into it by choice). This is
+    // the decode-axis difference between L2 and L3; L3 also owns the no-oracle
+    // FEATURES (HLG sampler, expert offload, batched mixed-precision).
     l1: { kv: "off",    perf: false, fusedSdpa: false, compiled: true, fusedDecode: false }, // = mlx-lm bit-for-bit (bf16)
-    l2: { kv: "config", perf: true,  fusedSdpa: true,  compiled: true, fusedDecode: false }, // = mlx-optiq bit-for-bit
-    l3: { kv: "config", perf: true,  fusedSdpa: true,  compiled: true, fusedDecode: false }, // best perf (decode == L2 today)
+    l2: { kv: "config", perf: false, fusedSdpa: true,  compiled: true, fusedDecode: false }, // = mlx-optiq bit-for-bit
+    l3: { kv: "config", perf: true,  fusedSdpa: true,  compiled: true, fusedDecode: false }, // best perf (envelope-gated decode)
   };
   const tier = flag("l1") ? "l1" : flag("l2") ? "l2" : flag("l3") ? "l3" : null;
   const p = tier ? TIERS[tier]! : null;
@@ -521,9 +802,20 @@ function serverRuntimeFlags(): { port: number; serverOptions: import("./server")
   if (budgetGB > 0) serverOptions.memoryBudgetBytes = budgetGB * 1e9;
   const pcRaw = opt("prompt-cache"); // null if absent; an explicit value (incl. 0) wins → `--prompt-cache 0` DISABLES the cache
   if (pcRaw !== null) serverOptions.promptCacheBytes = Math.max(0, Number(pcRaw)) * 2 ** 30;
+  // SSD cold tier (docs/design/ssd-kv-cold-tier.md) — off unless a dir is given.
+  const ssdDir = opt("ssd-cache");
+  if (ssdDir !== null) {
+    serverOptions.ssdCacheDir = ssdDir;
+    const maxRaw = opt("ssd-cache-max");
+    if (maxRaw !== null) serverOptions.ssdCacheMaxBytes = Math.max(1, Number(maxRaw)) * 2 ** 30;
+    if (flag("ssd-cache-verify")) serverOptions.ssdCacheVerify = true;
+  }
   // --batch N: max concurrent requests batched through the mlx-lm-parity
-  // engine (N=1 = today's serial path). --decode-concurrency is accepted as
-  // an mlx_lm.server-compatible alias (drop-in).
+  // engine (N=1 = today's serial path). --decode-concurrency is accepted for
+  // drop-in compatibility with mlx_lm.server, but the semantics differ: there
+  // it caps per-BatchGenerator decode parallelism (default 32); in mlx-bun it
+  // enables continuous batching with this cap (the default is the optimized
+  // serial path).
   const batchRaw = opt("batch") ?? opt("decode-concurrency");
   if (batchRaw !== null) {
     const n = Number(batchRaw);
@@ -534,8 +826,11 @@ function serverRuntimeFlags(): { port: number; serverOptions: import("./server")
     serverOptions.batch = n;
   }
   if (route.kvQuant !== undefined) serverOptions.kvQuant = route.kvQuant;
-  const host = opt("host");
-  if (host) serverOptions.hostname = host;
+  // Bind loopback unless asked otherwise (mlx_lm.server parity); --host
+  // 0.0.0.0 is the explicit opt-in for LAN exposure. The chat-UI open and
+  // `mlx-bun pi` attach both go through localhost, so loopback-only is
+  // transparent to them.
+  serverOptions.hostname = opt("host", "127.0.0.1")!;
   // Server-wide default for the chat template's enable_thinking variable
   // (CPM/MiniCPM5 and other hybrid-reasoning models). Unset ⇒ the model's
   // own default (false for MiniCPM5). onOff accepts true|false|on|off|1|0.
@@ -554,12 +849,18 @@ function serverRuntimeFlags(): { port: number; serverOptions: import("./server")
     }
     return n;
   };
-  const temp = numFlag("temperature", 0, 5);
+  // --temp is the mlx_lm.server spelling; explicit --temperature wins.
+  const temp = numFlag("temperature", 0, 5) ?? numFlag("temp", 0, 5);
   if (temp !== null) serverOptions.defaultTemperature = temp;
   const topP = numFlag("top-p", 0, 1);
   if (topP !== null) serverOptions.defaultTopP = topP;
   const topK = numFlag("top-k", 0, 1_000_000);
   if (topK !== null) serverOptions.defaultTopK = topK;
+  // mlx_lm.server's --max-tokens: the completion cap when a request omits
+  // max_tokens. Our built-in default stays 65,536 (chat) / 512 (raw text
+  // completion); `--max-tokens 512` reproduces mlx-lm's behavior exactly.
+  const maxTok = numFlag("max-tokens", 1, 10_000_000);
+  if (maxTok !== null) serverOptions.defaultMaxTokens = Math.floor(maxTok);
   // HLG sampling — piecewise tone curve on the logprobs (default off). Knobs in
   // nats; the mid gain folds from --temperature. docs/design/hlg-sampling.md.
   if (onOff("hlg-sampling") === true) {
@@ -572,7 +873,33 @@ function serverRuntimeFlags(): { port: number; serverOptions: import("./server")
       pivot: "top",
     };
   }
-  return { port: Number(opt("port", "8090")), serverOptions };
+  return { port: Number(opt("port", "8080")), serverOptions };
+}
+
+/** `--adapter <dir>` (alias `--adapter-path`, mlx_lm.server's spelling):
+ *  mount a LoRA adapter at startup — the same machinery as POST /v1/adapters —
+ *  and make it the default for requests that don't select one (a request's
+ *  explicit `adapter`, including "none", still wins; hot-swap unchanged).
+ *  This is the flag `mlx-bun train`'s completion message points at. Shared by
+ *  `serve` and the `pi` session server. Exits on a bad adapter — better a
+ *  loud startup failure than silently serving the base model. */
+async function mountStartupAdapter(
+  ctx: import("./server").ServerContext,
+  serverOptions: import("./server").ServerOptions,
+): Promise<void> {
+  const adapterDir = opt("adapter") ?? opt("adapter-path");
+  if (!adapterDir) return;
+  const { step, style } = await import("./tui");
+  const sAdp = step("mounting adapter");
+  try {
+    const adapterId = adapterDir.replace(/\/+$/, "").split("/").pop()!;
+    const info = await ctx.adapters.mount(adapterId, adapterDir);
+    serverOptions.defaultAdapter = info.id;
+    sAdp.done(`adapter ${style.bold(info.id)} ${style.dim(`· ${info.mountedLayers} layers · default for requests (select others via \`adapter\`)`)}`);
+  } catch (e) {
+    sAdp.fail(`adapter mount failed: ${(e as Error).message}`);
+    process.exit(1);
+  }
 }
 
 /** One-line summary of the active runtime levers for the ready card. */
@@ -591,8 +918,21 @@ function runtimeSummary(o: import("./server").ServerOptions): string {
 
 /** Shared model resolution: explicit query wins; otherwise e4b (the default
  *  model everywhere) if it's downloaded, else the largest supported model that
- *  fits this machine. Downloads the recommended model first on a fresh install. */
+ *  fits this machine. Downloads the recommended model first on a fresh install.
+ *  A query that is a DIRECTORY containing config.json loads directly via
+ *  scanSnapshot (no registry dependency) — the `--model <path>` bench/CI shape. */
 async function resolveModelAuto(query: string | null): Promise<{ m: import("./registry").ModelRecord; picked: boolean }> {
+  if (query && existsSync(join(query, "config.json"))) {
+    const { scanSnapshot } = await import("./registry");
+    const dir = resolve(query);
+    // Recover the repo id from an HF-cache path (…/models--org--name/snapshots/<rev>);
+    // otherwise the directory basename is the display id.
+    const hf = /models--([^/]+)--([^/]+)\/snapshots\//.exec(dir);
+    const repoId = hf ? `${hf[1]}/${hf[2]}` : basename(dir);
+    const m = await scanSnapshot(dir, repoId);
+    if (!m) throw new Error(`${dir} has config.json but no weights (*.safetensors)`);
+    return { m, picked: false };
+  }
   const reg = new Registry();
   if (reg.list().length === 0) await reg.scan();
   if (query) return { m: reg.resolve(query), picked: false };
@@ -664,13 +1004,33 @@ function parseSize(s: string): number {
 
 switch (cmd) {
   case "get": {
-    const repoId = positional(0);
-    if (!repoId || !repoId.includes("/")) {
-      console.error("usage: mlx-bun get <org/repo> [--revision main]");
+    let repoId = positional(0);
+    if (!repoId) {
+      console.error("usage: mlx-bun get <org/repo | substring> [--revision main]");
       process.exit(1);
     }
+    if (!repoId.includes("/")) {
+      // No org/name — treat it as a registry query over already-downloaded
+      // repos (re-get/refresh, e.g. `mlx-bun get 12B` after an upstream push).
+      try {
+        const regQ = new Registry();
+        if (regQ.list().length === 0) await regQ.scan();
+        repoId = regQ.resolve(repoId).repoId;
+      } catch (e) {
+        console.error((e as Error).message);
+        console.error(`usage: mlx-bun get <org/repo> [--revision main] — or a substring of a downloaded repo (try \`mlx-bun ls ${repoId}\`)`);
+        process.exit(1);
+      }
+    }
     const { downloadModel } = await import("./download");
     const { step, style } = await import("./tui");
+    const { join: joinPath, basename } = await import("node:path");
+    const { readdirSync, existsSync } = await import("node:fs");
+    const { DEFAULT_HUB, planRepoGc } = await import("./registry");
+    const repoDir = joinPath(DEFAULT_HUB, `models--${repoId.replaceAll("/", "--")}`);
+    const priorSnapshots = existsSync(joinPath(repoDir, "snapshots"))
+      ? readdirSync(joinPath(repoDir, "snapshots"))
+      : [];
     const s = step(`downloading ${repoId}`);
     const snap = await downloadModel(repoId, {
       revision: opt("revision", "main")!,
@@ -684,6 +1044,18 @@ switch (cmd) {
     const reg = new Registry();
     await reg.scan();
     sScan.done(`registry updated ${style.dim(`· ${snap}`)}`);
+    // Upstream pushed a new revision → this get created a NEW snapshots/<sha>
+    // dir; the old one stays on disk (that's how ~25 GB of dead blobs pile
+    // up). Say so, with what `gc` would get back.
+    if (priorSnapshots.length > 0 && !priorSnapshots.includes(basename(snap))) {
+      const plan = planRepoGc(repoDir);
+      const note = plan.skippedSnapshots.length > 0
+        ? " (a previous snapshot has files this revision lacks — gc will warn; --force to prune it)"
+        : "";
+      console.log(style.dim(
+        `  previous revision kept on disk — \`mlx-bun gc\` reclaims ~${gb(plan.reclaimBytes)}${note}`,
+      ));
+    }
     break;
   }
 
@@ -700,43 +1072,125 @@ switch (cmd) {
     const reg = new Registry();
     if ((reg.list().length ?? 0) === 0) await reg.scan();
     const maxSize = opt("max-size");
-    const models = reg.list({
+    const allRevisions = flag("all-revisions");
+    const lsFilter = {
       vision: flag("vision") ? true : undefined,
       maxBytes: maxSize ? parseSize(maxSize) : undefined,
       query: positional(0),
-    });
+    };
+    // One row per repo by default: the HF cache keeps a snapshots/<commit>
+    // dir per downloaded revision, and re-getting after an upstream push
+    // strands the old one — those are duplicates, not separate models.
+    // --all-revisions shows the per-snapshot truth (canonical marked *).
+    const models = allRevisions ? reg.list(lsFilter) : reg.listCanonical(lsFilter);
     if (models.length === 0) {
       console.log("no models match (try `mlx-bun scan`)");
       break;
     }
+    const { visionCapable } = await import("./registry");
+    const { supportTier } = await import("./model/support");
+    const canonicalPaths = new Set(reg.listCanonical(lsFilter).map((m) => m.path));
+    const capabilities = (m: (typeof models)[number]) => {
+      const tier = supportTier(m.modelType, m.repoId);
+      return [
+        tier ? `supported (${tier})` : `unsupported (${m.modelType})`,
+        visionCapable(m) ? "vision" : null,
+        m.hasToolTemplate ? "tools" : null,
+        m.hasKvConfig ? "kv-quant" : null,
+      ].filter(Boolean).join(" · ");
+    };
     const { table, style, h1 } = await import("./tui");
     h1("library");
     console.log();
     table(
       [
         { header: "model", paint: (c) => style.bold(c) },
-        { header: "size", align: "right" },
-        { header: "params", align: "right" },
+        ...(allRevisions ? [{ header: "revision" }] : []),
+        { header: "size", align: "right" as const },
+        { header: "params", align: "right" as const },
         { header: "quant" },
-        { header: "license", paint: (c) => style.dim(c) },
-        { header: "capabilities", paint: (c) => style.dim(c) },
+        { header: "license", paint: (c: string) => style.dim(c) },
+        { header: "capabilities", paint: (c: string) => style.dim(c) },
       ],
       models.map((m) => [
         m.repoId,
+        ...(allRevisions
+          ? [`${(m.path.split("/snapshots/")[1] ?? "").slice(0, 12)}${canonicalPaths.has(m.path) ? " *" : ""}`]
+          : []),
         gb(m.sizeBytes),
         m.paramCount ? `${(m.paramCount / 1e9).toFixed(1)}B` : "?",
         m.quantBits ? `${m.quantBits}-bit g${m.quantGroupSize}` : "full",
         m.license ?? "?",
-        [
-          isSupportedModelRecord(m.modelType, m.repoId) ? "supported" : `unsupported (${m.modelType})`,
-          m.hasVisionSidecar ? "vision" : null,
-          m.hasToolTemplate ? "tools" : null,
-          m.hasKvConfig ? "kv-quant" : null,
-        ].filter(Boolean).join(" · "),
+        capabilities(m),
       ]),
     );
     console.log();
-    console.log(style.dim(`  ${models.length} model(s) · mlx-bun fit <query> for a memory assessment`));
+    if (allRevisions) {
+      console.log(style.dim(
+        `  ${models.length} snapshot(s) · * = canonical (refs/main) · superseded snapshots: \`mlx-bun gc\``,
+      ));
+    } else {
+      console.log(style.dim(`  ${models.length} model(s) · mlx-bun fit <query> for a memory assessment`));
+    }
+    break;
+  }
+
+  case "gc": {
+    const { planGc, executeGc, DEFAULT_HUB } = await import("./registry");
+    const { table, style, h1 } = await import("./tui");
+    const force = flag("force");
+    const plans = planGc(DEFAULT_HUB, { force }).filter(
+      (p) => p.pruneSnapshots.length || p.skippedSnapshots.length || p.deadBlobs.length,
+    );
+    h1("gc — superseded snapshots + dead blobs");
+    console.log();
+    if (plans.length === 0) {
+      console.log("  nothing to reclaim — every snapshot is referenced by refs/*");
+      break;
+    }
+    table(
+      [
+        { header: "repo", paint: (c) => style.bold(c) },
+        { header: "keep", align: "right" },
+        { header: "prune", align: "right" },
+        { header: "skip", align: "right" },
+        { header: "reclaims", align: "right" },
+      ],
+      plans.map((p) => [
+        p.repoId,
+        String(p.keepSnapshots.length),
+        String(p.pruneSnapshots.length),
+        String(p.skippedSnapshots.length),
+        gb(p.reclaimBytes),
+      ]),
+    );
+    console.log();
+    for (const p of plans) {
+      for (const s of p.skippedSnapshots) {
+        const rev = (s.path.split("/snapshots/")[1] ?? s.path).slice(0, 12);
+        console.log(style.accent(
+          `  WARNING ${p.repoId}@${rev}: superseded snapshot has files the canonical revision lacks — skipped.`,
+        ));
+        console.log(style.dim(`    only copy of: ${s.extraFiles.join(", ")}`));
+        console.log(style.dim("    deleting it loses those files — rerun with --force if that's intended."));
+      }
+    }
+    const totalReclaim = plans.reduce((a, p) => a + p.reclaimBytes, 0);
+    const totalSnaps = plans.reduce((a, p) => a + p.pruneSnapshots.length, 0);
+    const totalBlobs = plans.reduce((a, p) => a + p.deadBlobs.length, 0);
+    console.log(
+      `  total: ${totalSnaps} snapshot(s), ${totalBlobs} blob(s), ${style.bold(gb(totalReclaim))}`,
+    );
+    if (flag("dry-run") || !flag("yes")) {
+      console.log(style.dim("  nothing deleted — rerun with --yes to delete (destructive)."));
+      break;
+    }
+    const res = executeGc(plans);
+    console.log(
+      `  deleted ${res.snapshots} snapshot(s) + ${res.blobs} blob(s) — reclaimed ${style.bold(gb(res.reclaimedBytes))}`,
+    );
+    const reg = new Registry();
+    await reg.scan(); // reap deleted snapshots from the registry
     break;
   }
 
@@ -804,7 +1258,12 @@ switch (cmd) {
         process.exit(1);
       }
     }
-    const { m, picked } = await resolveModelAuto(positional(0) ?? opt("query"));
+    // --model <path-or-query> is the explicit override (mlx_lm.server's
+    // spelling — previously accepted-but-IGNORED here, which silently
+    // auto-picked the wrong model). A directory with config.json loads
+    // straight from that path; anything else resolves like the positional
+    // fuzzy query. Precedence: --model > positional > --query > auto-pick.
+    const { m, picked } = await resolveModelAuto(opt("model") ?? positional(0) ?? opt("query"));
     const sFit = step("assessing fit");
     const config = await loadModelConfig(m.path);
     const report = fit(config, m.sizeBytes, 8192, undefined, undefined, m.expertsBytes);
@@ -829,8 +1288,9 @@ switch (cmd) {
     const sLoad = step("loading weights");
     const t0 = performance.now();
     const ctx = await loadContext(m.path, m.repoId, { memoryBudgetBytes: rt.serverOptions.memoryBudgetBytes });
-    const server = createServer(ctx, rt.port, { ...rt.serverOptions, owner: "serve" });
     sLoad.done(`weights loaded ${style.dim(`in ${(performance.now() - t0).toFixed(0)} ms`)}`);
+    await mountStartupAdapter(ctx, rt.serverOptions);
+    const server = createServer(ctx, rt.port, { ...rt.serverOptions, owner: "serve" });
     const shownHost = rt.serverOptions.hostname ?? "localhost";
     console.log();
     box([
@@ -860,35 +1320,115 @@ switch (cmd) {
     // RAW generate — a direct one-shot entry point (no server, no chat UI). The
     // three entry points (raw / OpenAI API / chat UI) differ only in how params
     // are POPULATED; here every param is explicit. Decode-path levers mirror
-    // serve so you can pin the route (mlx-lm compat = --perf-kernel off
-    // --fused-sdpa off --compiled-decode off). KV uses the bf16 bit-exact path.
-    applyDecodeRoute(); // --l1/--l2/--l3 + per-fork overrides set the decode env levers (KV stays bf16 via generateText)
+    // serve so you can pin the route (mlx-lm compat = --l1).
+    // --l1/--l2/--l3 + per-fork overrides set the decode env levers; the
+    // returned KV scheme is applied below so `generate --l2` runs the same
+    // quantized-KV route (and produces the same tokens) as `serve --l2`.
+    const route = applyDecodeRoute();
 
     const prompt = opt("prompt") ?? positional(1);
     if (!prompt) {
       console.error('usage: mlx-bun generate [query] --prompt "…" [--raw] [--max-tokens N]');
-      console.error('       sampling:  --temperature N --top-p N --top-k N --seed N');
-      console.error('       decode path: --perf-kernel off --fused-sdpa off --compiled-decode off  (= mlx-lm compat)');
+      console.error('       sampling:  --temperature N (alias --temp) --top-p N --top-k N --seed N');
+      console.error('       decode path: --l1 (= mlx-lm compat) / --l2 / --l3, or per-fork flags');
       process.exit(1);
     }
     const { loadTaskModel, generateText } = await import("./eval/runner");
     const tm = await loadTaskModel(positional(0) ?? opt("query") ?? "");
+    // Resolve the tier/--kv-quant KV scheme exactly the way serve does
+    // (server.ts kvScheme): "config" = the model's kv_config.json (absent →
+    // bf16, same silent fallback as serve), N = uniform bits from decode
+    // start. Unset (no tier, no --kv-quant) keeps generate's historical
+    // default: bf16 bit-exact greedy (generateText's parity path).
+    const kvScheme =
+      route.kvQuant === "off" ? {}
+      : route.kvQuant === "config"
+        ? (tm.config.kvQuant?.length ? { kvConfig: tm.config.kvQuant } : {})
+      : typeof route.kvQuant === "number"
+        ? { kvBits: route.kvQuant, quantizedKvStart: 0 }
+      : undefined;
     const num = (n: string): number | undefined => { const v = opt(n); return v == null ? undefined : Number(v); };
     const text = await generateText(tm, prompt, {
       maxTokens: Number(opt("max-tokens", "256")),
       useChat: !flag("raw"),
-      sampler: { temperature: num("temperature"), topP: num("top-p"), topK: num("top-k"), seed: num("seed") },
+      ...(kvScheme !== undefined ? { kvScheme } : {}),
+      sampler: { temperature: num("temperature") ?? num("temp"), topP: num("top-p"), topK: num("top-k"), seed: num("seed") },
     });
     process.stdout.write(text.endsWith("\n") ? text : text + "\n");
     break;
   }
 
+  case "embed": {
+    // Raw text embeddings — one-shot, no server. Text from --text, or one per
+    // line on stdin. Uses the same embedPooled path the parity test verifies.
+    const { Weights } = await import("./weights");
+    const { createModel } = await import("./model/factory");
+    const { loadTokenizer } = await import("./tokenizer");
+    const { embedMany, isEmbeddingModel } = await import("./embed");
+
+    let texts: string[];
+    const oneText = opt("text") ?? positional(1);
+    if (oneText != null) {
+      texts = [oneText];
+    } else if (!process.stdin.isTTY) {
+      texts = (await Bun.stdin.text()).split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    } else {
+      texts = [];
+    }
+    if (texts.length === 0) {
+      console.error('usage: mlx-bun embed [query] --text "…"   (or pipe text, one per line)');
+      console.error('       --instruct "…"  query instruction · --json  OpenAI-style output');
+      process.exit(1);
+    }
+
+    // Model resolution: an explicit query resolves normally; the no-query
+    // path auto-picks the first DOWNLOADED embedding model (plain Qwen3 —
+    // the record-level equivalent of isEmbeddingModel, which the factory
+    // maps to Qwen3Model). Never the chat default, and never the fresh-
+    // install starter download — a chat model can't embed, so downloading
+    // one here only to fail the isEmbeddingModel check would be a trap.
+    const embedQuery = positional(0) ?? opt("query");
+    let m: import("./registry").ModelRecord;
+    if (embedQuery) {
+      ({ m } = await resolveModelAuto(embedQuery));
+    } else {
+      const reg = new Registry();
+      if (reg.list().length === 0) await reg.scan();
+      const embedder = reg.list().find((r) => r.modelType === "qwen3");
+      if (!embedder) {
+        console.error("no embedding model downloaded — try: mlx-bun get mlx-community/Qwen3-Embedding-4B-4bit-DWQ");
+        process.exit(1);
+      }
+      m = embedder;
+    }
+    const config = await loadModelConfig(m.path);
+    const model = createModel(await Weights.open(m.path), config);
+    if (!isEmbeddingModel(model)) {
+      console.error(`"${m.repoId}" is not an embedding model (need plain Qwen3, e.g. Qwen3-Embedding).`);
+      process.exit(1);
+    }
+    const tok = await loadTokenizer(m.path);
+    const results = embedMany(model, tok, texts, opt("instruct") ?? undefined);
+
+    if (flag("json")) {
+      let total = 0;
+      const data = results.map((r, index) => { total += r.tokens; return { object: "embedding", index, embedding: Array.from(r.vector) }; });
+      process.stdout.write(JSON.stringify({
+        object: "list", data, model: m.repoId,
+        usage: { prompt_tokens: total, total_tokens: total },
+      }) + "\n");
+    } else {
+      for (const r of results) process.stdout.write(JSON.stringify(Array.from(r.vector)) + "\n");
+    }
+    break;
+  }
+
   case "bench":
   case "benchmark": {
     const { banner, step, box, style } = await import("./tui");
     banner(pkg.version);
     serverRuntimeFlags(); // env levers (--compiled-decode, --perf-kernel, ...) apply to the run
-    const { m, picked } = await resolveModelAuto(positional(0) ?? opt("query"));
+    const { m, picked } = await resolveModelAuto(opt("model") ?? positional(0) ?? opt("query"));
     const tokens = Number(opt("tokens", "256"));
     const runs = Number(opt("runs", "3"));
     const promptTokens = Number(opt("prompt-tokens", "0"));
@@ -1076,11 +1616,14 @@ switch (cmd) {
     // (src/pi-terminal.ts) — pi is bundled, nothing to install. Users who
     // already run their own pi connect it with `mlx-bun harness pi`.
     const OURS_VAL = new Set([
-      "--query", "-q", "--port", "--host", "--memory-budget", "--prompt-cache", "--kv-quant",
+      "--query", "-q", "--model", "--port", "--host", "--memory-budget", "--prompt-cache",
+      "--ssd-cache", "--ssd-cache-max", "--kv-quant",
+      "--batch", "--decode-concurrency", "--adapter", "--adapter-path",
       "--compiled-decode", "--perf-kernel", "--fused-decode", "--fused-sdpa", "--thinking",
-      "--temperature", "--top-p", "--top-k",
+      "--temperature", "--temp", "--top-p", "--top-k", "--max-tokens",
+      "--hlg-sampling", "--hlg-width", "--hlg-shoulder", "--hlg-toe", "--hlg-pivot-offset",
     ]);
-    const OURS_BOOL = new Set(["--force-wire", "--expert-offload"]);
+    const OURS_BOOL = new Set(["--force-wire", "--expert-offload", "--no-open", "--ssd-cache-verify", "--l1", "--l2", "--l3"]);
     const passthrough: string[] = [];
     for (let i = 1; i < argv.length; i++) {
       const a = argv[i]!;
@@ -1108,7 +1651,7 @@ switch (cmd) {
 
     const rt = serverRuntimeFlags();
     const port = rt.port;
-    const baseUrl = `http://localhost:${port}/v1`;
+    const baseUrl = `http://127.0.0.1:${port}/v1`;
     const { probeServer } = await import("./harness-pi");
     let models = await probeServer(baseUrl);
     let startedServer = false;
@@ -1123,7 +1666,7 @@ switch (cmd) {
         console.log(style.dim("  (stop it or use --port <other> to start a fresh server with these flags)"));
       }
       try {
-        const stats = await (await fetch(`http://localhost:${port}/stats`)).json() as
+        const stats = await (await fetch(`http://127.0.0.1:${port}/stats`)).json() as
           { server?: { owner?: string } };
         if (stats.server?.owner === "pi-session") {
           console.log("note: that server belongs to another `mlx-bun pi` session and ends when it does —");
@@ -1143,6 +1686,7 @@ switch (cmd) {
       const sLoad = step(`loading ${m.repoId}`);
       const t0 = performance.now();
       const ctx = await loadContext(m.path, m.repoId, { memoryBudgetBytes: rt.serverOptions.memoryBudgetBytes });
+      await mountStartupAdapter(ctx, rt.serverOptions);
       createServer(ctx, port, { ...rt.serverOptions, owner: "pi-session" });
       startedServer = true;
       sLoad.done(`serving ${style.bold(m.repoId)} ${style.dim(`at ${baseUrl} · ready in ${(performance.now() - t0).toFixed(0)} ms`)}`);
@@ -1167,11 +1711,17 @@ switch (cmd) {
     if (parsed.mode === "interactive")
       console.log(`launching mlx-bun pi (model ${models[0]!.id}) — /help for commands, double-Ctrl+C to exit`);
     restoreStdout();
+    if (parsed.ignored.length) {
+      const { style } = await import("./tui");
+      console.log(style.dim(`  ignoring pi flags: ${parsed.ignored.join(", ")}`));
+    }
     const code = await runEmbeddedPi({
       baseUrl,
       modelLabel: models[0]!.id,
       contextWindow: models[0]!.contextWindow,
       reasoning: models[0]!.reasoning,
+      vision: models[0]!.vision,
+      verbose: parsed.verbose,
       mode: parsed.mode,
       printFormat: parsed.printFormat,
       initialMessage: message,
@@ -1238,6 +1788,15 @@ switch (cmd) {
       process.exit(1);
     }
     const isOrpo = method === "orpo";
+    // ORPO chosen-NLL scope (trainer sftScope; job.ts sft_scope). "full" =
+    // paper/TRL-faithful prompt+response CE (the default); "response" =
+    // response-only, bit-exact to pre-2026-07 runs. Validated here so junk
+    // fails fast, before any model resolution or weight loading.
+    const sftScope = opt("sft-scope");
+    if (sftScope !== null && sftScope !== "full" && sftScope !== "response") {
+      console.error(`--sft-scope must be full | response (got "${sftScope}")`);
+      process.exit(1);
+    }
     // Validated numeric flag: default if absent, hard-exit on a non-number.
     const numFlag = (name: string, dflt: number): number => {
       const v = opt(name);
@@ -1297,6 +1856,7 @@ switch (cmd) {
       grad_clip_norm: numFlag("grad-clip", 1.0),
       val_max_examples: numFlag("val-size", 256),
       warm_start_adapter: resume,
+      ...(sftScope ? { sft_scope: sftScope } : {}),
       ...(isOrpo ? {
         orpo_lambda: numFlag("lambda", 0.1),
         orpo_lr_schedule: "cosine",
@@ -1387,6 +1947,368 @@ switch (cmd) {
     break;
   }
 
+  case "fuse": {
+    // mlx_lm.fuse counterpart over our native machinery (src/train/fuse.ts):
+    // fold a LoRA adapter into the base weights → standalone snapshot.
+    const unsupported = ["--de-quantize", "--dequantize", "--export-gguf", "--gguf-path", "--upload-repo"]
+      .filter((f) => argv.includes(f));
+    if (unsupported.length > 0) {
+      console.error(`${unsupported.join(", ")}: not supported (see: mlx-bun help fuse)`);
+      process.exit(1);
+    }
+    const modelArg = positional(0) ?? opt("model");
+    if (!modelArg) {
+      console.error("usage: mlx-bun fuse <model-query-or-path> --adapter <dir> [--save-path <dir>]");
+      process.exit(1);
+    }
+    const adapterDir = opt("adapter") ?? opt("adapter-path") ?? "adapters";
+    const savePath = opt("save-path") ?? "fused_model";
+    const { existsSync } = await import("node:fs");
+    if (!existsSync(adapterDir)) {
+      console.error(`adapter dir not found: ${adapterDir}`);
+      process.exit(1);
+    }
+    let modelDir = modelArg;
+    if (!existsSync(`${modelArg}/config.json`)) {
+      const reg = new Registry();
+      if (reg.list().length === 0) await reg.scan();
+      modelDir = reg.resolve(modelArg).path;
+    }
+    const { banner, step, box, style } = await import("./tui");
+    banner(pkg.version);
+    const sNative = step("native runtime");
+    await ensureNative(sNative);
+    sNative.done("native runtime ready");
+    const s = step(`fusing ${adapterDir} into ${modelDir}`);
+    const { fuseAdapter } = await import("./train");
+    try {
+      const stats = await fuseAdapter(modelDir, adapterDir, savePath, (e) => s.update(e.message));
+      s.done(`fused ${stats.fusedModules} module(s) ${style.dim(`· ${stats.totalTensors} tensors written`)}`);
+      console.log();
+      box([
+        `${style.green("●")} ${style.bold("fuse complete")}`,
+        "",
+        `base      ${style.dim(modelDir)}`,
+        `adapter   ${style.dim(adapterDir)}`,
+        `model     ${style.bold(stats.outDir)}`,
+        ...(stats.skippedAdapterTensors > 0
+          ? [`skipped   ${style.dim(`${stats.skippedAdapterTensors} adapter tensor(s) with no matching base weight`)}`] : []),
+        "",
+        `serve it   ${style.accent(`mlx-bun serve ${stats.outDir}`)}`,
+      ]);
+    } catch (e) {
+      s.fail(`fuse failed: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case "convert": {
+    // mlx_lm.convert counterpart over our native quantize pipeline (the same
+    // engine as the web /api/quantize): uniform affine 4/8-bit, or the OptiQ
+    // mixed-precision path via --target-bpw.
+    // --upload-repo (mlx_lm.convert parity): push the converted model to the
+    // Hub afterwards, via the same engine as `mlx-bun upload`. The token is
+    // resolved BEFORE any conversion work — failing after minutes of
+    // quantizing because auth is missing would be cruel.
+    const uploadRepo = ((): string | null => {
+      if (!argv.includes("--upload-repo")) return null;
+      const v = opt("upload-repo");
+      if (!v || v.startsWith("-")) {
+        console.error("--upload-repo expects a repo id (org/name)");
+        process.exit(1);
+      }
+      return v;
+    })();
+    let uploadToken: string | null = null;
+    if (uploadRepo) {
+      const { getHfToken } = await import("./hf-push");
+      uploadToken = getHfToken();
+      if (!uploadToken) {
+        console.error("--upload-repo needs a Hugging Face WRITE token and none was found —");
+        console.error("run `hf auth login`, export HF_TOKEN, or save one in the web UI (Settings → Hugging Face).");
+        process.exit(1);
+      }
+    }
+    const unsupported = ["--dtype", "-d", "--dequantize", "--quant-predicate"]
+      .filter((f) => argv.includes(f));
+    if (unsupported.length > 0) {
+      console.error(`${unsupported.join(", ")}: not supported (mixed precision: --target-bpw; see: mlx-bun help convert)`);
+      process.exit(1);
+    }
+    const qMode = opt("q-mode", "affine")!;
+    if (qMode !== "affine") {
+      console.error(`--q-mode ${qMode}: only "affine" is supported`);
+      process.exit(1);
+    }
+    const hfPath = opt("hf-path") ?? opt("model") ?? positional(0);
+    if (!hfPath) {
+      console.error("usage: mlx-bun convert --hf-path <repo-or-path> -q [--q-bits N] [--q-group-size N] [--mlx-path <dir>] [--target-bpw F]");
+      process.exit(1);
+    }
+    const targetBpwRaw = opt("target-bpw");
+    if (!argv.includes("-q") && !argv.includes("--quantize") && targetBpwRaw === null) {
+      console.error("plain (non-quantizing) conversion is not supported yet — pass -q or --target-bpw");
+      process.exit(1);
+    }
+    const targetBpw = targetBpwRaw !== null ? Number(targetBpwRaw) : undefined;
+    if (targetBpwRaw !== null && (!Number.isFinite(targetBpw!) || targetBpw! <= 0)) {
+      console.error(`--target-bpw expects a positive number (got "${targetBpwRaw}")`);
+      process.exit(1);
+    }
+    const qBits = Number(opt("q-bits", "4"));
+    if (qBits !== 4 && qBits !== 8) {
+      console.error(`--q-bits must be 4 or 8 (got "${opt("q-bits")}")`);
+      process.exit(1);
+    }
+    const qGroup = Number(opt("q-group-size", "64"));
+    if (qGroup !== 32 && qGroup !== 64) {
+      console.error(`--q-group-size must be 32 or 64 (got "${opt("q-group-size")}")`);
+      process.exit(1);
+    }
+    const candidateBits = opt("candidate-bits")?.split(",").map((s) => Number(s.trim()));
+    if (candidateBits && candidateBits.some((b) => !Number.isInteger(b) || b < 2 || b > 8)) {
+      console.error(`--candidate-bits expects a comma list of integers in [2, 8] (got "${opt("candidate-bits")}")`);
+      process.exit(1);
+    }
+    const mlxPath = opt("mlx-path", "mlx_model")!;
+    const { existsSync } = await import("node:fs");
+    if (existsSync(mlxPath)) {
+      console.error(`Cannot save to the path ${mlxPath} as it already exists — delete it or pass a fresh --mlx-path.`);
+      process.exit(1);
+    }
+    const { banner, step, box, style } = await import("./tui");
+    banner(pkg.version);
+    const sNative = step("native runtime");
+    await ensureNative(sNative);
+    sNative.done("native runtime ready");
+    // Resolve the source: local dir → itself; downloaded model → registry;
+    // otherwise an HF repo id, downloaded first (the point of the verb).
+    let srcDir = hfPath;
+    if (!existsSync(`${hfPath}/config.json`)) {
+      const reg = new Registry();
+      if (reg.list().length === 0) await reg.scan();
+      try {
+        srcDir = reg.resolve(hfPath).path;
+      } catch (e) {
+        if (!/^[\w.-]+\/[\w.-]+$/.test(hfPath)) {
+          console.error(e instanceof Error ? e.message : String(e));
+          process.exit(1);
+        }
+        const { downloadModel } = await import("./download");
+        const sDl = step(`downloading ${hfPath}`);
+        srcDir = await downloadModel(hfPath, {
+          onProgress: (file, received, total) => {
+            const pct = total ? Math.floor((received / total) * 100) : 0;
+            sDl.update(`${style.bold(hfPath)} ${style.dim(`· ${file} · ${gb(received)} / ${gb(total)} (${pct}%)`)}`);
+          },
+        });
+        sDl.done(`${style.bold(hfPath)} ${style.dim("downloaded · verified")}`);
+        await reg.scan();
+      }
+    }
+    const sQ = step(
+      targetBpw !== undefined
+        ? `quantizing (mixed, target ${targetBpw} bpw — sensitivity sweep, ~minutes)`
+        : `quantizing (${qBits}-bit, group ${qGroup})`,
+    );
+    const { quantizeModelDir } = await import("./quantize");
+    try {
+      const r = await quantizeModelDir(
+        srcDir,
+        mlxPath,
+        {
+          bits: qBits as 4 | 8,
+          groupSize: qGroup as 32 | 64,
+          mode: "affine",
+          ...(targetBpw !== undefined ? { targetBpw } : {}),
+          ...(candidateBits ? { candidateBits } : {}),
+          ...(opt("calibration-mix") ? { calibrationMix: opt("calibration-mix")! } : {}),
+          ...(opt("n-calibration") ? { nCalibration: Number(opt("n-calibration")) } : {}),
+        },
+        (e) => sQ.update(e.message),
+      );
+      sQ.done(`quantized ${r.nQuantized} module(s) ${style.dim(`· ${r.achievedBpw.toFixed(2)} bpw achieved`)}`);
+      console.log();
+      box([
+        `${style.green("●")} ${style.bold("convert complete")}`,
+        "",
+        `source    ${style.dim(srcDir)}`,
+        `model     ${style.bold(r.outDir)} ${style.dim(`· ${gb(r.write.totalSize)}`)}`,
+        `quant     ${style.dim(targetBpw !== undefined ? `mixed ${r.achievedBpw.toFixed(2)} bpw (target ${targetBpw})` : `${qBits}-bit g${qGroup} affine`)}`,
+        "",
+        `serve it   ${style.accent(`mlx-bun serve ${r.outDir}`)}`,
+      ]);
+      if (uploadRepo) {
+        const sUp = step(`uploading ${r.outDir} → ${uploadRepo}`);
+        try {
+          const { uploadFolder } = await import("./hf-push");
+          const up = await uploadFolder(r.outDir, uploadRepo, {
+            repoType: "model",
+            token: uploadToken,
+            commitMessage: "Upload with mlx-bun convert",
+            onProgress: (file, sent, total) =>
+              sUp.update(`${style.bold(uploadRepo)} ${style.dim(`· ${file} · ${gb(sent)} / ${gb(total)}`)}`),
+          });
+          sUp.done(`uploaded ${style.bold(up.url)}`);
+        } catch (e) {
+          sUp.fail(`upload failed: ${e instanceof Error ? e.message : String(e)}`);
+          console.error(`the converted model is intact at ${r.outDir} — retry with: mlx-bun upload --path ${r.outDir} --upload-repo ${uploadRepo}`);
+          process.exit(1);
+        }
+      }
+    } catch (e) {
+      sQ.fail(`convert failed: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case "upload": {
+    // mlx_lm.upload counterpart (same flag names: --path, --upload-repo) over
+    // our native push-to-hub (src/hf-push.ts — the exact engine the web
+    // /api/{quantize,finetune,dataset}/push routes call). Model-free until
+    // the network: everything before uploadFolder is arg + token validation.
+    const dir = opt("path", "mlx_model")!; // mlx_lm.upload's --path default
+    const repo = ((): string | null => {
+      const v = opt("upload-repo");
+      return v && !v.startsWith("-") ? v : null;
+    })();
+    if (!repo) {
+      console.error("usage: mlx-bun upload --path <model-dir> --upload-repo <org/repo> [--private]");
+      process.exit(1);
+    }
+    const { existsSync, statSync } = await import("node:fs");
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+      console.error(`not a directory: ${dir} (pass the model directory via --path)`);
+      process.exit(1);
+    }
+    const { getHfToken, uploadFolder } = await import("./hf-push");
+    const token = getHfToken();
+    if (!token) {
+      console.error("no Hugging Face token found — uploading needs a WRITE token from one of:");
+      console.error("  hf auth login                  (~/.cache/huggingface/token)");
+      console.error("  export HF_TOKEN=hf_…");
+      console.error("  web UI Settings → Hugging Face (~/.mlx-bun/hf.json)");
+      process.exit(1);
+    }
+    const { banner, step, box, style } = await import("./tui");
+    banner(pkg.version);
+    const s = step(`uploading ${dir} → ${repo}`);
+    try {
+      const r = await uploadFolder(dir, repo, {
+        repoType: "model",
+        private: flag("private"),
+        token,
+        commitMessage: "Upload with mlx-bun",
+        onProgress: (file, sent, total) =>
+          s.update(`${style.bold(repo)} ${style.dim(`· ${file} · ${gb(sent)} / ${gb(total)}`)}`),
+      });
+      s.done(`uploaded ${style.bold(repo)}`);
+      console.log();
+      box([
+        `${style.green("●")} ${style.bold("upload complete")}`,
+        "",
+        `source    ${style.dim(dir)}`,
+        `repo      ${style.url(r.url)}${flag("private") ? style.dim(" · private") : ""}`,
+        "",
+        `get it back anywhere:  ${style.accent(`mlx-bun get ${repo}`)}`,
+      ]);
+    } catch (e) {
+      s.fail(`upload failed: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case "perplexity": {
+    // mlx_lm.perplexity counterpart (methodology reproduced exactly — see
+    // src/eval/perplexity.ts) over a LOCAL dataset file; never downloads data.
+    const modelArg = positional(0) ?? opt("model") ?? opt("query");
+    const dataPath = opt("data-path");
+    if (!modelArg || !dataPath) {
+      console.error("usage: mlx-bun perplexity <model-query-or-path> --data-path <file.txt|file.jsonl> [--sequence-length 512] [--num-samples 256] [--batch-size 8] [--seed 123]");
+      process.exit(1);
+    }
+    const { existsSync } = await import("node:fs");
+    if (!existsSync(dataPath)) {
+      console.error(`data file not found: ${dataPath} (a local .txt or .jsonl — HF datasets are not downloaded)`);
+      process.exit(1);
+    }
+    const intFlag = (name: string, dflt: number, lo: number): number => {
+      const v = Number(opt(name, String(dflt)));
+      if (!Number.isInteger(v) || (v < lo && v !== -1)) {
+        console.error(`--${name} expects an integer >= ${lo} (got "${opt(name)}")`);
+        process.exit(1);
+      }
+      return v;
+    };
+    const seqLen = intFlag("sequence-length", 512, 2);
+    const numSamples = intFlag("num-samples", 256, 1); // -1 = all
+    const batchSize = intFlag("batch-size", 8, 1);
+    const seed = intFlag("seed", 123, 0);
+    const { banner, step, box, style } = await import("./tui");
+    banner(pkg.version);
+    const sNative = step("native runtime");
+    await ensureNative(sNative);
+    sNative.done("native runtime ready");
+    let modelDir = modelArg;
+    if (!existsSync(`${modelArg}/config.json`)) {
+      const reg = new Registry();
+      if (reg.list().length === 0) await reg.scan();
+      modelDir = reg.resolve(modelArg).path;
+    }
+    // Gemma/e4b: same forward env flags the trainer sets (full-sequence pass).
+    if ((await Bun.file(`${modelDir}/config.json`).text()).toLowerCase().includes("gemma")) {
+      process.env.MLX_BUN_PERF_KERNEL ??= "0";
+      process.env.MLX_BUN_FUSED_GELU ??= "0";
+    }
+    const sLoad = step(`loading ${modelDir}`);
+    const { Weights } = await import("./weights");
+    const { createModel } = await import("./model/factory");
+    const { loadTokenizer } = await import("./tokenizer");
+    const { peakMemory, resetPeakMemory } = await import("./mlx/ffi");
+    const config = await loadModelConfig(modelDir);
+    const model = createModel(await Weights.open(modelDir), config);
+    const tok = await loadTokenizer(modelDir);
+    sLoad.done(`model loaded ${style.dim(`· ${modelDir}`)}`);
+
+    const { parseSamples, packRows, evalPpl } = await import("./eval/perplexity");
+    const sData = step(`tokenizing ${dataPath}`);
+    const samples = parseSamples(await Bun.file(dataPath).text(), dataPath);
+    const rows = packRows(
+      samples.map((t) => tok.encode(t)),
+      { sequenceLength: seqLen, numSamples, seed },
+    );
+    if (rows.length === 0) {
+      sData.fail(`dataset too small: fewer than ${seqLen} tokens (need at least one full row)`);
+      process.exit(1);
+    }
+    sData.done(`${rows.length} row(s) × ${seqLen} tokens ${style.dim(`· ${samples.length} sample(s), seed ${seed}`)}`);
+
+    const sEval = step(`evaluating (batch ${batchSize})`);
+    resetPeakMemory();
+    const t0 = performance.now();
+    const r = evalPpl(model, rows, batchSize, (done, total) =>
+      sEval.update(`batch ${done}/${total}`));
+    const seconds = (performance.now() - t0) / 1000;
+    sEval.done(`evaluated ${r.tokens.toLocaleString()} tokens ${style.dim(`in ${seconds.toFixed(1)} s`)}`);
+    console.log();
+    box([
+      `${style.green("●")} ${style.bold("perplexity")} ${style.dim(`· ${modelDir.split("/snapshots/")[0]?.split("/").at(-1) ?? modelDir}`)}`,
+      "",
+      `ppl        ${style.green(style.bold(r.ppl.toFixed(3)))} ${style.dim(`± ${r.standardError.toFixed(3)}`)}`,
+      `mean CE    ${style.bold(r.meanLoss.toFixed(4))} ${style.dim("nats/token")}`,
+      `tokens     ${style.bold(r.tokens.toLocaleString())} ${style.dim(`· ${r.rows} row(s) × ${seqLen}`)}`,
+      `speed      ${style.dim(`${(r.tokens / seconds).toFixed(0)} tok/s · peak ${gb(peakMemory())}`)}`,
+    ]);
+    break;
+  }
+
+  // `setup` is a true alias for `memory` — same handler, same subcommands
+  // (`mlx-bun setup init` == `mlx-bun memory init`; the handler reads the
+  // subcommand from argv[1] onward, identical for both spellings).
+  case "setup":
   case "memory": {
     const { style, box, step, banner } = await import("./tui");
     const {
@@ -1475,13 +2397,14 @@ switch (cmd) {
       }
 
       // Offer to install the nightly synthesis job (a launchd agent). The job
-      // itself is a no-op today (synthesis is stubbed), but installing the
-      // schedule now means it starts producing articles the moment M1 lands —
-      // no reconfiguration. Persistent action → TTY-only, defaults to no.
+      // runs the real synthesis DAG (`mlx-bun memory synthesize`) — create new
+      // entity articles, then the editorial wikify sweep — so installing the
+      // schedule keeps your wiki current automatically. Persistent action →
+      // TTY-only, defaults to no.
       let scheduled: string | null = null;
       console.log(style.dim(
-        "\n  Synthesis (turning your conversations into articles) isn't implemented yet,\n" +
-        "  but you can install the nightly job now so it runs automatically once it is.",
+        "\n  Synthesis (turning your conversations into articles) runs as a nightly job;\n" +
+        "  install it now so your wiki stays current automatically.",
       ));
       if (await confirmYN("  Install the nightly synthesis job (runs in the background)?", false)) {
         const atRaw = await ask(`    At what time? 24h HH:MM ${style.dim("[03:00]")}: `, "03:00");
@@ -1507,8 +2430,8 @@ switch (cmd) {
           ? `nightly    ${style.green("scheduled")} ${style.dim(`· ${scheduled} daily · mlx-bun memory unschedule to undo`)}`
           : `nightly    ${style.dim("not scheduled · mlx-bun memory schedule to set it up")}`,
         "",
-        style.dim("Synthesis (conversations → articles) is stubbed for now; the scheduled"),
-        style.dim("job no-ops until it lands. Add or import articles to read meanwhile."),
+        style.dim("Synthesis (conversations → articles) runs the full DAG: create new entity"),
+        style.dim("articles, then an editorial wikify sweep. Run it now: mlx-bun memory synthesize."),
       ]);
       break;
     }
@@ -1528,8 +2451,7 @@ switch (cmd) {
         `articles   ${style.bold(String(st.articleCount))}`,
         `reference  ${style.bold(String(st.referenceCount))} ${style.dim("read-only docs")}`,
         `git        ${st.isGitRepo ? style.green("tracked") : style.dim("not a git repo")}`,
-        `synthesis  ${style.dim("stubbed (M1) — not implemented yet")}`,
-        `last run   ${style.dim("not available yet")}`,
+        `synthesis  ${style.green("available")} ${style.dim("· mlx-bun memory synthesize")}`,
         `nightly    ${
           sched.installed
             ? `${sched.loaded ? style.green("scheduled") : style.accent("installed (not loaded)")} ${style.dim(`· ${sched.plistPath}`)}`
@@ -1570,7 +2492,70 @@ switch (cmd) {
       break;
     }
 
-    if (sub === "synthesize") {
+    // Independent, chronological, resumable STAGE WORKERS. Each pulls its own
+    // eligible work from the DB by state, processes a bounded batch, persists,
+    // and exits — so a user can run the four as four separate processes on
+    // different slices concurrently (GPU/memory allowing). `synthesize` (below)
+    // remains the FULL DAG; these are its decomposed pieces.
+    if (sub === "segment" || sub === "extract" || sub === "route" || sub === "synthesize-stage" || sub === "stage-synthesize") {
+      const stages = await import("./memory/stages");
+      const { MemoryStore } = await import("./memory/db");
+      const limit = opt("limit") ? parseInt(opt("limit")!, 10) : undefined;
+      const convsRaw = opt("convs");
+      const convIds = convsRaw ? convsRaw.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+      const onEvent = (e: import("./memory/pipeline").SynthesisEvent) => {
+        if (e.type === "stage") console.log(`  ${style.dim("·")} ${e.message}`);
+        else console.log(`  ${e.message}`);
+      };
+      const store = new MemoryStore();
+      console.log();
+      try {
+        if (sub === "segment") {
+          const r = await stages.runSegmentStage(store, { convIds, limit, onEvent });
+          console.log(style.dim(`\n  segment: ${r.valid} segmented, ${r.chunks} chunks, ${r.skipped} skipped, ${r.errored} errored`));
+        } else if (sub === "extract") {
+          const r = await stages.runExtractStage(store, { convIds, limit, onEvent });
+          console.log(style.dim(`\n  extract: ${r.extracted} chunk(s) extracted, ${r.remaining} still pending`));
+        } else if (sub === "route") {
+          const r = await stages.runRouteStage(store, { convIds, onEvent });
+          console.log(style.dim(`\n  route: ${r.decisions.length} entities — ${r.createEligible} create-eligible, ${r.captured.length} captured`));
+        } else {
+          const r = await stages.runSynthesizeStage(store, { root, convIds, limit, onEvent });
+          console.log(style.dim(`\n  synthesize: ${r.created.length} created, ${r.patched.length} patched, ${r.skippedByGate.length} gated`));
+        }
+      } finally {
+        store.close();
+      }
+      break;
+    }
+
+    // CROSS-LINK — the dedicated edge-building stage. Deterministic + idempotent:
+    // inline-link first mentions of other articles + rebuild each ## See also from
+    // mentions + co-occurrence. No model required.
+    if (sub === "link") {
+      const { runLinkStage } = await import("./memory/crosslink");
+      const { MemoryStore } = await import("./memory/db");
+      const limit = opt("limit") ? parseInt(opt("limit")!, 10) : undefined;
+      const store = new MemoryStore();
+      console.log();
+      try {
+        const r = await runLinkStage(store, {
+          root,
+          limit,
+          onEvent: (e) => console.log(e.type === "stage" ? `  ${style.dim("·")} ${e.message}` : `  ${e.message}`),
+        });
+        console.log(
+          style.dim(
+            `\n  link: ${r.linked.length} article(s) linked · ${r.mentionEdges} mention edge(s) · ${r.skippedByGate.length} gated`,
+          ),
+        );
+      } finally {
+        store.close();
+      }
+      break;
+    }
+
+    if (sub === "synthesize" || sub === "pipeline" || sub === "all") {
       const { runSynthesis } = await import("./memory/pipeline");
       const dryRun = flag("dry-run");
       console.log();
@@ -1595,7 +2580,7 @@ switch (cmd) {
           : `${style.accent("●")} ${style.bold("plist written, but launchctl load failed")}`,
         "",
         `plist      ${style.dim(r.plistPath)}`,
-        `runs       ${style.dim("mlx-bun memory synthesize (a no-op until synthesis lands)")}`,
+        `runs       ${style.dim("mlx-bun memory synthesize (full DAG: create + wikify sweep)")}`,
         `undo       ${style.accent("mlx-bun memory unschedule")}`,
       ]);
       break;
@@ -1698,9 +2683,11 @@ switch (cmd) {
     }
 
 
+    // Unknown subcommand: help on stdout, but a FAILURE exit — scripts and
+    // launchd jobs must be able to detect typos (printHelp would exit 0).
     console.error(`unknown: mlx-bun memory ${sub}`);
-    printHelp("memory");
-    break;
+    console.log(renderHelp(HELP.memory!));
+    process.exit(1);
   }
 
   default: