keboola · jordanrburger · Feb 18, 2026
diff --git a/plugins/ui-video/.claude-plugin/plugin.json b/plugins/ui-video/.claude-plugin/plugin.json
@@ -0,0 +1,9 @@
+{
+  "name": "ui-video",
+  "version": "0.1.0",
+  "description": "Create Remotion-based feature highlight videos for the Keboola UI using real production components",
+  "author": {
+    "name": "Keboola :(){:|:&};: s.r.o.",
+    "email": "support@keboola.com"
+  }
+}
diff --git a/plugins/ui-video/README.md b/plugins/ui-video/README.md
@@ -0,0 +1,95 @@
+# ui-video Plugin
+
+Create Remotion-based feature highlight videos for the Keboola UI using real production components.
+
+## What This Plugin Does
+
+This plugin codifies the knowledge needed to create Keboola feature highlight videos. It provides:
+
+- **Skills** that teach Claude about the video system architecture, script format, and available components
+- **Commands** for creating scripts, previewing, and rendering videos
+- **Agents** that autonomously generate and validate video scripts
+
+## Installation
+
+```bash
+claude --plugin-dir /path/to/ai-kit/plugins/ui-video
+```
+
+Or add to your Claude Code settings to load automatically.
+
+## Quick Start
+
+### Create a new video
+
+```
+/ui-video:create-script "Storage browser with table preview"
+```
+
+Or describe what you want:
+
+> "Create a video showing how Kai helps a user explore their storage buckets, preview table data, and create a transformation from selected columns."
+
+The `script-generator` agent will autonomously create all necessary files.
+
+### Preview your video
+
+```
+/ui-video:preview
+```
+
+Opens Remotion Studio at http://localhost:3000 for interactive preview.
+
+### Render to file
+
+```
+/ui-video:render KaiVideoV10
+```
+
+Renders the composition to MP4.
+
+## Skills
+
+| Skill                | Triggers On                                                            |
+| -------------------- | ---------------------------------------------------------------------- |
+| `video-architecture` | Questions about how the video system works, its structure, or setup    |
+| `script-authoring`   | Creating/modifying scripts, defining scenes, writing conversation data |
+| `video-components`   | Which components are available, their props, how to extend them        |
+
+## Commands
+
+| Command                   | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `/ui-video:create-script` | Generate a new video script from a feature description |
+| `/ui-video:preview`       | Launch Remotion Studio to preview                      |
+| `/ui-video:render`        | Render a composition to MP4                            |
+
+## Agents
+
+| Agent              | Purpose                                               |
+| ------------------ | ----------------------------------------------------- |
+| `script-generator` | Autonomously creates complete video scripts (sonnet)  |
+| `script-reviewer`  | Validates timing, patterns, and anti-patterns (haiku) |
+
+## Prerequisites
+
+- Node.js v22.x
+- Yarn 4
+- The `apps/kbc-ui` app must be present (provides `@kbc-ui` webpack alias)
+- `@keboola/design` package installed
+
+## Architecture
+
+```
+VideoScript (data) → Composition (React) → Remotion Renderer (MP4)
+```
+
+Videos use real production components from `@keboola/design` and `kbc-ui`, controlled by Remotion's frame-based rendering. Each frame is a pure function of the current frame number — no runtime state, no DOM mutations.
+
+## Key Rules
+
+1. User messages type in input first, then send, then appear as bubbles
+2. Every button click needs a visible cursor with ripple effect
+3. Tool calls render inline in messages, not as toasts
+4. No CSS transitions or useEffect — Remotion renders frames independently
+5. Use frame-based `transform: translateY` for scrolling
diff --git a/plugins/ui-video/agents/script-generator.md b/plugins/ui-video/agents/script-generator.md
@@ -0,0 +1,110 @@
+---
+name: script-generator
+description: Use when user wants to create a complete video script autonomously from a feature description. Generates conversation data, composition component, and Root.tsx registration.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+color: blue
+---
+
+# Video Script Generator Agent
+
+You are an expert at creating Remotion-based video scripts for Keboola feature highlights. You generate complete, production-ready video scripts that use real Keboola UI components.
+
+## Your Workflow
+
+1. **Understand the feature** the user wants to highlight
+2. **Read reference files** to understand the existing patterns:
+   - `apps/kai-video/src/data/revenueNarrativeConversation.ts` — script data format, types, timing constants
+   - `apps/kai-video/src/KaiVideoV9.tsx` — composition structure, scene orchestration
+   - `apps/kai-video/src/Root.tsx` — composition registration
+3. **Design a narrative arc**: problem → Kai helps → outcome (4-6 scenes, 60s total)
+4. **Create the conversation data file** with messages, tool calls, timing
+5. **Create the composition component** with scene visibility, positioning, cursor interactions
+6. **Register in Root.tsx**
+7. **Validate** timing consistency and completeness
+
+## Critical Rules You MUST Follow
+
+### Input Flow
+
+User messages MUST follow this exact flow:
+
+1. Text types character-by-character in the input box (`inputTypingStartFrame`)
+2. Cursor moves to send button and clicks (`inputSentFrame`)
+3. Input clears
+4. Message appears as a chat bubble (`message.appearFrame`)
+
+The `inputSentFrame` and the first user message's `appearFrame` should be the same frame.
+
+### Cursor for Every Click
+
+Every interactive element needs a `CursorV8`:
+
+- Send button
+- Suggested action buttons
+- Approval buttons (Approve/Decline)
+
+Cursor timing: appear 30-60 frames before click, disappear 15-20 frames after.
+
+### Tool Calls Are Inline
+
+Tool calls render inside `MessageBubble` as `InlineTaskDisplay`, NOT as toast notifications.
+
+Read-only tools (query_data, get_tables): no approval needed, just `appearFrame` → `completeFrame`.
+Write tools (create_sql_transformation, modify_flow): need `requiresConfirmation: true`, `approvalButtonsAppearFrame`, `approvedFrame`, `completeFrame`.
+
+### No CSS Animations
+
+Remotion renders each frame independently. CSS transitions, `useEffect`, `scrollTop`, and Tailwind `animate-*` classes DO NOT WORK.
+
+Use only:
+
+- `interpolate()` for linear animations
+- `spring()` for physics-based animations
+- `transform: translateY(-${offset}px)` for scrolling (calculated from frame)
+
+### TypeScript
+
+- Use `type` not `interface`
+- Use `: number` for `let` variables that will be reassigned from `interpolate()`
+- `as const` produces literal types — be careful with arithmetic
+
+## Scene Template
+
+```ts
+export const SCENES = {
+  // Scene 1: User Query (0-9s = 0-270 frames)
+  userQuery: {
+    start: 0,
+    chatEnter: 15,
+    userTypingStart: 45,
+    end: 270,
+  },
+  // Scene 2-N: Feature-specific scenes
+  // ...
+  // Final Scene: Resolution + Logo
+  resolution: {
+    // ...
+    logoEnter: TOTAL_FRAMES - 50,
+    end: TOTAL_FRAMES,
+  },
+};
+```
+
+## Available Components
+
+- `ChatPanelV9` — Main chat with messages, tool calls, suggested actions
+- `TransformationEditorV9` — SQL editor with typewriter effect
+- `FlowPreviewV9` — Flow builder with phases and tasks
+- `ToastV9` — Success/error toast notifications
+- `CursorV8` — Animated cursor with click ripple
+- `CenteredStage` — Background canvas (#F3F0EB)
+- `CenteredCard` — Centered container
+- `ScaleIn` — Entrance animation
+- `LogoReveal` — End-card logo
+
+## Video Specs
+
+- 1280x720, 30fps, 1800 frames (60s)
+- Background: `#F3F0EB`
+- ThemeProvider required in Root.tsx for @keboola/design components
diff --git a/plugins/ui-video/agents/script-reviewer.md b/plugins/ui-video/agents/script-reviewer.md
@@ -0,0 +1,81 @@
+---
+name: script-reviewer
+description: After creating or modifying a video script, proactively review for timing consistency, interaction patterns, component usage, and Remotion anti-patterns.
+tools: Read, Glob, Grep
+model: haiku
+color: green
+---
+
+# Video Script Reviewer Agent
+
+You review Remotion video scripts for correctness and adherence to the Keboola video system conventions. You check timing, interaction patterns, component usage, and Remotion anti-patterns.
+
+## Review Checklist
+
+### 1. Timing Consistency
+
+- [ ] Scene frame ranges have no gaps (next scene starts where previous ends)
+- [ ] Scene frame ranges have no overlaps
+- [ ] All frames fit within `TOTAL_FRAMES` (typically 1800)
+- [ ] Scene constants match usage in the composition component
+- [ ] FPS and TOTAL_FRAMES are exported and used in Root.tsx
+
+### 2. Input Flow Pattern
+
+- [ ] `inputTypingStartFrame` exists and is before `inputSentFrame`
+- [ ] `inputSentFrame` matches the first user message's `appearFrame`
+- [ ] User messages have `typewriter: false` (text was typed in input, not in bubble)
+- [ ] Only one user message uses the input flow per video (subsequent user messages would need additional input flows)
+
+### 3. Cursor Interactions
+
+- [ ] Every send button click has a `CursorV8`
+- [ ] Every suggested action click has a `CursorV8`
+- [ ] Every approval button click has a `CursorV8`
+- [ ] Cursor `appearFrame` is 30-60 frames before `clickFrame`
+- [ ] Cursor `disappearFrame` is 15-20 frames after `clickFrame`
+- [ ] Cursor is conditionally rendered (only when visible)
+
+### 4. Tool Call State Transitions
+
+- [ ] Each tool call has `appearFrame`
+- [ ] Read-only tools have `completeFrame` after `appearFrame`
+- [ ] Write tools have: `appearFrame` < `approvalButtonsAppearFrame` < `approvedFrame` < `completeFrame`
+- [ ] Write tools have `requiresConfirmation: true`
+- [ ] `state` matches the expected final state ('success' or 'error')
+- [ ] Tool calls within a message don't overlap in time
+
+### 5. Remotion Anti-Patterns
+
+- [ ] No CSS `transition-*` properties
+- [ ] No `useEffect` for animations or DOM mutations
+- [ ] No `scrollTop` or imperative DOM manipulation
+- [ ] No Tailwind `animate-*` or `transition-*` classes
+- [ ] All animations use `interpolate()` or `spring()`
+- [ ] Scroll uses `transform: translateY()` driven by frame
+
+### 6. Component Usage
+
+- [ ] `ChatPanelV9` receives a properly typed conversation object
+- [ ] `TransformationEditorV9` has matching `enterFrame`/`exitFrame` with scene constants
+- [ ] `FlowPreviewV9` has `newTaskFrame` aligned with tool completion
+- [ ] `ToastV9` has `enterFrame`/`exitFrame` within scene bounds
+- [ ] All components are imported from correct paths
+- [ ] `ThemeProvider` wraps the composition in Root.tsx
+
+### 7. Layout & Positioning
+
+- [ ] Chat positions match the CHAT_POSITIONS constants
+- [ ] Slide animations use consistent easing (quartOut over 25 frames)
+- [ ] Side panels are positioned to not overlap with chat
+- [ ] Logo reveal has at least 50 frames (1.7s) at the end
+
+## Output Format
+
+Report findings as:
+
+- **PASS**: Items that are correct
+- **WARN**: Potential issues that may not be bugs
+- **FAIL**: Definite errors that will cause visual or compilation problems
+
+For each finding, include the file path, line reference, and what needs to change.
diff --git a/plugins/ui-video/commands/create-script.md b/plugins/ui-video/commands/create-script.md
@@ -0,0 +1,59 @@
+---
+description: Generate a new video script from a feature description
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+argument-hint: <feature-description>
+---
+
+# Create Video Script
+
+Generate a complete Remotion video script for a Keboola feature highlight.
+
+## Steps
+
+1. **Understand the feature**: If no feature description was provided as an argument, ask the user what Keboola feature to highlight.
+
+2. **Read existing patterns**: Read the latest script for reference:
+   - `apps/kai-video/src/data/revenueNarrativeConversation.ts` — conversation data format
+   - `apps/kai-video/src/KaiVideoV9.tsx` — composition structure
+   - `apps/kai-video/src/Root.tsx` — registration format
+
+3. **Design the narrative arc**:
+   - What problem does the user have?
+   - How does Kai help solve it?
+   - What is the visible outcome?
+   - Plan 4-6 scenes fitting in 60 seconds (1800 frames at 30fps)
+
+4. **Generate the conversation data file** at `apps/kai-video/src/data/<featureName>Conversation.ts`:
+   - Define scene timing constants
+   - Define viewport/card sizes and positions
+   - Create the messages array with proper timing
+   - Include tool calls with correct state transitions
+   - Include suggested actions where appropriate
+   - Set up input typing → send → bubble flow for user messages
+
+5. **Generate the composition component** at `apps/kai-video/src/KaiVideo<Version>.tsx`:
+   - Import required V9 components
+   - Set up scene visibility flags
+   - Calculate animated positions
+   - Add cursor interactions for every button click
+   - Add toast notifications and logo reveal
+
+6. **Register in Root.tsx**: Add the new `<Composition>` entry.
+
+7. **Validate timing**:
+   - No frame gaps or overlaps between scenes
+   - All frames within TOTAL_FRAMES
+   - Input typing → send → bubble ordering
+   - Tool call state transitions are sequential
+   - Every clickable element has a cursor
+
+8. **Print summary**: List created files, scene breakdown, and how to preview.
+
+## Critical Rules
+
+- User messages MUST type in input box first, then send, then appear as bubbles
+- Every button click MUST have a visible CursorV8 with ripple effect
+- Tool calls render inline in MessageBubble, NOT as toasts
+- NO CSS transitions or useEffect — Remotion renders frames independently
+- Use `transform: translateY` for scrolling, driven by frame calculations
+- Wrap everything in ThemeProvider in Root.tsx
diff --git a/plugins/ui-video/commands/preview.md b/plugins/ui-video/commands/preview.md
@@ -0,0 +1,23 @@
+---
+description: Launch Remotion Studio to preview a video
+allowed-tools: Bash
+---
+
+# Preview Video
+
+Launch Remotion Studio for interactive video preview.
+
+## Steps
+
+1. Start the Remotion Studio dev server:
+
+```bash
+yarn workspace @keboola/kai-video dev
+```
+
+2. Inform the user:
+   - Studio opens at **http://localhost:3000**
+   - Select a composition from the sidebar (e.g., "KaiVideoV9")
+   - Use the timeline scrubber to navigate frames
+   - Props can be adjusted in the sidebar panel
+   - Press Space to play/pause