mover-os 4.7.6 → 4.7.8

package/src/dashboard/lib/metrics-log-parser.js

@@ -0,0 +1,76 @@
+"use strict";
+
+const { metricsLogPath, healthAnalysisPath, safeRead, safeStat } = require("./paths");
+
+// Parse Metrics_Log.md + Health_Analysis_Full.md for vitality dashboard data.
+
+function parseMetricsLog(vault) {
+  const mPath = metricsLogPath(vault);
+  const hPath = healthAnalysisPath(vault);
+  const mText = safeRead(mPath);
+  const hText = safeRead(hPath);
+  const mStat = safeStat(mPath);
+
+  const out = {
+    available: !!(mText || hText),
+    metricsLogPath: mPath,
+    healthAnalysisPath: hPath,
+    lastUpdated: mStat ? mStat.mtime : null,
+    latestMetrics: {},
+    recentEntries: []
+  };
+
+  if (mText) {
+    // Extract bold-key fields (most recent ones first)
+    const fieldRe = /\*\*([^*]+):\*\*\s*([^\n]+)/g;
+    let m;
+    while ((m = fieldRe.exec(mText)) !== null) {
+      const k = m[1].trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_|_$/g, "");
+      if (!out.latestMetrics[k]) out.latestMetrics[k] = m[2].trim();
+    }
+
+    // Extract date-prefixed log entries
+    const lines = mText.split("\n");
+    for (const line of lines) {
+      const dateMatch = line.match(/^[-*]?\s*\[?(\d{4}-\d{2}-\d{2})\]?\s+(.+)$/);
+      if (dateMatch) {
+        out.recentEntries.push({ date: dateMatch[1], text: dateMatch[2].trim() });
+      }
+    }
+    out.recentEntries = out.recentEntries.slice(-10).reverse();
+  }
+
+  // Health Analysis: extract HRV, sleep, RHR, weight summary.
+  //
+  // T242 bug hunt fix (C#7): keep the relaxed key-then-anything-then-value
+  // greedy regex (it was finding correct values like sleep=6.73h, hrv=8.9ms
+  // in prose), but add a sanity-range filter. Previous bug: `Weight gain
+  // (+3-4 kg since baseline)` captured "4" as weight. The lazy `[^|]*?`
+  // matched " gain (+3-", then `\d+` grabbed "4", then `\s*kg` matched
+  // " kg". The 4 was a delta, not the weight. Range 30-300 rejects it.
+  // Same fix kills RHR=0.43 (some Fitbit entropy decimal) — out of 30-200.
+  if (hText) {
+    out.hrvLatest = extractMetricInRange(hText, /HRV[^|]*?(\d+(?:\.\d+)?)\s*(?:ms|rmssd)/i, 5, 200);
+    out.sleepLatest = extractMetricInRange(hText, /Sleep[^|]*?(\d+(?:\.\d+)?)\s*(?:h|hours?)/i, 0, 16);
+    out.rhrLatest = extractMetricInRange(hText, /(?:RHR|Resting HR)[^|]*?(\d+(?:\.\d+)?)\s*(?:bpm)?/i, 30, 200);
+    out.weightLatest = extractMetricInRange(hText, /Weight[^|]*?(\d+(?:\.\d+)?)\s*(?:kg|lb)/i, 30, 300);
+  }
+
+  return out;
+}
+
+function extractMetricInRange(text, re, min, max) {
+  const m = text.match(re);
+  if (!m) return null;
+  const v = parseFloat(m[1]);
+  if (!Number.isFinite(v)) return null;
+  if (v < min || v > max) return null;
+  return m[1];
+}
+
+function extractMetricFromText(text, re) {
+  const m = text.match(re);
+  return m ? m[1] : null;
+}
+
+module.exports = { parseMetricsLog };

package/src/dashboard/lib/moves-usage-parser.js

