dsh-hyperframes 0.3.1 → 0.4.0

package/skills/media-use/references/grading.md

@@ -20,7 +20,7 @@ assemble those from a generic LUT plus handmade CSS vignette/grain/opacity.
 **Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
+npx hyperframes media-use resolve --type grade --intent "warm daylight" --project . --json
 ```
 
 Preset-first output uses the core runtime vocabulary and does not freeze a file:
@@ -93,7 +93,7 @@ For a reusable color transform beyond the preset vocabulary, freeze a validated
 `.cube` under `.media/luts/` and return a block that references it:
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "teal orange blockbuster" --project . --json
+npx hyperframes media-use resolve --type grade --intent "teal orange blockbuster" --project . --json
 ```
 
 ```json
@@ -106,20 +106,20 @@ node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "teal orange blockbus
 Use `lut` when you only need the reusable `.cube` file:
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
+npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project .
 ```
 
 For a describable technical look, author an explicit parametric LUT with `--params`:
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type lut --params '{"contrast":0.2,"temperature":-0.3}' --project .
-node <SKILL_DIR>/scripts/resolve.mjs --type grade --params '{"exposure":0.2}' --project . --json
+npx hyperframes media-use resolve --type lut --params '{"contrast":0.2,"temperature":-0.3}' --project .
+npx hyperframes media-use resolve --type grade --params '{"exposure":0.2}' --project . --json
 ```
 
 For a LUT generated by your own script, ingest it with `--from`; media-use validates it before registration and rejects invalid or oversized cubes:
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type lut --from custom.cube --project .
+npx hyperframes media-use resolve --type lut --from custom.cube --project .
 ```
 
 Parametric math (`buildCube`) cannot reproduce real film stocks or emulsion
@@ -155,6 +155,6 @@ validates generated or downloaded cubes as it freezes them under
 `.media/luts/`.
 
 ```bash
-node skills/media-use/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project . --json
+npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project . --json
 node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
 ```

package/skills/media-use/references/media-treatment-recipes.md

@@ -784,7 +784,7 @@ node <SKILL_DIR>/scripts/dither.mjs \
   --palette '#17121a,#824c50,#e09873,#f7ddb1' \
   --point-size 3
 
-node <SKILL_DIR>/scripts/resolve.mjs \
+npx hyperframes media-use resolve \
   --from .media/generated/video_001.atkinson.mp4 --type video --project .
 ```
 

package/skills/media-use/references/memory.md

@@ -10,7 +10,7 @@ node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key destination --va
 node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key style_preset --value pin-and-paper --workflow faceless-explainer
 ```
 
-Only what the user actually confirmed gets recorded — never an inferred or defaulted value. How workflows consume these (a remembered value becomes the recommended default with a receipt, and never skips a question) is the brief contract's rule: `hyperframes-core/references/brief-contract.md` § 2, Remembered defaults.
+Only what the user actually confirmed gets recorded — never an inferred or defaulted value. How workflows consume these (a remembered value becomes the recommended default with a receipt, and never skips a question) is the brief contract's rule: `hyperframes/references/brief-contract.md` § 2, Remembered defaults.
 
 ## Recipes — frozen video bundles
 
@@ -22,7 +22,7 @@ node <SKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow product-laun
 node <SKILL_DIR>/scripts/recipe.mjs use --hyperframes . --name weekly-promo   # also: resolve.mjs --type recipe --entity weekly-promo
 ```
 
-The freeze is offered once after the final approval (`hyperframes-core/references/review-loop.md` § 4), and the intent layer (`/hyperframes` → `references/intent-interview.md`, step 1) checks for a match before its first question. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.
+The freeze is offered once after the final approval (`hyperframes/references/review-loop.md` § 4), and the intent layer (`/hyperframes` → `references/intent-interview.md`, step 1) checks for a match before its first question. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.
 
 ## Files
 

package/skills/media-use/references/meta.md

@@ -9,7 +9,7 @@ HyperFrames owns media _playback_; media-use owns everything else. Each row is e
 | HyperFrames gap                            | media-use owns it via                                                                                                                                                                                                                                                               |
 | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                                                                                                                                                                  |
-| No third-party brand logos                 | `resolve --type logo` (svgl → simple-icons → GitHub org avatar → domain favicon)                                                                                                                                                                                                    |
+| No third-party brand logos                 | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon)                                                                                                                                                                                                                 |
 | No voice / audio generation                | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`)                                                                                                                                                           |
 | Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                                                                                                                                                                  |
 | No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                                                                                                                                                                   |
