cycle-atlas/.claude/skills/hyperframes-cli/references/init-and-scaffold.md

init, capture, skills

Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, run transcription, and install AI coding skills.

init

npx hyperframes init my-video                                    # centered blank (TTY: wizard)
npx hyperframes init my-video --example warm-grain               # pick an example
npx hyperframes init my-video --resolution portrait
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 --tailwind                         # Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive                  # CI — flag-only, same blank

Default depends on TTY: in a terminal, the CLI prompts for example/options (default: centered blank). Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and scaffolds that blank. Pass --example only to start from a named example. Pass --non-interactive to force flag-only mode on a TTY.

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. (The closed set of hyperframes:example items in registry/registry.json plus the bundled blank template. hyperframes catalog does not list examples — its --type takes only block or component — so this list has no live equivalent and is checked by bun run lint:skills.)

Other useful flags:

• --resolution — preset: landscape (1920×1080), portrait (1080×1920), landscape-4k, portrait-4k, square (1080×1080), square-4k. Aliases: 1080p, 4k, uhd, 1080p-square, 4k-square.
• --skill=<slug> — record the owning skill (e.g. hyperframes) in hyperframes.json, so every later render of this project — re-renders, npm run render, --batch — is attributed to it on anonymous telemetry without re-passing the flag. You rarely pass it by hand.
• --skip-skills — temporarily ignored: init always checks AI coding skills against GitHub while the skills.sh registry catches up. To opt out (CI/tests), set the HYPERFRAMES_SKIP_SKILLS=1 env var instead.
• --skip-transcribe — don't auto-transcribe --audio / --video with Whisper.
• --model, --language — Whisper model / language for the auto-transcription.

Tailwind (--tailwind): the scaffold pins the Tailwind v4 browser runtime, not Studio's Tailwind v3 setup.

• Keep the pinned runtime; never swap in cdn.tailwindcss.com. Renders wait for window.__tailwindReady before frame 0. For offline or locked-down renders, compile to CSS and ship the stylesheet.
• Theme and custom utilities go in <style type="text/tailwindcss"> with @theme and @utility. No v3 @tailwind base/components/utilities, no tailwind.config.js; @config and @plugin abort the browser compile.
• Write complete class tokens in the HTML. The runtime only sees classes it can scan, so never build a render-critical class name at seek time (bg-${color}-500); vary items through CSS variables (style="--i: 2") or data variants.
• Tailwind is for static layout and style; timing stays in GSAP or another seekable runtime.

When --audio or --video is supplied, init transcribes the file with Whisper. For voice/model selection see the media-use skill.

capture

npx hyperframes capture https://stripe.com                  # scaffold from a website
npx hyperframes capture https://linear.app -o linear-video  # custom output directory
npx hyperframes capture https://example.com --json          # JSON output for agents
npx hyperframes capture https://example.com --skip-assets   # skip image/SVG download
npx hyperframes capture https://example.com --skip-vision   # skip optional AI captions
npx hyperframes capture https://example.com --max-screenshots 12
npx hyperframes capture https://example.com --timeout 60000 # page-load timeout in ms
npx hyperframes capture https://example.com --capture-budget 90000 # post-navigation budget

Captures a live URL as an editable HyperFrames project: screenshots become layered scenes, assets are downloaded locally, and the result is a normal project you can lint / preview / render. Use this when the user supplies a URL as the starting point for a video.

--timeout bounds page navigation; --capture-budget is the separate cooperative budget for work after navigation (fonts, assets, vision, and contact sheets). The latter is not a hard wall-clock watchdog and cannot interrupt native work already in flight. An outer caller deadline is therefore a third, distinct timeout. An outer caller timeout leaves the capture result unknown; it does not prove HyperFrames hung or that the navigation timeout should be increased. Preserve the last phase and classify the boundary that fired. --skip-vision disables only optional AI image captioning.

For agents, use --json. The result includes ok, warnings, and lastPhase. The command also emits stable HYPERFRAMES_CAPTURE_PHASE records so a watchdog can report the last started, completed, or degraded phase without retaining sensitive payloads.

Treat a non-zero exit, JSON ok: false, or an output BLOCKED.md as a hard stop. Do not render, build, or infer brand/design data from partial files in a blocked capture. A successful capture may degrade an optional phase within budget, but its structural output still has to be usable. Exit zero and file existence alone are not semantic success: require the current invocation's JSON ok: true, no BLOCKED.md, and artifacts usable for the video. Run each retry into a fresh output directory; never merge or reuse a blocked attempt's partial output.

skills

npx hyperframes skills    # install HyperFrames skills for AI coding tools

One-time setup that adds the HyperFrames skill pack (/hyperframes with its references, /hyperframes-cli, /hyperframes-registry, /media-use, /figma, /slideshow, /remotion-to-hyperframes) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.