From 1627ad3920affabfd1f1f86adbcc1f0c7fb9bf30 Mon Sep 17 00:00:00 2001
From: Michailbul <mbuloichykai@gmail.com>
Date: Fri, 23 Jan 2026 02:13:18 +0300
Subject: [PATCH 1/5] docs(agent): add confirmation-first execution guidance

---
 README.md                             | 10 +++++++++-
 docs/react.md                         |  8 ++++++++
 docs/sdk.md                           | 10 ++++++++++
 skills/varg-video-generation/SKILL.md | 19 +++++++++++++++++--
 src/init.ts                           | 23 ++++++++++++++---------
 5 files changed, 58 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 675fcaaf..830a310d 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,15 @@ run it:
 bun run hello.tsx
 ```
 
+## agent usage (confirmation before costs)
+
+when using the agent in this repo:
+
+- ask for confirmation before any command that triggers paid api calls
+- create tsx when needed, then run: `bun run src/cli/index.ts render <file.tsx> -o output/<name>.mp4`
+- use `bun run src/cli/index.ts preview <file.tsx>` for zero-cost checks
+- use single-step actions with: `bun run src/cli/index.ts run <action> ...`
+
 ## installation
 
 ```bash
@@ -534,4 +543,3 @@ see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
 
 Apache-2.0 — see [LICENSE.md](LICENSE.md)
 
-
diff --git a/docs/react.md b/docs/react.md
index 96dcc2a0..2817f003 100644
--- a/docs/react.md
+++ b/docs/react.md
@@ -22,6 +22,14 @@ await render(
 );
 ```
 
+## agent execution (confirmation before costs)
+
+when using the agent in this repo:
+
+- ask for confirmation before any command that triggers paid api calls
+- create tsx when needed, then run `bun run src/cli/index.ts render <file.tsx> -o output/<name>.mp4`
+- use `bun run src/cli/index.ts preview <file.tsx>` for zero-cost checks
+
 ## core concepts
 
 ### everything is cached
diff --git a/docs/sdk.md b/docs/sdk.md
index 2b3de16b..82f6d571 100644
--- a/docs/sdk.md
+++ b/docs/sdk.md
@@ -39,6 +39,16 @@ const { video } = await generateVideo({
 });
 ```
 
+## agent execution (confirmation before costs)
+
+when using the agent in this repo:
+
+- ask for confirmation before any command that triggers paid api calls
+- prefer cli execution for outputs:
+  - `bun run src/cli/index.ts run <action> ...`
+  - `bun run src/cli/index.ts render <file.tsx> -o output/<name>.mp4`
+  - `bun run src/cli/index.ts preview <file.tsx>` for zero-cost checks
+
 ---
 
 ## core concepts
diff --git a/skills/varg-video-generation/SKILL.md b/skills/varg-video-generation/SKILL.md
index 80c23ca0..d5e1afff 100644
--- a/skills/varg-video-generation/SKILL.md
+++ b/skills/varg-video-generation/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: varg-video-generation
-description: Generate AI videos using varg SDK React engine. Use when creating videos, animations, talking characters, slideshows, or social media content. Always run onboarding first to check API keys.
+description: This skill should be used when the user asks to "create a video", "generate a video", "render a tsx", "make a slideshow", "create a talking character", or "animate an image" using the varg React engine.
 license: MIT
 metadata:
   author: vargHQ
@@ -13,6 +13,14 @@ allowed-tools: Bash(bun:*) Bash(cat:*) Read Write Edit
 
 Generate AI videos using declarative JSX syntax with automatic caching and parallel generation.
 
+## Execution policy (must follow)
+
+- Ask for confirmation before running any command that triggers paid API calls.
+- Proceed without extra confirmation only when the user explicitly asks to run/render/generate now.
+- Prefer CLI execution after creating TSX; do not leave TSX files unrun.
+- Prefer `preview` for zero-cost checks before paid renders.
+- Write outputs to `output/` and do not commit new outputs.
+
 ## Quick Setup
 
 Run the setup script to initialize a project:
@@ -21,7 +29,7 @@ Run the setup script to initialize a project:
 bun scripts/setup.ts
 ```
 
-Or manually check API keys:
+Or check API keys directly:
 
 ```bash
 cat .env 2>/dev/null | grep -E "^(FAL_API_KEY|ELEVENLABS_API_KEY)=" || echo "No API keys found"
@@ -142,6 +150,13 @@ See [references/templates.md](references/templates.md) for more templates.
 ## Running Videos
 
 ```bash
+# preferred: render via CLI after creating TSX
+bun run src/cli/index.ts render your-video.tsx -o output/your-video.mp4
+
+# optional: fast, zero-cost preview
+bun run src/cli/index.ts preview your-video.tsx
+
+# direct execution (acceptable but less consistent)
 bun run your-video.tsx
 ```
 
diff --git a/src/init.ts b/src/init.ts
index 3de40678..026f2efd 100644
--- a/src/init.ts
+++ b/src/init.ts
@@ -238,11 +238,12 @@ const character = Image({ prompt: "blue robot" });
 `;
 
 // Example video file
-const EXAMPLE_VIDEO = `/**
+const EXAMPLE_VIDEO = `/** @jsxImportSource vargai */
+/**
  * Example: Simple animated video
  * Run: bun run examples/my-first-video.tsx
  */