@@ -26,7 +26,7 @@ HyperFrames owns media _playback_; media-use owns everything else. Each row is e
 Use `resolve --stats` for a local, shareable report over the current project's `.media/` manifest, the global `~/.media/` cache, and local resolve misses. Human output is compact; add `--json` for a single machine-readable object, and `--days N` to window timestamped records.
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --stats --project . --days 7
+npx hyperframes media-use resolve --stats --project . --days 7
 # media-use stats
 # total resolves: 12
 # misses: 2

package/skills/media-use/references/operations.md

@@ -79,7 +79,7 @@ node <SKILL_DIR>/scripts/dither.mjs \
   --palette '#0f380f,#306230,#8bac0f,#9bbc0f' \
   --point-size 3
 
-node <SKILL_DIR>/scripts/resolve.mjs \
+npx hyperframes media-use resolve \
   --from source.atkinson.mp4 --type video --project .
 ```
 
@@ -112,14 +112,16 @@ engine directly.
 # install once: uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx
 node <SKILL_DIR>/scripts/transcribe.mjs --input talk.mp4 --out talk.transcribe.json
 
-# equivalently, the hyperframes CLI has Parakeet built in (auto-detects it, whisper fallback):
+# the hyperframes CLI runs Parakeet on macOS, Linux and Windows once it is installed:
+npx hyperframes models install parakeet                 # once, ~640 MB, ask the user first
 npx hyperframes transcribe talk.mp4 --engine parakeet   # or --engine auto (default)
 ```
 
-VERIFIED on 24GB: accurate, ~3s (cached) for 8s audio. Parakeet covers English +
-25 European languages. For other languages, or when parakeet-mlx is not
-installed, transcribe.mjs auto-falls-back to whisper.cpp (99 languages) via
-`hyperframes transcribe`. `--engine parakeet|whisper` forces one. (Cohere
+VERIFIED on 24GB: accurate, ~3s (cached) for 8s audio. Parakeet covers 25
+European languages, English included. For other languages, or when parakeet-mlx is not
+installed, transcribe.mjs falls back to `hyperframes transcribe`, which uses the
+CLI's Parakeet when `models install parakeet` has run and whisper.cpp (99
+languages) otherwise. `--engine parakeet|whisper` forces one. (Cohere
 Transcribe tops the leaderboard on paper but its mlx-audio quants produced
 garbage and ran 40-70x slower on a Mac in testing, so it is not wired in.)
 
@@ -145,9 +147,10 @@ Use `--plan` first when you want to inspect the kept segment JSON before encodin
 
 ## Ducking (declare in-composition / bake for export)
 
-B1, declare ducking in the composition. `audio-duck.mjs` emits GSAP volume
-keyframes. Paste them into the composition timeline, the source file stays
-untouched.
+B1, declare ducking in the composition. `audio-duck.mjs` emits a volume lane
+as a `data-automation` attribute. Add it to the background `<audio>` element;
+the source file stays untouched. Lane times are clip-local, so pass
+`--composition` to let the script subtract the element's `data-start`.
 
 ```bash
 node <SKILL_DIR>/scripts/audio-duck.mjs \
@@ -156,10 +159,9 @@ node <SKILL_DIR>/scripts/audio-duck.mjs \
   --composition index.html
 ```
 
