dsh-hyperframes 0.2.0 → 0.3.0

package/skills/media-use/scripts/lib/prefs-store.test.mjs

@@ -0,0 +1,189 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  mergedPreferences,
+  preferenceKeyFor,
+  projectPrefsPath,
+  recordPreference,
+  userPrefsPath,
+} from "./prefs-store.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-prefs-"));
+  const home = join(root, "home");
+  const projectA = join(root, "proj-a");
+  const projectB = join(root, "proj-b");
+  mkdirSync(home, { recursive: true });
+  mkdirSync(projectA, { recursive: true });
+  mkdirSync(projectB, { recursive: true });
+  process.env.HOME = home;
+  return { root, home, projectA, projectB };
+}
+
+function restoreEnv(saved) {
+  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+  Object.assign(process.env, saved);
+}
+
+function withSandbox(fn) {
+  const savedEnv = { ...process.env };
+  const box = sandbox();
+  try {
+    fn(box);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(box.root, { recursive: true, force: true });
+  }
+}
+
+test("record writes the project tier and get merges it as source=project", () => {
+  withSandbox(({ projectA }) => {
+    const result = recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    assert.equal(result.promoted, false);
+    assert.deepEqual(result.confirmed_in, ["proj-a"]);
+
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.destination.value, "x-feed");
+    assert.equal(merged.destination.source, "project");
+
+    const onDisk = JSON.parse(readFileSync(projectPrefsPath(projectA), "utf8"));
+    assert.equal(onDisk.preferences.destination.value, "x-feed");
+  });
+});
+
+test("one project never promotes: a fresh project sees nothing user-tier", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    // proj-b has no project entry, and the value was only confirmed once.
+    assert.equal(mergedPreferences(projectB).destination, undefined);
+  });
+});
+
+test("the same value confirmed in two projects promotes to the user tier", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    const second = recordPreference({ projectDir: projectB, key: "destination", value: "x-feed" });
+    assert.equal(second.promoted, true);
+
+    const userFile = JSON.parse(readFileSync(userPrefsPath(), "utf8"));
+    assert.deepEqual(userFile.preferences.destination.confirmed_in.sort(), ["proj-a", "proj-b"]);
+
+    // A third project with no local entry now inherits the promoted default.
+    const projectC = join(projectA, "..", "proj-c");
+    mkdirSync(projectC, { recursive: true });
+    const merged = mergedPreferences(projectC);
+    assert.equal(merged.destination.value, "x-feed");
+    assert.equal(merged.destination.source, "user");
+  });
+});
+
+test("record is idempotent per project — confirmed_in stays deduped", () => {
+  withSandbox(({ projectA }) => {
+    recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    const again = recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    assert.deepEqual(again.confirmed_in, ["proj-a"]);
+    assert.equal(again.promoted, false);
+  });
+});
+
+test("a changed value restarts provenance instead of inheriting confirmations", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    recordPreference({ projectDir: projectB, key: "destination", value: "x-feed" });
+    const switched = recordPreference({
+      projectDir: projectA,
+      key: "destination",
+      value: "youtube",
+    });
+    assert.deepEqual(switched.confirmed_in, ["proj-a"]);
+    assert.equal(switched.promoted, false);
+    // The previously promoted value keeps serving other projects until youtube
+    // earns its own two confirmations.
+    const userFile = JSON.parse(readFileSync(userPrefsPath(), "utf8"));
+    assert.equal(userFile.preferences.destination.value, "x-feed");
+  });
+});
+
+test("project tier overrides a promoted user-tier value", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "yes" });
+    recordPreference({ projectDir: projectB, key: "storyboard", value: "yes" });
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "no" });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.storyboard.value, "no");
+    assert.equal(merged.storyboard.source, "project");
+  });
+});
+
+test("the retired mode key is rejected", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(
+      () => recordPreference({ projectDir: projectA, key: "mode", value: "collaborative" }),
+      /unknown preference key/,
+    );
+  });
+});
+
+test("the run-shape keys record and promote like any field", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "flow", value: "automation" });
+    const promoted = recordPreference({ projectDir: projectB, key: "flow", value: "automation" });
+    assert.equal(promoted.promoted, true);
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "yes" });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.flow.value, "automation");
+    assert.equal(merged.storyboard.value, "yes");
+    assert.equal(merged.storyboard.source, "project");
+  });
+});
+
+test("style_preset is keyed per workflow", () => {
+  withSandbox(({ projectA }) => {
+    assert.equal(
+      preferenceKeyFor("style_preset", "faceless-explainer"),
+      "style_preset.faceless-explainer",
+    );
+    assert.equal(preferenceKeyFor("destination", "faceless-explainer"), "destination");
+    recordPreference({
+      projectDir: projectA,
+      key: "style_preset",
+      value: "pin-and-paper",
+      workflow: "faceless-explainer",
+    });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged["style_preset.faceless-explainer"].value, "pin-and-paper");
+    assert.equal(merged["style_preset"], undefined);
+  });
+});
+
+test("style_preset without a workflow is rejected, never stored bare", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(
+      () => recordPreference({ projectDir: projectA, key: "style_preset", value: "pin-and-paper" }),
+      /pass --workflow/,
+    );
+    assert.deepEqual(mergedPreferences(projectA), {});
+  });
+});
+
+test("unknown keys and empty values are rejected", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(() => recordPreference({ projectDir: projectA, key: "vibe", value: "x" }));
+    assert.throws(() => recordPreference({ projectDir: projectA, key: "voice", value: "  " }));
+  });
+});
+
+test("corrupt files are treated as empty instead of crashing", () => {
+  withSandbox(({ projectA, home }) => {
+    mkdirSync(join(projectA, ".media"), { recursive: true });
+    writeFileSync(projectPrefsPath(projectA), "not json");
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(userPrefsPath(), '{"preferences": 42}');
+    assert.deepEqual(mergedPreferences(projectA), {});
+    const result = recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    assert.equal(result.value, "zh");
+  });
+});

