@damiangilgonzalez/harness 1.3.7

package/skills/shopify/references/checkout-extensibility.md

@@ -0,0 +1,71 @@
+# Checkout extensibility — migration off `checkout.liquid`
+
+Companion to the Checkout surface section of `../SKILL.md`. The old model (`checkout.liquid`,
+additional scripts, script tags, Script Editor) is deprecated and being removed.
+
+## The dated deadlines
+
+- **2024-08-13** — Information / Shipping / Payment steps stopped supporting `checkout.liquid`.
+- **2025-08-28** — Plus self-migrate deadline for Thank-you and Order-status page customizations
+  (additional scripts, script tags, `checkout.liquid`). This is the date to *act by*, not the
+  auto-upgrade date.
+- **2026-01** — **automatic upgrades** of Thank-you and Order-status pages begin. Shopify gives a
+  30-day email notice, then upgrades the store; any remaining additional-scripts, script-tag, or
+  `checkout.liquid` customizations stop running. (Non-Plus stores have a later self-migrate deadline
+  of 2026-08-26.)
+- **2026-04-15** — legacy Shopify Scripts can no longer be **edited or published** (existing
+  published scripts keep running until the shutdown below — so a bug after this date has no in-Script fix).
+- **2026-06-30** — legacy Shopify Scripts (Script Editor) **stop executing**. Replace with Functions.
+
+If a store says "checkout customizations broke after the August upgrade," they usually mean the
+2025-08-28 deadline passed and they were caught by the automatic upgrade (rolling out from 2026-01) —
+the old script no longer runs. Rebuild it on the seam below.
+
+## Migration map
+
+| Old mechanism | New seam | What you build |
+|---|---|---|
+| `checkout.liquid` markup / additional scripts (UI) | **Checkout UI extensions** | a sandboxed extension targeting a checkout location |
+| Script Editor discount logic | **Discount Function** | Wasm function returning discount operations |
+| Script Editor shipping/delivery logic | **Delivery customization Function** | reorder/rename/hide shipping options |
+| Script Editor payment logic | **Payment customization Function** | reorder/rename/hide payment methods |
+| `<script>` analytics/tracking in checkout | **Web Pixels** (+ server-side events) | sandboxed pixel; subscribe to standard events |
+| custom checkout CSS / branding | **Checkout Branding API** | GraphQL mutations on the checkout profile |
+
+## Checkout UI extensions
+
+React/JS extensions that render at defined **targets** (e.g. `purchase.checkout.block.render`,
+`purchase.checkout.delivery-address.render-before`). You get a typed API and components — **no DOM
+access**, by design (PCI + stability). Configure target + capabilities in the extension's TOML.
+
+```jsx
+import { reactExtension, Banner } from "@shopify/ui-extensions-react/checkout";
+export default reactExtension("purchase.checkout.block.render", () => <Banner>Free gift over 50</Banner>);
+```
+
+## Functions
+
+Deterministic server-side logic compiled to Wasm — author in Rust or JavaScript. A Function takes a
+typed input (a GraphQL query you define against the function's input schema) and returns operations.
+Categories: product discount, order discount, shipping discount, delivery customization, payment
+customization, cart/checkout validation. Generate with `shopify app generate extension`, build, and
+ship with `shopify app deploy`.
+
+```rust
+#[shopify_function]
+fn run(input: input::ResponseData) -> Result<output::FunctionRunResult> {
+    // return discount operations from typed input
+}
+```
+
+## Web Pixels
+
+For tracking/analytics that previously lived in checkout `<script>` tags. A pixel runs in a sandbox
+and subscribes to standard customer events (`checkout_completed`, `product_viewed`, …). It cannot
+reach the page DOM; send events to your endpoint or a destination.
+
+## Plus-only surfaces
+
+Full checkout UI customization and some Function/branding capabilities are **Shopify Plus-only**.
+Non-Plus stores get a constrained set of UI extension targets. Confirm the merchant's plan before
+promising a checkout customization.

package/skills/shopify/references/liquid-themes.md

@@ -0,0 +1,89 @@
+# Liquid & Online Store 2.0 themes — deep dive
+
+Companion to the Theme surface section of `../SKILL.md`. Everything here is OS 2.0 (GA 2021).
+
+## The architecture, end to end
+
+A storefront page is assembled top-down:
+
+1. `layout/theme.liquid` — the HTML shell. Renders `{{ content_for_header }}` and
+   `{{ content_for_layout }}`. One per theme (plus optional `checkout` layout on Plus).
+2. A **JSON template** (`templates/product.json`, `templates/index.json`, …) declares which
+   sections render and their order — not Liquid, pure JSON the theme editor mutates.
+3. Each **section** (`sections/*.liquid`) is markup + a `{% schema %}` of settings and blocks.
+4. **Section groups** (`sections/header.json`, `sections/footer.json`) make header/footer
+   editable as section lists.
+5. **Snippets** (`snippets/*.liquid`) are partials, always via `{% render %}`.
+
+```json
+// templates/product.json
+{
+  "sections": {
+    "main": { "type": "main-product" },
+    "related": { "type": "related-products", "settings": { "heading": "You may also like" } }
+  },
+  "order": ["main", "related"]
+}
+```
+
+## `{% schema %}` setting types & presets
+
+The schema is JSON inside the `.liquid` file. Common setting types: `text`, `textarea`,
+`richtext`, `image_picker`, `url`, `product`, `collection`, `product_list`, `color`, `range`,
+`select`, `checkbox`, `font_picker`, `metaobject`/`metaobject_list`.
+
+```liquid
+{% schema %}
+{
+  "name": "Featured collection",
+  "tag": "section",
+  "settings": [
+    { "type": "collection", "id": "collection", "label": "Collection" },
+    { "type": "range", "id": "limit", "min": 2, "max": 12, "step": 1, "default": 8, "label": "Products" }
+  ],
+  "blocks": [
+    { "type": "text", "name": "Text", "settings": [{ "type": "richtext", "id": "body", "label": "Body" }] },
+    { "type": "@app" }
+  ],
+  "presets": [{ "name": "Featured collection", "blocks": [{ "type": "text" }] }]
+}
+{% endschema %}
+```
+
+- `presets` is what makes the section show up in "Add section" in the editor. No preset → the
+  section exists but a merchant can't add it.
+- `blocks` with `{ "type": "@app" }` accepts app-provided blocks (theme app extensions).
+- Iterate blocks in render order: `{% for block in section.blocks %}{% render block.type, block: block %}{% endfor %}`
+  and emit `{{ block.shopify_attributes }}` on the block's root element so the editor can target it.
+
+## Theme blocks (OS 2.0 reusable blocks)
+
+`blocks/*.liquid` define reusable, nestable blocks usable across sections — distinct from a
+section's inline `blocks`. They have their own `{% schema %}` and can accept child blocks via
+`"blocks": [{ "type": "@theme" }]`. Use them to avoid copy-pasting block markup between sections.
+
+## Dynamic sources, metafields & metaobjects
+
+Bind structured content instead of hardcoding. A setting can carry a **dynamic source** so a
+merchant connects it to a metafield in the editor. Read metafields in Liquid:
+
+```liquid
+{{ product.metafields.custom.care_instructions | metafield_tag }}
+{% assign spec = product.metafields.custom.spec.value %}  {# metaobject reference #}
+```
+
+Prefer this over an `if product.type == ...` ladder: the branch becomes a metafield lookup, so
+new product types need data, not a theme deploy.
+
+## Storefront performance
+
+- Responsive images: `{{ image | image_url: width: 800 | image_tag: loading: 'lazy', sizes: '...', widths: '300,600,800,1200' }}`.
+- `loading="eager"` + a `<link rel="preload">` only for the LCP hero image; lazy-load the rest.
+- Defer non-critical media and scripts; avoid render-blocking app embeds.
+- Always `limit:` collection/loop output; unbounded loops dominate render time.
+
+## Theme Check
+
+`shopify theme check` (config: `.theme-check.yml`) flags deprecated `include`, unused
+assigns, missing `{{ block.shopify_attributes }}`, untranslated strings, and parser errors. Run
+it locally and in CI. `theme dev` gives hot reload as the inner loop.

package/skills/shopify/scripts/verify.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# verify.sh — advisory quality scan for a Shopify theme or app directory.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]
+#
+# Read-only by default. Greps a theme/app dir for high-signal Shopify foot-guns and prints
+# WARN / FAIL advisories. WARN = a smell to review; FAIL = a deprecated/removed mechanism that
+# will break. Exits non-zero only when a FAIL-level issue is found in a real Shopify dir.
+# On an empty or non-Shopify target it SKIPs and exits 0 (no false failure).
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, find-based globbing.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+warn() { printf '%sWARN%s %s\n' "$YELLOW" "$RESET" "$*"; }
+ok()   { printf '%s%s%s\n' "$GREEN" "$*" "$RESET"; }
+fail() { printf '%sFAIL%s %s\n' "$RED" "$RESET" "$*"; }
+
+WARNS=0; FAILS=0
+
+# A Shopify dir has either theme structure (sections/ or templates/*.json or *.liquid) or an
+# app/theme config TOML. Neither → nothing to verify, SKIP (exit 0).
+shopify_present() {
+  if [ -f "$TARGET/shopify.app.toml" ] || [ -f "$TARGET/shopify.theme.toml" ]; then return 0; fi
+  if [ -n "$(find "$TARGET" -type f -name '*.liquid' -print -quit 2>/dev/null)" ]; then return 0; fi
+  if [ -d "$TARGET/sections" ] || [ -d "$TARGET/extensions" ]; then return 0; fi
+  return 1
+}
+
+if ! shopify_present; then
+  warn "no Shopify theme/app found under '${TARGET}' (no *.liquid, no shopify.*.toml, no sections/ or extensions/)"
+  ok "verify.sh: ok (nothing to verify)"
+  exit 0
+fi
+
+# grep_count <pattern> <find-name-filter...> — count matching lines across files, 0 if none.
+# Uses find + grep so it stays bash-3.2 / BSD-grep safe and never errors on no match.
+scan() { # scan <label> <level:warn|fail> <regex> <file-glob>
+  local label="$1" level="$2" regex="$3" glob="$4"
+  local hits
+  hits=$(find "$TARGET" -type f -name "$glob" -print0 2>/dev/null \
+    | xargs -0 grep -nE "$regex" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    if [ "$level" = "fail" ]; then
+      fail "$label"; FAILS=$((FAILS + 1))
+    else
+      warn "$label"; WARNS=$((WARNS + 1))
+    fi
+    printf '%s\n' "$hits" | sed 's/^/    /' | head -10
+  fi
+}
+
+# 1. Deprecated {% include %} in Liquid (prefer {% render %}).
+scan "deprecated {% include %} — use {% render %} (scoped, cacheable)" warn \
+  '\{%-?[[:space:]]*include[[:space:]]' '*.liquid'
+
+# 2. Raw money output without a | money filter (heuristic: .price echoed without 'money').
+scan "price output without | money — renders raw cents/locale wrong" warn \
+  '\{\{[^}]*\.price[^}|]*\}\}' '*.liquid'
+
+# 3. checkout.liquid present — deprecated; automatic upgrades roll out starting 2026-01.
+if find "$TARGET" -type f -name 'checkout.liquid' -print -quit 2>/dev/null | grep -q . ; then
+  fail "checkout.liquid present — deprecated/removed; migrate to checkout extensibility"
+  FAILS=$((FAILS + 1))
+fi
+
+# 4. ScriptTag / additional-script usage — deprecated checkout/tracking mechanism.
+scan "ScriptTag / additional-scripts usage — deprecated; use Web Pixels / UI extensions" warn \
+  'ScriptTag|additional_scripts|additional scripts' '*'
+
+# 5. REST Admin API calls in app source — legacy; prefer GraphQL.
+scan "REST Admin API call (/admin/api/.../.json) — legacy; use admin.graphql()" warn \
+  '/admin/api/[0-9]{4}-[0-9]{2}/[^"'"'"' ]+\.json' '*'
+
+# 6. apiVersion pinned and within the supported window (2025-10 .. 2026-04 at time of writing;
+#    2025-07 is sunsetting ~2026-07-16, so flag it). Unpinned or an older literal → warn.
+APIV=$(find "$TARGET" -type f \( -name '*.js' -o -name '*.ts' -o -name '*.toml' \) -print0 2>/dev/null \
+  | xargs -0 grep -hoE 'apiVersion[^0-9]*(2[0-9]{3}-[0-9]{2})' 2>/dev/null \
+  | grep -oE '2[0-9]{3}-[0-9]{2}' | head -1 || true)
+if [ -f "$TARGET/shopify.app.toml" ] || find "$TARGET" -type f -name '*.server.*' -print -quit 2>/dev/null | grep -q .; then
+  if [ -z "$APIV" ]; then
+    warn "no pinned apiVersion found in app config/server — pin a supported version (e.g. 2026-04)"
+    WARNS=$((WARNS + 1))
+  else
+    case "$APIV" in
+      2026-04|2026-01|2025-10) : ;;
+      2025-07) warn "apiVersion '2025-07' is sunsetting (accessible only until 2026-07-16) — bump to a current version"; WARNS=$((WARNS + 1)) ;;
+      *) warn "apiVersion '$APIV' is outside the supported window (2025-10..2026-04) — bump it"; WARNS=$((WARNS + 1)) ;;
+    esac
+  fi
+fi
+
+# 7. Run Theme Check if a config and the CLI are both present (still read-only).
+if [ -f "$TARGET/.theme-check.yml" ] || [ -f "$TARGET/.theme-check.yaml" ]; then
+  if command -v shopify >/dev/null 2>&1; then
+    printf '==> shopify theme check\n'
+    if ! shopify theme check "$TARGET"; then
+      warn "theme check reported issues"; WARNS=$((WARNS + 1))
+    fi
+  else
+    warn ".theme-check.yml present but shopify CLI not installed — skipping theme check"
+  fi
+fi
+
+printf '\n%d warn, %d fail\n' "$WARNS" "$FAILS"
+if [ "$FAILS" -gt 0 ]; then
+  fail "verify.sh: deprecated/removed mechanisms detected"
+  exit 1
+fi
+ok "verify.sh: ok"
+exit 0

package/skills/shortform-editing/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: shortform-editing
+description: "Use when you have raw 9:16 footage and need it cut into a post-ready vertical short — dead air removed, fast jump cuts, karaoke word-by-word burned-in captions from a transcript, cuts and zooms snapped to the music beat, safe-area placement so captions clear the platform UI, and a platform-correct MP4 export. NOT writing the script, hook, beats or caption text (that is `video-shorts`), NOT building a Remotion React composition codebase (that is `remotion-video`), NOT deciding when or where to post (that is `social-publisher`)."
+tags: [video-editing, shortform, captions, ffmpeg, whisper, beat-sync, vertical-video]
+recommends: [video-shorts, remotion-video, shortform-packaging, social-publisher, podcast]
+origin: risco
+---
+
+# Shortform Editing — Cut the Footage Into a Posted-Ready Short
+
+*You are the edit-bay technician.* Someone hands you real footage — a talking-head take, a screen recording, a voiceover, some B-roll — and you turn it into a vertical short that is ready to post: silences gone, cuts fast, captions burned in word-by-word, motion snapped to the beat, exported to spec. You encode pixels and timing. You do not write the words or pick the hook.
+
+The rigor is a **checkable file**: a `1080x1920` H.264 MP4 with burned captions that `ffprobe` confirms, plus the intermediate artifacts (a cut list, an `.ass`/`.srt`, a beat grid). If you cannot `ffprobe` the result and see the specs, you are not done.
+
+## Scope: three skills touch "a vertical video" — know your lane
+
+| The ask | Goes to | Artifact |
+|---|---|---|
+| Write the script, hook, beats, on-screen caption *text*, edit decision sheet | `../video-shorts/SKILL.md` | a `.md` script |
+| Cut/caption/export real footage, tool-agnostic | **here** | edited `.mp4` + caption/cut files |
+| Build a Remotion React composition project (`<TransitionSeries>`, headless render) | `../remotion-video/SKILL.md` | a `.tsx` project |
+
+One-line router: **footage in → cut, captioned, exported → this skill.** Words or a plan → `video-shorts`. A React codebase → `remotion-video`. You are the only one of the three that is tool-portable.
+
+## Pick your route first
+
+Do not start cutting before you have chosen the tool. The choice is about who runs it and whether it must reproduce.
+
+| Situation | Route | Why |
+|---|---|---|
+| Reproducible / batch / CI / "do this to 40 clips" | **ffmpeg + WhisperX** | scriptable, deterministic, no GUI — same input, same output |
+| The repo is already a Remotion project | **`@remotion/captions`** | reuse the existing composition graph; don't shell out |
+| A human is polishing one video by hand | **CapCut click-path** | fastest for a single hands-on pass with auto-captions + auto beat markers |
+
+The rest of this skill is the **ffmpeg + WhisperX pipeline** (the reproducible path), with the Remotion and CapCut routes called out where they diverge. Long command blocks live in `references/ffmpeg-pipeline.md`; the caption detail lives in `references/captions.md`.
+
+## The reproducible pipeline, in order
+
+This is the spine. Run it top to bottom; each step feeds the next.
+
+**1. Extract a clean mono 16 kHz audio track for transcription.**
+
+```bash
+ffmpeg -i in.mp4 -vn -ac 1 -ar 16000 a.wav
+```
+
+*Why mono 16 kHz: that is what Whisper models expect; feeding stereo 48 kHz wastes time and changes nothing about accuracy.*
+
+**2. Transcribe with word-level timestamps.** Segment timestamps are not enough — word-by-word captions need per-word timing.
+
+```bash
+whisperx a.wav --model large-v3 --output_format json --highlight_words True
+```
+
+WhisperX (v3.8.5) runs faster-whisper plus wav2vec2 forced alignment, giving word timing accurate to **under 100 ms** — the floor for karaoke highlight. faster-whisper alone with `word_timestamps=True` works (~10% overhead) but drifts more on word boundaries. *Why forced alignment: Whisper's native word stamps are interpolated and jitter; forced alignment pins each word to the audio.* See `references/captions.md` for the install and the JSON shape.
+
+**3. Detect silence, then cut video AND audio together.** This is the step people get wrong.
+
+```bash
+# Pass 1: find the silent ranges (speech threshold)
+ffmpeg -i in.mp4 -af silencedetect=noise=-25dB:d=0.3 -f null - 2> silence.log
+```
+
+`silenceremove` alone is an **audio-only filter and desyncs the video** — never use it as a one-shot. Parse the `silence_start` / `silence_end` lines from `silence.log`, invert them into keep-ranges, and build a `select` + `aselect` filter (or a trim+concat graph) that drops the same ranges from both streams. Thresholds: speech `noise=-25dB:d=0.3`; music beds `noise=-40dB:d=1`. The filter-generation snippet is in `references/ffmpeg-pipeline.md`.
+
+**4. Build the beat grid** (only if you are cutting to music).
+
+```bash
+python -c "import librosa; y,sr=librosa.load('music.wav'); \
+_,b=librosa.beat.beat_track(y=y,sr=sr,units='time'); print(*b,sep='\n')" > beats.txt
+```
+
+`beats.txt` is a list of beat times in seconds. CapCut drops these markers on the waveform automatically; librosa (or aubio) gives you the same grid in a script.
+
+**5. Snap cut points and zoom keyframes to the nearest beat.** Round each cut time to its closest value in `beats.txt`. A zoom-punch on the beat reads as energy; see Beat sync below for when NOT to.
+
+**6. Burn the karaoke `.ass` captions.**
+
+```bash
+ffmpeg -i tightened.mp4 -vf "ass=captions.ass" -c:a copy captioned.mp4
+```
+
+The `.ass` carries the per-word `\k` timing built from step 2's word timestamps and the safe-zone margins. Generation detail and the template are in Karaoke captions below.
+
+**7. Export the platform master** (see Export specs).
+
+## Karaoke captions
+
+Word-by-word captions are the signature look. Build them from the word timestamps, not from segment timestamps.
+
+- **Timing.** Each word's on-screen highlight comes from its forced-alignment start/end. In `.ass`, the `\k<centiseconds>` tag advances the karaoke fill per word. Word-by-word from *segment* timing jitters and lands the highlight on the wrong word — always use the per-word stamps from step 2.
+- **Legibility for sound-off.** Big bold sans, heavy outline/stroke, optional drop shadow. People watch muted: if it is not readable at a glance on a phone, it failed. Keep it to **≤ 2 lines / ~6 words** on screen at once.
+- **Safe zone — the non-obvious one.** Place captions in the **vertical middle band**, not the bottom. Platform UI (right-rail icons, bottom caption/CTA/profile) covers the bottom ~15–20% and the right edge. Keep captions and key text inside the central ~80% of the `1080x1920` frame. Captions burned at the bottom get hidden behind the TikTok buttons — this is the #1 "my captions are broken" cause.
+
+Minimal `.ass` style block (full template in `references/captions.md`):
+
+```text
+[V4+ Styles]
+Style: Karaoke,Montserrat,64,&H00FFFFFF,&H0000FFFF,&H00000000,&H64000000,-1,0,0,0,100,100,0,0,1,5,2,5,80,80,640,1
+```
+
+`MarginV` (the trailing `640`) lifts the line into the middle band; the heavy `Outline` (`5`) keeps it readable on any background.
+
+**Remotion route:** if you are inside a Remotion project, use `@remotion/captions` — `createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })` pages the tokens. Low (200–500 ms) = word-by-word pop; high (1200–2000 ms) = phrase pages. Page `durationMs` was added in v4.0.261. **CapCut route:** Text → Auto captions → Generate, then restyle.
+
+## Beat sync
+
+A beat grid (step 4) is a list of seconds. Snap your cut points and zoom keyframes to the nearest beat so motion lands on the music.
+
+- **Bad → Good.** Cutting mid-word to land a cut exactly on a beat reads as a mistake → nudge the cut to the nearest beat that also respects the speech boundary. Honor the words first, the beat second.
+- **When NOT to beat-cut.** A talking-head explainer where the words carry the value: clarity beats rhythm. Beat-cutting a person mid-sentence chops their delivery. Reserve beat sync for B-roll montages, transitions, and music-led segments.
+- **Transitions stay cheap and fast.** Hard cut is the default. Whip-pan or zoom-punch only on a beat. Avoid 1-second crossfades in a 30-second short — they kill the pace; a short lives on fast hard cuts.
+
+## Export specs
+
+The universal vertical master — one file that plays cleanly across all three platforms:
+
+```bash
+ffmpeg -i captioned.mp4 \
+  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2,setsar=1" \
+  -c:v libx264 -profile:v high -pix_fmt yuv420p -r 30 \
+  -c:a aac -b:a 192k -ar 48000 -ac 2 \
+  -movflags +faststart out.mp4
+```
+
+`yuv420p` (broad playback), `+faststart` (web streaming starts before full download), AAC-LC 48 kHz. Use 30 fps; bump to **60 fps for high-motion** Shorts.
+
+| Platform | Video bitrate | Notes |
+|---|---|---|
+| TikTok | ~2,000–4,000 kbps | lightest of the three |
+| Instagram Reels | ~3,500–4,500 kbps | |
+| YouTube Shorts (1080p) | ~8,000–15,000 kbps | up to ~53,000 for 4K/60 |
+
+A single `1080x1920` H.264 MP4 @30 fps under **~250 MB** is safe everywhere. Verify before you ship:
+
+```bash
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,codec_name,avg_frame_rate out.mp4
+```
+
+Expect `width=1080 height=1920 codec_name=h264`. The full per-platform encode flags and `ffprobe` assertions are in `references/ffmpeg-pipeline.md`.
+
+## Anti-patterns
+
+| Bad | Why it breaks | Good |
+|---|---|---|
+| `silenceremove` as a one-shot filter | It is audio-only; the video keeps playing → audio/video desync | `silencedetect` → invert ranges → `select`+`aselect` cut both streams |
+| Word captions from segment timestamps | Highlight jitters and lands on the wrong word | Forced-alignment per-word stamps (WhisperX / `word_timestamps`) |
+| Captions burned in the bottom 15–20% | Platform UI (buttons, CTA, profile) covers them | Place in the vertical middle band, central ~80% |
+| One export reused for every platform | Over/under the bitrate target somewhere | Per-platform bitrate, or the safe universal master |
+| 1-second crossfades in a 30s short | Kills the pace; reads slow | Hard cuts; whip/zoom only on a beat |
+| Beat-cutting a talking-head mid-sentence | Chops the delivery; clarity lost | Beat-sync B-roll/montage only; honor speech boundaries |
+| Re-running the encode to "check the specs" | Wastes minutes; the file already exists | `ffprobe` the output; verify, don't re-render |
+| Writing the caption copy or the hook here | That is the script, not the cut | Route to `../video-shorts/SKILL.md`; you only burn it in |
+| `ffmpeg` overwriting the source in place | One bad flag and the original is gone | Always write to a new file; keep `in.mp4` untouched |
+
+## Verify & references
+
+- `bash scripts/verify.sh <output.mp4>` — runs `ffprobe` and asserts `width=1080`, `height=1920` (9:16), video codec `h264`, audio codec `aac`, fps in `{30, 60}`, and that a sibling `.srt`/`.ass` caption file exists and is non-empty. With no `ffprobe` it falls back to a path/extension check. Read-only; exits 0 on an empty/clean target so it never false-fails. The "does it feel on-beat" judgment is not mechanical — that lives in the capability eval.
+- `references/ffmpeg-pipeline.md` — the full silence-detect → keep-range inversion → `select`/`aselect` filter generation that cuts video+audio together, the concat/trim approach, per-platform encode flags, `ffprobe` assertions, and desync/audio-drift/faststart troubleshooting.
+- `references/captions.md` — WhisperX install + run, the word-timestamp JSON shape, the full `.ass` karaoke template with safe-zone margins, the Remotion `createTikTokStyleCaptions()` snippet with `combineTokensWithinMilliseconds` guidance, and the faster-whisper vs WhisperX tradeoff.

