dsh-hyperframes 0.2.0 → 0.3.1

package/skills/hyperframes-audio/scripts/carve.test.mjs

@@ -0,0 +1,239 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { carveSources, groupSourceRefusal, loadCore } from "./carve.mjs";
+
+const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** A voice as `detectTracks` yields it: an id plus its raw opening tag. */
+function voice(id, group) {
+  const attr = group === undefined ? "" : ` data-audio-group="${group}"`;
+  return { id, tag: `<audio id="${id}"${attr} src="${id}.wav"></audio>` };
+}
+
+/** An audio member as `main` describes it for the source decision. */
+function member(id, group, nameKind) {
+  return { id, group, nameKind };
+}
+
+/** A bed as `mediaElements` yields it: `kind` is what decides group membership. */
+function bed(id, group, kind = "audio") {
+  const attr = group === undefined ? "" : ` data-audio-group="${group}"`;
+  return { id, kind, tag: `<${kind} id="${id}"${attr} src="${id}.mp3"></${kind}>` };
+}
+
+async function inTempDir(run) {
+  const dir = mkdtempSync(join(tmpdir(), "carve-test-"));
+  try {
+    return await run(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("voices sharing one group carve against the group, not their ids", () => {
+  // SKILL.md's invariant: "A carve against more than one clip id is wrong.
+  // Group the clips and carve against the group." Naming the group lets
+  // membership resolve at analysis time, so a voice added later is covered.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover"), voice("vo3", "voiceover")];
+  assert.deepEqual(carveSources(voices, undefined, []), ["voiceover"]);
+});
+
+test("a single grouped voice still records the group", () => {
+  assert.deepEqual(carveSources([voice("vo1", "voiceover")], undefined, []), ["voiceover"]);
+});
+
+test("ungrouped voices keep their ids, so the lint rule can still say so", () => {
+  // Not silently inventing a group: `audio_carve_ungrouped_sources` is the
+  // right signal here, and it needs the ids to fire on.
+  assert.deepEqual(carveSources([voice("vo1"), voice("vo2")], undefined, []), ["vo1", "vo2"]);
+});
+
+test("voices in DIFFERENT groups keep their ids", () => {
+  // One carve cannot name two groups, and picking either would silently drop
+  // the other's members from the analysis.
+  const voices = [voice("vo1", "narration"), voice("vo2", "interview")];
+  assert.deepEqual(carveSources(voices, undefined, []), ["vo1", "vo2"]);
+});
+
+test("a partially grouped set keeps its ids", () => {
+  const voices = [voice("vo1", "voiceover"), voice("vo2")];
+  assert.deepEqual(carveSources(voices, undefined, []), ["vo1", "vo2"]);
+});
+
+test("an empty group attribute is not a group", () => {
+  assert.deepEqual(carveSources([voice("vo1", ""), voice("vo2", "")], undefined, []), [
+    "vo1",
+    "vo2",
+  ]);
+});
+
+// The nine cases above pass `[]` explicitly because they predate the membership
+// check and are about the bed and the group attributes alone. `members` is a
+// required argument: with `[]` the `mixed` refusal cannot fire, so a default
+// would let a call that forgot it return the group form and silently undo the
+// widening fix — see the wiring test at the bottom of this file.
+
+test("a bed inside the voices' group keeps clip ids, so it is never its own source", () => {
+  // `resolveCarveSourceIds` expands a group to every CURRENT member, and it gets
+  // no host element to exclude — so naming a group the bed belongs to puts the
+  // bed in its own voice list on the next analysis, and it is carved against
+  // itself. This run cannot see it (main sums the detected voices directly), so
+  // the check has to happen here.
+  const voices = [voice("vo1", "mix"), voice("vo2", "mix")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "mix"), []), ["vo1", "vo2"]);
+});
+
+test("a bed in a DIFFERENT group leaves the group form alone", () => {
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), []), ["voiceover"]);
+});
+
+test("an ungrouped bed leaves the group form alone", () => {
+  assert.deepEqual(carveSources([voice("vo1", "voiceover")], bed("bgm"), []), ["voiceover"]);
+});
+
+test("a VIDEO bed is immune — group membership is audio-only", () => {
+  // `data-audio-group` on a <video> is ignored by core, so expanding the group
+  // can never pull this bed in and declining would be a false positive.
+  const voices = [voice("vo1", "mix"), voice("vo2", "mix")];
+  assert.deepEqual(carveSources(voices, bed("clip", "mix", "video"), []), ["mix"]);
+});
+
+test("an sfx member of the voices' group blocks the group form", () => {
+  // The group resolves wider than the analysis: `resolveCarveSourceIds` expands
+  // it to every current member and `resolveCarveVoices` keeps any audio with a
+  // src, so an sfx clip sharing the voice group enters the sidechain on the next
+  // analysis and ducks the bed under a whoosh. This run cannot see it — it sums
+  // the voices `detectTracks` returned, which correctly excluded the sfx.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  const members = [
+    member("vo1", "voiceover", "voice"),
+    member("vo2", "voiceover", "voice"),
+    member("whoosh", "voiceover", "sfx"),
+    member("bgm", "music", "music"),
+  ];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["vo1", "vo2"]);
+});
+
+test("a music member of the voices' group blocks it too", () => {
+  const voices = [voice("vo1", "voiceover")];
+  const members = [member("vo1", "voiceover", "voice"), member("pad", "voiceover", "music")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["vo1"]);
+});
+
+test("a voice member this run did NOT analyse keeps the group form", () => {
+  // The designed case, and the one a membership check must not break: a voice
+  // that does not overlap the bed is left out of the analysis on purpose, and
+  // covering it on a later analysis without editing `sources` is the entire
+  // reason SKILL.md says to name the group. Refusing here would collapse the
+  // group form into clip ids for every ordinary narration sequence.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  const members = [
+    member("vo1", "voiceover", "voice"),
+    member("vo2", "voiceover", "voice"),
+    member("vo-outro", "voiceover", "voice"),
+  ];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["voiceover"]);
+});
+
+test("an unclassifiable member keeps the group form", () => {
+  // `unknown` is what `detectTracks` itself treats as a possible voice, so it is
+  // not evidence of a non-voice member — loose in the safe direction, same as
+  // detection.
+  const voices = [voice("vo1", "voiceover")];
+  const members = [member("vo1", "voiceover", "voice"), member("track7", "voiceover", "unknown")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["voiceover"]);
+});
+
+test("an sfx member of a DIFFERENT group is irrelevant", () => {
+  const voices = [voice("vo1", "voiceover")];
+  const members = [member("vo1", "voiceover", "voice"), member("whoosh", "sfx", "sfx")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["voiceover"]);
+});
+
+test("groupSourceRefusal names which member blocked the group, and why", () => {
+  // The stderr note is built from this, so it has to carry the ids: "sources are
+  // clip ids" plus `audio_carve_ungrouped_sources` reads as nonsense to an author
+  // who did group their clips.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  assert.deepEqual(
+    groupSourceRefusal(voices, bed("bgm", "music"), [member("whoosh", "voiceover", "sfx")]),
+    { group: "voiceover", reason: "mixed", ids: ["whoosh"] },
+  );
+  assert.deepEqual(groupSourceRefusal(voices, bed("bgm", "voiceover"), []), {
+    group: "voiceover",
+    reason: "bed",
+    ids: ["bgm"],
+  });
+  assert.equal(groupSourceRefusal(voices, bed("bgm", "music"), []), null);
+});
+
+test("the CLI still runs when invoked through a symlinked path", () => {
+  // argv[1] keeps the invoked spelling while import.meta.url is the realpath, so
+  // a raw compare in the entry guard skips main() and the CLI exits 0 having
+  // written nothing. macOS /tmp -> /private/tmp reaches this with no symlink of
+  // one's own; so does any skill install placed behind a link.
+  return inTempDir((dir) => {
+    const link = join(dir, "scripts-link");
+    symlinkSync(SCRIPTS_DIR, link, "junction");
+    let status = 0;
+    let stderr = "";
+    try {
+      execFileSync(process.execPath, [join(link, "carve.mjs")], { encoding: "utf-8" });
+    } catch (error) {
+      status = error.status;
+      stderr = String(error.stderr);
+    }
+    // Reaching parseArgs is the proof main() ran at all: no args is an error, and
+    // the broken guard's symptom is a silent exit 0 with no output.
+    assert.equal(status, 1, `expected the usage error, got status ${status}`);
+    assert.match(stderr, /--comp is required/);
+  });
+});
+
+test("loadCore honours an import-only export map, as the published core has", () => {
+  // The published manifest carries only `import` + `types` for these subpaths, so
+  // `require.resolve` cannot resolve them at all and the fallback has to read the
+  // export map itself. A fixture pins that without depending on npm.
+  return inTempDir(async (dir) => {
+    const pkgDir = join(dir, "node_modules", "@hyperframes", "core");
+    mkdirSync(join(pkgDir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "fixture-project" }));
+    writeFileSync(
+      join(pkgDir, "package.json"),
+      JSON.stringify({
+        name: "@hyperframes/core",
+        version: "0.0.0-fixture",
+        type: "module",
+        exports: {
+          "./package.json": "./package.json",
+          "./audio-carve": { import: "./dist/audioCarve.js" },
+          "./audio-fx": { import: "./dist/audioFx.js" },
+        },
+      }),
+    );
+    writeFileSync(join(pkgDir, "dist", "audioCarve.js"), 'export const marker = "carve";\n');
+    writeFileSync(join(pkgDir, "dist", "audioFx.js"), 'export const marker = "fx";\n');
+
+    const core = await loadCore(dir);
+    assert.equal(core.carve.marker, "carve");
+    assert.equal(core.fx.marker, "fx");
+  });
+});
+
+test("members is required, so dropping it cannot silently restore the group form", () => {
+  // The gap this closes: `main()` is the only code that BUILDS `members`, and no
+  // test runs `main()` (the symlink test stops at the usage error, a real run
+  // needs ffmpeg). With `members = []` defaulted, a refactor that dropped the
+  // third argument would return the group form again with the whole suite green
+  // — the same signature as the bug itself: first pass correct, persisted
+  // attribute wrong, nothing red. Omitting it now throws instead.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  assert.throws(() => carveSources(voices, bed("bgm", "music")), TypeError);
+  assert.throws(() => groupSourceRefusal(voices, bed("bgm", "music")), TypeError);
+});