-```js
-// auto-duck: #bgm under narration (generated; base volume 0.6)
-tl.to("#bgm", { volume: 0.15, duration: 0.15 }, 3.42);
-tl.to("#bgm", { volume: 0.6, duration: 0.4 }, 9.87);
+```html
+<!-- auto-duck: #bgm under narration; add to its <audio> element -->
+data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":0.6},{"t":3.42,"v":0.6},{"t":3.57,"v":0.15},{"t":9.87,"v":0.15},{"t":10.27,"v":0.6}]}]}'
 ```
 
 B2, bake ducking only for exported or standalone files.

package/skills/media-use/references/resolve.md

@@ -1,7 +1,7 @@
 # Resolve — command, flags, reuse, adopt, inventory
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
+npx hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>
 ```
 
 Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
@@ -14,7 +14,7 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
 | `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             | svgl → simple-icons → GitHub org avatar → domain favicon     |
+| `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               |
@@ -23,31 +23,31 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
 
 ```bash
 # Background music
-node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
+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
-node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
+npx hyperframes media-use resolve --type sfx --intent "whoosh" --project .
 # → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
 
 # Image
-node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
+npx hyperframes media-use resolve --type image --intent "gradient tech background" --project .
 # → resolved image_001 → .media/images/image_001.jpg (image)
 
 # Icon
-node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
+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)
-node <SKILL_DIR>/scripts/resolve.mjs --type logo --entity linkedin --intent "LinkedIn logo" --project .
+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
-node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
+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
-node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
+npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project .
 # → resolved lut_001 → .media/luts/lut_001.cube (lut)
 ```
 
@@ -76,7 +76,7 @@ node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuste
 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
-node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --candidates --project .
+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)
@@ -105,12 +105,23 @@ The deterministic floor still runs automatically: an identical (case/whitespace-
 
 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
-node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
+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)

package/skills/media-use/references/setup-providers.md

@@ -12,7 +12,7 @@ heygen auth login --oauth # OAuth = free subscription credits; --api-key bills A
 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
-node <SKILL_DIR>/scripts/resolve.mjs --doctor
+npx hyperframes media-use resolve --doctor
 ```
 
 ## Providers
@@ -31,7 +31,7 @@ see the ladder and override.
 | 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      | svgl, then simple-icons, then GitHub org avatar, then domain favicon (all free)                                                                                               |
+| 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 |
 
@@ -59,15 +59,15 @@ 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)                                         | `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), whisper.cpp (transcribe fallback), remove-background        | via the hyperframes CLI; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake), models download from HuggingFace              |
+| 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)`

package/skills/media-use/scripts/audio-duck.mjs

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { duckKeyframes, speechSpans } from "./lib/duck.mjs";
+import { duckKeyframes, duckLane, speechSpans } from "./lib/duck.mjs";
 import { track } from "./lib/telemetry.mjs";
 
 const { values: args } = parseArgs({
@@ -25,7 +25,7 @@ const { values: args } = parseArgs({
 });
 
 if (args.help) {
-  console.log(`media-use audio-duck — generate GSAP volume ducking keyframes
+  console.log(`media-use audio-duck — generate a volume ducking lane (data-automation)
 
 Usage:
   node audio-duck.mjs --meta audio_meta.json --target "#bgm"
@@ -40,8 +40,8 @@ Options:
   --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 from this HTML file
-  --json          Output { spans, keyframes }
+  --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);
 }
@@ -59,7 +59,7 @@ 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 = readBaseVolume(args.composition, target);
+  const { baseVolume, clipStart } = readTargetAttrs(args.composition, target);
   const offsets = args.offsets
     ? Object.fromEntries(
         args.offsets.split(",").map((pair) => {
@@ -81,41 +81,33 @@ function run() {
     baseVolume,
   });
 
+  const lane = duckLane(keyframes, { clipStart, baseVolume });
+
   if (args.json) {
-    console.log(JSON.stringify({ spans, keyframes }));
+    console.log(JSON.stringify({ spans, keyframes, lane }));
     return;
   }
 
-  console.log(
-    `// auto-duck: ${target} under narration (generated; base volume ${fmt(baseVolume)})`,
-  );
-  for (const keyframe of keyframes) {
-    console.log(
-      `tl.to(${JSON.stringify(target)}, { volume: ${fmt(keyframe.volume)}, duration: ${fmt(
-        keyframe.duration,
-      )} }, ${fmt(keyframe.time)});`,
-    );
-  }
+  console.log(`<!-- auto-duck: ${target} under narration; add to its <audio> element -->`);
+  console.log(`data-automation='${JSON.stringify(lane)}'`);
 }
 
