@scenerok/sdk 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/sdk",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "TypeScript-first SceneRok authoring SDK — build IRTimeline for complex agent-authored scenes",
   "type": "module",
   "main": "./dist/index.js",

package/skills/scenerok/SKILL.md

@@ -35,14 +35,15 @@ Copy this checklist into your notes and work through it:
 
 ```text
 - [ ] 1. Identify the environment (web editor, CLI, ChatGPT, MCP, chat without tools)
-- [ ] 2. Classify the request; read only the references it needs (table below)
-- [ ] 3. Branded promo with unknown colors or logo: ask once
-- [ ] 4. Probe real assets: type, width, height, duration
-- [ ] 5. Write the script
-- [ ] 6. Validate. Fix every error and validate again until clean
+- [ ] 2. Pick the closest recipe in recipes.md and read look-and-feel.md
+- [ ] 3. Gather pictures: page images, screenshots, logo, footage, or generated
+        stills (look-and-feel.md → Sourcing imagery). Probe each one; crop with ffmpeg
+- [ ] 4. Decide the look: palette, two fonts, type sizes, beats. Write them as `let`s
+- [ ] 5. Write the script from the recipe; read other references only as needed
+- [ ] 6. Validate. Fix every error and aesthetic warning; validate again until clean
 - [ ] 7. Uses TTS or generated media: deep-validate and fix the report (CLI only)
-- [ ] 8. Render
-- [ ] 9. Check the rendered MP4; fix and repeat from step 6 if it reports problems (CLI only)
+- [ ] 8. Render, pull one frame per beat, look at them, run the freeze check
+- [ ] 9. Fix what the frames show and render again. Done = the quality gate passes
 ```
 
 With the CLI:
@@ -56,9 +57,13 @@ scenerok lint-video <render-id> --cost medium --json            # billed
 
 `scenerok render script.vid --validate` renders and checks the MP4 in one step.
 
-With marketplace plugins (fastest when the user pasted structured source data):
-search, inspect, dry-run, then run a pinned ref — full workflow in
-[plugins.md](references/plugins.md):
+With marketplace plugins: search, inspect, dry-run, then run a pinned ref
+(full workflow in [plugins.md](references/plugins.md)). A plugin's output must
+pass the same quality gate. When a plugin's template is text over a flat
+colour, draft it (`scenerok plugin draft … --out draft.vid`), add the
+pictures and motion from [recipes.md](references/recipes.md), then
+`scenerok plugin render-draft <id> --vidscript draft.vid`. Today that covers
+the first-party `listing-promo` and `release-video` templates.
 
 ```bash
 scenerok plugin search "product promo"
@@ -96,6 +101,43 @@ ChatGPT, and MCP have their own validate and render calls but no deep
 validation or MP4 check, and can't read local files:
 [environments.md](references/environments.md).
 
+## Quality gate
+
+`validate` tells you the script is valid, not that the video is good. A video
+is done only when all of these hold. Text over a flat colour fails, however
+clean the script.
+
+1. **A picture under every beat.** Each beat shows a real asset (product
+   photo, screenshot, logo, footage, screen recording) or a generated image or
+   video. No beat is type on a plain colour.
+2. **Nothing stands still.** Every picture and text line has `animate:` with an
+   entrance; anything that leaves before the end also has an exit. Stills get a
+   slow push; logos float. After rendering, this prints nothing (no hold of 3 s
+   or longer; a `freeze_start` with no `freeze_end` runs to the end):
+   `ffmpeg -hide_banner -i out.mp4 -vf freezedetect=n=0.003:d=3 -map 0:v -f null - 2>&1 | grep freeze_start`
+3. **A deliberate look.** The script opens with `let` values for its palette
+   (bg, ink, muted, one accent) and its two fonts. Sizes follow the type scale
+   in [look-and-feel.md](references/look-and-feel.md): at least 44 px on a
+   1920 px tall canvas.
+4. **One grade.** `filter "cdl"` and/or `vignette` (or a LUT from an HTTPS
+   URL) spans the whole video.
+5. **Sound.** A music bed, a voiceover, or the footage's own audio, unless the
+   user asked for silence.
+6. **Validate clean.** Fix every error and every aesthetic warning, or write
+   down why a warning doesn't apply (each recipe names the warnings it accepts
+   and why).
+7. **Looked at.** Render, pull one frame per beat, open the frames, and fix what
+   you see: wrapped or colliding text, black boxes where a picture should be,
+   a fallback font, empty bands. Then render again. Validate's text sizes are
+   estimates, so only the frames show the real result.
+
+```bash
+for t in 1.5 5 9 13; do ffmpeg -loglevel error -y -ss $t -i out.mp4 -frames:v 1 frame-$t.png; done
+```
+
+Without a shell (web editor, ChatGPT, MCP), check 1-6 against the script and
+ask the user to watch the preview before you call it done.
+
 ## Rules that prevent most failures
 
 1. **Import before calling.** `import xai from "@scenerok/xai"`, then
@@ -114,6 +156,11 @@ validation or MP4 check, and can't read local files:
 6. **Use only documented syntax.** Don't invent functions or parameters. A
    validation error names the problem; fix that line rather than rewriting the
    script.
+7. **`font:` is a Google Fonts family name.** `"Inter Bold"` is not a family
+   and falls back. For heavy type use a heavy family such as
+   `"Archivo Black"`.
+8. **Crop stills with ffmpeg, not `.Crop()`.** Prepare images before you place
+   them; a cropped remote still rendered as nothing in testing.
 
 ## References
 
@@ -121,6 +168,7 @@ Read the ones the task needs. Paths are relative to this file.
 
 | Task | Read |
 | --- | --- |
+| Any video | [recipes.md](references/recipes.md) and [look-and-feel.md](references/look-and-feel.md) (always): complete product promo, release notes and talking-head scripts; palette, type scale, safe areas, motion, sourcing pictures |
 | Any VidScript | [vidscript-strict.md](references/vidscript-strict.md) (always) |
 | Editing and compositing: trims, speed, reverse, freeze, picture-in-picture, blend modes, masks, crops, split screens, audio mixing and ducking, grading and LUTs, captions, timecode | [editing-actions.md](references/editing-actions.md) |
 | Full grammar | [vidscript-guide.md](references/vidscript-guide.md) |
@@ -148,14 +196,25 @@ chat apps are there too: `consumer-chat-apps.md`,
 `chatgpt-gpt-instructions.md`, `gemini-gem-instructions.md`, `grok-skill.md`.
 Previews of every catalog item: https://scenerok.com/catalog.
 
-## Minimal VidScript
+## One beat, done properly
+
+The smallest unit that passes the gate: a real picture with a push, copy that
+enters and leaves, a grade, and sound. A video is several of these; the full
+scripts are in [recipes.md](references/recipes.md).
 
 ```vidscript
 import motion from "@scenerok/basic-animations"
 
