miriad-viz 0.13.0 → 0.13.2

package/dist-cli/{generate-viz-curation-KRFC2ZSB.js → generate-viz-curation-R6SUTONK.js}

@@ -114,7 +114,8 @@ function generateVizCuration(script, clipDurations, densityInput, projectStart,
         speaker: line.speaker,
         text: line.text,
         progress: positions[i],
-        duration: DEFAULT_PILL_DURATION
+        duration: DEFAULT_PILL_DURATION,
+        anchor: true
       });
     }
   }

package/dist-cli/index.js

@@ -242,8 +242,9 @@ function buildCurationTable(narration, pills, densityInput, projectStart, projec
     output.push(`  \u{1F4AC} ${pills.length} pills placed:`);
     for (const p of pills) {
       const truncText = p.text.length > 40 ? `${p.text.slice(0, 37)}...` : p.text;
+      const anchorTag = p.anchor ? " [anchor]" : "";
       output.push(
-        `    @ ${p.progress.toFixed(1)} (${p.duration.toFixed(1)}s): ${p.speaker} \u2014 "${truncText}"`
+        `    @ ${p.progress.toFixed(1)} (${p.duration.toFixed(1)}s): ${p.speaker} \u2014 "${truncText}"${anchorTag}`
       );
     }
   }
@@ -480,45 +481,20 @@ function buildVizTimingInProgress(_progress, densityInput, scriptLines, projectS
   output.push("    2.0 = viz covers project time 2x faster (LESS screen time)");
   output.push("    0.5 = viz covers project time 2x slower (MORE screen time)");
   output.push("");
-  output.push(
-    "  Also edit pacing.json for fine-grained control \u2014 you can change ONLY these 4 fields per line:"
-  );
-  output.push("    pauseAfter   \u2014 seconds of silence after this clip (default: 0.5)");
-  output.push("    vizSpeed     \u2014 viz speed DURING this clip (default: 1.0)");
-  output.push(
-    "    gapVizSpeed  \u2014 viz speed BETWEEN this clip and the next (default: same as defaultVizSpeed)"
-  );
-  output.push("    note         \u2014 your reasoning (for yourself, not rendered)");
-  output.push("");
-  output.push("  vizSpeed is a MULTIPLIER on project-time-per-second:");
-  output.push("    1.0 = default rate");
-  output.push("    2.0 = viz covers project time 2x faster (LESS screen time)");
-  output.push("    0.5 = viz covers project time 2x slower (MORE screen time)");
-  output.push("");
-  output.push("  HOW SPEED FIELDS MAP TO THE TIMELINE:");
-  output.push("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2510");
-  output.push("  \u2502 narrator-01 clip\u2502 \u2502 gap \u2502 \u2502 narrator-02 clip\u2502 \u2502 gap \u2502");
-  output.push("  \u2502  vizSpeed: 1.0  \u2502 \u2502 2.0 \u2502 \u2502  vizSpeed: 0.5  \u2502 \u2502 1.0 \u2502");
-  output.push("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2518");
-  output.push("   \u2191 speed DURING clip  \u2191 gapVizSpeed   \u2191 speed DURING clip  \u2191 gapVizSpeed");
-  output.push("     (audio playing)    (silence/pause)   (audio playing)     (silence/pause)");
-  output.push("");
-  output.push("  SPEED REASONING (creative choice, not formula):");
-  output.push("    Dead time (nothing happening) \u2192 high gapVizSpeed (skip through it)");
-  output.push("    Lots of action \u2192 normal or slow vizSpeed (let viewer see the frenzy)");
-  output.push("    Dramatic reveal \u2192 big pauseAfter (tension before the next line)");
-  output.push("    These are guidelines. Trust your creative judgment.");
+  output.push("  HOW TO CONTROL PACING:");
+  output.push("    Move progress points CLOSER together \u2192 smaller gap \u2192 lower vizSpeed \u2192 slower");
+  output.push("    Move progress points FURTHER apart \u2192 larger gap \u2192 higher vizSpeed \u2192 faster");
+  output.push("    Dense areas (lots of action) \u2192 cluster narration points (smaller gaps)");
+  output.push("    Dead zones (nothing happening) \u2192 space out narration points (larger gaps)");
   output.push("");
   output.push("  AFTER EVERY EDIT, run ONE command:");
-  output.push("    npx miriad-viz preview --from-pacing");
+  output.push("    npx miriad-viz preview --from-curation");
   output.push("");
   output.push("  This auto-runs: generate-timing \u2192 transform \u2192 preview (all three).");
-  output.push("  You edit ONE file, run ONE command, see the result.");
+  output.push("  You edit ONE file (viz-curation.json), run ONE command, see the result.");
   output.push("");
   output.push("  Then ask the human to watch the preview and give feedback.");
-  output.push(
-    "  Edit viz-curation.json or pacing.json based on feedback \u2192 run the command again \u2192 repeat."
-  );
+  output.push("  Edit viz-curation.json based on feedback \u2192 run the command again \u2192 repeat.");
   output.push("");
   output.push("  When human approves: npx miriad-viz next --timing-approved");
   const vizTimingDoc = readBundledDoc("miriad-viz-viz-timing");
@@ -534,7 +510,7 @@ function buildVizTimingApprovalError() {
   return [
     "",
     "\u2717 Cannot approve timing \u2014 no timing.json found.",
-    "  Run `npx miriad-viz preview --from-pacing` first to generate timing.json,",
+    "  Run `npx miriad-viz preview --from-curation` first to generate timing.json,",
     "  then approve with: npx miriad-viz next --timing-approved"
   ];
 }
@@ -819,28 +795,38 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
       }
       output.push("", "  Run `npx miriad-viz curate` to generate scaffolds.");
       output.push("");
