mlx-bun 0.0.8 → 0.0.10

package/src/train/trainer.ts

@@ -34,7 +34,7 @@ import {
   saveAdapter, disposeLora, warmStartFromAdapter, type TrainableLora, type SaveAdapterConfig,
 } from "./lora-params";
 import { resolveRanks, bitsMapFromModel, readPerLayerKl, DEFAULT_TARGET_MODULES, type RankScaling } from "./rank";
-import { sftLoss, dpoLoss, dpoRefLogps, dpoMetrics, orpoLoss, orpoMetrics, type ChunkCtx } from "./loss";
+import { sftLoss, dpoLoss, dpoRefLogps, dpoMetrics, orpoLoss, orpoMetrics, type ChunkCtx, type SftScope } from "./loss";
 import { orpoLossPrefixShared, orpoLossPrefixSharedGemma, splitPrefixBatch } from "./prefix-shared";
 import { AdamW, warmupCosineSchedule } from "./optimizer";
 import { writeFileSync, appendFileSync, mkdirSync } from "node:fs";
@@ -134,6 +134,15 @@ export interface TrainConfig {
    *  differ. Composes with orpoFlashCe/orpoFusedCe (each branch routes through the
    *  [M,V]-free head). See src/train/prefix-shared.ts. */
   orpoPrefixShared: boolean;
+  /** ORPO L_SFT scope (`sft_scope`). "full" (default; paper/TRL-faithful):
+   *  the chosen-NLL term is the token-mean cross-entropy over the FULL
+   *  prompt+response (only padding excluded), computed from the same chosen
+   *  forward — matching TRL's ORPOTrainer chosen_nll_loss. "response":
+   *  L_NLL = -ℓw (response-only), bit-exact to pre-sft_scope runs. The
+   *  odds-ratio ℓw/ℓr terms are response-only length-normalized means in BOTH
+   *  modes (that also matches TRL). Applies to every ORPO path (naive /
+   *  chunked / fused / flash / prefix-shared / segmented). orpo only. */
+  sftScope: SftScope;
   /** Warm-start: path to an existing adapter dir (with adapters.safetensors) whose
    *  LoRA weights initialize this run instead of the random/zero init. Continues
    *  training from a checkpoint's weights; the optimizer state and LR schedule restart.
@@ -188,6 +197,7 @@ export const DEFAULT_TRAIN_CONFIG: TrainConfig = {
   orpoFusedCe: false, // default off; true = fused linear-CE head (analytic backward, no [M,vocab])
   orpoFlashCe: false, // default off; true = flash-CCE Metal-kernel head (implies fused)
   orpoPrefixShared: false, // default off; true = shared prompt-prefix single forward (B=1)
+  sftScope: "full", // paper/TRL-faithful chosen-NLL over prompt+response; "response" = pre-2026-07 behavior
   warmStartAdapter: "", // default off; path to an adapter dir to warm-start LoRA weights from
   adapterPath: "adapters",
   baseModel: "",
@@ -298,6 +308,7 @@ export async function trainLora(
     iters: cfg.iters, learning_rate: cfg.learningRate, max_seq_length: cfg.maxSeqLen,
     batch_size: cfg.batchSize, rank: cfg.rank, scale: cfg.scale,
     orpo_lambda: cfg.method === "orpo" ? cfg.orpoLambda : undefined,
+    sft_scope: cfg.method === "orpo" ? cfg.sftScope : undefined,
     adapter_path: cfg.adapterPath,
   });
 
@@ -349,6 +360,7 @@ export async function trainLora(
           segmentSize: cfg.segmentSize, iters: cfg.iters,
           numLayers: cfg.numLayers, baseModel: cfg.baseModel,
           orpoLambda: cfg.method === "orpo" ? cfg.orpoLambda : undefined,
+          sftScope: cfg.method === "orpo" ? cfg.sftScope : undefined,
         },
         wallSeconds: (Date.now() - startedAt) / 1000,
         peakGb: peakMemory() / 1e9,
@@ -376,6 +388,16 @@ export async function trainLora(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Segment planning: uniform planSegmentsBySize only. A full-attention
+// ISOLATION planner (kernel-review backlog #2 / segmented-backward-training.md
+// §5) was built and A/B-measured 2026-07-02: ZERO peak win — mlx's sdpa
+// backward is O(L²) for EVERY layer (~3.5 GB/layer @8K e4b), sliding included,
+// so the worst segment is set by layer count alone and segment_size is the
+// whole knob (seg1 = 14.59 GB @8K, +3% step time — fits the 24 GB M4 Pro).
+// Evidence: scripts/experiments/seg-isolation-smoke.ts; note in segmented.ts.
+// ---------------------------------------------------------------------------
+
 // ---------------------------------------------------------------------------
 // SFT loop
 // ---------------------------------------------------------------------------
@@ -409,14 +431,14 @@ async function sftLoop(
   const useSegmented = cfg.segmentSize > 0;
   let segmented: SegmentedBackward | SegmentedBackwardGemma4 | null = null;
   if (useSegmented) {
-    if (model instanceof MiniCPM5Model)
-      segmented = new SegmentedBackward(model, lora, planSegmentsBySize(model.layers.length, cfg.segmentSize));
-    else if (model instanceof Gemma4Model)
-      segmented = new SegmentedBackwardGemma4(model, lora, planSegmentsBySize(model.layers.length, cfg.segmentSize));
-    else
+    if (!(model instanceof MiniCPM5Model) && !(model instanceof Gemma4Model))
       throw new Error("segmented backward (segmentSize > 0) is only wired for MiniCPM5 and Gemma4");
+    const ranges = planSegmentsBySize(model.layers.length, cfg.segmentSize);
+    segmented = model instanceof MiniCPM5Model
+      ? new SegmentedBackward(model, lora, ranges)
+      : new SegmentedBackwardGemma4(model, lora, ranges);
     emit({ type: "stage", stage: "setup", progress: 0.04,
-      message: `segmented backward: ${Math.ceil(model.layers.length / cfg.segmentSize)} segments of <=${cfg.segmentSize} layers` });
+      message: `segmented backward: ${ranges.length} segments of <=${cfg.segmentSize} layers` });
   }
 
   // The value_and_grad loss closure: temporarily swap the differentiated
@@ -466,14 +488,40 @@ async function sftLoop(
   // dQ-causal-barrier bugs were fixed; FD-validated in
   // scripts/experiments/flash-fd-check.ts), though ~30× slower than ops.sdpa.
   // Cleared in finally.
-  if (process.env.MLX_BUN_TRAIN_ATTN === "flash") setTrainingAttn("flash");
+  //
+  // GEMMA GUARD (same convention as the PERF_KERNEL/FUSED_GELU sanitization in
+  // cli.ts / job.ts, but enforced at the trainer): e4b on this path SIGTRAPed
+  // (uncatchable native crash) at multi-K sequence lengths (>=2K, reproduced in
+  // scripts/experiments/segmented-grad-test-e4b.ts; docs/reference/training.md)
+  // and has NOT been re-validated at that scale since the two kernel fixes —
+  // the regression tests stop at T<=256. cli.ts even defaults e4b seq to 8192,
+  // so a stale `export MLX_BUN_TRAIN_ATTN=flash` from a MiniCPM5 experiment
+  // would otherwise ride silently into a crash mid-run. Refuse it for Gemma
+  // until the >=2K re-validation lands; MiniCPM5 stays allowed.
+  if (process.env.MLX_BUN_TRAIN_ATTN === "flash") {
+    if (model instanceof Gemma4Model)
+      throw new Error(
+        "MLX_BUN_TRAIN_ATTN=flash is disabled for Gemma models: e4b SIGTRAPs on this " +
+          "path at seq >= 2048 (docs/reference/training.md) and it has not been " +
+          "re-validated at that scale since the kernel fixes. Unset MLX_BUN_TRAIN_ATTN " +
+          "(ops.sdpa, the default, is exact and ~30x faster) or train MiniCPM5.",
+      );
+    emit({ type: "stage", stage: "setup", progress: 0.045,
+      message: "training attention: hand-rolled flash kernel (MLX_BUN_TRAIN_ATTN=flash; O(L) memory, ~30x slower than ops.sdpa)" });
+    setTrainingAttn("flash");
+  }
 
   // Pad with the eos id when available (a real sentinel token); padded
   // positions are excluded from both the loss and attention masks, so the
   // exact pad value never affects the result — it just must be a valid id.
   const padId = tok.eosTokenId ?? 0;
   const batches = iterateSftBatches(train, cfg.batchSize, cfg.maxSeqLen, cfg.seed, true, padId);
-  const t0 = Date.now();
+  // tokens/sec follows mlx-lm's tuner convention: accumulate the response-token
+  // count across the REPORT WINDOW and divide by the window's own wall time
+  // (validation time excluded) — not one step's count extrapolated over the
+  // whole run, which jumps ~10x step-to-step on variable-length data.
+  let windowTokens = 0;
+  let windowStart = Date.now();
 
   try {
     for (let step = 1; step <= cfg.iters; step++) {
@@ -483,12 +531,11 @@ async function sftLoop(
       // when 1). afterMicroEval frees each micro-batch's gradient-checkpoint
       // closures right after its backward so they don't pile up across
       // accumulation.
-      let tokensThisStep = 0;
       const { loss: lossVal, grads } = accumulateStep(
         cfg.gradAccumSteps,
         () => {
           currentBatch = batches.next().value as SftBatch;
-          tokensThisStep += countResponseTokens(currentBatch);
+          windowTokens += countResponseTokens(currentBatch);
           return segmented ? segmented.step(currentBatch!) : vag!.apply(flatParams(lora));
         },
         ckptCtx
@@ -512,7 +559,7 @@ async function sftLoop(
       }
 
       if (step % cfg.stepsPerReport === 0 || step === 1) {
-        const elapsed = (Date.now() - t0) / 1000;
+        const elapsed = (Date.now() - windowStart) / 1000;
         emit({
           type: "metric",
           kind: "train",
@@ -520,19 +567,31 @@ async function sftLoop(
           loss: lossVal,
           grad_norm: gradNorm,
           learning_rate: opt.lr,
-          tokens_per_sec: elapsed > 0 ? (step * tokensThisStep) / elapsed : 0,
+          tokens_per_sec: elapsed > 0 ? windowTokens / elapsed : 0,
           progress: step / cfg.iters,
           message: `step ${step}/${cfg.iters} loss=${lossVal.toFixed(4)}`,
         });
+        windowTokens = 0;
+        windowStart = Date.now();
       }
 
       if (valid.length > 0 && step % cfg.stepsPerEval === 0) {
         // Eval is forward-only (no backward), so disable checkpointing for it —
         // it adds no benefit and a forward-only pass fits without it.
         if (ckptCtx) (model as Gemma4Model).gradCkpt = null;
-        const vLoss = evalSftLoss(model, valid, cfg);
+        const tVal = Date.now();
+        const { loss: vLoss, used, skipped } = evalSftLoss(model, valid, cfg);
         if (ckptCtx) (model as Gemma4Model).gradCkpt = ckptCtx;
-        emit({ type: "metric", kind: "val", step, loss: vLoss, progress: step / cfg.iters });
+        // A silently-shrinking val set must be visible: rows whose supervised
+        // span is empty after truncation are skipped BY DESIGN (mlx-lm drops
+        // them at dataset build time) — report how many, and over what n the
+        // mean was taken. Any other per-row failure now rethrows (see
+        // evalSftLoss).
+        emit({ type: "metric", kind: "val", step, loss: vLoss, progress: step / cfg.iters,
+          val_rows_used: used, val_rows_skipped: skipped,
+          ...(skipped > 0 ? { message: `val loss over ${used} rows (${skipped} skipped: no response tokens to supervise)` } : {}) });
+        // validation wall time is not training throughput — keep it out of the window
+        windowStart += Date.now() - tVal;
       }
     }
   } finally {
@@ -548,13 +607,16 @@ async function sftLoop(
   return { numIters: cfg.iters };
 }
 
-function evalSftLoss(model: RuntimeModel, valid: ReturnType<typeof Array.prototype.slice>, cfg: TrainConfig): number {
+function evalSftLoss(
+  model: RuntimeModel, valid: ReturnType<typeof Array.prototype.slice>, cfg: TrainConfig,
+): { loss: number; used: number; skipped: number } {
   let total = 0;
   let n = 0;
+  let skipped = 0;
   for (const ex of valid as { ids: number[]; promptLen: number }[]) {
     let ids = ex.ids;
     let promptLen = ex.promptLen;
-    if (ids.length < 2) continue;
+    if (ids.length < 2) { skipped++; continue; }
     if (ids.length > cfg.maxSeqLen) {
       ids = ids.slice(0, cfg.maxSeqLen);
       promptLen = Math.min(promptLen, Math.max(0, ids.length - 1));
@@ -565,12 +627,18 @@ function evalSftLoss(model: RuntimeModel, valid: ReturnType<typeof Array.prototy
       total += loss.toFloat32()[0]!;
       loss.dispose();
       n++;
-    } catch {
-      // skip examples with no response tokens
+    } catch (e) {
+      // ONLY the empty-supervision row is skippable (a truncated row whose
+      // response fell entirely past maxSeqLen — mlx-lm drops these at dataset
+      // build). Everything else (MLX OOM/shape/vjp errors surface as catchable
+      // JS Errors via the ffi handler) must rethrow: swallowing them silently
+      // reduces the val set to its easy rows and reports a plausible loss.
+      if (e instanceof Error && e.message === "sftLoss: no response tokens to supervise") skipped++;
+      else throw e;
     }
     clearCache();
   }
-  return n > 0 ? total / n : 0;
+  return { loss: n > 0 ? total / n : 0, used: n, skipped };
 }
 
 // ---------------------------------------------------------------------------
@@ -774,28 +842,28 @@ async function orpoLoop(
   let segmentedOrpo: SegmentedBackwardOrpo | SegmentedBackwardOrpoGemma4 | null = null;
   let segmentedOrpoPrefix: SegmentedBackwardOrpoPrefix | SegmentedBackwardOrpoPrefixGemma4 | null = null;
   if (useSegmented) {
+    if (!(model instanceof MiniCPM5Model) && !(model instanceof Gemma4Model))
+      throw new Error("segmented backward (segmentSize > 0) for ORPO is only wired for MiniCPM5 and Gemma4");
     const ranges = planSegmentsBySize(model.layers.length, cfg.segmentSize);
     if (useSegmentedPrefix) {
       // The composed prefix-shared segmented backward (MiniCPM5 or Gemma4/e4b), plus a
       // plain segmented-ORPO fallback for rows whose chosen/rejected prompts differ
       // (splitPrefixBatch returns null -> two-forward segmented step).
       if (model instanceof MiniCPM5Model) {
-        segmentedOrpoPrefix = new SegmentedBackwardOrpoPrefix(model, lora, ranges, cfg.orpoLambda, segPrefixChunk);
-        segmentedOrpo = new SegmentedBackwardOrpo(model, lora, ranges, cfg.orpoLambda, segFusedChunk);
+        segmentedOrpoPrefix = new SegmentedBackwardOrpoPrefix(model, lora, ranges, cfg.orpoLambda, segPrefixChunk, cfg.sftScope);
+        segmentedOrpo = new SegmentedBackwardOrpo(model, lora, ranges, cfg.orpoLambda, segFusedChunk, cfg.sftScope);
       } else {
-        segmentedOrpoPrefix = new SegmentedBackwardOrpoPrefixGemma4(model as Gemma4Model, lora, ranges, cfg.orpoLambda, segPrefixChunk);
-        segmentedOrpo = new SegmentedBackwardOrpoGemma4(model as Gemma4Model, lora, ranges, cfg.orpoLambda, segFusedChunk);
+        segmentedOrpoPrefix = new SegmentedBackwardOrpoPrefixGemma4(model as Gemma4Model, lora, ranges, cfg.orpoLambda, segPrefixChunk, cfg.sftScope);
+        segmentedOrpo = new SegmentedBackwardOrpoGemma4(model as Gemma4Model, lora, ranges, cfg.orpoLambda, segFusedChunk, cfg.sftScope);
       }
       emit({ type: "stage", stage: "setup", progress: 0.04,
-        message: `orpo segmented + prefix-share (${model instanceof Gemma4Model ? "e4b" : "MiniCPM5"}): single concat forward streamed over ${Math.ceil(model.layers.length / cfg.segmentSize)} segments of <=${cfg.segmentSize} layers (two-forward fallback on prompt mismatch)` });
+        message: `orpo segmented + prefix-share (${model instanceof Gemma4Model ? "e4b" : "MiniCPM5"}): single concat forward streamed over ${ranges.length} segments of <=${cfg.segmentSize} layers (two-forward fallback on prompt mismatch)` });
     } else if (model instanceof MiniCPM5Model)
-      segmentedOrpo = new SegmentedBackwardOrpo(model, lora, ranges, cfg.orpoLambda, segFusedChunk);
-    else if (model instanceof Gemma4Model)
-      segmentedOrpo = new SegmentedBackwardOrpoGemma4(model, lora, ranges, cfg.orpoLambda, segFusedChunk);
+      segmentedOrpo = new SegmentedBackwardOrpo(model, lora, ranges, cfg.orpoLambda, segFusedChunk, cfg.sftScope);
     else
-      throw new Error("segmented backward (segmentSize > 0) for ORPO is only wired for MiniCPM5 and Gemma4");
+      segmentedOrpo = new SegmentedBackwardOrpoGemma4(model as Gemma4Model, lora, ranges, cfg.orpoLambda, segFusedChunk, cfg.sftScope);
     if (!useSegmentedPrefix) emit({ type: "stage", stage: "setup", progress: 0.04,
-      message: `orpo segmented backward: ${Math.ceil(model.layers.length / cfg.segmentSize)} segments of <=${cfg.segmentSize} layers${segFusedChunk > 0 ? ` + fused linear-CE head (${segFusedChunk}/chunk)` : ""}` });
+      message: `orpo segmented backward: ${ranges.length} segments of <=${cfg.segmentSize} layers${segFusedChunk > 0 ? ` + fused linear-CE head (${segFusedChunk}/chunk)` : ""}` });
   }
 
   // Token-chunked head (non-segmented path only): the per-chunk checkpoints are
@@ -837,12 +905,12 @@ async function orpoLoop(
             const split = splitPrefixBatch(currentBatch!);
             if (split) {
               if (model instanceof MiniCPM5Model)
-                return orpoLossPrefixShared(model, split.promptIds, split.chosenResp, split.rejectedResp, cfg.orpoLambda, chunk);
-              return orpoLossPrefixSharedGemma(model as Gemma4Model, split.promptIds, split.chosenResp, split.rejectedResp, cfg.orpoLambda, chunk);
+                return orpoLossPrefixShared(model, split.promptIds, split.chosenResp, split.rejectedResp, cfg.orpoLambda, chunk, cfg.sftScope);
+              return orpoLossPrefixSharedGemma(model as Gemma4Model, split.promptIds, split.chosenResp, split.rejectedResp, cfg.orpoLambda, chunk, cfg.sftScope);
             }
             notePrefixFallback();
           }
-          return orpoLoss(model, currentBatch!, cfg.orpoLambda, chunk);
+          return orpoLoss(model, currentBatch!, cfg.orpoLambda, chunk, cfg.sftScope);
         } finally {
           restorePrimals(lora, saved);
         }
@@ -897,7 +965,7 @@ async function orpoLoop(
         // Diagnostics recompute the two forwards (like dpoMetrics) — cheap at
         // B=1 (response-only head, no full logits) and gated by stepsPerReport.
         // Reusing the value_and_grad forward is a shared-with-DPO follow-on.
-        const m = orpoMetrics(model, currentBatch!, cfg.orpoLambda);
+        const m = orpoMetrics(model, currentBatch!, cfg.orpoLambda, cfg.sftScope);
         const elapsed = (Date.now() - t0) / 1000;
         emit({
           type: "metric",
@@ -929,7 +997,7 @@ async function orpoLoop(
             chosenIds: [ex.chosenIds], rejectedIds: [ex.rejectedIds],
             chosenMask: [ex.chosenMask], rejectedMask: [ex.rejectedMask],
           };
-          const m = orpoMetrics(model, vb, cfg.orpoLambda);
+          const m = orpoMetrics(model, vb, cfg.orpoLambda, cfg.sftScope);
           vl += m.loss; va += m.accuracy; vm += m.margin; vn++;
           clearCache();
         }
@@ -1105,10 +1173,16 @@ function clipGradsByNorm(grads: MlxArray[], normVal: number, maxNorm: number): v
   }
 }
 
+/** Supervised (response) tokens across ALL rows of the batch — the count
+ *  tokens/sec is reported over (mlx-lm's n_tokens counts every row too). */
 function countResponseTokens(batch: SftBatch): number {
-  const promptLen = batch.promptLens[0]!;
-  const len = batch.ids[0]!.length;
-  return Math.max(0, len - Math.max(promptLen, 1));
+  let total = 0;
+  for (let r = 0; r < batch.ids.length; r++) {
+    const promptLen = batch.promptLens[r]!;
+    const len = batch.ids[r]!.length;
+    total += Math.max(0, len - Math.max(promptLen, 1));
+  }
+  return total;
 }
 
 async function fileExists(path: string): Promise<boolean> {

package/src/web/skills/memory/SKILL.md

@@ -20,26 +20,49 @@ the user's machine. Nothing about their memory leaves the device.
 
 When the answer depends on personal continuity — an explicit memory/recall
 request, or a named project, person, decision, preference, or history that is
-not explained in the current chat — consult memory before answering or asking
-the user to re-explain.
+not explained in the current chat — look it up **before** answering or asking
+the user to re-explain. Doing the lookup first, instead of answering from first
+principles, is itself the helpful move.
 
 Do **not** use memory for weather, current public facts, generic web research,
 or ordinary coding/file tasks when the current files or the web tools answer the
 question. Memory is for user-specific context, not for performing familiarity.
 
-1. **Search.** Call `memory_search` with the topic (plain phrasing is fine —
-   a name or key noun). It returns ranked articles and sample lines.
-2. **Read enough.** For short or central articles, call `memory_read`. For long
-   articles, use `memory_toc` then `memory_section` to read the relevant part.
-   The article is the answer — read it rather than reconstructing the user's
-   position from scattered fragments. Treat it as their current view.
-3. **Follow nearby context when useful.** Use `memory_links` if backlinks or
-   related concepts matter. `memory_list` gives an overview when search comes up
-   short. mlx-bun reference docs are separate from personal memory; use
-   `reference_search`, `reference_read`, and `reference_list` for those.
-   `memory_status` answers setup/schedule/location questions.
-4. **Use it silently, as a prior.** Let what you find shape your response like
-   a long-time colleague would — don't announce "I searched your memory."
+The read path is **FIND the article → READ it small → answer**. It is
+deterministic navigation — never a vector search, and there is no way to
+query/sort articles by an infobox field (the infobox is facts you *read*, via
+`memory_infobox`, not a filter).
+
+1. **FIND the article.**
+   - When the user names a specific thing, person, or project, call
+     `memory_resolve` with the name as said ("S5 IIX", "the Lumix"). It returns
+     the matched stem, title, kind, and lead — no search, no guessing.
+   - For "what do I have about X", call `memory_category` with a `category`
+     (e.g. `Lenses`), `type`, or `series`. This is membership, not search: it
+     lists the articles that are actually about X.
+2. **READ it small (the default).** Call `memory_read` to get the article's TOC
+   + lead, then `memory_section` to read just the **one** section you need. The
+   whole article is the exception — pass `force=true` only when you truly need
+   all of it. The article is the user's consolidated current position; read it
+   rather than reconstructing their view from scattered fragments.
+3. **Follow the graph / read the infobox when useful.** `memory_links` shows
+   outgoing links grouped by origin (infobox / series / see also / prose) plus
+   backlinks — use it to hop to a neighbour (e.g. from a camera's infobox
+   `mount: [[L-Mount]]` to the mount article). `memory_infobox` surfaces the
+   structured facts to read. `memory_list` is a bare overview;
+   `memory_status` answers setup/schedule/location questions. mlx-bun reference
+   docs are separate from personal memory; use `reference_search`,
+   `reference_read`, and `reference_list` for those.
+4. **`memory_search` is the LAST resort.** Only fall back to it when
+   `memory_resolve` / `memory_category` have failed across a couple of
+   phrasings. It is a plain substring scan that doesn't understand meaning.
+5. **Use it silently, as a continuation.** Let what you find shape your response
+   like a long-time colleague who already knows the state of things. Speak as a
+   continuation, never as a retrieval report: do not preface answers with "per
+   the wiki…", "according to the article…", "I checked your memory…", or
+   "welcome back, I see you're working on X". Cite an article by name only if
+   the user asks where something came from, or to distinguish "the wiki says X"
+   from "I think Y".
 
 Use memory as an invisible prior: it should narrow relevance and improve the
 answer, not become the topic of the answer. Avoid performative recall — do not
@@ -85,8 +108,8 @@ wiki, scheduling nightly synthesis). Confirm before each persistent action.
 
 ## What not to do
 
-- Don't claim a fact "from memory" that you didn't read in an article — search
-  and read first, or say you don't have it.
+- Don't claim a fact "from memory" that you didn't read in an article — find
+  and read the article first, or say you don't have it.
 - Don't write to or edit the wiki during a normal conversation; the read tools
   are read-only by design. Synthesis is a separate, deliberate step.
 - Do open the wiki or a specific article in Obsidian/Finder if the user asks to