-input hero = "https://cdn.example.com/clip.mp4"
-[0s .. 4s] = hero.Trim(1s, 5s)
-[0s .. 3s] = text "Hello", style: title, color: "#FFFFFF", area: "title", animate: motion.fadeIn(0.8s)
+let ink = "#F4F6FA"
+let display = "Archivo Black"
+
+input shot = "https://cdn.example.com/product-lifestyle.jpg"   # 1080x1920, probed
+input bed = "https://cdn.example.com/music.mp3"
+
+[0s .. 4s] = shot, width: 1080, height: 1920, x: 0, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }
+[0.2s .. 4s] = text "Cleans while you're out", font: display, size: 96, color: ink, x: "50%", y: "28%", max_width: "86%", align: center, shadow_color: "#000000", shadow_blur: 24, animate: [motion.riseIn(0.5s, 60), motion.fadeOut(0.3s)]
+[0s .. 4s] = filter "vignette", intensity: 0.3
+[0s .. 4s] = audio bed, volume: 0.5, fade_out: 0.5s
 output to "video.mp4", resolution: "1080x1920", fps: 30
 ```
 

package/skills/scenerok/references/animations-catalog.md

@@ -98,6 +98,15 @@ overlays (composite over video/scenes), honor every param, and scale to any outp
 Prefer these over hand-authoring when a headline/caption/stat treatment fits; see the
 `text-anim` rows in `animations-picker.md` for intent mapping.
 
+## Code blocks in vertical video
+
+At a 9:16 output the 12 VS Code theme `code_snippet_*` blocks and `code_diff` switch to a
+native 1080x1920 layout: no desktop chrome, ~40px type that wraps instead of shrinking, a
+line-by-line reveal with a moving focus bar and caret (a +/− count and a focus ring for
+`code_diff`), a camera that scrolls long code, and a lift-and-fade exit timed to the
+placement. Same params, same theme palettes; 16:9 is unchanged. It still reads best with
+3–12 short lines: put the one change that matters on screen, not the whole file.
+
 ## Custom HTML (bring your own animation)
 
 `animations.custom_html(...)` renders **your own HTML/CSS/JS** through the same HyperFrames

package/skills/scenerok/references/animations-picker.md

@@ -47,10 +47,13 @@ Param resolution: **named > positional > default**.
 | Block / family | Issue | Fix |
 | --- | --- | --- |
 | `code_diff` | Line indices may be 0-based in adapter | Match sample in `animations-catalog.md` |
+| Code blocks in 9:16 | Only the VS Code theme `code_snippet_*` blocks and `code_diff` have a portrait layout; `code_typing`, `code_morph`, the terminal blocks, etc. are scaled down from 16:9 and read small | Prefer `code_snippet_<theme>` / `code_diff` for vertical video; pass 3–12 short lines, not a file |
 | Unverified blocks | `scenerok validate` warns `verified:false` | Accept demo render or switch to verified family |
 | Maps / liquid-glass / app-showcase | Ignore user params | Use for demo aesthetic only, or hand-author |
 | Adapter blocks | No inline audio/text siblings | Put `audio`, `text`, `filter` on separate time blocks |
 | `logo_outro` | Renders upstream demo's Figma-style mark when no logo param given | Pass `brand: "scenerok"` or `logoUrl: "<image url>"` |
+| `code_*` and most blocks in 9:16 | Designed at 1920x1080 and scaled to fit: 56 % size with empty bands above and below (lower thirds have native 9:16 layouts) | Use them in 16:9; in 9:16 build a code card from `text` lines (`recipes.md` → Release notes) |
+| `text_counter_stat` | `suffix` defaults to `"+"`, so 12 reads "12+" | Pass `suffix: ""` unless the number really is a floor |
 
 ## Two-phase compose recipe
 

package/skills/scenerok/references/catalog-index.json

@@ -1,6 +1,6 @@
 {
   "schema": "https://scenerok.com/catalog-index/v1",
-  "generatedAt": "2026-10-26T01:38:31.092Z",
+  "generatedAt": "2026-10-27T20:44:13.966Z",
   "cdnBase": "https://assets-public.scenerok.com/catalog",
   "categories": [
     {

package/skills/scenerok/references/editing-actions.md

@@ -462,8 +462,10 @@ input a = "log-footage.mp4"
 [0s .. 4s] = filter "cdl", slope: "1.1 1 0.9", offset: "0 0 0", power: "1 1 1", saturation: 1
 ```
 
-- `filter "lut"` applies a 3D `.cube` file next to the script (512 KB at
-  most, up to 33 points per axis). Use the `filter` line, not `Filter("lut")`.
+- `filter "lut"` applies a 3D `.cube` file (512 KB at most, up to 33 points
+  per axis). Use the `filter` line, not `Filter("lut")`. A hosted compile (CLI
+  render, web, MCP) can't read a local path: give an HTTPS URL or a `data:`
+  URI, or use `cdl`.
 - `filter "cdl"` takes ASC CDL `slope`, `offset`, `power` (three numbers each)
   and `saturation`.
 

package/skills/scenerok/references/intent-router.md

@@ -29,13 +29,13 @@ Defaults unless the user says otherwise:
 
 | Workflow | Load these slugs | Primary APIs (VidScript · SDK) |
 | --- | --- | --- |
-| **Product promo** | `ai-models.md`, `text-styles.md`, `music.md`, `workflow.md`, `brand-setup.md` (+ `sdk-guide.md` if TS) | `xai.imagine` / `await xai.genVideo(...)`, `motion.popIn` / `fadeIn`, `eleven.music` |
+| **Product promo** | `recipes.md`, `look-and-feel.md`, `brand-setup.md` (+ `ai-models.md` when the page has no usable pictures, `sdk-guide.md` if TS) | page images as `input` with a scale push, `motion.riseIn` / `popIn`, `solid` CTA button, `filter "cdl"`, `eleven.music` |
 | **Motion graphic** | `animations-picker.md` (+ `animations-catalog.md` if needed) | `animations.*` (VidScript HyperFrames; prefer VidScript for catalog blocks) |
 | **Social proof card** | `animations-picker.md` | `animations.x_post`, `reddit_post`, … (VidScript) |
 | **Edit existing footage** | `editing-actions.md` (+ `media-stdlib.md` to probe the clips, `transitions-catalog.md` for cuts) | `Trim` / `Speed` / `Loop` / `Crop` / `Mask` / `Overlay` / `Composite`, `blend:`, `duck_under:`, `filter "lut"` (VidScript only) |
 | **Scene montage** | `transitions-catalog.md`, `ai-models.md` (+ `sdk-guide.md` if TS loops) | `tr.dissolve` · SDK: `import tr from '@scenerok/transitions'` + `t[start][end] = tr.dissolve()` |
 | **Narrated explainer** | `tts.md`, `text-styles.md`, `music.md`, `workflow.md` (+ `sdk-guide.md` if TS) | `xai.tts` · `await xai.tts(...)` + `t.push(vo)` |
