@scenerok/cli 2.2.0 → 2.4.0

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

@@ -0,0 +1,560 @@
+# Editing and compositing actions
+
+The everyday editing actions in VidScript: layering, cutting, sound, titles,
+color, and delivery. Each section shows one working spelling. Every example
+compiles as written; add an `output` line to render it.
+
+These are VidScript features. The TypeScript SDK covers clips, text, audio,
+filters, and transitions, but not masks, blends, crops, ducking, or the
+delivery keys below. For those, write the scene in VidScript; a VidScript file
+can still `import` an SDK scene and `use` it (see `vidscript-guide.md`).
+
+## Contents
+
+- Layering and compositing: picture-in-picture, blend modes, stacks, masks and
+  mattes, crop and shape, moving a group, split screens, hiding a layer
+- Cutting and timing: trim, speed, reverse, freeze, ramps, loops, back-to-back
+  cuts, frame-accurate times, transitions with handles, image sequences
+- Sound: a clip's own sound, volume and fades, J- and L-cuts, ducking, source
+  offset, pan, volume automation, loudness
+- Text and titles: per-word reveals, easing, rotation, captions
+- Color and finishing: per-clip grades, LUTs, CDL, color spaces, motion blur
+- Reuse and delivery: functions, timelines, modules, output settings, timecode
+- What VidScript can't do yet
+
+## Layering and compositing
+
+Text always draws over video. Between two video layers, say which one goes on
+top with `Overlay`, `Composite`, or `blend:`; two plain clips placed in the
+same window have no defined order.
+
+### Picture-in-picture
+
+`Overlay` puts one picture over a clip at a position (`x`, `y`, `opacity`).
+The overlaid side can be a clip, `text(…)`, `solid(…)`, or a function call:
+
+```vidscript
+input main = "interview.mp4"
+input cam = "screen.mp4"
+[0s .. 6s] = main.Overlay(cam.Resize(360, 640), x: 680, y: 60, opacity: 0.9)
+[6s .. 9s] = main.Overlay(text("LIVE", size: 48), x: 40, y: 40)
+```
+
+For rounded corners or any other placement property, place the inset as its
+own layer with `blend: "normal"`, which puts it over what is below. Placement
+properties follow any value, including a method chain; `video cam` and a bare
+`cam` are the same placement:
+
+```vidscript
+input main = "interview.mp4"
+input cam = "screen.mp4"
+[0s .. 6s] = main
+[0s .. 6s] = cam.Trim(10s, 16s), width: 360, height: 640, x: 680, y: 60, radius: 24, blend: "normal"
+```
+
+### Blend modes
+
+`blend:` blends a layer with whatever is below it in the same window. Modes:
+`normal`, `multiply`, `screen`, `overlay`, `difference`, `add`, `subtract`,
+`darken`, `lighten`.
+
+```vidscript
+input footage = "city.mp4"
+input flare = "light-leak.mp4"
+[0s .. 5s] = footage
+[0s .. 5s] = flare, blend: "screen", opacity: 0.7
+[0s .. 5s] = solid("#ff6a00", opacity: 0.25), blend: "multiply"
+```
+
+A blend with nothing below it is a compile error; place the base layer first.
+
+### Stacking composites
+
+`Composite` returns a value, so layers stack:
+
+```vidscript
+input base = "city.mp4"
+input grain = "film-grain.mp4"
+input leak = "light-leak.mp4"
+let graded = base.Composite(grain, mode: "overlay", opacity: 0.4)
+[0s .. 5s] = graded.Composite(leak, mode: "screen")
+```
+
+Both sides must overlap in time.
+
+### Masks and mattes
+
+`Mask(matte, mode:)` draws a value through a matte. The matte can be any
+picture: a `solid` shape, `text(…)`, a function, or another clip (a track
+matte). Modes: `"alpha"` (default), `"luma"`, `"inverted"`.
+
+```vidscript
+input portrait = "portrait.mp4"
+input matte = "matte.mp4"
+[0s .. 4s] = portrait.Mask(solid("#fff", x: 140, y: 560, width: 800, height: 800, radius: 400))
+[4s .. 8s] = portrait.Mask(text("SALE", size: 400))
+[8s .. 12s] = portrait.Mask(matte, mode: "luma")
+```
+
+- The matte is in output pixels, the same space as the placement: put the
+  shape where the clip appears on screen. The matte's color doesn't matter in
+  `"alpha"` mode.
+- Place the masked value (`[…] = a.Mask(…)`). `a.Mask(…)` on its own line after
+  `a` is placed is a compile error.
+- A masked clip can't be an `Overlay` or `Composite` side. Place it as its own
+  layer instead, with `blend: "normal"` to put it over another video:
+  `[0s .. 4s] = portrait.Mask(…), blend: "normal"`.
+
+### Crop, resize, rounded corners, corner pin, rotation
+
+```vidscript
+input wide = "landscape.mp4"
+input screen = "app-demo.mp4"
+[0s .. 4s] = wide.Crop(420, 0, 1080, 1920)
+[4s .. 8s] = screen, width: 900, height: 900, x: 90, y: 510, radius: 48, rotation: 4
+[8s .. 12s] = screen, corners: [[120, 400], [960, 460], [940, 1500], [140, 1440]]
+```
+
+- `Crop(x, y, width, height)` takes a rectangle in source pixels from the
+  top-left; the rectangle fills the clip's display size, so `Resize` to the
+  same aspect to avoid stretching. A second `Crop` is relative to the first.
+- `radius:` rounds the corners, in pixels.
+- `corners:` pins the picture to four output points, clockwise from top-left.
+- `rotation:` is in degrees. Positive values turn video counter-clockwise
+  (text turns the other way: see the note under Text and titles).
+
+### Move several layers as one
+
+A function that returns `video` draws as one item. Its placement takes
+`animate:`, `blend:`, `opacity:`, and the transform properties, so this is the
+camera move or the animated lower third. Times inside the body count from where
+the function is placed. Inputs declared at the top of the script aren't visible
+inside a function; pass clips in as parameters (`fn card(clip: video) -> video`).
+On a function value, `Crop`, `Filter`, `Mask`, `Opacity`, and `Resize` work;
+`Trim`, `Speed`, and `Loop` are errors.
+
+```vidscript
+input footage = "city.mp4"
+fn lowerThird(title: string) -> video {
+  [0s .. 3s] = solid("#111111", width: 800, height: 160, x: 140, y: 1500, radius: 24)
+  [0s .. 3s] = text title, size: 56, area: "lower-third", color: "#ffffff"
+}
+[0s .. 3s] = footage
+[0s .. 3s] = lowerThird("Day 1 · Goa"), animate: { type: "slideX", from: { x: -900 }, to: { x: 0 }, easing: "easeOutCubic" }
+```
+
+### Split screens
+
+Grid areas work for video as well as text. `rows` and `cols` take `%` and `fr`
+tracks; `areas` has one string per row:
+
+```vidscript
+input before = "before.mp4"
+input after = "after.mp4"
+grid rows: "1fr", cols: "1fr 1fr", areas: ["left right"]
+[0s .. 5s] = video before, area: "left"
+[0s .. 5s] = video after, area: "right"
+[0s .. 5s] = text "Before", area: "left"
+[0s .. 5s] = text "After", area: "right"
+```
+
+The grid applies to the whole script; `area:` is opt-in per placement, so
+later full-frame placements are unaffected. A video in an area is sized to the
+cell and stretched to fit, so crop it to the cell's shape first: a 1920x1080
+clip in a 960x1080 half is `before.Crop(480, 0, 960, 1080)`. Text in an area is
+centered in the cell; `area:` also works inside functions.
+
+A transition can't start from a layout of several clips. To dissolve from a
+split screen into one shot, run the layout past the cut and fade the shot in
+over it:
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+input before = "before.mp4"
+input after = "after.mp4"
+grid rows: "1fr", cols: "1fr 1fr", areas: ["left right"]
+[0s .. 5.5s] = before.Trim(0s, 5.5s).Crop(480, 0, 960, 1080), area: "left"
+[0s .. 5.5s] = after.Trim(0s, 5.5s).Crop(480, 0, 960, 1080), area: "right"
+[5s .. 10s] = after.Trim(5s, 10s), blend: "normal", animate: motion.fadeIn(0.5s)
+```
+
+### Hide a layer without deleting it
+
+```vidscript
+input footage = "city.mp4"
+input draft = "draft-overlay.mp4"
+[0s .. 5s] = footage
+[0s .. 5s] = video draft, enabled: false
+```
+
+## Cutting and timing
+
+A placed clip lasts its own length: the trimmed range divided by the speed,
+times the loop count. Make the window that long. A longer window does not hold
+the last frame (see Hold a frame below). `Speed(0)` is the exception: it holds
+for the whole window.
+
+### Trim, speed, reverse, freeze, loop
+
+Methods return a new value; chain them:
+
+```vidscript
+input clip = "surf.mp4"
+[0s .. 4s] = clip.Trim(2s, 6s)
+[4s .. 6s] = clip.Trim(10s, 14s).Speed(2)
+[6s .. 8s] = clip.Trim(2s, 4s).Speed(-1)
+[8s .. 9s] = clip.Trim(5s, 6s).Speed(0)
+[9s .. 15s] = clip.Trim(0s, 2s).Loop(3)
+```
+
+- `Trim(in, out)` plays exactly that source range. A second `Trim` is relative
+  to the first: `clip.Trim(10s, 20s).Trim(2s, 4s)` plays 12–14 s.
+- `Speed(n)`: above 1 is faster, below 1 slower, negative plays backwards,
+  `0` holds the in-point frame.
+- `Loop(n)` repeats the range `n` times.
+- Each placement is its own value: trimming the same input in several
+  placements cuts several independent pieces.
+
+### Hold a frame
+
+`Speed(0)` holds the first frame of the range for the whole window. To end on
+a freeze of the last frame, hold a range one frame long (1/fps seconds; 0.04 s
+at 25 fps) at the end:
+
+```vidscript
+input clip = "surf.mp4"
+[0s .. 4s] = clip.Trim(16s, 18s).Speed(0.5)
+[4s .. 6s] = clip.Trim(17.96s, 18s).Speed(0)
+```
+
+### Speed ramps
+
+Animate `speed` across the placement:
+
+```vidscript
+input clip = "surf.mp4"
+[0s .. 3s] = clip, animate: { type: "speed", from: { speed: 0.4 }, to: { speed: 2 }, easing: "easeInOutCubic" }
+```
+
+### Back-to-back cuts, gaps, and markers
+
+`[- 2s]` starts where the last visual block ended. `gap()` leaves an empty
+stretch; `marker("name")` records a named point (not drawn):
+
+```vidscript
+input a = "shot-a.mp4"
+input b = "shot-b.mp4"
+[- 2s] = a
+[- 0.5s] = gap()
+[- 2s] = b
+[2s .. 2s] = marker("beat drop")
+```
+
+### Frame-accurate times
+
+`48 frame` is 48 frames at the output frame rate (30 when `output` sets no
+`fps:`; a computed `fps:` is an error):
+
+```vidscript
+[0s .. 48 frame] = text "Two seconds at 24 fps"
+output to "video.mp4", resolution: "1920x1080", fps: 24
+```
+
+Timecode literals are `HH:MM:SS:FF@rate`, non-drop-frame (`;` is an error),
+FF below the rate, hours 0-23. Without `@rate` they use the literal output fps:
+
+```vidscript
+[00:00:01:12@24 .. 00:00:03:00@24] = text "1.5 s to 3 s"
+output to "video.mp4", resolution: "1920x1080", fps: 24
+```
+
+NTSC `fps:` values (23.976, 29.97, 47.952, 59.94, 119.88) are encoded at the
+exact `24000/1001` style rate, and block start/end times snap to whole frames
+of the output (`[0.1s .. 0.35s]` at 30 fps is frames 3 to 11).
+
+### Transitions and handles
+
+Transitions come from `@scenerok/transitions` (full list in
+`transitions-catalog.md`). By default the window sits between two clips. To
+dissolve across a straight cut instead, add handles: `in_offset` reads that
+much of the incoming clip before its in-point, `out_offset` that much of the
+outgoing clip past its out-point. The clips need that much spare source.
+
+A transition joins plain clips only. It is a compile error when either side is
+masked, cropped, motion-blurred, or a placed function; transition between the
+plain clips and apply those edits away from the cut.
+
+```vidscript
+import tr from "@scenerok/transitions"
+input a = "shot-a.mp4"
+input b = "shot-b.mp4"
+[0s .. 4s] = a.Trim(2s, 6s)
+[4s .. 8s] = b.Trim(2s, 6s)
+[3.8s .. 4.2s] = tr.dissolve(in_offset: 0.2s, out_offset: 0.2s)
+```
+
+### Image sequences
+
+A numbered image sequence is one input. `count:` is the number of frames;
+`rate:` defaults to the output fps; `first:` is the first file number
+(default 0):
+
+```vidscript
+input frames = "renders/shot.%04d.png", rate: 12, first: 1, count: 24
+[0s .. 2s] = frames
+```
+
+`Trim`, `Speed`, and `Loop` work on it. For cloud renders the pattern must be
+an `https` URL pattern.
+
+### Mixed frame rates
+
+`rate:` on a plain video input says what frame rate the footage runs at, for a
+timeline at another rate. Each output frame shows the source frame its time falls
+in, so 23.976 footage in a 30 fps timeline repeats frames in a 2:3-like cadence
+and never skips one:
+
+```vidscript
+input clip = "clip.mp4", rate: 23.976
+[0s .. 4s] = clip.Trim(1s, 5s)
+output to "out.mp4", resolution: "1920x1080", fps: 30
+```
+
+Write it only when the footage rate differs from `fps`. It is an error on audio
+or a still image; `first:` and `count:` stay sequence-only. A probed rate is never
+applied for you: if the probe differs from the declared rate by more than 0.1%
+the compile warns and the declared rate wins. Audio is not conformed.
+
+## Sound
+
+Every sound is an `audio` line with its own window, so J- and L-cuts need no
+special syntax: start or end the sound before or after the picture cut.
+
+### A clip's own sound, volume, and fades
+
+Video inputs are silent until you place their sound:
+
+```vidscript
+input a = "talk-a.mp4"
+input b = "talk-b.mp4"
+[0s .. 4s] = a
+[4s .. 8s] = b
+[0s .. 4s] = audio a, fade_in: 0.3s
+[3.5s .. 8s] = audio b.Trim(0s, 4.5s), volume: 0.9, fade_out: 1s
+```
+
+The second `audio` line is a J-cut: `b`'s sound starts half a second before its
+picture.
+
+### Duck music under a voice
+
+`duck_under:` lowers a bed to about a third of its volume, with short ramps,
+for the whole window in which the named track plays (it follows the track's
+time window, not speech). To duck only while someone speaks, place their
+sound in separate windows, one per line of speech. Name an `input`, or a `let`
+binding of generated speech:
+
+```vidscript
+import xai from "@scenerok/xai"
+input bed = "music.mp3"
+let vo = xai.tts("Here is what changed this week.", voice: "rex")
+[0s .. 10s] = audio bed, volume: 0.6, duck_under: vo, fade_out: 1.5s
+[1s .. 1s + vo.duration] = audio vo
+```
+
+### Start partway into a file, pan, and automate volume
+
+```vidscript
+input song = "song.mp3"
+input sfx = "whoosh.wav"
+[0s .. 8s] = audio song, trim_start: 30, animate: { type: "volume", from: { volume: 0 }, to: { volume: 0.8 }, start: 0, end: 3 }
+[2s .. 3s] = audio sfx, pan: -0.6
+```
+
+- `trim_start:` (seconds) or `song.Trim(30s, 38s)` starts the file 30 s in.
+- `pan:` runs from -1 (left) to 1 (right).
+- `animate: { type: "volume", … }` changes the level over time.
+
+### Even loudness
+
+```vidscript
+input voice = "raw-voiceover.wav"
+[0s .. 10s] = audio voice, loudness: "ebu-r128"
+```
+
+Generated speech and music are already normalized to broadcast loudness;
+use `loudness: "ebu-r128"` for your own recordings. It is the only value.
+
+## Text and titles
+
+```vidscript
+[0s .. 2.5s] = text "Built for speed", area: "title", stagger: "word", animate: { type: "slideY", from: { y: 40, opacity: 0 }, to: { y: 0, opacity: 1 }, easing: "spring" }
+[2.5s .. 5s] = text "NEW", size: 120, rotation: -8, anchor: "top-left", x: "8%", y: "12%"
+[0s .. 8s] = captions("talk.srt", size: 40, area: "caption")
+```
+
+- `style:` is `title` (64 px), `subtitle` (54), `caption` (36), or `default` (48).
+- Text without `x`, `y`, or `area:` is centered on the frame.
+- `stagger: "word"` or `"char"` reveals the text in pieces over the animation.
+- Easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`,
+  `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeOutBack`, `spring`.
+- `rotation:` turns text around its `anchor:`; a positive value turns static
+  text clockwise, the opposite of video. Check the preview when direction
+  matters.
+- `captions("file.srt", …)` makes one text layer per cue from a SubRip file;
+  the other arguments style every cue.
+
+For catalog text effects (word cascades, counters, kinetic type), see
+`animations-picker.md`.
+
+## Color and finishing
+
+`filter` without `target:` grades everything in its window. To grade one
+clip, add `target:` or use the `Filter` method; inside a function it grades
+only that function's picture.
+
+```vidscript
+input a = "shot-a.mp4"
+input b = "shot-b.mp4"
+[0s .. 4s] = a
+[0s .. 4s] = filter "sepia", intensity: 0.6, target: a
+[4s .. 8s] = b.Filter("saturation", amount: 1.2)
+[4s .. 8s] = filter "vignette", intensity: 0.3
+```
+
+Filters that change each pixel on its own can target one clip: `sepia`,
+`monochrome`, `contrast`, `saturation`, `brightness`, `vignette`, `premultiply`, `lut`, `cdl`.
+Filters that sample neighbouring pixels (`blur`, `glitch`, `chromatic`, and the
+VFX in `shaders-filters.md`) can't take `target:`. To blur only part of the
+picture, put the clip and the filter in a function; the filter stays inside it:
+
+```vidscript
+input speaker = "speaker.mp4"
+fn blurred(clip: video) -> video {
+  [0s .. 6s] = clip
+  [0s .. 6s] = filter "blur", radius: 8
+}
+[0s .. 6s] = blurred(speaker.Trim(0s, 6s))
+[0s .. 6s] = text "Sharp on top", area: "title"
+```
+
+Each filter reads its own parameter names; any other name is ignored without
+an error, so use these:
+
+| Filter | Parameter (default) |
+| --- | --- |
+| `sepia`, `monochrome` | `intensity`, 0–1 |
+| `vignette`, `glitch` | `intensity` (0.5) |
+| `contrast`, `saturation` | `amount`, a multiplier (contrast 1.2, saturation 1.5; 1 is unchanged) |
+| `brightness` | `amount`, added to each channel (0.1; 0 is unchanged) |
+| `blur` | `radius` in pixels (5) |
+| `chromatic` | `offset` (0.02) |
+| `lut` | `file` |
+| `cdl` | `slope`, `offset`, `power`, `saturation` |
+| `premultiply` | none: multiplies color by alpha, for footage with straight alpha |
+
+### LUTs and CDL
+
+```vidscript
+input a = "log-footage.mp4"
+[0s .. 4s] = a
+[0s .. 4s] = filter "lut", file: "look.cube", target: a
+[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 "cdl"` takes ASC CDL `slope`, `offset`, `power` (three numbers each)
+  and `saturation`.
+
+### Color spaces and motion blur
+
+```vidscript
+input a = "acescg-plate.mp4"
+input logo = "logo.png"
+[0s .. 3s] = video a, input_colorspace: "ACEScg", output_colorspace: "sRGB"
+[0s .. 3s] = video logo, width: 300, height: 300, x: 390, y: 800, animate: { type: "slideX", from: { x: -400 }, to: { x: 390 }, easing: "easeOutCubic" }, motion_blur: { shutter: 180, samples: 8 }
+```
+
+- Color spaces: `sRGB`, `Rec.709` (or `rec709`), `Display P3`, `ACEScg`,
+  `Linear`, `Gamma 2.2` (or `gamma22`).
+- `motion_blur: true` (or `{ shutter, samples }`) blurs an item's own
+  `animate:` movement. Each sample is another render of the frame, so use
+  it on fast moves only. It errors on text, solids, captions, and clips inside
+  a transition.
+
+## Reuse and delivery
+
+### Functions, timelines, and modules
+
+```vidscript
+input product = "product.png"
+export fn card(title: string, accent: string = "#ff5500") -> video {
+  [0s .. 2s] = solid(accent, opacity: 0.85)
+  [0s .. 2s] = text title, area: "title", color: "#ffffff"
+}
+export timeline intro(clip: video) {
+  [- 2s] = clip
+}
+[0s .. 2s] = card("Spring drop")
+[2s .. 4s] = card(title: "Free shipping", accent: "#0f766e")
+use intro at 4s .. 4s with { clip: product }
+```
+
+- Arguments are checked at the call: a missing, unknown, or wrong-kind
+  argument is a compile error that names it.
+- `-> video` draws as one item; a `timeline` body's items join the caller.
+- `import brand from "./brand.vid"` loads another file's exports
+  (`brand.card("Hi")`).
+
+### Output settings and timecode
+
+```vidscript
+input a = "master.mp4"
+[0s .. 10s] = a
+output to "master.mp4", resolution: "1920x1080", fps: 25, codec: "h264", bitrate: "8M", start_timecode: "01:00:00:00", burn_in: "timecode"
+```
+
+`start_timecode` is `HH:MM:SS:FF` and its frame field must be below `fps`.
+`burn_in: "timecode"` draws the running timecode on the picture.
+
+### Offline media
+
+```vidscript
+input a = "shot-a.mp4"
+input b = "shot-b.mp4"   # not delivered yet
+[0s .. 4s] = a
+[4s .. 8s] = b
+output to "draft.mp4", resolution: "1920x1080", fps: 25, allow_offline: true
+```
+
+With `allow_offline: true`, an input whose file is missing at compile time becomes an offline clip (OTIO `MissingReference`): it keeps its place and source path, lasts the block or `Trim` length, and draws as a flat `#2b2b2b` slate labelled `MEDIA OFFLINE` and the input name. `Resize`, `x`/`y`, `opacity` and `animate:` still apply. Its sound is dropped with a warning, and a transition at its seam is an error. Without the option a missing local file is a compile error. Media that disappears only at render time still fails the render.
+
+## What VidScript can't do yet
+
+Don't try to work around these. Tell the user when a request needs one.
+
+| Request | Today |
+| --- | --- |
+| Two aspect ratios from one script | Two `output` statements compile to two canvases, but only the local headless renderer renders both (one file per output). The render queue (web app, CLI, API) rejects a script with more than one `output` before billing, so write one script per format for a hosted render. |
+| Transparent video (alpha) | `alpha: true` is a compile error; renders are H.264 MP4. |
+| Multicam angle switching | No syntax. Cut between the angle clips with time blocks. |
+| Mixed frame rates | A timeline has one frame rate, the output `fps`. |
+| `repeat n { … }` and named tracks | Not in the language. Use a function or timeline and `use` it per repeat. |
+| Formats other than H.264 MP4 | `format:` and `codec:` are accepted, but every render is H.264 MP4 today. |
+| Rectangle and ellipse primitives | Use `solid(…)` with `width`, `height`, and `radius:` (a circle when the solid is square and `radius` is half its width), or `corners:` for a four-point shape. |
+
+## Compiles, but does nothing
+
+These pass validation and are silently ignored. Avoid them:
+
+- A filter parameter the filter doesn't have (`filter "saturation", value: 1.2`); use the table above.
+- An easing that isn't in the list (`easing: "easeOutElastic"` runs linear).
+- `animate: { keyframes: [...] }`: the points are dropped. For a path with
+  more than two points, list two-point segments with absolute `start` / `end`:
+
+```vidscript
+[0s .. 2s] = text "Path", animate: [{ type: "slideX", from: { x: 0 }, to: { x: 300 }, start: 0, end: 1 }, { type: "slideX", from: { x: 300 }, to: { x: 120 }, start: 1, end: 2 }]
+```
+
+- `Overlay(…, radius: …)`: use a placement with `blend: "normal"` (Picture-in-picture above).

