From de6d7ca92bd6ab3ff51c80ab11ddbaf8b6ead388 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 18 Sep 2026 20:49:11 -0400
Subject: [PATCH 01/11] docs(skills): an agent adds media with the duration
 Studio gives a dropped file

---
 scripts/creator-editing-recipes.test.mjs      | 17 +++++++
 .../references/creator-editing-recipes.md     | 51 +++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index 5d00b4423c..5dcc5c2623 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -73,3 +73,20 @@ test("the Studio skill's safe boxes equal the preview's", async () => {
   assert.match(skill, new RegExp(`Action-safe\\s*\\|\\s*${action}%`));
   assert.match(skill, new RegExp(`Title-safe\\s*\\|\\s*${title}%`));
 });
+
+test("the add-media recipe matches Studio's own drop defaults", async () => {
+  const helpers = await read("packages/studio/src/utils/studioHelpers.ts");
+  const defaults = helpers.match(/DEFAULT_TIMELINE_ASSET_DURATION[^=]*=\s*\{([^}]*)\}/)?.[1] ?? "";
+  const secs = (kind) => defaults.match(new RegExp(`${kind}:\\s*(\\d+)`))?.[1];
+  const section = (await read(OWNER)).split("## Add media")[1]?.split("\n## ")[0] ?? "";
+  assert.ok(secs("image"), "could not read Studio's image default");
+  assert.match(section, new RegExp(`Image: \`data-duration="${secs("image")}"\``));
+  assert.match(section, new RegExp(`\`${secs("video")}\` only when the length cannot be read`));
+  const image = section.match(/<img[\s\S]*?\/>/)?.[0] ?? "";
+  assert.match(image, new RegExp(`data-duration="${secs("image")}"`));
+  const drop = await read("packages/studio/src/utils/timelineAssetDrop.ts");
+  for (const attr of ["class=\"clip\"", "data-start", "data-duration", "data-track-index"]) {
+    assert.ok(drop.includes(attr), `Studio no longer writes ${attr}`);
+    assert.ok(image.includes(attr.split("=")[0]), `doc example lacks ${attr}`);
+  }
+});
diff --git a/skills/hyperframes-core/references/creator-editing-recipes.md b/skills/hyperframes-core/references/creator-editing-recipes.md
index 74932476a5..67140c1714 100644
--- a/skills/hyperframes-core/references/creator-editing-recipes.md
+++ b/skills/hyperframes-core/references/creator-editing-recipes.md
@@ -417,6 +417,57 @@ Timeline math: an audio element in the root composition has `data-start` in abso
 
 Timeline math: pick the clips first and say which ones you picked (by id) if the request does not match the file exactly; then add one `delta` to every member's `data-start`, so relative spacing is preserved (here `delta = 40`). Give each copy a new unique `id` and the next unused `data-track-index`; keep `src`, `data-duration`, `data-media-start`, `data-volume` and any `data-automation` as they are. Leave the originals untouched. Check the copies still end inside the composition's duration. Owner: `/hyperframes-core`. Limit: copies of a `<video>` or a sub-composition host follow the same rule, and a copied sub-composition needs its own host `id`.
 
