@damiangilgonzalez/harness 1.3.7

package/skills/redis/references/locks-and-rate-limiting.md

@@ -0,0 +1,140 @@
+# Locks and rate limiting — depth
+
+The full Redlock algorithm and its critique, lease renewal, fencing tokens, and all four
+rate-limit algorithms with complete Lua. Client-agnostic.
+
+## Single-instance lock (the baseline)
+
+```text
+SET resource:lock <random-token> NX PX <ttl-ms>   # acquire: only if absent, auto-expires
+# ... protected work ...
+# release via the compare-and-delete Lua below — NEVER a bare DEL
+```
+
+The token must be unguessable and unique per acquisition (a UUID or `<host>:<pid>:<rand>`), because
+release is "delete only if the value is still mine":
+
+```lua
+-- KEYS[1] = lock key, ARGV[1] = my token. Returns 1 if I held and released, else 0.
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+else
+  return 0
+end
+```
+
+## Lease renewal (watchdog)
+
+If protected work can outlast the TTL, the lock expires mid-task and a second worker starts. Renew
+the TTL periodically — but only if you still own it (same token guard), or you will extend a lock
+someone else now holds:
+
+```lua
+-- KEYS[1] = lock key, ARGV[1] = my token, ARGV[2] = new ttl ms.
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('PEXPIRE', KEYS[1], ARGV[2])
+else
+  return 0
+end
+```
+
+Run this from a watchdog at ~`ttl/3`. If a renewal ever returns 0, you lost the lock — stop the work,
+do not assume you still hold it.
+
+## Redlock (multi-instance) and why it is contested
+
+Redlock acquires the same lock on a majority of N independent masters (e.g. 3 of 5), each with
+`SET NX PX`, and considers the lock held only if the majority succeeded *within* a small fraction of
+the TTL (so the remaining validity time is still positive). Release deletes on all N.
+
+The critique (Kleppmann; acknowledged by antirez): Redlock's safety rests on **bounded clock drift**
+and **no long process pauses**. A GC pause, a hypervisor stop-the-world, or an NTP jump can let the
+TTL expire on the holder's wall clock while the holder still believes it is inside the lease; a second
+client then acquires, and both act. Majority-acquisition does not fix this — it is a *timing* problem,
+not a *quorum* problem.
+
+### Fencing tokens — the only real fix
+
+Issue a **monotonically increasing token** with every successful acquisition (e.g. `INCR
+resource:fence`). The protected resource (DB, file store, queue) records the highest token it has
+accepted and **rejects any write carrying a lower token**. Now even a paused-then-resumed holder is
+harmless: its token is stale, so its write is refused. No pure-Redis lock provides fencing; you must
+add the counter and enforce it at the resource.
+
+### Decision
+
+- **Idempotent / best-effort work** (cron de-dup, cache warm): single-instance `SET NX PX` is fine —
+  an occasional double-run is harmless.
+- **Hard mutual exclusion** (money, non-idempotent side effects): a Redis lock alone is *not* a safety
+  guarantee. Fence the resource, or use a real lease/consensus system (ZooKeeper, etcd, a DB advisory
+  lock). Redlock buys availability across instances, not correctness under pauses.
+
+## Rate limiting — four algorithms
+
+Every one must be a **single atomic `EVAL`**. The classic bug is splitting count and TTL: if the
+process dies between `INCR` and `EXPIRE`, the key never expires and the user is throttled forever.
+
+### Fixed window
+
+```lua
+-- KEYS[1]=counter, ARGV[1]=limit, ARGV[2]=window-seconds. 1=allow, 0=deny.
+local n = redis.call('INCR', KEYS[1])
+if n == 1 then redis.call('EXPIRE', KEYS[1], ARGV[2]) end
+if n > tonumber(ARGV[1]) then return 0 end
+return 1
+```
+
+Cheapest (one integer per key). Flaw: allows up to ~2× the limit across a window boundary (a burst at
+the end of one window plus a burst at the start of the next).
+
+### Sliding-window log
+
+Exact: store one timestamp per request in a sorted set, prune the old, count what remains.
+
+```lua
+-- KEYS[1]=zset, ARGV[1]=now-ms, ARGV[2]=window-ms, ARGV[3]=limit, ARGV[4]=member.
+redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, ARGV[1] - ARGV[2])   -- drop entries older than window
+local count = redis.call('ZCARD', KEYS[1])
+if count >= tonumber(ARGV[3]) then return 0 end
+redis.call('ZADD', KEYS[1], ARGV[1], ARGV[4])                   -- record this request
+redis.call('PEXPIRE', KEYS[1], ARGV[2])                         -- self-clean idle keys
+return 1
+```
+
+Exact, but O(requests) memory per key — expensive at high limits.
+
+### Sliding-window counter
+
+Approximates the log with two fixed-window counters (current + previous), weighting the previous one
+by how far into the current window you are. Near-exact at a fraction of the memory of the log. Keep
+both counters and compute `prev * (1 - elapsed_fraction) + curr` in Lua; deny if that exceeds the limit.
+
+### Token bucket
+
+Allows controlled bursts: a bucket of capacity C refills at R tokens/sec; each request costs one token.
+
+```lua
+-- KEYS[1]=hash{tokens,ts}, ARGV[1]=capacity, ARGV[2]=refill/sec, ARGV[3]=now-sec, ARGV[4]=cost.
+local s = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
+local tokens = tonumber(s[1]) or tonumber(ARGV[1])
+local ts     = tonumber(s[2]) or tonumber(ARGV[3])
+tokens = math.min(tonumber(ARGV[1]), tokens + (ARGV[3] - ts) * ARGV[2])   -- refill by elapsed time
+if tokens < tonumber(ARGV[4]) then
+  redis.call('HSET', KEYS[1], 'tokens', tokens, 'ts', ARGV[3]); return 0
+end
+tokens = tokens - tonumber(ARGV[4])
+redis.call('HSET', KEYS[1], 'tokens', tokens, 'ts', ARGV[3])
+redis.call('PEXPIRE', KEYS[1], math.ceil(tonumber(ARGV[1]) / tonumber(ARGV[2]) * 1000))
+return 1
+```
+
+Smallest memory (one small hash per key), smooth average rate, configurable burst. The usual default.
+
+### Choosing
+
+| Need | Pick |
+| --- | --- |
+| Cheapest, OK with 2× edge bursts | fixed window |
+| Exact, low traffic | sliding-window log |
+| Near-exact, high traffic | sliding-window counter |
+| Smooth rate + intentional bursts | token bucket |