-| **Code demo / PR** | `animations-picker.md` (code rows) | `code_typing`, `code_diff` (VidScript) |
+| **Code demo / PR / release notes** | `recipes.md` (release notes), `animations-picker.md` (code rows) | 16:9: `code_typing`, `code_diff`; 9:16: a code card of `text` lines with `motion.typewriter` (VidScript) |
 | **Text animation / headline / stat** | `animations-picker.md` (text-anim rows) | `animations.text_*` (VidScript) · SDK kinetic: `text` + `fadeIn` / `popIn` |
 | **Kinetic title only** | `text-styles.md` (+ `sdk-guide.md` if TS) | `text` + `motion.*` · SDK: `text(..., { area })` + `.animate(fadeIn(...))` |
 | **Custom-authored animation (no block fits)** | `animations-catalog.md` → "Custom HTML" | `animations.custom_html` (VidScript) |
@@ -43,7 +43,7 @@ Defaults unless the user says otherwise:
 
 ## Staged routing
 
-1. **Classify** — workflow from table above
+1. **Classify** — workflow from table above, then the matching script in `recipes.md`
 2. **Choose authoring** — VidScript by default and for every editing action (masks, blends, crops, ducking, LUTs, timecode); `@scenerok/sdk` (`sdk-guide.md`) only for loops or computed timing (it has none of the editing actions)
 3. **Load catalogs** — only what that workflow needs (conditional loading)
 4. **Name block or API** — VidScript: pick `animations.<fn>` from `animations-picker.md`. SDK: factories (`video` / `loadVideo`, `text`, `fadeIn`) + AI imports (`@scenerok/xai`, …)

package/skills/scenerok/references/look-and-feel.md

@@ -0,0 +1,139 @@
+# Look and feel
+
+Decide the look before you write a block. Declare it as `let` values at the top
+of the script and use only those values below. `recipes.md` shows the whole
+system in use.
+
+## Palette
+
+Four colours, declared once:
+
+| Name | Use | Default (dark) |
+| --- | --- | --- |
+| `bg` | Canvas and plates behind cards | `#0A0C10` |
+| `ink` | Headlines and body copy | `#F4F6FA` |
+| `muted` | Secondary lines: ratings, URLs, captions | `#A3ADBD` |
+| `accent` | One brand colour: kicker, price, bullets, CTA button, highlight bar | sampled from the brand |
+
+Sample the accent from the brand's own pixels (a button or logo on the page)
+or from `brand-setup.md`. Don't invent one. Use at most three non-neutral text
+colours (`validate` warns above that).
+
+## Type
+
+Use two families: a display face and a body face. `font:` is one Google
+Fonts family, loaded at weight 400. A weight in the name (`"Inter Bold"`,
+`"Inter Black"`) is not a family: the render falls back to a default face.
+For heavy type, use a family that is heavy at 400.
+
+Rendered and checked: `Archivo Black` (display), `Inter` (body),
+`JetBrains Mono` (code; turns `=>` into a ligature). Other single-weight
+display families: `Anton`, `Bebas Neue`.
+
+Sizes in output pixels (`size:`). `validate` flags text under 2.2 % of the
+canvas height:
+
+| Role | 1080x1920 (9:16) | 1920x1080 (16:9) |
+| --- | --- | --- |
+| Hero / price | 120-150 | 120-140 |
+| Headline | 84-104 | 72-88 |
+| Bullet / caption card | 64-72 | 48-56 |
+| Body / kicker / URL (the floor) | 44-48 | 32-36 |
+
+Kickers: body face, accent colour, `letter_spacing: 6`-`10`, all caps.
+Validate's text geometry is an estimate. A display face can run 15-20 % wider
+than it predicts, so check the rendered frame before trusting a line to fit.
+
+## Layout and safe areas
+
+- Text `x`/`y` place the text's centre (`anchor: "left"` places its
+  left-centre). Prefer `area:` when a named region fits. Use explicit pixels
+  for designed layouts like the recipes.
+- 9:16: keep copy between y 220 and y 1500 and x 72 to 1008. Feed UI covers
+  the top ~8 %, the bottom ~20 % and a right-hand icon rail.
+- 16:9: keep copy inside a 96 px margin. Put the picture on one side and the
+  copy on the other.
+- Margins: 48 px at the edge of a card; cards use `radius: 32`-`48`.
+- Show at most 3 text overlays at once, except the lines of a code card.
+
+## Pictures
+
+Every beat has a picture under its type. In order of preference:
+
+1. **Real**: product photos, logos, app screenshots, footage, screen recordings.
+2. **Generated**: `xai.image`, `xai.imageToVideo` from a real photo, `xai.imagine`
+   (`ai-models.md`; prompts forbid text).
+3. **Made**: a brand-colour glow or gradient rendered with ffmpeg (recipes →
+   Release notes), as a background behind real pictures, never as the only picture.
+
+Placing stills in a frame of a different shape:
+
+- **Card**: the still at its own aspect, `radius:` and `blend: "normal"`, on
+  a plain or blurred plate (a product on white in a 900 px card).
+- **Band + blurred fill**: a wide crop as a full-width band, over a blurred,
+  darkened 9:16 copy of the same shot. This works for small or landscape stills.
+- **Cover**: oversize the clip to fill, e.g. 16:9 into 9:16 at
+  `width: 3413, height: 1920, x: -1166`. This keeps transitions legal, which
+  `Crop` doesn't.
+
+Prepare stills with ffmpeg before you place them. Crop out baked-in
+captions, make the blurred fill, and probe the result:
+
+```bash
+ffmpeg -i in.jpg -vf "crop=W:H:X:Y,scale=1080:-2" band.jpg
+ffmpeg -i in.jpg -vf "crop=W:H:X:Y,scale=1080:1920,boxblur=40:2,eq=brightness=-0.18" fill.jpg
+sips -g pixelWidth -g pixelHeight band.jpg
+```
+
+Use `.Crop()` for video footage. A `.Crop()` on a remote still rendered as
+nothing in testing, so crop stills with ffmpeg.
+
+## Sourcing imagery
+
+Collect pictures before you write copy:
+
+| Source | How |
+| --- | --- |
+| Product page | Image URLs from `og:image`, the JSON-LD `Product.image`, Shopify `/products/<handle>.json` → `images`, Amazon `#landingImage` `data-old-hires` and the gallery `m.media-amazon.com/images/I/…` URLs |
+| Page screenshot | Browser tool at 1440x900 (desktop) and 390x844 (mobile). Crop to the hero, the price card, or the feature you name; never use a full page as a background |
+| Logo | The site's header SVG/PNG, `apple-touch-icon`, or the GitHub org avatar (`https://avatars.githubusercontent.com/u/<id>`) |
+| App or site in motion | A screen recording (QuickTime, `ffmpeg -f avfoundation`, a browser recorder) as an `input` clip |
+| Nothing usable | `xai.image` / `xai.imageToVideo` (`ai-models.md`) |
+
+Local `input` files upload with `scenerok render`. Probe every file
+(`sips`, `ffprobe`) and size placements from the measured aspect.
+
+## Files the server must read
+
+`filter "lut", file:` and `captions("…srt")` are read by the compiler. On a
+hosted compile (CLI, web, MCP) a local path fails with `local asset not
+found`. Pass an HTTPS URL or a `data:` URI, or grade with `filter "cdl"`,
+which needs no file.
+
+## Motion
+
+| Phase | Use | Timing |
+| --- | --- | --- |
+| Entrance | `motion.riseIn(0.5s, 40-80)` for copy and cards, `motion.popIn(0.4-0.6s)` for prices, buttons, logos, `motion.typewriter` for code, `motion.fadeIn(0.4s)` for secondary lines | Stagger items 0.3-0.6 s apart |
+| Hold | Stills: a push `{ type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }`. Logos and products: `motion.float(3s, 10-14)` | A static hold lasts 3 s at most |
+| Exit | `motion.fadeOut(0.3s)` on everything that leaves before the end | The last 0.3 s of the block |
+
+A push on a soft gradient doesn't count as motion: give it a still, footage,
+or a floating element to move. Fast moves can take `motion_blur:`
+(`editing-actions.md`).
+
+## Pacing
+
+- First visible picture and words by 0.3 s; the hook reads in under 1 s.
+- Beats last 2.5-4.5 s each. A 15 s promo is 4 beats; a 30 s video is 6-8.
+- One idea per beat: the hook, the product, three features, the price, and the call to action.
+- Close on the call to action for at least 2.5 s.
+
+## What premium means here
+
+- A real picture fills or anchors every beat; no beat is text on a flat colour.
+- One accent, used sparingly; everything else is ink and muted on dark (or the reverse).
+- Big type with tight copy: 3-6 words a line, never a paragraph.
+- Every element arrives, holds with a little motion, and leaves.
+- One grade ties it together: `filter "cdl"` warmth or coolness plus a `vignette` of about 0.3.
+- Sound under all of it: a music bed, a voiceover, or both.

