@scenerok/cli 1.0.4 → 1.0.5

package/skills/aider/vidscript-strict.md

@@ -0,0 +1,95 @@
+# VidScript v2 — Strict Agent Reference
+
+Follow these rules exactly. When in doubt, copy a file from `examples/system/` (installed with `scenerok skills install`).
+
+## Rule 1: Plugin imports are mandatory
+
+```vidscript
+import xai from "@scenerok/xai"
+```
+
+Without this line, `xai.imagine`, `xai.tts`, and animation helpers like `fadeIn` fail validation.
+
+**Never** call `video xai.imagine(...)` or `animate: fadeIn(...)` without the import above.
+
+## Rule 2: Put plugin calls directly in time blocks
+
+```vidscript
+[-] = video xai.imagine("Prompt here", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Voiceover line", voice: "eve")
+```
+
+**Never** assign plugins to variables: `let clip = xai.imagine(...)` is invalid.
+
+## Rule 3: Time ranges use `..`
+
+```vidscript
+[0s .. 5s] = text "Hello"
+```
+
+Not `[0s - 5s]`.
+
+## Rule 4: Text params stay on one line
+
+```vidscript
+[0.5s .. 3s] = text "Headline", font: "Inter", size: 64, color: "#FFFFFF", x: "50%", y: "30%", align: center
+```
+
+## Rule 5: Quote safety in prompts
+
+Use only straight `"` inside `xai.imagine("...")`. Do not nest quotes inside the prompt string (e.g. avoid `"RokMilk"` inside the prompt — say `labeled RokMilk` without extra quotes).
+
+## Rule 6: Audio syntax
+
+```vidscript
+[-] = audio xai.tts("Spoken line", voice: "eve", speed: 1.0)
+```
+
+**Invalid:** `audio music("...", duration: 15), volume: 0.35` — trailing `, volume` after a plugin call is a parse error.
+
+Music/generative audio plugins require their own `import` when available; do not invent bare `music(...)` calls.
+
+## Rule 7: Filters
+
+```vidscript
+[0s .. 15s] = filter "vignette", intensity: 0.3
+[0s .. 15s] = filter "saturation", value: 1.12
+```
+
+`saturation` uses `value`, not `intensity`.
+
+## Rule 8: Always end with output
+
+```vidscript
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+Do **not** use legacy `config { }` blocks — they are not part of VidScript v2.
+
+## Animations (after import)
+
+```vidscript
+[0s .. 2s] = text "Launch", x: "50%", y: "50%", animate: popIn(0.7s)
+```
+
+Available: `fadeIn`, `fadeOut`, `slideX`, `slideY`, `popIn`, `riseIn`, `swingIn`, `glitchIn`, `float`, `typewriter`.
+
+## Validate before render
+
+```bash
+scenerok validate my-video.vid
+```
+
+Each error line includes `Line N:C — message` when the server returns location info.
+
+## 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 |
+
+Full grammar: https://scenerok.com/docs/vidscript

package/skills/claude/SKILL.md

@@ -86,18 +86,20 @@ import music from "@elevenlabs/music" # generative music
 use intro at [-] with { clip: main, headline: "Welcome" }
 ```
 
-### Plugin Calls
+### Plugin Calls (required import)
 
 ```vidscript
-import eleven from "/tts"
+import xai from "@scenerok/xai"
 
-[-] = audio eleven.tts("Welcome to SceneRok", voice: "Rachel")
-[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16")
-[-] = audio music("upbeat launch soundtrack", duration: 12, instrumental: true)
-[-] = audio xai.tts("Next line", voice: "eve")
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 ```
 
-Package-style plugin calls are supported inside time blocks. Use `video ...` for generated visual clips and `audio ...` for generated speech, music, and other generated audio.
+**Always** add `import xai from "@scenerok/xai"` before any `xai.imagine` / `xai.tts` call or `animate: fadeIn(...)` helper. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+
+Put plugin calls **directly** in time blocks — never `let clip = xai.imagine(...)`.
+
+Read `vidscript-strict.md` for anti-patterns and `examples/system/*.vid` for copy-paste templates (installed with `scenerok skills install`).
 
 ### Placeholders
 
