From 341fdd353c50babdd5f0ec1cc7b7612fbd5d6a7d Mon Sep 17 00:00:00 2001
From: WaterrrForever <miao.yang@heygen.com>
Date: Tue, 3 Nov 2026 20:05:22 +0000
Subject: [PATCH] docs(skills): reverse-any-video runs sign-in and payment
 itself and opens the result (#7101)

* docs(skills): reverse-any-video runs sign-in and payment itself and opens the result

From Wenbo's end-to-end reverse test (F1, F2, F8, F9, F12, F13):
- the person types nothing: the agent runs auth login, billing subscribe and
  billing top-up itself and gives each page as a clickable link
- never sign in with an API key to get past Pro
- reverse start's plan is final; auth status is read only for a null plan,
  and its hyperframes field, never user.subscription
- an old CLI without reverse start: run this run as npx -y hyperframes@latest
- hand over: side by side from diff --sbs, Studio preview, Framey line
- animated shots: cut the guide inside a dissolve, retime each generated shot

* docs(skills): reverse sign-in names --device, reads auth status --json, trims dissolve frames

Rames's three wording notes on #7101, and the old-CLI subscribe line now
applies only to a plugin's pinned CLI, beside main's null upgrade_url rule.

* docs(skills): a plugin whose CLI can't reverse stops before payment

Jerrai on #7101: the plugin fallback sent the person to subscribe when the
pinned CLI has no reverse start, so the run could not go on after paying.
It now stops and says the plugin needs updating.
---
 skills-manifest.json                          |  2 +-
 skills/reverse-any-video/SKILL.md             |  4 +-
 .../reverse-any-video/references/animated.md  |  3 +-
 skills/reverse-any-video/references/start.md  | 63 ++++++++++---------
 4 files changed, 39 insertions(+), 33 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index ba53a985bd..799c27c315 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -26,7 +26,7 @@
       "files": 76
     },
     "reverse-any-video": {
-      "hash": "e809ebdad20e0f9a",
+      "hash": "9d9db28adf68ba87",
       "files": 5
     },
     "slideshow": {
diff --git a/skills/reverse-any-video/SKILL.md b/skills/reverse-any-video/SKILL.md
index 996e746d1d..619bf8f701 100644
--- a/skills/reverse-any-video/SKILL.md
+++ b/skills/reverse-any-video/SKILL.md
@@ -32,6 +32,6 @@ What decides whether drawn things match, in `references/match.md`: text sized fr
 
 1. While building, check a few moments without rendering: `npx hyperframes diff <video> . --at t,t,…`.
 2. When every shot has content: `npx hyperframes check` and fix its errors. Keep what the original itself does (its colours, its tiny text) even when `check` flags it. Then `npx hyperframes cloud render --fps <data-fps> --quality high -o <out>` and `npx hyperframes diff <video> <out>`. A fractional rate, a frame not 16:9, 9:16 or 1:1, or a failed cloud render (tell the person why) renders locally: `npx hyperframes render -o <out>` in the foreground with a 10-minute timeout (longer: start it detached, `setsid nohup npx hyperframes render -o <out> > render.log 2>&1 &`, and wait on the log in the foreground). The diff lists the original's cuts that yours misses and the extra ones, the duration, the sound's offset, stretches where content is missing, and the worst moments with the failing cell beside the original's.
-3. Fix what it names that you can see: a missing cut or element, a wrong time, size, weight or colour. Render and diff once more, then stop. Small score differences are not worth another round.
+3. Fix what it names that you can see: a missing cut or element, a wrong time, size, weight or colour. Render and diff once more, then stop.
 
-Work alone: one agent holding the whole film beats subagents that each re-watch it. Write a short `REVERSE.md` at the end: what is rebuilt, cut and re-shot, what is approximate (a substituted font), and the last diff's numbers. It holds no prices or credit numbers. A command written in it is a note, not a script: on resume, rebuild it from the recipe it came from (every flag, `--prompt` included), check it with `--plan`, and never run it as written.
+Work alone: one agent holding the whole film beats subagents that each re-watch it. Write a short `REVERSE.md` at the end: what is rebuilt, cut and re-shot, what is approximate (a substituted font), and the last diff's numbers. It holds no prices or credit numbers. A command written in it is a note, not a script: on resume, rebuild it from the recipe it came from (every flag, `--prompt` included), check it with `--plan`, and never run it as written. Hand over per `references/start.md`.
diff --git a/skills/reverse-any-video/references/animated.md b/skills/reverse-any-video/references/animated.md
index 9ecc50bde3..0616cb8072 100644
--- a/skills/reverse-any-video/references/animated.md
+++ b/skills/reverse-any-video/references/animated.md
@@ -25,8 +25,9 @@ Work as `people.md` does, one generated shot per original shot, with these chang
      --aspect <the source's> --seconds <n> --prompt "<the painting style, what moves, the camera>" --out <shot>.mp4
    ```
 
-   `--first-frame` does not combine with `--motion`, so the plate goes in `--reference`. Name the style in the prompt, and blank drawn text in the guide with `--mask`.
+   `--first-frame` does not combine with `--motion`, so the plate goes in `--reference`. Name the style in the prompt, and blank drawn text in the guide with `--mask`. Trim the guide to the shot's own frames: leave out the blended frames of a dissolve at either end, or it comes back as the neighbouring shot.
 
 4. **Frame it** by comparing a stable shape at the shot's start and end with `npx hyperframes diff <video> . --at t,t,…`, then set scale and position by hand. `measure face` is for real faces.
+5. **Retime it.** HeyGen performs the camera's moves late, so a generated shot rarely lines up as it comes back. Match its moves to the original's frames and set the clip's `data-media-start` and `data-playback-rate` to fit, shot by shot.
 
 `REVERSE.md` lists which shots are generated and which layers are code.
diff --git a/skills/reverse-any-video/references/start.md b/skills/reverse-any-video/references/start.md
index 917592d8a0..c3352c2a22 100644
--- a/skills/reverse-any-video/references/start.md
+++ b/skills/reverse-any-video/references/start.md
@@ -1,19 +1,24 @@
 # Opening a Reverse
 
 What the person reads at the start, and when credits run out mid-run. Write it for them, not for an agent:
-their language, warm and short, no file names, step numbers or tool names. Show any command they type as a code
-block they can copy.
+their language, warm and short, no file names, step numbers or tool names. They type nothing: you run every command,
+and any page they need (sign-in, upgrade, top-up) goes in your message as a plain link they can click, in case the
+browser did not open.
 
 For you, not them: run `npx hyperframes events --skill=reverse-any-video` as you start, and
 `npx hyperframes events --skill=reverse-any-video --event=skill_completed --outcome=success` when you hand over the
 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: afterwards run `npx hyperframes init <project> --video <video> --keep-original --skip-transcribe`,
+`signed_in` and `plan` (`free` or `pro`) pick the section below, and that plan is final. Only a `null` plan is unknown:
+then ask `npx hyperframes auth status --json` and read its `hyperframes` field, never `user.subscription`, which is the HeyGen
+app's plan and does not unlock Reverse. `<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.
+refuses a folder that already holds other files. Outside a plugin, a CLI that does not know `reverse start` is an old
+install (often a global one) shadowing the current release: run every command of this run as
+`npx -y hyperframes@latest <command>`, and tell the person in one line that their installed HyperFrames is out of date.
+Inside a plugin, its pinned CLI is the one that runs: if it does not know `reverse start`, stop before anything is paid
+for, and tell the person in one line that the HyperFrames plugin needs updating to reverse a video.
 
 ## Not signed in yet
 
@@ -21,32 +26,31 @@ Say why HeyGen matters before asking: signing in is what gets the best remake. H
 video, so they move and speak as they do in the original. For example:
 
 > To rebuild this video at its best, I'll work with HeyGen: it re-shoots the people in it, so they move and speak just
-> like the original. Sign in once by typing this in the prompt:
->
-> ```
-> ! npx hyperframes auth login
-> ```
->
-> Your browser opens the HeyGen sign-in. Once you're in, reply "done".
+> like the original. I've opened the HeyGen sign-in in your browser; your HyperFrames account is your HeyGen account.
+> I'll carry on as soon as you're in.
 >
 > Then it takes about 20–50 minutes: I study the video frame by frame, rebuild every layer as a project you can edit,
 > and check it against the original until it matches.
 
+Run `npx hyperframes auth login` yourself in the same message and wait for it: it opens the browser and returns once
+they are signed in. When the browser does not open, it prints the sign-in link: give it. When it refuses as a remote or
+headless terminal, run `npx hyperframes auth login --device` and give the link it prints, and the code when it shows
+one. Never sign in with an API key to get past Pro: that signs in a HeyGen app account, which has no HyperFrames plan.
+
 ## Signed in on Free
 
 Reverse is part of Pro. Say why in one line, then run the `reverse.subscribe_command` from `reverse start` exactly as
 printed (`npx hyperframes billing subscribe --feature reverse --session <id>`): it opens the plans page in the person's
 browser, credits the purchase to this run, and waits until they are on Pro, so the run goes on by itself. Start nothing
-before it finishes. For example:
+before it finishes. Give the `reverse.upgrade_url`, when it isn't `null`, as a link in the same message. For example:
 
 > Reverse is part of HyperFrames Pro: it re-shoots the people in your video with HeyGen. I've opened the upgrade page in
-> your browser and I'll carry on as soon as you're subscribed.
+> your browser (or open it here: <upgrade_url>) and I'll carry on as soon as you're subscribed.
 
 When `reverse start` refuses the run (it exits with an error whose `fix` is that command), run the `fix` the same way,
 then run `reverse start` again. When `subscribe_command` is `null` (or the refusal names no command), a plan can't be
-purchased right now: say so plainly, give no link, run nothing, and stop. Only on a CLI without `reverse start`, run
-`npx hyperframes billing subscribe` instead. If the command times out, tell the person and run it again once they say
-they are ready.
+purchased right now: say so plainly, give no link, run nothing, and stop. If the command times out, tell the person
+and run it again once they say they are ready.
 
 ## Signed in on Pro
 
@@ -61,18 +65,19 @@ the end of a run. `reverse start` and `auth status` are for the sign-in: never r
 
 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.
+needs, and run `npx hyperframes billing top-up --needed <total>` once for that total, never one step at a time. If a
+refusal prints no amount, run plain `billing top-up` for that one. It opens the top-up page and waits until the balance
+covers the total; give the refusal's `url` (on an older CLI, the link in its `fix`) as a link in the same message.
+Then relaunch every refused step. Never trim the plan to fit.
 
-> 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 633
-> ```
->
-> 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.
+> Three steps need 633 credits together and you have 30. I've opened the top-up page in your browser (or open it here:
+> <url>); I'll pick up right where I stopped once your balance covers them.
+
+## Handing it over
+
+They see the result, not file paths. Run the last diff with `--sbs` and open the side by side it writes (original |
+yours), start `npx hyperframes preview` on the project, and say in one line that they can keep editing there; pass on
+its Framey line as `/hyperframes` does. Then send `skill_completed`.
 
 ## Time