mover-os 4.7.8 → 4.7.10

package/src/dashboard/lib/goal-forecast.js

@@ -15,23 +15,30 @@ function computeGoalForecast({ strategy, activeContext, distribution, engineHeal
     now,
   });
 
-  const current = parsed.current;
+  const current = parsed.current;                 // null when progress is unmeasured
   const target = parsed.target;
-  const needed = Math.max(0, target - current);
+  const hasProgress = current != null;
+  const needed = (target && hasProgress) ? Math.max(0, target - current) : null;
   const deadline = parsed.deadline;
   const daysRemaining = deadline ? daysBetween(localDateKey(now), deadline) : null;
   const daysSafe = daysRemaining == null ? null : Math.max(0, daysRemaining);
-  const requiredPerDay = daysSafe == null
+  const requiredPerDay = (needed == null || daysSafe == null)
     ? null
     : daysSafe === 0 ? needed : round(needed / daysSafe, 2);
-  const progressPct = target > 0 ? Math.min(100, Math.round((current / target) * 100)) : 0;
+  // progressPct is null (UNMEASURED), never a false 0, when no scoped progress exists.
+  const progressPct = (target > 0 && hasProgress) ? Math.min(100, Math.round((current / target) * 100)) : null;
 
+  // Status is scoped to the OUTCOME. A real dated target with no scoped progress
+  // reads "unknown" (-> "Not measured" in the UI), never a fabricated on-track. A
+  // scoped zero reads on-track (0 of 2, deadline ahead). [sol #11 cross-scope]
   let status = "unknown";
-  if (target && current >= target) status = "complete";
+  if (!target) status = "unknown";
+  else if (hasProgress && current >= target) status = "complete";
   else if (daysRemaining != null && daysRemaining < 0) status = "failed";
+  else if (!hasProgress) status = "unknown";
   else if (daysRemaining != null && daysRemaining <= 1 && needed > 2) status = "unlikely";
   else if (requiredPerDay != null && requiredPerDay > 1) status = "at-risk";
-  else if (target) status = "on-track";
+  else status = "on-track";
 
   // Only act on distribution we actually measured. Unavailable (null) distribution
   // must NOT trigger a "0 actions logged" experiment. [false-zero — Codex, T261]
