From 57b3c7898783d8baec71cc55f39cee553a6f2534 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Wed, 8 Jul 2026 22:20:16 -0400
Subject: [PATCH] =?UTF-8?q?feat(media-use):=20color=20grading=20=E2=80=94?=
 =?UTF-8?q?=20grade/lut=20resolve,=20smart-grade,=20grade-compare=20+=20co?=
 =?UTF-8?q?mpare=20(#2041)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(media-use): color grading — grade/lut resolve, smart-grade, grade-compare CLI

Add color grading to media-use as first-class resolve types plus a faithful
comparison command. All local, offline, deterministic — no model, no GPU.

- resolve -t grade / -t lut: produce a data-color-grading block (or a frozen
  .cube). Look cascade: core preset (no file) -> bundled .cube library ->
  parametric buildCube. Emitted .cube is Rec.709 and validated against core's
  colorLuts constraints (LUT_3D_SIZE <= 64) before it is frozen.
- smart grade (grade --for <media>): ffmpeg signalstats -> adjust suggestion
  (exposure / contrast / white balance), surfaced with the measured evidence on
  stderr as a starting point; never auto-applied.
- hyperframes grade-compare: renders N candidate grades onto a reference frame
  through the real runtime shader into one labeled comparison PNG, so an agent
  picks a look without opening Studio. Prepends an "original" baseline cell by
  default (--no-baseline to omit). Shares the headless-capture pipeline with
  snapshot via capture/captureCompositionFrame.
- media-use SKILL: proactive "media opportunity pass" guidance (grounded
  signal -> offer, ask once, surface don't mutate).

Verified: media-use 116/116, grade-compare 7/7, snapshot 9/9, lint + format
clean, full build green, comparison renders end to end.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* test(cli): narrow grade-compare baseline assertion off unknown-typed grading

Assert the whole cell via toEqual instead of reaching into .grading.preset /
.grading.lut on the unknown-typed field, keeping the test typecheck-clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* feat(media-use): agent-authored LUTs via --params + validate --from cube; never-read-.cube guardrail

- resolve -t lut / -t grade --params '<json>': build a parametric .cube from
  explicit params (bypassing the intent cascade), validate, and freeze in one
  step. --intent becomes the optional description. Lets an agent commit a look
  it computed itself.
- --from <file.cube> now validates the ingested LUT for lut/grade types and
  rejects an invalid/oversized cube (no partial write) — the escape hatch for a
  LUT the agent generated with its own code.
- SKILL.md: hard rule to never read a .cube body into context (~size^3 lines,
  zero legible signal) — inspect via grade-compare (see it) or cube-validate
  (ok/size), read the manifest description for meaning; plus both authoring
  paths and the parametric-vs-film-stock ceiling note.

Verified: media-use 116/116, lint + format clean; smokes — --params builds a
valid frozen cube, grade --params returns a lut block, bad JSON and an oversized
--from cube are both rejected with no stray file.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* fix(cli): grade-compare validates referenced LUTs, warns on no-op cells, caps candidates

Bug-bash follow-ups — grade-compare silently accepted bad input:

- Validate LUT *content*, not just existence: each referenced .cube is parsed
  with core's parseCubeLut (now exported from @hyperframes/core) and rejected
  with a per-cell error ("LUT for \"<label>\" is not a valid .cube: ..."). A
  file that exists but isn't a valid cube no longer renders a silent no-op cell.
- Warn on inactive cells: a grading that normalizes to inactive (e.g. a
  malformed {lut:12345}) emits a stderr warning naming the cell; the
  auto-prepended "original" baseline is intentionally inactive and stays silent.
  stdout remains valid JSON.
- Cap candidates at 16 (excluding baseline): over-cap input renders the first N
  and reports {truncated:true, total:M} on stdout + a stderr note — no silent
  drop, no unbounded giant sheet.

Verified: grade-compare 10/10; non-cube LUT → clear error; {lut:12345} → warning
+ ok; 20 cells → cells=17 truncated total=20; valid runs unchanged. Lint/format
clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* feat(cli): general `hyperframes compare` visual-variant primitive

Generalize grade-compare's "render N variants → one labeled sheet → the agent
looks and picks" loop into a standalone command that works on ANY variation
(font, layout, motion, grade, whole compositions) — the tool never needs to
know what differs.

- `hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out] [--cols]
  [--json]`: renders each agent-authored composition variant through the real
  runtime (captureCompositionFrame) and stitches one labeled comparison sheet +
  JSON ({ok, sheet, rendered, variants, truncated?/total?}). 2+ paths required;
  caps at 16 with loud truncation. It presents, it does not judge — choosing is
  the caller's job.
- Factored the shared "render a labeled set → contact sheet" path so compare,
  grade-compare, and snapshot all sit on it (no duplication). grade-compare is
  now the first color-specific specialization of this primitive.
- New pathArgs util + contactSheet test; hyperframes-cli SKILL documents compare
  as the agent's "see your own renders and choose" primitive.

Verified: 26/26 across compare + grade-compare + snapshot + contactSheet (no
regressions); compare renders 3 variants into one visibly-distinct labeled
sheet; 2+-path error path clean; lint/format clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* fix(ci): green the skills CI — skip ffmpeg tests when absent, oxfmt markdown

The "Test: skills" CI job runs bare `node --test` with no ffmpeg on PATH (by
design — skills tests are meant to be node-builtin-only). The grade-analyzer +
smart-grade tests shell to ffmpeg and were failing there with ENOENT. Guard
them to skip when ffmpeg isn't on PATH; they still run locally / where it is.

Also oxfmt README.md + hyperframes/media-use SKILL.md (the whole-repo
`oxfmt --check .` Format job caught markdown left unformatted by the rebase
conflict resolution).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* fix(ci): skip core-conformance test when tsx is unavailable

The "Test: skills" CI job installs no deps, so the normalizeHfColorGrading
conformance test (which imports core's TS via `node --import tsx`) failed there.
Guard it to skip when tsx can't resolve; runs locally / in the deps-installed
Test job. Completes the skills-CI greening (the ffmpeg guards handled the rest).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* fix(cli): escape grade-compare src double-quotes (CodeQL XSS) + Windows-safe compare test

- grade-compare built `<img src="...">` (double-quoted) with the single-quote
  escaper, leaving `"` unescaped — a `"` in the frame path could break out
  (CodeQL: incomplete HTML attribute sanitization). Use escapeXml for src.
- compare label test hard-coded POSIX paths that can't match on Windows; assert
  the derived labels (the subject); path resolution is covered elsewhere.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* refactor(media-use): generate LUT library from params (drop committed .cube files)

The 3 bundled .cube files were 733 lines each (2,199 total) and were themselves
buildCube output — pure repo bloat. Replace with compact per-look params in
luts/index.json, generated on resolve; add an optional `url` for future scanned
LUTs to be CDN-hosted + downloaded on demand (freezeUrl) instead of committed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* feat(media-use): serve library LUTs from CDN on-demand (static.heygen.ai/luts), params fallback

Looks now carry a CDN `url` (hosted at s3://heygen-public/luts → static.heygen.ai/luts/<id>.cube);
resolve downloads + validates + freezes on demand, like bgm/image. `params` stays
as the deterministic offline fallback (--local-only, or if the download fails), so
resolution is never blocked on the network. Provider prefers url, falls back to params.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* fix(media-use): address #2041 review — atomic LUT writes, compare telemetry, follow-ups

- Atomic .cube writes: library provider (url + params) and the parametric
  generator now write to a .tmp path, validate, then rename, so a crash can
  never orphan an invalid .cube at the final path (was validate-after-write).
- track("media_use_resolve") now emits provenance.via (url/params-fallback/params).
- grade-compare + compare: --timeout flag (was hardcoded 5000) and a
  media_use_compare event (cells, truncated, total, render_ready_timed_out);
  openSettledCompositionPage now surfaces the render-ready timeout.
- compare staging skips node_modules/.git; --for gets an upfront existence check.
- Rec.709 luma comment; HYPERFRAMES_ANALYZE_TIMEOUT_MS override; measured note
  uses basename; LUT s3 hosting moved from index.json into luts/README.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     |   2 +-
 README.md                                     |  20 +-
 docs/guides/skills.mdx                        |   2 +-
 .../capture/captureCompositionFrame.test.ts   |  39 +
 .../src/capture/captureCompositionFrame.ts    | 175 +++++
 packages/cli/src/capture/contactSheet.test.ts |  52 ++
 packages/cli/src/capture/contactSheet.ts      |  14 +-
 packages/cli/src/cli.ts                       |   2 +
 packages/cli/src/commands/compare.test.ts     | 141 ++++
 packages/cli/src/commands/compare.ts          | 413 +++++++++++
 .../cli/src/commands/grade-compare.test.ts    | 253 +++++++
 packages/cli/src/commands/grade-compare.ts    | 698 ++++++++++++++++++
 packages/cli/src/commands/snapshot.ts         | 155 +---
 packages/cli/src/help.ts                      |   5 +
 packages/cli/src/telemetry/events.ts          |  19 +
 packages/cli/src/utils/pathArgs.ts            |  21 +
 packages/core/src/index.ts                    |   1 +
 skills-manifest.json                          |   8 +-
 skills/hyperframes-cli/SKILL.md               |   4 +-
 skills/hyperframes/SKILL.md                   |  20 +-
 skills/media-use/SKILL.md                     | 141 +++-
 skills/media-use/luts/README.md               |  28 +
 skills/media-use/luts/index.json              |  57 ++
 skills/media-use/scripts/lib/candidates.mjs   |   3 +-
 skills/media-use/scripts/lib/cube-build.mjs   | 181 +++++
 .../media-use/scripts/lib/cube-build.test.mjs |  80 ++
 .../media-use/scripts/lib/cube-validate.mjs   | 198 +++++
 .../scripts/lib/cube-validate.test.mjs        | 125 ++++
 .../media-use/scripts/lib/grade-analyzer.mjs  | 165 +++++
 .../scripts/lib/grade-analyzer.test.mjs       | 155 ++++
 .../scripts/lib/lut-preset-provider.mjs       | 232 ++++++
 .../scripts/lib/lut-preset-provider.test.mjs  | 130 ++++
 skills/media-use/scripts/lib/manifest.mjs     |   2 +
 .../media-use/scripts/lib/manifest.test.mjs   |  12 +
 skills/media-use/scripts/lib/registry.mjs     |   9 +
 .../media-use/scripts/lib/registry.test.mjs   |   4 +-
 skills/media-use/scripts/resolve.mjs          | 392 +++++++++-
 skills/media-use/scripts/resolve.test.mjs     | 318 +++++++-
 38 files changed, 4076 insertions(+), 200 deletions(-)
 create mode 100644 packages/cli/src/capture/captureCompositionFrame.test.ts
 create mode 100644 packages/cli/src/capture/captureCompositionFrame.ts
 create mode 100644 packages/cli/src/capture/contactSheet.test.ts
 create mode 100644 packages/cli/src/commands/compare.test.ts
 create mode 100644 packages/cli/src/commands/compare.ts
 create mode 100644 packages/cli/src/commands/grade-compare.test.ts
 create mode 100644 packages/cli/src/commands/grade-compare.ts
 create mode 100644 packages/cli/src/utils/pathArgs.ts
 create mode 100644 skills/media-use/luts/README.md
 create mode 100644 skills/media-use/luts/index.json
 create mode 100644 skills/media-use/scripts/lib/cube-build.mjs
 create mode 100644 skills/media-use/scripts/lib/cube-build.test.mjs
 create mode 100644 skills/media-use/scripts/lib/cube-validate.mjs
 create mode 100644 skills/media-use/scripts/lib/cube-validate.test.mjs
 create mode 100644 skills/media-use/scripts/lib/grade-analyzer.mjs
 create mode 100644 skills/media-use/scripts/lib/grade-analyzer.test.mjs
 create mode 100644 skills/media-use/scripts/lib/lut-preset-provider.mjs
 create mode 100644 skills/media-use/scripts/lib/lut-preset-provider.test.mjs

diff --git a/CLAUDE.md b/CLAUDE.md
index d4778bef5..7c895db16 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,7 +38,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
 - `/hyperframes-animation` — all animation knowledge: atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP default, plus Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).
 - `/hyperframes-keyframes` — seek-safe keyframe authoring across runtimes: GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth; plus `hyperframes keyframes` diagnostics for surfacing and verifying rendered motion.
 - `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.
-- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk.
+- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk.
 - `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering).
 - `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream.
 - `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.
diff --git a/README.md b/README.md
index 4a224041f..e6b2a4a7b 100644
--- a/README.md
+++ b/README.md
@@ -83,16 +83,16 @@ Installs stay lean after that: `npx hyperframes init` keeps the **core set** fre
 
 Atomic capabilities the creation workflows compose against — pull one when you need that specific layer.
 
-| Skill                    | Covers                                                                                                                                                                                                                                                                                                    |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/hyperframes-core`      | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules.                                                                                                                                            |
-| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).                                                                                                                                             |
-| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion.                                                                                               |
-| `/hyperframes-creative`  | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.                                                                                                                                                |
-| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
-| `/hyperframes-cli`       | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`).                                                                                                                                    |
-| `/hyperframes-registry`  | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream.                                                                                                                                                       |
-| `/figma`                 | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.                                                                          |
+| Skill                    | Covers                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/hyperframes-core`      | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules.                                                                                                                                                                                   |
+| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).                                                                                                                                                                                    |
+| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion.                                                                                                                                      |
+| `/hyperframes-creative`  | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.                                                                                                                                                                                       |
+| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
+| `/hyperframes-cli`       | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`).                                                                                                                                                                           |
+| `/hyperframes-registry`  | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream.                                                                                                                                                                                              |
+| `/figma`                 | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.                                                                                                                 |
 
 For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design).
 
diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx
index 394a572f9..9579f7df6 100644
--- a/docs/guides/skills.mdx
+++ b/docs/guides/skills.mdx
@@ -98,7 +98,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
 | `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).         |
 | `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. |
 | `/hyperframes-creative`  | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.            |
-| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking.          |
+| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking.          |
 | `/hyperframes-cli`       | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). |
 | `/hyperframes-registry`  | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream.                   |
 | `/figma`                 | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. |
