@scenerok/cli 2.2.0 → 2.4.0

package/skills/{remote → scenerok/references}/vidscript-strict.md

@@ -1,6 +1,6 @@
 # VidScript v2 — Strict Agent Reference
 
-Follow these rules exactly. When in doubt, fetch `vidscript-sample.md` from https://scenerok.com/.well-known/agent-skills/ or run `scenerok skills sync` for local copies.
+Follow these rules exactly. For a complete working script, see `vidscript-sample.md`; for cuts, layering, masks, audio mixing, and grading, see `editing-actions.md`.
 
 ## Rule 1: Package imports are mandatory
 
@@ -17,11 +17,7 @@ Without the owning import, calls like `xai.imagine`, `cf.video`, `xai.tts`, `ele
 
 ## Rule 2: Use URL assets selectively
 
-When the user gives a product, company, ecommerce, landing page, or app URL and you have browser/screenshot capability, you can visit the page and capture useful visual evidence. Favor above-fold screenshots, product views, app screenshots, pricing/offer cards, testimonials, and detectable logos or brand marks.
-
-Do not use full-page or very long website screenshots as video backgrounds; their text is usually illegible at output size. Crop or frame screenshots to the specific visual proof point, and use them sparingly.
-
-Website screenshots are optional source material, not a requirement to build the whole video from screenshots. You may combine them with still generation, text-to-video, image-to-video, reference-to-video, or extension plugins for lifestyle scenes, motion backgrounds, transitions, or product context. Do not invent claims; use website copy or ask the user.
+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`.
 
 ## Rule 2.5: Probe real asset type and dimensions before placement
 
@@ -37,6 +33,8 @@ identify asset.webp
 Use real video files for motion footage and still image inputs for screenshots, logos, product photos, and brand marks. The `video` primitive accepts both videos and images; image inputs render as static clips for the block duration.
 
 ```vidscript
+import motion from "@scenerok/basic-animations"
+
 input screenshot = "assets/screenshots/homepage.png"
 [0s .. 4s] = video screenshot, width: 1080, height: 1920, x: 0, y: 0, animate: motion.fadeIn(0.35s)
 ```
@@ -53,6 +51,7 @@ Add entry motion to real assets, not only text. When a static visual needs a cle
 ```vidscript
 import motion from "@scenerok/basic-animations"
 
+input product = "assets/product.png"
 [0s .. 3.4s] = video product, width: 760, height: 615, x: 160, y: 300, animate: [motion.riseIn(0.6s, 70), motion.float(2.4s, 8)]
 [3.4s .. 4s] = video product, width: 760, height: 615, x: 160, y: 300, animate: motion.fadeOut(0.6s)
 ```
@@ -64,8 +63,10 @@ AI-generated images and videos must not contain readable text. In every prompt f
 Good prompt pattern:
 
 ```vidscript
+import xai from "@scenerok/xai"
+
 [-] = video xai.imagine("Clean cinematic product background, premium lighting, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 5)
-[0.5s .. 3s] = text "Launch offer", style: title, color: "#FFFFFF", x: "50%", y: "30%", stroke: "#000000", stroke_width: 3
+[0.5s .. 3s] = text "Launch offer", style: title, color: "#FFFFFF", area: "title", stroke: "#000000", stroke_width: 3
 ```
 
 Invalid: asking the generator for signs, labels, packaging text, app UI text, title cards, lower thirds, prices, CTA buttons, or any readable copy.
@@ -101,13 +102,9 @@ Do not overuse one plugin function. Choose deliberately:
 | Voiceover | `xai.tts`, `xai.textToSpeech` |
 | Music bed | `eleven.music`, `eleven.generateMusic`, `eleven.composeMusic` |
 
-Use `imageToVideo` for one extracted screenshot/product/logo image. Use `referenceToVideo` for 1-7 reference images when extracted objects should guide the generated shot. xAI `referenceToVideo` requires a prompt and duration must be <= 10s.
+Use `imageToVideo` for one extracted screenshot/product/logo image and `referenceToVideo` for 1–7 reference images (xAI: prompt required, duration ≤ 10s). Cloudflare calls take an explicit `model:` and `aspect_ratio:`; models, signatures, and durations are in `ai-models.md` and the plugin table in `vidscript-guide.md`.
 
