hyperframes 0.6.97 → 0.6.98

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

@@ -1,144 +1,108 @@
 ---
 name: hyperframes-cli
-description: HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.
+description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).
 ---
 
 # HyperFrames CLI
 
-Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.
+Everything runs through `npx hyperframes` unless project instructions specify a local wrapper. Obey the local wrapper exactly. Requires Node.js >= 22 and FFmpeg.
 
 ## Workflow
 
-1. **Scaffold** — `npx hyperframes init my-video`
-2. **Write** — author HTML composition (see the `hyperframes` skill)
+1. **Scaffold** — `npx hyperframes init my-video` (or `capture` from a URL)
+2. **Write** — author HTML composition (see the `hyperframes-core` skill)
 3. **Lint** — `npx hyperframes lint`
-4. **Visual inspect** — `npx hyperframes inspect`
-5. **Preview** — `npx hyperframes preview`
-6. **Render** — `npx hyperframes render`
+4. **Validate** — `npx hyperframes validate` (runtime errors + contrast)
+5. **Visual inspect** — `npx hyperframes inspect`
+6. **Preview** — `npx hyperframes preview`
+7. **Render** — pick the variant:
+   - Iterate: `npx hyperframes render --quality draft`
+   - Deliver: `npx hyperframes render --quality high --output out.mp4`
+   - CI / cross-host repro: `npx hyperframes render --docker --strict --output out.mp4`
+   - Cloud (long / large): `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)
 
-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.
+Run lint, validate, and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `validate` loads the composition in headless Chrome and reports runtime console errors plus WCAG contrast issues. `inspect` seeks through the timeline and reports text spilling out of bubbles/containers or off the canvas.
 
-## Scaffolding
+For motion-heavy work, prefer snapshot-driven iteration — see `references/lint-validate-inspect.md` for the discipline.
 
-```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 --example blank --tailwind # with Tailwind v4 browser runtime
-npx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)
-```
-
-Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
-
-`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.
-
-When using `--tailwind`, invoke the `tailwind` skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.
+## Agent Conventions
 
-## Linting
+Cross-cutting rules that hold for every command:
 
-```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
-```
-
-Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
+- **`--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.
+- **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`.
 
-## Visual Inspect
-
-```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
-```
+## Routing
 
-Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
+| 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`     |
 
-- 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
+## Cross-Skill Hand-Offs
 
-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`.
+- **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.
 
-`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
+## Lambda (Cloud Rendering)
 
-## Previewing
+`hyperframes lambda` deploys distributed rendering to AWS Lambda and drives renders from your laptop or CI. End-to-end is three commands:
 
 ```bash
-npx hyperframes preview                   # serve current directory
-npx hyperframes preview --port 4567       # custom port (default 3002)
+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)
 ```
 
-Hot-reloads on file changes. Opens the studio in your browser automatically.
-
-When handing a project back to the user, use the Studio project URL, not the
-source `index.html` path:
+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`.
 
-```text
-http://localhost:<port>/#project/<project-name>
-```
+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.
 
-Use the actual port from the preview output and the project directory name. For
-example, after `npx hyperframes preview --port 3017` in `codex-openai-video`,
-report `http://localhost:3017/#project/codex-openai-video`.
+## Minimum Completion Gate
 
-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.
-
-## Rendering
+### Static gates
 
 ```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 lint
+npx hyperframes validate
 ```
 
-| 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                                        |
-| `--variables`        | JSON object           | —                          | Override variable values declared in `data-composition-variables`  |
-| `--variables-file`   | path                  | —                          | JSON file with variable values (alternative to `--variables`)      |
-| `--strict-variables` | flag                  | off                        | Fail render on undeclared keys or type mismatches in `--variables` |
-
-**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
+Add `inspect` for layout-sensitive work and `render --strict` in CI to fail on lint errors.
 
-**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI **`--variables '{"title":"Q4 Report"}'`** is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with **`data-variable-values`** — same object shape, scoped to one mount of the sub-composition. See the `hyperframes` skill for the full pattern.)
+### Visual smoke test — required when the project uses sub-compositions
 
-## Asset Preprocessing
+`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.
 
-`npx hyperframes tts`, `transcribe`, and `remove-background` produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each downloads its own model on first run. For voice selection, whisper model rules (the `.en`-translates-non-English gotcha), output format choice (VP9 alpha WebM vs ProRes), and the TTS → transcribe → captions chain, invoke the `hyperframes-media` skill.
-
-## Troubleshooting
+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:
 
 ```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
