@pixerate/editor 0.222.1 → 0.222.3

package/skills/pixerate-paint-watercolour/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: pixerate-paint-watercolour
+description: The watercolour workflow in the Pixerate paint editor - choosing the paper, planning light to dark and keeping the paper's white for highlights, wet-in-wet and wet-on-dry washes, letting water flow and drying before glazing, steering water with the wet tools, granulation, blooms and edge darkening, and finishing detail with a small brush. Use when asked to paint in watercolour or gouache, lay a wash, paint a sky, glaze, paint wet-in-wet, make blooms or granulation, or paint a loose or botanical watercolour, or when wet_paper, advance_wet_paint, dry_paint or set_wet_settings are available. Load with pixerate-paint-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-paint-editor
+---
+
+# Painting in watercolour
+
+Watercolour is transparent and it moves. Each wash lays water and pigment that keep flowing
+until they dry: edges darken, pigment settles into the paper's valleys, wet colours bleed into
+each other. Light comes from the paper, so you work light to dark and keep the white of the paper
+where you want highlights. A dried wash is fixed; the next one glazes over it. For an agent,
+time only passes when you call `advance_wet_paint` or `dry_paint`.
+
+This skill is the method. `pixerate-paint-editor` has the full tool reference and
+`references/wet-media.md` the engine's detail.
+
+## Goal and quality bar
+
+- The paper suits the piece: cold pressed for most work, rough for texture and granulation, hot
+  pressed for fine detail (`get_canvas_info` `paper.preset`).
+- Washes are even where they should be and soft where they should be; colours glow because
+  they are layered, not mixed to mud.
+- Highlights are the paper itself, not white paint (unless the user asks for gouache).
+- Every wash is dry before the next glaze over it (`get_wet_paint` `wet: false`), and the
+  painting is dry before export.
+
+## Inputs to confirm
+
+- **Subject and look:** loose and atmospheric (wet-in-wet) or crisp and detailed (wet-on-dry).
+- **Palette:** a few colours; `color_harmony` or `mix_colors` to plan.
+- **Highlights to keep white**, and where they are.
+
+## Working method
+
+1. **Ground.** `set_paper` with a watercolour preset (`cold-pressed`, `rough-watercolor`,
+   `hot-pressed`). Keep each pass on its own layer when you may want to change it (`add_layer`).
+   **Check:** `get_canvas_info` shows the paper.
+2. **Plan values light to dark** and where the paper stays white. Mix colours first
+   (`mix_colors` predicts the pigment mix; `add_swatch` keeps them).
+3. **First wash, lightest colour.** For soft skies and backgrounds, `wet_paper` the area first
+   (wet-in-wet); for crisp edges paint on dry paper. `set_brush` `watercolor-wash`, `set_color`,
+   then a few long `paint_stroke`s across the area, overlapping, avoiding the highlights.
+   **Check:** `get_wet_paint` shows the layer wet; `pick_color` inside is the colour you meant.
+4. **Let it move, then dry.** `advance_wet_paint` (`seconds` 1-5) to let it spread, bloom and
+   granulate; drop a second colour in while it is wet for soft blends. Then `dry_paint`.
+   **Check:** `get_wet_paint` `wet: false`.
+5. **Glaze.** Each further wash goes over a dry one, a little darker or another hue (blue over
+   yellow makes green). Paint only where it should deepen.
+   **Check:** `pick_color` where you glazed is darker; where you did not, unchanged.
+6. **Shapes, then details.** `watercolor-round` for shapes, `watercolor-detail` for lines and
+   details on dry paper, last.
+7. **Steer and fix while wet**: `blot` lifts paint (clouds, a highlight you lost), the
+   `add-water` tool softens an edge, `hair-dryer` stops a spread, `set_canvas_tilt` makes a wash
+   run, `set_wet_settings` tunes `granulation`, `edgeDarkening` and `bloom` for the layer.
+8. **Finish.** `dry_paint` everything; `render_preview` to look; export.
+
+## Decision table
+
+| Want | Approach |
+| --- | --- |
+| Soft sky, misty background | `wet_paper`, then `watercolor-wash`; drop colours in while wet |
+| Crisp shapes, hard edges with a dark rim | Paint on dry paper |
+| Deeper colour without mud | Dry, then glaze a second wash |
+| A white highlight | Leave the paper; or `blot` while wet to lift |
+| Light over dark | `gouache` (body 1) |
+| Grainy, textured washes | `rough-watercolor` paper and `granulation` up in `set_wet_settings` |
+| Fine lines and detail | `hot-pressed` paper, `watercolor-detail`, on dry paper |
+| Cauliflower blooms | Add water into a drying wash; `bloom` up |
+
+## Recipes
+
+**Flat wash.** `set_brush` `watercolor-wash` → `set_color` → one `paint_stroke` zigzagging
+across the area (rows about half the brush size apart) → `advance_wet_paint` `seconds` 2-5 →
+`dry_paint`.
+
+**Glaze.** On the dried wash, the same or a darker colour, painted only where it should deepen
+→ `dry_paint`. Repeat for more depth; three glazes are usually plenty.
+
+**Wet-in-wet sky.** `wet_paper` over the sky → blue wash along the top → while wet, a little
+warm colour near the horizon → `advance_wet_paint` → `blot` a few clouds → `dry_paint`.
+
+## Pitfalls
+
+- **Glazing on wet paint** mixes the two washes instead of layering them; dry first.
+- **Painting light over dark** does not work in transparent watercolour; plan the whites.
+- **Overworking**: many strokes over a wet wash lift and muddy it; lay it and leave it.
+- **Drawing-paper presets** (cartridge, smooth) do not behave like watercolour paper.
+- **Oil and watercolour on one layer**: a layer keeps the first medium's wet settings; use
+  separate layers.
+- **Nothing moves by itself** for an agent: without `advance_wet_paint` there is no flow, and
+  without `dry_paint` the next stroke paints into wet paint.
+
+## Tools used
+
+- `get_canvas_info`, `list_layers`, `render_preview`, `pick_color`: read the canvas and check colours
+- `list_papers`, `set_paper`: the watercolour ground
+- `add_layer`, `update_layer`: a layer per pass
+- `set_brush`, `set_color`, `mix_colors`, `color_harmony`, `add_swatch`: brush and palette
+- `paint_stroke`: washes, shapes and details, and the wet tools (water, dryer, blot)
+- `wet_paper`, `advance_wet_paint`, `dry_paint`, `get_wet_paint`: wet-in-wet, flow, drying and checking
+- `set_wet_settings`, `set_canvas_tilt`, `set_flow_map`: tune and steer the water
+- `undo_paint`: take back a step
+- `export_image`: deliver