@@ -0,0 +1,184 @@
+"use strict";
+
+// Moves usage parser — lights the Moves map (~25 Mover moves) by how often
+// each move has ACTUALLY run, read from Claude Code's real append-only
+// command history at ~/.claude/history.jsonl.
+//
+// Per the dashboard's "TELEMETRY NEVER" promise: this reads a local file
+// Claude Code already writes. Nothing is sent anywhere.
+//
+// Source line shape (one JSON object per line, append-only):
+//   { "display": "/log ", "pastedContents": {}, "timestamp": 1771088938619,
+//     "project": "<vault>/01_Projects/Mover OS Bundle",
+//     "sessionId": "50ba...-2562" }
+//
+//   - `display`   : the raw prompt text the user submitted. Slash commands
+//                   and `moveros <sub>` invocations start here.
+//   - `timestamp` : epoch ms of the invocation.
+//   - `project`   : the LITERAL cwd string at invocation time. NOT a slug.
+//                   On a machine that migrated platforms, this field can carry
+//                   both old and current absolute paths for the same vault.
+//
+// SCOPING (the crux): we count only invocations made inside THIS vault.
+//   - The dashboard server's canonical vault identity is
+//     `fs.realpathSync(path.resolve(vault))` (server.js:63). We mirror that
+//     so a symlinked vault resolves to the same identity here.
+//   - We then keep a history row only if its `project`, normalized to a
+//     boundary-aligned path-segment array, CONTAINS the vault realpath's
+//     distinctive tail segments as a contiguous run. This is a path-BOUNDARY
+//     match, NOT a substring `includes` — so a sibling like
+//     `Architect_OS_backup/` is correctly excluded (its segment is
+//     `Architect_OS_backup`, which never equals `Architect_OS`).
+//   - Old Windows-era rows can't be realpath-resolved on this machine, but
+//     they ARE this vault's history. The segment-anchor match recovers them
+//     (separators normalized `\` → `/`) without loosening the boundary.
+//
+// FALSE-ZERO DISCIPLINE (T261): history.jsonl absent or unreadable returns
+//   { available:false, source:'', totalRuns:null, byCommand:{} }
+// so the UI shows "calibrating", never a fabricated all-zero map. We NEVER
+// invent counts. A move the user simply hasn't run is ABSENT from byCommand
+// — the UI treats absent as a REAL zero ("never").
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+function historyPath() {
+  return path.join(os.homedir(), ".claude", "history.jsonl");
+}
+
+// Normalize any path string (Windows or POSIX) to a clean, trailing-slash-
+// stripped, forward-slash form, then split into non-empty segments.
+function pathSegments(p) {
+  return String(p)
+    .replace(/\\/g, "/")   // Windows separators → POSIX
+    .replace(/\/+$/, "")   // drop trailing slash(es)
+    .split("/")
+    .filter(Boolean);
+}
+
+// Build the vault's distinctive tail anchor: the last up-to-3 segments of the
+// vault realpath (e.g. ["Documents","Obsidian","Architect_OS"]). Three
+// segments is distinctive enough to avoid collisions while still matching the
+// cross-platform paths, which share the `Documents/Obsidian/Architect_OS`
+// tail. Falls back to whatever segments exist for shallow vault paths.
+function vaultAnchorSegments(vault) {
+  let vaultReal;
+  try {
+    vaultReal = fs.realpathSync(path.resolve(vault));
+  } catch (_) {
+    // Vault path doesn't resolve (missing / not yet created). Fall back to the
+    // literal resolved string so scoping still has an anchor to match against.
+    vaultReal = path.resolve(vault);
+  }
+  const segs = pathSegments(vaultReal);
+  return segs.slice(Math.max(0, segs.length - 3));
+}
+
+// True if `projectRaw` (a literal cwd from history) sits inside the vault.
+// Boundary-aligned: the anchor must appear as a contiguous run of WHOLE
+// segments. `Architect_OS_backup` never matches an `Architect_OS` anchor
+// segment, so sibling dirs are excluded.
+function projectMatchesVault(projectRaw, anchor) {
+  if (!projectRaw || anchor.length === 0) return false;
+  const segs = pathSegments(projectRaw);
+  for (let i = 0; i + anchor.length <= segs.length; i++) {
+    let hit = true;
+    for (let j = 0; j < anchor.length; j++) {
+      if (segs[i + j] !== anchor[j]) { hit = false; break; }
+    }
+    if (hit) return true; // everything after the anchor is a descendant → in
+  }
+  return false;
+}
+
+// Extract a Mover-move identity from a raw `display` string.
+// Returns { cmd, label } or null.
+//   - /slash-command   → cmd "log",          label "/log"
+//   - moveros <subcmd> → cmd "pulse",         label "moveros pulse"
+// Per the contract: command names are lowercase, may contain hyphens, and the
+// first letter is a-z (so we don't match `/1`, `/-x`, paths, etc.).
+function extractMove(display) {
+  const text = String(display || "");
+  const slash = text.match(/^\s*(\/[a-z][a-z-]+)/);
+  if (slash) {
+    const label = slash[1];
+    return { cmd: label.slice(1), label };
+  }
+  const cli = text.match(/^\s*moveros\s+([a-z-]+)/);
+  if (cli) {
+    return { cmd: cli[1], label: `moveros ${cli[1]}` };
+  }
+  return null;
+}
+
+// computeMovesUsage({ vault }) -> {
+//   available:  boolean,                 // false only when source is unreadable
+//   source:     string,                  // absolute history.jsonl path, or '' when absent
+//   totalRuns:  number | null,           // total in-scope move invocations; null when unavailable
+//   byCommand:  { [cmd]: { count, lastIso, lastLabel } }   // absent cmd === real zero
+// }
+function computeMovesUsage(opts = {}) {
+  const { vault } = opts;
+  const src = historyPath();
+
+  // False-zero gate: no readable history → unavailable, never a fake map.
+  let raw;
+  try {
+    raw = fs.readFileSync(src, "utf8");
+  } catch (_) {
+    return { available: false, source: "", totalRuns: null, byCommand: {} };
+  }
+
+  const anchor = vaultAnchorSegments(vault);
+  const byCommand = {};
+  // Track newest timestamp per command separately so the public shape only
+  // carries { count, lastIso, lastLabel } (no internal bookkeeping leaks out).
+  const lastTsByCmd = Object.create(null);
+  let totalRuns = 0;
+
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (_) {
+      // Forward-compat: a malformed line never aborts the scan. Skip it.
+      continue;
+    }
+    if (!projectMatchesVault(row.project, anchor)) continue;
+
+    const move = extractMove(row.display);
+    if (!move) continue;
+
+    const ts = Number(row.timestamp);
+    const hasTs = Number.isFinite(ts);
+    const iso = hasTs ? new Date(ts).toISOString() : null;
+
+    totalRuns += 1;
+    let entry = byCommand[move.cmd];
+    if (!entry) {
+      entry = byCommand[move.cmd] = { count: 0, lastIso: null, lastLabel: null };
+      lastTsByCmd[move.cmd] = -Infinity;
+    }
+    entry.count += 1;
+    // Keep the most-recent invocation's iso + label. Rows without a usable
+    // timestamp never overwrite a dated "last" (they stay as a fallback only
+    // if nothing dated was ever seen).
+    if (hasTs && ts > lastTsByCmd[move.cmd]) {
+      lastTsByCmd[move.cmd] = ts;
+      entry.lastIso = iso;
+      entry.lastLabel = move.label;
+    } else if (entry.lastLabel == null) {
+      // First sighting was undated — record at least the label so the UI has
+      // a name to show. lastIso stays null (honest: timestamp unknown).
+      entry.lastLabel = move.label;
+    }
+  }
+
+  return { available: true, source: src, totalRuns, byCommand };
+}
+
+module.exports = { computeMovesUsage };