+# 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
 ```
 
-Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
+Output lands in `snapshots/frame-NN-at-Xs.png`. Eyeball each frame against the scene plan.
 
-## Other
+Per-frame red flags (each maps to a specific failure mode the static gates miss):
 
-```bash
-npx hyperframes compositions   # list compositions in project
-npx hyperframes docs           # open documentation
-npx hyperframes benchmark .    # benchmark render performance
-```
+| What you see                                                                       | Root cause                                                                                  |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Text shows up tiny + unstyled in the top-left corner                               | `<style>` block left in `<head>` outside `<template>` (Pitfall 1) — no CSS reached live DOM |
+| SVG/icon elements blown up to canvas-size                                          | Same as above — no width/height constraints applied                                         |
+| Hero element of the scene is missing entirely; only background + watermark visible | Host-id ≠ template id (Pitfall 2) — timeline never ran, frame captured at initial state     |
+| Snapshot command logs `Sub-composition timelines not registered after 45000ms`     | Pitfall 2 — direct confirmation                                                             |
+
+`snapshots/` can be deleted after eyeballing; the user-facing final render is a separate pass with `npx hyperframes render`.

package/dist/skills/hyperframes-cli/references/doctor-browser.md

@@ -0,0 +1,45 @@
+# doctor, browser
+
+Environment diagnosis and bundled-Chrome management. Run these first when a render or preview fails.
+
+## doctor
+
+```bash
+npx hyperframes doctor
+npx hyperframes doctor --json     # CI / agent output (always exit 0; gate on payload `ok`)
+```
+
+Runs independent checks and reports each as ok/warn/fail:
+
+- **Version** — installed CLI vs latest on npm (hints upgrade when stale)
+- **Node.js** — ≥ 22 required
+- **CPU**, **Memory**, **Disk** — host resources
+- **Environment** — env vars that affect the renderer
+- **FFmpeg** / **FFprobe** — found, version, codecs
+- **Chrome** — bundled or system, version, path
+- **Docker** / **Docker running** — required only for `render --docker`
+- **/dev/shm** — inside containers only
+
+Run `doctor` first when:
+
+- `render` fails with a Chrome or FFmpeg error.
+- `preview` opens but the composition fails to load.
+- A fresh machine has never run HyperFrames.
+
+Common issues:
+
+- **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager.
+- **Missing bundled Chrome** — run `npx hyperframes browser ensure`.
+- **Low memory** — close other Chromes, reduce `--workers`, or use `--quality draft`.
+
+## browser
+
+```bash
+npx hyperframes browser ensure    # find or download the pinned Chrome
+npx hyperframes browser path      # print the browser executable path (for scripting)
+npx hyperframes browser clear     # remove the cached Chrome download
+```
+
+Manage the Chrome build HyperFrames uses for rendering. The pinned version exists because pixel output drifts across Chrome versions — using the bundled build keeps rendered output reproducible across machines.
+
+Use `path` to embed the binary in scripts: `$(npx hyperframes browser path)`.

package/dist/skills/hyperframes-cli/references/init-and-scaffold.md

@@ -0,0 +1,51 @@
+# 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
+
+```bash
+npx hyperframes init my-video                                    # TTY: interactive wizard
+npx hyperframes init my-video --example warm-grain               # pick an example
+npx hyperframes init my-video --example blank --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 --example blank --tailwind         # Tailwind v4 browser runtime
+npx hyperframes init my-video --non-interactive --example blank  # CI/agents — flag-only
+```
+
+**Default depends on TTY**: in a terminal, the CLI prompts for example/options. Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and **requires `--example`** (the CLI errors with a usage example if missing). Pass `--non-interactive` to force flag-only mode even on a TTY.
+
+Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
+
+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`.
+- `--skip-skills` — don't install AI coding skills after scaffold.
+- `--skip-transcribe` — don't auto-transcribe `--audio` / `--video` with Whisper.
+- `--model`, `--language` — Whisper model / language for the auto-transcription.
+
+When using `--tailwind`, invoke the `hyperframes-core` (Tailwind reference) skill before editing classes or theme tokens. The scaffold uses Tailwind v4 browser runtime patterns, not Studio's Tailwind v3 setup.
+
+When `--audio` or `--video` is supplied, `init` transcribes the file with Whisper. For voice/model selection see the `hyperframes-media` skill.
+
+## capture
+
+```bash
+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 --max-screenshots 12
+npx hyperframes capture https://example.com --timeout 60000 # page-load timeout in ms
+```
+
+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.
+
+## skills
+
+```bash
+npx hyperframes skills    # install HyperFrames skills for AI coding tools
+```
+
+One-time setup that adds the HyperFrames skill pack (`hyperframes-core`, `-creative`, `-animation`, `-cli`, `-registry`, `-media`, plus the `product-launch-video` and `hyperframes-read-first` orchestrators) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.