package/skills/pixerate-paint-watercolour/evals/glaze-over-dry.json

@@ -0,0 +1,24 @@
+{
+	"prompt": "The blue wash on this sheet is dry. Glaze a second wash of the same blue over the left half to deepen it, without lifting or muddying the first one.",
+	"fixture": {
+		"editor": "paint",
+		"width": 64,
+		"height": 64,
+		"setup": [
+			{ "tool": "set_brush", "args": { "id": "watercolor-wash" } },
+			{ "tool": "set_color", "args": { "color": "#6fa8dc" } },
+			{ "tool": "paint_stroke", "args": { "points": [{ "x": 0, "y": 10 }, { "x": 64, "y": 10 }, { "x": 64, "y": 32 }, { "x": 0, "y": 32 }, { "x": 0, "y": 54 }, { "x": 64, "y": 54 }] } },
+			{ "tool": "dry_paint" }
+		]
+	},
+	"checks": [
+		{ "why": "a second watercolour wash", "tool": "list_strokes", "expect": { "total": 2, "strokes": { "$every": { "brushId": { "$in": ["watercolor-round", "watercolor-wash", "gradient-wash", "watercolor-detail"] } } } } },
+		{ "why": "the left half is deeper (darker) than the paper-side right", "tool": "pick_color", "args": { "x": 10, "y": 32 }, "expect": { "color": { "$expr": "(([r, g, b]) => 0.3 * r + 0.59 * g + 0.11 * b < 170 && b > r + 15)([1, 3, 5].map((i) => parseInt(v.slice(i, i + 2), 16)))" } } },
+		{ "why": "the glaze is dry, so it stays put", "tool": "get_wet_paint", "expect": { "wet": false } }
+	],
+	"solution": [
+		{ "tool": "get_wet_paint" },
+		{ "tool": "paint_stroke", "args": { "points": [{ "x": 2, "y": 12 }, { "x": 26, "y": 12 }, { "x": 26, "y": 32 }, { "x": 2, "y": 32 }, { "x": 2, "y": 52 }, { "x": 26, "y": 52 }] } },
+		{ "tool": "dry_paint" }
+	]
+}

