---
name: snappy-video
role: Video/audio processing pipeline -- Whisper transcription, captioning, clip extraction, format conversion. Runs on Mac Mini via SSH.
loaded-by: PreToolUse hook (auto-injected when "snappy-video" is mentioned)
---

# snappy-video -- Agent Loader

You are operating the video and audio post-production pipeline. Everything runs on the Mac Mini via SSH (`robertboulos@Roberts-Mac-mini.local`). The single entry point is `caption-video.sh` which wraps Whisper transcription, SRT/ASS generation, ffmpeg caption burning, and optional auto-clip extraction.

## Rules

1. **Always SSH to the Mac Mini.** Never run ffmpeg/Whisper locally. The venv, models, and ffmpeg build live there.
2. **`cd /Users/robertboulos/robot-rob`** before running `./caption-video.sh`. The script resolves its venv relative to its own directory.
3. **Decide karaoke vs segment captions up front.** `--words` requires Whisper word_timestamps which doubles transcribe cost.
4. **Whisper `small` is default.** Enough for English under 5 min. Use `medium`/`large` only for non-English or noisy audio.
5. **Resize FIRST, then caption.** Captions baked into 16:9 won't survive a 9:16 crop.
6. **Use `nohup` for jobs > 5 min.** SSH disconnect kills foreground jobs.
7. **Never overwrite the source file.** Always write to a new path.
8. **Add `-movflags +faststart`** for any MP4 going to YouTube/Skool/web.
9. **Work in `/tmp/`** on the Mac Mini for ephemeral assets.
10. **Use `-c copy` for fast trims.** Only re-encode for exact frame boundaries.

## Routing table

| Intent | Action |
|---|---|
| Caption a video | `./caption-video.sh /tmp/in.mp4 /tmp/out.mp4 --style bold --words` |
| Word-level karaoke | Add `--words` flag |
| Auto-extract best clips | Add `--clips` flag |
| Known timestamp trim | `ffmpeg -y -ss HH:MM:SS -to HH:MM:SS -i in.mp4 -c copy clip.mp4` |
| Thumbnail at Ns | `ffmpeg -y -ss N -i in.mp4 -frames:v 1 -vf "scale=1280:720:..." thumb.jpg` |
| Resize to 9:16 | `ffmpeg -y -i in.mp4 -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:-1:-1:color=black" -c:a copy vert.mp4` |
| Extract audio | `ffmpeg -y -i in.mp4 -vn -c:a aac -b:a 192k audio.m4a` |
| Compress for web | `ffmpeg -y -i in.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k -movflags +faststart web.mp4` |

## Execution patterns

```bash
# Inline (file on Mac Mini, < 5 min)
ssh robertboulos@Roberts-Mac-mini.local \
  "cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/in.mp4 /tmp/out.mp4 --style bold --words"

# Background (long job)
ssh robertboulos@Roberts-Mac-mini.local \
  "nohup bash -c 'cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/in.mp4 /tmp/out.mp4 --style bold --words' > /tmp/video-job.log 2>&1 &"

# Push, process, pull (file is local)
scp ./video.mp4 robertboulos@Roberts-Mac-mini.local:/tmp/input.mp4
ssh robertboulos@Roberts-Mac-mini.local "cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/input.mp4 /tmp/output.mp4"
scp robertboulos@Roberts-Mac-mini.local:/tmp/output.mp4 ./output.mp4
```

## Pipeline architecture

```
Input -> [1] Whisper transcribe -> [2] SRT + ASS -> [3] ffmpeg burn -> [4] auto-clip (optional)
Output: captioned.mp4 + captions.srt [+ clip1.mp4 clip2.mp4 ...]
```

## Cross-skill flow

| From | What |
|---|---|
| snappy-content | Raw interview/recording footage |
| snappy-ads | Raw ad creative to caption + reformat |
| snappy-desktop | Screen recordings to caption |

| To | What |
|---|---|
| snappy-youtube | Captioned final + thumbnail for upload |
| snappy-post | 9:16 short clips for Reels/Shorts/TikTok |
| snappy-blog | Whisper SRT/transcript as blog raw material |
| snappy-image | Extracted frames as thumbnail candidates |

Orchestrated by snappy-ops on **Thursday -- Video Day**.

## Skill files

| File | Contents |
|---|---|
| SKILL.md | Full reference (pipeline, execution patterns, architecture, workflow) |
| ffmpeg-recipes.md | Every ffmpeg one-liner (trim, burn, resize, audio, compress, voiceover, splits) |
| caption-styles.md | Caption styles, flags, Whisper model trade-offs, ASS color reference |

## API module

```typescript
import { transcribe, caption, clip, resize, extractAudio } from "../snappy-video/api.ts";
```

Or CLI:
```bash
npx tsx ~/.claude/skills/snappy-video/api.ts transcribe /tmp/video.mp4
npx tsx ~/.claude/skills/snappy-video/api.ts caption /tmp/video.mp4
npx tsx ~/.claude/skills/snappy-video/api.ts clip /tmp/video.mp4 00:01:00 30
```

## API functions

| Function | Purpose |
|----------|---------|
| `transcribe(videoPath, model?)` | Whisper transcription via Mac Mini SSH |
| `caption(videoPath, options?)` | Caption a video with style/words/clips options |
| `clip(videoPath, startTime, duration, outputPath?)` | Extract a clip from a video |
| `resize(videoPath, format?, outputPath?)` | Resize video to 9:16 or 16:9 |
| `extractAudio(videoPath, outputPath?)` | Extract audio track as m4a |

---

If this loader doesn't cover your case:
```bash
echo "[$(date -u +%FT%TZ)] snappy-video: <what was missing>" >> ~/.claude/logs/agents-md-feedback.log
```


Show produced work with `snappy-faces`: call `draw` for image channels or `lang` for MCP Apps.

<!-- SKILL-INDEX-START -->
[snappy-video Index]|root: ~/.claude/skills/snappy-video|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md,caption-styles.md,ffmpeg-recipes.md}
<!-- SKILL-INDEX-END -->

## Used by

