video-edit-cli 0.1.0__tar.gz → 0.1.1__tar.gz

video_edit_cli-0.1.1/.claude/skills/release/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: release
+description: >
+  Release process for the video-edit-cli package. Handles version bumping
+  (major/minor/patch/beta), changelog updates, pre-release quality checks, wheel
+  verification (including the bundled agent skills), publishing to PyPI, git tagging,
+  and the GitHub Release. Use this skill whenever the user wants to cut a release,
+  bump the version, or publish to PyPI — even if they just say "let's ship it".
+---
+
+# video-edit-cli Release Process
+
+Releases are published locally with `uv publish` (authenticated via the
+`UV_PUBLISH_TOKEN` environment variable), then tagged and mirrored as a GitHub
+Release. CI (`test.yml`) is the quality gate but does not publish.
+
+## Before you start
+
+Verify the preconditions. If any fail, stop and tell the user.
+
+1. **Clean working tree** — `git status` shows no uncommitted changes
+2. **On `main` and up to date** — `git pull`; releases only come from main
+3. **CI green on HEAD** — `gh run list --branch main --limit 1` shows success
+4. **Publish token present** — `test -n "$UV_PUBLISH_TOKEN"`
+
+Ask the user what kind of release this is (patch / minor / major / beta). If
+they already said, don't ask again.
+
+## Step 1: Figure out what changed
+
+```bash
+git log $(git describe --tags --abbrev=0)..HEAD --oneline
+```
+
+Cross-reference with the `[Unreleased]` section of `CHANGELOG.md`; add any
+missing entries under the Keep a Changelog categories (Added / Changed /
+Fixed / Removed / Docs).
+
+## Step 2: Run quality checks
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run pytest
+```
+
+Fix any failure before continuing.
+
+## Step 3: Bump the version
+
+The version lives in **two** places; they must match:
+
+1. `pyproject.toml` — `version = "X.Y.Z"`
+2. `src/video_editor/__init__.py` — `__version__ = "X.Y.Z"`
+
+Beta convention: `0.2.0` → `0.2.1b1` → `0.2.1b2` → `0.2.1`.
+
+## Step 4: Update the changelog
+
+In `CHANGELOG.md`: rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`,
+add a fresh empty `## [Unreleased]` section on top, and review the entries
+for user-facing clarity. The release notes are taken from this section.
+
+## Step 5: Build and verify the artifacts
+
+```bash
+rm -rf dist && uv build
+```
+
+Then verify the wheel — this is the step that catches packaging regressions:
+
+- The `video-edit-cli` executable works from a clean venv:
+  `uv venv /tmp/vec-rel && uv pip install -p /tmp/vec-rel/bin/python dist/*.whl`
+  then run `--help` and `skills list`.
+- **Bundled skills are present**: `unzip -l dist/*.whl | grep video_editor/skills/`
+  must show `SKILL.md` and references for every skill in
+  `video_editor.skills.SHIPPED_SKILLS` (repo `skills/` dir is the source of truth;
+  the force-include entries in `pyproject.toml` do the bundling).
+- All JSON schemas are present: `unzip -l dist/*.whl | grep schemas/`.
+
+## Step 6: Commit, tag, publish
+
+Show the user a summary (version, changelog entry, files touched) and get
+confirmation before pushing or publishing.
+
+```bash
+git add pyproject.toml src/video_editor/__init__.py CHANGELOG.md
+git commit -m "release: vX.Y.Z"
+git tag vX.Y.Z
+git push origin main vX.Y.Z
+uv publish
+```
+
+If `uv publish` fails mid-upload, it is safe to re-run; PyPI rejects
+duplicate files idempotently.
+
+## Step 7: GitHub Release
+
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z" --notes "<the X.Y.Z changelog section>"
+```
+
+## Step 8: Verify
+
+```bash
+uv pip install --no-cache -p /tmp/vec-verify/bin/python video-edit-cli==X.Y.Z --index-url https://pypi.org/simple
+```
+
+(Create the venv first; PyPI's simple index can lag ~1–2 minutes after upload —
+retry rather than assuming failure.) Confirm `video-edit-cli skills install`
+works from the fresh install, then share the links:
+
+- PyPI: https://pypi.org/project/video-edit-cli/X.Y.Z/
+- GitHub Release: `gh release view vX.Y.Z --json url`
+
+## If something goes wrong after tagging
+
+PyPI versions are immutable — a broken published version cannot be replaced.
+Fix forward with a new patch release. If the tag was pushed but nothing was
+published, you may delete and re-create it (`git tag -d vX.Y.Z && git push
+origin :refs/tags/vX.Y.Z`) — confirm with the user first.

video_edit_cli-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+tests/fixtures/
+.venv/
+dist/
+__pycache__/
+*.py[cod]
+.agents/
+.claude/*
+!.claude/skills/
+.claude/skills/*
+!.claude/skills/release/
+.worktrees/

{video_edit_cli-0.1.0 → video_edit_cli-0.1.1}/PKG-INFO

@@ -1,8 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: video-edit-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Headless, project-agnostic video-editing CLI with atomic subcommands for AI agents.
-Keywords: video,editing,ffmpeg,agents,cli
+Project-URL: Repository, https://github.com/computerlovetech/video-edit-cli
+Project-URL: Issues, https://github.com/computerlovetech/video-edit-cli/issues
+Keywords: agents,cli,editing,ffmpeg,video
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Programming Language :: Python :: 3
@@ -11,15 +13,13 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Multimedia :: Video :: Conversion
+Requires-Python: >=3.11
 Requires-Dist: jsonschema>=4.21
 Requires-Dist: pyyaml>=6
-Requires-Dist: deepfilternet>=0.5 ; extra == 'df'
-Requires-Dist: mlx-whisper>=0.4 ; extra == 'mlx'
-Requires-Python: >=3.11
-Project-URL: Issues, https://github.com/computerlovetech/video-edit-cli/issues
-Project-URL: Repository, https://github.com/computerlovetech/video-edit-cli
 Provides-Extra: df
+Requires-Dist: deepfilternet>=0.5; extra == 'df'
 Provides-Extra: mlx
+Requires-Dist: mlx-whisper>=0.4; extra == 'mlx'
 Description-Content-Type: text/markdown
 
 # video-edit-cli
@@ -55,7 +55,18 @@ uv run video-edit-cli filmstrip create --input recording.mp4 \
 ```
 
 The companion skill in `skills/video-editor/` teaches agents the editing method;