package/skills/pixerate-paint-watercolour/evals/paper-and-brush-for-detail.json

@@ -0,0 +1,16 @@
+{
+	"prompt": "I want a detailed botanical study in watercolour with crisp, fine lines. Set up the paper for that and paint the thin stem with a small detail brush, a green line from (32, 60) up to (32, 20).",
+	"fixture": { "editor": "paint", "width": 64, "height": 64 },
+	"checks": [
+		{ "why": "smooth hot-pressed paper for fine detail", "tool": "get_canvas_info", "expect": { "paper": { "preset": "hot-pressed" } } },
+		{ "why": "a fine watercolour detail brush", "tool": "list_strokes", "expect": { "strokes": { "$some": { "brushId": "watercolor-detail" } } } },
+		{ "why": "a green stem", "tool": "pick_color", "args": { "x": 32, "y": 40 }, "expect": { "color": { "$expr": "(([r, g, b]) => g > r + 10 && g > b)([1, 3, 5].map((i) => parseInt(v.slice(i, i + 2), 16)))" } } }
+	],
+	"solution": [
+		{ "tool": "set_paper", "args": { "preset": "hot-pressed" } },
+		{ "tool": "set_brush", "args": { "id": "watercolor-detail" } },
+		{ "tool": "set_color", "args": { "color": "#3f7d3a" } },
+		{ "tool": "paint_stroke", "args": { "points": [{ "x": 32, "y": 60 }, { "x": 32, "y": 40 }, { "x": 32, "y": 20 }] } },
+		{ "tool": "dry_paint" }
+	]
+}

package/skills/pixerate-paint-watercolour/evals/sky-wash.json

@@ -0,0 +1,19 @@
+{
+	"prompt": "Paint a flat light-blue sky wash across the top third of the sheet in watercolour, and let it dry before anything else goes on.",
+	"fixture": { "editor": "paint", "width": 64, "height": 64, "setup": [{ "tool": "set_paper", "args": { "preset": "cartridge" } }] },
+	"checks": [
+		{ "why": "on watercolour paper", "tool": "get_canvas_info", "expect": { "paper": { "preset": { "$in": ["cold-pressed", "hot-pressed", "rough-watercolor"] } } } },
+		{ "why": "painted with a watercolour brush", "tool": "list_strokes", "expect": { "strokes": { "$length": { "$min": 1 }, "$every": { "brushId": { "$in": ["watercolor-round", "watercolor-wash", "gradient-wash", "watercolor-detail"] } } } } },
+		{ "why": "the sky is blue", "tool": "pick_color", "args": { "x": 32, "y": 6 }, "expect": { "color": { "$expr": "(([r, g, b]) => b > r + 15)([1, 3, 5].map((i) => parseInt(v.slice(i, i + 2), 16)))" } } },
+		{ "why": "the wash is dry", "tool": "get_wet_paint", "expect": { "wet": false } }
+	],
+	"solution": [
+		{ "tool": "set_paper", "args": { "preset": "cold-pressed" } },
+		{ "tool": "set_brush", "args": { "id": "watercolor-wash" } },
+		{ "tool": "set_color", "args": { "color": "#6fa8dc" } },
+		{ "tool": "paint_stroke", "args": { "points": [{ "x": 0, "y": 6 }, { "x": 64, "y": 6 }, { "x": 64, "y": 14 }, { "x": 0, "y": 14 }] } },
+		{ "tool": "advance_wet_paint", "args": { "seconds": 3 } },
+		{ "tool": "dry_paint" },
+		{ "tool": "get_wet_paint" }
+	]
+}