+## Add media (image, video, audio)
+
+Write exactly what Studio writes when a person drops a file on the timeline, so an agent-added clip behaves the same as a dropped one. Studio's source of truth is `DEFAULT_TIMELINE_ASSET_DURATION` in `packages/studio/src/utils/studioHelpers.ts` and `buildTimelineAssetInsertHtml` in `packages/studio/src/utils/timelineAssetDrop.ts`; a test keeps this section equal to them.
+
+- **Image: `data-duration="3"`.** A still has no length of its own, so it gets 3 seconds. Without a `data-duration` it never ends and stays on screen for the rest of the composition.
+- **Video and audio: the file's own length** in seconds (`ffprobe -v error -show_entries format=duration -of csv=p=0 file`); `5` only when the length cannot be read. Studio rounds to hundredths.
+- **Start: the playhead or the requested time, never a silent `0`.** Studio's asset-panel Add uses the playhead time on track `0`; a drop uses the drop point. Several files dropped together run end to end from the first start.
+- Give every clip `id`, `class="clip"`, `data-start`, `data-duration` and `data-track-index`. Video is `muted playsinline`; audio carries `data-volume="1"`.
+- Then make sure the root composition's `data-duration` is at least `data-start + data-duration`; Studio extends it, an agent must too, or the clip lies past the end and never plays.
+- Images and video sit absolutely positioned, `object-fit: contain`, centred at their natural size (scaled down to fit): `left = (frameWidth - width) / 2`, `top = (frameHeight - height) / 2`. Below, an 800x600 still in a 1920x1080 frame.
+
+```html
+<img
+  id="photo"
+  class="clip"
+  src="assets/photo.png"
+  data-start="4"
+  data-duration="3"
+  data-track-index="1"
+  style="position: absolute; left: 560px; top: 240px; width: 800px; height: 600px; object-fit: contain; z-index: 2"
+/>
+```
+
+```html
+<video
+  id="broll"
+  class="clip"
+  src="assets/broll.mp4"
+  data-start="4"
+  data-duration="6.5"
+  data-track-index="2"
+  muted
+  playsinline
+  style="position: absolute; left: 0px; top: 0px; width: 1920px; height: 1080px; object-fit: contain; z-index: 3"
+></video>
+```
+
+```html
+<audio
+  id="whoosh"
+  class="clip"
+  src="assets/whoosh.mp3"
+  data-start="4"
+  data-duration="1.2"
+  data-track-index="3"
+  data-volume="1"
+></audio>
+```
+
+Inside a sub-composition file, `data-start` is scene-local (see `## Align a sound to an on-screen event`). Owner: `/hyperframes-core`.
+
 ## Swap a media file
 
 ```html

From 849a59b235e2b03ef377e58d7336ecfd54f6c551 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 18 Sep 2026 21:06:39 -0400
Subject: [PATCH 02/11] docs(skills): add-media recipe matches Studio's
 full-frame geometry and z-index

---
 scripts/creator-editing-recipes.test.mjs               |  6 +++++-
 .../references/creator-editing-recipes.md              | 10 ++++++----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index 5dcc5c2623..9d6c57ebad 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -77,13 +77,17 @@ test("the Studio skill's safe boxes equal the preview's", async () => {
 test("the add-media recipe matches Studio's own drop defaults", async () => {
   const helpers = await read("packages/studio/src/utils/studioHelpers.ts");
   const defaults = helpers.match(/DEFAULT_TIMELINE_ASSET_DURATION[^=]*=\s*\{([^}]*)\}/)?.[1] ?? "";
-  const secs = (kind) => defaults.match(new RegExp(`${kind}:\\s*(\\d+)`))?.[1];
+  const secs = (kind) => defaults.match(new RegExp(`${kind}:\\s*(\\d+(?:\\.\\d+)?)`))?.[1];
   const section = (await read(OWNER)).split("## Add media")[1]?.split("\n## ")[0] ?? "";
   assert.ok(secs("image"), "could not read Studio's image default");
   assert.match(section, new RegExp(`Image: \`data-duration="${secs("image")}"\``));
   assert.match(section, new RegExp(`\`${secs("video")}\` only when the length cannot be read`));
   const image = section.match(/<img[\s\S]*?\/>/)?.[0] ?? "";
   assert.match(image, new RegExp(`data-duration="${secs("image")}"`));
