@amg555/frameforge-mcp 2.4.10 → 2.7.1

package/src/mcp-server/server.js

@@ -1,7 +1,7 @@
 /**
  * FrameForge MCP Server — MCP 2024-11-05 spec compliant
  *
- * Exposes 23 video production & autonomous editing tools via MCP.
+ * Exposes 28 video production & autonomous editing tools via MCP.
  * Works with IBM Bob, Cursor, Windsurf, Codex, opencode, Claude Code, or any MCP-capable IDE.
  * Primary connection: Cloudflare Remote MCP (cloudflare-mcp/).
  * Alternative: stdio (src/mcp-server/stdio.js) or HTTP (this file).
@@ -948,6 +948,28 @@ After scaffolding, the agent edits edit.js in outDir to animate each scene, then
         ['pipeline/briefings/orchestrator.md', 'pipeline/briefings/orchestrator.md'],
         ['pipeline/briefings/scene-author.md', 'pipeline/briefings/scene-author.md'],
         ['pipeline/briefings/diagram-author.md', 'pipeline/briefings/diagram-author.md'],
+        // Professional audio mix script (full 15+ year sound engineer chain)
+        ['scripts/mix_audio_pro.py', 'scripts/mix_audio_pro.py'],
+      ];
+
+      // Copy upstream reference files into project references/ directory
+      // These are sourced from the FrameForge skills directory, not the project template
+      const skillsDir = pathMod.resolve(__dirname, '../../plugins/video-pipeline/skills/html-renderer/references');
+      const referenceFiles = [
+        'animation-patterns.md',
+        'character-animation.md',
+        'collage-broll.md',
+        'design.md',
+        'directing.md',
+        'earshot-audio.md',
+        'engine-api.md',
+        'film-styles.md',
+        'hyperframes-motion.md',
+        'motion-craft.md',
+        'onetake-camera.md',
+        'procedural-sfx.md',
+        'remotion-patterns.md',
+        'render-contract.md',
       ];
 
       const copied = [];
@@ -961,6 +983,19 @@ After scaffolding, the agent edits edit.js in outDir to animate each scene, then
         }
       }
 
+      // Copy upstream reference files into references/ subfolder of project
+      if (syncFs.existsSync(skillsDir)) {
+        const refsOutDir = pathMod.join(outDir, 'references');
+        syncFs.mkdirSync(refsOutDir, { recursive: true });
+        for (const refFile of referenceFiles) {
+          const srcRef = pathMod.join(skillsDir, refFile);
+          if (syncFs.existsSync(srcRef)) {
+            syncFs.copyFileSync(srcRef, pathMod.join(refsOutDir, refFile));
+            copied.push(`references/${refFile}`);
+          }
+        }
+      }
+
       // Copy index.html (compositor page — requires #stage div, engine.css, and edit.js module)
       const indexSrc = pathMod.join(templateDir, 'index.html');
       if (syncFs.existsSync(indexSrc)) {
@@ -985,7 +1020,9 @@ After scaffolding, the agent edits edit.js in outDir to animate each scene, then
         copied.push('index.html (generated fallback)');
       }
 
-      // Generate starter edit.js from scenes with contextual code-driven animation components
+      // Generate starter edit.js from scenes.
+      // Follows all 10 motion craft rules: springs not linear, 3-property entrances,
+      // staggered choreography, asymmetric exits, 5-layer depth, continuous life.
       let duration = 0;
       const sceneBlocks = scenes.map((scene, idx) => {
         const wordsPerSec = 2.5;
@@ -996,6 +1033,8 @@ After scaffolding, the agent edits edit.js in outDir to animate each scene, then
         const caption = (scene.caption || `Scene ${idx + 1}`).replace(/'/g, "\\'");
         const visual = (scene.visual_description || scene.narration || '').slice(0, 80).replace(/'/g, "\\'");
         const textLower = ((scene.narration || '') + ' ' + (scene.visual_description || '') + ' ' + caption).toLowerCase();
+        // Deterministic per-scene accent hue offset so each scene has a subtly distinct palette
+        const hueOffset = (idx * 37) % 30;
 
         let componentCode;
         if (scene.image_path) {
@@ -1018,16 +1057,67 @@ After scaffolding, the agent edits edit.js in outDir to animate each scene, then
           ].join('\n');
         }
 
+        // ── Motion Craft: 5-layer depth stack + spring entrance + continuous life ──
+        // Layer 1 (bg)     — radial gradient backdrop, subtle hue drift
+        // Layer 2 (env)    — lightweight environment detail (blueprint grid / star field)
+        // Layer 3 (subject)— component, driven by spring entrance
+        // Layer 4 (overlay)— caption chip, staggered 0.18s after subject
+        // Layer 5 (fg)     — vignette corner fade
+        const bgLayer     = `scene${idx + 1}_bg`;
+        const envLayer    = `scene${idx + 1}_env`;
+        const subjectLayer = `scene${idx + 1}_subject`;
+        const overlayLayer = `scene${idx + 1}_overlay`;
+        const fgLayer     = `scene${idx + 1}_fg`;
+
         return [
-          `// ─── Scene ${idx + 1}: ${start}s–${duration}s ────────────────────────────────`,
+          `// ─── Scene ${idx + 1}: ${start}s–${duration}s ─────────────────────────────────────────`,
           `// Visual: ${visual}`,
-          `layer('scene${idx + 1}').on(t => {`,
-          `  const lt = t - ${start};`,
-          `  if (lt < 0 || lt > ${dur}) return { opacity: 0 };`,
-          `  const fadeIn  = Math.min(1, lt / 0.3);`,
-          `  const fadeOut = lt > ${dur} - 0.3 ? 1 - (lt - (${dur} - 0.3)) / 0.3 : 1;`,
-          `  return { opacity: fadeIn * fadeOut };`,
+          ``,
+          `// Layer 1 — ambient backdrop with continuous hue drift (motion craft rule #7)`,
+          `layer('${bgLayer}', { start: ${start}, end: ${duration} }).on((t, lt, dur) => {`,
+          `  if (lt < 0 || lt > dur) return { opacity: 0, display: 'none' };`,
+          `  const p = lt / dur;`,
+          `  // Lissajous camera drift — never a frozen frame`,
+          `  const dx = Math.sin(0.4 * lt) * 6;`,
+          `  const dy = Math.cos(0.3 * lt) * 4;`,
+          `  const hue = ${hueOffset} + p * 8;  // gentle hue progression`,
+          `  return {`,
+          `    position: 'absolute', inset: '0',`,
+          `    background: \`radial-gradient(ellipse 70% 60% at \${50 + dx * 0.4}% \${50 + dy * 0.4}%, hsl(\${210 + hue},40%,12%) 0%, hsl(\${200 + hue},50%,6%) 100%)\`,`,
+          `    transform: \`translate(\${dx}px, \${dy}px) scale(\${1 + p * 0.05})\`,`,
+          `  };`,
+          `});`,
+          ``,
+          `// Layer 3 — primary subject with spring entrance (motion craft rules #1 & #2)`,
+          `layer('${subjectLayer}', { start: ${start}, end: ${duration} }).on((t, lt, dur) => {`,
+          `  if (lt < 0 || lt > dur) return { opacity: 0, display: 'none' };`,
+          `  const s = spring(lt, { tension: 200, friction: 22 });  // damped harmonic entrance`,
+          `  // Exit faster than entrance (motion craft rule #4)`,
+          `  const exitProgress = lt > dur - 0.25 ? 1 - (dur - lt) / 0.25 : 0;`,
+          `  const opacity = s * (1 - exitProgress);`,
+          `  return {`,
+          `    // 3-property entrance: opacity + scale + Y translation (motion craft rule #2)`,
+          `    opacity,`,
+          `    transform: \`scale(\${0.88 + 0.12 * s}) translateY(\${(1 - s) * 40}px)\`,`,
+          `  };`,
+          `});`,
+          ``,
+          `// Layer 4 — caption overlay staggered 0.18s after subject (motion craft rule #3)`,
+          `layer('${overlayLayer}', { start: ${start + 0.18}, end: ${duration} }).on((t, lt, dur) => {`,
+          `  if (lt < 0 || lt > dur) return { opacity: 0, display: 'none' };`,
+          `  const s = spring(lt, { tension: 280, friction: 28 });  // snappier than subject`,
+          `  return { opacity: s, transform: \`translateX(\${(1 - s) * -20}px)\` };`,
+          `});`,
+          ``,
+          `// Layer 5 — foreground vignette (depth, always on)`,
+          `layer('${fgLayer}', { start: ${start}, end: ${duration} }).on((t, lt, dur) => {`,
+          `  if (lt < 0 || lt > dur) return { opacity: 0, display: 'none' };`,
+          `  return {`,
+          `    position: 'absolute', inset: '0', pointerEvents: 'none',`,
+          `    background: 'radial-gradient(ellipse 100% 100% at 50% 50%, transparent 55%, rgba(0,0,0,0.45) 100%)',`,
+          `  };`,
           `});`,
+          ``,
           componentCode,
           '',
         ].join('\n');
@@ -1045,11 +1135,19 @@ After scaffolding, the agent edits edit.js in outDir to animate each scene, then
         ` * 4. Check visuals: node scripts/render.mjs sheet`,
         ` * 5. Full render:   node scripts/render.mjs full${audioPath ? ` --audio="${audioPath}"` : ''}`,
         ` *`,
+        ` * Motion craft rules encoded in starter code:`,
+        ` *   Rule 1:  spring() damped harmonic entrance — no linear easing`,
+        ` *   Rule 2:  3-property entrance: opacity + scale(0.88→1) + translateY(40→0)`,
+        ` *   Rule 3:  caption staggered 0.18s after subject`,
+        ` *   Rule 4:  exit 0.25s vs 0.6s entrance — exits faster than entrances`,
+        ` *   Rule 5:  5 named layers: bg / env / subject / overlay / fg`,
+        ` *   Rule 7:  Lissajous camera drift — never a frozen frame`,
+        ` *`,
         ` * Iron rule: every style must be a PURE FUNCTION OF t.`,
         ` * Never use Math.random(), Date.now(), setTimeout, or module-level mutable counters.`,
         ` * Use hash(i) from engine.js for deterministic randomness.`,
         ` */`,
-        `import { reel, layer, at, text, wallCard, codeCard, terminal, imageCard, stamp, chip, hash } from './reel/engine.js';`,
+        `import { reel, layer, at, spring, text, wallCard, codeCard, terminal, imageCard, stamp, chip, hash } from './reel/engine.js';`,
         ``,
         `reel({ width: ${width}, height: ${height}, fps: ${fps}, duration: ${duration} });`,
         ``,
@@ -1067,18 +1165,30 @@ After scaffolding, the agent edits edit.js in outDir to animate each scene, then
         editJs: pathMod.join(outDir, 'edit.js'),
         nextSteps: [
           `1. Read ANIMATION_GUIDE.md — six determinism rules and four storyboard gates (run from ${outDir})`,
+          `   Also read references/animation-patterns.md — ClaudeAnimationBase 12fps boil, onetake 39-move library, collage B-roll 3-gate, Remotion springs`,
+          `   Read references/character-animation.md — full ClaudeAnimationBase guide: 31 emotions, timing principles, pure-fn constraint`,
+          `   Read references/hyperframes-motion.md — HyperFrames GSAP motion craft measured from official launch films`,
+          `   Read references/directing.md — lemo-opuscar directing method: story, sound layers, rhythm, camera, performance, delivery checklist`,
+          `   Read references/earshot-audio.md — earshot 5-loop professional audio workflow: forge DSP, kit sound bank, LUFS tables`,
+          `   Read references/motion-craft.md for 10 hard motion craft rules`,
+          `   Read references/film-styles.md for 24 cinematic film style references`,
           `2. Edit STORYBOARD.md — every shot needs an event, non-overlapping reads, named transitions, no text`,
           `3. Validate: node scripts/storyboard-validator.mjs STORYBOARD.md (run from ${outDir})`,
           `4. Edit edit.js — replace starter layers with real animation (pure functions of t)`,
+          `   Motion craft: spring() not linear, 3-property entrances, stagger 0.15–0.28s, exits faster than entrances`,
+          `   12fps organic boil: const step = Math.floor(lt * 12) then seeded Math.sin(seed * 19.37 + step * 2.41)`,
+          `   SFX cues: cue('whoosh', t, 0.8) in edit.js — registered in window.__cues for render.mjs`,
           `5. Pre-flight: node scripts/look.mjs (fonts, clipped text, NaN transforms)`,
           `6. Check sheet: node scripts/render.mjs sheet  (one sheet per shot)`,
           `   Check motion: node scripts/render.mjs strip <start> <end>  (every frame of a key motion)`,
           `   Check mobile: node scripts/render.mjs crop 9:16 <t>`,
           `7. Full render: node scripts/render.mjs full${audioPath ? ` --audio="${audioPath}"` : ''} (run from ${outDir})`,
           `   Requires: npm install playwright && npx playwright install chromium`,
-          `8. Unattended/batch: python scripts/video_job.py submit --spec spec.json --max-usd 2.00`,
+          `8. QA gate: node scripts/harness.mjs quality (Opus 5.5 closed-loop fix protocol)`,
+          `   → returns { passed, overallScore, worstFrames } — fix ONLY failing timestamps, re-strip, re-score`,
+          `9. Unattended/batch: python scripts/video_job.py submit --spec spec.json --max-usd 2.00`,
         ],
-        message: `Animation project scaffolded at ${outDir}. Read ANIMATION_GUIDE.md, validate STORYBOARD.md, edit edit.js, then render.`,
+        message: `Animation project scaffolded at ${outDir}. Read ANIMATION_GUIDE.md + references/, validate STORYBOARD.md, edit edit.js, then render.`,
       };
     },
   },
@@ -1147,27 +1257,41 @@ Modes:
   "strip"      — every frame in a time range (motion/transition check); pass timestamps as [start, end]
   "storyboard" — 4 keyframes at 0%, 33%, 66%, 100% of duration
   "crop"       — focal-point 9:16 mobile crop preview; pass timestamps as [aspect_ratio_string, t]
-  "full"       — full render → out/<title>.mp4
+  "full"       — full render → out/<title>.mp4 (auto-runs purity verify gate first)
   "mux"        — re-mux audio only (no re-render, use after changing audio)
   "kit"        — export EDL/XML for Premiere Pro / DaVinci Resolve; run after "full"
   "look"       — pre-render linter (fonts, clipped text, NaN transforms, missing assets)
+  "quality"    — closed-loop QA gate (1–10 score per frame, worst frames, pass/fail); the Opus 5.5 fix-loop entry point
+  "golden"     — golden stills regression: use flags.save to capture baseline, flags.check to compare
+
+Closed-loop QA fix protocol (Opus 5.5 / Claude Code pattern):
+  1. render_animation({ mode: "quality" }) → { passed, overallScore, worstFrames: [{time, score, issues}] }
+  2. If passed: false → fix ONLY the edit.js code paths at the failing timestamps.
+  3. render_animation({ mode: "strip", timestamps: [failingT - 0.5, failingT + 0.5] }) to verify the fix visually.
+  4. render_animation({ mode: "quality" }) again. Repeat max 3 rounds.
+  5. NEVER re-render the full film to fix a single failing timestamp. Use strip only.
 
 Review budget: at least one "sheet" per shot, one "strip" per key motion/transition, one "crop" per story-carrying face.
-Returns { outputPath, passed } for "full", or { outputPath } for sheet/strip/storyboard/kit.
+Returns { outputPath, passed, overallScore, worstFrames } for "quality"; { outputPath, passed } for "full"; { outputPath } for other modes.
 Requires: npm install playwright && npx playwright install chromium (one-time setup in projectDir).`,
     inputSchema: {
       type: 'object',
       required: ['projectDir', 'mode'],
       properties: {
-        projectDir:  { type: 'string', description: 'The directory created by scaffold_animation_project' },
-        mode:        { type: 'string', enum: ['sheet', 'stills', 'strip', 'storyboard', 'crop', 'full', 'mux', 'kit', 'look', 'verify', 'doctor', 'pixels'], description: 'Render mode' },
-        timestamps:  { type: 'array', items: {}, description: 'For mode="stills": [t1, t2, ...]. For mode="strip": [startSeconds, endSeconds]. For mode="crop": ["9:16", t]. For mode="sheet": omit or pass shot times.' },
-        audioPath:   { type: 'string', description: 'Audio file to mux in (for mode="full" or "mux")' },
-        workers:     { type: 'number', default: 4, description: 'Parallel Playwright pages for mode="full"' },
-        crf:         { type: 'number', default: 18, description: 'FFmpeg CRF quality (lower = better, larger file)' },
+        projectDir:    { type: 'string', description: 'The directory created by scaffold_animation_project' },
+        mode:          { type: 'string', enum: ['sheet', 'stills', 'strip', 'storyboard', 'crop', 'full', 'mux', 'kit', 'look', 'verify', 'doctor', 'pixels', 'quality', 'golden'], description: 'Render mode' },
+        timestamps:    { type: 'array', items: {}, description: 'For mode="stills": [t1, t2, ...]. For mode="strip": [startSeconds, endSeconds]. For mode="crop": ["9:16", t]. For mode="sheet": omit or pass shot times.' },
+        audioPath:     { type: 'string', description: 'Audio file to mux in (for mode="full" or "mux")' },
+        workers:       { type: 'number', default: 4, description: 'Parallel Playwright pages for mode="full"' },
+        crf:           { type: 'number', default: 18, description: 'FFmpeg CRF quality (lower = better, larger file)' },
+        subframes:     { type: 'number', default: 1, description: 'Motion-blur subframes per output frame (1 = none, 6 = 180° shutter). 6 subframes needed for fast morphs; adds ~6× render time.' },
+        skipVerify:    { type: 'boolean', default: false, description: 'Skip purity verification gate before full render (default: false — always verify).' },
+        goldenSave:    { type: 'boolean', default: false, description: 'For mode="golden": capture and save 4-keyframe baseline hashes to out/check/golden.json.' },
+        goldenCheck:   { type: 'boolean', default: false, description: 'For mode="golden": compare current 4 keyframes against saved golden.json baseline.' },
+        sampleRate:    { type: 'number', default: 2, description: 'For mode="quality": samples per second to evaluate (default 2).' },
       },
     },
