miriad-viz 0.2.0 → 0.2.2

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

@@ -132,7 +132,7 @@ function generateRetroPageData(dateRange, agents, rosterTypes) {
   const midISO = new Date(Math.round((startMs + endMs) / 2)).toISOString();
   const totalHours = dateRange?.hours ?? 0;
   return {
-    _comment: "Fill in phases, milestones, quotes, and trust arc. See docs/curation-guide.md for details.",
+    _comment: "Fill in phases, milestones, quotes, and trust arc.",
     meta: {
       title: "Project Title",
       subtitle: "A brief description of the project",
@@ -241,7 +241,7 @@ function generateRetroPageData(dateRange, agents, rosterTypes) {
 }
 function generateRetroPageQuotes() {
   return {
-    _comment: 'Additional quotes organized by category. See docs/curation-guide.md. 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 like "Feb 10 21:18". Avoid placing two quotes from the same agent close together \u2014 interleave different agents.',
     good: [
       {
         text: "Replace with a positive quote",
@@ -422,7 +422,6 @@ Your project spans ${dateRange.hours} hours.`);
   if (agents.length > 0) {
     console.log(`Agents: ${agents.join(", ")}`);
   }
-  console.log("\nSee: docs/curation-guide.md");
   progress.steps.curate = { status: "in_progress" };
   writeProgress(projectDir, progress);
   console.log("\nEdit the scaffold files, then run 'npx miriad-viz next' to continue.");

package/dist-cli/index.js

@@ -9,8 +9,8 @@ import {
 } from "./chunk-E6W6WNZ6.js";
 
 // src/cli/guided/index.ts
-import { existsSync as existsSync2, readFileSync, readdirSync } from "fs";
-import { resolve as resolve2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync } from "fs";
+import { resolve as resolve3 } from "path";
 
 // src/cli/guided/data-summary.ts
 function buildDataSummary(data) {
@@ -61,6 +61,30 @@ function buildDataSummary(data) {
   return lines;
 }
 
+// src/cli/guided/docs.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+function readBundledDoc(slug) {
+  const thisFile = fileURLToPath(import.meta.url);
+  const docsDir = findDocsDir(thisFile);
+  if (!docsDir) return null;
+  const filePath = resolve(docsDir, `${slug}.md`);
+  if (!existsSync(filePath)) return null;
+  return readFileSync(filePath, "utf-8");
+}
+function findDocsDir(fromFile) {
+  let dir = resolve(fromFile, "..");
+  for (let i = 0; i < 10; i++) {
+    const candidate = resolve(dir, "docs");
+    if (existsSync(resolve(dir, "package.json")) && existsSync(candidate)) {
+      return candidate;
+    }
+    dir = resolve(dir, "..");
+  }
+  return null;
+}
+
 // src/cli/guided/next.ts
 var AUDIO_DIR_PREFIX = "remotion/public/audio/";
 function buildCommand(step, progress, flags) {
@@ -116,9 +140,8 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     return { action: "all_done", progress, output: output2 };
   }
   const config = STEP_CONFIG[step];
-  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 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 state = progress.steps[step];
   if (state.status === "error") {
     output.push("", `\u2717 ${config.label} failed: ${state.error || "unknown error"}`);
@@ -258,7 +281,7 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     output.push("");
     output.push("  MANIFEST FORMAT:");
     output.push(`    Save to: ${AUDIO_DIR_PREFIX}audio-manifest.json`);
-    output.push("    Schema: AudioManifest from miriad-viz (see docs)");
+    output.push("    Schema: AudioManifest from miriad-viz (see guide below)");
     output.push("");
     output.push(
       "    { version: 1, fps: 30, totalDurationSec, dialog[], music[], sfx[], overlays[] }"
@@ -285,6 +308,13 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     output.push("    measure-duration.sh   \u2014 ffprobe wrapper \u2192 clip duration in seconds");
     output.push("");
     output.push("  To skip audio: npx miriad-viz next --skip-audio");
+    const audioDoc = readBundledDoc("miriad-viz-audio");
+    if (audioDoc) {
+      output.push("");
+      output.push("\u2501\u2501\u2501 AUDIO GENERATION GUIDE \u2501\u2501\u2501");
+      output.push(audioDoc);
+      output.push("\u2501\u2501\u2501 END AUDIO GUIDE \u2501\u2501\u2501");
+    }
     progress.steps.audio = { status: "in_progress" };
     return { action: "run_inline", step, progress, output };
   }
@@ -391,6 +421,13 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
   if (step === "curate") {
     output.push("", `\u25B6 ${config.label}...`);
     output.push(...curationContext());
+    const curationDoc = readBundledDoc("miriad-viz-curation");
+    if (curationDoc) {
+      output.push("");
+      output.push("\u2501\u2501\u2501 CURATION GUIDE \u2501\u2501\u2501");
+      output.push(curationDoc);
+      output.push("\u2501\u2501\u2501 END CURATION GUIDE \u2501\u2501\u2501");
+    }
     return { action: "run_inline", step, progress, output };
   }
   if (config.mode === "inline") {
@@ -401,6 +438,41 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
   const logFile = config.logFile || `${step}.log`;
   output.push("", `\u{1F4CB} ${config.label}`);
   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                                                        \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                                                        \u2502");
+    output.push("  \u2502  4. Confirm the plan before extracting.                \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("  \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) {
+      output.push("");
+      output.push("\u2501\u2501\u2501 RULES \u2014 READ BEFORE DOING ANYTHING \u2501\u2501\u2501");
+      output.push(rulesDoc);
+      output.push("\u2501\u2501\u2501 END RULES \u2501\u2501\u2501");
+    }
+    const pipelineDoc = readBundledDoc("miriad-viz-pipeline");
+    if (pipelineDoc) {
+      output.push("");
+      output.push("\u2501\u2501\u2501 PIPELINE OVERVIEW \u2501\u2501\u2501");
+      output.push(pipelineDoc);
+      output.push("\u2501\u2501\u2501 END PIPELINE OVERVIEW \u2501\u2501\u2501");
+    }
     output.push("");
     output.push("  \u256D\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\u256E");
     output.push("  \u2502  miriad-viz builds an animated timeline visualization   \u2502");
@@ -426,7 +498,7 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
       output.push("     nohup ./extract-channel.sh ./raw-data &> chat-extract.log &");
     } else {
       output.push("  \u{1F4D6} You need a platform extraction script for chat data.");
-      output.push('     On Miriad: kb_read(kb: "root", doc: "miriad-viz-extraction-script")');
+      output.push('     On Miriad: kb_read(kb: "root", doc: "miriad-viz")');
       output.push(
         "     Otherwise: provide JSON files directly with --chat-input / --artifact-input"
       );
@@ -439,6 +511,15 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     output.push("    --from <date>            Filter start date (ISO 8601, inclusive)");
     output.push("    --to <date>              Filter end date (ISO 8601, inclusive)");
   }
+  if (step === "render") {
+    const videoDoc = readBundledDoc("miriad-viz-video");
+    if (videoDoc) {
+      output.push("");
+      output.push("\u2501\u2501\u2501 VIDEO PRODUCTION GUIDE \u2501\u2501\u2501");
+      output.push(videoDoc);
+      output.push("\u2501\u2501\u2501 END VIDEO GUIDE \u2501\u2501\u2501");
+    }
+  }
   output.push("", "  Run this command:");
   output.push(`    nohup ${command} &> ${logFile} &`);
   output.push("");
@@ -451,8 +532,8 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
 }
 
 // src/cli/guided/steps/init.ts
-import { existsSync, mkdirSync } from "fs";
-import { resolve } from "path";
+import { existsSync as existsSync2, mkdirSync } from "fs";
+import { resolve as resolve2 } from "path";
 
 // src/cli/guided/parse-agents.ts
 function parseAgentList(input) {
@@ -467,12 +548,12 @@ function parseAgentList(input) {
 
 // src/cli/guided/steps/init.ts
 async function runInit(options) {
-  const projectDir = resolve(options.dir);
+  const projectDir = resolve2(options.dir);
   const existing = readProgress(projectDir);
   if (existing) {
     console.log(`
 Project already initialized: ${existing.project.name}`);
-    console.log(`Progress file: ${resolve(projectDir, PROGRESS_FILENAME)}`);
+    console.log(`Progress file: ${resolve2(projectDir, PROGRESS_FILENAME)}`);
     console.log("\nRun 'npx miriad-viz next' to continue.");
     return;
   }
@@ -491,12 +572,12 @@ Project already initialized: ${existing.project.name}`);
     dataDir,
     outputDir
   };
-  const absDataDir = resolve(projectDir, dataDir);
-  const absOutputDir = resolve(projectDir, outputDir);
-  if (!existsSync(absDataDir)) {
+  const absDataDir = resolve2(projectDir, dataDir);
+  const absOutputDir = resolve2(projectDir, outputDir);
+  if (!existsSync2(absDataDir)) {
     mkdirSync(absDataDir, { recursive: true });
   }
-  if (!existsSync(absOutputDir)) {
+  if (!existsSync2(absOutputDir)) {
     mkdirSync(absOutputDir, { recursive: true });
   }
   const progress = createProgressFile(config);
@@ -623,8 +704,8 @@ function requireProject() {
   return { projectDir, progress };
 }
 function gatherAudioFiles(projectDir) {
-  const audioDir = resolve2(projectDir, AUDIO_DIR_PREFIX);
-  if (!existsSync2(audioDir)) return [];
+  const audioDir = resolve3(projectDir, AUDIO_DIR_PREFIX);
+  if (!existsSync3(audioDir)) return [];
   const files = [];
   try {
     const entries = readdirSync(audioDir, { recursive: true });
@@ -642,11 +723,11 @@ function gatherExistingFiles(projectDir) {
   const files = [];
   for (const config of Object.values(STEP_CONFIG)) {
     for (const f of config.outputFiles) {
-      if (existsSync2(resolve2(projectDir, f))) {
+      if (existsSync3(resolve3(projectDir, f))) {
         files.push(f);
       }
     }
-    if (config.logFile && existsSync2(resolve2(projectDir, config.logFile))) {
+    if (config.logFile && existsSync3(resolve3(projectDir, config.logFile))) {
       files.push(config.logFile);
     }
   }
@@ -656,10 +737,10 @@ function gatherLogTails(projectDir) {
   const tails = {};
   for (const config of Object.values(STEP_CONFIG)) {
     if (!config.logFile) continue;
-    const logPath = resolve2(projectDir, config.logFile);
-    if (existsSync2(logPath)) {
+    const logPath = resolve3(projectDir, config.logFile);
+    if (existsSync3(logPath)) {
       try {
-        const content = readFileSync(logPath, "utf-8");
+        const content = readFileSync2(logPath, "utf-8");
         const lines = content.split("\n").filter(Boolean);
         tails[config.logFile] = lines.slice(-5);
       } catch {
@@ -676,10 +757,10 @@ function gatherDataSummary(projectDir, dataDir) {
     chatActivity: null
   };
   const tryRead = (filename) => {
-    const path = resolve2(projectDir, dataDir, filename);
-    if (!existsSync2(path)) return null;
+    const path = resolve3(projectDir, dataDir, filename);
+    if (!existsSync3(path)) return null;
     try {
-      return JSON.parse(readFileSync(path, "utf-8"));
+      return JSON.parse(readFileSync2(path, "utf-8"));
     } catch {
       return null;
     }
@@ -717,7 +798,7 @@ async function runNext(flags) {
   if (result.action === "run_inline" && result.step) {
     switch (result.step) {
       case "curate": {
-        const { runCurate } = await import("./curate-IYK3CRLW.js");
+        const { runCurate } = await import("./curate-KLE2K3TB.js");
         await runCurate({ projectDir, progress: result.progress });
         writeProgress(projectDir, result.progress);
         if (result.progress.steps.curate.status === "complete") {
@@ -792,7 +873,7 @@ async function main() {
     }
     case "curate": {
       const { projectDir, progress } = requireProject();
-      const { runCurate } = await import("./curate-IYK3CRLW.js");
+      const { runCurate } = await import("./curate-KLE2K3TB.js");
       await runCurate({ projectDir, progress });
       break;
     }
@@ -834,7 +915,7 @@ async function main() {
       }
       const { scaffoldTemplate, resolvePackageRoot } = await import("./init-template-F6X3TAAM.js");
       const packageRoot = resolvePackageRoot(import.meta.url);
-      const resolvedOutDir = resolve2(process.cwd(), outDir);
+      const resolvedOutDir = resolve3(process.cwd(), outDir);
       try {
         scaffoldTemplate(templateName, resolvedOutDir, packageRoot);
         console.log(`

package/docs/miriad-viz-pipeline.md

@@ -84,7 +84,7 @@ npx miriad-viz@latest init --name "My Retro" --repo owner/repo1,owner/repo2 --ag
 
 Extracts git commits, PR data, and chat messages mechanically. No LLM tokens.
 
-**Chat extraction uses a platform-specific script.** On Miriad, read `miriad-viz-extraction-script` from the root KB. Otherwise, provide JSON files directly with `--chat-input` / `--artifact-input`.
+**Chat extraction uses a platform-specific script.** On Miriad, read `miriad-viz` from the root KB — it includes the extraction script inline. Otherwise, provide JSON files directly with `--chat-input` / `--artifact-input`.
 
 > ### ⚠️ CRITICAL: Use the Shell Script, NOT MCP Tools
 > **DO NOT use `get_messages` or any MCP tools to extract messages.** Every MCP tool call puts the response into your context window — for thousands of messages, this wastes massive tokens. The shell script uses `curl` directly. **Zero tokens. Zero context usage.**

package/docs/miriad-viz.md

@@ -35,6 +35,6 @@ npx miriad-viz@latest next    # follow the output exactly
 | [Video Export](./miriad-viz-video.md) | At the render/video step |
 | [Reference](./miriad-viz-reference.md) | When you need CLI flags or data formats |
 
-**Extraction script** is platform-specific and not bundled. On Miriad, read `miriad-viz-extraction-script` from the root KB. Otherwise, provide JSON files directly with `--chat-input` / `--artifact-input`.
+**Extraction script** is platform-specific and not bundled. On Miriad, read `miriad-viz` from the root KB — it includes the extraction script inline. Otherwise, provide JSON files directly with `--chat-input` / `--artifact-input`.
 
 ⚠️ **Do NOT read all docs upfront.** Each step needs different context. Reading everything wastes tokens and creates confusion. Trust `next` to guide you.

package/package.json

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