package/skills/hyperframes-cli/SKILL.md

@@ -1,152 +1,170 @@
 ---
 name: hyperframes-cli
-description: "HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment. 中文：使用 hyperframes 命令行（初始化/校验/预览/渲染/转写/配音/环境诊断）时使用。"
-compatibility: Requires Node.js >= 22 and FFmpeg on PATH; the CLI runs via `npx hyperframes`.
-allowed-tools: Bash
+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`. Requires Node.js >= 22 and FFmpeg.
+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. **Find the move:** before authoring motion by hand, search for a primitive that already does it: `npx hyperframes catalog --query "reveal a headline one line at a time"`. Ask for the effect you want rather than the mechanism you have in mind. Install with `npx hyperframes add <name>` (see `/hyperframes-registry`). Author by hand only once nothing fits.
+3. **Author:** write the composition using `/hyperframes-core`.
+4. **Get fast feedback while editing:** run `npx hyperframes lint` after the first HTML pass and after structural changes.
+5. **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.
+6. **Inspect sub-compositions:** when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene.
+7. **Open the final Studio preview:** run `npx hyperframes preview --background`, verify the URL returns HTTP 200, hand the timeline project URL to the user, and ask whether to revise or render. Keep it alive until review ends.
+8. **Render only after approval:** use draft quality for iteration and high quality for delivery.
+9. **Verify the output:** confirm the file exists, is non-empty, and has a plausible duration.
+
+## Mandatory creator-edit cross-references
+
+- Before authoring or diagnosing a zoom, punch-in/punch-out, reframe, camera
+  move, or any keyframe motion, read `/hyperframes-keyframes` first.
+- Before `hyperframes keyframes`, read `/hyperframes-keyframes`; the command
+  surfaces animation trajectories and does not diagnose clip cuts.
+- For a cut, trim, splice, reorder, or source timing edit, read
+  `/hyperframes-core` and use its clip/timeline contract.
+- For fade-in/fade-out, crossfade, track gain, volume automation, ducking,
+  voiceover carve, or FX on placed audio, read `/hyperframes-audio`. Load core
+  alongside it when clip placement or picture timing also changes.
+- Use `/media-use` only to source/generate media or preprocess a derived asset.
+  Copy creator edit markup from `/hyperframes-core` → `references/creator-editing-recipes.md`.
 
-## Workflow
+```bash
+# Fast iteration check; repeat while authoring as needed.
+npx hyperframes lint
+
+# Required final gate; includes lint.
+npx hyperframes check
+npx hyperframes preview --background
+npx hyperframes render --quality high --output out.mp4
+test -s out.mp4
+ffprobe -v error -show_format out.mp4
+```
 
-1. **Scaffold** — `npx hyperframes init my-video`
-2. **Write** — author HTML composition (see the `hyperframes` skill)
-3. **Lint** — `npx hyperframes lint`
-4. **Visual inspect** — `npx hyperframes inspect`
-5. **Preview** — `npx hyperframes preview`
-6. **Render** — `npx hyperframes render`
+`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.
 
-Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.
+## Two different preview surfaces
 
-## Scaffolding
+Do not confuse these states:
 
-```bash
-npx hyperframes init my-video                        # interactive wizard
-npx hyperframes init my-video --example warm-grain   # pick an example
-npx hyperframes init my-video --video clip.mp4        # with video file
-npx hyperframes init my-video --audio track.mp3       # with audio file
-npx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)
-```
+| 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>`.              |
 
-Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
+The early board is not approval of the final video. Rendering always requires the final approval defined by `hyperframes-core/references/review-loop.md`.
 
-`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
+## Sub-composition smoke test
 
-## Linting
+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 lint                  # current directory
-npx hyperframes lint ./my-project     # specific project
-npx hyperframes lint --verbose        # info-level findings
-npx hyperframes lint --json           # machine-readable
+npx hyperframes snapshot --at <t1>,<t2>,<t3>
 ```
 
-Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
+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.
 
-## Visual Inspect
+## Agent conventions
 
-```bash
-npx hyperframes inspect                 # inspect rendered layout over the timeline
-npx hyperframes inspect ./my-project    # specific project
-npx hyperframes inspect --json          # agent-readable findings
-npx hyperframes inspect --samples 15    # denser timeline sweep
-npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
-```
+- **Search the catalog before writing motion by hand.** `npx hyperframes catalog --query "<the beat, in plain English>"`. Search is entirely local: there is no hosted tier, no account, and the query text is never sent anywhere. By default it ranks on vocabulary shared with the item's name, title and description, which misses any phrasing that does not reuse the catalog's own wording. Add `--on-device` to rank by meaning instead (see the offline tier below).
+- **Query in English even when the video is not.** Both tiers index an English catalog, so a query in another script produces no searchable terms and returns nothing. Describe the move in English; the on-screen copy stays in whatever language the video needs. `No searchable words in query` means exactly this and is not a missing component, so do not report it as a catalog gap.
+- **Read which tier answered; never infer it from results appearing.** With `--json` the envelope carries `query`, `tier` (`on-device` or `words`), `tier_detail`, `dropped`, `unindexed`, `shown`, `total` and `results`, plus `top_score` when the answering tier produces one and `warnings` when a tier was asked for and could not run. A weak result on `words` is expected; the same result on `on-device` is a bug. `top_score` is on-device only and has no threshold behind it: the ranker returns the whole catalog in some order for every query, so read it as evidence rather than as a pass or fail.
+- **`dropped` and `unindexed` are opposite skews between the registry and the on-device index, and rewording the query fixes neither.** `dropped` counts ranked names this registry cannot install, so the strongest matches are the ones being lost. `unindexed` counts registry moves the index cannot see at all, which no query can ever return. Refreshing the registry is not the answer to either: its manifest carries a 24h TTL and heals itself, while the vectors are a separately published artifact fetched into `~/.hyperframes/catalog/`. Re-running with `--on-device` refetches that index when `unindexed` is above zero, so that is the remedy to hand the user. A pure over-coverage skew (`dropped` above zero while `unindexed` is zero) does not trigger the refetch; clearing `~/.hyperframes/catalog/` is the only way out of that one. Both counts are of names rather than of results, so either can exceed `total`.
+- **When a search comes back with nothing worth installing, say so.** `npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>`. You do not have to assemble that line: `catalog --query` prints it pre-filled, and every `--json` search envelope carries it as `report_gap` with the query and tier already correct — fill in `--wanted` and send. This is the only path that sends a query anywhere, and it is a separate deliberate command precisely so plain `catalog --query` keeps its promise of sending nothing. **Report on either tier**, whenever the results do not do the thing; do not hold out for the on-device tier, which needs a consented 33 MB download and is therefore off in most agent runs — waiting for it means never reporting at all. The tier rides along in the report, so a vocabulary miss stays distinguishable from a meaning miss without you having to judge which one you hit. What comes back is a list of moves the catalog does not have yet, read directly rather than guessed from install counts, so the phrasing that matters is the effect you wanted, not the item name you imagined. It carries no rating and never lands in the rating metric.
+- **Offer the offline tier; never enable it silently.** A one-time ~33 MB download (a quantized ONNX build of `bge-small-en-v1.5` plus its tokenizer, pinned to a fixed revision) and the catalog vectors from the registry, both cached under `~/.hyperframes/`, neither added to the project or any package. Once cached it ranks by meaning with nothing sent. Say the size out loud and let the person decide, then pass `--on-device` (with `-y` to skip the prompt) once they agree. The interactive offer only fires on a TTY, and under `--json` nothing about it is printed at all, so in an agent run you have to raise it with the user yourself.
 
-Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
+- 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:
 
-- Text extending outside the nearest visual container or bubble
-- Text clipped by its own fixed-width/fixed-height box
-- Text extending outside the composition canvas
-- Children escaping clipping containers
+  ```bash
+  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
+  ```
 
-Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.
+- 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.
+- When a hosted cloud project approaches or exceeds the 200 MB upload limit, use `cloud render --dry-run --json` and follow the `.hyperframesignore` investigation in `references/cloud.md`. Never ignore an asset merely because it is large.
+- Never render merely because checks pass. Pause at the final preview and wait for approval.
 
-`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
+## Studio-directed edits
 
