From 05ddddbbf08fd358b5879726f935d5414733da3a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 3 Nov 2026 03:13:11 +0000
Subject: [PATCH] docs(skills): reverse tops up once for the run's total and
 inits with --video (#7048)

* docs(skills): reverse asks to top up once for the run's total

* docs(skills): reverse builds the project with init --video

* test(skills): pin reverse's init --video and top-up-once wording

* docs(skills): a refusal with no amount runs a plain top-up
---
 scripts/check-core-skills.test.mjs           | 14 ++++++++++++++
 skills-manifest.json                         |  2 +-
 skills/reverse-any-video/SKILL.md            |  2 +-
 skills/reverse-any-video/references/start.md | 18 +++++++++++-------
 4 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/scripts/check-core-skills.test.mjs b/scripts/check-core-skills.test.mjs
index 47c6dd4caf..2022f7f106 100644
--- a/scripts/check-core-skills.test.mjs
+++ b/scripts/check-core-skills.test.mjs
@@ -31,6 +31,20 @@ test("the paid-plan cloud final keeps the composition fps and high quality", ()
   }
 });
 
+test("reverse builds the project with init --video and asks to top up once for the run's total", () => {
+  const read = (path) =>
+    readFileSync(new URL(`../skills/reverse-any-video/${path}`, import.meta.url), "utf8");
+  const start = read("references/start.md");
+  assert.match(
+    start,
+    /`npx hyperframes init <project> --video <video> --keep-original --skip-transcribe`/,
+  );
+  assert.match(start, /add up what each refused step\s+needs, and ask once for that total/);
+  assert.match(start, /billing top-up --needed <total>|--needed <total>/);
+  assert.doesNotMatch(read("SKILL.md"), /copy the video into the project/);
+  assert.match(read("SKILL.md"), /`init --video` put the video in/);
+});
+
 test("reads the registered commands, quoted or not", () => {
   const source = `const commandLoaders = {\n  init: () => x,\n  "catch-up": () => y,\n};`;
   assert.deepEqual([...registeredCommands(source)], ["init", "catch-up"]);
diff --git a/skills-manifest.json b/skills-manifest.json
index 071ed6abbc..6401e6083d 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -26,7 +26,7 @@
       "files": 76
     },
     "reverse-any-video": {
-      "hash": "fe326730ec89a06b",
+      "hash": "20cf059946029bbb",
       "files": 5
     },
     "slideshow": {
diff --git a/skills/reverse-any-video/SKILL.md b/skills/reverse-any-video/SKILL.md
index 388d640ea8..28f58c5ea1 100644
--- a/skills/reverse-any-video/SKILL.md
+++ b/skills/reverse-any-video/SKILL.md
@@ -15,7 +15,7 @@ Reverse is a HyperFrames Pro feature: go on only on a paid plan, not Free. Open
 
 1. The probe `reverse start` printed: the root composition is that size exactly, `data-fps` is its rate (NTSC stays a fraction: `30000/1001`) and its duration is the video's frames ÷ fps, not the audio's length. `init`'s default canvas is wrong for most videos.
 2. `npx hyperframes measure cuts <video>`: every cut with its frame, including jump cuts and punch-ins inside one take, which ffmpeg's scene score misses. Every shot starts at its listed time. Write times as frame ÷ fps rounded down (frame 83 at 30 fps is `2.766666`): `2.767` lands a frame late.
-3. The sound is the original's: copy the video into the project and play it as one `<audio src="original.mp4">` over the whole film (no extracted or re-encoded track); every clip is muted.
+3. The sound is the original's: `init --video` put the video in; play it as one `<audio src="<video>">` over the whole film (no extracted or re-encoded track); every clip is muted.
 4. Read consecutive frames wherever something changes: each cut, entrance, exit and transition, a few frames either side (`npx hyperframes measure frames --range a,b --roi x,y,w,h`). Sheets a second or a quarter apart miss 1–3-frame timing, which way things enter and leave, blurs and dissolves at cuts, and one-frame flashes.
 
 ## Every layer
diff --git a/skills/reverse-any-video/references/start.md b/skills/reverse-any-video/references/start.md
index 40627d4308..825e7addc8 100644
--- a/skills/reverse-any-video/references/start.md
+++ b/skills/reverse-any-video/references/start.md
@@ -10,8 +10,9 @@ video (`--outcome=error` when you stop without one).
 
 Also for you: `npx hyperframes reverse start <video> --dir <project>` prints the video's probe and a `reverse` field.
 `signed_in` and `plan` (`free` or `pro`) pick the section below; a `null` plan is unknown, so ask
-`npx hyperframes auth status`. `<project>` is the folder you build in: `init` it there afterwards, which keeps the session
-it saved for `cloud render`. A CLI that does not know `reverse start` yet: use `auth status` for the sign-in and
+`npx hyperframes auth status`. `<project>` is the folder you build in: afterwards run `npx hyperframes init <project> --video <video> --keep-original --skip-transcribe`,
+which copies the video in untouched under its own file name and keeps the session it saved for `cloud render`. Keep the video out of `<project>` until then: `init`
+refuses a folder that already holds other files. A CLI that does not know `reverse start` yet: use `auth status` for the sign-in and
 plan and `npx hyperframes measure probe <video>` for the probe.
 
 ## Not signed in yet
@@ -58,16 +59,19 @@ the end of a run. `reverse start` and `auth status` are for the sign-in: never r
 
 ## Out of credits mid-run
 
-A refused step prints what it needs and the command that fixes it (top up, or pick a plan). Ask the person to run that
-command, then run the same step again once they reply. Never trim the plan to fit.
+A refused step prints what it needs and the command that fixes it (top up, or pick a plan). Shots are launched all
+at once, so several refuse together: wait until every launched step has answered, add up what each refused step
+needs, and ask once for that total (`--needed <total>`), never for one step at a time. If a refusal prints no
+amount, run plain `billing top-up` for that one. Then relaunch every refused
+step after they reply. Never trim the plan to fit.
 
-> This step needs 180 credits and you have 30. Add credits by typing this in the prompt:
+> Three steps need 180, 180 and 273 credits and you have 30. Add credits by typing this in the prompt:
 >
 > ```
-> ! npx hyperframes billing top-up --needed 180
+> ! npx hyperframes billing top-up --needed 633
 > ```
 >
-> It opens the top-up page and finishes once your balance covers the step. Reply "done" and I'll pick up right
+> It opens the top-up page and finishes once your balance covers all of them. Reply "done" and I'll pick up right
 > where I stopped.
 
 ## Time