package/skills/scenerok/references/plugins.md

@@ -7,7 +7,10 @@ cheaper than hand-composing. **Never assume which plugins exist** — discover
 them at run time; the catalog grows and changes.
 
 Plugins are the reuse-first path: check `intent-router.md` for the workflow
-match, and prefer a plugin whenever the user pasted structured source data.
+match. A plugin's video must still pass the quality gate in `SKILL.md`. Draft
+first, read the filled script, and if a beat is text over a flat colour, add
+the pictures and motion from `recipes.md` before `render-draft`. Today that
+applies to the first-party `listing-promo` and `release-video` templates.
 
 ## Workflow (MCP)
 
@@ -219,6 +222,18 @@ Notes:
    render afterwards. A failed draft costs no fee; a draft refused by the
    balance preflight costs nothing at all.
 
+## Permission grants
+
+A **third-party** plugin needs a first-run permission grant per account and per
+version before it can run or draft. The grant covers the capabilities the
+version declares (AI providers, network domains, connected accounts, host
+features) and is stored with the version's `capabilitiesHash`. The six
+`@scenerok` first-party plugins are pre-installed and never ask.
+
+| MCP result | Meaning | What to do |
+| --- | --- | --- |
+| `error.code: "permission_escalation"` (HTTP 409) | This account has not granted this version's permissions, or the version's `capabilitiesHash` changed since the last grant. `error.details.capabilities[]` lists exactly what is missing and `details.grantUrl` names the run page. | Tell the user which permissions are listed and ask them to open `details.grantUrl`, sign in, and allow them. Then call the same tool again. Do not loop on the retry and do not invent a grant. A `dryRun: true` still works and is free. |
+
 ## Reference
 
 - Environments and what they can call: `environments.md`

package/skills/scenerok/references/recipes.md

