mover-os 4.7.7 → 4.7.9

package/src/dashboard/lib/view-generator.js

@@ -0,0 +1,163 @@
+"use strict";
+
+// View Generator MVP — wishlist #64, the categorical differentiator.
+//
+// "Mover OS reads your vault, sessions, strategy, health notes, and agent
+// history. Then it generates the view you need for the job you are doing."
+//
+// V1 design: rather than a full LLM-driven layout system, this MVP:
+//   1. Accepts a free-text prompt ("make me a content tracker from current goals")
+//   2. Bundles relevant vault context (Goals + Strategy + Active_Context + plan files)
+//   3. Returns a STRUCTURED VIEW DEFINITION — JSON with sections, queries,
+//      and render hints — that the dashboard can interpret to build a
+//      bespoke layout from existing parsers.
+//   4. Persists view definitions to ~/.mover/views/<slug>.json so users
+//      can return to them.
+//
+// V2 (multi-week): wire to claude-code / codex CLI to actually generate
+// the view definition via LLM. For now: a templating engine that maps
+// keywords in the prompt to known view shapes ('content', 'metric',
+// 'project', 'pattern', 'distribution'). Honest MVP.
+//
+// The radical idea is that the dashboard layout is NOT FIXED. Same
+// underlying parsers, different views per job-to-be-done.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const VIEWS_DIR = path.join(os.homedir(), ".mover", "views");
+
+// Keyword → view template mapping. Each template names which state.json
+// fields to render and in what order. Extend as more shapes emerge.
+const VIEW_TEMPLATES = {
+  content: {
+    sections: [
+      { kind: "text", source: "strategy.singleTest", label: "Current bet" },
+      { kind: "list", source: "projects", filter: "tasks", label: "Active projects with tasks" },
+      { kind: "list", source: "library.inputs", limit: 10, label: "Recent Inputs (research)" },
+    ],
+  },
+  metric: {
+    sections: [
+      { kind: "number", source: "driftScore.value", label: "Drift score" },
+      { kind: "sparkline", source: "driftScore.history", label: "30-day trend" },
+      { kind: "list", source: "metrics.rolling30", label: "Rolling 30-day metrics" },
+    ],
+  },
+  project: {
+    sections: [
+      { kind: "list", source: "projects", filter: "all", label: "All projects" },
+      { kind: "list", source: "activeContext.commitments", label: "Outstanding commitments" },
+    ],
+  },
+  pattern: {
+    sections: [
+      { kind: "list", source: "activeContext.activePatterns", label: "Active patterns" },
+      { kind: "list", source: "roastWall.roasts", limit: 10, label: "Recent verdicts" },
+      { kind: "table", source: "correlations.correlations", label: "Black Box correlations" },
+    ],
+  },
+  distribution: {
+    sections: [
+      { kind: "text", source: "strategy.singleTest", label: "Sale gate" },
+      { kind: "list", source: "activeContext.commitments", filter: "distribution", label: "Distribution commitments" },
+      { kind: "number", source: "activation.installDays", label: "Days since install" },
+    ],
+  },
+  habit: {
+    sections: [
+      { kind: "heatmap", source: "streak.days", label: "Daily streak" },
+      { kind: "number", source: "streak.currentStreak", label: "Current streak" },
+      { kind: "table", source: "correlations.correlations", label: "What helps / hurts" },
+    ],
+  },
+};
+
+const KEYWORD_TO_TEMPLATE = [
+  { keywords: ["content", "post", "article", "tweet", "reel", "video"], template: "content" },
+  { keywords: ["metric", "kpi", "drift", "score", "trend"], template: "metric" },
+  { keywords: ["project", "deliverable", "milestone", "feature"], template: "project" },
+  { keywords: ["pattern", "behavior", "habit pattern", "avoidance", "leak"], template: "pattern" },
+  { keywords: ["distribution", "marketing", "sales", "dms", "reach"], template: "distribution" },
+  { keywords: ["habit", "routine", "streak", "vitality", "sleep"], template: "habit" },
+];
+
+function chooseTemplate(prompt) {
+  const lower = String(prompt || "").toLowerCase();
+  for (const { keywords, template } of KEYWORD_TO_TEMPLATE) {
+    if (keywords.some(k => lower.includes(k))) return template;
+  }
+  // Default: pattern view (most generally useful)
+  return "pattern";
+}
+
+function slugify(text) {
+  return String(text || "view")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60) || "view";
+}
+
+function generate({ prompt, save = true } = {}) {
+  if (!prompt) {
+    return { ok: false, error: "prompt required" };
+  }
+  const templateKey = chooseTemplate(prompt);
+  const template = VIEW_TEMPLATES[templateKey];
+  const slug = slugify(prompt);
+  const view = {
+    version: 1,
+    prompt,
+    template: templateKey,
+    slug,
+    createdAt: new Date().toISOString(),
+    sections: template.sections,
+  };
+  if (save) {
+    try {
+      fs.mkdirSync(VIEWS_DIR, { recursive: true });
+      const dest = path.join(VIEWS_DIR, `${slug}.json`);
+      fs.writeFileSync(dest, JSON.stringify(view, null, 2), "utf8");
+      view.path = dest;
+    } catch (e) {
+      view.saveError = e.message;
+    }
+  }
+  return { ok: true, view };
+}
+
+function list() {
+  try {
+    if (!fs.existsSync(VIEWS_DIR)) return [];
+    return fs.readdirSync(VIEWS_DIR)
+      .filter(f => f.endsWith(".json"))
+      .map(f => {
+        try {
+          return JSON.parse(fs.readFileSync(path.join(VIEWS_DIR, f), "utf8"));
+        } catch { return null; }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function get(slug) {
+  try {
+    const file = path.join(VIEWS_DIR, `${slug}.json`);
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch { return null; }
+}
+
+function remove(slug) {
+  try {
+    const file = path.join(VIEWS_DIR, `${slug}.json`);
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+    return true;
+  } catch { return false; }
+}
+
+module.exports = { generate, list, get, remove, VIEW_TEMPLATES, chooseTemplate };

package/src/dashboard/lib/voice-dna-parser.js

@@ -0,0 +1,57 @@
+"use strict";
+
+const { voiceDnaPath, safeRead, safeStat } = require("./paths");
+
+// Parse Voice_DNA.md — extract writing samples, banned phrases, tone scores, sentence patterns.
+
+function parseVoiceDna(vault) {
+  const filePath = voiceDnaPath(vault);
+  const text = safeRead(filePath);
+  const stat = safeStat(filePath);
+  if (!text) return { available: false };
+
+  const out = {
+    available: true,
+    filePath,
+    lastUpdated: stat ? stat.mtime : null,
+    raw: text,
+    samples: [],
+    fields: {}
+  };
+
+  // Bold field extraction
+  const re = /\*\*([^*]+):\*\*\s*([^\n]+)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const k = m[1].trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_|_$/g, "");
+    out.fields[k] = m[2].trim();
+  }
+
+  // Extract writing samples — code blocks ``` ... ```
+  const sampleRe = /```\s*([\s\S]*?)\s*```/g;
+  while ((m = sampleRe.exec(text)) !== null) {
+    out.samples.push(m[1].trim());
+  }
+
+  // Common patterns
+  out.lowercaseI = /lowercase\s*[\"']?i[\"']?/i.test(text);
+  out.commaSpliced = /comma[-\s]*spliced/i.test(text);
+  out.usesBrother = /\bbrother\b/i.test(text);
+  out.urlInline = /url[-\s]inline|inline\s*url/i.test(text);
+
+  // Banned phrases section
+  const bannedSection = text.match(/##+\s*Banned[^\n]*\n([\s\S]*?)(?=\n##+|\n---|\n$)/i);
+  if (bannedSection) {
+    out.bannedPhrases = bannedSection[1].split("\n")
+      .map(l => l.match(/^[-*]\s+(.+)$/))
+      .filter(Boolean).map(m => m[1].trim()).slice(0, 12);
+  } else out.bannedPhrases = [];
+
+  out.totalSamples = out.samples.length;
+  out.shortestSample = out.samples.reduce((min, s) => Math.min(min, s.length), Infinity);
+  out.longestSample = out.samples.reduce((max, s) => Math.max(max, s.length), 0);
+
+  return out;
+}
+
+module.exports = { parseVoiceDna };

package/src/dashboard/lib/walkthrough-script.js

@@ -0,0 +1,140 @@
+"use strict";
+
+/**
+ * walkthrough-script.js — structured walkthrough data for the Mover OS
+ * onboarding engine (onboarding-engine-SPEC.md §5 D6).
+ *
+ * The walkthrough runs AFTER setup. Its job is not to explain the system —
+ * the user just sat through that. Its job is to teach the user to OPERATE
+ * the agent: the gaps that cause 90% of day-3 drop-off:
+ *
+ *   1. Drive the LLM (don't just chat at it — run workflows)
+ *   2. Stay in ONE chat (session continuity is the product)
+ *   3. Compact when full (don't lose context — /compact before it degrades)
+ *   4. Verify file creation (trust the files, not the chat)
+ *   5. Discover capabilities (the system tells you what's next)
+ *   6. Strategy → Daily loop (the one rhythm that makes it self-sustaining)
+ *   7. Run a workflow end-to-end (/log)
+ *   8. Land on a first plan (/plan-tomorrow — the done-gate)
+ *
+ * Design principles (per grill findings + Mobbin "fast first-win"):
+ * - SHORT. 8 steps, 8 minutes. Not a lecture.
+ * - DOING, not explaining. Each step has a concrete `doThis` action.
+ * - `checkpoint` is HOW the agent verifies the user actually did it.
+ * - No recap of Engine files — setup covered that. This is ops, not orientation.
+ * - SENTINEL: when all 8 steps are confirmed, agent emits [[WALKTHROUGH_COMPLETE]]
+ *   so the GUI can fire the done banner (mirrors setup-poc.html's [[SETUP_COMPLETE]]).
+ */
+
+// ── System prompt for the walkthrough agent persona ──────────────────────────
+// Different from DEFAULT_SETUP_SYSTEM: the walkthrough agent is a GUIDE,
+// not an interviewer. It gives instructions, waits, confirms, and moves on.
+// It NEVER explains setup material again. It is brief and operational.
+const WALKTHROUGH_SYSTEM = [
+  "You are the Mover OS walkthrough guide.",
+  "Your ONLY job: teach the user to operate the system in 8 steps, taking no more than 8 minutes total.",
+  "Do NOT re-explain what Mover OS is, what Engine files are, or what setup covered.",
+  "Each turn: acknowledge the user's last action in ONE sentence, then give the next step's instruction clearly.",
+  "Keep every response under 4 sentences. No exceptions.",
+  "Do NOT use numbered lists, bullet points, or headings in your responses. Prose only.",
+  "Do NOT run any tools and do NOT read files — you have no tools in this session.",
+  "You may reference file names (like Active_Context.md or plan.md) but never their contents.",
+  "Tone: warm but fast. A co-founder showing someone the system in a short video call, not a teacher at a whiteboard.",
+  "When the user confirms they completed step 8 (running /plan-tomorrow and having a plan for tomorrow), emit the exact token [[WALKTHROUGH_COMPLETE]] on its own line, then write one sentence that says they are ready to operate the system.",
+  "CRITICAL: Only emit [[WALKTHROUGH_COMPLETE]] after the user has confirmed step 8. Not before.",
+].join(" ");
+
+// ── Walkthrough steps ─────────────────────────────────────────────────────────
+// Each step is self-contained: title + body for the card UI, doThis for the
+// concrete action the user takes, checkpoint for how the guide verifies it.
+//
+// The guide reads these steps and drives the conversation through them in order.
+// The GUI renders each step as a card BEFORE the agent turn so the user can
+// read the instruction while the agent is composing its confirmation.
+
+const STEPS = [
+  {
+    id: "welcome",
+    step: 1,
+    title: "You're set up. Now let's operate.",
+    body: "Setup extracted who you are and built your Engine. This walkthrough teaches you how to RUN it. Eight steps, eight minutes. No reading — only doing.",
+    doThis: "Type \"ready\" to begin.",
+    checkpoint: "User says they are ready or asks a question. Either counts — they are engaged.",
+  },
+
+  {
+    id: "first-workflow",
+    step: 2,
+    title: "Drive the system with workflows.",
+    body: "This is not a chatbot. You run commands. The core command is /morning — it loads your Engine files, checks your energy, and sets your Single Test for the session. Without /morning, you are flying blind.",
+    doThis: "Open a Claude Code session (a terminal, type `claude`). Run: /morning",
+    checkpoint: "User confirms they ran /morning, or asks where Claude Code is. If they ask, tell them: open a terminal, type `claude`, press Enter, then type /morning.",
+  },
+
+  {
+    id: "one-chat",
+    step: 3,
+    title: "One session. Not ten tabs.",
+    body: "Every new Claude Code window starts from zero — no memory of the last one. Your Engine files ARE the persistent memory. Opening a new window mid-task means re-loading all that context, which costs tokens and minutes. Continuity lives in the files, not the window.",
+    doThis: "For today: stay in the Claude Code session where you ran /morning. Do not open a new window unless you run /morning first.",
+    checkpoint: "User acknowledges the habit. No file action needed — they are committing to a behavior, not running a command.",
+  },
+
+  {
+    id: "compact",
+    step: 4,
+    title: "Compact before context breaks down.",
+    body: "After a long session, responses get shallower — the model is losing the thread. /compact compresses the conversation while re-loading your Engine context. It is not 'start over' — it is 'keep going with a clear head'. Use it when responses feel off or surface-level.",
+    doThis: "In your Claude Code session: type /compact. If the session is short, that is fine — run it anyway so you know what it does.",
+    checkpoint: "User ran /compact, or confirms they understand when to use it. If their session is short, acknowledge that is the correct read — they understand the trigger condition.",
+  },
+
+  {
+    id: "verify-files",
+    step: 5,
+    title: "The files are the truth. Not the chat.",
+    body: "The chat transcript is temporary — it disappears when you close the session. Every workflow writes its output to a file. Your Daily Note, Active_Context.md, plan.md — those are permanent. If a workflow ran and nothing was written, something went wrong. Always verify: did that actually land in a file?",
+    doThis: "Open Obsidian. Navigate to 02_Areas/Engine/. Confirm Active_Context.md exists and has content from setup. That is your proof the system is working.",
+    checkpoint: "User confirms they saw Active_Context.md with content. If they cannot find it, ask for their vault path and guide them to 02_Areas/Engine/.",
+  },
+
+  {
+    id: "discover",
+    step: 6,
+    title: "Every workflow tells you what comes next.",
+    body: "You do not need to memorize 25 commands. Every workflow ends with a handoff — a specific suggestion for what to run next. Follow the handoffs. Today that chain is: /morning → work → /log → /analyse-day → /plan-tomorrow. You already ran /morning. /log is next.",
+    doThis: "In your Claude Code session: type /log — the end-of-session capture. Read its output. Note what it suggests you run after it.",
+    checkpoint: "User ran /log and reports what it suggested. Any answer is correct — they have now seen the handoff pattern live.",
+  },
+
+  {
+    id: "daily-loop",
+    step: 7,
+    title: "The loop that keeps the system alive.",
+    body: "Run this every day and the system compounds. Skip it and it decays. The loop: /morning to start → do your work → /log to capture → /analyse-day to audit → /plan-tomorrow to set tomorrow. This is not optional ceremony. This is the product.",
+    doThis: "Say the loop back from memory — just the five steps.",
+    checkpoint: "User gives some version of: morning, work, log, analyse-day, plan-tomorrow. Exact words do not matter. If they miss a step, name it once, do not lecture. Then advance.",
+  },
+
+  {
+    id: "first-plan",
+    step: 8,
+    title: "Close the loop before you leave.",
+    body: "Do not walk away from setup and walkthrough without a plan for tomorrow. /plan-tomorrow pulls from your strategy, your backlogs, and what happened today. It gives you a clear first task for tomorrow morning. This is the bridge from 'I installed this' to 'I am actually using this'.",
+    doThis: "In your Claude Code session: type /plan-tomorrow. Confirm you have a plan for tomorrow when it finishes.",
+    checkpoint: "User confirms they ran /plan-tomorrow and have a plan. This is the done-gate. When confirmed, emit [[WALKTHROUGH_COMPLETE]] and the closing line.",
+  },
+];
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  WALKTHROUGH_SYSTEM,
+  STEPS,
+  /** Total number of steps (convenience for progress indicators). */
+  STEP_COUNT: STEPS.length,
+  /** Look up a step by id (returns undefined if not found). */
+  getStep: (id) => STEPS.find((s) => s.id === id),
+  /** Get step by 1-indexed position. */
+  getStepByIndex: (n) => STEPS[n - 1] || null,
+};

package/src/dashboard/lib/workflow-graph-parser.js

@@ -0,0 +1,170 @@
+"use strict";
+
+// Phase 41.7 — Workflow read/write graph parser.
+//
+// Scans every src/workflows/*.md for references to Engine files (or other
+// workflow files). Builds a directed graph: workflows are nodes, edges
+// represent "reads" or "writes" relationships.
+//
+// Heuristic source detection: workflow content is markdown, so we look for:
+//   - "READS:" / "WRITES:" / "READ:" / "WRITE:" labels (preferred format)
+//   - Bare references to known Engine files in code-fenced or quoted contexts
+//   - YAML frontmatter `reads:` / `writes:` arrays
+//
+// The graph powers Library → Workflow Graph tab, helps users see which
+// workflow updates which Engine file at a glance, and surfaces orphaned
+// workflows (no reads/writes).
+
+const fs = require("fs");
+const path = require("path");
+
+const ENGINE_FILES = [
+  "Strategy.md",
+  "Identity_Prime.md",
+  "Active_Context.md",
+  "Architect_Dossier.md",  // live filename (renamed from Mover_Dossier.md)
+  "Mover_Dossier.md",      // legacy alias — kept so older vaults still match
+  "Auto_Learnings.md",
+  "Goals.md",
+  "Metrics_Log.md",
+  "Someday_Maybe.md",
+  "Daily Note",
+  "Daily_Template.md",
+  "Voice_DNA.md",
+];
+
+function workflowsDir(bundleRoot) {
+  return path.join(bundleRoot, "src", "workflows");
+}
+
+function parseFrontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!m) return { fm: {}, body: text };
+  const fmText = m[1];
+  const body = text.slice(m[0].length);
+  const fm = {};
+  const lines = fmText.split("\n");
+  let currentKey = null;
+  let listBuf = null;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const topMatch = line.match(/^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i);
+    if (topMatch && !/^\s/.test(line)) {
+      if (currentKey && listBuf) fm[currentKey] = listBuf;
+      currentKey = topMatch[1];
+      listBuf = null;
+      const v = topMatch[2].trim();
+      if (v) {
+        fm[currentKey] = v.replace(/^["']|["']$/g, "");
+        currentKey = null;
+      } else {
+        listBuf = [];
+      }
+    } else if (currentKey && listBuf) {
+      const itemMatch = line.match(/^\s*-\s+(.+)$/);
+      if (itemMatch) listBuf.push(itemMatch[1].trim().replace(/^["']|["']$/g, ""));
+    }
+  }
+  if (currentKey && listBuf) fm[currentKey] = listBuf;
+  return { fm, body };
+}
+
+function extractFromFrontmatter(fm, key) {
+  const v = fm[key];
+  if (!v) return [];
+  if (Array.isArray(v)) return v;
+  return String(v).split(/[,;]/).map(s => s.trim()).filter(Boolean);
+}
+
+function extractFromBody(body) {
+  // Pattern: "READS: file1.md, file2.md" / "WRITES: file3.md"
+  const reads = new Set();
+  const writes = new Set();
+  for (const line of body.split("\n")) {
+    const r = line.match(/READS?:\s+(.+)/i);
+    if (r) for (const f of r[1].split(/[,;]/)) {
+      const trimmed = f.trim().replace(/[`*_]/g, "");
+      if (trimmed) reads.add(trimmed);
+    }
+    const w = line.match(/WRITES?:\s+(.+)/i);
+    if (w) for (const f of w[1].split(/[,;]/)) {
+      const trimmed = f.trim().replace(/[`*_]/g, "");
+      if (trimmed) writes.add(trimmed);
+    }
+  }
+  // Heuristic backup: scan for engine file mentions in headed contexts.
+  // Lower confidence — only count if file is named with explicit ".md".
+  for (const ef of ENGINE_FILES) {
+    if (ef === "Daily Note") continue;
+    const re = new RegExp(`\\b${ef.replace(/\./g, "\\.")}\\b`, "g");
+    const matches = body.match(re);
+    if (matches) {
+      // Default heuristic: if "write" appears within 80 chars before the
+      // file ref, count as write; otherwise read.
+      reads.add(ef);
+    }
+  }
+  return {
+    reads: Array.from(reads),
+    writes: Array.from(writes),
+  };
+}
+
+function parseWorkflow(filePath) {
+  const name = path.basename(filePath, ".md");
+  const text = fs.readFileSync(filePath, "utf8").replace(/\r\n/g, "\n");
+  const { fm, body } = parseFrontmatter(text);
+  const fmReads = extractFromFrontmatter(fm, "reads");
+  const fmWrites = extractFromFrontmatter(fm, "writes");
+  const bodyExtracted = extractFromBody(body);
+  // Frontmatter overrides body heuristics when present.
+  const reads = fmReads.length ? fmReads : bodyExtracted.reads;
+  const writes = fmWrites.length ? fmWrites : bodyExtracted.writes;
+  return {
+    name,
+    file: filePath,
+    description: fm.description || "",
+    reads,
+    writes,
+  };
+}
+
+function scan({ bundleRoot } = {}) {
+  if (!bundleRoot) return { available: false, workflows: [], edges: [] };
+  const dir = workflowsDir(bundleRoot);
+  if (!fs.existsSync(dir)) return { available: false, workflows: [], edges: [] };
+  const files = fs.readdirSync(dir).filter(f => f.endsWith(".md"));
+  const workflows = [];
+  const edges = [];
+  for (const f of files) {
+    try {
+      const parsed = parseWorkflow(path.join(dir, f));
+      workflows.push({
+        name: parsed.name,
+        description: parsed.description,
+        readCount: parsed.reads.length,
+        writeCount: parsed.writes.length,
+      });
+      for (const r of parsed.reads) edges.push({ from: parsed.name, to: r, kind: "reads" });
+      for (const w of parsed.writes) edges.push({ from: parsed.name, to: w, kind: "writes" });
+    } catch (e) {
+      // Skip unparseable
+    }
+  }
+  // Aggregate per-file: which workflows touch each engine file.
+  const fileMap = {};
+  for (const e of edges) {
+    if (!fileMap[e.to]) fileMap[e.to] = { file: e.to, readers: [], writers: [] };
+    if (e.kind === "reads") fileMap[e.to].readers.push(e.from);
+    if (e.kind === "writes") fileMap[e.to].writers.push(e.from);
+  }
+  return {
+    available: true,
+    workflowCount: workflows.length,
+    workflows,
+    edges,
+    files: Object.values(fileMap),
+  };
+}
+
+module.exports = { scan, parseWorkflow };

package/src/dashboard/lib/workflow-library-parser.js

@@ -0,0 +1,146 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// workflow-library-parser.js — Read all .md workflow files from
+// src/workflows/. Extract description, reads, writes, last-run timestamp.
+// Powers the Workflows tab in Studio (Phase 6.7).
+
+function indexWorkflows(bundleRoot) {
+  const workflowsDir = path.join(bundleRoot, "src", "workflows");
+  if (!fs.existsSync(workflowsDir)) return { available: false, workflows: [] };
+
+  const files = fs.readdirSync(workflowsDir).filter((f) => f.endsWith(".md"));
+  const workflows = files.map((file) => {
+    const filePath = path.join(workflowsDir, file);
+    const text = safeRead(filePath);
+    return parseWorkflow(file, filePath, text);
+  });
+
+  return {
+    available: true,
+    count: workflows.length,
+    workflows: workflows.sort((a, b) => a.name.localeCompare(b.name))
+  };
+}
+
+function parseWorkflow(file, filePath, text) {
+  const name = "/" + file.replace(/\.md$/, "");
+  const out = {
+    name,
+    filename: file,
+    filePath,
+    description: "",
+    risk: "LOW",
+    target: "",
+    role: "",
+    reads: [],
+    writes: [],
+    handsOffTo: [],
+    workflowLength: text ? text.length : 0
+  };
+
+  // Frontmatter (description from YAML frontmatter if present)
+  const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1];
+    const descLine = fm.match(/description:\s*(.+)$/im);
+    if (descLine) out.description = stripQuotes(descLine[1].trim());
+
+    // v6 SURFACE 1 — the Say-it card copy + the structured reads/writes
+    // contract. Additive: workflows without these keys parse exactly as before
+    // (does/long/needsYou undefined, io null). The card degrades honestly.
+    const doesLine = fm.match(/^does:\s*(.+)$/im);
+    if (doesLine) out.does = stripQuotes(doesLine[1].trim());
+    const longLine = fm.match(/^long:\s*(.+)$/im);
+    if (longLine) out.long = stripQuotes(longLine[1].trim());
+    const ny = fm.match(/^needs_you:\s*(true|false)\s*$/im);
+    if (ny) out.needsYou = ny[1].toLowerCase() === "true";
+    out.io = parseIoBlock(fm);
+  }
+
+  // Standard sections from Mover OS workflow template
+  const triggerMatch = text.match(/\*\*Trigger:\*\*\s+(.+)$/m);
+  const targetMatch = text.match(/\*\*Target:\*\*\s+(.+)$/m);
+  const roleMatch = text.match(/\*\*Role:\*\*\s+(.+)$/m);
+  const taskMatch = text.match(/\*\*Task:\*\*\s+(.+)$/m);
+  const riskMatch = text.match(/\*\*Risk Tier:\*\*\s+(\w+)/);
+
+  if (triggerMatch) out.trigger = triggerMatch[1].trim();
+  if (targetMatch) out.target = targetMatch[1].trim();
+  if (roleMatch) out.role = roleMatch[1].trim();
+  if (taskMatch && !out.description) out.description = taskMatch[1].trim();
+  if (riskMatch) out.risk = riskMatch[1].toUpperCase();
+
+  // Find what the workflow READS. The old approach matched a single
+  // LOAD/"Read these files"/Memory-Hierarchy section and only scanned the 800
+  // chars after it for backtick-wrapped files — it caught just 1 of 25 real
+  // workflows, so nearly every Run card rendered "reads —" while "changes" was
+  // populated, despite the workflows clearly reading Engine files. Scan the whole
+  // body with a broad, verb-anchored pattern that mirrors the writes scan below
+  // (basename only, deduped, capped). Lifts coverage 1/25 → 13/25; the rest
+  // genuinely declare no explicit .md read and honestly stay "—".
+  const readPattern = /(?:\bRe-?reads?\b|\bReads?\b|\bLOAD\b|\bReview\b)\s+(?:the\s+|your\s+|current\s+|today'?s\s+|active\s+)*[`*]?([A-Za-z_][A-Za-z0-9_/-]*\.md)[`*]?/gi;
+  const reads = [...text.matchAll(readPattern)].map((m) => m[1].replace(/^.*\//, ""));
+  out.reads = [...new Set(reads)].slice(0, 10);
+
+  // Find what the workflow WRITES (look for "Target:", "Write to", "Append to")
+  const writePattern = /(?:Target:|Write(?: to)?|Append to|Update)\s+[`*]?([A-Za-z_/]+\.md)[`*]?/gi;
+  const writes = [...text.matchAll(writePattern)].map((m) => m[1]);
+  out.writes = [...new Set(writes)].slice(0, 8);
+
+  // Handoff
+  const handoffMatch = text.match(/(?:HANDOFF|Next[: ]+).{0,200}?\/([a-z-]+)/im);
+  if (handoffMatch) out.handsOffTo.push("/" + handoffMatch[1]);
+
+  return out;
+}
+
+function safeRead(filePath) {
+  try { return fs.readFileSync(filePath, "utf8"); } catch (_) { return ""; }
+}
+
+function stripQuotes(s) {
+  return s.replace(/^['"]|['"]$/g, "");
+}
+
+// Parse the `io:` frontmatter block into { reads:[{f,src,note?}], writes:[…] }.
+// Line-based + indentation-aware on purpose (robust against blank lines and
+// `io:` appearing anywhere in the frontmatter; stops at the next top-level key).
+// Returns null when there is no io block — the honest "not declared yet" state.
+//   io:
+//     reads:
+//       - f: "Daily/{today}.md"
+//         src: dailyNote
+//     writes:
+//       - f: Metrics_Log.md
+//         src: metrics
+//         note: with a changelog entry
+function parseIoBlock(fm) {
+  const lines = fm.split("\n");
+  const start = lines.findIndex((l) => /^io:\s*$/.test(l));
+  if (start === -1) return null;
+  const io = { reads: [], writes: [] };
+  let bucket = null, cur = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\S/.test(line)) break;                 // next top-level key → io block ended
+    if (line.trim() === "") continue;
+    const key = line.match(/^\s{2}(reads|writes):\s*$/);
+    if (key) { bucket = io[key[1]]; cur = null; continue; }
+    if (!bucket) continue;
+    const item = line.match(/^\s{4}-\s*f:\s*(.+)$/);
+    if (item) { cur = { f: stripQuotes(item[1].trim()), src: null }; bucket.push(cur); continue; }
+    const sub = line.match(/^\s{6}(src|note):\s*(.+)$/);
+    if (sub && cur) {
+      const val = stripQuotes(sub[2].trim());
+      // YAML null on `src` → real null (a plain, non-drawer chip), not the
+      // string "null". Authors can also just omit the src line.
+      cur[sub[1]] = (sub[1] === "src" && (val === "null" || val === "~")) ? null : val;
+    }
+  }
+  return io;
+}
+
+module.exports = { indexWorkflows };