-## Previewing
+When the user refers to “this element” or the current selection, query Studio instead of guessing:
 
 ```bash
-npx hyperframes preview                   # serve current directory
-npx hyperframes preview --port 4567       # custom port (default 3002)
+npx hyperframes preview --context --json --context-fields selection
 ```
 
-Hot-reloads on file changes. Opens the studio in your browser automatically.
+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`.
 
-When handing a project back to the user, use the Studio project URL, not the
-source `index.html` path:
+## Render choices
 
-```text
-http://localhost:<port>/#project/<project-name>
-```
+| 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 the actual port from the preview output and the project directory name. For
-example, after `npx hyperframes preview --port 3017` in `hyperframes-video`,
-report `http://localhost:3017/#project/hyperframes-video`.
+Skill attribution is automatic — the examples above need no `--skill`. A project scaffolded by a workflow (`hyperframes init --skill=<workflow>`) records its owning skill in `hyperframes.json`, and every later render inherits it on anonymous telemetry: re-renders, `npm run render`, and `--batch` alike. Pass `--skill=<slug>` explicitly only to stamp a project that was not created through a workflow (its first render then persists it).
 
-Treat `index.html` as source-code context only. It is fine to link it as an
-implementation file, but do not label it as the project or preview surface.
+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.
 
-## Rendering
+After verifying a successful render, send one feedback report unless telemetry is disabled or the user opted out:
 
 ```bash
-npx hyperframes render                                # standard MP4
-npx hyperframes render --output final.mp4             # named output
-npx hyperframes render --quality draft                # fast iteration
-npx hyperframes render --fps 60 --quality high        # final delivery
-npx hyperframes render --format webm                  # transparent WebM
-npx hyperframes render --docker                       # byte-identical
+npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
 ```
 
