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, t

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 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 . 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 Do not confuse these states: 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 . 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: 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 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, 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. 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: 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. Studio directed edits When the user refers to “this element” or the current selection, query Studio instead of guessing: 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 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 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: 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 pas

hyperframes-cli