-For Cloudflare calls, always prefer explicit `model:` and use `aspect_ratio: "9:16"` for vertical, `"16:9"` for wide, `"1:1"` for square, or model-supported values such as `"4:3"`, `"3:4"`, and `"21:9"`. `cf.imageToVideo(image, prompt, model: ..., aspect_ratio: ..., duration: ...)` accepts `aspect_ratio`; for Runway Gen-4.5, SceneRok translates `"9:16"` to Cloudflare's required `ratio: "720:1280"`. Useful models include `pixverse/v6`, `vidu/q3-turbo`, `runwayml/gen-4.5`, `minimax/hailuo-2.3`, `bytedance/seedance-2.0`, `google/veo-3.1`, `google/veo-3.1-fast`, `google/veo-3-fast`, `black-forest-labs/flux-2-pro-preview`, and `openai/gpt-image-2`. Veo models accept `duration: 4`, `duration: 4s`, or `duration: "4s"` — all forms snap to the supported 4s/6s/8s durations.
-
-xAI TTS voices are only `eve`, `ara`, `rex`, `sal`, and `leo`.
-
-For ElevenLabs music, import `@elevenlabs/music` and use `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Do not call `eleven.tts(...)`; ElevenLabs TTS is not registered in VidScript today. Ads, promos, tutorials, and reels should normally include either `xai.tts` voiceover, an ElevenLabs music bed, or both unless the user asks for silent output.
+xAI TTS voices are only `eve`, `ara`, `rex`, `sal`, and `leo`. ElevenLabs is music only (`eleven.music`, `eleven.generateMusic`, `eleven.composeMusic`); there is no `eleven.tts`. Ads, promos, tutorials, and reels should normally have a voiceover, a music bed, or both unless the user asks for silence.
 
 ## Rule 4.5: `[-]` uses separate audio and visual playheads
 
@@ -129,16 +126,20 @@ Use explicit ranges when you need exact synchronization, overlaps, or cuts. Do n
 
 ## Rule 4.6: Never guess generated-asset durations
 
-Invalid — the real TTS length is unknown at write time, so a guessed window clips or overlaps:
+Avoid — the real TTS length is unknown at write time, so a guessed window clips or overlaps:
+
+```vidscript avoid
+import xai from "@scenerok/xai"
 
-```vidscript
 [0s .. 3s] = audio xai.tts("A sentence that may well run past three seconds", voice: "eve")
 [3s .. 6s] = audio xai.tts("This one starts while the first is still playing", voice: "eve")
 ```
 
-Valid — assign with `let` and reference the measured `duration` (arithmetic allowed), or use `[-]` auto blocks:
+Do this — assign with `let` and reference the measured `duration` (arithmetic allowed), or use `[-]` auto blocks:
 
 ```vidscript
+import xai from "@scenerok/xai"
+
 let vo1 = xai.tts("First line", voice: "eve")
 let vo2 = xai.tts("Second line", voice: "eve")
 [0 .. vo1.duration] = audio vo1
@@ -207,10 +208,12 @@ let bed = eleven.music("Soft premium ad music", duration: 15, instrumental: true
 
 ```vidscript
 [0s .. 15s] = filter "vignette", intensity: 0.3
-[0s .. 15s] = filter "saturation", value: 1.12
+[0s .. 15s] = filter "saturation", amount: 1.12
 ```
 
-Filters are optional finishing tools, not required ingredients. Use them only when they improve the visual result. `saturation` uses `value`, not `intensity`.
+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.
+
+A `filter` line grades everything in its window. To grade one clip, add `target: clip` or write `clip.Filter("sepia", intensity: 0.6)`.
 
 ## Rule 10: Always end with output
 
@@ -220,6 +223,24 @@ output to "video.mp4", resolution: "1080x1920", fps: 30
 
 Do **not** use legacy `config { }` blocks — they are not part of VidScript v2.
 
+## Rule 11: Edits are values — place the result
+
+`Trim`, `Speed`, `Loop`, `Crop`, `Resize`, `Mask`, `Filter`, `Overlay`, and `Composite` return a new value. Place the result in one line:
+
+```vidscript
+input hero = "hero.mp4"
+input logo = "logo.png"
+[0s .. 4s] = hero.Trim(2s, 6s).Crop(420, 0, 1080, 1920)
+[4s .. 8s] = hero.Trim(6s, 10s).Overlay(logo.Resize(200, 200), x: 840, y: 60)
+```
+
+- A placed value lasts its own length (trimmed range ÷ speed × loops). Make the window that long.
+- Put one video over another with `Overlay`, `Composite`, or `blend:`. Two plain clips in the same window have no defined order.
+- `Mask` on its own line after the clip is placed is a compile error.
+- Frame counts are written `48 frame` and use the output fps (30 if `output` has none). Timecodes are `01:00:02:12@24` (`@rate` optional; non-drop-frame only). Block times snap to the output frame grid; NTSC fps (23.976, 29.97) encodes at the exact rational rate.
+
+All editing actions (masks, speed ramps, ducking, LUTs, timecode): `editing-actions.md`.
+
 ## Animations (after import)
 
 ```vidscript
