@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/hyperframes/scripts/plugin-cli.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Run from the user's project; locate the release from this installed file.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = fileURLToPath(new URL("../../../", import.meta.url));
+const manifests = [
+  "plugin.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  ".cursor-plugin/plugin.json",
+  "gemini-extension.json",
+];
+
+export function pluginVersion(pluginRoot = root) {
+  for (const path of manifests) {
+    const file = join(pluginRoot, path);
+    if (!existsSync(file)) continue;
+    const manifest = JSON.parse(readFileSync(file, "utf8"));
+    if (
+      manifest.name !== "hyperframes" ||
+      !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version ?? "")
+    ) {
+      throw new Error(`Invalid HyperFrames plugin release: ${file}`);
+    }
+    return manifest.version;
+  }
+  throw new Error(
+    "No HyperFrames plugin manifest found. Use the standalone skills installation instructions.",
+  );
+}
+
+export function invocation(
+  args,
+  {
+    version = pluginVersion(),
+    env = process.env,
+    platform = process.platform,
+    node = process.execPath,
+    pathExists = existsSync,
+  } = {},
+) {
+  if (args[0] === "skills")
+    throw new Error(
+      "Update HyperFrames through your agent's plugin manager; bundled skills are release-managed.",
+    );
+  const childEnv = {
+    ...env,
+    HYPERFRAMES_SKIP_SKILLS: "1",
+    HYPERFRAMES_SKILL_PKG_VERSION: version,
+    HYPERFRAMES_PLUGIN_VERSION: version,
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+  };
+  if (args[0] === "--script") {
+    if (!args[1]) throw new Error("--script requires a Node script path.");
+    return { command: node, args: args.slice(1), env: childEnv };
+  }
+  const cliArgs = ["--yes", `hyperframes@${version}`, ...args];
+  if (platform !== "win32") return { command: "npx", args: cliArgs, env: childEnv };
+  const candidates = [
+    env.npm_execpath && win32.join(win32.dirname(env.npm_execpath), "npx-cli.js"),
+    win32.join(win32.dirname(node), "node_modules", "npm", "bin", "npx-cli.js"),
+  ].filter(Boolean);
+  const npx = candidates.find(pathExists);
+  if (!npx)
+    throw new Error(
+      "Cannot find npx-cli.js. Install Node.js with npm or run from an npm environment.",
+    );
+  return { command: node, args: [npx, ...cliArgs], env: childEnv };
+}
+
+if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+  try {
+    const command = invocation(process.argv.slice(2));
+    const result = spawnSync(command.command, command.args, {
+      env: command.env,
+      stdio: "inherit",
+      windowsHide: true,
+    });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/vendor/hyperframes/dist/skills/hyperframes/scripts/plugin-cli.test.mjs

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  copyFileSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { invocation, pluginVersion } from "./plugin-cli.mjs";
+
+function fixture(t, manifest = "plugin.json", version = "1.2.3") {
+  const root = mkdtempSync(join(tmpdir(), "hf-plugin-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  mkdirSync(join(root, "skills/hyperframes/scripts"), { recursive: true });
+  mkdirSync(join(root, manifest, ".."), { recursive: true });
+  writeFileSync(join(root, manifest), JSON.stringify({ name: "hyperframes", version }));
+  const launcher = join(root, "skills/hyperframes/scripts/plugin-cli.mjs");
+  copyFileSync(new URL("./plugin-cli.mjs", import.meta.url), launcher);
+  return { root, launcher };
+}
+
+for (const manifest of [
+  "plugin.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  ".cursor-plugin/plugin.json",
+  "gemini-extension.json",
+]) {
+  test(`locates ${manifest} without repository packages`, (t) => {
+    const { root } = fixture(t, manifest);
+    assert.equal(pluginVersion(root), "1.2.3");
+  });
+}
+
+test("rejects missing and floating plugin versions", (t) => {
+  const { root } = fixture(t, "plugin.json", "latest");
+  assert.throws(() => pluginVersion(root), /Invalid HyperFrames plugin release/);
+  rmSync(join(root, "plugin.json"));
+  assert.throws(() => pluginVersion(root), /No HyperFrames plugin manifest/);
+});
+
+test("pins CLI, suppresses standalone refresh, preserves unrelated environment", () => {
+  const result = invocation(["init", "project with spaces", "--non-interactive"], {
+    version: "1.2.3",
+    platform: "darwin",
+    env: { PATH: "/bin", HYPERFRAMES_SKIP_SKILLS: "0" },
+  });
+  assert.equal(result.command, "npx");
+  assert.deepEqual(result.args, [
+    "--yes",
+    "hyperframes@1.2.3",
+    "init",
+    "project with spaces",
+    "--non-interactive",
+  ]);
+  assert.deepEqual(result.env, {
+    PATH: "/bin",
+    HYPERFRAMES_SKIP_SKILLS: "1",
+    HYPERFRAMES_SKILL_PKG_VERSION: "1.2.3",
+    HYPERFRAMES_PLUGIN_VERSION: "1.2.3",
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+  });
+  assert.throws(() => invocation(["skills", "update"], { version: "1.2.3" }), /plugin manager/);
+});
+
+test("Windows launches npx through Node without shell argument interpretation", () => {
+  const result = invocation(["render", "a & b"], {
+    version: "1.2.3",
+    platform: "win32",
+    node: String.raw`C:\Program Files\nodejs\node.exe`,
+    env: { npm_execpath: String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js` },
+    pathExists: (p) => p === String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npx-cli.js`,
+  });
+  assert.equal(result.command, String.raw`C:\Program Files\nodejs\node.exe`);
+  assert.deepEqual(result.args, [
+    String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npx-cli.js`,
+    "--yes",
+    "hyperframes@1.2.3",
+    "render",
+    "a & b",
+  ]);
+  assert.throws(
+    () => invocation([], { version: "1.2.3", platform: "win32", env: {}, pathExists: () => false }),
+    /Cannot find npx/,
+  );
+});
+
+test("installed helper keeps cwd, arguments, release environment and exit code", (t) => {
+  const { root, launcher } = fixture(t);
+  const project = join(root, "user project");
+  mkdirSync(project);
+  const helper = join(root, "helper.mjs");
+  writeFileSync(
+    helper,
+    "console.log(JSON.stringify({ cwd: process.cwd(), args: process.argv.slice(2), skip: process.env.HYPERFRAMES_SKIP_SKILLS, version: process.env.HYPERFRAMES_SKILL_PKG_VERSION })); process.exit(7);",
+  );
+  const before = readFileSync(join(root, "plugin.json"), "utf8");
+  const result = spawnSync(
+    process.execPath,
+    [launcher, "--script", helper, "literal $value & spaces"],
+    { cwd: project, encoding: "utf8" },
+  );
+  assert.equal(result.status, 7, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), {
+    cwd: realpathSync(project),
+    args: ["literal $value & spaces"],
+    skip: "1",
+    version: "1.2.3",
+  });
+  assert.equal(readFileSync(join(root, "plugin.json"), "utf8"), before);
+});

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

@@ -0,0 +1,189 @@
+---
+name: hyperframes-cli
+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, timeline, history, clean, 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.
+---
+
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
+# HyperFrames CLI
+
+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>` (centered blank). Or capture a site. Pass `--example=<name>` only to start from a named example.
+2. **Find the move:** if the request names an asset, sound, image, voice or fast visual edit, resolve it through `/media-use` before proposing a plan. Otherwise, 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`. To know what is on a project's timeline (tracks, clips, starts, ends, what plays), run `npx hyperframes timeline --json` instead of reading `index.html` and every sub-composition file: nested rows carry absolute main-timeline `absStart`/`absEnd` and their owning `file`, not just their local, per-sub-composition time. Prefer `--json` over the text form; it costs fewer tokens for the same or better correctness. See `references/upgrade-info-misc.md` for one-liners that answer common questions without reading the whole output.
+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 `--quality draft` while iterating, `--quality looks` for the first real encode (the CLI default), and `--quality delivery` for final delivery.
+9. **Hand the project to the desktop app (on offer):** when the render's Framey line ends in `hyperframes open …`, offer `npx hyperframes open [dir]`. It opens the project in the HyperFrames desktop app and adds it to Home; under Claude Code or Codex its chat picks up this conversation. Without the app it exits 1 and prints the download link. `--json` for agents.
+10. **Verify the output:** confirm the file exists and is non-empty. Read the render summary's second line (`beginframe` vs `screenshot`, GPU, stage timings). `screenshot` + `software gpu` on Linux is the slow path. `ffprobe -v error -show_format -show_streams` and compare duration (and fps if the brief set it) to the root `data-duration`.
+
+<!-- history (trial): remove this block together with the command -->
+
+### Project history in your turn
+
+Every write to the project is kept as an entry that can be undone. Use it at two moments only, never on every step:
+
+- **Start of a turn:** `npx hyperframes history begin --who <your-name> --label "<what you are about to do>"`, then `npx hyperframes history --since mine --who <your-name>` to see what the person changed since your last turn. Build on their edits; never overwrite them.
+- **A check failed, or the person says it got worse:** `npx hyperframes history undo --who <your-name>` undoes your newest turn and leaves the person's edits alone. Do not hand-edit back. On a conflict it exits 2 and prints both choices.
+
+End each turn with `npx hyperframes history end`, so your writes read as yours, not as "Changed outside the app". While a turn is open, every write to the project counts as yours until 10 minutes pass without one; after that the turn has ended by itself.
+
+<!-- /history (trial) -->
+
+## 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.
+- A request naming an asset, sound, image, voice or fast visual edit resolves through `/media-use` before a plan is proposed.
+  Copy creator edit markup from `/hyperframes-core` → `references/creator-editing-recipes.md`.
+
+```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 looks --output out.mp4
+test -s out.mp4
+ffprobe -v error -show_format -show_streams out.mp4
+```
+
+`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.
+
+## Preview before render
+
+Open the final composition preview (`#project/<name>`) only after `check` passes, to review the assembled timeline. The plan in chat and the `storyboard.html` sketch sheet are not approval of the final video. Rendering always requires the final approval defined by `hyperframes/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 snapshot --at <t1>,<t2>,<t3>
+```
+
+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.
+
+## Agent conventions
+
+- **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, description and tags, 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, or when a search returned nothing and a better tier is still waiting on someone's consent. 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. Under `--json` there is no prompt, but a search that found nothing puts the same ask in `warnings`, so read that array and put the decision to the user yourself. When the person asks what the download is, why this model, or what leaves the machine, point them to https://hyperframes.heygen.com/developers/catalog-search.
+
+- 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 doctor --json | jq -e '.ok' >/dev/null
+  ```
+
+- Non-TTY mode is automatic and scaffolds the centered blank. Pass `--example` only to start from a named example. Use `--non-interactive` to force flag-only mode on a TTY.
+- Use one `HYPERFRAMES_RUN_ID` for all commands in the same verification loop.
+- When disk is tight, run `npx hyperframes clean` (`--dry-run` to list first); it removes what dead renders left and idle caches that rebuild themselves, never outputs, sources or anything a running render uses. Write QC frames to a temp dir, not the project.
+- 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.
+
+## Studio-directed edits
+
+When the user refers to “this element” or the current selection, query Studio instead of guessing:
+
+```bash
+npx hyperframes preview --context --json --context-fields selection
+```
+
+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`.
+
+## Render choices
+
+| Need                                     | Command                                                                       |
+| ---------------------------------------- | ----------------------------------------------------------------------------- |
+| Fast local iteration                     | `npx hyperframes render --quality draft`                                      |
+| First real encode                        | `npx hyperframes render --quality looks --output out.mp4`                     |
+| Final local delivery                     | `npx hyperframes render --quality delivery --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` |
+
+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).
+
+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.
+
+After verifying a successful render, send one feedback report unless telemetry is disabled or the user opted out:
+
+```bash
+npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
+```
+
+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`.
+
+## 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.
+
+| 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`, `timeline`, `docs`, `benchmark`, telemetry, media preprocessing | `references/upgrade-info-misc.md`     |
+
+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
+npx hyperframes media-treatment --capabilities
+npx hyperframes figma asset KEY:10-20
+```
+
+`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.
+
+## Commands you should not run
+
+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.
+
+## Remaining harness usage
+
+Run `npx hyperframes usage --json` at the start of a video workflow and again at milestones such as after drafting and before rendering. A fresh read at handoff can serve as the start read. Use `--harness claude-code`, `--harness codex`, or `--harness grok` to select explicitly.
+
+Known results contain `status: "known"`, `harness`, `planTier`, `session`, and `weekly`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`.
+
+Unknown results contain `status: "unknown"` and a token-free `reason`. Missing, expired, unsupported, ambiguous, or unreadable logins and unavailable provider responses return unknown. Report the unknown state without guessing allowance. The command reads existing credentials without refreshing or rewriting them and emits no tokens or telemetry. Usage is a snapshot; it does not reserve allowance or estimate the next video's cost. Keep scope and workflow choices with the user.

package/vendor/hyperframes/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/vendor/hyperframes/dist/skills/hyperframes-cli/references/cloud.md

@@ -0,0 +1,163 @@
+# cloud — HeyGen-hosted rendering (zero-infra)
+
+`hyperframes cloud render` renders a composition on HeyGen's managed cloud. The CLI zips the project, uploads it, runs the render on HeyGen's infrastructure (Chromium + FFmpeg), and downloads the finished video. Nothing to deploy, and no Chrome/FFmpeg/AWS to manage; you pay per credit.
+
+```bash
+npx hyperframes auth login            # one-time sign-in
+npx hyperframes cloud render          # zip, upload, render, download
+```
+
+## 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
+
+Cloud rendering needs a HeyGen credential, stored at `~/.heygen/credentials` (`0600`) and shared with the [`heygen` CLI](https://github.com/heygen-com/heygen-cli): sign in with one and the other picks up the session.
+
+```bash
+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
+```
+
+Credential resolution order (first match wins): `HEYGEN_API_KEY`, then `HYPERFRAMES_API_KEY`, then `~/.heygen/credentials`. Point at a different backend with `HEYGEN_API_URL` (default `https://api.heygen.com`).
+
+## The render pipeline
+
+`cloud render` runs end-to-end:
+
+1. **Resolve the project**: a local directory (default `.`), or skip the upload with `--asset-id` / `--url`.
+2. **Auto-detect aspect ratio** from the entry HTML's `data-width`/`data-height`.
+3. **Zip** the project (same ignore set as `hyperframes publish`, including `.hyperframesignore`).
+4. **Upload** the zip through the direct-to-S3 asset flow, yielding an `asset_id`.
+5. **Submit** the render to `POST /v3/hyperframes/renders`, yielding a `render_id`.
+6. **Poll** `GET /v3/hyperframes/renders/{id}` until it completes or fails (skip with `--no-wait`).
+7. **Download** the signed video URL to disk.
+
+## Archive size and `.hyperframesignore`
+
+The direct-upload limit is 200 MB. HyperFrames automatically excludes root-level `renders/` and `snapshots/`, along with its existing development exclusions such as `.git`, `node_modules`, `dist`, `.next`, `coverage`, and dotfiles. Add project-specific gitignore-style rules to `<project>/.hyperframesignore` when other generated or intermediate assets are not required at render time. The same rules affect `hyperframes publish`.
+
+Inspect the exact archive without authenticating, uploading, spending credits, or starting a render:
+
+```bash
+npx hyperframes cloud render <project> --dry-run --json
+```
+
+The result reports compressed `size_bytes`, `file_count`, the 200 MB limit, and the ten largest included files.
+
+When a cloud upload reports a size-limit error, agents must use this workflow:
+
+1. Run the dry-run command and inspect the largest included files and directories.
+2. Classify obvious generated outputs first: old renders, extra snapshot/contact-sheet directories, caches, exported previews, and source media used only to produce final assets.
+3. Before excluding anything else, search `src`, `href`, `url()`, `data-composition-src`, JavaScript strings, manifests, and variable-driven paths across every HTML, CSS, and JavaScript entry.
+4. Preserve existing `.hyperframesignore` comments and rules. Add the narrowest verified-unneeded root-relative paths; prefer an exact directory or file over a broad wildcard.
+5. Never ignore `index.html`, the selected composition, mounted sub-compositions, fonts, images, audio, video, scripts, or manifests merely because they are large. Never ignore all of `assets/`.
+6. Rerun dry-run until the archive is below the limit, then run `npx hyperframes check`. Remember that `check` sees the source directory, so it cannot prove a dynamically computed asset path remains in the filtered archive; the reference audit is still required.
+
+Example:
+
+```gitignore
+# Additional generated verification passes
+/snapshots2/
+/snapshots3/
+
+# Master used only to produce the final background clips
+/assets/bg-pattern.mp4
+```
+
+Rules support comments, globs, and negation. A later rule can override a default, for example `!/snapshots/` when that directory intentionally contains render inputs.
+
+## Render options
+
+| Flag                   | Default                     | Meaning                                                                                                                        |
+| ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--fps`                | `30`                        | Frames per second, 1–240.                                                                                                      |
+| `--quality`            | `standard`                  | `draft`, `standard`, or `high`.                                                                                                |
+| `--format`             | `mp4`                       | `mp4`, `webm`, or `mov` (webm/mov carry alpha).                                                                                |
+| `--resolution`         | `1080p`                     | `1080p` or `4k` (4k billed at 1.5×).                                                                                           |
+| `--aspect-ratio`       | auto                        | `16:9`, `9:16`, or `1:1`. Auto from a local project's `data-width`/`data-height`; defaults to `16:9` for `--asset-id`/`--url`. |
+| `--composition` / `-c` | `index.html`                | Entry HTML file inside the zip.                                                                                                |
+| `--output` / `-o`      | `renders/<render_id>.<ext>` | Local download destination.                                                                                                    |
+| `--dry-run`            | off                         | Build and inspect a local project zip without authenticating, uploading, or rendering.                                         |
+
+```bash
+npx hyperframes cloud render . \
+  --composition compositions/intro.html \
+  --output ./renders/intro.mp4
+
+npx hyperframes cloud render --quality high --fps 60
+```
+
+`--resolution 4k` cannot combine with `--format webm`/`mov`: the 4k supersampling path has no alpha channel. Render 4k as mp4, or render alpha at native resolution.
+
+## Templates and variables
+
+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"}'
+npx hyperframes cloud render --variables-file ./vars.json
+npx hyperframes cloud render --variables '{"title":"Q4 Recap"}' --strict-variables
+```
+
+For a **local project** the CLI validates `--variables` against the declared schema _before_ uploading. For `--asset-id`/`--url` the schema lives server-side, so mismatches surface as a `hyperframes_project_invalid` API error.
+
+**Upload once, re-render many** is the idiomatic template loop: render a local project to get its `asset_id`, then re-submit against that asset with new values (no re-zip, no re-upload).
+
+```bash
+npx hyperframes cloud render ./card-template                              # note the asset_id printed on upload
+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, 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
+
+By default the CLI blocks, polls, and downloads. Combine `--no-wait` (submit and exit with just the `render_id`) with `--callback-url` (HTTPS webhook on terminal status) for true fire-and-forget:
+
+```bash
+npx hyperframes cloud render --callback-url https://example.com/hf-hook --no-wait
+#    Poll later with: hyperframes cloud get hfr_def456
+```
+
+| Flag              | Meaning                                             |
+| ----------------- | --------------------------------------------------- |
+| `--no-wait`       | Submit and exit immediately; print the `render_id`. |
+| `--callback-url`  | HTTPS webhook fired when the render terminates.     |
+| `--callback-id`   | Opaque tracking ID echoed in webhook payloads.      |
+| `--poll-interval` | Poll cadence in seconds (default `10`).             |
+| `--max-wait`      | Max poll duration in minutes (default `60`).        |
+
+## Managing renders
+
+```bash
+npx hyperframes cloud list                 # recent renders (--limit, --token, --all)
+npx hyperframes cloud get hfr_def456       # full detail + short-lived signed video_url
+npx hyperframes cloud delete hfr_def456    # soft-delete (--no-confirm to skip the prompt)
+```
+
+`video_url` and `thumbnail_url` are short-lived presigned URLs, so re-fetch with `cloud get` rather than caching them.
+
+## Safe retries
+
+The CLI transparently retries a `401` by force-refreshing the OAuth token and replaying. That's harmless for reads, but the zip upload (`POST /v3/assets`) is **not** idempotent: a blind retry creates a duplicate asset and bills twice. Pass `--idempotency-key` so retries are safe:
+
+```bash
+npx hyperframes cloud render . --idempotency-key "$(uuidgen)"
+```
+
+The key is forwarded to both upload and submit (the server scopes idempotency per-endpoint, so reusing one value is safe). Use any opaque string in `[A-Za-z0-9_:.-]`, 1–255 chars.
+
+Full flag reference: docs `/deploy/cloud` and `/packages/cli#hyperframes-cloud`.