package/skills/pixerate-video-colour-grade/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: pixerate-video-colour-grade
+description: The colour grading workflow in the Pixerate video editor - correcting each shot first (exposure, contrast, white balance) so a scene matches, then one look over the whole piece on an adjustment clip, LUTs at a sensible strength with skin tones protected, masks for spot changes, and checking with scopes and frames. Use when asked to colour correct, colour grade, match shots, fix exposure or white balance in a video, add a look, a LUT, a film or cinematic look, warm or cool a video, or protect skin tones, or when update_video_clip grade, add_video_adjustment_clip, set_video_lut or get_video_scopes are available. Load with pixerate-video-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-video-editor
+---
+
+# Grading a video
+
+A grade has two passes. **Correction** makes each shot right and makes shots in a scene match:
+exposure, contrast and white balance on the clip's own `grade`. **The look** is one creative
+decision over everything: an adjustment clip above the timeline with its own grade or a LUT,
+so it is changed in one place. Faces are the reference: people notice skin that is wrong before
+anything else.
+
+This skill is the method. `pixerate-video-editor` has the full tool reference.
+
+## Goal and quality bar
+
+- Shots in a scene match in brightness and colour; cuts between them do not jump.
+- Corrections are moderate: exposure within about ±1 stop, contrast and saturation within
+  ±0.3, white balance within ±0.3, unless a shot is badly off.
+- One look, in one place: an adjustment clip over the whole timeline (or one per scene), not
+  the same settings pasted on every clip.
+- Skin stays natural under strong looks (skin protection 0.5-0.8 on LUTs).
+- The original corrections are not overwritten by the look.
+
+## Inputs to confirm
+
+- **The look:** natural, warm, cool, desaturated, high contrast, a named LUT; or a reference.
+- **Which shot is the reference** for matching (the best-exposed, or the one the user likes).
+- **Where the LUT file is** (a `.cube` path or URL the host can load).
+
+## Working method
+
+1. **Read.** `get_video_project` for clips and their `grade`; where the host has a preview,
+   `get_video_scopes` at a frame of each shot reads levels and colour in numbers.
+   **Check:** you know which shots are off and by how much.
+2. **Correct the reference shot** (`update_video_clip` `set.grade`): exposure first, then
+   contrast, then white balance (`temperature`, `tint`). The grade object replaces the clip's
+   whole grade, so pass every setting you want to keep.
+3. **Match the others to it.** A shot one stop under gets `exposure: 1`; a cooler shot more
+   `temperature`. `copy_video_grade` when shots from one camera setup need the same correction;
+   `apply_video_grade_preset` for a common starting point.
+   **Check:** the clip `grade` values; scopes or `get_video_frame` at both sides of each cut.
+4. **The look over everything.** `add_video_track` at the top (`at: 0`) and
+   `add_video_adjustment_clip` on it from 0 for the whole duration with the look's `grade`
+   (`scope: "underneath"`).
+   **Check:** one adjustment clip covering the timeline; media clips keep their corrections.
+5. **LUTs.** `set_video_lut` with `strength` 0.3-0.7 for a look (1 only for a technical
+   conversion LUT) and skin protection (`preserve_skin_tones: 0.7`, 0.5-0.8) when people are on screen;
+   `set_video_skin_protection` to change the protection later.
+   **Check:** each clip's `grade.lut` has the strength and protection you meant.
+6. **Spot changes.** `set_video_clip_mask` on a duplicate clip or an adjustment clip for a sky,
+   a face or a vignette.
+7. **Review.** `render_video_frame` with `times` across the piece for a contact sheet; fix any
+   shot that stands out.
+
+## Decision table
+
+| Problem | Fix |
+| --- | --- |
+| Shot too dark or bright | `grade.exposure` in stops (+1 doubles the light) |
+| Flat, low contrast | `grade.contrast` +0.1-0.3 |
+| Blue or orange cast | `grade.temperature` against it |
+| Green or magenta cast | `grade.tint` against it |
+| Same correction on many shots from one setup | `copy_video_grade` |
+| One look for the whole piece | Adjustment clip on a top track |
+| A LUT look | `set_video_lut`, strength 0.3-0.7 |
+| Faces off under the look | Skin protection 0.5-0.8 (`set_video_lut` or `set_video_skin_protection`), or lower the strength |
+| Change only part of the frame | `set_video_clip_mask` |
+
+## Recipes
+
+**Match an underexposed shot.** `update_video_clip` `{ clip, set: { grade: { exposure: 1 } } }`
+for one stop under; check with scopes or frames on both sides of the cut.
+
+**Warm, slightly desaturated look.** `add_video_track` `{ kind: "video", at: 0 }` →
+`add_video_adjustment_clip` `{ track, start: 0, duration: <project duration>, grade:
+{ temperature: 0.2, saturation: -0.15 } }`.
+
+**Tame a LUT.** `set_video_lut` `{ clips, src, strength: 0.6, preserve_skin_tones: 0.7 }`.
+
+## Pitfalls
+
+- **Grading before correcting.** A look over unmatched shots makes the mismatch stronger.
+- **Partial grade objects.** `set.grade` replaces the whole grade; read it first and include
+  the settings you keep.
+- **The look on every clip.** Pasting it per clip means every change is many edits; use an
+  adjustment clip.
+- **Full-strength creative LUTs** turn faces orange or green and crush detail.
+- **ffmpeg and skin protection.** The export's `lut3d` cannot protect skin; the export notes
+  it, and the preview differs from the file. Lower the strength when that matters.
+- **Judging on one frame.** Check several frames per shot; light changes within shots.
+
+## Tools used
+
+- `get_video_project`, `get_video_scopes`, `get_video_frame`, `render_video_frame`: read grades, measure and look
+- `update_video_clip`: each shot's correction (`set.grade`)
+- `copy_video_grade`, `apply_video_grade_preset`: match and start from a preset
+- `add_video_track`, `add_video_adjustment_clip`: one look over the timeline
+- `set_video_lut`, `remove_video_lut`, `set_video_skin_protection`: LUT looks and skin
+- `set_video_clip_mask`, `remove_video_clip_mask`: spot changes
+- `undo_video`: take back a step