@@ -240,12 +261,6 @@ Each error line includes `Line N:C — message` when the server returns location
 
 ## Bundled examples
 
-| File | Use case |
-|------|----------|
-| `minimal-text-reel.vid` | Text-only, no API keys |
-| `product-launch.vid` | User video input + text + vignette |
-| `ecom-product-launch.vid` | xAI product visuals + CTA |
-| `3-tips-fitness.vid` | Multiple `[-]` blocks + xAI per segment |
-| `rokmilk-chocolate-promo.vid` | 15s generated-video promo pattern |
+The `@scenerok/cli` npm package ships working scripts in `examples/system/`: `minimal-text-reel.vid` (text only), `product-launch.vid` (your own video + text), `ecom-product-launch.vid` (generated product visuals + CTA), `3-tips-fitness.vid` (several `[-]` blocks), `rokmilk-chocolate-promo.vid` (15 s generated promo).
 
-Full grammar: `vidscript-guide.md` or https://scenerok.com/.well-known/agent-skills/vidscript-guide.md
+Full grammar: `vidscript-guide.md`.

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

@@ -3,7 +3,7 @@
 ## Pipeline
 
 1. **Understand the goal** — promo, testimonial, meme, code demo, etc.
-2. **Choose authoring** — short/human → VidScript (`.vid`); complex/agent → TypeScript `@scenerok/sdk` (`.ts`, see `sdk-guide.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
@@ -13,7 +13,8 @@
 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. **Deliver** — share download URL when complete
+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
 
 ## Website URL asset workflow
 
@@ -50,11 +51,9 @@ scenerok validate scene.ts
 scenerok render script.vid --watch
 scenerok render scene.ts --watch
 scenerok status <render-id>
-scenerok skills install <platform>   # installs router skill
-scenerok skills sync                 # download full remote skill bundle
-scenerok skills check [--json]
-scenerok skills update
-scenerok secrets set KEY=VALUE
+scenerok skills install <platform>   # installs the skill (SKILL.md + references)
+scenerok skills check [--json]       # is the installed copy current?
+scenerok skills update               # refresh it from scenerok.com
 ```
 
 ## Error handling

package/skills/remote/sdk-guide.md

@@ -1,201 +0,0 @@
-# @scenerok/sdk — TypeScript authoring for complex scenes
-
-Use **TypeScript + `@scenerok/sdk`** when the scene needs loops, branches, arithmetic timing, or data-driven composition. Keep **VidScript** for short human-authored promos and templates.
-
-Both paths emit the same `IRTimeline`. Preview and render (Pass 2) are unchanged.
-
-## When to choose which
-
-| Signal | Language |
-|--------|----------|
-| Short promo, human edit, template placeholders | VidScript (`.vid`) |
-| Loop over clips, computed `start`/`end`, agent-authored complex timeline | TypeScript + `@scenerok/sdk` (`.ts`) |
-
-## Schedule syntax
-
-JavaScript has no `t[0, end]` dual key (comma operator collapses to one index). Use dual-index assignment:
-
-```ts
-import { timeline, loadVideo, text, audio, s, fadeIn } from '@scenerok/sdk'
-
-export default async function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
-  const scene1 = await loadVideo('./hero.mp4')
-
-  t[0][scene1.duration] = scene1.animate(fadeIn(s(0.4)))
-  t['0s']['3s'] = text('Hello', { size: 72 })
-  t[scene1.duration][scene1.duration + s(2)] = text('Next')
-  t.push(audio('./bed.mp3', { duration: 7, volume: 0.4 }))
-
-  return t.toIR()
-}
-```
-
-| Form | Meaning |
-|------|---------|
-| `t[start][end] = value` | Preferred dual-index schedule |
-| `t.range(start, end, value)` | Explicit call (no Proxy) |
-| `t['-'] = value` / `t.push(value)` | Auto-append at playhead |
-
-`start` / `end` accept numbers (seconds), `s(3)` / `ms(300)`, or strings (`'3s'`, `'1:30'`). Full JS arithmetic works.
-
-No `video` / `text` keywords after `=` — factories return typed values and the runtime infers IR kind.
-
-Use `loadVideo(path)` / `loadAudio(path)` to probe duration through the media stdlib when `duration` is omitted:
-
-```ts
-const clip = await loadVideo('./hero.mp4')
-t[0][clip.duration] = clip
-```
-
-Use the sync `video(path, { duration })` / `audio(path, { duration })` factories when you already know the timing.
-
-## Grid areas
-
-Same CSS-grid regions as VidScript. Declare a grid on the timeline, then place text with `area:`:
-
-```ts
-import { timeline, text, s } from '@scenerok/sdk'
-
-export default function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
-
-  t.grid({
-    rows: '20% 1fr 30%',
-    cols: '1fr 1fr',
-    areas: ['title title', 'left right', 'caption caption'],
-  })
-
-  t[0][s(3)] = text('BIG SALE', { size: 72, area: 'title' })
-  t[0][s(3)] = text('Left column', { size: 40, area: 'left' })
-
-  return t.toIR()
-}
-```
-
-Without `t.grid(...)`, `area: 'title' | 'stage' | 'lower-third' | 'caption'` uses the built-in social-video preset (portrait vs landscape). Explicit `x` / `y` / `maxWidth` / `maxHeight` override the area.
-
-Helpers also available: `resolveGridAreas`, `defaultGridSpec`, `placeInArea`.
-
-Same semantics as VidScript `grid rows: ..., areas: [...]` — see `vidscript-guide.md` → Grid Areas.
-
-## Transitions
-
-Same `@scenerok/transitions` package as VidScript. Schedule a transition window between abutting clips; `toIR()` binds `fromId` / `toId` automatically:
-
-```ts
-import { timeline, video } from '@scenerok/sdk'
-import tr from '@scenerok/transitions'
-
-export default function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
-
-  t[0][5] = video('./a.mp4', { duration: 5 })
-  t[5][5.6] = tr.dissolve()
-  t[5.6][10] = video('./b.mp4', { duration: 4.4 })
-
-  // Or auto-append with catalog default (0.6s):
-  // t.push(tr.push({ direction: 'right' }))
-
-  return t.toIR()
-}
-```
-
-Common options: `direction`, `ease`, `strength`, `mode` (`roll` | `freeze`). Full catalog: `transitions-catalog.md`.
-
-## Entry contract
-
-Export `default async function main()` (or sync `main`) that returns either:
-
-- `t.toIR()`, or
-- an `IRTimeline` object
-
-`async main` is supported so you can `await loadVideo(...)`, `await getVideoLength(...)`, or `await grabFrame(...)`.
-
-## Validate / render
-
-```bash
-scenerok validate scene.ts
-scenerok render scene.ts --watch
-```
-
-You can also **include** an SDK scene from VidScript:
-
-```vidscript
-import intro from "./intro.ts"
-use intro at 0s .. 0s with {}
-output to "reel.mp4"
-```
-
-See `vidscript-guide.md` → Include TypeScript / JavaScript scenes.
-
-MCP:
-
-- `scenerok_validate_vidscript` with `language: "typescript"`
-- `scenerok_render_video` with `language: "typescript"`
-- `scenerok_get_sdk_guide` for this document
-
-## AI plugins (xAI / Cloudflare / ElevenLabs)
-
-Same packages as VidScript. Import them in TypeScript; the SceneRok compile host runs the real plugins and returns SDK `video` / `audio` nodes:
-
-```ts
-import { timeline } from '@scenerok/sdk'
-import xai from '@scenerok/xai'
-import cf from '@scenerok/cloudflare'
-import eleven from '@elevenlabs/music'
-
-export default async function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
-  const clip = await xai.genVideo('Cinematic drone over mountains', {
-    duration: 5,
-    aspect_ratio: '9:16',
-    resolution: '720p',
-  })
-  const still = await cf.image('Product on seamless backdrop', { aspect_ratio: '9:16' })
-  const vo = await xai.tts('Welcome to SceneRok', { voice: 'eve' })
-  const bed = await eleven.music('Warm lo-fi bed', { duration: 12 })
-
-  t[0][clip.duration] = clip
-  t[clip.duration][clip.duration + still.duration] = still
-  t.push(vo)
-  t.push(bed)
-  return t.toIR()
-}
-```
-
-| Package | Import | Key functions |
-|---------|--------|---------------|
-| `@scenerok/xai` | `import xai from '@scenerok/xai'` | `imagine`, `genVideo`, `image`, `imageToVideo`, `referenceToVideo`, `extendVideo`, `tts`, `listVoices` |
-| `@scenerok/cloudflare` | `import cf from '@scenerok/cloudflare'` | `video` / `imagine`, `image`, `imageToVideo`, `extendVideo`, `listModels` |
-| `@elevenlabs/music` | `import eleven from '@elevenlabs/music'` | `music`, `generateMusic`, `composeMusic` |
-
-Requires the same env secrets as VidScript (`XAI_API_KEY`, `ELEVENLABS_API_KEY`, Cloudflare AI Gateway credentials). Generation is billed on render the same way as VidScript plugins.
-
-## MVP limits
-
-- Prefer `getVideoLength(path)` from `@scenerok/stdlib` instead of hard-coding `duration:` when assets exist on disk
-- `--generate-assets` remains VidScript-only (SDK scripts generate assets during `scenerok render` when plugins are called)
-
-## Media stdlib
-
-```ts
-import { loadVideo, getVideoLength, grabFrame, beats } from '@scenerok/sdk'
-
-export default async function main() {
-  const clip = await loadVideo('./hero.mp4')
-  const d = await getVideoLength('./hero.mp4')
-  const thumb = await grabFrame('./hero.mp4', d / 2)
-  // ...
-}
-```
-
-Same functions are available in VidScript via `import media from "@scenerok/media"`.
-
-See `skills/remote/media-stdlib.md` and `ai-models.md` / `tts.md` / `music.md` for prompt guidance.
-
-## Related
-
-- VidScript grammar: `vidscript-guide.md`
-- Intent routing: `intent-router.md`
-- Package README: `packages/scenerok-sdk/README.md`

package/skills/remote/vidscript-sample.md

@@ -1,28 +0,0 @@
-# VidScript v2 Sample — Product promo with generated video
-
-Copy this shape for promos that use xAI-generated clips. Run `scenerok validate` before `scenerok render`.
-
-```vidscript
-import xai from "@scenerok/xai"
-import motion from "@scenerok/basic-animations"
-
-input product_name = "{{product_name | RokMilk}}"
-input hook_text = "{{hook_text | Chocolate Milkshake}}"
-input cta_text = "{{cta_text | visit your nearest grocery store}}"
-
-[0s .. 2.5s] = text product_name, font: "Bebas Neue", size: 80, color: "#FFD700", x: "50%", y: "20%", align: center, stroke: "#3E1C00", stroke_width: 4, animate: motion.fadeIn(0.6s)
-
-[2s .. 4.5s] = text hook_text, font: "Outfit", size: 52, color: "#FFFFFF", x: "50%", y: "45%", align: center, stroke: "#3E1C00", stroke_width: 3, animate: motion.riseIn(0.8s)
-
-[-] = video xai.imagine(
-    "Premium lifestyle product shot of " + product_name + " chocolate milk in 250ml carton, cinematic lighting, 9:16 vertical, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy",
-    aspect_ratio: "9:16",
-    duration: 6
-)
-
-[8s .. 11s] = text cta_text, font: "Bebas Neue", size: 48, color: "#FFD700", x: "50%", y: "80%", align: center, stroke: "#3E1C00", stroke_width: 4, animate: motion.fadeIn(0.8s)
-
-output to "product-promo.mp4", resolution: "1080x1920", fps: 30
-```
-
-For clips you already have (no xAI), start from `examples/system/product-launch.vid` instead.

package/skills/shared/SKILL.md

@@ -1,157 +0,0 @@
----
-name: scenerok
-description: >-
-  Compose VidScript v2 or TypeScript @scenerok/sdk and render videos with SceneRok —
-  CLI, web editor, ChatGPT, or MCP. Use for promos, reels, motion graphics, code demos,
-  social cards, and any request mentioning VidScript, SceneRok, or scenerok.
-triggers:
-  - create a video
-  - make a reel
-  - generate a promo
-  - VidScript
-  - @scenerok/sdk
-  - scenerok render
-  - scenerok validate
-  - social video
-  - product launch video
-  - SceneRok editor
----
-
-# SceneRok Agent Skill
-
-You help users compose **VidScript v2** or **TypeScript `@scenerok/sdk`** and produce MP4s with SceneRok. Skill content is **live at scenerok.com** — fetch it rather than relying on stale copies.
-
-## Dual authoring
-
-| Who / scene | Write |
-|-------------|--------|
-| Humans / short promos / templates | **VidScript** (`.vid`) |
-| Agents / complex, data-driven timelines | **TypeScript + `@scenerok/sdk`** (`.ts`) |
-
-Both emit the same `IRTimeline`. Load **`sdk-guide.md`** before writing SDK scenes.
-
-## 1. Know your environment
-
-Load **`environments.md`** and follow its capability matrix.
-
-| You are… | Do this |
-| --- | --- |
-| In the **SceneRok web editor** | Use `patch_vidscript`; validate/render in-app — VidScript today (SDK via CLI/MCP) |
-| On the **user's machine** with `scenerok` | `scenerok validate` → `scenerok render` (`.vid` or `.ts`) |
-| A **ChatGPT GPT** with SceneRok Actions | OAuth + `validateVidscript` → `renderVideo`; import uploads first |
-| **Gemini / Grok** without HTTP tools | Compose VidScript or SDK TS; user renders elsewhere |
-| **MCP host** with `scenerok-mcp` | Use MCP compose/render tools (`language: typescript` for SDK) |
-
-## 2. Load remote docs (required before composing)
-
-1. `https://scenerok.com/.well-known/agent-skills/index.json` — catalog
-2. **Always:** `vidscript-strict.md`, `intent-router.md`, `environments.md`
-3. **Complex / agent TS scenes:** also load `sdk-guide.md`
-4. **Media probe / frame grab / loadVideo:** `media-stdlib.md`
-5. **By intent** (see `intent-router.md`):
-
-| Intent | Load |
-| --- | --- |
-| Any VidScript composition | `vidscript-strict.md` |
-| Complex TS / loops / computed timing / grid in TS | `sdk-guide.md` |
-| AI generation (xAI / CF / ElevenLabs) — VidScript or TS | `ai-models.md` / `tts.md` / `music.md` (+ `sdk-guide.md` if TS) |
-| Workflow routing | `intent-router.md` |
-| HyperFrames / code / lower-thirds / social cards | `animations-picker.md` (+ `animations-catalog.md` if you need every param) |
-| Text animations (word reveals, scramble, kinetic type, gradient, quotes, stats, glitch, neon) | `animations-picker.md` text-anim rows (`animations.text_*`) |
-| Custom / bring-your-own animation — write HTML+CSS with GSAP, Three.js, or any seekable JS lib | `animations-catalog.md` → "Custom HTML" (`animations.custom_html`; author contract + template inside) |
-| Scene cuts / whip / dissolve | `transitions-catalog.md` |
-| Kinetic titles (motion primitives on `text`) | `text-styles.md` |
-| AI b-roll / product visuals | `ai-models.md` |
-| Voiceover | `tts.md` |
-| Music bed | `music.md` |
-| VFX on one clip | `shaders-filters.md` |
-| Full promo / URL assets | `workflow.md`, `brand-setup.md` |
-| Grammar deep-dive | `vidscript-guide.md` |
-| ChatGPT setup | `consumer-chat-apps.md`, `chatgpt-gpt-instructions.md` |
-
-Base: `https://scenerok.com/.well-known/agent-skills/{filename}`
-
-**Offline:** `scenerok skills sync` · **Freshness:** `scenerok skills check` · **Update:** `scenerok skills update`
-
-Browse previews: https://scenerok.com/catalog
-
-## 3. Compose pipeline (summary)
-
-1. Classify intent → `intent-router.md`
-2. Choose authoring: simple → VidScript; complex/agent → `@scenerok/sdk` (`sdk-guide.md`)
-3. Pick animation / transition / text / AI modality from the right catalog — **reuse-first**, do not invent syntax
-4. If branded promo and colors/logo unknown → `brand-setup.md` (one short question max)
-5. Probe asset dimensions before placement (`media-stdlib.md` / `loadVideo` / CLI `ffprobe`)
-6. `scenerok validate script.vid` or `scenerok validate scene.ts` (or editor / ChatGPT equivalent)
-7. Before rendering VidScript with TTS or generated media: `scenerok validate script.vid --generate-assets --report-json` — runs the real compile (billed, assets cached for the render), then read the inspection report: fix `offCanvas`/`wasShrunk` text, element `collisions`, and unintended `audio.overlaps` (voiceover-on-voiceover; music beds are fine). Patch and re-validate until clean. (SDK: plugins generate during `scenerok render`; `--generate-assets` is VidScript-only.)
-8. Render and deliver download URL
-9. After rendering, verify the actual MP4: `scenerok lint-video <render-id> --cost medium --json`. Fix reported issues and repeat: **write → validate → render → lint-video → fix**.
-
-**Never guess asset durations.** VidScript: `let vo = xai.tts(...)` + `vo.duration`. SDK: `await loadVideo(path)` / `await xai.tts(...)` and use `.duration` on the returned node.
-
-**Never guess text coordinates.** VidScript: `area: "title"` (+ optional `grid ...`). SDK: `t.grid({...})` then `text(..., { area: 'title' })`.
-
-## 4. Packages (import before use)
-
-| Surface | Packages |
-| --- | --- |
-| VidScript | `@scenerok/xai`, `@scenerok/cloudflare`, `@elevenlabs/music`, `@scenerok/media`, `@scenerok/basic-animations`, `@scenerok/animations`, `@scenerok/transitions` |
-| SDK core | `import { timeline, video, loadVideo, text, audio, s, fadeIn } from '@scenerok/sdk'` |
-| SDK AI | `import xai from '@scenerok/xai'` · `import cf from '@scenerok/cloudflare'` · `import eleven from '@elevenlabs/music'` |
-| SDK transitions | `import tr from '@scenerok/transitions'` — same catalog as VidScript (`tr.dissolve()`, `tr.push({ direction: 'right' })`, …) |
-| SDK stdlib | `import { getVideoLength, grabFrame, beats } from '@scenerok/stdlib'` (also re-exported from `@scenerok/sdk`) |
-
-## 5. CLI quick reference (desktop only)
-
-```bash
-scenerok auth login
-scenerok validate script.vid
-scenerok validate scene.ts
-scenerok validate script.vid --render --cost medium
-scenerok render script.vid --watch
-scenerok render scene.ts --watch
-scenerok lint-video 42 --cost low --json
-scenerok skills install cursor --sync
-```
-
-## 6. Minimal VidScript
-
-```vidscript
-import motion from "@scenerok/basic-animations"
-
-input hero = "https://cdn.example.com/clip.mp4"
-[-] = hero
-[- 3s] = text "Hello", style: title, color: "#FFF", area: "title", animate: motion.fadeIn(0.8s)
-output to "video.mp4", resolution: "1080x1920", fps: 30
-```
-
-## 7. Minimal SDK (TypeScript)
-
-```ts
-import { timeline, text, s, fadeIn } from '@scenerok/sdk'
-
-export default function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
-  t.grid({
-    rows: '16% 1fr 18% 10%',
-    areas: ['title', 'stage', 'lower-third', 'caption'],
-  })
-  t[0][s(3)] = text('SceneRok', { size: 72, area: 'title' }).animate(fadeIn(s(0.4)))
-  t[3][5] = text('Text to video', { size: 40, area: 'lower-third' })
-  return t.toIR()
-}
-```
-
-For AI generation, stdlib probing, and dual-index scheduling, load **`sdk-guide.md`**.
-
-## Platform engineering
-
-For parser/render/API work (not video composition), load **`scenerok-development`** from `.agents/skills/scenerok-development/` in the SceneRok repo.
-
-## Reference
-
-- Grammar: https://scenerok.com/.well-known/agent-skills/vidscript-guide.md
-- SDK: https://scenerok.com/.well-known/agent-skills/sdk-guide.md
-- Media stdlib: https://scenerok.com/.well-known/agent-skills/media-stdlib.md
-- Full docs: https://scenerok.com/llms-full.txt
-- Manifest: https://scenerok.com/.well-known/agent-skills/manifest.json