-import { render, Render, Clip, Image, Animate } from "vargai/react";
+import { render, Render, Clip, Image, Video } from "vargai/react";
 import { fal } from "vargai/ai";
 
 async function main() {
@@ -251,13 +252,17 @@ async function main() {
   await render(
     <Render width={720} height={720}>
       <Clip duration={3}>
-        <Animate
-          image={Image({
-            prompt: "a friendly robot waving hello, cartoon style, blue colors",
-            model: fal.imageModel("flux-schnell"),
-            aspectRatio: "1:1",
-          })}
-          motion="robot waves hello, friendly gesture"
+        <Video
+          prompt={{
+            text: "robot waves hello, friendly gesture",
+            images: [
+              Image({
+                prompt: "a friendly robot waving hello, cartoon style, blue colors",
+                model: fal.imageModel("flux-schnell"),
+                aspectRatio: "1:1",
+              }),
+            ],
+          }}
           model={fal.videoModel("wan-2.5")}
           duration={3}
         />

From 611f6c009ad1a00c5212d518a0ddc3f72878a87b Mon Sep 17 00:00:00 2001
From: Michailbul <mbuloichykai@gmail.com>
Date: Fri, 23 Jan 2026 02:07:09 +0300
Subject: [PATCH 2/5] chore(gitignore): ignore cache and output

---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitignore b/.gitignore
index 8cfcecdc..86b509f5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,3 +48,6 @@ lib
 
 output
 *.mp4
+
+.cache/
+output/

From 89f76e271a4039481760ee3296cbd1cc3208cd29 Mon Sep 17 00:00:00 2001
From: Michailbul <mbuloichykai@gmail.com>
Date: Fri, 23 Jan 2026 02:05:49 +0300
Subject: [PATCH 3/5] feat(init): install pipeline cookbook skill

---
 SKILLS.md                                     | 172 +----
 skills/vargai-pipeline-cookbooks/SKILL.md     |  29 +
 .../references/remotion-video.md              | 585 +++++++++++++++
 .../references/round-video-character.md       | 337 +++++++++
 .../references/talking-character-pipeline.md  | 285 ++++++++
 .../references/talking-character.md           |  59 ++
 .../references/text-to-tiktok.md              | 669 ++++++++++++++++++
 .../references/trendwatching.md               | 156 ++++
 .../scripts/animate-frames-parallel.ts        |  84 +++
 .../scripts/combine-scenes.sh                 |  53 ++
 .../scripts/generate-frames-parallel.ts       |  99 +++
 .../scripts/still-to-video.sh                 |  37 +
 src/init.ts                                   | 272 +++----
 13 files changed, 2491 insertions(+), 346 deletions(-)
 create mode 100644 skills/vargai-pipeline-cookbooks/SKILL.md
 create mode 100644 skills/vargai-pipeline-cookbooks/references/remotion-video.md
 create mode 100644 skills/vargai-pipeline-cookbooks/references/round-video-character.md
 create mode 100644 skills/vargai-pipeline-cookbooks/references/talking-character-pipeline.md
 create mode 100644 skills/vargai-pipeline-cookbooks/references/talking-character.md
 create mode 100644 skills/vargai-pipeline-cookbooks/references/text-to-tiktok.md
 create mode 100644 skills/vargai-pipeline-cookbooks/references/trendwatching.md
 create mode 100644 skills/vargai-pipeline-cookbooks/scripts/animate-frames-parallel.ts
 create mode 100755 skills/vargai-pipeline-cookbooks/scripts/combine-scenes.sh
 create mode 100644 skills/vargai-pipeline-cookbooks/scripts/generate-frames-parallel.ts
 create mode 100755 skills/vargai-pipeline-cookbooks/scripts/still-to-video.sh

diff --git a/SKILLS.md b/SKILLS.md
index 223dee56..33eb6bdd 100644
--- a/SKILLS.md
+++ b/SKILLS.md
@@ -1,173 +1,39 @@
 # agent skills
 
-this sdk includes claude code agent skills for each service. each skill is co-located with its service code.
+this repo exposes a small set of claude code skills plus a cli. use skills for guidance and run the cli to produce outputs.
 
 ## available skills
 
-### service skills
+1. **varg-video-generation** (`skills/varg-video-generation/`)
+   - generate videos with the react engine
+   - agent should create tsx if needed, then run a render after confirmation
+   - cli: `bun run src/cli/index.ts render <file.tsx> [-o output.mp4]`
+   - preview: `bun run src/cli/index.ts preview <file.tsx>`
 
-located in `service/<name>/SKILL.md`:
+2. **vargai-pipeline-cookbooks** (`skills/vargai-pipeline-cookbooks/`)
+   - end-to-end workflows (talking character, text-to-tiktok, round selfie, trendwatching, remotion)
+   - source cookbooks in `pipeline/cookbooks/`
 
-1. **image-generation** (`service/image/`)
-   - generate ai images using fal (flux models) or higgsfield soul characters
-   - cli: `bun run service/image fal|soul <prompt> [options]`
+## agent execution policy (important)
 
-2. **video-generation** (`service/video/`)
-   - generate videos from images (local or url) or text prompts using fal.ai
-   - supports local image files - automatically uploads to fal storage
-   - cli: `bun run service/video from_image|from_text <args>`
+- ask for confirmation before running any command that triggers paid api calls
+- if the user explicitly says "run/render/generate now," proceed without extra confirmation
+- prefer cli execution over leaving tsx files unrun
+- write outputs to `output/` and do not commit new outputs
 
-3. **voice-synthesis** (`service/voice/`)
-   - generate realistic text-to-speech audio using elevenlabs
-   - cli: `bun run service/voice generate|elevenlabs <text> [options]`
+## cli actions (non-skill)
 
-3b. **music-generation** (`lib/elevenlabs.ts`)
-   - generate music from text prompts using elevenlabs
-   - generate sound effects from descriptions
-   - cli: `bun run lib/elevenlabs.ts music|sfx <prompt> [options]`
-
-4. **video-lipsync** (`service/sync/`)
-   - sync video with audio using wav2lip or simple overlay
-   - cli: `bun run service/sync sync|wav2lip|overlay <args>`
-
-5. **video-captions** (`service/captions/`)
-   - add auto-generated or custom subtitles to videos
-   - cli: `bun run service/captions <videoPath> [options]`
-
-6. **video-editing** (`service/edit/`)
-   - edit videos with ffmpeg (resize, trim, concat, social media prep)
-   - cli: `bun run service/edit social|montage|trim|resize|merge_audio <args>`
-
-7. **audio-transcription** (`service/transcribe/`)
-   - transcribe audio to text or subtitles using groq/fireworks
-   - cli: `bun run service/transcribe <audioUrl> <provider> [outputPath]`
-
-### library skills
-
-8. **apify-scraping** (`lib/apify.ts`)
-   - run apify actors for web scraping (tiktok, google maps, social media, etc.)
-   - cli: `bun run lib/apify.ts run <actor_id> [input_json]`
-   - example: `bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["viral"],"resultsPerPage":10}'`
-
-### utility skills
-
-9. **telegram-send** (external: `/Users/aleks/Github/Badaboom1995/rumble-b2c`)
-   - send videos to telegram users/channels as round videos
-   - automatically converts to 512x512 square format for telegram
-   - cli: `cd /Users/aleks/Github/Badaboom1995/rumble-b2c && bun run scripts/telegram-send-video.ts <videoPath> <@username>`
-   - example: `cd /Users/aleks/Github/Badaboom1995/rumble-b2c && bun run scripts/telegram-send-video.ts /path/to/video.mp4 @caffeinum`
-
-### pipeline skills
-
-located in `pipeline/cookbooks/SKILL.md`:
-
-10. **talking-character-pipeline** (`pipeline/cookbooks/`)
-    - complete workflow to create talking character videos
-    - combines: character generation → voiceover → animation → lipsync → captions → social prep
-
-11. **round-video-character** (`pipeline/cookbooks/round-video-character.md`)
-    - create realistic round selfie videos for telegram using nano banana pro + wan 2.5
-    - workflow: generate selfie first frame (person in setting) → voiceover → wan 2.5 video
-    - uses: `bun run lib/fal.ts`, `bun run lib/replicate.ts`, `bun run lib/elevenlabs.ts`
-    - input: text script + profile photo
-    - output: extreme close-up selfie video with authentic camera shake, lighting, and audio
-
-12. **trendwatching** (`pipeline/cookbooks/trendwatching.md`)
-    - discover viral tiktok content for any topic/hashtag
-    - uses apify tiktok scraper to find trending videos
-    - get engagement metrics: plays, likes, shares, comments
-    - cli: `bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["topic"],"resultsPerPage":10}'`
-
-## structure
-
-each skill follows this pattern:
-
-```
-service/<name>/
-├── index.ts      # service implementation
-└── SKILL.md      # claude code agent skill
-```
-
-## how skills work
-
-skills are **model-invoked** - claude autonomously decides when to use them based on your request and the skill's description.
-
-**example:**
-- you say: "create a talking character video"
-- claude reads `talking-character-pipeline` skill
-- claude executes the workflow using the pipeline steps
-
-## using skills
-
-### in claude code
-
-skills are automatically discovered when you're in the sdk directory:
-
-```
-user: create an image of a sunset
-claude: [uses image-generation skill]
-        bun run service/image fal "beautiful sunset over mountains"
-```
-
-### manually
-
-you can also run services directly:
+use `varg run` for single-step actions:
 
 ```bash
-# generate image
-bun run service/image fal "sunset over mountains" true
-
-# generate video from that image
-bun run service/video from_image "camera pan" https://image-url.jpg 5 true
-
-# add voice
-bun run service/voice elevenlabs "this is a beautiful sunset" rachel true
-
-# sync with video
-bun run service/sync wav2lip https://video-url.mp4 https://audio-url.mp3
+bun run src/cli/index.ts run image|video|voice|music|transcribe|captions|sync|upload|edit --help
 ```
 
-## skill features
-
-each skill includes:
-
-- **name**: unique skill identifier
-- **description**: when claude should use this skill
-- **allowed-tools**: restricted to Read, Bash for safety
-- **usage examples**: cli and programmatic examples
-- **when to use**: specific use cases
-- **tips**: best practices
-- **environment variables**: required api keys
-
-## benefits
-
-- **discoverability**: claude knows all available services
-- **context**: skills provide usage examples and best practices
-- **safety**: `allowed-tools` limits to read-only and bash execution
-- **documentation**: skills serve as living documentation
-
-## skill reference
-
-| skill | service | primary use case |
-|-------|---------|------------------|
-| image-generation | image | create ai images, character headshots |
-| video-generation | video | animate images, generate video clips |
-| voice-synthesis | voice | text-to-speech, voiceovers |
-| music-generation | elevenlabs | generate music, create sound effects |
-| video-lipsync | sync | sync audio with video, talking characters |
-| video-captions | captions | add subtitles, accessibility |
-| video-editing | edit | resize, trim, social media optimization |
-| audio-transcription | transcribe | speech-to-text, subtitle generation |
-| apify-scraping | lib/apify | web scraping via apify actors (tiktok, etc.) |
-| telegram-send | external | send videos to telegram as round videos |
-| talking-character-pipeline | pipeline | end-to-end talking character videos |
-| round-video-character | pipeline | telegram round selfie videos with wan 2.5 |
-| trendwatching | pipeline | discover viral tiktok content by hashtag |
-
 ## see also
 
 - [README.md](README.md) - sdk overview and installation
-- [STRUCTURE.md](STRUCTURE.md) - detailed module organization
+- [docs/react.md](docs/react.md) - jsx rendering
+- [docs/sdk.md](docs/sdk.md) - ai sdk usage
 - [pipeline/cookbooks/talking-character.md](pipeline/cookbooks/talking-character.md) - talking character workflow
 - [pipeline/cookbooks/round-video-character.md](pipeline/cookbooks/round-video-character.md) - telegram round selfie video cookbook
 - [pipeline/cookbooks/trendwatching.md](pipeline/cookbooks/trendwatching.md) - discover viral tiktok content
diff --git a/skills/vargai-pipeline-cookbooks/SKILL.md b/skills/vargai-pipeline-cookbooks/SKILL.md
new file mode 100644
index 00000000..0ab265cc
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: vargai-pipeline-cookbooks
+description: This skill should be used when the user asks to "create a talking character pipeline", "make a text-to-tiktok video", "build a round selfie video for Telegram", "do trendwatching with Apify", or "create a Remotion video pipeline".
+version: 0.1.0
+allowed-tools: Read, Bash
+---
+
+# pipeline cookbooks
+
+Provide complete, multi-step workflows for common varg pipelines. Select the closest cookbook and follow its steps end-to-end.
+
+## select a cookbook
+
+- **Talking character (full workflow)**: `references/talking-character-pipeline.md`
+- **Talking character (short form)**: `references/talking-character.md`
+- **Text-to-TikTok**: `references/text-to-tiktok.md`
+- **Round video character (Telegram selfie)**: `references/round-video-character.md`
+- **Trendwatching (Apify + TikTok)**: `references/trendwatching.md`
+- **Remotion editing pipeline**: `references/remotion-video.md`
+
+## scripts
+
+Use helper scripts from `scripts/` when the cookbook calls for them. Avoid editing scripts unless requested.
+
+## notes
+
+- Assume Bun and the varg SDK are available.
+- Many steps require API keys (`FAL_API_KEY`, `ELEVENLABS_API_KEY`, `REPLICATE_API_TOKEN`, `GROQ_API_KEY`).
+- Prefer the full talking-character pipeline when quality matters; use the short form for quick tests.
diff --git a/skills/vargai-pipeline-cookbooks/references/remotion-video.md b/skills/vargai-pipeline-cookbooks/references/remotion-video.md
new file mode 100644
index 00000000..c4520d9f
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/references/remotion-video.md
@@ -0,0 +1,585 @@
+# remotion video creation pipeline
+
+## overview
+create programmatic videos using react components with remotion
+
+## what remotion can do
+
+### video editing & effects
+- **trim & cut**: extract specific frame ranges from videos
+- **zoom & pan**: smooth ken burns effects, dynamic camera movements
+- **speed control**: slow motion, time-lapse, variable playback speed
+- **filters**: apply CSS filters (brightness, contrast, blur, grayscale)
+- **transitions**: crossfades, wipes, custom transitions between clips
+
+### combining content
+- **concatenate videos**: join multiple videos sequentially
+- **multi-track**: side-by-side, grid layouts, picture-in-picture
+- **audio mixing**: combine background music, voiceover, sound effects
+- **volume control**: fade in/out, dynamic volume adjustment
+- **layering**: overlay graphics, text, images on video
+
+### beautiful subtitles
+- **word-by-word captions**: sync text with audio timing
+- **custom styling**: fonts, colors, backgrounds, borders
+- **animations**: fade in/out, slide up, bounce effects
+- **positioning**: center, bottom, top, custom placement
+- **karaoke mode**: highlight current word
+- **rich formatting**: bold, italic, emoji, multi-line
+
+### thumbnail generation
+- **specific frame render**: capture any frame as still image using renderStill
+- **custom thumbnails**: create compositions with overlaid text/graphics
+- **multiple previews**: render several frames at different timestamps
+- **branded thumbnails**: add logos, titles, watermarks to frame captures
+
+### advanced capabilities
+- **motion graphics**: animated text, shapes, data visualizations
+- **responsive layouts**: adapt to different aspect ratios
+- **programmatic content**: generate videos from data/templates
+- **frame-perfect timing**: precise control down to single frame
+- **react ecosystem**: use any react library (charts, animations, etc)
+
+## when to use
+- need precise control over video composition
+- want to add dynamic captions/subtitles
+- combining multiple videos with effects
+- creating videos from templates
+- need frame-perfect synchronization
+- editing videos programmatically
+- generating thumbnails and previews
+- creating social media content at scale
+
+## prerequisites
+```bash
+bun install remotion @remotion/cli
+```
+
+## pipeline steps
+
+### step 1: analyze source media
+probe all input videos to get metadata
+
+```bash
+bun run lib/ffmpeg.ts probe media/video1.mp4
+bun run lib/ffmpeg.ts probe media/video2.mp4
+```
+
+**capture:**
+- duration (seconds)
+- fps (frames per second)
+- resolution (width x height)
+- codec
+
+**calculate:**
+- total frames = duration * fps
+- end frame for concatenation
+
+### step 2: setup composition
+```bash
+bun run lib/remotion/index.ts create MyVideo
+```
+
+**output:**
+- compositionPath: lib/remotion/compositions/MyVideo.tsx
+- rootPath: lib/remotion/compositions/MyVideo.root.tsx
+- compositionsDir: lib/remotion/compositions/
+
+### step 3: create composition component
+edit generated file `lib/remotion/compositions/MyVideo.tsx`
+
+**media files:**
+- copy media to `lib/remotion/public/` directory
+- use `staticFile("filename.ext")` to reference files
+- never use absolute paths in compositions
+
+```bash
+mkdir -p lib/remotion/public
+cp media/video.mp4 media/audio.mp3 lib/remotion/public/
+```
+
+if using subtitles, copy SRT and read:
+```bash
+cp media/subtitles.srt lib/remotion/public/
+```
+
+```typescript
+import { staticFile } from "remotion";
+const srtContent = await Bun.file(staticFile("subtitles.srt")).text();
+```
+
+**basic structure:**
+```typescript
+import { AbsoluteFill, OffthreadVideo, useCurrentFrame, useVideoConfig, staticFile } from "remotion";
+
+export const MyComposition: React.FC = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  
+  const video = staticFile("video1.mp4");
+  
+  return (
+    <AbsoluteFill>
+      <OffthreadVideo src={video} />
+    </AbsoluteFill>
+  );
+};
+```
+
+**for captions:**
+```typescript
+// parse SRT at top of file
+const subtitles = parseSRT(`1
+00:00:00,231 --> 00:00:00,491
+Hello
+
+2
+00:00:00,491 --> 00:00:00,651
+World
+`);
+
+// in component
+const currentTime = frame / fps;
+const currentSubtitle = subtitles.find(
+  sub => currentTime >= sub.startTime && currentTime <= sub.endTime
+);
+
+{currentSubtitle && (
+  <div style={{
+    fontFamily: "Inter",
+    fontSize: 48,
+    fontWeight: "bold",
+    color: "white",
+    backgroundColor: "rgba(0,0,0,0.7)",
+    padding: "20px 40px",
+    borderRadius: 12,
+  }}>
+    {currentSubtitle.text}
+  </div>
+)}
+```
+
+**for concatenation:**
+```typescript
+const video1 = staticFile("video1.mp4");
+const video2 = staticFile("video2.mp4");
+
+const video1EndFrame = 1430; // calculated from probe
+const video2StartFrame = video1EndFrame;
+
+{frame < video1EndFrame ? (
+  <OffthreadVideo src={video1} />
+) : (
+  <OffthreadVideo 
+    src={video2}
+    startFrom={Math.floor((frame - video2StartFrame) * (24/30))}
+  />
+)}
+```
+
+### step 4: register composition
+edit generated file `lib/remotion/compositions/MyVideo.root.tsx`
+
+```typescript
+import React from "react";
+import { Composition, registerRoot } from "remotion";
+import { MyComposition } from "./MyVideo";
+
+const fps = 30;
+const durationInFrames = 1582;  // total frames
+const width = 1920;
+const height = 1080;
+
+registerRoot(() => {
+  return (
+    <>
+      <Composition
+        id="MyVideo"
+        component={MyComposition}
+        durationInFrames={durationInFrames}
+        fps={fps}
+        width={width}
+        height={height}
+      />
+    </>
+  );
+});
+```
+
+**calculate durationInFrames:**
+- single video: `duration * fps`
+- concatenated: `video1Frames + video2Frames`
+- use fps from probe results
+
+### step 5: verify compositions
+```bash
+bun run lib/remotion/index.ts compositions lib/remotion/compositions/MyVideo.root.tsx
+```
+
+**check output:**
+- composition id matches
+- dimensions are correct
+- fps is correct
+- durationInFrames is correct
+
+### step 6: render video
+```bash
+bun run lib/remotion/index.ts render lib/remotion/compositions/MyVideo.root.tsx MyVideo media/output.mp4
+```
+
+**rendering process:**
+1. bundles project with webpack
+2. launches chrome headless
+3. renders each frame
+4. encodes with ffmpeg (h264 codec)
+5. saves to output.mp4
+
+**monitor:**
+- progress percentage
+- frames rendered
+- frames encoded
+
+### step 7: verify output
+```bash
+bun run lib/ffmpeg.ts probe media/output.mp4
+```
+
+check:
+- duration matches expected
+- fps is correct
+- resolution is correct
+
+## common workflows
+
+### workflow 1: video + captions
+```
+1. probe video → get duration, fps
+2. setup composition
+3. create composition with Video + captions
+4. parse SRT file into subtitle array
+5. sync captions with useCurrentFrame()
+6. register composition in root
+7. render
+```
+
+### workflow 2: concatenate videos
+```
+1. probe all videos → get durations, fps
+2. calculate frame boundaries
+3. setup composition
+4. create composition with frame-based switching
+5. use absolute paths to media files
+6. handle fps conversions if needed
+7. register composition with total duration
+8. render
+```
+
+### workflow 3: video with overlay graphics
+```
+1. probe video
+2. setup composition
+3. copy video + images to lib/remotion/public/
+4. create composition with layers using staticFile()
+5. use interpolate() for animations
+6. position overlays with AbsoluteFill
+7. register composition with registerRoot()
+8. render
+```
+
+### workflow 4: render custom thumbnail
+```
+1. setup composition
+2. copy video to lib/remotion/public/
+3. create thumbnail composition with OffthreadVideo + overlays
+4. use staticFile() for video path
+5. add text, logos, graphics on top
+6. register composition with registerRoot()
+7. render specific frame as png/jpg using renderStill
+```
+
+### workflow 5: zoom & pan effect
+```
+1. probe video or image
+2. setup composition
+3. copy media to lib/remotion/public/
+4. create composition with transform animations
+5. use staticFile() for media paths
+6. use interpolate() for scale and translate
+7. set easing for smooth motion
+8. register composition with registerRoot()
+9. render
+```
+
+### workflow 6: multi-track audio/video
+```
+1. probe all media files
+2. setup composition
+3. copy videos + audio files to lib/remotion/public/
+4. create composition with multiple OffthreadVideo/Audio components
+5. use staticFile() for all media paths
+6. adjust volume levels with interpolate()
+7. sync timing using frame calculations
+8. register composition with registerRoot()
+9. render
+```
+
+## calculation formulas
+
+### frames to seconds
+```typescript
+const seconds = frames / fps;
+```
+
+### seconds to frames
+```typescript
+const frames = Math.floor(seconds * fps);
+```
+
+### fps conversion
+```typescript
+// video is 24fps, composition is 30fps
+const adjustedFrame = Math.floor(frame * (24 / 30));
+```
+
+### srt time to seconds
+```typescript
+function parseTime(time: string) {
+  const [hours, minutes, rest] = time.split(":");
+  const [seconds, ms] = rest.split(",");
+  return (
+    parseInt(hours) * 3600 +
+    parseInt(minutes) * 60 +
+    parseInt(seconds) +
+    parseInt(ms) / 1000
+  );
+}
+```
+
+## tips & tricks
+
+### caption styling
+```typescript
+// word-by-word bold captions
+{
+  fontFamily: "Inter",
+  fontSize: 48,
+  fontWeight: "bold",
+  color: "white",
+  textAlign: "center",
+  backgroundColor: "rgba(0, 0, 0, 0.7)",
+  padding: "20px 40px",
+  borderRadius: 12,
+  textTransform: "uppercase",
+  letterSpacing: 2,
+}
+```
+
+### smooth transitions
+```typescript
+import { interpolate } from "remotion";
+
+const opacity = interpolate(
+  frame,
+  [0, 30, 60],
+  [0, 1, 0],
+  { extrapolateRight: "clamp" }
+);
+```
+
+### loading fonts
+```typescript
+import { loadFont } from "@remotion/google-fonts/Inter";
+const { fontFamily } = loadFont();
+```
+
+### responsive layouts
+```typescript
+const { width, height } = useVideoConfig();
+const scale = Math.min(width / 1920, height / 1080);
+```
+
+## troubleshooting
+
+### issue: video not loading
+**solution:**
+- copy media files to `lib/remotion/public/`
+- use `staticFile("filename.ext")` not absolute paths
+- verify file exists in public directory
+- check file permissions
+
+### issue: captions out of sync
+**solution:**
+- verify SRT timestamps
+- check fps matches video fps
+- log currentTime to debug: `console.log(frame / fps)`
+
+### issue: wrong video duration
+**solution:**
+- probe video to get exact duration
+- calculate frames correctly: `duration * fps`
+- round to nearest frame
+
+### issue: concatenation glitch
+**solution:**
+- calculate exact end frame of first video
+- adjust `startFrom` for fps differences
+- use `Math.floor()` for frame calculations
+
+### issue: render fails
+**solution:**
+- verify all media files exist in `lib/remotion/public/`
+- check composition is registered with `registerRoot()`
+- ensure durationInFrames is sufficient
+- verify all media paths use `staticFile()`
+- check console for webpack errors
+
+## performance optimization
+
+### use OffthreadVideo
+for better performance when concatenating:
+```typescript
+<OffthreadVideo src={staticFile("video.mp4")} />
+```
+
+### limit font requests
+```typescript
+loadFont({
+  weights: ["400", "700"], // only needed weights
+  subsets: ["latin"],      // only needed subsets
+});
+```
+
+### optimize media files
+```bash
+# compress video before using
+bun run lib/ffmpeg.ts convert input.mp4 output.mp4
+```
+
+## example workflows
+
+### example 1: video with captions and concatenation
+```bash
+# 1. probe videos
+bun run lib/ffmpeg.ts probe media/fitness-demo.mp4
+# output: 360x640 @ 30fps, 47.67s
+
+bun run lib/ffmpeg.ts probe media/kangaroo-scene.mp4
+# output: 1920x1080 @ 24fps, 5.04s
+
+# 2. setup composition
+bun run lib/remotion/index.ts create Demo
+
+# 3. create composition files
+# edit lib/remotion/compositions/Demo.tsx
+# edit lib/remotion/compositions/Demo.root.tsx
+
+# 4. verify
+bun run lib/remotion/index.ts compositions lib/remotion/compositions/Demo.root.tsx
+# Demo: 360x640 @ 30fps (1582 frames)
+
+# 5. render
+bun run lib/remotion/index.ts render lib/remotion/compositions/Demo.root.tsx Demo media/output.mp4
+# [remotion] progress: 100.0% | rendered: 1582 | encoded: 1582
+# [remotion] saved to media/output.mp4
+
+# 6. verify output
+bun run lib/ffmpeg.ts probe media/output.mp4
+# 360x640 @ 30fps, 52.73s
+```
+
+### example 2: custom thumbnail with overlay
+```bash
+# 1. setup composition
+bun run lib/remotion/index.ts create Thumbnail
+
+# 2. copy media
+cp media/video.mp4 lib/remotion/public/
+
+# 3. edit thumbnail composition lib/remotion/compositions/Thumbnail.tsx
+# import { AbsoluteFill, OffthreadVideo, staticFile } from "remotion";
+# export const Thumbnail = () => {
+#   const video = staticFile("video.mp4");
+#   return (
+#     <AbsoluteFill>
+#       <OffthreadVideo src={video} />
+#       <div style={{
+#         position: "absolute",
+#         bottom: 50,
+#         left: 50,
+#         fontSize: 72,
+#         fontWeight: "bold",
+#         color: "white",
+#         textShadow: "4px 4px 8px black"
+#       }}>
+#         MY VIDEO TITLE
+#       </div>
+#     </AbsoluteFill>
+#   );
+# };
+
+# 4. edit root with registerRoot() lib/remotion/compositions/Thumbnail.root.tsx
+
+# 5. render frame 90 (3 seconds in @ 30fps)
+bun run lib/remotion/index.ts still lib/remotion/compositions/Thumbnail.root.tsx Thumbnail 90 media/thumbnail.png
+# [remotion] saved to media/thumbnail.png
+```
+
+### example 3: zoom effect with audio
+```bash
+# 1. setup composition
+bun run lib/remotion/index.ts create Zoom
+
+# 2. copy media
+cp media/image.jpg media/music.mp3 lib/remotion/public/
+
+# 3. edit composition lib/remotion/compositions/Zoom.tsx
+# import { Img, Audio, staticFile, interpolate, useCurrentFrame } from "remotion";
+# const frame = useCurrentFrame();
+# const image = staticFile("image.jpg");
+# const audio = staticFile("music.mp3");
+# const scale = interpolate(frame, [0, 150], [1, 1.5]);
+# <div style={{ transform: `scale(${scale})` }}>
+#   <Img src={image} />
+# </div>
+# <Audio src={audio} />
+
+# 4. edit root with registerRoot() and durationInFrames: 150 (5 seconds @ 30fps)
+
+# 5. render
+bun run lib/remotion/index.ts render lib/remotion/compositions/Zoom.root.tsx Zoom media/zoomed.mp4
+```
+
+### example 4: side-by-side comparison
+```bash
+# 1. probe videos
+bun run lib/ffmpeg.ts probe media/before.mp4
+bun run lib/ffmpeg.ts probe media/after.mp4
+
+# 2. setup composition
+bun run lib/remotion/index.ts create Comparison
+
+# 3. copy media
+cp media/before.mp4 media/after.mp4 lib/remotion/public/
+
+# 4. edit composition lib/remotion/compositions/Comparison.tsx
+# import { AbsoluteFill, OffthreadVideo, staticFile } from "remotion";
+# const before = staticFile("before.mp4");
+# const after = staticFile("after.mp4");
+# <AbsoluteFill style={{ width: "50%", left: 0 }}>
+#   <OffthreadVideo src={before} />
+# </AbsoluteFill>
+# <AbsoluteFill style={{ width: "50%", left: "50%" }}>
+#   <OffthreadVideo src={after} />
+# </AbsoluteFill>
+
+# 5. edit root with registerRoot()
+
+# 6. render
+bun run lib/remotion/index.ts render lib/remotion/compositions/Comparison.root.tsx Comparison media/comparison.mp4
+```
+
+## see also
+- lib/remotion/SKILL.md - detailed remotion skill reference
+- lib/ffmpeg.ts - video probing and editing
+- service/captions/ - automated caption generation
+- service/edit/ - video editing workflows
diff --git a/skills/vargai-pipeline-cookbooks/references/round-video-character.md b/skills/vargai-pipeline-cookbooks/references/round-video-character.md
new file mode 100644
index 00000000..84c99fdb
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/references/round-video-character.md
@@ -0,0 +1,337 @@
+# round video character cookbook
+
+create realistic round selfie videos for telegram: front-facing camera POV videos with authentic camera shake, lighting, and audio
+
+## what this does
+
+1. generates 3 first frame options: person in specified setting (conference, station, etc)
+2. ai picks the best first frame from the 3 options
+3. generates voiceover from text script
+4. creates talking video using wan 2.5 with audio sync
+
+## inputs
+
+- `text_script`: what the person will say
+- `profile_photo`: photo of the person (e.g., media/friend/katia.jpg)
+- `scene_location`: where they are (from script or default: conference/underground station)
+
+## steps
+
+### step 1: generate first frame options (person in setting)
+
+generate 3 variations and let ai pick the best one:
+
+```bash
+# generate 3 SELFIE-STYLE first frame options using nano banana pro
+# CRITICAL: use the proven prompt structure below
+# aspect_ratio "auto" preserves the original photo's aspect ratio (portrait/landscape)
+
+# option 1
+bun run lib/fal.ts image_to_image \
+  "selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: hackathon space, wear black hoodie without any text on it" \
+  media/friend/katia.jpg \
+  auto
+
+# option 2
+bun run lib/fal.ts image_to_image \
+  "selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: hackathon space, wear black hoodie without any text on it" \
+  media/friend/katia.jpg \
+  auto
+
+# option 3
+bun run lib/fal.ts image_to_image \
+  "selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: hackathon space, wear black hoodie without any text on it" \
+  media/friend/katia.jpg \
+  auto
+```
+
+**important prompting for selfie style (image-to-image):**
+- start with "selfie POV" - simple and effective
+- include "camera with subtle natural wobble and shake throughout"
+- specify "focus on subject with shallow depth of field"
+- lighting: "dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast"
+- background: "ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights"
+- clothing: "wear black hoodie without any text on it" (or specify other clothing)
+- location: flexible - adjust based on script (hackathon space, metro station, office, etc.)
+- aspect ratio "auto" preserves original dimensions - critical for avoiding squashed/stretched video!
+
+each command outputs a URL like: `https://v3b.fal.media/files/.../image.jpg`
+
+download all 3 options:
+```bash
+curl -o media/friend/option1.jpg "https://url-from-option-1.jpg"
+curl -o media/friend/option2.jpg "https://url-from-option-2.jpg"
+curl -o media/friend/option3.jpg "https://url-from-option-3.jpg"
+```
+
+**ai should review the 3 options and pick the best one based on:**
+- face quality and recognition
+- natural selfie look
+- lighting and color balance
+- background blur and composition
+- overall authenticity
+
+use the selected image url for step 4 (wan 2.5)
+
+### step 2: generate voiceover
+
+```bash
+# generate voice from script
+# save to media/friend/[name]/voice.mp3 for organization
+bun run lib/elevenlabs.ts tts \
+  "hey everyone! excited to share this update from the conference" \
+  rachel \
+  media/friend/katia/voice.mp3
+```
+
+the audio is saved to `media/friend/[name]/voice.mp3`. you'll need to upload this to get a url for wan 2.5.
+
+### step 3: generate talking video with wan 2.5 (via fal)
+
+**important: audio must be at least 3 seconds long!**
+
+fal's wan-25 endpoint requires audio duration of 3+ seconds. if your script is too short, extend it.
+
+```bash
+# use fal's wan-25 endpoint (supports local files and urls)
+# audio and image files will be auto-uploaded if local paths are provided
+# duration MUST be 5 or 10 seconds only
+bun run lib/fal.ts wan \
+  media/friend/katia/option2.jpg \
+  media/friend/katia/voice.mp3 \
+  "front-facing camera selfie POV video, handheld phone directly in front of face with continuous slight wobble and shake, subject in sharp focus with softly blurred background shallow depth of field, dramatic low-light scene with intense magenta hot pink light illuminating face and blue ambient lights in blurred background, dark indoor busy conference setting with abstract out-of-focus lights, conversational audio with muffled background crowd chatter and commotion" \
+  10 \
+  480p
+```
+
+**command structure:**
+```bash
+bun run lib/fal.ts wan <image_path_or_url> <audio_path_or_url> <prompt> [duration] [resolution]
+```
+
+**parameters:**
+- image: local path or url (auto-uploaded if local)
+- audio: local path or url (auto-uploaded if local, **must be 3+ seconds**)
+- prompt: detailed video style description
+- duration: 5 or 10 (default: 5)
+- resolution: 480p, 720p, or 1080p (default: 480p)
+
+**detailed prompt structure for realistic selfie videos:**
+
+the prompt should include ALL these elements for maximum authenticity:
+
+**camera technique:**
+- "front-facing camera selfie POV video"
+- "handheld phone directly in front of face"
+- "continuous slight wobble and shake"
+
+**focus & composition:**
+- "subject in sharp focus"
+- "softly blurred background shallow depth of field"
+
+**lighting:**
+- "dramatic low-light scene"
+- "intense magenta hot pink light illuminating face" (or specify your lighting color)
+- "blue ambient lights in blurred background" (optional, for busy settings)
+
+**setting:**
+- "dark indoor busy setting with abstract out-of-focus lights" (adjust based on location)
+
+**audio characteristics:**
+- "conversational audio with muffled background crowd chatter and commotion"
+
+this comprehensive prompting creates videos that look like authentic, quickly-recorded selfie messages with realistic imperfections.
+
+this takes 2-4 minutes. the command will wait for completion and output the video url.
+
+### step 4: download result
+
+```bash
+# fal wan-25 returns video url like: https://v3b.fal.media/files/.../video.mp4
+curl -o media/friend/talking-character.mp4 "https://v3b.fal.media/files/.../video.mp4"
+```
+
+## output
+
+- first frame options: 3 variations (jpg) - `media/friend/[name]/option1.jpg`, `option2.jpg`, `option3.jpg`
+- selected first frame: best option chosen by ai
+- voiceover: `media/friend/[name]/voice.mp3`
+- final video: `media/friend/[name]/talking-character.mp4`
+
+## timing
+
+- first frame generation: 15-30s (3 options)
+- ai selection: instant
+- voiceover: 5-10s
+- wan 2.5 processing (fal): 2-4min
+
+**total: ~3-5 minutes**
+
+## scene context examples
+
+choose setting based on script context. always include handheld camera description for authentic look:
+
+| script mentions | step 1: first frame prompt | wan 2.5 prompt (detailed style) |
+|----------------|---------------------------|--------------------------------|
+| "at the conference" / "hackathon" | selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: hackathon space, wear black hoodie without any text on it | front-facing camera selfie POV video, handheld phone directly in front of face with continuous slight wobble, subject in sharp focus with softly blurred background, dramatic low-light with intense magenta hot pink light illuminating face and blue ambient lights in blurred background, dark indoor busy conference setting with abstract out-of-focus lights, conversational audio with muffled background crowd chatter |
+| "subway" / "metro" | selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with harsh fluorescent lighting, ambient lights scattered in background, dark underground station setting, abstract out-of-focus lights, location: metro station, wear black hoodie without any text on it | front-facing camera selfie POV video, handheld phone with slight shake, sharp focus on subject with blurred metro background, harsh fluorescent lighting with cool tones, dark underground station with out-of-focus commuters and lights, audio with echoing background noise and distant train sounds |
+| "office" | selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, soft indoor office lighting environment, ambient lights in background, modern workspace setting, abstract out-of-focus monitors and lights, location: office, wear black hoodie without any text on it | front-facing camera selfie POV video, handheld phone wobble, sharp subject focus with blurred office background, soft indoor office lighting, modern workspace with blurred monitors and colleagues in background, conversational audio with quiet office ambient noise |
+| "street" | selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, natural daylight or street lighting environment, ambient lights in background, urban street setting, abstract out-of-focus pedestrians and lights, location: city street, wear black hoodie without any text on it | front-facing camera selfie POV video, handheld shake, sharp focus with blurred street background, natural daylight or street lighting, urban setting with out-of-focus pedestrians and traffic, audio with street noise and distant traffic sounds |
+| no location | selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights, wear black hoodie without any text on it | front-facing camera selfie POV video, handheld phone with slight wobble, sharp subject with softly blurred background, natural indoor lighting, casual indoor setting, conversational audio (default) |
+
+**key phrases for authentic selfie look:**
+
+**step 1 (first frame - image-to-image):**
+
+proven prompt structure (adjust location only):
+```
+selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: [hackathon space/metro station/office/city street], wear black hoodie without any text on it
+```
+
+- start with "selfie POV" - simple, no zoom confusion
+- "camera with subtle natural wobble and shake throughout" - natural movement
+- "focus on subject with shallow depth of field" - proper framing
+- lighting: magenta/hot pink with blue ambient (adjust per setting)
+- location: flexible - change based on script
+- clothing: black hoodie without text (or adjust as needed)
+
+**step 4 (wan 2.5) - comprehensive style elements:**
+
+*camera technique:*
+- "front-facing camera selfie POV video"
+- "handheld phone directly in front of face"
+- "continuous slight wobble and shake"
+
+*focus & depth:*
+- "subject in sharp focus"
+- "softly blurred background"
+- "shallow depth of field"
+
+*lighting:*
+- "dramatic low-light scene"
+- "intense magenta hot pink light illuminating face" (adjust color per setting)
+- "blue ambient lights in blurred background" (optional)
+
+*setting:*
+- "dark indoor busy setting"
+- "abstract out-of-focus lights"
+- adjust per location (conference/metro/office/street)
+
+*audio:*
+- "conversational audio with muffled background crowd chatter and commotion"
+- adjust per setting (metro=echoing/train sounds, office=quiet ambient, street=traffic)
+
+## example: full workflow
+
+```bash
+# scenario: katia sharing conference update
+# script: "hey everyone! i'm so excited to share this amazing update with you from the conference today"
+# photo: media/friend/katia.jpg
+# note: audio must be 3+ seconds long for wan-25!
+
+# step 1: generate 3 SELFIE first frame options with nano banana pro
+bun run lib/fal.ts image_to_image \
+  "selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: hackathon space, wear black hoodie without any text on it" \
+  media/friend/katia.jpg \
+  auto
+# output 1: https://v3b.fal.media/files/.../option1.png
+
+bun run lib/fal.ts image_to_image \
+  "selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: hackathon space, wear black hoodie without any text on it" \
+  media/friend/katia.jpg \
+  auto
+# output 2: https://v3b.fal.media/files/.../option2.png
+
+bun run lib/fal.ts image_to_image \
+  "selfie POV, camera with subtle natural wobble and shake throughout, focus on subject with shallow depth of field, dramatic low-light environment with intense magenta and hot pink lighting creating strong color cast, ambient blue lights scattered in background, dark indoor busy setting, abstract out-of-focus colorful lights creating busy background, location: hackathon space, wear black hoodie without any text on it" \
+  media/friend/katia.jpg \
+  auto
+# output 3: https://v3b.fal.media/files/.../option3.png
+
+# download all 3 options
+curl -o media/friend/katia/option1.jpg "https://v3b.fal.media/files/.../option1.png"
+curl -o media/friend/katia/option2.jpg "https://v3b.fal.media/files/.../option2.png"
+curl -o media/friend/katia/option3.jpg "https://v3b.fal.media/files/.../option3.png"
+
+# ai reviews the 3 options and picks the best one based on:
+# - face quality and recognition
+# - natural selfie look
+# - lighting and color balance
+# - background blur and composition
+# - overall authenticity
+# selected: option2 (example)
+
+# step 2: generate voice (ensure 3+ seconds for wan-25)
+bun run lib/elevenlabs.ts tts \
+  "hey everyone! i'm so excited to share this amazing update with you from the conference today" \
+  rachel \
+  media/friend/katia/voice.mp3
+# output: media/friend/katia/voice.mp3
+
+# step 3: run wan-25 (fal) - auto-uploads local files
+bun run lib/fal.ts wan \
+  media/friend/katia/option2.jpg \
+  media/friend/katia/voice.mp3 \
+  "front-facing camera selfie POV video, handheld phone directly in front of face with continuous slight wobble and shake, subject in sharp focus with softly blurred background shallow depth of field, dramatic low-light scene with intense magenta hot pink light illuminating face and blue ambient lights in blurred background, dark indoor busy conference setting with abstract out-of-focus lights, conversational audio with muffled background crowd chatter and commotion" \
+  10 \
+  480p
+# takes 2-4 minutes...
+# output: { "data": { "video": { "url": "https://v3b.fal.media/files/.../video.mp4" } } }
+
+# step 4: download
+curl -o media/friend/katia-talking.mp4 "https://v3b.fal.media/files/.../video.mp4"
+```
+
+**tested successfully** with katia.jpg and aleks - see media/friend/ for example outputs!
+
+## tips
+
+- **selfie perspective**: CRITICAL - always use "selfie POV" in step 1 first frame generation!
+- **audio duration**: CRITICAL - wan-25 requires audio to be at least 3 seconds long. extend short scripts!
+- **duration constraint**: wan-25 only accepts 5 or 10 second videos
+- **script length**: ensure script is at least 3 seconds when spoken, max 10 seconds
+- **aspect ratio preservation**: CRITICAL - always use "auto" aspect ratio in image-to-image to avoid squashed/stretched videos!
+- **nano banana pro**: uses aspect_ratio="auto" to preserve original photo dimensions (portrait/landscape)
+- **local file support**: fal wan command auto-uploads local files - no need for manual upload step!
+- **handheld camera**: always include "handheld phone" + "wobble and shake" in wan-25 prompt for authentic look
+- **first frame quality**: this is the base - make it look natural and selfie-like!
+- **scene matching**: extract location from script when mentioned
+- **voice selection**: rachel (default) is clear and professional
+- **resolution**: 480p is faster (2-3min), 720p/1080p takes longer (4-5min)
+- **save intermediates**: store outputs in media/friend/[name]/ for organization and reuse
+- **using fal instead of replicate**: fal's wan-25 endpoint is faster and more reliable than replicate
+
+## voice options
+
+```bash
+# female voices (american english)
+bun run lib/elevenlabs.ts tts "script" rachel media/friend/[name]/voice.mp3
+bun run lib/elevenlabs.ts tts "script" bella media/friend/[name]/voice.mp3  
+bun run lib/elevenlabs.ts tts "script" elli media/friend/[name]/voice.mp3
+
+# male voices (american english)
+bun run lib/elevenlabs.ts tts "script" antoni media/friend/[name]/voice.mp3
+bun run lib/elevenlabs.ts tts "script" josh media/friend/[name]/voice.mp3
+```
+
+see all voices: `bun run lib/elevenlabs.ts voices`
+
+## environment setup
+
+```bash
+# required api keys
+export ELEVENLABS_API_KEY="your_key"
+export FAL_API_KEY="your_key"  # for wan-25 and image generation (or set FAL_KEY)
+```
+
+## changelog
+
+**2024-11-22:**
+- switched to fal's wan-25-preview endpoint (faster, more reliable than replicate)
+- added wan-25 support to lib/fal.ts with auto-upload for local files
+- discovered: audio must be at least 3 seconds long for wan-25 (critical!)
+- simplified workflow: no manual audio upload step needed
+- tested successfully with aleks photo and "give me money" script
+- switched from flux to nano banana pro for image-to-image (better aspect ratio preservation)
+- fixed squashed video issue by using aspect_ratio="auto"
+- clarified duration constraints (5 or 10 seconds only)
diff --git a/skills/vargai-pipeline-cookbooks/references/talking-character-pipeline.md b/skills/vargai-pipeline-cookbooks/references/talking-character-pipeline.md
new file mode 100644
index 00000000..8610dd4f
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/references/talking-character-pipeline.md
@@ -0,0 +1,285 @@
+---
+name: talking-character-pipeline
+description: complete workflow to create talking character videos with lipsync and captions. use when creating ai character videos, talking avatars, narrated content, or social media character content with voiceover.
+allowed-tools: Read, Bash
+---
+
+# talking character pipeline
+
+create professional talking character videos from scratch using the complete varg.ai sdk workflow.
+
+## overview
+
+this pipeline combines multiple services to create a fully produced talking character video:
+1. character headshot generation
+2. voiceover synthesis
+3. character animation
+4. lipsync
+5. auto-generated captions
+6. social media optimization
+
+**total time**: ~4-5 minutes per video
+
+## step-by-step workflow
+
+### 1. create character headshot
+```bash
+bun run service/image.ts soul "professional headshot of a friendly person, studio lighting" true
+```
+
+**output**: character image url + s3 url  
+**time**: ~30 seconds
+
+**tip**: be specific about character appearance, lighting, and style for best results
+
+### 2. generate voiceover
+```bash
+bun run service/voice.ts elevenlabs "hello world, this is my character speaking" rachel true
+```
+
+**output**: `media/voice-{timestamp}.mp3` + s3 url  
+**time**: ~10 seconds
+
+**tip**: choose voice that matches character (rachel/bella for female, josh/antoni for male)
+
+### 3. animate character
+```bash
+bun run service/video.ts from_image "person talking naturally, professional demeanor" <headshot_url> 5 true
+```
+
+**output**: animated video url + s3 url  
+**time**: ~2-3 minutes
+
+**tip**: use subtle motion prompts like "person talking naturally" or "slight head movement"
+
+### 4. add lipsync
+```bash
+bun run service/sync.ts wav2lip <video_url> <audio_url>
+```
+
+**output**: lipsynced video url  
+**time**: ~30 seconds
+
+**tip**: wav2lip works best with close-up character shots and clear audio
+
+### 5. add captions
+```bash
+bun run service/captions.ts <video_path> captioned.mp4 --provider fireworks
+```
+
+**output**: `captioned.mp4` with subtitles  
+**time**: ~15 seconds (includes transcription)
+
+**tip**: fireworks provider gives word-level timing for professional captions
+
+### 6. prepare for social media
+```bash
+bun run service/edit.ts social captioned.mp4 final-tiktok.mp4 tiktok
+```
+
+**output**: `final-tiktok.mp4` optimized for platform  
+**time**: ~5 seconds
+
+**platforms**: tiktok, instagram, youtube-shorts, youtube, twitter
+
+## complete example
+
+```bash
+# step 1: generate character
+bun run service/image.ts soul \
+  "professional business woman, friendly smile, studio lighting" \
+  true
+
+# step 2: create voiceover
+bun run service/voice.ts elevenlabs \
+  "welcome to our company. we're excited to show you our new product" \
+  rachel \
+  true
+
+# step 3: animate character
+bun run service/video.ts from_image \
+  "person talking professionally" \
+  https://your-s3-url/character.jpg \
+  5 \
+  true
+
+# step 4: sync lips
+bun run service/sync.ts wav2lip \
+  https://your-s3-url/animated.mp4 \
+  https://your-s3-url/voice.mp3
+
+# step 5: add captions
+bun run service/captions.ts \
+  synced-video.mp4 \
+  captioned.mp4 \
+  --provider fireworks \
+  --font "Arial Black" \
+  --size 32
+
+# step 6: optimize for tiktok
+bun run service/edit.ts social \
+  captioned.mp4 \
+  final-tiktok.mp4 \
+  tiktok
+```
+
+## programmatic workflow
+
+```typescript
+import { generateWithSoul } from "./service/image"
+import { generateVoice } from "./service/voice"
+import { generateVideoFromImage } from "./service/video"
+import { lipsyncWav2Lip } from "./service/sync"
+import { addCaptions } from "./service/captions"
+import { prepareForSocial } from "./service/edit"
+
+// 1. character
+const character = await generateWithSoul(
+  "friendly business person, professional",
+  { upload: true }
+)
+
+// 2. voice
+const voice = await generateVoice({
+  text: "hello, welcome to our video",
+  voice: "rachel",
+  upload: true,
+  outputPath: "media/voice.mp3"
+})
+
+// 3. animate
+const video = await generateVideoFromImage(
+  "person talking naturally",
+  character.uploaded!,
+  { duration: 5, upload: true }
+)
+
+// 4. lipsync
+const synced = await lipsyncWav2Lip({
+  videoUrl: video.uploaded!,
+  audioUrl: voice.uploadUrl!
+})
+
+// 5. captions
+const captioned = await addCaptions({
+  videoPath: synced,
+  output: "captioned.mp4",
+  provider: "fireworks"
+})
+
+// 6. social media
+const final = await prepareForSocial({
+  input: captioned,
+  output: "final.mp4",
+  platform: "tiktok"
+})
+```
+
+## use cases
+
+### marketing content
+- product announcements
+- brand messaging
+- explainer videos
+- social media ads
+
+### educational content
+- course introductions
+- tutorial narration
+- lesson summaries
+- educational social media
+
+### social media
+- tiktok character content
+- instagram reels with narration
+- youtube shorts
+- twitter video posts
+
+## tips for best results
+
+**character creation:**
+- be specific about appearance, expression, lighting
+- "professional", "friendly", "casual" work well
+- mention "studio lighting" for clean backgrounds
+
+**voiceover:**
+- write natural, conversational scripts
+- add punctuation for natural pauses
+- keep sentences short and clear
+- match voice gender to character
+
+**animation:**
+- use subtle motion prompts
+- 5 seconds is perfect for character talking shots
+- avoid complex camera movements
+
+**lipsync:**
+- wav2lip works best with frontal face views
+- ensure audio is clear and well-paced
+- close-up shots give better results
+
+**captions:**
+- use fireworks for word-level timing
+- larger font sizes (28-32) work better on mobile
+- white text with black outline is most readable
+
+**social media:**
+- vertical (9:16) for tiktok/instagram/shorts
+- landscape (16:9) for youtube/twitter
+- keep total video under 60 seconds for best engagement
+
+## estimated costs
+
+per video (approximate):
+- character image: $0.05 (higgsfield soul)
+- voiceover: $0.10 (elevenlabs)
+- animation: $0.20 (fal image-to-video)
+- lipsync: $0.10 (replicate wav2lip)
+- transcription: $0.02 (fireworks)
+
+**total**: ~$0.47 per video
+
+## troubleshooting
+
+**character doesn't look consistent:**
+- use higgsfield soul instead of fal for characters
+- save character image and reuse for consistency
+
+**lipsync doesn't match well:**
+- ensure video shows face clearly
+- use close-up shots
+- check audio quality and clarity
+
+**animation looks unnatural:**
+- simplify motion prompt
+- use "person talking naturally" or "slight movement"
+- avoid dramatic camera movements
+
+**captions are off-sync:**
+- use fireworks provider for better timing
+- check audio quality
+- verify video fps is standard (24/30fps)
+
+## required environment variables
+
+```bash
+HIGGSFIELD_API_KEY=hf_xxx
+HIGGSFIELD_SECRET=secret_xxx
+ELEVENLABS_API_KEY=el_xxx
+FAL_API_KEY=fal_xxx
+REPLICATE_API_TOKEN=r8_xxx
+FIREWORKS_API_KEY=fw_xxx
+CLOUDFLARE_R2_API_URL=https://xxx.r2.cloudflarestorage.com
+CLOUDFLARE_ACCESS_KEY_ID=xxx
+CLOUDFLARE_ACCESS_SECRET=xxx
+CLOUDFLARE_R2_BUCKET=m
+```
+
+## next steps
+
+after creating your talking character video:
+- upload to social platforms
+- analyze performance metrics
+- iterate on character design and scripts
+- create series with consistent character
+- experiment with different voices and styles
diff --git a/skills/vargai-pipeline-cookbooks/references/talking-character.md b/skills/vargai-pipeline-cookbooks/references/talking-character.md
new file mode 100644
index 00000000..eda24bf8
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/references/talking-character.md
@@ -0,0 +1,59 @@
+# talking character pipeline
+
+create a talking character video with lipsync and captions
+
+## steps
+
+### 1. create character headshot
+```bash
+# generate character using higgsfield soul
+bun run service/image.ts soul "professional headshot of a friendly person, studio lighting" true
+```
+
+### 2. generate voiceover
+```bash
+# use fal voice synthesis
+bun run lib/fal.ts generate_speech "hello world, this is my voice" true
+```
+
+### 3. animate character
+```bash
+# image-to-video with character talking
+bun run service/video.ts from_image "person talking naturally, professional demeanor" <headshot_url> 5 true
+```
+
+### 4. add lipsync
+```bash
+# sync lips with voiceover
+bun run service/sync.ts overlay <video_url> <audio_url> output.mp4
+```
+
+### 5. add captions
+```bash
+# add auto-generated captions with transcription
+bun run service/captions.ts output.mp4 captioned.mp4 --provider fireworks
+```
+
+### 6. prepare for social media
+```bash
+# resize and optimize for tiktok/instagram
+bun run service/edit.ts social captioned.mp4 final-tiktok.mp4 tiktok
+```
+
+## expected output
+- character headshot (png)
+- voiceover audio (mp3)
+- animated video (mp4)
+- lipsynced video (mp4)
+- captioned video (mp4)
+- final social media ready video (mp4)
+
+## estimated time
+- headshot: 30s
+- voiceover: 10s
+- animation: 2-3min
+- lipsync: 30s
+- captions: 15s (includes transcription)
+- social prep: 5s
+
+total: ~4-5min
diff --git a/skills/vargai-pipeline-cookbooks/references/text-to-tiktok.md b/skills/vargai-pipeline-cookbooks/references/text-to-tiktok.md
new file mode 100644
index 00000000..0dd7cb38
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/references/text-to-tiktok.md
@@ -0,0 +1,669 @@
+# text to tiktok pipeline
+
+turn text (reddit post, script, etc) into a tiktok with ai-generated looping background and voiceover
+
+## overview
+
+1. generate voiceover from text (elevenlabs)
+2. get word-level timestamps (fireworks whisper)
+3. generate looping background video (kling on fal.ai)
+4. combine with captions (ffmpeg)
+
+## step 1: prepare content
+
+```bash
+mkdir -p media/your-project
+```
+
+put your text in `media/your-project/post.md`
+
+## step 2: generate voiceover
+
+**important:** strip markdown formatting (like `#`) before sending to elevenlabs - it will read them aloud!
+
+```bash
+# sam voice - relaxed male (good for philosophical/alan watts style content)
+TEXT=$(cat media/your-project/post.md | sed 's/^# //')
+bun run lib/elevenlabs.ts tts "$TEXT" sam media/your-project/voiceover.mp3
+```
+
+voice options:
+- `sam` - relaxed american male (best for philosophical/calm content)
+- `adam` - deep american male (more intense/pushy)
+- `antoni` - mature male
+- `josh` - american male
+- `rachel` - american female
+
+model used: `eleven_multilingual_v2`
+
+check duration:
+```bash
+ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 media/your-project/voiceover.mp3
+```
+
+## step 3: get word timestamps
+
+```bash
+bun run lib/fireworks.ts media/your-project/voiceover.mp3 media/your-project/segments.json
+```
+
+outputs json with word-level timestamps for captions.
+
+## step 4: generate looping background video
+
+### 4a: generate first frame with motion (important for loops)
+
+for driving/movement scenes, bake motion blur into the first frame so the video starts already moving:
+
+```bash
+bun run lib/fal.ts generate_image "POV from inside moving car driving through rainy city at night, motion blur on streetlights and neon signs, raindrops streaking on windshield from speed, dashboard visible at bottom, blurred city lights rushing past, cinematic motion blur, photorealistic" "fal-ai/flux-pro/v1.1" "portrait_16_9"
+```
+
+download and save to `media/your-project/frame.jpg`
+
+### 4b: generate looping video with tail_image_url
+
+use the same image for start and end frame to create seamless loop:
+
+```typescript
+import { imageToVideo } from "./lib/fal.ts";
+
+const result = await imageToVideo({
+  prompt: "POV from inside car driving through rainy city at night, continuous forward motion, passing neon signs and streetlights, raindrops streaming on windshield, steady driving pace, seamless loop",
+  imageUrl: "media/your-project/frame.jpg",
+  tailImageUrl: "media/your-project/frame.jpg", // same as start = loop!
+  duration: 10,
+});
+```
+
+### 4c: extend to full length
+
+loop the 10sec clip to match voiceover duration:
+
+```bash
+# for 3 min voiceover, loop ~18 times
+ffmpeg -y -stream_loop 17 -i media/your-project/bg_10sec.mp4 -t 180 -c copy media/your-project/bg_full.mp4
+```
+
+## step 5: combine video + audio + captions + screenshot overlay
+
+combine everything with optional screenshot overlay for first few seconds:
+
+```bash
+ffmpeg -y \
+  -i media/your-project/bg_full.mp4 \
+  -i media/your-project/voiceover.mp3 \
+  -loop 1 -t 4 -i media/your-project/screenshot.png \
+  -filter_complex "\
+    [2:v]scale=900:-1,format=yuva420p,fade=t=out:st=3:d=1:alpha=1[screenshot]; \
+    [0:v][screenshot]overlay=(W-w)/2:(H-h)/2:shortest=0:eof_action=pass[vbase]; \
+    [vbase]subtitles=media/your-project/captions.srt:force_style='FontName=Arial,FontSize=20,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Bold=-1,Alignment=2,MarginV=60,Outline=3'[vout]" \
+  -map "[vout]" -map 1:a \
+  -c:v libx264 -preset faster -crf 20 \
+  -c:a aac -b:a 128k \
+  -shortest \
+  -movflags +faststart \
+  media/your-project/final.mp4
+```
+
+this command:
+- overlays screenshot for first 4 seconds with fade out
+- adds word-by-word SRT captions
+- combines background video + voiceover audio
+
+### simpler version (no screenshot overlay)
+
+```bash
+ffmpeg -y -i media/your-project/bg_full.mp4 \
+  -i media/your-project/voiceover.mp3 \
+  -vf "subtitles=media/your-project/captions.srt:force_style='FontName=Arial,FontSize=20,Bold=-1,Outline=3'" \
+  -c:v libx264 -preset faster -crf 20 \
+  -c:a aac -b:a 128k \
+  -shortest \
+  -movflags +faststart \
+  media/your-project/final.mp4
+```
+
+## tips for looping backgrounds
+
+### prompt tips for seamless loops
+- "continuous forward motion" - keeps direction consistent
+- "seamless loop" - hints at looping intent
+- "steady pace" - avoids acceleration/deceleration
+- "never stops" - prevents pausing
+
+### motion blur in first frame
+if your scene has movement (driving, walking, flying), generate the first frame WITH motion blur. otherwise kling will animate from a still start.
+
+bad: "car on rainy street" (static frame = car starts from stop)
+good: "moving car, motion blur on lights, raindrops streaking" (motion frame = already driving)
+
+### use tail_image_url for loops
+kling's `tail_image_url` parameter forces the video to end on a specific frame. set it to the same as `image_url` to create a seamless loop.
+
+### background ideas that loop well
+- driving POV (city, highway, rain)
+- walking POV (city streets, forest path)
+- clouds/sky timelapse
+- ocean waves
+- abstract particles/smoke
+
+### backgrounds that DON'T loop well
+- scenes with specific landmarks
+- conversations/interactions
+- anything with a narrative arc
+
+## tips for text prep
+
+### strip markdown before tts
+elevenlabs reads markdown literally - `# heading` becomes "hashtag heading". always strip:
+
+```bash
+TEXT=$(cat post.md | sed 's/^# //')
+```
+
+### run grammar check
+before generating voiceover, check for:
+- typos ("she'll met" vs "she'll meet")
+- missing apostrophes ("its" vs "it's")
+- repeated words ("into to")
+- missing commas ("After all she" vs "After all, she")
+
+## example project structure
+
+```
+media/your-project/
+├── post.md              # original text
+├── voiceover.mp3        # elevenlabs output
+├── segments.json        # word timestamps
+├── frame.jpg            # first frame (with motion blur)
+├── bg_10sec.mp4         # 10sec looping clip
+├── bg_full.mp4          # extended to voiceover length
+├── subtitles.ass        # generated captions
+└── final.mp4            # final tiktok
+```
+
+## full example: philosophical reddit post
+
+```bash
+# 1. voiceover (strip markdown, use relaxed sam voice)
+TEXT=$(cat media/girl-ruined-you/post.md | sed 's/^# //')
+bun run lib/elevenlabs.ts tts "$TEXT" sam media/girl-ruined-you/voiceover.mp3
+
+# 2. get word timestamps for captions (outputs .srt)
+bun run lib/fireworks.ts media/girl-ruined-you/voiceover.mp3 media/girl-ruined-you/captions.srt
+
+# 3. first frame with motion blur
+bun run lib/fal.ts generate_image "POV from inside moving car driving through rainy city at night, motion blur on streetlights, raindrops streaking on windshield, cinematic" "fal-ai/flux-pro/v1.1" "portrait_16_9"
+
+# 4. looping video (run as ts script for tail_image_url)
+# see step 4b above
+
+# 5. extend loop to match voiceover duration
+ffmpeg -y -stream_loop 17 -i media/girl-ruined-you/bg_car_final.mp4 -t 177 -c copy media/girl-ruined-you/bg_full.mp4
+
+# 6. combine with screenshot overlay + captions
+ffmpeg -y \
+  -i media/girl-ruined-you/bg_full.mp4 \
+  -i media/girl-ruined-you/voiceover.mp3 \
+  -loop 1 -t 4 -i media/girl-ruined-you/shot.png \
+  -filter_complex "\
+    [2:v]scale=900:-1,format=yuva420p,fade=t=out:st=3:d=1:alpha=1[screenshot]; \
+    [0:v][screenshot]overlay=(W-w)/2:(H-h)/2:shortest=0:eof_action=pass[vbase]; \
+    [vbase]subtitles=media/girl-ruined-you/captions.srt:force_style='FontName=Arial,FontSize=20,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Bold=-1,Alignment=2,MarginV=60,Outline=3'[vout]" \
+  -map "[vout]" -map 1:a \
+  -c:v libx264 -preset faster -crf 20 \
+  -c:a aac -b:a 128k \
+  -shortest \
+  -movflags +faststart \
+  media/girl-ruined-you/final_with_captions.mp4
+```
+
+## alternative: minecraft/subway surfers background
+
+if you have a minecraft parkour or subway surfers video:
+
+```bash
+# loop existing background video
+ffmpeg -stream_loop -1 -i media/backgrounds/minecraft_parkour.mp4 \
+  -i media/your-project/voiceover.mp3 \
+  -vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920" \
+  -c:v libx264 -preset faster -crf 23 \
+  -c:a aac -b:a 128k \
+  -shortest \
+  -movflags +faststart \
+  media/your-project/final.mp4
+```
+
+note: yt-dlp currently broken for youtube downloads. use cobalt.tools or screen record instead.
+
+---
+
+# helper scripts
+
+scripts in `pipeline/cookbooks/scripts/` to speed up common tasks:
+
+| script | description | usage |
+|--------|-------------|-------|
+| `generate-frames-parallel.ts` | generate multiple scene frames in parallel using flux kontext | `bun run pipeline/cookbooks/scripts/generate-frames-parallel.ts` |
+| `animate-frames-parallel.ts` | animate multiple frames in parallel using kling | `bun run pipeline/cookbooks/scripts/animate-frames-parallel.ts` |
+| `combine-scenes.sh` | combine scene videos with audio clips using ffmpeg | `./pipeline/cookbooks/scripts/combine-scenes.sh media/your-project` |
+| `still-to-video.sh` | convert still image to video with ken burns effect | `./pipeline/cookbooks/scripts/still-to-video.sh input.jpg output.mp4 5 in` |
+
+**generate-frames-parallel.ts** - edit the `configs` array to define your scenes, supports single character (kontext) and multi-character (kontext/multi) frames.
+
+**animate-frames-parallel.ts** - edit the `configs` array with frame paths and prompts. all kling requests run in parallel.
+
+**combine-scenes.sh** - edit the `SCENES` array to define scene timing. handles audio extraction, video looping, and concatenation.
+
+**still-to-video.sh** - useful when kling fails or for simple scenes. creates slow zoom (ken burns) effect from a still frame.
+
+---
+
+# advanced: character-based storytelling videos
+
+for narrative content with consistent characters (like animated story videos)
+
+## character generation
+
+### generate consistent characters with nano banana pro
+
+```bash
+# protagonist (male)
+bun run lib/fal.ts generate_image "3D cartoon anthropomorphic male cat character, cute stylized, standing pose, young adult male energy, slightly guarded but hopeful expression, big expressive eyes, wearing hoodie and jeans, muted earth tones, pixar dreamworks style, full body shot, white background, character reference sheet" "fal-ai/nano-banana-pro" "portrait_16_9"
+
+# love interest (female)  
+bun run lib/fal.ts generate_image "3D cartoon anthropomorphic female cat character, cute stylized, standing pose, mature confident woman energy, warm loving expression, big expressive eyes, wearing elegant but casual dress, warm colors, pixar dreamworks style, full body shot, white background, character reference sheet" "fal-ai/nano-banana-pro" "portrait_16_9"
+```
+
+save as `cat_protagonist.png`, `cat_love_interest.png`, etc.
+
+## video generation models comparison
+
+### for character consistency (multiple characters in one scene)
+
+| model | reference support | best for |
+|-------|------------------|----------|
+| **veo3.1/reference-to-video** | multiple `image_urls` | best character consistency across multiple refs |
+| **vidu/q2/reference-to-video** | up to 7 `reference_image_urls` | good consistency (had api issues) |
+| **bytedance/lynx** | subject reference | designed for subject consistency |
+
+### for single character animation
+
+| model | notes |
+|-------|-------|
+| **kling-video/v2.5-turbo/pro** | reliable, good motion, supports `tail_image_url` for loops |
+| **sora-2/image-to-video** | up to 12 sec, great quality, no reference support |
+| **veo3.1/image-to-video** | good quality, uses image as literal first frame |
+
+## workflow: scene-by-scene generation
+
+### step 1: create scene script with timestamps
+
+use the SRT file to understand timing:
+```bash
+head -50 media/your-project/captions.srt
+```
+
+create a scene breakdown markdown file (`scene_script.md`):
+
+```markdown
+# Scene Script - Cat Story (2:56 total)
+
+Characters:
+- **Protagonist** (male cat in hoodie) - the "you/brother"
+- **First Girl** (young playful female cat in pastel) - the immature one
+- **Second Girl/Amelia** (mature elegant female cat in orange) - "The One"
+
+All scenes: 9:16 portrait, pixar 3d style, no talking/lip movement, cinematic
+
+---
+
+## Scene 1: Title/Hook (0:00-0:03)
+**Text:** "How a girl that didn't love you ruined your future marriage"
+**Visual:** Protagonist cat sitting alone on a bench at night, city lights behind, looking down sadly.
+**Duration:** 3 sec
+
+## Scene 2: Young Love (0:03-0:09)
+**Text:** "When you were young, you fell in love..."
+**Visual:** Protagonist and First Girl walking together in a park, sunny day.
+**Duration:** 6 sec
+
+## Scene 7: Flashback (0:54-1:01)
+**Text:** "...your training kicks in..."
+**Visual:** FLASHBACK - reuse Scene 5 video in B&W jittery style
+**Duration:** 6.5 sec
+```
+
+key tips:
+- include character descriptions at top
+- note when to reuse videos (flashbacks, repeated scenes)
+- specify visual style effects (B&W, jitter, etc)
+- include exact timestamps from SRT
+
+### step 2: generate scene frames with flux kontext
+
+**important:** veo3.1 image-to-video uses the reference as the literal first frame. generate proper scene frames first!
+
+**use the helper script for parallel generation:**
+```bash
+# edit the configs in the script first, then run:
+bun run pipeline/cookbooks/scripts/generate-frames-parallel.ts
+```
+
+or manually:
+```typescript
+import { fal } from "@fal-ai/client";
+
+// upload character reference
+const protagonist = await fal.storage.upload(Bun.file("media/your-project/cat_protagonist.png"));
+
+// use flux kontext to place character in scene
+const result = await fal.subscribe("fal-ai/flux-pro/kontext", {
+  input: {
+    prompt: "Place this 3D cartoon cat character sitting alone on a park bench at night, city lights bokeh in background, looking down sadly, melancholy mood, cinematic lighting, pixar style, 9:16 portrait vertical composition",
+    image_url: protagonist,
+    aspect_ratio: "9:16"
+  }
+});
+```
+
+### step 3: animate frames with kling
+
+**use the helper script for parallel animation:**
+```bash
+# edit the configs in the script first, then run:
+bun run pipeline/cookbooks/scripts/animate-frames-parallel.ts
+```
+
+or manually:
+```typescript
+const result = await fal.subscribe("fal-ai/kling-video/v2.5-turbo/pro/image-to-video", {
+  input: {
+    prompt: "3D pixar animation, the cat character sits still on bench looking down sadly, subtle breathing movement, city lights twinkle softly in background, slow gentle camera push in, melancholy cinematic mood, no talking",
+    image_url: sceneFrameUrl,
+    duration: "5",
+    aspect_ratio: "9:16"
+  }
+});
+```
+
+**for static frames (ken burns effect):**
+```bash
+# convert still image to video with slow zoom
+./pipeline/cookbooks/scripts/still-to-video.sh media/your-project/scene1_frame.jpg media/your-project/scene1_video.mp4 5 in
+```
+
+### step 4: for scenes with multiple characters
+
+use veo3.1 reference-to-video:
+
+```typescript
+const result = await fal.subscribe("fal-ai/veo3.1/reference-to-video", {
+  input: {
+    prompt: "3D pixar style animation, two anthropomorphic cats walking together in a sunny park - male cat looks at female cat with love, she looks distracted, sunny golden hour lighting, no talking",
+    image_urls: [protagonistUrl, loveInterestUrl],
+    duration: "8s",
+    resolution: "720p",
+    generate_audio: false
+  }
+});
+```
+
+### step 5: assemble with remotion
+
+after generating all scene videos, use remotion for final assembly:
+
+```bash
+# copy all scene videos to remotion public folder
+cp media/your-project/scene*_video.mp4 lib/remotion/public/your-project/
+cp media/your-project/voiceover.mp3 lib/remotion/public/your-project/
+
+# create composition
+bun run lib/remotion/index.ts create YourProject
+
+# edit composition with scene timeline (see remotion workflow section)
+# preview in studio
+bun remotion studio lib/remotion/compositions/YourProject.root.tsx --public-dir=lib/remotion/public
+
+# render
+bun remotion render lib/remotion/compositions/YourProject.root.tsx YourProject final.mp4 --public-dir=lib/remotion/public
+```
+
+**alternative: simple ffmpeg assembly (no captions styling):**
+```bash
+# use the combine-scenes script
+./pipeline/cookbooks/scripts/combine-scenes.sh media/your-project
+```
+
+## tips for character videos
+
+### no talking/lip sync
+- prompt with "no talking", "no lip movement", "silent"
+- characters express emotion through body language
+- voiceover is added in post
+
+### portrait format (9:16)
+- flux kontext supports `aspect_ratio: "9:16"`
+- kling supports `aspect_ratio: "9:16"`
+- veo3.1 reference-to-video outputs landscape by default (16:9)
+
+### scene continuity
+- keep same character references across all scenes
+- use similar lighting descriptions ("cinematic", "golden hour", "moody blue")
+- match camera style ("slow push in", "static shot")
+
+### stitching scenes (simple ffmpeg)
+```bash
+# create file list
+echo "file 'scene1.mp4'" > scenes.txt
+echo "file 'scene2.mp4'" >> scenes.txt
+echo "file 'scene3.mp4'" >> scenes.txt
+
+# concatenate
+ffmpeg -f concat -safe 0 -i scenes.txt -c copy combined_scenes.mp4
+```
+
+### stitching scenes (remotion - recommended)
+use remotion for more control:
+- reuse same video in multiple scenes (flashbacks)
+- add effects (B&W, jitter for flashbacks)
+- tiktok-style word-by-word captions
+- named sequences visible in studio
+
+```typescript
+// separate video file from scene id - allows reuse
+const SCENES = [
+  { id: 1, video: 1, name: "1. Title", start: 0, duration: 3.5 },
+  { id: 7, video: 5, name: "7. Flashback", start: 54.5, duration: 6.5, flashback: true },
+  { id: 12, video: 13, name: "12. Years Pass", start: 120, duration: 15 },
+  { id: 14, video: 13, name: "14. His Love", start: 155, duration: 10 }, // same video!
+];
+```
+
+### flashback effect
+for memory/past scenes, add B&W + jitter:
+```typescript
+const flashbackStyle = flashback ? {
+  filter: "grayscale(100%) contrast(1.2) brightness(0.9)",
+  transform: `translate(${Math.sin(frame * 0.5) * 2}px, ${Math.cos(frame * 0.7) * 1.5}px)`,
+} : {};
+```
+
+### video looping (critical!)
+when scene duration > video duration, video freezes on last frame. fix with `<Loop>`:
+
+```typescript
+import { Loop } from "remotion";
+
+// define actual video file durations (from ffprobe)
+const VIDEO_DURATIONS_SECONDS: Record<number, number> = {
+  1: 5.041667,
+  2: 10.041667,
+  3: 5.041667,
+  // ... etc
+};
+
+// looping video component
+const LoopingVideo: React.FC<{
+  src: string;
+  flashback?: boolean;
+  loopDurationInFrames: number;
+}> = ({ src, flashback, loopDurationInFrames }) => {
+  const frame = useCurrentFrame();
+  
+  const flashbackStyle = flashback ? {
+    filter: "grayscale(100%) contrast(1.2) brightness(0.9)",
+    transform: `translate(${Math.sin(frame * 0.5) * 2}px, ${Math.cos(frame * 0.7) * 1.5}px)`,
+  } : {};
+
+  return (
+    <Loop durationInFrames={loopDurationInFrames}>
+      <OffthreadVideo src={src} style={{ ...flashbackStyle }} muted />
+    </Loop>
+  );
+};
+
+// usage: pass video's actual duration, not scene duration
+const loopDuration = VIDEO_DURATIONS_SECONDS[scene.video];
+const loopDurationInFrames = Math.round(loopDuration * fps);
+
+<LoopingVideo
+  src={staticFile(`scene${scene.video}_video.mp4`)}
+  loopDurationInFrames={loopDurationInFrames}
+/>
+```
+
+**key insight**: `<Loop durationInFrames>` needs the VIDEO's duration, not the scene's duration. the video loops within the scene's timeframe.
+
+### get video durations
+```bash
+# probe all scene videos
+for f in lib/remotion/public/your-project/scene*_video.mp4; do
+  echo -n "$(basename $f): "
+  ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$f"
+done
+```
+
+## project structure for character videos
+
+```
+media/your-project/
+├── post.md                    # script/text
+├── scene_script.md            # scene breakdown with timestamps
+├── characters/
+│   ├── cat_protagonist.png    # character reference
+│   ├── cat_first_girl.png
+│   └── cat_second_girl.png
+├── frames/
+│   ├── scene1_frame.jpg       # generated scene frames
+│   ├── scene2_frame.jpg
+│   └── ...
+├── scenes/
+│   ├── scene1.mp4             # animated scenes
+│   ├── scene2.mp4
+│   └── ...
+├── voiceover.mp3
+├── captions.srt
+└── final.mp4
+```
+
+---
+
+## remotion workflow (advanced: beautiful tiktok-style captions)
+
+for professional captions with word-by-word highlighting, use remotion instead of ffmpeg:
+
+### step 1: copy assets to remotion public folder
+
+```bash
+mkdir -p lib/remotion/public/your-project
+cp media/your-project/*.mp4 lib/remotion/public/your-project/
+cp media/your-project/voiceover.mp3 lib/remotion/public/your-project/
+```
+
+### step 2: create remotion composition
+
+```bash
+bun run lib/remotion/index.ts create YourProject
+```
+
+### step 3: edit composition with scene timeline
+
+key features:
+- **named sequences** - each scene gets a name visible in Studio
+- **separate video id from scene id** - allows reusing videos (flashbacks, repeated scenes)
+- **flashback effects** - B&W + jitter for memory/past scenes
+- **tiktok captions** - word-by-word highlighting with active word glow
+
+example scene structure:
+```typescript
+const SCENES = [
+  // protagonist alone on bench at night
+  { id: 1, video: 1, name: "1. Title/Hook", start: 0, duration: 3.5 },
+  
+  // flashback - reuse scene 5 with B&W effect
+  { id: 7, video: 5, name: "7. Flashback", start: 54.5, duration: 6.5, flashback: true },
+  
+  // same video used in multiple places
+  { id: 12, video: 13, name: "12. Years Pass", start: 120, duration: 15 },
+  { id: 14, video: 13, name: "14. His Love", start: 155, duration: 10 },
+];
+```
+
+### step 4: preview with remotion studio
+
+```bash
+bun remotion studio lib/remotion/compositions/YourProject.root.tsx --public-dir=lib/remotion/public
+```
+
+studio features:
+- scrub through timeline
+- see all named sequences
+- debug timing issues
+- preview before rendering
+
+### step 5: render
+
+```bash
+# quick preview (480p)
+bun remotion render lib/remotion/compositions/YourProject.root.tsx YourProject preview.mp4 --public-dir=lib/remotion/public --scale=0.5
+
+# full quality
+bun remotion render lib/remotion/compositions/YourProject.root.tsx YourProject final.mp4 --public-dir=lib/remotion/public
+```
+
+### remotion vs ffmpeg
+
+| feature | ffmpeg | remotion |
+|---------|--------|----------|
+| basic captions | yes (ASS/SRT) | yes |
+| word-by-word highlight | limited | excellent |
+| flashback effects | complex filters | simple CSS |
+| scene names/debugging | none | Studio UI |
+| reusing videos | manual | easy (video != id) |
+| transitions | complex | built-in |
+| render time | fast | slower |
+
+**use ffmpeg** for simple overlays, **use remotion** for polished tiktok-style videos
+
+### embedding SRT in composition
+
+avoid file loading issues by embedding SRT content directly:
+
+```typescript
+// paste SRT content directly in file
+const SRT_CONTENT = `1
+00:00:00,071 --> 00:00:00,291
+How
+
+2
+00:00:00,291 --> 00:00:00,351
+a
+...`;
+
+// parse once at module level
+const CAPTIONS = parseSRT(SRT_CONTENT);
+```
+
+see `lib/remotion/SKILL.md` for full caption implementation
diff --git a/skills/vargai-pipeline-cookbooks/references/trendwatching.md b/skills/vargai-pipeline-cookbooks/references/trendwatching.md
new file mode 100644
index 00000000..d0f3f8fb
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/references/trendwatching.md
@@ -0,0 +1,156 @@
+# trendwatching pipeline
+
+discover viral tiktok content for any topic or hashtag using apify scrapers
+
+## overview
+
+use this pipeline to:
+- find trending videos for a specific topic/hashtag
+- analyze engagement metrics (plays, likes, shares, comments)
+- get video urls for inspiration or downloading
+- identify top creators in a niche
+
+## steps
+
+### 1. search by hashtag (save to file)
+
+```bash
+# get 10 viral videos for a hashtag, save to output/
+bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["relationship"],"resultsPerPage":10}' tiktok-relationship.json
+```
+
+### 2. search multiple hashtags
+
+```bash
+# search multiple related hashtags
+bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["viral","trending","fyp"],"resultsPerPage":5}' tiktok-viral.json
+```
+
+### 3. scrape specific profiles
+
+```bash
+# get videos from specific creators
+bun run lib/apify.ts run clockworks/tiktok-scraper '{"profiles":["@username"],"resultsPerPage":10}' creator-videos.json
+```
+
+### 4. get discover page trends
+
+```bash
+# scrape tiktok discover page for trending topics
+bun run lib/apify.ts run clockworks/tiktok-discover-scraper '{"hashtags":["fitness"]}' fitness-trends.json
+```
+
+### 5. download videos from saved json
+
+download all videos from a saved json file using yt-dlp:
+
+```bash
+# download all videos to output/videos/
+bun run lib/apify.ts download tiktok-relationship.json
+
+# download to custom directory
+bun run lib/apify.ts download tiktok-relationship.json output/my-videos
+```
+
+### 6. read saved results
+
+results are saved to `output/<filename>.json` - you can read them later:
+
+```bash
+# list all video urls
+cat output/tiktok-relationship.json | jq -r '.[].webVideoUrl'
+
+# get top videos by play count
+cat output/tiktok-relationship.json | jq 'sort_by(-.playCount) | .[0:3] | .[] | {url: .webVideoUrl, plays: .playCount}'
+```
+
+## output data
+
+each video includes:
+- `webVideoUrl` - tiktok video url
+- `text` - video caption/description
+- `playCount` - total views
+- `diggCount` - likes
+- `shareCount` - shares  
+- `commentCount` - comments
+- `collectCount` - saves/bookmarks
+- `authorMeta` - creator info (name, followers, etc.)
+- `musicMeta` - audio/music info
+- `hashtags` - all hashtags used
+- `createTimeISO` - when posted
+
+## example output
+
+```json
+{
+  "webVideoUrl": "https://www.tiktok.com/@user/video/123",
+  "text": "Not the tiny violin #prank #couples #relationship",
+  "playCount": 13200000,
+  "diggCount": 2900000,
+  "shareCount": 34700,
+  "commentCount": 11000,
+  "authorMeta": {
+    "name": "samandmonica",
+    "fans": 4000000
+  }
+}
+```
+
+## available scrapers
+
+| actor | use case |
+|-------|----------|
+| `clockworks/tiktok-scraper` | general hashtag/profile scraping |
+| `clockworks/tiktok-hashtag-scraper` | hashtag-specific scraping |
+| `clockworks/tiktok-profile-scraper` | creator profile scraping |
+| `clockworks/tiktok-discover-scraper` | trending topics & discover page |
+| `clockworks/tiktok-video-scraper` | specific video urls |
+| `clockworks/tiktok-comments-scraper` | video comments |
+
+## pricing
+
+apify pay-per-event pricing:
+- actor start: $0.005
+- per result: $0.003
+- video download: $0.001 (optional)
+
+example: 100 videos = ~$0.31
+
+## complete workflow example
+
+```bash
+# 1. scrape viral relationship videos
+bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["relationship"],"resultsPerPage":5}' tiktok-relationship.json
+
+# 2. check what we got
+cat output/tiktok-relationship.json | jq -r '.[].webVideoUrl'
+
+# 3. download all videos
+bun run lib/apify.ts download tiktok-relationship.json
+
+# 4. videos are now in output/videos/
+ls output/videos/
+```
+
+## tips
+
+- use `resultsPerPage` to limit results and costs
+- combine multiple hashtags for broader search
+- check `playCount` and `diggCount` ratio for engagement quality
+- look at `createTimeISO` to find recent trending content
+- save results to json to analyze patterns over time
+- download videos for offline analysis or inspiration
+
+## environment
+
+requires `APIFY_TOKEN` in `.env`
+
+```bash
+APIFY_TOKEN=apify_api_xxx
+```
+
+requires `yt-dlp` for video downloads:
+
+```bash
+brew install yt-dlp
+```
diff --git a/skills/vargai-pipeline-cookbooks/scripts/animate-frames-parallel.ts b/skills/vargai-pipeline-cookbooks/scripts/animate-frames-parallel.ts
new file mode 100644
index 00000000..a1810268
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/scripts/animate-frames-parallel.ts
@@ -0,0 +1,84 @@
+/**
+ * Animate multiple frames in parallel using kling
+ * Usage: bun run pipeline/cookbooks/scripts/animate-frames-parallel.ts
+ */
+
+import { fal } from "@fal-ai/client";
+
+interface VideoConfig {
+  name: string;
+  framePath: string;
+  prompt: string;
+  duration?: "5" | "10";
+}
+
+async function animateFrames(configs: VideoConfig[], outputDir: string) {
+  console.log(`Animating ${configs.length} frames in parallel...\n`);
+
+  // Upload all frames first
+  const frameUrls: string[] = [];
+  for (const config of configs) {
+    const url = await fal.storage.upload(Bun.file(config.framePath));
+    frameUrls.push(url);
+  }
+
+  const promises = configs.map((config, i) => {
+    return fal.subscribe("fal-ai/kling-video/v2.5-turbo/pro/image-to-video", {
+      input: {
+        prompt: `${config.prompt}, NO talking NO lip movement`,
+        image_url: frameUrls[i],
+        duration: config.duration || "5",
+        // note: aspect_ratio is determined by input image dimensions
+      },
+    });
+  });
+
+  const results = await Promise.all(promises);
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i] as { data?: { video?: { url?: string } } };
+    const url = result.data?.video?.url;
+    const config = configs[i];
+    if (url && config) {
+      const response = await fetch(url);
+      const buffer = await response.arrayBuffer();
+      await Bun.write(`${outputDir}/${config.name}_video.mp4`, buffer);
+      console.log(`${config.name}_video.mp4 saved`);
+    } else {
+      console.error(`No URL for ${config?.name ?? "unknown"}`);
+    }
+  }
+
+  console.log("\nAll videos saved!");
+}
+
+// Example usage:
+async function main() {
+  const outputDir = "media/girl-ruined-you";
+
+  const configs: VideoConfig[] = [
+    {
+      name: "scene6",
+      framePath: `${outputDir}/scene6_frame.jpg`,
+      prompt:
+        "3D pixar animation, two cats meet eyes in coffee shop, warm romantic moment",
+      duration: "5",
+    },
+    {
+      name: "scene7",
+      framePath: `${outputDir}/scene7_frame.jpg`,
+      prompt: "3D pixar animation, two cats walking together, sunset, romantic",
+      duration: "5",
+    },
+    {
+      name: "scene14",
+      framePath: `${outputDir}/scene14_frame.jpg`,
+      prompt: "3D pixar animation, cat looks at sunrise, hopeful realization",
+      duration: "5",
+    },
+  ];
+
+  await animateFrames(configs, outputDir);
+}
+
+main().catch(console.error);
diff --git a/skills/vargai-pipeline-cookbooks/scripts/combine-scenes.sh b/skills/vargai-pipeline-cookbooks/scripts/combine-scenes.sh
new file mode 100755
index 00000000..7f36bb6b
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/scripts/combine-scenes.sh
@@ -0,0 +1,53 @@
+#!/bin/bash
+# Combine multiple scene videos with audio clips
+# Usage: ./combine-scenes.sh <project_dir>
+
+PROJECT_DIR=${1:-"media/girl-ruined-you"}
+
+# Scene timing configuration (adjust as needed)
+# Format: scene_num:start_time:duration
+SCENES=(
+  "1:0:3.5"
+  "2:3.5:6.5"
+  "3:10:10"
+  "4:20:15"
+  "5:35:7"
+)
+
+echo "Extracting audio clips..."
+for scene_config in "${SCENES[@]}"; do
+  IFS=':' read -r num start dur <<< "$scene_config"
+  ffmpeg -y -i "$PROJECT_DIR/voiceover.mp3" -ss "$start" -t "$dur" "$PROJECT_DIR/audio_scene${num}.mp3" 2>/dev/null
+  echo "  audio_scene${num}.mp3 ($dur sec)"
+done
+
+echo ""
+echo "Combining videos with audio..."
+for scene_config in "${SCENES[@]}"; do
+  IFS=':' read -r num start dur <<< "$scene_config"
+  
+  # Calculate loop count needed (5s videos)
+  loops=$(echo "($dur / 5) - 1" | bc)
+  if [ "$loops" -lt 0 ]; then loops=0; fi
+  
+  ffmpeg -y -stream_loop "$loops" -i "$PROJECT_DIR/scene${num}_video.mp4" \
+    -i "$PROJECT_DIR/audio_scene${num}.mp3" \
+    -t "$dur" -c:v libx264 -preset fast -crf 20 -c:a aac -b:a 128k -shortest \
+    "$PROJECT_DIR/scene${num}_final.mp4" 2>/dev/null
+  echo "  scene${num}_final.mp4"
+done
+
+echo ""
+echo "Creating concat file..."
+rm -f "$PROJECT_DIR/scenes.txt"
+for scene_config in "${SCENES[@]}"; do
+  IFS=':' read -r num start dur <<< "$scene_config"
+  echo "file 'scene${num}_final.mp4'" >> "$PROJECT_DIR/scenes.txt"
+done
+
+echo "Concatenating all scenes..."
+cd "$PROJECT_DIR" && ffmpeg -y -f concat -safe 0 -i scenes.txt -c copy combined_scenes.mp4 2>/dev/null
+
+duration=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 combined_scenes.mp4)
+echo ""
+echo "Done! combined_scenes.mp4 ($duration sec)"
diff --git a/skills/vargai-pipeline-cookbooks/scripts/generate-frames-parallel.ts b/skills/vargai-pipeline-cookbooks/scripts/generate-frames-parallel.ts
new file mode 100644
index 00000000..414bfacc
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/scripts/generate-frames-parallel.ts
@@ -0,0 +1,99 @@
+/**
+ * Generate multiple scene frames in parallel using flux kontext
+ * Usage: bun run pipeline/cookbooks/scripts/generate-frames-parallel.ts
+ */
+
+import { fal } from "@fal-ai/client";
+
+interface FrameConfig {
+  name: string;
+  prompt: string;
+  imageUrls: string[]; // character reference URLs
+  multi?: boolean; // use kontext/multi for multiple characters
+}
+
+async function generateFrames(configs: FrameConfig[], outputDir: string) {
+  console.log(`Generating ${configs.length} frames in parallel...\n`);
+
+  const promises = configs.map((config) => {
+    if (config.multi) {
+      return fal.subscribe("fal-ai/flux-pro/kontext/multi", {
+        input: {
+          prompt: config.prompt,
+          image_urls: config.imageUrls,
+          aspect_ratio: "9:16" as const,
+        },
+      });
+    } else {
+      return fal.subscribe("fal-ai/flux-pro/kontext", {
+        input: {
+          prompt: config.prompt,
+          image_url: config.imageUrls[0] ?? "",
+          aspect_ratio: "9:16" as const,
+        },
+      });
+    }
+  });
+
+  const results = await Promise.all(promises);
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i] as {
+      data?: { images?: Array<{ url?: string }> };
+    };
+    const url = result.data?.images?.[0]?.url;
+    const config = configs[i];
+    if (url && config) {
+      const response = await fetch(url);
+      const buffer = await response.arrayBuffer();
+      await Bun.write(`${outputDir}/${config.name}_frame.jpg`, buffer);
+      console.log(`${config.name}_frame.jpg saved`);
+    } else {
+      console.error(`No URL for ${config?.name ?? "unknown"}`);
+    }
+  }
+
+  console.log("\nAll frames saved!");
+}
+
+// Example usage:
+async function main() {
+  const outputDir = "media/girl-ruined-you";
+
+  // Upload character references first
+  const protagonist = await fal.storage.upload(
+    Bun.file(`${outputDir}/cat_protagonist.png`),
+  );
+  const secondGirl = await fal.storage.upload(
+    Bun.file(`${outputDir}/cat_second_girl.png`),
+  );
+
+  const configs: FrameConfig[] = [
+    {
+      name: "scene6",
+      prompt:
+        "3D pixar style: male cat in hoodie (first) and elegant female cat (second) meeting eyes in coffee shop, warm golden lighting, vertical portrait 9:16",
+      imageUrls: [protagonist, secondGirl],
+      multi: true,
+    },
+    {
+      name: "scene7",
+      prompt:
+        "3D pixar style: male cat and female cat walking together, sunset, romantic, vertical portrait 9:16",
+      imageUrls: [protagonist, secondGirl],
+      multi: true,
+    },
+    // Single character scene
+    {
+      name: "scene14",
+      prompt:
+        "Place this cat looking at sunrise through window, hopeful, vertical portrait 9:16",
+      imageUrls: [protagonist],
+      multi: false,
+    },
+  ];
+
+  await generateFrames(configs, outputDir);
+}
+
+main().catch(console.error);
diff --git a/skills/vargai-pipeline-cookbooks/scripts/still-to-video.sh b/skills/vargai-pipeline-cookbooks/scripts/still-to-video.sh
new file mode 100755
index 00000000..6c992058
--- /dev/null
+++ b/skills/vargai-pipeline-cookbooks/scripts/still-to-video.sh
@@ -0,0 +1,37 @@
+#!/bin/bash
+# Convert still frame to video with ken burns effect (slow zoom)
+# Usage: ./still-to-video.sh <input.jpg> <output.mp4> <duration> [zoom_direction]
+# zoom_direction: in (default), out
+
+INPUT=$1
+OUTPUT=$2
+DURATION=$3
+ZOOM=${4:-"in"}
+
+if [ -z "$INPUT" ] || [ -z "$OUTPUT" ] || [ -z "$DURATION" ]; then
+  echo "Usage: ./still-to-video.sh <input.jpg> <output.mp4> <duration> [in|out]"
+  exit 1
+fi
+
+# Get input dimensions
+WIDTH=$(ffprobe -v error -select_streams v:0 -show_entries stream=width -of csv=p=0 "$INPUT")
+HEIGHT=$(ffprobe -v error -select_streams v:0 -show_entries stream=height -of csv=p=0 "$INPUT")
+
+echo "Creating $DURATION sec video from $INPUT ($WIDTH x $HEIGHT)..."
+
+if [ "$ZOOM" = "out" ]; then
+  # Zoom out: start zoomed in, end at normal
+  FILTER="zoompan=z='1.2-0.2*on/(${DURATION}*25)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=${DURATION}*25:s=${WIDTH}x${HEIGHT}:fps=25"
+else
+  # Zoom in: start normal, end zoomed
+  FILTER="zoompan=z='1+0.2*on/(${DURATION}*25)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=${DURATION}*25:s=${WIDTH}x${HEIGHT}:fps=25"
+fi
+
+ffmpeg -y -loop 1 -i "$INPUT" \
+  -vf "$FILTER" \
+  -t "$DURATION" \
+  -c:v libx264 -preset fast -crf 20 \
+  -pix_fmt yuv420p \
+  "$OUTPUT"
+
+echo "Done: $OUTPUT"
diff --git a/src/init.ts b/src/init.ts
index 026f2efd..9e59203e 100644
--- a/src/init.ts
+++ b/src/init.ts
@@ -8,15 +8,18 @@
  *
  * This script:
  * 1. Checks/creates .env with required API keys
- * 2. Installs Claude Code rules for video generation
+ * 2. Installs Claude Code + Codex skills for video generation
  * 3. Creates example files
  * 4. Verifies the setup works
  */
 
 import {
+  copyFileSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
+  statSync,
   symlinkSync,
   unlinkSync,
   writeFileSync,
@@ -49,193 +52,50 @@ const log = {
     ),
 };
 
-// Agent Skills format SKILL.md
-const SKILL_MD = `---
-name: varg-video-generation
-description: Generate AI videos using varg SDK React engine. Use when creating videos, animations, talking characters, slideshows, or social media content. Always run onboarding first to check API keys.
-license: MIT
-metadata:
-  author: vargHQ
-  version: "1.0.0"
-compatibility: Requires bun runtime. FAL_API_KEY required. Optional ELEVENLABS_API_KEY, REPLICATE_API_TOKEN, GROQ_API_KEY
-allowed-tools: Bash(bun:*) Bash(cat:*) Read Write Edit
----
-
-# Video Generation with varg React Engine
-
-## Overview
-
-This rule helps you generate AI videos using the varg SDK's React engine. It provides:
-- Declarative JSX syntax for video composition
-- Automatic caching (same props = instant cache hit)
-- Parallel generation where possible
-- Support for images, video, music, voice, and captions
-
-## Step 1: Onboarding (REQUIRED for new users)
-
-Before generating videos, ensure the user has the required API keys configured.
-
-### Check Current Setup
-
-Run this command to check existing configuration:
-
-\`\`\`bash
-cat .env 2>/dev/null | grep -E "^(FAL_API_KEY|ELEVENLABS_API_KEY|REPLICATE_API_TOKEN|GROQ_API_KEY)=" || echo "No API keys found in .env"
-\`\`\`
-
-### Required: FAL_API_KEY
-
-**This is the minimum requirement for video generation.**
-
-| Detail | Value |
-|--------|-------|
-| Provider | Fal.ai |
-| Get it | https://fal.ai/dashboard/keys |
-| Free tier | Yes (limited credits) |
-| Used for | Image generation (Flux), Video generation (Wan 2.5, Kling) |
-
-If user doesn't have \`FAL_API_KEY\`:
-1. Direct them to https://fal.ai/dashboard/keys
-2. They need to create an account and generate an API key
-3. Add to \`.env\` file in project root
-
-### Optional Keys (warn if missing, but continue)
-
-| Feature | Required Key | Provider | Get It |
-|---------|-------------|----------|--------|
-| Music generation | \`ELEVENLABS_API_KEY\` | ElevenLabs | https://elevenlabs.io/app/settings/api-keys |
-| Voice/Speech | \`ELEVENLABS_API_KEY\` | ElevenLabs | https://elevenlabs.io/app/settings/api-keys |
-| Lipsync | \`REPLICATE_API_TOKEN\` | Replicate | https://replicate.com/account/api-tokens |
-| Transcription | \`GROQ_API_KEY\` | Groq | https://console.groq.com/keys |
-
-**When keys are missing, inform user what features are unavailable.**
+function resolveCodexHome(cwd: string): string {
+  const env = process.env.CODEX_HOME;
+  const home = process.env.HOME ?? cwd;
+  if (!env) return join(home, ".codex");
+  if (env === "~") return home;
+  if (env.startsWith("~/")) {
+    return join(home, env.slice(2));
+  }
+  return env;
+}
 
-## Step 2: Quick Templates
+function copyDirSync(srcDir: string, destDir: string): void {
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
 
-### Simple Slideshow (FAL only)
+  for (const entry of readdirSync(srcDir)) {
+    const srcPath = join(srcDir, entry);
+    const destPath = join(destDir, entry);
+    const stats = statSync(srcPath);
 
-\`\`\`tsx
-import { render, Render, Clip, Image } from "vargai/react";
+    if (stats.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
 
-const SCENES = [
-  "sunset over ocean, cinematic",
-  "mountain peaks at dawn, misty",
-  "city skyline at night, neon",
-];
+function installSkillFromRepo(
+  cwd: string,
+  skillName: string,
+  destBase: string,
+): string | null {
+  const srcDir = join(cwd, "skills", skillName);
+  if (!existsSync(srcDir)) {
+    log.warn(`Skill source not found: ${srcDir}`);
+    return null;
+  }
 
-await render(
-  <Render width={1080} height={1920}>
-    {SCENES.map((prompt, i) => (
-      <Clip key={i} duration={3} transition={{ name: "fade", duration: 0.5 }}>
-        <Image prompt={prompt} zoom="in" />
-      </Clip>
-    ))}
-  </Render>,
-  { output: "output/slideshow.mp4" }
-);
-\`\`\`
-
-### Animated Video (FAL + ElevenLabs)
-
-\`\`\`tsx
-import { render, Render, Clip, Image, Animate, Music } from "vargai/react";
-import { fal, elevenlabs } from "vargai/ai";
-
-await render(
-  <Render width={1080} height={1920}>
-    <Music prompt="upbeat electronic" model={elevenlabs.musicModel()} duration={10} />
-    <Clip duration={5}>
-      <Animate
-        image={Image({ prompt: "cute cat on windowsill" })}
-        motion="cat turns head, blinks slowly"
-        model={fal.videoModel("wan-2.5")}
-        duration={5}
-      />
-    </Clip>
-  </Render>,
-  { output: "output/video.mp4" }
-);
-\`\`\`
-
-### Talking Character
-
-\`\`\`tsx
-import { render, Render, Clip, Image, Animate, Speech } from "vargai/react";
-import { fal, elevenlabs } from "vargai/ai";
-
-await render(
-  <Render width={1080} height={1920}>
-    <Clip duration="auto">
-      <Animate
-        image={Image({ prompt: "friendly robot, blue metallic", aspectRatio: "9:16" })}
-        motion="robot talking, subtle head movements"
-        model={fal.videoModel("wan-2.5")}
-      />
-      <Speech voice="adam" model={elevenlabs.speechModel("turbo")}>
-        Hello! I'm your AI assistant. Let's create something amazing!
-      </Speech>
-    </Clip>
-  </Render>,
-  { output: "output/talking-robot.mp4" }
-);
-\`\`\`
-
-## Step 3: Running Videos
-
-\`\`\`bash
-bun run your-video.tsx
-\`\`\`
-
-## Key Components
-
-| Component | Purpose | Required Key |
-|-----------|---------|--------------|
-| \`<Render>\` | Root container | - |
-| \`<Clip>\` | Sequential segment | - |
-| \`<Image>\` | AI image | FAL |
-| \`<Animate>\` | Image-to-video | FAL |
-| \`<Music>\` | Background music | ElevenLabs |
-| \`<Speech>\` | Text-to-speech | ElevenLabs |
-
-## Common Patterns
-
-### Character Consistency
-\`\`\`tsx
-const character = Image({ prompt: "blue robot" });
-// Reuse same reference for consistent appearance
-<Animate image={character} motion="waving" />
-<Animate image={character} motion="dancing" />
-\`\`\`
-
-### Transitions
-\`\`\`tsx
-<Clip transition={{ name: "fade", duration: 0.5 }}>
-// Options: fade, crossfade, wipeleft, cube, slideup, etc.
-\`\`\`
-
-### Aspect Ratios
-- \`9:16\` - TikTok, Reels, Shorts (vertical)
-- \`16:9\` - YouTube (horizontal)
-- \`1:1\` - Instagram (square)
-
-## Troubleshooting
-
-### "FAL_API_KEY not found"
-- Check \`.env\` file exists in project root
-- Ensure no spaces around \`=\` sign
-- Restart terminal after adding keys
-
-### "Rate limit exceeded"
-- Free tier has limited credits
-- Wait or upgrade plan
-- Use caching to avoid regenerating
-
-## Next Steps
-
-1. Add your FAL_API_KEY to \`.env\`
-2. Run \`bun run examples/my-first-video.tsx\`
-3. Or ask the agent: "create a 10 second tiktok video about cats"
-`;
+  const destDir = join(destBase, "skills", skillName);
+  copyDirSync(srcDir, destDir);
+  return destDir;
+}
 
 // Example video file
 const EXAMPLE_VIDEO = `/** @jsxImportSource vargai */
@@ -424,20 +284,35 @@ Get your free API key at: ${COLORS.cyan}https://fal.ai/dashboard/keys${COLORS.re
     }
   }
 
-  // Step 3: Install Agent Skills (SKILL.md) + Claude Code symlink
+  // Step 3: Install Agent Skills (from repo) + Claude Code symlink
   log.step("Installing Agent Skills");
 
-  // Create .claude/skills/varg-video-generation/ (Agent Skills format)
-  const skillsDir = join(cwd, ".claude/skills/varg-video-generation");
-  const skillPath = join(skillsDir, "SKILL.md");
+  const skillsToInstall = [
+    "varg-video-generation",
+    "vargai-pipeline-cookbooks",
+  ];
+  const claudeBase = join(cwd, ".claude");
+  const localCodexHome = join(cwd, ".codex");
+  const codexHome = resolveCodexHome(cwd);
+  const codexDisplayBase = codexHome === localCodexHome ? ".codex" : codexHome;
+
+  const installedClaudeSkills: string[] = [];
+  const installedCodexSkills: string[] = [];
+
+  for (const skillName of skillsToInstall) {
+    const claudeDest = installSkillFromRepo(cwd, skillName, claudeBase);
+    if (claudeDest) {
+      installedClaudeSkills.push(`.claude/skills/${skillName}/`);
+      log.success(`Installed ${skillName} for Claude Code`);
+    }
 
-  if (!existsSync(skillsDir)) {
-    mkdirSync(skillsDir, { recursive: true });
+    const codexDest = installSkillFromRepo(cwd, skillName, codexHome);
+    if (codexDest) {
+      installedCodexSkills.push(`${codexDisplayBase}/skills/${skillName}/`);
+      log.success(`Installed ${skillName} for Codex (${codexDisplayBase})`);
+    }
   }
 
-  writeFileSync(skillPath, SKILL_MD);
-  log.success("Installed SKILL.md (Agent Skills format)");
-
   // Create .claude/rules/ symlink for Claude Code compatibility
   const rulesDir = join(cwd, ".claude/rules");
   const rulePath = join(rulesDir, "video-generation.md");
@@ -495,8 +370,19 @@ Get your free API key at: ${COLORS.cyan}https://fal.ai/dashboard/keys${COLORS.re
 ${COLORS.green}${COLORS.bold}Setup complete!${COLORS.reset}
 
 ${COLORS.bold}What was installed:${COLORS.reset}
-  ${COLORS.dim}├─${COLORS.reset} .claude/skills/varg-video-generation/SKILL.md ${COLORS.dim}(Agent Skills)${COLORS.reset}
+  ${installedClaudeSkills
+    .map(
+      (path) =>
+        `${COLORS.dim}├─${COLORS.reset} ${path} ${COLORS.dim}(Claude skill)${COLORS.reset}`,
+    )
+    .join("\n  ")}
   ${COLORS.dim}├─${COLORS.reset} .claude/rules/video-generation.md ${COLORS.dim}(symlink for Claude Code)${COLORS.reset}
+  ${installedCodexSkills
+    .map(
+      (path) =>
+        `${COLORS.dim}├─${COLORS.reset} ${path} ${COLORS.dim}(Codex skill)${COLORS.reset}`,
+    )
+    .join("\n  ")}
   ${COLORS.dim}├─${COLORS.reset} examples/my-first-video.tsx ${COLORS.dim}(starter example)${COLORS.reset}
   ${COLORS.dim}├─${COLORS.reset} output/ ${COLORS.dim}(video output folder)${COLORS.reset}
   ${COLORS.dim}└─${COLORS.reset} .cache/ai/ ${COLORS.dim}(generation cache)${COLORS.reset}

From 15073762c293ff52a3c3ae1c0f74d6747847eb65 Mon Sep 17 00:00:00 2001
From: Michailbul <mbuloichykai@gmail.com>
Date: Fri, 23 Jan 2026 01:37:34 +0300
Subject: [PATCH 4/5] fix(examples): make onlyfans workflow fal-only

---
 src/react/examples/onlyfans-1m/workflow.tsx | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/src/react/examples/onlyfans-1m/workflow.tsx b/src/react/examples/onlyfans-1m/workflow.tsx
index 5282610d..46f09da5 100644
--- a/src/react/examples/onlyfans-1m/workflow.tsx
+++ b/src/react/examples/onlyfans-1m/workflow.tsx
@@ -1,19 +1,19 @@
 /**
  * OnlyFans-style selfie video workflow (React DSL)
  *
- * 1. Generate base girl image using Higgsfield Soul
+ * 1. Generate base girl image using fal nano-banana-pro
  * 2. Edit bra color using nano-banana-pro/edit
  * 3. Generate 5 photos with different angles using nano-banana
  * 4. Animate all with prompts (step back, turn left/right)
  * 5. Concatenate into ~10 second video
  *
- * Run: bun run src/ai-sdk/react/cli.ts src/ai-sdk/examples/onlyfans-1m/workflow.tsx -o output/onlyfans-1m.mp4
+ * Run: bun run src/cli/index.ts render src/react/examples/onlyfans-1m/workflow.tsx -o output/onlyfans-1m.mp4
  *
- * Required env: HIGGSFIELD_API_KEY, HIGGSFIELD_SECRET, FAL_KEY
+ * Required env: FAL_API_KEY (or FAL_KEY)
  */
 
-import { fal, higgsfield } from "../../../ai-sdk";
-import { Clip, Image, Render, Video } from "../..";
+import { fal } from "vargai/ai";
+import { Clip, Image, Render, Video } from "vargai/react";
 
 // ============================================================================
 // CHARACTER DEFINITION
@@ -21,14 +21,11 @@ import { Clip, Image, Render, Video } from "../..";
 
 const NEW_BRA_COLOR = "deep purple";
 
-// Base character prompt for Higgsfield
+// Base character prompt (seedream edit requires an image input)
 const baseCharacter = Image({
   prompt:
     "A beautiful Slavic woman in her late 20s with platinum blonde hair, icy blue eyes, and perfect skin. She bends very close to the phone lens, her chest framed by a white sports bra with a bold neckline, and she is wearing high-waisted athletic shorts in pale grey that accentuate her figure. Her expression is confident and slightly teasing. The background shows a modern apartment with soft daylight through large windows, reinforcing the natural homemade vibe",
-  model: higgsfield.imageModel("soul", {
-    quality: "1080p",
-    styleId: higgsfield.styles.CAM_360,
-  }),
+  model: fal.imageModel("nano-banana-pro"),
   aspectRatio: "9:16",
 });
 

From d4d6f8b8b31a926ae381672420ffe7c90843bcab Mon Sep 17 00:00:00 2001
From: Michailbul <mbuloichykai@gmail.com>
Date: Fri, 23 Jan 2026 01:35:08 +0300
Subject: [PATCH 5/5] docs(skill): fix setup command

---
 skills/varg-video-generation/SKILL.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/skills/varg-video-generation/SKILL.md b/skills/varg-video-generation/SKILL.md
index d5e1afff..d330e8d7 100644
--- a/skills/varg-video-generation/SKILL.md
+++ b/skills/varg-video-generation/SKILL.md
@@ -26,7 +26,7 @@ Generate AI videos using declarative JSX syntax with automatic caching and paral
 Run the setup script to initialize a project:
 
 ```bash
-bun scripts/setup.ts
+bun run src/init.ts
 ```
 
 Or check API keys directly:
@@ -222,7 +222,7 @@ const character = Image({ prompt: "blue robot" });
 
 ## Next Steps
 
-1. Run `bun scripts/setup.ts` to initialize project
+1. Run `bun run src/init.ts` to initialize project
 2. Add your FAL_API_KEY to `.env`
 3. Run `bun run examples/my-first-video.tsx`
 4. Or ask the agent: "create a 10 second tiktok video about cats"