mlx-bun 0.0.8 → 0.0.9

package/docs/design/parity-tier-dag.md

@@ -61,16 +61,24 @@ Worked examples:
 | lever | parity | perf | placement |
 |---|---|---|---|
 | `compiled-decode` | bit-exact w/ uncompiled (`compiled-decode.test`) | faster | **default-on, every level** |
-| `perf-kernel` | matches optiq, not mlx-lm (`perf-kernel-oracle.test`) | faster | **default-on from L2** (the L2 bridge) |
-| `fused-sdpa` | matches optiq, not mlx-lm (`fused-sdpa.test`) | faster | **default-on from L2** (the L2 bridge) |
+| `perf-kernel` | **envelope-gated, no bit-exact oracle** — mlx-bun-original kernel; gate is ≥56/64 teacher-forced argmax vs *our own* frozen compat trajectory (`perf-kernel-oracle.test`, `freeze-perf-oracle.ts`), and the optiq kv-quant goldens track the **stock unfused L=1 decode** (`regen-kvq-goldens.ts`) | faster | **L3 / explicit opt-in only** (off in bare `--l2`; on in `--l3` and the no-tier default) |
+| `fused-sdpa` | matches optiq bit-for-bit, not mlx-lm (`fused-sdpa.test` tier-a goldens) | faster | **default-on from L2** (the L2 bridge) |
 | `fused-decode` | (would be L3) | ~3% slower (`optimization_plan.md`) | **kept, off everywhere** |
 
 So `--l1/--l2/--l3` is the **parity** axis (the guarantee), and the defaults within
-each tier are the **performance** axis (the fastest kernel that still holds it). For
-the *decode path* L2 == L3 today (every decode kernel matches mlx-lm or optiq); L3's
-real territory is the no-oracle **features** — HLG sampler, expert offload, batched
+each tier are the **performance** axis (the fastest kernel that still holds it). On
+the *decode path* L2 and L3 now differ by exactly one node — the perf kernel (bare
+`--l2` = the optiq-golden composition: fused N-tiled prefill + stock unfused L=1
+decode; `--l3` adds the envelope-gated fused decode kernel). L3's remaining
+territory is the no-oracle **features** — HLG sampler, expert offload, batched
 mixed-precision — which live off the decode axis and are gated by KL + quality.
 