@@ -0,0 +1,221 @@
+# Recipes
+
+Three complete scripts that pass the quality gate in `SKILL.md`. Each uses
+the look system in `look-and-feel.md`. Copy the one that fits, then swap in
+your own assets, copy, and palette. Keep the structure: a picture under every
+beat, motion on everything, and a grade and sound over the whole video.
+
+## Product promo (9:16, 15 s)
+
+Four beats: hook, hero, features, then price and CTA. The images are the
+product page's own (Amazon `landingImage`, `og:image`, or JSON-LD `image`;
+see `look-and-feel.md` → Sourcing imagery). Prepare them before you write the
+script. Amazon stills are 500 px squares with baked-in captions, so crop to a
+clean region and make a blurred 9:16 backdrop from the same shot:
+
+```bash
+ffmpeg -i room.jpg -vf "crop=500:185:0:95,scale=1080:-2" room-band.jpg
+ffmpeg -i room.jpg -vf "crop=104:185:140:95,scale=1080:1920,boxblur=40:2,eq=brightness=-0.18" room-bg.jpg
+sips -g pixelWidth -g pixelHeight room-band.jpg   # 1080x398: place at 984x363
+```
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+import eleven from "@elevenlabs/music"
+
+# Look: one palette, two fonts, one accent.
+let bg = "#0A0C10"
+let ink = "#F4F6FA"
+let muted = "#A3ADBD"
+let accent = "#3D8BFF"
+let display = "Archivo Black"
+let body = "Inter"
+
+# Assets: the product page's own images, cropped and blurred with ffmpeg first.
+input hero = "hero.jpg"               # 483x472, product on white
+input roomBand = "room-band.jpg"      # 1080x398, crop of a lifestyle shot
+input roomBg = "room-bg.jpg"          # 1080x1920, same shot, blurred + darkened
+input closeBand = "closeup-band.jpg"  # 1080x368
+input closeBg = "closeup-bg.jpg"      # 1080x1920
+
+# Slow push-in for every still, so no frame is ever frozen.
+let push = { type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }
+
+# 1. Hook (0-3 s): lifestyle shot; the headline lands in the first second.
+[0s .. 3s] = roomBg, width: 1080, height: 1920, x: 0, y: 0, animate: push
+[0s .. 3s] = roomBand, width: 984, height: 363, x: 48, y: 820, radius: 36, blend: "normal", animate: [motion.riseIn(0.5s, 80), push, motion.fadeOut(0.3s)]
+[0.2s .. 3s] = text "Vacuums. Mops.\nEmpties itself.", font: display, size: 104, color: ink, line_height: 1.05, x: "50%", y: "27%", max_width: "86%", align: center, shadow_color: "#000000", shadow_blur: 24, animate: [motion.riseIn(0.6s, 50), motion.fadeOut(0.3s)]
+
+# 2. Hero (3-7 s): the product on its own white card.
+[3s .. 7s] = solid(bg)
+[3s .. 7s] = hero, width: 900, height: 880, x: 90, y: 300, radius: 48, blend: "normal", animate: [motion.fadeIn(0.4s), push, motion.fadeOut(0.3s)]
+[3.3s .. 7s] = text "ECOVACS", font: body, size: 44, color: accent, letter_spacing: 10, x: "50%", y: "64.5%", align: center, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+[3.5s .. 7s] = text "DEEBOT T30e OMNI", font: display, size: 72, color: ink, x: "50%", y: "71%", max_width: "88%", align: center, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+
+# 3. Features (7-11 s): a close-up band, then one bullet every 0.6 s.
+[7s .. 11s] = closeBg, width: 1080, height: 1920, x: 0, y: 0, animate: push
+[7s .. 11s] = closeBand, width: 984, height: 335, x: 48, y: 300, radius: 36, blend: "normal", animate: [motion.fadeIn(0.4s), push, motion.fadeOut(0.3s)]
+[7.4s .. 11s] = solid(accent, width: 24, height: 24, x: 96, y: 868, radius: 12), animate: [motion.popIn(0.4s), motion.fadeOut(0.3s)]
+[7.4s .. 11s] = text "25,000 Pa suction", font: display, size: 64, color: ink, x: 150, y: 880, anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+[8.0s .. 11s] = solid(accent, width: 24, height: 24, x: 96, y: 1028, radius: 12), animate: [motion.popIn(0.4s), motion.fadeOut(0.3s)]
+[8.0s .. 11s] = text "ZeroTangle 3.0 brush", font: display, size: 64, color: ink, x: 150, y: 1040, anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+[8.6s .. 11s] = solid(accent, width: 24, height: 24, x: 96, y: 1188, radius: 12), animate: [motion.popIn(0.4s), motion.fadeOut(0.3s)]
+[8.6s .. 11s] = text "Self-emptying dock", font: display, size: 64, color: ink, x: 150, y: 1200, max_width: "80%", anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+
+# 4. Price and CTA (11-15 s). The button is a solid with a radius under the label.
+[11s .. 15s] = solid(bg)
+[11s .. 15s] = hero, width: 560, height: 548, x: 260, y: 260, radius: 40, blend: "normal", animate: [motion.popIn(0.5s), motion.float(3s, 10)]
+[11.3s .. 15s] = text "₹44,999", font: display, size: 150, color: ink, x: "50%", y: "50%", align: center, animate: motion.popIn(0.5s)
+[11.6s .. 15s] = text "★ 4.4  ·  166 ratings", font: body, size: 48, color: muted, x: "50%", y: "58.5%", align: center, animate: motion.fadeIn(0.4s)
+[12s .. 15s] = solid(accent, width: 660, height: 132, x: 210, y: 1210, radius: 66), animate: motion.popIn(0.5s)
+[12s .. 15s] = text "Shop on Amazon", font: display, size: 56, color: "#FFFFFF", x: "50%", y: 1276, align: center, animate: motion.fadeIn(0.4s)
+
+# Grade: warm the whole frame, pull the edges down.
+[0s .. 15s] = filter "cdl", slope: "1.04 1.0 0.96", offset: "0 0 0", power: "1 1 1", saturation: 1.08
+[0s .. 15s] = filter "vignette", intensity: 0.3
+
+# Sound: a bed under everything.
+let bed = eleven.music("Bright, modern electronic product-ad bed, confident pulse, clean ending", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.5, fade_out: 1s
+
+output to "promo.mp4", resolution: "1080x1920", fps: 30, background: "#0A0C10"
+```
+
+`validate` warns `too-many-animations` at the bullets: the three bullets
+leave together on one 0.3 s fade, and the linter counts each exit as motion.
+Accept that warning here and fix any other.
+
+Variations: replace the hook band with
+`xai.imageToVideo(hero, "slow orbit around the product, …", aspect_ratio: "9:16", duration: 3)`
+for a moving hero shot (`ai-models.md`). For 16:9, use the 16:9 type scale
+and put the product on the right and the copy on the left.
+
+## Release notes / changelog (9:16, 18 s)
+
+Four beats: version hook, the one new feature as typed code with a
+highlight, a stat, and an outro. Facts come from the release body
+(`gh api repos/<owner>/<repo>/releases/latest --jq .body`); count the
+`fix`/`feat` lines rather than estimating. The logo is the project's own
+(`https://avatars.githubusercontent.com/u/<id>`, or the README image). The
+background is a brand glow made with ffmpeg:
+
+```bash
+ffmpeg -f lavfi -i "color=c=black:s=1080x1920,format=rgb24" -frames:v 1 \
+  -vf "geq=r='11+90*exp(-((X-760)^2+(Y-520)^2)/180000)':g='11+30*exp(-((X-760)^2+(Y-520)^2)/180000)':b='15+4*exp(-((X-760)^2+(Y-520)^2)/180000)'" glow.png
+```
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+import animations from "@scenerok/animations"
+import eleven from "@elevenlabs/music"
+
+let ink = "#F5F5F7"
+let muted = "#9CA3AF"
+let accent = "#FF5B11"
+let display = "Archivo Black"
+let mono = "JetBrains Mono"
+
+input glow = "glow.png"    # 1080x1920, made with ffmpeg: brand-colour glow on near-black
+input flame = "flame.png"  # 460x460 RGBA, the project's logo
+
+# Ambient layer: the background drifts for the whole video.
+[0s .. 18s] = glow, width: 1080, height: 1920, x: 0, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.15 }, easing: "linear" }
+
+# 1. Hook (0-3.5 s)
+[0s .. 3.5s] = flame, width: 460, height: 460, x: 310, y: 340, blend: "normal", animate: [motion.popIn(0.6s), motion.float(2.9s, 14), motion.fadeOut(0.3s)]
+[0.3s .. 3.5s] = text "RELEASE NOTES", font: mono, size: 44, color: accent, letter_spacing: 8, x: "50%", y: "50%", align: center, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+[0.5s .. 3.5s] = text "hono v4.13.14", font: display, size: 120, color: ink, x: "50%", y: "57%", max_width: "88%", align: center, animate: [motion.riseIn(0.6s, 60), motion.fadeOut(0.3s)]
+
+# 2. The new feature as code (3.5-10 s): headline, card, then the code types itself.
+[3.5s .. 10s] = text "NEW IN BEARER-AUTH", font: mono, size: 44, color: accent, letter_spacing: 6, x: 96, y: 300, anchor: "left", align: left, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+[3.6s .. 10s] = text "Error messages can\nreturn a Response", font: display, size: 84, color: ink, line_height: 1.1, x: 96, y: 440, anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+[4s .. 10s] = solid("#16161D", width: 960, height: 700, x: 60, y: 620, radius: 32), animate: [motion.riseIn(0.5s, 60), motion.fadeOut(0.3s)]
+# One text layer per code line: a tall multi-line block can clip. Indent with x, not spaces.
+[4.4s .. 10s] = text "bearerAuth({ token,", font: mono, size: 44, color: ink, x: 108, y: 760, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[4.9s .. 10s] = text "invalidToken: {", font: mono, size: 44, color: ink, x: 164, y: 836, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[5.4s .. 10s] = text "message: (c) =>", font: mono, size: 44, color: accent, x: 220, y: 912, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[5.9s .. 10s] = text "c.json(problem, 401),", font: mono, size: 44, color: accent, x: 276, y: 988, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[6.4s .. 10s] = text "}})", font: mono, size: 44, color: ink, x: 108, y: 1064, anchor: "left", align: left, animate: [motion.typewriter(0.3s), motion.fadeOut(0.3s)]
+# Highlight beat: a bar sweeps under the changed lines once the code is typed.
+[7.2s .. 10s] = solid(accent, width: 900, height: 158, x: 90, y: 872, radius: 16, opacity: 0.16), animate: [{ type: "slideX", from: { x: -1000 }, to: { x: 0 }, start: 0, end: 0.5, easing: "easeOutCubic" }, motion.fadeOut(0.3s)]
+[7.4s .. 10s] = text "Any content type, e.g. problem+json", font: mono, size: 44, color: muted, x: 108, y: 1220, anchor: "left", align: left, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+
+# 3. Highlight (10-14 s): one number, then three rows. suffix: "" because the block defaults to "+".
+[10s .. 14s] = animations.text_counter_stat("12", "BUG FIXES", suffix: "", accent: accent)
+[11s .. 14s] = text "serve-static: GET and HEAD only", font: mono, size: 44, color: ink, x: "50%", y: "70%", align: center, animate: [motion.riseIn(0.4s, 30), motion.fadeOut(0.3s)]
+[11.4s .. 14s] = text "css: safer url() minifying", font: mono, size: 44, color: ink, x: "50%", y: "74.5%", align: center, animate: [motion.riseIn(0.4s, 30), motion.fadeOut(0.3s)]
+[11.8s .. 14s] = text "trie-router: keep first param", font: mono, size: 44, color: ink, x: "50%", y: "79%", align: center, animate: [motion.riseIn(0.4s, 30), motion.fadeOut(0.3s)]
+
+# 4. Outro (14-18 s)
+[14s .. 18s] = flame, width: 320, height: 320, x: 380, y: 520, blend: "normal", animate: [motion.popIn(0.5s), motion.float(3s, 12)]
+[14.3s .. 18s] = solid("#1C1C24", width: 860, height: 120, x: 110, y: 950, radius: 60), animate: motion.popIn(0.5s)
+[14.3s .. 18s] = text "npm i hono@4.13.14", font: mono, size: 48, color: ink, x: "50%", y: 1010, align: center, animate: motion.fadeIn(0.4s)
+[14.8s .. 18s] = text "github.com/honojs/hono", font: mono, size: 44, color: muted, x: "50%", y: 1150, align: center, animate: motion.fadeIn(0.4s)
+
+# Grade
+[0s .. 18s] = filter "cdl", slope: "1.03 1.0 0.97", offset: "0 0 0", power: "1 1 1", saturation: 1.05
+[0s .. 18s] = filter "vignette", intensity: 0.35
+
+let bed = eleven.music("Minimal driving synth pulse for a developer product update, clean and modern", duration: 18, instrumental: true)
+[0s .. 18s] = audio bed, volume: 0.5, fade_out: 1.5s
+
+output to "release.mp4", resolution: "1080x1920", fps: 30, background: "#0B0B0F"
+```
+
+`validate` warns `crowded-text-overlays` and `too-many-animations` on the
+code card, because each code line counts as an overlay. Accept those two
+there; fix any other warning. The `code_*` catalog blocks are 1920x1080
+designs: use them in 16:9, where they fill the frame. In 9:16 they shrink to
+56 % with empty bands above and below.
+
+## Talking head with captions (9:16, 14 s)
+
+A 16:9 interview cut for a vertical feed: fill the frame by oversizing the
+clip (no `Crop`, so transitions stay legal), punch in on the key line, cut
+away to b-roll with a whip pan, and burn in short, timed caption cards.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+import animations from "@scenerok/animations"
+import tr from "@scenerok/transitions"
+
+let ink = "#FFFFFF"
+let accent = "#FFD43B"
+let display = "Archivo Black"
+
+input talk = "https://cdn.example.com/interview-16x9.mp4"  # 1920x1080, probed
+input broll = "https://cdn.example.com/broll-16x9.mp4"     # 1920x1080, probed
+input bed = "https://cdn.example.com/music.mp3"
+
+# Fill 9:16 from 16:9: scale to 1920 tall (3413 wide) and centre it, x = (1080 - 3413) / 2.
+# Cut 1: wide, with a slow push. Cut 2: punch in on the key line. Cut 3: b-roll. Cut 4: back to the speaker.
+[0s .. 4s] = talk.Trim(12s, 16s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.05 }, easing: "linear" }
+[4s .. 7s] = talk.Trim(16s, 19s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1.18 }, to: { scale: 1.22 }, easing: "linear" }
+[6.8s .. 7.2s] = tr.whip_pan()
+[7.2s .. 10s] = broll.Trim(0s, 2.8s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1.1 }, to: { scale: 1 }, easing: "linear" }
+[9.8s .. 10.2s] = tr.dissolve()
+[10.2s .. 14s] = talk.Trim(22.2s, 26s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.05 }, easing: "linear" }
+
+# Name card from the catalog (it has a native 9:16 layout).
+[0.6s .. 4s] = animations.lt_kicker_name("FOUNDER", "Asha Rao", accent: accent)
+
+# Captions: 2-4 words per card, timed to the transcript, the key words in the accent colour.
+[0.2s .. 1.4s] = text "We shipped it", font: display, size: 72, color: ink, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+[1.4s .. 2.8s] = text "in nine days", font: display, size: 72, color: accent, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+[4s .. 5.6s] = text "and it paid", font: display, size: 72, color: ink, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+[5.6s .. 7s] = text "for itself", font: display, size: 72, color: accent, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+
+# Sound: the speaker's own audio, with music ducked under it.
+[0s .. 7s] = audio talk.Trim(12s, 19s)
+[10.2s .. 14s] = audio talk.Trim(22.2s, 26s)
+[0s .. 14s] = audio bed, volume: 0.5, duck_under: talk, fade_out: 1s
+
+[0s .. 14s] = filter "cdl", slope: "1.02 1.0 0.98", offset: "0 0 0", power: "1 1 1", saturation: 1.05
+
+output to "talk.mp4", resolution: "1080x1920", fps: 30
+```
+
+With a transcript in an SRT file, `captions("talk.srt", font: display, size: 72, area: "caption")`
+replaces the caption lines (`editing-actions.md` → Text and titles). On a
+hosted render the file must be an HTTPS URL; see `look-and-feel.md` → Files the
+server must read.