package/skills/redis/references/queues.md

@@ -0,0 +1,102 @@
+# Queues — depth
+
+Full reliable-list and Streams consumer-group implementations, stalled/pending recovery, dead-letter
+queues, idempotency, and the library comparison. Client-agnostic.
+
+## Reliable list pattern
+
+Never `RPOP` straight into a worker: a crash between the pop and the work loses the job. Move it
+atomically to a per-worker processing list, do the work idempotently, then ack by removing it. A
+separate reaper requeues anything orphaned in a processing list whose worker has died.
+
+```bash
+# 1. Atomic claim: pop from the queue, push onto THIS worker's processing list, in one command.
+job=$(redis-cli LMOVE jobs jobs:proc:w1 LEFT RIGHT)     # BLMOVE for a blocking variant
+
+# 2. Do the work — idempotently, because delivery is at-least-once (see below).
+
+# 3. Ack: remove the job from the processing list.
+redis-cli LREM jobs:proc:w1 1 "$job"
+```
+
+Reaper (runs periodically): for each `jobs:proc:*`, if its worker is gone (heartbeat key expired),
+`LMOVE` every element back to `jobs`. The trade-off: a job that was *almost* done but un-acked gets
+re-run — hence handlers must be idempotent.
+
+`LMOVE`/`BLMOVE` (Redis 6.2+) replace the older `RPOPLPUSH`/`BRPOPLPUSH`, which still work.
+
+## Streams + consumer groups (preferred for reliable jobs)
+
+Streams give per-message acks and a Pending Entries List (PEL) for free — no hand-rolled processing
+list. This is the right native primitive for reliable jobs.
+
+```bash
+# Create the group once (MKSTREAM creates the stream if absent). '$' = only new messages.
+redis-cli XGROUP CREATE jobs g1 '$' MKSTREAM
+
+# Producer: append, capping growth so the stream can't grow unbounded.
+redis-cli XADD jobs MAXLEN '~' 100000 '*' type email to user@x.com
+
+# Consumer: read new messages ('>'), each delivered message enters this consumer's PEL.
+redis-cli XREADGROUP GROUP g1 worker1 COUNT 10 BLOCK 5000 STREAMS jobs '>'
+
+# Ack a finished message — removes it from the PEL.
+redis-cli XACK jobs g1 <id>
+```
+
+### Stalled / pending recovery
+
+A worker that dies leaves its in-flight messages in the PEL, un-acked. Reclaim them with
+`XAUTOCLAIM` (Redis 6.2+), which transfers messages idle longer than a threshold to a live consumer:
+
+```bash
+# Claim messages in group g1 idle > 60000ms, reassigning them to worker2, starting at id 0.
+redis-cli XAUTOCLAIM jobs g1 worker2 60000 0
+# Inspect the backlog: XPENDING jobs g1   (summary)  /  XPENDING jobs g1 - + 10  (detail)
+```
+
+Track a delivery count per message (`XPENDING` reports it); after K deliveries, stop retrying and
+route to a dead-letter stream instead of looping forever on a poison message.
+
+### Dead-letter queue
+
+```bash
+# Poison message exceeded max deliveries: copy to a DLQ stream, then ack it off the main group.
+redis-cli XADD jobs:dead '*' orig_id <id> reason max-deliveries-exceeded payload "$payload"
+redis-cli XACK jobs g1 <id>
+```
+
+Trim both the main and DLQ streams (`MAXLEN ~`) so neither grows without bound. Redis 8.2 adds
+`XDELEX`/`XACKDEL` for ack-and-delete in one step.
+
+## Idempotency and at-least-once
+
+Every Redis queue (list or stream) is **at-least-once**: a crash after work but before ack re-runs
+the job. Make handlers idempotent:
+
+- Carry an **idempotency key** (a job id or a hash of the payload). Before the side effect, `SET
+  done:<key> 1 NX EX <ttl>`; if it returns nil, the job already ran — skip the side effect, just ack.
+- Or make the side effect itself idempotent (upserts keyed by id, conditional writes with a fencing
+  token, external APIs that accept an idempotency key).
+
+Exactly-once delivery does not exist over a network; exactly-once *effect* is achievable only by
+making the effect idempotent.
+
+## When to use a library instead of hand-rolling
+
+| Library | Language | You get |
+| --- | --- | --- |
+| **BullMQ** | TypeScript/Node | retries, delays, repeatable jobs, priorities, a dashboard, **stalled-job lock renewal** via `lockDuration`/`lockRenewTime` |
+| **Sidekiq** | Ruby | multi-threaded workers, retries, scheduling, web UI |
+| **RQ** | Python | simple, list-based, easy to reason about |
+| **Celery** (Redis broker) | Python | mature, broad feature set, can use Redis or others |
+
+Reach for a library the moment you need retries with backoff, scheduled/delayed jobs, priorities, or a
+dashboard — do not reinvent them. BullMQ's stalled-job handling is the canonical example: a worker
+holds a lock on its active job and renews it every `lockRenewTime`; if a worker dies, the lock lapses
+after `lockDuration` and the job is moved back to be retried up to its attempt limit. Setting
+`lockDuration` below your real job duration is the usual cause of "my jobs keep getting marked
+stalled and reprocessed" — raise it above the worst-case job time (and renew), don't lower your
+expectations.
+
+Hand-roll lists/streams only for the simplest cases or when no good library exists for your runtime.

