takomi 2.5.1 → 2.5.4

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

@@ -1,45 +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)`.
+# 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/assets/.agent/skills/hyperframes-cli/references/init-and-scaffold.md

@@ -1,51 +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` — **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 `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` orchestrators) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.
+# 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` — **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 `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` orchestrators) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.

package/assets/.agent/skills/hyperframes-cli/references/lambda.md

@@ -1,132 +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.
+# 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.