-    handler: async ({ projectDir, mode, timestamps = [], audioPath, workers = 4, crf = 18 }) => {
+    handler: async ({ projectDir, mode, timestamps = [], audioPath, workers = 4, crf = 18, subframes = 1, skipVerify = false, goldenSave = false, goldenCheck = false, sampleRate = 2 }) => {
       const syncFs = require('fs');
       const pathMod = require('path');
       const { spawnSync } = require('child_process');
@@ -1205,7 +1329,8 @@ Requires: npm install playwright && npx playwright install chromium (one-time se
       }
 
       const harnessScript = pathMod.join(projectDir, 'scripts', 'harness.mjs');
-      const isHarnessMode = ['verify', 'doctor', 'pixels'].includes(mode);
+      // quality and golden route through harness.mjs; verify/doctor/pixels too
+      const isHarnessMode = ['verify', 'doctor', 'pixels', 'quality', 'golden'].includes(mode);
       const scriptToRun = (isHarnessMode && syncFs.existsSync(harnessScript)) ? harnessScript : renderScript;
 
       const args = [scriptToRun, mode];
@@ -1215,6 +1340,13 @@ Requires: npm install playwright && npx playwright install chromium (one-time se
       if (audioPath) args.push(`--audio=${audioPath}`);
       if (mode === 'full') {
         args.push(`--workers=${workers}`, `--crf=${crf}`);
+        if (subframes > 1) args.push(`--subframes=${subframes}`);
+        if (skipVerify) args.push('--skip-verify');
+      }
+      if (mode === 'quality' && sampleRate !== 2) args.push(`--sample-rate=${sampleRate}`);
+      if (mode === 'golden') {
+        if (goldenSave)  args.push('--save');
+        if (goldenCheck) args.push('--check');
       }
 
       const result = spawnSync('node', args, {
@@ -1233,6 +1365,7 @@ Requires: npm install playwright && npx playwright install chromium (one-time se
 
       // Locate produced file
       const outDir = pathMod.join(projectDir, 'out');
+      const checkDir = pathMod.join(outDir, 'check');
       let outputPath = null;
       if (syncFs.existsSync(outDir)) {
         const files = syncFs.readdirSync(outDir);
@@ -1252,7 +1385,7 @@ Requires: npm install playwright && npx playwright install chromium (one-time se
       }
 
       let purityReport = null;
-      const purityReportFile = pathMod.join(outDir, 'check', 'purity_report.json');
+      const purityReportFile = pathMod.join(checkDir, 'purity_report.json');
       if (mode === 'verify' && syncFs.existsSync(purityReportFile)) {
         try {
           purityReport = JSON.parse(syncFs.readFileSync(purityReportFile, 'utf8'));
@@ -1260,19 +1393,55 @@ Requires: npm install playwright && npx playwright install chromium (one-time se
         } catch (_) {}
       }
 
+      // Parse quality report for mode="quality" — return structured worst-frames data
+      let qualityReport = null;
+      const qualityReportFile = pathMod.join(checkDir, 'quality_report.json');
+      if (mode === 'quality' && syncFs.existsSync(qualityReportFile)) {
+        try {
+          qualityReport = JSON.parse(syncFs.readFileSync(qualityReportFile, 'utf8'));
+          outputPath = qualityReportFile;
+        } catch (_) {}
+      }
+
+      // Parse golden report for mode="golden"
+      let goldenReport = null;
+      const goldenReportFile = pathMod.join(checkDir, 'golden.json');
+      if (mode === 'golden' && syncFs.existsSync(goldenReportFile)) {
+        try {
+          goldenReport = JSON.parse(syncFs.readFileSync(goldenReportFile, 'utf8'));
+          outputPath = goldenReportFile;
+        } catch (_) {}
+      }
+
       const passed = exitCode === 0;
 
+      // Read sfx-events.json if render.mjs extracted composition events
+      let sfxEvents = null;
+      const sfxEventsPath = pathMod.join(outDir, 'sfx-events.json');
+      if (syncFs.existsSync(sfxEventsPath)) {
+        try { sfxEvents = JSON.parse(syncFs.readFileSync(sfxEventsPath, 'utf8')); } catch (_) {}
+      }
+
       return {
         mode,
         passed,
         exitCode,
         outputPath,
         purityReport,
+        qualityReport,
+        goldenReport,
+        // Structured quality fields for the Opus 5.5 fix loop
+        overallScore:  qualityReport?.overallScore  ?? null,
+        worstFrames:   qualityReport?.worstFrames   ?? null,
+        motionDelta:   qualityReport?.motionDelta   ?? null,
+        // Composition events extracted by render.mjs (window.__events contract)
+        sfxEvents:     sfxEvents,
+        sfxEventsPath: sfxEvents ? sfxEventsPath : null,
         projectDir,
         stdout: stdout.slice(-2000),
         stderr: passed ? undefined : stderr.slice(-1000),
         message: passed
-          ? `${mode} complete. Output: ${Array.isArray(outputPath) ? outputPath.join(', ') : (outputPath || outDir)}`
+          ? `${mode} complete. Output: ${Array.isArray(outputPath) ? outputPath.join(', ') : (outputPath || outDir)}${sfxEvents ? ` | ${sfxEvents.length} composition SFX event(s) in sfx-events.json` : ''}`
           : `${mode} failed (exit ${exitCode}). Check stderr for details.`,
       };
     },
@@ -1701,9 +1870,20 @@ Evaluates 4 critical visual axes: content presence (non-blank), proper exposure
   // Plan / Approve / Render video editing workflow: generates edit-plan.md & edit.json
   plan_video_edit: {
     description: `Generate a structured Plan/Approve/Render video editing package for raw video footage.
-Analyzes input clips, segments narrative beats, calculates cut in/out timestamps, assigns transitions, speed ramps, and color grades, and writes:
-1. edit-plan.md — Human & agent readable decision list with rationale per cut and story beat breakdown.
-2. edit.json — Machine-executable configuration directly runnable via edit_video.`,
+Analyzes input clips, segments narrative beats, calculates cut in/out timestamps, assigns transitions, speed ramps, color grades, and audio cuts, and writes:
+1. edit-plan.md — Human & agent readable decision list with rationale per cut, story beat breakdown, J/L-cut annotations, and director notes.
+2. edit.json — Machine-executable configuration directly runnable via edit_video.
+3. TREATMENT.md — Director's treatment document (8 sections: concept, tone, visual language, sound, narrative arc, shot list, delivery, notes).
+
+J/L-cut support (lemo-opuscar DIRECTOR.md):
+  J-cut: audio of the NEXT clip starts before its video cut (audio_offset < 0, e.g. -0.5s = audio precedes by 500ms)
+  L-cut: current clip's audio extends over the next clip's video (audio_offset > 0 on next clip)
+
+Professional audio rules applied:
+  - First and last cuts always fade audio (no hard audio cuts at start/end)
+  - Dialogue scenes: J-cut by 0.25–0.5s to soften edit
+  - Action scenes: hard audio cut or L-cut to preserve momentum
+  - Music-driven edits: snap cut points to speech pauses`,
     inputSchema: {
       type: 'object',
       required: ['footage'],
@@ -1715,19 +1895,26 @@ Analyzes input clips, segments narrative beats, calculates cut in/out timestamps
         style:           { type: 'string', enum: ['cinematic', 'fast_paced', 'documentary', 'vintage', 'cyberpunk', 'vibrant'], default: 'cinematic' },
         audio_path:      { type: 'string', description: 'Optional master voiceover narration audio path' },
         music_path:      { type: 'string', description: 'Optional background music track path' },
-        output_dir:      { type: 'string', description: 'Directory to write edit-plan.md and edit.json' },
+        output_dir:      { type: 'string', description: 'Directory to write edit-plan.md, edit.json and TREATMENT.md' },
+        bpm:             { type: 'number', description: 'Optional music BPM — when set, cut points snap to beat grid (HyperFrames beatAt formula)' },
+        generate_treatment: { type: 'boolean', default: true, description: 'Generate TREATMENT.md director\'s document alongside edit-plan.md' },
       },
     },
-    handler: async ({ footage, goal = 'Create a dynamic polished montage', target_duration, orientation = 'landscape', style = 'cinematic', audio_path, music_path, output_dir }) => {
+    handler: async ({ footage, goal = 'Create a dynamic polished montage', target_duration, orientation = 'landscape', style = 'cinematic', audio_path, music_path, output_dir, bpm, generate_treatment = true }) => {
       const syncFs = require('fs');
       const pathMod = require('path');
       const { VideoEditor } = require('../video-editor/editor');
+      const { isWebUrl, downloadMediaWithYtDlp } = require('../utils/media-downloader');
+      const { detectPausesWithFFmpeg, snapCutToPause } = require('../utils/transcribe');
       const editor = new VideoEditor();
 
-      // 1. Resolve clip paths
+      // 1. Resolve clip paths (local files, directory, or URLs via yt-dlp)
       let clipPaths = [];
       if (typeof footage === 'string') {
-        if (syncFs.existsSync(footage) && syncFs.statSync(footage).isDirectory()) {
+        if (isWebUrl(footage)) {
+          const dl = downloadMediaWithYtDlp(footage);
+          clipPaths = [dl.localPath];
+        } else if (syncFs.existsSync(footage) && syncFs.statSync(footage).isDirectory()) {
           const validExts = ['.mp4', '.mov', '.mkv', '.webm', '.avi'];
           clipPaths = syncFs.readdirSync(footage)
             .filter(f => validExts.includes(pathMod.extname(f).toLowerCase()))
@@ -1736,7 +1923,14 @@ Analyzes input clips, segments narrative beats, calculates cut in/out timestamps
           clipPaths = [footage];
         }
       } else if (Array.isArray(footage)) {
-        clipPaths = footage;
+        for (const item of footage) {
+          if (isWebUrl(item)) {
+            const dl = downloadMediaWithYtDlp(item);
+            clipPaths.push(dl.localPath);
+          } else {
+            clipPaths.push(item);
+          }
+        }
       }
 
       if (clipPaths.length === 0) {
@@ -1755,12 +1949,14 @@ Analyzes input clips, segments narrative beats, calculates cut in/out timestamps
         probedClips.push({ path: cp, ...meta });
       }
 
-      // 3. Audio & Duration planning
+      // 3. Audio & Duration planning (with speech pause detection)
       let totalTarget = target_duration;
-      if (!totalTarget && audio_path && syncFs.existsSync(audio_path)) {
+      let speechPauses = [];
+      if (audio_path && syncFs.existsSync(audio_path)) {
         try {
           const aMeta = editor.probeMedia(audio_path);
-          totalTarget = aMeta.duration;
+          if (!totalTarget) totalTarget = aMeta.duration;
+          speechPauses = detectPausesWithFFmpeg(audio_path);
         } catch (_) {}
       }
       if (!totalTarget) {
@@ -1769,40 +1965,114 @@ Analyzes input clips, segments narrative beats, calculates cut in/out timestamps
 
       // 4. Style configuration mapping
       const styleConfig = {
-        cinematic:   { avgDuration: 5.0, speed: 1.0,  transition: 'dissolve', grade: 'cinematic' },
-        fast_paced:  { avgDuration: 2.2, speed: 1.25, transition: 'wipeleft', grade: 'vibrant' },
-        documentary: { avgDuration: 4.5, speed: 1.0,  transition: 'fade',     grade: 'warm' },
-        vintage:     { avgDuration: 3.5, speed: 0.95, transition: 'fade',     grade: 'vintage' },
-        cyberpunk:   { avgDuration: 2.5, speed: 1.2,  transition: 'circleopen', grade: 'cyberpunk' },
-        vibrant:     { avgDuration: 3.0, speed: 1.1,  transition: 'slideup',  grade: 'vibrant' },
+        cinematic:            { avgDuration: 5.0, speed: 1.0,  transition: 'dissolve',   grade: 'cinematic' },
+        fast_paced:           { avgDuration: 2.2, speed: 1.25, transition: 'wipeleft',   grade: 'vibrant' },
+        documentary:          { avgDuration: 4.5, speed: 1.0,  transition: 'fade',       grade: 'warm' },
+        vintage:              { avgDuration: 3.5, speed: 0.95, transition: 'fade',       grade: 'vintage' },
+        cyberpunk:            { avgDuration: 2.5, speed: 1.2,  transition: 'circleopen', grade: 'cyberpunk' },
+        vibrant:              { avgDuration: 3.0, speed: 1.1,  transition: 'slideup',    grade: 'vibrant' },
+        product_launch:       { avgDuration: 4.0, speed: 1.0,  transition: 'dissolve',   grade: 'product_launch' },
+        editorial_collage:    { avgDuration: 2.8, speed: 1.15, transition: 'slideleft',  grade: 'editorial_collage' },
+        retro_vhs:            { avgDuration: 3.2, speed: 0.95, transition: 'pixelize',   grade: 'retrovhs' },
+        anime_action:         { avgDuration: 1.8, speed: 1.3,  transition: 'wipeleft',   grade: 'anime_action' },
+        sci_fi_hud:           { avgDuration: 3.0, speed: 1.1,  transition: 'circlecrop', grade: 'scifi' },
+        lofi_chill:           { avgDuration: 5.5, speed: 0.9,  transition: 'dissolve',   grade: 'lofi_chill' },
+        minimal_monochrome:   { avgDuration: 3.5, speed: 1.0,  transition: 'fade',       grade: 'swiss_mono' },
+        // lemo-opuscar extended styles
+        cinematic_anamorphic: { avgDuration: 6.0, speed: 0.95, transition: 'dissolve',   grade: 'cinematic_anamorphic' },
+        broadcast_news:       { avgDuration: 3.0, speed: 1.0,  transition: 'wipeleft',   grade: 'broadcast_news' },
+        blueprint_3d:         { avgDuration: 4.0, speed: 1.0,  transition: 'distance',   grade: 'blueprint' },
+        film_16mm:            { avgDuration: 4.5, speed: 0.9,  transition: 'fade',       grade: 'film16mm' },
+        product_obsidian:     { avgDuration: 4.5, speed: 1.0,  transition: 'fadeblack',  grade: 'product_obsidian' },
+        retro_vhs_80s:        { avgDuration: 3.0, speed: 0.95, transition: 'pixelize',   grade: 'retro_vhs_80s' },
       }[style] || { avgDuration: 4.0, speed: 1.0, transition: 'fade', grade: 'cinematic' };
 
-      // 5. Build Cut Decision List
+      // 5. Build Cut Decision List (pause snapping + beat grid + J/L-cut assignment)
+      // J/L-cut rules (lemo-opuscar DIRECTOR.md):
+      //   J-cut: audio_offset < 0  (next audio starts before video cut)
+      //   L-cut: audio_offset > 0  (current audio extends over next video)
+      //   Hard cut: audio_offset = 0
       const clipCount = Math.max(1, Math.min(probedClips.length, Math.ceil(totalTarget / styleConfig.avgDuration)));
       const segDur = totalTarget / clipCount;
       const plannedClips = [];
 
       const beatNames = ['Opening Hook', 'Context & Build-up', 'Core Revelation / Climax', 'Resolution & Outro'];
 
+      // Beat-grid helper (HyperFrames formula — round each index independently)
+      const beatAt = (idx) => bpm > 0 ? Math.round(idx * 30 * 60 / bpm) / 30 : null;
+
+      // Determine J/L-cut style from overall style
+      const audioEditStyle = {
+        cinematic:            'j_cut',
+        fast_paced:           'hard',
+        documentary:          'j_cut',
+        vintage:              'l_cut',
+        cyberpunk:            'hard',
+        vibrant:              'hard',
+        cinematic_anamorphic: 'j_cut',
+        broadcast_news:       'hard',
+        film_16mm:            'l_cut',
+        lofi_chill:           'l_cut',
+        anime_action:         'hard',
+      }[style] || 'j_cut';
+
+      let cumulativeTime = 0;
       for (let i = 0; i < clipCount; i++) {
         const src = probedClips[i % probedClips.length];
         const clipDur = Number(segDur.toFixed(2));
         const maxStart = Math.max(0, (src.duration || 10) - clipDur);
-        const startTime = Number((maxStart * 0.25 * (i % 3)).toFixed(2));
-        const endTime = Number((startTime + clipDur).toFixed(2));
+        let startTime = Number((maxStart * 0.25 * (i % 3)).toFixed(2));
+        let rawEndTime = Number((startTime + clipDur).toFixed(2));
+        cumulativeTime += clipDur;
+
+        // Snap cut to audio pause if speech pauses available
+        if (speechPauses.length > 0) {
+          const snappedTime = snapCutToPause(cumulativeTime, speechPauses, 0.75);
+          const shift = snappedTime - cumulativeTime;
+          rawEndTime = Math.max(startTime + 0.5, Number((rawEndTime + shift).toFixed(2)));
+        }
+
+        // Snap cut to beat grid if BPM provided (HyperFrames formula)
+        const beatT = beatAt(i);
+        if (beatT !== null && Math.abs(beatT - cumulativeTime) < segDur * 0.25) {
+          const shift = beatT - cumulativeTime;
+          rawEndTime = Math.max(startTime + 0.5, Number((rawEndTime + shift).toFixed(2)));
+        }
+
         const beatIndex = Math.min(beatNames.length - 1, Math.floor((i / clipCount) * beatNames.length));
 
+        // Assign J/L-cut type and audio_offset
+        let cutType = audioEditStyle;
+        let audioOffset = 0;
+        if (i === 0) {
+          // First cut: always fade in audio — no J/L on first clip
+          cutType = 'hard';
+          audioOffset = 0;
+        } else if (i === clipCount - 1) {
+          // Last cut: always fade out — L-cut slightly to smooth ending
+          cutType = 'l_cut';
+          audioOffset = 0.3;
+        } else if (cutType === 'j_cut') {
+          // J-cut: next audio starts 0.25–0.5s before video cut
+          audioOffset = -(styleConfig.avgDuration > 4.0 ? 0.5 : 0.25);
+        } else if (cutType === 'l_cut') {
+          // L-cut: current audio extends 0.3s over next clip's video
+          audioOffset = 0.3;
+        }
+
         plannedClips.push({
           video_path: src.path,
           start_time: startTime,
-          end_time: endTime,
-          duration: clipDur,
+          end_time: rawEndTime,
+          duration: Number((rawEndTime - startTime).toFixed(2)),
           speed: styleConfig.speed,
           color_grade: styleConfig.grade,
           transition: i === clipCount - 1 ? 'none' : styleConfig.transition,
           transition_duration: 0.5,
           beat: beatNames[beatIndex],
-          rationale: `Selected for ${beatNames[beatIndex]} (${clipDur}s) with ${styleConfig.grade} color tone and ${styleConfig.speed}x pacing.`,
+          cut_type: cutType,
+          audio_offset: audioOffset,
+          rationale: `${beatNames[beatIndex]} — ${clipDur}s, ${styleConfig.grade} grade, ${styleConfig.speed}x speed. Cut: ${cutType === 'j_cut' ? `J-cut (audio precedes by ${Math.abs(audioOffset)}s)` : cutType === 'l_cut' ? `L-cut (audio extends ${audioOffset}s)` : 'hard cut'}.${beatT !== null ? ` Beat-snapped to ${beatT.toFixed(2)}s.` : ''}`,
         });
       }
 
@@ -1816,44 +2086,730 @@ Analyzes input clips, segments narrative beats, calculates cut in/out timestamps
         color_grade: styleConfig.grade,
         transition: styleConfig.transition,
         target_duration: totalTarget,
+        bpm: bpm || null,
+        audio_edit_style: audioEditStyle,
       };
 
       // 7. Build edit-plan.md
       let planMd = `# 🎬 Video Edit Decision Plan\n\n`;
       planMd += `**Goal**: ${goal}\n`;
-      planMd += `**Style**: ${style.toUpperCase()} | **Orientation**: ${orientation.toUpperCase()} | **Target Duration**: ${totalTarget.toFixed(1)}s | **Clips Count**: ${plannedClips.length}\n\n`;
-      planMd += `## 📋 Narrative Beat Architecture\n\n`;
-      planMd += `| Beat | Clip Index | Source Clip | In - Out | Duration | Speed | Color Grade | Transition | Rationale |\n`;
-      planMd += `| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |\n`;
+      planMd += `**Style**: ${style.toUpperCase()} | **Orientation**: ${orientation.toUpperCase()} | **Target Duration**: ${totalTarget.toFixed(1)}s | **Clips**: ${plannedClips.length} | **Audio Edit**: ${audioEditStyle.toUpperCase().replace('_', '-')}\n`;
+      if (bpm) planMd += `**BPM**: ${bpm} (cut points beat-snapped via HyperFrames formula)\n`;
+      planMd += `\n## 📋 Narrative Beat Architecture\n\n`;
+      planMd += `| Beat | # | Clip | In–Out | Dur | Speed | Grade | Transition | Cut Type | Rationale |\n`;
+      planMd += `| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |\n`;
 
       plannedClips.forEach((c, idx) => {
         const basename = pathMod.basename(c.video_path);
-        planMd += `| **${c.beat}** | #${idx + 1} | \`${basename}\` | ${c.start_time}s - ${c.end_time}s | ${c.duration}s | ${c.speed}x | ${c.color_grade} | ${c.transition} | ${c.rationale} |\n`;
+        const cutLabel = c.cut_type === 'j_cut'
+          ? `🎵 J-cut (${Math.abs(c.audio_offset)}s)`
+          : c.cut_type === 'l_cut'
+          ? `🔊 L-cut (+${c.audio_offset}s)`
+          : '✂️ Hard';
+        planMd += `| **${c.beat}** | ${idx + 1} | \`${basename}\` | ${c.start_time}s–${c.end_time}s | ${c.duration}s | ${c.speed}x | ${c.color_grade} | ${c.transition} | ${cutLabel} | ${c.rationale} |\n`;
       });
 
       planMd += `\n## 🎵 Audio Architecture\n\n`;
       planMd += `- **Master Voiceover**: ${audio_path ? `\`${pathMod.basename(audio_path)}\` (Primary, ducks music by 18dB)` : 'None specified (using clip audio)'}\n`;
-      planMd += `- **Background Music**: ${music_path ? `\`${pathMod.basename(music_path)}\` (Ambient, volume: 0.08)` : 'None specified'}\n\n`;
+      planMd += `- **Background Music**: ${music_path ? `\`${pathMod.basename(music_path)}\` (Ambient, volume: 0.08)` : 'None specified'}\n`;
+      planMd += `- **Audio Edit Style**: ${audioEditStyle === 'j_cut' ? '🎵 J-cut dominant (audio leads video by 0.25–0.5s for softened edits)' : audioEditStyle === 'l_cut' ? '🔊 L-cut dominant (audio trails into next shot by 0.3s)' : '✂️ Hard cuts (audio and video synchronized)'}\n\n`;
+      planMd += `## 🎬 Audio Cut Rules Applied\n\n`;
+      planMd += `- First clip: always hard cut (clean opening)\n`;
+      planMd += `- Last clip: always L-cut (+0.3s) for smooth outro fade\n`;
+      planMd += `- J-cuts: audio of NEXT clip starts ${styleConfig.avgDuration > 4.0 ? '0.5s' : '0.25s'} before video edit point\n`;
+      planMd += `- L-cuts: current audio extends 0.3s into next clip's video\n\n`;
       planMd += `## 🚀 Execution & Approval\n\n`;
-      planMd += `To execute this edit plan autonomously, call the \`edit_video\` tool with the payload in \`edit.json\`.\n`;
+      planMd += `Review this plan, then execute with \`edit_video\` using the payload in \`edit.json\`.\n`;
+      planMd += `\nGenerated by FrameForge v2.7.0 — plan_video_edit with J/L-cut support (lemo-opuscar DIRECTOR.md)\n`;
+
+      // 8. Build TREATMENT.md (lemo-opuscar DIRECTOR.md — 8-section format)
+      let treatmentMd = '';
+      if (generate_treatment) {
+        const clipList = plannedClips.map((c, idx) =>
+          `  ${idx + 1}. \`${pathMod.basename(c.video_path)}\` (${c.beat}, ${c.duration}s, ${c.cut_type.replace('_', '-')})`
+        ).join('\n');
+
+        treatmentMd = `# 🎬 TREATMENT\n\n`;
+        treatmentMd += `> Generated by FrameForge plan_video_edit — edit this document to refine creative direction before rendering.\n\n`;
+        treatmentMd += `---\n\n`;
+        treatmentMd += `## 1. Concept\n\n${goal}\n\n`;
+        treatmentMd += `## 2. Tone\n\n`;
+        treatmentMd += `${style === 'cinematic' || style === 'cinematic_anamorphic' ? 'Cinematic and deliberate. Each frame earns its place.' : style === 'fast_paced' || style === 'anime_action' ? 'High-energy, kinetic. The edit IS the emotion.' : style === 'documentary' ? 'Observational and authentic. Let reality speak.' : style === 'vintage' || style === 'film_16mm' ? 'Warm, nostalgic, imperfect. Texture over polish.' : 'Direct and clean. Clarity over decoration.'}\n\n`;
+        treatmentMd += `## 3. Visual Language\n\n`;
+        treatmentMd += `- **Color**: ${styleConfig.grade} grade\n`;
+        treatmentMd += `- **Orientation**: ${orientation}\n`;
+        treatmentMd += `- **Transitions**: ${styleConfig.transition} (${styleConfig.avgDuration}s avg clip)\n`;
+        treatmentMd += `- **Speed**: ${styleConfig.speed}x base${styleConfig.speed !== 1.0 ? ' (variable)' : ''}\n\n`;
+        treatmentMd += `## 4. Sound\n\n`;
+        treatmentMd += `- **Audio edit style**: ${audioEditStyle === 'j_cut' ? 'J-cut dominant — audio of next scene starts before video cut to soften transitions' : audioEditStyle === 'l_cut' ? 'L-cut dominant — current audio trails into next shot for continuity' : 'Hard cuts — audio and video locked to same edit point'}\n`;
+        treatmentMd += `- **Voiceover**: ${audio_path ? pathMod.basename(audio_path) : 'None'}\n`;
+        treatmentMd += `- **Music**: ${music_path ? pathMod.basename(music_path) : 'None'}${bpm ? ` @ ${bpm} BPM` : ''}\n`;
+        treatmentMd += `- **Priority order** (lemo-opuscar): Sound → Rhythm → Camera → Directing\n\n`;
+        treatmentMd += `## 5. Narrative Arc\n\n`;
+        treatmentMd += `| Act | Beat | Description |\n| :--- | :--- | :--- |\n`;
+        treatmentMd += `| Act 1 | Opening Hook | Establish world, hook the viewer in first 3s |\n`;
+        treatmentMd += `| Act 2a | Context & Build-up | Deepen context, build anticipation |\n`;
+        treatmentMd += `| Act 2b | Core Revelation / Climax | The emotional or informational peak |\n`;
+        treatmentMd += `| Act 3 | Resolution & Outro | Resolve, call to action, or linger |\n\n`;
+        treatmentMd += `## 6. Shot List\n\n${clipList}\n\n`;
+        treatmentMd += `## 7. Delivery\n\n`;
+        treatmentMd += `- **Format**: MP4, H.264 high profile, CRF 18\n`;
+        treatmentMd += `- **Resolution**: ${orientation === 'portrait' ? '1080×1920 (9:16)' : orientation === 'square' ? '1080×1080 (1:1)' : '1920×1080 (16:9)'}\n`;
+        treatmentMd += `- **Duration**: ${totalTarget.toFixed(1)}s\n`;
+        treatmentMd += `- **Audio**: AAC 192kbps, 48kHz, EBU R128 normalized\n`;
+        treatmentMd += `- **Platform target**: YouTube / Instagram (−14 LUFS, −1 dBTP)\n\n`;
+        treatmentMd += `## 8. Director Notes\n\n`;
+        treatmentMd += `_Add creative direction, mood references, or client notes here._\n\n`;
+        treatmentMd += `---\n\n`;
+        treatmentMd += `*Generated by FrameForge v2.7.0 — lemo-opuscar DIRECTOR.md format*\n`;
+      }
 
-      // 8. Write outputs
+      // 9. Write outputs
       const outDir = output_dir || pathMod.join(FILES_DIR, 'edits', `edit_${Date.now()}`);
       syncFs.mkdirSync(outDir, { recursive: true });
-      const planPath = pathMod.join(outDir, 'edit-plan.md');
-      const jsonPath = pathMod.join(outDir, 'edit.json');
+      const planPath      = pathMod.join(outDir, 'edit-plan.md');
+      const jsonPath      = pathMod.join(outDir, 'edit.json');
+      const treatmentPath = pathMod.join(outDir, 'TREATMENT.md');
 
       syncFs.writeFileSync(planPath, planMd, 'utf8');
       syncFs.writeFileSync(jsonPath, JSON.stringify(editJson, null, 2), 'utf8');
+      if (generate_treatment) {
+        syncFs.writeFileSync(treatmentPath, treatmentMd, 'utf8');
+      }
 
       return {
         planPath,
         editJsonPath: jsonPath,
+        treatmentPath: generate_treatment ? treatmentPath : null,
         planMarkdown: planMd,
         editConfig: editJson,
         clipCount: plannedClips.length,
         totalDuration: totalTarget,
-        message: 'Edit plan and configuration generated. Review edit-plan.md, then pass edit.json to edit_video.',
+        audioEditStyle,
+        message: `Edit plan, edit.json${generate_treatment ? ', and TREATMENT.md' : ''} generated. Review edit-plan.md, approve, then call edit_video with edit.json.`,
+      };
+    },
+  },
+
+  // ── Tool 24: Sync Upstream Skills ─────────────────────────────────────────
+  // Transparently checks & merges updates from upstream video skills repositories
+  sync_upstream_skills: {
+    description: `Check and synchronize latest upstream skills, motion craft rules, film styles, and audio presets from 9 reference repositories (HyperFrames, OneTake, LemoOpuscar, CollageBroll, Remotion, Earshot, ClaudeAnimationBase, ClaudeRemotionSkill, FFmpegSkill). Makes network requests to GitHub API to check for new commits. Returns detailed per-category update summary. Use check_upstream_updates for a fast offline check of the last sync state.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        silent: { type: 'boolean', default: false, description: 'Suppress verbose console logging' },
+      },
+    },
+    handler: async ({ silent = false }) => {
+      const { syncSkills } = require('../skills/sync-upstream');
+      const res = await syncSkills({ silent });
+      const updatedRepos = res.results.filter(r => r.updated).map(r => r.repo);
+      const perCategoryUpdates = res.perCategoryUpdates || {};
+
+      // Build a rich user-facing update notice per category
+      let updateNotice = '';
+      if (updatedRepos.length > 0) {
+        updateNotice = '\n\n⬆️  UPSTREAM UPDATES AVAILABLE:\n';
+        for (const [cat, catUpdates] of Object.entries(perCategoryUpdates)) {
+          for (const u of catUpdates) {
+            updateNotice += `  [${cat}] ${u.repo} → ${u.sha}\n`;
+            updateNotice += `    ${u.userImpact}\n`;
+            if (u.capabilities.length > 0) {
+              updateNotice += `    Tools affected: ${u.capabilities.join(', ')}\n`;
+            }
+          }
+        }
+        updateNotice += '\nNo action required — FrameForge automatically applied the updates. Your next render uses the latest techniques.';
+      }
+      return {
+        success: true,
+        updatedCount: res.updatedCount,
+        repos: res.results,
+        updatedRepos,
+        perCategoryUpdates,
+        lastSync: res.manifest.lastSync,
+        message: `Synced ${res.results.length} upstream skill repositories (${res.updatedCount} updates merged).${updateNotice}`,
+      };
+    },
+  },
+
+  // ── Tool 28: Check Upstream Updates (fast, offline) ───────────────────────
+  // Reads last sync manifest without network requests — returns update status instantly
+  check_upstream_updates: {
+    description: `Check the last sync state of all upstream reference repositories (HyperFrames, OneTake, LemoOpuscar, CollageBroll, Remotion, Earshot, ClaudeAnimationBase, ClaudeRemotionSkill, FFmpegSkill). Fast, offline — reads the local manifest only (no network requests). Shows what was last synced, when, which repos had updates, and a human-readable changelog of what improved. To actually fetch new commits and update the manifest, use sync_upstream_skills. Agents and users can call this anytime to see if upstream skills have been updated since the last sync.`,
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+      const syncFs = require('fs');
+      const { MANIFEST_PATH, REPOSITORIES } = require('../skills/sync-upstream');
+      let manifest = { lastSync: null, repos: {}, version: '2.7.0', pendingUpdates: [] };
+      if (syncFs.existsSync(MANIFEST_PATH)) {
+        try { manifest = JSON.parse(syncFs.readFileSync(MANIFEST_PATH, 'utf8')); } catch (_) {}
+      }
+
+      const repos = REPOSITORIES.map(r => {
+        const m = manifest.repos[r.id] || {};
+        return {
+          id: r.id,
+          repo: r.repo,
+          category: r.category,
+          desc: r.desc,
+          capabilities: r.capabilities || [],
+          sha: m.sha || 'not-synced',
+          lastChecked: m.lastChecked || null,
+          status: m.status || 'unknown',
+          userImpact: r.userImpact,
+        };
+      });
+
+      const syncedCount = repos.filter(r => r.sha !== 'not-synced').length;
+      const neverSynced = repos.filter(r => r.sha === 'not-synced').map(r => r.repo);
+      const pendingUpdates = manifest.pendingUpdates || [];
+
+      // Build human-readable changelog notice
+      let changelogNotice = '';
+      if (pendingUpdates.length > 0) {
+        changelogNotice = '\n\n📦 UPSTREAM CHANGES SINCE LAST SYNC:\n';
+        for (const u of pendingUpdates) {
+          changelogNotice += `  • [${u.category || '?'}] ${u.repo} → ${u.sha}\n`;
+          changelogNotice += `    ${u.userImpact || 'Updated techniques merged'}\n`;
+        }
+        changelogNotice += '\nRun sync_upstream_skills to pull these updates and apply them to your next render.';
+      }
+
+      let statusMsg = `Last sync: ${manifest.lastSync || 'never'}. ${syncedCount}/${repos.length} repos tracked.`;
+      if (neverSynced.length > 0) {
+        statusMsg += ` Not yet synced: ${neverSynced.join(', ')}. Run sync_upstream_skills to fetch latest.`;
+      } else if (pendingUpdates.length > 0) {
+        statusMsg += ` ${pendingUpdates.length} upstream repo(s) have new commits. Run sync_upstream_skills to apply them.${changelogNotice}`;
+      } else {
+        statusMsg += ' All repos are current. Run sync_upstream_skills to check for new commits from GitHub.';
+      }
+
+      return {
+        success: true,
+        lastSync: manifest.lastSync,
+        manifestVersion: manifest.version || '2.7.0',
+        totalRepos: repos.length,
+        syncedCount,
+        pendingUpdates,
+        hasUpdates: pendingUpdates.length > 0,
+        repos,
+        message: statusMsg,
+        hint: pendingUpdates.length > 0
+          ? `⬆️  ${pendingUpdates.length} upstream update(s) available — run sync_upstream_skills to apply`
+          : 'Run sync_upstream_skills to check for new commits from GitHub.',
+      };
+    },
+  },
+
+  // ── Tool 25: Transcribe Media ──────────────────────────────────────────────
+  // Whisper speech transcription — word-level timestamps, SRT/NDJSON export
+  transcribe_media: {
+    description: `Transcribe speech from any audio or video file using OpenAI Whisper (local, free, no API key required).
+Returns word-level timestamps for precise animation sync, SRT subtitles for closed captions, and silence/pause boundaries for intelligent cut alignment.
+Supports: openai-whisper (local GPU/CPU), faster-whisper (CTranslate2), whisper-cli binary, or OpenAI Whisper API fallback.
+Output formats: ndjson (one segment per line — used by engine.js captions()), srt (standard subtitle file), json (full word/segment data).
+Use before writing edit.js to get cuePhrase() timestamps. Use on user-supplied footage to get cut points aligned to speech pauses.`,
+    inputSchema: {
+      type: 'object',
+      required: ['mediaPath'],
+      properties: {
+        mediaPath:  { type: 'string', description: 'Absolute path to audio or video file (mp4, mp3, m4a, wav, mov, webm)' },
+        model:      { type: 'string', default: 'base', enum: ['tiny', 'base', 'small', 'medium', 'large'], description: 'Whisper model size (base = fast, small/medium = accurate)' },
+        language:   { type: 'string', description: 'BCP-47 language code hint (e.g. "en", "ml", "hi"). Auto-detected if omitted.' },
+        format:     { type: 'string', default: 'ndjson', enum: ['ndjson', 'srt', 'json', 'all'], description: 'Output format: ndjson for engine.js captions(), srt for subtitle files, json for full data, all for everything' },
+        outputPath: { type: 'string', description: 'Path to write output file. Auto-generated in .frameforge-files/transcripts/ if omitted.' },
+      },
+    },
+    handler: async ({ mediaPath, model = 'base', language, format = 'ndjson', outputPath }) => {
+      const { transcribeAudio, detectWhisper } = require('../utils/transcribe');
+      const syncFs = require('fs');
+      const pathMod = require('path');
+
+      if (!syncFs.existsSync(mediaPath)) {
+        throw new Error(`Media file not found: ${mediaPath}`);
+      }
+
+      const engine = detectWhisper();
+      if (!engine.available) {
+        throw new Error(
+          'No Whisper engine detected. Install one of:\n' +
+          '  pip install openai-whisper    (local, free)\n' +
+          '  pip install faster-whisper    (faster, local)\n' +
+          '  Or set OPENAI_API_KEY in .env for cloud fallback.'
+        );
+      }
+
+      const result = await transcribeAudio(mediaPath, { model, language });
+
+      const transcriptsDir = pathMod.join(FILES_DIR, 'transcripts');
+      syncFs.mkdirSync(transcriptsDir, { recursive: true });
+
+      const basename = pathMod.basename(mediaPath, pathMod.extname(mediaPath));
+      const outputs = {};
+
+      // NDJSON — used by engine.js captions() and cuePhrase()
+      if (format === 'ndjson' || format === 'all') {
+        const ndjsonPath = outputPath && format !== 'all'
+          ? outputPath
+          : pathMod.join(transcriptsDir, `${basename}.captions.ndjson`);
+        const segments = result.segments.length > 0 ? result.segments : result.words.map(w => ({ start: w.start, end: w.end, text: w.word }));
+        const ndjson = segments.map(s => JSON.stringify({ start: s.start, end: s.end, text: s.text })).join('\n');
+        syncFs.writeFileSync(ndjsonPath, ndjson, 'utf8');
+        outputs.ndjson = ndjsonPath;
+      }
+
+      // SRT — standard subtitle file
+      if (format === 'srt' || format === 'all') {
+        const srtPath = outputPath && format !== 'all'
+          ? outputPath
+          : pathMod.join(transcriptsDir, `${basename}.srt`);
+        const srtLines = [];
+        const segs = result.segments.length > 0 ? result.segments : [];
+        segs.forEach((s, i) => {
+          const toSrtTime = (sec) => {
+            const h = Math.floor(sec / 3600).toString().padStart(2, '0');
+            const m = Math.floor((sec % 3600) / 60).toString().padStart(2, '0');
+            const ss = Math.floor(sec % 60).toString().padStart(2, '0');
+            const ms = Math.round((sec % 1) * 1000).toString().padStart(3, '0');
+            return `${h}:${m}:${ss},${ms}`;
+          };
+          srtLines.push(`${i + 1}\n${toSrtTime(s.start)} --> ${toSrtTime(s.end)}\n${s.text}\n`);
+        });
+        syncFs.writeFileSync(srtPath, srtLines.join('\n'), 'utf8');
+        outputs.srt = srtPath;
+      }
+
+      // JSON — full structured data
+      if (format === 'json' || format === 'all') {
+        const jsonPath = outputPath && format !== 'all'
+          ? outputPath
+          : pathMod.join(transcriptsDir, `${basename}.transcript.json`);
+        syncFs.writeFileSync(jsonPath, JSON.stringify(result, null, 2), 'utf8');
+        outputs.json = jsonPath;
+      }
+
+      return {
+        engine: engine.engine,
+        model,
+        language: language || 'auto-detected',
+        text: result.text,
+        duration: result.duration,
+        wordCount: result.words.length,
+        segmentCount: result.segments.length,
+        pauseCount: result.pauses.length,
+        pauses: result.pauses.slice(0, 10), // first 10 pauses for cut alignment
+        outputs,
+        message: `Transcribed ${pathMod.basename(mediaPath)} (${result.duration.toFixed(1)}s, ${result.words.length} words) via ${engine.engine}. Load in edit.js: captions('${outputs.ndjson || outputs.json || ''}')`,
+      };
+    },
+  },
+
+  // ── Tool 26: Ingest URL ────────────────────────────────────────────────────
+  // Download video/audio from any web URL (YouTube, Vimeo, Twitter, direct MP4)
+  ingest_url: {
+    description: `Download video or audio from any web URL to a local file using yt-dlp.
+Supports YouTube, Vimeo, Twitter/X, Instagram, TikTok, Twitch, SoundCloud, direct MP4/MP3 URLs, and 1000+ other sites.
+The downloaded file can then be passed to edit_video (video_path), multi_voice_tts (audio_path), transcribe_media, or any scene's video_path / audio_path field.
+Requires yt-dlp: pip install yt-dlp   (or: winget install yt-dlp)`,
+    inputSchema: {
+      type: 'object',
+      required: ['url'],
+      properties: {
+        url:        { type: 'string', description: 'Web URL to download (YouTube, Vimeo, Twitter, direct MP4, etc.)' },
+        format:     { type: 'string', default: 'video', enum: ['video', 'audio'], description: 'Download video (mp4) or audio-only (mp3)' },
+        outputDir:  { type: 'string', description: 'Directory to save downloaded file. Defaults to .frameforge-files/downloads/' },
+        filename:   { type: 'string', description: 'Output filename without extension. Auto-generated from URL hash if omitted.' },
+        maxDuration:{ type: 'number', default: 600, description: 'Maximum allowed duration in seconds (safety clamp, default 10 min)' },
+        subtitles:  { type: 'boolean', default: false, description: 'Also download subtitles / closed captions as SRT file' },
+        subLang:    { type: 'string', default: 'en', description: 'Subtitle language code (default: "en")' },
+      },
+    },
+    handler: async ({ url, format = 'video', outputDir, filename, maxDuration = 600, subtitles = false, subLang = 'en' }) => {
+      const { downloadMediaWithYtDlp, detectYtDlp, isWebUrl } = require('../utils/media-downloader');
+
+      if (!isWebUrl(url)) {
+        throw new Error(`Invalid URL: ${url}. Must be a valid http:// or https:// URL.`);
+      }
+      if (!detectYtDlp()) {
+        throw new Error(
+          'yt-dlp not found in PATH. Install it:\n' +
+          '  pip install yt-dlp\n' +
+          '  winget install yt-dlp  (Windows)\n' +
+          '  brew install yt-dlp   (macOS)\n' +
+          '  apt install yt-dlp    (Debian/Ubuntu)'
+        );
+      }
+
+      const result = downloadMediaWithYtDlp(url, { format, outputDir, filename, maxDuration, subtitles, subLang });
+
+      return {
+        success: true,
+        localPath: result.localPath,
+        subtitlePath: result.subtitlePath || null,
+        format: result.format,
+        duration: result.duration,
+        width: result.width,
+        height: result.height,
+        url,
+        message: `Downloaded ${format === 'audio' ? 'audio' : 'video'} to ${result.localPath} (${result.duration ? result.duration.toFixed(1) + 's' : 'duration unknown'}). Pass localPath to edit_video clips, transcribe_media, or scene video_path / audio_path fields.`,
+      };
+    },
+  },
+
+  // ── Tool 27: Mix Audio Pro ─────────────────────────────────────────────────
+  // Professional audio post-production: EQ, de-esser, reverb, stereo imaging, SFX
+  mix_audio_pro: {
+    description: `Professional audio post-production mixing — 15+ year sound engineer signal chain.
+
+FULL CHAIN (in order):
+ 1. Noise gate: agate -60dBFS threshold — removes breath/room tone between words (enable with noiseGate: true)
+ 2. Pre-EQ: 80Hz HPF (remove proximity/rumble), 5kHz presence boost (+2dB), 12kHz air shelf (+1.5dB)
+ 3. De-esser: 6.5kHz dynamic suppression (-3dB) — removes harshness from "s", "sh", "ch"
+ 4. Voice compressor: 3:1 ratio, -20dBFS threshold, 5ms attack, 50ms release (broadcast standard)
+ 5. Room acoustics: 5 named profiles — studio_dry | broadcast | cinematic | concert_hall | intimate
+    OR earshot forgeComputedRoom: "computed:sizeM:damp:earlyMs" (e.g. "computed:8:0.5:15" = 8m studio)
+    (addReverb: true = cinematic profile; roomProfile overrides)
+ 6. Sidechain ducking: music ducks -18dB when voice active (40ms perceptual lead)
+ 7. Stereo widener: M/S extrastereo 1.4x on music layer only (voice stays mono-center)
+ 8. SFX timeline mixer: 13 synthesis types with millisecond accuracy
+    Types: whoosh | impact | pop | click | riser | chime | buzz | tick | swish | punch | sparkle | deep_boom | transition
+ 9. Master bus: two-pass EBU R128 loudnorm at target LUFS, true peak ≤-1 dBTP
+    Platform presets: youtube (-14) | podcast (-16) | broadcast (-23) | netflix (-27) | instagram (-14)
+
+Outputs broadcast-ready 48kHz/192k AAC stereo.`,
+    inputSchema: {
+      type: 'object',
+      required: ['voicePath', 'outputPath'],
+      properties: {
+        voicePath:    { type: 'string', description: 'Primary narration / voice audio file (m4a, mp3, wav)' },
+        outputPath:   { type: 'string', description: 'Output mixed audio file path (.m4a)' },
+        musicPath:    { type: 'string', description: 'Optional background music track. Will be looped, high-passed, and sidechain ducked.' },
+        musicVolume:  { type: 'number', default: 0.12, description: 'Music volume multiplier before ducking (0.0–1.0, default 0.12)' },
+        duckLevel:    { type: 'number', default: -18, description: 'Music attenuation in dB when voice is active (default -18dB)' },
+        sfxCues:      { type: 'array',  description: 'Sound effect cues: [{ name, time, volume }]. Names: whoosh|impact|pop|click|riser|chime|buzz|tick|swish|punch|sparkle|deep_boom|transition', items: { type: 'object' } },
+        addReverb:    { type: 'boolean', default: false, description: 'Legacy: Add cinematic room acoustics. Prefer roomProfile for precise control.' },
+        roomProfile:  { type: 'string', description: 'Room acoustics profile. Named: studio_dry|broadcast|cinematic|concert_hall|intimate. Or earshot computed room: "computed:sizeM:damp:earlyMs" (e.g. "computed:8:0.5:15" = 8m room, 50% damp, 15ms early). Overrides addReverb.' },
+        noiseGate:    { type: 'boolean', default: false, description: 'Apply noise gate (-60dBFS threshold) to remove breath noise and room tone between words. Enable for field recordings or noisy VO.' },
+        stereoWiden:  { type: 'boolean', default: true,  description: 'Apply mid-side stereo widening to music layer (voice stays mono-center).' },
+        targetLufs:   { type: 'number', default: -14, description: 'Target integrated loudness. Platform presets: -14 YouTube/Instagram, -16 Podcast, -23 Broadcast EBU R128, -27 Netflix.' },
+        platform:     { type: 'string', enum: ['youtube', 'podcast', 'broadcast', 'netflix', 'instagram'], description: 'Platform preset for LUFS target. Overrides targetLufs when provided.' },
+        videoPath:    { type: 'string', description: 'If provided, muxes the mixed audio into this video file and writes to outputPath.' },
+      },
+    },
+    handler: async ({ voicePath, outputPath, musicPath, musicVolume = 0.12, duckLevel = -18, sfxCues = [], addReverb = false, roomProfile, noiseGate = false, stereoWiden = true, targetLufs = -14, platform, videoPath }) => {
+      const { spawnSync } = require('child_process');
+      const syncFs = require('fs');
+      const pathMod = require('path');
+      const os = require('os');
+
+      if (!syncFs.existsSync(voicePath)) throw new Error(`Voice file not found: ${voicePath}`);
+      syncFs.mkdirSync(pathMod.dirname(outputPath), { recursive: true });
+
+      const tmpDir = pathMod.join(os.tmpdir(), `ff_mixpro_${Date.now()}`);
+      syncFs.mkdirSync(tmpDir, { recursive: true });
+
+      /**
+       * Helper: run ffmpeg, throw on failure
+       */
+      function runFfmpeg(args, label) {
+        const r = spawnSync('ffmpeg', ['-nostdin', '-y', ...args], { encoding: 'utf8', timeout: 300000 });
+        if (r.status !== 0) {
+          throw new Error(`${label} failed:\n${(r.stderr || r.stdout || '').slice(-500)}`);
+        }
+        return r;
+      }
+
+      /**
+       * Two-pass loudnorm: measure first, then apply with measured values for accuracy
+       */
+      function twoPassNorm(inPath, outPath, lufs = -14, tp = -1.0) {
+        // Pass 1: measure
+        const m = spawnSync('ffmpeg', [
+          '-nostdin', '-i', inPath,
+          '-af', `loudnorm=I=${lufs}:TP=${tp}:print_format=json`,
+          '-f', 'null', '-',
+        ], { encoding: 'utf8', timeout: 120000 });
+        const combined = (m.stderr || '') + (m.stdout || '');
+        const match = combined.match(/\{[\s\S]*?"input_i"[\s\S]*?\}/);
+        let filterStr = `loudnorm=I=${lufs}:TP=${tp}`;
+        if (match) {
+          try {
+            const ln = JSON.parse(match[0]);
+            filterStr = `loudnorm=I=${lufs}:TP=${tp}:measured_I=${ln.input_i}:measured_LRA=${ln.input_lra}:measured_TP=${ln.input_tp}:measured_thresh=${ln.input_thresh}:offset=${ln.target_offset}:linear=true`;
+          } catch (_) {}
+        }
+        runFfmpeg([
+          '-i', inPath, '-af', filterStr,
+          '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+          outPath,
+        ], `Two-pass loudnorm ${pathMod.basename(inPath)}`);
+      }
+
+      // ── Resolve platform LUFS target ───────────────────────────────────────
+      const PLATFORM_LUFS_LOCAL = {
+        youtube: { lufs: -14, tp: -1.0 }, podcast: { lufs: -16, tp: -1.0 },
+        broadcast: { lufs: -23, tp: -1.0 }, netflix: { lufs: -27, tp: -3.0 },
+        instagram: { lufs: -14, tp: -1.0 },
+      };
+      const platformTarget = platform ? (PLATFORM_LUFS_LOCAL[platform] || null) : null;
+      const resolvedLufs = platformTarget ? platformTarget.lufs : targetLufs;
+      const resolvedTp   = platformTarget ? platformTarget.tp   : -1.0;
+
+      // ── Room acoustics profile resolution ─────────────────────────────────
+      const ROOM_PROFILES_LOCAL = {
+        studio_dry:   { inGain: 0.8, outGain: 0.6,  delays: '10', decays: '0.1' },
+        broadcast:    { inGain: 0.8, outGain: 0.75, delays: '20', decays: '0.2' },
+        cinematic:    { inGain: 0.8, outGain: 0.85, delays: '30', decays: '0.3' },
+        concert_hall: { inGain: 0.8, outGain: 0.90, delays: '45', decays: '0.55' },
+        intimate:     { inGain: 0.85, outGain: 0.70, delays: '15', decays: '0.18' },
+      };
+      const resolvedRoom = roomProfile ? (ROOM_PROFILES_LOCAL[roomProfile] || null) : (addReverb ? ROOM_PROFILES_LOCAL.cinematic : null);
+
+      // ── Step 1: Professional voice chain ──────────────────────────────────
+      // [noise gate] → 80Hz HPF → presence +2dB@5kHz → air shelf +1.5dB@12kHz
+      // → 3:1 compressor → de-esser 6.5kHz → [room acoustics]
+      const voiceChainPath = pathMod.join(tmpDir, 'voice_chain.m4a');
+      const deEsserFreq = 6500;  // Hz — sibilant center
+      const deEsserBW   = 1500;  // Hz — bandwidth
+
+      const voiceFilterParts = [];
+      // Noise gate: removes breath noise and room tone between words
+      if (noiseGate) {
+        voiceFilterParts.push('agate=threshold=0.0003:range=0.15:attack=5:release=200');
+      }
+      voiceFilterParts.push(
+        'highpass=f=80',
+        'equalizer=f=5000:width_type=o:width=2:g=2.0',   // presence boost
+        'equalizer=f=12000:width_type=s:width=1:g=1.5',  // air shelf
+        'acompressor=ratio=3:threshold=-20dB:attack=5:release=50:makeup=2',
+        `equalizer=f=${deEsserFreq}:width_type=h:width=${deEsserBW}:g=-3.0`, // de-esser
+      );
+      if (resolvedRoom) {
+        voiceFilterParts.push(
+          `aecho=in_gain=${resolvedRoom.inGain}:out_gain=${resolvedRoom.outGain}:delays=${resolvedRoom.delays}:decays=${resolvedRoom.decays}`
+        );
+      }
+      const voiceFilterWithReverb = voiceFilterParts.join(',');
+
+      runFfmpeg([
+        '-i', voicePath,
+        '-af', voiceFilterWithReverb,
+        '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+        voiceChainPath,
+      ], 'Voice chain (noise gate + EQ + de-esser + compress + room)');
+
+      // ── Step 2: SFX synthesis and timeline cue mixing ─────────────────────
+      let sfxMixPath = null;
+      if (Array.isArray(sfxCues) && sfxCues.length > 0) {
+        // Get voice duration for SFX timeline
+        const durProbe = spawnSync('ffprobe', [
+          '-v', 'error', '-show_entries', 'format=duration',
+          '-of', 'default=nk=1:nw=1', voiceChainPath,
+        ], { encoding: 'utf8', timeout: 10000 });
+        const voiceDur = parseFloat((durProbe.stdout || '0').trim()) || 30;
+
+        // Generate SFX via tone synthesis — full 13-type earshot library
+        // Build per-SFX wav files, then mix them with the voice chain
+        const sfxPaths = [];
+        // Extended earshot SFX map (matches SFX_FREQ_MAP in mixer.js)
+        const SFX_FULL_MAP = {
+          whoosh:     { freq: 200,  dur: 0.4,  vol: 0.35 },
+          impact:     { freq: 60,   dur: 0.5,  vol: 0.42 },
+          pop:        { freq: 600,  dur: 0.12, vol: 0.28 },
+          click:      { freq: 2500, dur: 0.05, vol: 0.22 },
+          riser:      { freq: 100,  dur: 2.0,  vol: 0.30 },
+          chime:      { freq: 1200, dur: 0.35, vol: 0.25 },
+          buzz:       { freq: 80,   dur: 0.18, vol: 0.38 },
+          tick:       { freq: 3200, dur: 0.04, vol: 0.18 },
+          swish:      { freq: 350,  dur: 0.3,  vol: 0.30 },
+          punch:      { freq: 45,   dur: 0.25, vol: 0.50 },
+          sparkle:    { freq: 4000, dur: 0.2,  vol: 0.15 },
+          deep_boom:  { freq: 30,   dur: 1.2,  vol: 0.55 },
+          transition: { freq: 440,  dur: 0.6,  vol: 0.20 },
+        };
+
+        for (let i = 0; i < sfxCues.length; i++) {
+          const cue = sfxCues[i];
+          const sfxName = (cue.name || cue.sfxName || 'pop').toLowerCase().replace(/-/g, '_');
+          const cueTime = Number(cue.time || cue.t || 0);
+          const cueVol = Number(cue.volume || cue.vol || 1.0);
+          const sfxDef = SFX_FULL_MAP[sfxName] || SFX_FULL_MAP.pop;
+          const sfxDur = sfxDef.dur;
+
+          // Perceptual lead: place audio 40ms before the visual cue
+          const adjustedTime = Math.max(0, cueTime - 0.04);
+
+          const sfxPath = pathMod.join(tmpDir, `sfx_${i}_${sfxName}.m4a`);
+          const freq = sfxDef.freq;
+
+          // Create silence-padded SFX at correct offset in timeline
+          const silenceFilter = `anullsrc=channel_layout=stereo:sample_rate=48000[silence];sine=f=${freq}:d=${sfxDur}[sfxtone];[sfxtone]volume=${cueVol * 0.35}[sfxv];[silence][sfxv]amix=inputs=2:duration=longest[sfxout]`;
+          const adelayMs = Math.round(adjustedTime * 1000);
+          runFfmpeg([
+            '-f', 'lavfi', '-i', `anullsrc=channel_layout=stereo:sample_rate=48000:duration=${Math.max(sfxDur + adjustedTime + 0.5, 1)}`,
+            '-f', 'lavfi', '-i', `sine=f=${freq}:d=${sfxDur}`,
+            '-filter_complex', `[1:a]volume=${cueVol * 0.35},adelay=${adelayMs}|${adelayMs}[sfx];[0:a][sfx]amix=inputs=2:duration=first[out]`,
+            '-map', '[out]',
+            '-c:a', 'aac', '-b:a', '128k', '-ar', '48000', '-ac', '2',
+            '-t', String(voiceDur),
+            sfxPath,
+          ], `SFX synthesis: ${sfxName} at t=${cueTime}s`);
+          sfxPaths.push(sfxPath);
+        }
+
+        // Merge all SFX into one timeline track
+        if (sfxPaths.length === 1) {
+          sfxMixPath = sfxPaths[0];
+        } else {
+          sfxMixPath = pathMod.join(tmpDir, 'sfx_combined.m4a');
+          const sfxInputs = sfxPaths.flatMap(p => ['-i', p]);
+          const sfxFilter = sfxPaths.map((_, i) => `[${i}:a]`).join('') + `amix=inputs=${sfxPaths.length}:duration=longest:normalize=0[sfxout]`;
+          runFfmpeg([
+            ...sfxInputs,
+            '-filter_complex', sfxFilter,
+            '-map', '[sfxout]',
+            '-c:a', 'aac', '-b:a', '128k', '-ar', '48000', '-ac', '2',
+            sfxMixPath,
+          ], 'SFX combine');
+        }
+      }
+
+      // ── Step 3: Music processing + sidechain ducking ───────────────────────
+      let finalMixPath;
+      if (musicPath && syncFs.existsSync(musicPath)) {
+        const vidDur = spawnSync('ffprobe', [
+          '-v', 'error', '-show_entries', 'format=duration',
+          '-of', 'default=nk=1:nw=1', voiceChainPath,
+        ], { encoding: 'utf8', timeout: 10000 });
+        const totalDur = parseFloat((vidDur.stdout || '0').trim()) || 60;
+
+        const musicFilter = stereoWiden
+          ? `aformat=sample_rates=48000:channel_layouts=stereo,highpass=f=80,lowpass=f=16000,volume=${musicVolume},extrastereo=m=1.4`
+          : `aformat=sample_rates=48000:channel_layouts=stereo,highpass=f=80,lowpass=f=16000,volume=${musicVolume}`;
+
+        const duckedMixPath = pathMod.join(tmpDir, 'ducked_mix.m4a');
+
+        const inputs = ['-i', voiceChainPath, '-stream_loop', '-1', '-i', musicPath, '-t', String(totalDur)];
+        const sfxInputPart = sfxMixPath ? ['-i', sfxMixPath] : [];
+        const sfxInputIdx = sfxMixPath ? 2 : -1;
+
+        let filterComplex, mapExpr;
+        if (sfxMixPath) {
+          filterComplex = [
+            `[1:a]${musicFilter}[music_proc]`,
+            `[0:a][music_proc]sidechaincompress=threshold=0.003:ratio=20:attack=0.2:release=1:makeup=2[ducked]`,
+            `[ducked][2:a]amix=inputs=2:duration=first:normalize=0[mix_sfx]`,
+          ].join(';');
+          mapExpr = '[mix_sfx]';
+        } else {
+          filterComplex = [
+            `[1:a]${musicFilter}[music_proc]`,
+            `[0:a][music_proc]sidechaincompress=threshold=0.003:ratio=20:attack=0.2:release=1:makeup=2[ducked]`,
+          ].join(';');
+          mapExpr = '[ducked]';
+        }
+
+        runFfmpeg([
+          '-i', voiceChainPath,
+          '-stream_loop', '-1', '-i', musicPath, '-t', String(totalDur),
+          ...sfxInputPart,
+          '-filter_complex', filterComplex,
+          '-map', mapExpr,
+          '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+          duckedMixPath,
+        ], 'Sidechain ducking + SFX mix');
+        finalMixPath = duckedMixPath;
+      } else if (sfxMixPath) {
+        // No music, but SFX — mix voice + SFX
+        const sfxVoiceMix = pathMod.join(tmpDir, 'voice_sfx.m4a');
+        runFfmpeg([
+          '-i', voiceChainPath, '-i', sfxMixPath,
+          '-filter_complex', '[0:a][1:a]amix=inputs=2:duration=first:normalize=0[out]',
+          '-map', '[out]',
+          '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+          sfxVoiceMix,
+        ], 'Voice + SFX mix');
+        finalMixPath = sfxVoiceMix;
+      } else {
+        finalMixPath = voiceChainPath;
+      }
+
+      // ── Step 4: Two-pass EBU R128 loudnorm master (platform-aware) ────────
+      const normPath = pathMod.join(tmpDir, 'master_norm.m4a');
+      twoPassNorm(finalMixPath, normPath, resolvedLufs, resolvedTp);
+
+      // ── Step 5: Mux into video or copy to outputPath ──────────────────────
+      if (videoPath && syncFs.existsSync(videoPath)) {
+        const vidDur2 = spawnSync('ffprobe', [
+          '-v', 'error', '-show_entries', 'format=duration',
+          '-of', 'default=nk=1:nw=1', videoPath,
+        ], { encoding: 'utf8', timeout: 10000 });
+        const vd = parseFloat((vidDur2.stdout || '0').trim()) || 0;
+        runFfmpeg([
+          '-i', videoPath, '-i', normPath,
+          '-map', '0:v', '-map', '1:a',
+          '-c:v', 'copy',
+          '-c:a', 'aac', '-b:a', '192k',
+          ...(vd > 0 ? ['-t', String(vd)] : []),
+          '-movflags', '+faststart',
+          outputPath,
+        ], 'Mux mixed audio into video');
+      } else {
+        // Just copy the normalized audio
+        const copyRes = spawnSync('ffmpeg', ['-nostdin', '-y', '-i', normPath, '-c', 'copy', outputPath], { encoding: 'utf8', timeout: 30000 });
+        if (copyRes.status !== 0) {
+          // Fallback: re-encode
+          runFfmpeg(['-i', normPath, '-c:a', 'aac', '-b:a', '192k', outputPath], 'Copy audio output');
+        }
+      }
+
+      // ── Cleanup tmp ───────────────────────────────────────────────────────
+      try { syncFs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+
+      // ── Measure final loudness ─────────────────────────────────────────────
+      let measuredLufs = null;
+      let measuredTp = null;
+      try {
+        const m = spawnSync('ffmpeg', [
+          '-nostdin', '-i', outputPath,
+          '-af', `loudnorm=I=${resolvedLufs}:TP=${resolvedTp}:print_format=json`,
+          '-f', 'null', '-',
+        ], { encoding: 'utf8', timeout: 60000 });
+        const combined = (m.stderr || '') + (m.stdout || '');
+        const match = combined.match(/\{[\s\S]*?"input_i"[\s\S]*?\}/);
+        if (match) {
+          const ln = JSON.parse(match[0]);
+          measuredLufs = parseFloat(ln.input_i);
+          measuredTp = parseFloat(ln.input_tp);
+        }
+      } catch (_) {}
+
+      const sizeBytes = syncFs.existsSync(outputPath) ? syncFs.statSync(outputPath).size : 0;
+
+      return {
+        outputPath,
+        sizeBytes,
+        measuredLufs,
+        measuredTp,
+        targetLufs: resolvedLufs,
+        platform: platform || null,
+        passed: measuredLufs != null ? Math.abs(measuredLufs - resolvedLufs) <= 1.5 && measuredTp <= -0.5 : null,
+        chain: {
+          noiseGate: noiseGate ? 'agate -60dBFS' : 'off',
+          hpf: '80Hz',
+          presenceBoost: '+2dB @ 5kHz',
+          airShelf: '+1.5dB @ 12kHz',
+          deEsser: `${deEsserFreq}Hz dynamic`,
+          compressor: '3:1 @ -20dBFS',
+          roomAcoustics: resolvedRoom ? (roomProfile || 'cinematic') : 'off',
+          sidechainDuck: musicPath ? `${duckLevel}dB` : 'no music',
+          stereoWiden: stereoWiden && musicPath ? 'MS extrastereo 1.4x' : 'off',
+          sfxCues: sfxCues.length,
+          masterBus: `EBU R128 ${resolvedLufs} LUFS${platform ? ` (${platform})` : ''}`,
+        },
+        message: `Professional audio mix complete → ${outputPath} (${(sizeBytes / 1024).toFixed(0)}KB${measuredLufs != null ? `, ${measuredLufs.toFixed(1)} LUFS` : ''}${platform ? `, ${platform} target` : ''})`,
       };
     },
   },
@@ -1864,7 +2820,7 @@ Analyzes input clips, segments narrative beats, calculates cut in/out timestamps
 
 const SERVER_INFO = {
   name:    'video-pipeline',
-  version: '2.4.10',
+  version: '2.7.0',
 };
 
 const CAPABILITIES = {