@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/references/resolve.md

@@ -0,0 +1,150 @@
+# Resolve — command, flags, reuse, adopt, inventory
+
+```bash
+npx hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>
+```
+
+Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
+
+## Types
+
+| Type    | What it finds                    | Provider / cascade                                           |
+| ------- | -------------------------------- | ------------------------------------------------------------ |
+| `bgm`   | Background music                 | HeyGen audio catalog (10k+ tracks)                           |
+| `sfx`   | Sound effects                    | Bundled 19-file library + HeyGen catalog                     |
+| `image` | Photos, backgrounds              | HeyGen asset search (75k+ vectors)                           |
+| `icon`  | Icons, symbols                   | HeyGen asset search (type=icon)                              |
+| `logo`  | Official brand marks             | theSVG → GitHub org avatar → domain favicon                  |
+| `voice` | TTS voiceover                    | HeyGen TTS free-usage path; optional local Kokoro            |
+| `grade` | HyperFrames color-grading blocks | Core preset → look index params/CDN LUT → deterministic cube |
+| `lut`   | Reusable `.cube` LUT files       | Look index params/CDN LUT → deterministic cube               |
+
+## Examples
+
+```bash
+# Background music
+npx hyperframes media-use resolve --type bgm --intent "upbeat tech launch" --project .
+# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
+
+# Sound effect
+npx hyperframes media-use resolve --type sfx --intent "whoosh" --project .
+# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
+
+# Image
+npx hyperframes media-use resolve --type image --intent "gradient tech background" --project .
+# → resolved image_001 → .media/images/image_001.jpg (image)
+
+# Icon
+npx hyperframes media-use resolve --type icon --intent "rocket" --project .
+# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
+
+# Brand logo (official mark — never redrawn by hand)
+npx hyperframes media-use resolve --type logo --entity linkedin --intent "LinkedIn logo" --project .
+# → resolved logo_001 → .media/images/logo_001.svg (logo, official mark)
+
+# Color grade block
+npx hyperframes media-use resolve --type grade --intent "warm daylight" --project . --json
+# → {"ok":true,"preset":"warm-daylight","grading":{"preset":"warm-daylight","intensity":1},...}
+
+# LUT file
+npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project .
+# → resolved lut_001 → .media/luts/lut_001.cube (lut)
+```
+
+## Flags
+
+| Flag            | Description                                                                          |
+| --------------- | ------------------------------------------------------------------------------------ |
+| `--type, -t`    | Media type: bgm, sfx, image, icon, logo, voice, grade, lut                           |
+| `--intent, -i`  | What you need (natural language)                                                     |
+| `--entity, -e`  | Entity name for cache matching (optional)                                            |
+| `--project, -p` | Project directory (default: .)                                                       |
+| `--candidates`  | List reusable assets (project + global cache) for `--type`; no download, no mutation |
+| `--reuse <sha>` | Import a specific global-cache asset (by content sha/prefix, from `--candidates`)    |
+| `--from`        | Freeze a local file or direct public URL (ingest)                                    |
+| `--for`         | Analyze a local image/video and add measured adjust suggestions (`grade` only)       |
+| `--local-only`  | Offline: skip every network provider (cache + local only)                            |
+| `--provider`    | Force one generator (e.g. `codex`, `mflux`, `kokoro`, `heygen`)                      |
+| `--adopt`       | Bulk-import existing assets/ into manifest                                           |
+| `--doctor`      | Check local CLI dependencies; no manifest changes                                    |
+| `--stats`       | Print local usage stats from `.media/` and `~/.media`; no manifest changes           |
+| `--days N`      | Limit `--stats` to timestamped records/misses from the last N days                   |
+| `--json`        | Output JSON instead of one-line result                                               |
+
+## Reuse before you resolve
+
+Before resolving bgm/sfx/image/icon/logo/grade/lut, **check what already exists and reuse it when it fits.** media-use does not semantically match for you — you are the judge. It surfaces candidates; you decide.
+
+```bash
+npx hyperframes media-use resolve --type bgm --intent "upbeat tech launch" --candidates --project .
+#   [project] upbeat tech launch (25s, heygen.audio.sounds)
+#           .media/audio/bgm/bgm_001.wav
+#   [global]  energetic tech intro (22s, heygen.audio.sounds)
+#           --reuse 06e052c075fd2b80
+```
+
+Read the list and judge semantic fit yourself — "upbeat tech launch" ≈ "energetic tech intro" is a call only you can make from the descriptions. Then:
+
+- **A project candidate fits** → just reference its path in your composition. Nothing else to run.
+- **A global candidate fits** → `resolve --type bgm --reuse <sha>` copies it into this project (self-contained render) and records it.
+- **Nothing fits** → resolve fresh (`--type ... --intent ...`).
+
+**Trust guardrail — when unsure, resolve fresh.** A redundant download is cheap; shipping the wrong asset is not. Judge fit from description + prompt + type + duration/dims. For **brand/entity** assets, reuse a _global_ candidate only when the entity matches exactly — the global cache aggregates every project you have worked on, so a `--candidates` list can surface another client's brand mark and its prompt text. Never reuse a cross-project brand asset on a loose match.
+
+The deterministic floor still runs automatically: an identical (case/whitespace-insensitive) repeat auto-reuses with no `--candidates` step. `--candidates` is only for the semantic layer above that floor — and a fuzzy match is **never** auto-applied; reuse is always your explicit call. On a resolve that misses the floor and is about to fetch, media-use prints a one-line stderr hint when similar cached assets exist, pointing you back here.
+
+## How it works
+
+`resolve` runs an automatic floor, then falls through to fetching:
+
+1. Check project `.media/manifest.jsonl` for a prompt match (case- and whitespace-insensitive) — auto-reuse
+2. Scan existing `assets/` directory for unregistered files that share a word with the need
+3. Check global cache `~/.media/` for a reusable asset matched on the same normalized prompt — auto-reuse
+4. Search via provider (HeyGen audio catalog, HeyGen asset search), or resolve color locally
+5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`, auto-promote to `~/.media/`
+
+Steps 1 and 3 are the **deterministic floor**: they only auto-reuse an exact-normalized match, never a fuzzy one. Semantic reuse ("close enough") is the agent's explicit call via [Reuse before you resolve](#reuse-before-you-resolve) — it never happens automatically. The agent gets back **one line**; candidates, scores, provenance stay on disk.
+
+## Stamping provenance when mounting a resolved video
+
+`resolve` never writes composition HTML itself — mounting a `<video>` element
+into a composition is always the agent's own edit. When the mounted video's
+manifest record has `provenance.provider === "heygen.video"` (check
+`.media/manifest.jsonl` or the one-line resolve output for the provider name),
+add `data-media-source="heygen"` to that `<video>` tag. Leave the attribute off
+entirely for every other provider (`ltx.local`, an adopted/local file, etc.) —
+this is not a general provider taxonomy, just the one signal render telemetry
+tracks today.
+
+## Adopt existing projects
+
+Most HyperFrames projects already have assets in `assets/`. media-use adopts them:
+
+```bash
+npx hyperframes media-use resolve --adopt --project .
+# → adopted 9 assets from assets/
+#   bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
+#   image_001 → assets/images/avatar.jpg (image, 400×400)
+```
+
+`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.
+
+## Reading the inventory
+
+After resolve or adopt, read `.media/index.md` for the full inventory:
+
+```
+# .media · 4 assets
+
+id         type   dur   dims       path                          description
+bgm_001    bgm    25s   -          .media/audio/bgm/bgm_001.mp3  upbeat tech launch
+sfx_001    sfx    0.6s  -          .media/audio/sfx/sfx_001.mp3  whoosh
+image_001  image  -     1920×1080  .media/images/image_001.jpg   gradient tech background
+icon_001   icon   -     200×200    .media/images/icon_001.png    rocket
+```
+
+## Cross-project reuse
+
+Assets are cached automatically on resolve. Every resolved/ingested asset is auto-promoted to the global cache at `~/.media/`, so subsequent resolves for the same (or near-identical) prompt, in any project, hit the cache with no re-download and no provider call.
+
+For a _semantically_ similar (not identical) need in another project, the exact-match floor won't fire — use [Reuse before you resolve](#reuse-before-you-resolve): `--candidates` lists the global assets, and `--reuse <sha>` imports the one you pick. This is how a track resolved in one project gets reused in the next when the wording differs.