-      output.push("  Remember: the scaffold gives you RAW events (activity density).");
-      output.push("  You must ADD milestone events with labels at narration-aligned timestamps.");
-      output.push("  Each narration line needs at least one labeled event in its time range.");
-      output.push(
-        "  Raw messages (messages-full.json) are your SOURCE \u2014 read them to find content."
-      );
-      output.push("  timeline-events.json is your OUTPUT \u2014 the chat pills that appear on screen.");
-      output.push("");
-      output.push("  Edit viz-curation.json for narration placement + chat pills:");
-      output.push("    \u2022 narration array \u2014 progress points with clipDuration");
-      output.push("    \u2022 pills array \u2014 progress + duration + speaker + text");
-      output.push("  Run `npx miriad-viz next` again to see updated vizSpeed and table.");
+      if (vizCuration && vizCuration.narration.length > 0) {
+        output.push("  Edit viz-curation.json for narration placement + chat pills:");
+        output.push("    \u2022 narration array \u2014 progress points with clipDuration");
+        output.push("    \u2022 pills array \u2014 progress + duration + speaker + text");
+        output.push("    \u2022 Anchor pills (auto-generated from quotes) are marked [anchor]");
+        output.push("  Run `npx miriad-viz next` again to see updated vizSpeed and table.");
+      } else {
+        output.push("  Remember: the scaffold gives you RAW events (activity density).");
+        output.push("  You must ADD milestone events with labels at narration-aligned timestamps.");
+        output.push("  Each narration line needs at least one labeled event in its time range.");
+        output.push(
+          "  Raw messages (messages-full.json) are your SOURCE \u2014 read them to find content."
+        );
+        output.push(
+          "  timeline-events.json is your OUTPUT \u2014 the chat pills that appear on screen."
+        );
+        output.push("");
+        output.push("  Edit viz-curation.json for narration placement + chat pills:");
+        output.push("    \u2022 narration array \u2014 progress points with clipDuration");
+        output.push("    \u2022 pills array \u2014 progress + duration + speaker + text");
+        output.push("  Run `npx miriad-viz next` again to see updated vizSpeed and table.");
+      }
       output.push("", "  When done: npx miriad-viz next");
       return { action: "waiting_for_edit", step, progress, output };
     }
     output.push("", "\u{1F4CB} Curate Editorial Content");
     output.push("");
     output.push("  This step generates scaffold files for editorial content:");