- `snappy-ads`
- `snappy-ffmpeg`
- `snappy-remotion`
- `snappy-voice-control`

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `caption` | `path` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-video/api.ts caption <path>` |
| `clip` | `path`, `start`, `duration` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-video/api.ts clip <path> <start> <duration>` |
| `transcribe` | `path`, `model?` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-video/api.ts transcribe <path>` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---
name: snappy-video
instruction-only: true
reports_to: build
head: false
description: "Video and audio processing pipeline for Snappy, run on the Mac Mini via SSH (caption-video.sh wrapper around video-pipeline.py): Whisper transcription, SRT and ASS subtitles, word-level karaoke, ffmpeg caption burning, auto-clip detection by speech density, thumbnail extraction, audio extraction (m4a/mp3), 16:9 / 9:16 / 1:1 conversion, screen recording + voiceover merge, web compression. THE DEFAULT for any video or audio task. Use when Robert says: /snappy-video, \"caption this video\", \"burn the subtitles\", \"transcribe this with whisper\", \"clip the best parts\", \"make it vertical for shorts / reels\", \"compress the video for web\", \"extract the audio\", \"video for youtube\", \"video for ads\". Triggers on: video, captions, subtitles, whisper, ffmpeg burn, vertical clip, b-roll, thumbnail. NOT local ffmpeg on this Mac (see snappy-ffmpeg). NOT the Charlotte mac_mini_exec argument table (see video-pipeline). NOT scripting or retention structure (see retention-script)."
---

# Snappy Video

## Purpose

Transcribe, caption, clip, and reformat any video or audio asset on the Mac Mini. The single
entry point is `caption-video.sh`; everything else (Whisper, ffmpeg, ASS karaoke generation,
clip scoring) is composed under it. Runs over SSH so a session disconnect never kills a job.

## When to Use This Skill

Activates whenever the user mentions:

- Captioning, subtitling, transcribing, burning text into a video
- Whisper, SRT, ASS, karaoke, word-level highlights
- Clip extraction, splitting a long recording, "best moments", reels, shorts
- Thumbnail frames, key frames, hero stills from a video
- Format conversion (YouTube 16:9, Reels 9:16, square 1:1), resizing, compressing
- Audio extraction (m4a/mp3) from video
- Screen recordings + voiceover that need a captioned final cut

If the upstream task is content production (interview / blog / post), defer to `snappy-content`
first; this skill is the post-production primitive it calls.

## Quick Start

```bash
# Most common: caption a local video with karaoke word highlights, bold style
ssh robertboulos@Roberts-Mac-mini.local \
  "cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/input.mp4 /tmp/output.mp4 --style bold --words"
```

If you have a remote URL instead of a file:

```bash
ssh robertboulos@Roberts-Mac-mini.local "curl -L -o /tmp/input.mp4 'https://...'"
```

Then run the caption command above. Always work in `/tmp` on the Mac Mini for ephemeral assets.

### Routing Table -- pick the lane before running anything

| User intent | Lane |
|---|---|
| Caption a single video | Caption Pipeline (below) |
| Word-level karaoke captions | `--style bold --words` |
| Slice a long video into best clips | `--clips` flag (auto-detect) |
| Cut a known timestamp range | Manual ffmpeg trim ([ffmpeg-recipes.md](ffmpeg-recipes.md)) |
| Burn an existing SRT/ASS into video | [ffmpeg-recipes.md](ffmpeg-recipes.md) → Subtitle Burning |
| Pull a thumbnail/key frame | [ffmpeg-recipes.md](ffmpeg-recipes.md) → Thumbnails |
| Resize for YouTube/Reels/Square | [ffmpeg-recipes.md](ffmpeg-recipes.md) → Format Conversion |
| Extract audio only | [ffmpeg-recipes.md](ffmpeg-recipes.md) → Audio Extraction |
| Compress for web/Skool upload | [ffmpeg-recipes.md](ffmpeg-recipes.md) → Compression |
| Record on Mac then voiceover | [ffmpeg-recipes.md](ffmpeg-recipes.md) → Screen + Voiceover |
| Style / flag reference | [caption-styles.md](caption-styles.md) |

---

## Caption Pipeline (the wrapper script)

The Mac Mini has `caption-video.sh` which wraps `video-pipeline.py`. It handles Whisper
transcription, SRT generation, ASS karaoke generation, ffmpeg burn, and optional clip
extraction in one call.

```bash
# Simple segment-level captions
./caption-video.sh /tmp/input.mp4

# Specify output path
./caption-video.sh /tmp/input.mp4 /tmp/output.mp4

# Word-level karaoke (ASS) with bold style
./caption-video.sh /tmp/input.mp4 /tmp/output.mp4 --style bold --words

# Caption + auto-extract best clips (yellow highlight style)
./caption-video.sh /tmp/long.mp4 --style highlight --words --clips

# Override Whisper model (default: small)
./caption-video.sh /tmp/input.mp4 --model medium
```

Style names, color/position effects, and every flag are documented in
[caption-styles.md](caption-styles.md). Don't memorize them, retrieve them.

### Audio-only input is auto-detected

Pass an `.mp3` / `.m4a` / `.wav` and the pipeline composites it onto a black background, then
captions it. No manual conversion needed.

```bash
./caption-video.sh /tmp/podcast.mp3 /tmp/podcast-captioned.mp4 --style minimal
```

---

## Workflow

**Inputs (skills that feed this one):**
- `snappy-content` -- provides the recorded raw video/audio that needs post-production
- `snappy-transcripts` -- alternative source of audio (meetings) when re-captioning a recording
- `snappy-ads` -- provides raw ad creative footage to caption + reformat
- `snappy-youtube` -- provides raw long-form footage that needs captions, clips, and a thumbnail
- `snappy-skool` -- provides classroom recordings that need lightweight captions for Skool
- `snappy-desktop` / `snappy-infra` -- provides screen recordings captured on the Mac Mini

**Outputs (skills that consume this one):**
- `snappy-youtube` -- receives captioned final cut + thumbnail JPG for upload
- `snappy-ads` -- receives captioned, resized ad creative (1:1, 9:16, 16:9) for ad upload
- `snappy-post` -- receives short vertical clips (9:16) for Reels/Shorts/TikTok distribution
- `snappy-content` -- receives auto-extracted clips and Whisper SRT to seed repurposing
- `snappy-skool` -- receives compressed captioned classroom clips for Skool
- `snappy-blog` -- receives Whisper SRT/transcript text as raw material for blog drafts
- `snappy-image` -- receives extracted frames as candidates for thumbnail generation/editing

**Channels (where output is delivered):**
- File outputs land on the Mac Mini under `/tmp/`. Pull with `scp` to local, or pass the
  Mac Mini path directly to the consumer skill (most consumers run on the Mac Mini too).
- Final assets meant for permanence are uploaded by the consumer to the DO Spaces CDN via
  `snappy-image`'s `upload_cdn` tool.

**Orchestrator:**
- `snappy-ops` schedules video work on **Thursday -- Video Day** (see
  `snappy-ops/weekly-rhythm.md`). Captioning + clip extraction + thumbnail are the standard
  Thursday morning batch.

---

## Remote Execution (Mac Mini, every time)

All processing runs on the Mac Mini. Three patterns:

| Pattern | When |
|---|---|
| Inline SSH | Quick jobs, < ~5 min |
| `nohup` background | Long jobs, > 5 min, avoid SSH timeout |
| `scp` push then SSH then `scp` pull | Source file lives only on the local Mac |

```bash
# 1. Inline (file already on Mac Mini)
ssh robertboulos@Roberts-Mac-mini.local \
  "cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/in.mp4 /tmp/out.mp4 --style bold --words"