+  const dropOps = await read("packages/studio/src/hooks/useTimelineAssetDropOps.ts");
+  assert.match(dropOps, /fitTimelineAssetGeometry\(\s*null,/, "Studio centres by natural size now; update the doc");
+  assert.match(section, /fill the whole frame/);
+  assert.match(image, /left: 0px; top: 0px; width: 1920px; height: 1080px/);
   const drop = await read("packages/studio/src/utils/timelineAssetDrop.ts");
   for (const attr of ["class=\"clip\"", "data-start", "data-duration", "data-track-index"]) {
     assert.ok(drop.includes(attr), `Studio no longer writes ${attr}`);
diff --git a/skills/hyperframes-core/references/creator-editing-recipes.md b/skills/hyperframes-core/references/creator-editing-recipes.md
index 67140c1714..292103daf0 100644
--- a/skills/hyperframes-core/references/creator-editing-recipes.md
+++ b/skills/hyperframes-core/references/creator-editing-recipes.md
@@ -423,10 +423,12 @@ Write exactly what Studio writes when a person drops a file on the timeline, so
 
 - **Image: `data-duration="3"`.** A still has no length of its own, so it gets 3 seconds. Without a `data-duration` it never ends and stays on screen for the rest of the composition.
 - **Video and audio: the file's own length** in seconds (`ffprobe -v error -show_entries format=duration -of csv=p=0 file`); `5` only when the length cannot be read. Studio rounds to hundredths.
-- **Start: the playhead or the requested time, never a silent `0`.** Studio's asset-panel Add uses the playhead time on track `0`; a drop uses the drop point. Several files dropped together run end to end from the first start.
+- **Start: the playhead or the requested time, never a silent `0`.** Studio's asset-panel Add uses the playhead time on track `0`; a drop uses the drop point.
 - Give every clip `id`, `class="clip"`, `data-start`, `data-duration` and `data-track-index`. Video is `muted playsinline`; audio carries `data-volume="1"`.
-- Then make sure the root composition's `data-duration` is at least `data-start + data-duration`; Studio extends it, an agent must too, or the clip lies past the end and never plays.
-- Images and video sit absolutely positioned, `object-fit: contain`, centred at their natural size (scaled down to fit): `left = (frameWidth - width) / 2`, `top = (frameHeight - height) / 2`. Below, an 800x600 still in a 1920x1080 frame.
+- Then make sure the root composition's `data-duration` is at least `data-start + data-duration`: Studio raises a declared root duration to cover the new clip, so an agent must too, or the clip lies past the end and never plays.
+- **Images and video fill the whole frame**: absolutely positioned at `left: 0; top: 0`, `width` and `height` equal to the composition's `data-width` and `data-height`, `object-fit: contain`. Studio does not know a dropped file's natural size, so it does not centre a smaller one.
+- `z-index` is the number of top-level clips already in that file plus one (at least `1`); later clips stack above earlier ones.
+- Several files dropped together share the drop's track and run end to end.
 
 ```html
 <img
@@ -436,7 +438,7 @@ Write exactly what Studio writes when a person drops a file on the timeline, so
   data-start="4"
   data-duration="3"
   data-track-index="1"
-  style="position: absolute; left: 560px; top: 240px; width: 800px; height: 600px; object-fit: contain; z-index: 2"
+  style="position: absolute; left: 0px; top: 0px; width: 1920px; height: 1080px; object-fit: contain; z-index: 2"
 />
 ```
 

From 4be3b5018d612ee69bfe1cd965fd06e88e80bbec Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 18 Sep 2026 21:36:10 -0400
Subject: [PATCH 03/11] docs(skills): recipes start with hyperframes timeline
 to see tracks and clips

---
 skills/hyperframes-core/references/creator-editing-recipes.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/skills/hyperframes-core/references/creator-editing-recipes.md b/skills/hyperframes-core/references/creator-editing-recipes.md
index 292103daf0..62a2fb31f8 100644
--- a/skills/hyperframes-core/references/creator-editing-recipes.md
+++ b/skills/hyperframes-core/references/creator-editing-recipes.md
@@ -2,6 +2,8 @@
 
 Use these copyable contracts after `tracks-and-clips.md`. Global math: **consumed source = timeline duration × rate**; **natural timeline duration = remaining source / rate**.
 
+Before any edit, run `npx hyperframes timeline` (add `--json` for a machine-readable list) to see the project's tracks and clips instead of reading the HTML.
+
 These recipes keep sound on a separate `<audio>` element with the `<video>` muted, which is the pattern to reach for when picture and sound are cut independently. An unmuted `<video>` that declares `data-has-audio="true"` is also mixed, so a separate track is a choice, not a requirement.
 
 **Every `<video>` and `<audio>` below carries an `id`, and that is not cosmetic**: `lint` errors with `media_missing_id` on timed media without one, and an id-less `<audio>` is never picked up by the mixer, so the render comes out silent. Keep the ids when you copy a recipe.

From 457b739835796be53c3c12ca30a4f0210ba824ea Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 18 Sep 2026 23:48:15 -0400
Subject: [PATCH 04/11] test(skills): split the add-media drift test so each
 check stays small and formatted

---
 scripts/creator-editing-recipes.test.mjs | 25 ++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index 9d6c57ebad..1aa12ae85f 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -74,22 +74,39 @@ test("the Studio skill's safe boxes equal the preview's", async () => {
   assert.match(skill, new RegExp(`Title-safe\\s*\\|\\s*${title}%`));
 });
 
-test("the add-media recipe matches Studio's own drop defaults", async () => {
+async function addMediaFacts() {
   const helpers = await read("packages/studio/src/utils/studioHelpers.ts");
   const defaults = helpers.match(/DEFAULT_TIMELINE_ASSET_DURATION[^=]*=\s*\{([^}]*)\}/)?.[1] ?? "";
   const secs = (kind) => defaults.match(new RegExp(`${kind}:\\s*(\\d+(?:\\.\\d+)?)`))?.[1];
   const section = (await read(OWNER)).split("## Add media")[1]?.split("\n## ")[0] ?? "";
+  const image = section.match(/<img[\s\S]*?\/>/)?.[0] ?? "";
+  return { secs, section, image };
+}
+
+test("the add-media recipe uses Studio's default durations", async () => {
+  const { secs, section, image } = await addMediaFacts();
   assert.ok(secs("image"), "could not read Studio's image default");
   assert.match(section, new RegExp(`Image: \`data-duration="${secs("image")}"\``));
   assert.match(section, new RegExp(`\`${secs("video")}\` only when the length cannot be read`));
-  const image = section.match(/<img[\s\S]*?\/>/)?.[0] ?? "";
   assert.match(image, new RegExp(`data-duration="${secs("image")}"`));
+});
+
+test("the add-media recipe uses Studio's full-frame geometry", async () => {
+  const { section, image } = await addMediaFacts();
   const dropOps = await read("packages/studio/src/hooks/useTimelineAssetDropOps.ts");
-  assert.match(dropOps, /fitTimelineAssetGeometry\(\s*null,/, "Studio centres by natural size now; update the doc");
+  assert.match(
+    dropOps,
+    /fitTimelineAssetGeometry\(\s*null,/,
+    "Studio centres by natural size now; update the doc",
+  );
   assert.match(section, /fill the whole frame/);
   assert.match(image, /left: 0px; top: 0px; width: 1920px; height: 1080px/);
+});
+
+test("the add-media example carries every attribute Studio's drop writes", async () => {
+  const { image } = await addMediaFacts();
   const drop = await read("packages/studio/src/utils/timelineAssetDrop.ts");
-  for (const attr of ["class=\"clip\"", "data-start", "data-duration", "data-track-index"]) {
+  for (const attr of ['class="clip"', "data-start", "data-duration", "data-track-index"]) {
     assert.ok(drop.includes(attr), `Studio no longer writes ${attr}`);
     assert.ok(image.includes(attr.split("=")[0]), `doc example lacks ${attr}`);
   }

From b05675911b44eadea8f0cca51b03e9da3a78cfbf Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 00:26:30 -0400
Subject: [PATCH 05/11] test(skills): split addMediaFacts into single-purpose
 helpers to clear the CRAP-score gate

---
 scripts/creator-editing-recipes.test.mjs | 36 +++++++++++++++---------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index 1aa12ae85f..10ea430386 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -74,25 +74,35 @@ test("the Studio skill's safe boxes equal the preview's", async () => {
   assert.match(skill, new RegExp(`Title-safe\\s*\\|\\s*${title}%`));
 });
 
-async function addMediaFacts() {
+async function studioDefaultSeconds(kind) {
   const helpers = await read("packages/studio/src/utils/studioHelpers.ts");
-  const defaults = helpers.match(/DEFAULT_TIMELINE_ASSET_DURATION[^=]*=\s*\{([^}]*)\}/)?.[1] ?? "";
-  const secs = (kind) => defaults.match(new RegExp(`${kind}:\\s*(\\d+(?:\\.\\d+)?)`))?.[1];
-  const section = (await read(OWNER)).split("## Add media")[1]?.split("\n## ")[0] ?? "";
-  const image = section.match(/<img[\s\S]*?\/>/)?.[0] ?? "";
-  return { secs, section, image };
+  const block = helpers.match(/DEFAULT_TIMELINE_ASSET_DURATION[^=]*=\s*\{([^}]*)\}/);
+  const defaults = block ? block[1] : "";
+  const value = defaults.match(new RegExp(`${kind}:\\s*(\\d+(?:\\.\\d+)?)`));
+  return value ? value[1] : undefined;
+}
+
+async function addMediaSection() {
+  const doc = await read(OWNER);
+  const afterHeading = doc.split("## Add media")[1] ?? "";
+  const section = afterHeading.split("\n## ")[0];
+  const imageMatch = section.match(/<img[\s\S]*?\/>/);
+  const image = imageMatch ? imageMatch[0] : "";
+  return { section, image };
 }
 
 test("the add-media recipe uses Studio's default durations", async () => {
-  const { secs, section, image } = await addMediaFacts();
-  assert.ok(secs("image"), "could not read Studio's image default");
-  assert.match(section, new RegExp(`Image: \`data-duration="${secs("image")}"\``));
-  assert.match(section, new RegExp(`\`${secs("video")}\` only when the length cannot be read`));
-  assert.match(image, new RegExp(`data-duration="${secs("image")}"`));
+  const { section, image } = await addMediaSection();
+  const imageSecs = await studioDefaultSeconds("image");
+  const videoSecs = await studioDefaultSeconds("video");
+  assert.ok(imageSecs, "could not read Studio's image default");
+  assert.match(section, new RegExp(`Image: \`data-duration="${imageSecs}"\``));
+  assert.match(section, new RegExp(`\`${videoSecs}\` only when the length cannot be read`));
+  assert.match(image, new RegExp(`data-duration="${imageSecs}"`));
 });
 
 test("the add-media recipe uses Studio's full-frame geometry", async () => {
-  const { section, image } = await addMediaFacts();
+  const { section, image } = await addMediaSection();
   const dropOps = await read("packages/studio/src/hooks/useTimelineAssetDropOps.ts");
   assert.match(
     dropOps,
@@ -104,7 +114,7 @@ test("the add-media recipe uses Studio's full-frame geometry", async () => {
 });
 
 test("the add-media example carries every attribute Studio's drop writes", async () => {
-  const { image } = await addMediaFacts();
+  const { image } = await addMediaSection();
   const drop = await read("packages/studio/src/utils/timelineAssetDrop.ts");
   for (const attr of ['class="clip"', "data-start", "data-duration", "data-track-index"]) {
     assert.ok(drop.includes(attr), `Studio no longer writes ${attr}`);

From 74814d6f4f54103bd9fdf11ee2f7c66b58ab53a0 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 03:30:41 -0400
Subject: [PATCH 06/11] docs(skills): add-media recipe needs only data-start
 for video and audio

---
 scripts/creator-editing-recipes.test.mjs                  | 5 +++--
 .../references/creator-editing-recipes.md                 | 8 +++-----
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index 10ea430386..2b17b914f3 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -94,10 +94,11 @@ async function addMediaSection() {
 test("the add-media recipe uses Studio's default durations", async () => {
   const { section, image } = await addMediaSection();
   const imageSecs = await studioDefaultSeconds("image");
-  const videoSecs = await studioDefaultSeconds("video");
   assert.ok(imageSecs, "could not read Studio's image default");
   assert.match(section, new RegExp(`Image: \`data-duration="${imageSecs}"\``));
-  assert.match(section, new RegExp(`\`${videoSecs}\` only when the length cannot be read`));
+  assert.match(section, /`data-start` is enough/);
+  assert.doesNotMatch(section, /ffprobe/);
+  assert.match(section, /root composition's `data-duration` is at least/);
   assert.match(image, new RegExp(`data-duration="${imageSecs}"`));
 });
 
diff --git a/skills/hyperframes-core/references/creator-editing-recipes.md b/skills/hyperframes-core/references/creator-editing-recipes.md
index 62a2fb31f8..e72d59a114 100644
--- a/skills/hyperframes-core/references/creator-editing-recipes.md
+++ b/skills/hyperframes-core/references/creator-editing-recipes.md
@@ -424,10 +424,10 @@ Timeline math: pick the clips first and say which ones you picked (by id) if the
 Write exactly what Studio writes when a person drops a file on the timeline, so an agent-added clip behaves the same as a dropped one. Studio's source of truth is `DEFAULT_TIMELINE_ASSET_DURATION` in `packages/studio/src/utils/studioHelpers.ts` and `buildTimelineAssetInsertHtml` in `packages/studio/src/utils/timelineAssetDrop.ts`; a test keeps this section equal to them.
 
 - **Image: `data-duration="3"`.** A still has no length of its own, so it gets 3 seconds. Without a `data-duration` it never ends and stays on screen for the rest of the composition.
-- **Video and audio: the file's own length** in seconds (`ffprobe -v error -show_entries format=duration -of csv=p=0 file`); `5` only when the length cannot be read. Studio rounds to hundredths.
+- **Video and audio: `data-start` is enough.** The length comes from the media itself. An authored `data-duration` shorter than the file is a trim, never a requirement; leave it out unless the request asks for a shorter clip.
 - **Start: the playhead or the requested time, never a silent `0`.** Studio's asset-panel Add uses the playhead time on track `0`; a drop uses the drop point.
-- Give every clip `id`, `class="clip"`, `data-start`, `data-duration` and `data-track-index`. Video is `muted playsinline`; audio carries `data-volume="1"`.
-- Then make sure the root composition's `data-duration` is at least `data-start + data-duration`: Studio raises a declared root duration to cover the new clip, so an agent must too, or the clip lies past the end and never plays.
+- Give every clip `id`, `class="clip"`, `data-start` and `data-track-index` (an image also `data-duration`). Video is `muted playsinline`; audio carries `data-volume="1"`.
+- Then make sure the root composition's `data-duration` is at least the clip's end (`data-start` plus its length: 3 for an image, the media's length for video and audio): Studio raises a declared root duration to cover the new clip, so an agent must too, or the clip lies past the end and never plays.
 - **Images and video fill the whole frame**: absolutely positioned at `left: 0; top: 0`, `width` and `height` equal to the composition's `data-width` and `data-height`, `object-fit: contain`. Studio does not know a dropped file's natural size, so it does not centre a smaller one.
 - `z-index` is the number of top-level clips already in that file plus one (at least `1`); later clips stack above earlier ones.
 - Several files dropped together share the drop's track and run end to end.
@@ -450,7 +450,6 @@ Write exactly what Studio writes when a person drops a file on the timeline, so
   class="clip"
   src="assets/broll.mp4"
   data-start="4"
-  data-duration="6.5"
   data-track-index="2"
   muted
   playsinline
@@ -464,7 +463,6 @@ Write exactly what Studio writes when a person drops a file on the timeline, so
   class="clip"
   src="assets/whoosh.mp3"
   data-start="4"
-  data-duration="1.2"
   data-track-index="3"
   data-volume="1"
 ></audio>

From ad273ce72d1edf9fb13cf0a1163f45959f92f86c Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 03:56:20 -0400
Subject: [PATCH 07/11] docs(skills): add-media intro names the video and audio
 difference and a test guards it

---
 scripts/creator-editing-recipes.test.mjs             | 12 ++++++++++++
 .../references/creator-editing-recipes.md            |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index 2b17b914f3..e2715d5a80 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -122,3 +122,15 @@ test("the add-media example carries every attribute Studio's drop writes", async
     assert.ok(image.includes(attr.split("=")[0]), `doc example lacks ${attr}`);
   }
 });
+
+test("the video and audio add-media examples carry no data-duration and keep the clip attributes", async () => {
+  const { section } = await addMediaSection();
+  for (const tag of ["video", "audio"]) {
+    const example = section.match(new RegExp(`<${tag}[\\s\\S]*?</${tag}>`))?.[0] ?? "";
+    assert.ok(example, `no <${tag}> example`);
+    assert.doesNotMatch(example, /data-duration/, `${tag} example must not author a duration`);
+    for (const attr of ["id=", 'class="clip"', "data-start", "data-track-index"]) {
+      assert.ok(example.includes(attr), `${tag} example lacks ${attr}`);
+    }
+  }
+});
diff --git a/skills/hyperframes-core/references/creator-editing-recipes.md b/skills/hyperframes-core/references/creator-editing-recipes.md
index e72d59a114..14d4f40a15 100644
--- a/skills/hyperframes-core/references/creator-editing-recipes.md
+++ b/skills/hyperframes-core/references/creator-editing-recipes.md
@@ -421,7 +421,7 @@ Timeline math: pick the clips first and say which ones you picked (by id) if the
 
 ## Add media (image, video, audio)
 
-Write exactly what Studio writes when a person drops a file on the timeline, so an agent-added clip behaves the same as a dropped one. Studio's source of truth is `DEFAULT_TIMELINE_ASSET_DURATION` in `packages/studio/src/utils/studioHelpers.ts` and `buildTimelineAssetInsertHtml` in `packages/studio/src/utils/timelineAssetDrop.ts`; a test keeps this section equal to them.
+Write what Studio writes when a person drops a file on the timeline, so an agent-added clip behaves the same as a dropped one; the one difference is that video and audio need no `data-duration`. Studio's source of truth is `DEFAULT_TIMELINE_ASSET_DURATION` in `packages/studio/src/utils/studioHelpers.ts` and `buildTimelineAssetInsertHtml` in `packages/studio/src/utils/timelineAssetDrop.ts`; a test keeps this section equal to them.
 
 - **Image: `data-duration="3"`.** A still has no length of its own, so it gets 3 seconds. Without a `data-duration` it never ends and stays on screen for the rest of the composition.
 - **Video and audio: `data-start` is enough.** The length comes from the media itself. An authored `data-duration` shorter than the file is a trim, never a requirement; leave it out unless the request asks for a shorter clip.

From 4423ecbc74fd4078628ace29265eea1d754c4e78 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 04:28:42 -0400
Subject: [PATCH 08/11] docs(skills): add-media image duration is optional and
 defaults to 3 seconds

---
 scripts/creator-editing-recipes.test.mjs                  | 8 +++++---
 .../references/creator-editing-recipes.md                 | 7 +++----
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index e2715d5a80..2614991ad0 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -95,11 +95,11 @@ test("the add-media recipe uses Studio's default durations", async () => {
   const { section, image } = await addMediaSection();
   const imageSecs = await studioDefaultSeconds("image");
   assert.ok(imageSecs, "could not read Studio's image default");
-  assert.match(section, new RegExp(`Image: \`data-duration="${imageSecs}"\``));
+  assert.match(section, new RegExp(`defaults to ${imageSecs} seconds`));
   assert.match(section, /`data-start` is enough/);
   assert.doesNotMatch(section, /ffprobe/);
   assert.match(section, /root composition's `data-duration` is at least/);
-  assert.match(image, new RegExp(`data-duration="${imageSecs}"`));
+  assert.doesNotMatch(image, /data-duration/);
 });
 
 test("the add-media recipe uses Studio's full-frame geometry", async () => {
@@ -119,7 +119,9 @@ test("the add-media example carries every attribute Studio's drop writes", async
   const drop = await read("packages/studio/src/utils/timelineAssetDrop.ts");
   for (const attr of ['class="clip"', "data-start", "data-duration", "data-track-index"]) {
     assert.ok(drop.includes(attr), `Studio no longer writes ${attr}`);
-    assert.ok(image.includes(attr.split("=")[0]), `doc example lacks ${attr}`);
+  }
+  for (const attr of ['class="clip"', "data-start", "data-track-index"]) {
+    assert.ok(image.includes(attr), `doc example lacks ${attr}`);
   }
 });
 
diff --git a/skills/hyperframes-core/references/creator-editing-recipes.md b/skills/hyperframes-core/references/creator-editing-recipes.md
index 14d4f40a15..6977324653 100644
--- a/skills/hyperframes-core/references/creator-editing-recipes.md
+++ b/skills/hyperframes-core/references/creator-editing-recipes.md
@@ -423,11 +423,11 @@ Timeline math: pick the clips first and say which ones you picked (by id) if the
 
 Write what Studio writes when a person drops a file on the timeline, so an agent-added clip behaves the same as a dropped one; the one difference is that video and audio need no `data-duration`. Studio's source of truth is `DEFAULT_TIMELINE_ASSET_DURATION` in `packages/studio/src/utils/studioHelpers.ts` and `buildTimelineAssetInsertHtml` in `packages/studio/src/utils/timelineAssetDrop.ts`; a test keeps this section equal to them.
 
-- **Image: `data-duration="3"`.** A still has no length of its own, so it gets 3 seconds. Without a `data-duration` it never ends and stays on screen for the rest of the composition.
+- **Image: `data-duration` is optional and defaults to 3 seconds**, the same as a dropped image, because a still has no length of its own. Write it only for another length. A test keeps the 3 equal to the default in code.
 - **Video and audio: `data-start` is enough.** The length comes from the media itself. An authored `data-duration` shorter than the file is a trim, never a requirement; leave it out unless the request asks for a shorter clip.
 - **Start: the playhead or the requested time, never a silent `0`.** Studio's asset-panel Add uses the playhead time on track `0`; a drop uses the drop point.
-- Give every clip `id`, `class="clip"`, `data-start` and `data-track-index` (an image also `data-duration`). Video is `muted playsinline`; audio carries `data-volume="1"`.
-- Then make sure the root composition's `data-duration` is at least the clip's end (`data-start` plus its length: 3 for an image, the media's length for video and audio): Studio raises a declared root duration to cover the new clip, so an agent must too, or the clip lies past the end and never plays.
+- Give every clip `id`, `class="clip"`, `data-start` and `data-track-index`. Video is `muted playsinline`; audio carries `data-volume="1"`.
+- Then make sure the root composition's `data-duration` is at least the clip's end (`data-start` plus its length: 3 for an image unless you set another, the media's length for video and audio): Studio raises a declared root duration to cover the new clip, so an agent must too, or the clip lies past the end and never plays.
 - **Images and video fill the whole frame**: absolutely positioned at `left: 0; top: 0`, `width` and `height` equal to the composition's `data-width` and `data-height`, `object-fit: contain`. Studio does not know a dropped file's natural size, so it does not centre a smaller one.
 - `z-index` is the number of top-level clips already in that file plus one (at least `1`); later clips stack above earlier ones.
 - Several files dropped together share the drop's track and run end to end.
@@ -438,7 +438,6 @@ Write what Studio writes when a person drops a file on the timeline, so an agent
   class="clip"
   src="assets/photo.png"
   data-start="4"
-  data-duration="3"
   data-track-index="1"
   style="position: absolute; left: 0px; top: 0px; width: 1920px; height: 1080px; object-fit: contain; z-index: 2"
 />

From bbe604352163c5ae43c7277a89fdf84e795d71f4 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 04:43:35 -0400
Subject: [PATCH 09/11] chore(skills): regenerate the skills manifest after
 rebasing onto main

---
 skills-manifest.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index 0f9e21c193..09f7233eff 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -34,7 +34,7 @@
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "ca3bc11c4e163225",
+      "hash": "cea1f2632dd66290",
       "files": 11
     },
     "hyperframes-creative": {

From 210a34d66067e463f00e786f1c93f483bf5ef01b Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 05:19:15 -0400
Subject: [PATCH 10/11] docs(skills): tracks-and-clips says image duration is
 optional, and a test pins the 3

---
 scripts/creator-editing-recipes.test.mjs               | 1 +
 skills-manifest.json                                   | 2 +-
 skills/hyperframes-core/references/tracks-and-clips.md | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index 2614991ad0..c964bda1c8 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -99,6 +99,7 @@ test("the add-media recipe uses Studio's default durations", async () => {
   assert.match(section, /`data-start` is enough/);
   assert.doesNotMatch(section, /ffprobe/);
   assert.match(section, /root composition's `data-duration` is at least/);
+  assert.match(section, new RegExp(`${imageSecs} for an image unless you set another`));
   assert.doesNotMatch(image, /data-duration/);
 });
 
diff --git a/skills-manifest.json b/skills-manifest.json
index 09f7233eff..b1789536e0 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -34,7 +34,7 @@
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "cea1f2632dd66290",
+      "hash": "99a07539f407ca0d",
       "files": 11
     },
     "hyperframes-creative": {
diff --git a/skills/hyperframes-core/references/tracks-and-clips.md b/skills/hyperframes-core/references/tracks-and-clips.md
index 9d0996c692..e9231d0131 100644
--- a/skills/hyperframes-core/references/tracks-and-clips.md
+++ b/skills/hyperframes-core/references/tracks-and-clips.md
@@ -10,7 +10,7 @@ A clip is any DOM element with `data-start` and, where required, `data-duration`
 - **Sub-composition hosts** — `<div>` with `data-composition-src`. Always require `data-duration`.
 - **Video clips** — `<video>` with `muted` and `playsinline`. Duration can default to media length.
 - **Audio clips** — `<audio>`. Duration can default to media length.
-- **Image clips** — `<img>`. Always require `data-duration`.
+- **Image clips** — `<img>`. `data-duration` is optional and defaults to 3 seconds; write it only for another length.
 
 Add `class="clip"` to authored visual clips. The runtime does not read it, but the scaffold's shared `.clip { position: absolute; inset: 0 }` rule is what gives a scene its full-frame box, Studio treats it as an edit hint, and `lint` warns without it.
 

From d0f48c541f64d1d28efeae7f1cf47bef7fe2a506 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 08:23:01 -0400
Subject: [PATCH 11/11] test(skills): split the add-media example check into
 small helpers

Clears the Fallow complexity finding on the test callback.
---
 scripts/creator-editing-recipes.test.mjs | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/scripts/creator-editing-recipes.test.mjs b/scripts/creator-editing-recipes.test.mjs
index c964bda1c8..a1fa442b94 100644
--- a/scripts/creator-editing-recipes.test.mjs
+++ b/scripts/creator-editing-recipes.test.mjs
@@ -126,14 +126,25 @@ test("the add-media example carries every attribute Studio's drop writes", async
   }
 });
 
+const CLIP_ATTRS = ["id=", 'class="clip"', "data-start", "data-track-index"];
+
+const mediaExample = (section, tag) =>
+  section.match(new RegExp(`<${tag}[\\s\\S]*?</${tag}>`))?.[0] ?? "";
+
+const assertNoAuthoredDuration = (example, tag) => {
+  assert.ok(example, `no <${tag}> example`);
+  assert.doesNotMatch(example, /data-duration/, `${tag} example must not author a duration`);
+};
+
+const assertHasAttrs = (example, tag, attrs) => {
+  for (const attr of attrs) assert.ok(example.includes(attr), `${tag} example lacks ${attr}`);
+};
+
 test("the video and audio add-media examples carry no data-duration and keep the clip attributes", async () => {
   const { section } = await addMediaSection();
   for (const tag of ["video", "audio"]) {
-    const example = section.match(new RegExp(`<${tag}[\\s\\S]*?</${tag}>`))?.[0] ?? "";
-    assert.ok(example, `no <${tag}> example`);
-    assert.doesNotMatch(example, /data-duration/, `${tag} example must not author a duration`);
-    for (const attr of ["id=", 'class="clip"', "data-start", "data-track-index"]) {
-      assert.ok(example.includes(attr), `${tag} example lacks ${attr}`);
-    }
+    const example = mediaExample(section, tag);
+    assertNoAuthoredDuration(example, tag);
+    assertHasAttrs(example, tag, CLIP_ATTRS);
   }
 });