+    output.push("    \u2022 viz-curation.json \u2014 unified narration + pills (PRIMARY editing target)");
     output.push("    \u2022 retro-page-data.json \u2014 phases, milestones, featured quotes, narration");
     output.push("    \u2022 retro-page-quotes.json \u2014 additional standout quotes");
-    output.push("    \u2022 timeline-events.json \u2014 scaffolded from extracted data (YOU MUST EDIT THIS)");
-    output.push("    \u2022 viz-curation.json \u2014 unified narration + pills (progress-based)");
+    output.push("    \u2022 timeline-events.json \u2014 legacy/retro-page format (optional, for retro page)");
     output.push("");
     output.push("  \u26A0\uFE0F  Three concepts \u2014 understand these before editing:");
     output.push("  \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");
@@ -868,6 +854,7 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     output.push("     - Cluster narration in dense areas, space out in dead zones");
     output.push("     - ADD 15-20 milestone events with labels as pills");
     output.push('     - Each pill: { speaker: "...", text: "...", progress: N, duration: N }');
+    output.push("     - Auto-generated anchor pills are marked with anchor: true");
     output.push("     - Goal: every narration line should have related pills nearby");
     output.push("     - Anchors shown in next output \u2014 place related pills nearby");
     output.push("     - Run next again to see updated vizSpeed and table");
@@ -882,7 +869,7 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     output.push("");
     output.push("  \u2501\u2501\u2501 SCHEMA EXAMPLES (copy these as starting templates) \u2501\u2501\u2501");
     output.push("");
-    output.push("  \u{1F4C4} viz-curation.json:");
+    output.push("  \u{1F4C4} viz-curation.json (PRIMARY \u2014 edit this):");
     output.push("  ```json");
     output.push("  {");
     output.push('    "meta": { "totalClipDuration": 226.5, "totalProgress": 100,');
@@ -899,7 +886,7 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     output.push("    ],");
     output.push('    "pills": [');
     output.push('      { "speaker": "snorre", "text": "THE NEW CLIP DOES NOT HAVE SOUND",');
-    output.push('        "progress": 7.1, "duration": 2.0 },');
+    output.push('        "progress": 7.1, "duration": 2.0, "anchor": true },');
     output.push('      { "speaker": "bob", "text": "rendering now with narration scale 3.5",');
     output.push('        "progress": 8.0, "duration": 1.5 }');
     output.push("    ]");