package/skills/shortform-editing/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — shortform-editing
+
+These are routing + capability checks for a human or an LLM judge, not a renderer
+test — nothing here encodes a video. To run them, read `cases.yaml` and confirm the
+skill's `description` would fire on every `should_trigger` prompt (including the
+non-obvious "captions out of sync and hidden behind the TikTok buttons" symptom and
+the Spanish/Catalan phrasings) and that each `should_not_trigger` prompt routes to
+the named sibling instead (`video-shorts`, `remotion-video`, `social-publisher`,
+`youtube-thumbnails`, `podcast`) rather than here. For the `capability` scenario,
+have the skill produce the pipeline/commands and grade them line by line against the
+`must_include` rubric: word-level transcription, a two-pass silence cut that removes
+video AND audio together, a beat grid with cuts snapped to it, karaoke `.ass`
+captions in the safe middle band, a 1080x1920 H.264/AAC export, and `ffprobe`
+verification. The "does it feel on-beat" judgment is subjective and stays in this
+rubric. To mechanically check a produced output, point `scripts/verify.sh` at the
+emitted `.mp4`.

package/skills/shortform-editing/evals/cases.yaml

@@ -0,0 +1,61 @@
+skill: shortform-editing
+
+# This skill is the edit-bay technician: it CUTS real footage into a posted-ready
+# vertical short — silence removal, karaoke burned captions from word timestamps,
+# beat-synced cuts, platform-correct export. It does NOT write the script/hook
+# (video-shorts), build a Remotion codebase (remotion-video), schedule posts
+# (social-publisher), make thumbnails (youtube-thumbnails), or master podcast audio
+# (podcast).
+
+should_trigger:
+  - prompt: "Remove the dead air and silences from this talking-head clip automatically."
+    why: "Core silence-removal job — the skill's two-pass silencedetect → cut-both-streams move."
+
+  - prompt: "Burn TikTok-style word-by-word captions onto this short from my Whisper transcript."
+    why: "Core caption job — karaoke .ass from word-level timestamps."
+
+  - prompt: "Cut this footage to the beat of the song so the cuts land on the drops."
+    why: "Beat sync — build a beat grid and snap cut points to it."
+
+  - prompt: "Export this Reel with the right TikTok and Shorts specs."
+    why: "Export job — 1080x1920 H.264 master plus per-platform bitrate."
+
+  - prompt: "My burned-in captions are out of sync and getting hidden behind the TikTok buttons — fix the timing and placement."
+    why: "Non-obvious — the user names a symptom, not the skill; the fix is word-timestamp re-timing plus moving captions out of the bottom UI safe zone, both signature moves."
+
+  - prompt: "Quítale los silencios a este vídeo y ponle subtítulos quemados estilo TikTok."
+    why: "Spanish for 'remove the silences and add burned TikTok-style captions' — language coverage plus the two core jobs."
+
+  - prompt: "Munta'm aquest clip vertical amb talls ràpids sincronitzats amb la música."
+    why: "Catalan for 'edit this vertical clip with fast cuts synced to the music' — language coverage plus beat-synced cutting."
+
+should_not_trigger:
+  - prompt: "Write me a 30-second hook and script for a Reel about cold brew."
+    route_to: video-shorts
+    why: "Words and a plan, no footage — the script/hook is authored, not cut."
+
+  - prompt: "Build a Remotion React project with a TransitionSeries and composition code I can render in CI."
+    route_to: remotion-video
+    why: "A React composition codebase, not a one-off cut on real footage."
+
+  - prompt: "When and where should I post this short across platforms?"
+    route_to: social-publisher
+    why: "Distribution and cadence, not the cut/encode."
+
+  - prompt: "Make me a thumbnail / cover frame for this short."
+    route_to: youtube-thumbnails
+    why: "A still packaging visual, not video editing."
+
+  - prompt: "Master and chapter my podcast episode audio for the RSS feed."
+    route_to: podcast
+    why: "Long-form audio mastering and feed work, not a vertical video cut."
+
+capability:
+  - scenario: "Given a raw 9:16 talking-head clip plus a music track, produce an edited, posted-ready vertical MP4 with karaoke captions, and verify it."
+    must_include:
+      - "Word-level transcription via WhisperX (or faster-whisper word_timestamps), not segment-only timestamps"
+      - "Two-pass silence handling: silencedetect to find ranges, then a select/aselect (or trim+concat) filter that cuts video AND audio together — NOT silenceremove alone"
+      - "A beat grid (librosa/aubio/CapCut markers) with cut points snapped to the nearest beat, and the note that talking-head clarity can outrank rhythm"
+      - "Karaoke .ass captions with per-word \\k timing from the word timestamps, placed in the vertical middle band / central ~80% (not the bottom 15-20% UI zone)"
+      - "Export to 1080x1920 H.264 (yuv420p, +faststart) at 30 or 60 fps with AAC 48 kHz audio, per-platform bitrate or the safe universal master"
+      - "ffprobe verification of resolution, codecs, and frame rate on the output file"