@@ -165,7 +167,15 @@ Always ask clarifying questions about:
 - Desired duration and style
 - Whether they want to start from a template or from scratch
 
+## Reference files (in this skill folder)
+
+| File | Purpose |
+|------|---------|
+| `vidscript-guide.md` | Full grammar reference |
+| `vidscript-strict.md` | **Read first** — rules that prevent common agent mistakes |
+| `vidscript-sample.md` | Minimal promo with xAI import |
+| `examples/system/*.vid` | Official SceneRok templates (text-only, product launch, xAI reels) |
+
 ## Full Reference
 
-For exhaustive grammar documentation, visit:
 https://scenerok.com/docs/vidscript

package/skills/claude/vidscript-guide.md

@@ -2,6 +2,22 @@
 
 VidScript is a declarative DSL for composing short-form videos. Write a script, render an MP4.
 
+## Agent quick start (read before composing)
+
+1. **Import plugins** — `import xai from "@scenerok/xai"` before `xai.imagine`, `xai.tts`, or `animate: fadeIn(...)`.
+2. **Validate early** — `scenerok validate file.vid` (errors show as `Line N:C — message`).
+3. **Copy working examples** — see `examples/system/` in this skill folder (e.g. `minimal-text-reel.vid`, `ecom-product-launch.vid`, `rokmilk-chocolate-promo.vid`).
+4. **Strict rules** — see `vidscript-strict.md` for invalid patterns (bare `xai.imagine`, `audio music(...), volume:`, nested quotes in prompts).
+
+### Common validation failures
+
+| Symptom | Fix |
+|---------|-----|
+| `Unknown function 'xai.imagine'` | Add `import xai from "@scenerok/xai"` at top |
+| `Unknown function 'fadeIn'` | Same import (animation helpers are plugin-backed) |
+| `Expected ... but "," found` | Do not put `, volume:` after a plugin call on the same line |
+| Parse error on imagine prompt | Remove nested `"` quotes inside the prompt string |
+
 ## Program Structure
 
 A VidScript program is a sequence of statements separated by newlines.
@@ -218,21 +234,24 @@ Audio sources can be MP3 inputs, audio plugin results, or the embedded audio str
 | `fade_in` | number | Fade-in duration (seconds) |
 | `fade_out` | number | Fade-out duration (seconds) |
 
-### Plugin Calls (explicit default import — the only supported form)
+### Plugin Calls
 
 ```vidscript
 import xai from "@scenerok/xai"
-import eleven from "@elevenlabs/tts"   # example future scoped package
 
-[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16")
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
 [-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
-[-] = audio eleven.tts("Hello", voice: "Rachel")
-[-] = audio music("upbeat launch soundtrack", duration: 12, instrumental: true)
 ```
 
-**Rule:** Always start with `import name from "@scope/pkg"`. No more bare globals or named imports. This is the single obvious syntax for both humans and LLMs.
+Plugins require an explicit default import. The server registers `@scenerok/xai` when API keys are configured. Plugin calls run at compile time and must appear **inside time blocks**, not in `let` assignments.
 
-Plugins are npm packages that add new function names. The built-in server registration includes xAI media/TTS (via `@scenerok/xai`) and others when keys are configured. They run at compile time.
+**Invalid (will not validate):**
+
+```vidscript
+[-] = video xai.imagine("...")          # missing import
+[-] = audio music("..."), volume: 0.5   # trailing params after plugin call
+let clip = xai.imagine("...")           # plugin assigned to variable
+```
 
 ## Animations, Effects & Plugins (v2 Extensibility)
 

package/skills/claude/vidscript-sample.md

@@ -1,21 +1,29 @@
-# VidScript v2 Sample — Product Launch Promo
-# A 6-second vertical video for TikTok / Instagram Reels
-# Demonstrates dynamic timeblocks, video shorthand, named args, expressions, and filters
+# VidScript v2 Sample — Product promo with generated video
 
-input hero = "{{hero_clip}}"
+Copy this shape for promos that use xAI-generated clips. Run `scenerok validate` before `scenerok render`.
 
