mlx-bun 0.0.13 → 0.3.0

package/bin/mlx-bun.mjs

@@ -4,7 +4,7 @@
 // (a guard inside cli.ts would never run under Node — its static imports
 // hoist and fail on the bun: scheme first).
 
-const MIN_BUN = "1.3.14"; // Bun.Image + verified FFI behavior (see README)
+const MIN_BUN = "1.4.0"; // fixed macOS arm64 FFI stack layout (see README)
 
 if (typeof Bun === "undefined") {
   console.error(

package/docs/README.md

@@ -0,0 +1,91 @@
+# docs/ map (generated — do not edit; `bun scripts/check-hygiene.ts --write-docs-map`)
+
+## docs/archive/
+
+Frozen history — read-only, never extended in place; recover raw data via git history.
+
+- [hlg-sampling.md](../docs/archive/hlg-sampling.md) — HLG sampling — a piecewise tone curve on the logits
+- [investigations/audio-input-plan.md](../docs/archive/investigations/audio-input-plan.md) — Audio input — design & implementation plan (gemma-4 audio tower)
+- [investigations/chunk-finetune-experiment.md](../docs/archive/investigations/chunk-finetune-experiment.md) — Fine-tuning experiment: chunking task (2026-06-16)
+- [investigations/colibri-glm52-port.md](../docs/archive/investigations/colibri-glm52-port.md) — GLM-5.2 on a 32 GB Mac — native MLX port of the Colibri hierarchy
+- [investigations/colibri-oracle-pin.md](../docs/archive/investigations/colibri-oracle-pin.md) — Colibri oracle pin for the native GLM-5.2 port
+- [investigations/curve-bisector-routing.md](../docs/archive/investigations/curve-bisector-routing.md) — Curve sampler: bisectors, routing, and the falsification
+- [investigations/decode-roofline-lookagain.md](../docs/archive/investigations/decode-roofline-lookagain.md) — Decode perf "look again" — adversarial re-exam of the M=1 floor claim (2026-07-01)
+- [investigations/diffusion-gemma-port.md](../docs/archive/investigations/diffusion-gemma-port.md) — DiffusionGemma port — plan & parity strategy
+- [investigations/dspark-handoff.md](../docs/archive/investigations/dspark-handoff.md) — DSpark — handoff
+- [investigations/expert-offload-single-user-moe.md](../docs/archive/investigations/expert-offload-single-user-moe.md) — Expert offload for single-user local MoE — findings + design sketch
+- [investigations/faithful-l1-consolidation.md](../docs/archive/investigations/faithful-l1-consolidation.md) — Faithful → L1: consolidating the "match mlx-lm" path
+- [investigations/hlg-sampling-investigation.md](../docs/archive/investigations/hlg-sampling-investigation.md) — Investigation: HLG sampling — a piecewise tone curve on the logits
+- [investigations/indexshare-performance-spike.md](../docs/archive/investigations/indexshare-performance-spike.md) — IndexShare / IndexCache performance spike
+- [investigations/kernel-perf-review-2026-07.md](../docs/archive/investigations/kernel-perf-review-2026-07.md) — Kernel/perf deep review — 2026-07-01 (condensed, tracked record)
+- [investigations/lab-build-journal.md](../docs/archive/investigations/lab-build-journal.md) — Build journal — mlx-bun Lab (web UI + native quantize/train/dataset + pi web chat)
+- [investigations/minicpm5-decode-megakernel.md](../docs/archive/investigations/minicpm5-decode-megakernel.md) — MiniCPM5 Decode Megakernel — end-to-end build plan (handoff)
+- [investigations/openwiki-evaluation.md](../docs/archive/investigations/openwiki-evaluation.md) — OpenWiki — evaluation & fit analysis
+- [investigations/optimization_plan.md](../docs/archive/investigations/optimization_plan.md) — mlx-bun: gemma4.ts decompose & optimize — action plan
+- [investigations/orpo-base-uf-experiment-and-directions.md](../docs/archive/investigations/orpo-base-uf-experiment-and-directions.md) — ORPO from-base on UltraFeedback (mixed-5bpw) — results + research directions
+- [investigations/orpo-flash-cce-pin-leak.md](../docs/archive/investigations/orpo-flash-cce-pin-leak.md) — flash-CCE host-buffer pin leak — post-mortem + L3 verification approach
+- [investigations/orpo-uf-testing-handoff.md](../docs/archive/investigations/orpo-uf-testing-handoff.md) — ORPO-on-UF — results + testing-phase handoff
+- [investigations/pareto-specialized-runtime-findings.md](../docs/archive/investigations/pareto-specialized-runtime-findings.md) — Pareto-specialized runtime findings
+- [investigations/pi-builtin-investigation.md](../docs/archive/investigations/pi-builtin-investigation.md) — Investigation: pi as a "built-in" terminal for mlx-bun
+- [investigations/pre-colibri-stabilization.md](../docs/archive/investigations/pre-colibri-stabilization.md) — Pre-Colibri stabilization program
+- [investigations/segmented-backward-handoff.md](../docs/archive/investigations/segmented-backward-handoff.md) — Handoff — segmented backward training (2026-06-16)
+- [investigations/starter-model-port-handoff.md](../docs/archive/investigations/starter-model-port-handoff.md) — Handoff: the sub-GB starter model port (publishing gate 1)
+- [investigations/steel-flash-cce-handoff.md](../docs/archive/investigations/steel-flash-cce-handoff.md) — Steel flash-CCE — handoff
+- [investigations/the-dreaming-handoff.md](../docs/archive/investigations/the-dreaming-handoff.md) — THE DREAMING — HANDOFF (2026-06-28)
+- [investigations/trainer-validation-experiment.md](../docs/archive/investigations/trainer-validation-experiment.md) — Trainer validation experiment
+- [planning/chat-ui-vision-memory-first.md](../docs/archive/planning/chat-ui-vision-memory-first.md) — Chat UI Vision: The Model That Knows You
+- [planning/chat-ui-vision.md](../docs/archive/planning/chat-ui-vision.md) — The mlx-bun chat surface: a vision
+- [planning/chunk-task-roadmap.md](../docs/archive/planning/chunk-task-roadmap.md) — Chunk-task quality roadmap (2026-06-17)
+- [planning/curve-sampler-research-plan.md](../docs/archive/planning/curve-sampler-research-plan.md) — Curve sampler — preregistered research plan (distinctness track)
+- [planning/journal.md](../docs/archive/planning/journal.md) — Engineering Journal
+- [planning/memory-docs-and-dag-plan.md](../docs/archive/planning/memory-docs-and-dag-plan.md) — Memory docs organization + DAG-view refresh — review & plan
+- [planning/pi-integration-review.md](../docs/archive/planning/pi-integration-review.md) — pi integration review — internal embeds + `harness pi` (2026-07-01)
+- [planning/release-notes-v0.0.10.md](../docs/archive/planning/release-notes-v0.0.10.md) — mlx-bun v0.0.10 — batching parity, SSD KV cache, sharper serving
+- [planning/release-notes-v0.0.11.md](../docs/archive/planning/release-notes-v0.0.11.md) — v0.0.11 release notes
+- [planning/release-notes-v0.0.12.md](../docs/archive/planning/release-notes-v0.0.12.md) — v0.0.12 release notes
+- [planning/release-notes-v0.0.13.md](../docs/archive/planning/release-notes-v0.0.13.md) — v0.0.13 release notes
+- [planning/release-notes-v0.0.9.md](../docs/archive/planning/release-notes-v0.0.9.md) — v0.0.9 release notes (DRAFT — Josh edits + publishes)
+- [planning/release-notes-v0.2.0.md](../docs/archive/planning/release-notes-v0.2.0.md) — mlx-bun v0.2.0
+- [planning/web-ui-pass-plan.md](../docs/archive/planning/web-ui-pass-plan.md) — Web UI pass — ranked fix list (2026-07-01 audit)
+- [planning/website-readme-pass-plan.md](../docs/archive/planning/website-readme-pass-plan.md) — Website + README pass — audit findings and fix plan (2026-07-01)
+
+## docs/design/
+
+Active engineering design docs — one per topic; status lives in front matter + PLAN.md.
+
+- [batching.md](../docs/design/batching.md) — Batching — continuous scheduling for `--batch N`
+- [decode-speed-program.md](../docs/design/decode-speed-program.md) — Inference performance program
+- [dreaming-nightly-pipeline.md](../docs/design/dreaming-nightly-pipeline.md) — The Dreaming — memory write path + synthesis (canonical design)
+- [generic-model-support.md](../docs/design/generic-model-support.md) — Model support — run anything mlx-lm runs, and the ports we target
+- [kv-cache.md](../docs/design/kv-cache.md) — KV cache — residency and layout
+- [orpo-training.md](../docs/design/orpo-training.md) — Training — design (ORPO, flash-CCE head, prefix sharing, segmented backward)
+- [speculative-decoding.md](../docs/design/speculative-decoding.md) — Speculative decoding — one verifier, every draft source
+- [turboquant.md](../docs/design/turboquant.md) — TurboQuant — rotation-based quantization (KV leg landed, weights leg open)
+- [unified-engine-frontier-plan.md](../docs/design/unified-engine-frontier-plan.md) — Engine architecture — four layers, per-scheme oracles, one request path
+- [web-chat-redesign.md](../docs/design/web-chat-redesign.md) — Web chat — the built-in chat surface (canonical design)
+
+## docs/planning/
+
+Living product/vision docs (USING side).
+
+- [PRODUCT_ROADMAP.md](../docs/planning/PRODUCT_ROADMAP.md) — PRODUCT ROADMAP
+- [ResearchTopics.md](../docs/planning/ResearchTopics.md) — Research Topics
+- [release-notes-v0.3.0.md](../docs/planning/release-notes-v0.3.0.md) — mlx-bun v0.3.0
+- [video-series.md](../docs/planning/video-series.md) — mlx-bun video series
+
+## docs/reference/
+
+User-facing reference — the ONLY home for flags, routes, models, numbers, and environment facts.
+
+- [benchmarks.md](../docs/reference/benchmarks.md) — mlx-bun benchmark results (curated)
+- [cli.md](../docs/reference/cli.md) — CLI reference
+- [distribution.md](../docs/reference/distribution.md) — Distributing mlx-bun — build, sign, notarize, publish
+- [environment.md](../docs/reference/environment.md) — Reference environment and platform facts
+- [glossary.md](../docs/reference/glossary.md) — mlx-bun serving
+- [library-api.md](../docs/reference/library-api.md) — Library API
+- [memory.md](../docs/reference/memory.md) — Memory — the personal wiki
+- [models.md](../docs/reference/models.md) — Models: supported roster + management (get / scan / ls / gc)
+- [server-api.md](../docs/reference/server-api.md) — Server API
+- [server-config.md](../docs/reference/server-config.md) — Server configuration
+- [training.md](../docs/reference/training.md) — Training / fine-tuning reference
+- [troubleshooting.md](../docs/reference/troubleshooting.md) — Troubleshooting

package/docs/{design → archive}/hlg-sampling.md

@@ -1,6 +1,6 @@
 # HLG sampling — a piecewise tone curve on the logits
 
-Status: **implemented, found neutral, superseded by Curve Designer** — `applyHlg` shipped in `src/sampler.ts`; investigation found HLG a wash vs plain temperature; the Curve Designer (`src/curve-sampler.ts`) is its v2 replacement. See [docs/investigations/hlg-sampling-investigation.md](../investigations/hlg-sampling-investigation.md) for findings. This doc remains as the design rationale.
+Status: **implemented, found neutral, superseded by Curve Designer** — `applyHlg` shipped in `src/sampler.ts`; investigation found HLG a wash vs plain temperature; the Curve Designer (`src/curve-sampler.ts`) is its v2 replacement. See [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md) for findings. This doc remains as the design rationale.
 Owner: sampling layer (`src/sampler.ts`)
 Default: **off** (`--hlg-sampling off` = today's temperature sampler, untouched)
 
@@ -12,7 +12,7 @@ Default: **off** (`--hlg-sampling off` = today's temperature sampler, untouched)
 
 ## Outcome / Retrospective
 
-HLG was implemented through **Piece 2** (pure curve + neutrality tests + serial wiring, `applyHlg` live in `src/sampler.ts`). Evaluation found it **neutral vs plain temperature** — no measurable gain in diversity or quality at matched output entropy. As a result, HLG is **superseded by the Curve Designer** (`src/curve-sampler.ts`), which generalizes the same region-shaping idea with an editable control-point interface and cleaner UX. Full empirical findings are in [docs/investigations/hlg-sampling-investigation.md](../investigations/hlg-sampling-investigation.md).
+HLG was implemented through **Piece 2** (pure curve + neutrality tests + serial wiring, `applyHlg` live in `src/sampler.ts`). Evaluation found it **neutral vs plain temperature** — no measurable gain in diversity or quality at matched output entropy. As a result, HLG is **superseded by the Curve Designer** (`src/curve-sampler.ts`), which generalizes the same region-shaping idea with an editable control-point interface and cleaner UX. Full empirical findings are in [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md).
 
 The sections below (Goal through Correctness) remain as design rationale. Pieces 3–6 of Phasing and the Open Questions were never executed; see the [Phasing](#phasing-the-piece-n-increments) and [Open Questions](#open-questions--risks) sections for historical context.
 
@@ -347,4 +347,4 @@ for it. That a transfer function is standard practice in another domain says
 nothing about whether it helps token sampling — that is decided only by
 measurement (the KL characterization, the capability guardrail, and the
 diversity lens in [Correctness](#correctness--evaluation)). The full empirical
-write-up is in [docs/investigations/hlg-sampling-investigation.md](../investigations/hlg-sampling-investigation.md).
+write-up is in [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md).

package/docs/{design → archive/investigations}/audio-input-plan.md

@@ -210,7 +210,7 @@ All under `optiq/vlm/_mlxvlm/models/gemma4/` in the oracle venv:
 ### 3.4 Parity strategy (tree doctrine)
 
 Oracle = optiq internal gemma4 model in the pinned venv, driven by
-`scripts/regen-audio-goldens.py` (modeled on their calibration loader;
+`regen-audio-goldens.py (deleted; git history)` (modeled on their calibration loader;
 remember `enable_thinking` pinning for any templated prompt). Tiers follow
 the e4b vision precedent exactly:
 
@@ -238,7 +238,7 @@ Expectation (to be *measured*, not asserted): the tower is tiny —
 ≤750 mel frames → ~≤188 post-subsample positions × 12 layers × hidden
 1024 bf16 — so added TTFT should be dominated by CPU feature extraction
 plus one extra graph eval; sidecar RSS delta is the 752 bf16 tensors.
-Every number that gets quoted comes from preflight-gated `benchmark.sh`
+Every number that gets quoted comes from preflight-gated `scripts/bench-serve.ts all`
 cells (tower ms, TTFT delta vs text-only, peak RSS delta) and lands in
 `benchmarks/RESULTS.md`.
 
@@ -247,7 +247,7 @@ cells (tower ms, TTFT delta vs text-only, peak RSS delta) and lands in
 **Phase A0 — groundwork**
 - [ ] Bind `mlx_conv2d` (full header signature; CPU/GPU sanity test vs
       oracle conv output)
-- [ ] `scripts/regen-audio-goldens.py` + fixtures; dump mel golden,
+- [ ] `regen-audio-goldens.py (deleted; git history)` + fixtures; dump mel golden,
       tower-output golden, spliced ids, greedy ids
 - [ ] Resolve open questions §3.3 (write the answers into this doc)
 - Exit: goldens on disk; masking/zeroing semantics documented.
@@ -332,7 +332,7 @@ cells (tower ms, TTFT delta vs text-only, peak RSS delta) and lands in
       docs-map hygiene green. ✅ 2026-07-07
 
 **Phase A5 — bench + coverage**
-- [ ] benchmark.sh cells → RESULTS.md (tower ms, TTFT delta, RSS delta)
+- [ ] scripts/bench-serve.ts all cells → RESULTS.md (tower ms, TTFT delta, RSS delta)
 - [ ] 12B audio cell: rebuild its sidecar via optiq `build_vision_sidecar`
       (selective download), own goldens — per-model doctrine, every
       (model, quant) cell gets its own validation or an explicit deferral

package/docs/{design → archive/investigations}/colibri-glm52-port.md

@@ -692,7 +692,7 @@ batch.
 
 G0 inventory note (2026-07-21): the exact pin, artifact/layout contract, and
 manual checklist are recorded in
-[`../investigations/colibri-oracle-pin.md`](../investigations/colibri-oracle-pin.md).
+[`../archive/investigations/colibri-oracle-pin.md`](../archive/investigations/colibri-oracle-pin.md).
 Because the pinned Makefile writes ignored build artifacts and even creates a
 configuration stamp while parsing, model-free oracle targets must run from a
 temporary `git archive` extraction, not in the read-only checkout. The pinned

package/docs/{design → archive/investigations}/diffusion-gemma-port.md

@@ -120,7 +120,7 @@ tied 4-bit head → fp32 softcap** — is **BIT-EXACT vs the optiq golden**: arg
 maxDiff 0.0, relRMSE 0.0, meanKL 0.0 (`tests/diffusion-parity.test.ts`,
 `MLX_BUN_TEST_DIFFUSION=1`). Per-stage sub-gates (enc_hidden / dec_hidden / presoftcap /
 per-layer / layer-0 attn·dense·MoE) all 0.0 (`scripts/experiments/diffusion-{stage,layer,l0}-diag.ts`,
-golden dumps in `scripts/gen-diffusion-golden.py`).
+golden dumps in `scripts/oracle/gen-diffusion-golden.py`).
 - **The one bug found + fixed (per-model parity gotcha):** the Router pre-projection
   norm must be the literal two-step `rms_norm(x, None, eps) * scale * hidden**-0.5`,
   **NOT** the gemma4-style fold `rms_norm(x, scale*hidden**-0.5)`. The fold changes the
@@ -152,7 +152,7 @@ reuse, linear temp schedule, the un-mask loop, BOTH samplers (confidence-thresho
 OptiQ public default, entropy-bound = engine default), self-conditioning feedback,
 stability/EOS, canvas block loop. **Token-for-token parity vs the optiq engine at
 temp 0 on a fixed seed for BOTH samplers** (`tests/diffusion-gen-parity.test.ts`,
-`MLX_BUN_TEST_DIFFUSION=1`; golden `scripts/gen-diffusion-gen-golden.py`):
+`MLX_BUN_TEST_DIFFUSION=1`; golden `scripts/oracle/gen-diffusion-gen-golden.py`):
 confidence 17 tok / 7 steps, entropy 15 tok / 48 steps — both `.tokens`/`.steps`/
 `.finishReason` identical.
 - **RNG parity (the crux) SOLVED:** bound `mlx_random_randint` (+`mlx_random_seed`,
@@ -241,7 +241,7 @@ output matches optiq `generate`; HTTP test green; no regression to AR models.
 
 ### D4 — Performance (L3, optional, measured) `[ ]`
 `confidence-threshold` is already the fast path (optiq: ~58 tok/s code / ~9
-prose). Measure mlx-bun tok/s with `benchmark.sh`; fuse kernels only if a number
+prose). Measure mlx-bun tok/s with `scripts/bench-serve.ts all`; fuse kernels only if a number
 says so. KV holds only the prompt (no per-step growth → no KV-quant needed).
 **Exit:** quotable tok/s within range of optiq on this machine; any fused kernel
 gated by KL + the 6-task quality suite (no bit-exact ancestor for novel fusions).

package/docs/{design → archive/investigations}/faithful-l1-consolidation.md

@@ -275,13 +275,13 @@ kernels, selected (or not) by the individual flags.
 ### Phase 4 — Docs + benchmark ✅ LANDED 2026-07-04 (numbers Josh-gated)
 
 Docs updated: `features-matrix.md` (new `--compiled-activations` + `--fused-gelu`
-rows), `server-config.md` + `cli.md` (Phase 2). Reworked `scripts/bench-faithful-matrix.ts`
-+ `benchmark.sh` comparison 0 for the new model — since faithful is now the default,
+rows), `server-config.md` + `cli.md` (Phase 2). Reworked `scripts/bench-levers.ts faithful-matrix`
++ `scripts/bench-serve.ts all` comparison 0 for the new model — since faithful is now the default,
 the matrix measures what **removing** each faithful kernel costs and what the L3
 custom kernels add on top (`− compiled-decode`, `− compiled activations`,
 `+ custom fused-gelu`), all vs mlx-lm; tsc 0. **The actual numbers are Josh-gated**
-(clean/rebooted machine — `./benchmark.sh --redo`, or
-`bun scripts/bench-faithful-matrix.ts`); loaded-machine absolutes are noise. Promote
+(clean/rebooted machine — `bun scripts/bench-serve.ts all --redo`, or
+`bun scripts/bench-levers.ts faithful-matrix`); loaded-machine absolutes are noise. Promote
 quotable rows to `benchmarks/RESULTS.md` after the clean run.
 
 ## Status: consolidation complete

package/docs/{investigations → archive/investigations}/hlg-sampling-investigation.md

@@ -3,7 +3,7 @@
 *2026-06-14. Question: can the structure of a piecewise nonlinear transfer
 function (HLG, the HDR transfer function) be transplanted onto a logit
 distribution as a sampling method, and if so, where do you place its pivot
-(middle grey)? Design contract: [docs/design/hlg-sampling.md](../design/hlg-sampling.md).
+(middle grey)? Design contract: [docs/archive/hlg-sampling.md](../design/hlg-sampling.md).
 Code: `src/sampler.ts` (`applyHlg`, `makeSampler`). Harness:
 `scripts/hlg-compare.ts`. Model under test: `gemma-4-e4b-it-OptiQ-4bit` on the
 M4 Pro.*

package/docs/{design → archive/investigations}/minicpm5-decode-megakernel.md

@@ -108,7 +108,7 @@ a 1-token parity probe before trusting it (Phase 2 gate catches mismatch).
 **Validation goldens (ALREADY EXIST, no regen needed):**
 - L1: `goldens/minicpm5-parity.json` (prompt_ids `[0,608,4894,304,6918,357]`,
   greedy_ids[100], vocab 130560) + `goldens/minicpm5-logits-step{0..99}.bin`
-  (f32 last-position logits). Produced by `scripts/regen-minicpm5-goldens.ts`.
+  (f32 last-position logits). Produced by `scripts/regen.ts minicpm5`.
 - L2: `goldens/minicpm5-kv-parity.json` + `…-kv-logits-step*.bin`.
 
 **Reference forward to copy (the source of truth for correctness):**
@@ -132,7 +132,7 @@ All default-OFF, `bun test tests/minicpm5-*.test.ts` green. From this session:
   @ M=8–256, ~1 ULP correct.** This is a working prototype of one megakernel STAGE
   and the dequant/GEMV patterns to copy. (Note: it currently corrupts when CHAINED
   in the lazy graph — that's the whole reason for the megakernel; the kernel math
-  itself is correct, proven by `scripts/experiments/fused-mlp-check.ts`.)
+  itself is correct, proven by `fused-mlp-check.ts (deleted; git history)`.)
 - `src/model/steel-linear-kernel.ts` — `steelLinear`: plain quantized linear as our
   dispatch (q/k/v/o/down), ~1 ULP vs `ops.quantizedMatmul`. The projection GEMV
   pattern.
@@ -232,7 +232,7 @@ megapack-check.ts`.) This catches layout bugs before any kernel.
 
 ### Phase 2 — Single-threadgroup correct megakernel (G=1)
 **Files:** `src/model/megakernel-kernel.ts` (the `MetalKernel` + dispatch),
-`scripts/gen-minicpm5-megakernel.ts` (emits the per-layer-bits-baked SOURCE into
+`gen-minicpm5-megakernel.ts (deleted; git history)` (emits the per-layer-bits-baked SOURCE into
 `src/model/generated/minicpm5-megakernel.ts`).
 **Design:** ONE threadgroup (`G=1`, `TGN=256` threads). `hidden[H]` in threadgroup
 memory (6 KB). Loop layers; each stage uses `threadgroup_barrier`. GEMVs: the 256
@@ -246,13 +246,13 @@ down). KV read/write from `KBUF`/`VBUF`. Final: finalNorm + lmHead GEMV → logi
 **Transcribe** `src/model/minicpm5.ts` op-for-op; match dtypes: accumulate in f32,
 round to bf16 at each op boundary to track the reference (`(T)` casts, as `fusedMlp`
 does). RoPE: match `ops.rope` exactly (verify with a single-layer probe).
-**Gate (THE correctness gate):** `scripts/experiments/megakernel-teacherforced.ts`
+**Gate (THE correctness gate):** `megakernel-teacherforced.ts (deleted 2026-08-23; git history)`
 (copy `swiglu-teacherforced.ts`): drive 100 decode steps via the megakernel,
 teacher-forced on `goldens/minicpm5-parity.json`, KV cache in `KBUF`/`VBUF`. Require
 **≥98/100 argmax agreement, deterministic across 3 runs, no NaN.** If an early step
 mismatches, bisect by stage: add a debug output for `hidden` after layer L (env
 `MLX_BUN_MEGA_DUMP_LAYER=L`) and compare to the reference model's per-layer hidden
-(capture via the wrapper trick in `scripts/experiments/swiglu-layerN.ts`).
+(capture via the wrapper trick in `swiglu-layerN.ts (deleted; git history)`).
 
 ### Phase 3 — Persistent multi-threadgroup (G>1) for SPEED
 **Do:** generalize Phase 2 to `G` threadgroups. Move `hidden`,`xn`,`hn`,`q/k/v/attn/
@@ -332,7 +332,7 @@ Swap `KBUF/VBUF` for the per-layer quantized-KV format. **Facts gathered:**
   q = min(round((w-bias)/scale), n_bins)     // dequant: scale*q+bias
   ```
 **Implementation steps:**
-1. ✅ **DONE — quantize formula validated** (`scripts/experiments/kv-quant-formula-check.ts`):
+1. ✅ **DONE — quantize formula validated** (`kv-quant-formula-check.ts (deleted 2026-08-23; git history)`):
    the affine_quantize transcription matches `ops.quantize` to bf16 ULP (scale/bias diff
    1.8e-3 @4-bit, 6e-5 @8-bit; dequant residual = expected bf16-storage rounding). The
    riskiest piece is de-risked. Compute scale/bias in f32, store bf16 (as mlx does).
@@ -411,7 +411,7 @@ Guard: bf16 KV (L1) only, no adapters, no vision. Add `--megakernel` CLI flag.
 of the old `tests/perf-kernel-oracle.test.ts` — deleted 2026-07-05 with its kernel,
 unified-engine-frontier-plan.md §6; the envelope-gate methodology stands on its
 own); paired decode tok/s A/B logged. Update
-`STATUS.md` + `benchmarks/RESULTS.md` (preflight-gated `benchmark.sh` for the
+`STATUS.md` + `benchmarks/RESULTS.md` (preflight-gated `scripts/bench-serve.ts all` for the
 quotable number — `[[dirty-machine-numbers-are-garbage]]`).
 
 ---
@@ -462,12 +462,12 @@ so its 1-ULP/op drift is within contract — bit-exact is a focused REBUILD, not
 
 ```
 src/model/megakernel-pack.ts            # Phase 1: weight repack + layout table
-scripts/gen-minicpm5-megakernel.ts      # Phase 2: emit per-layer-baked kernel SOURCE
+gen-minicpm5-megakernel.ts (deleted; git history)      # Phase 2: emit per-layer-baked kernel SOURCE
 src/model/generated/minicpm5-megakernel.ts   # (generated) the kernel SOURCE + bits
 src/model/megakernel-kernel.ts          # Phase 2/3: MetalKernel + decodeMegakernel()
-scripts/experiments/megapack-check.ts        # Phase 1 gate
-scripts/experiments/megakernel-teacherforced.ts  # Phase 2/3 correctness gate
-scripts/experiments/megakernel-perf.ts       # Phase 3/5 paired tok/s A/B
+megapack-check.ts (deleted 2026-08-23; git history)        # Phase 1 gate
+megakernel-teacherforced.ts (deleted 2026-08-23; git history)  # Phase 2/3 correctness gate
+megakernel-perf.ts (deleted 2026-08-23; git history)       # Phase 3/5 paired tok/s A/B
 tests/minicpm5-megakernel.test.ts       # Phase 5 CI gate (env-gated)
 ```
 Modify: `src/model/minicpm5.ts` (add `decodeStep` megakernel branch),

package/docs/{design → archive/investigations}/optimization_plan.md

@@ -39,7 +39,7 @@ chasing host overhead that compile already removed.
 
 **Steps:**
 
-1. **Characterize before touching anything.** Run `scripts/decode-split.ts`
+1. **Characterize before touching anything.** Run `decode-split.ts (deleted; git history)`
    (the per-step wall-time splitter that already exists) on all three models at
    @600 and @8k. Record GPU-blocked time vs JS-graph-build time per step. This
    is the control measurement; everything in Phase A is judged against it. The

package/docs/archive/investigations/pareto-specialized-runtime-findings.md

@@ -0,0 +1,92 @@
+# Pareto-specialized runtime findings
+
+## Question
+
+Which parts of mlx-bun should converge on shared infrastructure, and which parts should remain deliberately specialized so cleanup does not turn the runtime into a lowest-common-denominator model host?
+
+This note compares three mature specialization clusters: the Colibri/GLM-5.2 runtime, the Qwen3.8 27B TurboQuant and MTP work, and ORPO training. The evidence says the same thing in all three places: share lifecycle and composition policy, but keep artifact layout and numerical work close to the model or method that owns them.
+
+## Shared control-plane infrastructure
+
+The shared layer decides what runs, owns resources, and records what happened. It does not rewrite the selected computation.
+
+- **Model construction.** `openModel()` recognizes the direct Colibri artifact before ordinary safetensors loading. `createModel()` prefers dedicated and fingerprint-generated model classes before the universal fallback, and explicitly says the generic path must not shadow a dedicated port. This is shared dispatch with specialized implementations, not one universal graph. [Factory dispatch](../../../src/model/factory.ts#L30-L150)
+- **Concurrency and request composition.** The target is one concurrency-driven engine. One active request uses the B=1 pipelined or compiled fast path; concurrent requests use the general step up to `--batch N`. B=1 is an internal specialization, not a permanent public lane. Features are stackable layers, and scheduling must not replace the selected KV scheme, adapter, draft method, grammar, or sampler. [Unified engine decision](../../design/unified-engine-frontier-plan.md#L333-L403) [Composition matrix](../../design/unified-engine-frontier-plan.md#L405-L424)
+- **Cache lifecycle and capability.** `Cache` owns update, masks, state, rollback, accounting, and disposal. `BatchableCache` adds row merge, extraction, filtering, and byte projection. The scheduler can depend on those capabilities without knowing whether a row contains ordinary KV, recurrent state, TurboQuant tensors, or compressed GLM state. [Cache interface](../../../src/model/gemma4-base.ts#L264-L303) [Batchable cache interface](../../../src/model/gemma4-base.ts#L347-L357)
+- **Resolved KV policy.** `KvScheme` preserves bf16, uniform affine, per-layer affine, and TurboQuant as distinct immutable schemes. It centralizes names, accounting, and current batch capability checks without pretending the schemes have identical storage or kernels. [KV scheme](../../../src/kv-scheme.ts#L84-L169)
+- **Draft lifecycle.** `DraftProvider` owns server-lifetime machinery and opens a request-scoped `DraftSource`. The source interface carries prompt mode, target taps, draft, commit, rollback-related cache state, and disposal. Assistant, DSpark, Qwen MTP, and native GLM MTP can share speculative orchestration while retaining different state transitions. [Draft source](../../../src/spec/source.ts#L31-L101) [Draft provider](../../../src/spec/source.ts#L103-L118)
+- **Expert residency policy.** The budget equation, stable expert union, lease state, backend contract, telemetry, and pressure correction are reusable. GLM supplies artifact geometry and byte segments to that policy. [Residency planning and union](../../../src/expert-residency.ts#L17-L155) [Residency backend](../../../src/expert-residency.ts#L157-L170)
+- **Offline transform orchestration.** `WeightTransform` separates name/config planning from lazy tensor application. Llama, the Qwen3.5 trunk, and Qwen MTP are real adapters over the same conversion seam. [Weight transform interface](../../../src/quantize/weight-transform.ts#L40-L51) [Qwen transform adapters](../../../src/quantize/weight-transform.ts#L244-L268)
+- **Training orchestration.** `TrainConfig` names independent techniques such as segmented backward, fused or flash CCE, prefix sharing, regularization, and ORPO semantics. `orpoLoop()` composes the selected techniques and chooses the model-specific backward implementation. [Training configuration](../../../src/train/trainer.ts#L42-L150) [ORPO composition](../../../src/train/trainer.ts#L821-L948)
+
+## Deliberately specialized data-plane code
+
+### Colibri and GLM-5.2
+
+GLM-5.2 is not a descriptor-table variation of a dense transformer. Its graph has MLA, DSA, shared plus routed MoE, native MTP, and compressed cache state. Its public artifact also has a dedicated container and streamed expert layout. The design therefore calls for a dedicated `Glm52Model`, direct artifact support, and a one-read routed-expert kernel rather than repacking into generic projection-major tensors. [Dedicated graph and artifact contract](../../design/colibri-glm52-port.md#L323-L357)
+
+The memory contract is also model and artifact specific. A header-only preflight reads the container, derives expert slot layouts, counts DSA and MTP state, and refuses startup when the exact resident weights, expert slabs, compressed KV, verification transients, allocator reserve, Bun reserve, and safety margin exceed the process limit. [GLM geometry and preflight](../../../src/model/glm52-memory.ts#L340-L500) The runtime then maps Colibri segments into generic residency leases, but retains GLM-specific slot layouts, MTP slabs, signed-int8 requirements, and routed-SwiGLU executors. [GLM residency binding](../../../src/model/glm52-residency.ts#L138-L230) [GLM executor construction](../../../src/model/glm52-residency.ts#L300-L459)
+
+That split is intentional. Bun owns residency policy and observability; the native helper owns aligned slabs, `pread`, wiring, and completion fences; the GLM model owns tensor semantics and kernels. [Ownership map](../../design/colibri-glm52-port.md#L580-L600)
+
+### Qwen3.8 27B, TurboQuant, and MTP
+
+Qwen3.5/3.8 keeps a dedicated graph because gated DeltaNet recurrence, full attention, MRoPE, output gates, and recurrent speculative rollback are numerical behavior, not configuration decoration. [Qwen graph](../../../src/model/qwen3_5.ts#L128-L322) [Qwen model interface](../../../src/model/qwen3_5.ts#L512-L673)
+
+Qwen MTP preserves its own artifact and state machine behind `DraftProvider` and `DraftSource`. The provider rejects a non-Qwen target or a hidden-size mismatch. The request source uses tapped pre-final-norm target state, maintains its own KV, samples through the target sampler, and rebuilds accepted rows from verified target hiddens. Those rules must not move into generic speculative orchestration. [Qwen MTP provider](../../../src/spec/qwen-mtp-source.ts#L193-L235) [Qwen MTP state machine](../../../src/spec/qwen-mtp-source.ts#L237-L430)
+
+TurboQuant KV demonstrates the right form of specialization. `TurboQuantKVCache` implements the shared `Cache` lifecycle, while keeping packed indices, scales, zero points, FWHT-domain values, supported head dimensions, and conversion rules inside the class. [TurboQuant cache](../../../src/model/gemma4-base.ts#L1539-L1800) The weight pipeline follows the same rule. `WeightTransform` is shared, but the Qwen corridor map preserves the output gate, recurrent internals, vision-to-residual seam, untied 27B head, and companion MTP basis. [Qwen transform seam](../../design/turboquant-weights.md#L80-L87) [Qwen corridor map](../../design/turboquant-weights.md#L125-L174)
+
+### ORPO training
+
+ORPO benefits from composition, not one generic backward. The trainer combines prefix sharing, segmented recomputation, fused or flash CCE, LoRA regularization, and objective semantics. The data plane remains specialized where the model topology demands it. Gemma4 segmented ORPO threads per-layer inputs and cross-segment donor KV cotangents; MiniCPM5 uses a simpler segment graph. [Composed ORPO paths](../../design/orpo-training.md#L178-L218) [Gemma4 segmented backward](../../../src/train/segmented.ts#L1137-L1471)
+
+Flash CCE is a shared quantized-head interface with specialized Metal kernels and explicit shape guards. Its implementation selects Steel, simdgroup, or scalar kernels from actual hidden, vocabulary, group, and tile geometry, and exposes exact-gradient escape hatches. Flattening this into a generic matrix-loss helper would lose the memory and watchdog constraints that justify it. [Flash CCE head](../../../src/train/flash-cce.ts#L42-L64) [Forward dispatch](../../../src/train/flash-cce.ts#L1033-L1132) [Backward dispatch](../../../src/train/flash-cce.ts#L1134-L1234)
+
+Dynamic lambda is not implemented. Its design belongs in the ORPO control plane: validation metrics update a live lambda source in `orpoLoop()`, while every monolithic and segmented loss reads the same value. It should not create another family of backward classes. [Dynamic-lambda status and signals](../../design/orpo-dynamic-lambda.md#L1-L27) [Proposed wiring](../../design/orpo-dynamic-lambda.md#L163-L180)
+
+## Interfaces that already preserve specialization
+
+| Interface | Shared invariant | Specialization retained behind it |
+|---|---|---|
+| `RuntimeModel` plus factory dispatch | Construction and serving can hold one model type | Dedicated GLM, Qwen, Gemma, diffusion, MoE, and generated graphs |
+| `Cache` / `BatchableCache` | Lifecycle, rollback, row operations, byte projection | Plain, rotating, quantized, TurboQuant, SSM, MLA, and DSA storage |
+| `KvScheme` | One resolved KV choice and stable identity | Per-scheme accounting, conversion, persistence, and kernels |
+| `DraftProvider` / `DraftSource` | Request lifecycle, target taps, draft and commit | Assistant, DSpark, Qwen MTP, and GLM MTP state machines |
+| `ExpertResidencyBackend` | Lease and I/O lifecycle | Colibri container offsets, slot packing, expert kernels, and prediction policy inputs |
+| `WeightTransform` | Plan first, apply lazily, record identity | Family-specific exact fold corridors and companion artifacts |
+| ORPO trainer configuration | One run composes selected techniques | Model-specific masks, donor topology, VJPs, and Metal kernels |
+
+## Declared profile seam (S2, 2026-08-21)
+
+Model construction now resolves one `ResolvedModelProfile` before opening
+weights. An exact artifact declaration binds an immutable external fingerprint,
+config fingerprint, fidelity contract, required engine capabilities, and a
+loader/graph/loop composition. Exact Qwen3.8 OptiQ and GLM-5.2 Colibri revisions
+are pinned; other supported artifacts retain dedicated family resolution and
+then the universal dense fallback.
+
+The factory consumes the resolved composition, and the serving context retains
+it for library callers. A matched exact declaration with a config or capability
+mismatch refuses rather than taking another route. The profile seam does not
+own request methods: MTP, KV schemes, adapters, grammar, and sampling remain
+independently resolved inputs to completion execution. This keeps the control
+plane declarative without turning a model profile into a feature preset.
+
+These interfaces preserve specialization because they describe lifecycle or capability, not tensor algebra. They also have multiple real implementations. That is the useful test for whether an abstraction belongs.
+
+## Rules for steady-state cleanup
+
+1. **Unify control, not math.** Centralize admission, concurrency, cancellation, ownership, accounting, persistence, telemetry, and technique composition. Keep tensor layout, recurrence, cache encoding, model topology, and kernel selection with their owning model, artifact, or method.
+2. **Keep one concurrency-driven engine.** B=1 and B>1 are internal step specializations in one engine. `--batch N` is a concurrency cap. Observed placement may be reported, but serial versus batch must not become a permanent public mode or feature-selection interface. Current feature-specific serial routing is capability debt.
+3. **Never weaken a resolved composition to fit a path.** If batching lacks TurboQuant, MTP, adapters, grammar, or another selected method, close that capability gap or reject the unsupported composition. Do not silently substitute bf16 KV, disable drafting, or change sampling.
+4. **Prefer capability interfaces over family checks.** Scheduling should ask caches whether they can merge or project bytes and draft sources what target state they require. Factory dispatch is the proper place for model identity checks.
+5. **Let dedicated ports outrank generic fallbacks.** The universal model path is valuable for ordinary architectures. It must not absorb GLM MLA/DSA, Qwen recurrence, artifact-specific MTP, or another optimized graph merely to reduce class count.
+6. **Treat artifacts as executable contracts.** Validate manifests, tensor families, layouts, quantization metadata, companion seeds, and memory equations before allocation. Keep artifact-specific loaders and transforms when repacking would add copies, lose reproducibility, or change arithmetic.
+7. **Generalize only after the invariant is visible in two implementations.** Extract lifecycle and capability seams such as `DraftSource` or `WeightTransform`. Do not extract a common tensor algorithm from code that only looks similar but has different masks, state, accumulation order, or oracle.
+8. **Compose optimizations at the orchestrator, then test the cross-product.** ORPO proves that prefix sharing, flash CCE, segmented backward, and regularization can stack while model-specific backward code remains intact. Serving needs the same discipline for model graph, KV scheme, MTP, adapters, grammar, sampling, and concurrency.
+9. **Bind every specialized path to its own oracle and measured purpose.** A specialized module earns its place through parity, memory, quality, or throughput gates on the artifact and hardware it targets. If the benefit disappears, delete the specialization instead of preserving it as architecture folklore.
+
+## Strongest conclusion
+
+The steady state is not a generic engine with scattered exceptions. It is a shared control plane that carries authoritative compositions through one concurrency-driven engine, plus specialized data planes selected by model, artifact, and numerical method. That structure preserves the project's Pareto advantage: common serving and training behavior where sameness is real, and unapologetically specific code where the result depends on it.

package/docs/{design → archive/investigations}/pre-colibri-stabilization.md

@@ -96,7 +96,7 @@ change that state.
 | LEAK-03 | P2 | fixed | `src/mlx/{autograd,checkpoint,custom-vjp}.ts` constructors | Failure out-parameter slots are initialized with live handles that may not be freed when native constructor calls fail. | Failure-injection tests for all three constructors prove slots, closures, and callbacks return to baseline with no double free. |
 | HYG-01 | P2 | fixed | `src/train/job.ts`, empty Gemma block | A config read and stale comment claim load-bearing environment setup, but the branch is empty. | Remove the read/block/comment; job parsing and training setup tests stay green. |
 | HYG-02 | P2 | fixed | `tsconfig.json` exclusions | Shipped web sources and tests that run in the gate are excluded from the zero-error typecheck contract. | Remove the exclusions or replace them with an explicit checked project reference; repository and web typechecks are green with no hidden files. |
-| HYG-03 | P2 | fixed | `scripts/test.sh` test glob | `scripts/bench-serving-load.test.ts` is model-free but outside the gate. | Gate enumerates and runs it exactly once; a sentinel/failing-case check proves it cannot silently fall out again. |
+| HYG-03 | P2 | fixed | `scripts/test.sh` test glob | `tests/bench-serving-load.test.ts` is model-free but outside the gate. | Gate enumerates and runs it exactly once; a sentinel/failing-case check proves it cannot silently fall out again. |
 | SEC-01 | P0 | fixed | `src/web-tools.ts`, `web_fetch` | Model-selected URLs bypass the existing public-destination policy, follow redirects automatically, and buffer the full body. This permits SSRF into loopback/private services and unbounded response buffering. | Reuse one shared fetch-policy implementation: reject private literals and DNS resolutions, revalidate every redirect, combine caller abort with timeout, and stream to a byte cap. Tests cover loopback, private DNS, public-to-private redirect, redirect limit, chunked over-cap, and normal public text. |
 | SEC-02 | P1 | fixed | `src/download.ts`, `blobId` | An unvalidated blob ID reaches `join()` and symlink creation, unlike the adjacent validated digest. It requires a hostile HF-compatible endpoint. | Reject any non-lowercase-40-hex SHA-1 blob ID before path construction; traversal and malformed-ID tests fail closed. |
 | DEPLOY-01 | D | deferred | `src/server.ts`, WebSocket upgrade | No WebSocket Origin enforcement. | Deferred while bind is loopback-only. Reopen before any supported non-loopback bind, tunnel, reverse proxy, or browser origin; then add an allowlist and cross-origin rejection tests. |
@@ -127,7 +127,7 @@ change that state.
   transform constructors return slots, closures, and callbacks to zero under
   repeated failure injection. The root typecheck now includes DOM/web sources
   and the formerly excluded web tests. `scripts/test.sh` enumerates
-  `scripts/bench-serving-load.test.ts` exactly once and rejects gate drift.
+  `tests/bench-serving-load.test.ts` exactly once and rejects gate drift.
 - `bunx tsc --noEmit`, `bun scripts/check-hygiene.ts`, `bash -n
   scripts/test.sh`, and `git diff --check` are green after Wave 3. The full
   post-Wave-3 repository gate and both performance measurements remain open.
@@ -140,7 +140,7 @@ change that state.
   Standard PEFT `use_rslora` now mounts and saves at exactly
   `alpha / sqrt(rank)`. Custom-VJP also frees the first callback if allocation
   of the second callback throws.
-- **PERF-01:** `scripts/bench-stream-decoder.ts` measured the original
+- **PERF-01:** `bench-stream-decoder.ts (deleted 2026-08-23; git history)` measured the original
   full-history decoder against the bounded exact-suffix implementation with
   five paired repetitions. MiniCPM5 medians were 142.62 → 27.40 ms at 512
   tokens (5.20×), 576.01 → 56.45 ms at 1,024 (10.20×), and 2,284.57 →
@@ -148,7 +148,7 @@ change that state.
   113.62–116.06 ms). Every per-push chunk and final byte stream matched at
   64–2,048 tokens; the e4b 1,024-token check was 88.62 → 10.25 ms. Raw,
   gitignored artifacts are under `reports/perf-01-stream-decoder-*.json`.
-- **PERF-02:** `scripts/bench-logprobs-readback.ts` confirmed the reported
+- **PERF-02:** `bench-logprobs-readback.ts (deleted 2026-08-23; git history)` confirmed the reported
   barrier on a clean M1 Max 32 GB with Bun 1.3.14 and
   Qwen2.5-0.5B-Instruct-4bit (256 tokens, two warmups, five measured rounds).
   At clean base `00e597e`, off/logprobs/top-5 medians were
@@ -302,7 +302,7 @@ after any overlapping merge.
 | Adapters/training | `tests/{lora,train-*,ifeval}.test.ts`; delayed writes, PEFT + mlx-lm layouts, unequal padding, optimizer LR scales, frozen scorer corpus |
 | Grammar/Responses store | `tests/{grammar,grammar-jump,responses,server}.test.ts`; degrade forms, top-logprob alignment, fake-clock reordered LRU |
 | MLX/resource ownership | focused diffusion/weights/autograd/checkpoint/custom-VJP failure loops with handle/allocation baselines |
-| Repository gate | `bun scripts/check-hygiene.ts`, `bunx tsc --noEmit`, `bash scripts/test.sh`; prove `scripts/bench-serving-load.test.ts` is included |
+| Repository gate | `bun scripts/check-hygiene.ts`, `bunx tsc --noEmit`, `bash scripts/test.sh`; prove `tests/bench-serving-load.test.ts` is included |
 | Performance | deterministic raw artifact, paired A/B, exact output parity, quiet-machine preflight before any curated claim |
 
 ## 8. Exit gate

package/docs/{design → archive/investigations}/the-dreaming-handoff.md

@@ -21,7 +21,7 @@ cross-linked, self-healing personal wiki. It **works end-to-end on real data.**
 ```
 # resumable driver; continues from cursor 720. Writes to ~/.mlx-bun/wiki-full (NOT the
 # real vault ~/.mlx-bun/wiki). ~25 min / 20-conv batch, ~50h total, SERIAL.
-bun scripts/experiments/dreaming-full-run.ts          # resume (clean-slate guarded by an init flag)
+bun scripts/memory/dreaming-full-run.ts          # resume (clean-slate guarded by an init flag)
 # state files: ~/.mlx-bun/full-run-cursor.txt, ~/.mlx-bun/full-run-initialized, ~/.mlx-bun/full-run.log
 # after the import finishes: reindex, then connect the graph:
 mlx-bun memory link
@@ -78,7 +78,7 @@ RECONCILE (infobox-ground-truth consistency) → LINK (cross-link) → WIKIFY (e
    to the latest value; KEEPS the trajectory in a `## History` section **only for the
    USER's evolving positions** — an AI *factual error* is silently overwritten (no
    history). Date-aware; `reconcile.ts` is the consistency authority (infobox = ground
-   truth). Proven via a timestamp-swap demo (`scripts/experiments/dreaming-selfheal-demo.ts`).
+   truth). Proven via a timestamp-swap demo (`scripts/memory/dreaming-selfheal-demo.ts`).
 6. **Parroting (recurred 5×).** The small model copies ANY concrete example value from
    prompts/Meta pages into unrelated articles (phantom S5IIX, "Anamorphic Video", etc.).
    **ALL prompts + Meta pages must be SCHEMATIC** (no real names/specs/dates). Purged;

package/docs/{planning → archive/planning}/chat-ui-vision.md

@@ -1,6 +1,6 @@
 # The mlx-bun chat surface: a vision
 
-*Draft vision, product/design lead pass — 2026-07-06. Bold stance: reimagine the chat surface from scratch. Companion to the market research and current-state audit that produced it; see `docs/planning/web-ui-pass-plan.md` for the tactical bug list and `docs/design/adapters-end-to-end.md` / `docs/design/memory-system.md` for the backend contracts this vision assumes.*
+*Draft vision, product/design lead pass — 2026-07-06. Bold stance: reimagine the chat surface from scratch. Companion to the market research and current-state audit that produced it; see `docs/archive/planning/web-ui-pass-plan.md` for the tactical bug list and `docs/design/adapters-end-to-end.md` / `docs/design/memory-system.md` for the backend contracts this vision assumes.*
 
 ## The feeling
 

package/docs/{planning → archive/planning}/chunk-task-roadmap.md

@@ -2,7 +2,7 @@
 
 Where the MiniCPM5 chunking adapter stands and what raises real segmentation
 quality. Companion to the chunk-eval metric vs. accuracy finding (score = well-formedness, not gold accuracy) and
-[`docs/investigations/chunk-finetune-experiment.md`](../investigations/chunk-finetune-experiment.md).
+[`docs/archive/investigations/chunk-finetune-experiment.md`](../investigations/chunk-finetune-experiment.md).
 
 ## Where we are
 

package/docs/{planning → archive/planning}/curve-sampler-research-plan.md

@@ -250,8 +250,8 @@ diversity; the audit below as methods material).
 
 ## 6. Why the old data is not trusted — audit of the prior experiments
 
-Committed artifacts checked: `docs/investigations/curve-runs/*.json`,
-`docs/investigations/hlg-runs/*`, harness sources. Severity: **INVALIDATES** /
+Committed artifacts checked: `docs/archive/investigations/curve-runs/*.json`,
+`docs/archive/investigations/hlg-runs/*`, harness sources. Severity: **INVALIDATES** /
 **WEAKENS** / cosmetic.
 
 - **F1 — INVALIDATES (the old distinctness claim).** The curve-temp family
@@ -327,5 +327,5 @@ Committed artifacts checked: `docs/investigations/curve-runs/*.json`,
 - Witness probe: `scripts/experiments/curve-distinctness.ts`.
 - Assessment: `reports/curve-designer-paper-assessment-2026-07-01.md`.
 - Prior investigations (superseded on the points in §6):
-  `docs/investigations/hlg-sampling-investigation.md`,
-  `docs/investigations/curve-bisector-routing.md`.
+  `docs/archive/investigations/hlg-sampling-investigation.md`,
+  `docs/archive/investigations/curve-bisector-routing.md`.

package/docs/{planning → archive/planning}/memory-docs-and-dag-plan.md

@@ -21,7 +21,7 @@ are treated as the direction of record and untouched.
 | `docs/design/bucketing-stage.md` | Classify-stage design (2026-06-26) | **No banner.** Core content (embeddings as candidate-narrower) is dead under "no embeddings anywhere"; the binary-question ladder survives inside the nightly BUCKET stage | **Needs a SUPERSEDED banner** (same shape as memory-synthesis's): dead = embedding narrower + silhouette; survives = capacity-by-decomposition, one-binary-question-at-a-time. |
 | `docs/design/write-pipeline-entity.md` | Entity-keyed routing design (2026-06-26); itself "supersedes bucket-centric routing" | **No banner.** Half-dead: pure entity ROUTE (no bucket layer) is replaced by BUCKET→RESOLVE; the personal-notability checklist is dead. Survives: articles-are-THINGS, name/alias/category lookup, no-embeddings routing | **Needs a PARTIALLY SUPERSEDED banner** mapping survives/dead — otherwise its own "supersedes bucketing" claim inverts the actual chain for a newcomer. |
 | `docs/design/memory-system.md` | M0 substrate design (vault, read tools, CLI, scheduling, consent) | **Status header is FALSE**: "synthesize is currently a safe no-op stub", "stage modules throw if called" — the pipeline is built and has produced 677+ articles. Directly contradicts `docs/reference/memory.md`. The four-adapter table + "Next implementation steps" describe the abandoned M1 sketch | **Fix the header + scope it down.** Retitle scope to "M0 substrate: vault + read path (landed)"; delete or banner the "Synthesis pipeline design (M1/M2)" and "Next implementation steps" sections, pointing at dreaming-nightly-pipeline. The substrate half (storage layout, tools, skill, scheduling, consent) is still the best writeup of the read side — keep it. |
-| `docs/design/memory-inference-path.md` | Inference-path rework: design + measured verification | Accurate, self-bannered (BUILT + VERIFIED; batching measured a loss). It's really an investigation record | Fine as-is. Optional (low priority): move to `docs/investigations/` where measured-experiment records live. |
+| `docs/design/memory-inference-path.md` | Inference-path rework: design + measured verification | Accurate, self-bannered (BUILT + VERIFIED; batching measured a loss). It's really an investigation record | Fine as-is. Optional (low priority): move to `docs/archive/investigations/` where measured-experiment records live. |
 | `docs/reference/memory.md` | User-facing reference | Mostly current (synthesize description matches as-built stages; status truth fixed 2026-07-01). **But** the "Synthesis roadmap" section still tells the old four-named-LoRA / HF-adapter-pack story (memory-bucket/memory-synthesis/memory-editor LoRAs "distributed from Hugging Face") — not the plan of record (`memory-<stage>` convention, only `memory-chunk` exists, base+policy otherwise) | **Rewrite the roadmap section** to the as-built stage list + the `memory-<stage>` adapter convention; update stage names again when BUCKET/RESOLVE land. |
 | `STATUS.md` § THE DREAMING | Live state | Current and correct (batch default 1, third-person fix merged, import paused at cursor 900/2096, inference-path landed) | Keep as the ONLY live-state location. |
 

package/docs/{planning → archive/planning}/release-notes-v0.0.9.md

@@ -117,6 +117,6 @@ overturning a load-bearing performance assumption.
   "failures" were M4-Pro fixtures; all code exonerated — mlx-lm reproduces
   mlx-bun token-for-token per machine); CI gate (typecheck + model-free tests).
 - **Research (the lab):** decode-roofline re-measurement overturned the "at
-  the floor" assumption (docs/investigations/decode-roofline-lookagain.md);
+  the floor" assumption (docs/archive/investigations/decode-roofline-lookagain.md);
   curve-sampler distinctness theorem + witness numbers + preregistered
   protocol (docs/planning/curve-sampler-research-plan.md).