# 2. Background -- fire and forget, tail log later
ssh robertboulos@Roberts-Mac-mini.local \
  "nohup bash -c 'cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/in.mp4 /tmp/out.mp4 --style bold --words' > /tmp/video-job.log 2>&1 &"
ssh robertboulos@Roberts-Mac-mini.local "tail -20 /tmp/video-job.log"

# 3. Push, process, pull (file is local-only)
scp ./video.mp4 robertboulos@Roberts-Mac-mini.local:/tmp/input.mp4
ssh robertboulos@Roberts-Mac-mini.local \
  "cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/input.mp4 /tmp/output.mp4 --style bold --words"
scp robertboulos@Roberts-Mac-mini.local:/tmp/output.mp4 ./output.mp4
```

For arbitrary ffmpeg one-liners on the Mac Mini, see [ffmpeg-recipes.md](ffmpeg-recipes.md).

---

## What AI Agents Get Wrong

These are the recurring failure modes. Read them before running anything destructive.

| Wrong | Right |
|---|---|
| Run ffmpeg/Whisper locally on the laptop | Always SSH to the Mac Mini (`robertboulos@Roberts-Mac-mini.local`) -- that's where the venv, models, and ffmpeg build live |
| `./caption-video.sh input.mp4` from current dir | `cd /Users/robertboulos/robot-rob && ./caption-video.sh ...` -- the script resolves the venv relative to its own directory |
| Forget `--words` then re-run later | Decide karaoke vs segment captions up front; word-level requires Whisper word_timestamps which doubles the transcribe cost |
| Use Whisper `large` for short clips | `small` (default) is enough for English under 5 min. Reserve `medium`/`large` for non-English or noisy audio |
| Use re-encode trim (`-c:v libx264`) when copying timestamps would do | Use `-c copy` for fast cuts; only re-encode if you need exact frame boundaries |
| Hard-cut a vertical from a 16:9 source | Use `scale=...:force_original_aspect_ratio=decrease,pad=...:color=black` so nothing gets cropped |
| Run a 30-min job over an SSH pipe | Use `nohup ... &` and tail the log -- SSH disconnect kills foreground jobs |
| Caption then resize | Resize FIRST, then caption -- captions baked into a 16:9 frame won't survive a 9:16 crop |
| Overwrite the source file (`-y` to same path) | Always write to a new path; keep the original |
| Skip `-movflags +faststart` for web uploads | Add it for any MP4 going to YouTube/Skool/web -- enables progressive playback |

---

## Quick Reference

### Key paths (Mac Mini)

|Component|Path|
|---|---|
|Pipeline script (Python)|`/Users/robertboulos/robot-rob/video-pipeline.py`|
|Shell wrapper|`/Users/robertboulos/robot-rob/caption-video.sh`|
|Python venv|`/Users/robertboulos/robot-rob/venv/` (Python 3.14, whisper, torch)|
|ffmpeg|Homebrew build with drawtext + subtitles + ass filters|
|Default Whisper model|`small` (override with `--model {tiny,base,small,medium,large}`)|
|Working dir for I/O|`/tmp/` on the Mac Mini|
|SSH host|`robertboulos@Roberts-Mac-mini.local`|

### One-liners

```bash
# Trim with no re-encode (fast, keyframe-aligned)
ffmpeg -y -ss 00:01:30 -to 00:02:45 -i in.mp4 -c copy clip.mp4

# Thumbnail at 15s, 1280x720 with letterbox
ffmpeg -y -ss 00:00:15 -i in.mp4 -frames:v 1 \
  -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1:color=black" \
  -q:v 2 thumb.jpg

# Resize to 9:16 vertical (1080x1920)
ffmpeg -y -i in.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:-1:-1:color=black" \
  -c:a copy vertical.mp4

# Extract audio as m4a
ffmpeg -y -i in.mp4 -vn -c:a aac -b:a 192k audio.m4a

# Compress for web
ffmpeg -y -i in.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k -movflags +faststart web.mp4
```

Full recipe library (subtitle burning, karaoke ASS, segment splitting, screen+voiceover,
loudness normalization, frame-accurate cuts) lives in [ffmpeg-recipes.md](ffmpeg-recipes.md).

### Architecture

```
Input video / audio
   │
   ▼
[1] Whisper transcribe        (--model, word_timestamps if --words)
   │
   ▼
[2] SRT + (optional) ASS      (karaoke \kf tags when --words)
   │
   ▼
[3] ffmpeg burn captions      (subtitles= filter for SRT, ass= filter for ASS)
   │
   ▼
[4] Optional auto-clip        (speech-density scoring, --clips flag)
   │
   ▼
