mlx-bun 0.0.7 → 0.0.9

package/docs/planning/website-readme-pass-plan.md

@@ -0,0 +1,224 @@
+# Website + README pass — audit findings and fix plan (2026-07-01)
+
+Scope: the `website/` Astro subproject (mlx-bun.dev), `README.md`, and the
+`docs/reference/` sources that feed both. Audited read-only against current
+main **and against the published `v0.0.8` tag** (what installers actually
+get). Every claim below was verified in source (`git show v0.0.8:…` for
+release attribution), not doc-vs-doc.
+
+## 0. The one decision that gates everything
+
+**The site and README already document v0.0.9 behavior.** The published
+v0.0.8 binary serves on **port 8090, bound to all interfaces**; main (and
+every doc: README, quickstart, http-api, the synced server-config page)
+says **8080 + loopback**. A fresh `brew install` user today follows the
+quickstart and every curl example fails. The five auto-synced reference
+pages likewise already describe `--max-tokens`, logprobs, `--sft-scope`,
+and `/v1/completions` — all post-tag.
+
+Two coherent options:
+
+- **(A) Recommended: cut v0.0.9, then deploy the site.** All docs become
+  true simultaneously; nothing below needs version annotations. The
+  release-notes draft already exists (`docs/planning/release-notes-v0.0.9.md`).
+- **(B)** If v0.0.9 is not imminent: hold site deploys, and treat every
+  item marked *v0.0.9* below as blocked. (Reverting docs to 8090 is churn
+  for nothing — don't.)
+
+The rest of this plan assumes (A); each item is still marked
+**[safe-now]** (true for v0.0.8 users too) or **[v0.0.9]** (true only
+after release).
+
+## 1. Mechanism: how site content is produced
+
+- **Generated (cannot drift):** 5 pages built from `docs/reference/*.md`
+  by `website/scripts/sync-reference-docs.mjs`, run on every
+  dev/build via the `astro:config:setup` hook in `astro.config.mjs`:
+  `server-api.md`, `server-config.md`, `training.md` → `reference/`;
+  `library-api.md`, `embedding.md` → `guides/`. Generated copies are
+  gitignored. This works well — verified accurate against main.
+- **Hand-written (tracked, CAN silently drift, and did):** `index.mdx`,
+  `getting-started/{introduction,installation,quickstart,models}`,
+  `guides/{http-api,troubleshooting}`, `reference/cli.md`, `about/*` (4).
+  The three that drifted are exactly the ones duplicating CLI/model facts:
+  `reference/cli.md`, `getting-started/models.md`, `guides/http-api.md`.
+- **Not synced at all:** `docs/reference/{memory,models,orpo-quickstart,distribution}.md`.
+  The first three are user-facing and site-worthy; distribution.md is
+  maintainer-ops, keep repo-only.
+
+### Mechanism bugs
+
+1. **Deploy trigger misses the source docs.** `.github/workflows/deploy-site.yml`
+   triggers only on `paths: website/**`. Edits to `docs/reference/*.md`
+   alone never redeploy — the "cannot drift" pages drift *in production*
+   until the next unrelated website commit. **Fix [safe-now]:** add
+   `docs/reference/**` to the paths filter.
+2. **"Edit page" links on the 5 generated pages 404.** Starlight's global
+   `editLink.baseUrl` points at `website/src/content/docs/…`, but those
+   files are gitignored, so GitHub 404s. **Fix [safe-now]:** have the sync
+   script inject per-page `editUrl:` frontmatter pointing at the real
+   source (`docs/reference/<file>.md`).
+3. **Local dev/build needs Node ≥ 22.12** (Astro 6). The machine default
+   is nvm Node 18 → `bun run build` fails locally; CI uses Node 22 and is
+   fine. **Fix [safe-now]:** add `"engines": { "node": ">=22.12.0" }` to
+   `website/package.json` and a one-liner in `website/README.md`
+   (`nvm use 22` or `bunx --bun astro build`).
+
+### Build health (measured)
+
+- Build: **green** — 18 pages, pagefind index, sitemap (built with Node 22 semantics via `bunx --bun astro build`).
+- Internal links: **all 17 unique internal hrefs resolve** to built routes.
+- GitHub `blob/main` links (22 unique): **all targets exist** in the repo.
+- Assets: `public/{CNAME,install.sh,favicon.svg}` present.
+- The only broken-link class is the editLink bug above.
+
+## 2. WRONG (fix first — actively misleads)
+
+| # | Where | Claim | Truth | Gate |
+|---|---|---|---|---|
+| W1 | Site quickstart/installation/index-hero, README (lines 96/108/208/235/286), synced server-config | server on `localhost:8080`, loopback | **v0.0.8 = port 8090, all interfaces**; 8080+loopback is post-tag (8ee691d) | **[v0.0.9]** — resolves itself under option (A) |
+| W2 | `website/…/reference/cli.md:29` | `--no-kv-quant` / `--kv-bits <n>` | Never existed. Real flag: `--kv-quant config\|off\|4\|8` | [safe-now] |
+| W3 | `website/…/reference/cli.md:30` | `--adapter id=dir` | Syntax is `--adapter <dir>` | [safe-now] |
+| W4 | `README.md:304` | "Published to npm as `mlx-bun` (current: 0.0.4)" | 0.0.8 | [safe-now] |
+| W5 | `getting-started/models.md:19` + `introduction.md:33` | "Currently MiniCPM5 plus the Gemma-4 quants… Qwen 3.x is next on the roadmap" | **Qwen3.5-4B is supported in v0.0.8** (support.ts at tag) — and `about/comparison.md:39` already says so; the site contradicts itself | [safe-now] |
+| W6 | `README.md:39`, `installation.mdx:22` | pin example `MLX_BUN_VERSION=v0.0.4` | Use `v0.0.8` (or drop the pinned example) | [safe-now] |
+
+## 3. STALE (true once, now behind)
+
+- S1 `getting-started/models.md` table: add the Qwen3.5-4B row (copy the
+  README's row: 3.1 GB, 8 GB, thinking + tool calling). [safe-now]
+- S2 `guides/http-api.md:85-89` endpoint list: `/stats`, `/fit`,
+  `/library`, `/downloads` existed at v0.0.8 and are undocumented
+  [safe-now]; `/v1/completions`, `/v1/embeddings`, `/health`,
+  logprobs/top_logprobs are **[v0.0.9]**.
+- S3 `about/benchmarks.md:6`: "mlx-optiq 0.2.1" — oracle venv now runs
+  0.2.4; also "clean-machine re-measure is pending" (line 35) — refresh or
+  date-stamp when the re-measure lands. [safe-now, low priority]
+- S4 README "Status" section: reflect the v0.0.9 wave (CI gate now exists,
+  Tier-0 generics, mlx-lm tool parity) — **[v0.0.9]**.
+
+## 4. MISSING (goals with no page)
+
+- M1 **Memory system — goal 5 — has ZERO website presence.** The
+  README sells it; the site never mentions it. `docs/reference/memory.md`
+  is accurate and site-worthy. **Fix:** add to the sync MAP →
+  `guides/memory.md` ("Personal memory") + a home-page feature card + a
+  sidebar entry. Read path (init/status/open/search/agent tools) shipped
+  in v0.0.8 [safe-now]; `memory synthesize` as a real pipeline is
+  **[v0.0.9]** (f7dad8f is post-tag) — under option (A) publish the whole
+  page at once.
+- M2 **CLI reference covers 7 of ~21 verbs.** Missing and in v0.0.8:
+  `gen/generate`, `bench`, `train`, `train-watch`, `memory`, `pi`, `help`
+  [safe-now]. Missing and post-tag: `embed`, `gc`, `fuse`, `convert`,
+  `upload`, `perplexity`, `setup` alias **[v0.0.9]**. **Structural fix:**
+  stop hand-writing it — create `docs/reference/cli.md` as the tracked
+  source (or generate from `printHelp`) and add it to the sync MAP, so the
+  CLI page can never drift again.
+- M3 **Model management** (`get`/`scan`/`ls`/`gc`, cache layout, gc safety
+  rails): `docs/reference/models.md` is accurate + site-worthy → sync to
+  `guides/model-management.md`. gc verb is **[v0.0.9]**; the rest safe-now.
+- M4 **Drop-in mlx-lm replacement — goal 1 — has no page.** It's v0.0.9's
+  headline (mlx_lm.server endpoint/flag/sampler/logprobs parity, same
+  port/host defaults, `fuse`/`convert`/`perplexity`/`upload` tool parity).
+  **Fix [v0.0.9]:** new `guides/drop-in-mlx-lm.md` — "stop
+  `mlx_lm.server`, start `mlx-bun serve`, same curl works" with the
+  parity table and the deliberately-not-ported list.
+- M5 **Tier-0 generic models** (UniversalDense, 11 archs, L1-gated,
+  bit-exact goldens for llama/qwen2/gemma2): reframes the scope story from
+  "a few models" to "runs what mlx-lm runs; *optimizes* the targets".
+  Rewrite `models.md` around the targeted-vs-generic tier split (`ls`
+  already labels it). **[v0.0.9]**.
+- M6 **The lab — goal 6 — is invisible.** ORPO training (orpo-quickstart
+  is accurate + site-worthy), DSpark speculative decoding, the curve
+  designer (`/curves` UI ships in v0.0.8!), diffusion-gemma, the
+  train-watch dashboard. **Fix:** new `about/lab.md` (or top-level "The
+  lab") presenting these as the experimental playground with GitHub links
+  into docs/design + docs/investigations; sync orpo-quickstart →
+  `guides/fine-tuning-quickstart.md`. Mostly [safe-now] (frame as
+  experimental); `--sft-scope` mention is [v0.0.9].
+- M7 **README link coverage:** memory paragraphs (137–145) should link
+  `docs/reference/memory.md` + `docs/design/memory-synthesis.md`; the
+  model table (155) should link `docs/reference/models.md`; nothing links
+  to **mlx-bun.dev** anywhere except install.sh — add a "Docs:
+  https://mlx-bun.dev" line at the top. [safe-now]
+
+## 5. Structure / information architecture
+
+### Website — proposed sidebar (new items marked)
+
+```
+Getting started
+  Introduction · Installation · Quickstart · Choosing a model (rewrite: tiers, M5)
+Guides
+  The HTTP API
+  Drop-in for mlx-lm            ← NEW (M4, v0.0.9)
+  Personal memory               ← NEW (M1, synced from docs/reference/memory.md)
+  Model management              ← NEW (M3, synced from docs/reference/models.md)
+  Using the library · Embedding in a Mac app
+  Fine-tuning quickstart        ← NEW (M6, synced from orpo-quickstart.md)
+  Troubleshooting
+Reference
+  CLI (→ synced, M2) · Server API · Server configuration · Training & fine-tuning
+About
+  Why mlx-bun · How it compares · Benchmarks · Correctness
+  The lab                       ← NEW (M6)
+```
+
+### Six-goals legibility scorecard (today → after)
+
+| Goal | Today | After |
+|---|---|---|
+| 1 Drop-in mlx-lm replacement | implicit ("OpenAI-compatible") | M4 page + home card names mlx_lm.server explicitly |
+| 2 JS library / Mac apps | ✅ library + embedding guides | unchanged (already good) |
+| 3 Memory/quality/speed | ✅ benchmarks + correctness + fit | S3 refresh |
+| 4 One command <60s, 4 paths | ✅ home hero + installation | W1 port fix is the blocker |
+| 5 Memory showcase | ❌ absent | M1 guide + home feature card |
+| 6 Playground | ❌ absent | M6 lab page + home card |
+
+- **Home page:** the 6 feature cards cover goals 1–4 twice and 5–6 never.
+  Swap/add two cards: "Personal memory" (goal 5) and "The lab" (goal 6);
+  make the Protocols card say "drop-in for mlx_lm.server" (goal 1).
+- **Reading order** is otherwise sound: hero → install → quickstart →
+  guides works; introduction.md and why.md duplicate two paragraphs
+  verbatim — acceptable, but keep them in sync or have intro link out.
+
+### README
+
+- The 60-second promise is buried at line 92 inside the *fourth* install
+  path. Move it into the opening: "one command, chatting in under a
+  minute" as the first bold claim, install one-liner immediately after —
+  matching the website hero (they should tell the same story; today the
+  README leads with the product-bet essay).
+- Add the six goals as an explicit bulleted frame (the "What mlx-bun is"
+  section at line 120 is close — reorder it to map 1:1 and give the memory
+  system and the lab their own H2s with doc links).
+- Add the mlx-bun.dev docs link at the top (M7).
+- Keep README ⊆ website: README states, website explains — every README
+  section should end with a link to the corresponding site page once M1–M6
+  land.
+
+## 6. Execution order
+
+1. **[safe-now, no release needed]** W2–W6, S1–S3, M7, mechanism fixes
+   (deploy paths filter, editUrl injection, engines field). Note: do NOT
+   deploy the site after these until step 2, because the synced pages
+   already carry v0.0.9 content (W1).
+2. **Josh: cut v0.0.9** (release-notes draft exists).
+3. **[with v0.0.9]** W1 becomes true; land M1–M6 + S4 + README
+   restructure; deploy once. New synced pages = add 4 entries to the
+   sync-script MAP (cli, memory, models→model-management,
+   orpo-quickstart→fine-tuning-quickstart) + sidebar entries + link
+   rewrites for the new routes.
+
+## Appendix: release-attribution ground truth (verified via `git show v0.0.8:`)
+
+- **In v0.0.8:** verbs get/scan/ls/fit/serve/gen/bench/evals/pi/harness/
+  train/train-watch/memory(read-path); Qwen3.5 + DiffusionGemma support;
+  `/curves`, `/dag`, `/stats`, `/fit`, `/library`, `/downloads`, chat UI;
+  port **8090**, host **all interfaces**.
+- **Post-tag (v0.0.9):** port 8080 + loopback, `--temp`/`--max-tokens`,
+  `/v1/completions`, `/health`, `/v1/embeddings`, logprobs/top_logprobs,
+  sampler parity (min_p/XTC/logit_bias/penalties), verbs
+  embed/gc/fuse/convert/perplexity/upload, `--sft-scope`, Tier-0
+  UniversalDense (11 archs, L1 goldens), memory synthesize (real
+  pipeline), registry dedupe, CI gate, `--l2` tier-contract fix.

package/docs/reference/cli.md

@@ -0,0 +1,255 @@
+# CLI reference
+
+Every mlx-bun verb. Commands are shown as `mlx-bun <verb>`; from a clone the
+identical command is `bun src/cli.ts <verb>`. `mlx-bun help <verb>` (or
+`mlx-bun <verb> --help`) prints the full flag list for any command.
+
+Model arguments are **substring queries** against the registry (`e4b`, `26B`,
+`12B-it`); a query matching more than one model errors out and lists the
+candidates — just make it more specific.
+
+Bare `mlx-bun` with no verb runs `serve` — the appliance path: first run
+downloads a starter model, serves it, and opens the chat UI.
+
+> Verbs marked **(v0.0.9)** ship in v0.0.9; everything else is in v0.0.8.
+
+## Serving & chat
+
+### `serve` — run the server
+
+Start the OpenAI/Anthropic-compatible server plus the status page and browser
+chat UI.
+
+```sh
+mlx-bun serve                              # default model, http://localhost:8080
+mlx-bun serve e4b                          # pick a model by substring
+mlx-bun serve gemma --memory-budget 18     # ...with admission control (GB)
+mlx-bun serve e4b --no-open                # don't open the browser chat UI
+```
+
+Common flags (full list in [server-config.md](server-config.md)):
+
+| Flag | Effect |
+|---|---|
+| `--host <addr>` | Interface to bind (default `127.0.0.1`, loopback only; `0.0.0.0` to expose) |
+| `--port <n>` | Listen port (default 8080) |
+| `--memory-budget <GB>` | Reject loads/requests that can't fit the budget |
+| `--kv-quant config\|off\|4\|8` | KV cache quantization: per-layer `kv_config.json`, bf16, or uniform bits (default `config`) |
+| `--adapter <dir>` | Mount a LoRA adapter at startup (`--adapter-path` accepted as the mlx_lm.server alias) |
+| `--batch <n>` | Continuous-batched bf16 serving (default 1 = serial) |
+| `--temperature` / `--top-p` / `--top-k` / `--max-tokens` | Server-wide sampling defaults (per-request fields still win) |
+| `--l1` / `--l2` / `--l3` | Parity tier: bit-exact to mlx-lm / bit-exact to mlx-optiq / best performance |
+| `--no-open` | Don't auto-open the chat UI |
+
+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`. Full
+schemas in [server-api.md](server-api.md).
+
+### `pi` — built-in coding agent
+
+Run the pi coding agent's terminal UI in-process against a local model —
+nothing to install. Reuses a healthy running server, otherwise starts one for
+the session.
+
+```sh
+mlx-bun pi                          # interactive agent session
+mlx-bun pi -p "explain this repo"   # one-shot: print the reply and exit
+```
+
+### `harness pi` — connect your own pi
+
+For people who already use
+[pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent): installs a small,
+reversible discovery extension that registers the local server as a pi
+provider.
+
+```sh
+mlx-bun harness pi              # then: pi --provider mlx-bun
+mlx-bun harness pi --remove     # disconnect
+```
+
+### `generate` (alias `gen`) — one-shot generation
+
+Load the model, generate, print, exit — no server. Renders through the chat
+template by default; `--raw` feeds the prompt verbatim. Sampling and
+decode-path levers mirror `serve` (`--temperature`, `--seed`, `--l1/--l2/--l3`,
+`--kv-quant`, …).
+
+```sh
+mlx-bun generate gemma "a haiku about metal shaders"
+mlx-bun gen e4b --prompt "…" --max-tokens 512 --seed 42
+```
+
+### `embed` — text embeddings **(v0.0.9)**
+
+One-shot embeddings from a local Qwen3-Embedding model (last-token pooled,
+L2-normalized — bit-exact vs mlx-lm). One JSON vector per input line.
+
+```sh
+mlx-bun embed --text "hello world"
+echo -e "line one\nline two" | mlx-bun embed --json
+```
+
+For a server endpoint, `mlx-bun serve <embedding-model>` then
+`POST /v1/embeddings`.
+
+## Models & disk
+
+Full guide: [models.md](models.md).
+
+### `get` — download a model
+
+Resumable, checksum-verified download into the standard Hugging Face cache
+(plain HTTPS, no Xet — no 0% stalls).
+
+```sh
+mlx-bun get mlx-community/gemma-4-12B-it-OptiQ-4bit
+mlx-bun get 12B                  # no "/" = registry query; re-gets/refreshes the match
+```
+
+### `scan` — index your cache
+
+Re-index the HF cache into the registry (config + safetensors headers only,
+never tensor bytes) so `ls`, `serve`, and `fit` can find models by substring.
+
+```sh
+mlx-bun scan
+```
+
+### `ls` — list models
+
+```sh
+mlx-bun ls                          # size, params, quant, capabilities
+mlx-bun ls --vision --max-size 10GB # filter
+mlx-bun ls --all-revisions          # one row per cached snapshot
+```
+
+### `gc` — reclaim disk **(v0.0.9)**
+
+Delete superseded snapshots and the blobs only they reference. Prints the plan
+by default; `--yes` actually deletes.
+
+```sh
+mlx-bun gc          # dry-run: what would be reclaimed
+mlx-bun gc --yes    # delete
+```
+
+### `fit` — memory contract
+
+Deterministic memory assessment: does it fit, what's the max context, predicted
+tok/s. Weights bytes from safetensors headers, KV bytes/token from the config,
+calibrated prefill transient, wired-memory ceiling.
+
+```sh
+mlx-bun fit gemma --ctx 32768          # for this machine
+mlx-bun fit gemma --ctx 8192 --skus    # across the Apple Silicon lineup
+```
+
+## Training & model creation
+
+Full reference: [training.md](training.md); guided walkthrough:
+[orpo-quickstart.md](orpo-quickstart.md).
+
+### `train` — LoRA fine-tune
+
+SFT / DPO / ORPO on your data, with the full memory stack (flash-CCE head,
+prefix-sharing, segmented backward) on by default. Saves a mountable adapter.
+
+```sh
+mlx-bun train e4b --data ./prefs                     # ORPO (default) on {prompt,chosen,rejected}
+mlx-bun train e4b --data ./prefs --method sft        # SFT on {messages|text}
+mlx-bun train e4b --data ./prefs --dry-run           # inspect the plan, don't train
+```
+
+### `train-watch` — live training dashboard
+
+Tails an adapter dir's `metrics.jsonl` and renders live loss / speed / memory.
+
+```sh
+mlx-bun train-watch ~/.cache/mlx-bun/mlx-bun-finetunes/orpo-e4b
+```
+
+### `fuse` — merge an adapter into the base **(v0.0.9)**
+
+Folds LoRA deltas into the base weights and writes a standalone snapshot; a
+quantized base keeps its exact quantization layout. Flag names match
+`mlx_lm.fuse`.
+
+```sh
+mlx-bun fuse e4b --adapter ./adapters --save-path ./fused_model
+mlx-bun serve ./fused_model
+```
+
+### `convert` — quantize a model **(v0.0.9)**
+
+Quantize an HF model (local path, downloaded model, or repo id) into a local
+MLX snapshot — uniform 4/8-bit, or mixed-precision via `--target-bpw`
+(sensitivity sweep + per-layer bit knapsack). `--upload-repo` pushes the result.
+
+```sh
+mlx-bun convert Qwen/Qwen3-4B -q                      # uniform 4-bit
+mlx-bun convert Qwen/Qwen3-4B --target-bpw 4.5        # mixed precision
+```
+
+### `upload` — push to the Hugging Face Hub **(v0.0.9)**
+
+Native push-to-hub, no Python: creates the repo if needed, uploads via the
+git-LFS batch protocol, commits. Flag names match `mlx_lm.upload`.
+
+```sh
+mlx-bun upload --path ./fused_model --upload-repo you/my-model
+```
+
+### `perplexity` — evaluate on your data **(v0.0.9)**
+
+`mlx_lm.perplexity` methodology exactly, over a **local** `.jsonl`/`.txt` file.
+
+```sh
+mlx-bun perplexity e4b --data-path ./corpus.jsonl
+```
+
+## Memory
+
+### `memory` — the personal wiki
+
+A local, durable memory for the assistant: a git-tracked Markdown wiki at
+`~/.mlx-bun/wiki` that loads into every `mlx-bun pi` / `mlx-bun serve` session.
+Full guide: [memory.md](memory.md).
+
+```sh
+mlx-bun memory init              # create the wiki (idempotent); import + schedule
+mlx-bun memory status            # path, article count, git + schedule state
+mlx-bun memory open [article]    # open in Obsidian (falls back to Finder)
+mlx-bun memory search <query>    # search articles from the terminal
+mlx-bun memory synthesize        # conversations → cross-linked articles, all local
+mlx-bun memory schedule --at 03:00
+```
+
+`setup` is an alias for `memory` **(v0.0.9)**.
+
+## Measurement
+
+### `benchmark` (alias `bench`) — measure our stack
+
+Runs mlx-bun by itself on this machine and records to the eval DB.
+
+```sh
+mlx-bun bench e4b --tokens 256 --runs 3
+```
+
+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,
+writing `benchmarks-h2h-<date>.md`.
+
+### `evals` — recorded runs
+
+```sh
+mlx-bun evals                # table: when, model, KV mode, tok/s, TTFT, peak, commit
+mlx-bun evals --raw          # JSON lines for scripts/jq
+```
+
+## Everything else
+
+- `help [verb]` — overview, or per-verb help (same as `<verb> --help`).
+- `--version` / `-v` — print the version.

package/docs/reference/embedding.md

@@ -1,5 +1,10 @@
 # Embedding mlx-bun (single-binary sidecar)
 
+> **Not text embeddings.** This page is about *embedding the mlx-bun binary*
+> inside an app. For text-vector embeddings (Qwen3-Embedding, `mlx-bun embed`,
+> `POST /v1/embeddings`), see [server-api.md](./server-api.md#post-v1embeddings-openai-embeddings-api)
+> and [library-api.md](./library-api.md#text-embeddings).
+
 Ship local inference inside a Mac app (Tauri, Electron, or anything
 that can spawn a process) with zero user-visible dependencies: one
 executable + three native libraries, dropped into your app's resources.
@@ -89,7 +94,7 @@ Spawn the server on app start, point your in-app client at it:
 ```ts
 // Electron main / Tauri sidecar config
 const child = spawn(resourcePath("mlx-bun"), [
-  "serve", "gemma-4-12B", "--port", "8090", "--memory-budget", "12",
+  "serve", "gemma-4-12B", "--port", "8080", "--memory-budget", "12",
 ]);
 // readiness: poll GET /v1/models (start→ready is ~0.4 s warm)
 ```
@@ -113,7 +118,7 @@ The binary includes the resumable verified downloader:
 ```sh
 mlx-bun get mlx-community/gemma-4-12B-it-OptiQ-4bit   # → standard HF cache
 mlx-bun scan                                          # index it
-mlx-bun serve gemma-4-12B --port 8090
+mlx-bun serve gemma-4-12B --port 8080
 ```
 
 Downloads resume across interruption, every blob is checksum-verified

package/docs/reference/library-api.md

@@ -78,7 +78,7 @@ prompt time), the decode clock from there.
 import { loadContext, createServer } from "mlx-bun";
 
 const ctx = await loadContext(dir, "my-model", { memoryBudgetBytes: 12e9 });
-const server = createServer(ctx, 8090, {
+const server = createServer(ctx, 8080, {
   promptCacheBytes: 2e9,        // byte-capped LRU (never count-capped)
   kvQuant: undefined,           // default: kv_config.json; "off" | bits
   memoryBudgetBytes: 12e9,      // admission control — the only OOM defense
@@ -87,8 +87,27 @@ const server = createServer(ctx, 8090, {
 
 `loadContext` refuses models that cannot serve any context within the
 budget (pre-GPU, mmap-only check). The server exposes OpenAI chat
-completions, Anthropic `/v1/messages`, OpenAI Responses, adapters, and
-`/stats` — [server-api.md](./server-api.md).
+completions, Anthropic `/v1/messages`, OpenAI Responses, embeddings,
+adapters, and `/stats` — [server-api.md](./server-api.md).
+
+## Text embeddings
+
+```ts
+import { createModel, loadTokenizer, isEmbeddingModel, embedMany } from "mlx-bun";
+
+const model = createModel(await Weights.open(dir), config); // Qwen3-Embedding
+if (!isEmbeddingModel(model)) throw new Error("not an embedding model");
+const tok = await loadTokenizer(dir);
+
+const [a, b] = embedMany(model, tok, ["the cat sat", "a kitten rested"]);
+// a.vector / b.vector are Float32Array, L2-normalized → dot product = cosine.
+```
+
+`isEmbeddingModel` narrows a `RuntimeModel` to the plain-Qwen3 backbone (the
+only one exposing `embedPooled`: last-token hidden → L2-norm). `embedOne`/
+`embedMany` append the `<|endoftext|>` pooling token and, given an optional
+`instruction`, apply Qwen3-Embedding's query format. Same vectors the CLI
+(`mlx-bun embed`) and `/v1/embeddings` produce — bit-exact vs mlx-lm.
 
 ## Prompt cache (in-process prefix reuse)
 

package/docs/reference/memory.md

@@ -6,7 +6,7 @@ Core rule:
 
 > Chat agents read memory articles. `mlx-bun memory synthesize` is the only writer.
 
-The current release includes the vault, read path, Obsidian open flow, and scheduler. Synthesis is scaffolded but still a no-op M1 stub. The planned synthesis engine uses the same local models you chat with, switched into an editorial pipeline with stage-specific LoRA adapters.
+The current release includes the vault, read path, Obsidian open flow, scheduler, and a live synthesis engine: `mlx-bun memory synthesize` runs the full local DAG (and the nightly job runs it on a schedule). Synthesis uses the same local models you chat with, switched into an editorial pipeline; stage-specific LoRA adapters are the hardening roadmap below.
 
 ## Storage
 
@@ -38,7 +38,7 @@ mlx-bun memory schedule --at 03:00
 mlx-bun memory unschedule
 ```
 
-`memory synthesize` is currently safe and side-effect-free: it reports that M1 stage bodies are not implemented and writes nothing. In the full flow, `memory init` will be able to offer the HF-hosted memory adapter pack download so synthesis can run locally.
+**`memory synthesize` writes to your vault.** It runs the full local synthesis DAG (segment → extract → route → create/patch → reconcile → link → wikify) and creates/patches articles under `articles/` (git-committed, so every change is reviewable and revertible). `--dry-run` is the safe, no-write mode: it reports what would happen without touching the vault. `--since` and `--model` scope/steer a run. The decomposed stage workers (`segment`/`extract`/`route`/`synthesize-stage`/`link`) run one stage each and are resumable.
 
 ## Agent tools
 
@@ -50,7 +50,7 @@ Both `mlx-bun pi` and the web chat expose these read-only tools:
 - `memory_section`
 - `memory_links`
 - `memory_list` — user articles plus read-only `Reference/*` docs
-- `memory_status` — vault path, setup state, article count, git state, last-synthesis placeholder, schedule state, recent changed articles
+- `memory_status` — vault path, setup state, article count, git state, last synthesis run (from the vault's git log), schedule state, recent changed articles
 
 The tools are always registered. If no vault exists, they return a setup message instead of disappearing. Search/read results prefixed with `Reference/` are mlx-bun docs, not user memory articles.
 
@@ -65,7 +65,7 @@ The first command opens the vault. The second opens one article. Obsidian is pre
 
 ## Synthesis roadmap
 
-M1/M2 will turn saved pi sessions into articles using the local model plus four specialized LoRA adapters trained by Josh from existing Lucien-scale pipeline data and distributed from Hugging Face:
+The pipeline (saved pi sessions → articles) runs today on the local model; the roadmap hardens each stage with four specialized LoRA adapters trained from existing Lucien-scale pipeline data and distributed from Hugging Face:
 
 1. deterministic ingest of saved web/terminal pi session JSONL;
 2. **memory-chunk LoRA** — conversation → topic chunks (already trained as a WIP artifact);
@@ -74,4 +74,4 @@ M1/M2 will turn saved pi sessions into articles using the local model plus four
 5. **memory-editor LoRA** — candidate article → polished wiki Markdown;
 6. deterministic footnote/wikilink normalization, quality gates, and git commit.
 
-The adapters propose; the pipeline validates and writes. The pipeline writes only `articles/`; `Reference/` is immutable context. Until synthesis lands, memory works with imported/hand-written user articles plus the built-in read-only mlx-bun reference docs.
+The adapters propose; the pipeline validates and writes. The pipeline writes only `articles/`; `Reference/` is immutable context. Synthesis is live today (`mlx-bun memory synthesize` runs the full DAG; the nightly `memory schedule` job runs it automatically); imported/hand-written user articles and the built-in read-only mlx-bun reference docs coexist with synthesized ones.