package/skills/media-use/scripts/lib/probe.mjs

@@ -0,0 +1,39 @@
+import { execFileSync } from "node:child_process";
+import { extname } from "node:path";
+
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".ico"]);
+
+export function probe(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".svg") return { width: null, height: null, duration: null, codec: "svg" };
+
+  try {
+    // execFileSync (no shell) so a hostile filename like `"; rm -rf ~; ".png`
+    // can't break out of the quoting — filePath is passed as a literal argv entry.
+    const raw = execFileSync(
+      "ffprobe",
+      ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", "--", filePath],
+      { encoding: "utf8", timeout: 5000 },
+    );
+    const info = JSON.parse(raw);
+    const stream = info.streams?.[0];
+    const format = info.format;
+
+    const isImage = IMAGE_EXT.has(ext);
+    const duration = isImage
+      ? null
+      : parseFloat(format?.duration) || parseFloat(stream?.duration) || null;
+    const width = parseInt(stream?.width, 10) || null;
+    const height = parseInt(stream?.height, 10) || null;
+    const codec = stream?.codec_name || null;
+
+    return {
+      duration: duration != null ? Math.round(duration * 10) / 10 : null,
+      width,
+      height,
+      codec,
+    };
+  } catch {
+    return { duration: null, width: null, height: null, codec: null };
+  }
+}

package/skills/media-use/scripts/lib/probe.test.mjs