package/skills/redis/scripts/verify.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — redis skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, NEVER connects to a Redis server, never writes):
+#   Scans discovered Redis-touching source/config for high-confidence foot-guns. It exits
+#   non-zero ONLY on a near-certain production bug (`KEYS` / `KEYS *` in non-test source).
+#   Everything else is advisory [warn], and an absence of Redis usage is [skip] (exit 0).
+#
+# Heuristics are deliberately conservative: client SDKs and config look wildly different across
+# node-redis, ioredis, redis-py, go-redis and Lettuce, so all the soft checks are warnings you
+# eyeball, not build-breakers. The hard fail is reserved for `KEYS` because it is essentially
+# always wrong on a hot path and trivially confirmable.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays). Arrays are initialised so
+# they expand safely under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# is_test_path <path> — true for files that look like tests/specs/fixtures, where foot-guns are fine.
+is_test_path() {
+  case "$1" in
+    *test*|*Test*|*spec*|*Spec*|*__tests__*|*fixtures*|*/mocks/*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Discover candidate source files (common Redis-client languages) and redis.conf, excluding vendor dirs.
+SRC_FILES=()
+while IFS= read -r -d '' f; do
+  SRC_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \
+       -o -path '*/dist/*' -o -path '*/build/*' -o -path '*/.next/*' \) -prune -o \
+    -type f \( -name '*.js' -o -name '*.ts' -o -name '*.jsx' -o -name '*.tsx' -o -name '*.mjs' \
+               -o -name '*.py' -o -name '*.go' -o -name '*.rb' -o -name '*.java' -o -name '*.kt' \
+               -o -name '*.lua' -o -name '*.php' -o -name '*.rs' \) -print0 2>/dev/null
+)
+
+CONF_FILES=()
+while IFS= read -r -d '' f; do
+  CONF_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' \) -prune -o \
+    -type f \( -name 'redis.conf' -o -name 'valkey.conf' -o -name '*redis*.conf' \) -print0 2>/dev/null
+)
+
+# Decide whether this project touches Redis at all. If not, skip cleanly.
+# Use -l (newline-separated) not -Z: BSD/macOS grep ignores -Z when listing filenames, so a
+# NUL-delimited read loop would mis-parse. Filenames with newlines are not supported here (rare),
+# which is an acceptable trade for portability across BSD and GNU grep.
+REDIS_HINT=0
+HINT_FILES=()
+if [ "${#SRC_FILES[@]}" -gt 0 ]; then
+  while IFS= read -r f; do
+    [ -n "$f" ] && HINT_FILES+=("$f")
+  done < <(
+    grep -ril -E 'redis|valkey|ioredis|bullmq|sidekiq|XREADGROUP|maxmemory' "${SRC_FILES[@]}" 2>/dev/null || true
+  )
+fi
+if [ "${#HINT_FILES[@]}" -gt 0 ] || [ "${#CONF_FILES[@]}" -gt 0 ]; then
+  REDIS_HINT=1
+fi
+
+if [ "$REDIS_HINT" -eq 0 ]; then
+  skip "no Redis/Valkey usage detected in this project — nothing to check"
+  ok "verify.sh passed"
+  exit 0
+fi
+
+# Only scan the files that actually mentioned Redis (plus conf files), to cut false positives.
+SCAN_FILES=()
+for f in ${HINT_FILES[@]+"${HINT_FILES[@]}"}; do SCAN_FILES+=("$f"); done
+for f in ${CONF_FILES[@]+"${CONF_FILES[@]}"}; do SCAN_FILES+=("$f"); done
+
+# ---- 1. KEYS / KEYS * in non-test source -> HARD FAIL ----
+# Match a KEYS command (quoted, or as a client method call), not the identifier "keys" in general.
+KEYS_HIT=0
+for f in "${SCAN_FILES[@]}"; do
+  is_test_path "$f" && continue
+  if grep -Eniq "([\"'\` ]KEYS[[:space:]]+[^)]|\.keys\(|->keys\(|[\"'\`]KEYS\*)" "$f" 2>/dev/null; then
+    # Exclude obvious false friends: object key iteration like Object.keys(, dict.keys(), .Keys (Go map helpers vary; conservative).
+    if grep -Eniq "([\"'\`][[:space:]]*KEYS[[:space:]]|[\"'\`]KEYS\*|redis[^.]*\.keys\(|client\.keys\(|->keys\()" "$f" 2>/dev/null; then
+      err "$f: uses Redis KEYS (O(N), blocks the single thread). Use SCAN MATCH ... COUNT ... instead."
+      KEYS_HIT=1
+    fi
+  fi
+done
+[ "$KEYS_HIT" -eq 0 ] && ok "no Redis KEYS in non-test source"
+
+# ---- 2. FLUSHALL / FLUSHDB in non-test source -> warn ----
+for f in "${SCAN_FILES[@]}"; do
+  is_test_path "$f" && continue
+  if grep -Eniq "FLUSHALL|FLUSHDB|\.flushall\(|\.flushdb\(" "$f" 2>/dev/null; then
+    note "$f: FLUSHALL/FLUSHDB present — wipes the instance; never run on a shared/prod Redis."
+  fi
+done
+
+# ---- 3. Lock release via DEL near a lock key without a token compare -> warn ----
+for f in "${SCAN_FILES[@]}"; do
+  is_test_path "$f" && continue
+  if grep -Eniq "lock" "$f" 2>/dev/null \
+     && grep -Eniq "(\.del\(|\.delete\(|->del\(|[\"'\`]DEL[\"'\` ])" "$f" 2>/dev/null \
+     && ! grep -Eiq "get'?\)?[[:space:]]*==[[:space:]]*ARGV|get'?[^=]*==[^=]*token|compare.?and.?del|redis\.call\('get'" "$f" 2>/dev/null; then
+    note "$f: lock + DEL but no visible token compare-and-delete — a bare DEL can release another owner's lock. Use a Lua GET==token then DEL."
+  fi
+done
+
+# ---- 4. SET ... NX for a lock with no PX/EX -> warn (lock that can't expire) ----
+for f in "${SCAN_FILES[@]}"; do
+  is_test_path "$f" && continue
+  # A SET with NX but neither PX nor EX on the same line/call is a lock that never auto-frees.
+  if grep -Eni "set[^\n]*\bNX\b" "$f" 2>/dev/null | grep -Eivq "\bP?X\b|expire|ttl" 2>/dev/null; then
+    if grep -Eni "set[^\n]*\bNX\b" "$f" 2>/dev/null | grep -Eiq "lock" 2>/dev/null; then
+      note "$f: SET ... NX on a lock with no PX/EX — a crashed owner holds it forever. Add PX <ttl-ms>."
+    fi
+  fi
+done
+
+# ---- 5. INCR not followed by an EXPIRE (counter with no TTL) -> warn ----
+for f in "${SCAN_FILES[@]}"; do
+  is_test_path "$f" && continue
+  if grep -Eniq "(\.incr\(|->incr\(|[\"'\`]INCR[\"'\` ])" "$f" 2>/dev/null \
+     && ! grep -Eniq "(expire|EXPIRE|pexpire|PEXPIRE|EX[[:space:]]|setex|SETEX)" "$f" 2>/dev/null; then
+    note "$f: INCR with no EXPIRE in the same file — a rate-limit counter with no TTL counts forever. Set EXPIRE atomically (Lua, or only when n==1)."
+  fi
+done
+
+# ---- 6/7. redis.conf eviction checks -> warn ----
+for f in ${CONF_FILES[@]+"${CONF_FILES[@]}"}; do
+  if grep -Eiq "^[[:space:]]*maxmemory[[:space:]]" "$f" 2>/dev/null \
+     && ! grep -Eiq "^[[:space:]]*maxmemory-policy" "$f" 2>/dev/null; then
+    note "$f: maxmemory set without maxmemory-policy — defaults to noeviction, which 500s a full cache. Set allkeys-lru/lfu for a cache."
+  fi
+  if grep -Eiq "^[[:space:]]*maxmemory-policy[[:space:]]+noeviction" "$f" 2>/dev/null; then
+    case "$f" in
+      *cache*|*Cache*) note "$f: maxmemory-policy noeviction on a file that looks like a cache config — a cache must evict (allkeys-lru/lfu), not fail writes." ;;
+    esac
+  fi
+done
+
+# ---- 8. while/long loop inside an inline Lua EVAL string -> warn ----
+for f in "${SCAN_FILES[@]}"; do
+  is_test_path "$f" && continue
+  if grep -Eniq "EVAL|eval" "$f" 2>/dev/null \
+     && grep -Eniq "while[[:space:]].*do|for[[:space:]].*=.*,.*do" "$f" 2>/dev/null \
+     && grep -Eniq "redis\.call" "$f" 2>/dev/null; then
+    note "$f: a loop inside Lua run via EVAL blocks ALL clients while it runs (Redis is single-threaded). Keep each EVAL a short bounded step."
+  fi
+done
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/remotion-video/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: remotion-video
+description: "Use when you need to render an actual video file with Remotion — React compositions, the Composition/Sequence/TransitionSeries graph, transitions, burned-in word-by-word captions from a transcript, automatic silence removal, b-roll overlays, headless CI renders, and a final MP4 or MOV. NOT writing the script, hook, beats or caption text (that is `video-shorts`), NOT mastering audio to LUFS or building an RSS feed (that is `podcast`), NOT structuring the narrative arc (that is `course-storytelling`)."
+tags: [remotion, video-rendering, react, captions, ffmpeg, whisper, youtube]
+recommends: [video-shorts, podcast, course-storytelling, youtube-packaging, nextjs]
+origin: risco
+---
+
+# Remotion Video — Encode the Actual Frames
+
+*You are the encoder and renderer.* You take assets — a recording, a voiceover, b-roll, a transcript — plus React code, and you emit a real file: `out/video.mp4`. Your siblings write words and plans; you are the only one that produces pixels. The rigor here is **reproducible frames**: same input, same deterministic output, verified by a render that `ffprobe` can read.
+
+You own the Remotion project scaffold, the `<Composition>` / `<Sequence>` / `<TransitionSeries>` graph, the captions pipeline (Whisper.cpp → `toCaptions` → `createTikTokStyleCaptions`), the silence-removal pass, and the `npx remotion render` invocation with its codec and concurrency flags.
+
+## The one decision: frames or words?
+
+If the ask is to produce a file, you are in the right place. If it is to produce text or a plan, route out before writing a single `.tsx`.
+
+| The ask | Goes to | Why |
+|---|---|---|
+| Produce an MP4/MOV, transitions, burned captions, render | **here** | These are pixels and frames |
+| Write the script, hook, beats, on-screen caption *text*, edit decision sheet | `../video-shorts/SKILL.md` | Those are words; the cut decisions, not the cut execution |
+| Master audio to a LUFS target, produce chapters + RSS `<item>` | `../podcast/SKILL.md` | Audio mastering and feed, not video encode |
+| Structure the lesson/video narrative arc and flow | `../course-storytelling/SKILL.md` | Narrative architecture, not rendering |
+| Design the thumbnail image | `../youtube-thumbnails/SKILL.md` | A still image, not a video |
+
+Boundary in one line: **video-shorts decides the cuts and writes the caption text; you execute the cuts in code and burn the captions into frames.**
+
+## Scaffold the project
+
+```bash
+npx create-video@latest --yes --blank my-video
+cd my-video
+npm i
+npm run dev        # opens Remotion Studio in the browser
+```
+
+Remotion's current stable line is **4.0.471**; it needs Node 16+ (or Bun 1.0.3+), and local rendering targets macOS 15 (Sequoia)+. Since **January 2026** Remotion ships Agent Skills — `npx skills add remotion-dev/skills` wires Remotion-aware guidance into Claude Code. Run it inside a Remotion project when you want the framework's own skill loaded alongside this one.
+
+**Pin fps and dimensions on `<Composition>` first, and never change them mid-project.** *Why: every duration downstream is measured in frames, and `frames = seconds * fps`. Change fps after you have written durations and every timing silently shifts.* Vertical shorts are `1080×1920 @ 30`; landscape is `1920×1080 @ 30`.
+
+## The composition graph
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { MyVideo } from "./MyVideo";
+
+export const RemotionRoot: React.FC = () => {
+  return (
+    <Composition
+      id="MyVideo"            // the id you pass to `remotion render`
+      component={MyVideo}
+      durationInFrames={300}  // 10s at 30fps
+      fps={30}
+      width={1080}
+      height={1920}
+    />
+  );
+};
+```
+
+```tsx
+// src/MyVideo.tsx
+import { AbsoluteFill, Sequence, useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
+
+export const MyVideo: React.FC = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
+  const scale = spring({ frame, fps, config: { damping: 200 } });
+  return (
+    <AbsoluteFill style={{ backgroundColor: "black" }}>
+      <Sequence from={0} durationInFrames={90}>
+        <AbsoluteFill style={{ opacity, transform: `scale(${scale})` }}>{/* scene 1 */}</AbsoluteFill>
+      </Sequence>
+      <Sequence from={90} durationInFrames={210}>{/* scene 2 */}</Sequence>
+    </AbsoluteFill>
+  );
+};
+```
+
+Animate off `useCurrentFrame()` with `interpolate()` and `spring()` only. **Never read wall-clock time (`Date.now()`) or call `Math.random()` unseeded inside a composition.** *Why: rendering is parallel and frame-addressable — each frame is computed independently, so any non-frame input produces a different pixel on re-render and breaks the "same input, same output" guarantee.* If you need randomness, use Remotion's `random(seed)`.
+
+## Transitions
+
+Use `@remotion/transitions` (available since **v4.0.53**). `<TransitionSeries>` interleaves `.Sequence` (a clip, with `durationInFrames`) and `.Transition` (a `presentation` + a `timing`). The transition duration is *subtracted* from the total, so adjacent sequences overlap during the wipe.
+
+```tsx
+import { TransitionSeries, linearTiming, springTiming } from "@remotion/transitions";
+import { slide } from "@remotion/transitions/slide";
+import { fade } from "@remotion/transitions/fade";
+import { Easing } from "remotion";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={90}>{/* scene A */}</TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={slide({ direction: "from-left" })}
+    timing={springTiming({ config: { damping: 200 }, durationInFrames: 30, durationRestThreshold: 0.001 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={120}>{/* scene B */}</TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15, easing: Easing.inOut(Easing.ease) })}
+  />
+  <TransitionSeries.Sequence durationInFrames={90}>{/* scene C */}</TransitionSeries.Sequence>
+</TransitionSeries>
+```
+
+Each presentation is a sub-import (`@remotion/transitions/slide`, `/fade`, `/wipe`, `/flip`, `/clockWipe`, `/none`).
+
+| Presentation | Feel / when |
+|---|---|
+| `slide` | Scene pushes the next in; directional momentum between beats |
+| `fade` | Soft crossfade; calm, neutral scene change |
+| `wipe` | A hard edge sweeps across; energetic, "next topic" |
+| `flip` | 3D card flip; playful, for reveals |
+| `clockWipe` | Radial sweep; countdowns, "time passing" |
+| `none` | A hard cut with no motion, but still as a TransitionSeries node |
+
+**`linearTiming` for predictable, frame-exact cuts; `springTiming` for organic motion.** *Why: linear is deterministic in duration so you can budget frames exactly; spring overshoots and settles, which reads as natural but needs `durationRestThreshold` so the render knows when it has finished.*
+
+## Animated burned-in captions
+
+The native `@remotion/captions` package shipped in **v4.0.216** (the same release that deprecated the old `convertToCaptions()` helper). The pipeline runs once on a Node server, then the composition reads the captions:
+
+1. **Transcribe.** `@remotion/install-whisper-cpp` downloads Whisper.cpp and a model (`medium.en` is ~1.5 GB) and transcribes the audio on a Node server to Whisper JSON.
+2. **Convert.** `toCaptions()` from `@remotion/install-whisper-cpp` turns that JSON into a `Caption[]` with per-token timestamps. *(`convertToCaptions()` is the legacy alias — deprecated as of v4.0.216; use `toCaptions()`.)*
+3. **Segment into pages.** `@remotion/captions` `createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })` groups tokens into "pages" that appear together.
+
+**The `combineTokensWithinMilliseconds` value is the page-size dial.** *Why: a low value (~200ms) keeps each word on its own page → word-by-word pop animation; a high value (~1200ms) packs a phrase per page.* Low ms = TikTok word-by-word energy; high ms = readable phrases. Pick by the format, not by default.
+
+Full Whisper.cpp install, the transcribe server, and the token-highlight caption renderer component (with safe-zone styling) live in `references/captions-pipeline.md` — read it before building the captions layer.
+
+## Automatic silence removal
+
+**The silence pass runs on the source audio/video BEFORE it enters Remotion**, not inside a composition. *Why: Remotion renders frames you give it; trimming dead air is an upstream edit on the asset, and doing it first means every downstream frame number already reflects the tightened timeline.*
+
+Use `auto-editor` (a Python + ffmpeg engine) for a first pass that cuts dead space by audio loudness:
+
+```bash
+auto-editor input.mp4 --margin 0.2s --edit audio:threshold=4% -o tightened.mp4
+```
+
+- `--margin` pads each kept region so cuts do not clip speech.
+- `--edit audio:threshold=4%` sets the loudness floor below which a region is "silence".
+- `--export premiere` emits an EDL/XML instead of a file, to re-import into an NLE.
+
+**pip distribution is stale/discontinued — install via the official binary or `pipx`, not `pip install`.** *Why: the PyPI package lags behind and may not match the documented flags.* When `auto-editor` is unavailable, the low-level fallback is ffmpeg's `silencedetect` / `silenceremove` filters. Both, with the full flag matrix, are in `references/render-and-pipeline.md`.
+
+## B-roll overlays
+
+Stack the overlay above the main video by layering `<OffthreadVideo>` (or `<Img>`) inside an `<AbsoluteFill>`, gated by a `<Sequence from>`:
+
+```tsx
+import { AbsoluteFill, Sequence, OffthreadVideo, staticFile } from "remotion";
+
+const fps = 30;
+const broll = { start: 4.0, duration: 3.0 }; // seconds
+<AbsoluteFill>
+  <OffthreadVideo src={staticFile("main.mp4")} />        {/* base layer */}
+  <Sequence from={Math.round(broll.start * fps)} durationInFrames={Math.round(broll.duration * fps)}>
+    <AbsoluteFill style={{ /* e.g. inset for picture-in-picture */ }}>
+      <OffthreadVideo src={staticFile("broll.mp4")} />    {/* overlay layer */}
+    </AbsoluteFill>
+  </Sequence>
+</AbsoluteFill>
+```
+
+**Convert every timecode to frames with `Math.round(seconds * fps)`, once, at the edge.** *Why: a b-roll cue at 4.0s is frame 120 at 30fps but frame 240 at 60fps — keep seconds in your data and multiply by `fps` from `useVideoConfig()` so changing fps never desyncs overlays.* Use `<OffthreadVideo>` (not the DOM `<video>` or `<Video>`) for frame-accurate decoding during render.
+
+## Render
+
+```bash
+# region test first: 1-2 seconds, validates the pipeline cheaply
+npx remotion render MyVideo out/test.mp4 --frames=0-45
+
+# then the full render
+npx remotion render MyVideo out/video.mp4
+```
+
+Omit the composition id to get an interactive picker. Configure via `@remotion/cli/config` in `remotion.config.ts`, or pass flags on the CLI (flags win):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+Config.setConcurrency(8);
+Config.setCodec("h264");
+```
+
+| Codec | Use | Flag |
+|---|---|---|
+| `h264` | Default for web/YouTube; broad compatibility | (default) |
+| `h265` | Smaller files, same quality; less universal playback | `--codec=h265` |
+| `prores` | Edit-grade master, large files, re-import to an NLE | `--codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png` |
+| `vp8` / `gif` | Web-alpha or looping previews | `--codec=vp8` / `--codec=gif` |
+
+**Always render a 1–2s region (`--frames=0-45`) before the full render.** *Why: a full render of a minutes-long composition costs real time and CPU; a region test surfaces a broken caption layer or missing asset in seconds.* For headless/CI renders, deterministic-output rules, and the codec/quality matrix in full, see `references/render-and-pipeline.md`.
+
+## Anti-patterns
+
+| Bad | Why it breaks | Good |
+|---|---|---|
+| Hardcoding durations in seconds inside JSX | Remotion thinks in frames; seconds desync the moment fps changes | Store seconds in data, `Math.round(seconds * fps)` at the edge |
+| `Date.now()` / unseeded `Math.random()` in a composition | Frames render in parallel and on re-render → non-deterministic pixels | Drive everything off `useCurrentFrame()`; use `random(seed)` |
+| Changing `fps` after writing durations | Every frame-count downstream silently shifts | Pin fps + dimensions on `<Composition>` up front, leave them |
+| Re-downloading the Whisper model every run | The ~1.5 GB `medium.en` download repeats and stalls the pipeline | Download once, cache the model path, reuse it |
+| Committing the 1.5 GB Whisper model to git | Bloats the repo; the model is a build asset | `.gitignore` the model dir; fetch it in setup/CI |
+| Rendering the full video to test a change | Minutes of wasted render to find a broken layer | `--frames=0-45` region test, then full render |
+| Writing the caption *copy* or hook here | That is the script, not the encode | Route to `../video-shorts/SKILL.md`; you only burn it in |
+| Plain `<video>` / `<Video>` for b-roll in a render | Not frame-accurate; tears or skips on render | `<OffthreadVideo>` for frame-exact decode |
+| Running silence removal inside the composition | Trimming dead air is an upstream asset edit | `auto-editor` on the source file before Remotion |
+
+## Verify & references
+
+- `bash scripts/verify.sh <project-dir>` — checks the Remotion project is well-formed and renders. With Node + ffmpeg present it runs `npx remotion compositions` to confirm a composition id exists, does a short region render to a temp MP4, and uses `ffprobe` to confirm a video stream with the expected dimensions/fps. With neither, it falls back to a static check: at least one composition `.tsx` exists and the render script references a real composition id and an output path. Read-only by default; exits 0 on an empty/clean target.
+- `references/captions-pipeline.md` — full Whisper.cpp install + transcribe server, `toCaptions`, the token-highlight caption renderer component, and caption styling/safe-zone notes.
+- `references/render-and-pipeline.md` — `auto-editor` + ffmpeg silence commands, the full render flag matrix, headless/CI render, the codec table, and `ffprobe` verification.

