@scenerok/cli 2.2.0 → 2.4.0

package/README.md

@@ -51,17 +51,17 @@ scenerok auth logout       # Remove credentials
 ### `skills`
 
 ```bash
-scenerok skills install <platform> [--sync]  # Install router skill (+ optional full sync)
-scenerok skills sync                         # Download remote skill bundle
-scenerok skills check [--json]               # Compare local vs remote manifest
-scenerok skills update                       # Refresh outdated skills
-scenerok skills list                         # List remote skills + local status
+scenerok skills install <platform> [--sync]  # Install the scenerok skill (SKILL.md + references/); --sync refreshes it from scenerok.com
+scenerok skills check [--json]               # Compare the installed copy with scenerok.com
+scenerok skills update                       # Download what changed
+scenerok skills sync                         # Download every skill file
+scenerok skills list                         # List skill files and local status
 scenerok skills platforms                    # List supported agent platforms
 ```
 
 Supported platforms: `opencode`, `claude`, `codex`, `cursor`, `aider`
 
-Remote skills are served from https://scenerok.com/.well-known/agent-skills/ and updated on every deploy — no CLI release needed for skill content changes.
+The skill ships inside this package (`skills/scenerok/`), so `install` works offline. scenerok.com serves the same files at https://scenerok.com/.well-known/agent-skills/ and updates them on every deploy; `check` and `update` pick up changes between CLI releases.
 
 ### `validate`
 

package/dist/commands/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgGpC,eAAO,MAAM,aAAa,SAuKvB,CAAC"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqGpC,eAAO,MAAM,aAAa,SAqKvB,CAAC"}

package/dist/commands/skills.js

