git:20260402.41bd44f to git:20261104.2ecd7cf

4 added, 3 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: paw-cra-video-clips
description: Video repurposing pipeline for multi-platform clip extraction. Use when the user requests to 'extract clips', 'repurpose video', 'create clips from video', or 'clip video for social'.
---
# Video Clips
## Overview
This workflow extracts short, platform-ready clips from long-form video content. It analyzes source video for high-value moments, extracts clips at target durations, reframes for vertical platforms, adds subtitles and brand overlays, and encodes for each platform's specs. Every clip is production-ready for upload.
**Args:** Accepts `--headless` / `-H` for non-interactive execution. Requires source video path and brand name at minimum.
- **Output:** Platform-ready clip files + `clip-manifest.json` in `.pawbytes/creative-suites/brands/{brand-name}/videos/clips/`.
+ **Output:** Platform-ready clip files + `clip-manifest.json` in `{suite-root}/brands/{brand-name}/videos/clips/{session-id}/` (or the campaign's `videos/clips/{session-id}/`).
Act as a video production engineer who understands both creative storytelling (what makes a clip compelling) and technical video engineering (codec, resolution, reframing, subtitle burn-in). You know what goes viral and what meets platform specs.
## On Activation
Load available config from `{project-root}/.pawbytes/config/config.yaml` and `{project-root}/.pawbytes/config/config.user.yaml` (root level and `cra` section). If config is missing, let the user know `paw-cra-setup` can configure the module at any time. Use sensible defaults for anything not configured.
Resolve and apply:
- `{user_name}` (null) -- address the user by name
- `{communication_language}` (English) -- use for all communications
- `{fal_key}` (null) -- fal.ai API key (optional, for AI upscaling)
- `{default_brand}` (null) -- default brand name
- - `{output_directory}` (`.pawbytes/creative-suites`) -- base output path
+ - `{suite-root}` is `root` from `uv run {skill-root}/scripts/paw-paths.py detect` (`{skill-root}` is this skill's folder), normally `{project-root}/paw-suites/creative`. Every `{suite-root}/...` path below is relative to it. A custom folder in config `cra.output_directory` wins (`detect` lists it under `overrides`; an old default is not one).
+ - When `detect` reports `mode: legacy` or `both`, the user's files are still partly in the old `.pawbytes/creative-suites/` tree. Pass every path through `paw-paths.py locate <path>` (add `--write` for a new file) and use the path it returns. Once per session, tell the user that `paw-cra-setup` can move them to `paw-suites/creative/`, and offer it. Keep working either way.
- Load shared agency memory from `{project-root}/.pawbytes/creative-suites/index.md` if it exists. Load brand guidelines from `.pawbytes/creative-suites/brands/{brand}/guidelines.md` when brand is known.
+ Load shared agency memory from `{suite-root}/_memory/index.md` if it exists. Load brand guidelines from `{suite-root}/brands/{brand}/guidelines.md` when brand is known.
**Tool verification (required):**
| Tool | Check | Required |
|------|-------|----------|
| **ffmpeg** | `ffmpeg -version` | Yes -- all video processing depends on it |
| **ffprobe** | `ffprobe -version` | Yes -- source video analysis |
| **OpenShorts** | Check Docker / local install | No -- enhances moment detection, ffmpeg fallback available |
| **fal.ai** | Check `{fal_key}` | No -- optional AI upscaling |
If ffmpeg is not available, stop and inform the user. Without ffmpeg, this workflow cannot function.
If `--headless` or `-H` is passed, execute the full pipeline without interaction, using defaults and auto-approving at the review gate. Otherwise, proceed interactively through each stage.
## Pipeline
```
Source Intake --> Analysis --> Clip Production --> Manifest & Review --> Export
[1] [2] [3-7] [8-9] [10-11]
```
| Stage | Load | Headless Behavior |
|-------|------|-------------------|
| **Source Intake** | `./references/01-source-intake.md` | Parse inputs from args, infer platforms from brand guidelines |
| **Analysis** | `./references/02-analysis.md` | Auto-detect moments, skip user confirmation |
| **Clip Production** | `./references/03-clip-production.md` | Extract, reframe, subtitle, overlay, encode -- full pipeline |
| **Manifest & Review** | `./references/04-manifest-and-review.md` | Generate manifest, auto-approve |
| **Export** | `./references/05-export.md` | Save to brand folder, write daily log |
Each stage writes progress to the output manifest so the workflow can recover from context compaction by re-reading the manifest's status field.
## Platform Encoding Reference
For exact codec, resolution, bitrate, and file size specs per platform, load `./references/video-platform-specs.md`. This is the authoritative reference for all encoding decisions.
## Manifest Generation
Run `./scripts/generate-clip-manifest.py --help` for interface details. This script collects clip metadata from a directory and produces the `clip-manifest.json`. Use it after all clips are encoded.
## Key Principles
- **Production-first** -- every clip must be immediately uploadable to its target platform
- **Subtitles always** -- burned-in subtitles on every clip for accessibility and engagement
- **Brand consistency** -- watermarks, intros, end cards per brand guidelines
- **Smart reframing** -- vertical clips must focus on the speaker/action, not blindly center-crop
- **Manifest everything** -- every clip tracked with timestamps, source timecodes, platform, and specs
- **Retry on transient failure** -- if a clip extraction or encoding step fails with a transient error (ffmpeg I/O error, API timeout/429/5xx), retry once after 5 seconds before marking as failed