package/skills/remotion-video/evals/README.md

@@ -0,0 +1,23 @@
+# Evals — remotion-video
+
+`cases.yaml` is a routing-and-capability spec, not an automated test suite. To run it,
+load a model with the skill catalog available and replay each prompt:
+
+- **should_trigger** — each prompt must select `remotion-video`. These cover the core
+  render, the captions pipeline, the upstream silence pass, transitions, CI/headless
+  render, plus Spanish and Catalan phrasings and the non-obvious "remove silences
+  before render" cue.
+- **should_not_trigger** — each prompt must route to the named sibling instead
+  (`video-shorts`, `podcast`, `youtube-thumbnails`, `youtube-packaging`,
+  `course-storytelling`). They probe the frames-vs-words boundary.
+- **capability** — load the skill and have it produce the scenario; grade the output
+  against the `must_include` rubric line by line. A pass means every rubric item is
+  present (pinned fps/dimensions, frames=seconds*fps math, a TransitionSeries with a
+  timing, the toCaptions → createTikTokStyleCaptions pipeline, the silence pass
+  located before Remotion, the b-roll overlay, an explicit render command, the
+  determinism note, and a region test before the full render).
+
+There is no harness script here; judge by reading the model's selection and output
+against the YAML. The runnable artifact check lives in `../scripts/verify.sh`, which
+validates an emitted Remotion project (compositions list + a region render that
+`ffprobe` confirms, with a static fallback when Node/ffmpeg are absent).