@@ -1,9 +1,9 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { existsSync, copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { checkSkills, fetchManifest, fetchSkillFile, slugToFilename, } from '../utils/skillsManifest.js';
+import { checkSkills, fetchManifest, fetchSkillFile, skillFiles, } from '../utils/skillsManifest.js';
 function getPlatformConfig(platform) {
     const configs = {
         opencode: {
@@ -29,7 +29,8 @@ function getPlatformConfig(platform) {
     };
     return configs[platform] || null;
 }
-const ROUTER_SKILL = { source: 'skills/shared/SKILL.md', dest: 'SKILL.md' };
+/** The skill this package ships: SKILL.md plus references/, copied from the repo's skills/scenerok/ at build. */
+const BUNDLED_SKILL = 'skills/scenerok';
 async function findSkillSource(sourcePath) {
     const modulePath = join(dirname(new URL(import.meta.url).pathname), '../..', sourcePath);
     if (existsSync(modulePath))
@@ -59,13 +60,18 @@ function printSkillDiff(skills) {
 }
 async function syncSkills(skillDir, slugs) {
     const manifest = await fetchManifest();
-    const toSync = slugs ?? Object.keys(manifest.skills);
+    const files = skillFiles(manifest);
+    const toSync = slugs ?? Object.keys(files);
     let count = 0;
     for (const slug of toSync.sort()) {
-        const content = await fetchSkillFile(slug);
-        const dest = join(skillDir, slugToFilename(slug));
+        const path = files[slug];
+        if (!path)
+            continue;
+        const content = await fetchSkillFile(slug, undefined, path);
+        const dest = join(skillDir, path);
+        mkdirSync(dirname(dest), { recursive: true });
         writeFileSync(dest, content, 'utf8');
-        console.log(chalk.green(`  ✓ ${slugToFilename(slug)}`));
+        console.log(chalk.green(`  ✓ ${path}`));
         count++;
     }
     return count;
@@ -73,9 +79,9 @@ async function syncSkills(skillDir, slugs) {
 export const skillsCommand = new Command('skills')
     .description('Install and sync SceneRok agent skills')
     .addCommand(new Command('install')
-    .description('Install the router skill for a platform')
+    .description('Install the scenerok skill (SKILL.md + references) for a platform')
     .argument('<platform>', 'Agent platform: opencode, claude, codex, cursor, aider')
-    .option('--sync', 'Also download the full remote skill bundle')
+    .option('--sync', 'Then refresh it from scenerok.com (newer than this CLI release)')
     .action(async (platform, opts) => {
     const config = getPlatformConfig(platform);
     if (!config) {
@@ -83,28 +89,28 @@ export const skillsCommand = new Command('skills')
         console.log(chalk.dim('Supported platforms: opencode, claude, codex, cursor, aider'));
         process.exit(1);
     }
-    console.log(chalk.cyan(`\n📦 Installing SceneRok router skill for ${config.name}...\n`));
-    if (!existsSync(config.skillDir)) {
-        mkdirSync(config.skillDir, { recursive: true });
-    }
-    const source = await findSkillSource(ROUTER_SKILL.source);
-    const dest = join(config.skillDir, ROUTER_SKILL.dest);
+    console.log(chalk.cyan(`\n📦 Installing the SceneRok skill for ${config.name}...\n`));
+    const source = await findSkillSource(BUNDLED_SKILL);
     if (!source) {
-        console.log(chalk.red(`  ✗ Router skill not found (${ROUTER_SKILL.source})`));
+        console.log(chalk.red(`  ✗ Bundled skill not found (${BUNDLED_SKILL})`));
         process.exit(1);
     }
-    copyFileSync(source, dest);
-    console.log(chalk.green(`  ✓ ${ROUTER_SKILL.dest} (router)`));
+    // The directory is ours: replace it so files from older installs
+    // (the flat pre-references layout) don't linger.
+    rmSync(config.skillDir, { recursive: true, force: true });
+    mkdirSync(config.skillDir, { recursive: true });
+    cpSync(source, config.skillDir, { recursive: true });
+    console.log(chalk.green('  ✓ SKILL.md'));
+    console.log(chalk.green('  ✓ references/'));
     if (opts.sync) {
-        console.log(chalk.cyan('\n⬇️  Syncing remote skill bundle...\n'));
+        console.log(chalk.cyan('\n⬇️  Refreshing from scenerok.com...\n'));
         await syncSkills(config.skillDir);
     }
-    console.log(chalk.cyan(`\n✅ Router skill installed to ${config.skillDir}\n`));
-    console.log(chalk.dim('Agents fetch latest docs from https://scenerok.com/.well-known/agent-skills/'));
-    console.log(chalk.dim('Offline fallback: scenerok skills sync'));
+    console.log(chalk.cyan(`\n✅ Skill installed to ${config.skillDir}\n`));
+    console.log(chalk.dim('Check for newer docs: scenerok skills check · refresh: scenerok skills update'));
 }))
     .addCommand(new Command('sync')
-    .description('Download the full remote skill bundle locally')
+    .description('Download the latest skill files from scenerok.com')
     .option('--dir <path>', 'Skill directory (auto-detected if omitted)')
     .option('--platform <platform>', 'Platform to resolve skill dir')
     .action(async (opts) => {
@@ -186,8 +192,8 @@ export const skillsCommand = new Command('skills')
         console.log(chalk.cyan('\n📦 SceneRok remote skills\n'));
         printSkillDiff(result.skills);
         console.log(chalk.dim(`\nManifest: ${Object.keys(manifest.skills).length} skills · source: ${manifest.source}`));
-        console.log(chalk.dim('Install router: scenerok skills install <platform>'));
-        console.log(chalk.dim('Sync all:       scenerok skills sync\n'));
+        console.log(chalk.dim('Install: scenerok skills install <platform>'));
+        console.log(chalk.dim('Sync:    scenerok skills sync\n'));
     }
     catch (err) {
         console.log(chalk.red(`❌ ${err.message}`));

package/dist/utils/skillsManifest.d.ts

@@ -2,6 +2,8 @@ export declare const DEFAULT_MANIFEST_URL = "https://scenerok.com/.well-known/ag
 export interface SkillEntry {
     hash: string;
     files: number;
+    /** Location inside an installed skill directory. */
+    path?: string;
 }
 export interface SkillsManifest {
     source: string;
@@ -13,6 +15,7 @@ export interface SkillDiff {
     status: SkillStatus;
     installedHash?: string;
     latestHash?: string;
+    /** Path inside the skill directory. */
     filename: string;
 }
 export interface SkillsCheckResult {
@@ -25,18 +28,25 @@ export interface SkillsCheckResult {
     };
     skills: SkillDiff[];
 }
-/** Map manifest slug to on-disk filename. */
+/** Map manifest slug to its served filename. */
 export declare function slugToFilename(slug: string): string;
+/**
+ * The manifest entries that make up the installed skill, keyed by slug, with
+ * their path inside the skill directory. A manifest from before paths existed
+ * lists every file flat, so all of its entries count, at their flat filenames.
+ */
+export declare function skillFiles(manifest: SkillsManifest): Record<string, string>;
 export declare function hashInstalledFile(filePath: string): SkillEntry | null;
 export declare function hashInstalled(skillDir: string, manifest: SkillsManifest): Record<string, SkillEntry>;
 export declare function diffSkills(installed: Record<string, SkillEntry>, latest: SkillsManifest): Omit<SkillsCheckResult, 'location'>;
 export declare function fetchManifest(url?: string): Promise<SkillsManifest>;
-export declare function fetchSkillFile(slug: string, baseUrl?: string): Promise<string>;
+/** Fetch one skill file. The site serves every file flat, by its basename. */
+export declare function fetchSkillFile(slug: string, baseUrl?: string, path?: string): Promise<string>;
 export declare function locateSkillDir(platform?: string): string | null;
 export declare function checkSkills(opts?: {
     dir?: string;
     manifestUrl?: string;
 }): Promise<SkillsCheckResult>;
-/** List extra local files not in manifest (legacy bundled files). */
+/** List top-level local files the manifest doesn't know (left by older installs). */
 export declare function listExtraLocalFiles(skillDir: string, manifest: SkillsManifest): string[];
 //# sourceMappingURL=skillsManifest.d.ts.map

package/dist/utils/skillsManifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillsManifest.d.ts","sourceRoot":"","sources":["../../src/utils/skillsManifest.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,oBAAoB,gEAC8B,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAWD,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAKrE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAQpG;AAED,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACrC,MAAM,EAAE,cAAc,GACrB,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,CA8BrC;AAED,wBAAsB,aAAa,CAAC,GAAG,SAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQvF;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOpF;AAED,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB/D;AAED,wBAAsB,WAAW,CAAC,IAAI,GAAE;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAMlC;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,EAAE,CAKxF"}
+{"version":3,"file":"skillsManifest.d.ts","sourceRoot":"","sources":["../../src/utils/skillsManifest.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,oBAAoB,gEAC8B,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAWD,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAY3E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAKrE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAOpG;AAED,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACrC,MAAM,EAAE,cAAc,GACrB,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,CA+BrC;AAED,wBAAsB,aAAa,CAAC,GAAG,SAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQvF;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnG;AAED,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB/D;AAED,wBAAsB,WAAW,CAAC,IAAI,GAAE;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAMlC;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,EAAE,CAKxF"}

package/dist/utils/skillsManifest.js

@@ -1,10 +1,12 @@
 /**
- * Remote skill freshness: hash flat markdown/json files against the published manifest.
+ * Skill freshness: hash the installed skill's files against the published manifest.
+ * Manifest entries with a `path` belong to the installed skill (`SKILL.md`,
+ * `references/<file>`); entries without one are site-only docs and are skipped.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 export const DEFAULT_MANIFEST_URL = 'https://scenerok.com/.well-known/agent-skills/manifest.json';
 const TEXT_EXT = new Set(['.md', '.json', '.txt']);
 function hashFileContent(content, ext) {
@@ -13,12 +15,32 @@ function hashFileContent(content, ext) {
     h.update(normalized);
     return h.digest('hex').slice(0, 16);
 }
-/** Map manifest slug to on-disk filename. */
+/** Map manifest slug to its served filename. */
 export function slugToFilename(slug) {
     if (slug === 'catalog-index')
         return 'catalog-index.json';
     return `${slug}.md`;
 }
+/**
+ * The manifest entries that make up the installed skill, keyed by slug, with
+ * their path inside the skill directory. A manifest from before paths existed
+ * lists every file flat, so all of its entries count, at their flat filenames.
+ */
+export function skillFiles(manifest) {
+    const entries = Object.entries(manifest.skills);
+    const hasPaths = entries.some(([, e]) => e.path);
+    const out = {};
+    for (const [slug, entry] of entries) {
+        if (hasPaths) {
+            if (entry.path)
+                out[slug] = entry.path;
+        }
+        else {
+            out[slug] = slugToFilename(slug);
+        }
+    }
+    return out;
+}
 export function hashInstalledFile(filePath) {
     if (!existsSync(filePath))
         return null;
@@ -28,9 +50,8 @@ export function hashInstalledFile(filePath) {
 }
 export function hashInstalled(skillDir, manifest) {
     const out = {};
-    for (const slug of Object.keys(manifest.skills)) {
-        const filename = slugToFilename(slug);
-        const entry = hashInstalledFile(join(skillDir, filename));
+    for (const [slug, path] of Object.entries(skillFiles(manifest))) {
+        const entry = hashInstalledFile(join(skillDir, path));
         if (entry)
             out[slug] = entry;
     }
@@ -39,7 +60,8 @@ export function hashInstalled(skillDir, manifest) {
 export function diffSkills(installed, latest) {
     const skills = [];
     const summary = { current: 0, outdated: 0, missing: 0 };
-    for (const name of Object.keys(latest.skills).sort()) {
+    const files = skillFiles(latest);
+    for (const name of Object.keys(files).sort()) {
         const latestEntry = latest.skills[name];
         const installedEntry = installed[name];
         let status;
@@ -60,7 +82,7 @@ export function diffSkills(installed, latest) {
             status,
             installedHash: installedEntry?.hash,
             latestHash: latestEntry.hash,
-            filename: slugToFilename(name),
+            filename: files[name],
         });
     }
     return {
@@ -79,9 +101,10 @@ export async function fetchManifest(url = DEFAULT_MANIFEST_URL) {
     }
     return data;
 }
-export async function fetchSkillFile(slug, baseUrl) {
+/** Fetch one skill file. The site serves every file flat, by its basename. */
+export async function fetchSkillFile(slug, baseUrl, path) {
     const site = (baseUrl ?? 'https://scenerok.com').replace(/\/$/, '');
-    const filename = slugToFilename(slug);
+    const filename = path ? basename(path) : slugToFilename(slug);
     const url = `${site}/.well-known/agent-skills/${filename}`;
     const res = await fetch(url);
     if (!res.ok)
@@ -112,11 +135,11 @@ export async function checkSkills(opts = {}) {
     const diff = diffSkills(installed, latest);
     return { location, ...diff };
 }
-/** List extra local files not in manifest (legacy bundled files). */
+/** List top-level local files the manifest doesn't know (left by older installs). */
 export function listExtraLocalFiles(skillDir, manifest) {
     if (!existsSync(skillDir))
         return [];
-    const known = new Set(Object.keys(manifest.skills).map(slugToFilename));
+    const known = new Set(Object.values(skillFiles(manifest)).map((p) => p.split('/')[0]));
     known.add('SKILL.md');
     return readdirSync(skillDir).filter((f) => !known.has(f));
 }

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

@@ -20,6 +20,6 @@ import motion from "@scenerok/basic-animations"
 [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
+[0s .. 15s] = filter "saturation", amount: 1.12
 
 output to "rokmilk-chocolate-promo.mp4", resolution: "1080x1920", fps: 30, background: "#1A0F05"

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

@@ -16,6 +16,6 @@ main.Trim(start: 0s, end: 12s)
 [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
+[0s .. 12s] = filter "saturation", amount: 1.12
 
 output to "voice-visual-promo.mp4", resolution: "1080x1920", fps: 30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/cli",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "SceneRok CLI - Create videos from your terminal and agent workflows",
   "type": "module",
   "bin": {
@@ -14,10 +14,10 @@
     "README.md"
   ],
   "scripts": {
+    "prebuild": "node ../../scripts/copy-scenerok-skill.mjs .",
     "build": "tsc",
     "dev": "tsc --watch",
-    "sync:skills": "node ../../scripts/sync-scenerok-skills.mjs",
-    "prepublishOnly": "npm run sync:skills && npm run build"
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "scenerok",

package/skills/scenerok/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: scenerok
+description: >-
+  Writes, validates, and renders SceneRok videos from VidScript (.vid) or the
+  TypeScript @scenerok/sdk: promos, reels, explainers, social cards, motion
+  graphics, and edits of existing footage (trims, speed changes, picture-in-picture,
+  blend modes, masks, crops, color grades, LUTs, audio mixing and ducking, captions,
+  timecode). Use when the user wants to make or edit a video with SceneRok, or
+  mentions VidScript, a .vid file, @scenerok/sdk, the scenerok CLI, or the SceneRok
+  MCP tools.
+---
+
+# SceneRok
+
+SceneRok turns a script into an MP4. Write the script in VidScript or in
+TypeScript with `@scenerok/sdk`; both compile to the same timeline. Then
+validate it, render it, and check the rendered file.
+
+## Choose the language
+
+| | VidScript (`.vid`) | TypeScript (`@scenerok/sdk`, `.ts`) |
+| --- | --- | --- |
+| Use for | Promos, reels, templates, and every editing action: masks, blends, crops, speed ramps, ducking, LUTs, timecode | Timelines built by code: loops over data, computed timing across many clips |
+| Start with | [vidscript-strict.md](references/vidscript-strict.md) | [sdk-guide.md](references/sdk-guide.md) |
+
+The SDK has the same values and placement (masks, blends, crops, groups,
+ducking, timecode); LUT files, caption files, several outputs, and offline
+media are VidScript only. A `.vid` can `import kit from "./kit.ts"` and place
+the module's exports (`[0s .. 3s] = kit.title`), so build data-driven parts in
+TypeScript and finish the edit in VidScript.
+
+## Workflow
+
+Copy this checklist into your notes and work through it:
+
+```text
+- [ ] 1. Identify the environment (web editor, CLI, ChatGPT, MCP, chat without tools)
+- [ ] 2. Classify the request; read only the references it needs (table below)
+- [ ] 3. Branded promo with unknown colors or logo: ask once
+- [ ] 4. Probe real assets: type, width, height, duration
+- [ ] 5. Write the script
+- [ ] 6. Validate. Fix every error and validate again until clean
+- [ ] 7. Uses TTS or generated media: deep-validate and fix the report (CLI only)
+- [ ] 8. Render
+- [ ] 9. Check the rendered MP4; fix and repeat from step 6 if it reports problems (CLI only)
+```
+
+With the CLI:
+
+```bash
+scenerok validate script.vid                                    # or scene.ts
+scenerok validate script.vid --generate-assets --report-json    # billed; VidScript only
+scenerok render script.vid --watch
+scenerok lint-video <render-id> --cost medium --json            # billed
+```
+
+`scenerok render script.vid --validate` renders and checks the MP4 in one step.
+
+The deep validation generates the real speech and media (cached for the
+render) and reports text that runs off-canvas or was shrunk (`offCanvas`,
+`wasShrunk`), overlapping elements (`collisions`), and voice-over-voice
+overlaps (`audio.overlaps`; music under voice is fine). The web editor,
+ChatGPT, and MCP have their own validate and render calls but no deep
+validation or MP4 check, and can't read local files:
+[environments.md](references/environments.md).
+
+## Rules that prevent most failures
+
+1. **Import before calling.** `import xai from "@scenerok/xai"`, then
+   `xai.tts(…)`. The same for `@scenerok/cloudflare`, `@elevenlabs/music`,
+   `@scenerok/basic-animations`, `@scenerok/animations`,
+   `@scenerok/transitions`, and `@scenerok/media`.
+2. **Never guess a duration.** Bind generated media and use its length:
+   `let vo = xai.tts(…)` then `[0 .. vo.duration] = audio vo`.
+3. **Never guess text coordinates.** Use `area: "title"` (also `stage`,
+   `lower-third`, `caption`, or your own `grid`).
+4. **No text in generated images or video.** Every prompt asks for no text,
+   letters, logos, or watermarks; put all copy in `text` lines.
+5. **Edits return values; place the result.**
+   `[0s .. 4s] = clip.Trim(2s, 6s).Crop(420, 0, 1080, 1920)`. Put one video
+   over another with `Overlay`, `Composite`, or `blend:`.
+6. **Use only documented syntax.** Don't invent functions or parameters. A
+   validation error names the problem; fix that line rather than rewriting the
+   script.
+
+## References
+
+Read the ones the task needs. Paths are relative to this file.
+
+| Task | Read |
+| --- | --- |
+| Any VidScript | [vidscript-strict.md](references/vidscript-strict.md) (always) |
+| Editing and compositing: trims, speed, reverse, freeze, picture-in-picture, blend modes, masks, crops, split screens, audio mixing and ducking, grading and LUTs, captions, timecode | [editing-actions.md](references/editing-actions.md) |
+| Full grammar | [vidscript-guide.md](references/vidscript-guide.md) |
+| A complete commented promo script | [vidscript-sample.md](references/vidscript-sample.md) |
+| TypeScript SDK | [sdk-guide.md](references/sdk-guide.md) |
+| Probing media, grabbing frames, beats | [media-stdlib.md](references/media-stdlib.md) |
+| Generated images and video | [ai-models.md](references/ai-models.md) |
+| Voiceover | [tts.md](references/tts.md) |
+| Music beds | [music.md](references/music.md) |
+| Animated blocks: lower thirds, code, social cards, text animations, custom HTML | [animations-picker.md](references/animations-picker.md), then [animations-catalog.md](references/animations-catalog.md) for every parameter |
+| Titles animated with motion primitives | [text-styles.md](references/text-styles.md) |
+| Scene transitions | [transitions-catalog.md](references/transitions-catalog.md) |
+| Filters, VFX, custom shaders | [shaders-filters.md](references/shaders-filters.md) |
+| A promo from a product URL | [workflow.md](references/workflow.md), [brand-setup.md](references/brand-setup.md) |
+| Which workflow fits the request | [intent-router.md](references/intent-router.md) |
+| Where you are running and what you can call | [environments.md](references/environments.md) |
+| Every catalog item as data | [catalog-index.json](references/catalog-index.json) |
+
+Without local files (for example, only this text was pasted into a chat),
+fetch any reference from
+`https://scenerok.com/.well-known/agent-skills/<filename>`. Setup guides for
+chat apps are there too: `consumer-chat-apps.md`,
+`chatgpt-gpt-instructions.md`, `gemini-gem-instructions.md`, `grok-skill.md`.
+Previews of every catalog item: https://scenerok.com/catalog.
+
+## Minimal VidScript
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+input hero = "https://cdn.example.com/clip.mp4"
+[0s .. 4s] = hero.Trim(1s, 5s)
+[0s .. 3s] = text "Hello", style: title, color: "#FFFFFF", area: "title", animate: motion.fadeIn(0.8s)
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+## Minimal SDK scene
+
+```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()
+}
+```
+
+Validate and render it like a `.vid`: `scenerok validate scene.ts`.
+
+## Keeping the skill current
+
+`scenerok skills check` compares the installed copy with scenerok.com;
+`scenerok skills update` downloads what changed.

package/skills/{remote → scenerok/references}/ai-models.md

@@ -12,8 +12,6 @@
 
 **Always import:** `import xai from "@scenerok/xai"` and/or `import cf from "@scenerok/cloudflare"`.
 
-Prefer **720p** (or the model default) for generative video. Cap spend with duration, not exotic post-steps.
-
 Generative prompts must require: no text, no words, no letters, no captions, no logos, no watermarks, no readable UI copy.
 
 ## Examples
@@ -63,3 +61,4 @@ import xai from "@scenerok/xai"
 
 [prev .. prev + 0.8s] = text "Grok imagine()", font: "Inter Bold", size: 56, color: "#FFFFFF", shadow_color: "#000000", shadow_blur: 12, position: "bottom", align: "center"
 ```
+