package/dist/skills/hyperframes-cli/references/lambda.md

@@ -0,0 +1,132 @@
+# lambda — Cloud Rendering on AWS Lambda
+
+Deploy HyperFrames distributed rendering to AWS Lambda and drive renders from your laptop or CI. Wraps `@hyperframes/aws-lambda` SDK plus AWS SAM. End-to-end is three commands:
+
+```bash
+npx hyperframes lambda deploy
+npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
+npx hyperframes lambda destroy
+```
+
+## When to Use Lambda vs Local Render
+
+- **Local `render`** — dev-loop iteration, single host, anything under a few minutes at 1080p.
+- **`lambda render`** — long videos, 4K, large parallel batches, or anything where local Chrome would time out / exhaust RAM. Pay-per-invocation, no idle cost.
+
+For one-off short renders Lambda is not worth the deploy overhead.
+
+## Prerequisites
+
+- AWS credentials configured (env vars, `~/.aws/credentials`, SSO, or IMDS).
+- AWS SAM CLI on `PATH`.
+- `bun` on `PATH` (builds the Lambda handler ZIP).
+
+## Subcommands
+
+### deploy
+
+```bash
+npx hyperframes lambda deploy \
+  --stack-name=hyperframes-prod \
+  --region=us-east-1 \
+  --concurrency=8 \
+  --memory=10240
+```
+
+Builds `packages/aws-lambda/dist/handler.zip` and SAM-deploys the stack (Lambda + Step Functions + S3 + IAM). Idempotent — re-running on the same `--stack-name` is a no-op when nothing changed. Writes `<cwd>/.hyperframes/lambda-stack-<name>.json` so later subcommands don't need to call `describe-stacks`.
+
+| Flag            | Default                         | Description                   |
+| --------------- | ------------------------------- | ----------------------------- |
+| `--stack-name`  | `hyperframes-default`           | CloudFormation stack name     |
+| `--region`      | `AWS_REGION` env or `us-east-1` | AWS region                    |
+| `--profile`     | `AWS_PROFILE` env               | Named AWS credentials profile |
+| `--concurrency` | `8`                             | Lambda reserved concurrency   |
+| `--memory`      | `10240`                         | Lambda memory in MB           |
+| `--skip-build`  | off                             | Reuse existing `handler.zip`  |
+
+### sites create
+
+```bash
+npx hyperframes lambda sites create ./my-project
+# → siteId: abc1234deadbeef0  (stable across re-runs of the same tree)
+
+npx hyperframes lambda render ./my-project --site-id=abc1234deadbeef0 ...
+```
+
+Tars + uploads `<projectDir>` to S3 with a content-addressed key. Returns a stable `siteId` you can reuse — re-renders of the same tree skip the upload.
+
+### render
+
+```bash
+npx hyperframes lambda render ./my-project \
+  --width 1920 --height 1080 --fps 30 --format mp4 \
+  --chunk-size 240 --max-parallel-chunks 16 \
+  --wait
+```
+
+Starts a Step Functions execution. Returns immediately with a `renderId` unless `--wait` is set, in which case the CLI blocks until completion and streams per-chunk progress lines. Add `--json` for machine-parseable output.
+
+| Flag                    | Description                                                                                                                                                                                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--width` / `--height`  | Output dimensions in pixels                                                                                                                                                                                                                                                                                                                                   |
+| `--output-resolution`   | Supersampling preset (engages Chrome `deviceScaleFactor`) — `landscape` / `landscape-4k` / `portrait` / `portrait-4k` / `square` / `square-4k`, plus aliases (`1080p`, `4k`, `uhd`, `hd`, `1080p-portrait`, `4k-portrait`, `1080p-square`, `4k-square`). Use this to render an authored-at-1080p composition at 4K without re-laying-out — see footgun below. |
+| `--fps`                 | `24` / `30` / `60`                                                                                                                                                                                                                                                                                                                                            |
+| `--format`              | `mp4` / `mov` / `png-sequence` (default `mp4`)                                                                                                                                                                                                                                                                                                                |
+| `--codec`               | `h264` / `h265` (mp4 only)                                                                                                                                                                                                                                                                                                                                    |
+| `--quality`             | `draft` / `standard` / `high`                                                                                                                                                                                                                                                                                                                                 |
+| `--chunk-size`          | Frames per chunk (default `240`)                                                                                                                                                                                                                                                                                                                              |
+| `--max-parallel-chunks` | Max concurrent chunks (default `16`)                                                                                                                                                                                                                                                                                                                          |
+| `--site-id`             | Reuse an existing site (skip upload)                                                                                                                                                                                                                                                                                                                          |
+| `--wait`                | Block until completion, stream progress                                                                                                                                                                                                                                                                                                                       |
+| `--json`                | Machine-parseable progress snapshot                                                                                                                                                                                                                                                                                                                           |
+
+**`--width` / `--height` footgun.** Setting `--width 3840 --height 2160` against a composition whose `data-width="1920"` silently produces 1080p — the runtime lays out the page at the composition's authored dimensions and the CLI flags are ignored for layout. To actually output at 4K, use `--output-resolution 4k` (supersamples via `deviceScaleFactor`). The CLI now prints a warning when CLI dimensions disagree with the composition's `data-width` / `data-height` and `--output-resolution` is not set; the warning is suppressed when `--json` is on or `index.html` isn't on disk (`--site-id` flows).
+
+### progress
+
+```bash
+npx hyperframes lambda progress hf-render-abcd1234
+npx hyperframes lambda progress arn:aws:states:us-east-1:...:execution:...
+```
+
+Prints one snapshot — overall percent, frames rendered, Lambda invocations, accrued cost, and any errors. Accepts a bare `renderId` (resolved against the stack's state-machine ARN) or a full SFN execution ARN.
+
+### destroy
+
+```bash
+npx hyperframes lambda destroy
+```
+
+Calls `sam delete --no-prompts` and drops the local state file. **The render S3 bucket is configured `Retain`** so it survives stack destruction — empty + delete it via the AWS console / CLI if you want the storage back.
+
+### Non-retryable errors
+
+A subset of failures the Step Functions state machine short-circuits instead of running through its 4× 15-min retry budget. `progress` surfaces these immediately with the error class name; do not re-issue `lambda render` blindly when you see one.
+
+- **`ChromeBinaryUnavailableError`** — `@sparticuz/chromium` returned an empty/missing executable path. A prior chunk hit `Sandbox.Timedout` mid-extraction and the warm instance is wedged until the execution environment recycles. Remedy: bump a Lambda env var (forces a new exec env) or `lambda deploy` again. Not a transient render failure; retries will burn budget on the same wedged instance.
+- **`FFMPEG_VERSION_MISMATCH`** / **`PLAN_HASH_MISMATCH`** — planner / executor version drift. Re-deploy.
+
+### policies
+
+Print or validate the minimum IAM permissions the CLI needs.
+
+```bash
+npx hyperframes lambda policies user                                  # inline policy for an IAM user
+npx hyperframes lambda policies role --principal=cloudformation       # { TrustRelationship, InlinePolicy }
+npx hyperframes lambda policies validate ./infra/iam/hf-deploy.json   # CI gate
+```
+
+`validate` reads a JSON policy doc and checks the union of its `Effect: Allow` actions (expanding `s3:*` / `s3:Get*` / `*` wildcards) against the CLI's required action set. Missing actions print to stderr; the command exits non-zero. Wire it into CI to catch policy drift before the next deploy fails.
+
+The default action set is deliberately broad (`Resource: "*"`) because CloudFormation creates new ARNs on every adopter's first deploy. Tighten `Resource` after that first run if security posture requires it.
+
+## State Files
+
+`hyperframes lambda` stores per-stack metadata under `<cwd>/.hyperframes/lambda-stack-<name>.json` (bucket name, state-machine ARN, region). Not secret, but AWS-account-identifying. Commit it to a repo or `.gitignore` it per your workflow.
+
+## Cost and Cleanup
+
+- `lambda destroy` removes the SAM stack but **leaves the S3 bucket** (`Retain`). Delete it manually if you want the storage back.
+- Lambda billing is per-invocation + duration. `progress` reports the accrued cost.
+- `--concurrency` caps parallel Lambda invocations — keep it aligned with your account quota.
+- `--chunk-size` and `--max-parallel-chunks` trade off per-chunk overhead against parallelism; larger chunks reduce coordinator overhead, smaller chunks parallelize more aggressively.

package/dist/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -0,0 +1,93 @@
+# lint, validate, inspect, snapshot
+
+The correctness pipeline. Run in this order: `lint` (static, fast) → `validate` (runtime, headless Chrome) → `inspect` (layout sweep). `snapshot` is a separate utility for capturing still frames.
+
+## Discipline (motion-heavy work)
+
+When the composition is animation-driven, run the checks before you reach for `preview` or `render`:
+
+- Run `lint` after the first HTML pass — earlier, not later.
+- Capture `snapshot` at meaningful timeline states; look at the PNGs.
+- Inspect snapshots _before_ tuning automated warnings — your eye catches what the auditor misses.
+- Treat layout warnings as defects unless a snapshot proves the overflow is intentional, in which case mark it with `data-layout-allow-overflow`.
+
+## lint
+
+```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
+```
+
+Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). Catches missing `data-composition-id`, overlapping tracks on the same `data-track-index`, and unregistered timelines.
+
+**Blind spot — media inside a sub-composition (not yet a lint rule).** A `<video>`/`<audio>` inside a `compositions/*.html` `<template>` (or nested in a wrapper `<div>` anywhere) is never seeked/decoded and renders blank/black; `lint`/`validate`/`inspect` all pass. Media must be a direct child of the host root (`index.html`) — see `hyperframes-core` → `variables-and-media.md`. Until a rule exists, check manually before render:
+
+```bash
+grep -nE '<(video|audio)\b' compositions/*.html   # expect NO matches; media belongs in index.html
+```
+
+A non-empty result is a defect. Then `snapshot` each scene that has a video and confirm the panel actually shows footage (a blank/black panel where a clip should play is a bug, not a placeholder — treat it as render-blocking).
+
+## validate
+
+```bash
+npx hyperframes validate              # current directory
+npx hyperframes validate ./my-project # specific project
+npx hyperframes validate --json       # agent-readable findings
+npx hyperframes validate --timeout 5000  # ms to wait for scripts (default 3000)
+npx hyperframes validate --no-contrast   # skip WCAG contrast audit while iterating
+```
+
+Static lint is fast but blind to runtime failures. `validate` loads the composition in headless Chrome, plays through it, and reports:
+
+- JavaScript console errors and unhandled exceptions
+- Failed network requests (media-file `ERR_ABORTED` filtered out)
+- WCAG AA contrast violations on visible text — sampled at 5 timestamps across the timeline. Disable with `--no-contrast`.
+
+**Fixing contrast warnings** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold):
+
+- On dark backgrounds, brighten the failing color until it clears the threshold; on light backgrounds, darken it.
+- Stay within the palette family — don't invent a new color, adjust the existing one.
+- Re-run `validate` until clean.
+
+Run `validate` before `inspect` when an animation has scripts, fetched data, or theming. Combine with `render --strict` in CI.
+
+## inspect
+
+```bash
+npx hyperframes inspect                 # inspect rendered layout over the timeline
+npx hyperframes inspect ./my-project    # specific project
+npx hyperframes inspect --json          # agent-readable findings (schemaVersion, samples, issues, bboxes)
+npx hyperframes inspect --samples 15    # denser timeline sweep (default 9)
+npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
+npx hyperframes inspect --tolerance 4   # allowed overflow in px before reporting (default 2)
+npx hyperframes inspect --strict        # exit non-zero on warnings too (default: only errors)
+```
+
+Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
+
+- 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
+
+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.
+
+**Escape hatches:**
+
+- `data-layout-allow-overflow` — mark an element or ancestor when overflow is intentional for an entrance/exit animation.
+- `data-layout-ignore` — mark a decorative element that should never be audited.
+
+`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
+
+## snapshot
+
+```bash
+npx hyperframes snapshot                       # 5 key frames as PNG
+npx hyperframes snapshot ./my-project          # specific project
+npx hyperframes snapshot --frames 10           # evenly-spaced N frames
+```
+
+Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory.