@scenerok/cli 1.0.4 → 1.0.6

package/examples/system/glitch-title.vid

@@ -0,0 +1,17 @@
+# Glitch Title
+# A stylized intro with glitch effects and bold typography.
+# Great for gaming, tech, or edgy brand content.
+
+input background = "{{background_clip}}"
+
+[0s .. 5s] = background
+background.Trim(start: 0s, end: 5s)
+background.Opacity(value: 0.8, duration: 5s)
+
+[0.5s .. 3s] = text "{{title}}", font: "Bebas Neue", position: center, color: "#00FF88", size: 72, stroke: "#000000", stroke_width: 4, x: "50%", y: "45%", align: center, letter_spacing: 4
+
+[3.2s .. 4.5s] = text "{{subtitle}}", font: "Oswald", position: center, color: "#FF0055", size: 96, stroke: "#000000", stroke_width: 4, x: "50%", y: "60%", align: center, rotation: 2, shadow_color: "#00FF88", shadow_blur: 8
+
+[0s .. 5s] = filter "glitch", intensity: 0.4
+
+output to "glitch-title.mp4", resolution: "1080x1920", fps: 30

package/examples/system/meme-remix.vid

@@ -0,0 +1,15 @@
+# Meme Remix
+# Fast-cut format with top and bottom text overlays.
+# Perfect for reaction clips, punchline edits, and viral-style content.
+
+input clip = "{{reaction_clip}}"
+
+[0s .. 4s] = clip
+clip.Trim(start: 0s, end: 4s)
+clip.Speed(factor: 1.2)
+
+[0.1s .. 1.5s] = text "{{hook_text}}", style: title, position: top, color: "#FFFFFF", size: 56, stroke: "#000000", stroke_width: 3
+
+[2.5s .. 3.8s] = text "{{punchline}}", style: title, position: bottom, color: "#EF4444", size: 64, stroke: "#000000", stroke_width: 4
+
+output to "meme-remix.mp4", resolution: "1080x1920", fps: 30

package/examples/system/minimal-text-reel.vid

@@ -0,0 +1,11 @@
+# Minimal Text Reel v2
+# A clean text-only reel demonstrating advanced typography:
+# dynamic placement, rotation, Google Fonts, shadows, letter spacing.
+
+[0s .. 2.5s] = text "{{headline}}", font: "Bebas Neue", size: 96, color: "#FFFFFF", x: "50%", y: "30%", align: center, letter_spacing: 8, shadow_color: "#FF0055", shadow_blur: 10, shadow_offset_x: 4, shadow_offset_y: 4
+
+[2s .. 4s] = text "{{subtitle}}", font: "Inter", size: 48, color: "#00FF88", x: "50%", y: "55%", align: center, rotation: -3, opacity: 0.9
+
+[3.5s .. 5.5s] = text "{{cta}}", font: "Space Grotesk", size: 44, color: "#6366F1", x: "50%", y: "75%", align: center, shadow_color: "#000000", shadow_blur: 16, shadow_offset_y: 6
+
+output to "minimal-text-reel.mp4", resolution: "1080x1920", fps: 30

package/examples/system/product-launch.vid

@@ -0,0 +1,18 @@
+# Product Launch
+# Showcase a product with bold headlines and a clear call-to-action.
+# Uses a subtle vignette filter for cinematic depth.
+
+input hero = "{{hero_clip}}"
+
+[0s .. 6s] = hero
+hero.Trim(start: 0s, end: 6s)
+
+[0.3s .. 2.3s] = text "{{headline}}", style: title, position: top, color: "#FFFFFF", size: 64, stroke: "#000000", stroke_width: 3
+
+[2.5s .. 4.5s] = text "{{description}}", style: caption, position: center, color: "#F3F4F6", size: 36, stroke: "#000000", stroke_width: 2
+
+[4.5s .. 5.8s] = text "{{cta}}", style: title, position: bottom, color: "#F59E0B", size: 52, stroke: "#000000", stroke_width: 3
+
+[0s .. 6s] = filter "vignette", intensity: 0.35
+
+output to "product-launch.mp4", resolution: "1080x1920", fps: 30

package/examples/system/rokmilk-chocolate-promo.vid