@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { probe } from "./probe.mjs";
+
+// Regression for the shell-injection fix: probe() must pass the path as a literal
+// argv entry, never through a shell. A filename containing shell metacharacters
+// must NOT execute. Under the old execSync(`ffprobe ... "${path}"`) the embedded
+// `touch` ran and created the marker; under execFileSync it cannot, regardless of
+// whether ffprobe is installed (the injected command never reaches a shell).
+test("probe does not execute shell metacharacters in a filename", () => {
+  const dir = mkdtempSync(join(tmpdir(), "probe-inject-"));
+  const marker = join(dir, "INJECTED");
+  // Slash-free basename (a real on-disk filename) that breaks out of the old
+  // double-quoted interpolation and would `touch INJECTED` in the cwd.
+  const evil = join(dir, `clip"; touch INJECTED; echo ".mp4`);
+  const prevCwd = process.cwd();
+  try {
+    writeFileSync(evil, "not real media");
+    process.chdir(dir); // so a leaked `touch INJECTED` would land next to `marker`
+    const meta = probe(evil);
+    assert.equal(existsSync(marker), false, "injected `touch` must not have run");
+    // Bogus/unreadable media still returns the null-shaped result, never throws.
+    assert.deepEqual(Object.keys(meta).sort(), ["codec", "duration", "height", "width"]);
+  } finally {
+    process.chdir(prevCwd);
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/skills/media-use/scripts/lib/providers.mjs

@@ -0,0 +1,5 @@
+// Back-compat surface for the v1 provider API. The ordered, capability-based
+// registry now lives in registry.mjs; this re-exports the v1 helpers so existing
+// callers keep working. New code should import from registry.mjs directly
+// (getProviders / runCapability).
+export { getProvider, listTypes } from "./registry.mjs";

package/skills/media-use/scripts/lib/recipe-store.mjs

@@ -0,0 +1,367 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { appendRecord, mediaDir, nextId } from "./manifest.mjs";
+import { regenerateIndex } from "./index-gen.mjs";
+import { mergedPreferences } from "./prefs-store.mjs";
+
+/**
+ * Recipes — the heavyweight tier of HyperFrames user memory.
+ *
+ * A recipe is the full confirmed bundle for one video type: the frozen design
+ * spec (`frame.md`), the storyboard skeleton (structure with the content
+ * blanked), and the confirmed brief values — frozen after the run's final
+ * approval, reused to start the next video of the same type from everything
+ * already approved.
+ *
+ * Storage is **named folders**, not content-addressed cache entries: a recipe
+ * is an evolving bundle with a `version`, so re-freezing the same name bumps
+ * the version and archives the old folder as `<name>@v<N>`. Two tiers, same
+ * split as everything else in media-use: project `.media/recipes/<name>/`
+ * (committed) and user `~/.media/recipes/<name>/` (a freeze is already a
+ * confirmed bundle, so it promotes immediately — no two-project rule here).
+ */
+
+/** Frontmatter keys that describe THIS video, not the reusable type. */
+const FRONTMATTER_CONTENT_KEYS = new Set(["message", "audience", "mode"]);
+
+/** BRIEF.md frontmatter keys that describe this run, not the reusable type —
+ * a recipe never locks the run's shape, so the intent layer always re-asks. */
+const BRIEF_CONTENT_KEYS = new Set(["flow", "storyboard", "message", "audience"]);
+
+/** Per-frame metadata that is content, not structure. */
+const FRAME_CONTENT_KEYS = new Set([
+  "voiceover",
+  "vo",
+  "voice_over",
+  "narration",
+  "scene",
+  "description",
+  "summary",
+  "caption",
+  "asset_candidates",
+]);
+
+const FRAME_HEADING_RE = /^(#{2,3})\s+(?:frame|beat|scene)\s+\d+/i;
+
+export function projectRecipesDir(projectDir) {
+  return join(mediaDir(projectDir), "recipes");
+}
+
+export function userRecipesDir() {
+  return join(homedir(), ".media", "recipes");
+}
+
+export function slugifyRecipeName(name) {
+  const slug = String(name ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  if (!slug) throw new Error(`recipe name "${name}" has no usable characters`);
+  return slug;
+}
+
+function frameTitle(headingLine) {
+  const dash = headingLine.split(/\s+—\s+/)[1];
+  if (dash && dash.trim()) return dash.trim();
+  return headingLine.replace(/^#+\s*/, "").trim();
+}
+
+/** Frontmatter: drop the content keys, keep structure/style keys verbatim. */
+function skeletonFrontmatter(lines, out, contentKeys = FRONTMATTER_CONTENT_KEYS) {
+  if (lines[0]?.trim() !== "---") return 0;
+  out.push(lines[0]);
+  let i = 1;
+  while (i < lines.length && lines[i].trim() !== "---") {
+    const key = lines[i].match(/^(\w+)\s*:/)?.[1]?.toLowerCase();
+    if (!key || !contentKeys.has(key)) out.push(lines[i]);
+    i++;
+  }
+  if (i < lines.length) {
+    out.push(lines[i]); // closing ---
+    i++;
+  }
+  return i;
+}
+
+/** One line inside a frame section — returns the replacement lines (may be none). */
+function skeletonFrameLine(line, state, out) {
+  const bulletKey = line.match(/^-\s+(\w+)\s*:/)?.[1]?.toLowerCase();
+  if (bulletKey) {
+    if (bulletKey === "status") out.push("- status: outline");
+    else if (!FRAME_CONTENT_KEYS.has(bulletKey)) out.push(line);
+    return;
+  }
+  if (!line.trim()) {
+    out.push(line);
+    return;
+  }
+  // Frame prose: one placeholder per frame in place of the narrative.
+  if (!state.proseReplaced) {
+    out.push(
+      `<fill in: this video's content for the "${state.title}" beat — keep the layout role, replace the words.>`,
+    );
+    state.proseReplaced = true;
+  }
+}
+
+/**
+ * Skeletonize a STORYBOARD.md: keep the reusable structure (frame count,
+ * durations, transitions, src paths, the Video direction block, style-ish
+ * frontmatter), reset every status to `outline`, and blank the content
+ * (message/audience, narration guides, per-frame prose) down to a fill-in
+ * placeholder that names the frame's role.
+ */
+/**
+ * Skeletonize a BRIEF.md: keep the frontmatter's reusable keys (workflow,
+ * destination, aspect, language, length, angle…), drop the run-shape and
+ * content keys (flow, storyboard, message, audience), and blank each body
+ * section down to a fill-in placeholder under its kept heading.
+ */
+export function skeletonizeBrief(source) {
+  const lines = String(source ?? "").split(/\r?\n/);
+  const out = [];
+  let i = skeletonFrontmatter(lines, out, BRIEF_CONTENT_KEYS);
+  for (; i < lines.length; i++) {
+    const heading = lines[i].match(/^##\s+(.+)$/);
+    if (heading) {
+      out.push(lines[i], "");
+      out.push(
+        `<fill in: this video's ${heading[1].trim().toLowerCase()} — the recipe keeps the shape, this run supplies the specifics.>`,
+      );
+      out.push("");
+    }
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+export function skeletonizeStoryboard(source) {
+  const lines = String(source ?? "").split(/\r?\n/);
+  const out = [];
+  const state = { inFrame: false, proseReplaced: false, title: "" };
+  for (let i = skeletonFrontmatter(lines, out); i < lines.length; i++) {
+    const line = lines[i];
+    if (/^#{2,3}\s/.test(line)) {
+      state.inFrame = FRAME_HEADING_RE.test(line);
+      state.proseReplaced = false;
+      state.title = state.inFrame ? frameTitle(line) : "";
+      out.push(line);
+    } else if (!state.inFrame) {
+      out.push(line);
+    } else {
+      skeletonFrameLine(line, state, out);
+    }
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+/** The run's workflow as BRIEF.md records it — the source of truth a freeze
+ * must not contradict. Undefined when no BRIEF.md (or no `workflow:`) exists. */
+function briefWorkflow(root) {
+  const brief = join(root, "BRIEF.md");
+  if (!existsSync(brief)) return undefined;
+  const lines = readFileSync(brief, "utf8").split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return undefined;
+  for (let i = 1; i < lines.length && lines[i].trim() !== "---"; i++) {
+    const match = lines[i].match(/^workflow\s*:\s*(.+?)\s*$/);
+    if (match) return match[1].replace(/^["']|["']$/g, "") || undefined;
+  }
+  return undefined;
+}
+
+function readRecipeJson(dir) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, "recipe.json"), "utf8"));
+    if (typeof parsed !== "object" || parsed === null || typeof parsed.name !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function prefValue(prefs, key) {
+  return prefs[key]?.value;
+}
+
+/**
+ * Freeze the current project's approved run as a named recipe. Writes the
+ * project-tier folder + a manifest record, then copies to the user tier (a
+ * freeze is already confirmed — it promotes immediately).
+ */
+export function freezeRecipe({ projectDir, name, workflow, blocks }) {
+  const slug = slugifyRecipeName(name);
+  const root = resolve(projectDir);
+  const fromBrief = briefWorkflow(root);
+  const fromFlag = workflow && String(workflow).trim() ? String(workflow).trim() : undefined;
+  // BRIEF.md decides; the flag only covers projects briefed before it existed.
+  const resolvedWorkflow = fromBrief ?? fromFlag;
+  if (!resolvedWorkflow) {
+    throw new Error("no workflow found — BRIEF.md names none and no --workflow was given");
+  }
+  const frameSpec = join(root, "frame.md");
+  const storyboard = join(root, "STORYBOARD.md");
+  if (!existsSync(frameSpec)) throw new Error("no frame.md to freeze — run the design step first");
+  if (!existsSync(storyboard)) throw new Error("no STORYBOARD.md to freeze");
+
+  const dir = join(projectRecipesDir(root), slug);
+  let version = 1;
+  const previous = existsSync(dir) ? readRecipeJson(dir) : null;
+  if (previous) {
+    version = (Number.isInteger(previous.version) ? previous.version : 1) + 1;
+    const archive = `${dir}@v${previous.version ?? 1}`;
+    rmSync(archive, { recursive: true, force: true });
+    renameSync(dir, archive);
+  }
+  mkdirSync(dir, { recursive: true });
+
+  const prefs = mergedPreferences(root);
+  const recipe = {
+    version,
+    name: slug,
+    workflow: resolvedWorkflow,
+    approved_at: new Date().toISOString(),
+    source_project: basename(root),
+    destination: prefValue(prefs, "destination"),
+    aspect: prefValue(prefs, "aspect"),
+    language: prefValue(prefs, "language"),
+    voice: prefValue(prefs, "voice"),
+    // The bare-key fallback tolerates records made before the store required
+    // style_preset to be workflow-scoped.
+    style_preset:
+      prefValue(prefs, `style_preset.${resolvedWorkflow}`) ?? prefValue(prefs, "style_preset"),
+    blocks: Array.isArray(blocks) && blocks.length > 0 ? blocks : undefined,
+  };
+
+  writeFileSync(join(dir, "recipe.json"), `${JSON.stringify(recipe, null, 2)}\n`);
+  cpSync(frameSpec, join(dir, "frame.md"));
+  writeFileSync(
+    join(dir, "storyboard-skeleton.md"),
+    `${skeletonizeStoryboard(readFileSync(storyboard, "utf8")).trimEnd()}\n`,
+  );
+
+  // Best-effort fourth artifact — projects briefed before BRIEF.md existed
+  // (or by workflows that don't write one) freeze fine without it.
+  const brief = join(root, "BRIEF.md");
+  const briefSkeleton = existsSync(brief);
+  if (briefSkeleton) {
+    writeFileSync(
+      join(dir, "brief-skeleton.md"),
+      `${skeletonizeBrief(readFileSync(brief, "utf8")).trimEnd()}\n`,
+    );
+  }
+
+  const id = nextId(root, "recipe");
+  appendRecord(root, {
+    id,
+    type: "recipe",
+    path: `.media/recipes/${slug}/recipe.json`,
+    entity: slug,
+    description: `recipe: ${slug} (${recipe.workflow}, v${version})`,
+    provenance: { provider: "recipe.freeze", version, source_project: recipe.source_project },
+  });
+  regenerateIndex(root);
+
+  // User tier — best-effort, like every other promotion.
+  try {
+    const userDir = join(userRecipesDir(), slug);
+    mkdirSync(userDir, { recursive: true });
+    cpSync(dir, userDir, { recursive: true, force: true });
+  } catch {
+    // The project-tier freeze already landed.
+  }
+
+  return {
+    id,
+    slug,
+    version,
+    dir,
+    briefSkeleton,
+    workflow: resolvedWorkflow,
+    workflowOverridden: Boolean(fromBrief && fromFlag && fromBrief !== fromFlag),
+  };
+}
+
+function scanRecipesDir(dir, source) {
+  if (!existsSync(dir)) return [];
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.includes("@v")) continue;
+    const recipe = readRecipeJson(join(dir, entry.name));
+    if (recipe) found.push({ ...recipe, source, dir: join(dir, entry.name) });
+  }
+  return found;
+}
+
+/** Two-tier merged listing (project wins), newest approval first. */
+export function listRecipes({ projectDir, workflow }) {
+  const merged = new Map();
+  for (const recipe of scanRecipesDir(userRecipesDir(), "user")) merged.set(recipe.name, recipe);
+  for (const recipe of scanRecipesDir(projectRecipesDir(resolve(projectDir)), "project")) {
+    merged.set(recipe.name, recipe);
+  }
+  let list = [...merged.values()];
+  if (workflow) list = list.filter((r) => r.workflow === workflow);
+  return list.sort((a, b) =>
+    String(b.approved_at ?? "").localeCompare(String(a.approved_at ?? "")),
+  );
+}
+
+/**
+ * Adopt a recipe into the current project: import the folder from the user
+ * tier when the project doesn't have it, copy its frame.md over the project's,
+ * and hand back the values + the skeleton path for the storyboard draft.
+ */
+export function useRecipe({ projectDir, name }) {
+  const slug = slugifyRecipeName(name);
+  const root = resolve(projectDir);
+  let dir = join(projectRecipesDir(root), slug);
+
+  if (!readRecipeJson(dir)) {
+    const userDir = join(userRecipesDir(), slug);
+    if (!readRecipeJson(userDir)) {
+      const known = listRecipes({ projectDir: root }).map((r) => r.name);
+      throw new Error(
+        `no recipe named "${slug}"${known.length ? ` (known: ${known.join(", ")})` : ""}`,
+      );
+    }
+    mkdirSync(dir, { recursive: true });
+    cpSync(userDir, dir, { recursive: true, force: true });
+    const imported = readRecipeJson(dir);
+    appendRecord(root, {
+      id: nextId(root, "recipe"),
+      type: "recipe",
+      path: `.media/recipes/${slug}/recipe.json`,
+      entity: slug,
+      description: `recipe: ${slug} (${imported.workflow}, v${imported.version})`,
+      provenance: { provider: "recipe.local", imported_from: "user-tier" },
+    });
+    regenerateIndex(root);
+  }
+
+  const recipe = readRecipeJson(dir);
+  cpSync(join(dir, "frame.md"), join(root, "frame.md"));
+  return {
+    recipe,
+    dir,
+    frameSpecPath: "frame.md",
+    skeletonPath: `.media/recipes/${slug}/storyboard-skeleton.md`,
+    // Recipes frozen before BRIEF.md existed have no brief skeleton — degrade.
+    briefSkeletonPath: existsSync(join(dir, "brief-skeleton.md"))
+      ? `.media/recipes/${slug}/brief-skeleton.md`
+      : undefined,
+  };
+}