-| Flag           | Options               | Default                    | Notes                       |
-| -------------- | --------------------- | -------------------------- | --------------------------- |
-| `--output`     | path                  | renders/name_timestamp.mp4 | Output path                 |
-| `--fps`        | 24, 30, 60            | 30                         | 60fps doubles render time   |
-| `--quality`    | draft, standard, high | standard                   | draft for iterating         |
-| `--format`     | mp4, webm             | mp4                        | WebM supports transparency  |
-| `--workers`    | 1-8 or auto           | auto                       | Each spawns Chrome          |
-| `--docker`     | flag                  | off                        | Reproducible output         |
-| `--gpu`        | flag                  | off                        | GPU-accelerated encoding    |
-| `--strict`     | flag                  | off                        | Fail on lint errors         |
-| `--strict-all` | flag                  | off                        | Fail on errors AND warnings |
+Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command (relative to the project directory — feedback is submitted to a public channel, so do **not** paste absolute paths, home-directory prefixes, or user/machine identifiers), expected versus actual behavior, exact error (also strip absolute paths from stack traces — keep basename + line, drop the leading directory), whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a `COMPOSITION_STRUCTURE:` block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
 
-**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
+## Read the matching reference before running a command
 
-## Transcription
+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.
 
-```bash
-npx hyperframes transcribe audio.mp3
-npx hyperframes transcribe video.mp4 --model medium.en --language en
-npx hyperframes transcribe subtitles.srt   # import existing
-npx hyperframes transcribe subtitles.vtt
-npx hyperframes transcribe openai-response.json
-```
+| 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`     |
 
-## Text-to-Speech
+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`.
 