-function readBaseVolume(composition, target) {
-  if (!composition || !target.startsWith("#")) return 1;
+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 raw = tag?.match(/\bdata-volume=["']([^"']+)["']/i)?.[1];
-  const volume = Number(raw);
-  return Number.isFinite(volume) ? volume : 1;
+  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, "\\$&");
 }
-
-function fmt(n) {
-  return Number(n)
-    .toFixed(3)
-    .replace(/\.?0+$/, "");
-}

package/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" },
+  );
+}

package/skills/media-use/scripts/lib/config-lock.mjs

@@ -0,0 +1,45 @@
+// The one lock on ~/.hyperframes/config.json, for the CLI, its auto-update step and media-use. The auto-update step
+// embeds this function's source, so it must use only its arguments and globals.
+export function withFileLock(lockPath, fs, task) {
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const started = Date.now();
+  for (;;) {
+    let fd;
+    try {
+      fd = fs.openSync(lockPath, "wx");
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      // Never taken over: a lock older than any hold was left by a process that stopped, and a person removes it.
+      let leftover = false;
+      try {
+        leftover = Date.now() - fs.statSync(lockPath).mtimeMs > 5000;
+      } catch {}
+      if (leftover || Date.now() - started > 10000)
+        throw Object.assign(
+          new Error(
+            `Settings are locked by another hyperframes process. If none is running, delete ${lockPath}`,
+          ),
+          { code: "HF_SETTINGS_LOCKED" },
+        );
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+      continue;
+    }
+    try {
+      fs.writeSync(fd, token);
+    } catch (error) {
+      fs.rmSync(lockPath, { force: true });
+      throw error;
+    } finally {
+      fs.closeSync(fd);
+    }
+    break;
+  }
+  try {
+    return task();
+  } finally {
+    // No code removes another's lock, so release needs no check (only a person deleting a live one defeats it).
+    try {
+      fs.rmSync(lockPath);
+    } catch {}
+  }
+}

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

@@ -1,15 +1,6 @@
 import { wordListsFromMediaMeta } from "./words.mjs";
 
-/**
- * Speech spans from word timestamps.
- *
- * audio_meta.json word times are relative to EACH LINE'S OWN FILE, not to the
- * composition. Without placement info, multiple lines would overlap at t=0 and
- * merge into one bogus span. Placement options:
- *   offsets:    { [voiceId]: startSeconds } explicit composition placement
- *   sequential: stack lines back to back (plus `gap` seconds between lines)
- * A single word list (bare transcript) needs neither.
- */
+// audio_meta.json word times are relative to each line's own file.
 export function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false, gap = 0 } = {}) {
   const merge = Number(mergeGap);
   const lists = wordListsFromMediaMeta(meta);
@@ -63,6 +54,21 @@ export function duckKeyframes(
   return keyframes.sort((a, b) => a.time - b.time);
 }
 
+/** Volume lane for `data-automation`: composition-time keyframes as clip-local ramps. */
+export function duckLane(keyframes, { clipStart = 0, baseVolume = 1 } = {}) {
+  const start = finiteOr(clipStart, 0);
+  const points = [{ t: 0, v: round3(finiteOr(baseVolume, 1)) }];
+  const push = (t, v) => {
+    if (t > points.at(-1).t) points.push({ t: round3(t), v });
+  };
+  for (const kf of keyframes) {
+    const t = Math.max(0, kf.time - start);
+    push(t, points.at(-1).v);
+    push(t + kf.duration, kf.volume);
+  }
+  return { version: 1, lanes: [{ target: "volume", points }] };
+}
+
 function mergeIntervals(intervals, mergeGap) {
   const sorted = intervals
     .map((range) => ({ start: round3(range.start), end: round3(range.end) }))