-this package owns the mechanics. Tests generate small deterministic fixtures at
+this package owns the mechanics. The skill ships inside the package — install it
+into a project with:
+
+```sh
+video-edit-cli skills install            # copies into .claude/skills/
+video-edit-cli skills install --target <dir>
+```
+
+Alternatively, manage it with agr: `agr add computerlovetech/video-edit-cli/video-editor`.
+Skills in `skills/` that are not listed in `video_editor.skills.SHIPPED_SKILLS`
+(and the matching force-include entries in `pyproject.toml`) are agr-only and do
+not ship in the wheel. Tests generate small deterministic fixtures at
 runtime (`tests/generate_fixtures.py`); no media is committed.
 
 Quality gates (run from this directory):

{video_edit_cli-0.1.0 → video_edit_cli-0.1.1}/README.md

@@ -31,7 +31,18 @@ uv run video-edit-cli filmstrip create --input recording.mp4 \
 ```
 
 The companion skill in `skills/video-editor/` teaches agents the editing method;
-this package owns the mechanics. Tests generate small deterministic fixtures at
+this package owns the mechanics. The skill ships inside the package — install it
+into a project with:
+
+```sh
+video-edit-cli skills install            # copies into .claude/skills/
+video-edit-cli skills install --target <dir>
+```
+
+Alternatively, manage it with agr: `agr add computerlovetech/video-edit-cli/video-editor`.
+Skills in `skills/` that are not listed in `video_editor.skills.SHIPPED_SKILLS`
+(and the matching force-include entries in `pyproject.toml`) are agr-only and do
+not ship in the wheel. Tests generate small deterministic fixtures at
 runtime (`tests/generate_fixtures.py`); no media is committed.
 
 Quality gates (run from this directory):

{video_edit_cli-0.1.0 → video_edit_cli-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "video-edit-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Headless, project-agnostic video-editing CLI with atomic subcommands for AI agents."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -39,11 +39,20 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.7.19,<0.9.0"]
-build-backend = "uv_build"
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
 
-[tool.uv.build-backend]
-module-name = "video_editor"
+[tool.hatch.build.targets.wheel]
+packages = ["src/video_editor"]
+
+# Ship the user-facing agent skills inside the package (playwright-cli pattern):
+# the canonical copies stay in the repository-root skills/ directory, and only
+# the listed skills are bundled. Development-only skills must not be added here.
+[tool.hatch.build.targets.wheel.force-include]
+"skills/video-editor" = "video_editor/skills/video-editor"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "skills", "tests", "README.md", "pyproject.toml"]
 
 [tool.pytest.ini_options]
 markers = [

video_edit_cli-0.1.1/skills/create-clips/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: create-clips
+description: Derive several publishable social clips (YouTube Shorts, standard YouTube videos, LinkedIn) from a long-form recording — podcast episode, interview, vlog, talk, or livestream. Use when the user asks to make clips, shorts, highlights, or teasers from a video, especially after a main edit already exists. Builds on the video-editor skill and the video-edit-cli CLI.
+---
+
+You turn one long recording into a small set of clips worth publishing, each
+packaged with everything needed to post it. The `video-editor` skill and the
+`video-edit-cli` CLI are your workbench for all media mechanics; this skill owns
+the clip-release workflow. Read the `video-editor` skill first if it is not
+already loaded — its invariants (immutable sources, evidence before edits,
+validate before rendering) all apply here.
+
+## Inputs
+
+Establish these before cutting anything; ask only for what you cannot infer.
+
+- **Source**: an existing video-editor workspace (preferred — reuse its
+  transcript, plans, and hashes) or standalone media (then `workspace init` first).
+- **Clip count**: default 3–5 if unspecified.
+- **Full-episode URL**: needed for descriptions; use a `[LINK]` placeholder and
+  say so if unknown.
+- **Language**: of the recording; copy is written in the same language unless
+  asked otherwise.
+- **Formats**: default is both 9:16 vertical and 16:9 horizontal per clip.
+- **Brand/voice**: any project profile, tone guidance, or naming conventions the
+  hosting repo provides (e.g. a project-specific publishing skill or profile YAML).
+
+## Method
+
+1. **Know the material.** Reuse the workspace transcript if present; otherwise
+   transcribe (see the video-editor transcription reference). Skim the full
+   transcript before selecting anything.
+2. **Select moments editorially.** Choose self-contained segments with a hook in
+   the first seconds, one clear idea, and a natural ending — a claim, a result, a
+   story, a provocation. You choose; no command picks highlights for you. Target
+   20–90 s for Shorts. Prefer moments that stand alone without episode context.
+3. **Tighten boundaries on evidence.** Use word-level transcript timing to start
+   on the first word of a sentence and end on a completed thought; verify each
+   boundary visually (frames/preview) before rendering.
+4. **Render both formats per clip.** Vertical via `short create-plan` (mind the
+   vertical-video reference — check for burned-in captions before cropping faces);
+   horizontal as a straight excerpt at source aspect. Master audio to the
+   platform loudness target and run `output validate` on every deliverable.
+5. **Subtitles.** Burn styled subtitles into both renders when the source has
+   none; always keep `subtitles.srt` and `subtitles.vtt` sidecars. If the source
+   already has burned-in captions, do not double-caption — mux instead.
+6. **Write the copy.** For each clip, in the recording's language:
+   - `youtube-short.txt` — clickable title (line 1) + short description with the
+     episode link and relevant hashtags.
+   - `youtube-video.txt` — title + fuller description linking the episode.
+   - `linkedin.txt` — a self-contained post (hook, substance, link); no
+     clickbait that the clip doesn't cash.
+7. **Package and review.** Assemble the layout in
+   [references/package-format.md](references/package-format.md), review every
+   render's cut boundaries and framing, and report any residual defects honestly.
+
+## Boundaries
+
+- Never modify the main edit or the source media; clips are derived artifacts.
+- Do not publish anywhere — the deliverable is the reviewed package. Publishing
+  is owned by project-specific skills (e.g. a podcast's release skill).
+- Project-specific tone, branding, output location, and naming conventions come
+  from the hosting repo; when absent, use the defaults above and say so.

video_edit_cli-0.1.1/skills/create-clips/references/package-format.md

@@ -0,0 +1,43 @@
+# Clip package format
+
+One directory per clip, numbered in publish order, slug from the clip's topic:
+
+```text
+clips/
+  01-<topic-slug>/
+    vertical.mp4        # 9:16 master, validated
+    horizontal.mp4      # 16:9 master, validated
+    subtitles.srt
+    subtitles.vtt
+    youtube-short.txt   # title on line 1, blank line, description
+    youtube-video.txt   # title on line 1, blank line, description
+    linkedin.txt        # complete post text
+    manifest.json
+```
+
+`manifest.json` records provenance and the editorial decision:
+
+```json
+{
+  "schema_version": "1",
+  "slug": "01-<topic-slug>",
+  "source": {"path": "…", "sha256": "…"},
+  "range": {"start": 123.45, "end": 187.2},
+  "reason": "why this moment was selected",
+  "language": "da",
+  "episode_url": "https://…",
+  "renders": {
+    "vertical": {"file": "vertical.mp4", "canvas": "1080x1920"},
+    "horizontal": {"file": "horizontal.mp4", "canvas": "1920x1080"}
+  },
+  "validation": "passed"
+}
+```
+
+Rules:
+
+- Every render keeps its `*.provenance.json` sidecar next to it.
+- Formats a clip intentionally omits are left out of `renders` (and the reason
+  noted in the summary), never shipped unvalidated.
+- If the episode URL is unknown, use `[LINK]` in all copy and `null` in the
+  manifest, and flag it in the final summary.

video_edit_cli-0.1.1/skills/video-editor/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: video-editor
+description: Edit, inspect, transcribe, cut, master, or package video and audio media with the headless `video-edit-cli` CLI. Use when the user asks to edit a recording, cut a video, inspect unfamiliar media, extract audio, preview a range, synchronize cameras, make a vertical clip, or produce podcast/episode deliverables.
+---
+
+You are the editor; the `video-edit-cli` CLI is your workbench. It exposes atomic,
+deterministic primitives that print one JSON result on stdout. You form the
+editorial plan yourself — no command decides what to keep, remove, or highlight.
+
+Run `video-edit-cli --help` (and `--help` on any subcommand) for the authoritative
+command surface; inside this repository run it as `uv run video-edit-cli …`.
+
+## Invariants (hold for every task)
+
+- Source media is immutable. Never overwrite, re-encode in place, or delete an
+  original. Every derived file is new and keeps its `*.provenance.json` sidecar.
+- Evidence before edits: never act on a range you have not inspected through
+  metadata, transcript, frames, waveform, or preview.
+- Validate before rendering; preview before mastering when edits are material.
+- Prefer the cheapest sufficient evidence: `probe` and transcript first for
+  dialogue; targeted visual/audio inspection only where a decision needs it.
+
+## Method
+
+1. **Establish the outcome.** Restate what deliverable is requested and what
+   media exists. Done when you can name the requested outputs and every source
+   file involved.
+2. **Set up a workspace.** Read [references/workspace.md](references/workspace.md),
+   then `video-edit-cli workspace init`. Done when `workspace.json` lists every
+   source with its hash.
+3. **Inspect the media.** `probe` every source; gather audio, proxies, frames,
+   filmstrips, waveforms, or range previews as decisions require. For dialogue
+   media read [references/transcription.md](references/transcription.md) and
+   transcribe first. Done when you know each source's duration, streams, and
+   content well enough to justify the plan you are about to form.
+4. **Plan and render.** Read [references/edit-plan.md](references/edit-plan.md)
+   before creating or modifying a plan; author the plan yourself, validate it,
+   and render a preview. Done when the validated plan renders and its manifest
+   exists.
+5. **Review and revise.** Read [references/cut-review.md](references/cut-review.md);
+   inspect every boundary of any render you produced. Done when each cut passes
+   or its defect is fixed or explicitly reported.
+6. **Finish the deliverable.** Done when every requested output exists, passes
+   its relevant validation, and your summary reports remaining defects honestly.
+
+## Branch references (read when the condition applies)
+
+- Audio cleanup/mastering requested, or analysis finds degraded speech →
+  [references/audio-restoration.md](references/audio-restoration.md)
+- Packaged deliverable (project profile, subtitles, assets, music, master
+  render) → [references/subtitles-and-assets.md](references/subtitles-and-assets.md)
+- Multiple synchronized visual/audio sources →
+  [references/multicamera.md](references/multicamera.md)
+- Vertical or short-form deliverable →
+  [references/vertical-video.md](references/vertical-video.md)

video_edit_cli-0.1.1/skills/video-editor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Video Editor"
+  short_description: "Inspect, edit, master, and package video"
+  default_prompt: "Use $video-editor to inspect and edit this media into a validated deliverable."

video_edit_cli-0.1.1/skills/video-editor/references/audio-restoration.md

@@ -0,0 +1,33 @@
+# Audio restoration and mastering
+
+Audio enhancement is adaptive: characterize first, then choose the lightest
+treatment that meets the request. Never apply neural restoration blindly, and
+always keep a mastering-only baseline candidate.
+
+1. **Characterize.** `video-edit-cli audio analyze --input <wav>` reports
+   integrated loudness, true peak, loudness range, clipping indicators, silence
+   spans, and a high-frequency-dropoff signal. Decide from these numbers whether
+   the recording is clean, noisy, clipped, or band-limited.
+2. **Baseline.** `video-edit-cli audio master --input <wav> --output <ws>/renders/mastered.wav`
+   applies the deterministic chain (highpass, gentle compression, two-pass
+   BS.1770 loudness normalization). Targets default to −16 LUFS / −1.5 dBTP;
+   take project targets from the external profile when one is supplied.
+3. **Denoise only when analysis or listening justifies it.**
+   `video-edit-cli audio denoise --input <wav> --output <ws>/renders/denoised.wav
+   --backend deepfilternet` (requires the `df` extra). Master the denoised
+   result too, so candidates differ only in restoration.
+4. **Compare at matched loudness.** `video-edit-cli audio compare --input <a>
+   --input <b> --output-dir <ws>/reports/ab` writes loudness-matched excerpts
+   plus metrics. Metrics rank candidates; they do not prove speech still sounds
+   natural — review the excerpts before choosing, and say which candidate you
+   chose and why.
+
+Invariants: intermediates stay lossless WAV (the commands enforce this);
+originals are never replaced; every processed file keeps its provenance
+sidecar naming backend, model, and parameters. If the recording is damaged
+beyond conservative treatment (heavy clipping, missing bandwidth), report the
+limitation rather than reaching for reconstruction that alters the voice.
+
+Completion: the delivered audio meets the requested loudness/true-peak targets
+(verify with `audio analyze`), the mastering-only baseline still exists as an
+artifact, and any denoising applied is justified in your summary.

video_edit_cli-0.1.1/skills/video-editor/references/cut-review.md

@@ -0,0 +1,26 @@
+# Cut review
+
+A render is unreviewed until every boundary has evidence. The loop is
+render → inspect → revise → re-render, repeated until each cut passes or its
+defect is explicitly reported.
+
+1. `video-edit-cli cuts list --manifest <render>.manifest.json` enumerates every
+   boundary with its output time and the source out/in times it joins.
+2. For each cut, `video-edit-cli cut inspect --manifest <manifest> --cut <i>
+   --output-dir <workspace>/reports --transcript <transcript.json>` produces a
+   filmstrip, waveform, short preview, before/after frames, and a report with
+   deterministic checks:
+   - `black_frames_near_cut` / `silence_near_cut` — timestamps flagged by
+     blackdetect/silencedetect in the review window.
+   - `clipped_word_before` / `clipped_word_after` — a transcript word whose span
+     straddles the cut point (pass `--transcript` whenever one exists).
+3. Judge the evidence yourself: look at the filmstrip and frames for visual
+   jumps, posture/continuity mismatches, or mid-gesture cuts, and play or
+   inspect the preview's waveform for audible bumps. `passed: true` means the
+   deterministic checks found nothing — it does not certify the cut feels right.
+4. Fix a defective cut by writing a revised plan (`parent_plan` set, adjusted
+   in/out times), re-rendering, and re-inspecting that boundary.
+
+Completion: every cut in the final render has a report in
+`<workspace>/reports/`, and each is either clean or explicitly listed as an
+unresolved defect when you present the result.

video_edit_cli-0.1.1/skills/video-editor/references/edit-plan.md

@@ -0,0 +1,39 @@
+# Edit plans
+
+A plan is an ordered keep-list compiled deterministically to FFmpeg: each
+timeline clip keeps `[in, out)` seconds of a source, in output order. Times come
+from transcript JSON or direct inspection — never estimated. The authoritative
+field reference is `video-edit-cli/src/video_editor/schemas/edit-plan.schema.json`;
+unknown fields fail validation.
+
+Minimal plan:
+
+```json
+{
+  "schema_version": "1",
+  "plan_id": "rough-cut-1",
+  "created_by": "<agent>",
+  "sources": [{"id": "src-1", "path": "/abs/path/recording.mp4"}],
+  "timeline": [
+    {"source": "src-1", "in": 0.5, "out": 42.1, "reason": "keep intro"},
+    {"source": "src-1", "in": 55.0, "out": 120.4, "reason": "false start removed at 42.1-55.0"}
+  ]
+}
+```
+
+Rules:
+
+- Every clip carries a `reason` — the editorial justification for what this keep
+  implies was removed. Write reasons a reviewer could audit.
+- Clips on the same source must be in increasing source order and must not
+  overlap; a plan that reorders or repeats source material is rejected.
+- Store plans in `<workspace>/plans/`, one file per revision; set `parent_plan`
+  when revising instead of editing a rendered plan in place.
+- `video-edit-cli plan validate --plan <file>` checks schema, references, ranges
+  against real media, and ordering; it also reports output duration and the cut
+  boundaries you must later inspect.
+- `video-edit-cli render preview --plan <file> --output <workspace>/previews/<name>.mp4`
+  renders the validated rough cut (360p default) and writes
+  `<output>.manifest.json` mapping every output-time boundary back to source
+  times — the input for cut review. Never present a render whose boundaries you
+  have not inspected.

video_edit_cli-0.1.1/skills/video-editor/references/multicamera.md

@@ -0,0 +1,25 @@
+# Multi-camera editing
+
+Applies when multiple synchronized (or synchronizable) recordings cover the
+same session — extra cameras, separate audio recorders, screen captures.
+
+1. **Synchronize first.** `video-edit-cli sync analyze --reference <a> --other <b>`
+   estimates the offset by audio correlation and reports candidates and a
+   confidence ratio; it never rewrites sources. Verify a low-confidence result
+   by inspecting waveforms around the claimed alignment before trusting it.
+2. **Apply explicitly.** `video-edit-cli sync apply --input <b> --offset <s>
+   --output <ws>/renders/b-aligned.mp4` (or a `.json` output for mapping
+   metadata only). All plan times then refer to the aligned timeline.
+3. **Relate sources to roles.** Record which source is which camera/mic in the
+   workspace `--role` labels; project camera aliases live in the external
+   profile, not here.
+4. **Choose cameras with evidence.** A clip's `video_source` selects the camera
+   while audio stays on the clip's `source`. Decide switches from transcript
+   context plus filmstrips of each candidate camera — check the speaker is
+   usable (framing, focus, reactions) on the camera you pick.
+5. **Review switches like cuts.** Every camera switch is a boundary in the
+   render manifest; inspect each with `cut inspect` for continuity (posture,
+   gaze, gesture) across the switch.
+
+Completion: sources verified aligned, every switch justified by inspected
+evidence, and the single-source path still used when only one camera is usable.

video_edit_cli-0.1.1/skills/video-editor/references/subtitles-and-assets.md

@@ -0,0 +1,32 @@
+# Packaging: profiles, subtitles, assets, master render
+
+Project identity — canvases, codecs, loudness targets, music, brand assets,
+fonts, subtitle style — lives in an external YAML project profile passed by
+path, never in the skill or your defaults. Without a profile you can still
+preview; a publishable master needs one.
+
+Order of operations for a packaged episode:
+
+1. **Validate the profile's assets.** `video-edit-cli asset inspect --input <file>`
+   for each intro/outro/music/font/image the profile references; loading the
+   profile also fails on missing files. Fix or report missing assets before
+   rendering.
+2. **Master render.** `video-edit-cli render master --plan <plan> --profile
+   <profile.yaml> --profile-name <name> --output <ws>/renders/<name>.mp4`
+   compiles the approved plan at the profile canvas/codec, mixes profile music
+   with speech-keyed ducking when declared, and normalizes loudness to the
+   profile targets. It writes the same boundary manifest as preview renders —
+   review cuts on the master too if timing changed.
+3. **Subtitles.** `video-edit-cli subtitles create --manifest <render manifest>
+   --transcript <transcript.json> --output-srt … --output-vtt …` maps transcript
+   words through the kept ranges into output time (removed ranges drop their
+   words). Transcripts must carry the plan's source id — pass `--source-id` at
+   `transcript create` time. Attach with `subtitles render` (`--mode mux`
+   default; `burn` requires an ffmpeg build with libass and fails cleanly
+   otherwise).
+4. **Validate the deliverable.** `video-edit-cli output validate --input <file>
+   --profile <profile.yaml> --profile-name <name> --expect-duration <s>
+   [--expect-subtitles --subtitles <srt>]` checks streams, canvas, frame rate,
+   duration, loudness/true peak, and subtitle timing. The command reports
+   `passed` with an issues list — the deliverable is not done until `passed`
+   is true or each issue is explicitly accepted by the user.

video_edit_cli-0.1.1/skills/video-editor/references/transcription.md

@@ -0,0 +1,31 @@
+# Transcription
+
+For dialogue media the transcript is the primary editing surface — but not the
+only one: reactions, gestures, camera usability, and continuity still need
+targeted visual inspection (frames, filmstrips, previews).
+
+Workflow:
+
+1. `video-edit-cli transcript create --input <audio-or-video> --output <ws>/analysis/transcript.json`
+   runs the local backend (default `mlx-whisper`; requires the `mlx` extra) and
+   writes the authoritative word-level JSON. Pass `--source-id` so the transcript
+   records which workspace source it describes. Transcribing the extracted
+   canonical WAV is faster than the full video.
+2. `transcript pack` derives a compact `[start-end] text` view sized for your
+   context. Read the packed view; treat the JSON as the source of truth for
+   times.
+3. `transcript search --query "<phrase>"` returns word-aligned start/end times
+   plus segment context. Use it to locate passages precisely instead of scanning.
+
+Rules:
+
+- Every editorial time you use must come from transcript JSON times or direct
+  media inspection — never estimate timestamps from memory of the packed view's
+  prose.
+- Transcript evidence is insufficient when the decision depends on what is
+  visible (reactions, demonstrations, camera choice) or on sound that is not
+  speech (music, noise, overlaps). Inspect the range visually/aurally before
+  deciding.
+- If transcription fails or the backend is unavailable, fall back to waveform +
+  filmstrip inspection and say so; do not pretend acoustic evidence equals
+  semantic understanding.

video_edit_cli-0.1.1/skills/video-editor/references/vertical-video.md

@@ -0,0 +1,26 @@
+# Vertical / short-form deliverables
+
+Applies when a vertical or short-form clip is requested. You choose the moment
+— from the transcript and targeted inspection — and the tools execute it; no
+command picks highlights.
+
+1. **Choose the range yourself.** Find candidate moments in the transcript
+   (hooks, self-contained arguments), confirm visually with filmstrips, and pick
+   exact word-aligned in/out times.
+2. **Frame explicitly.** Inspect a frame to decide the crop, then check it with
+   `video-edit-cli reframe preview --input <src> --start … --end …
+   --crop x:y:w:h --canvas 1080x1920`. Iterate until the speaker sits correctly
+   in the vertical frame.
+3. **Derive the plan.** `video-edit-cli short create-plan --input <src>
+   --start … --end … --canvas 1080x1920 --crop … --reason "…"
+   --output <ws>/plans/short-1.json` writes a normal, editable edit plan with
+   `output_canvas` set; refine it like any plan (split clips, adjust times).
+4. **Render and caption.** `render preview` honors the plan's canvas. Create
+   captions with `subtitles create` against the short's render manifest and
+   attach with `subtitles render`. Vertical viewers rely on captions — include
+   them unless told otherwise.
+5. **Validate.** `output validate --expect-duration … --expect-subtitles`
+   plus a filmstrip of the result to confirm framing survived.
+
+Completion: the short matches the requested canvas and duration, captions map
+correctly to the excerpt, and your summary states why this range was chosen.