package/skills/pixerate-video-colour-grade/evals/look-in-one-place.json

@@ -0,0 +1,16 @@
+{
+	"prompt": "Give the whole piece a warm, slightly desaturated look that I can tweak in one place later, on top of the shot corrections.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "a", "kind": "video", "src": "shot-a.mp4", "duration": 8000 } },
+			{ "tool": "add_video_asset", "args": { "id": "b", "kind": "video", "src": "shot-b.mp4", "duration": 8000 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "a", "id": "c1", "start": 0, "duration": 6000 } } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "b", "id": "c2", "start": 6000, "duration": 6000 } } }] },
+	"checks": [
+		{ "why": "one adjustment clip over the whole timeline", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "adjustment", "start": 0, "duration": { "$min": 12000 } } } } } } },
+		{ "why": "warm and a little desaturated", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "adjustment", "grade": { "temperature": { "$min": 0.05, "$max": 0.5 }, "saturation": { "$min": -0.4, "$max": -0.02 } } } } } } } },
+		{ "why": "the shots' own grades are left alone", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$expr": "v.filter((c) => c.type === 'media').every((c) => !c.grade)" } } } } }
+	],
+	"solution": [
+		{ "tool": "add_video_track", "args": { "kind": "video", "id": "v0", "at": 0 } },
+		{ "tool": "add_video_adjustment_clip", "args": { "track": "v0", "start": 0, "duration": 12000, "grade": { "temperature": 0.2, "saturation": -0.15 } } }
+	]
+}

package/skills/pixerate-video-colour-grade/evals/lut-keep-skin.json