diff --git a/packages/cli/src/capture/captureCompositionFrame.test.ts b/packages/cli/src/capture/captureCompositionFrame.test.ts
new file mode 100644
index 000000000..cf942565c
--- /dev/null
+++ b/packages/cli/src/capture/captureCompositionFrame.test.ts
@@ -0,0 +1,39 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { runFfmpegOnce } from "./captureCompositionFrame.js";
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), "hf-capture-frame-test-"));
+}
+
+describe("runFfmpegOnce", () => {
+  it("returns the process exit code and collected stderr", async () => {
+    const dir = tempDir();
+    try {
+      const script = join(dir, "fail.cjs");
+      writeFileSync(script, 'process.stderr.write("ffmpeg failed"); process.exit(3);\n');
+
+      const result = await runFfmpegOnce(process.execPath, [script], 1000);
+
+      expect(result).toEqual({ code: 3, stderr: "ffmpeg failed", timedOut: false });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("terminates the process when the timeout elapses", async () => {
+    const dir = tempDir();
+    try {
+      const script = join(dir, "hang.cjs");
+      writeFileSync(script, "setTimeout(() => {}, 10000);\n");
+
+      const result = await runFfmpegOnce(process.execPath, [script], 50);
+
+      expect(result.timedOut).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
new file mode 100644
index 000000000..fbc15331a
--- /dev/null
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -0,0 +1,175 @@
+import { spawn } from "node:child_process";
+import type { Browser, Page } from "puppeteer-core";
+import { c } from "../ui/colors.js";
+import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
+
+const CHROME_LAUNCH_ARGS = [
+  "--no-sandbox",
+  "--disable-gpu",
+  "--disable-dev-shm-usage",
+  "--enable-webgl",
+  "--use-gl=angle",
+  "--use-angle=swiftshader",
+];
+
+const SHADER_TRANSITIONS_TIMEOUT_MS = 90_000;
+const CAPTURE_SETTLE_MS = 1500;
+
+export interface SettledCompositionPage {
+  browser: Browser;
+  page: Page;
+  // True when the runtime never signaled __renderReady within the timeout — the
+  // capture proceeds anyway (possibly mid-animation), so callers can surface it.
+  renderReadyTimedOut: boolean;
+}
+
+export interface OpenSettledCompositionPageOptions {
+  renderReadyTimeoutMs: number;
+  renderReadyWarningSuffix: string;
+}
+
+export interface FfmpegRunResult {
+  code: number | null;
+  stderr: string;
+  timedOut: boolean;
+}
+
+function compositionRuntimeReadyInBrowser(): boolean {
+  return Boolean(Reflect.get(window, "__renderReady"));
+}
+
+function shaderTransitionsReadyInBrowser(): boolean {
+  function shaderTransitionRegistryReady(): boolean | undefined {
+    const hf = Reflect.get(window, "__hf");
+    if (typeof hf !== "object" || hf === null) return undefined;
+
+    const shaderTransitions = Reflect.get(hf, "shaderTransitions");
+    if (typeof shaderTransitions !== "object" || shaderTransitions === null) return undefined;
+
+    for (const key of Object.keys(shaderTransitions)) {
+      const entry = Reflect.get(shaderTransitions, key);
+      if (typeof entry !== "object" || entry === null) return false;
+      if (Reflect.get(entry, "ready") !== true) return false;
+    }
+    return true;
+  }
+
+  function shaderLoadingOverlayReady(): boolean {
+    const overlay = document.querySelector("[data-hyper-shader-loading]");
+    if (!overlay) return true;
+    if (!(overlay instanceof HTMLElement)) return true;
+    return window.getComputedStyle(overlay).display === "none";
+  }
+
+  return shaderTransitionRegistryReady() ?? shaderLoadingOverlayReady();
+}
+
+async function waitForCompositionSettle(
+  page: Page,
+  options: OpenSettledCompositionPageOptions,
+): Promise<boolean> {
+  const runtimeReady = await page
+    .waitForFunction(compositionRuntimeReadyInBrowser, { timeout: options.renderReadyTimeoutMs })
+    .then(() => true)
+    .catch(() => false);
+
+  if (!runtimeReady) {
+    console.warn(
+      `\n   ${c.warn("⚠")} Runtime did not become render-ready within ${options.renderReadyTimeoutMs}ms — ${options.renderReadyWarningSuffix}`,
+    );
+  }
+
+  await page
+    .waitForFunction(shaderTransitionsReadyInBrowser, {
+      timeout: SHADER_TRANSITIONS_TIMEOUT_MS,
+    })
+    .catch(() => {
+      console.warn(`   ${c.warn("⚠")} Shader transitions did not finish pre-rendering`);
+    });
+
+  await page.evaluate(() => document.fonts.ready).catch(() => {});
+  await new Promise((resolveSettle) => setTimeout(resolveSettle, CAPTURE_SETTLE_MS));
+  return runtimeReady;
+}
+
+export async function openSettledCompositionPage(
+  html: string,
+  url: string,
+  options: OpenSettledCompositionPageOptions,
+): Promise<SettledCompositionPage> {
+  const { ensureBrowser } = await import("../browser/manager.js");
+  const browser = await ensureBrowser();
+  const puppeteer = await import("puppeteer-core");
+
+  let chromeBrowser: Browser | undefined;
+  try {
+    chromeBrowser = await puppeteer.default.launch({
+      headless: true,
+      executablePath: browser.executablePath,
+      args: CHROME_LAUNCH_ARGS,
+    });
+
+    const page = await chromeBrowser.newPage();
+    await page.setViewport(resolveCompositionViewportFromHtml(html));
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 10000 });
+    const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
+    return { browser: chromeBrowser, page, renderReadyTimedOut };
+  } catch (err) {
+    await chromeBrowser?.close().catch(() => {});
+    throw err;
+  }
+}
+
+export async function seekCompositionTimeline(
+  page: Pick<Page, "evaluate">,
+  timeSeconds: number,
+): Promise<void> {
+  await page.evaluate((t: number) => {
+    const player = (window as any).__player;
+    if (!player) return;
+    const safe = Math.max(0, Number(t) || 0);
+    if (typeof player.renderSeek === "function") {
+      player.renderSeek(safe);
+    } else if (typeof player.seek === "function") {
+      player.seek(safe);
+    }
+    if ((window as any).gsap?.ticker?.tick) {
+      (window as any).gsap.ticker.tick();
+    }
+  }, timeSeconds);
+
+  await page.evaluate(`new Promise(function(r) {
+    var settled = false;
+    function finish() { if (settled) return; settled = true; r(); }
+    window.setTimeout(finish, 100);
+    requestAnimationFrame(function() { requestAnimationFrame(finish); });
+  })`);
+}
+
+export async function runFfmpegOnce(
+  ffmpegPath: string,
+  args: readonly string[],
+  timeoutMs: number,
+): Promise<FfmpegRunResult> {
+  return await new Promise((resolvePromise) => {
+    const ff = spawn(ffmpegPath, args);
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      ff.kill("SIGTERM");
+    }, timeoutMs);
+
+    ff.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+    ff.on("close", (code) => {
+      clearTimeout(timer);
+      resolvePromise({ code, stderr, timedOut });
+    });
+    ff.on("error", () => {
+      clearTimeout(timer);
+      resolvePromise({ code: null, stderr: "ffmpeg spawn failed", timedOut });
+    });
+  });
+}
diff --git a/packages/cli/src/capture/contactSheet.test.ts b/packages/cli/src/capture/contactSheet.test.ts
new file mode 100644
index 000000000..2c1b5808d
--- /dev/null
+++ b/packages/cli/src/capture/contactSheet.test.ts
@@ -0,0 +1,52 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import sharp from "sharp";
+import { describe, expect, it } from "vitest";
+import { createContactSheet } from "./contactSheet.js";
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), "hf-contact-sheet-test-"));
+}
+
+describe("createContactSheet", () => {
+  it("writes PNG output when the output path uses a .png extension", async () => {
+    const dir = tempDir();
+    try {
+      const a = join(dir, "a.png");
+      const b = join(dir, "b.png");
+      const out = join(dir, "sheet.png");
+      await sharp({
+        create: {
+          width: 16,
+          height: 9,
+          channels: 3,
+          background: { r: 255, g: 0, b: 0 },
+        },
+      })
+        .png()
+        .toFile(a);
+      await sharp({
+        create: {
+          width: 16,
+          height: 9,
+          channels: 3,
+          background: { r: 0, g: 255, b: 0 },
+        },
+      })
+        .png()
+        .toFile(b);
+
+      await createContactSheet([a, b], out, {
+        cols: 2,
+        labelMode: "custom",
+        labels: ["A", "B"],
+        maxImages: 2,
+      });
+
+      await expect(sharp(out).metadata()).resolves.toMatchObject({ format: "png" });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/cli/src/capture/contactSheet.ts b/packages/cli/src/capture/contactSheet.ts
index 0f9d00207..8468c107b 100644
--- a/packages/cli/src/capture/contactSheet.ts
+++ b/packages/cli/src/capture/contactSheet.ts
@@ -93,17 +93,20 @@ export async function createContactSheet(
     overlays.push({ input: labelSvg, left: x, top: y });
   }
 
-  await sharp({
+  const sheet = sharp({
     create: {
       width: totalW,
       height: totalH,
       channels: 3,
       background: { r: 26, g: 26, b: 26 },
     },
-  })
-    .composite(overlays)
-    .jpeg({ quality })
-    .toFile(outputPath);
+  }).composite(overlays);
+
+  if (extname(outputPath).toLowerCase() === ".png") {
+    await sheet.png().toFile(outputPath);
+  } else {
+    await sheet.jpeg({ quality }).toFile(outputPath);
+  }
 
   return outputPath;
 }
@@ -263,6 +266,7 @@ export async function createAssetContactSheet(
  * parent assets/ root (for external SVGs downloaded as <img src="*.svg">).
  * Files are deduplicated by basename so duplicates across dirs are collapsed.
  */
+// fallow-ignore-next-line complexity
 export async function createSvgContactSheet(
   svgsDir: string,
   outputPath: string,
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 2c2726e79..b98ad6d44 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -139,6 +139,8 @@ const commandLoaders = {
   events: () => import("./commands/events.js").then((m) => m.default),
   validate: () => import("./commands/validate.js").then((m) => m.default),
   snapshot: () => import("./commands/snapshot.js").then((m) => m.default),
+  "grade-compare": () => import("./commands/grade-compare.js").then((m) => m.default),
+  compare: () => import("./commands/compare.js").then((m) => m.default),
   capture: () => import("./commands/capture.js").then((m) => m.default),
   lambda: () => import("./commands/lambda.js").then((m) => m.default),
   cloudrun: () => import("./commands/cloudrun.js").then((m) => m.default),
diff --git a/packages/cli/src/commands/compare.test.ts b/packages/cli/src/commands/compare.test.ts
new file mode 100644
index 000000000..f5381449e
--- /dev/null
+++ b/packages/cli/src/commands/compare.test.ts
@@ -0,0 +1,141 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import {
+  buildCompareSuccessPayload,
+  capCompareVariants,
+  parseCompareArgs,
+  prepareCompareVariantProjects,
+} from "./compare.js";
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), "hf-compare-test-"));
+}
+
+describe("parseCompareArgs", () => {
+  it("requires at least two composition paths", () => {
+    expect(() => parseCompareArgs({ _: ["variant-a"] }, "/tmp")).toThrow(
+      "need 2+ paths to compare",
+    );
+  });
+
+  it("rejects --labels when the count does not match the path count", () => {
+    expect(() =>
+      parseCompareArgs({ _: ["variant-a", "variant-b"], labels: "one,two,three" }, "/tmp"),
+    ).toThrow("--labels count (3) must match path count (2)");
+  });
+
+  it("derives default labels from directory basenames and html filenames", () => {
+    const parsed = parseCompareArgs(
+      { _: ["./looks/warm", "./looks/cool.html", "/tmp/hero.alt.html"] },
+      "/work/project",
+    );
+
+    // Labels are the subject here — derived cross-platform via path.basename.
+    // (inputPath/displayPath are absolute/relative resolutions that differ by OS
+    // — separators + drive letter on Windows — and are covered by the resolution
+    // tests; asserting them literally here made this a POSIX-only test.)
+    expect(parsed.variants.map((v) => v.label)).toEqual(["warm", "cool", "hero.alt"]);
+  });
+});
+
+describe("capCompareVariants", () => {
+  it("truncates over-cap variants and exposes truncation metadata for JSON output", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const variants = Array.from({ length: 20 }, (_, index) => ({
+        label: `variant ${index + 1}`,
+        inputPath: `/tmp/variant-${index + 1}`,
+        displayPath: `variant-${index + 1}`,
+      }));
+
+      const capped = capCompareVariants(variants);
+
+      expect(capped.variants).toHaveLength(16);
+      expect(capped.variants.at(0)?.label).toBe("variant 1");
+      expect(capped.variants.at(15)?.label).toBe("variant 16");
+      expect(capped.truncated).toBe(true);
+      expect(capped.total).toBe(20);
+      expect(buildCompareSuccessPayload("/tmp/compare.png", capped.variants, capped)).toMatchObject(
+        {
+          ok: true,
+          sheet: "/tmp/compare.png",
+          rendered: 16,
+          truncated: true,
+          total: 20,
+        },
+      );
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Warning: 20 compare variants exceed the 16-variant cap"),
+      );
+      expect(logSpy).not.toHaveBeenCalled();
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+});
+
+describe("prepareCompareVariantProjects", () => {
+  it("uses project directories directly and stages standalone html files as index.html", () => {
+    const dir = tempDir();
+    try {
+      const projectDir = join(dir, "variant-a");
+      const htmlDir = join(dir, "variant-b");
+      const projectIndex = join(projectDir, "index.html");
+      const htmlFile = join(htmlDir, "candidate.html");
+      mkdirSync(projectDir, { recursive: true });
+      mkdirSync(htmlDir, { recursive: true });
+      writeFileSync(projectIndex, "<!doctype html><title>A</title>", { flag: "wx" });
+      writeFileSync(htmlFile, "<!doctype html><title>B</title>", { flag: "wx" });
+      writeFileSync(join(htmlDir, "asset.txt"), "asset");
+
+      const prepared = prepareCompareVariantProjects([
+        { label: "A", inputPath: projectDir, displayPath: "variant-a" },
+        { label: "B", inputPath: htmlFile, displayPath: "variant-b/candidate.html" },
+      ]);
+
+      try {
+        expect(prepared).toHaveLength(2);
+        expect(prepared[0]).toMatchObject({
+          label: "A",
+          inputPath: projectDir,
+          displayPath: "variant-a",
+          projectDir,
+        });
+        expect(prepared[0]?.stagedDir).toBeUndefined();
+        expect(prepared[1]?.projectDir).not.toBe(htmlDir);
+        expect(prepared[1]?.stagedDir).toBe(prepared[1]?.projectDir);
+        expect(readFileSync(join(prepared[1]!.projectDir, "index.html"), "utf-8")).toContain(
+          "<title>B</title>",
+        );
+        expect(readFileSync(join(prepared[1]!.projectDir, "asset.txt"), "utf-8")).toBe("asset");
+        expect(existsSync(join(prepared[1]!.projectDir, "candidate.html"))).toBe(false);
+      } finally {
+        for (const variant of prepared) {
+          if (variant.stagedDir) rmSync(variant.stagedDir, { recursive: true, force: true });
+        }
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("errors clearly for inputs that are not composition projects or html files", () => {
+    const dir = tempDir();
+    try {
+      const badFile = join(dir, "notes.txt");
+      writeFileSync(badFile, "not a composition");
+
+      expect(() =>
+        prepareCompareVariantProjects([
+          { label: "notes", inputPath: badFile, displayPath: "notes.txt" },
+          { label: "other", inputPath: join(dir, "missing"), displayPath: "missing" },
+        ]),
+      ).toThrow(/not a composition input.*notes\.txt/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/cli/src/commands/compare.ts b/packages/cli/src/commands/compare.ts
new file mode 100644
index 000000000..a55fd168e
--- /dev/null
+++ b/packages/cli/src/commands/compare.ts
@@ -0,0 +1,413 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, join } from "node:path";
+import { defineCommand } from "citty";
+import { createContactSheet } from "../capture/contactSheet.js";
+import {
+  openSettledCompositionPage,
+  seekCompositionTimeline,
+} from "../capture/captureCompositionFrame.js";
+import { c } from "../ui/colors.js";
+import { normalizeErrorMessage } from "../utils/errorMessage.js";
+import { displayPathFromInput, readOptionalString, resolveFromBase } from "../utils/pathArgs.js";
+import { trackCompareSheet } from "../telemetry/events.js";
+import { serveStaticProjectHtml } from "../utils/staticProjectServer.js";
+import { withMeta } from "../utils/updateCheck.js";
+import type { Example } from "./_examples.js";
+
+const MAX_COMPARE_VARIANTS = 16;
+const MAX_COLUMNS = 4;
+const DEFAULT_RENDER_READY_TIMEOUT_MS = 5000;
+
+export interface CompareVariantSpec {
+  label: string;
+  inputPath: string;
+  displayPath: string;
+}
+
+export interface PreparedCompareVariant extends CompareVariantSpec {
+  projectDir: string;
+  stagedDir?: string;
+}
+
+export interface ParsedCompareArgs {
+  variants: CompareVariantSpec[];
+  outPath: string;
+  atSeconds: number;
+  cols?: number;
+  json: boolean;
+  timeoutMs: number;
+}
+
+export interface CompareVariantCapResult {
+  variants: CompareVariantSpec[];
+  truncated: boolean;
+  total: number;
+}
+
+export interface CompareSuccessPayload {
+  ok: true;
+  sheet: string;
+  variants: { label: string; path: string }[];
+  rendered: number;
+  truncated?: true;
+  total?: number;
+}
+
+export const examples: Example[] = [
+  [
+    "Compare two agent-authored composition variants",
+    "hyperframes compare ./variants/a ./variants/b --out compare.png",
+  ],
+  [
+    "Compare three variants at a specific timeline time",
+    "hyperframes compare ./a ./b ./c --at 2.5 --labels classic,bold,quiet --json",
+  ],
+];
+
+function defaultLabelForPath(input: string): string {
+  const name = basename(input);
+  return extname(name).toLowerCase() === ".html" ? basename(name, extname(name)) : name;
+}
+
+function parsePathArgs(args: { _?: readonly unknown[] }): string[] {
+  return (args._ ?? [])
+    .filter((value): value is string => typeof value === "string")
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function parseLabels(value: unknown, pathCount: number): string[] | undefined {
+  const raw = readOptionalString(value);
+  if (!raw) return undefined;
+  const labels = raw.split(",").map((part) => part.trim());
+  if (labels.some((label) => label.length === 0)) {
+    throw new Error("--labels entries must be non-empty");
+  }
+  if (labels.length !== pathCount) {
+    throw new Error(`--labels count (${labels.length}) must match path count (${pathCount})`);
+  }
+  return labels;
+}
+
+function parseAtSeconds(value: unknown): number {
+  const raw = readOptionalString(value);
+  if (!raw) return 0;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error("--at must be a non-negative number of seconds");
+  }
+  return parsed;
+}
+
+function parseColumns(value: unknown): number | undefined {
+  const raw = readOptionalString(value);
+  if (!raw) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error("--cols must be a positive integer");
+  }
+  return parsed;
+}
+
+function defaultCompareCols(cellCount: number): number {
+  return Math.max(1, Math.min(MAX_COLUMNS, Math.ceil(Math.sqrt(cellCount))));
+}
+
+export function parseCompareArgs(
+  args: {
+    _?: readonly unknown[];
+    labels?: unknown;
+    out?: unknown;
+    at?: unknown;
+    cols?: unknown;
+    json?: unknown;
+    timeout?: unknown;
+  },
+  cwd = process.cwd(),
+): ParsedCompareArgs {
+  const paths = parsePathArgs(args);
+  if (paths.length < 2) {
+    throw new Error("need 2+ paths to compare");
+  }
+
+  const labels = parseLabels(args.labels, paths.length);
+  const variants = paths.map((input, index) => ({
+    label: labels?.[index] ?? defaultLabelForPath(input),
+    inputPath: resolveFromBase(cwd, input),
+    displayPath: displayPathFromInput(cwd, input),
+  }));
+
+  return {
+    variants,
+    outPath: resolveFromBase(cwd, readOptionalString(args.out) ?? "compare.png"),
+    atSeconds: parseAtSeconds(args.at),
+    cols: parseColumns(args.cols),
+    json: args.json === true,
+    timeoutMs:
+      Number.parseInt(readOptionalString(args.timeout) ?? "", 10) ||
+      DEFAULT_RENDER_READY_TIMEOUT_MS,
+  };
+}
+
+export function capCompareVariants(
+  variants: readonly CompareVariantSpec[],
+): CompareVariantCapResult {
+  const total = variants.length;
+  if (total <= MAX_COMPARE_VARIANTS) {
+    return { variants: [...variants], truncated: false, total };
+  }
+  console.error(
+    c.warn(
+      `Warning: ${total} compare variants exceed the ${MAX_COMPARE_VARIANTS}-variant cap — rendering the first ${MAX_COMPARE_VARIANTS} of ${total}; re-run with fewer variants or split into multiple runs.`,
+    ),
+  );
+  return {
+    variants: variants.slice(0, MAX_COMPARE_VARIANTS),
+    truncated: true,
+    total,
+  };
+}
+
+export function buildCompareSuccessPayload(
+  sheet: string,
+  variants: readonly CompareVariantSpec[],
+  capResult: CompareVariantCapResult,
+): CompareSuccessPayload {
+  const payload: CompareSuccessPayload = {
+    ok: true,
+    sheet,
+    variants: variants.map((variant) => ({
+      label: variant.label,
+      path: variant.displayPath,
+    })),
+    rendered: variants.length,
+  };
+  if (capResult.truncated) {
+    payload.truncated = true;
+    payload.total = capResult.total;
+  }
+  return payload;
+}
+
+function inputError(variant: CompareVariantSpec): Error {
+  return new Error(
+    `Variant "${variant.label}" is not a composition input (${variant.displayPath}): expected a directory containing index.html or a .html file`,
+  );
+}
+
+function stageHtmlVariant(variant: CompareVariantSpec): PreparedCompareVariant {
+  const stagedDir = mkdtempSync(join(tmpdir(), "hf-compare-variant-"));
+  try {
+    // Copy the composition's sibling files but skip heavy/irrelevant trees — a
+    // variant sitting next to node_modules or .git shouldn't drag them into tmp.
+    cpSync(dirname(variant.inputPath), stagedDir, {
+      recursive: true,
+      filter: (src) => {
+        const base = basename(src);
+        return base !== "node_modules" && base !== ".git";
+      },
+    });
+    const sourceName = basename(variant.inputPath);
+    if (sourceName !== "index.html") {
+      renameSync(join(stagedDir, sourceName), join(stagedDir, "index.html"));
+    }
+    return {
+      ...variant,
+      projectDir: stagedDir,
+      stagedDir,
+    };
+  } catch (err) {
+    rmSync(stagedDir, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+export function prepareCompareVariantProjects(
+  variants: readonly CompareVariantSpec[],
+): PreparedCompareVariant[] {
+  const prepared: PreparedCompareVariant[] = [];
+  try {
+    for (const variant of variants) {
+      if (!existsSync(variant.inputPath)) {
+        throw inputError(variant);
+      }
+      const stat = statSync(variant.inputPath);
+      if (stat.isDirectory() && existsSync(join(variant.inputPath, "index.html"))) {
+        prepared.push({
+          ...variant,
+          projectDir: variant.inputPath,
+        });
+        continue;
+      }
+      if (stat.isFile() && extname(variant.inputPath).toLowerCase() === ".html") {
+        prepared.push(stageHtmlVariant(variant));
+        continue;
+      }
+      throw inputError(variant);
+    }
+    return prepared;
+  } catch (err) {
+    for (const variant of prepared) {
+      if (variant.stagedDir) {
+        rmSync(variant.stagedDir, { recursive: true, force: true });
+      }
+    }
+    throw err;
+  }
+}
+
+function cleanupPreparedCompareVariants(variants: readonly PreparedCompareVariant[]): void {
+  for (const variant of variants) {
+    if (variant.stagedDir) {
+      rmSync(variant.stagedDir, { recursive: true, force: true });
+    }
+  }
+}
+
+async function renderCompareVariant(
+  variant: PreparedCompareVariant,
+  opts: { atSeconds: number; framePath: string; timeoutMs: number },
+): Promise<{ framePath: string; renderReadyTimedOut: boolean }> {
+  try {
+    const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
+    const html = await bundleToSingleHtml(variant.projectDir);
+    const server = await serveStaticProjectHtml(variant.projectDir, html);
+    try {
+      const {
+        browser: chromeBrowser,
+        page,
+        renderReadyTimedOut,
+      } = await openSettledCompositionPage(html, server.url, {
+        renderReadyTimeoutMs: opts.timeoutMs,
+        renderReadyWarningSuffix: `comparison variant "${variant.label}" may be inaccurate`,
+      });
+      try {
+        if (opts.atSeconds > 0) {
+          await seekCompositionTimeline(page, opts.atSeconds);
+        }
+        await page.screenshot({ path: opts.framePath, type: "png" });
+        return { framePath: opts.framePath, renderReadyTimedOut };
+      } finally {
+        await chromeBrowser.close();
+      }
+    } finally {
+      await server.close();
+    }
+  } catch (err) {
+    throw new Error(
+      `Render failed for variant "${variant.label}" (${variant.displayPath}): ${normalizeErrorMessage(err)}`,
+    );
+  }
+}
+
+async function renderCompareSheet(parsed: ParsedCompareArgs): Promise<CompareSuccessPayload> {
+  const capResult = capCompareVariants(parsed.variants);
+  const variants = capResult.variants;
+  const prepared = prepareCompareVariantProjects(variants);
+  const frameDir = mkdtempSync(join(tmpdir(), "hf-compare-frames-"));
+  const framePaths: string[] = [];
+
+  try {
+    let renderReadyTimedOut = false;
+    for (let i = 0; i < prepared.length; i++) {
+      const variant = prepared[i]!;
+      const framePath = join(frameDir, `variant-${String(i + 1).padStart(2, "0")}.png`);
+      const rendered = await renderCompareVariant(variant, {
+        atSeconds: parsed.atSeconds,
+        framePath,
+        timeoutMs: parsed.timeoutMs,
+      });
+      framePaths.push(rendered.framePath);
+      renderReadyTimedOut = renderReadyTimedOut || rendered.renderReadyTimedOut;
+    }
+
+    mkdirSync(dirname(parsed.outPath), { recursive: true });
+    await createContactSheet(framePaths, parsed.outPath, {
+      cols: parsed.cols ?? defaultCompareCols(framePaths.length),
+      maxImages: framePaths.length,
+      labelMode: "custom",
+      labels: variants.map((variant) => variant.label),
+    });
+
+    trackCompareSheet({
+      command: "compare",
+      cells: variants.length,
+      truncated: capResult.truncated,
+      total: capResult.total,
+      renderReadyTimedOut,
+    });
+    return buildCompareSuccessPayload(parsed.outPath, variants, capResult);
+  } finally {
+    cleanupPreparedCompareVariants(prepared);
+    rmSync(frameDir, { recursive: true, force: true });
+  }
+}
+
+function printJson(payload: object): void {
+  console.log(JSON.stringify(withMeta(payload), null, 2));
+}
+
+export default defineCommand({
+  meta: {
+    name: "compare",
+    description: "Render independent composition variants into one labeled comparison sheet",
+  },
+  args: {
+    path: {
+      type: "positional",
+      description: "Composition project directory or .html file (pass 2+ paths)",
+      required: false,
+    },
+    at: {
+      type: "string",
+      description: "Timeline time in seconds to seek before screenshotting each variant",
+    },
+    labels: {
+      type: "string",
+      description: "Comma-separated labels matching the variant path count",
+    },
+    out: {
+      type: "string",
+      description: "Output comparison sheet path (default: ./compare.png)",
+    },
+    cols: {
+      type: "string",
+      description: "Grid columns (default: sqrt heuristic, capped at 4)",
+    },
+    timeout: {
+      type: "string",
+      description: "Render-ready timeout in ms per variant (default: 5000)",
+    },
+    json: {
+      type: "boolean",
+      description: "Output result as JSON",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const jsonRequested = args.json === true;
+    try {
+      const parsed = parseCompareArgs(args);
+      if (!parsed.json) {
+        console.log(
+          `${c.accent("◆")}  Rendering ${Math.min(parsed.variants.length, MAX_COMPARE_VARIANTS)} of ${parsed.variants.length} composition variants`,
+        );
+      }
+      const payload = await renderCompareSheet(parsed);
+      if (parsed.json) {
+        printJson(payload);
+      } else {
+        console.log(`\n${c.success("◇")}  Comparison sheet saved to ${payload.sheet}`);
+      }
+    } catch (err) {
+      const message = normalizeErrorMessage(err);
+      if (jsonRequested) {
+        printJson({ ok: false, error: message });
+      } else {
+        console.error(`\n${c.error("✗")} Compare failed: ${message}`);
+      }
+      process.exit(1);
+    }
+  },
+});
diff --git a/packages/cli/src/commands/grade-compare.test.ts b/packages/cli/src/commands/grade-compare.test.ts
new file mode 100644
index 000000000..a321a859a
--- /dev/null
+++ b/packages/cli/src/commands/grade-compare.test.ts
@@ -0,0 +1,253 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { HF_COLOR_GRADING_ATTR, serializeHfColorGrading } from "@hyperframes/core";
+import { describe, expect, it, vi } from "vitest";
+import {
+  buildGradeCompareHtml,
+  buildGradeCompareSuccessPayload,
+  capCandidateCells,
+  parseGradeCompareArgs,
+  parseGradesFile,
+  prepareGradeCompareTempProject,
+  prependBaselineCell,
+  resolveLutCells,
+  warnInactiveGradingCells,
+} from "./grade-compare.js";
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), "hf-grade-compare-test-"));
+}
+
+function validCubeLut(): string {
+  return `LUT_3D_SIZE 2
+0 0 0
+1 0 0
+0 1 0
+1 1 0
+0 0 1
+1 0 1
+0 1 1
+1 1 1
+`;
+}
+
+describe("parseGradesFile", () => {
+  it("parses a valid grades array into labeled cells", () => {
+    const dir = tempDir();
+    try {
+      const file = join(dir, "grades.json");
+      writeFileSync(
+        file,
+        JSON.stringify([
+          { label: "warm", grading: { preset: "warm-daylight" } },
+          { label: "punch", grading: { adjust: { exposure: 0.5, contrast: 0.4 } } },
+        ]),
+      );
+
+      expect(parseGradesFile(file)).toEqual([
+        { label: "warm", grading: { preset: "warm-daylight" } },
+        { label: "punch", grading: { adjust: { exposure: 0.5, contrast: 0.4 } } },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("errors clearly for missing or invalid grades files", () => {
+    const dir = tempDir();
+    try {
+      expect(() => parseGradesFile(join(dir, "missing.json"))).toThrow(
+        /Grades file not found: .*missing\.json/,
+      );
+
+      const invalid = join(dir, "invalid.json");
+      writeFileSync(invalid, JSON.stringify({ label: "not an array" }));
+      expect(() => parseGradesFile(invalid)).toThrow(
+        "Grades file must be a JSON array of { label, grading } objects",
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("prependBaselineCell", () => {
+  it("prepends an ungraded 'original' reference cell", () => {
+    const candidates = resolveLutCells("/tmp/luts/film.cube");
+    const withBaseline = prependBaselineCell(candidates);
+    expect(withBaseline).toHaveLength(candidates.length + 1);
+    // empty grading (no preset / no lut) → normalizes to inactive → renders the
+    // source frame untouched, giving a reference to judge candidates against
+    expect(withBaseline.at(0)).toEqual({ label: "original", grading: {} });
+    expect(withBaseline.slice(1)).toEqual(candidates);
+  });
+});
+
+describe("resolveLutCells", () => {
+  it("expands comma-separated LUT paths into labeled grading cells", () => {
+    expect(resolveLutCells("/tmp/luts/film.cube,./cool.look.cube")).toEqual([
+      { label: "film", grading: { lut: { src: "/tmp/luts/film.cube" } } },
+      { label: "cool.look", grading: { lut: { src: "./cool.look.cube" } } },
+    ]);
+  });
+});
+
+describe("parseGradeCompareArgs", () => {
+  it("requires exactly one grade source", () => {
+    expect(() => parseGradeCompareArgs({ for: "frame.png" })).toThrow(
+      "Exactly one of --grades or --luts is required",
+    );
+    expect(() =>
+      parseGradeCompareArgs({ for: "frame.png", grades: "grades.json", luts: "a.cube" }),
+    ).toThrow("Exactly one of --grades or --luts is required");
+  });
+});
+
+describe("buildGradeCompareHtml", () => {
+  it("renders one labeled color-graded image per cell with composition metadata", () => {
+    const cells = [
+      { label: "warm <daylight>", grading: { preset: "warm-daylight" } },
+      { label: "cool", grading: { adjust: { temperature: -0.8 } } },
+      { label: "punchy", grading: { adjust: { exposure: 0.5, contrast: 0.4 } } },
+    ];
+
+    const html = buildGradeCompareHtml({
+      cells,
+      frameSrc: "frame.png",
+      frameWidth: 640,
+      frameHeight: 360,
+    });
+
+    const escapedAttr = HF_COLOR_GRADING_ATTR.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const attrPattern = new RegExp(`<img[^>]+${escapedAttr}=`, "g");
+    expect(html.match(attrPattern)).toHaveLength(cells.length);
+    expect(html).toContain('data-composition-id="grade-compare"');
+    expect(html).toContain('data-width="1168"');
+    expect(html).toContain('data-height="742"');
+    expect(html).toContain('data-duration="1"');
+    expect(html).toContain("warm &lt;daylight&gt;");
+    for (const cell of cells) {
+      expect(html).toContain(`${HF_COLOR_GRADING_ATTR}='${serializeHfColorGrading(cell.grading)}'`);
+    }
+  });
+});
+
+describe("prepareGradeCompareTempProject", () => {
+  it("copies the frame and LUTs into a temp project and rewrites LUT src values", async () => {
+    const dir = tempDir();
+    try {
+      const framePath = join(dir, "frame.png");
+      const lutPath = join(dir, "look.cube");
+      writeFileSync(framePath, "fake-png");
+      writeFileSync(lutPath, validCubeLut());
+
+      const prepared = await prepareGradeCompareTempProject({
+        projectDir: dir,
+        framePath,
+        frameBuffer: Buffer.from("fake-png"),
+        cells: [
+          { label: "film", grading: { lut: { src: basename(lutPath), intensity: 0.7 } } },
+          { label: "warm", grading: { preset: "warm-daylight" } },
+        ],
+        frameWidth: 640,
+        frameHeight: 360,
+      });
+
+      try {
+        expect(readFileSync(join(prepared.tempDir, "frame.png"), "utf-8")).toBe("fake-png");
+        expect(readFileSync(join(prepared.tempDir, "lut-0.cube"), "utf-8")).toBe(validCubeLut());
+        expect(readFileSync(join(prepared.tempDir, "index.html"), "utf-8")).toContain(
+          `${HF_COLOR_GRADING_ATTR}='${serializeHfColorGrading({
+            lut: { src: "lut-0.cube", intensity: 0.7 },
+          })}'`,
+        );
+      } finally {
+        rmSync(prepared.tempDir, { recursive: true, force: true });
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects an existing LUT file whose .cube content cannot be parsed", async () => {
+    const dir = tempDir();
+    try {
+      const framePath = join(dir, "frame.png");
+      const lutPath = join(dir, "broken.cube");
+      writeFileSync(framePath, "fake-png");
+      writeFileSync(lutPath, "plain text, not cube data\n");
+
+      await expect(
+        prepareGradeCompareTempProject({
+          projectDir: dir,
+          framePath,
+          frameBuffer: Buffer.from("fake-png"),
+          cells: [{ label: "broken look", grading: { lut: { src: basename(lutPath) } } }],
+          frameWidth: 640,
+          frameHeight: 360,
+        }),
+      ).rejects.toThrow(/LUT for "broken look" is not a valid \.cube:/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("warnInactiveGradingCells", () => {
+  it("warns to stderr for normalized-but-inactive candidate grades", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      expect(() =>
+        warnInactiveGradingCells([{ label: "numeric lut", grading: { lut: 12345 } }]),
+      ).not.toThrow();
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'Warning: grading for "numeric lut" is inactive/no-op — it will render ungraded',
+        ),
+      );
+      expect(logSpy).not.toHaveBeenCalled();
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+});
+
+describe("capCandidateCells", () => {
+  it("truncates over-cap candidates and exposes truncation metadata for JSON output", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const cells = Array.from({ length: 18 }, (_, index) => ({
+        label: `candidate ${index + 1}`,
+        grading: { adjust: { exposure: index / 10 } },
+      }));
+
+      const capped = capCandidateCells(cells);
+
+      expect(capped.cells).toHaveLength(16);
+      expect(capped.cells.at(0)?.label).toBe("candidate 1");
+      expect(capped.cells.at(15)?.label).toBe("candidate 16");
+      expect(capped.truncated).toBe(true);
+      expect(capped.total).toBe(18);
+      expect(buildGradeCompareSuccessPayload("grade-compare.png", 17, capped)).toEqual({
+        ok: true,
+        sheet: "grade-compare.png",
+        cells: 17,
+        truncated: true,
+        total: 18,
+      });
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Warning: 18 candidate grades exceed the 16-cell cap — rendering the first 16 of 18; re-run with fewer grades or split into multiple runs.",
+        ),
+      );
+      expect(logSpy).not.toHaveBeenCalled();
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+});
diff --git a/packages/cli/src/commands/grade-compare.ts b/packages/cli/src/commands/grade-compare.ts
new file mode 100644
index 000000000..d62c172b8
--- /dev/null
+++ b/packages/cli/src/commands/grade-compare.ts
@@ -0,0 +1,698 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import {
+  HF_COLOR_GRADING_ATTR,
+  isHfColorGradingActive,
+  normalizeHfColorGrading,
+  parseCubeLut,
+  serializeHfColorGrading,
+} from "@hyperframes/core";
+import { defineCommand } from "citty";
+import sharp from "sharp";
+import type { Example } from "./_examples.js";
+import { openSettledCompositionPage, runFfmpegOnce } from "../capture/captureCompositionFrame.js";
+import { findFFmpeg } from "../browser/ffmpeg.js";
+import { c } from "../ui/colors.js";
+import { normalizeErrorMessage } from "../utils/errorMessage.js";
+import { displayPathFromBase, readOptionalString, resolveFromBase } from "../utils/pathArgs.js";
+import { trackCompareSheet } from "../telemetry/events.js";
+import { serveStaticProjectHtml } from "../utils/staticProjectServer.js";
+import { withMeta } from "../utils/updateCheck.js";
+
+const COMPOSITION_ID = "grade-compare";
+const COMPOSITION_DURATION = "1";
+const DEFAULT_CELL_WIDTH = 560;
+const MAX_CANDIDATE_CELLS = 16;
+const MAX_COLUMNS = 4;
+const GRID_PADDING = 16;
+const LABEL_HEIGHT = 32;
+const FFMPEG_EXTRACT_TIMEOUT_MS = 30_000;
+
+export interface GradeCompareCell {
+  label: string;
+  grading: unknown;
+}
+
+interface ParsedGradeCompareArgs {
+  framePath: string;
+  projectDir: string;
+  outPath: string;
+  source: { kind: "grades"; path: string } | { kind: "luts"; value: string };
+  json: boolean;
+  timeoutMs: number;
+}
+
+interface PreparedGradeCompareProject {
+  tempDir: string;
+  html: string;
+  cells: GradeCompareCell[];
+}
+
+export interface CandidateCellCapResult {
+  cells: GradeCompareCell[];
+  truncated: boolean;
+  total: number;
+}
+
+export interface GradeCompareSuccessPayload {
+  ok: true;
+  sheet: string;
+  cells: number;
+  truncated?: true;
+  total?: number;
+}
+
+interface GradeCompareHtmlOptions {
+  cells: readonly GradeCompareCell[];
+  frameSrc: string;
+  frameWidth: number;
+  frameHeight: number;
+}
+
+interface ReferenceFrame {
+  buffer: Buffer;
+  width: number;
+  height: number;
+  stagedName: string;
+}
+
+export const examples: Example[] = [
+  [
+    "Compare grade presets on one reference frame",
+    "hyperframes grade-compare --for frame.png --grades grades.json",
+  ],
+  [
+    "Compare LUT files and print agent-friendly JSON",
+    "hyperframes grade-compare --for frame.png --luts looks/a.cube,looks/b.cube --json",
+  ],
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function cloneRecord(record: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    next[key] = value;
+  }
+  return next;
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function escapeSingleQuotedAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/'/g, "&#39;");
+}
+
+function validateCell(label: string, grading: unknown): GradeCompareCell {
+  if (!normalizeHfColorGrading(grading)) {
+    throw new Error(`Invalid color grading for cell "${label}"`);
+  }
+  return { label, grading };
+}
+
+export function warnInactiveGradingCells(cells: readonly GradeCompareCell[]): void {
+  for (const cell of cells) {
+    const normalized = normalizeHfColorGrading(cell.grading);
+    if (!isHfColorGradingActive(normalized)) {
+      console.error(
+        c.warn(`Warning: grading for "${cell.label}" is inactive/no-op — it will render ungraded`),
+      );
+    }
+  }
+}
+
+export function capCandidateCells(cells: readonly GradeCompareCell[]): CandidateCellCapResult {
+  const total = cells.length;
+  if (total <= MAX_CANDIDATE_CELLS) {
+    return { cells: [...cells], truncated: false, total };
+  }
+  console.error(
+    c.warn(
+      `Warning: ${total} candidate grades exceed the ${MAX_CANDIDATE_CELLS}-cell cap — rendering the first ${MAX_CANDIDATE_CELLS} of ${total}; re-run with fewer grades or split into multiple runs.`,
+    ),
+  );
+  return { cells: cells.slice(0, MAX_CANDIDATE_CELLS), truncated: true, total };
+}
+
+export function buildGradeCompareSuccessPayload(
+  sheet: string,
+  cells: number,
+  capResult: CandidateCellCapResult,
+): GradeCompareSuccessPayload {
+  if (!capResult.truncated) {
+    return { ok: true, sheet, cells };
+  }
+  return { ok: true, sheet, cells, truncated: true, total: capResult.total };
+}
+
+function serializedGradingForCell(cell: GradeCompareCell): string {
+  const normalized = normalizeHfColorGrading(cell.grading);
+  if (!normalized) {
+    throw new Error(`Invalid color grading for cell "${cell.label}"`);
+  }
+  return serializeHfColorGrading(normalized);
+}
+
+function lutSrcFromGrading(grading: unknown): string | null {
+  if (!isRecord(grading) || !hasOwn(grading, "lut")) return null;
+  const lut = grading.lut;
+  if (typeof lut === "string" && lut.trim()) return lut.trim();
+  if (!isRecord(lut)) return null;
+  const src = lut.src;
+  return typeof src === "string" && src.trim() ? src.trim() : null;
+}
+
+function rewriteGradingLutSrc(grading: unknown, src: string): unknown {
+  if (!isRecord(grading) || !hasOwn(grading, "lut")) return grading;
+  const lut = grading.lut;
+  const next = cloneRecord(grading);
+  if (typeof lut === "string") {
+    next.lut = { src };
+    return next;
+  }
+  if (isRecord(lut)) {
+    const nextLut = cloneRecord(lut);
+    nextLut.src = src;
+    next.lut = nextLut;
+  }
+  return next;
+}
+
+export function parseGradesFile(filePath: string): GradeCompareCell[] {
+  if (!existsSync(filePath)) {
+    throw new Error(`Grades file not found: ${filePath}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Could not parse grades JSON: ${normalizeErrorMessage(err)}`);
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new Error("Grades file must be a JSON array of { label, grading } objects");
+  }
+
+  return parsed.map((entry, index) => {
+    if (!isRecord(entry)) {
+      throw new Error(`Grade entry ${index + 1} must be an object with label and grading`);
+    }
+    const label = entry.label;
+    if (typeof label !== "string" || !label.trim()) {
+      throw new Error(`Grade entry ${index + 1} must have a non-empty string label`);
+    }
+    if (!hasOwn(entry, "grading")) {
+      throw new Error(`Grade entry "${label}" must include a grading value`);
+    }
+    return validateCell(label, entry.grading);
+  });
+}
+
+export function resolveLutCells(luts: string): GradeCompareCell[] {
+  const paths = luts
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (paths.length === 0) {
+    throw new Error("--luts must include at least one LUT path");
+  }
+  return paths.map((lutPath) =>
+    validateCell(basename(lutPath, extname(lutPath)), { lut: { src: lutPath } }),
+  );
+}
+
+// The ungraded frame as a leading reference cell. An empty grading object
+// normalizes to inactive, so the runtime renders the source image untouched —
+// giving the agent a baseline to judge every candidate look against.
+export function prependBaselineCell(cells: GradeCompareCell[]): GradeCompareCell[] {
+  return [validateCell("original", {}), ...cells];
+}
+
+export function parseGradeCompareArgs(args: {
+  for?: unknown;
+  grades?: unknown;
+  luts?: unknown;
+  project?: unknown;
+  out?: unknown;
+  json?: unknown;
+  timeout?: unknown;
+}): ParsedGradeCompareArgs {
+  const frameArg = readOptionalString(args.for);
+  if (!frameArg) throw new Error("--for <path> is required");
+
+  const gradesArg = readOptionalString(args.grades);
+  const lutsArg = readOptionalString(args.luts);
+  if (Boolean(gradesArg) === Boolean(lutsArg)) {
+    throw new Error("Exactly one of --grades or --luts is required");
+  }
+
+  const projectDir = resolve(readOptionalString(args.project) ?? process.cwd());
+  const framePath = resolveFromBase(projectDir, frameArg);
+  const outPath = resolveFromBase(projectDir, readOptionalString(args.out) ?? "grade-compare.png");
+
+  return {
+    framePath,
+    projectDir,
+    outPath,
+    source: gradesArg
+      ? { kind: "grades", path: resolveFromBase(projectDir, gradesArg) }
+      : { kind: "luts", value: lutsArg ?? "" },
+    json: args.json === true,
+    timeoutMs: Number.parseInt(readOptionalString(args.timeout) ?? "", 10) || 5000,
+  };
+}
+
+function gridMetrics(
+  cellCount: number,
+  frameWidth: number,
+  frameHeight: number,
+): {
+  columns: number;
+  rows: number;
+  cellImageWidth: number;
+  cellImageHeight: number;
+  width: number;
+  height: number;
+} {
+  const columns = Math.max(1, Math.min(MAX_COLUMNS, Math.ceil(Math.sqrt(cellCount))));
+  const rows = Math.ceil(cellCount / columns);
+  const cellImageWidth = DEFAULT_CELL_WIDTH;
+  const aspect = frameHeight > 0 && frameWidth > 0 ? frameHeight / frameWidth : 9 / 16;
+  const cellImageHeight = Math.max(1, Math.round(cellImageWidth * aspect));
+  return {
+    columns,
+    rows,
+    cellImageWidth,
+    cellImageHeight,
+    width: columns * cellImageWidth + (columns + 1) * GRID_PADDING,
+    height: rows * (cellImageHeight + LABEL_HEIGHT) + (rows + 1) * GRID_PADDING,
+  };
+}
+
+export function buildGradeCompareHtml(options: GradeCompareHtmlOptions): string {
+  if (options.cells.length === 0) {
+    throw new Error("At least one grade cell is required");
+  }
+  const metrics = gridMetrics(options.cells.length, options.frameWidth, options.frameHeight);
+
+  const cellHtml = options.cells
+    .map((cell, index) => {
+      const serialized = escapeSingleQuotedAttr(serializedGradingForCell(cell));
+      const label = escapeXml(cell.label);
+      const row = Math.floor(index / metrics.columns);
+      const col = index % metrics.columns;
+      const left = GRID_PADDING + col * (metrics.cellImageWidth + GRID_PADDING);
+      const top = GRID_PADDING + row * (metrics.cellImageHeight + LABEL_HEIGHT + GRID_PADDING);
+      return `      <figure class="grade-cell" style="left:${left}px;top:${top}px;width:${metrics.cellImageWidth}px;height:${metrics.cellImageHeight + LABEL_HEIGHT}px">
+        <figcaption>${label}</figcaption>
+        <img src="${escapeXml(options.frameSrc)}" ${HF_COLOR_GRADING_ATTR}='${serialized}' alt="${label}" />
+      </figure>`;
+    })
+    .join("\n");
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=${metrics.width}, height=${metrics.height}" />
+    <title>HyperFrames Grade Compare</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      html,
+      body {
+        margin: 0;
+        width: ${metrics.width}px;
+        height: ${metrics.height}px;
+        overflow: hidden;
+        background: #191919;
+        font-family: Arial, Helvetica, sans-serif;
+      }
+
+      #${COMPOSITION_ID} {
+        position: relative;
+        width: ${metrics.width}px;
+        height: ${metrics.height}px;
+        overflow: hidden;
+        background: #191919;
+      }
+
+      .grade-cell {
+        position: absolute;
+        margin: 0;
+        background: #0f0f0f;
+      }
+
+      .grade-cell figcaption {
+        height: ${LABEL_HEIGHT}px;
+        line-height: ${LABEL_HEIGHT}px;
+        padding: 0 10px;
+        box-sizing: border-box;
+        overflow: hidden;
+        white-space: nowrap;
+        text-overflow: ellipsis;
+        color: #ffffff;
+        background: #111111;
+        font-size: 14px;
+        font-weight: 700;
+      }
+
+      .grade-cell img {
+        display: block;
+        width: ${metrics.cellImageWidth}px;
+        height: ${metrics.cellImageHeight}px;
+        object-fit: contain;
+        background: #000000;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="${COMPOSITION_ID}"
+      data-composition-id="${COMPOSITION_ID}"
+      data-start="0"
+      data-duration="${COMPOSITION_DURATION}"
+      data-width="${metrics.width}"
+      data-height="${metrics.height}"
+    >
+${cellHtml}
+      <script>
+        window.__timelines = window.__timelines || {};
+        window.__timelines["${COMPOSITION_ID}"] = gsap.timeline({ paused: true });
+      </script>
+    </div>
+  </body>
+</html>
+`;
+}
+
+function frameFileNameForPath(framePath: string): string {
+  const ext = extname(framePath).toLowerCase();
+  if (ext === ".jpg" || ext === ".jpeg") return `frame${ext}`;
+  return "frame.png";
+}
+
+export async function prepareGradeCompareTempProject(opts: {
+  projectDir: string;
+  framePath: string;
+  frameBuffer: Buffer;
+  cells: readonly GradeCompareCell[];
+  frameWidth: number;
+  frameHeight: number;
+  frameFileName?: string;
+}): Promise<PreparedGradeCompareProject> {
+  const tempDir = mkdtempSync(join(tmpdir(), "hf-grade-compare-"));
+  try {
+    const frameFileName = opts.frameFileName ?? frameFileNameForPath(opts.framePath);
+    writeFileSync(join(tempDir, frameFileName), opts.frameBuffer);
+
+    let lutIndex = 0;
+    const stagedCells = opts.cells.map((cell) => {
+      const lutSrc = lutSrcFromGrading(cell.grading);
+      if (!lutSrc) return cell;
+
+      const sourcePath = resolveFromBase(opts.projectDir, lutSrc);
+      if (!existsSync(sourcePath)) {
+        throw new Error(`LUT file not found for "${cell.label}": ${sourcePath}`);
+      }
+      const lutText = readFileSync(sourcePath, "utf-8");
+      try {
+        parseCubeLut(lutText, { maxSize: 64 });
+      } catch (err) {
+        throw new Error(
+          `LUT for "${cell.label}" is not a valid .cube: ${normalizeErrorMessage(err)}`,
+        );
+      }
+      const lutExt = extname(sourcePath) || ".cube";
+      const stagedName = `lut-${lutIndex}${lutExt}`;
+      lutIndex += 1;
+      copyFileSync(sourcePath, join(tempDir, stagedName));
+      return {
+        label: cell.label,
+        grading: rewriteGradingLutSrc(cell.grading, stagedName),
+      };
+    });
+
+    const html = buildGradeCompareHtml({
+      cells: stagedCells,
+      frameSrc: frameFileName,
+      frameWidth: opts.frameWidth,
+      frameHeight: opts.frameHeight,
+    });
+    writeFileSync(join(tempDir, "index.html"), html);
+    return { tempDir, html, cells: stagedCells };
+  } catch (err) {
+    rmSync(tempDir, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+function isVideoPath(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  return [".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi", ".mpeg", ".mpg", ".ogv"].includes(ext);
+}
+
+async function extractVideoFrameToBuffer(videoPath: string): Promise<Buffer | null> {
+  const tmp = mkdtempSync(join(tmpdir(), "hf-grade-compare-frame-"));
+  const outPath = join(tmp, "frame.png");
+  try {
+    const ffmpegPath = findFFmpeg();
+    if (!ffmpegPath) return null;
+    const args = [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-ss",
+      "0",
+      "-i",
+      videoPath,
+      "-frames:v",
+      "1",
+      "-q:v",
+      "2",
+      "-y",
+      outPath,
+    ];
+    const result = await runFfmpegOnce(ffmpegPath, args, FFMPEG_EXTRACT_TIMEOUT_MS);
+    if (result.timedOut) {
+      throw new Error(`ffmpeg timed out extracting first frame from ${videoPath}`);
+    }
+    if (result.code !== 0 || !existsSync(outPath)) {
+      const detail = result.stderr.trim() ? `: ${result.stderr.trim()}` : "";
+      throw new Error(`ffmpeg could not extract first frame from ${videoPath}${detail}`);
+    }
+    return readFileSync(outPath);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+async function loadReferenceFrame(framePath: string): Promise<ReferenceFrame> {
+  if (!existsSync(framePath)) {
+    throw new Error(`Reference frame not found: ${framePath}`);
+  }
+
+  const buffer = isVideoPath(framePath)
+    ? await extractVideoFrameToBuffer(framePath)
+    : readFileSync(framePath);
+  if (!buffer) {
+    throw new Error(`Could not extract a frame from video: ${framePath}`);
+  }
+
+  const metadata = await sharp(buffer).metadata();
+  if (!metadata.width || !metadata.height) {
+    throw new Error(`Could not read reference frame dimensions: ${framePath}`);
+  }
+
+  return {
+    buffer,
+    width: metadata.width,
+    height: metadata.height,
+    stagedName: isVideoPath(framePath) ? "frame.png" : frameFileNameForPath(framePath),
+  };
+}
+
+async function captureGradeCompareSheet(
+  projectDir: string,
+  timeoutMs: number,
+): Promise<{ sheetPath: string; renderReadyTimedOut: boolean }> {
+  const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
+
+  const html = await bundleToSingleHtml(projectDir);
+  const server = await serveStaticProjectHtml(projectDir, html);
+  const sheetPath = join(projectDir, "grade-compare.png");
+
+  try {
+    const {
+      browser: chromeBrowser,
+      page,
+      renderReadyTimedOut,
+    } = await openSettledCompositionPage(html, server.url, {
+      renderReadyTimeoutMs: timeoutMs,
+      renderReadyWarningSuffix: "grade comparison may be inaccurate",
+    });
+
+    try {
+      await page.screenshot({ path: sheetPath, type: "png" });
+      return { sheetPath, renderReadyTimedOut };
+    } finally {
+      await chromeBrowser.close();
+    }
+  } finally {
+    await server.close();
+  }
+}
+
+function printJson(payload: object): void {
+  console.log(JSON.stringify(withMeta(payload), null, 2));
+}
+
+export default defineCommand({
+  meta: {
+    name: "grade-compare",
+    description: "Render candidate color grades onto a reference frame as one comparison PNG",
+  },
+  args: {
+    for: {
+      type: "string",
+      description: "Reference image path, or a video path to sample at t=0",
+      required: true,
+    },
+    grades: {
+      type: "string",
+      description: "JSON array of { label, grading } candidate grades",
+    },
+    luts: {
+      type: "string",
+      description: "Comma-separated .cube LUT paths to compare",
+    },
+    project: {
+      type: "string",
+      description: "Base directory for relative --for, --grades, and LUT paths (default: cwd)",
+    },
+    out: {
+      type: "string",
+      description: "Output PNG path (default: <project>/grade-compare.png)",
+    },
+    json: {
+      type: "boolean",
+      description: "Output result as JSON",
+      default: false,
+    },
+    timeout: {
+      type: "string",
+      description: "Render-ready timeout in ms before capture (default: 5000)",
+    },
+    baseline: {
+      type: "boolean",
+      description:
+        "Prepend the ungraded frame as an 'original' reference cell (--no-baseline to omit)",
+      default: true,
+    },
+  },
+  async run({ args }) {
+    const jsonRequested = args.json === true;
+    let preparedDir: string | null = null;
+    try {
+      const parsed = parseGradeCompareArgs({
+        for: args.for,
+        grades: args.grades,
+        luts: args.luts,
+        project: args.project,
+        out: args.out,
+        json: args.json,
+        timeout: args.timeout,
+      });
+      let cells =
+        parsed.source.kind === "grades"
+          ? parseGradesFile(parsed.source.path)
+          : resolveLutCells(parsed.source.value);
+      if (cells.length === 0) {
+        throw new Error("At least one grade candidate is required");
+      }
+      const capResult = capCandidateCells(cells);
+      cells = capResult.cells;
+      warnInactiveGradingCells(cells);
+      if (args.baseline !== false) {
+        cells = prependBaselineCell(cells);
+      }
+
+      if (!parsed.json) {
+        console.log(
+          `${c.accent("◆")}  Rendering ${cells.length} grade candidates from ${c.accent(basename(parsed.framePath))}`,
+        );
+      }
+
+      const frame = await loadReferenceFrame(parsed.framePath);
+      const prepared = await prepareGradeCompareTempProject({
+        projectDir: parsed.projectDir,
+        framePath: parsed.framePath,
+        frameBuffer: frame.buffer,
+        frameWidth: frame.width,
+        frameHeight: frame.height,
+        frameFileName: frame.stagedName,
+        cells,
+      });
+      preparedDir = prepared.tempDir;
+
+      const { sheetPath: tempSheet, renderReadyTimedOut } = await captureGradeCompareSheet(
+        prepared.tempDir,
+        parsed.timeoutMs,
+      );
+      mkdirSync(dirname(parsed.outPath), { recursive: true });
+      copyFileSync(tempSheet, parsed.outPath);
+      trackCompareSheet({
+        command: "grade-compare",
+        cells: prepared.cells.length,
+        truncated: capResult.truncated,
+        total: capResult.total,
+        renderReadyTimedOut,
+      });
+
+      const sheet = displayPathFromBase(parsed.projectDir, parsed.outPath);
+      if (parsed.json) {
+        printJson(buildGradeCompareSuccessPayload(sheet, prepared.cells.length, capResult));
+      } else {
+        console.log(`\n${c.success("◇")}  Grade comparison saved to ${sheet}`);
+      }
+    } catch (err) {
+      const message = normalizeErrorMessage(err);
+      if (jsonRequested) {
+        printJson({ ok: false, error: message });
+      } else {
+        console.error(`\n${c.error("✗")} Grade compare failed: ${message}`);
+      }
+      process.exit(1);
+    } finally {
+      if (preparedDir) {
+        rmSync(preparedDir, { recursive: true, force: true });
+      }
+    }
+  },
+});
diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index 42d408659..51e9f3c7e 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -1,12 +1,15 @@
 // fallow-ignore-file complexity
-import { spawn } from "node:child_process";
 import { defineCommand } from "citty";
 import { existsSync, mkdtempSync, readFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { resolve, join, relative, isAbsolute, basename } from "node:path";
+import {
+  openSettledCompositionPage,
+  runFfmpegOnce,
+  seekCompositionTimeline,
+} from "../capture/captureCompositionFrame.js";
 import { resolveProject } from "../utils/project.js";
 import { normalizeErrorMessage } from "../utils/errorMessage.js";
-import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
 import { serveStaticProjectHtml } from "../utils/staticProjectServer.js";
 import { c } from "../ui/colors.js";
 import { findFFmpeg } from "../browser/ffmpeg.js";
@@ -67,46 +70,25 @@ async function extractVideoFrameToBuffer(
   try {
     const ffmpegPath = findFFmpeg();
     if (!ffmpegPath) return null;
-    const result = await new Promise<{ code: number | null; stderr: string; timedOut: boolean }>(
-      (resolvePromise) => {
-        // `-ss` before `-i` performs a fast keyframe seek; adequate for snapshot accuracy
-        // (±1 frame) and orders of magnitude faster than the decode-and-scan alternative.
-        const args = ["-hide_banner", "-loglevel", "error"];
-        if (useVp9AlphaDecoder) {
-          args.push("-c:v", "libvpx-vp9");
-        }
-        args.push(
-          "-ss",
-          String(Math.max(0, timeSeconds)),
-          "-i",
-          videoPath,
-          "-frames:v",
-          "1",
-          "-q:v",
-          "2",
-          "-y",
-          outPath,
-        );
-        const ff = spawn(ffmpegPath, args);
-        let stderr = "";
-        let timedOut = false;
-        const timer = setTimeout(() => {
-          timedOut = true;
-          ff.kill("SIGTERM");
-        }, FFMPEG_EXTRACT_TIMEOUT_MS);
-        ff.stderr.on("data", (d: Buffer) => {
-          stderr += d.toString();
-        });
-        ff.on("close", (code) => {
-          clearTimeout(timer);
-          resolvePromise({ code, stderr, timedOut });
-        });
-        ff.on("error", () => {
-          clearTimeout(timer);
-          resolvePromise({ code: null, stderr: "ffmpeg spawn failed", timedOut });
-        });
-      },
+    // `-ss` before `-i` performs a fast keyframe seek; adequate for snapshot accuracy
+    // (±1 frame) and orders of magnitude faster than the decode-and-scan alternative.
+    const args = ["-hide_banner", "-loglevel", "error"];
+    if (useVp9AlphaDecoder) {
+      args.push("-c:v", "libvpx-vp9");
+    }
+    args.push(
+      "-ss",
+      String(Math.max(0, timeSeconds)),
+      "-i",
+      videoPath,
+      "-frames:v",
+      "1",
+      "-q:v",
+      "2",
+      "-y",
+      outPath,
     );
+    const result = await runFfmpegOnce(ffmpegPath, args, FFMPEG_EXTRACT_TIMEOUT_MS);
     if (result.code !== 0 || result.timedOut || !existsSync(outPath)) return null;
     return readFileSync(outPath);
   } finally {
@@ -193,7 +175,6 @@ async function captureSnapshots(
   },
 ): Promise<string[]> {
   const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
-  const { ensureBrowser } = await import("../browser/manager.js");
 
   const numFrames = opts.frames ?? 5;
 
@@ -203,75 +184,12 @@ async function captureSnapshots(
   const savedPaths: string[] = [];
 
   try {
-    const browser = await ensureBrowser();
-    const puppeteer = await import("puppeteer-core");
-    const chromeBrowser = await puppeteer.default.launch({
-      headless: true,
-      executablePath: browser.executablePath,
-      args: [
-        "--no-sandbox",
-        "--disable-gpu",
-        "--disable-dev-shm-usage",
-        "--enable-webgl",
-        "--use-gl=angle",
-        "--use-angle=swiftshader",
-      ],
+    const { browser: chromeBrowser, page } = await openSettledCompositionPage(html, server.url, {
+      renderReadyTimeoutMs: opts.timeout ?? 5000,
+      renderReadyWarningSuffix: "snapshots may be inaccurate",
     });
 
     try {
-      const page = await chromeBrowser.newPage();
-      await page.setViewport(resolveCompositionViewportFromHtml(html));
-
-      await page.goto(server.url, {
-        waitUntil: "domcontentloaded",
-        timeout: 10000,
-      });
-
-      // __renderReady is set after the player is constructed AND the root
-      // timeline is bound — waiting for it guarantees renderSeek will work.
-      const timeoutMs = opts.timeout ?? 5000;
-      const runtimeReady = await page
-        .waitForFunction(() => !!(window as any).__renderReady, { timeout: timeoutMs })
-        .then(() => true)
-        .catch(() => false);
-
-      if (!runtimeReady) {
-        console.warn(
-          `\n   ${c.warn("⚠")} Runtime did not become render-ready within ${timeoutMs}ms — snapshots may be inaccurate`,
-        );
-      }
-
-      // Wait for shader transition pre-rendering (HyperShader IndexedDB hydration).
-      // Uses the ready state flag as primary signal, with the loading overlay
-      // display:none as a fallback for older builds.
-      await page
-        .waitForFunction(
-          () => {
-            const win = window as unknown as {
-              __hf?: { shaderTransitions?: Record<string, { ready?: boolean }> };
-            };
-            const shaderTransitions = win.__hf?.shaderTransitions;
-            if (shaderTransitions !== undefined) {
-              return Object.values(shaderTransitions).every((s) => s.ready === true);
-            }
-            const overlay = document.querySelector(
-              "[data-hyper-shader-loading]",
-            ) as HTMLElement | null;
-            if (!overlay) return true;
-            return window.getComputedStyle(overlay).display === "none";
-          },
-          { timeout: 90_000 },
-        )
-        .catch(() => {
-          console.warn(`   ${c.warn("⚠")} Shader transitions did not finish pre-rendering`);
-        });
-
-      // Wait for fonts to finish loading before capturing
-      await page.evaluate(() => document.fonts.ready).catch(() => {});
-
-      // Extra settle time for media and animations to initialize
-      await new Promise((r) => setTimeout(r, 1500));
-
       // Font verification — split into loaded / errored / unused. Only status
       // "error" is a real failure; a face still "unloaded"/"loading" after
       // document.fonts.ready + the settle wait was simply never requested by any
@@ -406,26 +324,7 @@ async function captureSnapshots(
       for (let i = 0; i < positions.length; i++) {
         const time = positions[i]!;
 
-        await page.evaluate((t: number) => {
-          const player = (window as any).__player;
-          if (!player) return;
-          const safe = Math.max(0, Number(t) || 0);
-          if (typeof player.renderSeek === "function") {
-            player.renderSeek(safe);
-          } else if (typeof player.seek === "function") {
-            player.seek(safe);
-          }
-          if ((window as any).gsap?.ticker?.tick) {
-            (window as any).gsap.ticker.tick();
-          }
-        }, time);
-
-        await page.evaluate(`new Promise(function(r) {
-          var settled = false;
-          function finish() { if (settled) return; settled = true; r(); }
-          window.setTimeout(finish, 100);
-          requestAnimationFrame(function() { requestAnimationFrame(finish); });
-        })`);
+        await seekCompositionTimeline(page, time);
 
         if (cameraExpr) await page.evaluate(cameraExpr);
 
diff --git a/packages/cli/src/help.ts b/packages/cli/src/help.ts
index 41f22a6ac..11f0e15de 100644
--- a/packages/cli/src/help.ts
+++ b/packages/cli/src/help.ts
@@ -41,6 +41,11 @@ const GROUPS: Group[] = [
       ["inspect", "Inspect rendered visual layout across the timeline"],
       ["keyframes", "Inspect keyframes and render onion-shot diagnostics"],
       ["snapshot", "Capture key frames as PNG screenshots for visual verification"],
+      [
+        "grade-compare",
+        "Render candidate color grades onto a reference frame as one labeled comparison PNG",
+      ],
+      ["compare", "Render composition variants into one labeled comparison sheet"],
       ["info", "Print project metadata"],
       ["compositions", "List all compositions in a project"],
       ["docs", "View inline documentation in the terminal"],
diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts
index b138778f1..c90392ce4 100644
--- a/packages/cli/src/telemetry/events.ts
+++ b/packages/cli/src/telemetry/events.ts
@@ -492,6 +492,25 @@ export function trackTranscribeUnavailable(props: { optional: boolean }): void {
   trackEvent("transcribe_unavailable", { optional: props.optional });
 }
 
+// grade-compare / compare stand up headless Chrome and render up to 16 cells.
+// Cell count, truncation-cap hits, and whether the render-ready timeout fired
+// are the signals needed before safely lifting the cap. Low-cardinality only.
+export function trackCompareSheet(props: {
+  command: "grade-compare" | "compare";
+  cells: number;
+  truncated: boolean;
+  total: number;
+  renderReadyTimedOut: boolean;
+}): void {
+  trackEvent("media_use_compare", {
+    command: props.command,
+    cells: props.cells,
+    truncated: props.truncated,
+    total: props.total,
+    render_ready_timed_out: props.renderReadyTimedOut,
+  });
+}
+
 // A skills install was skipped because a required prerequisite binary is
 // absent from PATH (e.g. git on a fresh Windows box). Best-effort callers
 // (init) skip cleanly rather than crash, so the skip is otherwise invisible;
diff --git a/packages/cli/src/utils/pathArgs.ts b/packages/cli/src/utils/pathArgs.ts
new file mode 100644
index 000000000..ce6764ce7
--- /dev/null
+++ b/packages/cli/src/utils/pathArgs.ts
@@ -0,0 +1,21 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+export function readOptionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function resolveFromBase(baseDir: string, input: string): string {
+  return isAbsolute(input) ? input : resolve(baseDir, input);
+}
+
+export function displayPathFromBase(baseDir: string, filePath: string): string {
+  const rel = relative(baseDir, filePath);
+  if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
+  return filePath;
+}
+
+export function displayPathFromInput(baseDir: string, input: string): string {
+  return isAbsolute(input) ? displayPathFromBase(baseDir, input) : input;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index fec8f7652..0a527d9a3 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -188,6 +188,7 @@ export {
   type HfColorGradingVariableMap,
   type NormalizedHfColorGrading,
 } from "./colorGrading";
+export { parseCubeLut, CubeLutParseError, type ParseCubeLutOptions } from "./colorLuts";
 
 // Inline scripts
 export {
diff --git a/skills-manifest.json b/skills-manifest.json
index e1e6ae374..49bbd956b 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -18,7 +18,7 @@
       "files": 1
     },
     "hyperframes": {
-      "hash": "24ec436b52957fcc",
+      "hash": "7ddbb928a3674e5e",
       "files": 1
     },
     "hyperframes-animation": {
@@ -26,7 +26,7 @@
       "files": 116
     },
     "hyperframes-cli": {
-      "hash": "493e59cafaab3d10",
+      "hash": "8ca3bef87f169ba1",
       "files": 7
     },
     "hyperframes-core": {
@@ -46,8 +46,8 @@
       "files": 10
     },
     "media-use": {
-      "hash": "22d8da57c4af6ddd",
-      "files": 103
+      "hash": "1bea0c917a66f085",
+      "files": 113
     },
     "motion-graphics": {
       "hash": "96ed2f7d8051b009",
diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md
index 5cd24cfce..a05b06895 100644
--- a/skills/hyperframes-cli/SKILL.md
+++ b/skills/hyperframes-cli/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: hyperframes-cli
-description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, feedback, 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 / sites`).
+description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, compare, grade-compare, preview, play, render, publish, feedback, 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 / sites`).
 ---
 
 # HyperFrames CLI
@@ -24,7 +24,7 @@ Everything runs through `npx hyperframes` unless project instructions specify a
 
 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 — and, when a `*.motion.json` sidecar is present, verifies motion intent (entrances firing under seek, stagger order, in-frame, liveness) against that same seeked timeline.
 
-For motion-heavy work, prefer snapshot-driven iteration and a `*.motion.json` sidecar — see `references/lint-validate-inspect.md` for the discipline and motion-verification spec.
+For motion-heavy work, prefer snapshot-driven iteration and a `*.motion.json` sidecar — see `references/lint-validate-inspect.md` for the discipline and motion-verification spec. To compare agent-authored candidate variants, use `npx hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json]` to render each composition through its own runtime, assemble one labeled sheet, inspect it side by side, and choose. For color-grade selection, use the color-specific sibling `npx hyperframes grade-compare --for <frame> --grades grades.json` (or `--luts a.cube,b.cube`) to render every grading candidate through the real WebGL grading runtime into one labeled PNG before choosing the winner.
 
 ## Agent Conventions
 
diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md
index 5a674a653..b80d7e1cc 100644
--- a/skills/hyperframes/SKILL.md
+++ b/skills/hyperframes/SKILL.md
@@ -25,16 +25,16 @@ Below: a **capability map** (the domain skills, loaded on demand) and the **inte
 
 Atomic capabilities you load **on demand** — not full workflows; they never own the end-to-end task. For "make me a…" intent, use the intent router below.
 
-| You want to…                                                                                                                                                            | Skill                    |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Author / edit an HTML composition** — the `data-*` contract, clips, tracks, sub-compositions, variables                                                               | `/hyperframes-core`      |
-| **Animate** — atomic motion, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU)                              | `/hyperframes-animation` |
-| **Author seek-safe keyframes** — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth, plus `hyperframes keyframes` diagnostics | `/hyperframes-keyframes` |
-| **Creative direction** — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive                                                       | `/hyperframes-creative`  |
-| **Media** — resolve/generate BGM, SFX, image, icon, brand logo, voice; TTS voiceover, transcription, background removal, captions; cross-project reuse                  | `/media-use`             |
-| **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor                                                                                      | `/hyperframes-cli`       |
-| **Install registry blocks / components** (`hyperframes add`)                                                                                                            | `/hyperframes-registry`  |
-| **Import Figma content** — assets, tokens, components, storyboards→reconstructed motion (REST/CLI); Motion (MCP), shaders (MCP source / native export)                  | `/figma`                 |
+| You want to…                                                                                                                                                             | Skill                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| **Author / edit an HTML composition** — the `data-*` contract, clips, tracks, sub-compositions, variables                                                                | `/hyperframes-core`      |
+| **Animate** — atomic motion, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU)                               | `/hyperframes-animation` |
+| **Author seek-safe keyframes** — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth, plus `hyperframes keyframes` diagnostics  | `/hyperframes-keyframes` |
+| **Creative direction** — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive                                                        | `/hyperframes-creative`  |
+| **Media** — resolve/generate BGM, SFX, image, icon, brand logo, voice, color grade, LUT; TTS voiceover, transcription, background removal, captions; cross-project reuse | `/media-use`             |
+| **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor                                                                                       | `/hyperframes-cli`       |
+| **Install registry blocks / components** (`hyperframes add`)                                                                                                             | `/hyperframes-registry`  |
+| **Import Figma content** — assets, tokens, components, storyboards→reconstructed motion (REST/CLI); Motion (MCP), shaders (MCP source / native export)                   | `/figma`                 |
 
 ---
 
diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md
index 40e94fcc7..0eaf69a59 100644
--- a/skills/media-use/SKILL.md
+++ b/skills/media-use/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: media-use
-description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, or voice into a frozen local file + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Keeps search noise on disk, hands the agent a path. Use for any audio, image, icon, voiceover, caption, or media-asset need.
+description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Keeps search noise on disk, hands the agent one path or block. Use for any audio, image, icon, logo, voiceover, caption, color-grading, or media-asset need.
 ---
 
 # media-use
@@ -21,13 +21,36 @@ HyperFrames owns media _playback_; media-use owns everything else. Each row is e
 | No transcript-driven cutting               | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists                                                                   |
 | No auto-duck / publish loudness            | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes                                                            |
 | No cross-project memory                    | global content-addressed cache + auto-promote (`~/.media`)                                                                                  |
+| No color-grade authoring                   | `resolve --type grade` emits a paste-ready `data-color-grading` block; `resolve --type lut` freezes validated `.cube` files                 |
 | No image generation                        | RAM-graded local mflux (FLUX) via `scripts/lib/mflux-provider.mjs`, codex `image_gen` upsell (`scripts/lib/codex-provider.mjs`)             |
 | No video generation                        | spec-gated local LTX (`videogen` in `scripts/lib/local-models.mjs`); `heygen video create` avatar upsell                                    |
 | Weak local-model defaults                  | free-usage HeyGen first (TTS, bg-removal) via the `heygen` CLI; local open-source only as an opt-out fallback (`scripts/lib/local-run.mjs`) |
 
 ## When to use
 
-Call `resolve` whenever a composition needs media: background music, sound effects, images, icons, brand logos, or voice. For voiceover / TTS, music, SFX, and caption timing, use the **audio engine** (below); background removal is delegated to the `hyperframes` CLI; transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`). For cutting / reframing / transforming existing media, see `references/operations.md`. media-use searches the HeyGen catalog first, freezes the best match locally, registers it in a manifest, and hands the agent one line; all search noise stays on disk.
+Call `resolve` whenever a composition needs media: background music, sound effects, images, icons, brand logos, voice, a color grade, or a LUT. For voiceover / TTS, music, SFX, and caption timing, use the **audio engine** (below); background removal is delegated to the `hyperframes` CLI; transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`). For cutting / reframing / transforming existing media, see `references/operations.md`. media-use searches the HeyGen catalog first for media files, resolves official logos through the logo cascade, uses local deterministic color grading for `grade`/`lut`, freezes the best match locally when a file is needed, registers it in a manifest, and hands the agent one line; all search noise stays on disk.
+
+## Be proactive — run a media opportunity pass
+
+The human usually can't tell which media would lift the piece. You can. When you build or review a composition, do **one** grounded scan and then **ask once** — don't silently add, and don't nag per asset.
+
+Surface an opportunity only when a concrete signal is present:
+
+| Signal detected                                        | Offer                                                                                       |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| On-screen text / a script with no voiceover            | TTS voiceover (audio engine)                                                                |
+| Emoji or a `<div>` styled as an icon                   | resolve real `icon`s                                                                        |
+| Image that is a placeholder, tiny, or upscaled-looking | a better `image` (and/or upscale — see `references/operations.md`)                          |
+| Hard scene cuts / transitions with no sound            | transition `sfx`                                                                            |
+| A piece over ~10s with no music bed                    | `bgm`                                                                                       |
+| Footage that reads under/over-exposed or color-cast    | a corrective `grade` (analyze with `grade --for`, preview with `hyperframes grade-compare`) |
+
+Rules that keep this a help, not nagware:
+
+- **Grounded, not generic.** No signal → no suggestion. Never open with "want better images?".
+- **Opinionated + concrete.** Propose the specific fix ("add a VO from your script, swap 3 emoji for real icons, replace the 400×400 hero, whooshes on the 4 cuts"), with defaults chosen — the human just approves **all / some / none**.
+- **Once per project.** One consolidated ask, top few highest-value items. Respect "leave it" and don't re-raise.
+- **Surface, never silently mutate.** Color grades especially: propose and preview, never auto-apply — a gray-world "correction" ruins an intentional sunset or neon look.
 
 ## Resolve
 
@@ -39,14 +62,16 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
 
 ### Types
 
-| Type    | What it finds        | Provider                                                 |
-| ------- | -------------------- | -------------------------------------------------------- |
-| `bgm`   | Background music     | HeyGen audio catalog (10k+ tracks)                       |
-| `sfx`   | Sound effects        | Bundled 19-file library + HeyGen catalog                 |
-| `image` | Photos, backgrounds  | HeyGen asset search (75k+ vectors)                       |
-| `icon`  | Icons, symbols       | HeyGen asset search (type=icon)                          |
-| `logo`  | Official brand marks | svgl → simple-icons → GitHub org avatar → domain favicon |
-| `voice` | TTS voiceover        | Local Kokoro (free); HeyGen TTS upsell                   |
+| Type    | What it finds                    | Provider / cascade                                           |
+| ------- | -------------------------------- | ------------------------------------------------------------ |
+| `bgm`   | Background music                 | HeyGen audio catalog (10k+ tracks)                           |
+| `sfx`   | Sound effects                    | Bundled 19-file library + HeyGen catalog                     |
+| `image` | Photos, backgrounds              | HeyGen asset search (75k+ vectors)                           |
+| `icon`  | Icons, symbols                   | HeyGen asset search (type=icon)                              |
+| `logo`  | Official brand marks             | svgl → simple-icons → GitHub org avatar → domain favicon     |
+| `voice` | TTS voiceover                    | Local Kokoro (free); HeyGen TTS upsell                       |
+| `grade` | HyperFrames color-grading blocks | Core preset → look index params/CDN LUT → deterministic cube |
+| `lut`   | Reusable `.cube` LUT files       | Look index params/CDN LUT → deterministic cube               |
 
 ### Examples
 
@@ -70,19 +95,28 @@ node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
 # Brand logo (official mark — never redrawn by hand)
 node <SKILL_DIR>/scripts/resolve.mjs --type logo --entity linkedin --intent "LinkedIn logo" --project .
 # → resolved logo_001 → .media/images/logo_001.svg (logo, official mark)
+
+# Color grade block
+node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
+# → {"ok":true,"preset":"warm-daylight","grading":{"preset":"warm-daylight","intensity":1},...}
+
+# LUT file
+node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
+# → resolved lut_001 → .media/luts/lut_001.cube (lut)
 ```
 
 ### Flags
 
 | Flag            | Description                                                                          |
 | --------------- | ------------------------------------------------------------------------------------ |
-| `--type, -t`    | Media type: bgm, sfx, image, icon, voice                                             |
+| `--type, -t`    | Media type: bgm, sfx, image, icon, logo, voice, grade, lut                           |
 | `--intent, -i`  | What you need (natural language)                                                     |
 | `--entity, -e`  | Entity name for cache matching (optional)                                            |
 | `--project, -p` | Project directory (default: .)                                                       |
 | `--candidates`  | List reusable assets (project + global cache) for `--type`; no download, no mutation |
 | `--reuse <sha>` | Import a specific global-cache asset (by content sha/prefix, from `--candidates`)    |
 | `--from`        | Freeze a local file or direct public URL (ingest)                                    |
+| `--for`         | Analyze a local image/video and add measured adjust suggestions (`grade` only)       |
 | `--local-only`  | Offline: skip every network provider (cache + local only)                            |
 | `--provider`    | Force one generator (e.g. `codex`, `mflux`, `kokoro`, `heygen`)                      |
 | `--adopt`       | Bulk-import existing assets/ into manifest                                           |
@@ -90,7 +124,7 @@ node <SKILL_DIR>/scripts/resolve.mjs --type logo --entity linkedin --intent "Lin
 
 ## Reuse before you resolve
 
-Before resolving bgm/sfx/image/icon, **check what already exists and reuse it when it fits.** media-use does not semantically match for you — you are the judge. It surfaces candidates; you decide.
+Before resolving bgm/sfx/image/icon/logo/grade/lut, **check what already exists and reuse it when it fits.** media-use does not semantically match for you — you are the judge. It surfaces candidates; you decide.
 
 ```bash
 node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --candidates --project .
@@ -110,6 +144,84 @@ Read the list and judge semantic fit yourself — "upbeat tech launch" ≈ "ener
 
 The deterministic floor still runs automatically: an identical (case/whitespace-insensitive) repeat auto-reuses with no `--candidates` step. `--candidates` is only for the semantic layer above that floor — and a fuzzy match is **never** auto-applied; reuse is always your explicit call. On a resolve that misses the floor and is about to fetch, media-use prints a one-line stderr hint when similar cached assets exist, pointing you back here.
 
+## Color grading
+
+Use `grade` when you need the actual HyperFrames `data-color-grading` value to paste onto an `<img>` or `<video>`. Core presets and params-backed library looks resolve locally; future CDN-backed library looks require network unless already frozen:
+
+**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
+```
+
+Preset-first output uses the core runtime vocabulary and does not freeze a file:
+
+```json
+{
+  "preset": "warm-daylight",
+  "intensity": 1
+}
+```
+
+Paste it as an attribute value after JSON string escaping:
+
+```html
+<video
+  class="clip"
+  src="./media/scene.mp4"
+  data-color-grading='{"preset":"warm-daylight","intensity":1}'
+></video>
+```
+
+Looks beyond the preset vocabulary freeze a validated `.cube` under `.media/luts/` and return a block that references it:
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "teal orange blockbuster" --project . --json
+```
+
+```json
+{
+  "intensity": 1,
+  "lut": { "src": ".media/luts/grade_001.cube", "intensity": 0.85 }
+}
+```
+
+Use `lut` when you only need the reusable `.cube` file:
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
+```
+
+For a describable technical look, author an explicit parametric LUT with `--params`:
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type lut --params '{"contrast":0.2,"temperature":-0.3}' --project .
+node <SKILL_DIR>/scripts/resolve.mjs --type grade --params '{"exposure":0.2}' --project . --json
+```
+
+For a LUT generated by your own script, ingest it with `--from`; media-use validates it before registration and rejects invalid or oversized cubes:
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type lut --from custom.cube --project .
+```
+
+Parametric math (`buildCube`) cannot reproduce real film stocks or emulsion looks. Use a CDN-backed scanned `.cube` entry or ingest a real scanned `.cube` for those.
+
+For visual selection, list reusable looks with `resolve --type grade --candidates`, write the promising entries to a `grades.json`, run `hyperframes grade-compare --for <frame> --grades grades.json`, then commit the winner with `resolve -t grade` as the final `data-color-grading` block.
+
+Smart grade is `grade --for <media>`. It runs local `ffmpeg`/`ffprobe` signalstats, merges a bounded `adjust` suggestion into the returned block, and prints the measured evidence to stderr. Stdout remains valid JSON under `--json`; the suggestion is a starting point for the agent to tune, not an automatic neutralization of intentional color.
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm cinematic" --for ./frame.png --project . --json
+```
+
+Library looks live in `luts/index.json`. Each entry keeps `id`, `description`, `tags`, and `intensity`, then supplies either compact `params` for on-demand `buildCube(params)` generation or a direct CDN `url` for future scanned `.cube` files. Do not commit generated `.cube` bodies; resolve validates generated or downloaded cubes as it freezes them under `.media/luts/`.
+
+```bash
+node skills/media-use/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project . --json
+node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
+```
+
 ## Providers
 
 media-use holds no keys; every external tool owns its auth. Generation is
@@ -124,6 +236,7 @@ ladder, `describeModelLadder`); the agent can see the ladder and override.
 | voice         | local **Kokoro** (free, on-device), then **heygen tts** paid upsell                     |
 | icon          | heygen asset search                                                                     |
 | logo          | svgl, then simple-icons, then GitHub org avatar, then domain favicon (all free)         |
+| grade/lut     | local core-preset map, params/CDN look index, deterministic `buildCube` fallback        |
 | video (local) | local LTX (`videogen` ladder); `heygen video create` avatar upsell                      |
 
 Local Kokoro (voice), mflux (image), and LTX (video) run on-device (free,
@@ -147,7 +260,7 @@ leaving the project + global cache and any local provider.
 1. Check project `.media/manifest.jsonl` for a prompt match (case- and whitespace-insensitive) — auto-reuse
 2. Scan existing `assets/` directory for unregistered files that share a word with the need
 3. Check global cache `~/.media/` for a reusable asset matched on the same normalized prompt — auto-reuse
-4. Search via provider (HeyGen audio catalog, HeyGen asset search), then generate
+4. Search via provider (HeyGen audio catalog, HeyGen asset search), or resolve color locally
 5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`, auto-promote to `~/.media/`
 
 Steps 1 and 3 are the **deterministic floor**: they only auto-reuse an exact-normalized match, never a fuzzy one. Semantic reuse ("close enough") is the agent's explicit call via [Reuse before you resolve](#reuse-before-you-resolve) — it never happens automatically. The agent gets back **one line**; candidates, scores, provenance stay on disk.
@@ -227,7 +340,7 @@ tool to unlock its free, private, on-device path. media-use holds no keys.
 
 | Tool               | Serves                                                                   | Install                                                                                                             |
 | ------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `ffmpeg`/`ffprobe` | adopt probing, cut, duck bake, loudnorm                                  | system package (`brew install ffmpeg`)                                                                              |
+| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm         | system package (`brew install ffmpeg`)                                                                              |
 | `heygen`           | catalog (bgm/sfx/image/icon), TTS + avatar upsell                        | `curl -fsSL https://static.heygen.ai/cli/install.sh \| bash` then `heygen auth login --key <key>` (needs >= v0.1.6) |
 | `mflux-generate`   | local image gen (FLUX), best-for-RAM                                     | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                  |
 | `codex`            | image gen upsell (ChatGPT sub)                                           | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                |
diff --git a/skills/media-use/luts/README.md b/skills/media-use/luts/README.md
new file mode 100644
index 000000000..dc3ed9ae5
--- /dev/null
+++ b/skills/media-use/luts/README.md
@@ -0,0 +1,28 @@
+# LUT library (authoring)
+
+`index.json` is the agent-consumed catalog of color-grade looks. Each entry resolves
+on demand — no `.cube` bodies are committed to the repo.
+
+Each look has:
+
+- `id`, `description`, `tags`, `intensity` — matching + application metadata.
+- `url` (optional) — a hosted `.cube` downloaded, validated, and frozen at resolve
+  time, exactly like bgm/image assets.
+- `params` (optional) — a deterministic `buildCube` spec used offline (`--local-only`)
+  or as a fallback if the `url` download/validation fails.
+
+An entry needs at least one of `url` or `params`; prefer both (CDN url with a params
+fallback) so resolution is never blocked on the network.
+
+## Hosting a new look (operators)
+
+1. Generate the `.cube` (e.g. `resolve -t lut --params '{...}'` or a graded export).
+2. Upload it to the public CDN origin bucket:
+
+   ```
+   aws s3 cp <id>.cube s3://heygen-public/luts/<id>.cube
+   ```
+
+   It is then served at `https://static.heygen.ai/luts/<id>.cube` (CloudFront).
+
+3. Add an entry to `index.json` with that `url` (and ideally a `params` fallback).
diff --git a/skills/media-use/luts/index.json b/skills/media-use/luts/index.json
new file mode 100644
index 000000000..9f6725c4a
--- /dev/null
+++ b/skills/media-use/luts/index.json
@@ -0,0 +1,57 @@
+{
+  "notes": "Look entries resolve on-demand from a CDN .cube `url` (downloaded + frozen, like bgm/image); `params` is a deterministic buildCube fallback used offline (--local-only) or if the download/validation fails. No .cube bodies are committed. See README.md to author or host a new look.",
+  "looks": [
+    {
+      "id": "teal-orange-blockbuster",
+      "description": "Teal shadows and warm orange highlights for blockbuster-style cinematic footage.",
+      "tags": ["teal", "orange", "blockbuster", "cinematic", "split tone", "movie"],
+      "intensity": 0.85,
+      "url": "https://static.heygen.ai/luts/teal-orange-blockbuster.cube",
+      "params": {
+        "contrast": 0.18,
+        "saturation": 0.08,
+        "vibrance": 0.12,
+        "splitTone": {
+          "intensity": 0.62,
+          "balance": 0.52,
+          "shadows": [-0.04, 0.05, 0.09],
+          "highlights": [0.1, 0.04, -0.03]
+        }
+      }
+    },
+    {
+      "id": "bleach-bypass",
+      "description": "High-contrast desaturated bleach bypass look with strong blacks.",
+      "tags": ["bleach", "bypass", "desaturated", "high contrast", "gritty", "film"],
+      "intensity": 0.8,
+      "url": "https://static.heygen.ai/luts/bleach-bypass.cube",
+      "params": {
+        "blacks": 0.04,
+        "shadows": -0.08,
+        "highlights": 0.08,
+        "whites": 0.18,
+        "contrast": 0.55,
+        "temperature": -0.02,
+        "saturation": -0.72,
+        "vibrance": -0.25
+      }
+    },
+    {
+      "id": "film-fade",
+      "description": "Soft faded film wash with lifted blacks and warm highlights.",
+      "tags": ["film", "fade", "faded", "wash", "warm", "vintage"],
+      "intensity": 0.75,
+      "url": "https://static.heygen.ai/luts/film-fade.cube",
+      "params": {
+        "blacks": 0.35,
+        "shadows": 0.18,
+        "highlights": 0.02,
+        "whites": -0.03,
+        "contrast": -0.28,
+        "temperature": 0.16,
+        "saturation": -0.12,
+        "vibrance": -0.08
+      }
+    }
+  ]
+}
diff --git a/skills/media-use/scripts/lib/candidates.mjs b/skills/media-use/scripts/lib/candidates.mjs
index 4532c49fa..c8ecff055 100644
--- a/skills/media-use/scripts/lib/candidates.mjs
+++ b/skills/media-use/scripts/lib/candidates.mjs
@@ -75,7 +75,8 @@ export function formatCandidates(candidates, { truncated, total } = {}) {
   if (candidates.length === 0) return "no reuse candidates found (project or global cache)";
   const lines = [`${candidates.length} reuse candidate${candidates.length === 1 ? "" : "s"}:`, ""];
   for (const c of candidates) {
-    const handle = c.scope === "global" ? `--reuse ${String(c.sha).slice(0, 16)}` : c.path;
+    const handle =
+      c.scope === "global" ? `--reuse ${String(c.sha).slice(0, 16)}` : c.path || `manifest:${c.id}`;
     const m = meta(c);
     lines.push(`  [${c.scope}] ${c.description}${m ? ` (${m})` : ""}`);
     lines.push(`          ${handle}`);
diff --git a/skills/media-use/scripts/lib/cube-build.mjs b/skills/media-use/scripts/lib/cube-build.mjs
new file mode 100644
index 000000000..92b8f2012
--- /dev/null
+++ b/skills/media-use/scripts/lib/cube-build.mjs
@@ -0,0 +1,181 @@
+const DEFAULT_SIZE = 33;
+const MAX_SIZE = 64;
+
+function clamp(value, min, max) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(max, Math.max(min, value));
+}
+
+function clampUnit(value) {
+  return clamp(value, 0, 1);
+}
+
+function readParam(params, key, min, max) {
+  return clamp(Number(params?.[key] ?? 0), min, max);
+}
+
+function luma([r, g, b]) {
+  // Rec.709 luma weightings (matches the color space the grading runtime uses).
+  return r * 0.2126 + g * 0.7152 + b * 0.0722;
+}
+
+function smoothstep(edge0, edge1, value) {
+  const t = clampUnit((value - edge0) / (edge1 - edge0));
+  return t * t * (3 - 2 * t);
+}
+
+function applyLiftGain(color, params) {
+  const y = luma(color);
+  const blacks = readParam(params, "blacks", -1, 1);
+  const shadows = readParam(params, "shadows", -1, 1);
+  const highlights = readParam(params, "highlights", -1, 1);
+  const whites = readParam(params, "whites", -1, 1);
+  const shadowMask = 1 - smoothstep(0.18, 0.62, y);
+  const highlightMask = smoothstep(0.38, 0.82, y);
+  const offset =
+    blacks * 0.08 + shadows * 0.12 * shadowMask + highlights * 0.12 * highlightMask + whites * 0.08;
+  return color.map((channel) => clampUnit(channel + offset));
+}
+
+function applyExposure(color, params) {
+  const exposure = readParam(params, "exposure", -2, 2);
+  const gain = 2 ** exposure;
+  const lift = Math.max(0, exposure) * 0.015;
+  return color.map((channel) => clampUnit(channel * gain + lift));
+}
+
+function applyContrast(color, params) {
+  const contrast = readParam(params, "contrast", -1, 1);
+  if (contrast === 0) return color;
+  const factor = 1 + contrast * 1.2;
+  return color.map((channel) => clampUnit(0.5 + (channel - 0.5) * factor));
+}
+
+function applyWhiteBalance(color, params) {
+  const temperature = readParam(params, "temperature", -1, 1);
+  const tint = readParam(params, "tint", -1, 1);
+  const redScale = 1 + temperature * 0.28 + tint * 0.08;
+  const greenScale = 1 - Math.abs(tint) * 0.1 - tint * 0.08;
+  const blueScale = 1 - temperature * 0.28 + tint * 0.08;
+  return [
+    clampUnit(color[0] * redScale),
+    clampUnit(color[1] * greenScale),
+    clampUnit(color[2] * blueScale),
+  ];
+}
+
+function applySplitTone(color, params) {
+  const split = params?.splitTone;
+  if (!split) return color;
+  const intensity = clampUnit(Number(split.intensity ?? 0));
+  if (intensity === 0) return color;
+  const balance = clampUnit(Number(split.balance ?? 0.5));
+  const y = luma(color);
+  const shadowMask = 1 - smoothstep(balance - 0.25, balance + 0.2, y);
+  const highlightMask = smoothstep(balance - 0.2, balance + 0.25, y);
+  const shadows = Array.isArray(split.shadows) ? split.shadows : [0, 0, 0];
+  const highlights = Array.isArray(split.highlights) ? split.highlights : [0, 0, 0];
+  return color.map((channel, i) =>
+    clampUnit(
+      channel +
+        Number(shadows[i] ?? 0) * shadowMask * intensity +
+        Number(highlights[i] ?? 0) * highlightMask * intensity,
+    ),
+  );
+}
+
+function applySaturation(color, params) {
+  const saturation = readParam(params, "saturation", -1, 1);
+  const vibrance = readParam(params, "vibrance", -1, 1);
+  if (saturation === 0 && vibrance === 0) return color;
+  const y = luma(color);
+  const currentSat = Math.max(
+    Math.abs(color[0] - y),
+    Math.abs(color[1] - y),
+    Math.abs(color[2] - y),
+  );
+  const vibranceWeight = 1 - clampUnit(currentSat * 2);
+  const factor = clamp(1 + saturation + vibrance * vibranceWeight, 0, 2.5);
+  return color.map((channel) => clampUnit(y + (channel - y) * factor));
+}
+
+function applyParams(color, params) {
+  let out = applyLiftGain(color, params);
+  out = applyExposure(out, params);
+  out = applyContrast(out, params);
+  out = applyWhiteBalance(out, params);
+  out = applySplitTone(out, params);
+  out = applySaturation(out, params);
+  return out;
+}
+
+function formatNumber(value) {
+  return clampUnit(value).toFixed(6);
+}
+
+export function buildCube(params = {}, size = DEFAULT_SIZE) {
+  if (!Number.isInteger(size) || size < 2 || size > MAX_SIZE) {
+    throw new Error(`LUT size must be an integer from 2 to ${MAX_SIZE}`);
+  }
+  const lines = [
+    `TITLE "media-use parametric grade"`,
+    "DOMAIN_MIN 0 0 0",
+    "DOMAIN_MAX 1 1 1",
+    `LUT_3D_SIZE ${size}`,
+  ];
+  const denom = size - 1;
+  for (let b = 0; b < size; b++) {
+    for (let g = 0; g < size; g++) {
+      for (let r = 0; r < size; r++) {
+        const out = applyParams([r / denom, g / denom, b / denom], params);
+        lines.push(`${formatNumber(out[0])} ${formatNumber(out[1])} ${formatNumber(out[2])}`);
+      }
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function paramsFromIntent(intent) {
+  const text = String(intent ?? "").toLowerCase();
+  const params = {};
+  let matched = false;
+
+  if (/\b(warm|golden|sunlit|sunny)\b/.test(text)) {
+    params.temperature = 0.18;
+    matched = true;
+  } else if (/\b(cool|blue|icy|crisp)\b/.test(text)) {
+    params.temperature = -0.16;
+    matched = true;
+  }
+
+  if (/\b(cinematic|film|movie)\b/.test(text)) {
+    params.contrast = 0.08;
+    params.saturation = 0.04;
+    matched = true;
+  }
+  if (/\b(punchy|contrast|dramatic|bold)\b/.test(text)) {
+    params.contrast = Math.max(params.contrast ?? 0, 0.22);
+    matched = true;
+  }
+  if (/\b(bright|airy|lift)\b/.test(text)) {
+    params.exposure = 0.16;
+    params.shadows = 0.08;
+    matched = true;
+  }
+  if (/\b(dark|moody|low-key)\b/.test(text)) {
+    params.exposure = -0.12;
+    params.contrast = Math.max(params.contrast ?? 0, 0.12);
+    matched = true;
+  }
+  if (/\b(vibrant|saturated|colorful)\b/.test(text)) {
+    params.saturation = Math.max(params.saturation ?? 0, 0.16);
+    params.vibrance = 0.12;
+    matched = true;
+  }
+  if (/\b(muted|desaturated|washed)\b/.test(text)) {
+    params.saturation = Math.min(params.saturation ?? 0, -0.16);
+    matched = true;
+  }
+
+  return matched ? params : null;
+}
diff --git a/skills/media-use/scripts/lib/cube-build.test.mjs b/skills/media-use/scripts/lib/cube-build.test.mjs
new file mode 100644
index 000000000..7824d7a2c
--- /dev/null
+++ b/skills/media-use/scripts/lib/cube-build.test.mjs
@@ -0,0 +1,80 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { buildCube, paramsFromIntent } from "./cube-build.mjs";
+import { validateCube } from "./cube-validate.mjs";
+
+function rows(cube) {
+  return cube
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^[+-]?(?:\d|\.\d)/.test(line))
+    .map((line) => line.split(/\s+/).map(Number));
+}
+
+function rowAt(cubeRows, size, r, g, b) {
+  return cubeRows[(b * size + g) * size + r];
+}
+
+function luma(row) {
+  return row[0] * 0.2126 + row[1] * 0.7152 + row[2] * 0.0722;
+}
+
+test("all-zero params produce a near-identity LUT", () => {
+  const cube = buildCube({}, 3);
+  assert.equal(validateCube(cube).ok, true);
+  const parsed = rows(cube);
+  for (let b = 0; b < 3; b++) {
+    for (let g = 0; g < 3; g++) {
+      for (let r = 0; r < 3; r++) {
+        const row = rowAt(parsed, 3, r, g, b);
+        assert.ok(Math.abs(row[0] - r / 2) < 0.000001);
+        assert.ok(Math.abs(row[1] - g / 2) < 0.000001);
+        assert.ok(Math.abs(row[2] - b / 2) < 0.000001);
+      }
+    }
+  }
+});
+
+test("positive exposure increases unclipped output luma", () => {
+  const identity = rows(buildCube({}, 5));
+  const exposed = rows(buildCube({ exposure: 0.3 }, 5));
+  for (let i = 0; i < identity.length; i++) {
+    const before = luma(identity[i]);
+    if (before > 0.02 && before < 0.95) {
+      assert.ok(luma(exposed[i]) > before, `row ${i} should brighten`);
+    }
+  }
+});
+
+test("positive temperature warms mid-gray", () => {
+  const parsed = rows(buildCube({ temperature: 0.2 }, 3));
+  const mid = rowAt(parsed, 3, 1, 1, 1);
+  assert.ok(mid[0] > 0.5, "red channel should rise");
+  assert.ok(mid[2] < 0.5, "blue channel should fall");
+});
+
+test("positive contrast darkens shadows and brightens highlights", () => {
+  const parsed = rows(buildCube({ contrast: 0.3 }, 5));
+  const shadow = rowAt(parsed, 5, 1, 1, 1);
+  const highlight = rowAt(parsed, 5, 3, 3, 3);
+  assert.ok(luma(shadow) < 0.25, "below-mid gray should darken");
+  assert.ok(luma(highlight) > 0.75, "above-mid gray should brighten");
+});
+
+test("outputs validate at the default size and are deterministic", () => {
+  const params = { exposure: 0.15, contrast: 0.2, temperature: -0.1, saturation: 0.12 };
+  const a = buildCube(params);
+  const b = buildCube(params);
+  assert.equal(a, b);
+  assert.equal(validateCube(a).ok, true);
+  assert.equal(validateCube(a).size, 33);
+});
+
+test("paramsFromIntent declines zero-overlap prompts and maps technical words", () => {
+  assert.equal(paramsFromIntent("zqxv imaginary neutron look"), null);
+  assert.deepEqual(paramsFromIntent("warm cinematic"), {
+    temperature: 0.18,
+    contrast: 0.08,
+    saturation: 0.04,
+  });
+});
diff --git a/skills/media-use/scripts/lib/cube-validate.mjs b/skills/media-use/scripts/lib/cube-validate.mjs
new file mode 100644
index 000000000..4aef33ac0
--- /dev/null
+++ b/skills/media-use/scripts/lib/cube-validate.mjs
@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+// Standalone mirror of packages/core/src/colorLuts.ts. media-use cannot import
+// the TypeScript source at runtime, so cube-validate.test.mjs mirrors core
+// parser cases to catch drift in accepted .cube files before freezing them.
+
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_MAX_CUBE_LUT_SIZE = 64;
+
+const DEFAULT_DOMAIN_MIN = [0, 0, 0];
+const DEFAULT_DOMAIN_MAX = [1, 1, 1];
+
+class CubeValidateError extends Error {
+  constructor(message, lineNumber = null) {
+    super(lineNumber == null ? message : `${message} at line ${lineNumber}`);
+    this.name = "CubeValidateError";
+    this.lineNumber = lineNumber;
+  }
+}
+
+function stripComment(line) {
+  let inQuote = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') inQuote = !inQuote;
+    if (char === "#" && !inQuote) return line.slice(0, i);
+  }
+  return line;
+}
+
+function parseFiniteNumber(value, lineNumber) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new CubeValidateError(`Invalid number "${value}"`, lineNumber);
+  }
+  return parsed;
+}
+
+function parseVec3(parts, keyword, lineNumber) {
+  if (parts.length !== 3) {
+    throw new CubeValidateError(`${keyword} expects three numbers`, lineNumber);
+  }
+  return [
+    parseFiniteNumber(parts[0], lineNumber),
+    parseFiniteNumber(parts[1], lineNumber),
+    parseFiniteNumber(parts[2], lineNumber),
+  ];
+}
+
+function parseSize(value, keyword, lineNumber) {
+  if (!value) throw new CubeValidateError(`${keyword} expects a size`, lineNumber);
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 2) {
+    throw new CubeValidateError(`${keyword} must be an integer greater than 1`, lineNumber);
+  }
+  return parsed;
+}
+
+function validateDomain(domainMin, domainMax) {
+  if (
+    domainMax[0] <= domainMin[0] ||
+    domainMax[1] <= domainMin[1] ||
+    domainMax[2] <= domainMin[2]
+  ) {
+    throw new CubeValidateError("DOMAIN_MAX values must be greater than DOMAIN_MIN values");
+  }
+}
+
+function isNumericDataLine(token) {
+  return /^[+-]?(?:\d|\.\d)/.test(token);
+}
+
+function parseCube(input, options = {}) {
+  const maxSize = options.maxSize ?? DEFAULT_MAX_CUBE_LUT_SIZE;
+  let domainMin = DEFAULT_DOMAIN_MIN;
+  let domainMax = DEFAULT_DOMAIN_MAX;
+  let lut1dSize = null;
+  let lut3dSize = null;
+  let rows = 0;
+
+  const lines = String(input)
+    .replace(/^\uFEFF/, "")
+    .split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const lineNumber = i + 1;
+    const line = stripComment(lines[i] ?? "").trim();
+    if (!line) continue;
+    const parts = line.split(/\s+/);
+    const keyword = (parts[0] ?? "").toUpperCase();
+    const rest = parts.slice(1);
+
+    if (keyword === "TITLE") continue;
+    if (keyword === "DOMAIN_MIN") {
+      domainMin = parseVec3(rest, keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "DOMAIN_MAX") {
+      domainMax = parseVec3(rest, keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "LUT_3D_INPUT_RANGE") {
+      if (rest.length !== 2) {
+        throw new CubeValidateError(`${keyword} expects two numbers`, lineNumber);
+      }
+      const min = parseFiniteNumber(rest[0], lineNumber);
+      const max = parseFiniteNumber(rest[1], lineNumber);
+      if (max <= min) {
+        throw new CubeValidateError("LUT_3D_INPUT_RANGE max must exceed min", lineNumber);
+      }
+      domainMin = [min, min, min];
+      domainMax = [max, max, max];
+      continue;
+    }
+    if (keyword === "LUT_1D_SIZE") {
+      lut1dSize = parseSize(rest[0], keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "LUT_3D_SIZE") {
+      lut3dSize = parseSize(rest[0], keyword, lineNumber);
+      if (lut3dSize > maxSize) {
+        throw new CubeValidateError(`LUT_3D_SIZE ${lut3dSize} exceeds max ${maxSize}`, lineNumber);
+      }
+      continue;
+    }
+
+    if (!isNumericDataLine(keyword)) {
+      if (keyword.startsWith("LUT_")) {
+        throw new CubeValidateError(`Unsupported cube keyword ${keyword}`, lineNumber);
+      }
+      continue;
+    }
+    if (!lut3dSize) {
+      if (lut1dSize) {
+        throw new CubeValidateError("1D cube LUTs are not supported yet", lineNumber);
+      }
+      throw new CubeValidateError("LUT data appears before LUT_3D_SIZE", lineNumber);
+    }
+    if (parts.length !== 3) {
+      throw new CubeValidateError("LUT data rows must contain three numbers", lineNumber);
+    }
+    parseFiniteNumber(parts[0], lineNumber);
+    parseFiniteNumber(parts[1], lineNumber);
+    parseFiniteNumber(parts[2], lineNumber);
+    rows++;
+  }
+
+  if (lut1dSize && lut3dSize) {
+    throw new CubeValidateError("Mixed 1D and 3D cube LUTs are not supported yet");
+  }
+  if (!lut3dSize) {
+    if (lut1dSize) throw new CubeValidateError("1D cube LUTs are not supported yet");
+    throw new CubeValidateError("Missing LUT_3D_SIZE");
+  }
+  validateDomain(domainMin, domainMax);
+
+  const expectedRows = lut3dSize * lut3dSize * lut3dSize;
+  if (rows !== expectedRows) {
+    throw new CubeValidateError(
+      `Expected ${expectedRows} LUT rows for size ${lut3dSize}, found ${rows}`,
+    );
+  }
+
+  return { size: lut3dSize };
+}
+
+export function validateCube(input, options = {}) {
+  try {
+    const parsed = parseCube(input, options);
+    return { ok: true, size: parsed.size };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+export function validateCubeFile(filePath, options = {}) {
+  return validateCube(readFileSync(filePath, "utf8"), options);
+}
+
+function main(argv) {
+  const file = argv[2];
+  if (!file) {
+    console.error("usage: cube-validate.mjs <file.cube>");
+    process.exit(2);
+  }
+  const result = validateCubeFile(file);
+  if (!result.ok) {
+    console.error(`error: ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`ok: LUT_3D_SIZE ${result.size}`);
+}
+
+if (process.argv[1] && resolvePath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv);
+}
diff --git a/skills/media-use/scripts/lib/cube-validate.test.mjs b/skills/media-use/scripts/lib/cube-validate.test.mjs
new file mode 100644
index 000000000..2465bfbcd
--- /dev/null
+++ b/skills/media-use/scripts/lib/cube-validate.test.mjs
@@ -0,0 +1,125 @@
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { validateCube } from "./cube-validate.mjs";
+
+const IDENTITY_2 = `
+# comment
+TITLE "Identity 2"
+DOMAIN_MIN 0 0 0
+DOMAIN_MAX 1 1 1
+LUT_3D_SIZE 2
+0 0 0
+1 0 0
+0 1 0
+1 1 0
+0 0 1
+1 0 1
+0 1 1
+1 1 1
+`;
+
+test("accepts a valid minimal 3D cube LUT", () => {
+  const result = validateCube(IDENTITY_2);
+  assert.deepEqual(result, { ok: true, size: 2 });
+});
+
+test("rejects oversize LUTs with the core parser message", () => {
+  const result = validateCube("LUT_3D_SIZE 65", { maxSize: 64 });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /LUT_3D_SIZE 65 exceeds max 64/);
+});
+
+test("rejects data rows before LUT_3D_SIZE", () => {
+  const result = validateCube("0 0 0\nLUT_3D_SIZE 2");
+  assert.equal(result.ok, false);
+  assert.match(result.error, /LUT data appears before LUT_3D_SIZE/);
+});
+
+test("rejects missing LUT_3D_SIZE", () => {
+  const result = validateCube('TITLE "No Size"');
+  assert.equal(result.ok, false);
+  assert.match(result.error, /Missing LUT_3D_SIZE/);
+});
+
+test("rejects row count mismatches with the core parser message", () => {
+  const result = validateCube("LUT_3D_SIZE 2\n0 0 0");
+  assert.equal(result.ok, false);
+  assert.match(result.error, /Expected 8 LUT rows/);
+});
+
+test("rejects inverted domains", () => {
+  const result = validateCube(`
+    DOMAIN_MIN 0 0 0
+    DOMAIN_MAX 1 0 1
+    LUT_3D_SIZE 2
+    0 0 0
+    1 0 0
+    0 1 0
+    1 1 0
+    0 0 1
+    1 0 1
+    0 1 1
+    1 1 1
+  `);
+  assert.equal(result.ok, false);
+  assert.match(result.error, /DOMAIN_MAX values must be greater than DOMAIN_MIN values/);
+});
+
+test("rejects unsupported 1D and mixed cube LUTs", () => {
+  const oneD = validateCube("LUT_1D_SIZE 2\n0 0 0\n1 1 1");
+  assert.equal(oneD.ok, false);
+  assert.match(oneD.error, /1D cube LUTs are not supported yet/);
+
+  const mixed = validateCube(`
+    LUT_1D_SIZE 2
+    LUT_3D_SIZE 2
+    0 0 0
+    1 0 0
+    0 1 0
+    1 1 0
+    0 0 1
+    1 0 1
+    0 1 1
+    1 1 1
+  `);
+  assert.equal(mixed.ok, false);
+  assert.match(mixed.error, /Mixed 1D and 3D cube LUTs are not supported yet/);
+});
+
+test("CLI exits zero for valid files and non-zero for invalid files", () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-cube-validate-"));
+  try {
+    const valid = join(dir, "valid.cube");
+    const invalid = join(dir, "invalid.cube");
+    writeFileSync(valid, IDENTITY_2);
+    writeFileSync(invalid, "LUT_3D_SIZE 65");
+
+    const out = execFileSync(
+      process.execPath,
+      [new URL("./cube-validate.mjs", import.meta.url).pathname, valid],
+      {
+        encoding: "utf8",
+      },
+    );
+    assert.match(out, /ok: LUT_3D_SIZE 2/);
+
+    assert.throws(
+      () =>
+        execFileSync(
+          process.execPath,
+          [new URL("./cube-validate.mjs", import.meta.url).pathname, invalid],
+          {
+            encoding: "utf8",
+            stdio: "pipe",
+          },
+        ),
+      (err) => err.status === 1 && String(err.stderr).includes("exceeds max 64"),
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/skills/media-use/scripts/lib/grade-analyzer.mjs b/skills/media-use/scripts/lib/grade-analyzer.mjs
new file mode 100644
index 000000000..054e5119b
--- /dev/null
+++ b/skills/media-use/scripts/lib/grade-analyzer.mjs
@@ -0,0 +1,165 @@
+import { execFileSync } from "node:child_process";
+import { basename, extname } from "node:path";
+
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tif", ".tiff"]);
+const SAMPLE_FRAMES = 5;
+// A long HD clip on slow storage can exceed the default 15s signalstats window;
+// override without a code change via HYPERFRAMES_ANALYZE_TIMEOUT_MS.
+const SIGNALSTATS_TIMEOUT_MS = Number(process.env.HYPERFRAMES_ANALYZE_TIMEOUT_MS) || 15000;
+
+const ADJUST_LIMITS = {
+  exposure: { min: -2, max: 2 },
+  contrast: { min: -1, max: 1 },
+  highlights: { min: -1, max: 1 },
+  shadows: { min: -1, max: 1 },
+  whites: { min: -1, max: 1 },
+  blacks: { min: -1, max: 1 },
+  temperature: { min: -1, max: 1 },
+  tint: { min: -1, max: 1 },
+  vibrance: { min: -1, max: 1 },
+  saturation: { min: -1, max: 1 },
+};
+
+function clamp(value, key) {
+  const limit = ADJUST_LIMITS[key];
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(limit.max, Math.max(limit.min, value));
+}
+
+function round(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function avg(values) {
+  if (values.length === 0) return 0;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function probeDuration(mediaPath) {
+  try {
+    const raw = execFileSync(
+      "ffprobe",
+      ["-v", "quiet", "-print_format", "json", "-show_format", mediaPath],
+      { encoding: "utf8", timeout: 5000 },
+    );
+    const parsed = JSON.parse(raw);
+    const duration = Number(parsed.format?.duration);
+    return Number.isFinite(duration) && duration > 0 ? duration : null;
+  } catch {
+    return null;
+  }
+}
+
+function filterFor(mediaPath) {
+  const ext = extname(mediaPath).toLowerCase();
+  if (IMAGE_EXT.has(ext)) return "signalstats,metadata=print:file=-";
+  const duration = probeDuration(mediaPath);
+  if (!duration || duration <= 1) return "signalstats,metadata=print:file=-";
+  const fps = Math.max(0.1, Math.min(2, SAMPLE_FRAMES / duration));
+  return `fps=${fps.toFixed(4)},signalstats,metadata=print:file=-`;
+}
+
+function parseSignalStats(raw) {
+  const frames = [];
+  let current = null;
+  for (const line of String(raw).split(/\r?\n/)) {
+    const frameMatch = line.match(/^frame:/);
+    if (frameMatch) {
+      if (current) frames.push(current);
+      current = {};
+      continue;
+    }
+    const match = line.match(/lavfi\.signalstats\.([A-Z]+)=([+-]?(?:\d+(?:\.\d+)?|\.\d+))/);
+    if (!match) continue;
+    if (!current) current = {};
+    current[match[1]] = Number(match[2]);
+  }
+  if (current) frames.push(current);
+  const complete = frames.filter(
+    (frame) =>
+      Number.isFinite(frame.YMIN) &&
+      Number.isFinite(frame.YMAX) &&
+      Number.isFinite(frame.YAVG) &&
+      Number.isFinite(frame.UAVG) &&
+      Number.isFinite(frame.VAVG),
+  );
+  if (complete.length === 0) {
+    throw new Error("no signalstats frames found");
+  }
+  return {
+    frames: complete.length,
+    yMin: Math.min(...complete.map((frame) => frame.YMIN)),
+    yMax: Math.max(...complete.map((frame) => frame.YMAX)),
+    yAvg: avg(complete.map((frame) => frame.YAVG)),
+    uAvg: avg(complete.map((frame) => frame.UAVG)),
+    vAvg: avg(complete.map((frame) => frame.VAVG)),
+  };
+}
+
+export function statsToAdjust(stats) {
+  const yMin = Number(stats.yMin);
+  const yMax = Number(stats.yMax);
+  const yAvg = Number(stats.yAvg);
+  const uAvg = Number(stats.uAvg);
+  const vAvg = Number(stats.vAvg);
+  const spread = (yMax - yMin) / 255;
+  const normalizedAvg = yAvg / 255;
+  const exposure = clamp((0.45 - normalizedAvg) * 1.8, "exposure");
+  const contrast = clamp((0.42 - spread) * 0.9, "contrast");
+  const whites =
+    yMax > 230 ? clamp(-((yMax - 230) / 40 + Math.max(0, normalizedAvg - 0.74)), "whites") : 0;
+  const blacks = yMin < 12 ? clamp((12 - yMin) / 80, "blacks") : 0;
+  const chromaWarmth = (vAvg - 128 + (128 - uAvg)) / 128;
+  const temperature = clamp(-chromaWarmth * 0.7, "temperature");
+  const tint = clamp(-(uAvg - 128 + (vAvg - 128)) / 256, "tint");
+
+  return {
+    adjust: {
+      exposure: round(exposure),
+      contrast: round(contrast),
+      blacks: round(blacks),
+      whites: round(whites),
+      temperature: round(temperature),
+      tint: round(tint),
+    },
+    measured: {
+      frames: Number(stats.frames ?? 1),
+      yMin: round(yMin),
+      yMax: round(yMax),
+      yAvg: round(yAvg),
+      uAvg: round(uAvg),
+      vAvg: round(vAvg),
+    },
+  };
+}
+
+export function analyzeMediaGrade(mediaPath) {
+  try {
+    const raw = execFileSync(
+      "ffmpeg",
+      [
+        "-hide_banner",
+        "-nostdin",
+        "-v",
+        "error",
+        "-i",
+        mediaPath,
+        "-vf",
+        filterFor(mediaPath),
+        "-frames:v",
+        String(SAMPLE_FRAMES),
+        "-f",
+        "null",
+        "-",
+      ],
+      { encoding: "utf8", timeout: SIGNALSTATS_TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"] },
+    );
+    return statsToAdjust(parseSignalStats(raw));
+  } catch (err) {
+    throw new Error(`grade analysis failed for ${mediaPath}: ${err.message}`);
+  }
+}
+
+export function formatMeasuredNote(mediaPath, measured) {
+  return `media-use: measured ${basename(mediaPath)}: frames=${measured.frames}, YMIN=${measured.yMin}, YMAX=${measured.yMax}, YAVG=${measured.yAvg}, UAVG=${measured.uAvg}, VAVG=${measured.vAvg}; adjust is a starting suggestion`;
+}
diff --git a/skills/media-use/scripts/lib/grade-analyzer.test.mjs b/skills/media-use/scripts/lib/grade-analyzer.test.mjs
new file mode 100644
index 000000000..86e6632a6
--- /dev/null
+++ b/skills/media-use/scripts/lib/grade-analyzer.test.mjs
@@ -0,0 +1,155 @@
+import { strict as assert } from "node:assert";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { analyzeMediaGrade, formatMeasuredNote, statsToAdjust } from "./grade-analyzer.mjs";
+
+// The "Test: skills" CI job runs bare `node --test` with no ffmpeg on PATH (by
+// design — skills tests are meant to be node-builtin-only). Tests that shell to
+// ffmpeg skip there and run wherever ffmpeg is present (locally, dev).
+const FFMPEG_SKIP =
+  spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0
+    ? false
+    : "ffmpeg not on PATH";
+
+const ADJUST_LIMITS = {
+  exposure: { min: -2, max: 2 },
+  contrast: { min: -1, max: 1 },
+  highlights: { min: -1, max: 1 },
+  shadows: { min: -1, max: 1 },
+  whites: { min: -1, max: 1 },
+  blacks: { min: -1, max: 1 },
+  temperature: { min: -1, max: 1 },
+  tint: { min: -1, max: 1 },
+  vibrance: { min: -1, max: 1 },
+  saturation: { min: -1, max: 1 },
+};
+
+function makeFrame(dir, name, color) {
+  const out = join(dir, name);
+  execFileSync(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-f",
+      "lavfi",
+      "-i",
+      `color=c=${color}:s=64x64`,
+      "-frames:v",
+      "1",
+      "-y",
+      out,
+    ],
+    { stdio: "pipe" },
+  );
+  return out;
+}
+
+function assertWithinLimits(adjust) {
+  for (const [key, value] of Object.entries(adjust)) {
+    const limit = ADJUST_LIMITS[key];
+    assert.ok(limit, `unexpected adjust key ${key}`);
+    assert.ok(value >= limit.min && value <= limit.max, `${key} out of range: ${value}`);
+  }
+}
+
+test("under-exposed synthetic frame suggests positive exposure", { skip: FFMPEG_SKIP }, () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-grade-under-"));
+  try {
+    const file = makeFrame(dir, "under.png", "0x202020");
+    const { adjust, measured } = analyzeMediaGrade(file);
+    assert.ok(measured.frames >= 1);
+    assert.ok(adjust.exposure > 0, `expected positive exposure, got ${adjust.exposure}`);
+    assertWithinLimits(adjust);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("over-exposed synthetic frame pulls exposure and whites down", { skip: FFMPEG_SKIP }, () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-grade-over-"));
+  try {
+    const file = makeFrame(dir, "over.png", "white");
+    const { adjust } = analyzeMediaGrade(file);
+    assert.ok(adjust.exposure < 0, `expected negative exposure, got ${adjust.exposure}`);
+    assert.ok(adjust.whites < 0, `expected negative whites, got ${adjust.whites}`);
+    assertWithinLimits(adjust);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test(
+  "warm-cast synthetic frame suggests negative temperature correction",
+  { skip: FFMPEG_SKIP },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "mu-grade-warm-"));
+    try {
+      const file = makeFrame(dir, "warm.png", "orange");
+      const { adjust } = analyzeMediaGrade(file);
+      assert.ok(adjust.temperature < 0, `expected cooling correction, got ${adjust.temperature}`);
+      assertWithinLimits(adjust);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+test("low-spread stats suggest positive contrast", () => {
+  const { adjust } = statsToAdjust({
+    frames: 1,
+    yMin: 104,
+    yMax: 116,
+    yAvg: 110,
+    uAvg: 128,
+    vAvg: 128,
+  });
+  assert.ok(adjust.contrast > 0, `expected positive contrast, got ${adjust.contrast}`);
+  assertWithinLimits(adjust);
+});
+
+test("malformed media fails cleanly", () => {
+  assert.throws(
+    () => analyzeMediaGrade(join(tmpdir(), "does-not-exist.png")),
+    /grade analysis failed/,
+  );
+});
+
+test(
+  "media path with shell metacharacters is passed as argv, not a shell string",
+  {
+    skip: FFMPEG_SKIP,
+  },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "mu-grade-shell-"));
+    const sentinel = join(process.cwd(), "mu-grade-shell-sentinel.png");
+    try {
+      if (existsSync(sentinel)) unlinkSync(sentinel);
+      const file = makeFrame(dir, "frame; touch mu-grade-shell-sentinel.png", "orange");
+      const result = analyzeMediaGrade(file);
+      assert.ok(result.measured.frames >= 1);
+      assert.equal(existsSync(sentinel), false);
+    } finally {
+      if (existsSync(sentinel)) unlinkSync(sentinel);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+test("measured note is a stderr-safe single-line summary", () => {
+  const note = formatMeasuredNote("/tmp/frame.png", {
+    frames: 1,
+    yMin: 10,
+    yMax: 240,
+    yAvg: 80,
+    uAvg: 120,
+    vAvg: 140,
+  });
+  assert.match(note, /^media-use: measured /);
+  assert.match(note, /YAVG=80/);
+  assert.equal(note.includes("\n"), false);
+});
diff --git a/skills/media-use/scripts/lib/lut-preset-provider.mjs b/skills/media-use/scripts/lib/lut-preset-provider.mjs
new file mode 100644
index 000000000..28b6d840f
--- /dev/null
+++ b/skills/media-use/scripts/lib/lut-preset-provider.mjs
@@ -0,0 +1,232 @@
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { allocateId } from "./manifest.mjs";
+import { freezeUrl } from "./freeze.mjs";
+import { tokenOverlap } from "./match.mjs";
+import { buildCube } from "./cube-build.mjs";
+import { validateCube, validateCubeFile } from "./cube-validate.mjs";
+
+const SKILL_DIR = join(import.meta.dirname, "..", "..");
+const LUT_DIR = join(SKILL_DIR, "luts");
+const LUT_INDEX = join(LUT_DIR, "index.json");
+export const LIBRARY_LUT_OFFLINE_CODE = "MEDIA_USE_LIBRARY_LUT_OFFLINE";
+
+// Mirrored from packages/core/src/colorGrading.ts HfColorGradingPresetId.
+// Keep this list in lockstep with the core runtime contract.
+export const CORE_PRESET_IDS = [
+  "neutral",
+  "natural-lift",
+  "fresh-pop",
+  "warm-daylight",
+  "clean-studio",
+  "skin-soft",
+  "food-pop",
+  "night-lift",
+  "muted-editorial",
+  "vintage-wash",
+  "mono-clean",
+  "mono-fade",
+  "warm-clean",
+  "cool-clean",
+  "soft-boost",
+  "bright-pop",
+  "deep-contrast",
+];
+
+const PRESET_SYNONYMS = {
+  neutral: ["neutral", "identity", "none", "ungraded", "natural base"],
+  "natural-lift": ["natural lift", "natural light", "gentle lift", "soft natural"],
+  "fresh-pop": ["fresh pop", "fresh", "bright fresh", "clean colorful"],
+  "warm-daylight": [
+    "warm daylight",
+    "warm natural light",
+    "golden daylight",
+    "sunlit",
+    "warm sunny",
+  ],
+  "clean-studio": ["clean studio", "studio clean", "cool studio", "product studio"],
+  "skin-soft": ["skin soft", "soft skin", "portrait soft", "beauty skin"],
+  "food-pop": ["food pop", "food vibrant", "appetizing", "restaurant color"],
+  "night-lift": ["night lift", "night", "low light lift", "city night"],
+  "muted-editorial": ["muted editorial", "editorial muted", "magazine muted"],
+  "vintage-wash": ["vintage wash", "vintage", "retro wash", "aged film"],
+  "mono-clean": ["mono clean", "black white clean", "monochrome clean"],
+  "mono-fade": ["mono fade", "black white fade", "faded monochrome"],
+  "warm-clean": ["warm clean", "clean warm", "warm product"],
+  "cool-clean": ["cool clean", "clean cool", "cool crisp"],
+  "soft-boost": ["soft boost", "soft bright", "gentle boost"],
+  "bright-pop": ["bright pop", "bright punchy", "vivid bright"],
+  "deep-contrast": ["deep contrast", "high contrast punchy", "punchy contrast", "bold contrast"],
+};
+
+function presetCandidates() {
+  return CORE_PRESET_IDS.map((id) => ({
+    kind: "preset",
+    preset: id,
+    synonyms: PRESET_SYNONYMS[id] ?? [],
+    text: [id, ...(PRESET_SYNONYMS[id] ?? [])].join(" "),
+  }));
+}
+
+export function readBundledLutIndex() {
+  if (!existsSync(LUT_INDEX)) return [];
+  const parsed = JSON.parse(readFileSync(LUT_INDEX, "utf8"));
+  const entries = Array.isArray(parsed) ? parsed : parsed.looks;
+  if (!Array.isArray(entries)) return [];
+  return entries.map((entry) => {
+    const params =
+      entry.params && typeof entry.params === "object" && !Array.isArray(entry.params)
+        ? entry.params
+        : null;
+    const url = typeof entry.url === "string" && entry.url.trim() ? entry.url.trim() : null;
+    return {
+      id: String(entry.id),
+      description: String(entry.description ?? entry.id),
+      tags: Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+      intensity: Number.isFinite(Number(entry.intensity)) ? Number(entry.intensity) : 1,
+      ...(params && { params }),
+      ...(url && { url }),
+    };
+  });
+}
+
+function libraryCandidates() {
+  return readBundledLutIndex().map((entry) => ({
+    kind: "library",
+    ...entry,
+    text: [entry.id, entry.description, ...entry.tags].join(" "),
+  }));
+}
+
+export function matchColorLook(intent) {
+  const normalized = String(intent ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ");
+  for (const candidate of presetCandidates()) {
+    if (candidate.preset === normalized) {
+      return { kind: "preset", preset: candidate.preset, score: 99 };
+    }
+  }
+
+  const candidates = [...presetCandidates(), ...libraryCandidates()]
+    .map((candidate, index) => ({
+      ...candidate,
+      index,
+      score: tokenOverlap(intent, candidate.text),
+    }))
+    .filter((candidate) => candidate.score >= 2)
+    .sort((a, b) => b.score - a.score || a.index - b.index);
+
+  if (candidates.length === 0) return null;
+  const best = candidates[0];
+  if (best.kind === "preset") {
+    return { kind: "preset", preset: best.preset, score: best.score };
+  }
+  return {
+    kind: "library",
+    id: best.id,
+    description: best.description,
+    tags: best.tags,
+    intensity: best.intensity,
+    ...(best.params && { params: best.params }),
+    ...(best.url && { url: best.url }),
+    score: best.score,
+  };
+}
+
+export function isLibraryLutOfflineMiss(err) {
+  return err?.code === LIBRARY_LUT_OFFLINE_CODE;
+}
+
+function libraryRecord(match, { id, localPath, fullPath, via }) {
+  return {
+    id,
+    localPath,
+    fullPath,
+    lut: { src: localPath, intensity: match.intensity },
+    source: "library",
+    description: match.description,
+    metadata: {
+      provider: "cube_lut.library",
+      provenance: {
+        look_id: match.id,
+        tags: match.tags,
+        via,
+      },
+    },
+  };
+}
+
+function assertValidCubeText(cube, label) {
+  const check = validateCube(cube);
+  if (!check.ok) throw new Error(`${label}: ${check.error}`);
+}
+
+function assertValidCubeFile(path, label) {
+  const check = validateCubeFile(path);
+  if (!check.ok) throw new Error(`${label}: ${check.error}`);
+}
+
+function offlineLibraryMiss(match) {
+  const err = new Error(`library LUT "${match.id}" is CDN-only and --local-only is set`);
+  err.code = LIBRARY_LUT_OFFLINE_CODE;
+  return err;
+}
+
+export async function freezeLibraryLut(match, { projectDir, type, localOnly = false }) {
+  if (!match || match.kind !== "library") {
+    throw new Error("freezeLibraryLut requires a library match");
+  }
+
+  // Prefer the CDN url so looks download on-demand (like bgm/image). Fall back
+  // to deterministic buildCube params when offline (--local-only) or if the
+  // download/validation fails, so resolution is never blocked on the network.
+  if (match.url && !localOnly) {
+    const { id, localPath } = allocateId(projectDir, type, ".cube");
+    const fullPath = join(projectDir, localPath);
+    const tmpPath = `${fullPath}.tmp`;
+    try {
+      // Download + validate at a .tmp path, then atomically rename. A crash
+      // (SIGKILL/OOM) between write and validate can't orphan an invalid .cube
+      // at the final path — only a validated cube is ever renamed into place.
+      await freezeUrl(match.url, tmpPath);
+      assertValidCubeFile(tmpPath, `downloaded library LUT ${match.id} failed validation`);
+      renameSync(tmpPath, fullPath);
+      return libraryRecord(match, { id, localPath, fullPath, via: "url" });
+    } catch (err) {
+      rmSync(tmpPath, { force: true });
+      if (!match.params) {
+        throw new Error(`failed to freeze library LUT ${match.id}: ${err.message}`);
+      }
+      // else: fall through to the params fallback below
+    }
+  }
+
+  if (match.params) {
+    const { id, localPath } = allocateId(projectDir, type, ".cube");
+    const fullPath = join(projectDir, localPath);
+    const tmpPath = `${fullPath}.tmp`;
+    try {
+      const cube = buildCube(match.params);
+      assertValidCubeText(cube, `invalid library LUT ${match.id}`);
+      // Write + validate at .tmp, then atomic rename — same no-orphan guarantee
+      // as the url path above.
+      writeFileSync(tmpPath, cube);
+      assertValidCubeFile(tmpPath, `invalid frozen LUT ${localPath}`);
+      renameSync(tmpPath, fullPath);
+    } catch (err) {
+      rmSync(tmpPath, { force: true });
+      throw err;
+    }
+    return libraryRecord(match, {
+      id,
+      localPath,
+      fullPath,
+      via: match.url ? "params-fallback" : "params",
+    });
+  }
+
+  if (match.url) throw offlineLibraryMiss(match); // url-only entry, offline
+  throw new Error(`misconfigured library LUT "${match.id}": expected params or url`);
+}
diff --git a/skills/media-use/scripts/lib/lut-preset-provider.test.mjs b/skills/media-use/scripts/lib/lut-preset-provider.test.mjs
new file mode 100644
index 000000000..2cfe241cd
--- /dev/null
+++ b/skills/media-use/scripts/lib/lut-preset-provider.test.mjs
@@ -0,0 +1,130 @@
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import {
+  CORE_PRESET_IDS,
+  LIBRARY_LUT_OFFLINE_CODE,
+  freezeLibraryLut,
+  matchColorLook,
+  readBundledLutIndex,
+} from "./lut-preset-provider.mjs";
+import { buildCube } from "./cube-build.mjs";
+import { validateCube, validateCubeFile } from "./cube-validate.mjs";
+
+const REPO_ROOT = join(import.meta.dirname, "..", "..", "..", "..");
+
+function corePresetIdsFromSource() {
+  const src = readFileSync(join(REPO_ROOT, "packages/core/src/colorGrading.ts"), "utf8");
+  const match = src.match(/export type HfColorGradingPresetId =([\s\S]*?);/);
+  assert.ok(match, "core preset union should be readable");
+  return [...match[1].matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+}
+
+test("warm daylight and warm natural light resolve to the core warm-daylight preset", () => {
+  assert.deepEqual(matchColorLook("warm daylight"), {
+    kind: "preset",
+    preset: "warm-daylight",
+    score: 2,
+  });
+  assert.equal(matchColorLook("warm natural light").preset, "warm-daylight");
+});
+
+test("high contrast punchy resolves to deep-contrast", () => {
+  assert.equal(matchColorLook("high contrast punchy").preset, "deep-contrast");
+});
+
+test("library look freezes a validated cube from params offline (--local-only)", async () => {
+  const projectDir = mkdtempSync(join(tmpdir(), "mu-lut-provider-"));
+  try {
+    const match = matchColorLook("teal orange blockbuster");
+    assert.equal(match.kind, "library");
+    // localOnly forces the deterministic params path (no network); online, the
+    // same look downloads its .cube from the CDN url (via "url").
+    const frozen = await freezeLibraryLut(match, { projectDir, type: "grade", localOnly: true });
+    assert.match(frozen.localPath, /^\.media\/luts\/grade_001\.cube$/);
+    assert.ok(existsSync(join(projectDir, frozen.localPath)));
+    assert.equal(validateCubeFile(join(projectDir, frozen.localPath)).ok, true);
+    assert.equal(frozen.lut.src, frozen.localPath);
+    assert.equal(frozen.metadata.provenance.via, "params-fallback");
+  } finally {
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+test("preset IDs stay in sync with packages/core/src/colorGrading.ts", () => {
+  assert.deepEqual(CORE_PRESET_IDS, corePresetIdsFromSource());
+  for (const id of CORE_PRESET_IDS) {
+    const match = matchColorLook(id);
+    assert.equal(match.kind, "preset");
+    assert.equal(match.preset, id);
+  }
+});
+
+test("zero-overlap intent returns no preset or library match", () => {
+  assert.equal(matchColorLook("zqxv imaginary neutron look"), null);
+});
+
+test("bundled LUT index entries resolve from params or url", () => {
+  for (const entry of readBundledLutIndex()) {
+    assert.ok(entry.id);
+    assert.ok(entry.description);
+    assert.ok(entry.params || entry.url, `${entry.id} should define params or url`);
+    if (entry.params) {
+      assert.equal(typeof entry.params, "object");
+      assert.equal(validateCube(buildCube(entry.params)).ok, true, `${entry.id} params validate`);
+    }
+    if (entry.url) assert.equal(typeof entry.url, "string");
+  }
+});
+
+test("url library entries respect localOnly and freeze through fetch", async () => {
+  const projectDir = mkdtempSync(join(tmpdir(), "mu-lut-url-provider-"));
+  const match = {
+    kind: "library",
+    id: "cdn-look",
+    description: "CDN-hosted look",
+    tags: ["cdn"],
+    intensity: 0.7,
+    url: "https://example.invalid/look.cube",
+  };
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  try {
+    globalThis.fetch = async () => {
+      fetchCalls++;
+      throw new Error("network should be skipped under localOnly");
+    };
+    await assert.rejects(
+      freezeLibraryLut(match, { projectDir, type: "lut", localOnly: true }),
+      (err) => {
+        assert.equal(err.code, LIBRARY_LUT_OFFLINE_CODE);
+        assert.match(err.message, /--local-only/);
+        return true;
+      },
+    );
+    assert.equal(fetchCalls, 0);
+
+    const cube = buildCube({ contrast: 0.1 });
+    const body = Buffer.from(cube);
+    globalThis.fetch = async (url) => {
+      fetchCalls++;
+      assert.equal(url, match.url);
+      return {
+        ok: true,
+        headers: { get: () => String(body.length) },
+        body: [body],
+      };
+    };
+
+    const frozen = await freezeLibraryLut(match, { projectDir, type: "lut" });
+    assert.equal(fetchCalls, 1);
+    assert.match(frozen.localPath, /^\.media\/luts\/lut_001\.cube$/);
+    assert.equal(validateCubeFile(join(projectDir, frozen.localPath)).ok, true);
+    assert.equal(frozen.metadata.provenance.via, "url");
+  } finally {
+    globalThis.fetch = originalFetch;
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});
diff --git a/skills/media-use/scripts/lib/manifest.mjs b/skills/media-use/scripts/lib/manifest.mjs
index 70ac936dd..f5aea62b5 100644
--- a/skills/media-use/scripts/lib/manifest.mjs
+++ b/skills/media-use/scripts/lib/manifest.mjs
@@ -24,6 +24,8 @@ const TYPE_DIRS = {
   logo: "images",
   brand: "images",
   video: "video",
+  grade: "luts",
+  lut: "luts",
 };
 
 export function mediaDir(projectDir) {
diff --git a/skills/media-use/scripts/lib/manifest.test.mjs b/skills/media-use/scripts/lib/manifest.test.mjs
index 6c6f56a35..7ed343591 100644
--- a/skills/media-use/scripts/lib/manifest.test.mjs
+++ b/skills/media-use/scripts/lib/manifest.test.mjs
@@ -13,6 +13,7 @@ import {
   manifestPath,
   mediaDir,
   typeDirPath,
+  typeSubdir,
 } from "./manifest.mjs";
 import { regenerateIndex, generateIndexContent } from "./index-gen.mjs";
 import {
@@ -81,6 +82,17 @@ function runTests() {
     cleanup();
   });
 
+  test("lut and grade artifacts use the shared .media/luts subdir", () => {
+    assert.equal(typeSubdir("lut"), "luts");
+    assert.equal(typeSubdir("grade"), "luts");
+
+    setup();
+    const allocated = allocateId(tmp, "lut", ".cube");
+    assert.equal(allocated.localPath, ".media/luts/lut_001.cube");
+    assert.ok(existsSync(join(tmp, allocated.localPath)));
+    cleanup();
+  });
+
   test("appendRecord appends multiple records", () => {
     setup();
     appendRecord(tmp, makeRecord({ id: "bgm_001" }));
diff --git a/skills/media-use/scripts/lib/registry.mjs b/skills/media-use/scripts/lib/registry.mjs
index 207b5a397..7cba32d7e 100644
--- a/skills/media-use/scripts/lib/registry.mjs
+++ b/skills/media-use/scripts/lib/registry.mjs
@@ -77,6 +77,15 @@ const REGISTRY = {
     // Local design spec, not heygen — reads frame.md / design.md tokens.
     A("design_spec", { search: brandProvider.search }),
   ],
+  grade: [
+    // Local deterministic cascade handled by resolve.mjs so grade records can
+    // carry an inline block as well as an optional frozen .cube file.
+    A("color_grade.local", { search: async () => null, generate: async () => null }),
+  ],
+  lut: [
+    // Lower-level local LUT generation/freezing path handled by resolve.mjs.
+    A("cube_lut.local", { search: async () => null, generate: async () => null }),
+  ],
 };
 
 function listFor(type) {
diff --git a/skills/media-use/scripts/lib/registry.test.mjs b/skills/media-use/scripts/lib/registry.test.mjs
index d7b8f5e4b..b8b63ca6a 100644
--- a/skills/media-use/scripts/lib/registry.test.mjs
+++ b/skills/media-use/scripts/lib/registry.test.mjs
@@ -6,7 +6,7 @@ import { getProviders, getProvider, listTypes, runProviders, runCapability } fro
 
 test("listTypes exposes the v2 media types", () => {
   const types = listTypes();
-  for (const t of ["bgm", "sfx", "image", "icon", "voice", "brand"]) {
+  for (const t of ["bgm", "sfx", "image", "icon", "logo", "voice", "brand", "grade", "lut"]) {
     assert.ok(types.includes(t), `missing type: ${t}`);
   }
 });
@@ -21,7 +21,7 @@ test("heygen provider is first for every type it serves", () => {
 
 test("sanctioned providers only: heygen, local mflux/kokoro, codex, design spec, logo tiers", () => {
   const allowed =
-    /^heygen|^mflux\.local$|^kokoro\.local$|^codex\.image_gen$|^design_spec$|^svgl$|^simple-icons$|^github\.avatar$|^favicon\.ddg$/;
+    /^heygen|^mflux\.local$|^kokoro\.local$|^codex\.image_gen$|^design_spec$|^svgl$|^simple-icons$|^github\.avatar$|^favicon\.ddg$|^color_grade\.local$|^cube_lut\.local$/;
   for (const t of listTypes()) {
     for (const p of getProviders(t)) {
       assert.ok(allowed.test(p.name), `${t} lists unsanctioned provider: ${p.name}`);
diff --git a/skills/media-use/scripts/resolve.mjs b/skills/media-use/scripts/resolve.mjs
index b366c7d85..59918f533 100644
--- a/skills/media-use/scripts/resolve.mjs
+++ b/skills/media-use/scripts/resolve.mjs
@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, statSync } from "node:fs";
+import { existsSync, statSync, writeFileSync, renameSync, rmSync } from "node:fs";
 import { resolve, join, extname, basename } from "node:path";
 import { parseArgs } from "node:util";
 import { appendRecord, findByPrompt, findByEntity, nextId, allocateId } from "./lib/manifest.mjs";
@@ -13,6 +13,14 @@ import { track } from "./lib/telemetry.mjs";
 import { typesMatch } from "./lib/match.mjs";
 import { listCandidates, formatCandidates, CANDIDATE_CAP } from "./lib/candidates.mjs";
 import { findGlobalBySha } from "./lib/cache.mjs";
+import { buildCube, paramsFromIntent } from "./lib/cube-build.mjs";
+import { validateCubeFile } from "./lib/cube-validate.mjs";
+import { analyzeMediaGrade, formatMeasuredNote } from "./lib/grade-analyzer.mjs";
+import {
+  freezeLibraryLut,
+  isLibraryLutOfflineMiss,
+  matchColorLook,
+} from "./lib/lut-preset-provider.mjs";
 
 const { values: args } = parseArgs({
   options: {
@@ -25,6 +33,8 @@ const { values: args } = parseArgs({
     "dry-run": { type: "boolean", default: false },
     reuse: { type: "string" },
     from: { type: "string" },
+    params: { type: "string" },
+    for: { type: "string" },
     "local-only": { type: "boolean", default: false },
     provider: { type: "string" },
     json: { type: "boolean", default: false },
@@ -51,15 +61,24 @@ Options:
                   download, no mutation. Read them and decide reuse yourself.
   --reuse <sha>   Import a specific global-cache asset (by content sha/prefix,
                   from --candidates) into this project
+  --from <file>   Freeze a local file or direct public URL (ingest)
+  --params <json> Build an explicit parametric LUT (lut/grade only)
+  --for <media>   Analyze a local image/video and add measured grade adjust
+                  suggestions (grade only)
+  --local-only    Offline: skip every network provider
   --provider      Force one generator (e.g. codex, mflux, kokoro, heygen)
   --json          Output JSON instead of one-line result
   --help, -h      Show this help`);
   process.exit(0);
 }
 
+const projectDir = resolve(args.project);
+const type = args.type;
+const intent = args.intent;
+const entity = args.entity || null;
+
 if (args.adopt) {
   const { adoptExistingAssets } = await import("./lib/adopt.mjs");
-  const projectDir = resolve(args.project);
   const adopted = adoptExistingAssets(projectDir);
   if (args.json) {
     console.log(JSON.stringify({ ok: true, adopted: adopted.length, assets: adopted }));
@@ -95,6 +114,23 @@ if (args.from) {
   process.exit(0);
 }
 
+if (args.params !== undefined) {
+  if (type !== "lut" && type !== "grade") {
+    exitError(
+      type
+        ? `--params only supports --type lut or grade (got ${type})`
+        : "--params requires --type lut or grade",
+      2,
+    );
+  }
+  try {
+    await runParams();
+    process.exit(0);
+  } catch (err) {
+    exitError(err.message, 1);
+  }
+}
+
 if (!args.type || !args.intent || !args.intent.trim()) {
   console.error("error: --type and a non-empty --intent are required");
   process.exit(2);
@@ -115,10 +151,21 @@ if (args.provider && !providerMatches(args.type, args.provider)) {
   process.exit(2);
 }
 
-const projectDir = resolve(args.project);
-const type = args.type;
-const intent = args.intent;
-const entity = args.entity || null;
+function recordAvailable(projectDir, record) {
+  if (!record) return false;
+  if (record.path) return existsSync(join(projectDir, record.path));
+  return record.type === "grade" && record.grading;
+}
+
+function localizeImportedRecord(record, localPath) {
+  if (record?.type === "grade" && record.grading?.lut) {
+    record.grading = {
+      ...record.grading,
+      lut: { ...record.grading.lut, src: localPath },
+    };
+  }
+  return record;
+}
 
 async function run() {
   // A forced --provider means "(re)generate with THIS provider" — it bypasses
@@ -129,7 +176,7 @@ async function run() {
 
   // 1. project manifest — exact-prompt match
   const projectHit = forced ? null : findByPrompt(projectDir, intent, type);
-  if (projectHit && existsSync(join(projectDir, projectHit.path))) {
+  if (recordAvailable(projectDir, projectHit)) {
     return result(projectHit, "cached");
   }
 
@@ -138,17 +185,16 @@ async function run() {
   // always recorded as type image while agents ask for logos as type icon.
   if (!forced && entity) {
     const entityHit = findByEntity(projectDir, entity);
-    if (
-      entityHit &&
-      typesMatch(entityHit.type, type) &&
-      existsSync(join(projectDir, entityHit.path))
-    ) {
+    if (entityHit && typesMatch(entityHit.type, type) && recordAvailable(projectDir, entityHit)) {
       return result(entityHit, "cached");
     }
   }
 
   // 1c. scan existing assets/ directory for unregistered matches
-  const existingAsset = forced ? null : findExistingAsset(projectDir, intent, type);
+  const existingAsset =
+    forced || type === "grade" || type === "lut"
+      ? null
+      : findExistingAsset(projectDir, intent, type);
   if (existingAsset) {
     const id = nextId(projectDir, type);
     const record = {
@@ -169,7 +215,10 @@ async function run() {
   if (cacheHit) {
     const ext = extname(cacheHit.cached_path);
     const { id, localPath } = allocateId(projectDir, type, ext);
-    const imported = importFromCache(cacheHit, projectDir, id, localPath);
+    const imported = localizeImportedRecord(
+      importFromCache(cacheHit, projectDir, id, localPath),
+      localPath,
+    );
     if (imported) {
       appendRecord(projectDir, imported);
       regenerateIndex(projectDir);
@@ -182,7 +231,10 @@ async function run() {
     if (entityCacheHit && typesMatch(entityCacheHit.type, type)) {
       const ext = extname(entityCacheHit.cached_path);
       const { id, localPath } = allocateId(projectDir, type, ext);
-      const imported = importFromCache(entityCacheHit, projectDir, id, localPath);
+      const imported = localizeImportedRecord(
+        importFromCache(entityCacheHit, projectDir, id, localPath),
+        localPath,
+      );
       if (imported) {
         appendRecord(projectDir, imported);
         regenerateIndex(projectDir);
@@ -212,6 +264,10 @@ async function run() {
     // hint is best-effort; never block a resolve
   }
 
+  if (type === "grade" || type === "lut") {
+    return resolveColor(type, intent, { projectDir });
+  }
+
   // 3. provider search — registry tries providers in order (heygen-CLI first)
   let searchResult = null;
   try {
@@ -303,9 +359,276 @@ async function run() {
   return result(record, searchResult.source || "search");
 }
 
+function mergeSmartAdjust(block) {
+  if (!args.for) return block;
+  const mediaPath = resolve(args.for);
+  // Clear upfront error beats an ffmpeg "No such file" stack on a typo'd path.
+  if (!existsSync(mediaPath)) throw new Error(`--for file not found: ${mediaPath}`);
+  const analysis = analyzeMediaGrade(mediaPath);
+  console.error(formatMeasuredNote(mediaPath, analysis.measured));
+  return {
+    ...block,
+    adjust: {
+      ...(block.adjust || {}),
+      ...analysis.adjust,
+    },
+  };
+}
+
+function freezeGeneratedLut(
+  params,
+  {
+    projectDir,
+    type,
+    description = "parametric color grade",
+    validationErrorPrefix = "generated LUT failed validation",
+  },
+) {
+  const { id, localPath } = allocateId(projectDir, type, ".cube");
+  const fullPath = join(projectDir, localPath);
+  const tmpPath = `${fullPath}.tmp`;
+  try {
+    // Write + validate at .tmp, then atomic rename, so a crash between write and
+    // validate can't leave an invalid .cube at the final path.
+    writeFileSync(tmpPath, buildCube(params));
+    const check = validateCubeFile(tmpPath);
+    if (!check.ok) throw new Error(check.error);
+    renameSync(tmpPath, fullPath);
+  } catch (err) {
+    rmSync(tmpPath, { force: true });
+    throw new Error(`${validationErrorPrefix}: ${err.message}`);
+  }
+  return {
+    id,
+    localPath,
+    fullPath,
+    lut: { src: localPath, intensity: 1 },
+    source: "generated",
+    description,
+    metadata: {
+      provider: "cube_lut.builder",
+      provenance: { params },
+    },
+  };
+}
+
+function exitError(message, status = 1) {
+  if (args.json) {
+    console.log(JSON.stringify({ ok: false, error: message }));
+  } else {
+    console.error(`error: ${message}`);
+  }
+  process.exit(status);
+}
+
+function parseExplicitParams() {
+  try {
+    return JSON.parse(args.params);
+  } catch (err) {
+    throw new Error(`invalid --params JSON: ${err.message}`);
+  }
+}
+
+async function runParams() {
+  if (type === "lut" && args.for) {
+    throw new Error("--for is only supported with --type grade");
+  }
+  const params = parseExplicitParams();
+  const description =
+    typeof intent === "string" && intent.trim()
+      ? intent.trim()
+      : `custom parametric ${type === "lut" ? "lut" : "grade"}`;
+  const frozen = freezeGeneratedLut(params, {
+    projectDir,
+    type,
+    description,
+    validationErrorPrefix: "--params produced an invalid LUT",
+  });
+  const record = {
+    id: frozen.id,
+    type,
+    path: frozen.localPath,
+    source: frozen.source,
+    description: frozen.description,
+    ...(type === "grade" && { grading: mergeSmartAdjust({ intensity: 1, lut: frozen.lut }) }),
+    provenance: {
+      provider: frozen.metadata.provider,
+      ...frozen.metadata.provenance,
+    },
+  };
+  return finalizeColorRecord(record, frozen.source, frozen.fullPath);
+}
+
+async function finalizeColorRecord(record, source, fullPath = null) {
+  appendRecord(projectDir, record);
+  regenerateIndex(projectDir);
+  if (fullPath) {
+    try {
+      cachePut(fullPath, record);
+    } catch {
+      // promotion is best-effort
+    }
+  }
+  return result(record, source);
+}
+
+async function colorMiss(type, intent) {
+  await track("media_use_resolve_miss", {
+    type,
+    local_only: !!args["local-only"],
+    provider_override: !!args.provider,
+  });
+  const msg = `no local color grade could resolve ${type}: "${intent}"`;
+  if (args.json) {
+    console.log(JSON.stringify({ ok: false, error: msg }));
+  } else {
+    console.error(`error: ${msg}`);
+  }
+  process.exit(1);
+}
+
+async function resolveGrade(intent, { projectDir }) {
+  const match = matchColorLook(intent);
+  if (match?.kind === "preset") {
+    const id = nextId(projectDir, "grade");
+    const grading = mergeSmartAdjust({ preset: match.preset, intensity: 1 });
+    const record = {
+      id,
+      type: "grade",
+      source: "preset",
+      description: intent,
+      grading,
+      provenance: {
+        provider: "color_grade.local",
+        prompt: intent,
+        preset: match.preset,
+      },
+    };
+    return finalizeColorRecord(record, "preset");
+  }
+
+  if (match?.kind === "library") {
+    let frozen;
+    try {
+      frozen = await freezeLibraryLut(match, {
+        projectDir,
+        type: "grade",
+        localOnly: args["local-only"],
+      });
+    } catch (err) {
+      if (isLibraryLutOfflineMiss(err)) return colorMiss("grade", intent);
+      throw err;
+    }
+    const grading = mergeSmartAdjust({ intensity: 1, lut: frozen.lut });
+    const record = {
+      id: frozen.id,
+      type: "grade",
+      path: frozen.localPath,
+      source: frozen.source,
+      description: frozen.description,
+      grading,
+      provenance: {
+        provider: frozen.metadata.provider,
+        prompt: intent,
+        ...frozen.metadata.provenance,
+      },
+    };
+    return finalizeColorRecord(record, frozen.source, frozen.fullPath);
+  }
+
+  const params = paramsFromIntent(intent);
+  if (!params) {
+    // No creative look matched. With --for, the measured adjust block is a
+    // valid grade on its own (footage auto-correction); only a true miss
+    // (no look AND no analysis) aborts.
+    if (args.for) {
+      const grading = mergeSmartAdjust({ intensity: 1 });
+      const record = {
+        id: nextId(projectDir, "grade"),
+        type: "grade",
+        source: "measured",
+        description: intent,
+        grading,
+        provenance: { provider: "color_grade.local", prompt: intent, measured: true },
+      };
+      return finalizeColorRecord(record, "measured");
+    }
+    return colorMiss("grade", intent);
+  }
+  const frozen = freezeGeneratedLut(params, { projectDir, type: "grade" });
+  const grading = mergeSmartAdjust({ intensity: 1, lut: frozen.lut });
+  const record = {
+    id: frozen.id,
+    type: "grade",
+    path: frozen.localPath,
+    source: frozen.source,
+    description: intent,
+    grading,
+    provenance: {
+      provider: frozen.metadata.provider,
+      prompt: intent,
+      ...frozen.metadata.provenance,
+    },
+  };
+  return finalizeColorRecord(record, frozen.source, frozen.fullPath);
+}
+
+async function resolveLut(intent, { projectDir }) {
+  if (args.for) {
+    throw new Error("--for is only supported with --type grade");
+  }
+  const match = matchColorLook(intent);
+  if (match?.kind === "library") {
+    let frozen;
+    try {
+      frozen = await freezeLibraryLut(match, {
+        projectDir,
+        type: "lut",
+        localOnly: args["local-only"],
+      });
+    } catch (err) {
+      if (isLibraryLutOfflineMiss(err)) return colorMiss("lut", intent);
+      throw err;
+    }
+    const record = {
+      id: frozen.id,
+      type: "lut",
+      path: frozen.localPath,
+      source: frozen.source,
+      description: frozen.description,
+      provenance: {
+        provider: frozen.metadata.provider,
+        prompt: intent,
+        ...frozen.metadata.provenance,
+      },
+    };
+    return finalizeColorRecord(record, frozen.source, frozen.fullPath);
+  }
+
+  const params = paramsFromIntent(intent);
+  if (!params) return colorMiss("lut", intent);
+  const frozen = freezeGeneratedLut(params, { projectDir, type: "lut" });
+  const record = {
+    id: frozen.id,
+    type: "lut",
+    path: frozen.localPath,
+    source: frozen.source,
+    description: intent,
+    provenance: {
+      provider: frozen.metadata.provider,
+      prompt: intent,
+      ...frozen.metadata.provenance,
+    },
+  };
+  return finalizeColorRecord(record, frozen.source, frozen.fullPath);
+}
+
+async function resolveColor(type, intent, options) {
+  if (type === "grade") return resolveGrade(intent, options);
+  return resolveLut(intent, options);
+}
+
 async function ingest(src) {
-  const projectDir = resolve(args.project);
-  const type = args.type;
   if (!type || !listTypes().includes(type)) {
     console.error(`error: --from requires --type (one of: ${listTypes().join(", ")})`);
     process.exit(2);
@@ -332,6 +655,15 @@ async function ingest(src) {
   const fullPath = join(projectDir, localPath);
   if (isUrl) await freezeUrl(src, fullPath);
   else freezeLocalFile(resolve(src), fullPath);
+  if (type === "lut" || type === "grade") {
+    try {
+      const check = validateCubeFile(fullPath);
+      if (!check.ok) throw new Error(check.error);
+    } catch (err) {
+      rmSync(fullPath, { force: true });
+      exitError(`ingested LUT is invalid: ${err.message}`, 1);
+    }
+  }
   const record = {
     id,
     type,
@@ -407,7 +739,10 @@ async function reuseGlobal(shaArg) {
   }
   const ext = extname(rec.cached_path || "") || defaultExt(type);
   const { id, localPath } = allocateId(projectDir, type, ext);
-  const imported = importFromCache(rec, projectDir, id, localPath);
+  const imported = localizeImportedRecord(
+    importFromCache(rec, projectDir, id, localPath),
+    localPath,
+  );
   if (!imported) {
     console.error(`error: cache entry for "${shaArg}" is incomplete or missing on disk`);
     process.exit(1);
@@ -427,19 +762,34 @@ async function result(record, source) {
     type: record.type,
     source,
     provider: record.provenance?.provider,
+    // How a library LUT resolved: "url" (CDN), "params-fallback" (CDN failed →
+    // parametric), or "params" (offline). Surfaces silent CDN→params downgrades
+    // in prod, which --doctor can't (it only answers "reachable now?").
+    via: record.provenance?.via,
     local_only: !!args["local-only"],
     provider_override: !!args.provider,
   });
   if (args.json) {
-    console.log(JSON.stringify({ ok: true, ...record, _source: source }));
+    const grading = record.type === "grade" && record.grading ? record.grading : null;
+    console.log(
+      JSON.stringify({
+        ok: true,
+        ...record,
+        ...(grading || {}),
+        ...(grading && { grading }),
+        _source: source,
+      }),
+    );
   } else {
     const meta = formatMeta(record, source);
-    console.log(`resolved ${record.id} → ${record.path} (${meta})`);
+    console.log(`resolved ${record.id} → ${record.path || "inline"} (${meta})`);
   }
 }
 
 function formatMeta(record, source) {
   const parts = [record.type];
+  if (record.grading?.preset) parts.push(`preset ${record.grading.preset}`);
+  if (record.grading?.lut) parts.push("lut");
   if (record.duration != null) parts.push(`${record.duration}s`);
   if (record.width && record.height) parts.push(`${record.width}×${record.height}`);
   if (record.transparent) parts.push("transparent");
@@ -464,6 +814,8 @@ const DEFAULT_EXT = {
   icon: ".svg",
   logo: ".svg",
   brand: ".png",
+  grade: ".cube",
+  lut: ".cube",
 };
 
 function defaultExt(type) {
diff --git a/skills/media-use/scripts/resolve.test.mjs b/skills/media-use/scripts/resolve.test.mjs
index 60899fd92..2f08fb310 100644
--- a/skills/media-use/scripts/resolve.test.mjs
+++ b/skills/media-use/scripts/resolve.test.mjs
@@ -1,16 +1,35 @@
 import { strict as assert } from "node:assert";
-import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, existsSync } from "node:fs";
+import {
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+  readFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+} from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { appendRecord, readManifest } from "./lib/manifest.mjs";
 import { regenerateIndex } from "./lib/index-gen.mjs";
 import { getProvider } from "./lib/providers.mjs";
 import { freezeLocalFile } from "./lib/freeze.mjs";
 import { cachePut, cacheGet, importFromCache } from "./lib/cache.mjs";
+import { validateCubeFile } from "./lib/cube-validate.mjs";
 
 const REPO_ROOT = join(import.meta.dirname, "..", "..", "..");
 const RESOLVE_CLI = join(import.meta.dirname, "resolve.mjs");
+// The "Test: skills" CI job has no ffmpeg on PATH (by design). The smart-grade
+// test shells to ffmpeg, so it's skipped there and runs where ffmpeg exists.
+const HAS_FFMPEG = spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0;
+// The core-conformance test imports core's TypeScript via tsx. The dependency-free
+// "Test: skills" CI job has neither tsx nor installed deps, so skip it there; it
+// runs wherever the workspace is installed (locally, the main Test job).
+const CAN_TSX =
+  spawnSync(process.execPath, ["--import", "tsx", "--input-type=module", "-e", "0"], {
+    stdio: "ignore",
+  }).status === 0;
 let tmp;
 
 function setup() {
@@ -45,6 +64,60 @@ function runResolve(args, opts = {}) {
   });
 }
 
+function spawnResolve(args, opts = {}) {
+  return spawnSync(process.execPath, [RESOLVE_CLI, ...args], {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    ...opts,
+  });
+}
+
+function makeFrame(dir, name, color) {
+  const out = join(dir, name);
+  execFileSync(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-f",
+      "lavfi",
+      "-i",
+      `color=c=${color}:s=64x64`,
+      "-frames:v",
+      "1",
+      "-y",
+      out,
+    ],
+    { stdio: "pipe" },
+  );
+  return out;
+}
+
+function normalizeWithCoreSource(grading) {
+  const sourcePath = join(REPO_ROOT, "packages/core/src/colorGrading.ts");
+  const code = `
+    import { normalizeHfColorGrading } from ${JSON.stringify(sourcePath)};
+    const grading = JSON.parse(process.env.HF_GRADING_JSON);
+    const normalized = normalizeHfColorGrading(grading);
+    if (!normalized) process.exit(2);
+    console.log(JSON.stringify({
+      preset: normalized.preset,
+      intensity: normalized.intensity,
+      adjust: normalized.adjust,
+      lut: normalized.lut,
+      colorSpace: normalized.colorSpace
+    }));
+  `;
+  return JSON.parse(
+    execFileSync(process.execPath, ["--import", "tsx", "--input-type=module", "-e", code], {
+      cwd: REPO_ROOT,
+      encoding: "utf8",
+      env: { ...process.env, HF_GRADING_JSON: JSON.stringify(grading) },
+    }),
+  );
+}
+
 const tests = [];
 function test(name, fn) {
   tests.push({ name, fn });
@@ -217,6 +290,19 @@ test("--help exits 0", () => {
   const out = runResolve(["--help"]);
   assert.ok(out.includes("media-use resolve"));
   assert.ok(out.includes("--type"));
+  assert.ok(out.includes("--for"));
+  assert.ok(out.includes("--from"));
+  assert.ok(out.includes("--local-only"));
+});
+
+test("unknown type error lists grade and lut", () => {
+  try {
+    runResolve(["--type", "bogus", "--intent", "x"], { stdio: "pipe" });
+    assert.fail("should have exited");
+  } catch (err) {
+    assert.equal(err.status, 2);
+    assert.match(String(err.stderr), /known: .*grade.*lut/);
+  }
 });
 
 test("missing required args exits 2", () => {
@@ -257,6 +343,234 @@ test("one-line output format matches contract", () => {
   cleanup();
 });
 
+// --- color grading ---
+
+test("grade resolves a preset-only look with no cube file", () => {
+  setup();
+  const out = runResolve([
+    "--type",
+    "grade",
+    "--intent",
+    "warm daylight",
+    "--project",
+    tmp,
+    "--json",
+  ]);
+  const parsed = JSON.parse(out.trim());
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.type, "grade");
+  assert.equal(parsed.grading.preset, "warm-daylight");
+  assert.equal(parsed.grading.lut, undefined);
+  assert.equal(parsed.path, undefined);
+  assert.equal(readManifest(tmp).length, 1);
+  cleanup();
+});
+
+test("grade resolves a library LUT look and freezes a validated cube", () => {
+  setup();
+  const out = runResolve([
+    "--type",
+    "grade",
+    "--intent",
+    "teal orange blockbuster",
+    "--project",
+    tmp,
+    "--json",
+  ]);
+  const parsed = JSON.parse(out.trim());
+  assert.equal(parsed.ok, true);
+  assert.match(parsed.grading.lut.src, /^\.media\/luts\/grade_001\.cube$/);
+  assert.equal(parsed.path, parsed.grading.lut.src);
+  assert.ok(existsSync(join(tmp, parsed.grading.lut.src)));
+  assert.equal(validateCubeFile(join(tmp, parsed.grading.lut.src)).ok, true);
+  cleanup();
+});
+
+test("smart grade merges measured adjust and keeps stdout valid JSON", () => {
+  if (!HAS_FFMPEG) {
+    console.log("  (skipped: ffmpeg not on PATH)");
+    return;
+  }
+  setup();
+  const frame = makeFrame(tmp, "under.png", "0x202020");
+  const proc = spawnResolve([
+    "--type",
+    "grade",
+    "--intent",
+    "warm cinematic",
+    "--for",
+    frame,
+    "--project",
+    tmp,
+    "--json",
+  ]);
+  assert.equal(proc.status, 0, proc.stderr);
+  const parsed = JSON.parse(proc.stdout);
+  assert.equal(parsed.ok, true);
+  assert.ok(parsed.grading.adjust.exposure > 0, "under-exposed frame should suggest lift");
+  assert.match(proc.stderr, /media-use: measured/);
+  cleanup();
+});
+
+test("emitted grading block survives the core normalizeHfColorGrading contract", () => {
+  if (!CAN_TSX) {
+    console.log("  (skipped: tsx / core source unavailable)");
+    return;
+  }
+  setup();
+  const out = runResolve([
+    "--type",
+    "grade",
+    "--intent",
+    "teal orange blockbuster",
+    "--project",
+    tmp,
+    "--json",
+  ]);
+  const parsed = JSON.parse(out.trim());
+  const normalized = normalizeWithCoreSource(parsed.grading);
+  assert.equal(normalized.lut.src, parsed.grading.lut.src);
+  assert.equal(normalized.lut.intensity, parsed.grading.lut.intensity);
+  assert.equal(normalized.colorSpace, "rec709");
+  cleanup();
+});
+
+test("lut resolves only the frozen cube path", () => {
+  setup();
+  const out = runResolve([
+    "--type",
+    "lut",
+    "--intent",
+    "teal orange blockbuster",
+    "--project",
+    tmp,
+    "--json",
+  ]);
+  const parsed = JSON.parse(out.trim());
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.type, "lut");
+  assert.match(parsed.path, /^\.media\/luts\/lut_001\.cube$/);
+  assert.equal(parsed.grading, undefined);
+  assert.equal(validateCubeFile(join(tmp, parsed.path)).ok, true);
+  cleanup();
+});
+
+test("lut --params builds, validates, and freezes a cube", () => {
+  setup();
+  const params = { contrast: 0.2, temperature: -0.3 };
+  const out = runResolve(["-t", "lut", "--params", JSON.stringify(params), "-p", tmp, "--json"]);
+  const parsed = JSON.parse(out.trim());
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.type, "lut");
+  assert.match(parsed.path, /^\.media\/luts\/lut_001\.cube$/);
+  assert.equal(parsed.description, "custom parametric lut");
+  assert.equal(parsed.provenance.provider, "cube_lut.builder");
+  assert.deepEqual(parsed.provenance.params, params);
+  assert.ok(existsSync(join(tmp, parsed.path)));
+  assert.equal(validateCubeFile(join(tmp, parsed.path)).ok, true);
+  cleanup();
+});
+
+test("grade --params returns a grading block with a frozen valid cube", () => {
+  setup();
+  const out = runResolve([
+    "-t",
+    "grade",
+    "--params",
+    JSON.stringify({ exposure: 0.2 }),
+    "-p",
+    tmp,
+    "--json",
+  ]);
+  const parsed = JSON.parse(out.trim());
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.type, "grade");
+  assert.equal(parsed.grading.intensity, 1);
+  assert.match(parsed.grading.lut.src, /^\.media\/luts\/grade_001\.cube$/);
+  assert.equal(parsed.lut.src, parsed.grading.lut.src);
+  assert.equal(parsed.path, parsed.grading.lut.src);
+  assert.equal(validateCubeFile(join(tmp, parsed.grading.lut.src)).ok, true);
+  cleanup();
+});
+
+test("--params malformed JSON errors cleanly without freezing a cube", () => {
+  setup();
+  const proc = spawnResolve(["-t", "lut", "--params", "{not json", "-p", tmp, "--json"]);
+  assert.equal(proc.status, 1, proc.stderr);
+  const parsed = JSON.parse(proc.stdout);
+  assert.equal(parsed.ok, false);
+  assert.match(parsed.error, /^invalid --params JSON:/);
+  assert.equal(readManifest(tmp).length, 0);
+  assert.equal(existsSync(join(tmp, ".media/luts")), false);
+  cleanup();
+});
+
+// buildCube clamps every accepted parameter and resolve.mjs does not expose
+// the size argument, so there is no CLI input that can make --params emit a
+// structurally invalid cube. Invalid cube cleanup is covered through --from.
+test("--from rejects invalid lut cube without registering or leaving a frozen file", () => {
+  setup();
+  const broken = join(tmp, "broken.cube");
+  writeFileSync(broken, "LUT_3D_SIZE 999\n");
+  const proc = spawnResolve(["--from", broken, "-t", "lut", "-p", tmp, "--json"]);
+  assert.equal(proc.status, 1, proc.stderr);
+  const parsed = JSON.parse(proc.stdout);
+  assert.equal(parsed.ok, false);
+  assert.match(parsed.error, /^ingested LUT is invalid: LUT_3D_SIZE 999 exceeds max 64/);
+  assert.equal(readManifest(tmp).length, 0);
+  const lutDir = join(tmp, ".media/luts");
+  assert.deepEqual(existsSync(lutDir) ? readdirSync(lutDir) : [], []);
+  cleanup();
+});
+
+test("grade miss exits explicitly with no partial file", () => {
+  setup();
+  const missIntent = `zqxv imaginary neutron ${process.pid}`;
+  try {
+    runResolve(["--type", "grade", "--intent", missIntent, "--project", tmp, "--json"]);
+    assert.fail("should have exited");
+  } catch (err) {
+    assert.equal(err.status, 1);
+    const parsed = JSON.parse(String(err.stdout));
+    assert.equal(parsed.ok, false);
+    assert.match(parsed.error, /no local color grade could resolve/);
+    assert.equal(readManifest(tmp).length, 0);
+    assert.equal(existsSync(join(tmp, ".media/luts")), false);
+  }
+  cleanup();
+});
+
+test("identical grade resolve hits the project cache without re-freezing", () => {
+  setup();
+  const first = JSON.parse(
+    runResolve([
+      "--type",
+      "grade",
+      "--intent",
+      "teal orange blockbuster",
+      "--project",
+      tmp,
+      "--json",
+    ]),
+  );
+  const second = JSON.parse(
+    runResolve([
+      "--type",
+      "grade",
+      "--intent",
+      "teal orange blockbuster",
+      "--project",
+      tmp,
+      "--json",
+    ]),
+  );
+  assert.equal(second._source, "cached");
+  assert.equal(second.id, first.id);
+  assert.equal(second.path, first.path);
+  assert.equal(readManifest(tmp).length, 1);
+  cleanup();
+});
+
 // --- run ---
 
 async function main() {