reelme 0.2.2 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # reelme
 
-Turn your repo into launch videos for social platforms — rendered locally with [Remotion](https://www.remotion.dev), zero cloud, zero API keys.
+Turn your repo into launch videos for social platforms — rendered on your machine with [Remotion](https://www.remotion.dev). No accounts, no API keys, nothing uploaded.
 
 `reelme` is the rendering engine behind the [reelme agent skill](https://github.com/RubenGlez/reelme). The skill does the thinking (it reads your repo, interviews you, and writes a `reelme.json` brief at your repo root); this CLI does the work: it scaffolds a Remotion project in a global cache and renders one video variant per publishing platform.
 
@@ -24,12 +24,13 @@ npx skills add RubenGlez/reelme
 |---|---|
 | `npx reelme render` | Renders every platform selected in `reelme.json` to `./reelme-out/` |
 | `npx reelme studio` | Opens Remotion Studio against the cached project, for previewing and tweaking |
-| `npx reelme clean` | Removes the reelme cache (`~/.reelme/cache`) |
+| `npx reelme validate` | Checks `reelme.json` (schema, platforms, scene types and fields) without rendering |
+| `npx reelme clean` | Removes this project's cache (add `--all` to wipe every project's cache in `~/.reelme/cache`) |
 
 ## How it works
 
 - Your repo keeps only two things: `reelme.json` (the brief — commit it, it's your video's source of truth across releases) and `reelme-out/` (rendered videos; add it to `.gitignore`).
-- The heavy Remotion project lives in `~/.reelme/cache/<project-hash>/`, scaffolded on first render and reused afterwards. Re-renders don't reinstall anything; upgrading the CLI rebuilds the scaffold automatically.
+- The heavy Remotion project lives in `~/.reelme/cache/<project-hash>/`, scaffolded on first render and reused afterwards. Re-renders don't reinstall anything; upgrading the CLI (or changing the template's dependencies) rebuilds the scaffold automatically.
 - Each platform you select (X, LinkedIn, YouTube, TikTok, Instagram Reel/Story/Feed, GitHub README) maps to a preset that resolves dimensions, duration ceilings, and safe areas internally — you never deal with aspect ratios. GitHub README outputs a GIF; everything else is MP4. Briefs with a `teaser` cut also get a short `<platform>-teaser.mp4` per social platform.
 
 ## Requirements
@@ -37,6 +38,12 @@ npx skills add RubenGlez/reelme
 - Node.js >= 18
 - [pnpm](https://pnpm.io) (used to install render dependencies inside the cache)
 
+The first render needs network access: it installs the Remotion project into the
+cache (npm registry), downloads a headless Chrome build (hundreds of MB, once),
+and fetches the on-screen fonts from Google Fonts. After the first successful
+render most of this is cached, but font loading still runs per render — nothing
+you author is ever uploaded.
+
 ## License
 
 MIT

package/assets/audio/PROVENANCE.md

@@ -0,0 +1,16 @@
+# ReelMe Bundled Audio Provenance
+
+The bundled tracks in this directory are instrumental loops generated by
+`generate-tracks.mjs` for ReelMe. They do not sample third-party recordings,
+loops, MIDI files, or stems.
+
+The generated tracks are dedicated to the public domain under CC0 1.0. The
+manifest source URLs point to the generator definition used to create each
+track. Regenerate the MP3 files with:
+
+```bash
+node cli/assets/audio/generate-tracks.mjs
+```
+
+Each track is 32 seconds long, encoded as MP3, and kept below 2 MB for package
+size.

package/assets/audio/generate-tracks.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+import { rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SAMPLE_RATE = 44100;
+const DURATION = 32;
+const TWO_PI = Math.PI * 2;
+
+const TRACKS = [
+  {
+    id: "calm-keys",
+    file: "calm-keys.mp3",
+    bpm: 92,
+    key: 57,
+    scale: [0, 2, 4, 7, 9],
+    chords: [[0, 4, 7, 11], [9, 0, 4, 7], [5, 9, 0, 4], [7, 11, 2, 5]],
+    melody: [0, 2, 4, 7, 4, 2, 0, 9],
+    mood: "soft",
+  },
+  {
+    id: "steady-launch",
+    file: "steady-launch.mp3",
+    bpm: 104,
+    key: 50,
+    scale: [0, 2, 5, 7, 9],
+    chords: [[0, 5, 9], [7, 0, 5], [9, 2, 5], [5, 9, 0]],
+    melody: [0, 5, 7, 9, 7, 5, 2, 0],
+    mood: "drive",
+  },
+  {
+    id: "clean-horizon",
+    file: "clean-horizon.mp3",
+    bpm: 88,
+    key: 55,
+    scale: [0, 2, 4, 7, 11],
+    chords: [[0, 4, 7], [4, 7, 11], [9, 0, 4], [7, 11, 2]],
+    melody: [7, 4, 2, 0, 2, 4, 7, 11],
+    mood: "soft",
+  },
+  {
+    id: "bright-sparks",
+    file: "bright-sparks.mp3",
+    bpm: 118,
+    key: 60,
+    scale: [0, 2, 4, 7, 9],
+    chords: [[0, 4, 7], [5, 9, 0], [7, 11, 2], [4, 7, 11]],
+    melody: [0, 4, 7, 9, 7, 4, 2, 4],
+    mood: "bounce",
+  },
+  {
+    id: "pixel-bounce",
+    file: "pixel-bounce.mp3",
+    bpm: 126,
+    key: 58,
+    scale: [0, 3, 5, 7, 10],
+    chords: [[0, 3, 7], [10, 3, 5], [5, 8, 0], [7, 10, 2]],
+    melody: [0, 3, 7, 10, 7, 3, 5, 7],
+    mood: "chip",
+  },
+  {
+    id: "sunny-loop",
+    file: "sunny-loop.mp3",
+    bpm: 112,
+    key: 62,
+    scale: [0, 2, 4, 7, 9],
+    chords: [[0, 4, 7], [9, 0, 4], [5, 9, 0], [7, 11, 2]],
+    melody: [4, 7, 9, 12, 9, 7, 4, 2],
+    mood: "bounce",
+  },
+  {
+    id: "circuit-pulse",
+    file: "circuit-pulse.mp3",
+    bpm: 124,
+    key: 45,
+    scale: [0, 2, 3, 7, 10],
+    chords: [[0, 3, 7], [7, 10, 2], [3, 7, 10], [10, 2, 5]],
+    melody: [0, 7, 3, 10, 2, 7, 3, 0],
+    mood: "pulse",
+  },
+  {
+    id: "vector-grid",
+    file: "vector-grid.mp3",
+    bpm: 116,
+    key: 48,
+    scale: [0, 2, 5, 7, 10],
+    chords: [[0, 5, 10], [7, 0, 5], [10, 2, 7], [5, 10, 0]],
+    melody: [0, 2, 5, 7, 10, 7, 5, 2],
+    mood: "pulse",
+  },
+  {
+    id: "midnight-protocol",
+    file: "midnight-protocol.mp3",
+    bpm: 98,
+    key: 47,
+    scale: [0, 2, 3, 7, 9],
+    chords: [[0, 3, 7], [9, 0, 3], [7, 10, 2], [3, 7, 9]],
+    melody: [0, 3, 7, 9, 7, 3, 2, 0],
+    mood: "drive",
+  },
+];
+
+function midiToFreq(note) {
+  return 440 * 2 ** ((note - 69) / 12);
+}
+
+function triangle(phase) {
+  return (2 / Math.PI) * Math.asin(Math.sin(phase));
+}
+
+function env(position, attack, release) {
+  if (position < attack) return position / attack;
+  return Math.exp(-(position - attack) * release);
+}
+
+function renderSample(track, t, i) {
+  const beat = 60 / track.bpm;
+  const bar = beat * 4;
+  const chord = track.chords[Math.floor(t / (bar * 2)) % track.chords.length];
+  const chordPos = (t % (bar * 2)) / (bar * 2);
+  const noteStep = Math.floor(t / (beat / 2)) % track.melody.length;
+  const notePos = (t % (beat / 2)) / (beat / 2);
+  const root = track.key;
+
+  let sample = 0;
+
+  for (let c = 0; c < chord.length; c += 1) {
+    const freq = midiToFreq(root + chord[c]);
+    const wobble = 1 + Math.sin(TWO_PI * t * 0.08 + c) * 0.002;
+    const amp = track.mood === "soft" ? 0.055 : 0.04;
+    sample += Math.sin(TWO_PI * freq * wobble * t) * amp * env(chordPos, 0.08, 1.2);
+    sample += triangle(TWO_PI * freq * 2 * t) * amp * 0.18;
+  }
+
+  // Sustained sub-bass that swells once per chord — a smooth harmonic floor
+  // rather than a per-beat thump. The old per-beat kick/hat read as a disturbing
+  // pulse under narration, so these beds are now ambient, not percussive.
+  const bassRoot = root - 24 + chord[0];
+  sample += Math.sin(TWO_PI * midiToFreq(bassRoot) * t) * 0.11 * env(chordPos, 0.06, 0.9);
+
+  const melodyNote = root + 12 + track.melody[noteStep];
+  const leadWave = track.mood === "chip"
+    ? Math.sign(Math.sin(TWO_PI * midiToFreq(melodyNote) * t))
+    : triangle(TWO_PI * midiToFreq(melodyNote) * t);
+  sample += leadWave * 0.06 * env(notePos, 0.03, track.mood === "soft" ? 4 : 7);
+
+  return Math.max(-0.98, Math.min(0.98, sample));
+}
+
+function writeWav(path, track) {
+  const frames = SAMPLE_RATE * DURATION;
+  const dataSize = frames * 2 * 2;
+  const buffer = Buffer.alloc(44 + dataSize);
+
+  buffer.write("RIFF", 0);
+  buffer.writeUInt32LE(36 + dataSize, 4);
+  buffer.write("WAVE", 8);
+  buffer.write("fmt ", 12);
+  buffer.writeUInt32LE(16, 16);
+  buffer.writeUInt16LE(1, 20);
+  buffer.writeUInt16LE(2, 22);
+  buffer.writeUInt32LE(SAMPLE_RATE, 24);
+  buffer.writeUInt32LE(SAMPLE_RATE * 2 * 2, 28);
+  buffer.writeUInt16LE(4, 32);
+  buffer.writeUInt16LE(16, 34);
+  buffer.write("data", 36);
+  buffer.writeUInt32LE(dataSize, 40);
+
+  for (let i = 0; i < frames; i += 1) {
+    const t = i / SAMPLE_RATE;
+    const left = renderSample(track, t, i);
+    const right = renderSample(track, t + 0.006, i + 17);
+    buffer.writeInt16LE(Math.round(left * 32767), 44 + i * 4);
+    buffer.writeInt16LE(Math.round(right * 32767), 44 + i * 4 + 2);
+  }
+
+  writeFileSync(path, buffer);
+}
+
+const outDir = dirname(fileURLToPath(import.meta.url));
+
+for (const track of TRACKS) {
+  const wavPath = join(outDir, `${track.id}.wav`);
+  const mp3Path = join(outDir, track.file);
+  writeWav(wavPath, track);
+  const result = spawnSync(
+    "ffmpeg",
+    [
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      wavPath,
+      "-af",
+      "loudnorm=I=-21:LRA=10:TP=-1.5",
+      "-codec:a",
+      "libmp3lame",
+      "-b:a",
+      "96k",
+      mp3Path,
+    ],
+    { stdio: "inherit" }
+  );
+  // Check the encode status before cleaning up. On failure, remove both the
+  // intermediate WAV and any partial/stale MP3 so a broken encode never leaves a
+  // misleading file from this or a previous run on disk.
+  if (result.error || result.status !== 0) {
+    rmSync(wavPath, { force: true });
+    rmSync(mp3Path, { force: true });
+    process.exitCode = result.status || 1;
+    break;
+  }
+  rmSync(wavPath, { force: true });
+  console.log(`wrote ${mp3Path}`);
+}

package/assets/audio/manifest.json

@@ -0,0 +1,83 @@
+[
+  {
+    "file": "calm-keys.mp3",
+    "title": "Calm Keys",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#calm-keys",
+    "license": "CC0",
+    "tones": ["professional"],
+    "duration": 32
+  },
+  {
+    "file": "steady-launch.mp3",
+    "title": "Steady Launch",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#steady-launch",
+    "license": "CC0",
+    "tones": ["professional", "technical"],
+    "duration": 32
+  },
+  {
+    "file": "clean-horizon.mp3",
+    "title": "Clean Horizon",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#clean-horizon",
+    "license": "CC0",
+    "tones": ["professional"],
+    "duration": 32
+  },
+  {
+    "file": "bright-sparks.mp3",
+    "title": "Bright Sparks",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#bright-sparks",
+    "license": "CC0",
+    "tones": ["playful"],
+    "duration": 32
+  },
+  {
+    "file": "pixel-bounce.mp3",
+    "title": "Pixel Bounce",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#pixel-bounce",
+    "license": "CC0",
+    "tones": ["playful", "technical"],
+    "duration": 32
+  },
+  {
+    "file": "sunny-loop.mp3",
+    "title": "Sunny Loop",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#sunny-loop",
+    "license": "CC0",
+    "tones": ["playful"],
+    "duration": 32
+  },
+  {
+    "file": "circuit-pulse.mp3",
+    "title": "Circuit Pulse",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#circuit-pulse",
+    "license": "CC0",
+    "tones": ["technical"],
+    "duration": 32
+  },
+  {
+    "file": "vector-grid.mp3",
+    "title": "Vector Grid",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#vector-grid",
+    "license": "CC0",
+    "tones": ["technical"],
+    "duration": 32
+  },
+  {
+    "file": "midnight-protocol.mp3",
+    "title": "Midnight Protocol",
+    "artist": "ReelMe procedural audio generator",
+    "source": "https://github.com/RubenGlez/reelme/blob/main/cli/assets/audio/generate-tracks.mjs#midnight-protocol",
+    "license": "CC0",
+    "tones": ["technical", "professional"],
+    "duration": 32
+  }
+]

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "reelme",
-  "version": "0.2.2",
-  "description": "Turn your repo into launch videos for social platforms. Local Remotion rendering, zero cloud.",
+  "version": "0.4.0",
+  "description": "Turn your repo into launch videos for social platforms. Rendered on your machine with Remotion — no accounts, no uploads.",
   "type": "module",
   "bin": {
     "reelme": "src/cli.mjs"
   },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
   "files": [
     "src",
+    "assets",
     "template",
     "!template/out",
     "!template/src/__tests__",
@@ -18,6 +22,9 @@
   "engines": {
     "node": ">=18"
   },
+  "optionalDependencies": {
+    "gifsicle": "^7.0.1"
+  },
   "keywords": [
     "launch-video",
     "remotion",

package/src/cache.mjs

@@ -20,11 +20,25 @@ export const CACHE_ROOT = join(homedir(), ".reelme", "cache");
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 export const TEMPLATE_DIR = join(PKG_ROOT, "template");
+export const AUDIO_DIR = join(PKG_ROOT, "assets", "audio");
 
 const CLI_VERSION = JSON.parse(
   readFileSync(join(PKG_ROOT, "package.json"), "utf8")
 ).version;
 
+// Cache-invalidation key. The per-render `src/` re-sync keeps scene code fresh,
+// but dependencies and pnpm config only reach an existing cache on a full
+// rebuild — so the marker hashes those files, not just the CLI version (F8).
+// A bumped Remotion version or workspace change now forces a reinstall.
+function templateFingerprint() {
+  const hash = createHash("sha256").update(CLI_VERSION);
+  for (const file of ["package.json", "pnpm-workspace.yaml"]) {
+    const path = join(TEMPLATE_DIR, file);
+    if (existsSync(path)) hash.update(readFileSync(path));
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+
 // Not copied into the cache scaffold (mirrors the old SKILL.md rsync excludes).
 const SCAFFOLD_EXCLUDES = new Set([
   "node_modules",
@@ -47,6 +61,84 @@ export function loadPlatforms() {
   );
 }
 
+// Per-scene contract, mirroring the TypeScript union in template/src/brief.ts.
+// The CLI runs first and owns the error UX, so it validates exhaustively here
+// (F4/F13/F24): a typo'd scene type or a missing required prop is caught with a
+// named error instead of a cryptic NaN duration or crash minutes into Remotion.
+const SCENE_REQUIRED = {
+  problem: ["headline"],
+  "code-reveal": ["language", "code"],
+  terminal: ["commands"],
+  "data-flow": ["nodes", "edges"],
+  cta: ["installCommand", "repoUrl"],
+  browser: ["url"],
+  split: ["before", "after"],
+  "feature-list": ["items"],
+  "stat-callout": ["stats"],
+  "file-tree": ["entries"],
+  mobile: [],
+  "os-window": ["items"],
+  hotkey: ["keys"],
+  hook: ["text"],
+  clip: ["src", "frame"],
+  benchmark: ["bars"],
+};
+const ARRAY_FIELDS = new Set([
+  "commands", "nodes", "edges", "items", "stats", "entries", "keys", "bars",
+]);
+const CLIP_EXTS = ["mp4", "mov", "gif"];
+const IMAGE_EXTS = ["png", "jpg", "jpeg", "webp"];
+
+function extOf(p) {
+  const dot = p.lastIndexOf(".");
+  return dot === -1 ? "" : p.slice(dot + 1).toLowerCase();
+}
+
+function validateScene(scene, where, errors) {
+  if (!scene || typeof scene !== "object") {
+    errors.push(`${where}: scene must be an object.`);
+    return;
+  }
+  const spec = SCENE_REQUIRED[scene.type];
+  if (!spec) {
+    errors.push(
+      `${where}: unknown scene type "${scene.type ?? "(none)"}". Valid types: ${Object.keys(SCENE_REQUIRED).join(", ")}.`
+    );
+    return;
+  }
+  for (const field of spec) {
+    if (scene[field] === undefined || scene[field] === null) {
+      errors.push(`${where} (${scene.type}): missing required field "${field}".`);
+    } else if (ARRAY_FIELDS.has(field) && !Array.isArray(scene[field])) {
+      errors.push(`${where} (${scene.type}): "${field}" must be an array.`);
+    }
+  }
+  // Asset extension checks — the direct-CLI path has no skill to pre-validate.
+  const assetChecks = [
+    ["clip", "src", CLIP_EXTS],
+    ["mobile", "screenshot", IMAGE_EXTS],
+    ["browser", "image", IMAGE_EXTS],
+  ];
+  for (const [type, field, exts] of assetChecks) {
+    if (scene.type === type && typeof scene[field] === "string" && !exts.includes(extOf(scene[field]))) {
+      errors.push(
+        `${where} (${type}): "${field}" must be one of ${exts.join(", ")} (got "${scene[field]}").`
+      );
+    }
+  }
+}
+
+// Empty cut arrays are normalized to absent so a `"vertical": []` behaves like a
+// missing vertical cut everywhere (F3): the CLI and the template agree on the
+// main-cut fallback instead of building a zero-duration composition.
+function normalizeCuts(brief) {
+  for (const key of ["vertical", "teaser"]) {
+    if (Array.isArray(brief.cuts?.[key]) && brief.cuts[key].length === 0) {
+      delete brief.cuts[key];
+    }
+  }
+}
+
 export function readBrief(repoRoot) {
   const briefPath = join(repoRoot, "reelme.json");
   if (!existsSync(briefPath)) {
@@ -82,6 +174,17 @@ export function readBrief(repoRoot) {
   if (!Array.isArray(brief.cuts?.main) || brief.cuts.main.length === 0) {
     fail(`cuts.main is missing or empty — the main cut is required.`);
   }
+  normalizeCuts(brief);
+
+  const errors = [];
+  for (const key of ["main", "vertical", "teaser"]) {
+    const cut = brief.cuts[key];
+    if (!Array.isArray(cut)) continue;
+    cut.forEach((scene, i) => validateScene(scene, `cuts.${key}[${i}]`, errors));
+  }
+  if (errors.length > 0) {
+    fail(`reelme.json has ${errors.length} scene problem(s):\n${errors.map((e) => `  ${e}`).join("\n")}`);
+  }
   return brief;
 }
 
@@ -90,8 +193,16 @@ export function projectCacheDir(repoRoot) {
   return join(CACHE_ROOT, hash);
 }
 
+// spawnSync with the pnpm/npx shims resolved on every OS. On Windows those
+// shims are `.cmd` files, which Node's spawnSync can only launch via a shell
+// (and since CVE-2024-27980 that is the only sanctioned route). Elsewhere we
+// avoid the shell so arguments never go through word-splitting.
+export function runShell(command, args, cwd) {
+  return spawnSync(command, args, { cwd, stdio: "inherit", shell: process.platform === "win32" });
+}
+
 function run(command, args, cwd) {
-  const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+  const result = runShell(command, args, cwd);
   if (result.error) fail(`failed to run ${command}: ${result.error.message}`);
   if (result.status !== 0) {
     fail(`${command} ${args.join(" ")} exited with status ${result.status}`);
@@ -104,13 +215,18 @@ function run(command, args, cwd) {
 export function ensureScaffold(repoRoot) {
   const cacheDir = projectCacheDir(repoRoot);
   const versionMarker = join(cacheDir, ".reelme-template-version");
+  const fingerprint = templateFingerprint();
 
-  const stale =
-    existsSync(versionMarker) &&
-    readFileSync(versionMarker, "utf8").trim() !== CLI_VERSION;
-  if (stale) {
+  // A cache with a package.json but a missing or mismatched marker is stale — a
+  // missing marker is treated as stale, not fresh (F8), so half-built or
+  // pre-marker caches always rebuild.
+  const cacheExists = existsSync(join(cacheDir, "package.json"));
+  const markerValue = existsSync(versionMarker)
+    ? readFileSync(versionMarker, "utf8").trim()
+    : null;
+  if (cacheExists && markerValue !== fingerprint) {
     console.log(
-      `reelme: template updated (CLI ${CLI_VERSION}) — rebuilding the cache scaffold.`
+      `reelme: template changed (CLI ${CLI_VERSION}) — rebuilding the cache scaffold.`
     );
     rmSync(cacheDir, { recursive: true, force: true });
   }
@@ -122,27 +238,52 @@ export function ensureScaffold(repoRoot) {
       recursive: true,
       filter: (src) => !SCAFFOLD_EXCLUDES.has(basename(src)),
     });
-    writeFileSync(versionMarker, `${CLI_VERSION}\n`);
+    writeFileSync(versionMarker, `${fingerprint}\n`);
   }
 
+  // Re-sync the template source on every render. The version marker only fires
+  // on a CLI bump, so without this a render reuses whatever scene code the cache
+  // was scaffolded with — local template edits (and the gallery render eval)
+  // would silently test stale code. This is a cheap dir copy; node_modules stays
+  // gated below so we don't reinstall. (Deleted template files aren't pruned from
+  // the cache — a CLI bump or `reelme clean` does a full rebuild.)
+  cpSync(join(TEMPLATE_DIR, "src"), join(cacheDir, "src"), {
+    recursive: true,
+    filter: (src) => !SCAFFOLD_EXCLUDES.has(basename(src)),
+  });
+
   // The user's brief always wins over the template sample.
   cpSync(join(repoRoot, "reelme.json"), join(cacheDir, "src", "brief.json"));
 
   if (!existsSync(join(cacheDir, "node_modules"))) {
     console.log("reelme: installing render dependencies (first run only)…");
+    // esbuild's build script is pre-approved in template/pnpm-workspace.yaml
+    // (allowBuilds), so `pnpm install` runs it without a blanket approval of
+    // every dependency's scripts (F15) — the supply-chain gate stays closed.
     run("pnpm", ["install"], cacheDir);
-    // esbuild needs its post-install script; pnpm-workspace.yaml persists the approval.
-    run("pnpm", ["approve-builds", "--all"], cacheDir);
   }
 
   return cacheDir;
 }
 
-export function cleanCache() {
-  if (!existsSync(CACHE_ROOT)) {
-    console.log("reelme: cache is already empty.");
+// Removes the current project's cache by default; pass `all` to wipe every
+// project's cache (F16). A moved/renamed repo hashes to a new dir, so `--all`
+// is the way to reclaim orphaned caches.
+export function cleanCache(repoRoot, all = false) {
+  if (all) {
+    if (!existsSync(CACHE_ROOT)) {
+      console.log("reelme: cache is already empty.");
+      return;
+    }
+    rmSync(CACHE_ROOT, { recursive: true, force: true });
+    console.log(`reelme: removed all project caches (${CACHE_ROOT})`);
+    return;
+  }
+  const cacheDir = projectCacheDir(repoRoot);
+  if (!existsSync(cacheDir)) {
+    console.log("reelme: no cache for this project. Use `reelme clean --all` to wipe every project's cache.");
     return;
   }
-  rmSync(CACHE_ROOT, { recursive: true, force: true });
-  console.log(`reelme: removed ${CACHE_ROOT}`);
+  rmSync(cacheDir, { recursive: true, force: true });
+  console.log(`reelme: removed this project's cache (${cacheDir})`);
 }