@@ -0,0 +1,25 @@
+# RokMilk Chocolate Milkshake — 15s promo (correct VidScript v2 patterns)
+# Requires: scenerok secrets set XAI_API_KEY=... (or configured on scenerok.com account)
+
+import xai from "@scenerok/xai"
+import motion from "@scenerok/basic-animations"
+
+# Generated visuals — one clip per segment; prompts must use straight double quotes only
+[-] = video xai.imagine("Cinematic slow-motion pour of rich creamy chocolate milk into a sleek modern 250ml carton on marble, warm studio lighting, shallow depth of field, 9:16 vertical", aspect_ratio: "9:16", duration: 5)
+
+[-] = video xai.imagine("Elegant rotating product shot of premium chocolate milk carton labeled RokMilk, brown and gold palette, soft bokeh, advertising visual, 9:16 vertical", aspect_ratio: "9:16", duration: 5)
+
+[-] = video xai.imagine("Silky chocolate milk swirl in glass with RokMilk carton blurred in background, golden light, appetizing food cinematography, 9:16 vertical", aspect_ratio: "9:16", duration: 5)
+
+[0s .. 2.5s] = text "RokMilk", font: "Bebas Neue", size: 80, color: "#FFD700", x: "50%", y: "18%", align: center, stroke: "#3E1C00", stroke_width: 4, letter_spacing: 6, animate: motion.fadeIn(0.6s)
+
+[2s .. 5s] = text "Chocolate Milkshake", font: "Outfit", size: 56, color: "#FFFFFF", x: "50%", y: "45%", align: center, stroke: "#3E1C00", stroke_width: 3, animate: motion.riseIn(0.8s)
+
+[5s .. 8s] = text "250ml of Pure Indulgence", font: "Inter", size: 42, color: "#F3E5AB", x: "50%", y: "55%", align: center, stroke: "#3E1C00", stroke_width: 2, animate: motion.slideY(40, 0, 0.8s)
+
+[11s .. 14s] = text "visit your nearest grocery store", font: "Bebas Neue", size: 48, color: "#FFD700", x: "50%", y: "82%", align: center, stroke: "#3E1C00", stroke_width: 4, letter_spacing: 3, animate: motion.fadeIn(1s)
+
+[0s .. 15s] = filter "vignette", intensity: 0.3
+[0s .. 15s] = filter "saturation", value: 1.12
+
+output to "rokmilk-chocolate-promo.mp4", resolution: "1080x1920", fps: 30, background: "#1A0F05"

package/examples/system/testimonial-cut.vid

@@ -0,0 +1,16 @@
+# Testimonial Cut
+# A quote-focused format with a subtle vintage feel.
+# Great for customer stories, reviews, and social proof clips.
+
+input speaker = "{{speaker_clip}}"
+
+[0s .. 5s] = speaker
+speaker.Trim(start: 0s, end: 5s)
+
+[0.5s .. 3s] = text "{{quote}}", style: subtitle, position: center, color: "#FFFFFF", size: 42, stroke: "#000000", stroke_width: 2
+
+[3.2s .. 4.8s] = text "{{attribution}}", style: caption, position: bottom, color: "#D1D5DB", size: 32, stroke: "#000000", stroke_width: 2
+
+[0s .. 5s] = filter "sepia", intensity: 0.3
+
+output to "testimonial.mp4", resolution: "1080x1920", fps: 30

package/examples/system/ugc-testimonial-voiceover.vid

@@ -0,0 +1,33 @@
+# UGC Testimonial with Voiceover - Reusable Template
+# Uses xAI (via explicit import) for TTS voiceover + generated visuals
+
+import xai from "@scenerok/xai"
+
+# === INPUTS ===
+input quote = "{{quote | This product completely changed how I work}}"
+input customer_name = "{{customer_name | Sarah K.}}"
+input product_name = "{{product_name | SceneRok}}"
+
+# === VOICEOVER + VISUAL ===
+[-] = audio xai.tts(
+    quote + ". " + customer_name + " from " + product_name,
+    voice: "eve",
+    speed: 1.05
+)
+
+[-] = video xai.imagine(
+    "Cinematic lifestyle shot representing: " + quote + ", premium modern aesthetic, 9:16 vertical",
+    aspect_ratio: "9:16",
+    resolution: "1k"
+)
+
+# === QUOTE TEXT (appears while voiceover plays) ===
+[-] = text "\"" + quote + "\"", style: quote, position: center, color: "#FFFFFF", size: 52, align: center
+
+# === ATTRIBUTION ===
+[- 2s] = text "— " + customer_name, style: attribution, position: "center, 75%", color: "#CCCCCC", size: 32
+
+# === BRANDING ===
+[-] = text "Made with SceneRok", style: watermark, position: "85%, 92%", color: "#888888", size: 24, opacity: 0.6
+
+output to "ugc-testimonial.mp4", resolution: "1080x1920", fps: 30