-# Auto-append: cursor starts at 0, each [-] advances automatically
-[-] = video hero
-hero.Trim(start: 0s, end: 6s)
+```vidscript
+import xai from "@scenerok/xai"
 
-# Text overlays with comma-separated named params
-[0.3s .. 2.3s] = text "NEW DROP", style: title, position: top, color: "#FFFFFF", size: 64, stroke: "#000000", stroke_width: 3
+input product_name = "{{product_name | RokMilk}}"
+input hook_text = "{{hook_text | Chocolate Milkshake}}"
+input cta_text = "{{cta_text | visit your nearest grocery store}}"
 
-[2.5s .. 4.5s] = text "The most anticipated release of the season", style: caption, position: center, color: "#F3F4F6", size: 36, stroke: "#000000", stroke_width: 2
+[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: fadeIn(0.6s)
 
-[4.5s .. 5.8s] = text "SHOP NOW", style: title, position: bottom, color: "#F59E0B", size: 52, stroke: "#000000", stroke_width: 3
+[2s .. 4.5s] = text hook_text, font: "Outfit", size: 52, color: "#FFFFFF", x: "50%", y: "45%", align: center, stroke: "#3E1C00", stroke_width: 3, animate: riseIn(0.8s)
 
-# Filter applied from start to end of the clip
-[0s .. 6s] = filter "vignette", intensity: 0.35
+[-] = video xai.imagine(
+    "Premium lifestyle product shot of " + product_name + " chocolate milk in 250ml carton, cinematic lighting, 9:16 vertical",
+    aspect_ratio: "9:16",
+    duration: 6
+)
 
-output to "product-launch.mp4", resolution: "1080x1920", fps: 30
+[8s .. 11s] = text cta_text, font: "Bebas Neue", size: 48, color: "#FFD700", x: "50%", y: "80%", align: center, stroke: "#3E1C00", stroke_width: 4, animate: fadeIn(0.8s)
+
+[0s .. 12s] = filter "vignette", intensity: 0.3
+
+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/claude/vidscript-strict.md

@@ -0,0 +1,95 @@
+# VidScript v2 — Strict Agent Reference
+
+Follow these rules exactly. When in doubt, copy a file from `examples/system/` (installed with `scenerok skills install`).
+
+## Rule 1: Plugin imports are mandatory
+
+```vidscript
+import xai from "@scenerok/xai"
+```
+
+Without this line, `xai.imagine`, `xai.tts`, and animation helpers like `fadeIn` fail validation.
+
+**Never** call `video xai.imagine(...)` or `animate: fadeIn(...)` without the import above.
+
+## Rule 2: Put plugin calls directly in time blocks
+
+```vidscript
+[-] = video xai.imagine("Prompt here", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Voiceover line", voice: "eve")
+```
+
+**Never** assign plugins to variables: `let clip = xai.imagine(...)` is invalid.
+
+## Rule 3: Time ranges use `..`
+
+```vidscript
+[0s .. 5s] = text "Hello"
+```
+
+Not `[0s - 5s]`.
+
+## Rule 4: Text params stay on one line
+
+```vidscript
+[0.5s .. 3s] = text "Headline", font: "Inter", size: 64, color: "#FFFFFF", x: "50%", y: "30%", align: center
+```
+
+## Rule 5: Quote safety in prompts
+
+Use only straight `"` inside `xai.imagine("...")`. Do not nest quotes inside the prompt string (e.g. avoid `"RokMilk"` inside the prompt — say `labeled RokMilk` without extra quotes).
+
+## Rule 6: Audio syntax
+
+```vidscript
+[-] = audio xai.tts("Spoken line", voice: "eve", speed: 1.0)
+```
+
+**Invalid:** `audio music("...", duration: 15), volume: 0.35` — trailing `, volume` after a plugin call is a parse error.
+
+Music/generative audio plugins require their own `import` when available; do not invent bare `music(...)` calls.
+
+## Rule 7: Filters
+
+```vidscript
+[0s .. 15s] = filter "vignette", intensity: 0.3
+[0s .. 15s] = filter "saturation", value: 1.12
+```
+
+`saturation` uses `value`, not `intensity`.
+
+## Rule 8: Always end with output
+
+```vidscript
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+Do **not** use legacy `config { }` blocks — they are not part of VidScript v2.
+
+## Animations (after import)
+
+```vidscript
+[0s .. 2s] = text "Launch", x: "50%", y: "50%", animate: popIn(0.7s)
+```
+
+Available: `fadeIn`, `fadeOut`, `slideX`, `slideY`, `popIn`, `riseIn`, `swingIn`, `glitchIn`, `float`, `typewriter`.
+
+## Validate before render
+
+```bash
+scenerok validate my-video.vid
+```
+
+Each error line includes `Line N:C — message` when the server returns location info.
+
+## 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 |
+
+Full grammar: https://scenerok.com/docs/vidscript

package/skills/codex/SKILL.md

@@ -86,18 +86,20 @@ import music from "@elevenlabs/music" # generative music
 use intro at [-] with { clip: main, headline: "Welcome" }
 ```
 
-### Plugin Calls
+### Plugin Calls (required import)
 
 ```vidscript
-import eleven from "/tts"
+import xai from "@scenerok/xai"
 
-[-] = audio eleven.tts("Welcome to SceneRok", voice: "Rachel")
-[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16")
-[-] = audio music("upbeat launch soundtrack", duration: 12, instrumental: true)
-[-] = audio xai.tts("Next line", voice: "eve")
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 ```
 
-Package-style plugin calls are supported inside time blocks. Use `video ...` for generated visual clips and `audio ...` for generated speech, music, and other generated audio.
+**Always** add `import xai from "@scenerok/xai"` before any `xai.imagine` / `xai.tts` call or `animate: fadeIn(...)` helper. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+
+Put plugin calls **directly** in time blocks — never `let clip = xai.imagine(...)`.
+
+Read `vidscript-strict.md` for anti-patterns and `examples/system/*.vid` for copy-paste templates (installed with `scenerok skills install`).
 
 ### Placeholders
 
@@ -165,7 +167,15 @@ Always ask clarifying questions about:
 - Desired duration and style
 - Whether they want to start from a template or from scratch
 
+## Reference files (in this skill folder)
+
+| File | Purpose |
+|------|---------|
+| `vidscript-guide.md` | Full grammar reference |
+| `vidscript-strict.md` | **Read first** — rules that prevent common agent mistakes |
+| `vidscript-sample.md` | Minimal promo with xAI import |
+| `examples/system/*.vid` | Official SceneRok templates (text-only, product launch, xAI reels) |
+
 ## Full Reference
 
-For exhaustive grammar documentation, visit:
 https://scenerok.com/docs/vidscript

package/skills/codex/vidscript-guide.md

@@ -2,6 +2,22 @@
 
 VidScript is a declarative DSL for composing short-form videos. Write a script, render an MP4.
 
+## Agent quick start (read before composing)
+
+1. **Import plugins** — `import xai from "@scenerok/xai"` before `xai.imagine`, `xai.tts`, or `animate: fadeIn(...)`.
+2. **Validate early** — `scenerok validate file.vid` (errors show as `Line N:C — message`).
+3. **Copy working examples** — see `examples/system/` in this skill folder (e.g. `minimal-text-reel.vid`, `ecom-product-launch.vid`, `rokmilk-chocolate-promo.vid`).
+4. **Strict rules** — see `vidscript-strict.md` for invalid patterns (bare `xai.imagine`, `audio music(...), volume:`, nested quotes in prompts).
+
+### Common validation failures
+
+| Symptom | Fix |
+|---------|-----|
+| `Unknown function 'xai.imagine'` | Add `import xai from "@scenerok/xai"` at top |
+| `Unknown function 'fadeIn'` | Same import (animation helpers are plugin-backed) |
+| `Expected ... but "," found` | Do not put `, volume:` after a plugin call on the same line |
+| Parse error on imagine prompt | Remove nested `"` quotes inside the prompt string |
+
 ## Program Structure
 
 A VidScript program is a sequence of statements separated by newlines.
@@ -221,17 +237,21 @@ Audio sources can be MP3 inputs, audio plugin results, or the embedded audio str
 ### Plugin Calls
 
 ```vidscript
-import eleven from "@elevenlabs/tts"  # future scoped package
-import music from "@elevenlabs/music"
-
-[-] = audio tts("Welcome to SceneRok", voice: "Rachel")
-[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16")
-[-] = audio music("upbeat launch soundtrack", duration: 12, instrumental: true)
-[-] = audio xai.tts("Next line", voice: "eve")
-[-] = tts("Next line")
+import xai from "@scenerok/xai"
+
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 ```
 
-Plugins are npm packages that add new function names. The built-in server registration includes xAI media/TTS and ElevenLabs music when the matching API keys are configured. They run at compile time and their outputs are baked into the final video. Package-style calls such as `video xai.imagine(...)` and qualified calls such as `audio xai.tts(...)` are supported inside time blocks.
+Plugins require an explicit default import. The server registers `@scenerok/xai` when API keys are configured. Plugin calls run at compile time and must appear **inside time blocks**, not in `let` assignments.
+
+**Invalid (will not validate):**
+
+```vidscript
+[-] = video xai.imagine("...")          # missing import
+[-] = audio music("..."), volume: 0.5   # trailing params after plugin call
+let clip = xai.imagine("...")           # plugin assigned to variable
+```
 
 ## Animations, Effects & Plugins (v2 Extensibility)
 

package/skills/codex/vidscript-sample.md

@@ -1,21 +1,29 @@
-# VidScript v2 Sample — Product Launch Promo
-# A 6-second vertical video for TikTok / Instagram Reels
-# Demonstrates dynamic timeblocks, video shorthand, named args, expressions, and filters
+# VidScript v2 Sample — Product promo with generated video
 
-input hero = "{{hero_clip}}"
+Copy this shape for promos that use xAI-generated clips. Run `scenerok validate` before `scenerok render`.
 
-# Auto-append: cursor starts at 0, each [-] advances automatically
-[-] = video hero
-hero.Trim(start: 0s, end: 6s)
+```vidscript
+import xai from "@scenerok/xai"
 
-# Text overlays with comma-separated named params
-[0.3s .. 2.3s] = text "NEW DROP", style: title, position: top, color: "#FFFFFF", size: 64, stroke: "#000000", stroke_width: 3
+input product_name = "{{product_name | RokMilk}}"
+input hook_text = "{{hook_text | Chocolate Milkshake}}"
+input cta_text = "{{cta_text | visit your nearest grocery store}}"
 
-[2.5s .. 4.5s] = text "The most anticipated release of the season", style: caption, position: center, color: "#F3F4F6", size: 36, stroke: "#000000", stroke_width: 2
+[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: fadeIn(0.6s)
 
-[4.5s .. 5.8s] = text "SHOP NOW", style: title, position: bottom, color: "#F59E0B", size: 52, stroke: "#000000", stroke_width: 3
+[2s .. 4.5s] = text hook_text, font: "Outfit", size: 52, color: "#FFFFFF", x: "50%", y: "45%", align: center, stroke: "#3E1C00", stroke_width: 3, animate: riseIn(0.8s)
 
-# Filter applied from start to end of the clip
-[0s .. 6s] = filter "vignette", intensity: 0.35
+[-] = video xai.imagine(
+    "Premium lifestyle product shot of " + product_name + " chocolate milk in 250ml carton, cinematic lighting, 9:16 vertical",
+    aspect_ratio: "9:16",
+    duration: 6
+)
 
-output to "product-launch.mp4", resolution: "1080x1920", fps: 30
+[8s .. 11s] = text cta_text, font: "Bebas Neue", size: 48, color: "#FFD700", x: "50%", y: "80%", align: center, stroke: "#3E1C00", stroke_width: 4, animate: fadeIn(0.8s)
+
+[0s .. 12s] = filter "vignette", intensity: 0.3
+
+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/codex/vidscript-strict.md

@@ -0,0 +1,95 @@
+# VidScript v2 — Strict Agent Reference
+
+Follow these rules exactly. When in doubt, copy a file from `examples/system/` (installed with `scenerok skills install`).
+
+## Rule 1: Plugin imports are mandatory
+
+```vidscript
+import xai from "@scenerok/xai"
+```
+
+Without this line, `xai.imagine`, `xai.tts`, and animation helpers like `fadeIn` fail validation.
+
+**Never** call `video xai.imagine(...)` or `animate: fadeIn(...)` without the import above.
+
+## Rule 2: Put plugin calls directly in time blocks
+
+```vidscript
+[-] = video xai.imagine("Prompt here", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Voiceover line", voice: "eve")
+```
+
+**Never** assign plugins to variables: `let clip = xai.imagine(...)` is invalid.
+
+## Rule 3: Time ranges use `..`
+
+```vidscript
+[0s .. 5s] = text "Hello"
+```
+
+Not `[0s - 5s]`.
+
+## Rule 4: Text params stay on one line
+
+```vidscript
+[0.5s .. 3s] = text "Headline", font: "Inter", size: 64, color: "#FFFFFF", x: "50%", y: "30%", align: center
+```
+
+## Rule 5: Quote safety in prompts
+
+Use only straight `"` inside `xai.imagine("...")`. Do not nest quotes inside the prompt string (e.g. avoid `"RokMilk"` inside the prompt — say `labeled RokMilk` without extra quotes).
+
+## Rule 6: Audio syntax
+
+```vidscript
+[-] = audio xai.tts("Spoken line", voice: "eve", speed: 1.0)
+```
+
+**Invalid:** `audio music("...", duration: 15), volume: 0.35` — trailing `, volume` after a plugin call is a parse error.
+
+Music/generative audio plugins require their own `import` when available; do not invent bare `music(...)` calls.
+
+## Rule 7: Filters
+
+```vidscript
+[0s .. 15s] = filter "vignette", intensity: 0.3
+[0s .. 15s] = filter "saturation", value: 1.12
+```
+
+`saturation` uses `value`, not `intensity`.
+
+## Rule 8: Always end with output
+
+```vidscript
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+Do **not** use legacy `config { }` blocks — they are not part of VidScript v2.
+
+## Animations (after import)
+
+```vidscript
+[0s .. 2s] = text "Launch", x: "50%", y: "50%", animate: popIn(0.7s)
+```
+
+Available: `fadeIn`, `fadeOut`, `slideX`, `slideY`, `popIn`, `riseIn`, `swingIn`, `glitchIn`, `float`, `typewriter`.
+
+## Validate before render
+
+```bash
+scenerok validate my-video.vid
+```
+
+Each error line includes `Line N:C — message` when the server returns location info.
+
+## 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 |
+
+Full grammar: https://scenerok.com/docs/vidscript

package/skills/cursor/SKILL.md

@@ -86,18 +86,20 @@ import music from "@elevenlabs/music" # generative music
 use intro at [-] with { clip: main, headline: "Welcome" }
 ```
 
-### Plugin Calls
+### Plugin Calls (required import)
 
 ```vidscript
-import eleven from "/tts"
+import xai from "@scenerok/xai"
 
-[-] = audio eleven.tts("Welcome to SceneRok", voice: "Rachel")
-[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16")
-[-] = audio music("upbeat launch soundtrack", duration: 12, instrumental: true)
-[-] = audio xai.tts("Next line", voice: "eve")
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 ```
 
-Package-style plugin calls are supported inside time blocks. Use `video ...` for generated visual clips and `audio ...` for generated speech, music, and other generated audio.
+**Always** add `import xai from "@scenerok/xai"` before any `xai.imagine` / `xai.tts` call or `animate: fadeIn(...)` helper. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+
+Put plugin calls **directly** in time blocks — never `let clip = xai.imagine(...)`.
+
+Read `vidscript-strict.md` for anti-patterns and `examples/system/*.vid` for copy-paste templates (installed with `scenerok skills install`).
 
 ### Placeholders
 
@@ -165,7 +167,15 @@ Always ask clarifying questions about:
 - Desired duration and style
 - Whether they want to start from a template or from scratch
 
+## Reference files (in this skill folder)
+
+| File | Purpose |
+|------|---------|
+| `vidscript-guide.md` | Full grammar reference |
+| `vidscript-strict.md` | **Read first** — rules that prevent common agent mistakes |
+| `vidscript-sample.md` | Minimal promo with xAI import |
+| `examples/system/*.vid` | Official SceneRok templates (text-only, product launch, xAI reels) |
+
 ## Full Reference
 
-For exhaustive grammar documentation, visit:
 https://scenerok.com/docs/vidscript