hyperframes-cli Checked

• **--json is available on every command except render, preview, and play.** Use it for any agent / CI invocation of the supported commands; output includes a _meta envelope (cli version, latest available, update advice). render reports status via stdout + exit code only — verify success with the post-render check below; preview / play are servers, no JSON.
• **doctor --json always exits 0**, even when the environment is broken. Gate on the payload's ok field: npx hyperframes doctor --json | jq -e '.ok' > /dev/null. This insulates pipelines from CLI release churn.
• **Non-TTY mode is auto-detected.** When stdout is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; init then **requires --example**. Pass --non-interactive to force this mode even on a TTY.
• **CI gating on render**: --strict fails on lint errors, --strict-all fails on warnings too, --strict-variables fails on undeclared --variables keys.
• **Paths in --json are redacted** — $HOME becomes the literal $HOME so output is safe to paste into bug reports and agent contexts.
• **Render is user-gated.** Never auto-render once the checks pass. Pause at preview, tell the user the video is editable in Studio, and render only after they approve.
• **Post-render verification.** After render returns exit 0, confirm the output file exists and has plausible size before reporting success: [ -s "$OUTPUT" ] || echo "render produced no output". The CLI prints ◇ <path> on success; for long renders also sanity-check duration with ffprobe -i "$OUTPUT" -show_format -v error.

Routing

| Want to… | Read |

| ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |

| Scaffold a project (init, capture, skills) | references/init-and-scaffold.md |

| Check correctness (lint, validate, inspect, snapshot) | references/lint-validate-inspect.md |

| Preview or render (preview, play, render, publish) | references/preview-render.md |

| Diagnose the environment (doctor, browser) | references/doctor-browser.md |

| Cloud render on AWS Lambda (lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |

| Everything else (info, upgrade, compositions, docs, benchmark, telemetry, asset preprocessing) | references/upgrade-info-misc.md |

Cross-Skill Hand-Offs

• **Tailwind projects** (init --tailwind) → use hyperframes-core (Tailwind reference) before editing classes or theme tokens.
• **Registry blocks/components** (hyperframes add, hyperframes catalog) → use hyperframes-registry for install paths, sub-composition wiring, and snippet merging.
• **Asset preprocessing** (tts, transcribe, remove-background) → use hyperframes-media for voice selection, Whisper model rules, captions, and TTS-to-captions chain.
• **Parametrized renders** (--variables) → declared via data-composition-variables on <html>; see hyperframes-core for the full schema.

Lambda (Cloud Rendering)

hyperframes lambda deploys distributed rendering to AWS Lambda and drives renders from your laptop or CI. End-to-end is three commands:

npx hyperframes lambda deploy                                             # provision SAM stack (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # tear down (S3 bucket is retained)

Use Lambda when a render is too long / too large for one host (multi-minute videos, 4K, large parallel batches) and you have AWS credentials configured. For dev-loop iteration stay on local render.

See references/lambda.md for prerequisites, all 6 subcommands (deploy, sites create, render, progress, destroy, policies), IAM policy validation, state files, and cost / cleanup rules.

Minimum Completion Gate

### Static gates

npx hyperframes lint
npx hyperframes validate

Add inspect for layout-sensitive work and render --strict in CI to fail on lint errors.

### Visual smoke test — required when the project uses sub-compositions

lint / validate / inspect evaluate each composition **in isolation**. They never load index.html and mount sub-compositions via data-composition-src, so they cannot catch cross-file mount failures (see hyperframes-core → references/sub-compositions.md, "Common pitfalls"). The only gate that catches them is one that actually loads index.html and seeks the timeline.

Use hyperframes snapshot — it loads the project the same way render does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:

# Capture one frame at the midpoint of every sub-composition.
# Midpoints = data-start + data-duration/2 for each host slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Or, if you don't need per-scene targeting, an evenly-spaced sample:
npx hyperframes snapshot --frames 9

Output lands in snapshots/frame-NN-at-Xs.png. Eyeball each frame against the scene plan.

Per-frame red flags (each maps to a specific failure mode the static gates miss):

| What you see | Root cause