package/skills/scenerok/references/shaders-filters.md

@@ -21,7 +21,7 @@ A `filter` line grades everything on screen during its window. Add `target: clip
 | `saturation` | Color intensity |
 | `brightness` | Exposure lift/drop |
 
-Use filters as optional finishing tools — do not add by default.
+Give every finished video one grade across its whole length: `cdl` for warmth or coolness plus `vignette` around 0.3 (see `look-and-feel.md`). Effect filters (`glitch`, `chromatic`, `blur`) are optional accents; don't stack them by default.
 
 ## VFX filters
 

package/skills/scenerok/references/text-styles.md

@@ -2,6 +2,11 @@
 
 `import motion from "@scenerok/basic-animations"` — use with `animate:` on `text` blocks.
 
+Fonts: `font:` is one Google Fonts family at weight 400. Names with a weight such as
+`"Inter Black"` or `"Inter Bold"` (in some catalog examples below) are not families and fall
+back to a default face in renders; use a heavy family such as `"Archivo Black"` instead.
+Type scale, palette and motion timing: `look-and-feel.md`.
+
 ## Motion primitives
 
 | Primitive | Suits | Phase |

package/skills/scenerok/references/vidscript-guide.md

@@ -11,8 +11,8 @@ Contents: Agent quick start · Program structure · Statements (input, output, l
 1. **Import every package function** — use `import xai from "@scenerok/xai"`, `import cf from "@scenerok/cloudflare"`, `import eleven from "@elevenlabs/music"`, and `import motion from "@scenerok/basic-animations"` before calling `xai.*`, `cf.*`, `eleven.*`, or `motion.*`.
 2. **Validate early** — `scenerok validate file.vid` (errors show as `Line N:C — message`).
 3. **Music package syntax** — `import eleven from "@elevenlabs/music"`, then call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`.