package/vendor/hyperframes/dist/skills/media-use/references/setup-providers.md

@@ -0,0 +1,80 @@
+# Setup and providers — install, auth, RAM ladders, forcing a provider
+
+## Setup — install heygen first (free-usage path)
+
+Install the HeyGen CLI through its [verified release instructions](https://developers.heygen.com/cli), then run:
+
+```bash
+heygen update             # free usage needs the OAuth-capable CLI (v0.3.0+)
+heygen auth login --oauth # OAuth = free subscription credits; --api-key bills API credits
+```
+
+This unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
+
+```bash
+npx hyperframes media-use resolve --doctor
+```
+
+## Providers
+
+media-use holds no keys; every external tool owns its auth. Generation is
+centered on the HeyGen CLI free-usage path. Install and authenticate `heygen`
+before resolving bgm/sfx/image/icon/voice/avatar-video. Local tools are opt-in
+alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
+transcription, and LTX for local video generation. `resolve` spec-checks
+AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
+see the ladder and override.
+
+| Type      | Provider / path                                                                                                                                                               |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| bgm/sfx   | heygen catalog free-usage path                                                                                                                                                |
+| image     | heygen search free-usage path; optional local mflux; codex `image_gen` upsell                                                                                                 |
+| voice     | heygen tts free-usage path; optional local **Kokoro** (free, on-device)                                                                                                       |
+| icon      | heygen asset search free-usage path                                                                                                                                           |
+| logo      | theSVG (thesvg.org), then GitHub org avatar, then domain favicon (all free)                                                                                                   |
+| grade/lut | local core-preset map, params/CDN look index, deterministic `buildCube` fallback                                                                                              |
+| video     | heygen avatar video free-usage path (sign-in nudge on auth failure); optional local LTX (`videogen` ladder). Image-to-video / photo-avatar / dub stay manual `heygen` recipes |
+
+Local Kokoro (voice), mflux (image), and LTX (video) run on-device (free,
+private, offline once cached). The `codex` CLI remains the ChatGPT-sub image
+upsell. Cost rule (X4): the agent confirms before an agent-initiated paid call;
+a user-requested one just runs — `heygen.video` is flagged paid (metered free
+allowance) so an agent-initiated `resolve --type video` confirms first.
+
+To force a specific generator (e.g. a user says "make this image with codex"),
+pass `--provider codex`: it pins resolution to that provider and skips the
+free-usage default. See `references/operations.md` for the RAM ladders and
+provider recipes.
+
+`--local-only` skips every network provider, including the free HeyGen ones,
+leaving the project + global cache and any installed local provider. For
+HeyGen-only types, that means no fresh resolve.
+
+## CLI tools used (what to run, and how to enable each)
+
+`resolve` auto-cascades; each provider shells one CLI. HeyGen is the
+free-usage path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar
+video, so those capabilities need `heygen` installed and authenticated. Local
+tools are OPT-IN alternatives where they exist; install one to unlock its free,
+private, on-device path instead of or ahead of HeyGen for that type. Only
+`ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
+
+| Tool               | Serves                                                                          | Install                                                                                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm                | system package (`brew install ffmpeg`)                                                                                                                                                      |
+| `heygen`           | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0)                                               |
+| `mflux-generate`   | local image gen (FLUX), best-for-RAM                                            | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                                                                                          |
+| `codex`            | image gen upsell (ChatGPT sub)                                                  | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                                                                                        |
+| `parakeet-mlx`     | local transcription (default ASR, best) on Apple Silicon                        | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`                                                                                                    |
+| `ltx-2-mlx`        | local video gen                                                                 | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras`                                                                                                    |
+| `npx hyperframes`  | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background     | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
+
+The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
+`scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`
+to see which model fits this machine). Without a tool on PATH, its provider
+prints a one-line diagnostic to stderr and resolve falls through where another
+provider exists (e.g. no `mflux` -> codex image upsell; no `parakeet-mlx` -> whisper.cpp).
+
+`heygen asset search` is a pre-launch command hidden from `heygen --help`, but it
+runs; providers tag requests with the allowlisted `X-HeyGen-Client-Source` header
+(v0.3.0+).

package/vendor/hyperframes/dist/skills/media-use/references/telemetry-dashboard.md

@@ -0,0 +1,49 @@
+# media-use usage dashboard
+
+Reproducible definition of the media-use usage dashboard. The dashboard answers
+"how much is media-use used, for what, is reuse working, and what can't it
+satisfy" from the telemetry `scripts/lib/telemetry.mjs` already emits. Build it
+in an authorized HyperFrames analytics project; this doc is the source of truth
+so it can be recreated. Local complement: `resolve --stats` (same questions,
+from `.media/` + `~/.media`, no dashboard access needed).
+
+## Identity (see `scripts/lib/telemetry.mjs`)
+
+Events attribute to the **same person as the hyperframes CLI and studio**
+— the shared install id in `~/.hyperframes/config.json` (`anonymousId`), stitched
+to the HeyGen account (`$identify`, `distinct_id` = email/username) on sign-in.
+Not fully anonymous by design; pseudonymous before sign-in, account-linked after.
+`$ip:null`. Opt-out: `HYPERFRAMES_NO_TELEMETRY=1` / `DO_NOT_TRACK=1` (also CI, dev).
+
+## Event catalog (verified present in-project)
+
+Every event carries `surface: "media-use"`. Event **properties are coarse** —
+never intent text, file names, or paths.
+
+| Event                                                                  | Fires on                                  | Key properties                                                         |
+| ---------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
+| `media_use_resolve`                                                    | a resolve that produced/returned an asset | `type`, `source`, `provider`, `via`, `local_only`, `provider_override` |
+| `media_use_resolve_miss`                                               | a resolve that found nothing              | `type`, `local_only`, `provider_override` (no intent)                  |
+| `media_use_candidates`                                                 | `--candidates` / `--dry-run` listing      | `type`, counts                                                         |
+| `media_use_doctor_run`                                                 | `--doctor`                                | `ok`, `checks_failed`, `failed[]`                                      |
+| `media_use_compare`                                                    | `grade-compare` / `compare`               | `command`, `cells`, `truncated`, `total`, `render_ready_timed_out`     |
+| `media_use_transcribe` · `media_use_duck` · `media_use_transcript_cut` | audio-engine ops                          | op-specific                                                            |
+
+## Dashboard tiles
+
+1. **Invocation volume** — `query-trends`, count of `media_use_resolve` over time (daily). "How much."
+2. **By media type** — `media_use_resolve` broken down by `type` (bgm/sfx/image/icon/logo/voice/grade/lut). "For what."
+3. **Resolve hit-rate** — trends formula: `A / (A + B)` where A = `media_use_resolve`, B = `media_use_resolve_miss`. "Is the catalog covering needs."
+4. **Provider mix** — `media_use_resolve` broken down by `provider`; a second tile by `via` (`url` / `params-fallback` / `params`) to catch CDN→params LUT downgrades.
+5. **Top misses** — `media_use_resolve_miss` broken down by `type` (the tuning signal — pair with local `resolve --stats`, which also shows the missed _intents_ that telemetry deliberately omits).
+6. **Doctor health** — `media_use_doctor_run` broken down by `failed[]` (which dependency check fails most) + `checks_failed` distribution.
+7. **Compare cost** — `media_use_compare` by `command`, plus `truncated` / `render_ready_timed_out` rates (observe before lifting the 16-cell cap).
+8. **Adoption (optional)** — if the `first_run` property ships (plan U5), segment `media_use_resolve` first-run vs repeat.
+
+## Recreate in an analytics dashboard
+
+For each tile, confirm the event/property schema, build its trend or breakdown,
+then add it to a dashboard. Keep names prefixed `media-use:` so the dashboard is
+greppable. Cross-surface note: because identity is shared with CLI/studio, you
+can also break these down by the same person across `cli_command*` and `studio:*`
+events.

package/vendor/hyperframes/dist/skills/media-use/scripts/audio-duck.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { duckKeyframes, duckLane, speechSpans } from "./lib/duck.mjs";
+import { track } from "./lib/telemetry.mjs";
+
+const { values: args } = parseArgs({
+  options: {
+    meta: { type: "string" },
+    target: { type: "string" },
+    duck: { type: "string", default: "0.25" },
+    attack: { type: "string", default: "0.15" },
+    release: { type: "string", default: "0.4" },
+    "merge-gap": { type: "string", default: "0.6" },
+    sequential: { type: "boolean", default: false },
+    gap: { type: "string", default: "0" },
+    offsets: { type: "string" },
+    composition: { type: "string" },
+    json: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  strict: true,
+});
+
+if (args.help) {
+  console.log(`media-use audio-duck — generate a volume ducking lane (data-automation)
+
+Usage:
+  node audio-duck.mjs --meta audio_meta.json --target "#bgm"
+
+Options:
+  --meta          audio_meta.json or JSON word transcript
+  --target        GSAP selector for the background audio element
+  --duck          Duck multiplier (default: 0.25)
+  --attack        Duck-in duration seconds (default: 0.15)
+  --release       Restore duration seconds (default: 0.4)
+  --merge-gap     Bridge speech gaps smaller than this many seconds (default: 0.6)
+  --sequential    Place multi-line meta back to back at composition time
+  --gap           Extra seconds between sequential lines (default: 0)
+  --offsets       Explicit placement, "l1=0,l2=3.4" (voice id = start seconds)
+  --composition   Read target data-volume and data-start from this HTML file
+  --json          Output { spans, keyframes, lane }
+  --help, -h      Show this help`);
+  process.exit(0);
+}
+
+try {
+  run();
+  await track("media_use_duck", { sequential: !!args.sequential });
+} catch (err) {
+  if (args.json) console.log(JSON.stringify({ ok: false, error: err.message }));
+  else console.error(`error: ${err.message}`);
+  process.exit(1);
+}
+
+function run() {
+  if (!args.meta || !args.target) throw new Error("--meta and --target are required");
+  const meta = JSON.parse(readFileSync(resolve(args.meta), "utf8"));
+  const target = args.target;
+  const { baseVolume, clipStart } = readTargetAttrs(args.composition, target);
+  const offsets = args.offsets
+    ? Object.fromEntries(
+        args.offsets.split(",").map((pair) => {
+          const [id, t] = pair.split("=");
+          return [id.trim(), Number(t)];
+        }),
+      )
+    : undefined;
+  const spans = speechSpans(meta, {
+    mergeGap: Number(args["merge-gap"]),
+    sequential: args.sequential,
+    gap: Number(args.gap),
+    offsets,
+  });
+  const keyframes = duckKeyframes(spans, {
+    duck: Number(args.duck),
+    attack: Number(args.attack),
+    release: Number(args.release),
+    baseVolume,
+  });
+
+  const lane = duckLane(keyframes, { clipStart, baseVolume });
+
+  if (args.json) {
+    console.log(JSON.stringify({ spans, keyframes, lane }));
+    return;
+  }
+
+  console.log(`<!-- auto-duck: ${target} under narration; add to its <audio> element -->`);
+  console.log(`data-automation='${JSON.stringify(lane)}'`);
+}
+
+function readTargetAttrs(composition, target) {
+  if (!composition || !target.startsWith("#")) return { baseVolume: 1, clipStart: 0 };
+  const id = target.slice(1);
+  const html = readFileSync(resolve(composition), "utf8");
+  // ponytail: regex is enough here because this only reads one attribute from
+  // one user-authored composition element, not arbitrary HTML.
+  const tag = html.match(new RegExp(`<[^>]*\\bid=["']${escapeRegExp(id)}["'][^>]*>`, "i"))?.[0];
+  const attr = (name) => Number(tag?.match(new RegExp(`\\b${name}=["']([^"']+)["']`, "i"))?.[1]);
+  const volume = attr("data-volume");
+  const start = attr("data-start");
+  return {
+    baseVolume: Number.isFinite(volume) ? volume : 1,
+    clipStart: Number.isFinite(start) ? start : 0,
+  };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/compatibility.test.mjs

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+
+process.env.HYPERFRAMES_MEDIA_HOME = mkdtempSync(join(tmpdir(), "media-use-compat-home-"));
+
+function run(scriptsDir, script, args) {
+  return execFileSync(process.execPath, [join(scriptsDir, script), ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+test("published memory scripts run without reaching outside the skill", () => {
+  const scratchDir = mkdtempSync(join(tmpdir(), "media-use-compat-"));
+  const skillDir = join(scratchDir, "media-use");
+  cpSync(new URL("..", import.meta.url), skillDir, { recursive: true });
+  const scriptsDir = join(skillDir, "scripts");
+  const projectDir = join(scratchDir, "project");
+  try {
+    run(scriptsDir, "prefs.mjs", ["get", "--hyperframes", projectDir, "--json"]);
+    run(scriptsDir, "recipe.mjs", ["list", "--hyperframes", projectDir, "--json"]);
+    run(scriptsDir, "transcribe.mjs", ["--help"]);
+  } finally {
+    rmSync(scratchDir, { recursive: true, force: true });
+  }
+});
+
+test("published audio helpers import without the CLI package tree", () => {
+  const root = mkdtempSync(join(tmpdir(), "media-use-audio-"));
+  const skill = join(root, "media-use");
+  try {
+    cpSync(new URL("..", import.meta.url), skill, { recursive: true });
+    for (const helper of ["heygen.mjs", "tts.mjs"])
+      run(join(skill, "audio/scripts/lib"), helper, []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+for (const name of ["faceless-explainer", "pr-to-video", "product-launch-video"]) {
+  test(name + " assembles from its installed directory alone", () => {
+    const root = mkdtempSync(join(tmpdir(), "installed-workflow-"));
+    try {
+      const skill = join(root, name);
+      cpSync(new URL("../../" + name, import.meta.url), skill, { recursive: true });
+      const project = join(root, "project");
+      mkdirSync(join(project, "compositions/frames"), { recursive: true });
+      writeFileSync(
+        join(project, "STORYBOARD.md"),
+        "---\nformat: 1920x1080\nmessage: Test\n---\n\n## Frame 1\n- duration: 3s\n- src: compositions/frames/01-a.html\n",
+      );
+      writeFileSync(
+        join(project, "compositions/frames/01-a.html"),
+        '<template><div data-composition-id="01-a" data-duration="3" data-width="1920" data-height="1080"><section class="clip" data-start="0" data-duration="3"></section></div></template>',
+      );
+      run(join(skill, "scripts"), "assemble-index.mjs", [
+        "--hyperframes",
+        project,
+        "--storyboard",
+        join(project, "STORYBOARD.md"),
+      ]);
+      assert.match(readFileSync(join(project, "index.html"), "utf8"), /01-a/);
+      importPacketBuilder(join(skill, "scripts/frame-packets.mjs"));
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
+
+test("general-video packet builder starts from its installed directory alone", () => {
+  const root = mkdtempSync(join(tmpdir(), "installed-packets-"));
+  try {
+    cpSync(new URL("../../general-video", import.meta.url), root, { recursive: true });
+    importPacketBuilder(join(root, "scripts/frame-packets.mjs"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+function importPacketBuilder(path) {
+  execFileSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "-e",
+      'const m = await import(process.argv[1]); if (typeof m.buildFramePackets !== "function") throw new Error("missing builder");',
+      pathToFileURL(path).href,
+    ],
+    { stdio: "pipe" },
+  );
+}