@@ -0,0 +1,132 @@
+{
+	"prompt": "The teal-and-orange LUT on both shots is too strong and turns the faces orange. Tone the look down to a moderate strength and keep the skin tones natural.",
+	"fixture": {
+		"editor": "video",
+		"setup": [
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "a",
+					"kind": "video",
+					"src": "shot-a.mp4",
+					"duration": 8000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "b",
+					"kind": "video",
+					"src": "shot-b.mp4",
+					"duration": 8000
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "a",
+						"id": "c1",
+						"start": 0,
+						"duration": 6000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "b",
+						"id": "c2",
+						"start": 6000,
+						"duration": 6000
+					}
+				}
+			},
+			{
+				"tool": "set_video_lut",
+				"args": {
+					"clips": [
+						"c1",
+						"c2"
+					],
+					"src": "data:text/plain,TITLE%20%22Teal%20orange%22%0ALUT_3D_SIZE%202%0A0%200.1%200.1%0A1%200.5%200.2%0A0%201%200.9%0A1%201%200.6%0A0%200.2%201%0A1%200.4%200.9%0A0%201%201%0A1%201%201%0A",
+					"strength": 1
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the LUT is still on both shots, at a moderate strength",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"clips": {
+							"$length": 2,
+							"$every": {
+								"grade": {
+									"lut": {
+										"src": {
+											"$match": "^data:"
+										},
+										"strength": {
+											"$min": 0.3,
+											"$max": 0.85
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "skin tones protected",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"clips": {
+							"$every": {
+								"grade": {
+									"lut": {
+										"preserveSkinTones": {
+											"$min": 0.4
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "get_video_project"
+		},
+		{
+			"tool": "set_video_lut",
+			"args": {
+				"clips": [
+					"c1",
+					"c2"
+				],
+				"src": {
+					"$read": "get_video_project",
+					"path": "tracks.0.clips.0.grade.lut.src"
+				},
+				"strength": 0.6,
+				"preserve_skin_tones": 0.7
+			}
+		}
+	]
+}

package/skills/pixerate-video-colour-grade/evals/match-exposure.json

@@ -0,0 +1,14 @@
+{
+	"prompt": "Shot two (c2) was filmed one stop underexposed compared with shot one. Match it to shot one without touching shot one.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "a", "kind": "video", "src": "shot-a.mp4", "duration": 8000 } },
+			{ "tool": "add_video_asset", "args": { "id": "b", "kind": "video", "src": "shot-b.mp4", "duration": 8000 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "a", "id": "c1", "start": 0, "duration": 6000 } } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "b", "id": "c2", "start": 6000, "duration": 6000 } } }] },
+	"checks": [
+		{ "why": "c2 brought up by about one stop", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "id": "c2", "grade": { "exposure": { "$min": 0.8, "$max": 1.2 } } } } } } } },
+		{ "why": "shot one is untouched", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "id": "c1", "$expr": "!v.grade || Object.values(v.grade).every((x) => x === 0)" } } } } } }
+	],
+	"solution": [
+		{ "tool": "update_video_clip", "args": { "clip": "c2", "set": { "grade": { "exposure": 1 } } } }
+	]
+}

package/skills/pixerate-video-editor/SKILL.md

@@ -33,6 +33,9 @@ the pitfalls, and uses the tools below.
 
 - `pixerate-talking-head-edit`: dialogue cleanup by transcript: fillers, pauses, stutters.
 - `pixerate-bgm-alignment`: cutting to the beat, ducking music under speech, loudness.
+- `pixerate-video-social-cut`: vertical reframes, the hook first, platform lengths, titles in the safe area.
+- `pixerate-video-colour-grade`: correct and match shots, one look on an adjustment clip, LUTs and skin.
+- `pixerate-video-montage`: selects on the beat, pacing, transitions, music and the ending.
 
 ## Working method
 