-4. **Copy working examples** — `vidscript-sample.md`, and the `.vid` files in the `@scenerok/cli` package's `examples/system/` (e.g. `minimal-text-reel.vid`, `ecom-product-launch.vid`, `rokmilk-chocolate-promo.vid`).
-5. **Use URL assets selectively** — if the user gives a website or product URL and browser screenshot tools are available, you can capture above-fold screenshots, product images, app screenshots, and logos for VidScript `input` assets. Do not treat screenshots as mandatory or as the only visual source.
+4. **Start from a recipe** — `recipes.md` (product promo, release notes, talking head) and the look system in `look-and-feel.md`. A finished video passes the quality gate in `SKILL.md`: a picture under every beat, motion on everything, one grade, sound.
+5. **A URL means its pictures go in the video** — when the user gives a website or product URL, use the page's own product images, logo and focused screenshots as `input` assets (`look-and-feel.md` → Sourcing imagery). Don't use a full-page screenshot as a background.
 6. **Probe asset type and dimensions** — before placing real assets, identify image vs video with `file`; inspect width, height, and duration with `ffprobe`, `sips`, or `identify`; then scale from the measured aspect ratio and set explicit `width`, `height`, `x`, and `y`.
 7. **Use still images directly** — `input` supports videos and images. Place still screenshots, logos, and product photos with `video image_input`; the renderer treats images as static clips for the block duration.
 8. **Use the full media plugin toolkit** — choose still generation, text-to-video, image-to-video, reference-to-video, video extension, TTS, and music deliberately. Do not default to only `xai.imagine`.
@@ -681,7 +681,7 @@ import motion from "@scenerok/basic-animations"
 [0s .. 5s] = filter "glitch", intensity: 0.5, animate: motion.fadeIn(1s)
 ```
 
-Filters are optional finishing tools; use them only when they improve the composition. Parameter names per filter: `editing-actions.md` → Color and finishing.
+Grade the whole video once (`cdl`, `vignette`, or a `lut`); effect filters are optional accents. Parameter names per filter: `editing-actions.md` → Color and finishing.
 
 ### Animation functions (`@scenerok/basic-animations`)
 

package/skills/scenerok/references/vidscript-strict.md

@@ -15,9 +15,9 @@ Without the owning import, calls like `xai.imagine`, `cf.video`, `xai.tts`, `ele
 
 **Never** call package functions without importing the package alias first.
 
