mlx-bun 0.5.0 → 1.0.0

package/docs/archive/planning/release-notes-v0.5.0.md

@@ -1,37 +0,0 @@
-# mlx-bun v0.5.0
-
-Whisper speech-to-text: transcription, dictation and voice input, bit-exact
-against mlx-whisper and faster than both mlx-whisper and whisper.cpp on the
-same clips.
-
-- `mlx-community/whisper-large-v3-turbo` (any fp16 `mlx-community/whisper-*`)
-  loads as a new encoder-decoder family. The oracle-parity graph matches
-  mlx-whisper 0.4.3 bit-exactly on the mel spectrogram, the encoder output and
-  every decoder logit; the default fast path (fused attention, fused cross-K/V,
-  a compiled decoder step with device-side logit filters, pipelined greedy,
-  in-graph beam top-k) is held to at most two differing tokens per clip. M1 Max,
-  11 s clip: 340 ms greedy (mlx-whisper 371), 424 ms beam-5 (whisper.cpp 499).
-- Decoding: greedy, sampling with the temperature fallback ladder, beam search
-  (mlx-whisper has none; matches whisper.cpp's beam-5 transcripts), prompts and
-  vocabulary hints fitted to the 223-token budget, language detection,
-  translation, >30 s seek loop, word-level timestamps.
-- `POST /v1/audio/transcriptions` and `/v1/audio/translations` (OpenAI shape,
-  multipart or JSON, json/verbose_json/text/srt/vtt, SSE streaming) on every
-  server, with Whisper loaded per take beside the chat model and released right
-  after it; `mlx-bun serve <whisper model>` runs a transcription-only server.
-- Streaming sessions (`/v1/audio/sessions`): audio uploaded while recording,
-  every finished 30 s window transcribed during capture — a 62 s take returns
-  327 ms after its last chunk.
-- Silero VAD v6.2 gate (ported from the reference graph, verified against the
-  pip package): silence returns an empty transcript without running Whisper;
-  runs on the stream inside sessions.
-- In-process audio decoding through AudioToolbox (3.7 ms for an 11 s mp3 vs
-  72 ms via afconvert); any CoreAudio-readable container.
-- `mlx-bun transcribe <file>` and `mlx-bun dictate` (push-to-talk from the
-  microphone, print / clipboard / typed keystrokes; new `mlx-bun-mic-capture`
-  sidecar), and a hold-to-talk mic in the web composer for any chat model.
-- Measured and shelved: a Core ML encoder on the Neural Engine (3.3× slower
-  than the GPU on the M1 Max); whisper.cpp-style encoder context truncation
-  ships as an off-by-default Lab option.
-
-Native pack `native-v0.5.0` adds the `mlx-bun-mic-capture` helper.

package/docs/archive/planning/web-ui-pass-plan.md

@@ -1,213 +0,0 @@
-# Web UI pass — ranked fix list (2026-07-01 audit)
-
-Read-only audit of every web surface against the current server contract:
-`src/web/app.html` (unified SPA: chat / quantize / finetune / dataset /
-status+library / routes), `src/assets/curve-designer.html` (/curves),
-`src/pi-web.ts` (WS chat bridge), `src/server.ts` routes, plus the dead
-`src/status-page.html`. Method: diffed every fetch/WS consumer in the pages
-against the actual handler shapes in `server.ts`, `src/jobs/types.ts`,
-`src/train/{job,trainer}.ts`, `src/quantize/job.ts`, `src/download.ts`,
-`src/registry.ts`, `src/model/support.ts`.
-
-**Live click-through was skipped deliberately**: GPU-loading test suites
-(`bun test tests/server.test.ts …`, loads MiniCPM5) were running for the whole
-audit window, and starting a second model server would have contended with
-them. Every finding below is source-verified on both sides of the contract.
-
-Port sweep: no stale `8090` or hardcoded URLs remain in any html/js.
-`curve-designer.html:92` falls back to `http://localhost:8080` (matches the
-new default) and uses `location.origin` when served at `/curves`. ✓
-
----
-
-## WRONG (bugs — fix first)
-
-1. **Fine-tune live stats never show LR or tok/s — metric field-name mismatch.**
-   `src/web/app.html:2317-2318` reads `e.lr` / `e.tps`, but the trainer emits
-   `learning_rate` / `tokens_per_sec` (`src/train/trainer.ts:559-560`, same at
-   :724-727 and :966-969; contract comment in `src/jobs/types.ts:23`). The
-   "learning rate" and "tok/s" chart stats stay `—` for the entire run.
-   Also update the protocol doc-comment at `app.html:1089` (`lr?`, `tps?`).
-   **Fix:** read `e.learning_rate` and `e.tokens_per_sec`.
-
-2. **Chat queue bar renders arrays as strings and empty tags.**
-   `pi-web.ts:183` sends `queue_update` with `steering: readonly string[]` and
-   `followUp: readonly string[]` (arrays). `app.html:1683-1684` does
-   `if (q.steering) … esc(String(q.steering))` — an empty array is truthy, so
-   every `queue_update` renders empty `steering:`/`queued:` pills, and multiple
-   queued messages render comma-joined.
-   **Fix:** guard with `.length` and render `q.followUp.map(...)` (or
-   `q.steering[q.steering.length-1]`).
-
-3. **Library table loads exactly once per app lifetime — new quants never appear.**
-   `app.html:2603` gates `loadLibrary()`/`loadFit()` behind `fitLoaded`, which
-   is never reset. The server explicitly invalidates its 30 s `/library` cache
-   when a quantize job completes so "the next poll rescans and shows it"
-   (`src/server.ts:2510-2513`) — but the UI never re-polls. A model quantized,
-   downloaded, or gc'd mid-session never shows until a full page reload.
-   **Fix:** refresh the library on its own interval (e.g. every 15 s inside
-   `tick()`), and force one refresh when a quantize job reaches `done`.
-
-4. **Adapter mount failure toasts "[object Object]".**
-   `POST /v1/adapters` errors use the OpenAI envelope `{error:{message}}`
-   (`src/server.ts:1600`), and the `api()` helper (`app.html:1080`) keeps
-   `data.error` as that object; `onSelectAdapter` (`app.html:1908-1909`) then
-   string-concatenates it. Any mount failure reads
-   `adapter: [object Object]`.
-   **Fix:** in `api()`, unwrap
-   `data.error && typeof data.error === "object" ? data.error.message : …`.
-
-5. **Quantize inspect result parsing targets a response shape the server never sends.**
-   `inspectModel` returns `support: boolean` (`src/quantize/job.ts:101`), but
-   `app.html:2135-2140` checks `d.support === "supported" | "ok" | "untested"`
-   (all dead branches) and, when `support` is false, prints
-   `esc(d.support || "unknown architecture")` → always "unknown architecture"
-   even when `arch` was resolved. `size_gb` is also rendered raw (unrounded
-   float, and `0` when a direct path bypasses the registry).
-   **Fix:** treat `support` as boolean; show `arch` + "not quantizable" on
-   false; `(+d.size_gb).toFixed(2)` and hide when 0.
-
-6. **Stale vision claim in the chat attach path.**
-   `app.html:1848`: "This model can't see images — switch to the **12B** for
-   vision." SigLIP landed: e2b/e4b/26B/31B are vision-capable too
-   (`src/registry.ts:213-219` `visionCapable`), so the 12B-only advice is
-   wrong.
-   **Fix:** model-agnostic copy: "This model can't see images — serve a
-   vision-capable model (Gemma vision builds show a *vision* tag in the
-   Library)."
-
----
-
-## MISSING (current capabilities the UI doesn't expose)
-
-7. **`sft_scope` absent from the fine-tune form.**
-   The finetune job accepts `sft_scope: "full" | "response"` and validates it
-   at submit (`src/train/job.ts:54,74-76`); default is now `"full"`
-   (paper/TRL-faithful, commit d32fe32). The ORPO panel
-   (`app.html:791-800`) has λ + schedule but no scope control, and
-   `collectHP()` (`app.html:2276-2289`) never sends it.
-   **Fix:** add a segmented control (full · response) to `#f-orpo-extra` with
-   a hint ("full = paper/TRL chosen-NLL over the whole sequence; response =
-   pre-2026-07 response-only"), include `sft_scope` in `collectHP()` when
-   method === "orpo".
-
-8. **`min_p` / `xtc_probability` / `xtc_threshold` / `logprobs` not in any request-builder UI.**
-   Server supports them per-request (`src/server.ts:280-304`, wired at
-   :1138-1141). The chat sampling popover (`app.html:592-613`) only has
-   temperature/top_p/top_k — and the whole chain is width-limited: the
-   `set_sampling` WS frame (`pi-web.ts:160`), `SamplingOverrides`
-   (`pi-web.ts:408-412`), and `injectSampling` (`pi-web.ts:420-440`) all only
-   carry those three fields.
-   **Fix (scoped):** add `min_p` (slider 0–0.5) end-to-end: popover row →
-   `set_sampling` frame → `SamplingOverrides.min_p` → `injectSampling`. XTC and
-   logprobs are power-user/API features; document rather than add sliders.
-
-9. **No gc/reclaim story in Library or Downloads.**
-   `mlx-bun gc` exists (CLI `src/cli.ts:1100`; planner
-   `src/registry.ts:375-455` `planGc`/`executeGc`) and the download path
-   prints "gc reclaims ~X GB" (`cli.ts:1015-1018`) — but the web Library shows
-   superseded revisions' disk cost with no affordance. **Needs a new server
-   endpoint first** (e.g. `GET /api/gc/plan`, `POST /api/gc/execute {yes}`),
-   then a Library footer line: "N superseded snapshots · reclaim X GB —
-   [Clean up]". (Separate from the listCanonical wiring below, but pairs
-   naturally with it: dedupe hides the stale revisions, gc deletes them.)
-
-10. **Other accepted-but-hidden finetune/quantize knobs** (lower priority):
-    `grad_accumulation_steps`, `warm_start_adapter`, adapter naming (submit
-    always writes `adapter-<timestamp>`, `src/server.ts:2529-2530`) on the
-    finetune form; `reference`, `calibration_mix`, `n_calibration`
-    (`src/server.ts:2460-2461`) on the mixed-bpw quantize step. Add an
-    "Advanced" disclosure rather than more top-level fields.
-
----
-
-## BLOCKED on the queued server.ts listCanonical / visionCapable / tier wiring
-
-The functions exist and are tested (`Registry.listCanonical`
-`src/registry.ts:181`, `visionCapable` :217, `supportTier`
-`src/model/support.ts:53`) but the server still serves the old view. UI
-consumption points to touch when the wiring lands:
-
-11. **Revision duplicates in /library and /v1/models.**
-    `src/server.ts:1263` (`/library`) and :1491 (`/v1/models`) iterate
-    `reg.list()` — one row per cached snapshot revision. Both should use
-    `reg.listCanonical()`. UI needs no change; the Library table and every
-    /v1/models-driven picker (external pi, CLI) currently show dupes.
-
-12. **`vision` flag understates capability.**
-    `src/server.ts:1278` sends `vision: m.hasVisionSidecar`, which misses the
-    12B's encoder-free `gemma4_unified_vision` (config-declared, no sidecar
-    file). Should be `visionCapable(m)`. UI consumption at `app.html:2663`
-    then needs no change.
-
-13. **`supported` is a boolean; tiers are invisible.**
-    `src/server.ts:1264` sends `supported: isSupportedModelRecord(...)`.
-    Generic Tier-0 models (universal-dense descriptors) now count as
-    supported — correct — but the Library can't distinguish "targeted
-    (L2/L3 paths)" from "generic (L1 monolith only)". When the server sends
-    `tier: "targeted" | "generic" | null` (from `supportTier`), update:
-    - `app.html:2659` status cell: keep `unsupported (model_type)` for null;
-      add a dim "generic" badge for Tier-0 rows.
-    - Keep `supported` as a boolean alongside `tier` for one release so the
-      UI change can land independently.
-
----
-
-## CONFUSING / polish
-
-14. **Sampling popover "recommended" values are hardcoded to MiniCPM5.**
-    `app.html:1824-1825` (`SAMP_REC {topP:.95, topK:0}`, `recTemp()` 0.9/0.7)
-    claims to "mirror server toOptions defaultTemp", but the server resolves
-    defaults from each model's `generation_config.json`
-    (`src/server.ts:1120-1132`). For any other served model the dimmed "auto"
-    readouts lie. Fix: surface `genDefaults` (e.g. on the `ready` frame or
-    `/v1/models` extras) and seed the popover from it.
-
-15. **Adapter dropdown goes stale after training.**
-    `refreshAdapters()` runs only at chat init and on `ready` frames
-    (`app.html:1789-1792, 2037`). An adapter trained in the Fine-tune tab
-    doesn't appear until reconnect/reload. Refresh on finetune `done` and on
-    chat `enter()`. Also escape the interpolation at `app.html:1897-1898`
-    (`a.id`/`a.path` go into HTML unescaped).
-
-16. **Dead file: `src/status-page.html` (497 lines) + `scripts/status-page-stub.ts`.**
-    Nothing imports it since the SPA absorbed status (only
-    `scripts/status-page-stub.ts` references it). Delete both, or move the
-    stub note into the SPA docs.
-
-17. **Routes tab breaks in the compiled binary.**
-    `#/routes` iframes `/dag`, which `readFileSync`s
-    `../docs/dag/training-inference-map.html` (`src/server.ts:1231`) — absent
-    outside the repo checkout, so the tab shows a bare 404 string. Either
-    embed the artifact like app.html, or hide the tab when `/dag` 404s.
-
-18. **CLI banner vs landing route.** `src/cli.ts:64` says "status page at
-    http://localhost:8080/", but `/` lands on `#/chat`. Say "web app" or point
-    at `/#/status`.
-
-19. **Curves nav tab never highlights.** It's a full-page `href="/curves"`
-    (`app.html:520`), outside the hash router, so the active-tab logic
-    (`app.html:1390`) can't mark it. Cosmetic; acceptable, but a
-    `aria-current` on the curve page's back-link side would be tidier.
-
-20. **Library "too big" rows hide the useful number.** `app.html:2665-2666`
-    shows max context/decode only when `a.fits` (fit solved at 8192); a model
-    that fits at a smaller context shows `—`. Show `max_safe_context`
-    whenever it's > 0.
-
-21. **Downloads visibility is per-process.** `/downloads` reads a
-    process-local tracker (`src/download.ts:276-279`) — a `mlx-bun get` in
-    another terminal is invisible to the nav pill/status card. Note in the UI
-    copy or leave; fixing needs a shared store.
-
----
-
-## Suggested landing order
-
-1. Bugs #1–#6 (one UI-only PR; no server changes).
-2. #7 sft_scope + #15 adapter refresh (small, independent).
-3. The queued server wiring (#11–#13) as its own PR: `listCanonical` +
-   `visionCapable` + `tier` in `/library` and `/v1/models`, then the
-   one-line UI badge.
-4. #8 min_p end-to-end, #9 gc endpoint + Library affordance.
-5. Cleanup: #16 dead files, #17 routes tab, #14 genDefaults surfacing.

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

@@ -1,224 +0,0 @@
-# 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/archive/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.