miriad-viz 0.2.2 → 0.3.0

package/dist-cli/{curate-KLE2K3TB.js → curate-EWAMDCOW.js}

@@ -207,19 +207,6 @@ function generateRetroPageData(dateRange, agents, rosterTypes) {
       ],
       _hint: "Categories: theGood, theBad, theUgly, theFunny (optional). Avoid placing two quotes from the same agent close together \u2014 interleave quotes from different agents."
     },
-    trustArc: [
-      {
-        time: startISO,
-        level: 50,
-        label: "Starting trust level",
-        _hint: "0 = no trust, 100 = full trust. Transform normalizes to 0-1."
-      },
-      {
-        time: endISO,
-        level: 80,
-        label: "Final trust level"
-      }
-    ],
     editorialNarration: [
       {
         time: startISO,
@@ -236,17 +223,38 @@ function generateRetroPageData(dateRange, agents, rosterTypes) {
         text: "Replace with narration for the next phase",
         type: "milestone"
       }
-    ]
+    ],
+    _narrationTimingWarning: "\u26A0\uFE0F narration-editorial.json uses FRACTIONAL 0-1 for start/end (e.g. 0.23, 0.68). Everything else in curation uses ISO timestamps. Do NOT mix them up."
   };
 }
-function generateRetroPageQuotes() {
+function generateRetroPageQuotes(dateRange) {
+  const start = dateRange ? new Date(dateRange.earliest) : /* @__PURE__ */ new Date();
+  const end = dateRange ? new Date(dateRange.latest) : /* @__PURE__ */ new Date();
+  const mid = new Date(Math.round((start.getTime() + end.getTime()) / 2));
+  const fmt = (d) => {
+    const months = [
+      "Jan",
+      "Feb",
+      "Mar",
+      "Apr",
+      "May",
+      "Jun",
+      "Jul",
+      "Aug",
+      "Sep",
+      "Oct",
+      "Nov",
+      "Dec"
+    ];
+    return `${months[d.getUTCMonth()]} ${d.getUTCDate()} ${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}`;
+  };
   return {
-    _comment: 'Additional quotes organized by category. Timestamps can be informal like "Feb 10 21:18". Avoid placing two quotes from the same agent close together \u2014 interleave different agents.',
+    _comment: 'Additional quotes organized by category. Timestamps can be informal (e.g. "Mar 2 14:30"). Avoid placing two quotes from the same agent close together \u2014 interleave different agents.',
     good: [
       {
         text: "Replace with a positive quote",
         author: "@agent-name",
-        timestamp: "Feb 10 12:00",
+        timestamp: fmt(start),
         context: "What was happening when this was said"
       }
     ],
@@ -254,7 +262,7 @@ function generateRetroPageQuotes() {
       {
         text: "Replace with a quote about a challenge",
         author: "@agent-name",
-        timestamp: "Feb 10 15:00",
+        timestamp: fmt(mid),
         context: "What went wrong"
       }
     ],
@@ -262,7 +270,7 @@ function generateRetroPageQuotes() {
       {
         text: "Replace with a quote about the hardest moment",
         author: "@agent-name",
-        timestamp: "Feb 10 18:00",
+        timestamp: fmt(end),
         context: "The lowest point"
       }
     ]
@@ -398,7 +406,7 @@ async function runCurate(options) {
   const retroData = generateRetroPageData(dateRange, agents, rosterTypes);
   writeFileSync(retroDataPath, `${JSON.stringify(retroData, null, 2)}
 `);
-  const retroQuotes = generateRetroPageQuotes();
+  const retroQuotes = generateRetroPageQuotes(dateRange);
   writeFileSync(retroQuotesPath, `${JSON.stringify(retroQuotes, null, 2)}
 `);
   const extractDateRange = {
@@ -412,7 +420,7 @@ async function runCurate(options) {
   console.log(`
 Generated curation scaffolds in ${progress.project.dataDir}/:
 `);
-  console.log("  \u25CB retro-page-data.json \u2014 fill in phases, milestones, quotes, trust arc");
+  console.log("  \u25CB retro-page-data.json \u2014 fill in phases, milestones, quotes, narration");
   console.log("  \u25CB retro-page-quotes.json \u2014 add additional quotes");
   console.log(`  \u2713 timeline-events.json \u2014 auto-generated (${eventCount} events)`);
   if (dateRange) {

package/dist-cli/index.js

@@ -13,6 +13,23 @@ import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync }
 import { resolve as resolve3 } from "path";
 
 // src/cli/guided/data-summary.ts
+function formatShortDate(d) {
+  const months = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec"
+  ];
+  return `${months[d.getUTCMonth()]} ${d.getUTCDate()} ${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}`;
+}
 function buildDataSummary(data) {
   const lines = [];
   const parts = [];
@@ -58,8 +75,54 @@ function buildDataSummary(data) {
     lines.push("");
     lines.push(`  \u{1F4CA} Data inventory: ${parts.join(", ")}`);
   }
+  const dateRange = getDateRangeFromData(data);
+  if (dateRange) {
+    lines.push(
+      `  \u{1F4C5} Date range: ${formatShortDate(dateRange.earliest)} \u2192 ${formatShortDate(dateRange.latest)}`
+    );
+  }
+  if (data.chatActivity?.agentTotals) {
+    const sorted = Object.entries(data.chatActivity.agentTotals).sort(([, a], [, b]) => b - a).slice(0, 5);
+    if (sorted.length > 0) {
+      const speakerList = sorted.map(([agent, count]) => `${agent} (${count})`).join(", ");
+      lines.push(`  \u{1F5E3}\uFE0F Top speakers: ${speakerList}`);
+    }
+  }
+  if (data.chatActivity?.bursts && data.chatActivity.bursts.length > 0) {
+    const topBursts = data.chatActivity.bursts.sort((a, b) => b.messages - a.messages).slice(0, 3);
+    if (topBursts.length > 0) {
+      lines.push("  \u{1F525} Activity bursts:");
+      for (const burst of topBursts) {
+        const start = formatShortDate(new Date(burst.start));
+        lines.push(
+          `     ${start} \u2014 ${burst.messages} msgs${burst.label ? ` (${burst.label})` : ""}`
+        );
+      }
+    }
+  }
   return lines;
 }
+function getDateRangeFromData(data) {
+  const allDates = [];
+  if (data.commits) {
+    for (const c of data.commits) {
+      const t = new Date(c.date).getTime();
+      if (!Number.isNaN(t)) allDates.push(t);
+    }
+  }
+  if (data.chatActivity?.coverage) {
+    const { start, end } = data.chatActivity.coverage;
+    const s = new Date(start).getTime();
+    const e = new Date(end).getTime();
+    if (!Number.isNaN(s)) allDates.push(s);
+    if (!Number.isNaN(e)) allDates.push(e);
+  }
+  if (allDates.length === 0) return null;
+  return {
+    earliest: new Date(Math.min(...allDates)),
+    latest: new Date(Math.max(...allDates))
+  };
+}
 
 // src/cli/guided/docs.ts
 import { existsSync, readFileSync } from "fs";
@@ -121,13 +184,11 @@ function curationContext() {
     "  \u2502    Each phase gets a name, color, and time range.       \u2502",
     "  \u2502                                                         \u2502",
     "  \u2502  Quotes \u2192 speech bubbles above agents in the viz.       \u2502",
-    "  \u2502    Memorable lines shown as floating pills.             \u2502",
+    "  \u2502    Sequenced like a conversation \u2014 one at a time.       \u2502",
     "  \u2502                                                         \u2502",
     "  \u2502  Narration \u2192 text in the narration lane below the       \u2502",
     "  \u2502    timeline. Documentary-style storytelling.             \u2502",
     "  \u2502                                                         \u2502",
-    "  \u2502  Trust arc \u2192 a trust bar that rises/falls over time.    \u2502",
-    "  \u2502                                                         \u2502",
     "  \u2502  Journey: extract \u2192 curate \u2192 preview \u2192 iterate \u2192 video  \u2502",
     "  \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"
   ];
@@ -140,8 +201,9 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     return { action: "all_done", progress, output: output2 };
   }
   const config = STEP_CONFIG[step];
-  const stepPrefix = step === "extract" ? "\u26D4 FOLLOW THESE INSTRUCTIONS EXACTLY. This step requires human input BEFORE running any commands." : config.creative ? "\u26D4 FOLLOW THESE INSTRUCTIONS EXACTLY. This is a CREATIVE step \u2014 present results to the human and WAIT for their direction before proceeding." : "\u26D4 FOLLOW THESE INSTRUCTIONS EXACTLY. This is a mechanical step \u2014 run it, report the result, then call `next` again.";
-  const output = [stepPrefix];
+  const output = [
+    config.creative ? "\u26D4 FOLLOW THESE INSTRUCTIONS EXACTLY. This is a CREATIVE step \u2014 present results to the human and WAIT for their direction before proceeding." : "\u26D4 FOLLOW THESE INSTRUCTIONS EXACTLY. This is a mechanical step \u2014 run it, report the result, then call `next` again."
+  ];
   const state = progress.steps[step];
   if (state.status === "error") {
     output.push("", `\u2717 ${config.label} failed: ${state.error || "unknown error"}`);
@@ -338,10 +400,13 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
       output.push("", "\u270F\uFE0F  Curation in progress");
       output.push(...curationContext());
       output.push("", "  Edit the scaffold files in data/:");
-      output.push("    \u25CB retro-page-data.json \u2014 phases, milestones, quotes, trust arc");
+      output.push("    \u25CB retro-page-data.json \u2014 phases, milestones, quotes");
       output.push("    \u25CB retro-page-quotes.json \u2014 additional quotes");
+      output.push("    \u25CB narration-editorial.json \u2014 editorial narration (fractional 0-1 timing)");
       output.push("    \u2713 timeline-events.json \u2014 auto-generated");
-      output.push("", "  When done, run 'npx miriad-viz next' again.");
+      output.push("");
+      output.push("  \u26A0\uFE0F  Run `npx miriad-viz timeline` to check sequencing after every edit.");
+      output.push("  When timeline is clean, run 'npx miriad-viz next' to advance.");
       return { action: "waiting_for_edit", step, progress, output };
     }
     const outputsExist = config.outputFiles.some((f) => fileSet.has(f));
@@ -421,6 +486,62 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
   if (step === "curate") {
     output.push("", `\u25B6 ${config.label}...`);
     output.push(...curationContext());
+    const story = progress.project.story;
+    if (story?.direction) {
+      output.push("");
+      output.push("  \u{1F4D6} Story direction from init:");
+      output.push(`    Arc: ${story.direction}`);
+      if (story.focusPeriod) output.push(`    Focus period: ${story.focusPeriod}`);
+      if (story.keyMoments?.length) {
+        output.push(`    Key moments: ${story.keyMoments.join("; ")}`);
+      }
+      if (story.notes) output.push(`    Notes: ${story.notes}`);
+    }
+    output.push("");
+    output.push("  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+    output.push("  CURATION METHODOLOGY \u2014 follow these phases in order:");
+    output.push("  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+    output.push("");
+    output.push("  Phase A \u2014 Present data findings (mechanical):");
+    output.push("    Read the extracted data summary. Reference the story direction.");
+    output.push(`    "Your human asked for [arc]. Here's what the data shows..."`);
+    output.push("");
+    output.push("  Phase B \u2014 Mine the data (mechanical):");
+    output.push("    Search by each focus agent to understand their arc.");
+    output.push('    Search for emotional keywords: "fixed", "broken", "wtf",');
+    output.push('    "sorry", "actually", "wrong", all-caps, 3+ exclamation marks.');
+    output.push("    Search around turning point timestamps. Verify numbers.");
+    output.push("");
+    output.push("  Phase C \u2014 Show findings to human (CREATIVE STOP):");
+    output.push('    "Here are the 5 most dramatic moments I found: [moments]"');
+    output.push('    "Does this match your story? Should I adjust focus?"');
+    output.push("    WAIT for human feedback before proceeding.");
+    output.push("");
+    output.push("  Phase D \u2014 Propose structure + quotes (CREATIVE STOP):");
+    output.push("    Present proposed phases, milestones, candidate quotes.");
+    output.push("    Quotes sequenced as DIALOG \u2014 one pill at a time, no overlap.");
+    output.push(`    "Here's the story I'd tell. Does this work?"`);
+    output.push("    WAIT for human feedback before writing files.");
+    output.push("");
+    output.push("  Phase E \u2014 Write curation files + validate:");
+    output.push("    Write retro-page-data.json, retro-page-quotes.json.");
+    output.push("    Run `npx miriad-viz timeline` to check sequencing.");
+    output.push("    Fix issues, run timeline again until clean.");
+    output.push("");
+    output.push("  \u26A0\uFE0F  Run `npx miriad-viz timeline` BEFORE calling `next`.");
+    output.push("  It shows narration + quotes on a timeline with overlap/gap");
+    output.push("  warnings. Run it after every edit. When clean, run `next`.");
+    output.push("");
+    output.push("  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+    output.push("  SEQUENCING RULES \u2014 hard constraints:");
+    output.push("  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+    output.push("");
+    output.push("  \u2022 Same-agent quotes: NEVER overlap. Absolute.");
+    output.push("  \u2022 Cross-agent quotes: some overlap OK, but reads like");
+    output.push("    a conversation \u2014 one talks, then another responds.");
+    output.push("  \u2022 Narration: each segment finishes before next starts.");
+    output.push("  \u2022 \u26A0\uFE0F narration-editorial.json uses FRACTIONAL 0-1 for");
+    output.push("    start/end. Everything else uses ISO timestamps.");
     const curationDoc = readBundledDoc("miriad-viz-curation");
     if (curationDoc) {
       output.push("");
@@ -430,6 +551,26 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     }
     return { action: "run_inline", step, progress, output };
   }
+  if (step === "init") {
+    output.push("", `\u25B6 ${config.label}...`);
+    output.push("");
+    output.push("  After collecting repo, agents, and channel info, ask the human");
+    output.push("  about the STORY in natural conversation (not forms, not structured_ask):");
+    output.push("");
+    output.push(`    "What's the story of this project? What's the arc?"`);
+    output.push('    "Any key turning points or moments to focus on?"');
+    output.push('    "What tone \u2014 dramatic, funny, documentary?"');
+    output.push('    "Any time range to focus on, or the full history?"');
+    output.push("");
+    output.push("  Write the answers to progress.json under project.story:");
+    output.push("    { direction, focusPeriod, keyMoments, notes }");
+    output.push('  All fields optional. If human says "just show me what happened":');
+    output.push('    story.direction = "exploratory \u2014 discover the story from the data"');
+    output.push("");
+    output.push("  The story direction drives everything downstream \u2014 extract scope,");
+    output.push("  curation focus, what the agent mines for in the data.");
+    return { action: "run_inline", step, progress, output };
+  }
   if (config.mode === "inline") {
     output.push("", `\u25B6 ${config.label}...`);
     return { action: "run_inline", step, progress, output };
@@ -440,24 +581,20 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
   if (step === "extract") {
     output.push("");
     output.push("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
-    output.push("  \u2502  \u26D4 BEFORE RUNNING ANYTHING \u2014 Talk to the human first  \u2502");
-    output.push("  \u2502                                                        \u2502");
-    output.push("  \u2502  1. Explain what miriad-viz does (animated timeline     \u2502");
-    output.push("  \u2502     visualization of channel activity \u2014 commits, PRs,   \u2502");
-    output.push("  \u2502     messages, agent interactions rendered as video)     \u2502");
-    output.push("  \u2502                                                        \u2502");
-    output.push("  \u2502  2. Ask about scope:                                   \u2502");
-    output.push('  \u2502     "Which time period? Full channel history, or a     \u2502');
-    output.push('  \u2502      specific sprint/week/date range?"                 \u2502');
+    output.push("  \u2502  FIRST: Explain to the human what you're about to do  \u2502");
     output.push("  \u2502                                                        \u2502");
-    output.push("  \u2502  3. Ask about data sources:                            \u2502");
-    output.push('  \u2502     "Do you have a git repo for this project?          \u2502');
-    output.push('  \u2502      Where is the chat data?"                          \u2502');
+    output.push("  \u2502  miriad-viz builds an animated timeline visualization   \u2502");
+    output.push("  \u2502  of project activity \u2014 commits, PRs, messages, and     \u2502");
+    output.push("  \u2502  agent interactions rendered as a video.               \u2502");
     output.push("  \u2502                                                        \u2502");
-    output.push("  \u2502  4. Confirm the plan before extracting.                \u2502");
+    output.push("  \u2502  The pipeline:                                         \u2502");
+    output.push("  \u2502    1. Extract \u2014 pull raw data (git, chat, artifacts)   \u2502");
+    output.push("  \u2502    2. Curate  \u2014 editorial content (phases, quotes)     \u2502");
+    output.push("  \u2502    3. Preview \u2014 interactive browser preview            \u2502");
+    output.push("  \u2502    4. Audio   \u2014 narration, music, SFX                  \u2502");
+    output.push("  \u2502    5. Render  \u2014 final MP4 video                        \u2502");
     output.push("  \u2502                                                        \u2502");
-    output.push("  \u2502  Only run the extraction command AFTER the human       \u2502");
-    output.push("  \u2502  confirms the scope and data sources.                  \u2502");
+    output.push("  \u2502  Then proceed with extraction.                         \u2502");
     output.push("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
     const rulesDoc = readBundledDoc("miriad-viz-rules");
     if (rulesDoc) {
@@ -493,6 +630,12 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
       }
       output.push("");
     }
+    const focusPeriod = progress.project.story?.focusPeriod;
+    if (focusPeriod) {
+      output.push(`  \u{1F4C5} Story focus period: ${focusPeriod}`);
+      output.push("     Consider using --from/--to flags to scope extraction.");
+      output.push("");
+    }
     if (fileSet.has("extract-channel.sh")) {
       output.push("  \u{1F4D6} Extraction script found. Run it in background:");
       output.push("     nohup ./extract-channel.sh ./raw-data &> chat-extract.log &");
@@ -669,6 +812,7 @@ Commands:
   transform          Run transform pipeline
   preview            Launch the viewer
   render             Export video via Remotion
+  timeline           Check curation sequencing (narrative linter)
   init-viewer <dir>  Scaffold a viewer project
   init-remotion <dir> Scaffold a Remotion video project
 
@@ -798,7 +942,7 @@ async function runNext(flags) {
   if (result.action === "run_inline" && result.step) {
     switch (result.step) {
       case "curate": {
-        const { runCurate } = await import("./curate-KLE2K3TB.js");
+        const { runCurate } = await import("./curate-EWAMDCOW.js");
         await runCurate({ projectDir, progress: result.progress });
         writeProgress(projectDir, result.progress);
         if (result.progress.steps.curate.status === "complete") {
@@ -873,7 +1017,7 @@ async function main() {
     }
     case "curate": {
       const { projectDir, progress } = requireProject();
-      const { runCurate } = await import("./curate-KLE2K3TB.js");
+      const { runCurate } = await import("./curate-EWAMDCOW.js");
       await runCurate({ projectDir, progress });
       break;
     }
@@ -904,6 +1048,13 @@ async function main() {
       await runRender({ projectDir, progress, draft: flags.draft === true });
       break;
     }
+    case "timeline": {
+      const { projectDir, progress } = requireProject();
+      const { runTimeline } = await import("./timeline-EDSW3EWB.js");
+      const exitCode = runTimeline(projectDir, progress);
+      if (exitCode !== 0) process.exitCode = exitCode;
+      break;
+    }
     case "init-viewer":
     case "init-remotion": {
       const templateName = command === "init-viewer" ? "viewer" : "remotion";

package/dist-cli/timeline-EDSW3EWB.js

@@ -0,0 +1,335 @@
+// src/cli/guided/steps/timeline.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+
+// src/cli/guided/validate-curation.ts
+function parseTimestamp(timeStr, referenceYear) {
+  if (!timeStr) return null;
+  const isoDate = new Date(timeStr);
+  if (!Number.isNaN(isoDate.getTime()) && timeStr.includes("-")) {
+    return isoDate.getTime();
+  }
+  const months = {
+    jan: 0,
+    feb: 1,
+    mar: 2,
+    apr: 3,
+    may: 4,
+    jun: 5,
+    jul: 6,
+    aug: 7,
+    sep: 8,
+    oct: 9,
+    nov: 10,
+    dec: 11
+  };
+  const match = timeStr.match(/^(\w{3})\s+(\d{1,2})(?:\s+(\d{1,2}):(\d{2}))?/i);
+  if (match) {
+    const month = months[match[1].toLowerCase()];
+    if (month !== void 0) {
+      const day = Number.parseInt(match[2], 10);
+      const hour = match[3] ? Number.parseInt(match[3], 10) : 12;
+      const minute = match[4] ? Number.parseInt(match[4], 10) : 0;
+      const year = referenceYear ?? (/* @__PURE__ */ new Date()).getFullYear();
+      return new Date(year, month, day, hour, minute).getTime();
+    }
+  }
+  return null;
+}
+function resolveQuotes(input, startMs, durationMs) {
+  const quotes = [];
+  const referenceYear = new Date(startMs).getFullYear();
+  const rpd = input.retroPageData?.quotes;
+  if (rpd) {
+    for (const category of [rpd.theGood, rpd.theBad, rpd.theUgly, rpd.theFunny]) {
+      if (!category) continue;
+      for (const q of category) {
+        const ms = parseTimestamp(q.time, referenceYear);
+        if (ms !== null && durationMs > 0) {
+          quotes.push({
+            author: q.author.replace(/^@/, ""),
+            text: q.text,
+            normalizedTime: (ms - startMs) / durationMs
+          });
+        }
+      }
+    }
+  }
+  const rpq = input.retroPageQuotes;
+  if (rpq) {
+    for (const category of [rpq.good, rpq.bad, rpq.ugly]) {
+      if (!category) continue;
+      for (const q of category) {
+        const ms = parseTimestamp(q.timestamp, referenceYear);
+        if (ms !== null && durationMs > 0) {
+          quotes.push({
+            author: q.author.replace(/^@/, ""),
+            text: q.timestamp,
+            // Use timestamp as identifier
+            normalizedTime: (ms - startMs) / durationMs
+          });
+        }
+      }
+    }
+  }
+  return quotes.sort((a, b) => a.normalizedTime - b.normalizedTime);
+}
+function resolveNarration(input, startMs, durationMs) {
+  const entries = input.retroPageData?.editorialNarration;
+  if (!entries || entries.length === 0) return [];
+  const result = [];
+  for (const entry of entries) {
+    const ms = parseTimestamp(entry.time);
+    if (ms !== null && durationMs > 0) {
+      result.push({
+        text: entry.text,
+        phaseTitle: entry.phaseTitle ?? "",
+        normalizedTime: (ms - startMs) / durationMs
+      });
+    }
+  }
+  return result.sort((a, b) => a.normalizedTime - b.normalizedTime);
+}
+function computePillWindow(totalHours) {
+  const SIM_HOURS_PER_SECOND = 0.6;
+  const MIN_PILL_SECONDS = 5;
+  const playbackSeconds = totalHours / SIM_HOURS_PER_SECOND;
+  if (playbackSeconds <= 0) return 0.04;
+  return MIN_PILL_SECONDS / playbackSeconds;
+}
+function getTimeRange(input) {
+  const meta = input.retroPageData?.meta;
+  if (!meta?.startDate || !meta?.endDate) return null;
+  const startMs = new Date(meta.startDate).getTime();
+  const endMs = new Date(meta.endDate).getTime();
+  if (Number.isNaN(startMs) || Number.isNaN(endMs)) return null;
+  const durationMs = endMs - startMs;
+  const totalHours = meta.totalHours ?? durationMs / 36e5;
+  return { startMs, endMs, durationMs, totalHours };
+}
+function validateCurationFiles(input) {
+  const errors = [];
+  const warnings = [];
+  const range = getTimeRange(input);
+  if (!range) {
+    errors.push("Missing or invalid meta.startDate/endDate \u2014 cannot validate timing.");
+    return { valid: false, errors, warnings };
+  }
+  const { startMs, durationMs, totalHours } = range;
+  const pillWindow = computePillWindow(totalHours);
+  const quotes = resolveQuotes(input, startMs, durationMs);
+  const narration = resolveNarration(input, startMs, durationMs);
+  const byAgent = /* @__PURE__ */ new Map();
+  for (const q of quotes) {
+    let group = byAgent.get(q.author);
+    if (!group) {
+      group = [];
+      byAgent.set(q.author, group);
+    }
+    group.push(q);
+  }
+  for (const [agent, agentQuotes] of byAgent) {
+    for (let i = 0; i < agentQuotes.length - 1; i++) {
+      const current = agentQuotes[i];
+      const next = agentQuotes[i + 1];
+      const gap = next.normalizedTime - current.normalizedTime;
+      if (gap < pillWindow) {
+        const currentPct = (current.normalizedTime * 100).toFixed(1);
+        const nextPct = (next.normalizedTime * 100).toFixed(1);
+        errors.push(
+          `Same-agent overlap: @${agent} has quotes at ${currentPct}% and ${nextPct}% (gap ${(gap * 100).toFixed(1)}% < pill window ${(pillWindow * 100).toFixed(1)}%)`
+        );
+      }
+    }
+  }
+  for (let i = 0; i < narration.length - 1; i++) {
+    const current = narration[i];
+    const next = narration[i + 1];
+    const gap = next.normalizedTime - current.normalizedTime;
+    if (gap < pillWindow) {
+      const currentPct = (current.normalizedTime * 100).toFixed(1);
+      const nextPct = (next.normalizedTime * 100).toFixed(1);
+      errors.push(
+        `Narration overlap: entries at ${currentPct}% and ${nextPct}% (gap ${(gap * 100).toFixed(1)}% < window ${(pillWindow * 100).toFixed(1)}%)`
+      );
+    }
+  }
+  for (let i = 0; i < quotes.length - 1; i++) {
+    const current = quotes[i];
+    const next = quotes[i + 1];
+    if (current.author === next.author) continue;
+    const gap = next.normalizedTime - current.normalizedTime;
+    if (gap < pillWindow * 0.5) {
+      const currentPct = (current.normalizedTime * 100).toFixed(1);
+      const nextPct = (next.normalizedTime * 100).toFixed(1);
+      warnings.push(
+        `Cross-agent overlap: @${current.author} at ${currentPct}% and @${next.author} at ${nextPct}% are very close (gap ${(gap * 100).toFixed(1)}%)`
+      );
+    }
+  }
+  const teamAgents = new Set(
+    (input.retroPageData?.teamAssembly ?? []).map((a) => a.agent.replace(/^@/, ""))
+  );
+  if (teamAgents.size > 0) {
+    const quoteAgents = new Set(quotes.map((q) => q.author));
+    for (const agent of quoteAgents) {
+      if (!teamAgents.has(agent)) {
+        warnings.push(`Quote references @${agent} who is not in teamAssembly.`);
+      }
+    }
+  }
+  const allEvents = [
+    ...quotes.map((q) => q.normalizedTime),
+    ...narration.map((n) => n.normalizedTime)
+  ].sort((a, b) => a - b);
+  const GAP_THRESHOLD = 0.2;
+  if (allEvents.length > 0) {
+    if (allEvents[0] > GAP_THRESHOLD) {
+      warnings.push(
+        `Gap at start: no content until ${(allEvents[0] * 100).toFixed(0)}% of timeline.`
+      );
+    }
+    for (let i = 0; i < allEvents.length - 1; i++) {
+      const gap = allEvents[i + 1] - allEvents[i];
+      if (gap > GAP_THRESHOLD) {
+        const startPct = (allEvents[i] * 100).toFixed(0);
+        const endPct = (allEvents[i + 1] * 100).toFixed(0);
+        warnings.push(`Gap: no content from ${startPct}% to ${endPct}% of timeline.`);
+      }
+    }
+    const last = allEvents[allEvents.length - 1];
+    if (1 - last > GAP_THRESHOLD) {
+      warnings.push(`Gap at end: no content after ${(last * 100).toFixed(0)}% of timeline.`);
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function printTimeline(input) {
+  const range = getTimeRange(input);
+  if (!range) {
+    return "Cannot render timeline: missing meta.startDate/endDate.";
+  }
+  const { startMs, durationMs, totalHours } = range;
+  const pillWindow = computePillWindow(totalHours);
+  const quotes = resolveQuotes(input, startMs, durationMs);
+  const narration = resolveNarration(input, startMs, durationMs);
+  const lines = [];
+  lines.push(
+    `Timeline (${totalHours.toFixed(1)}h, pill window: ${(pillWindow * 100).toFixed(1)}%):`
+  );
+  lines.push("");
+  const events = [];
+  for (const q of quotes) {
+    const truncated = q.text.length > 40 ? `${q.text.slice(0, 37)}...` : q.text;
+    events.push({
+      normalizedTime: q.normalizedTime,
+      type: "quote",
+      label: `@${q.author}: "${truncated}"`,
+      agent: q.author
+    });
+  }
+  for (const n of narration) {
+    const truncated = n.text.length > 40 ? `${n.text.slice(0, 37)}...` : n.text;
+    const prefix = n.phaseTitle ? `[${n.phaseTitle}] ` : "";
+    events.push({
+      normalizedTime: n.normalizedTime,
+      type: "narration",
+      label: `${prefix}"${truncated}"`
+    });
+  }
+  events.sort((a, b) => a.normalizedTime - b.normalizedTime);
+  let lastEnd = 0;
+  const GAP_THRESHOLD = 0.2;
+  for (const event of events) {
+    const pos = event.normalizedTime;
+    if (pos - lastEnd > GAP_THRESHOLD) {
+      const gapStart = (lastEnd * 100).toFixed(0);
+      const gapEnd = (pos * 100).toFixed(0);
+      lines.push(`  \u26A0\uFE0F  GAP: ${gapStart}%-${gapEnd}% \u2014 no narration or quotes`);
+    }
+    const pct = (pos * 100).toFixed(1);
+    if (event.type === "narration") {
+      const endPct = ((pos + pillWindow) * 100).toFixed(1);
+      lines.push(`${pct.padStart(5)}%-${endPct.padStart(5)}%  [narration] ${event.label}`);
+    } else {
+      lines.push(`${pct.padStart(5)}%           ${event.label}`);
+    }
+    lastEnd = pos + pillWindow;
+  }
+  if (events.length > 0 && 1 - lastEnd > GAP_THRESHOLD) {
+    const gapStart = (lastEnd * 100).toFixed(0);
+    lines.push(`  \u26A0\uFE0F  GAP: ${gapStart}%-100% \u2014 no narration or quotes`);
+  }
+  lines.push("");
+  lines.push(`Summary: ${quotes.length} quotes, ${narration.length} narration entries`);
+  const validation = validateCurationFiles(input);
+  if (validation.errors.length > 0) {
+    lines.push("");
+    lines.push("ERRORS:");
+    for (const err of validation.errors) {
+      lines.push(`  \u274C ${err}`);
+    }
+  }
+  if (validation.warnings.length > 0) {
+    lines.push("");
+    lines.push("WARNINGS:");
+    for (const warn of validation.warnings) {
+      lines.push(`  \u26A0\uFE0F  ${warn}`);
+    }
+  }
+  if (validation.valid && validation.warnings.length === 0) {
+    lines.push("");
+    lines.push("\u2705 No issues found.");
+  }
+  return lines.join("\n");
+}
+
+// src/cli/guided/steps/timeline.ts
+function readCurationFiles(dataDir) {
+  const input = {};
+  const retroDataPath = resolve(dataDir, "retro-page-data.json");
+  if (existsSync(retroDataPath)) {
+    try {
+      input.retroPageData = JSON.parse(readFileSync(retroDataPath, "utf-8"));
+    } catch {
+      console.error(`  \u26A0\uFE0F  Could not parse ${retroDataPath}`);
+    }
+  }
+  const retroQuotesPath = resolve(dataDir, "retro-page-quotes.json");
+  if (existsSync(retroQuotesPath)) {
+    try {
+      input.retroPageQuotes = JSON.parse(readFileSync(retroQuotesPath, "utf-8"));
+    } catch {
+      console.error(`  \u26A0\uFE0F  Could not parse ${retroQuotesPath}`);
+    }
+  }
+  return input;
+}
+function runTimeline(projectDir, progress) {
+  const dataDir = resolve(projectDir, progress.project.dataDir);
+  if (!existsSync(dataDir)) {
+    console.error(`
+\u2717 Data directory not found: ${dataDir}`);
+    console.error("  Run extraction first: npx miriad-viz next");
+    return 1;
+  }
+  const retroDataPath = resolve(dataDir, "retro-page-data.json");
+  if (!existsSync(retroDataPath)) {
+    console.error("\n\u2717 No curation files found.");
+    console.error("  Run curation first: npx miriad-viz curate");
+    return 1;
+  }
+  const input = readCurationFiles(dataDir);
+  const timeline = printTimeline(input);
+  console.log("");
+  console.log(timeline);
+  const validation = validateCurationFiles(input);
+  return validation.valid ? 0 : 1;
+}
+export {
+  runTimeline
+};

package/docs/curation-guide.md

@@ -7,7 +7,7 @@ How to author the editorial layer that turns raw data into a story.
 miriad-viz separates data into two streams:
 
 - **RawData** — automated extraction. Commits, PRs, messages, agent joins. Deterministic: given the same channel, you always get the same output.
-- **CurationData** — editorial content. Phases, milestones, quotes, trust arc, and editorial narration. Requires human judgment: what mattered, when the story turned, which words captured the moment, and how to tell the story.
+- **CurationData** — editorial content. Phases, milestones, quotes, and editorial narration. Requires human judgment: what mattered, when the story turned, which words captured the moment, and how to tell the story.
 
 RawData tells you *what happened*. CurationData tells you *what it meant*.
 
@@ -47,12 +47,120 @@ The process:
 2. Form hypotheses about the story arc before picking quotes
 3. Verify every quote verbatim against the original message (timestamp, exact wording, speaker)
 4. Organize quotes by tone and arc position (good/bad/ugly, or by phase)
-5. Author the trust arc as a series of keyframes with human-readable labels
-6. Define phase boundaries at narrative turning points, not arbitrary time slices
-7. Iterate with the team — they'll catch misattributions and add context you missed
+5. Define phase boundaries at narrative turning points, not arbitrary time slices
+6. Iterate with the team — they'll catch misattributions and add context you missed
 
 **When to use:** External-facing content, published retrospectives, video narration. When accuracy and narrative quality both matter.
 
+---
+
+## Mining Methodology
+
+Build the arc first, search for quotes second. Don't browse messages hoping to find a story. Understand what happened, then find the evidence.
+
+### Phase A — Build the Skeleton
+
+Before touching any quotes, understand the story structure:
+
+1. **Read message history chronologically in chunks.** Don't try to read everything — filter strategically.
+2. **Filter by key players** to understand each person's journey through the project:
+   - Filter by the human to see every intervention
+   - Filter by leads for technical decisions
+   - Filter by testers/reviewers for QA moments
+3. **Build a timeline of turning points** — not every message, just the moments where the direction changed.
+4. **Form your hypothesis:** What's the arc? Setup → crisis → recovery? Exploration → convergence → polish? Name the acts before you search for quotes.
+
+### Phase B — Find the Beats (Targeted Search)
+
+Once you know the story beats, search for specific moments. **Search by emotion and turning points, not by topic.**
+
+Effective search terms:
+- `"fixed"` — finds every time someone claimed something was fixed (reveals fix loops)
+- `"broken"`, `"wrong"`, `"wtf"` — finds frustration peaks
+- `"sorry"`, `"actually"` — finds corrections and ownership moments
+- `"never"`, `"always"`, `"stop"`, `"please"` — finds intensity
+- All-caps messages, 3+ exclamation marks — finds emotional peaks
+- `"screenshot"`, `"vision"`, `"prove"` — finds methodology shifts
+
+**The technique:** The good quotes are AT the turning points. Search for the moment, the quote comes with it.
+
+### Phase C — Show Findings to the Human
+
+Present your top 5-10 most dramatic moments with actual quotes. Ask:
+- "Does this match your story? Should I adjust focus?"
+- "Are there moments I'm missing?"
+
+**WAIT for the human's refinement before proposing structure.**
+
+### Phase D — Propose Structure + Quotes
+
+Present proposed phases, milestones, and candidate quotes. The human drives editorial vision — what's funny, what's honest, what structure serves the story. The agent does legwork.
+
+**WAIT for human feedback before writing files.**
+
+### Phase E — Write + Validate + Iterate
+
+Write the curation files, then validate:
+
+```bash
+npx miriad-viz timeline
+```
+
+This shows your narration + quotes on a timeline with overlap/gap warnings. Run it after every edit. When clean, run `next` to advance.
+
+### Verify Every Number
+
+If a number appears in your curation, you must be able to point to the message or commit that proves it. Verify before writing, not after.
+
+- Test counts → search messages for test count claims
+- Lines deleted → check git log for the specific PR
+- PR counts → list every PR in the range
+- QA misses → find the specific "confirmed fixed" / "looks correct" messages
+
+---
+
+## Sequencing Rules (Conversation Model)
+
+Everything is sequenced like a conversation. No talking over each other.
+
+### Chat Pills (Quotes)
+
+- **Same agent: NEVER overlap.** Absolute rule. Two quotes from the same speaker must not be visible at the same time.
+- **Different agents: some overlap OK**, but should read like a conversation — one person talks, then another responds. Not two full pills stacked at the exact same time.
+- Think dialog turns or group chat: quick sequential bursts with pauses.
+- If original data has simultaneous messages, curation staggers them.
+
+### Narration Lines
+
+- Each narration segment finishes before the next starts. Sequenced, no overlap.
+- Like a narrator reading a script — one line at a time.
+
+### Validation
+
+Use `npx miriad-viz timeline` to check sequencing. The validator checks:
+
+1. **Same-agent quote overlap → REJECT** (hard error, must fix)
+2. **Narration segment overlap → REJECT** (hard error, must fix)
+3. **Cross-agent quote overlap → WARN** (some OK, excessive is bad)
+
+---
+
+## ⚠️ Narration Timing Format Warning
+
+**`narration-editorial.json` uses FRACTIONAL 0-1 for `start`/`end`.** Everything else in curation uses ISO timestamps.
+
+```json
+// narration-editorial.json — FRACTIONAL (0-1)
+{ "start": 0.23, "end": 0.68, "l1": "THE CRISIS", ... }
+
+// retro-page-data.json — ISO TIMESTAMPS
+{ "time": "2026-03-01T10:00:00+01:00", "label": "💡 Kickoff", ... }
+```
+
+Do NOT mix them up. If you put ISO timestamps in narration-editorial.json, the narration will not display. If you put fractions in retro-page-data.json, the phases will be wrong.
+
+---
+
 ## CurationData Contract
 
 The `CurationData` interface (defined in `src/types/raw-data.ts`):
@@ -126,25 +234,6 @@ Milestones are the timeline's signposts. They appear as vertical markers with la
 - Emoji prefixes work well for visual scanning: 💡 🔧 💔 ✅ 🏁
 - Space them so labels don't visually overlap. The renderer places labels at the milestone's timestamp — two milestones within minutes of each other will collide. If events are that close, pick the more important one.
 
-### Trust Keyframes
-
-```typescript
-interface CurationTrustKeyframe {
-  timestamp: number; // unix ms
-  level: number;     // 0-1 (0 = no trust, 1 = full trust)
-  label: string;     // human-readable, e.g. "Trust hits rock bottom"
-}
-```
-
-The trust arc is the emotional throughline. It tracks the human's confidence in the AI team over time. The engine interpolates between keyframes using smoothstep, so you only need to define the inflection points.
-
-**Guidelines:**
-- This is the most editorial piece of curation. It's a subjective judgment call — there's no algorithm that can extract "trust level" from chat messages.
-- Place keyframes at moments where trust visibly changed: a promise broken, a recovery delivered, a surprise failure, an unqualified praise.
-- 10-20 keyframes for a multi-day project. The smoothstep interpolation handles the gaps.
-- The renderer maps trust to color: red (0-0.3) → amber (0.3-0.7) → cyan (0.7-1.0). Design your arc knowing these thresholds.
-- Labels should be readable standalone — someone scanning the trust arc data should understand the story without reading the full history.
-
 ## Reasoning About Timing
 
 Your timeline has a total duration. The engine maps that to a progress bar (0→1). Every visual element — pills, narration, milestones — occupies a fraction of that bar. To make good curation decisions, you need to reason about how your content maps to screen time.
@@ -197,6 +286,8 @@ The queue logic: milestones are sorted by time and always take priority. Phase n
 
 Editorial narration lives in a dedicated file: `narration-editorial.json`
 
+⚠️ **This file uses FRACTIONAL 0-1 for `start`/`end`, NOT ISO timestamps.** See [Narration Timing Format Warning](#️-narration-timing-format-warning) above.
+
 ```json
 [
   {
@@ -275,7 +366,7 @@ The CLI expects curation data as JSON files in the data directory:
 
 ### `retro-page-data.json`
 
-The primary curation file. Contains phases, milestones, quotes, trust arc, team assembly, and project metadata.
+The primary curation file. Contains phases, milestones, quotes, team assembly, and project metadata.
 
 ```json
 {
@@ -325,20 +416,12 @@ The primary curation file. Contains phases, milestones, quotes, trust arc, team
     "theBad": [],
     "theUgly": [],
     "theFunny": []
-  },
-  "trustArc": [
-    {
-      "time": "2026-03-01T10:00:00",
-      "level": 80,
-      "label": "Excited kickoff"
-    }
-  ]
+  }
 }
 ```
 
 **Notes:**
 - `quotes.time` uses informal format ("Mar 2 14:30") — the transform layer parses this. ISO 8601 also works.
-- `trustArc.level` is 0-100 in the source file. The transform normalizes to 0-1.
 - `phases.color` and `phases.prRange` are informational — the processing layer assigns its own colors and doesn't use PR ranges.
 - `teamAssembly` feeds into RawData agent joins, not CurationData directly.
 
@@ -367,6 +450,8 @@ Both files are merged by `transformToCurationData()` in the transform layer. Quo
 
 Editorial narration for the narration lane. See the [Editorial Narration](#editorial-narration) section above for the full format specification and writing guide.
 
+⚠️ **Uses FRACTIONAL 0-1 for `start`/`end`, NOT ISO timestamps.**
+
 ```json
 [
   {
@@ -388,15 +473,13 @@ This file is optional. Without it, the narration lane will display quote text (f
 
 Run extraction to produce the automated data files (`git-commits.json`, `pr-details.json`, `chat-activity.json`, etc.). You need this context before you can curate — the raw data tells you the timeline, the players, and the activity patterns.
 
-### Step 2: Read the History
+### Step 2: Mine the History
 
-Read the channel's message history. For Tier 2, an agent can do this via MCP tools (`get_messages` with pagination). For Tier 3, a human reads alongside.
-
-Look for:
-- **Turning points** — where did the project's direction change? These become phase boundaries.
-- **Emotional peaks** — moments of frustration, celebration, surprise, disappointment. These become trust keyframes.
-- **Memorable quotes** — words that capture a moment better than any summary could. These become quotes.
-- **Concrete milestones** — first working prototype, first test passing, first deployment, first user feedback. These become milestones.
+Follow the [Mining Methodology](#mining-methodology) above:
+1. Build the skeleton — filter by key players, identify turning points
+2. Search by emotion — `"fixed"`, `"broken"`, `"sorry"`, `"actually"`, all-caps
+3. Show findings to the human — top 5-10 dramatic moments with quotes
+4. Get human refinement before proposing structure
 
 ### Step 3: Define Phases
 
@@ -426,13 +509,7 @@ Search for quotes that:
 - [ ] Speaker attribution is correct
 - [ ] Phase assignment makes sense
 
-### Step 6: Author the Trust Arc
-
-Plot the human's confidence over time. This is subjective — embrace that. The trust arc is editorial, not data.
-
-Start at the beginning: how confident was the human when the project kicked off? Walk through each phase and ask: did trust go up or down here? By how much? Place a keyframe at each inflection point.
-
-### Step 7: Write Editorial Narration
+### Step 6: Write Editorial Narration
 
 Once you have phases and milestones, write the narration layer. See [Editorial Narration](#editorial-narration) for the full guide. The short version:
 
@@ -445,30 +522,30 @@ This step is optional but strongly recommended. Without narration, the visualiza
 
 **Tier 2 shortcut:** Have an LLM read your phases + milestones + a sample of key messages, then draft the narration. Review and rewrite — LLM-drafted narration tends to be too formal and too long. Cut aggressively. Add humor. Make it sound like a person, not a report.
 
-### Step 8: Write the JSON Files
+### Step 7: Validate with Timeline
 
-Create `retro-page-data.json`, `retro-page-quotes.json`, and `narration-editorial.json` in your data directory following the formats above. Run the pipeline:
+Run `npx miriad-viz timeline` to check your work. It shows:
+- Narration segments + quotes on a single timeline axis
+- Same-agent quote overlaps (errors)
+- Narration overlaps (errors)
+- Gaps where the narration lane will be empty (warnings)
 
-```bash
-pnpm viz <data-dir>
-```
+Fix any issues, run `timeline` again until clean.
+
+### Step 8: Write the JSON Files
 
-The CLI will validate the files and produce `viz-data.json`. Check the output:
-- Are all phases present with correct time ranges?
-- Are quotes assigned to the right phases?
-- Does the trust arc have the shape you intended?
-- Does the narration lane show editorial text (not quote fallback)?
+Create `retro-page-data.json`, `retro-page-quotes.json`, and `narration-editorial.json` in your data directory following the formats above. Run `npx miriad-viz next` to validate and advance.
 
 ### Step 9: Iterate
 
 Watch the visualization. Does the story come through? Common issues:
 - **Quotes appearing at wrong times** — check timestamps
 - **Phases too short or too long** — adjust boundaries
-- **Trust arc too flat** — add more keyframes at inflection points
 - **Too many milestones clustered together** — thin them out, keep the most important
-- **Narration lane empty or showing quotes** — check `narration-editorial.json` is loaded and entries have correct `start`/`end` times
+- **Narration lane empty or showing quotes** — check `narration-editorial.json` is loaded and entries have correct `start`/`end` times (fractional 0-1, NOT ISO timestamps)
 - **Narration feels rushed** — widen the `start`/`end` windows so text stays on screen longer
 - **Narration gaps (lane goes blank)** — add phase gap-fillers or lower the gap threshold
+- **Same-agent quotes overlapping** — run `npx miriad-viz timeline` to find them, then stagger
 
 ## The Measurement Paradox
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miriad-viz",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snorrees/miriad-viz.git"