hyperframes 0.7.57 → 0.7.59

package/dist/skills/hyperframes/references/skill-lifecycle.md

@@ -0,0 +1,33 @@
+# Skill installation and freshness
+
+Read this reference when installing or updating skills, diagnosing unexpected workflow behavior, or running HyperFrames setup in CI.
+
+HyperFrames installs the core set eagerly and workflow skills lazily.
+
+- **Core set:** `/hyperframes`, the `hyperframes-*` domain skills, and `/media-use`.
+- **Workflow skills:** installed when routing selects them through `npx hyperframes skills update <workflow-name>`.
+
+## What `init` does
+
+`npx hyperframes init` checks GitHub and refreshes the core set plus other skills already installed. It does not install workflows that have never been used. A current install is a no-op. Offline or rate-limited checks degrade gracefully and do not fail project scaffolding.
+
+The `--skip-skills` CLI flag is temporarily ignored. CI and tests may opt out with `HYPERFRAMES_SKIP_SKILLS=1`.
+
+## Diagnose and update
+
+```bash
+npx hyperframes skills check
+npx hyperframes skills check --json
+npx hyperframes skills update
+npx hyperframes skills update <workflow-name>
+npx hyperframes skills
+```
+
+- `skills check` exits non-zero when an installed skill is stale or the core set is incomplete. Workflows available on demand but not installed are not failures.
+- Bare `skills update` refreshes the core set and everything already installed, prunes unpublished skills, and does not expand the workflow set.
+- Named `skills update <name...>` also installs those named workflows or domain skills.
+- Bare `skills` installs the full published set explicitly.
+
+If the HyperFrames CLI is unavailable, use `npx skills add heygen-com/hyperframes --skill <workflow-name>` for one workflow or `npx skills add heygen-com/hyperframes --all` for the full published set.
+
+The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `check`. Treat a failed update as a visible tool failure; do not continue from a remembered workflow contract.

package/dist/skills/hyperframes/references/workflow-catalog.md