-```bash
-npx hyperframes tts "Text here" --voice af_nova --output narration.wav
-npx hyperframes tts script.txt --voice bf_emma
-npx hyperframes tts --list  # show all voices
-```
-
-## Troubleshooting
+The specialized commands are deliberately documented by their owning workflows:
 
 ```bash
-npx hyperframes doctor       # check environment (Chrome, FFmpeg, Node, memory)
-npx hyperframes browser      # manage bundled Chrome
-npx hyperframes info         # version and environment details
-npx hyperframes upgrade      # check for updates
+npx hyperframes present <project-dir> --port 3004 --no-open
+npx hyperframes beats <project-dir> --json
+npx hyperframes keyframes <project-dir> --json
+npx hyperframes media-treatment --capabilities
+npx hyperframes figma asset KEY:10-20
 ```
 
-Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
+`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. `media-treatment` discovers, applies, and clears deterministic looks on local footage — start with `--capabilities` for the overview and `--capability <name>` for one family; `/media-use` owns which treatment a brief is asking for. `figma` imports over the REST API with the `asset`, `tokens`, and `component` subcommands and needs `FIGMA_TOKEN`; motion and shader import have no REST endpoint and are agent-only, so `/figma` owns those.
 
-## Other
+## Commands you should not run
 
-```bash
-npx hyperframes compositions   # list compositions in project
-npx hyperframes docs           # open documentation
-npx hyperframes benchmark .    # benchmark render performance
-```
+Two entries in `hyperframes --help` are not part of the authoring loop, and reaching for them wastes a turn:
+
+- `events` is the telemetry endpoint skills use to report their **own** invocation, ideally from a bundled script. It emits an anonymous event and exits 0 no matter what you pass it. It is not a way to read telemetry back, and an agent has no reason to call it by hand.
+- `validate`, `inspect`, and `layout` are deprecated aliases kept for old scripts. `check` is the one that is maintained, and it is what every reference in this skill assumes.

package/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.