dsh-hyperframes 0.1.1 → 0.3.0

package/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`.

package/skills/hyperframes-cli/references/cloudrun.md

@@ -0,0 +1,62 @@
+# Cloud Run rendering on Google Cloud
+
+Use `hyperframes cloudrun` only when the user explicitly wants self-managed Google Cloud infrastructure. It deploys Cloud Run, Workflows, and Cloud Storage. For a managed default use `hyperframes cloud`; for AWS use `hyperframes lambda`.
+
+## Prerequisites
+
+- `gcloud` is authenticated and the target project has billing enabled.
+- Terraform 1.5 or newer is on `PATH`.
+- Docker or permission to use Cloud Build is available.
+
+## Lifecycle
+
+```bash
+npx hyperframes cloudrun deploy --project <gcp-project> --region us-central1
+npx hyperframes cloudrun sites create ./project
+npx hyperframes cloudrun render ./project --width 1920 --height 1080 --wait
+npx hyperframes cloudrun progress <execution-name>
+npx hyperframes cloudrun destroy --project <gcp-project>
+```
+
+`deploy` enables the required Google APIs, builds or accepts a container image, applies the bundled Terraform module, and stores the resulting coordinates in `~/.hyperframes/cloudrun-state.json`. Use deploy flags such as `--image`, `--repo`, `--cpu`, `--memory`, `--max-instances`, and `--timeout` only when the infrastructure needs those overrides.
+
+`sites create` uploads a content-addressed project archive for reuse by `render-batch`; pass its `--site-id` to that command to skip the batch upload. Single `cloudrun render` currently resolves the project from its directory and does not consume `--site-id`. Both render commands require `--width` and `--height`; supported output formats are `mp4`, `mov`, `png-sequence`, and `webm`. Use `--output-resolution 4k` to supersample an authored composition without changing its layout dimensions.
+
+Common render flags are `--fps 24|30|60`, `--quality draft|standard|high`, `--codec h264|h265` for MP4, `--chunk-size`, `--max-parallel-chunks`, `--target-chunk-frames`, `--render-id`, `--output-key`, `--wait`, and `--wait-interval-ms`. Use `--json` for machine-readable output.
+
+For a variable-driven single render:
+
+```bash
+npx hyperframes cloudrun render ./template \
+  --width 1920 --height 1080 \
+  --variables-file ./alice.json \
+  --strict-variables \
+  --wait
+```
+
+Use exactly one of `--variables` and `--variables-file`. Read [`variables-and-media.md`](../../hyperframes-core/references/variables-and-media.md#variables) for the composition-side contract.
+
+## JSONL batches
+
+```bash
+npx hyperframes cloudrun render-batch ./template \
+  --batch ./users.jsonl \
+  --width 1920 --height 1080 \
+  --max-concurrent 10 \
+  --site-id <site-id> \
+  --json
+```
+
+Each nonblank line must contain an `outputKey`; `variables` is optional:
+
+```json
+{ "outputKey": "renders/alice.mp4", "variables": { "name": "Alice" } }
+```
+
+- `--max-concurrent` defaults to `50` and limits in-flight executions. `--max-parallel-chunks` separately limits chunks inside one render.
+- `--dry-run` parses the file and prints `would-start` rows without starting executions.
+- The template uploads once unless `--site-id` is supplied.
+- Per-entry start errors remain visible and make the command exit nonzero.
+- Do not rely on `--strict-variables` for `cloudrun render-batch`: the current command accepts the flag but does not validate batch rows. Validate the JSONL variable objects against the composition schema before dispatch. The strict gate does work for single `cloudrun render`.
+
+`render` without `--wait` returns an execution name. Use `cloudrun progress <execution-name>` until it succeeds, then verify the reported GCS output. `destroy` removes the Terraform-managed stack and its scratch bucket; preserve any deliverables that must outlive the stack.

package/skills/hyperframes-cli/references/compare-and-batch.md

@@ -0,0 +1,105 @@
+# Compare and batch rendering
+
+Use these commands for deliberate visual comparison or variable-driven template output. They do not replace `lint`, `check`, final preview approval, or output verification.
+
+## Contents
+
+- [Compare projects or variants](#compare-projects-or-variants)
+- [Compare color grades](#compare-color-grades)
+- [Batch template renders](#batch-template-renders)
+
+## Compare projects or variants
+
+Render the same timestamp from two or more project directories or HTML files into one labeled contact sheet:
+
+```bash
+npx hyperframes compare <path-a> <path-b> [<path-c> ...] \
+  --at <seconds> \
+  --labels baseline,candidate \
+  --out compare.png \
+  --cols 2
+```
+
+Useful options:
+
+- `--at <seconds>` selects the shared comparison time.
+- `--labels <a,b,...>` labels cells in input order.
+- `--out <file>` chooses the sheet path.
+- `--cols <n>` controls its grid.
+- `--json` returns machine-readable results.
+- `--timeout <ms>` changes the per-variant render-ready timeout.
+
+One sheet accepts at most 16 variants. Extra inputs are truncated with a warning; split larger comparisons into several runs.
+
+`compare` is a visual review surface, not a quality gate. Run it when checking a baseline against a candidate, comparing implementation variants, or verifying that a repair preserves the intended look. Inspect the generated image; do not treat command success as visual approval.
+
+## Compare color grades
+
+Create grade candidates from a source frame:
+
+```bash
+npx hyperframes grade-compare \
+  --for frame.png \
+  --grades grades.json \
+  --project . \
+  --out grade-compare.png
+```
+
+`grades.json` is an array of labeled HyperFrames grading blocks:
+
+```json
+[{ "label": "warm", "grading": { "adjust": { "temperature": 0.2, "contrast": 0.1 } } }]
+```
+
+Or compare explicit LUT files:
+
+```bash
+npx hyperframes grade-compare \
+  --for source.mp4 \
+  --luts warm.cube,cool.cube \
+  --out grade-compare.png
+```
+
+- `--for` accepts an image or a video. For video input, the command extracts the first frame.
+- Supply exactly one candidate source: `--grades <json>` or `--luts <a.cube,b.cube>`.
+- A neutral baseline is included by default; pass `--no-baseline` only when the baseline is not a useful reference.
+- The command accepts at most 16 candidate grades. With the default neutral baseline, the sheet may contain 17 cells. Extra candidates are truncated with a warning; split larger sets into several runs.
+- `--timeout <ms>` changes the render-ready timeout for the generated comparison composition.
+- Use `--json` for machine-readable output.
+
+This command helps select a grade. It does not apply the selected grade to the composition or replace `/media-use` provenance and LUT validation.
+
+## Batch template renders
+
+`render --batch` accepts either a JSON array of variable objects or an object with a `rows` array:
+
+```json
+{
+  "rows": [
+    { "name": "alpha", "headline": "Hello" },
+    { "name": "beta", "headline": "Welcome" }
+  ]
+}
+```
+
+Declare the variables in the composition, then run:
+
+```bash
+npx hyperframes render \
+  --batch rows.json \
+  --output "renders/{name}.mp4" \
+  --batch-concurrency 1 \
+  --strict-variables
+```
+
+Batch rules:
+
+- Do not combine `--batch` with `--variables` or `--variables-file`; each row is the variable set for one render.
+- If `--output` is omitted, the generated filename includes `{index}` so rows remain unique.
+- Output templates support `{index}` and row keys containing letters, numbers, `_`, `.`, or `-`. A placeholder value must be a string, number, or boolean; `null`, objects, and arrays are invalid. Missing placeholders and output collisions are errors.
+- `--batch-concurrency` defaults to `1`. Raise it conservatively because each render already uses workers.
+- `--batch-fail-fast` stops scheduling after the first failure. Without it, independent rows keep running and failures remain visible in the manifest.
+- `--strict-variables` validates every row before rendering and aborts before output when the declared variable contract is violated.
+- `--json` emits progress events suitable for agents and CI.
+
+The command writes `manifest.json` in the common output directory and updates it throughout the run. It records each row's variables, status, output, error, and timing. Completion means the manifest has no failed rows and every completed output exists, is non-empty, and has a plausible duration.

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

@@ -0,0 +1,57 @@
+# 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`.
+- **Chrome exits instantly inside an agent sandbox (macOS)** — seatbelt-style sandboxes
+  (e.g. codex `workspace-write`) block Chromium's Mach port bootstrap
+  (`MachPortRendezvous`; openai/codex#21292), so every Chrome — bundled, system, or
+  headless shell — dies at startup. This is a host-level block, not a HyperFrames or
+  Chrome install problem: compile checks and audio still pass, only rendering is
+  unavailable. State the blocker and deliver the checked composition; render outside the
+  sandbox or via `render --docker` / cloud rendering where available. **Do not build a
+  substitute rasterizer** (magick/PIL/SVG frame pipelines) — on a blocked-browser host
+  the deliverable IS the checked composition plus this blocker note, and rendering is
+  handed to `--docker`, cloud, or the user. Write your final summary the moment the
+  blocker is identified, BEFORE any optional fallback work: a later session failure must
+  not erase the report of work already done.
+
+## 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/skills/hyperframes-cli/references/init-and-scaffold.md

@@ -0,0 +1,72 @@
+# 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`.
+- `--skill=<slug>` — record the owning authoring workflow (e.g. `product-launch-video`) 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. Creation workflows set this automatically; 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.
+
+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 `media-use` 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 --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 satisfy the owning
+workflow's gate. 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 that workflow. Run each retry
+into a fresh output directory; never merge or reuse a blocked attempt's partial output.
+
+## 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` orchestrators) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.