package/src/dashboard/lib/onboarding-forge.js

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * onboarding-forge.js — turn the REAL list of Engine files being written into an
+ * ordered, human "forge" sequence for the onboarding synthesis beat (the moment the
+ * system composes your operating record from your answers).
+ *
+ * HONESTY CONTRACT: every beat after the lead-in corresponds 1:1 to a file the writer
+ * actually produces — never an invented step, never padding. Unknown-but-real files are
+ * appended (still honest) rather than dropped. Deterministic + zero-dep (mirrors the
+ * connect-recommender / skill-recommender pattern: pure logic here, rendered by the jsx).
+ *
+ * @param {Array<string>} files  file paths or basenames the finalize step will write
+ * @param {{cap?:number}} [opts]
+ * @returns {Array<{ key:string, label:string, file:string|null }>}  lead beat first
+ */
+
+// canonical compose order — the record is built identity-first, then the bet, then leverage
+const ORDER = [
+  "Identity_Prime", "Strategy", "Goals", "Mover_Dossier",
+  "Active_Context", "Auto_Learnings", "Metrics_Log", "Voice_DNA",
+];
+
+// each label is a present-tense act of composition, warm + specific (never "Writing file 3/5")
+const LABELS = {
+  Identity_Prime: "Shaping who you are",
+  Strategy:       "Setting your strategy",
+  Goals:          "Naming the bet",
+  Mover_Dossier:  "Taking stock of your leverage",
+  Active_Context: "Opening your working memory",
+  Auto_Learnings: "Preparing to learn your patterns",
+  Metrics_Log:    "Laying out your scoreboard",
+  Voice_DNA:      "Tuning to your voice",
+};
+
+function basename(name) {
+  return String(name || "").split(/[\\/]/).pop().replace(/\.md$/i, "").trim();
+}
+
+function forgeBeats(files, opts) {
+  const cap = (opts && Number.isFinite(opts.cap)) ? opts.cap : 6;
+  const list = Array.isArray(files) ? files : [];
+  const seen = new Set();
+  const ordered = [];
+
+  // 1. canonical order first (Identity → Strategy → Goals → Dossier → …)
+  for (const key of ORDER) {
+    if (!seen.has(key) && list.some((f) => basename(f) === key)) {
+      seen.add(key);
+      ordered.push(key);
+    }
+  }
+  // 2. any real file we don't have a canonical slot for — appended, never dropped (honest)
+  for (const f of list) {
+    const k = basename(f);
+    if (k && !seen.has(k)) { seen.add(k); ordered.push(k); }
+  }
+
+  const beats = ordered.slice(0, cap).map((k) => ({
+    key: k,
+    label: LABELS[k] || ("Writing " + k.replace(/_/g, " ")),
+    file: k + ".md",
+  }));
+
+  // lead beat — the real first act: parsing the transcript into a profile. file:null because
+  // it isn't a file being written, it's the read that precedes the writes.
+  return [{ key: "_read", label: "Reading your answers", file: null }, ...beats];
+}
+
+module.exports = { forgeBeats, LABELS, ORDER };

package/src/dashboard/lib/override-outcome-parser.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { dailiesDir } = require("./paths");
+const { localDateKey } = require("./date-utils");
+
+// override-outcome-parser.js — F18 / Codex viral #3. Cross-references each
+// override entry against subsequent Daily Notes to detect:
+//   - Did the deferred workflow actually run later? (resolution outcome)
+//   - Was the chosen alternative followed through? (justification outcome)
+//
+// Returns: array of { override, resolution: 'kept'|'reverted'|'unknown', daysToResolve, evidenceFiles }
+
+function compute({ vault, overrides = [], windowDays = 90 } = {}) {
+  if (!vault || !Array.isArray(overrides) || overrides.length === 0) {
+    return { available: false, outcomes: [] };
+  }
+  const dDir = dailiesDir(vault);
+  if (!fs.existsSync(dDir)) return { available: false, outcomes: [] };
+
+  const outcomes = overrides.slice(-20).map((o) => {
+    const overrideDate = o.at ? new Date(o.at) : null;
+    if (!overrideDate || isNaN(overrideDate.getTime())) {
+      return { override: o, resolution: 'unknown', daysToResolve: null, evidenceFiles: [], outcome7d: null, outcome30d: null };
+    }
+    const deferredWorkflow = (o.over || '').toLowerCase();
+    const startTs = overrideDate.getTime();
+    const evidenceFiles = [];
+    let firstSubsequentRun = null;
+
+    // Walk daily notes within windowDays after the override
+    for (let i = 0; i <= windowDays; i++) {
+      const d = new Date(startTs + i * 24 * 3600 * 1000);
+      const key = localDateKey(d);
+      const monthDir = key.slice(0, 7);
+      const fpath = path.join(dDir, monthDir, `Daily - ${key}.md`);
+      try {
+        const text = fs.readFileSync(fpath, "utf8");
+        // Look for the deferred workflow keyword in this daily note
+        if (deferredWorkflow && text.toLowerCase().includes(deferredWorkflow)) {
+          if (!firstSubsequentRun) firstSubsequentRun = { date: key, daysAfter: i };
+          evidenceFiles.push({ date: key, file: `Daily - ${key}.md` });
+          if (evidenceFiles.length >= 3) break;
+        }
+      } catch (_) { /* skip */ }
+    }
+
+    const resolution = firstSubsequentRun ? 'kept' : 'unknown';
+    return {
+      override: o,
+      resolution,
+      daysToResolve: firstSubsequentRun ? firstSubsequentRun.daysAfter : null,
+      evidenceFiles,
+      outcome7d: firstSubsequentRun && firstSubsequentRun.daysAfter <= 7 ? 'kept' : 'pending',
+      outcome30d: firstSubsequentRun && firstSubsequentRun.daysAfter <= 30 ? 'kept' : 'pending',
+    };
+  });
+
+  return {
+    available: true,
+    outcomes,
+    kept: outcomes.filter(x => x.resolution === 'kept').length,
+    unresolved: outcomes.filter(x => x.resolution === 'unknown').length,
+  };
+}
+
+module.exports = { compute };

package/src/dashboard/lib/override-summary.js

@@ -0,0 +1,73 @@
+"use strict";
+
+// Normalize override entries from pattern-manifest.json.
+//
+// T242 bug hunt fix (C#5): manifest sometimes carries `at` as the short
+// "2026-04-20T11:11" form (no seconds). Per ECMAScript spec, that string
+// is non-standard — Safari parses it as NaN. Force full ISO-8601 with
+// seconds + UTC marker so Date.parse() is consistent across V8/Safari/
+// Firefox. If the input is already valid, normalize to a canonical form.
+function toFullIso(raw) {
+  if (!raw) return "";
+  const s = String(raw).trim();
+  // Already a full ISO with seconds + zone? Keep.
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})$/.test(s)) return s;
+  // Short form: pad to seconds and treat as UTC. Date constructor accepts
+  // this form universally.
+  const m = s.match(/^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/);
+  if (m) {
+    const ss = m[4] || "00";
+    return `${m[1]}T${m[2]}:${m[3]}:${ss}.000Z`;
+  }
+  // Date-only? Anchor to midnight UTC.
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return `${s}T00:00:00.000Z`;
+  // Anything else — let Date.parse have a try. If valid, re-emit ISO.
+  const t = Date.parse(s);
+  return Number.isFinite(t) ? new Date(t).toISOString() : s;
+}
+
+function normalizeOverrides(manifest) {
+  const raw = (manifest && (manifest.overrideHistory || manifest.override_history)) || [];
+  if (!Array.isArray(raw)) return [];
+  return raw.map((o, i) => ({
+    id: o.id || `${o.timestamp || o.date || "x"}-${i}`,
+    at: toFullIso(o.timestamp || o.date),
+    project: o.project || "",
+    level: o.level || "",
+    what: o.what || o.action || o.task || "",
+    over: o.over || o.plan_item || o.conflicted_with || "",
+    reason: o.reason || o.justification || o.user_override || "",
+    outcome: o.outcome || "",
+  })).filter(o => o.at || o.what || o.reason);
+}
+
+function computeOverrideSummary(overrides, now = new Date()) {
+  const entries = Array.isArray(overrides) ? overrides : [];
+  const nowMs = now.getTime();
+  const day = 24 * 3600 * 1000;
+  const countWithin = (days) => entries.filter(o => {
+    const t = Date.parse(o.at || "");
+    return Number.isFinite(t) && nowMs - t <= days * day;
+  }).length;
+  const byLevel = entries.reduce((acc, o) => {
+    const level = String(o.level || "UNKNOWN").toUpperCase() || "UNKNOWN";
+    acc[level] = (acc[level] || 0) + 1;
+    return acc;
+  }, {});
+  const last = entries
+    .slice()
+    .sort((a, b) => (Date.parse(b.at || "") || 0) - (Date.parse(a.at || "") || 0))
+    .slice(0, 30);
+
+  return {
+    total: entries.length,
+    last7d: countWithin(7),
+    last14d: countWithin(14),
+    last30d: countWithin(30),
+    last90d: countWithin(90),
+    byLevel,
+    recent: last,
+  };
+}
+
+module.exports = { normalizeOverrides, computeOverrideSummary };