package/examples/system/voice-visual-promo.vid

@@ -0,0 +1,21 @@
+# Voice + Visual Promo
+# Combines main footage with voiceover or music and layered titles.
+
+input main = "{{main_video}}"
+input voice = "{{voiceover_audio}}"
+
+[0s .. 12s] = main
+main.Trim(start: 0s, end: 12s)
+
+[0s .. 12s] = audio voice, volume: 0.9
+
+[0.5s .. 3s] = text "{{title}}", font: "Inter", size: 68, color: "{{brand_color}}", x: "50%", y: "22%", align: center, stroke: "#111827", stroke_width: 3
+
+[3s .. 7s] = text "{{subtitle}}", font: "Inter", size: 34, color: "#F3F4F6", x: "50%", y: "50%", align: center, stroke: "#0F172A", stroke_width: 2
+
+[7s .. 11s] = text "{{cta}}", font: "Inter", size: 56, color: "#FFFFFF", x: "50%", y: "78%", align: center, stroke: "#000000", stroke_width: 3
+
+[0s .. 12s] = filter "vignette", intensity: 0.22
+[0s .. 12s] = filter "saturation", value: 1.12
+
+output to "voice-visual-promo.mp4", resolution: "1080x1920", fps: 30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/cli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "SceneRok CLI - Create videos from your terminal and agent workflows",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "skills",
+    "examples",
     "README.md"
   ],
   "scripts": {

package/skills/aider/SKILL.md

@@ -67,37 +67,34 @@ Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignett
 output to "video.mp4", resolution: "1080x1920", fps: 30
 ```
 
-### Module System
+### Package Imports
 
 ```vidscript
-export const BRAND_COLOR = "#FF5733"
-export timeline intro(clip: string, headline: string) {
-  [-] = clip                                # auto-append
-  clip.Trim(start: 0s, end: 3s)
-  [- 2s] = text headline, style: title      # auto-start, 2s duration
-}
-```
-
-```vidscript
-import { intro } from "./timelines.vid"
-import * as pack from "./effects.vid"
-import eleven from "@elevenlabs/tts"  # future scoped package      # from npm registry
-import music from "@elevenlabs/music" # generative music
-use intro at [-] with { clip: main, headline: "Welcome" }
+import xai from "@scenerok/xai"                    # xAI image/video/tts
+import eleven from "@elevenlabs/music"          # ElevenLabs generative music
+import motion from "@scenerok/basic-animations" # text/video animation helpers
 ```
 
 ### Plugin Calls
 
 ```vidscript
-import eleven from "/tts"
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
+
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 
-[-] = 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")
+# ElevenLabs music package functions require an import alias.
+let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
 ```
 
-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** import the package that owns the function: `xai.*` from `@scenerok/xai`, `eleven.*` from `@elevenlabs/music`, and `motion.*` from `@scenerok/basic-animations`. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+
+For ElevenLabs music, import `@elevenlabs/music` and call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Use `let bed = eleven.music(...)` followed by `audio bed, volume: ...` when you need volume or fades.
+
+Read `vidscript-strict.md` for anti-patterns and `examples/system/*.vid` for copy-paste templates (installed with `scenerok skills install`).
 
 ### Placeholders
 
@@ -165,7 +162,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/aider/vidscript-guide.md

@@ -2,6 +2,24 @@
 
 VidScript is a declarative DSL for composing short-form videos. Write a script, render an MP4.
 
+## Agent quick start (read before composing)
+
+1. **Import every package function** — use `import xai from "@scenerok/xai"`, `import eleven from "@elevenlabs/music"`, and `import motion from "@scenerok/basic-animations"` before calling `xai.*`, `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** — see `examples/system/` in this skill folder (e.g. `minimal-text-reel.vid`, `ecom-product-launch.vid`, `rokmilk-chocolate-promo.vid`).
+5. **Strict rules** — see `vidscript-strict.md` for invalid patterns (bare `xai.imagine`, bare `eleven.music(...)` without import, trailing params after direct plugin calls, nested quotes in prompts).
+
+### Common validation failures
+
+| Symptom | Fix |
+|---------|-----|
+| `Unknown function 'xai.imagine'` | Add `import xai from "@scenerok/xai"` at top |
+| `Unknown function 'fadeIn'` | Use `import motion from "@scenerok/basic-animations"` and call `motion.fadeIn(...)` |
+| `Expected ... but "," found` | Do not put `, volume:` after a direct plugin call. Use `let bed = eleven.music(...)`, then `audio bed, volume: ...` |
+| `Unknown function 'eleven.generateMusic'` | Add `import eleven from "@elevenlabs/music"` before calling `eleven.generateMusic(...)` |
+| 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.
@@ -50,28 +68,18 @@ let clipName = "hero"
 
 Variables can hold strings, numbers, time literals, and object expressions. Variables are evaluated at compile time.
 
-### Import / Export (Module System)
-
-```vidscript
-# Export a constant
-export const BRAND_COLOR = "#FF5733"
-
-# Export a timeline
-export timeline intro(clip: string, title_text: string) {
-  [-] = clip
-  [- 2s] = text title_text, size: 72
-}
+### Package Imports
 
-# Import from another file
-import { intro, BRAND_COLOR } from "./timelines.vid"
+Only default package imports are supported for callable packages. Call functions through the imported alias.
 
-# Import namespace
-import * as transitions from "@scenerok/transitions"
-
-# Use a timeline
-use intro at 0s .. 5s with { clip: hero, title_text: "Hello" }
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
 ```
 
+Named imports (`import { fn } ...`) and namespace imports (`import * as ...`) are not supported.
+
 ## Time Blocks
 
 Time blocks are the core of VidScript. They define when instructions execute on the timeline.
@@ -221,17 +229,30 @@ 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"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
+
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
+
+# ElevenLabs music package functions require an import alias.
+[0s .. 15s] = audio eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
+
+# If you need volume or fades, store the generated audio first.
+let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
 ```
 
-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.
+`@scenerok/xai` requires an explicit default import. ElevenLabs music validates as `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)` after `import eleven from "@elevenlabs/music"`. Plugin calls run at compile time; direct media plugin instructions cannot have trailing audio params, so use a `let` binding when you need `volume`, `fade_in`, or `fade_out`.
+
+**Invalid (will not validate):**
+
+```vidscript
+[-] = video xai.imagine("...")                    # missing xAI import
+[0s .. 15s] = audio eleven.generateMusic("...")   # missing `import eleven from "@elevenlabs/music"`
+[0s .. 15s] = audio eleven.music("..."), volume: 0.5      # trailing params after direct plugin call
+```
 
 ## Animations, Effects & Plugins (v2 Extensibility)
 
@@ -249,9 +270,11 @@ These accept either plugin function calls or plain object descriptors.
 Attach animations to **any** text or video surface.
 
 ```vidscript
-text "Hello", animate: fadeIn(0.8s)
+import motion from "@scenerok/basic-animations"
+
+text "Hello", animate: motion.fadeIn(0.8s)
 
-video hero, animate: [fadeIn(0.5s), slideY(-40, 0, 1.2s)]
+video hero, animate: [motion.fadeIn(0.5s), motion.slideY(-40, 0, 1.2s)]
 
 text "Title", animate: {
   type: "fade",
@@ -279,16 +302,16 @@ video hero, effects: [{
 
 | Function                  | Description                  |
 |---------------------------|------------------------------|
-| `fadeIn(duration?)`       | Opacity 0 → 1                |
-| `fadeOut(duration?)`      | Opacity 1 → 0                |
-| `slideX(from, to, dur?)`  | Horizontal slide             |
-| `slideY(from, to, dur?)`  | Vertical slide               |
-| `popIn(duration?)`        | Scale + fade entrance        |
-| `riseIn(duration?, dist?)` | Upward fade entrance         |
-| `swingIn(duration?)`      | Rotating slide/fade         |
-| `glitchIn(duration?)`     | Jitter + flash entrance      |
-| `float(duration?, amp?)`   | Gentle vertical bob          |
-| `typewriter(duration?)`   | Character reveal             |
+| `motion.fadeIn(duration?)`       | Opacity 0 → 1                |
+| `motion.fadeOut(duration?)`      | Opacity 1 → 0                |
+| `motion.slideX(from, to, dur?)`  | Horizontal slide             |
+| `motion.slideY(from, to, dur?)`  | Vertical slide               |
+| `motion.popIn(duration?)`        | Scale + fade entrance        |
+| `motion.riseIn(duration?, dist?)` | Upward fade entrance         |
+| `motion.swingIn(duration?)`      | Rotating slide/fade         |
+| `motion.glitchIn(duration?)`     | Jitter + flash entrance      |
+| `motion.float(duration?, amp?)`   | Gentle vertical bob          |
+| `motion.typewriter(duration?)`   | Character reveal             |
 
 More plugins (advanced text animations, pixel effects, 3D, etc.) are planned.
 

package/skills/aider/vidscript-sample.md

@@ -1,21 +1,30 @@
-# 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"
+import motion from "@scenerok/basic-animations"
 
-# 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: motion.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: motion.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: motion.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/aider/vidscript-strict.md

@@ -0,0 +1,113 @@
+# 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: Package imports are mandatory
+
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
+```
+
+Without the owning import, calls like `xai.imagine`, `xai.tts`, `eleven.music`, and `motion.fadeIn` fail validation.
+
+**Never** call package functions without importing the package alias first.
+
+## Rule 2: Use registered plugin surfaces
+
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+
+[-] = video xai.imagine("Prompt here", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Voiceover line", voice: "eve")
+[0s .. 15s] = audio eleven.music("Warm premium music bed", duration: 15, instrumental: true)
+```
+
+For ElevenLabs music, import `@elevenlabs/music` and use `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`.
+
+## 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
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+
+[-] = audio xai.tts("Spoken line", voice: "eve", speed: 1.0)
+
+# Direct music call, no trailing audio params.
+[0s .. 15s] = audio eleven.music("Soft premium ad music", duration: 15, instrumental: true)
+
+# Use a binding when you need volume or fades.
+let bed = eleven.music("Soft premium ad music", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
+```
+
+**Invalid:** `audio eleven.music("...", duration: 15), volume: 0.35` — trailing `, volume` after a direct plugin call is a parse error.
+
+**Invalid:** `eleven.generateMusic(...)` without `import eleven from "@elevenlabs/music"`.
+
+## 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
+import motion from "@scenerok/basic-animations"
+
+[0s .. 2s] = text "Launch", x: "50%", y: "50%", animate: motion.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

@@ -67,37 +67,34 @@ Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignett
 output to "video.mp4", resolution: "1080x1920", fps: 30
 ```
 
-### Module System
+### Package Imports
 
 ```vidscript
-export const BRAND_COLOR = "#FF5733"
-export timeline intro(clip: string, headline: string) {
-  [-] = clip                                # auto-append
-  clip.Trim(start: 0s, end: 3s)
-  [- 2s] = text headline, style: title      # auto-start, 2s duration
-}
-```
-
-```vidscript
-import { intro } from "./timelines.vid"
-import * as pack from "./effects.vid"
-import eleven from "@elevenlabs/tts"  # future scoped package      # from npm registry
-import music from "@elevenlabs/music" # generative music
-use intro at [-] with { clip: main, headline: "Welcome" }
+import xai from "@scenerok/xai"                    # xAI image/video/tts
+import eleven from "@elevenlabs/music"          # ElevenLabs generative music
+import motion from "@scenerok/basic-animations" # text/video animation helpers
 ```
 
 ### Plugin Calls
 
 ```vidscript
-import eleven from "/tts"
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
+
+[-] = video xai.imagine("Cinematic product shot", aspect_ratio: "9:16", duration: 5)
+[-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 
-[-] = 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")
+# ElevenLabs music package functions require an import alias.
+let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
 ```
 
-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** import the package that owns the function: `xai.*` from `@scenerok/xai`, `eleven.*` from `@elevenlabs/music`, and `motion.*` from `@scenerok/basic-animations`. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+
+For ElevenLabs music, import `@elevenlabs/music` and call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Use `let bed = eleven.music(...)` followed by `audio bed, volume: ...` when you need volume or fades.
+
+Read `vidscript-strict.md` for anti-patterns and `examples/system/*.vid` for copy-paste templates (installed with `scenerok skills install`).
 
 ### Placeholders
 
@@ -165,7 +162,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