captioned.mp4 + captions.srt [+ clip1.mp4 clip2.mp4 ...]
```

---

## Navigation Guide

|Need|File|
|---|---|
|Every ffmpeg one-liner (trim, burn, resize, audio, compress, voiceover, splits)|[ffmpeg-recipes.md](ffmpeg-recipes.md)|
|Caption styles, flags, Whisper model trade-offs, ASS color reference|[caption-styles.md](caption-styles.md)|

---

## Related Skills

|Skill|Why|
|---|---|
|`snappy-content`|Owns the upstream interview/script; calls this skill on Thursday for clip + caption|
|`snappy-youtube`|Consumes the captioned final + thumbnail; uploads to YouTube|
|`snappy-ads`|Consumes the captioned, resized ad creative; uploads to Meta/YouTube ads|
|`snappy-post`|Consumes 9:16 short clips for Reels/Shorts/TikTok scheduling|
|`snappy-blog`|Consumes the Whisper SRT/transcript as raw material for blog drafts|
|`snappy-skool`|Consumes compressed Skool-friendly classroom clips|
|`snappy-image`|Sister skill -- generates the final thumbnail image; this skill extracts the candidate frame|
|`snappy-transcripts`|Alternative transcript source (meeting recordings) when re-captioning meetings|
|`snappy-infra`|Owns the Mac Mini SSH primitives this skill rides on|
|`snappy-desktop`|Captures source screen recordings that this skill then captions|
|`snappy-ops`|Schedules Thursday Video Day batch runs|

---

**Skill Status**: COMPLETE

## Near neighbours

Skills whose description overlaps this one enough that a reader could pick the
wrong door. Each row is that skill's own first sentence about itself, so the
choice is made on its words, not on a summary written here.

| Skill | Reach for it instead when |
|---|---|
| `snappy-analytics` | Centralized analytics and metrics for the entire Snappy operating system. |
| `snappy-artifact-loop` | Build published Artifacts as I/O devices where the AGENT is the backend, not as static output… |
| `snappy-ax` | Drive any Mac app through the Accessibility tree (AXUIElement) the way the shipping tools act… |
| `snappy-browse` | THE DEFAULT for actually driving a browser on this machine -- Snappy stack and client sites v… |
| `snappy-cleanshot` | CleanShot X local capture primitive. |
| `snappy-corpus` | The Krisp transcript corpus + nugget mining pipeline: import calls into the corpus, find quot… |
| `snappy-docs` | THE DEFAULT for writing to Notion -- the Snappy stack's Notion primitive over the REST API (a… |
| `snappy-gemini` | Single canonical interface to Google's Gemini family for the Snappy system. |
| `snappy-jcode` | Dispatch GPT 5.6 (Luna/Sol) agents as sandboxed lane workers via the local jcode CLI, on this… |
| `snappy-nightshift` | The overnight orchestration operating system: one orchestrator drives a repo toward 100% all… |
| `snappy-os-operator` | Operate SnappyOS like a pro through product doors only: governed connector reads, staged writ… |
| `snappy-resident` | The non-stop user seat: drive the Snappy OS app as a real user through a real browser (agent-… |
| `snappy-telegram` | Telegram Bot API channel for Snappy: direct calls to api.telegram.org (no Xano middleware) to… |
| `snappy-voice-control` | Voice control on macOS, extracted from two shipping open-source agents (fazm by mediar-ai; Ag… |
| `snappy-xano-mcp` | THE EXISTING, DEPLOYED Snappy MCP server: the Cloudflare Worker exposing the Snappy Xano API… |

#!/usr/bin/env npx tsx
/**
 * snappy-video/api.ts -- Video processing pipeline via Mac Mini SSH.
 *
 * All heavy processing (Whisper, ffmpeg, caption-video.sh) runs on the Mac Mini.
 * This module wraps SSH commands.
 *
 * Usage:
 *   npx tsx api.ts transcribe <path>
 *   npx tsx api.ts caption <path>
 *   npx tsx api.ts clip <path> <start> <duration>
 *
 * Or import as module:
 *   import { transcribe, caption, clip } from "../snappy-video/api.ts";
 */

import { execSync } from "child_process";
import { env } from "../snappy-settings/load.ts";
import { realpathSync } from "fs";
import { annotationsForClass } from "../snappy-settings/tool-annotations.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";

const MAC_MINI = "robertboulos@Roberts-Mac-mini.local";
const ROBOT_ROB = "/Users/robertboulos/robot-rob";

function ssh(command: string, timeoutMs = 300000): string {
  const full = `ssh ${MAC_MINI} "${command.replace(/"/g, '\\"')}"`;
  return execSync(full, {
    encoding: "utf-8",
    timeout: timeoutMs,
    stdio: ["pipe", "pipe", "pipe"],
  }).trim();
}

// --- Public API ---

export function transcribe(videoPath: string, model = "small"): string {
  const outBase = videoPath.replace(/\.[^.]+$/, "");
  const cmd = `cd ${ROBOT_ROB} && source venv/bin/activate && whisper "${videoPath}" --model ${model} --output_format srt --output_dir /tmp/`;
  return ssh(cmd);
}

export function caption(
  videoPath: string,
  options: { style?: string; words?: boolean; clips?: boolean; outputPath?: string } = {}
): string {
  const outPath = options.outputPath || videoPath.replace(/(\.[^.]+)$/, "-captioned$1");
  const flags: string[] = [];
  if (options.style) flags.push(`--style ${options.style}`);
  if (options.words) flags.push("--words");
  if (options.clips) flags.push("--clips");
  const cmd = `cd ${ROBOT_ROB} && ./caption-video.sh "${videoPath}" "${outPath}" ${flags.join(" ")}`;
  return ssh(cmd);
}

export function clip(videoPath: string, startTime: string, duration: string, outputPath?: string): string {
  const outPath = outputPath || `/tmp/clip-${Date.now()}.mp4`;
  const cmd = `ffmpeg -y -ss ${startTime} -t ${duration} -i "${videoPath}" -c copy "${outPath}"`;
  return ssh(cmd);
}

export function resize(videoPath: string, format: "9:16" | "16:9" = "9:16", outputPath?: string): string {
  const outPath = outputPath || videoPath.replace(/(\.[^.]+)$/, `-${format.replace(":", "x")}$1`);
  const vf = format === "9:16"
    ? "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:-1:-1:color=black"
    : "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:-1:-1:color=black";
  const cmd = `ffmpeg -y -i "${videoPath}" -vf "${vf}" -c:a copy "${outPath}"`;
  return ssh(cmd);
}

