Workflow skills reach render before FFmpeg is checked, and the docs only offer brew install ffmpeg

[pixagentur]

Problem

FFmpeg is the only hard prerequisite that nothing before render needs. init, lint, check, snapshot and preview all run without it, so an agent can go through planning, several design rounds and the user's approval, and only then hit "FFmpeg not found", at the moment the user is waiting for the file.

• motion-graphics/SKILL.md lists under Prerequisites "brew install node ffmpeg. npx hyperframes doctor once", but no numbered step runs doctor. hyperframes/SKILL.md and hyperframes-cli/SKILL.md (development loop steps 1 to 10) do not run it either; hyperframes-cli only says "The CLI requires Node.js 22 or newer and FFmpeg." (main @ 042ec2e, identical to the installed skills.)
• render does fail fast (fix(cli): pre-flight FFmpeg check and propagate render failure stage #1149), but that is still the last step.
• The only remedy anywhere in the skills and in doctor's hint is brew install ffmpeg. On a Mac without Homebrew (our case) that is a dead end for an agent, which then improvises. We ended up with a project-local npm ffmpeg-static + ffprobe-static prepended to PATH.
• The CLI already has two clean answers that are documented nowhere in the skills or in doctor-browser.md: HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH (fix: run the configured ffmpeg and ffprobe everywhere and say when an upload was not checked #4611) and project-local discovery in .hyperframes/bin (fix(cli): discover project-local ffmpeg binaries #2464, resolved against the working directory in packages/parsers/src/ffBinaries.ts).

Proposed solution

1. Skills: run npx hyperframes doctor --json | jq -e '.ok' (or at least check FFmpeg/FFprobe in the payload) right after init / project resume in the entry skill, so every workflow inherits it, and surface a missing render dependency before design work starts.
2. Docs: in hyperframes-cli/references/doctor-browser.md ("Missing FFmpeg") and in the doctor hint, add the non-Homebrew paths: the two env vars, .hyperframes/bin, and e.g. a static build (npm i ffmpeg-static ffprobe-static in a scratch folder, then point the env vars at the binaries).
3. Optional CLI: init (or the first preview/check) prints a one-line warning when FFmpeg/FFprobe cannot be resolved, so the gap shows up without anyone remembering to run doctor.

Alternatives considered

• Leave it to render's pre-flight (fix(cli): pre-flight FFmpeg check and propagate render failure stage #1149): correct, but too late in an agent workflow with user approval gates.
• Cloud render as the fallback: valid when the user wants it, but it changes cost and data flow and should not be the silent answer to a missing local binary.

Additional context

• Environment: hyperframes 0.8.141, Node 24, macOS arm64, no Homebrew.
• Duplicate search (issues and PRs, open and closed): doctor, "ffmpeg not found", "ffmpeg missing", ffmpeg-static, homebrew, "doctor init", "ffmpeg prerequisite", "ffmpeg install". Related, already merged: fix(cli): pre-flight FFmpeg check and propagate render failure stage #1149, fix(cli): preflight FFmpeg + Chrome check before studio renders #1014, fix(cli): verify browser/ffmpeg binaries exist before render starts #1365 (render pre-flight), fix(cli): discover project-local ffmpeg binaries #2464 (.hyperframes/bin), fix: run the configured ffmpeg and ffprobe everywhere and say when an upload was not checked #4611 (env vars), fix(cli): doctor shows platform-correct install hints #319 (platform install hints). None moves the check earlier in the workflow or documents the env vars / .hyperframes/bin for agents.