package/skills/{remote → scenerok/references}/environments.md

@@ -11,33 +11,33 @@ SceneRok skills are shared across several runtimes. **Detect where you are runni
 | ChatGPT Actions, OAuth to SceneRok, `openaiFileIdRefs` | **ChatGPT GPT** | `validateVidscript` → `renderVideo`; import uploads first |
 | Gemini Gem or Grok Skill; may lack HTTP tools | **Consumer chat (limited)** | Compose VidScript; user renders elsewhere if no API |
 | `scenerok-mcp` tools (`scenerok_validate_vidscript`, `scenerok_render_video`, …) or remote `https://mcp.scenerok.com/mcp` | **MCP host** | MCP tools instead of raw CLI |
-| Reading bundled `SKILL.md` only | **Router-only** | Fetch remote docs from index (next section) |
+| Only `SKILL.md` text available, no `references/` files | **Router-only** | Fetch references from the base URL below |
 
 When unsure, ask one clarifying question: *"Are we in the SceneRok editor, your terminal, or a chat app like ChatGPT?"*
 
-## Remote doc loading (router-only / desktop)
+## Loading references
 
-1. Fetch `https://scenerok.com/.well-known/agent-skills/index.json`
-2. **Always load** `vidscript-strict.md` and `intent-router.md`
-3. Load `environments.md` (this file) on first turn
-4. Conditionally load catalogs per `intent-router.md`
-5. Offline: `scenerok skills sync` then read local skill directory
-6. Freshness: `scenerok skills check` · update: `scenerok skills update`
-
-Base URL: `https://scenerok.com/.well-known/agent-skills/{filename}`
+- **Installed skill** (`scenerok skills install <platform>`, or the copy inside the `@scenerok/cli` or `@scenerok/sdk` npm package): read `references/<file>` next to `SKILL.md`.
+- **Router-only:** fetch `https://scenerok.com/.well-known/agent-skills/<file>`; the list is at `https://scenerok.com/.well-known/agent-skills/index.json`.
+- **Freshness:** `scenerok skills check` · refresh: `scenerok skills update`
 
 ## Capability matrix
 