export function extractAudio(videoPath: string, outputPath?: string): string {
  const outPath = outputPath || videoPath.replace(/\.[^.]+$/, ".m4a");
  const cmd = `ffmpeg -y -i "${videoPath}" -vn -c:a aac -b:a 192k "${outPath}"`;
  return ssh(cmd);
}

// --- CLI ---
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
/** THE HOST-FACING FACTS ⟨lane CONTRACTS N–Z, 2026-09-09⟩. `class` is the
 *  closed effect set snappy-tool-design rule 18 grades; `annotations` are
 *  DERIVED from it by the ONE derivation in
 *  `snappy-settings/tool-annotations.ts`, never written per verb, so a class
 *  and its published hints cannot disagree; `refusals` projects the ONE closed
 *  table in `snappy-settings/refusal-codes.ts`; `requires` is exactly the
 *  credential keys this file's own executable reads name, and nothing else. */
export const HAND_CONTRACT = {
  skill: "snappy-video",
  description: "Video and audio processing pipeline for Snappy, run on the Mac Mini via SSH (caption-video.sh wrapper around video-pipeline.py): Whisper transcription, SRT and ASS subtitles, word-level karaoke, ffmpeg caption burning, auto-clip detection by speech density, thumbnail extraction, audio extraction (m4a/mp3), 16:9 / 9:16 / 1:1 conversion, screen recording + voiceover merge, web compression. THE DEFAULT for any video or audio task. Use when Robert says: /snappy-video, \\\"caption this video\\\", \\\"burn the subtitles\\\", \\\"transcribe this with whisper\\\", \\\"clip the best parts\\\", \\\"make it vertical for shorts / reels\\\", \\\"compress the video for web\\\", \\\"extract the audio\\\", \\\"video for youtube\\\", \\\"video for ads\\\". Triggers on: video, captions, subtitles, whisper, ffmpeg burn, vertical clip, b-roll, thumbnail. NOT local ffmpeg on this Mac (see snappy-ffmpeg). NOT the Charlotte mac_mini_exec argument table (see video-pipeline). NOT scripting or retention structure (see retention-script).",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("missing_argument", "unknown_verb"),
  verbs: {
    caption: {
      args: ["path"], effect: "write-reversible", class: "additive-write", openWorld: true,
      annotations: annotationsForClass("additive-write", { openWorld: true }),
      inputSchema: { properties: { path: { type: "string", description: "Path to the video file to caption" } } },
    },
    clip: {
      args: ["path","start","duration"], effect: "write-reversible", class: "additive-write", openWorld: true,
      annotations: annotationsForClass("additive-write", { openWorld: true }),
      inputSchema: { properties: { path: { type: "string", description: "Path to the source video" }, start: { type: "string", description: "Start offset into the source video as HH:MM:SS" }, duration: { type: "string", description: "Clip length in seconds" } } },
    },
    transcribe: {
      args: ["path","model?"], effect: "write-reversible", class: "additive-write", openWorld: true,
      annotations: annotationsForClass("additive-write", { openWorld: true }),
      inputSchema: { properties: { path: { type: "string", description: "Path to the video or audio file to transcribe" }, model: { type: "string", description: "Model id to transcribe with" } } },
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}


if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "transcribe": {
        const [path, model] = args;
        if (!path) { console.error("Usage: api.ts transcribe <path> [model]"); process.exit(1); }
        console.log(transcribe(path, model || "small"));
        break;
      }
      case "caption": {
        const [path] = args;
        if (!path) { console.error("Usage: api.ts caption <path>"); process.exit(1); }
        console.log(caption(path, { style: "bold", words: true }));
        break;
      }
      case "clip": {
        const [path, start, duration] = args;
        if (!path || !start || !duration) {
          console.error("Usage: api.ts clip <path> <start> <duration>");
          process.exit(1);
        }
        console.log(clip(path, start, duration));
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [transcribe|caption|clip] ...");
    }
  })();
}

# Caption Styles, Flags, and Whisper Reference -- snappy-video

Reference for the `caption-video.sh` wrapper. Read this when you need a specific look or you
need to know what a flag does. Don't memorize.

## Table of Contents