package/src/dashboard/lib/paths.js

@@ -0,0 +1,192 @@
+"use strict";
+
+const path = require("path");
+const os = require("os");
+const fs = require("fs");
+
+function moverDir() {
+  return path.join(os.homedir(), ".mover");
+}
+
+function moverConfigPath() {
+  return path.join(moverDir(), "config.json");
+}
+
+function moverPatternManifestPath() {
+  return path.join(moverDir(), "pattern-manifest.json");
+}
+
+function dashboardOutDir() {
+  return path.join(moverDir(), "dashboard");
+}
+
+function dashboardIndexPath() {
+  return path.join(dashboardOutDir(), "index.html");
+}
+
+function dashboardBuildLogPath() {
+  return path.join(dashboardOutDir(), "build.log");
+}
+
+function dashboardSnoozesPath() {
+  return path.join(dashboardOutDir(), "snoozes.json");
+}
+
+// Vault-relative paths (caller passes vault root)
+function engineDir(vault) { return path.join(vault, "02_Areas", "Engine"); }
+
+function engineFile(vault, name) { return path.join(engineDir(vault), name); }
+
+function dailiesDir(vault) { return path.join(engineDir(vault), "Dailies"); }
+
+function weeklyReviewsDir(vault) { return path.join(engineDir(vault), "Weekly Reviews"); }
+
+function projectsDir(vault) { return path.join(vault, "01_Projects"); }
+
+function libraryDir(vault) { return path.join(vault, "03_Library"); }
+
+function inboxDir(vault) { return path.join(vault, "00_Inbox"); }
+
+function archivesDir(vault) { return path.join(vault, "04_Archives"); }
+
+// Engine file shortcuts
+function activeContextPath(vault) { return engineFile(vault, "Active_Context.md"); }
+function strategyPath(vault) { return engineFile(vault, "Strategy.md"); }
+function identityPrimePath(vault) { return engineFile(vault, "Identity_Prime.md"); }
+function goalsPath(vault) { return engineFile(vault, "Goals.md"); }
+function autoLearningsPath(vault) { return engineFile(vault, "Auto_Learnings.md"); }
+// Dossier filename varies by user: Mover_Dossier.md (default), Architect_Dossier.md, Red_Team_Dossier.md.
+// Returns the first existing file from candidate list, or default if none exist.
+function moverDossierPath(vault) {
+  const candidates = ["Mover_Dossier.md", "Architect_Dossier.md", "Red_Team_Dossier.md"];
+  for (const name of candidates) {
+    const p = engineFile(vault, name);
+    try { if (fs.existsSync(p)) return p; } catch (_) {}
+  }
+  return engineFile(vault, candidates[0]);
+}
+function voiceDnaPath(vault) { return engineFile(vault, "Voice_DNA.md"); }
+function metricsLogPath(vault) { return engineFile(vault, "Metrics_Log.md"); }
+function healthAnalysisPath(vault) { return engineFile(vault, "Health_Analysis_Full.md"); }
+
+// Daily note resolver — supports YYYY-MM/Daily - YYYY-MM-DD.md format
+function dailyNotePath(vault, date) {
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  return path.join(dailiesDir(vault), `${yyyy}-${mm}`, `Daily - ${yyyy}-${mm}-${dd}.md`);
+}
+
+// Library subdirs
+function libraryCheatsheetsDir(vault) { return path.join(libraryDir(vault), "Cheatsheets"); }
+function libraryPrinciplesDir(vault) { return path.join(libraryDir(vault), "Principles"); }
+function librarySopsDir(vault) { return path.join(libraryDir(vault), "SOPs"); }
+function libraryEntitiesDir(vault) { return path.join(libraryDir(vault), "Entities"); }
+function libraryEntitiesPeopleDir(vault) { return path.join(libraryEntitiesDir(vault), "People"); }
+function libraryEntitiesOrgsDir(vault) { return path.join(libraryEntitiesDir(vault), "Organizations"); }
+function libraryEntitiesPlacesDir(vault) { return path.join(libraryEntitiesDir(vault), "Places"); }
+function libraryEntitiesDecisionsDir(vault) { return path.join(libraryEntitiesDir(vault), "Decisions"); }
+function libraryInputsDir(vault) { return path.join(libraryDir(vault), "Inputs"); }
+function libraryScriptsDir(vault) { return path.join(libraryDir(vault), "Scripts"); }
+function libraryMocsDir(vault) { return path.join(libraryDir(vault), "MOCs"); }
+
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
+}
+
+// Resolve the vault root with NO hardcoded/PII path (so lib CLI entrypoints never ship a machine
+// path): env MOVER_VAULT → ~/.mover/config.json vaultPath → walk up from cwd for 02_Areas/Engine → cwd.
+function resolveVault() {
+  const hasEngine = (v) => { try { return !!v && fs.existsSync(path.join(v, "02_Areas", "Engine")); } catch { return false; } };
+  if (hasEngine(process.env.MOVER_VAULT)) return process.env.MOVER_VAULT;
+  let cfg = {}; try { cfg = JSON.parse(fs.readFileSync(moverConfigPath(), "utf8")) || {}; } catch {}
+  if (hasEngine(cfg.vaultPath)) return cfg.vaultPath;
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (hasEngine(dir)) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return process.env.MOVER_VAULT || cfg.vaultPath || process.cwd();
+}
+
+function safeRead(p, fallback = null) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return fallback; }
+}
+
+function safeReadJson(p, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fallback; }
+}
+
+function safeStat(p) {
+  try { return fs.statSync(p); } catch { return null; }
+}
+
+function safeListDir(p, options = {}) {
+  try {
+    let entries = fs.readdirSync(p, { withFileTypes: true });
+    if (options.dirsOnly) entries = entries.filter(e => e.isDirectory());
+    if (options.filesOnly) entries = entries.filter(e => e.isFile());
+    if (options.extension) entries = entries.filter(e => e.isFile() && e.name.endsWith(options.extension));
+    if (options.skipUnderscore) entries = entries.filter(e => !e.name.startsWith("_") && !e.name.startsWith("."));
+    return entries.map(e => ({
+      name: e.name,
+      path: path.join(p, e.name),
+      isDir: e.isDirectory(),
+      isFile: e.isFile()
+    }));
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  // Mover dirs
+  moverDir,
+  moverConfigPath,
+  moverPatternManifestPath,
+  dashboardOutDir,
+  dashboardIndexPath,
+  dashboardBuildLogPath,
+  dashboardSnoozesPath,
+  // Vault dirs
+  engineDir,
+  engineFile,
+  dailiesDir,
+  weeklyReviewsDir,
+  projectsDir,
+  libraryDir,
+  inboxDir,
+  archivesDir,
+  // Engine files
+  activeContextPath,
+  strategyPath,
+  identityPrimePath,
+  goalsPath,
+  autoLearningsPath,
+  moverDossierPath,
+  voiceDnaPath,
+  metricsLogPath,
+  healthAnalysisPath,
+  dailyNotePath,
+  // Library
+  libraryCheatsheetsDir,
+  libraryPrinciplesDir,
+  librarySopsDir,
+  libraryEntitiesDir,
+  libraryEntitiesPeopleDir,
+  libraryEntitiesOrgsDir,
+  libraryEntitiesPlacesDir,
+  libraryEntitiesDecisionsDir,
+  libraryInputsDir,
+  libraryScriptsDir,
+  libraryMocsDir,
+  // Helpers
+  resolveVault,
+  exists,
+  safeRead,
+  safeReadJson,
+  safeStat,
+  safeListDir
+};