-| Capability | Web editor | CLI / MCP | ChatGPT Action | Gemini / Grok (no API) |
-| --- | --- | --- | --- | --- |
-| Edit VidScript in place | `patch_vidscript` | Write `.vid` / `.ts` file | Return script to user | Return script |
-| Validate | Editor API (VidScript) | `scenerok validate` (`.vid` or `.ts`) | `validateVidscript` (+ `language` for SDK) | Explain only |
-| Render | Editor UI / API (VidScript) | `scenerok render` (`.vid` or `.ts`) | `renderVideo` + poll | Instruct user |
-| Shell / ffprobe / sips | No | Yes | No | No |
-| Browse product URL | If browser tool | If browser tool | Limited | Limited |
-| User asset library | Yes (logged in) | Via URLs / uploads | Via `importOpenAIConversationFiles` | Ask for public URLs |
-| Ask brand questions | Yes (chat) | Yes (terminal) | Yes (chat) | Yes (chat) |
-| OAuth / API tokens | Session cookie | `scenerok auth login` | OAuth per user | Manual token fallback |
+| Capability | Web editor | CLI | MCP | ChatGPT Action | Gemini / Grok (no API) |
+| --- | --- | --- | --- | --- | --- |
+| Edit VidScript in place | `patch_vidscript` | Write `.vid` / `.ts` file | Pass the script as a string | Return script to user | Return script |
+| Validate | Editor API (VidScript) | `scenerok validate` (`.vid` or `.ts`) | `scenerok_validate_vidscript` (`language: "typescript"` for SDK) | `validateVidscript` (+ `language` for SDK) | Explain only |
+| Deep-validate with generated assets | No | `--generate-assets --report-json` | No | No | No |
+| Render | Editor UI / API (VidScript) | `scenerok render` (`.vid` or `.ts`) | `scenerok_render_video` + `scenerok_check_render_status` | `renderVideo` + poll | Instruct user |
+| Check the rendered MP4 | No | `scenerok lint-video` | No | No | No |
+| Local files (`input "./x.mp4"`, `file: "look.cube"`, `import "./brand.vid"`) | No; library URLs | Yes | No; public URLs only | No; imported files | No |
+| Shell / ffprobe / sips | No | Yes | Only if the host has a shell | No | No |
+| Browse product URL | If browser tool | If browser tool | If browser tool | Limited | Limited |
+| User asset library | Yes (logged in) | Via URLs / uploads | Via URLs | Via `importOpenAIConversationFiles` | Ask for public URLs |
+| Ask brand questions | Yes (chat) | Yes (terminal) | Yes | Yes (chat) | Yes (chat) |
+| OAuth / API tokens | Session cookie | `scenerok auth login` | Configured in the MCP server | OAuth per user | Manual token fallback |
+
+Where deep validation or the MP4 check isn't available, validate, render, and review the result with the user instead.
 
 ## Environment-specific rules
 