- [Style names](#style-names)
- [Flag reference](#flag-reference)
- [Whisper model trade-offs](#whisper-model-trade-offs)
- [Style picker -- by use case](#style-picker--by-use-case)
- [ASS color reference](#ass-color-reference)
- [Custom styles via force_style](#custom-styles-via-force_style)

---

## Style names

`caption-video.sh ... --style NAME`

|Style|Look|Best for|
|---|---|---|
|`bottom`|White text, black outline, bottom-center|General use, default|
|`top`|White text, black outline, top-center|When the bottom of the frame is busy (lower thirds, logos)|
|`bold`|Large white text, thick black outline, bold weight|Social media, presentations, vertical clips|
|`highlight`|Yellow text on dark backdrop, bottom|Emphasis, attention-grabbing, ad creative|
|`minimal`|Small semi-transparent white|Documentary, podcast-on-background, subtle UX videos|

If none of these fit, write a one-off SRT and burn it with a custom `force_style`. See
[ffmpeg-recipes.md](ffmpeg-recipes.md) → Subtitle Burning, plus the
[force_style table below](#custom-styles-via-force_style).

---

## Flag reference

| Flag | Default | Description |
|---|---|---|
| `--style NAME` | `bottom` | One of bottom, top, bold, highlight, minimal |
| `--words` | off | Generate ASS with word-level karaoke (`\kf` tags). Doubles Whisper transcribe time |
| `--clips` | off | After captioning, score speech density and emit best clips as `*_clipN.mp4` |
| `--model SIZE` | `small` | Whisper model: tiny, base, small, medium, large |

Combinations are unrestricted: `--style bold --words --clips --model medium` is valid.

### Output naming

If you don't pass an explicit output path, the wrapper writes:

```
<input>_captioned.mp4         # base captioned cut
<input>_captioned.srt         # generated SRT
<input>_captioned.ass         # generated ASS, only if --words
<input>_clip1.mp4 ...         # only if --clips
```

---

## Whisper model trade-offs

|Model|RAM|Speed|Accuracy|When to use|
|---|---|---|---|---|
|`tiny`|~1 GB|32x|Bad for nuance|Throwaway drafts, very clean English|
|`base`|~1 GB|16x|Better than tiny|Drafts where you'll hand-fix obvious errors|
|`small`|~2 GB|6x|Solid|**Default.** English under 30 min, clean audio|
|`medium`|~5 GB|2x|Strong|Accented English, light noise, non-English|
|`large`|~10 GB|1x|Best|Production transcripts, multilingual, noisy audio|

The Mac Mini has plenty of RAM for `large`, the constraint is wall time. A 10-min video on
`small` takes ~90s; on `large` it's ~10 min. Use `--model large` only when you need it.

---

## Style picker -- by use case

|Output goes to|Style|Why|
|---|---|---|
|YouTube long-form|`bottom`|Standard, doesn't fight title cards or lower thirds|
|YouTube Shorts|`bold` + `--words`|Vertical, muted-by-default, needs eye-grab|
|Instagram Reels / TikTok|`bold` + `--words`|Same as Shorts|
|LinkedIn native video|`bold`|Muted autoplay, professional context|
|Meta ad creative|`highlight` + `--words`|Stop-the-scroll, bright color cue|
|YouTube ad creative|`bold` + `--words`|Standard, captions critical for muted view|
|Skool classroom clip|`bottom` (no `--words`)|Casual, less production polish, smaller file|
|Podcast video (audio + waveform)|`minimal`|Subtle, doesn't compete with audio focus|
|Demo / screen recording|`top`|Bottom of frame usually shows the dock or app UI|

---

## ASS color reference

ASS uses BGR (not RGB) hex with an `&H00` prefix and trailing color: `&H00BBGGRR`.

|Color|ASS code|Notes|
|---|---|---|
|White|`&H00FFFFFF`|Default text|
|Black|`&H00000000`|Default outline|
|Yellow|`&H0000FFFF`|Highlight style|
|Red|`&H000000FF`|Warning / error overlays|
|Green|`&H0000FF00`|Success / positive|
|Cyan|`&H00FFFF00`|Tech / dev content|
|Magenta|`&H00FF00FF`|Brand accents|
|Snappy brand orange|`&H000099FF`|Custom Snappy color|

Convert any web RGB to ASS BGR: take `#RRGGBB`, swap to `BB GG RR`, prefix `&H00`.
Example: `#FF6600` (snappy orange) → `&H000066FF`.

---

## Custom styles via force_style

When you want a one-off look without editing the wrapper script:

```bash
ffmpeg -y -i in.mp4 \
  -vf "subtitles=captions.srt:force_style='FontName=Helvetica Neue,FontSize=32,PrimaryColour=&H0000FFFF,OutlineColour=&H00000000,Outline=3,Shadow=2,MarginV=80,Bold=1,Alignment=2'" \
  -c:a copy out.mp4
```

|Key|Range / Value|Effect|
|---|---|---|
|`FontName`|System font|`Helvetica Neue`, `Arial`, `Impact`, `SF Pro Display`|
|`FontSize`|px @ 1080p|24-48 typical, 56+ for vertical/Shorts|
|`PrimaryColour`|ASS BGR|Text fill color|
|`OutlineColour`|ASS BGR|Stroke color|
|`BackColour`|ASS BGR|Box background color (with `BorderStyle=3`)|
|`Outline`|0-4|Stroke width|
|`Shadow`|0-4|Shadow distance|
|`Bold`|0/1|Bold weight on/off|
|`Italic`|0/1|Italic on/off|
|`MarginV`|px|Vertical margin from edge|
|`MarginL` / `MarginR`|px|Horizontal margins|
|`Alignment`|1-9|Numpad layout: 1=BL, 2=BC, 3=BR, 4=ML, 5=MC, 6=MR, 7=TL, 8=TC, 9=TR|
|`BorderStyle`|1 or 3|1 = outline+shadow, 3 = opaque box|
|`Spacing`|px|Letter-spacing|

# ffmpeg Recipes -- snappy-video

Every ffmpeg one-liner the snappy-video pipeline depends on, plus the manual recipes you reach
for when `caption-video.sh` doesn't fit. All commands assume the file lives on the Mac Mini in
`/tmp/`. Wrap with `ssh robertboulos@Roberts-Mac-mini.local "..."` for remote execution.

## Table of Contents

- [Trimming and clipping](#trimming-and-clipping)
- [Subtitle burning (SRT and ASS)](#subtitle-burning-srt-and-ass)
- [Whisper transcription (manual)](#whisper-transcription-manual)
- [Thumbnails and key frames](#thumbnails-and-key-frames)
- [Audio extraction](#audio-extraction)
- [Format conversion and resizing](#format-conversion-and-resizing)
- [Compression for web/upload](#compression-for-webupload)
- [Concatenation and segments](#concatenation-and-segments)
- [Screen recording + voiceover merge](#screen-recording--voiceover-merge)
- [Loudness normalization](#loudness-normalization)
- [Probing and inspection](#probing-and-inspection)

---

## Trimming and clipping

### Fast trim -- keyframe-aligned, no re-encode

Use this for 95% of cuts. It is instant and lossless but the cut snaps to the nearest keyframe
(usually within 1-2 seconds of the requested timestamp).

```bash
ffmpeg -y -ss 00:01:30 -to 00:02:45 -i in.mp4 -c copy clip.mp4
```

### Frame-accurate trim -- re-encode

Use only when you need an exact frame boundary (e.g. cutting on a specific word ending).

```bash
ffmpeg -y -i in.mp4 -ss 00:01:30 -to 00:02:45 -c:v libx264 -preset medium -crf 18 -c:a aac clip.mp4
```

### Trim by duration instead of end timestamp

```bash
ffmpeg -y -ss 00:01:30 -t 75 -i in.mp4 -c copy clip.mp4   # 75 seconds starting at 1:30
```

### Cut the first or last N seconds

```bash
ffmpeg -y -ss 5 -i in.mp4 -c copy out.mp4                  # drop first 5s
ffmpeg -y -i in.mp4 -t 30 -c copy first30.mp4              # keep first 30s only
```

---

## Subtitle burning (SRT and ASS)

### Burn an existing SRT into the video

```bash
ffmpeg -y -i in.mp4 \
  -vf "subtitles=captions.srt:force_style='FontSize=24,FontName=Arial,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,Outline=2,Shadow=1,MarginV=30'" \
  -c:a copy out.mp4
```

| force_style key | Meaning |
|---|---|
| `FontSize` | px at 1080p; scale up for 4K |
| `FontName` | system font name on the Mac Mini |
| `PrimaryColour` | text color, ASS BGR hex `&H00BBGGRR` |
| `OutlineColour` | stroke color, same format |
| `Outline` | stroke width in px |
| `Shadow` | shadow distance in px |
| `MarginV` | vertical margin from the bottom |
| `Alignment` | 1=BL, 2=BC, 3=BR, 5=TL, 6=TC, 7=TR |

### Burn an ASS file (karaoke / styled)

```bash
ffmpeg -y -i in.mp4 -vf "ass=captions.ass" -c:a copy out.mp4
```

The pipeline writes ASS files with `\kf` karaoke timing tags when you pass `--words` to
`caption-video.sh`. Don't hand-roll ASS unless you have a reason -- let the pipeline emit it.

### Soft subtitles (mux without burning, viewer can toggle)

```bash
ffmpeg -y -i in.mp4 -i captions.srt -c copy -c:s mov_text -metadata:s:s:0 language=eng out.mp4
```

---

## Whisper transcription (manual)

The pipeline does this for you, but here's the raw call when you need just an SRT:

```bash
ssh robertboulos@Roberts-Mac-mini.local "cd /Users/robertboulos/robot-rob && \
  source venv/bin/activate && \
  python3 -c \"
import whisper
model = whisper.load_model('small')
result = model.transcribe('/tmp/input.mp4', word_timestamps=True)
with open('/tmp/output.srt', 'w') as f:
    for i, seg in enumerate(result['segments'], 1):
        s, e, t = seg['start'], seg['end'], seg['text'].strip()
        f.write(f'{i}\n{int(s//3600):02d}:{int(s%3600//60):02d}:{s%60:06.3f} --> {int(e//3600):02d}:{int(e%3600//60):02d}:{e%60:06.3f}\n{t}\n\n')
\""
```

| Model | RAM | Speed | Use |
|---|---|---|---|
| `tiny` | ~1 GB | 32x realtime | Drafts, low-stakes English |
| `base` | ~1 GB | 16x | Faster than `small`, slightly worse |
| `small` | ~2 GB | 6x | **Default.** English, normal audio |
| `medium` | ~5 GB | 2x | Non-English, noisy, accented |
| `large` | ~10 GB | 1x | Production transcripts, multilingual |

---

## Thumbnails and key frames

### Single frame at a timestamp

```bash
ffmpeg -y -ss 00:00:15 -i in.mp4 -frames:v 1 -q:v 2 thumb.jpg
```

`-q:v 2` is high JPEG quality (lower = better, range 1-31).

### Frame at a specific resolution (YouTube 1280x720)

```bash
ffmpeg -y -ss 00:00:15 -i in.mp4 -frames:v 1 \
  -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1:color=black" \
  -q:v 2 thumb.jpg
```

### Multiple candidate frames (every 10s)

```bash
ffmpeg -y -i in.mp4 -vf "fps=1/10" -q:v 2 thumb_%04d.jpg
```

### Smart key-frame extraction (one per scene change)

```bash
ffmpeg -y -i in.mp4 -vf "select='gt(scene,0.4)',showinfo" -vsync vfr -q:v 2 scene_%04d.jpg
```

### Animated GIF preview

```bash
ffmpeg -y -ss 00:00:02 -t 3 -i in.mp4 -vf "fps=10,scale=480:-1:flags=lanczos" preview.gif
```

---

## Audio extraction

### m4a (AAC, smaller, modern)

```bash
ffmpeg -y -i in.mp4 -vn -c:a aac -b:a 192k audio.m4a
```

### mp3 (universal compatibility)

```bash
ffmpeg -y -i in.mp4 -vn -c:a libmp3lame -b:a 192k audio.mp3
```

### wav (lossless, for re-processing through Whisper)

```bash
ffmpeg -y -i in.mp4 -vn -ac 1 -ar 16000 -c:a pcm_s16le audio.wav
```

`-ac 1 -ar 16000` matches Whisper's expected input -- saves a resample step.

### Strip audio from a video (silent video)

```bash
ffmpeg -y -i in.mp4 -an -c:v copy silent.mp4
```

---

## Format conversion and resizing

### YouTube (16:9, 1920x1080)

```bash
ffmpeg -y -i in.mp4 \
  -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:-1:-1:color=black" \
  -c:a copy youtube.mp4
```

### Reels / Shorts / TikTok (9:16, 1080x1920)

```bash
ffmpeg -y -i in.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:-1:-1:color=black" \
  -c:a copy vertical.mp4
```

### Instagram square (1:1, 1080x1080)

```bash
ffmpeg -y -i in.mp4 \
  -vf "scale=1080:1080:force_original_aspect_ratio=decrease,pad=1080:1080:-1:-1:color=black" \
  -c:a copy square.mp4
```

### Crop to a square instead of letterbox

```bash
ffmpeg -y -i in.mp4 -vf "crop=ih:ih,scale=1080:1080" -c:a copy square_cropped.mp4
```

### Change container only (mov to mp4, etc.)

```bash
ffmpeg -y -i in.mov -c copy out.mp4
```

---

## Compression for web/upload

### Standard H.264 web compression

```bash
ffmpeg -y -i in.mp4 \
  -c:v libx264 -crf 23 -preset medium \
  -c:a aac -b:a 128k \
  -movflags +faststart \
  web.mp4
```

| Knob | Lower = | Higher = |
|---|---|---|
| `-crf` | Bigger file, better quality (range 18-28) | Smaller file, worse quality |
| `-preset` | Slower encode, better compression (`veryslow`...`ultrafast`) | Faster encode, larger file |

### Aggressive compression for Skool (under 100 MB)

```bash
ffmpeg -y -i in.mp4 \
  -c:v libx264 -crf 26 -preset slow \
  -c:a aac -b:a 96k \
  -movflags +faststart \
  skool.mp4
```

### H.265 (HEVC) -- half the size at same quality, slower encode

```bash
ffmpeg -y -i in.mp4 -c:v libx265 -crf 28 -preset medium -tag:v hvc1 -c:a aac -b:a 128k h265.mp4
```

`-tag:v hvc1` makes the file play in QuickTime / Safari / iOS.

---

## Concatenation and segments

### Split into N-second segments (no re-encode)

```bash
ffmpeg -y -i in.mp4 -f segment -segment_time 60 -c copy -reset_timestamps 1 segment_%03d.mp4
```

### Concatenate same-codec files (fast, no re-encode)

```bash
# 1. Build a list file
printf "file 'a.mp4'\nfile 'b.mp4'\nfile 'c.mp4'\n" > concat.txt
# 2. Concat
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy joined.mp4
```

### Concatenate different-codec files (re-encode)

```bash
ffmpeg -y -i a.mp4 -i b.mp4 -filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]" \
  -map "[v]" -map "[a]" joined.mp4
```

---

## Screen recording + voiceover merge

```bash
# 1. Generate voiceover with macOS TTS
ssh robertboulos@Roberts-Mac-mini.local "say -v Samantha -o /tmp/vo.aiff 'Your narration here'"

# 2. Convert to m4a
ssh robertboulos@Roberts-Mac-mini.local "ffmpeg -y -i /tmp/vo.aiff -c:a aac /tmp/vo.m4a"

# 3. Merge VO over screen recording (replace original audio)
ssh robertboulos@Roberts-Mac-mini.local \
  "ffmpeg -y -i /tmp/screen.mp4 -i /tmp/vo.m4a \
   -c:v copy -c:a aac -map 0:v:0 -map 1:a:0 -shortest /tmp/merged.mp4"

# 4. Caption the result
ssh robertboulos@Roberts-Mac-mini.local \
  "cd /Users/robertboulos/robot-rob && ./caption-video.sh /tmp/merged.mp4 /tmp/final.mp4 --style bold --words"
```

### Mix VO and original audio (don't replace, blend)

```bash
ffmpeg -y -i screen.mp4 -i vo.m4a \
  -filter_complex "[0:a]volume=0.3[orig];[1:a]volume=1.0[vo];[orig][vo]amix=inputs=2:duration=longest" \
  -c:v copy mixed.mp4
```

---

## Loudness normalization

YouTube targets ~-14 LUFS. Apply EBU R128 loudnorm in two passes for accuracy:

```bash
# Pass 1 -- measure
ffmpeg -i in.mp4 -af loudnorm=I=-14:LRA=11:TP=-1.5:print_format=summary -f null - 2>&1 | tail -20

# Pass 2 -- apply (substitute the input_i / input_tp / input_lra / input_thresh from pass 1)
ffmpeg -y -i in.mp4 -af loudnorm=I=-14:LRA=11:TP=-1.5:measured_I=-23.4:measured_LRA=8.2:measured_TP=-2.1:measured_thresh=-33.8:linear=true -c:v copy normalized.mp4
```

Quick single-pass (good enough for most clips):

```bash
ffmpeg -y -i in.mp4 -af loudnorm=I=-14:LRA=11:TP=-1.5 -c:v copy normalized.mp4
```

---

## Probing and inspection

### Duration, codec, resolution at a glance

```bash
ffprobe -v error -show_entries stream=codec_name,width,height,duration -show_entries format=duration -of default=noprint_wrappers=1 in.mp4
```

### Just the duration in seconds

```bash
ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 in.mp4
```

### Frame rate

```bash
ffprobe -v error -select_streams v:0 -show_entries stream=r_frame_rate -of default=nw=1:nk=1 in.mp4
```

### Audio sample rate / channels

```bash
ffprobe -v error -select_streams a:0 -show_entries stream=sample_rate,channels -of default=nw=1:nk=1 in.mp4
```

### Full JSON dump

```bash
ffprobe -v error -print_format json -show_format -show_streams in.mp4
```

/**
 * COVERAGE FOR SNAPPY-VIDEO'S DECLARED REFUSAL CODES
 * (snappy-tool-design rule 33: "refusal codes form one closed table and each
 * row has coverage").
 *
 * Two things are graded here, and the second is the one that matters. The
 * first is that the hand's table is a PROJECTION of the collection's one
 * closed table in snappy-settings/refusal-codes.ts — same object, not a copy
 * that can drift. The second is that every declared code is GROUNDED: the
 * evidence that justified declaring it is re-checked here, because a refusal
 * code with no path that emits it is a branch the reader waits for and never
 * sees, and a table of those passes a lint while teaching a lie.
 *
 * The code list is spelled out rather than read from the contract: a test that
 * iterates the thing it grades passes for an empty table.
 */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES } from "../snappy-settings/refusal-codes.ts";

const SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "api.ts"), "utf8");

/** Every refusal code snappy-video declares. */
const DECLARED = [
  "missing_argument",
  "unknown_verb",
] as const;

test("snappy-video declares exactly these refusal codes", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals).sort(), [...DECLARED].sort());
});

test("every declared code is the SAME row as the one closed table's, never a copy", () => {
  const table = HAND_CONTRACT.refusals as Record<string, unknown>;
  for (const code of DECLARED) {
    assert.equal(table[code], REFUSAL_CODES[code], `${code} is not the shared row`);
  }
});

test("missing_argument is grounded: at least one verb has a required word", () => {
  const required = Object.values(HAND_CONTRACT.verbs as Record<string, { args?: readonly string[] }>)
    .flatMap((v) => (v.args ?? []).filter((a) => !a.endsWith("?")));
  assert.ok(required.length > 0, "no verb has a required argument, so missing_argument can never fire");
});

test("unknown_verb is grounded: the contract closes the verb set, so a word outside it is refusable", () => {
  assert.ok(Object.keys(HAND_CONTRACT.verbs).length >= 0);
  assert.ok(!Object.keys(HAND_CONTRACT.verbs).includes("no-such-verb"));
});