From cf7c1d7609cb7816eaaa5e6651d53dd3873de162 Mon Sep 17 00:00:00 2001 From: Miguel Angel Simon Sierra Date: Fri, 10 Jul 2026 12:47:14 -0400 Subject: [PATCH] docs(cli,skills): teach check as the canonical verification gate Scaffolded projects' npm run check now invokes the single check command instead of chaining lint, validate, and inspect (three Chrome boots become one). The CLI skill, its correctness reference, the entry skill's capability map, README/docs catalog rows, the Mintlify CLI page (new check section, deprecation banner on inspect), template CLAUDE/AGENTS (byte-identical), root CLAUDE/AGENTS, and every creation-workflow skill that taught the old sequence all point at check. snapshot keeps its standalone sections; validate/inspect stay documented as deprecated aliases with their check equivalents. --- AGENTS.md | 2 +- CLAUDE.md | 4 +- README.md | 2 +- docs/contributing/catalog.mdx | 2 +- docs/guides/pipeline.mdx | 2 +- docs/guides/prompting.mdx | 2 +- docs/guides/skills.mdx | 2 +- docs/guides/video-editor-cheatsheet.mdx | 10 +- docs/packages/cli.mdx | 30 +++++ packages/cli/src/commands/init.test.ts | 6 +- packages/cli/src/commands/init.ts | 4 +- packages/cli/src/templates/_shared/AGENTS.md | 4 +- packages/cli/src/templates/_shared/CLAUDE.md | 4 +- skills-manifest.json | 32 +++--- skills/faceless-explainer/SKILL.md | 4 +- skills/figma/SKILL.md | 2 +- skills/general-video/SKILL.md | 4 +- .../hyperframes-animation/adapters/animejs.md | 2 +- .../adapters/css-animations.md | 2 +- .../hyperframes-animation/adapters/lottie.md | 2 +- .../hyperframes-animation/adapters/three.md | 2 +- .../hyperframes-animation/adapters/waapi.md | 2 +- .../rules/motion-blur-streak.md | 2 +- skills/hyperframes-cli/SKILL.md | 27 ++--- .../references/lint-validate-inspect.md | 106 +++++++++--------- skills/hyperframes-core/SKILL.md | 4 +- .../references/data-attributes.md | 2 +- .../hyperframes-core/references/tailwind.md | 6 +- .../references/house-style.md | 2 +- skills/hyperframes-keyframes/SKILL.md | 2 +- .../references/contributing.md | 4 +- skills/hyperframes/SKILL.md | 2 +- skills/motion-graphics/SKILL.md | 2 +- skills/motion-graphics/agents/builder.md | 2 +- skills/motion-graphics/agents/finalize.md | 2 +- .../references/builder-contract.md | 2 +- skills/music-to-video/SKILL.md | 2 +- skills/pr-to-video/SKILL.md | 4 +- skills/product-launch-video/SKILL.md | 4 +- skills/slideshow/SKILL.md | 2 +- skills/website-to-video/SKILL.md | 2 +- 41 files changed, 164 insertions(+), 141 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7264b1adb..1c1cd9eff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,7 +51,7 @@ After creating or editing any `.html` composition: ```bash npx hyperframes lint # Static HTML structure check -npx hyperframes validate # Runtime check (headless Chrome — catches JS errors, missing assets) +npx hyperframes check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast) ``` Both must pass before previewing or considering work complete. diff --git a/CLAUDE.md b/CLAUDE.md index 7c895db16..abd8a019f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,7 +39,7 @@ Atomic capabilities the creation workflows compose against — pull one when you - `/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, 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-cli` — CLI dev loop: `init`, `add`, `lint`, `check`, `snapshot`, `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. @@ -81,7 +81,7 @@ After creating or editing any `.html` composition: ```bash npx hyperframes lint # Static HTML structure check -npx hyperframes validate # Runtime check (headless Chrome — catches JS errors, missing assets) +npx hyperframes check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast) ``` Both must pass before previewing or considering work complete. diff --git a/README.md b/README.md index e6b2a4a7b..d12516ace 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ Atomic capabilities the creation workflows compose against — pull one when you | `/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-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `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. | diff --git a/docs/contributing/catalog.mdx b/docs/contributing/catalog.mdx index a630a41e2..be61d7f57 100644 --- a/docs/contributing/catalog.mdx +++ b/docs/contributing/catalog.mdx @@ -141,7 +141,7 @@ Not everything belongs in the registry. The bar is production quality. ```bash hyperframes lint - hyperframes validate + hyperframes check npx oxfmt your-block.html ``` diff --git a/docs/guides/pipeline.mdx b/docs/guides/pipeline.mdx index c701ddb7a..8298adf98 100644 --- a/docs/guides/pipeline.mdx +++ b/docs/guides/pipeline.mdx @@ -165,7 +165,7 @@ Three checks before delivery: ```bash npx hyperframes lint # static HTML structure checks -npx hyperframes validate # loads in headless Chrome, catches runtime errors +npx hyperframes check # one browser session: runtime errors, layout, motion, contrast npx hyperframes snapshot my-video --at 2.9,10.4 # PNGs at beat midpoints ``` diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx index 49907ccc6..fe78e6904 100644 --- a/docs/guides/prompting.mdx +++ b/docs/guides/prompting.mdx @@ -268,7 +268,7 @@ Things that cause friction (or wrong output): - **Don't ask for React / Vue components.** Hyperframes compositions are plain HTML with `data-*` attributes and a GSAP timeline. Asking for "a React component for the intro" forces the agent to translate later. - **Don't ask for 4K or 60fps unless you need it.** Defaults (1920×1080, 30fps) render fast and look great. Higher specs slow rendering meaningfully. - **Don't skip the slash command.** Without `/hyperframes`, the agent may guess at HTML video conventions instead of using the framework's actual rules (`class="clip"` on timed elements, `window.__timelines` registration, etc.). -- **Don't paste long error logs into the prompt without context.** Run `npx hyperframes lint` and `npx hyperframes validate` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems). +- **Don't paste long error logs into the prompt without context.** Run `npx hyperframes check` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems). - **Don't assume the agent knows your assets.** Mention file paths explicitly (`assets/intro.mp4`, `assets/logo.png`) — the agent will check what's there but a hint speeds it up. ## Recommended workflow diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 9579f7df6..254d85aea 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -99,7 +99,7 @@ Atomic capabilities the creation workflows compose against — pull one when you | `/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 / destroy / policies`). | +| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `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/docs/guides/video-editor-cheatsheet.mdx b/docs/guides/video-editor-cheatsheet.mdx index e9216f6bf..16e3431ab 100644 --- a/docs/guides/video-editor-cheatsheet.mdx +++ b/docs/guides/video-editor-cheatsheet.mdx @@ -27,7 +27,7 @@ Before showing or rendering a project: ```bash npx hyperframes lint -npx hyperframes validate +npx hyperframes check npx hyperframes render --quality standard --output review.mp4 ``` @@ -174,8 +174,8 @@ I moved the hero title and resized the CTA manually in Studio. Inspect the chang | `npx hyperframes capture https://example.com` | Capture a website as source material for a video | | `npx hyperframes preview` | Open the live Studio preview | | `npx hyperframes lint` | Catch structural mistakes before preview or render | -| `npx hyperframes validate` | Run the composition in headless Chrome to catch runtime errors | -| `npx hyperframes inspect` | Find text overflow and layout problems across the timeline | +| `npx hyperframes check` | Run the composition in headless Chrome to catch runtime errors | +| `npx hyperframes check` | Find text overflow and layout problems across the timeline | | `npx hyperframes snapshot --at 1,3,5` | Save PNG checks at exact timestamps | | `npx hyperframes render --output final.mp4` | Render the video | | `npx hyperframes publish` | Upload the project and get a shareable HyperFrames URL | @@ -278,9 +278,9 @@ For editor-facing changes, keep `npx hyperframes preview` running, then have the | --- | --- | | Preview will not start | `npx hyperframes doctor` | | Port already in use | `npx hyperframes preview --port 4567` | -| Render fails | `npx hyperframes lint` then `npx hyperframes validate` | +| Render fails | `npx hyperframes lint` then `npx hyperframes check` | | Need exact frame checks | `npx hyperframes snapshot --at 1,2.5,5` | -| Text overflows in the frame | `npx hyperframes inspect` | +| Text overflows in the frame | `npx hyperframes check` | | Final render is too slow | Try `--quality draft`, reduce image sizes, or lower `--fps` | | Need to share editable project | `npx hyperframes publish` | diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index bd4839625..91094b0ed 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -520,6 +520,34 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o The linter detects missing attributes, missing adapter libraries (GSAP, Lottie, Three.js), structural problems, and more. See [Common Mistakes](/guides/common-mistakes) for details on each rule. + ### `check` + + The browser verification gate: everything the old `validate` → `inspect` → `snapshot` loop did, in **one** command with one browser session: + + ```bash + npx hyperframes check [dir] + npx hyperframes check [dir] --json # {ok, lint, runtime, layout, motion, contrast, snapshots} + npx hyperframes check [dir] --snapshots # annotated overview frames + per-finding crops + npx hyperframes check [dir] --at 1.5,4,7.25 + npx hyperframes check [dir] --strict # exit non-zero on warnings too + ``` + + `check` runs the linter first (browser skipped entirely on lint errors), then loads the bundled composition once and sweeps one seek grid running every audit per sample: runtime console errors and failed requests, layout defects (overflow, clipping, held overlaps, occlusion), `*.motion.json` sidecar assertions, and WCAG AA contrast. + + | Flag | Description | + |------|-------------| + | `--json` | Aggregated machine-readable envelope; every finding carries selector, `data-*` identity, source file, bbox, and sample time | + | `--snapshots` | Write overview frames (annotated with labeled finding boxes when there are errors) plus `finding-NN-.png` crops | + | `--samples` / `--at` / `--at-transitions` | Control the seek grid (default 9 samples; `--at-transitions` adds tween boundaries) | + | `--tolerance` | Allowed overflow in px before reporting (default 2) | + | `--timeout` | Initial settle budget in ms (default 3000) | + | `--no-contrast` | Skip the WCAG audit while iterating | + | `--strict` | Exit non-zero on warnings too (default: only errors) | + | `--caption-zone ""` | Opt-in band gate: flags content whose center sits inside the fractional band (optional `severity`, `seek`) | + | `--frame-check` | Opt-in media out-of-frame detection (img/svg/video/canvas) | + + Contrast failures are **errors** and include the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color. Severity is persistence-aware: single-sample transients demote to info, held findings gate the exit code, and a frozen timeline on a 3s+ composition fails with `sweep_static`. + ### `beats` Detect the beats in a composition's music track and write them to a beat file the Studio uses to draw beat guides on the timeline: @@ -549,6 +577,8 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o ### `inspect` + Deprecated: use [`check`](#check) — it covers this layout sweep plus runtime, motion, and contrast in one browser session. `inspect` keeps working and marks `_meta.deprecated: true` in JSON output. + Inspect rendered visual layout across the composition timeline: ```bash diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts index e913d6119..ef73b31be 100644 --- a/packages/cli/src/commands/init.test.ts +++ b/packages/cli/src/commands/init.test.ts @@ -50,8 +50,7 @@ describe("hyperframes init flag rename", () => { expect(pkg.type).toBe("module"); expect(pkg.scripts).toMatchObject({ dev: "npx --yes hyperframes preview", - check: - "npx --yes hyperframes lint && npx --yes hyperframes validate && npx --yes hyperframes inspect", + check: "npx --yes hyperframes check", render: "npx --yes hyperframes render", publish: "npx --yes hyperframes publish", }); @@ -84,8 +83,7 @@ describe("hyperframes init flag rename", () => { }; expect(pkg.scripts).toMatchObject({ dev: "npx --yes hyperframes preview", - check: - "npx --yes hyperframes lint && npx --yes hyperframes validate && npx --yes hyperframes inspect", + check: "npx --yes hyperframes check", render: "npx --yes hyperframes render", publish: "npx --yes hyperframes publish", }); diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 3866a4fbc..4bb625c7f 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -224,9 +224,7 @@ function hyperframesScript(command: string): string { function buildPackageScripts(): Record { return { dev: hyperframesScript("preview"), - check: - `${hyperframesScript("lint")} && ${hyperframesScript("validate")} && ` + - `${hyperframesScript("inspect")}`, + check: hyperframesScript("check"), render: hyperframesScript("render"), publish: hyperframesScript("publish"), }; diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index a30e02dbe..3e8a31aba 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -33,7 +33,7 @@ The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes- ```bash npm run dev # start the preview server (long-running — keep it alive in background) -npm run check # lint + validate + inspect +npm run check # lint + runtime + layout + motion + contrast (one command) npm run render # render to MP4 npm run publish # publish and get a shareable link npx hyperframes lint --verbose # include info-level findings @@ -76,7 +76,7 @@ After creating or editing any `.html` composition, **always** run the full check npm run check ``` -Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering. +Fix all errors before presenting the result. Warnings should be reviewed before rendering. ## Key Rules diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md index a30e02dbe..3e8a31aba 100644 --- a/packages/cli/src/templates/_shared/CLAUDE.md +++ b/packages/cli/src/templates/_shared/CLAUDE.md @@ -33,7 +33,7 @@ The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes- ```bash npm run dev # start the preview server (long-running — keep it alive in background) -npm run check # lint + validate + inspect +npm run check # lint + runtime + layout + motion + contrast (one command) npm run render # render to MP4 npm run publish # publish and get a shareable link npx hyperframes lint --verbose # include info-level findings @@ -76,7 +76,7 @@ After creating or editing any `.html` composition, **always** run the full check npm run check ``` -Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering. +Fix all errors before presenting the result. Warnings should be reviewed before rendering. ## Key Rules diff --git a/skills-manifest.json b/skills-manifest.json index e346b5d1c..97daf2d5f 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -6,43 +6,43 @@ "files": 144 }, "faceless-explainer": { - "hash": "09bc257e79dabebc", + "hash": "a09191a97564b114", "files": 18 }, "figma": { - "hash": "99538ee56a4ca553", + "hash": "0e6e96f5a76ff824", "files": 2 }, "general-video": { - "hash": "67f3dae100541eed", + "hash": "1aed9f4f68414a45", "files": 1 }, "hyperframes": { - "hash": "132596767485f923", + "hash": "fce43b4c3355cde9", "files": 1 }, "hyperframes-animation": { - "hash": "16ecdf00cf5cebf1", + "hash": "b982a1af9821e326", "files": 99 }, "hyperframes-cli": { - "hash": "9544d2cee786ebaf", + "hash": "f1c8c70693101e59", "files": 7 }, "hyperframes-core": { - "hash": "511a6283a5dbd7ea", + "hash": "507aecd0bb312a94", "files": 14 }, "hyperframes-creative": { - "hash": "d60c84ddca9ea6db", + "hash": "3e5bcbf46dc14427", "files": 69 }, "hyperframes-keyframes": { - "hash": "555c0cd491c40cea", + "hash": "040453e302a0e15b", "files": 3 }, "hyperframes-registry": { - "hash": "e3b389526834109d", + "hash": "5f49178cc43e100b", "files": 10 }, "media-use": { @@ -50,19 +50,19 @@ "files": 122 }, "motion-graphics": { - "hash": "0f1ac928e387a74c", + "hash": "dafcdce07d221aa4", "files": 23 }, "music-to-video": { - "hash": "5bb405421a7e19ba", + "hash": "ccb6181af8bcef09", "files": 132 }, "pr-to-video": { - "hash": "a93fde2b33b26e75", + "hash": "21dcf8aa94fc1033", "files": 22 }, "product-launch-video": { - "hash": "14404973ef5d38a0", + "hash": "158398dbfc4ab652", "files": 20 }, "remotion-to-hyperframes": { @@ -70,7 +70,7 @@ "files": 70 }, "slideshow": { - "hash": "114b57cf22b39068", + "hash": "0f0364c54f77cb9b", "files": 2 }, "talking-head-recut": { @@ -78,7 +78,7 @@ "files": 27 }, "website-to-video": { - "hash": "79af52a847abaa43", + "hash": "e8143700c50b7469", "files": 32 } } diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md index 2f965990e..a402597b7 100644 --- a/skills/faceless-explainer/SKILL.md +++ b/skills/faceless-explainer/SKILL.md @@ -177,9 +177,9 @@ Inject transitions, run checks, pause for review, then render. `npx hyperframes lint` -`npx hyperframes validate` +`npx hyperframes check` -`npx hyperframes inspect` +`npx hyperframes check` `npx hyperframes snapshot --at ` diff --git a/skills/figma/SKILL.md b/skills/figma/SKILL.md index b08f77174..605cd954d 100644 --- a/skills/figma/SKILL.md +++ b/skills/figma/SKILL.md @@ -95,7 +95,7 @@ No REST equivalent exists. You drive the MCP tools, then hand output to the pure 2b. **Validate against ground truth before calling it done — mandatory**: `export_video` on the cohort's `rootNodeId` gives Figma's own render of the timeline. Run `node skills/figma/scripts/verify-motion.mjs --reference --render --crop WxH+X+Y` — it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR (calibrated: faithful ≈ 20+, diverging ≈ 5). Measure `--crop` from the render's actual card edges, don't guess. FAIL means re-check the translation, not the threshold. 3. `motionToGsap(doc)` → `emitTimelineScript(spec)` → inject as a `