@@ -908,8 +895,11 @@ function computeNext(progress, existingFiles, logTails, flags = {}, dataSummary,
     output.push("  \u26A0\uFE0F  narration.progress is a SINGLE number (0-100), not a range.");
     output.push("  \u26A0\uFE0F  pills are a SEPARATE top-level array, not nested under narration lines.");
     output.push("  \u26A0\uFE0F  vizSpeed is COMPUTED (gap/clipDuration) \u2014 shown in the table, not stored.");
+    output.push(
+      "  \u26A0\uFE0F  anchor: true marks auto-generated pills \u2014 add your own pills WITHOUT anchor."
+    );
     output.push("");
-    output.push("  \u{1F4C4} timeline-events.json:");
+    output.push("  \u{1F4C4} timeline-events.json (legacy \u2014 for retro page only):");
     output.push("  ```json");
     output.push("  [");
     output.push('    { "type": "message", "t": "2026-02-20T14:30:00Z", "from": "bob",');
@@ -2095,7 +2085,7 @@ async function main() {
     case "scaffold-curation": {
       const { projectDir, progress } = requireProject();
       const { ScriptFileSchema } = await import("./script-V3LKE4ZU.js");
-      const { generateVizCuration } = await import("./generate-viz-curation-KRFC2ZSB.js");
+      const { generateVizCuration } = await import("./generate-viz-curation-R6SUTONK.js");
       const { readAudioDurations } = await import("./read-audio-durations-TIGU4A7K.js");
       const { writeFileSync, mkdirSync: mkdirSync2 } = await import("fs");
       const dataDir = resolve3(projectDir, progress.project.dataDir);

package/docs/miriad-viz-pipeline.md

@@ -133,19 +133,19 @@ See [Voice Generation Guide](./miriad-viz-voice-generation.md) for the full guid
 
 See [Viz Timing Guide](./miriad-viz-viz-timing.md) for the full guide.
 
-**This is where the video's rhythm is crafted.** You scaffold a pacing file, annotate speed and pauses, and iterate with the human watching the preview.
+**This is where the video's rhythm is crafted.** You scaffold a curation file, adjust narration placement and pills, and iterate with the human watching the preview.
 
 **The iterate loop:**
 ```bash
-# 1. Scaffold pacing file (once)
-npx miriad-viz@latest scaffold-pacing
+# 1. Scaffold curation file (once)
+npx miriad-viz@latest scaffold-curation
 
-# 2. Edit pacing.json, then run ONE command:
-npx miriad-viz@latest preview --from-pacing
+# 2. Edit viz-curation.json, then run ONE command:
+npx miriad-viz@latest preview --from-curation
 # This auto-chains: generate-timing → transform → preview
 ```
 
-You edit ONE file (`pacing.json`), run ONE command, see the result. Repeat until the human approves.
+You edit ONE file (`viz-curation.json`), run ONE command, see the result. Repeat until the human approves.
 
 **Timeline padding:**
 ```bash
@@ -185,7 +185,7 @@ See [Video Export](./miriad-viz-video.md) for the full guide. Mechanical step
 | Extract (git) | `npx miriad-viz@latest extract &> extract.log &` |
 | Extract (chat) | `./extract-channel.sh ./raw-data &> chat-extract.log &` |
 | Transform | `npx miriad-viz@latest transform &> transform.log &` |
-| Preview (from pacing) | `npx miriad-viz@latest preview --from-pacing &> preview.log &` |
+| Preview (from curation) | `npx miriad-viz@latest preview --from-curation &> preview.log &` |
 | Render (video) | `pnpm render &> render.log &` |
 
 Pattern: start in background → set alarm (1-min for extract/transform, 3-min for render) → poll + report → repeat until done.

package/docs/miriad-viz-viz-timing.md

@@ -4,10 +4,11 @@
 
 Place narration on the timeline and decide how fast the viz moves. This is where the video's **pacing** is crafted — the rhythm of fast and slow, tension and release.
 
-Voice clip durations are fixed facts (from Step 3). You control **three things:**
-1. How long to pause between lines (`pauseAfter`)
-2. How fast the viz moves during a line (`vizSpeed`)
-3. How fast the viz moves during pauses (`gapVizSpeed`)
+Voice clip durations are fixed facts (from Step 3). You control **two things:**
+1. Where each narration line sits on the 0-100 progress scale (`progress`)
+2. Which chat pills appear and where (`pills` array)
+
+vizSpeed is **computed mechanically**: `gap / clipDuration`. You control it indirectly by moving progress points closer (slower) or further apart (faster).
 
 ## Files
 
@@ -15,131 +16,131 @@ Voice clip durations are fixed facts (from Step 3). You control **three things:*
 |------|-----------|-------------|
 | `data/script.json` | Read | The narrative script |
 | `audio/*.mp3` | Read | Voice clips (durations measured automatically) |
-| `data/pacing.json` | **Write** | Your pacing annotations |
-| `data/timing.json` | Generated | Engine-facing timing (generated by `generate-timing`) |
-| `output/viz-data.json` | Generated | Final viz data (generated by `transform`) |
+| `data/viz-curation.json` | **Write** | Your narration placement + chat pills |
+| `data/timing.json` | Generated | Engine-facing timing (generated by transform) |
+| `output/viz-data.json` | Generated | Final viz data (generated by transform) |
 
 ## Getting Started
 
-### 1. Scaffold the Pacing File
+### 1. Scaffold the Curation File
 
 ```bash
-npx miriad-viz@latest scaffold-pacing
+npx miriad-viz@latest scaffold-curation
 ```
 
-This reads `script.json` + measures audio clip durations → generates `pacing.json` with all defaults filled in. The output is ready to preview immediately — you only edit where you want to deviate from defaults.
+This reads `script.json` + measures audio clip durations → generates `viz-curation.json` with density-proportional defaults. The output is ready to preview immediately — you only edit where you want to deviate from defaults.
 
-### 2. Understand the Pacing File
+### 2. Understand the Curation File
 
 ```json
 {
-  "version": 1,
-  "leadInSec": 1.0,
-  "tailOutSec": 2.0,
-  "defaultPauseSec": 0.5,
-  "defaultVizSpeed": 1.0,
-  "lines": [
-    { "id": "narrator-01", "text": "February 9th. Midnight.", "clipDuration": 3.2 },
-    { "id": "narrator-02", "text": "The team had been shipping for 12 hours.",
-      "clipDuration": 4.8, "vizSpeed": 1.5, "pauseAfter": 2.0, "gapVizSpeed": 0.5,
-      "note": "montage of commits, then let it breathe" },
-    { "id": "lead-03", "text": "Adding agents is free.", "clipDuration": 2.1 },
-    { "id": "snorre-04", "text": "Full throttle.", "clipDuration": 1.4,
-      "vizSpeed": 2.0, "pauseAfter": 3.0, "gapVizSpeed": 0.3,
-      "note": "dramatic silence before crisis reveal" },
-    { "id": "narrator-05", "text": "Then everything broke.", "clipDuration": 3.6,
-      "vizSpeed": 0.5, "note": "slow down for impact" }
+  "meta": { "totalClipDuration": 226.5, "totalProgress": 100,
+    "phases": [{ "id": "bootstrap", "label": "Bootstrap", "progress": [0, 22] }] },
+  "narration": [
+    { "id": "narrator-01", "type": "narrator", "speaker": "narrator",
+      "text": "February 9th. Midnight.", "clipDuration": 3.2, "progress": 3.5 },
+    { "id": "narrator-02", "type": "narrator", "speaker": "narrator",
+      "text": "The team had been shipping for 12 hours.",
+      "clipDuration": 4.8, "progress": 8.3 },
+    { "id": "snorre-04", "type": "quote", "speaker": "snorre",
+      "text": "Full throttle.", "clipDuration": 1.4, "progress": 45.0 }
+  ],
+  "pills": [
+    { "speaker": "snorre", "text": "Full throttle.", "progress": 45.0,
+      "duration": 2.0, "anchor": true },
+    { "speaker": "bob", "text": "rendering now", "progress": 46.5,
+      "duration": 1.5 }
   ]
 }
 ```
 
-### What You Can Edit (4 fields per line)
+### What You Can Edit
+
+**Narration array** — adjust `progress` (0-100) to control where each line plays:
+- Move points **closer together** → smaller gap → lower vizSpeed → slower playback
+- Move points **further apart** → larger gap → higher vizSpeed → faster playback
 
-| Field | Default | Description |
-|-------|---------|-------------|
-| `pauseAfter` | `defaultPauseSec` | Seconds of silence after this line |
-| `vizSpeed` | `defaultVizSpeed` | Viz speed multiplier DURING this clip |
-| `gapVizSpeed` | `defaultVizSpeed` | Viz speed multiplier DURING the pause after this clip |
-| `note` | — | Your reasoning (not rendered, just for you and the human) |
+**Pills array** — add/edit/remove chat pills:
+- `speaker` — who says it
+- `text` — what appears on screen (can be fabricated)
+- `progress` — where it appears (0-100)
+- `duration` — how long it stays visible (in progress-space units)
+- Pills with `anchor: true` are auto-generated from quote lines — add your own WITHOUT anchor
 
 ### What You Must NOT Edit (read-only)
 
 | Field | Why |
 |-------|-----|
 | `id` | Matches script.json and audio filenames |
-| `text` | From script.json — shown so you can reason about content → pacing |
+| `text` (narration) | From script.json — shown so you can reason about content |
 | `clipDuration` | Measured from audio clips — this is a fact, not a choice |
+| `meta` | Computed by the lib — phases, totalClipDuration |
 
-### Global Settings
+## How vizSpeed Works
 
-| Field | Description |
-|-------|-------------|
-| `leadInSec` | Silence before the first line (intro breathing room) |
-| `tailOutSec` | Silence after the last line (outro) |
-| `defaultPauseSec` | Default pause between lines (when `pauseAfter` is absent) |
-| `defaultVizSpeed` | Default viz speed (when `vizSpeed`/`gapVizSpeed` are absent) |
-
-## How Speed Works
+vizSpeed is **computed**, not set directly:
 
 ```
-┌─────────────────┐ ┌─────┐ ┌─────────────────┐ ┌─────┐
-│ narrator-01 clip│ │ gap │ │ narrator-02 clip│ │ gap │
-│  vizSpeed: 1.0  │ │ 2.0 │ │  vizSpeed: 0.5  │ │ 1.0 │
-└─────────────────┘ └─────┘ └─────────────────┘ └─────┘
- ↑ speed DURING clip  ↑ gapVizSpeed   ↑ speed DURING clip  ↑ gapVizSpeed
-   (audio playing)    (silence/pause)   (audio playing)     (silence/pause)
+vizSpeed = gap / clipDuration
+
+gap = distance to next narration point in progress-space
 ```
 
+**Example:**
+- narrator-01 at progress 3.5, clipDuration 5.0s
+- narrator-02 at progress 8.3
+- gap = 8.3 - 3.5 = 4.8
+- vizSpeed = 4.8 / 5.0 = 0.96x
+
 **vizSpeed is a multiplier on project-time-per-second:**
 - `1.0` = default rate
 - `2.0` = viz covers project time 2× faster → **less screen time** (fast-forward)
 - `0.5` = viz covers project time 2× slower → **more screen time** (slow motion)
 
-**Key insight:** higher vizSpeed = faster = less screen time. Lower = slower = more screen time. The timing preview table (printed by `generate-timing`) shows concrete screen-time-per-line numbers so you don't have to do the math.
-
-**`gapVizSpeed` defaults to `defaultVizSpeed`, NOT to the line's `vizSpeed`.** This is intentional — a slow dramatic line (`vizSpeed: 0.5`) shouldn't automatically make its pause slow too. The pause speed is a separate creative choice.
+**Key insight:** wider gaps = higher vizSpeed = faster. Narrower gaps = lower vizSpeed = slower. The curation table (shown by `next`) displays concrete vizSpeed per line so you don't have to do the math.
 
 ## The Iterate Loop
 
-After every edit to `pacing.json`, run ONE command:
+After every edit to `viz-curation.json`, run ONE command:
 
 ```bash
-npx miriad-viz@latest preview --from-pacing
+npx miriad-viz@latest preview --from-curation
 ```
 
 This auto-chains three operations:
-1. `generate-timing` — computes `timing.json` from pacing + project time range
+1. Derives `timing.json` from viz-curation.json + project time range
 2. `transform` — produces `viz-data.json` with timing-aware narration
 3. Opens the preview viewer
 
-**You edit ONE file, run ONE command, see the result.** The three-step chain is an implementation detail.
+**You edit ONE file (viz-curation.json), run ONE command, see the result.** The three-step chain is an implementation detail.
 
-### The Timing Preview Table
+### The Curation Table
 
-`generate-timing` prints a table showing concrete screen time per line:
+`next` prints a table showing computed vizSpeed and density per line:
 
 ```
-narrator-01 (3.2s clip + 0.5s pause) → covers 2h at 1.0x = 10.4s screen
-narrator-02 (4.8s clip + 2.0s pause) → covers 4h at 0.5x = 52.8s screen ⚠️ LONG
-lead-03     (2.1s clip + 0.5s pause) → covers 1h at 1.0x = 5.2s screen
-Total: 4:32 video
+LINE             | CLIP  | PROGRESS | GAP  | vizSpeed | MSGS  | COMMITS
+narrator-01      | 5.2s  | @ 3.5    | 3.6  | 0.69x    | 182   | 12
+snorre-01        | 3.2s  | @ 7.1    | 4.9  | 1.53x    | 47    | 3
+narrator-02      | 4.1s  | @ 12.0   | 16.0 | 3.90x    | 0     | 0  ← dead zone
 ```
 
 Use this to catch problems **before watching the preview:**
-- `⚠️ LONG` — this segment takes a lot of screen time. Is that intentional?
-- Very short segments — will the audience have time to read the narration?
-- Total duration — does the video length feel right for the content?
+- `← dead zone` — zero activity in this region. Space out narration (larger gaps) to skip through it.
+- High vizSpeed (> 3x) — the viz is moving very fast here. Is that intentional?
+- Low vizSpeed (< 0.5x) — the viz is very slow. Enough content to fill the screen time?
+- Anchors — quote-type lines auto-generate pills. Place related pills nearby.
 
-## Speed Reasoning — Creative Choice, Not Formula
+## Pacing Reasoning — Creative Choice, Not Formula
 
-The `next` output shows **event density** per script line — how many PRs, commits, and messages happened during each line's time range. Use this as input, not as a rule:
+The `next` output shows **event density** per narration line — how many messages and commits happened in each line's progress window. Use this as input, not as a rule:
 
 **Guidelines (not rules):**
-- **Dead time** (few events, nothing happening) → high `gapVizSpeed` (skip through it)
-- **Intense action** (many PRs, message bursts) → normal or low `vizSpeed` (let the viewer see the frenzy)
-- **Dramatic reveal** → big `pauseAfter` (tension before the next line)
-- **Emotional moment** → low `vizSpeed` (slow down for impact)
-- **Montage** → high `vizSpeed` during clip (time-lapse of activity)
+- **Dead zones** (zero events) → space out narration points (larger gaps, higher vizSpeed)
+- **Dense areas** (many events) → cluster narration points (smaller gaps, lower vizSpeed)
+- **Dramatic reveal** → place narration points close together before the reveal (slow buildup)
+- **Emotional moment** → narrow gap (low vizSpeed, slow down for impact)
+- **Montage** → wide gap (high vizSpeed, time-lapse of activity)
 
 **Trust your creative judgment.** The data tells you what happened. You and the human decide how it should feel. A quiet period might deserve slow pacing if it's the calm before the storm. A busy period might deserve fast pacing if it's routine work.
 
@@ -148,23 +149,15 @@ The `next` output shows **event density** per script line — how many PRs, comm
 Share the preview link and watch together. The human evaluates:
 
 - **Does the pacing feel right?** Too fast? Too slow? Uneven?
-- **Do the pauses land?** Is there enough silence before dramatic moments?
+- **Do the pills land?** Are they readable? Too many? Too few?
 - **Does the narration sync with the visuals?** When the narrator says "then everything broke," is the viz showing the crisis?
 - **Is the total duration right?** Too long for the content? Too short to absorb?
 
 Common feedback and how to respond:
-- *"Slow down the middle section"* → lower `vizSpeed` on those lines
-- *"The pause before the crisis isn't dramatic enough"* → increase `pauseAfter`
-- *"Skip through the overnight period faster"* → increase `gapVizSpeed` on lines covering that range
-- *"The whole thing is too long"* → increase `defaultVizSpeed` globally, or increase specific `gapVizSpeed` values
-
-## Validation
-
-`generate-timing` validates the pacing file and warns about:
-- Total wall-clock time < 30s or > 30min (unusual for typical scripts)
-- Viz coverage < 50% (narration only covers half the timeline — intentional?)
-- Negative values (invalid)
-- Missing line IDs (script.json has lines not in pacing.json)
+- *"Slow down the middle section"* → move narration points closer together in that region
+- *"Skip through the overnight period faster"* → space out narration points in that region
+- *"Add a pill when Bob says that"* → add a pill to the pills array at the right progress point
+- *"The whole thing is too long"* → space out narration points globally (wider gaps)
 
 ## What You Cannot Control (v1)
 
@@ -172,12 +165,12 @@ Be honest with the human about these boundaries:
 
 | Cannot control | Why | Future |
 |---|---|---|
-| **Visual emphasis** — can't zoom into an agent, hide a band, or highlight a node at a specific moment | Viz is a pure function of progress. No per-moment visual overrides. | Camera directives in pacing file |
-| **Cross-fades between lines** — every line cuts to the next, no overlap or blend | Audio clips are discrete files, no mixing in v1 | Crossfade field on PacingLine |
-| **What data appears** — can't add/remove agents, PRs, or events from the viz | Data comes from extraction, not pacing | Selective data filtering |
+| **Visual emphasis** — can't zoom into an agent, hide a band, or highlight a node at a specific moment | Viz is a pure function of progress. No per-moment visual overrides. | Camera directives |
+| **Cross-fades between lines** — every line cuts to the next, no overlap or blend | Audio clips are discrete files, no mixing in v1 | Crossfade support |
+| **What data appears** — can't add/remove agents, PRs, or events from the viz | Data comes from extraction, not curation | Selective data filtering |
 | **Layout or visual style** — can't change colors, positions, or rendering | Renderer is fixed, driven by viz-data | Style overrides per phase |
 
-You control **pacing** (how fast time moves) and **audio** (what you hear). The visual content is determined by the extracted data and the renderer. This is by design — it keeps the pacing file simple and the iterate loop fast.
+You control **pacing** (via narration placement) and **pills** (what text appears on screen). The visual content is determined by the extracted data and the renderer. This is by design — it keeps the curation file simple and the iterate loop fast.
 
 ## When to Stop for Human Review
 
@@ -187,4 +180,4 @@ You control **pacing** (how fast time moves) and **audio** (what you hear). The
 npx miriad-viz@latest next --timing-approved
 ```
 
-**Timing is now locked.** Step 5 (Sound Design) adds SFX and music on top of the locked timing. Changes to pacing after this point require going back to this step.
+**Timing is now locked.** Step 5 (Sound Design) adds SFX and music on top of the locked timing. Changes to curation after this point require going back to this step.

package/docs/miriad-viz-voice-generation.md

@@ -21,7 +21,7 @@ echo $ELEVENLABS_API_KEY
 
 **If missing:** Tell the human: "ElevenLabs API key not configured. To add narration, set `ELEVENLABS_API_KEY` in your environment. Without it, I can skip voices — the viz will use estimated durations based on text length, and the video will be silent."
 
-**No API key is not a blocker.** The pipeline continues without audio — `scaffold-pacing` estimates clip durations from text length, and the viz renders with text-only narration. Audio can be added later.
+**No API key is not a blocker.** The pipeline continues without audio — `scaffold-curation` estimates clip durations from text length, and the viz renders with text-only narration. Audio can be added later.
 
 ## The Filename Convention
 
@@ -35,7 +35,7 @@ script.json line:  { "id": "lead-03", ... }
 audio file:        audio/lead-03.mp3
 ```
 
-`scaffold-pacing` (Step 4) looks up clips by this convention. Wrong filenames = missing audio = broken pacing.
+`scaffold-curation` (Step 4) looks up clips by this convention. Wrong filenames = missing audio = broken timing.
 
 ## Workflow
 
@@ -103,7 +103,7 @@ After generating all clips, measure their durations:
 ffprobe -v quiet -show_entries format=duration -of csv=p=0 audio/narrator-01.mp3
 ```
 
-You don't need to record these manually — `scaffold-pacing` (Step 4) reads them automatically from the audio files.
+You don't need to record these manually — `scaffold-curation` (Step 4) reads them automatically from the audio files.
 
 ### 5. Human Review
 

package/package.json

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