+> History: commit `f1bf5cc` put the perf kernel in the L2 preset claiming
+> "perf-kernel-oracle.test asserts the fused kernel == the frozen optiq goldens".
+> Both halves were wrong — that golden is frozen from mlx-bun's own compat engine,
+> and the gate is argmax-agreement, not equality — so 2026-07-01 restored the tier
+> rule: the bare tier is the guarantee; perf kernels are opt-ins within it.
+
 ## Why this matters for CLI flags
 
 We are accumulating a **lot** of flags (`--grad-accum`, `--grad-clip`, `--seg`,

package/docs/design/spec-decode-larger-targets.md

@@ -0,0 +1,229 @@
+# Spec decode on larger targets — does the Gemma drafter pay on 12B / 26B?
+
+Status: **12B γ=1 is a WIN after the verify fix; matches optiq bit-exactly** (2026-06-14; 26B not run)
+Owner: decode / spec
+Default: **off** (speculation is opt-in; non-spec greedy is untouched)
+
+## Result (2026-06-14, v2) — fixed the wrong-oracle bug; γ=1 now wins
+
+The first 12B measurement (v1, below) was made through a verify path that
+targeted the **wrong oracle**. Fixing it changed the conclusion.
+
+### The wrong-oracle bug
+
+Assistant-drafter speculation is an **optiq** feature — mlx-lm has only
+generic standalone-`draft_model` two-model spec and structurally cannot
+drive a KV-borrowing drafter. So the correctness oracle is optiq's
+`spec_generate`. **Both optiq and mlx-lm BATCH the verify lm-head** (one
+matmul over the γ+1 window, then argmax per position); neither is bit-
+exact to stock token-at-a-time decode. Our port instead verified
+**per-position** to be bit-exact to *stock decode* — a target no real
+implementation has, and one that re-reads the ~1 GB tied lm-head matrix
+γ+1× per iteration instead of once. So we were exact to the wrong thing
+*and* paying a γ-scaling tax for it. Fix: `picksBatched` in
+`src/spec/generate.ts` — one batched verify lm-head, matching optiq.
+
+### Do we match optiq? YES — bit-exact (e4b)
+
+Cross-checked our `specGenerate` against optiq's `spec_generate` on the
+identical prompt ids (`scripts/oracle-spec.py` + `scripts/spec-dump.ts`),
+e4b γ=2: **identical 48-token output AND identical accept/reject trace**
+(drafted 60, accepted 17, target calls 31 in both). Before the fix we
+matched *stock*, not optiq, at knife-edges; now we match optiq.
+
+### Is it still a loss? Not at γ=1 (12B)
+
+12B pair, batched verify (loaded machine — ratios paired/trustworthy,
+absolutes depressed & not quotable):
+
+| γ | v2 speedup (batched) | v1 (per-position) | acceptance |
+|---|----------------------|-------------------|-----------|
+| 1 | **1.09× (WIN)** | 0.96× | 42% |
+| 2 | 0.91× (near break-even) | 0.77× | 29% |
+| 3 | 0.72× | 0.67× | 23% |
+| 4 | 0.56× | 0.52× | 17% |
+
+Acceptance is unchanged (the fix only touches verify cost, not which
+tokens are accepted). The per-position verify was a large self-inflicted
+tax: removing it flips γ=1 from loss to **win** and moves γ=2 to the edge.
+γ≥2 still loses because the *drafter's own* cost dominates there — the
+12B drafter is heavy (hidden 1024 vs e4b 256, 16 heads, and a full 262k
+tied-embedding head **every draft step**) and acceptance falls with depth.
+
+**So the v1 "hypothesis refuted / net loss at every γ" was itself partly
+an artifact of the wrong-oracle verify.** Corrected conclusion: γ=1
+speculation on 12B is a real ~9% decode win (pending clean-machine
+confirmation before quoting); γ≥2 doesn't pay with the shipped heavy
+drafter.
+
+### Bonus finding: we're ahead of optiq on the unified drafters
+
+optiq's *installed* runtime can't actually drive the 12B/26B
+`gemma4_unified_assistant` drafters: its head detection is config-based
+(`use_ordered_embeddings = num_centroids and top_k`), but those artifacts
+declare `num_centroids` while shipping **no** centroid tensors and **no**
+`lm_head` (tied `embed_tokens` instead). optiq loads the centroid path
+with zero-init weights → garbage drafts → **0% acceptance** (measured:
+drafted 46, accepted 0 on 12B). Our `drafter.ts` detects the head by
+**tensor presence** and uses the tied-embedding path → 29% acceptance on
+the same artifact.
+
+### Remaining levers / next
+
+- **Clean-machine rerun** before promoting any number to RESULTS.md
+  (baseline jumped 15.4→24.4 between runs under memory pressure — exactly
+  why only paired ratios are trusted here).
+- **Cheaper drafter head**: the 262k tied-embed argmax every draft step is
+  the dominant remaining γ≥2 cost; capping/approximating it (e4b-style)
+  could extend the win past γ=1.
+- **26B-MoE**: still unlikely — MoE decode reads only top-8/128 experts
+  (~2.4 GB active), so per-token target cost is *lower* than its size →
+  harder to beat. Measure if curious.
+- **Optional strict mode**: the old per-position verify gave "spec output
+  identical to spec-off" — a product nicety no oracle provides. Could be
+  kept as a default-off `strictVerify` flag rather than deleted
+  ([[dont-delete-optionality-on-one-measurement]]) — not implemented; ask.
+
+## v1 (superseded) — per-position verify, "net loss at every γ"
+
+> Kept for the record. The numbers (0.96/0.77/0.67/0.52×) were real but
+> measured through the wrong-oracle per-position verify; v2 above is the
+> optiq-faithful measurement.
+
+## TL;DR
+
+The Gemma `-assistant-bf16` drafters are Gemma's substitute for an MTP
+head: a 4-layer Q-only module that reuses the target's KV + hidden state
+to draft tokens (`src/spec/drafter.ts`), verified by the target's own
+greedy pick (`src/spec/generate.ts`). True MTP (a trained
+`mtp.safetensors` head + an `optiq/runtime/mtp` backend) **does not exist
+for Gemma** and never will — that's the Qwen path (Phase 14). The
+assistant drafter is the functional equivalent we already have.
+
+It was measured a **net loss on e4b** (Phase 6): γ=2 ran at 0.78× the
+54 tok/s baseline, ~23% acceptance — because e4b decode is already too
+fast for a low-acceptance drafter to beat. **This doc is the experiment
+to find out whether the same drafter wins on a slower target**, where
+each skipped target-forward is worth more.
+
+## The hypothesis
+
+The drafter's per-step cost is roughly fixed. The *value* of each
+accepted draft = one skipped target forward, which grows as the target
+gets slower per token. e4b is the worst case for speculation (fastest
+target). So the SAME acceptance rate can flip net-positive as the target
+slows:
+
+| target | non-spec decode | per-accepted-draft value | drafter | status |
+|--------|-----------------|--------------------------|---------|--------|
+| e4b              | ~54 tok/s | low  | 160 MB (cached) | **measured net loss** (0.91/0.78/0.63/0.51× @ γ=1–4) |
+| 12B              | ~25 tok/s | ~2× e4b | 846 MB (cached) | **measured net loss** — see Result above (hypothesis refuted) |
+| 26B-A4B (MoE)    | ~32 tok/s | high (MoE forward) | 839 MB (HF, **not downloaded**) | untested (follow-on; expect loss) |
+
+> The reasoning below is the *pre-measurement* hypothesis — kept for the
+> record. It predicted the crossover assuming a fixed-cost drafter; the
+> 12B drafter is not fixed-cost (it scales with the target), which is
+> exactly why the Result section above refutes it.
+
+Crossover intuition: a drafter is a net win when
+`acceptance × (target_step_cost − draft_step_cost) > verify_overhead`.
+On e4b the target step is cheap, so the bar isn't cleared at 23%. On 12B
+the target step is ~2× more expensive while the drafter cost barely
+moves — same acceptance, very different sign. **Measure, don't assume**
+(it could still lose; this is exactly the kind of thing the e4b result
+warned against assuming).
+
+Acceptance itself may also differ on 12B (a stronger target predicts
+itself differently). We don't know the direction — that's why we run it.
+
+## What is already wired (this change)
+
+- **`scripts/spec-bench.ts`** — now multi-pair, **one pair per process**
+  (memory-safe; 12B+drafter ≈ 8 GB, 26B ≈ 17 GB, never co-resident):
+  - `bun scripts/spec-bench.ts e4b` (default) — reproduces the baseline.
+  - `bun scripts/spec-bench.ts 12B` — the experiment.
+  - `bun scripts/spec-bench.ts 26B` — follow-on.
+  - Auto-detects whether each `(target, drafter)` snapshot pair is
+    present; exits with a clear "download with: hf download …" message
+    otherwise. Records baseline + γ-sweep (acceptance + tok/s) to the
+    eval DB tagged `spec-bench[<id>]`.
+- **`tests/spec-decode.test.ts`** — added a `(12B)` parity block,
+  auto-skipped until the drafter is downloaded. Gate = long-prefix
+  agreement (greedy spec vs greedy non-spec). It guards the shared
+  accept/reject/**rollback + cache-trim** machinery against 12B's
+  distinct layer/cache shapes — NOT drafter correctness (see the
+  important nuance below). The calibrated e4b block (exact `toEqual` +
+  knife-edge) is unchanged.
+
+The port (`drafter.ts` + `generate.ts`) is already generic over the
+target's `backbone_hidden_size` — drafters are target-bonded artifacts
+(e4b 2560, 12B 3840, 26B 2816) but there's no per-pair code, just the
+matching weights. Expect to *validate* each cell per the project's
+per-model-specialization reality, not assume it's free.
+
+## Important nuance: a broken drafter still produces correct tokens
+
+Speculation can't corrupt output. The target verifies every position and
+replaces every rejected draft with its own greedy pick; drafts only ever
+*skip* target forwards. So a mis-wired drafter (wrong KV borrow, wrong
+projection) shows up as **low/zero acceptance — a perf signal**, not bad
+tokens. This splits the validation cleanly:
+
+- **Correctness** (parity test): does the shared accept/reject/rollback
+  + cache-trim logic still hold on 12B's cache shapes? A trim bug *would*
+  corrupt output, shortly after the first rejection — that's what the
+  long-prefix gate catches. (Shape-incompatible KV borrow throws, it
+  doesn't silently corrupt.)
+- **Payoff** (bench): is acceptance high enough, and the target slow
+  enough, that γ>0 beats the non-spec baseline? This is the actual
+  question.
+
+## Procedure (once the 12B drafter is downloaded)
+
+1. `hf download mlx-community/gemma-4-12B-it-assistant-bf16`
+   (846 MB; `HF_HUB_DISABLE_XET=1`). The 12B OptiQ-4bit target is
+   already cached.
+2. **Correctness first** — `bun test tests/spec-decode.test.ts`
+   (the `(12B)` block now runs). Long-prefix gate must pass for γ=1,2,3.
+   If it fails early → rollback/trim bug on 12B caches, fix before
+   trusting any number.
+3. **Calibrate + promote (optional)** — find a tie-free prompt
+   on-device, promote the 12B gate from long-prefix to exact `toEqual`
+   like e4b, for a stronger standing guard.
+4. **Measure** — `bun scripts/spec-bench.ts 12B` on a clean machine
+   (preflight matters: dirty-machine numbers are garbage). Read
+   acceptance + speedup-vs-baseline per γ.
+5. **Record + decide** — numbers land in the eval DB. Promote into
+   `benchmarks/RESULTS.md` only if quotable (clean machine).
+6. **26B follow-on** — repeat with `26B` if 12B is encouraging; MoE
+   target adds a validation cell (donor KV borrow through the MoE
+   decoder), and a slower/heavier forward that should favor speculation
+   even more — but the MoE forward also reads only top-8/128 experts at
+   decode, so the per-token cost advantage is smaller than weight size
+   suggests. Measure.
+
+## Exit criteria
+
+- 12B spec parity gate green (rollback/trim correct on 12B caches).
+- 12B acceptance + tok/s-vs-baseline recorded in the eval DB across
+  γ=1–4.
+- A decision written down: ship speculation as the **default** only for
+  the (model, context) cells where it measurably wins; otherwise record
+  it as a characterized default-off lever (same disposition as the e4b
+  net-loss result — a documented option, never a deletion).
+
+## Caveats / interactions
+
+- **Batched serving (Phase 18).** Speculation needs trimmable caches for
+  partial-accept rollback — `generate.ts` throws once a `RotatingKVCache`
+  ring wraps past the sliding window — and variable accept-lengths per
+  slot break a uniform-B batch. Speculation is naturally a **B=1 latency**
+  optimization; batched-throughput serving is a different regime. Layering
+  both is real work, not free composition.
+- **One serve path, two backends.** The assistant-drafter loop and the
+  Qwen MTP runtime are two backends of the *same* "draft γ → verify in one
+  forward → accept-longest-prefix → rollback" abstraction. As Phase 14
+  (MTP) and Phase 18 (slots) land, build one verify/accept executor, not
+  two — the drafter vs MTP-head difference is just what fills the draft.
+- **Denominator discipline.** Speedups are only ever vs the *same model's*
+  non-spec baseline. e4b's 54 tok/s is the wrong denominator for 12B.

package/docs/design/tauri-desktop-app.md

@@ -62,7 +62,7 @@ The window renders the **same page** `mlx-bun serve` serves today
    app exit. One generation runs at a time server-side, so no client
    concurrency to manage.
 3. **Port.** Bind an ephemeral port in Rust, pass it to both the spawn
-   (`--port`) and the webview URL, to avoid 8090 collisions with a
+   (`--port`) and the webview URL, to avoid 8080 collisions with a
    user's own `mlx-bun serve`.
 4. **Readiness gate.** Show a lightweight "starting…/downloading model…"
    splash until `/v1/models` returns 200. Warm start ~0.4s; first-ever
@@ -99,7 +99,7 @@ then `xcrun stapler staple`.
 
 ## Milestones
 
-1. **Spike** — `tauri init` in a new repo; hardcode port 8090; spawn a
+1. **Spike** — `tauri init` in a new repo; hardcode port 8080; spawn a
    locally-built `mlx-bun serve --no-open`; load `/#/chat` in the window;
    `cargo tauri dev`. Proves the wrap end-to-end.
 2. **Robust runtime** — ephemeral port; readiness poll + splash;

package/docs/design/the-dreaming-handoff.md

@@ -0,0 +1,141 @@
+# THE DREAMING — HANDOFF (2026-06-28)
+
+Live handoff for the local personal-wiki memory system (`src/memory/`). A fresh
+session can resume from this doc. **Companion docs:** `research-journal.md` (dated
+findings), `docs/design/memory-inference-path.md` (the in-progress templating/batching
+rework), and the per-phase `p*-judge.md` reports.
+
+---
+
+## TL;DR — where we are
+
+The Dreaming turns conversations → chunks → entities → **subject articles** →
+cross-linked, self-healing personal wiki. It **works end-to-end on real data.**
+
+- **Full-corpus import RESUMED from cursor 720/2096** into `~/.mlx-bun/wiki-full`, on the
+  corrected templating, batching off (serial, ~50h).
+- **Committed + merged to `main`** (the Dreaming pipeline + inference-path rework). tsc 0.
+- Templating fix **VERIFIED live** on real convs (bare prompt + a 40-msg conv → valid chunks).
+
+## Resume the import
+```
+# 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)
+# 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
+```
+**Gotcha:** background bash + detached processes get **reaped across turns** in this
+harness. Drive long GPU runs as foreground bounded batches, or `nohup … & disown` (still
+iffy). The pipeline is resumable, so just re-launch to continue.
+
+---
+
+## Architecture (as-built, after this session's corrections)
+
+**Staged, chronological, resumable pipeline** (`src/memory/stages.ts`). Each stage is an
+independent DB-state-keyed worker, ordered `updated_at ASC` (chronological), resumable
+(skips done work). CLI: `mlx-bun memory segment|extract|route|synthesize-stage|link` (run
+separately/concurrently) — and `mlx-bun memory synthesize` runs the full DAG.
+
+```
+ingest → SEGMENT (our e4b-chunk-300 chunker) → EXTRACT (entities) → ROUTE (subject-based,
+surface-everything) → CREATE/PATCH (per-section bounded synthesis; self-healing) →
+RECONCILE (infobox-ground-truth consistency) → LINK (cross-link) → WIKIFY (editorial) → commit
+```
+
+- **Vault = truth** (markdown files in `articles/`); **DB = derived cache** (`reindex`
+  rebuilds it). The article FILES are the real artifacts. The `entities.article_stem`
+  column being unset mid-run is cosmetic (file-presence is the source of truth).
+- **Vaults:** `~/.mlx-bun/wiki` (the REAL vault — untouched), `~/.mlx-bun/wiki-full`
+  (import target), `wiki-smoke|slice|pattern|pattern2|link-test` (scratch).
+- **Model:** ONE base **Gemma-4-e4b** (`SNAPSHOT_E4B`). **Only ONE adapter trained so far:
+  `e4b-chunk-300`** (the chunker), symlinked `~/.cache/mlx-bun/adapters/memory-chunk`.
+  `callLocal(stage,…)` picks `memory-<stage>` adapter iff it exists, else base.
+- **Lucien is a READ-ONLY oracle/data-source** (`~/Code/lucien/.lucien/lucien.db` opened
+  readonly; `~/Dreaming`). We reuse NONE of its derived chunks/buckets — only the raw
+  conversation text (≡ a JSONL export / scraper). Never write there.
+
+---
+
+## What we LEARNED / CORRECTED this session (load-bearing — don't re-derive)
+
+1. **NO notability/ownership filter.** Surface everything; notable = "anything that recurs
+   in your thinking" (Lucien `Editorial_Guidelines.md`). The plan's "owned/decided/≥3
+   chunks → PARK as trivia" was **fabricated by a prior agent and ripped out.** ROUTE now:
+   surface everything, strongly prefer an existing article, mint a new one only for a
+   substantive/recurring subject, `_captured` bucket (searchable) for the rest — **nothing
+   dropped.**
+2. **Subject-based articles = the one deliberate improvement over Lucien** (which drifted
+   into `X_and_Y` topic-bins). Verified: frameworks (Kaizen, TPS, LessWrong, Free energy
+   principle) get good articles; coverage resolves (`resolve("Kaizen")` → article).
+3. **Our chunker must be used.** The pipeline's `segment` was a no-op reusing Lucien's
+   chunks; fixed — `e4b-chunk-300` segments the raw conversations (better, topic-coherent).
+4. **Chronological ordering.** Was `ORDER BY id` (= conv UUID, random); fixed to
+   `updated_at ASC` everywhere. Load-bearing for self-healing.
+5. **Self-healing.** A later-dated correction flips the LEAD + INFOBOX + every body section
+   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`).
+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;
+   defensive strips added. Keep this rule for any new prompt.
+7. **Cross-linking is WIKIFY's job, NOT synthesis** (synthesis updates ONE article, can't
+   know others). Built a dedicated `link` stage (`crosslink.ts`): mention-based (prose
+   names another article → `[[link]]`) + co-occurrence (shared folded chunks → See also).
+   Result on a 587-article snapshot: See-also 18%→96%, resolved edges 309→**7026 (22.7×)**.
+   Idempotent; fence-fix handles malformed input.
+8. **Metrics.** Do NOT measure articles-per-conversation (there is no conv→article link).
+   Measure **topic aggregation** (e.g. `El_Salvador` ← 30 conversations → 1 article).
+   Quality is judged by a **CLOUD JUDGE on real output**, never Lucien bucket-F1 (that's the
+   bin taxonomy we replace).
+9. **Inference path (IN PROGRESS — see `docs/design/memory-inference-path.md`):**
+   - **Template mismatch (fixed in working tree):** the chunk adapter was SFT'd with a
+     **system role** (Gemma-4 renders `<|turn>system…<turn|>` distinctly), but inference
+     dropped it (one user message). `callLocal` now passes `{system, user}` matching
+     training; the chunk stage uses `CHUNK_SYSTEM` (its exact trained system prompt). Also
+     noted: the live `CHUNK_PROMPT` drifted from training (only 2 of 8 Meta pages; abstracted
+     examples) — adapter still generalizes, so quality delta is **modest**.
+   - **Batching = DEAD END.** Measured ~**1.7× SLOWER** (warm, uniform: 0.607 vs 0.357
+     s/chunk). The `BatchScheduler` pads heterogeneous prefills and doesn't amortize
+     weight-loads. Default OFF (`MLX_BUN_MEMORY_BATCH=1`). Import is genuinely ~50h serial;
+     batching is NOT the lever (a *better* batched-decode that amortizes weights could help
+     in principle, but that's a real perf project, not worth it for a one-time import).
+   - **Load-once / persistent server = the REAL efficiency win, for DAILY use.** Each CLI
+     invocation today reloads the model + pays warmup; routing memory generation through the
+     **resident server** (model loaded once) kills that. Within the single-process import
+     the model is already loaded once, so it doesn't speed the import.
+
+## Product framing (from the user)
+- **Daily local conversations (pi sessions) folding in is the product** — watermark-gated
+  ingest, minutes/day, self-healing. The 4-year Claude/ChatGPT import is a one-time
+  **onboarding feature + stress test**. Throughput only matters for the import.
+
+---
+
+## NEXT STEPS (prioritized)
+
+1. **Finish the inference-path rework.** Templating fix is in the working tree (verify it
+   end-to-end). **Wire memory generation through the persistent server (load-once)** — the
+   user's actual ask — keeping a no-server fallback; default batching OFF. Verify the chunk
+   stage decodes on-distribution (system role present).
+2. **Import is RUNNING** (resumed from 720, serial, corrected templating). Just let it finish.
+   Re-segmenting the first 720 is **low-urgency** (old chunks were valid).
+3. **After import:** `reindex` → `mlx-bun memory link` → browse `wiki-full` in Obsidian;
+   cloud-judge a broad, diverse sample (not just frameworks/gear).
+4. **Promote to the real vault** when satisfied: point `~/.mlx-bun/wiki` at the bootstrapped
+   content; wire the **nightly daily fold-in** from pi sessions (`schedule.ts` exists).
+5. **Open quality items** (low priority): ~<1% articles leak a prompt fragment; some leads
+   run on; the `owned/used/chosen` framing in `Article_Conventions` lead spec can put
+   `owned: yes` on abstract concepts (reframe).
+6. **Commit when ready** — everything is uncommitted; the user has not asked to commit.
+
+## Gotchas / facts
+- `bunx tsc` sometimes can't resolve typescript in this checkout; use global `tsc`. Repo = 0 errors.
+- The `mlx-bun train-watch orpo-e4b-chunk` process is a **stale idle daemon, not training** — GPU is free.
+- e4b training still OOMs on this 32GB M1 Max; P10 adapter training stays USER-ACTION (segmented-backward).
+- The `Reference/` folder in vaults symlinks the mlx-bun repo docs (`setupVault`) — non-portable; fine for now, drop for the real personal vault.
+- Methodology memories: cloud-judge not bucket-F1; Lucien read-only; surface-everything notability.