package/skills/shortform-editing/references/captions.md

@@ -0,0 +1,85 @@
+# Captions — word timestamps, .ass karaoke, Remotion route
+
+## Why word-level timestamps
+
+Karaoke captions highlight one word at a time. That needs each word's start/end, not the segment's. Two sources:
+
+| Tool | Word timing accuracy | Cost | When |
+|---|---|---|---|
+| faster-whisper `word_timestamps=True` | interpolated, drifts on boundaries | ~10% overhead, ~4x faster on GPU / 2x on CPU vs reference Whisper (CTranslate2) | quick, GPU-light, tolerant of small drift |
+| WhisperX v3.8.5 (faster-whisper + wav2vec2 forced alignment) | **< 100 ms** | extra alignment pass | word-by-word highlight where the fill must land on the right word |
+
+For karaoke, prefer WhisperX. Its forced alignment pins each word to the audio instead of interpolating.
+
+## Install + run WhisperX
+
+```bash
+pip install whisperx
+whisperx a.wav --model large-v3 --language en \
+  --output_format json --highlight_words True --output_dir out/
+```
+
+This emits `out/a.json`. Shape (trimmed):
+
+```json
+{
+  "segments": [
+    {
+      "start": 0.31, "end": 2.84, "text": " here is the thing",
+      "words": [
+        { "word": "here", "start": 0.31, "end": 0.52 },
+        { "word": "is",   "start": 0.52, "end": 0.64 },
+        { "word": "the",  "start": 0.64, "end": 0.78 },
+        { "word": "thing","start": 0.78, "end": 1.10 }
+      ]
+    }
+  ]
+}
+```
+
+Each `words[i].start/end` is what drives the `.ass` `\k` timing and the Remotion token pages.
+
+## .ass karaoke template
+
+```text
+[Script Info]
+ScriptType: v4.00+
+PlayResX: 1080
+PlayResY: 1920
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Karaoke,Montserrat,64,&H00FFFFFF,&H0000FFFF,&H00000000,&H64000000,-1,0,0,0,100,100,0,0,1,5,2,5,80,80,640,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+Dialogue: 0,0:00:00.31,0:00:01.10,Karaoke,,0,0,0,,{\k21}here {\k12}is {\k14}the {\k32}thing
+```
+
+- `\k<centiseconds>` per word = `(word.end - word.start) * 100`, rounded. The karaoke fill advances by that many centiseconds.
+- `PrimaryColour` is the highlighted/active fill; `SecondaryColour` is the not-yet-spoken color.
+- `Alignment 5` = centered middle. `MarginV 640` lifts the line off the bottom into the safe middle band.
+- `Outline 5` + `Shadow 2` keep it legible on any background for sound-off viewing.
+
+### Safe-zone math
+
+Frame is `1080x1920`. Reserve the bottom ~15–20% (≈ 290–384 px) for platform UI and the right edge for the icon rail. Keep caption baselines inside the central ~80%: roughly **y from 384 to 1536**. A `MarginV` around `560–720` lands the line in the lower-middle of that band — high enough to clear the buttons, low enough to feel like a caption.
+
+## Remotion route (when the repo is a Remotion project)
+
+```tsx
+import { createTikTokStyleCaptions, type Caption } from "@remotion/captions";
+
+const captions: Caption[] = /* from convertToCaptions(whisperJson) */;
+
+const { pages } = createTikTokStyleCaptions({
+  captions,
+  combineTokensWithinMilliseconds: 350, // low = word-by-word; 1200–2000 = phrase pages
+});
+```
+
+- `combineTokensWithinMilliseconds` is the page-size dial: low (200–500 ms) → one word per page → word-by-word pop; high (1200–2000 ms) → a phrase per page.
+- Per-page `durationMs` is available since v4.0.261.
+- Style the rendered token in the composition, not here; keep it in the same safe middle band (`bottom: ~25%` of a `1080x1920` frame).
+
+Do not build a Remotion project just to caption a one-off clip — that is `../remotion-video/SKILL.md`. Use this route only when the project already exists.