@@ -0,0 +1,70 @@
+# Workflow catalog
+
+Use this catalog while routing, before the selected workflow is lazy-installed. After the routing table in `../SKILL.md` yields a candidate, read that candidate's section and confirm that its input and output match the request.
+
+## Sections
+
+- [`/product-launch-video`](#product-launch-video), [`/faceless-explainer`](#faceless-explainer), [`/pr-to-video`](#pr-to-video)
+- [`/embedded-captions`](#embedded-captions), [`/talking-head-recut`](#talking-head-recut)
+- [`/motion-graphics`](#motion-graphics), [`/music-to-video`](#music-to-video), [`/slideshow`](#slideshow)
+- [`/general-video`](#general-video), [`/remotion-to-hyperframes`](#remotion-to-hyperframes)
+
+## `/product-launch-video`
+
+- **Input:** A website URL; a script or brief that names a site; or a product-launch script with no derivable site or an explicit “do not scrape” instruction. Capture website assets and brand tokens unless the brief selects no-capture mode. Ask whether supplied script copy is verbatim voice-over or may be restructured.
+- **Output:** A product promo, launch video, site tour, or showcase MP4. Sweet spot 30–90s; hard cap about 3 minutes. A show-it-as-is brief features captured screens rather than inventing a separate route.
+- **Triggers:** “launch video for X”, “promo for our site”, “turn this script into a 60s promo”, “text-only launch video”, “turn this website into a video”, “site tour from this URL”.
+
+## `/faceless-explainer`
+
+- **Input:** A topic, article, notes, or arbitrary text being explained, with no product being marketed and no website to capture.
+- **Output:** A faceless explainer MP4 with invented typography, abstract graphics, diagrams, or data visualization. Sweet spot 30–90s; hard cap about 3 minutes.
+- **Triggers:** “faceless explainer about X”, “explain how DNS works as a video”, “turn this article into an explainer”.
+
+## `/pr-to-video`
+
+- **Input:** A GitHub PR URL, `owner/repo#N`, or “this PR”, read through `gh`; it is not a website capture request.
+- **Output:** A changelog, feature reveal, fix explainer, or refactor walkthrough with diff, before/after, file-tree, and impact scenes. Hard cap about 3 minutes; duration follows change size.
+- **Triggers:** “make a video about this PR”, “turn PR #1187 into a changelog video”, “release-notes video from this pull request”.
+
+## `/embedded-captions`
+
+- **Input:** Existing talking-head footage to caption. It is an actual media file, not a URL or creative brief.
+- **Output:** The same footage, untouched, with a caption layer and selected caption identity. The subject may occlude embedded captions. Any length.
+- **Triggers:** “add captions”, “add subtitles”, “captions behind the subject”, “cinematic captions for my clip”.
+
+## `/talking-head-recut`
+
+- **Input:** Existing talking-head, interview, or podcast footage to package. The underlying clip plays unchanged.
+- **Output:** The same footage with transcript-synced graphic-overlay cards: kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, or picture-in-picture. Any length.
+- **Triggers:** “package this video”, “add graphic overlays to my talk”, “add lower-thirds or data callouts to this interview”.
+
+## `/motion-graphics`
+
+- **Input:** A short design-led unit, typically under 10s, with no narration, where motion is the message: kinetic type, stat/count-up, chart hit, logo sting, animated title, lower-third, map, tweet/headline/page highlight, or asset-fusion shot.
+- **Output:** A short MP4 or transparent alpha WebM/MOV overlay.
+- **Triggers:** “an 8s logo sting”, “animate this stat”, “kinetic-type intro”, “animate this title”, “transparent lower-third overlay”.
+
+## `/music-to-video`
+
+- **Input:** A music track, or a video whose audio becomes the track, with no narration or website capture. User images or videos are optional.
+- **Output:** A beat-synced MP4 driven by a deterministic beat/energy map (`audiomap.json`). It may become a lyric video, slideshow, visualizer, or kinetic promo without changing pipelines.
+- **Triggers:** “make a video for this song”, “beat-synced video”, “lyric video”, “music visualizer”, “kinetic promo to this beat”.
+
+## `/slideshow`
+
+- **Input:** A brief, outline, or existing page to author as a presentation, pitch deck, or interactive deck. If “slides”, “deck”, or “convert this page” is ambiguous, confirm that the user wants a HyperFrames slideshow before authoring.
+- **Output:** A runnable HyperFrames composition plus the JSON island used by `SlideshowController`: discrete slides, fragment reveals, branching, hotspots, presenter mode, and speaker notes. The deliverable is a navigable deck, not an MP4.
+- **Triggers:** “make a pitch deck”, “interactive presentation”, “convert this page into slides”, “slideshow with presenter mode”.
+
+## `/general-video`
+
+- **Input:** Any custom creation or edit not covered above: a static title card, longer brand or sizzle reel, multi-scene montage, static loop/poster, NLE-like footage remix, or freeform composition. It also executes every `flow: companion` brief.
+- **Output:** A HyperFrames composition of any length or format through design → plan → static layout → animation → check → approval → render.
+- **Triggers:** “make a static title card”, “longer brand reel”, “multi-scene composition”, “static loop”, “custom video”, or any unmatched video request.
+
+## `/remotion-to-hyperframes`
+
+- **Input:** Existing Remotion React source, only when the user explicitly asks to port, convert, or migrate it. A passing Remotion mention is not a trigger.
+- **Output:** A HyperFrames HTML composition translated from the source and compared with the Remotion render through the migration evaluation harness.
+- **Triggers:** “port my Remotion project”, “convert this Remotion composition”, “migrate from Remotion”.

package/dist/skills/hyperframes-cli/SKILL.md

@@ -1,146 +1,136 @@
 ---
 name: hyperframes-cli
-description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, render, publish, cloud, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background (validate/inspect/layout are deprecated aliases covered by check), or when troubleshooting the HyperFrames build/render environment. Entry point for HeyGen-hosted cloud rendering (`hyperframes cloud render / list / get / delete`) and self-managed AWS Lambda rendering (`hyperframes lambda deploy / render / progress / destroy / policies / sites`).
+description: >
+  Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot,
+  compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish,
+  cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs,
+  benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build
+  or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local,
+  HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.
 ---
 
 # HyperFrames CLI
 
-Everything runs through `npx hyperframes` unless project instructions specify a local wrapper. Obey the local wrapper exactly. Requires Node.js >= 22 and FFmpeg.
-
-## Workflow
-
-1. **Scaffold** — `npx hyperframes init my-video` (or `capture` from a URL). `init` also checks the installed skills against the latest on GitHub and updates the global set if any are out of date. The `--skip-skills` flag is currently neutered (temporary, while the skills.sh registry catches up), so every `init` runs this check and pulls our latest skills regardless.
-2. **Write** — author HTML composition (see the `hyperframes-core` skill)
-3. **Lint** — `npx hyperframes lint` (static, fast — run it early while iterating)
-4. **Check** — `npx hyperframes check` (the browser gate; add `--snapshots` for annotated frames + per-finding crops)
-5. **Preview / edit** — `npx hyperframes preview` opens **Studio**, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
-6. **Render** — pick the variant:
-   - Iterate: `npx hyperframes render --quality draft`
-   - Deliver: `npx hyperframes render --quality high --output out.mp4`
-   - CI / cross-host repro: `npx hyperframes render --docker --strict --output out.mp4`
-   - Cloud, zero-infra: `npx hyperframes cloud render` (HeyGen hosts the render; no local Chrome/FFmpeg/AWS, see Cloud below)
-   - Cloud, bring-your-own-AWS: `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)
-7. **Report feedback** — after verifying the output, `npx hyperframes feedback --rating <1-5> --comment "..."` once per task (see Agent Conventions).
-
-Run `check` before preview. It runs the linter first (and skips the browser entirely on lint errors), then does everything the old validate → inspect → snapshot sequence did in **one** browser session and one seek pass: runtime console errors and failed requests, layout defects (text spilling out of bubbles/containers or off canvas, held overlaps, occlusion), motion-sidecar verification (`*.motion.json` — entrances under seek, stagger order, in-frame, liveness), and WCAG contrast. Contrast failures are errors and carry the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color, so most contrast fixes need no screenshot. Every finding carries a selector, `data-*` identity, composition source file, bbox, and sample time — jump straight to the HTML. Single-sample transients demote to info; findings held across samples gate the exit code (`--strict` gates warnings too). `validate`, `inspect`, and `layout` still work but are deprecated aliases of parts of `check`.
-
-For motion-heavy work, prefer snapshot-driven iteration and a `*.motion.json` sidecar — see `references/lint-validate-inspect.md` for the discipline and motion-verification spec. To compare agent-authored candidate variants, use `npx hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json]` to render each composition through its own runtime, assemble one labeled sheet, inspect it side by side, and choose. For color-grade selection, use the color-specific sibling `npx hyperframes grade-compare --for <frame> --grades grades.json` (or `--luts a.cube,b.cube`) to render every grading candidate through the real WebGL grading runtime into one labeled PNG before choosing the winner.
-
-## Agent Conventions
-
-Cross-cutting rules that hold for every command:
-
-- **`--json` is available on every command except `render`, `preview`, and `play` server modes.** Use it for any agent / CI invocation of the supported commands; output includes a `_meta` envelope (cli version, latest available, update advice). `render` reports status via stdout + exit code only — verify success with the post-render check below. `preview --selection --json` and `preview --context --json` are the preview exceptions: they do not start a server, they query the user's running Studio session and exit.
-- **`doctor --json` always exits 0**, even when the environment is broken. Gate on the payload's `ok` field: `npx hyperframes doctor --json | jq -e '.ok' > /dev/null`. This insulates pipelines from CLI release churn.
-- **Non-TTY mode is auto-detected.** When `stdout` is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; `init` then **requires `--example`**. Pass `--non-interactive` to force this mode even on a TTY.
-- **CI gating on render**: `--strict` fails on lint errors, `--strict-all` fails on warnings too, `--strict-variables` fails on undeclared `--variables` keys.
-- **Correlate a verify loop with `HYPERFRAMES_RUN_ID`.** Orchestrators driving the CLI per task/design element should set this env var once per unit of work; every command invocation attaches it to telemetry, and `check` emits a per-gate breakdown, making roundtrips-per-task measurable.
-- **Paths in `--json` are redacted** — `$HOME` becomes the literal `$HOME` so output is safe to paste into bug reports and agent contexts.
-- **Render is user-gated.** Never auto-render once the checks pass. Pause at `preview`, tell the user the video is editable in Studio, and render only after they approve.
-- **Use Studio context for user-directed edits.** When the user says "this selected element", "the thing I clicked", "current selection", or similar, ask them to select it in Studio, then run `npx hyperframes preview --context --json --context-fields selection`. Use the returned `selection.target.hfId` / `selector`, `selection.sourceFile`, `selection.currentTime`, and `selection.thumbnailUrl` to anchor the edit. If `selection` is `null` and `errors.selection.code` is `no-selection`, ask the user to click the element and rerun; do not guess from screenshots.
-- **Keep Studio context compact.** `preview --context --json` returns compact selection by default. Add `--context-fields selection`, `--context-fields selection,lint`, or `--context-fields lint` to avoid bloating agent context. Use `--context-detail full` only when you need heavy fields like computed styles, inline styles, or text-field metadata.
-- **Post-render verification.** After `render` returns exit 0, confirm the output file exists and has plausible size before reporting success: `[ -s "$OUTPUT" ] || echo "render produced no output"`. The CLI prints `◇  <path>` on success; for long renders also sanity-check duration with `ffprobe -i "$OUTPUT" -show_format -v error`.
-- **Report feedback after a successful render.** Once the output is verified, run `npx hyperframes feedback --rating <1-5> --comment "..."` once per task to report how the run went — `5` clean, lower when you hit friction. Put any bug, workaround, missing feature, or confusing behaviour you encountered in `--comment`. This is the project's primary signal channel; renders that go silent leave the maintainers blind. Skip only when telemetry is disabled or the user opted out.
-  - **For a reproducible bug, add `--file-issue`** — it publishes a minimal repro of the project to a public URL and opens a pre-filled GitHub issue with your comment + environment. A comment alone almost never lets a maintainer reproduce; the published composition is what makes the report actionable. Point `--dir <project>` at the failing composition if it isn't the current directory.
-  - **Write bug comments a maintainer can reproduce from — a paraphrase they can't act on wastes the report.** The CLI already attaches os/arch/mem/ffmpeg/CLI-version, so don't repeat those; spend the comment on what only you saw. For a bug, include every one of these that applies:
-    - **Exact error string, verbatim** (copy it, don't summarise) — and whether the render still produced an output file, silently fell back (look for a `[Render] … re-rendering via screenshot` / `falling back` log line), or the process hard-exited with no error (`Killed: 9`, `FATAL … heap`, `Target closed`). "Which timeout / which failure mode" is the single most useful fact.
-    - **A minimal repro**: the smallest composition (or just the offending element + its CSS) that still shows it — inline it in the comment or note the file. Name the trigger you isolated (e.g. "only when the text node uses `font-family: 苹方`", "only at 4K", "only with a `<video>` present").
-    - **The exact command + flags** you ran, and any env vars set (`HF_*` / `PRODUCER_*`).
-    - **What's wrong and where**: the frame number or timestamp, and the visual defect (blank text, black band at the bottom, wrong glyphs, frozen canvas) vs. what you expected. A screenshot path if you saved one.
-    - If it reproduces only sometimes, say so and give the hit rate.
-
-## Routing
-
-| Want to…                                                                                                   | Read                                                                  |
-| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Scaffold a project (`init`, `capture`, `skills`)                                                           | `references/init-and-scaffold.md`                                     |
-| Check correctness (`lint`, `check`, `snapshot`, deprecated `validate`/`inspect`)                           | `references/lint-validate-inspect.md`                                 |
-| Preview or render (`preview`, `play`, `render`, `publish`)                                                 | `references/preview-render.md`                                        |
-| Diagnose the environment (`doctor`, `browser`)                                                             | `references/doctor-browser.md`                                        |
-| Cloud render, zero-infra HeyGen-hosted (`cloud render / list / get / delete`, `auth`)                      | `references/cloud.md`                                                 |
-| Cloud render on your own AWS Lambda (`lambda deploy / sites / render / progress / destroy / policies`)     | `references/lambda.md`                                                |
-| Parametrize / template renders (`--variables`, `--variables-file`, `--strict-variables`, `--batch`)        | `references/cloud.md` + `hyperframes-core` (`variables-and-media.md`) |
-| Everything else (`info`, `upgrade`, `compositions`, `docs`, `benchmark`, `telemetry`, asset preprocessing) | `references/upgrade-info-misc.md`                                     |
-
-## Cross-Skill Hand-Offs
-
-- **Tailwind projects** (`init --tailwind`) → use `hyperframes-core` (Tailwind reference) before editing classes or theme tokens.
-- **Registry blocks/components** (`hyperframes add`, `hyperframes catalog`) → use `hyperframes-registry` for install paths, sub-composition wiring, and snippet merging.
-- **Asset preprocessing** (`tts`, `transcribe`, `remove-background`) → use `media-use` for voice selection, Whisper model rules, captions, and TTS-to-captions chain.
-- **Parametrized renders** (`--variables`) → declared via `data-composition-variables` on `<html>`; see `hyperframes-core` for the full schema.
-
-## Cloud (HeyGen-hosted rendering)
-
-`hyperframes cloud render` is the **zero-infra** render path: the CLI zips your project, uploads it, renders on HeyGen's cloud, and downloads the mp4. No Chrome, no FFmpeg, no AWS, and you pay per credit. This is the default answer to "render this in the cloud"; reach for Lambda only when you already own AWS and need distributed/chunked rendering.
+Run commands as `npx hyperframes ...` unless project instructions provide a wrapper. Obey the wrapper when present. The CLI requires Node.js 22 or newer and FFmpeg.
+
+## Development loop
+
+1. **Scaffold:** `npx hyperframes init <project>` or capture a site. In non-TTY mode, pass `--non-interactive --example=<name>`.
+2. **Author:** write the composition using `/hyperframes-core`.
+3. **Get fast feedback while editing:** run `npx hyperframes lint` after the first HTML pass and after structural changes.
+4. **Run the final gate:** run `npx hyperframes check`; it reruns lint before opening the browser. Do not prepend a redundant standalone lint invocation. Add `--snapshots` for annotated overview frames and finding crops.
+5. **Inspect sub-compositions:** when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene.
+6. **Open the final Studio preview:** run `npx hyperframes preview`, hand the timeline project URL to the user, and ask whether to revise or render.
+7. **Render only after approval:** use draft quality for iteration and high quality for delivery.
+8. **Verify the output:** confirm the file exists, is non-empty, and has a plausible duration.
 
 ```bash
-npx hyperframes auth login            # one-time sign-in (shared with the `heygen` CLI)
-npx hyperframes cloud render          # zip, upload, render, download to renders/<id>.mp4
+# Fast iteration check; repeat while authoring as needed.
+npx hyperframes lint
+
+# Required final gate; includes lint.
+npx hyperframes check
+npx hyperframes preview
+npx hyperframes render --quality high --output out.mp4
+test -s out.mp4
+ffprobe -v error -show_format out.mp4
 ```
 
-Common flags: `--composition <html>`, `--output <path>`, `--quality draft|standard|high`, `--fps`, `--resolution 1080p|4k`, `--format mp4|webm|mov`, `--aspect-ratio` (auto-detected from `data-width`/`data-height`). Fire-and-forget with `--no-wait` + `--callback-url`; make retries safe with `--idempotency-key "$(uuidgen)"`. Manage jobs with `cloud list` / `cloud get <id>` / `cloud delete <id>`.
+`check` runs lint first, then uses one browser session and one seek pass to audit runtime errors, failed requests, layout, `*.motion.json` assertions, and WCAG contrast. Persistent findings gate the exit code; transient entrance or exit findings are informational. Use `--strict` to gate warnings. `validate`, `inspect`, and `layout` remain aliases for compatibility but must not appear in new instructions or scripts.
+
+## Two different preview surfaces
 
-The idiomatic **template workflow is upload-once, re-render-many**: render a local project once to get its `asset_id`, then re-submit against that asset with different `--variables` (skips zip + upload). See `references/cloud.md` for the full flag set, the auth model, webhooks, and the template loop.
+Do not confuse these states:
 
-## Variables (parametrized / template renders)
+| Surface                   | When it may open                                       | Purpose                                                                           |
+| ------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| Storyboard board          | Before composition checks, only when `storyboard: yes` | Review plan cards and wireframe sketches. Open `?view=storyboard#project/<name>`. |
+| Final composition preview | After `check` passes                                   | Review the assembled timeline before render. Open `#project/<name>`.              |
 
-Any render (local, cloud, or Lambda) can fill declared template slots at render time. Declarations live on the composition (`data-composition-variables`); the CLI surface is:
+The early board is not approval of the final video. Rendering always requires the final approval defined by `hyperframes-core/references/review-loop.md`.
+
+## Sub-composition smoke test
+
+Static audits cannot catch every mount failure. When the project uses sub-compositions, capture at least one visible midpoint for each host slot:
 
 ```bash
-npx hyperframes render --variables '{"title":"Q4 Recap","theme":"dark"}' --output q4.mp4
-npx hyperframes render --variables-file ./vars.json --output out.mp4
-npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
-npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
+npx hyperframes snapshot --at <t1>,<t2>,<t3>
 ```
 
-`--strict-variables` fails the render on any undeclared key or type mismatch (use it in CI). `--batch <rows.json>` renders one output per data row with `{key}`/`{index}` path placeholders and writes a `manifest.json`. For the **full schema** (declaring types, `data-var-src`/`data-var-text` declarative bindings, per-instance `data-variable-values` for sub-compositions, and precedence) use the `hyperframes-core` skill (`references/variables-and-media.md`). The cloud template loop lives in `references/cloud.md`.
+Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timeline-registration timeouts as render-blocking mount defects. See `hyperframes-core/references/sub-compositions.md` for the corresponding fixes.
 
-## Lambda (Cloud Rendering)
+## Agent conventions
 
-`hyperframes lambda` deploys distributed rendering to AWS Lambda and drives renders from your laptop or CI. End-to-end is three commands:
+- Prefer `--json` for agent and CI calls. Server-mode `render`, `preview`, and `play` do not provide ordinary JSON output; `preview --selection --json` and `preview --context --json` are query-mode exceptions.
+- `doctor --json` always exits zero. Gate on its payload:
 
-```bash
-npx hyperframes lambda deploy                                             # provision SAM stack (Lambda + Step Functions + S3)
-npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
-npx hyperframes lambda destroy                                            # tear down (S3 bucket is retained)
-```
+  ```bash
+  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
+  ```
 
-Use Lambda when a render is too long / too large for one host (multi-minute videos, 4K, large parallel batches) and you have AWS credentials configured. For dev-loop iteration stay on local `render`.
+- Non-TTY mode is automatic. `init` requires `--example` there; use `--non-interactive` to force deterministic behavior on a TTY.
+- Use one `HYPERFRAMES_RUN_ID` for all commands in the same verification loop.
+- Use `--strict`, `--strict-all`, and `--strict-variables` when the corresponding warnings, variables, or CI conditions must gate the render.
+- JSON paths redact the home directory as `$HOME`; do not try to reverse the redaction.
+- Never render merely because checks pass. Pause at the final preview and wait for approval.
 
-See `references/lambda.md` for prerequisites, all 6 subcommands (`deploy`, `sites create`, `render`, `progress`, `destroy`, `policies`), IAM policy validation, state files, and cost / cleanup rules.
+## Studio-directed edits
 
-## Minimum Completion Gate
+When the user refers to “this element” or the current selection, query Studio instead of guessing:
 
 ```bash
-npx hyperframes check
+npx hyperframes preview --context --json --context-fields selection
 ```
 
-One command covers the old lint + validate + inspect sequence in one browser session. Add `--strict` to gate warnings and `render --strict` in CI to fail on lint errors. `--caption-zone "<x0=..;y0=..;x1=..;y1=..>"` and `--frame-check` add opt-in band/bounds gates for pipelines that need them.
+Use `selection.target.hfId` when available, otherwise its selector and source file. If the result reports `no-selection`, ask the user to click the element and rerun. Request only the context slices you need; use `--context-detail full` only for computed styles or editable text metadata. Full behavior and failure codes live in `references/preview-render.md`.
 
-### Visual smoke test — required when the project uses sub-compositions
+## Render choices
 
-The audits evaluate the bundled composition; they cannot catch every cross-file mount failure when `index.html` mounts sub-compositions via `data-composition-src` (see `hyperframes-core` → `references/sub-compositions.md`, "Common pitfalls"). The gate that catches those is one that actually loads `index.html` the way `render` does and seeks the timeline.
+| Need                                     | Command                                                                       |
+| ---------------------------------------- | ----------------------------------------------------------------------------- |
+| Fast local iteration                     | `npx hyperframes render --quality draft`                                      |
+| Final local delivery                     | `npx hyperframes render --quality high --output out.mp4`                      |
+| Reproducible container render            | `npx hyperframes render --docker --strict --output out.mp4`                   |
+| Local variable-driven batch render       | `npx hyperframes render --batch rows.json --output "renders/{name}.mp4"`      |
+| HeyGen-hosted zero-infrastructure render | `npx hyperframes cloud render`                                                |
+| Self-managed distributed AWS render      | `npx hyperframes lambda render <project> --width 1920 --height 1080 --wait`   |
+| Self-managed distributed GCP render      | `npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait` |
 
-Use `hyperframes snapshot` — it loads the project the same way `render` does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:
+Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS. Use Lambda only when AWS ownership is a requirement. Use Cloud Run only when GCP ownership is a requirement. Read the matching reference before running any cloud path.
 
-```bash
-# Capture one frame at the midpoint of every sub-composition.
-# Midpoints = data-start + data-duration/2 for each host slot in index.html.
-npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
+After verifying a successful render, send one feedback report unless telemetry is disabled or the user opted out:
 
-# Or, if you don't need per-scene targeting, an evenly-spaced sample:
-npx hyperframes snapshot --frames 9
+```bash
+npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
 ```
 
-Output lands in `snapshots/frame-NN-at-Xs.png`. Eyeball each frame against the scene plan.
+Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The bug report format and privacy warning live in `references/preview-render.md`.
+
+## Read the matching reference before running a command
+
+The following references and owning skills are mandatory command contracts, not optional background reading. Before running a command in the table, read its matching row.
 
-Per-frame red flags (each maps to a specific failure mode the static gates miss):
+| Need                                                                                   | Reference                             |
+| -------------------------------------------------------------------------------------- | ------------------------------------- |
+| `init`, `capture`, `skills`                                                            | `references/init-and-scaffold.md`     |
+| `lint`, `check`, motion sidecars, `snapshot`                                           | `references/lint-validate-inspect.md` |
+| `compare`, `grade-compare`, variable-driven `render --batch`                           | `references/compare-and-batch.md`     |
+| `beats` for an existing project's Studio beat grid                                     | `references/beats.md`                 |
+| `preview`, `play`, `render`, `publish`, Studio context, feedback                       | `references/preview-render.md`        |
+| `doctor`, browser management                                                           | `references/doctor-browser.md`        |
+| `auth`, HeyGen-hosted cloud rendering, and template variables                          | `references/cloud.md`                 |
+| AWS Lambda deployment and rendering                                                    | `references/lambda.md`                |
+| Google Cloud Run deployment and rendering                                              | `references/cloudrun.md`              |
+| `info`, `upgrade`, `compositions`, `docs`, `benchmark`, telemetry, media preprocessing | `references/upgrade-info-misc.md`     |
 
-| What you see                                                                       | Root cause                                                                                  |
-| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| Text shows up tiny + unstyled in the top-left corner                               | `<style>` block left in `<head>` outside `<template>` (Pitfall 1) — no CSS reached live DOM |
-| SVG/icon elements blown up to canvas-size                                          | Same as above — no width/height constraints applied                                         |
-| Hero element of the scene is missing entirely; only background + watermark visible | Host-id ≠ template id (Pitfall 2) — timeline never ran, frame captured at initial state     |
-| Snapshot command logs `Sub-composition timelines not registered after 45000ms`     | Pitfall 2 — direct confirmation                                                             |
+For composition variables, also read `/hyperframes-core` → `references/variables-and-media.md`. For `hyperframes add` and `hyperframes catalog`, use `/hyperframes-registry`. Before `hyperframes present`, read `/slideshow`; before `hyperframes keyframes`, read `/hyperframes-keyframes`. For TTS, transcription, captions, or background removal choices, use `/media-use`.
+
+The specialized commands are deliberately documented by their owning workflows:
+
+```bash
+npx hyperframes present <project-dir> --port 3004 --no-open
+npx hyperframes beats <project-dir> --json
+npx hyperframes keyframes <project-dir> --json
+```
 
-`snapshots/` can be deleted after eyeballing; the user-facing final render is a separate pass with `npx hyperframes render`.
+`present` serves a navigable deck with presenter and audience synchronization. `beats` is the standalone Studio beat-grid utility defined in `references/beats.md`. `keyframes` surfaces seek-safe animation and motion-path diagnostics.

package/dist/skills/hyperframes-cli/references/beats.md

@@ -0,0 +1,19 @@
+# Generate a project beat grid
+
+Use `hyperframes beats` when an existing HyperFrames project needs the Studio-compatible beat file for its music track. This is a CLI utility, not a complete video workflow.
+
+```bash
+npx hyperframes beats
+npx hyperframes beats ./my-video
+npx hyperframes beats ./my-video --json
+```
+
+The project must contain a local music `<audio>` source. Mark it with `data-timeline-role="music"`; an id containing `music`, `bgm`, or `soundtrack` is also recognized. The command analyzes that file in headless Chrome and writes `beats/<audio-relative-path>.json`.
+
+If no beats are detected, the command fails and writes nothing. If Chrome is unavailable, run:
+
+```bash
+npx hyperframes browser ensure
+```
+
+For a complete beat-synced video, route through `/music-to-video`. That workflow owns a different audio-driven pipeline and its `audiomap.json`; do not replace its analyzer with this Studio utility.

package/dist/skills/hyperframes-cli/references/cloud.md

@@ -7,11 +7,12 @@ npx hyperframes auth login            # one-time sign-in
 npx hyperframes cloud render          # zip, upload, render, download
 ```
 
-## When to use cloud vs lambda vs local
+## When to use managed cloud, Lambda, Cloud Run, or local
 
 - **`hyperframes render`** (local): fastest iteration loop, use while authoring.
 - **`hyperframes cloud render`**: zero-infra. HeyGen runs the render and you pay per credit. This is the default answer to "render in the cloud" when you don't want to manage Chrome/FFmpeg/AWS.
 - **`hyperframes lambda render`**: bring-your-own-AWS distributed rendering with chunked parallelism. Only worth it when you've already invested in AWS (see `lambda.md`).
+- **`hyperframes cloudrun render`**: bring-your-own-GCP distributed rendering through Cloud Run and Workflows. Use only when GCP ownership is explicit (see `cloudrun.md`).
 
 ## Authentication
 
@@ -21,6 +22,10 @@ Cloud rendering needs a HeyGen credential, stored at `~/.heygen/credentials` (`0
 npx hyperframes auth login              # OAuth 2.0 + PKCE, opens the browser
 npx hyperframes auth login --api-key    # CI/headless: hidden prompt, or pipe: echo "$HEYGEN_API_KEY" | ... --api-key
 npx hyperframes auth status             # active credential source, identity, billing snapshot
+                                        #   exit 0 = signed in and verified; exit 1 = not signed in,
+                                        #   or the credential was rejected — signed-out exit 1 is the
+                                        #   normal offline state (scripts: `auth status || echo offline`),
+                                        #   not a command failure
 npx hyperframes auth refresh            # force-refresh an OAuth token before a long job
 npx hyperframes auth logout             # clear the stored credential
 ```
@@ -63,7 +68,7 @@ npx hyperframes cloud render --quality high --fps 60
 
 ## Templates and variables
 
-Cloud rendering supports [variables](../SKILL.md#variables-parametrized--template-renders): declare `data-composition-variables` on the composition, then fill them at render time.
+Cloud rendering supports [composition variables](../../hyperframes-core/references/variables-and-media.md#variables): declare `data-composition-variables` on the composition, then fill them at render time.
 
 ```bash
 npx hyperframes cloud render --variables '{"title":"Q4 Recap","theme":"dark"}'
@@ -81,7 +86,7 @@ npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
 npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Linus"}'
 ```
 
-For high-volume personalized batches, the Lambda path adds a JSONL fan-out (see `lambda.md`). The full variables schema (types, declarative bindings, sub-composition overrides, precedence) lives in the `hyperframes-core` skill.
+For high-volume personalized batches, both self-managed paths provide JSONL fan-out: AWS Lambda (`lambda.md`) and Google Cloud Run (`cloudrun.md`). The full variables schema (types, declarative bindings, sub-composition overrides, precedence) lives in the `hyperframes-core` skill.
 
 ## Fire-and-forget and webhooks
 

package/dist/skills/hyperframes-cli/references/cloudrun.md

@@ -0,0 +1,62 @@
+# Cloud Run rendering on Google Cloud
+
+Use `hyperframes cloudrun` only when the user explicitly wants self-managed Google Cloud infrastructure. It deploys Cloud Run, Workflows, and Cloud Storage. For a managed default use `hyperframes cloud`; for AWS use `hyperframes lambda`.
+
+## Prerequisites
+
+- `gcloud` is authenticated and the target project has billing enabled.
+- Terraform 1.5 or newer is on `PATH`.
+- Docker or permission to use Cloud Build is available.
+
+## Lifecycle
+
+```bash
+npx hyperframes cloudrun deploy --project <gcp-project> --region us-central1
+npx hyperframes cloudrun sites create ./project
+npx hyperframes cloudrun render ./project --width 1920 --height 1080 --wait
+npx hyperframes cloudrun progress <execution-name>
+npx hyperframes cloudrun destroy --project <gcp-project>
+```
+
+`deploy` enables the required Google APIs, builds or accepts a container image, applies the bundled Terraform module, and stores the resulting coordinates in `~/.hyperframes/cloudrun-state.json`. Use deploy flags such as `--image`, `--repo`, `--cpu`, `--memory`, `--max-instances`, and `--timeout` only when the infrastructure needs those overrides.
+
+`sites create` uploads a content-addressed project archive for reuse by `render-batch`; pass its `--site-id` to that command to skip the batch upload. Single `cloudrun render` currently resolves the project from its directory and does not consume `--site-id`. Both render commands require `--width` and `--height`; supported output formats are `mp4`, `mov`, `png-sequence`, and `webm`. Use `--output-resolution 4k` to supersample an authored composition without changing its layout dimensions.
+
+Common render flags are `--fps 24|30|60`, `--quality draft|standard|high`, `--codec h264|h265` for MP4, `--chunk-size`, `--max-parallel-chunks`, `--target-chunk-frames`, `--render-id`, `--output-key`, `--wait`, and `--wait-interval-ms`. Use `--json` for machine-readable output.
+
+For a variable-driven single render:
+
+```bash
+npx hyperframes cloudrun render ./template \
+  --width 1920 --height 1080 \
+  --variables-file ./alice.json \
+  --strict-variables \
+  --wait
+```
+
+Use exactly one of `--variables` and `--variables-file`. Read [`variables-and-media.md`](../../hyperframes-core/references/variables-and-media.md#variables) for the composition-side contract.
+
+## JSONL batches
+
+```bash
+npx hyperframes cloudrun render-batch ./template \
+  --batch ./users.jsonl \
+  --width 1920 --height 1080 \
+  --max-concurrent 10 \
+  --site-id <site-id> \
+  --json
+```
+
+Each nonblank line must contain an `outputKey`; `variables` is optional:
+
+```json
+{ "outputKey": "renders/alice.mp4", "variables": { "name": "Alice" } }
+```
+
+- `--max-concurrent` defaults to `50` and limits in-flight executions. `--max-parallel-chunks` separately limits chunks inside one render.
+- `--dry-run` parses the file and prints `would-start` rows without starting executions.
+- The template uploads once unless `--site-id` is supplied.
+- Per-entry start errors remain visible and make the command exit nonzero.
+- Do not rely on `--strict-variables` for `cloudrun render-batch`: the current command accepts the flag but does not validate batch rows. Validate the JSONL variable objects against the composition schema before dispatch. The strict gate does work for single `cloudrun render`.
+
+`render` without `--wait` returns an execution name. Use `cloudrun progress <execution-name>` until it succeeds, then verify the reported GCS output. `destroy` removes the Terraform-managed stack and its scratch bucket; preserve any deliverables that must outlive the stack.

package/dist/skills/hyperframes-cli/references/compare-and-batch.md

@@ -0,0 +1,105 @@
+# Compare and batch rendering
+
+Use these commands for deliberate visual comparison or variable-driven template output. They do not replace `lint`, `check`, final preview approval, or output verification.
+
+## Contents
+
+- [Compare projects or variants](#compare-projects-or-variants)
+- [Compare color grades](#compare-color-grades)
+- [Batch template renders](#batch-template-renders)
+
+## Compare projects or variants
+
+Render the same timestamp from two or more project directories or HTML files into one labeled contact sheet:
+
+```bash
+npx hyperframes compare <path-a> <path-b> [<path-c> ...] \
+  --at <seconds> \
+  --labels baseline,candidate \
+  --out compare.png \
+  --cols 2
+```
+
+Useful options:
+
+- `--at <seconds>` selects the shared comparison time.
+- `--labels <a,b,...>` labels cells in input order.
+- `--out <file>` chooses the sheet path.
+- `--cols <n>` controls its grid.
+- `--json` returns machine-readable results.
+- `--timeout <ms>` changes the per-variant render-ready timeout.
+
+One sheet accepts at most 16 variants. Extra inputs are truncated with a warning; split larger comparisons into several runs.
+
+`compare` is a visual review surface, not a quality gate. Run it when checking a baseline against a candidate, comparing implementation variants, or verifying that a repair preserves the intended look. Inspect the generated image; do not treat command success as visual approval.
+
+## Compare color grades
+
+Create grade candidates from a source frame:
+
+```bash
+npx hyperframes grade-compare \
+  --for frame.png \
+  --grades grades.json \
+  --project . \
+  --out grade-compare.png
+```
+
+`grades.json` is an array of labeled HyperFrames grading blocks:
+
+```json
+[{ "label": "warm", "grading": { "temperature": 0.2, "contrast": 0.1 } }]
+```
+
+Or compare explicit LUT files:
+
+```bash
+npx hyperframes grade-compare \
+  --for source.mp4 \
+  --luts warm.cube,cool.cube \
+  --out grade-compare.png
+```
+
+- `--for` accepts an image or a video. For video input, the command extracts the first frame.
+- Supply exactly one candidate source: `--grades <json>` or `--luts <a.cube,b.cube>`.
+- A neutral baseline is included by default; pass `--no-baseline` only when the baseline is not a useful reference.
+- The command accepts at most 16 candidate grades. With the default neutral baseline, the sheet may contain 17 cells. Extra candidates are truncated with a warning; split larger sets into several runs.
+- `--timeout <ms>` changes the render-ready timeout for the generated comparison composition.
+- Use `--json` for machine-readable output.
+
+This command helps select a grade. It does not apply the selected grade to the composition or replace `/media-use` provenance and LUT validation.
+
+## Batch template renders
+
+`render --batch` accepts either a JSON array of variable objects or an object with a `rows` array:
+
+```json
+{
+  "rows": [
+    { "name": "alpha", "headline": "Hello" },
+    { "name": "beta", "headline": "Welcome" }
+  ]
+}
+```
+
+Declare the variables in the composition, then run:
+
+```bash
+npx hyperframes render \
+  --batch rows.json \
+  --output "renders/{name}.mp4" \
+  --batch-concurrency 1 \
+  --strict-variables
+```
+
+Batch rules:
+
+- Do not combine `--batch` with `--variables` or `--variables-file`; each row is the variable set for one render.
+- If `--output` is omitted, the generated filename includes `{index}` so rows remain unique.
+- Output templates support `{index}` and row keys containing letters, numbers, `_`, `.`, or `-`. A placeholder value must be a string, number, or boolean; `null`, objects, and arrays are invalid. Missing placeholders and output collisions are errors.
+- `--batch-concurrency` defaults to `1`. Raise it conservatively because each render already uses workers.
+- `--batch-fail-fast` stops scheduling after the first failure. Without it, independent rows keep running and failures remain visible in the manifest.
+- `--strict-variables` validates every row before rendering and aborts before output when the declared variable contract is violated.
+- `--json` emits progress events suitable for agents and CI.
+
+The command writes `manifest.json` in the common output directory and updates it throughout the run. It records each row's variables, status, output, error, and timing. Completion means the manifest has no failed rows and every completed output exists, is non-empty, and has a plausible duration.