-## Rule 2: Use URL assets selectively
+## Rule 2: A URL means its pictures go in the video
 
-A product or landing-page URL is optional source material. Capture focused, legible pieces (above-the-fold views, product shots, logos), never full-page screenshots as backgrounds, and don't invent claims. The full URL workflow is in `workflow.md`.
+When the user gives a product or landing-page URL, the video uses that page's own pictures: product shots, logos, focused screenshots. Reading only the title and price is not enough. Take focused, legible pieces, never a full-page screenshot as a background, and don't invent claims. How to collect and prepare them: `look-and-feel.md` → Sourcing imagery.
 
 ## Rule 2.5: Probe real asset type and dimensions before placement
 
@@ -211,7 +211,7 @@ let bed = eleven.music("Soft premium ad music", duration: 15, instrumental: true
 [0s .. 15s] = filter "saturation", amount: 1.12
 ```
 
-Filters are optional finishing tools, not required ingredients. Use them only when they improve the visual result. Each filter has its own parameter name (`saturation` takes `amount`, `blur` takes `radius`); a wrong name is ignored without an error. The table is in `editing-actions.md` → Color and finishing.
+Every finished video carries one grade over the whole timeline (`cdl` and/or `vignette`, or a `lut` from an HTTPS URL): see the quality gate in `SKILL.md`. Effect filters (`glitch`, `chromatic`, `blur`) stay optional. Each filter has its own parameter name (`saturation` takes `amount`, `blur` takes `radius`); a wrong name is ignored without an error. The table is in `editing-actions.md` → Color and finishing.
 
 A `filter` line grades everything in its window. To grade one clip, add `target: clip` or write `clip.Filter("sepia", intensity: 0.6)`.
 

package/skills/scenerok/references/workflow.md

@@ -2,35 +2,29 @@
 
 ## Pipeline
 
-1. **Understand the goal** — promo, testimonial, meme, code demo, etc.
+1. **Understand the goal** — promo, testimonial, meme, code demo, etc. Pick the closest script in `recipes.md`
 2. **Choose authoring** — VidScript (`.vid`) by default and for every editing action; TypeScript `@scenerok/sdk` (`.ts`, `sdk-guide.md`) only for loops or computed timing
-3. **Plan the structure** — time blocks, durations, inputs
-4. **Gather assets** — URLs, local paths, generated clips, selective website screenshots
-5. **Probe asset type and dimensions** — `loadVideo` / media stdlib, or `file` / `ffprobe` / `sips` / `identify`; never guess
-6. **Use images directly when useful** — VidScript `video image_input`; SDK `video(path)` / `loadVideo`
+3. **Plan the structure** — beats of 2.5–4.5 s, each with a picture, copy, and motion (`look-and-feel.md`)
+4. **Gather pictures** — page images, focused screenshots, logo, footage, screen recordings; generated stills or clips when nothing real exists. A video with no picture is not done
+5. **Probe and prepare** — `file` / `ffprobe` / `sips` / `identify` (or `loadVideo` / media stdlib); crop and blur stills with ffmpeg; never guess sizes
+6. **Decide the look** — palette, two fonts, and type sizes as `let` values (`look-and-feel.md`)
 7. **Choose plugin modality** — still / t2v / i2v / ref2v / extend / TTS / music (`ai-models.md`, `tts.md`, `music.md`)
 8. **Compose** — measured dimensions, `area:` / `t.grid` for text, symbolic durations (`vo.duration` / returned node `.duration`), entry/exit beats
 9. **Validate** — `scenerok validate script.vid` or `scenerok validate scene.ts`
 10. **Deep-validate (VidScript)** — for scripts with TTS/generated media: `scenerok validate script.vid --generate-assets --report-json` (billed; assets cache for the render). SDK plugins generate during `scenerok render` instead. Fix `offCanvas`/`wasShrunk` text, `collisions`, and unintended `audio.overlaps`, then re-validate.
 11. **Render** — `scenerok render script.vid --watch` or `scenerok render scene.ts --watch`
-12. **Check the render** — `scenerok lint-video <render-id> --cost medium --json` (billed); fix and re-render if it reports problems. `scenerok render script.vid --validate` does render and check in one step
-13. **Deliver** — share download URL when complete
+12. **Look at the render** — pull one frame per beat with ffmpeg and open them; run the freeze check (both commands are in the quality gate in `SKILL.md`). Fix what you see and render again. `scenerok lint-video <render-id> --cost medium --json` (billed) adds an LLM review of frame grabs
+13. **Deliver** — share the download URL once the quality gate passes
 
 ## Website URL asset workflow
 
-When the user provides a product, company, landing page, or ecommerce URL:
-
-1. Visit the URL with a browser tool before composing.
-2. Capture screenshots sparingly — above-fold, product closeups, pricing cards. Avoid full-page backgrounds.
-3. Crop to the visual evidence needed.
-4. Save product images, logos, app screenshots when accessible.
-5. Probe saved asset dimensions before composing.
-6. Use stills as timeline inputs or feed into `xai.imageToVideo` / `xai.referenceToVideo` (VidScript or SDK).
-7. Combine real assets with generated clips, text, and music.
-8. Scale from measured aspect ratio; keep primary visuals in ~80–88% frame width for 9:16.
-9. Animate assets: `motion.popIn` / SDK `popIn`, `fadeIn`, `slideY`.
-10. Generative prompts must require **no text, logos, watermarks, or readable UI** in AI output — add copy with `text`.
-11. Do not invent product claims — extract from site or ask the user.
+When the user gives a product, company, landing-page or store URL, the page's
+own pictures go in the video. Reading only the title, price and bullets is not
+enough. Collect the image URLs and focused screenshots, probe them, crop out
+baked-in captions, and place them as cards, bands over a blurred fill, or
+full-frame covers: `look-and-feel.md` → Pictures and Sourcing imagery. A worked
+example is the product promo in `recipes.md`. Don't invent product claims;
+extract them from the page or ask.
 
 ## Best practices
 
@@ -62,7 +56,9 @@ If render fails: check `scenerok status <id>`, fix missing assets or syntax, re-
 
 ## Sample video types
 
-- **Product promo** — hero + headline + CTA
+- **Product promo** — hero image, features, price + CTA (`recipes.md`)
+- **Release notes** — logo, typed code, stat, outro (`recipes.md`)
+- **Talking head** — speaker cut, punch-ins, b-roll, captions (`recipes.md`)
 - **Social hook** — fast cuts, bold text
 - **Testimonial** — speaker clip + quote overlay
 - **Meme remix** — reaction clip + punchlines