@@ -49,10 +49,9 @@ Base URL: `https://scenerok.com/.well-known/agent-skills/{filename}`
 
 ### Desktop agent (CLI / Cursor / Claude Code / Codex)
 - Run `scenerok validate` before every render (`.vid` or `.ts`).
-- Prefer `@scenerok/sdk` for agent-authored complex scenes; VidScript for short human edits.
+- Write VidScript by default and for every editing action; use `@scenerok/sdk` only for loops or computed timing.
 - Probe local assets with `loadVideo` / media stdlib, or `file` / `ffprobe` / `sips` / `identify` before placement.
-- Install router: `scenerok skills install <platform> [--sync]`
-- Full offline bundle: `scenerok skills sync`
+- Install the skill: `scenerok skills install <platform>` (claude, codex, cursor, opencode, aider)
 
 ### ChatGPT GPT
 - Load `consumer-chat-apps.md` and `chatgpt-gpt-instructions.md` for OAuth and file import.
@@ -69,5 +68,5 @@ Base URL: `https://scenerok.com/.well-known/agent-skills/{filename}`
 | --- | --- | --- |
 | `scenerok render ...` | Use editor render | Use `renderVideo` action |
 | `scenerok auth login` | N/A (session) | OAuth instead |
-| Fetch remote skill URLs | Already inlined locally | Fetch if network tool exists |
+| Fetch reference URLs | Already inlined locally | Fetch if a network tool exists |
 | Local file paths in VidScript | Use library HTTPS URLs | Use imported asset URLs |