@@ -57,7 +64,7 @@ function computeGoalForecast({ strategy, activeContext, distribution, engineHeal
     pushAction(adjustments, workflows, {
       workflow: "/pivot-strategy",
       title: status === "failed" ? "Close the failed Single Test" : "Recalibrate the current strategy",
-      detail: `${current}/${target} against the active target. Keep the test, kill it, or replace it with a dated operating gate.`,
+      detail: `${current ?? "—"}/${target} against the active target. Keep the test, kill it, or replace it with a dated operating gate.`,
       priority: status === "failed" ? "critical" : "high",
     });
   }
@@ -85,14 +92,34 @@ function computeGoalForecast({ strategy, activeContext, distribution, engineHeal
   return {
     available,
     singleTest: parsed.singleTest || null,
+    // current stays null when the target is parseable but progress is unmeasured
+    // (a clean bet with no scoped record) — the UI shows "Progress not measured".
     current: available ? current : null,
     target: available ? target : null,
     unit: parsed.unit,
+    // kind rides with the parsed counter when one exists (the verdict must
+    // cite what the numbers actually count); keyword classification only
+    // labels the no-counter cases (revenue/vitality wording, available:false).
+    kind: parsed.counterKind || classifyGoalKind(strategy && strategy.singleTest),
+    // shape: "clean" (one metric + date), "compound" (a multi-signal gate), or
+    // "unparseable" (no target the dashboard can score). The hero renders each
+    // differently; a compound/legacy bet gets a "rewrite for clarity" affordance.
+    gate: parsed.gate === true,
+    shape: parsed.shape || (parsed.gate ? "compound" : (available ? "clean" : "unparseable")),
+    // whether `current` came from a real test-scoped record vs is just unmeasured.
+    progressMeasured: parsed.progressMeasured === true,
+    // the input commitment (daily quota) + the channel it names, both SEPARATE
+    // from the bet — Today renders these, never the hero.
+    commitment: (strategy && strategy.commitment) || null,
+    channel: parseChannel(strategy && strategy.commitment),
     deadline,
     daysRemaining,
-    needed,
-    requiredPerDay,
-    progressPct,
+    // Derived pace numerals are honest-null when there is no measurable target
+    // (a gate/unparseable test) OR when the target is real but progress is
+    // unmeasured. Secondary readers that copy them raw must not report a false 0%.
+    needed: available ? needed : null,
+    requiredPerDay: available ? requiredPerDay : null,
+    progressPct: available ? progressPct : null,
     status,
     source: parsed.source,
     distribution7d: total7dKnown ? total7d : null,
@@ -106,22 +133,87 @@ function pushAction(adjustments, workflows, action) {
   if (action.workflow && !workflows.includes(action.workflow)) workflows.push(action.workflow);
 }
 
+// The channel named in the Commitment ("...via X replies and DMs; ...") — the
+// hero's support line uses it ("From X replies and DMs, by Jul 26"). Null-safe.
+function parseChannel(commitment) {
+  if (!commitment) return null;
+  const m = String(commitment).match(/\b(?:via|through|on|using)\s+([^;.,]+?)(?=\s*[;.,]|$)/i);
+  return m ? m[1].trim() : null;
+}
+
+// A scoped progress record's unit must be the SAME kind of thing as the target.
+// The HEAD noun (last word) must match, so "0/2 paying customers" counts toward a
+// "customers" target, but "2/2 customer support calls" (head = calls) and
+// "1/2 customer interviews" (head = interviews) do NOT — a shared adjective is not
+// a unit match, or a same-denominator side metric fabricates "Complete". [sol #12]
+function unitFamilyMatch(scopedUnit, targetUnit) {
+  const norm = (s) => String(s || "").toLowerCase().replace(/[^a-z ]+/g, " ").trim().replace(/s\b/g, "");
+  const t = norm(targetUnit).split(/\s+/).filter(Boolean);
+  const s = norm(scopedUnit).split(/\s+/).filter(Boolean);
+  if (!t.length || !s.length) return false;
+  return t[t.length - 1] === s[s.length - 1];  // head nouns must be identical
+}
+
+// What currency is the goal stated in, and does anything on file measure it?
+// Drives the goal-anchored verdict on Evidence: an installs goal is pushed by
+// distribution receipts; a distribution goal IS the receipts; a revenue or
+// vitality goal has no parser yet, so the card must say "unmeasured" instead
+// of pretending workflow counts answer it. Order matters: adoption phrasing
+// ("15 activated installs") usually also names the channel, so adoption wins
+// when both appear. Returns null when nothing matches (generic verdict).
+function classifyGoalKind(singleTest) {
+  const t = String(singleTest || "").toLowerCase();
+  if (!t) return null;
+  if (/\b(installs?|activat|referrals?|sign-?ups?|customers?|users?|sales?|purchases?|buyers?|strangers?)/.test(t)) return "adoption";
+  if (/\b(dms?|outreach|repl(y|ies)|posts?|publish\w*|distribut\w*|articles?|reels?|videos?|content|newsletters?|followers?|subscribers?|views?|audience|impressions?)\b/.test(t)) return "distribution";
+  if (/(revenue|mrr\b|income|profit|£|\$|€)/.test(t)) return "revenue";
+  if (/\b(sleep|gym|weight|prayers?|fajr|salah|steps|health|energy|fasting)\b/.test(t)) return "vitality";
+  return null;
+}
+
 function parseGoalProgress({ singleTest, sourceText, targetDate, now }) {
   const out = {
     singleTest: singleTest || null,
-    current: 0,
+    current: null,          // measured ONLY from a test-scoped record; null = unmeasured
     target: 0,
     unit: "customers",
+    counterKind: null,
+    shape: "unparseable",
+    progressMeasured: false,
     deadline: null,
     source: "strategy",
   };
 
   if (singleTest) {
+    // A multi-signal GATE ("Hit 2 of 3": 10 conversations / 5 install starts /
+    // 2 paid) is not one countable number. The single-counter regex below would
+    // grab "5 install starts" as target=5 and pair it with an unrelated sales
+    // count elsewhere on file, fabricating "4 of 5 installs". Detect the gate,
+    // refuse to collapse it, keep the deadline so the card can still pace to the
+    // date, and let the UI render the honest "scored by hand" state.
+    //
+    // The marker must be a gate VERDICT, not a bare "N of M": require a scoring
+    // verb (hit/pass/meet/clear, "of" or "out of") OR an "N of M =" verdict
+    // clause. A bare "N of M" would false-trigger on "Day 2 of 14: send 50 DMs"
+    // (a real distribution counter) and hide it; the verb/"=" gate keeps those
+    // parsing normally. A "+" rider ("15 installs + 1 referral") has no "of" at
+    // all and still parses its primary counter. [gate honesty, sol #10 hardening]
+    if (/\b(?:hit|hitting|pass(?:ed)?|meet|met|clear(?:ed)?)\s+\d+\s+(?:out\s+of|of)\s+\d+\b|\b\d+\s+(?:out\s+of|of)\s+\d+\s*=/i.test(singleTest)) {
+      out.gate = true;
+      out.counterKind = "gate";
+      out.shape = "compound";
+      out.deadline = extractDate(singleTest, now) || targetDate || null;
+      return out; // target stays 0 -> available:false -> honest-null, no fabricated counter
+    }
     // Regex captures count-based phrasing (e.g. "10 paying customers/sales")
     // AND activation phrasing ("N activated installs / referrals"). The
     // extended unit list keeps backwards-compat and makes an activation-style
     // mid-term metric ("N activated installs + M referrals by <date>") parse correctly.
-    const targetMatch = singleTest.match(/\b(\d+)\s+(?:paying\s+|activated\s+)?(?:strangers?|customers?|sales|users?|installs?|referrals?|activations?)\b/i);
+    // The negative lookahead stops an adoption noun acting as a MODIFIER of a
+    // distribution noun from being read as the counter: "10 sales posts" is a
+    // publishing target, never a sales counter. [terra F3, 2026-07-10]
+    const DIST_NOUN = "posts?|dms?|reels?|articles?|videos?|emails?|threads?|newsletters?";
+    const targetMatch = singleTest.match(new RegExp("\\b(\\d+)\\s+(?:paying\\s+|activated\\s+)?(?:strangers?|customers?|sales|users?|installs?|referrals?|activations?)\\b(?!\\s+(?:" + DIST_NOUN + ")\\b)", "i"));
     if (targetMatch) {
       out.target = Number(targetMatch[1]);
       // Set unit from the matched phrase so the hero strip says
@@ -131,29 +223,45 @@ function parseGoalProgress({ singleTest, sourceText, targetDate, now }) {
       else if (/referral/.test(phrase)) out.unit = "referrals";
       else if (/user/.test(phrase)) out.unit = "users";
       else out.unit = "customers";
+      out.counterKind = "adoption";
+      out.shape = "clean";
+    } else {
+      // Distribution counter ("publish 10 posts", "send 50 DMs", "10 sales
+      // posts"): the kind rides with the SAME match that set the number, so
+      // the verdict can never cite a counter the parse didn't produce.
+      const distMatch = singleTest.match(new RegExp("\\b(\\d+)\\s+(?:[a-z-]+\\s+)?(" + DIST_NOUN + ")\\b", "i"));
+      if (distMatch) {
+        out.target = Number(distMatch[1]);
+        out.unit = distMatch[2].toLowerCase();
+        out.counterKind = "distribution";
+        out.shape = "clean";
+      }
     }
     const deadline = extractDate(singleTest, now) || targetDate;
     if (deadline) out.deadline = deadline;
   }
 
   const text = sourceText || "";
-  const ratios = Array.from(text.matchAll(/\b(\d+)\s*\/\s*(\d+)\s*(?:sales|paying|customers?|strangers?|users?)\b/gi));
-  if (ratios.length) {
-    const latest = ratios[ratios.length - 1];
-    out.current = Number(latest[1]);
-    if (!out.target) out.target = Number(latest[2]);
-    out.source = "active_context_ratio";
-  }
 
-  const sales = [
-    ...Array.from(text.matchAll(/\b(?:LIVE,\s*|Status:\s*[^\n]{0,60}?|confirmed\s+|current:\s*)(\d+)\s+(?:SALES|sales|purchases)\b/g)),
-    ...Array.from(text.matchAll(/\b(\d+)\s+sales\s+confirmed\b/gi)),
-  ];
-  if (sales.length) {
-    const max = Math.max(...sales.map(m => Number(m[1])).filter(Number.isFinite));
-    if (Number.isFinite(max) && max > out.current) {
-      out.current = max;
-      out.source = "active_context_sales";
+  // Progress is TEST-SCOPED, and ONLY test-scoped. A generic lifetime line
+  // ("LIVE, 4 SALES" — all from April) or a historical ratio ("4/10 sales" from
+  // a dead strategy) must NOT count as progress toward THIS bet; doing so
+  // fabricated "4 of 2 · complete" the moment the target became a clean 2. The
+  // ONLY thing that counts as current is an explicit scoped record whose
+  // denominator and unit family match the active target:
+  //   "Current bet progress: 0/2 paying customers". [sol #11 cross-scope bug]
+  if (out.target) {
+    const scoped = text.match(/current\s+bet\s+progress:\s*(\d+)\s*\/\s*(\d+)\s*([a-z][a-z ]*)?/i);
+    if (scoped) {
+      const cur = Number(scoped[1]);
+      const den = Number(scoped[2]);
+      const scopedUnit = (scoped[3] || "").trim();
+      const unitOk = !scopedUnit || unitFamilyMatch(scopedUnit, out.unit);
+      if (Number.isFinite(cur) && den === out.target && unitOk) {
+        out.current = cur;               // a scoped ZERO is honest progress, not "unmeasured"
+        out.progressMeasured = true;
+        out.source = "scoped_progress";
+      }
     }
   }
 
@@ -166,8 +274,12 @@ function parseGoalProgress({ singleTest, sourceText, targetDate, now }) {
 
 function extractDate(text, now) {
   if (!text) return null;
-  const iso = text.match(/\b(20\d{2}-[01]\d-[0-3]\d)\b/);
-  if (iso) return iso[1];
+  const iso = text.match(/\b(20\d{2})-([01]\d)-([0-3]\d)\b/);
+  if (iso) {
+    // Impossible dates (2026-02-30) must yield NO deadline, not a silent
+    // JS rollover to March 2 rendered as a real target. [terra F4, 2026-07-10]
+    return validCalendarDay(Number(iso[1]), Number(iso[2]) - 1, Number(iso[3])) ? iso[0] : null;
+  }
   const months = ["jan","feb","mar","apr","may","jun","jul","aug","sep","sept","oct","nov","dec","january","february","march","april","june","july","august","september","october","november","december"];
   const m = text.match(new RegExp(`\\b(?:by\\s+)?(${months.join("|")})\\s+(\\d{1,2})(?:,?\\s*(20\\d{2}))?`, "i"));
   if (!m) return null;
@@ -175,9 +287,17 @@ function extractDate(text, now) {
   const day = Number(m[2]);
   const year = m[3] ? Number(m[3]) : now.getFullYear();
   if (month < 0 || !Number.isFinite(day)) return null;
+  if (!validCalendarDay(year, month, day)) return null; // "Feb 30" rolls over too
   return localDateKey(new Date(year, month, day));
 }
 
+// True only when (year, month0, day) names a day that exists: round-trip
+// through UTC and require every component to survive unchanged.
+function validCalendarDay(year, month0, day) {
+  const d = new Date(Date.UTC(year, month0, day));
+  return d.getUTCFullYear() === year && d.getUTCMonth() === month0 && d.getUTCDate() === day;
+}
+
 function monthIndex(name) {
   const n = String(name || "").toLowerCase().slice(0, 3);
   return { jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5, jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11 }[n] ?? -1;
@@ -301,4 +421,7 @@ function parseChainStages(chain) {
     .map((label) => ({ label, current: null }));
 }
 
-module.exports = { computeGoalForecast, parseDomainProgress };
+// parseGoalProgress exported for the menu-bar CLI (cmdPulseBar): the bar's
+// mission number must come from the SAME parse the dashboard shows, never a
+// second implementation that can drift. [owner: glance-number = the bet]
+module.exports = { computeGoalForecast, parseGoalProgress, parseDomainProgress, classifyGoalKind };

package/src/dashboard/lib/library-indexer-v2.js

@@ -3,6 +3,7 @@
 const path = require("path");
 const {
   archivesDir,
+  engineDir,
   libraryDir,
   libraryCheatsheetsDir,
   libraryPrinciplesDir,
@@ -189,6 +190,18 @@ function indexLibraryV2(vault) {
       .filter((e) => !e.name.startsWith(".") && !e.name.startsWith("_")).length;
   }
 
+  // Engine: count-only, top-level FILES of 02_Areas/Engine (subdirs like
+  // Dailies/ and State/ are their own worlds; the Library shelf browse lists
+  // exactly these files). Replaces a hardcoded 12 in the UI mapper — terra
+  // confirmed it fabricated (real vault held 15) and it contaminated the
+  // "indexed" headline sum (2026-07-12). Not added to totalCount, same
+  // reasoning as archives.
+  const engine = { count: 0 };
+  if (exists(engineDir(vault))) {
+    engine.count = safeListDir(engineDir(vault))
+      .filter((e) => e.isFile && !e.name.startsWith(".")).length;
+  }
+
   const totalCount =
     mocs.count + principles.count + cheatsheets.count + sops.count +
     scripts.count + inputs.count + entities.count;
@@ -205,6 +218,7 @@ function indexLibraryV2(vault) {
       inputs,
       entities,
       archives,
+      engine,
     },
   };
 }

package/src/dashboard/lib/library-search.js

@@ -0,0 +1,290 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// library-search.js — ONE truthful search index for the Library route.
+//
+// Sol full product review (2026-07-11, Library 5.0/10): the "EVERYTHING"
+// search box indexed only the libraryV2 subset while the other shelves were
+// counts with no rows behind them. This module makes the coverage equal the
+// advertised shelves: every shelf the bento names is either content-searchable
+// here or explicitly reported as notIndexable with the reason (CLI commands
+// are usage counts, not files).
+//
+// Contract:
+//   - Read-only. Never writes. Never leaves the declared shelf roots.
+//   - Bounded: per-file size cap, per-shelf file cap, result cap, passage cap.
+//   - Results carry root + vault-relative (or root-relative) path + a 1-based
+//     line anchor + the matched passage, so the UI can open the real file AT
+//     the passage in the existing viewer.
+//   - Honest coverage: shelves whose directory does not exist are reported in
+//     coverage.missing; shelves with nothing to read are in
+//     coverage.notIndexable. Nothing is silently skipped.
+//   - Non-text files (PDFs, images) match by NAME only and say so
+//     (nameOnly: true, line/passage null) — never implied content coverage.
+
+const MAX_FILE_BYTES = 256 * 1024;      // matches /api/file/read cap
+const MAX_FILES_PER_SHELF = 2000;
+const MAX_DEPTH = 6;
+const MAX_LIMIT = 100;
+const DEFAULT_LIMIT = 40;
+const PASSAGE_CAP = 240;
+const EXCLUDED_DIRS = new Set([
+  "node_modules", "dist", ".git", ".obsidian", ".trash", "coverage",
+]);
+
+// Extensions whose CONTENT we read as text. Everything else is name-only.
+const TEXT_EXTS = new Set([".md", ".txt", ".sh", ".js", ".mjs", ".ps1", ".canvas", ".json"]);
+
+// ── shelf definitions — ids are stable API; labels mirror the bento ─────────
+// dirs(ctx) returns the roots to walk for that shelf, each tagged with the
+// serving root id the file-read endpoint understands (vault|skills|workflows|hooks).
+const SHELVES = [
+  {
+    id: "engine", label: "Engine files",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "02_Areas", "Engine"), depth: 1 }],
+  },
+  {
+    id: "projects", label: "Projects",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "01_Projects"), depth: MAX_DEPTH }],
+  },
+  {
+    id: "library", label: "Library notes",
+    dirs: (ctx) => [
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "MOCs"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Principles"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "SOPs"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Cheatsheets"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Scripts"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "Decisions"), depth: 3 },
+    ],
+  },
+  {
+    id: "skills", label: "Skills",
+    dirs: (ctx) => [{ root: "skills", dir: path.join(ctx.claudeDir, "skills"), depth: 3 }],
+  },
+  {
+    id: "hooks", label: "Hooks",
+    dirs: (ctx) => [{ root: "hooks", dir: path.join(ctx.bundleRoot, "src", "hooks"), depth: 2 }],
+  },
+  {
+    id: "workflows", label: "Workflows",
+    dirs: (ctx) => [{ root: "workflows", dir: path.join(ctx.bundleRoot, "src", "workflows"), depth: 1 }],
+  },
+  {
+    id: "cli", label: "CLI commands",
+    notIndexable: "CLI commands are usage counts stored in your config, not files. There is no text to search.",
+  },
+  {
+    id: "people", label: "People",
+    dirs: (ctx) => [
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "People"), depth: 2 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "Organizations"), depth: 2 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "Places"), depth: 2 },
+    ],
+  },
+  {
+    id: "captures", label: "Captures",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "03_Library", "Inputs"), depth: 3 }],
+  },
+  {
+    id: "archives", label: "Archives",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "04_Archives"), depth: MAX_DEPTH }],
+  },
+];
+
+/** Map a serving-root id to its absolute directory. Used by the file-read
+ *  endpoint to resolve non-vault results with the same realpath containment
+ *  it already applies to the vault. Returns null for unknown roots. */
+function rootDirFor(ctx, root) {
+  if (root === "vault") return ctx.vault;
+  if (root === "skills") return path.join(ctx.claudeDir, "skills");
+  if (root === "workflows") return path.join(ctx.bundleRoot, "src", "workflows");
+  if (root === "hooks") return path.join(ctx.bundleRoot, "src", "hooks");
+  return null;
+}
+
+function walkFiles(dir, maxDepth, out, state) {
+  if (state.count >= MAX_FILES_PER_SHELF) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { return; }
+  for (const ent of entries) {
+    if (state.count >= MAX_FILES_PER_SHELF) return;
+    if (ent.name.startsWith(".")) continue;
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) {
+      if (EXCLUDED_DIRS.has(ent.name)) continue;
+      if (maxDepth > 1) walkFiles(full, maxDepth - 1, out, state);
+      continue;
+    }
+    if (!ent.isFile()) continue; // symlinks are not followed — containment stays real
+    out.push(full);
+    state.count += 1;
+  }
+}
+
+/** Collect the files behind one shelf. Returns { files: [{abs, root, rootDir}], missing } */
+function shelfFiles(shelf, ctx) {
+  const roots = shelf.dirs ? shelf.dirs(ctx) : [];
+  const files = [];
+  let anyDirExists = false;
+  const state = { count: 0 };
+  for (const r of roots) {
+    let stat = null;
+    try { stat = fs.statSync(r.dir); } catch (_e) { /* absent */ }
+    if (!stat || !stat.isDirectory()) continue;
+    anyDirExists = true;
+    const abs = [];
+    walkFiles(r.dir, r.depth || 1, abs, state);
+    for (const a of abs) files.push({ abs: a, root: r.root, rootDir: rootDirFor(ctx, r.root) });
+  }
+  return { files, missing: roots.length > 0 && !anyDirExists };
+}
+
+/** Build the passage around the first match inside a line, capped. */
+function passageFrom(line, matchIdx, qLen) {
+  const trimmed = line.trim();
+  if (trimmed.length <= PASSAGE_CAP) return trimmed;
+  // center the window on the match
+  const lead = Math.max(0, matchIdx - Math.floor((PASSAGE_CAP - qLen) / 2));
+  const slice = line.slice(lead, lead + PASSAGE_CAP).trim();
+  return slice;
+}
+
+/**
+ * searchLibrary(ctx, opts) — the one index.
+ *   ctx  = { vault, bundleRoot, claudeDir }
+ *   opts = { q, shelf, limit }
+ *     q     — case-insensitive substring; empty q + shelf = browse listing
+ *     shelf — shelf id to scope to ("" = every indexed shelf)
+ *     limit — max results (1..100)
+ * Returns { q, shelf, results, truncated, scanned, coverage }.
+ */
+function searchLibrary(ctx, opts = {}) {
+  const q = String(opts.q || "").slice(0, 200);
+  const scope = String(opts.shelf || "");
+  const limit = Math.max(1, Math.min(MAX_LIMIT, Number(opts.limit) || DEFAULT_LIMIT));
+  const lc = q.toLowerCase();
+
+  const coverage = { indexed: [], notIndexable: [], missing: [] };
+  const results = [];
+  let scannedFiles = 0;
+  let skippedLarge = 0;
+  let truncated = false;
+
+  for (const shelf of SHELVES) {
+    if (shelf.notIndexable) {
+      coverage.notIndexable.push({ id: shelf.id, label: shelf.label, reason: shelf.notIndexable });
+      continue;
+    }
+    const { files, missing } = shelfFiles(shelf, ctx);
+    if (missing) {
+      coverage.missing.push({ id: shelf.id, label: shelf.label });
+      continue;
+    }
+    coverage.indexed.push({ id: shelf.id, label: shelf.label, files: files.length });
+
+    if (scope && scope !== shelf.id) continue; // counted for coverage, never searched
+
+    for (const f of files) {
+      // Every skill's file is literally named SKILL.md — the skill's actual
+      // name is its folder. Rendering the basename made the whole Skills
+      // shelf read "SKILL.md, SKILL.md, ..." (owner report + terra CONFIRMED
+      // #1, 2026-07-12). Same rule for any convention-named container file.
+      const base = path.basename(f.abs);
+      let name = base;
+      if (/^(SKILL|README|INDEX)\.md$/i.test(base)) {
+        const folder = path.basename(path.dirname(f.abs));
+        if (folder && folder !== "." && folder !== path.basename(f.rootDir)) name = folder;
+      }
+      const relPath = path.relative(f.rootDir, f.abs).split(path.sep).join("/");
+      // ext/textReadable ALWAYS derive from the real file, never the display
+      // name — a folder-derived name has no extension and would silently
+      // demote the file to name-only search.
+      const ext = path.extname(base).toLowerCase();
+      const textReadable = TEXT_EXTS.has(ext);
+
+      let mtime = null;
+      let size = 0;
+      try { const st = fs.statSync(f.abs); mtime = st.mtime.toISOString(); size = st.size; } catch (_e) { continue; }
+
+      // Browse mode: empty query + a shelf scope lists the shelf's real files.
+      if (!lc) {
+        if (!scope) continue; // browsing "everything" is the catalog's job
+        results.push({
+          shelf: shelf.id, shelfLabel: shelf.label, name, relPath, root: f.root,
+          line: null, passage: null, matches: 0, nameOnly: !textReadable, mtime,
+        });
+        continue;
+      }
+
+      const nameHit = name.toLowerCase().includes(lc);
+
+      if (!textReadable) {
+        // Content is not text — a name match is the only honest match.
+        if (nameHit) {
+          results.push({
+            shelf: shelf.id, shelfLabel: shelf.label, name, relPath, root: f.root,
+            line: null, passage: null, matches: 0, nameOnly: true, mtime,
+          });
+        }
+        continue;
+      }
+
+      if (size > MAX_FILE_BYTES) { skippedLarge += 1; continue; }
+
+      let content = "";
+      try { content = fs.readFileSync(f.abs, "utf8"); } catch (_e) { continue; }
+      scannedFiles += 1;
+
+      let firstLine = null;
+      let firstPassage = null;
+      let matches = 0;
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const idx = lines[i].toLowerCase().indexOf(lc);
+        if (idx === -1) continue;
+        matches += 1;
+        if (firstLine === null) {
+          firstLine = i + 1;
+          firstPassage = passageFrom(lines[i], idx, lc.length);
+        }
+      }
+
+      if (!nameHit && matches === 0) continue;
+      results.push({
+        shelf: shelf.id, shelfLabel: shelf.label, name, relPath, root: f.root,
+        line: firstLine, passage: firstPassage, matches,
+        nameOnly: matches === 0, mtime,
+      });
+    }
+  }
+
+  // Rank: name matches first, then by match density, then recency.
+  if (lc) {
+    results.sort((a, b) => {
+      const an = a.name.toLowerCase().includes(lc) ? 1 : 0;
+      const bn = b.name.toLowerCase().includes(lc) ? 1 : 0;
+      if (an !== bn) return bn - an;
+      if (a.matches !== b.matches) return b.matches - a.matches;
+      return String(b.mtime || "").localeCompare(String(a.mtime || ""));
+    });
+  } else {
+    results.sort((a, b) => String(b.mtime || "").localeCompare(String(a.mtime || "")));
+  }
+
+  if (results.length > limit) {
+    results.length = limit;
+    truncated = true;
+  }
+
+  return {
+    q, shelf: scope || "all",
+    results, truncated,
+    scanned: { files: scannedFiles, skippedLarge },
+    coverage,
+  };
+}
+
+module.exports = { searchLibrary, rootDirFor, SHELVES };