package/skills/pixerate-video-montage/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: pixerate-video-montage
+description: The montage workflow in the Pixerate video editor - choosing selects and their best moments, assembling them on beats or a rhythm, varying shot length for pacing, cutting on action, short transitions where they help, music under the whole sequence, and a clean start and end. Use when asked to make a montage, a highlight reel, a sizzle reel, a recap, a music video edit, a slideshow of clips or photos, or to cut a set of clips to music or a rhythm, or when edit_video, add_video_marker, set_video_transition or find_video_gaps are available. Load with pixerate-video-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-video-editor
+---
+
+# Cutting a montage
+
+A montage tells its story through rhythm: the best moment of each shot, in an order that
+builds, cut to a beat. The work is choosing (selects and their best seconds), then placing
+(on the beat, with shot lengths that breathe and quicken), then finishing (transitions only
+where they help, music under everything, a clear ending).
+
+This skill is the method. `pixerate-video-editor` has the full tool reference; for beats in a
+music track and cutting to them, see `pixerate-bgm-alignment`.
+
+## Goal and quality bar
+
+- Each shot is its best moment: taken from the middle of the action, not its first frames
+  (`in` past the camera's settle).
+- Cuts land on beats or on action, on frame boundaries, with no gaps (`find_video_gaps` empty).
+- Pacing varies: longer shots to establish, shorter to build, a held shot to land.
+- Straight cuts by default; short crossfades (300-600 ms) or dips only for a reason (time
+  passing, a change of section), each with enough media on both sides (no handle errors).
+- Music runs under the whole sequence and ends with it (a fade out or a musical ending), and
+  the picture ends cleanly (a fade to black or a held final frame).
+
+## Inputs to confirm
+
+- **Selects and order:** which clips, in what order (story, chronology, energy).
+- **Rhythm:** music with beats, markers, or a shot length (e.g. 1 s per shot).
+- **Length** of the finished piece.
+
+## Working method
+
+1. **Read.** `get_video_project`: assets (with durations), markers (beats), music.
+   With music, `find_video_beats` (`pixerate-bgm-alignment`) marks the beats.
+   **Check:** you have a beat grid or a shot length, and each select's usable range.
+2. **Pick the moments.** For each select, the `in` point of its best stretch (skip the first
+   second or two, where the camera settles).
+3. **Assemble in one batch.** `edit_video` with one add-clip op per shot (`asset`, `id`, `in`,
+   `start` on a beat, `duration` to the next beat), `dry_run: true` first.
+   **Check:** the clips are in order, each `start` on a beat; `find_video_gaps` is empty.
+4. **Refine the rhythm.** `roll_video_edit` to move a cut to a beat or onto action without
+   shifting anything else; `slip_video_clip` to change what a shot shows without moving it.
+   Vary lengths: build up with shorter shots before the peak.
+5. **Transitions, sparingly.** `set_video_transition` `crossfade` 300-600 ms (or `dip` for a
+   section change); every type but dip needs half its length in media past the cut on both sides.
+   **Check:** `check_video_project` has no errors.
+6. **Music and ending.** The music clip on an audio track from 0 for the whole duration, with a
+   `fadeOut` of 1-3 s (or cut on its last beat); the last picture clip `fadeOut` 300-1000 ms to
+   black.
+   **Check:** `get_video_project` shows both, ending together.
+7. **Review.** `render_video_frame` with `times` at each cut for a contact sheet; watch the
+   rhythm in the preview where available.
+
+## Decision table
+
+| Want | Approach |
+| --- | --- |
+| Energy, a build | Shorter shots toward the peak, cuts on every beat |
+| Calm, reflective | Longer shots, cuts every 2-4 beats, crossfades |
+| Time passing | Crossfade or dip between shots |
+| A section change | Dip to black or a held shot, then a new rhythm |
+| Continuity of motion | Cut on action (`roll_video_edit` onto the movement) |
+| Photos in a slideshow | Image assets, a slow push-in (`set_video_keyframes` scale 1 to 1.08) |
+
+## Recipes
+
+**On the beat.** Beats every `b` ms from 0: `edit_video` with `{ op: "add_clip", track: "v1", clip:
+{ type: "media", asset, id, in, start: k * b, duration: b } }` for each shot `k`; then `find_video_gaps`.
+
+**Crossfades.** `edit_video` with `{ op: "set_transition", clip, transition: { type: "crossfade",
+duration: 400 } }` for every clip after the first; then `check_video_project`.
+
+**Music and fade-out.** `add_video_clip` on the audio track `{ type: "media", asset: music,
+start: 0, duration: <sequence>, fadeOut: 2000 }`; `update_video_clip` on the last shot
+`{ set: { fadeOut: 500 } }`.
+
+## Pitfalls
+
+- **First frames of a clip** are often the camera settling; take `in` later.
+- **Transitions everywhere** soften the rhythm and look dated; cut straight by default.
+- **Missing handles.** A transition needs media past the cut on both sides; trimmed-to-the-edge
+  clips fail `check_video_project`.
+- **Music that stops dead** at the end of the picture; fade it or end on a musical phrase.
+- **Uniform shot lengths** for a long montage feel mechanical; vary them.
+
+## Tools used
+
+- `get_video_project`, `find_video_gaps`, `check_video_project`, `render_video_frame`: read and check
+- `add_video_marker`: beats and sections
+- `edit_video`, `add_video_clip`: assemble in one batch
+- `roll_video_edit`, `slip_video_clip`, `trim_video_clip`, `close_video_gaps`: refine the rhythm
+- `set_video_transition`: crossfades and dips
+- `update_video_clip`, `set_video_keyframes`: fades, volume and push-ins
+- `undo_video`: take back a step