goatedit-mcp 1.1.18 → 1.1.20

package/bundle/goatedit-mcp.js

@@ -20269,7 +20269,7 @@ var BASE_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        url: str("Publicly reachable https URL of the video, audio or image, or a `magnific:<id>` url from search_stock."),
+        url: str("Publicly reachable https URL of the video, audio or image, a `magnific:<id>` url from search_stock, or an `sfx:<id>` url from search_sfx."),
         name: str("Display name for the bin."),
         type: { type: "string", enum: ["video", "audio", "image"], description: "Kind of media." },
         duration: num("Duration in seconds. Required for video and audio, but treated as a hint \u2014 the probe on import overrides it when they disagree."),
@@ -20503,7 +20503,7 @@ var BASE_TOOLS = [
   },
   {
     name: "set_camera",
-    description: 'One camera for the whole sequence. While it is on screen, every clip switched to 3D (set_clip_effect type "layer3d") is seen through it, so a dolly, truck, pan, orbit, zoom or rack focus moves them all together, each by its own depth: near layers slide past far ones. 3D model clips (.glb) are seen through it too: moved, sized and turned, with any 3D layer parented to them. 2D layers ignore it. At rest it changes nothing (layers at posZ 0 draw 1:1), so build the layout flat, push layers back with layer3d posZ (1080p px, bigger is farther), then move the camera. Creates the camera if the sequence has none (spanning the sequence unless startTime/duration say otherwise); call again to change it. 3D layers and models stack by depth while the camera is on, whatever their tracks; a 2D layer between them in the stack keeps its place and splits them (the reply warns).',
+    description: 'One camera for the whole sequence. While it is on screen, every clip switched to 3D (set_clip_effect type "layer3d") is seen through it, so a dolly, truck, pan, orbit, zoom or rack focus moves them all together, each by its own depth: near layers slide past far ones. 3D model clips (.glb) are seen through it too: moved, sized and turned, with any 3D layer parented to them. 2D layers ignore it. At rest it changes nothing (layers at posZ 0 draw 1:1), so build the layout flat, push layers back with layer3d posZ (1080p px, bigger is farther), then move the camera. Creates the camera if the sequence has none (spanning the sequence unless startTime/duration say otherwise); call again to change it. 3D layers and models stack by depth while the camera is on, whatever their tracks; a 2D layer between them in the stack keeps its place and splits them (the reply and lint_timeline warn). Give a backdrop layer3d param fill: 1 and it grows just enough to cover the frame for the whole camera move.',
     inputSchema: {
       type: "object",
       properties: {
@@ -21106,7 +21106,7 @@ var BASE_TOOLS = [
   },
   {
     name: "set_keyframes",
-    description: "Animate one property of a clip over time. set_clip_transform sets a value; this is what makes it move \u2014 a card sliding on, a background drifting, a photo pushing in. Times are in seconds RELATIVE TO THE CLIP's start, and each keyframe may carry its own outgoing easing as a CSS cubic-bezier ([0.22, 1, 0.36, 1] is a good decelerate). Two or more keyframes make motion; one holds a value. Writing keyframes for a property overrides whatever flat value the clip carries for it, and replaces any track already on that property \u2014 pass clear to remove one.",
+    description: "Animate one property of a clip over time. set_clip_transform sets a value; this is what makes it move \u2014 a card sliding on, a background drifting, a photo pushing in. Times are in seconds RELATIVE TO THE CLIP's start, and each keyframe may carry its own outgoing easing as a CSS cubic-bezier ([0.22, 1, 0.36, 1] is a good decelerate). Two or more keyframes make motion; one holds a value. Writing keyframes for a property overrides whatever flat value the clip carries for it, and replaces any track already on that property \u2014 pass clear to remove one. Pass expression to drive it with a formula, from time or from another layer (keyframes are then optional).",
     inputSchema: {
       type: "object",
       properties: {
@@ -21140,16 +21140,26 @@ var BASE_TOOLS = [
             "cropRight",
             "cropBottom",
             "cropRadius",
-            "cropFeather"
+            "cropFeather",
+            "shapeWidth",
+            "shapeHeight",
+            "shapeCornerRadius",
+            "shapeStrokeWidth",
+            "shapeDash",
+            "shapeGap"
           ],
-          description: "Property to animate. posX/posY and opacity are 0..1 fractions, rotation is degrees, scaleX/scaleY are multipliers (1 = unchanged), pathTrimEnd 0\u21921 draws a pen stroke on, textPathOffset slides text along its path (0..1) and textPathWave is the height of the wave bending it (px @1080p). cropLeft/Top/Right/Bottom are 0..1 of the layer cut from that side (set_mask crop sets them once), cropRadius rounds the crop's corners and cropFeather softens its edge, both px @1080p."
+          description: "Property to animate. posX/posY and opacity are 0..1 fractions, rotation is degrees, scaleX/scaleY are multipliers (1 = unchanged), pathTrimEnd 0\u21921 draws a pen stroke on, textPathOffset slides text along its path (0..1) and textPathWave is the height of the wave bending it (px @1080p). cropLeft/Top/Right/Bottom are 0..1 of the layer cut from that side (set_mask crop sets them once), cropRadius rounds the crop's corners and cropFeather softens its edge, both px @1080p. shapeWidth/shapeHeight/shapeCornerRadius/shapeStrokeWidth/shapeDash/shapeGap animate a shape layer in its own px @1080p (a square or circle needs width and height keyed together)."
         },
         keyframes: {
           type: "array",
           description: "The track, as [{ time, value, ease?, hold? }]. `time` is seconds from the clip's start, `ease` is four numbers (cubic-bezier control points) applied on the way to the NEXT keyframe, and `hold: true` freezes the value until the next one instead of interpolating.",
           items: { type: "object" }
         },
-        clear: bool("Remove this property's keyframes instead of setting them, leaving the clip's flat value in charge again.")
+        clear: bool("Remove this property's keyframes instead of setting them, leaving the clip's flat value in charge again."),
+        expression: {
+          type: "string",
+          description: `An After-Effects-style expression that drives the property instead (keyframes still feed it as \`value\`); "" removes it. A math-only language: numbers, value, time (seconds from this clip's start), duration, index (this layer's number, top track first), Math.*, wiggle(freq, amp), random(a, b), noise(t), clamp, linear(t, tMin, tMax, v1, v2), ease(...same), valueAtTime(t), loopOut("cycle"|"pingpong"|"offset"|"continue", n?), loopIn(...), thisLayer.<prop>, and layer("Name").<prop> or layer(2).<prop> (optionally .valueAtTime(t)), read at the same moment of the timeline. Rigs: a null named "Controls" whose posX drives others via layer("Controls").posX * 100; scaleY = thisLayer.scaleX; a stagger with valueAtTime(time - (index - 1) * 0.08); a looping bob with keyframes plus loopOut("pingpong"). Props use this tool's units (posX 0..1, rotation degrees).`
+        }
       },
       required: ["clipId", "prop"]
     },
@@ -21164,7 +21174,7 @@ var BASE_TOOLS = [
         clipId: CLIP_ID,
         type: {
           type: "string",
-          description: "Effect type: blur, invert, hue, saturation, brightness, contrast, exposure, grayscale, sepia, gradientMap, vignette, filmGrain, flicker, posterizeTime, lensDistortion, chromaticAberration, lensFlare, liquidGlass, opacityFx, colorCorrection, depthMap, gradientMap, vegas, glow, pixelDissolve, motionBlur, dropShadow, reflection, colorama, outline, echo, flutedGlass, lightRays, halftone, datamosh, roughenEdges, filmStock, halation, starGlow, filmDamage, lightLeak, thermal, colorBalance, duotone, levels, monochrome, channelMixer, dither, threshold, fourColorGradient, lensBlur, boxBlur, directionalBlur, spinBlur, zoomBlur, sharpen, cameraShake, bulge, twirl, ripple, waveWarp, polarCoords, turbulentDisplace, elasticGrid, gridSplit, cubify, glitch, vhs, ntsc, crtScreen, ledScreen, rgbSplit, jpegGlitch, ascii, macpaint, modulation, stripe, risograph, emboss, bevel, inkBleed, paperTexture, paperCutout, crossHatch, scatter, blobTracker, edgeGlow, pageTurn, lightSweep, deepGlow, twister, fill, compositeOriginal, grid, repeater, plus transform, layer3d, camera3d (on a camera clip; use set_camera), model3d and showcase. Call describe_effect with a type for its parameters, their ranges and what they do before setting anything but the obvious. An unknown name comes back with the full list."
+          description: "Effect type: blur, invert, hue, saturation, brightness, contrast, exposure, grayscale, sepia, gradientMap, vignette, filmGrain, flicker, posterizeTime, lensDistortion, chromaticAberration, lensFlare, liquidGlass, opacityFx, colorCorrection, depthMap, depthParticles, gradientMap, vegas, glow, pixelDissolve, motionBlur, dropShadow, reflection, colorama, outline, echo, flutedGlass, lightRays, halftone, datamosh, roughenEdges, filmStock, halation, starGlow, filmDamage, lightLeak, thermal, colorBalance, duotone, levels, monochrome, channelMixer, dither, threshold, fourColorGradient, lensBlur, boxBlur, directionalBlur, spinBlur, zoomBlur, sharpen, cameraShake, bulge, twirl, ripple, waveWarp, polarCoords, turbulentDisplace, elasticGrid, gridSplit, cubify, glitch, vhs, ntsc, crtScreen, ledScreen, rgbSplit, jpegGlitch, ascii, macpaint, modulation, stripe, risograph, emboss, bevel, inkBleed, paperTexture, paperCutout, crossHatch, scatter, blobTracker, edgeGlow, pageTurn, lightSweep, deepGlow, twister, fill, compositeOriginal, grid, repeater, plus transform, layer3d, camera3d (on a camera clip; use set_camera), model3d and showcase. Call describe_effect with a type for its parameters, their ranges and what they do before setting anything but the obvious. An unknown name comes back with the full list."
         },
         params: {
           type: "object",
@@ -21354,6 +21364,24 @@ var BASE_TOOLS = [
     },
     method: "searchStock"
   },
+  {
+    name: "search_sfx",
+    description: 'Search GoatEdit\'s sound effect library: originals made by GoatEdit (pops, clicks, whooshes, swishes, risers, thuds, pings, chimes, shine, glitch, typing, page flips, shutter, blips) real CC0 recordings from Freesound (keyboards, paper, whooshes, risers, impacts, shutters, cash register) and Kenney\'s CC0 packs (UI sounds, impacts, power-ups, sci-fi). Every sound is free to use and to export, with no credit owed. Each result carries a `use` line saying which on-screen moment it is for \u2014 pick by that, never by guessing a filename. Bring one in by passing its `url` (sfx:<id>) and `name` to add_media_file (type "audio"), then place it with insert_clip on the sound-effects track (set_audio_master tags a track "sfx"), starting about two frames before the visual it belongs to. It comes in at -16 dB (clip volume 0.16), under the voice; leave that unless it is lost or too loud. Only on visible actions; vary the variant on repeated items.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: str('What happens on screen or the sound wanted, e.g. "card lands", "whoosh", "notification".'),
+        category: {
+          type: "string",
+          enum: ["pop", "click", "whoosh", "riser", "impact", "notify", "success", "error", "shine", "glitch", "typing", "paper", "camera", "tech"],
+          description: "Only this kind of sound."
+        },
+        limit: num("How many results. Defaults to 12, at most 40.")
+      },
+      required: ["query"]
+    },
+    method: "searchSfx"
+  },
   {
     name: "create_html_clip",
     description: "Place a CSS-animated HTML snippet on the timeline as a clip. This is the way to get motion that is miserable to keyframe and trivial in CSS: drifting mesh gradients, dot grids, typing input fields, tickers, pulsing badges, UI mock-ups. It renders deterministically \u2014 every animation is paused and seeked per frame \u2014 so the export is frame-identical to the preview, and the clip transforms, fades and keyframes like any other. Prefer CSS or WAAPI animation: a snippet carrying a script or a <video> renders through the costlier sandbox pipeline, and an <iframe> cannot be rasterised at all. Knobs declared as --custom-properties on :host can be overridden per clip through `vars`. Author against the clip box: it is `width` x `height` (defaulting to the project frame), and `100vw`/`100vh` mean exactly that box, not the browser window. Media queries, however, still see the editor window \u2014 size with the units, not with breakpoints. Reference images and footage through `slots` rather than inlining them; the result lists the available slot ids.",
@@ -21387,6 +21415,23 @@ var BASE_TOOLS = [
     },
     method: "addHtmlClip"
   },
+  {
+    name: "update_html_clip",
+    description: "Change an HTML clip made with create_html_clip in place: new markup, some of its --custom-property `vars`, its `slots`, or its render size. The clip keeps its id, position, keyframes, parent and effects \u2014 revise a snippet with this, never by removing and re-creating it. `vars` and `slots` merge over the current values, so pass only what changes. New `html` clears slot overrides (slot ids are element order) unless `slots` is given in the same call. Every clip playing the same snippet changes with it; the reply says how many.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        clipId: str("The HTML clip."),
+        html: str("Replacement markup, with its <style> inline."),
+        vars: { type: "object", description: 'CSS custom properties to change, e.g. { "--accent": "#ff5a1f" }. Merged over the current ones.' },
+        slots: { type: "object", description: "Slot fills to change, keyed by slot id, as in create_html_clip. Merged over the current ones." },
+        width: num("New render width in pixels."),
+        height: num("New render height in pixels.")
+      },
+      required: ["clipId"]
+    },
+    method: "updateHtmlClip"
+  },
   {
     name: "add_transition",
     description: 'Put a transition on a clip. edge "in" (the default) is the clip\'s start: mixed with the clip before it on the same track \u2014 transitions between two shots belong to the incoming clip, so pass the id of the SECOND shot \u2014 or, with nothing before it, transitioned in over whatever is below from its first frame. edge "out" is the clip\'s end: its last `duration` seconds take it out to whatever is below (the entrance played backwards for moves, a fade for dissolves) \u2014 for a clip that ends over a gap, the background or lower layers. A duration that does not fit is refused rather than silently ignored.',
@@ -21887,6 +21932,7 @@ var SEQUENCE_EDITS = /* @__PURE__ */ new Set([
   "setClipEffect",
   "setTextAnimation",
   "addHtmlClip",
+  "updateHtmlClip",
   "setColorGrade",
   "setClipDenoise",
   "addTransition",
@@ -21912,7 +21958,17 @@ var SEQUENCE_EDITS = /* @__PURE__ */ new Set([
   "setMarkers",
   "setScene",
   "setAudioMaster",
-  "loopClip"
+  "loopClip",
+  "setCamera",
+  "addShape3D",
+  "updateShape3D",
+  "create3dObject",
+  "createShowcase",
+  "animateClip",
+  "animateScene",
+  "joinScenes",
+  "replaceClipMedia",
+  "retimeRange"
 ]);
 var SEQUENCE_READS = /* @__PURE__ */ new Set([
   "getTimeline",
@@ -21976,6 +22032,38 @@ var TOOLS_BY_NAME = new Map([
     return tool ? [[alias, tool]] : [];
   })
 ]);
+var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
+  "get_session_status",
+  "get_design_guide",
+  "get_project_state",
+  "get_transcript",
+  "render_preview_frame",
+  "probe_audio",
+  "export_range",
+  "lint_timeline",
+  "get_edit_log",
+  "list_projects",
+  "list_sequences",
+  "export_design",
+  "get_timeline",
+  "get_clip",
+  "list_checkpoints",
+  "get_media_bin",
+  "describe_motion",
+  "lint_motion",
+  "list_cuts",
+  "measure_text",
+  "describe_effect",
+  "list_presets",
+  "preview_media",
+  "search_stock",
+  "search_sfx",
+  "get_style_profile",
+  "list_plugins",
+  "describe_plugin",
+  "studio_tasks",
+  "studio_workflows"
+]);
 function editDistance(a, b) {
   const rows = [Array.from({ length: b.length + 1 }, (_, j) => j)];
   for (let i = 1; i <= a.length; i++) {
@@ -22058,8 +22146,8 @@ var SKILLS = [
       {
         "path": "SKILL.md",
         "uri": "skill://goatedit/goatedit-editing-story/SKILL.md",
-        "text": "---\nname: goatedit-editing-story\ndescription: Editing craft for GoatEdit \u2014 story structure and hooks, retention, where and why to cut (emotion, story, rhythm, eye trace), J and L cuts, pacing by format, cutting talking heads, choosing B-roll, captions with exact reading-speed and line rules, music, sound effects, ducking and loudness targets, and colour grading. Use when cutting footage, building a story from a transcript, adding captions, mixing sound, grading, or when an edit drags, confuses, or sounds amateur.\n---\n\n# Editing and story\n\n## Story first\n\nWrite or find the story before touching visuals. Every video, however short,\nhas the same spine:\n\n1. **Hook (0\u20133 s).** Say what this is and why it matters, in words and\n   picture, before anything else. Open in the middle of the action, on a\n   close-up, on the result, or on a bold claim. No logos, greetings or\n   \"in this video\" first.\n2. **Promise.** Tell them what they will get \u2014 the list, the answer, the\n   transformation. Previewing a list opens a loop the viewer wants closed.\n3. **Build.** One idea per beat, each raising a question the next answers.\n   Cut anything that does not move the story, however good it looks.\n4. **Re-engage.** In anything over about a minute, add a turn, a reveal or a\n   change of scene or pace every 45\u201390 s; long videos lose people at the\n   points where nothing new arrives.\n5. **Payoff.** Answer the hook. Call back to the opening image.\n6. **Direction.** One clear next step (follow, comment a keyword, visit,\n   buy), shown as well as said.\n\n**The test:** watch the first three seconds muted. Would a stranger know what\nthis is and want the rest?\n\n## Where to cut\n\nWhen choosing a cut, weigh in this order (Walter Murch's rule of six):\n**emotion** first, then **story**, then **rhythm**, then **eye trace** (where\nthe viewer is looking at the cut), then the screen's 2D plane, then 3D\ncontinuity. A cut that is right emotionally survives a continuity error; the\nreverse does not.\n\n- **Cut on action.** Cut in the middle of a movement \u2014 a turn, a hand\n  reaching, a door \u2014 so the motion hides the cut.\n- **Cut on the eye.** Put the incoming subject where the viewer is already\n  looking at the end of the outgoing shot.\n- **J cut:** the next shot's sound starts before its picture (we hear the\n  answer, then see the speaker). **L cut:** the current sound carries over the\n  next picture (the speaker keeps talking over B-roll). Both make dialogue\n  flow; a straight cut on picture and sound together feels abrupt.\n- **Change the shot size or angle** across a cut of the same subject\n  (wide to close, or 30\xB0 or more round). A small change looks like a jump.\n- **Keep screen direction.** People and objects keep moving the same way\n  across cuts unless something turns them.\n- **Cut music on the beat or the bar**, and music edits on phrase boundaries.\n- **Let it breathe after a big moment** \u2014 hold 0.5\u20131 s before the next idea.\n\n## Pacing by format\n\n| Format | Average shot | Notes |\n| --- | --- | --- |\n| Reel / TikTok / Short | 1.1\u20131.5 s, none over about 3 s | first cut within 1 s, on the first charged word |\n| Ad (6\u201330 s) | 1\u20132 s | product or brand within the first 3\u20135 s |\n| YouTube explainer | 2\u20134 s visuals over steady voice | change the picture at least every 4\u20136 s |\n| Tutorial | as long as the action needs | zoom to the part being discussed; cut dead time |\n| Documentary / brand film | 3\u20136 s, longer holds on faces | let emotional beats breathe |\n| Music video / montage | on the beat; vary 1, 2 and 4 beats | build cut speed toward the drop |\n| Trailer | accelerate across the act; stop dead before the title | |\n\nFaster is not better by itself: change the pace to show what matters. Slow\ndown for the important line, speed up through set-up.\n\n## Cutting talking heads\n\n1. `get_transcript` (or `transcribe`). Every time comes from real word\n   timings.\n2. Read every line. Keep the last clean take of each line; cut false starts\n   and repeats.\n3. Cut between phrases, never inside one. Trim dead air to under 0.2 s but\n   keep natural beats after commas and list markers (0.2\u20130.4 s). Remove a\n   filler only when there is silence on both sides. Never speed up a voice.\n4. `apply_ai_edit` with `dryRun: true` first; check each proposed range\n   against the transcript before applying.\n5. Hide jump cuts with a punch-in (scale 110\u2013120% on alternate cuts), a\n   B-roll cover, or a graphic \u2014 not a dissolve.\n6. Transcripts end words 40\u201380 ms before the sound dies: cut after the decay.\n7. `create_checkpoint` before any destructive pass.\n\n## B-roll\n\n- One visual per noun phrase, starting on its word (at most 0.15 s early).\n- Prefer, in order: real footage of the thing named; a real screen recording\n  zoomed to the part discussed; a clearly labelled mock; generated video with\n  a concrete metaphor. `search_stock` for footage; check every result with\n  `preview_media` before using it.\n- Every still or B-roll shot moves: a slow push of 3\u20138%, or a pan along the\n  subject.\n- Use each B-roll shot once. Never invent results or numbers on screen.\n- In vertical video keep the speaker on screen about 45% of the time and\n  never gone longer than about 3.5 s; mix split layouts (B-roll above,\n  speaker below), full B-roll, and punch-ins.\n\n## Captions\n\n**Readable subtitles** (explainers, interviews, anything people must follow):\n- At most 42 characters per line and two lines, one line when it fits.\n- Reading speed at most 17\u201320 characters a second (about 160\u2013180 words a\n  minute); children's content slower.\n- Break lines after punctuation and before conjunctions and prepositions.\n  Never split an article from its noun, a first name from a last name, or a\n  verb from its pronoun. Bottom-heavy shape.\n- On screen from the first word to just after the last; never across a scene\n  cut if it can be avoided \u2014 split it at the cut instead.\n- Numbers one to ten in words, 11 and above in figures.\n\n**Social captions** (reels, shorts, ads):\n- 1\u20133 words per card, split on phrase boundaries (`generate_captions`\n  `wordsPerChunk` 2\u20133), hard swaps, on screen two frames before the word.\n- Heavy sans, uppercase, about 60\u201364 px on a 1080\xD71920 frame, in the safe\n  area \u2014 never over a mouth.\n- Colour on a quarter to a third of cards, whole card only, with fixed\n  meaning (one colour for the key idea, one for the payoff or warning).\n- One style for the whole video; every card in the same box or the same\n  treatment. Mixing boxed and bare looks cheap.\n- Captions are an overlay on top of the film, not a reserved band: keep the\n  composition centred on the true centre of the frame.\n- Promote a word to a big designed graphic only at a real peak \u2014 at most one\n  per beat and never two in a row.\n- Fix names the transcriber cannot know with `glossary`.\n\n## Sound\n\nSound is half the video. You cannot hear it, so measure it (`probe_audio`)\nand ask the user to listen.\n\n- **Tracks:** voice, music and effects on audio tracks of their own \u2014 sound on\n  a video track is not mixed. Tag them with `set_audio_master` `roles`.\n- **Voice on top.** Music sits roughly 10\u201314 dB under speech\n  (`set_audio_master` `ducking: true`, `duckDb` \u221210 to \u221214) and comes up\n  between lines. The first second or two of a voiceover often wants the\n  music lower still.\n- **Loudness targets** (integrated, from `probe_audio` `loudness`): YouTube,\n  TikTok, Reels and Spotify about \u221214 LUFS; podcasts and Apple about \u221216 LUFS;\n  broadcast \u221223 LUFS. True peak at or below \u22121 dBTP \u2014 turn on the limiter\n  (`set_audio_master` `limiter: true`, `ceilingDb: -1`).\n- **Music** by mood: confident, darker beats for claims and news; light\n  grooves for methods and how-tos; swelling strings or piano for emotion.\n  Cut it on bars; end on the music's own ending (or a clean button), never a\n  fade in the middle of a phrase. Fade in 0.3\u20131 s; fade out 1\u20133 s.\n- **Sound effects only on visible actions:** a soft air move on a real\n  slide, a damped tap when a logo lands, a dry click for UI, paper for\n  documents, one warm tone for a success. Vary files on repeated actions.\n  No whoosh on every cut; no cartoon zaps unless the look is cartoon.\n- **Room tone.** Never cut voice to digital silence mid-scene; it sounds\n  broken.\n- Never fade the last spoken word.\n\n## Grade\n\n- **Fix, then style.** First balance each shot: exposure so faces sit in the\n  mids, white balance so whites are white, contrast so blacks are black but\n  not crushed (`set_color_grade` exposure, temperature, tint, contrast).\n- **Match shots** in a scene to each other before adding a look; compare\n  with `render_preview_frame` side by side.\n- **Skin first.** Midtones (`gamma`) are where skin lives; protect it when\n  pushing a look. A look that turns skin green or grey is wrong whatever the\n  palette.\n- **One look per video**, chosen in the brief: warm and soft for lifestyle\n  and documentary; cool and contrasty for tech and thriller; lifted blacks\n  (`lift`) for a film or matte feel; light saturation for premium.\n- Finish with texture when the look wants it: `filmGrain`, `halation`,\n  `filmStock`, a gentle `vignette` \u2014 subtle enough that nobody names it.\n- Verify every grade by looking at frames; numbers can look right while the\n  picture is wrong.\n",
-        "digest": "sha256:f056af026658635792303a5992c77751b19e3e4413f83660ffc7322aeed501b5"
+        "text": '---\nname: goatedit-editing-story\ndescription: Editing craft for GoatEdit \u2014 story structure and hooks, retention, where and why to cut (emotion, story, rhythm, eye trace), J and L cuts, pacing by format, cutting talking heads, choosing B-roll, captions with exact reading-speed and line rules, music, sound effects, ducking and loudness targets, and colour grading. Use when cutting footage, building a story from a transcript, adding captions, mixing sound, grading, or when an edit drags, confuses, or sounds amateur.\n---\n\n# Editing and story\n\n## Story first\n\nWrite or find the story before touching visuals. Every video, however short,\nhas the same spine:\n\n1. **Hook (0\u20133 s).** Say what this is and why it matters, in words and\n   picture, before anything else. Open in the middle of the action, on a\n   close-up, on the result, or on a bold claim. No logos, greetings or\n   "in this video" first.\n2. **Promise.** Tell them what they will get \u2014 the list, the answer, the\n   transformation. Previewing a list opens a loop the viewer wants closed.\n3. **Build.** One idea per beat, each raising a question the next answers.\n   Cut anything that does not move the story, however good it looks.\n4. **Re-engage.** In anything over about a minute, add a turn, a reveal or a\n   change of scene or pace every 45\u201390 s; long videos lose people at the\n   points where nothing new arrives.\n5. **Payoff.** Answer the hook. Call back to the opening image.\n6. **Direction.** One clear next step (follow, comment a keyword, visit,\n   buy), shown as well as said.\n\n**The test:** watch the first three seconds muted. Would a stranger know what\nthis is and want the rest?\n\n## Where to cut\n\nWhen choosing a cut, weigh in this order (Walter Murch\'s rule of six):\n**emotion** first, then **story**, then **rhythm**, then **eye trace** (where\nthe viewer is looking at the cut), then the screen\'s 2D plane, then 3D\ncontinuity. A cut that is right emotionally survives a continuity error; the\nreverse does not.\n\n- **Cut on action.** Cut in the middle of a movement \u2014 a turn, a hand\n  reaching, a door \u2014 so the motion hides the cut.\n- **Cut on the eye.** Put the incoming subject where the viewer is already\n  looking at the end of the outgoing shot.\n- **J cut:** the next shot\'s sound starts before its picture (we hear the\n  answer, then see the speaker). **L cut:** the current sound carries over the\n  next picture (the speaker keeps talking over B-roll). Both make dialogue\n  flow; a straight cut on picture and sound together feels abrupt.\n- **Change the shot size or angle** across a cut of the same subject\n  (wide to close, or 30\xB0 or more round). A small change looks like a jump.\n- **Keep screen direction.** People and objects keep moving the same way\n  across cuts unless something turns them.\n- **Cut music on the beat or the bar**, and music edits on phrase boundaries.\n- **Let it breathe after a big moment** \u2014 hold 0.5\u20131 s before the next idea.\n\n## Pacing by format\n\n| Format | Average shot | Notes |\n| --- | --- | --- |\n| Reel / TikTok / Short | 1.1\u20131.5 s, none over about 3 s | first cut within 1 s, on the first charged word |\n| Ad (6\u201330 s) | 1\u20132 s | product or brand within the first 3\u20135 s |\n| YouTube explainer | 2\u20134 s visuals over steady voice | change the picture at least every 4\u20136 s |\n| Tutorial | as long as the action needs | zoom to the part being discussed; cut dead time |\n| Documentary / brand film | 3\u20136 s, longer holds on faces | let emotional beats breathe |\n| Music video / montage | on the beat; vary 1, 2 and 4 beats | build cut speed toward the drop |\n| Trailer | accelerate across the act; stop dead before the title | |\n\nFaster is not better by itself: change the pace to show what matters. Slow\ndown for the important line, speed up through set-up.\n\n## Cutting talking heads\n\n1. `get_transcript` (or `transcribe`). Every time comes from real word\n   timings.\n2. Read every line. Keep the last clean take of each line; cut false starts\n   and repeats.\n3. Cut between phrases, never inside one. Trim dead air to under 0.2 s but\n   keep natural beats after commas and list markers (0.2\u20130.4 s). Remove a\n   filler only when there is silence on both sides. Never speed up a voice.\n4. `apply_ai_edit` with `dryRun: true` first; check each proposed range\n   against the transcript before applying.\n5. Hide jump cuts with a punch-in (scale 110\u2013120% on alternate cuts), a\n   B-roll cover, or a graphic \u2014 not a dissolve.\n6. Transcripts end words 40\u201380 ms before the sound dies: cut after the decay.\n7. `create_checkpoint` before any destructive pass.\n\n## B-roll\n\n- One visual per noun phrase, starting on its word (at most 0.15 s early).\n- Prefer, in order: real footage of the thing named; a real screen recording\n  zoomed to the part discussed; a clearly labelled mock; generated video with\n  a concrete metaphor. `search_stock` for footage; check every result with\n  `preview_media` before using it.\n- Every still or B-roll shot moves: a slow push of 3\u20138%, or a pan along the\n  subject.\n- Use each B-roll shot once. Never invent results or numbers on screen.\n- In vertical video keep the speaker on screen about 45% of the time and\n  never gone longer than about 3.5 s; mix split layouts (B-roll above,\n  speaker below), full B-roll, and punch-ins.\n\n## Captions\n\n**Readable subtitles** (explainers, interviews, anything people must follow):\n- At most 42 characters per line and two lines, one line when it fits.\n- Reading speed at most 17\u201320 characters a second (about 160\u2013180 words a\n  minute); children\'s content slower.\n- Break lines after punctuation and before conjunctions and prepositions.\n  Never split an article from its noun, a first name from a last name, or a\n  verb from its pronoun. Bottom-heavy shape.\n- On screen from the first word to just after the last; never across a scene\n  cut if it can be avoided \u2014 split it at the cut instead.\n- Numbers one to ten in words, 11 and above in figures.\n\n**Social captions** (reels, shorts, ads):\n- 1\u20133 words per card, split on phrase boundaries (`generate_captions`\n  `wordsPerChunk` 2\u20133), hard swaps, on screen two frames before the word.\n- Heavy sans, uppercase, about 60\u201364 px on a 1080\xD71920 frame, in the safe\n  area \u2014 never over a mouth.\n- Colour on a quarter to a third of cards, whole card only, with fixed\n  meaning (one colour for the key idea, one for the payoff or warning).\n- One style for the whole video; every card in the same box or the same\n  treatment. Mixing boxed and bare looks cheap.\n- Captions are an overlay on top of the film, not a reserved band: keep the\n  composition centred on the true centre of the frame.\n- Promote a word to a big designed graphic only at a real peak \u2014 at most one\n  per beat and never two in a row.\n- Fix names the transcriber cannot know with `glossary`.\n\n## Sound\n\nSound is half the video. You cannot hear it, so measure it (`probe_audio`)\nand ask the user to listen.\n\n- **Tracks:** voice, music and effects on audio tracks of their own \u2014 sound on\n  a video track is not mixed. Tag them with `set_audio_master` `roles`.\n- **Voice on top.** Music sits roughly 10\u201314 dB under speech\n  (`set_audio_master` `ducking: true`, `duckDb` \u221210 to \u221214) and comes up\n  between lines. The first second or two of a voiceover often wants the\n  music lower still.\n- **Loudness targets** (integrated, from `probe_audio` `loudness`): YouTube,\n  TikTok, Reels and Spotify about \u221214 LUFS; podcasts and Apple about \u221216 LUFS;\n  broadcast \u221223 LUFS. True peak at or below \u22121 dBTP \u2014 turn on the limiter\n  (`set_audio_master` `limiter: true`, `ceilingDb: -1`).\n- **Music** by mood: confident, darker beats for claims and news; light\n  grooves for methods and how-tos; swelling strings or piano for emotion.\n  Cut it on bars; end on the music\'s own ending (or a clean button), never a\n  fade in the middle of a phrase. Fade in 0.3\u20131 s; fade out 1\u20133 s.\n- **Sound effects only on visible actions:** a soft air move on a real\n  slide, a damped tap when a logo lands, a dry click for UI, paper for\n  documents, one warm tone for a success. Vary files on repeated actions.\n  No whoosh on every cut; no cartoon zaps unless the look is cartoon.\n  Find them with `search_sfx` by the on-screen action ("card lands",\n  "slides in", "typing") and pick by each result\'s `use` line; add with\n  `add_media_file` (`sfx:<id>`), place on the sfx-role track about two frames\n  before the visual. They come in at -16 dB; change that only by ear.\n- **Room tone.** Never cut voice to digital silence mid-scene; it sounds\n  broken.\n- Never fade the last spoken word.\n\n## Grade\n\n- **Fix, then style.** First balance each shot: exposure so faces sit in the\n  mids, white balance so whites are white, contrast so blacks are black but\n  not crushed (`set_color_grade` exposure, temperature, tint, contrast).\n- **Match shots** in a scene to each other before adding a look; compare\n  with `render_preview_frame` side by side.\n- **Skin first.** Midtones (`gamma`) are where skin lives; protect it when\n  pushing a look. A look that turns skin green or grey is wrong whatever the\n  palette.\n- **One look per video**, chosen in the brief: warm and soft for lifestyle\n  and documentary; cool and contrasty for tech and thriller; lifted blacks\n  (`lift`) for a film or matte feel; light saturation for premium.\n- Finish with texture when the look wants it: `filmGrain`, `halation`,\n  `filmStock`, a gentle `vignette` \u2014 subtle enough that nobody names it.\n- Verify every grade by looking at frames; numbers can look right while the\n  picture is wrong.\n',
+        "digest": "sha256:2409fecd10f0230711b51f5e810245feb29df80c2f9555f400e5911a61cefab6"
       }
     ]
   },
@@ -22092,8 +22180,8 @@ var SKILLS = [
       {
         "path": "SKILL.md",
         "uri": "skill://goatedit/goatedit-motion-design/SKILL.md",
-        "text": '---\nname: goatedit-motion-design\ndescription: Motion design for GoatEdit \u2014 easing, durations, stagger, overshoot, hierarchy and holds with exact numbers; how one scene hands motion to the next (direction, matched speed, cutting mid-motion, carriers); the seam techniques (push, zoom-through, inverse zoom, match cut, morph, rack focus); keeping a scene alive without idle wobble; kinetic typography; and which GoatEdit tool does each. Use before animating anything, joining scenes, or when a video feels static, jumpy, floaty or "like slides".\n---\n\n# Motion design\n\nMotion has one job: show the viewer where to look next. Every move answers\n"what changed, and where should the eye go?" A video should feel like one\ncontinuous camera move through ideas, not a stack of slides that each animate\non their own.\n\n## The numbers\n\n| Principle | Rule |\n| --- | --- |\n| Easing | Never linear. Arriving: ease-out `[0.22,1,0.36,1]`. Leaving: ease-in `[0.55,0,1,0.45]`. Moving on screen: in-out `[0.65,0,0.35,1]`. Snappy arrivals: expo-out. |\n| Duration | Nudge 0.15 s. Entrance 0.3\u20130.5 s, never one element over 0.8 s. Across the frame 0.4\u20130.7 s. Camera push at a cut 0.35\u20130.45 s each side. Exit about 75% of its entrance. |\n| Stagger | 30\u201360 ms between siblings, in reading order or outward from the hero; the whole group inside 0.4\u20130.5 s. With 8+ items tighten the gap rather than lengthen the group. |\n| Overshoot | Pops and arrivals overshoot 5\u201310% and settle. Never on camera moves. No bounce-out or elastic-out eases: they read as a toy. |\n| Anticipation | A big exit starts with 0.1 s the other way, 3\u20135% of the distance. |\n| Hierarchy | One hero move at a time; everything else smaller, shorter or later. |\n| Consistency | Similar elements share one ease and one duration. Never a unique pair per element. |\n| Arcs | Organic things travel on curves; type and UI may go straight. |\n| Squash and stretch | Fast round things stretch along their travel and squash on impact. |\n| Motion blur | Only on fast moves, 2D layers only. |\n| Parallax | Background layers move 30\u201360% as far as the foreground. |\n| Holds | After an impact or reveal, hold 0.3\u20130.6 s. Text stays 0.3 s a word plus 0.5 s. |\n| Stillness before the payoff | Leave 0.3\u20130.75 s between the action and its result \u2014 the dramatic comma. |\n| Rhythm | Alternate fast and slow. Don\'t use the same join twice running unless it is a pattern. |\n| Sync | A visual lands 0.1\u20130.25 s before the word it shows, never after. With music, hero moves land on beats. |\n\n## One film, one current\n\n**Pick one direction for the whole video** \u2014 say, leftward \u2014 and send every\nordinary scene change that way. Other directions are reserved and mean\nsomething when spent:\n\n| Vector | Means |\n| --- | --- |\n| The current (e.g. left) | next beat, forward progress |\n| Up | a conclusion or reveal rising above what came before |\n| Zoom forward (push in) | going deeper into the same thought |\n| Zoom backward (pull out) | arrival: something bigger lands, the payoff |\n\n- Never run two scene changes back to back in opposite directions; ping-pong\n  reads as a mistake. A change of direction needs a visible cause (a click,\n  an impact) or a new chapter.\n\n## How one scene hands to the next\n\n**The rule:** how scene A leaves decides how scene B arrives \u2014 same axis,\nsame direction, matched speed, and the cut falls mid-motion on both sides.\n\n1. **Axis.** Sideways stays sideways, vertical stays vertical, zoom stays\n   zoom.\n2. **Direction.** Never mirror. On zoom, direction is whether things grow or\n   shrink: a shrinking (pull-back) exit must be answered by an entrance that\n   also shrinks into place (starts oversized), not one that grows from small.\n   This is the most common mistake, because grow-from-small is everyone\'s\n   default entrance.\n3. **Speed.** Exit with ease-in, enter with the matching ease-out, over the\n   same distance and time \u2014 the two halves of one in-out curve, so the speed\n   matches at the cut.\n4. **Phase.** Cut while both sides are moving. A scene that settles to rest\n   before the cut, or an entrance that starts from rest after it, is a dead\n   beat.\n5. **No crossfades between scenes.** A dissolve has nothing for the eye to\n   follow. Keep dissolves for time passing or a dream-like mood.\n\n**Carriers.** The eye follows objects. The strongest join hands a concrete\nthing across the cut at the same place and speed: a card that becomes the\nnext screen, a word that becomes a heading, a dot that becomes a map pin, a\ncursor mid-path. Plan carriers at storyboard time.\n\n**Partial travel.** Scene pushes travel about 12% of the frame (about 230 px\nat 1920) with a quick fade, not a full-frame slide. Full-frame slides look\nlike a slideshow.\n\n## The joins, and the GoatEdit tool for each\n\n`list_cuts` shows every cut and which ones are still (`stillCuts`).\n`join_scenes` makes them flow. `auto` picks one and says why in `picked`.\n\n| Technique | Use for | GoatEdit |\n| --- | --- | --- |\n| **Push** (cut the curve) | the default scene change, in the film\'s current | `join_scenes` type `push`, `direction` = the current, `duration` 0.3\u20130.4 |\n| **Zoom-through** | going deeper: fly into one hero element, the next scene opens out of it | `join_scenes` type `zoomThrough`, `clipId` = that element. Never into one letter of a row |\n| **Inverse zoom** | the payoff arriving: outgoing shrinks away, incoming arrives oversized and settles | push-out camera keys with `set_keyframes`: out 1\u21920.8, in 1.25\u21921, expo-out, about 0.7 s total. Spend it once or twice per video |\n| **Match cut** | one layer becomes another in the same spot | `join_scenes` type `matchCut` with `fromClipId`/`toClipId` |\n| **Morph** | every layer grows out of its partner (Smart Animate) \u2014 the strongest join | `join_scenes` type `morph`; name partners with the same last word |\n| **Rack focus** | the one cut you want seen: same surface, new state | blur spike 8\u201312 px peak at the cut with a 1.06 scale breath (`set_clip_effect` blur keyframes); at most once every 8 s |\n| **Hard cut on a beat** | energy, music videos, reels | no join; cut exactly on the beat marker |\n\nBlur on zoom joins: about 10 px for text-sized subjects, 18\u201320 px for\nfull-frame surfaces. Use two or three join types per video and repeat them;\nvariety for its own sake reads as a template showcase.\n\n## Keeping a scene alive\n\nA scene that finishes its entrance with seconds left is a planning problem.\nFill it with story, not wobble. Idle loops on graphics (floating, breathing,\npulsing glow) read as "the video is waiting" \u2014 don\'t. Each stretch between\nentrance and exit belongs to one of these:\n\n- **Staged reveals** \u2014 hold content back and reveal it on the words that\n  name it. The default when a scene has two or more ideas.\n- **Camera with intent** \u2014 start wide, travel, arrive on the subject. A slow\n  push on a photo or footage (3\u20138% over the shot) counts; `animate_scene`\'s\n  `hold` drift on pictures does this.\n  A push through a scene with depth is not one zoom: split it into planes\n  (backdrop, subject, props in front) and let each grow at its own rate \u2014\n  near things grow faster than far ones. Everything on one null scaled\n  equally reads flat. The direct way: switch each plane to 3D\n  (`set_clip_effect` type `layer3d`, `posZ` 0 for the subject, 800\u20132000 for\n  backdrops, negative for foreground props) and move one `set_camera`: a\n  dolly (`z`), truck (`x`), orbit (`orbit` with `pivotZ` at the subject\'s\n  depth) or lens pull (`focalLength`) moves every plane by its own depth.\n  3D planes stack by depth, not track, so an orbit passes them correctly;\n  keep 2D layers (titles, adjustment layers) above or below all of them.\n  Scale a far plane up by its distance (posZ 1480 halves it) so it still\n  fills the frame. `aperture` + `focus` racks focus between planes.\n- **The product doing its thing** \u2014 a progress bar fills, a count ticks, a\n  highlight steps down a list.\n- **Acted-out beats** \u2014 a card files into a stack, an item is dragged, a\n  result assembles.\n- **Cursor-led** \u2014 an oversized cursor walks to a button and its click\n  triggers the next beat.\n\nTest: pause on any second. Something meaningful should be mid-flight.\n\n**Cause and effect.** Chain moves so each is launched by the last \u2014 click,\nsquash, release, flight, impact, recoil, reveal. A reaction starts on the\nframe of its cause, not "shortly after". Heavy things rebound slower; small\nthings snap.\n\n## Entrances\n\n- **Waterfall entry** for titles, openers and lists: words arrive from below\n  one after another, each starting before the last settles, gaps shrinking,\n  the last one snapping. Heavy words travel 60\u201380 px over 0.16\u20130.2 s, normal\n  words 40\u201350 px over 0.13\u20130.16 s, small words 30\u201345 px over 0.1\u20130.13 s.\n  Opacity cuts on rather than fading.\n- **One direction per cascade.** Never ease-in-out on an entrance.\n- **Text keeps its own animation.** A text layer gets a text preset\n  (`set_text_animation`, letters or words, `delay` for its place in the\n  cascade), never a block keyframe move.\n- **Text leaves the way it came.** `set_text_animation` with\n  `exit: { preset, duration, stagger, order }` plays a preset out at the clip\n  end, carrying on in its own direction (rises in, rises out). Exit alone,\n  with no entrance, keeps the words on from frame one. For a typed line that\n  deletes itself, `unit: "letter"` plus `exit: { preset: "typewriterCursor",\n  stagger: 0.03 }`: last letter first, with a caret that blinks just before.\n  Check the reply\'s `exitStartsAt` and any overlap warning; `exit: null`\n  removes it. Kinetic presets and countUp cannot be exits.\n\n| Feel | Hero title | Text | Row of words | Picture hero | Support |\n| --- | --- | --- | --- | --- | --- |\n| smooth | `cinematicRise` | `riseFade` | `riseFade` | blurIn, zoomIn, maskReveal | fadeUp |\n| snappy | `maskRise` | `slideUp` | `maskRise` | popIn, slideIn, maskReveal | slideIn outward from the hero |\n| bouncy | `springUp` | `scaleIn` | `bounceDrop` | dropIn, popIn, spinIn | popIn |\n\nPick one feel for the whole video. `animate_scene` applies these by role\n(ground, hero, support, text, detail, follower) with `style` = the feel; use\n`dryRun: true` to see the plan, then hand-key only the hero move.\n\n## Kinetic typography\n\n- Time every word to the voice: `set_text_animation` with `syncToWords`, or\n  cut each word on at its real start from `get_transcript`.\n- One to four words on screen at a time; the key word bigger, heavier or in\n  the accent.\n- Vary scale and position with the rhythm of the line \u2014 a stressed word hits\n  harder (`slamIn`, `focusPull`), a soft word drifts (`riseFade`).\n- Move the camera, not every word: a group of words can push or rotate as one\n  (parent them to a null with `add_null` and `set_parent`).\n- Hand from line to line with a word-level push in the current\'s direction.\n\n## Stepped motion\n\nFor a hand-made, editorial or collage feel, step graphics at 12 fps inside a\n24\u201330 fps video (`set_clip_effect` `posterizeTime`). Keep camera moves and\nfootage smooth.\n\n## Workflow in GoatEdit\n\n1. Approved stills, one element per layer, layers named for their partners.\n2. `animate_scene` (`all: true` or per scene) in one feel.\n3. Hand-key the hero move with `set_keyframes` (times relative to the clip\n   start; posX/posY are fractions of the frame).\n4. `list_cuts`, then `join_scenes` on each still cut, in the current.\n5. `lint_motion`; run each finding\'s `fix` calls one at a time; lint again\n   until only judgement notes remain.\n6. `export_range` strips around every join and hero move, then fix what you\n   see. A lint pass is not a watch.\n\nGoatEdit specifics: HTML clips crop at their box when moved \u2014 animate inside\nthem with CSS. 3D frames render slowly through the bridge, so keep strips\nshort. `describe_motion` returns the numbers `lint_motion` checks.\n',
-        "digest": "sha256:a352501647a09a7a85e0b8c178dddbdaa4fd55efb432c88c008b5eb91f11d91d"
+        "text": '---\nname: goatedit-motion-design\ndescription: Motion design for GoatEdit \u2014 easing, durations, stagger, overshoot, hierarchy and holds with exact numbers; how one scene hands motion to the next (direction, matched speed, cutting mid-motion, carriers); the seam techniques (push, zoom-through, inverse zoom, match cut, morph, rack focus); keeping a scene alive without idle wobble; kinetic typography; and which GoatEdit tool does each. Use before animating anything, joining scenes, or when a video feels static, jumpy, floaty or "like slides".\n---\n\n# Motion design\n\nMotion has one job: show the viewer where to look next. Every move answers\n"what changed, and where should the eye go?" A video should feel like one\ncontinuous camera move through ideas, not a stack of slides that each animate\non their own.\n\n## The numbers\n\n| Principle | Rule |\n| --- | --- |\n| Easing | Never linear. Arriving: ease-out `[0.22,1,0.36,1]`. Leaving: ease-in `[0.55,0,1,0.45]`. Moving on screen: in-out `[0.65,0,0.35,1]`. Snappy arrivals: expo-out. |\n| Duration | Nudge 0.15 s. Entrance 0.3\u20130.5 s, never one element over 0.8 s. Across the frame 0.4\u20130.7 s. Camera push at a cut 0.35\u20130.45 s each side. Exit about 75% of its entrance. |\n| Stagger | 30\u201360 ms between siblings, in reading order or outward from the hero; the whole group inside 0.4\u20130.5 s. With 8+ items tighten the gap rather than lengthen the group. |\n| Overshoot | Pops and arrivals overshoot 5\u201310% and settle. Never on camera moves. No bounce-out or elastic-out eases: they read as a toy. |\n| Anticipation | A big exit starts with 0.1 s the other way, 3\u20135% of the distance. |\n| Hierarchy | One hero move at a time; everything else smaller, shorter or later. |\n| Consistency | Similar elements share one ease and one duration. Never a unique pair per element. |\n| Arcs | Organic things travel on curves; type and UI may go straight. |\n| Squash and stretch | Fast round things stretch along their travel and squash on impact. |\n| Motion blur | Only on fast moves, 2D layers only. |\n| Parallax | Background layers move 30\u201360% as far as the foreground. |\n| Holds | After an impact or reveal, hold 0.3\u20130.6 s. Text stays 0.3 s a word plus 0.5 s. |\n| Stillness before the payoff | Leave 0.3\u20130.75 s between the action and its result \u2014 the dramatic comma. |\n| Rhythm | Alternate fast and slow. Don\'t use the same join twice running unless it is a pattern. |\n| Sync | A visual lands 0.1\u20130.25 s before the word it shows, never after. With music, hero moves land on beats. |\n\n## One film, one current\n\n**Pick one direction for the whole video** \u2014 say, leftward \u2014 and send every\nordinary scene change that way. Other directions are reserved and mean\nsomething when spent:\n\n| Vector | Means |\n| --- | --- |\n| The current (e.g. left) | next beat, forward progress |\n| Up | a conclusion or reveal rising above what came before |\n| Zoom forward (push in) | going deeper into the same thought |\n| Zoom backward (pull out) | arrival: something bigger lands, the payoff |\n\n- Never run two scene changes back to back in opposite directions; ping-pong\n  reads as a mistake. A change of direction needs a visible cause (a click,\n  an impact) or a new chapter.\n\n## How one scene hands to the next\n\n**The rule:** how scene A leaves decides how scene B arrives \u2014 same axis,\nsame direction, matched speed, and the cut falls mid-motion on both sides.\n\n1. **Axis.** Sideways stays sideways, vertical stays vertical, zoom stays\n   zoom.\n2. **Direction.** Never mirror. On zoom, direction is whether things grow or\n   shrink: a shrinking (pull-back) exit must be answered by an entrance that\n   also shrinks into place (starts oversized), not one that grows from small.\n   This is the most common mistake, because grow-from-small is everyone\'s\n   default entrance.\n3. **Speed.** Exit with ease-in, enter with the matching ease-out, over the\n   same distance and time \u2014 the two halves of one in-out curve, so the speed\n   matches at the cut.\n4. **Phase.** Cut while both sides are moving. A scene that settles to rest\n   before the cut, or an entrance that starts from rest after it, is a dead\n   beat.\n5. **No crossfades between scenes.** A dissolve has nothing for the eye to\n   follow. Keep dissolves for time passing or a dream-like mood.\n\n**Carriers.** The eye follows objects. The strongest join hands a concrete\nthing across the cut at the same place and speed: a card that becomes the\nnext screen, a word that becomes a heading, a dot that becomes a map pin, a\ncursor mid-path. Plan carriers at storyboard time.\n\n**Partial travel.** Scene pushes travel about 12% of the frame (about 230 px\nat 1920) with a quick fade, not a full-frame slide. Full-frame slides look\nlike a slideshow.\n\n## The joins, and the GoatEdit tool for each\n\n`list_cuts` shows every cut and which ones are still (`stillCuts`).\n`join_scenes` makes them flow. `auto` picks one and says why in `picked`.\n\n| Technique | Use for | GoatEdit |\n| --- | --- | --- |\n| **Push** (cut the curve) | the default scene change, in the film\'s current | `join_scenes` type `push`, `direction` = the current, `duration` 0.3\u20130.4 |\n| **Zoom-through** | going deeper: fly into one hero element, the next scene opens out of it | `join_scenes` type `zoomThrough`, `clipId` = that element. Never into one letter of a row |\n| **Inverse zoom** | the payoff arriving: outgoing shrinks away, incoming arrives oversized and settles | push-out camera keys with `set_keyframes`: out 1\u21920.8, in 1.25\u21921, expo-out, about 0.7 s total. Spend it once or twice per video |\n| **Match cut** | one layer becomes another in the same spot | `join_scenes` type `matchCut` with `fromClipId`/`toClipId` |\n| **Morph** | every layer grows out of its partner (Smart Animate) \u2014 the strongest join | `join_scenes` type `morph`; name partners with the same last word |\n| **Rack focus** | the one cut you want seen: same surface, new state | blur spike 8\u201312 px peak at the cut with a 1.06 scale breath (`set_clip_effect` blur keyframes); at most once every 8 s |\n| **Hard cut on a beat** | energy, music videos, reels | no join; cut exactly on the beat marker |\n\nBlur on zoom joins: about 10 px for text-sized subjects, 18\u201320 px for\nfull-frame surfaces. Use two or three join types per video and repeat them;\nvariety for its own sake reads as a template showcase.\n\n## Keeping a scene alive\n\nA scene that finishes its entrance with seconds left is a planning problem.\nFill it with story, not wobble. Idle loops on graphics (floating, breathing,\npulsing glow) read as "the video is waiting" \u2014 don\'t. Each stretch between\nentrance and exit belongs to one of these:\n\n- **Staged reveals** \u2014 hold content back and reveal it on the words that\n  name it. The default when a scene has two or more ideas.\n- **Camera with intent** \u2014 start wide, travel, arrive on the subject. A slow\n  push on a photo or footage (3\u20138% over the shot) counts; `animate_scene`\'s\n  `hold` drift on pictures does this.\n  A push through a scene with depth is not one zoom: split it into planes\n  (backdrop, subject, props in front) and let each grow at its own rate \u2014\n  near things grow faster than far ones. Everything on one null scaled\n  equally reads flat. The direct way: switch each plane to 3D\n  (`set_clip_effect` type `layer3d`, `posZ` 0 for the subject, 800\u20132000 for\n  backdrops, negative for foreground props) and move one `set_camera`: a\n  dolly (`z`), truck (`x`), orbit (`orbit` with `pivotZ` at the subject\'s\n  depth) or lens pull (`focalLength`) moves every plane by its own depth.\n  3D planes stack by depth, not track, so an orbit passes them correctly;\n  keep 2D layers (titles, adjustment layers) above or below all of them\n  (`lint_timeline` flags one that splits them). For a backdrop set layer3d\n  `fill: 1`: it grows just enough to cover the frame for the camera\'s whole\n  move, so an orbit never shows its edge. `aperture` + `focus` racks focus between planes.\n- **Rig, don\'t copy keys** \u2014 `set_keyframes` `expression` links properties\n  the way After Effects does: a null named "Controls" whose `posX` drives\n  many layers (`layer("Controls").posX * 100`), a cascade with\n  `valueAtTime(time - (index - 1) * 0.08)` on shared keys, an idle bob as two\n  keys plus `loopOut("pingpong")`, `thisLayer.scaleX` to keep proportions.\n  Change the one control, and everything tied to it follows.\n- **Animate the shape, not just its transform** \u2014 `set_keyframes` keys a\n  shape layer\'s `shapeWidth`, `shapeHeight`, `shapeCornerRadius`,\n  `shapeStrokeWidth`, `shapeDash` and `shapeGap`: a bar that grows from its\n  edge instead of stretching its corners, a pill that rounds into a circle.\n  Key width and height together on a square or circle.\n- **The product doing its thing** \u2014 a progress bar fills, a count ticks, a\n  highlight steps down a list.\n- **Acted-out beats** \u2014 a card files into a stack, an item is dragged, a\n  result assembles.\n- **Cursor-led** \u2014 an oversized cursor walks to a button and its click\n  triggers the next beat.\n\nTest: pause on any second. Something meaningful should be mid-flight.\n\n**Cause and effect.** Chain moves so each is launched by the last \u2014 click,\nsquash, release, flight, impact, recoil, reveal. A reaction starts on the\nframe of its cause, not "shortly after". Heavy things rebound slower; small\nthings snap.\n\n## Entrances\n\n- **Waterfall entry** for titles, openers and lists: words arrive from below\n  one after another, each starting before the last settles, gaps shrinking,\n  the last one snapping. Heavy words travel 60\u201380 px over 0.16\u20130.2 s, normal\n  words 40\u201350 px over 0.13\u20130.16 s, small words 30\u201345 px over 0.1\u20130.13 s.\n  Opacity cuts on rather than fading.\n- **One direction per cascade.** Never ease-in-out on an entrance.\n- **Text keeps its own animation.** A text layer gets a text preset\n  (`set_text_animation`, letters or words, `delay` for its place in the\n  cascade), never a block keyframe move.\n- **Text leaves the way it came.** `set_text_animation` with\n  `exit: { preset, duration, stagger, order }` plays a preset out at the clip\n  end, carrying on in its own direction (rises in, rises out). Exit alone,\n  with no entrance, keeps the words on from frame one. For a typed line that\n  deletes itself, `unit: "letter"` plus `exit: { preset: "typewriterCursor",\n  stagger: 0.03 }`: last letter first, with a caret that blinks just before.\n  Check the reply\'s `exitStartsAt` and any overlap warning; `exit: null`\n  removes it. Kinetic presets and countUp cannot be exits.\n\n| Feel | Hero title | Text | Row of words | Picture hero | Support |\n| --- | --- | --- | --- | --- | --- |\n| smooth | `cinematicRise` | `riseFade` | `riseFade` | blurIn, zoomIn, maskReveal | fadeUp |\n| snappy | `maskRise` | `slideUp` | `maskRise` | popIn, slideIn, maskReveal | slideIn outward from the hero |\n| bouncy | `springUp` | `scaleIn` | `bounceDrop` | dropIn, popIn, spinIn | popIn |\n\nPick one feel for the whole video. `animate_scene` applies these by role\n(ground, hero, support, text, detail, follower) with `style` = the feel; use\n`dryRun: true` to see the plan, then hand-key only the hero move.\n\n## Kinetic typography\n\n- Time every word to the voice: `set_text_animation` with `syncToWords`, or\n  cut each word on at its real start from `get_transcript`.\n- One to four words on screen at a time; the key word bigger, heavier or in\n  the accent.\n- Vary scale and position with the rhythm of the line \u2014 a stressed word hits\n  harder (`slamIn`, `focusPull`), a soft word drifts (`riseFade`).\n- Move the camera, not every word: a group of words can push or rotate as one\n  (parent them to a null with `add_null` and `set_parent`).\n- Hand from line to line with a word-level push in the current\'s direction.\n\n## Stepped motion\n\nFor a hand-made, editorial or collage feel, step graphics at 12 fps inside a\n24\u201330 fps video (`set_clip_effect` `posterizeTime`). Keep camera moves and\nfootage smooth.\n\n## Workflow in GoatEdit\n\n1. Approved stills, one element per layer, layers named for their partners.\n2. `animate_scene` (`all: true` or per scene) in one feel.\n3. Hand-key the hero move with `set_keyframes` (times relative to the clip\n   start; posX/posY are fractions of the frame).\n4. `list_cuts`, then `join_scenes` on each still cut, in the current.\n5. `lint_motion`; run each finding\'s `fix` calls one at a time; lint again\n   until only judgement notes remain.\n6. `export_range` strips around every join and hero move, then fix what you\n   see. A lint pass is not a watch.\n\nGoatEdit specifics: HTML clips crop at their box when moved \u2014 animate inside\nthem with CSS. 3D frames render slowly through the bridge, so keep strips\nshort. `describe_motion` returns the numbers `lint_motion` checks.\n',
+        "digest": "sha256:b3e82f40c23ddc9983d492580a4bd7c4647e2415d96d6245b839fe2253032101"
       }
     ]
   },
@@ -22109,8 +22197,8 @@ var SKILLS = [
       {
         "path": "SKILL.md",
         "uri": "skill://goatedit/goatedit-video-director/SKILL.md",
-        "text": '---\nname: goatedit-video-director\ndescription: Start here for any GoatEdit video \u2014 reel, short, ad, explainer, product launch, tutorial, talking head, kinetic type, montage. The director\'s workflow (brief, references, script, storyboard, style frames, build, motion, sound, checks), which other GoatEdit skill to load for each step, the quality bar a finished video must clear, and the self-review that catches what lint cannot. Use before the first edit of a new video or a big change to one.\n---\n\n# GoatEdit video director\n\nYou are directing a video, not filling a timeline. Tools do the mechanics; this\nskill and its four siblings carry the taste. Load them as you reach each step:\n\n| Step | Load |\n| --- | --- |\n| Look: type, colour, layout, safe areas, choosing a look | `goatedit-visual-design` |\n| Motion: easing, timing, joins between scenes, kinetic type | `goatedit-motion-design` |\n| Story, cutting, B-roll, captions, sound, grade | `goatedit-editing-story` |\n| The playbook for the kind of video asked for | `goatedit-formats` |\n\nNo skill support in your app? Call `get_design_guide` \u2014 it serves the same\ntext by skill, section or keyword (`get_design_guide({ topic: "captions" })`).\n\n## Order of authority\n\n1. What the user asked for in this conversation.\n2. Their saved style (`get_style_profile`) and brand.\n3. These skills.\n\nA reference video the user gives beats every number here. Measure it\n(`begin_request` with `referenceMediaIds`) and match it.\n\n## The workflow\n\nNever skip ahead. Each step ends with something the user can approve.\n\n1. **Brief.** `begin_request` with the edit type and the user\'s style words,\n   then `get_style_profile`. Write back, in three lines: who it is for, the\n   one thing they should remember, the platform and length. Ask only what you\n   cannot infer: platform, length, brand, whether there is a voiceover.\n2. **References.** Ask for one or two videos they like, or name two you will\n   aim at ("a Vox explainer", "an Apple product film"). Say what you take from\n   each: pacing, type, colour, motion feel.\n3. **Script and beat sheet.** For anything with words, write the script first.\n   Split it into beats, one idea each, with a target duration. Spoken words run\n   about 2.5 a second; a 30 s reel holds about 70 words. With a voiceover the\n   voice is the clock: generate or record it, `transcribe`, and time every beat\n   from real word timings, never from word counts.\n4. **Storyboard.** One line per beat: what is on screen, the hero element, the\n   layout, what each element is built as (see Build map), the move into the\n   next beat. Vary the layouts (full-bleed, split,\n   type-only, close-up, data); never the same composition three beats running.\n   Plan joins now: layers that become each other across a cut share a name\n   ending ("S2 tag Price" then "S3 card Price") so `join_scenes` can morph them.\n5. **Animatic, then style frames.** For motion-graphics pieces, first build\n   a rough draft of every section: black and white, plain type, flat shapes,\n   one simple move each, timed to the voice or music. It proves the plan \u2014\n   which idea goes in which section and when each move lands \u2014 before any\n   polish. Then build two or three key frames as finished stills (the hook,\n   the busiest beat, the end card), `render_preview_frame` each and show the\n   user. Polish nothing until the plan and the look are approved. One element\n   per layer.\n6. **Build.** Lay every beat on the timeline with its real duration. Plan\n   tracks first (overlapping clips on one track replace each other): V1 main\n   picture, V2 B-roll, V3 graphics, V4 captions; A1 voice, A2 music, A3\n   effects. Mark beats with `set_scene`. Where the connector offers `run_tools`,\n   send several edits as one call.\n7. **Motion.** `animate_scene` per scene in one feel for the whole video,\n   hand-key only the hero move, then join the cuts (`list_cuts`, `join_scenes`).\n   See `goatedit-motion-design`.\n8. **Sound.** Music bed, voice, effects only on visible actions, ducking,\n   loudness. See `goatedit-editing-story`.\n9. **Check** (below). Fix, re-check, then hand over with the report.\n\nFor a quick edit (trim this, add captions, swap the music) skip to the step it\ntouches, but still run the checks that cover it.\n\n## Build map: what each element is made of\n\nDecide this per element at storyboard time and write it in the storyboard as\na "build as" column. The rule under every row: **anything the user might want\nto move, retime, recolour or swap is its own layer.**\n\n| Element | Build as | Not as |\n| --- | --- | --- |\n| Designed words \u2014 a headline, a kinetic line, a word that changes colour | text clips (`create_text_clip` + `set_text_animation`), one clip per line, or per word when that word moves on its own | words inside an HTML clip, or caption cards |\n| Spoken words, timed to the voice | captions (`generate_captions`), on their own track, one style | text clips placed by hand, words in HTML |\n| A word that turns into an icon or a picture | the word, the icon and the next word as separate clips; `join_scenes` `morph` or `matchCut` between them | one clip with everything baked in |\n| UI that behaves like UI \u2014 a typing field, chat bubbles arriving, a list scrolling, a toggle, a progress bar | one HTML clip per UI surface, CSS or WAAPI animation, no scripts. Text inside the UI stays in the HTML: it is part of the interface, not the film\'s type | a pile of text and shape clips pretending to be an app |\n| A moving backdrop \u2014 mesh gradient, soft glow blobs, grid, grain | one HTML clip on the lowest track, or a shape with effects | baked into a picture or into the scene\'s HTML |\n| A phone, laptop or monitor showing something | the device as its own layer; the screen content (HTML, footage, still) as another, masked to the screen with `set_mask` and parented to the device with `set_parent`; hands on top as a cut-out | one flat picture of a device with a screen |\n| A ring, globe, tunnel, orbit, fan or carousel of cards \u2014 pictures, clips or UI stills looping in 3D | `create_showcase` with the right template (the Presets panel\'s Showcase shelf), filled from the bin; tune it with `set_clip_effect` on its showcase effect | cards keyframed one by one round a null |\n| A product with words circling it | `create_showcase` with a product template (`productRing`, `productOrbit`\u2026) and the cut-out or 3D model | hand-built text on a path |\n| A few floating photos or cut-outs that each move on their own | one image clip each (`remove_background` for cut-outs), each with its own shadow, parented to a null (`add_null`) so the group drifts as one | a flattened collage image |\n| Props with depth \u2014 candy shapes, a tumbling object, a glass ring | `create_3d_shape` with one `material` family for the whole video | 3D for flat UI, body text or anything that must be read |\n| A logo with depth, a word as a solid | `create_3d_object` (text, or a transparent PNG or SVG) | \u2014 |\n| Logo reveal | the mark and the wordmark as separate layers so they can assemble | one image that fades in |\n| A scene change | `join_scenes` between the scenes | a transition drawn inside an HTML clip |\n\n**Text: designed or caption?** Ask: if the voice were deleted, would this text\nstill need to be on screen? Yes \u2014 it is designed type: a text clip, placed and\nanimated with the layout. No \u2014 it transcribes speech: a caption. A video can\nhave both; they never share a track or a style, and a designed headline never\ndoubles as the caption of the line it shows.\n\n**When HTML is the right call.** Something that behaves like a web page or an\napp, or motion that is trivial in CSS and miserable to keyframe (a ticker, a\ntyping cursor, a looping gradient). When it is wrong: the parts must animate\nseparately, morph into the next scene, be retimed by the user, or the text is\nthe hero. An HTML clip is one layer to everything else in GoatEdit. HTML clip\nrules: layout in px for the composition size, longhand font properties rather\nthan the `font` shorthand, class-styled divs rather than styled `b` or `span`,\nand animate inside the snippet \u2014 moving the clip crops it at its box.\n\n**When 3D earns its place.** One hero object or a handful of accents a scene,\nlit and finished the same way across the video (one material family, one\nlight direction). It renders slower than anything else, so keep it to the\nmoments that need depth: a logo, a product, props that burst or tumble past a\ndevice. Depth comes from scale, blur and parallax as much as from the model.\n\n**Track order, bottom to top:** backdrop; footage and devices; collage and 3D\nprops; designed type; UI overlays and cursor; captions; brand bug.\n\n**Breaking down a reference.** Watch it through, then for each section write:\ntime in and out, what is on screen, every element with its "build as" from\nthe table above, the move into the next section, and what the music does\nthere. That table is the storyboard; build from it, never from memory of the\nvideo.\n\n**Measure a reference shot before moving anything.** Thumbnails and contact\nsheets are too small to read perspective or depth; guesses from them are\nwrong. Pull full-resolution frames every ~0.1 s across the move (`ffmpeg`, or\n`preview_media` with `saveToDisk`) and measure a few things per frame: the\nsubject\'s width, where its top edge sits, how much that edge narrows (tilt).\nThose numbers tell a camera move (subject grows, edge barely moves) from a\nslide, give the starting tilt, and show *when* it moves \u2014 most moves happen in\na short burst and then hold. Match that timing with the eases; never spread a\nmove evenly because the reference "moves for a second". After every change,\nrender your frame and the reference at the same timestamps, side by side.\n\n## Tool habits that save rework\n\n- **Swap a picture, don\'t re-add it.** `replace_clip_media` changes what a\n  clip plays and keeps its position, scale, effects, grade, keyframes and\n  parent. Deleting and inserting starts the new clip from defaults. A picture\n  of a different shape keeps the same scale \u2014 check the framing.\n- **Parent first, then animate the parent.** `set_parent` measures the child\n  against the parent\'s pose when the child starts (or at `time`), not the\n  playhead. Set the child\'s position and scale for the parent as it is at\n  that moment. To follow a parent that is already animated, pass the `time`\n  you laid the child out at.\n- **One camera, not many keyframed layers.** For a 3D move across a layout,\n  put the planes in 3D at their depths and animate `set_camera` once,\n  instead of keying Z on every layer. 3D layers and `.glb` models sort by\n  depth through it. The reply lists the layers it sees and warns when a 2D\n  layer sits between them in the stack.\n- **One effect on many clips.** Applying an effect with several clips\n  selected adds it to each; in the editor, editing or removing it from the\n  inspector changes all of them. Over MCP, `set_clip_effect` acts on the\n  clip you name \u2014 call it per clip, or use `batch_edit`.\n- **Frames to disk.** Over the local connector `render_preview_frame` and\n  `preview_media` write a full-resolution file by default and return its path;\n  read it with your file tools. Over the cloud connector they come back\n  inline, shrunk to fit. Contact sheets (`times`) are one image either way.\n- **Cut-outs keep their transparency through a colour grade and the CSS-type\n  effects** (brightness, contrast, blur). Grade the cut-out to match the\n  ground it sits on.\n- **3D limits today.** A `.glb` model drawn from a recording is redrawn live\n  while the camera turns it, so it costs a live render. A 3D layer cannot be\n  a parent: for a screen that tilts with a phone, nest the phone and its\n  screen (`nest_clips`) and put the 3D layer on the nest. A `.glb` model\'s\n  screen cannot show an image or video.\n\n## The quality bar\n\nA finished video clears all of these. Each is something a viewer notices.\n\n- **The first frame works as a thumbnail** and the first 2\u20133 seconds say what\n  the video is about, even muted.\n- **One focal point per frame.** The hero is clearly bigger, brighter or\n  sharper than everything else \u2014 about 2\u20133\xD7 the next element. If you squint\n  and two things compete, one goes.\n- **Everything is readable.** Text holds on screen at least 0.3 s a word plus\n  0.5 s, sits inside the safe area, and has contrast of 4.5:1 or better\n  (body) and 3:1 (large display type) against what is actually behind it.\n- **Nothing moves linearly, nothing moves for no reason.** Every move points\n  the eye at what changed. No idle bobbing to fill time \u2014 add story instead.\n- **The cuts flow.** Every scene change is either a deliberate hard cut on a\n  beat or a join where motion carries through.\n- **The layouts vary** and the look stays one look: one type family pairing,\n  one palette, one motion feel, the same caption style throughout.\n- **Every picture earns its place.** B-roll shows the noun being said, at the\n  moment it is said. No generic stock filler, no tiny UI floating in space.\n- **Sound is finished.** Voice clear and on top, music ducked under it, no\n  clipped peaks, loudness near the platform target.\n- **It ends on purpose** \u2014 a payoff, a call to action, or a held end card \u2014\n  never a fade to nothing mid-thought.\n\n## Checks before handing over\n\nRun them and say which ran and what they showed. A check not run is reported\nas not run, never as passed.\n\n1. `lint_timeline` and `lint_motion`; apply each fix one call at a time, lint\n   again until only judgement notes remain.\n2. `list_cuts` \u2014 every cut intended; `stillCuts` joined or deliberate.\n3. `export_range` with 12\u201324 frames over each section (one tiled sheet), and\n   a strip around every join (\u22120.3, \u22120.15, 0, +0.15, +0.35 s). Look for blank\n   frames, flashes, text over faces, captions over the wrong shot.\n4. `render_preview_frame` at the first frame, the busiest frame, the end card,\n   and behind every caption style.\n5. `probe_audio` over the whole video: voice present, `truePeak` at or below\n   \u22121 dBTP, integrated loudness near the platform target.\n6. The self-review below.\n\n## Self-review: critique it like a hard client\n\nLook at the frames from step 3 and score each line 1\u201310. Anything under 7\ngets fixed before you hand over, and you say what you changed.\n\n- **Impact** \u2014 does the first frame stop a scroll? Is there one clear idea?\n- **Hierarchy** \u2014 one dominant element per frame, a clear reading order,\n  weight and size contrast (not everything bold).\n- **Colour and type** \u2014 a deliberate palette (not default pure red, pure\n  black, pure white), at most two families, sizes from one scale.\n- **Motion** \u2014 eases with character, staggered entrances, joins that carry\n  momentum, no dead air and no wobble.\n- **Craft** \u2014 alignment to a grid, consistent margins, no clipped text, no\n  stray layers, captions consistent.\n- **Story** \u2014 hook, build, payoff; every beat earns its seconds.\n\nThen name the single weakest frame and improve it. A lint pass is not a watch:\nyou cannot hear, so ask the user to watch for lip sync and clipped words.\n\n## Failure list \u2014 what makes a video look AI-made\n\n- The same centred title-over-background layout on every beat.\n- Small subjects floating in big empty frames; whole web pages shrunk to phone\n  size.\n- Everything bold, everything the same size, everything the same colour.\n- Default palettes: pure #FF0000, #000000 and #FFFFFF together; rainbow\n  accents; a different accent per scene.\n- Linear moves, everything entering at once, every element fading up the same\n  way, crossfades between every scene.\n- Text that leaves before it can be read; captions that blink or jump styles.\n- Stock shots that only loosely match the words; AI stills used as B-roll;\n  invented numbers or redrawn logos.\n- A music bed at full level over the voice, a whoosh on every cut.\n- Ending on a fade to black in the middle of a sentence.\n\n## Talking to the user\n\n- Before a long run of edits, say the plan in two or three lines, then work\n  without stopping to ask.\n- Offer variants for open-ended requests (one sequence each: fast cut, story\n  cut, minimal cut) and call `record_choice` when they pick, so GoatEdit\n  learns their taste.\n- Never publish or post anything, never promise a video will go viral, never\n  call a draft final \u2014 the user\'s review is the last gate.\n',
-        "digest": "sha256:47c6b51c0cb0d84dfb54f51f6a73c99e8f25f389bd7f00e473c91d9760807f29"
+        "text": '---\nname: goatedit-video-director\ndescription: Start here for any GoatEdit video \u2014 reel, short, ad, explainer, product launch, tutorial, talking head, kinetic type, montage. The director\'s workflow (brief, references, script, storyboard, style frames, build, motion, sound, checks), which other GoatEdit skill to load for each step, the quality bar a finished video must clear, and the self-review that catches what lint cannot. Use before the first edit of a new video or a big change to one.\n---\n\n# GoatEdit video director\n\nYou are directing a video, not filling a timeline. Tools do the mechanics; this\nskill and its four siblings carry the taste. Load them as you reach each step:\n\n| Step | Load |\n| --- | --- |\n| Look: type, colour, layout, safe areas, choosing a look | `goatedit-visual-design` |\n| Motion: easing, timing, joins between scenes, kinetic type | `goatedit-motion-design` |\n| Story, cutting, B-roll, captions, sound, grade | `goatedit-editing-story` |\n| The playbook for the kind of video asked for | `goatedit-formats` |\n\nNo skill support in your app? Call `get_design_guide` \u2014 it serves the same\ntext by skill, section or keyword (`get_design_guide({ topic: "captions" })`).\n\n## Order of authority\n\n1. What the user asked for in this conversation.\n2. Their saved style (`get_style_profile`) and brand.\n3. These skills.\n\nA reference video the user gives beats every number here. Measure it\n(`begin_request` with `referenceMediaIds`) and match it.\n\n## The workflow\n\nNever skip ahead. Each step ends with something the user can approve.\n\n1. **Brief.** `begin_request` with the edit type and the user\'s style words,\n   then `get_style_profile`. Write back, in three lines: who it is for, the\n   one thing they should remember, the platform and length. Ask only what you\n   cannot infer: platform, length, brand, whether there is a voiceover.\n2. **References.** Ask for one or two videos they like, or name two you will\n   aim at ("a Vox explainer", "an Apple product film"). Say what you take from\n   each: pacing, type, colour, motion feel.\n3. **Script and beat sheet.** For anything with words, write the script first.\n   Split it into beats, one idea each, with a target duration. Spoken words run\n   about 2.5 a second; a 30 s reel holds about 70 words. With a voiceover the\n   voice is the clock: generate or record it, `transcribe`, and time every beat\n   from real word timings, never from word counts.\n4. **Storyboard.** One line per beat: what is on screen, the hero element, the\n   layout, what each element is built as (see Build map), the move into the\n   next beat. Vary the layouts (full-bleed, split,\n   type-only, close-up, data); never the same composition three beats running.\n   Plan joins now: layers that become each other across a cut share a name\n   ending ("S2 tag Price" then "S3 card Price") so `join_scenes` can morph them.\n5. **Animatic, then style frames.** For motion-graphics pieces, first build\n   a rough draft of every section: black and white, plain type, flat shapes,\n   one simple move each, timed to the voice or music. It proves the plan \u2014\n   which idea goes in which section and when each move lands \u2014 before any\n   polish. Then build two or three key frames as finished stills (the hook,\n   the busiest beat, the end card), `render_preview_frame` each and show the\n   user. Polish nothing until the plan and the look are approved. One element\n   per layer.\n6. **Build.** Lay every beat on the timeline with its real duration. Plan\n   tracks first (overlapping clips on one track replace each other): V1 main\n   picture, V2 B-roll, V3 graphics, V4 captions; A1 voice, A2 music, A3\n   effects. Mark beats with `set_scene`. Where the connector offers `run_tools`,\n   send several edits as one call.\n7. **Motion.** `animate_scene` per scene in one feel for the whole video,\n   hand-key only the hero move, then join the cuts (`list_cuts`, `join_scenes`).\n   See `goatedit-motion-design`.\n8. **Sound.** Music bed, voice, effects only on visible actions, ducking,\n   loudness. See `goatedit-editing-story`.\n9. **Check** (below). Fix, re-check, then hand over with the report.\n\nFor a quick edit (trim this, add captions, swap the music) skip to the step it\ntouches, but still run the checks that cover it.\n\n## Build map: what each element is made of\n\nDecide this per element at storyboard time and write it in the storyboard as\na "build as" column. The rule under every row: **anything the user might want\nto move, retime, recolour or swap is its own layer.**\n\n| Element | Build as | Not as |\n| --- | --- | --- |\n| Designed words \u2014 a headline, a kinetic line, a word that changes colour | text clips (`create_text_clip` + `set_text_animation`), one clip per line, or per word when that word moves on its own | words inside an HTML clip, or caption cards |\n| Spoken words, timed to the voice | captions (`generate_captions`), on their own track, one style | text clips placed by hand, words in HTML |\n| A word that turns into an icon or a picture | the word, the icon and the next word as separate clips; `join_scenes` `morph` or `matchCut` between them | one clip with everything baked in |\n| UI that behaves like UI \u2014 a typing field, chat bubbles arriving, a list scrolling, a toggle, a progress bar | one HTML clip per UI surface, CSS or WAAPI animation, no scripts. Text inside the UI stays in the HTML: it is part of the interface, not the film\'s type | a pile of text and shape clips pretending to be an app |\n| A moving backdrop \u2014 mesh gradient, soft glow blobs, grid, grain | one HTML clip on the lowest track, or a shape with effects | baked into a picture or into the scene\'s HTML |\n| A phone, laptop or monitor showing something | the device as its own layer; the screen content (HTML, footage, still) as another, masked to the screen with `set_mask` and parented to the device with `set_parent`; hands on top as a cut-out | one flat picture of a device with a screen |\n| A ring, globe, tunnel, orbit, fan or carousel of cards \u2014 pictures, clips or UI stills looping in 3D | `create_showcase` with the right template (the Presets panel\'s Showcase shelf), filled from the bin; tune it with `set_clip_effect` on its showcase effect | cards keyframed one by one round a null |\n| A product with words circling it | `create_showcase` with a product template (`productRing`, `productOrbit`\u2026) and the cut-out or 3D model | hand-built text on a path |\n| A few floating photos or cut-outs that each move on their own | one image clip each (`remove_background` for cut-outs), each with its own shadow, parented to a null (`add_null`) so the group drifts as one | a flattened collage image |\n| Props with depth \u2014 candy shapes, a tumbling object, a glass ring | `create_3d_shape` with one `material` family for the whole video | 3D for flat UI, body text or anything that must be read |\n| A logo with depth, a word as a solid | `create_3d_object` (text, or a transparent PNG or SVG) | \u2014 |\n| Logo reveal | the mark and the wordmark as separate layers so they can assemble | one image that fades in |\n| A scene change | `join_scenes` between the scenes | a transition drawn inside an HTML clip |\n\n**Text: designed or caption?** Ask: if the voice were deleted, would this text\nstill need to be on screen? Yes \u2014 it is designed type: a text clip, placed and\nanimated with the layout. No \u2014 it transcribes speech: a caption. A video can\nhave both; they never share a track or a style, and a designed headline never\ndoubles as the caption of the line it shows.\n\n**When HTML is the right call.** Something that behaves like a web page or an\napp, or motion that is trivial in CSS and miserable to keyframe (a ticker, a\ntyping cursor, a looping gradient). When it is wrong: the parts must animate\nseparately, morph into the next scene, be retimed by the user, or the text is\nthe hero. An HTML clip is one layer to everything else in GoatEdit. HTML clip\nrules: layout in px for the composition size, longhand font properties rather\nthan the `font` shorthand, class-styled divs rather than styled `b` or `span`,\nand animate inside the snippet \u2014 moving the clip crops it at its box.\n\n**When 3D earns its place.** One hero object or a handful of accents a scene,\nlit and finished the same way across the video (one material family, one\nlight direction). It renders slower than anything else, so keep it to the\nmoments that need depth: a logo, a product, props that burst or tumble past a\ndevice. Depth comes from scale, blur and parallax as much as from the model.\n\n**Track order, bottom to top:** backdrop; footage and devices; collage and 3D\nprops; designed type; UI overlays and cursor; captions; brand bug.\n\n**Breaking down a reference.** Watch it through, then for each section write:\ntime in and out, what is on screen, every element with its "build as" from\nthe table above, the move into the next section, and what the music does\nthere. That table is the storyboard; build from it, never from memory of the\nvideo.\n\n**Measure a reference shot before moving anything.** Thumbnails and contact\nsheets are too small to read perspective or depth; guesses from them are\nwrong. Pull full-resolution frames every ~0.1 s across the move (`ffmpeg`, or\n`preview_media` with `saveToDisk`) and measure a few things per frame: the\nsubject\'s width, where its top edge sits, how much that edge narrows (tilt).\nThose numbers tell a camera move (subject grows, edge barely moves) from a\nslide, give the starting tilt, and show *when* it moves \u2014 most moves happen in\na short burst and then hold. Match that timing with the eases; never spread a\nmove evenly because the reference "moves for a second". After every change,\nrender your frame and the reference at the same timestamps, side by side.\n\n## Tool habits that save rework\n\n- **Swap a picture, don\'t re-add it.** `replace_clip_media` changes what a\n  clip plays and keeps its position, scale, effects, grade, keyframes and\n  parent. Deleting and inserting starts the new clip from defaults. A picture\n  of a different shape keeps the same scale \u2014 check the framing.\n- **Parent first, then animate the parent.** `set_parent` measures the child\n  against the parent\'s pose when the child starts (or at `time`), not the\n  playhead. Set the child\'s position and scale for the parent as it is at\n  that moment. To follow a parent that is already animated, pass the `time`\n  you laid the child out at.\n- **One camera, not many keyframed layers.** For a 3D move across a layout,\n  put the planes in 3D at their depths and animate `set_camera` once,\n  instead of keying Z on every layer. 3D layers and `.glb` models sort by\n  depth through it. The reply lists the layers it sees and warns when a 2D\n  layer sits between them in the stack; `lint_timeline` repeats that warning\n  after later edits. A backdrop with layer3d `fill: 1` covers the frame for\n  the whole move.\n- **One effect on many clips.** Applying an effect with several clips\n  selected adds it to each; in the editor, editing or removing it from the\n  inspector changes all of them. Over MCP, `set_clip_effect` acts on the\n  clip you name \u2014 call it per clip, or use `batch_edit`.\n- **Frames to disk.** Over the local connector `render_preview_frame` and\n  `preview_media` write a full-resolution file by default and return its path;\n  read it with your file tools. Over the cloud connector they come back\n  inline, shrunk to fit. Contact sheets (`times`) are one image either way.\n- **Cut-outs keep their transparency through a colour grade and the CSS-type\n  effects** (brightness, contrast, blur). Grade the cut-out to match the\n  ground it sits on.\n- **3D limits today.** A `.glb` model drawn from a recording is redrawn live\n  while the camera turns it, so it costs a live render. A 3D layer cannot be\n  a parent: for a screen that tilts with a phone, nest the phone and its\n  screen (`nest_clips`) and put the 3D layer on the nest. A `.glb` model\'s\n  screen cannot show an image or video.\n\n## The quality bar\n\nA finished video clears all of these. Each is something a viewer notices.\n\n- **The first frame works as a thumbnail** and the first 2\u20133 seconds say what\n  the video is about, even muted.\n- **One focal point per frame.** The hero is clearly bigger, brighter or\n  sharper than everything else \u2014 about 2\u20133\xD7 the next element. If you squint\n  and two things compete, one goes.\n- **Everything is readable.** Text holds on screen at least 0.3 s a word plus\n  0.5 s, sits inside the safe area, and has contrast of 4.5:1 or better\n  (body) and 3:1 (large display type) against what is actually behind it.\n- **Nothing moves linearly, nothing moves for no reason.** Every move points\n  the eye at what changed. No idle bobbing to fill time \u2014 add story instead.\n- **The cuts flow.** Every scene change is either a deliberate hard cut on a\n  beat or a join where motion carries through.\n- **The layouts vary** and the look stays one look: one type family pairing,\n  one palette, one motion feel, the same caption style throughout.\n- **Every picture earns its place.** B-roll shows the noun being said, at the\n  moment it is said. No generic stock filler, no tiny UI floating in space.\n- **Sound is finished.** Voice clear and on top, music ducked under it, no\n  clipped peaks, loudness near the platform target.\n- **It ends on purpose** \u2014 a payoff, a call to action, or a held end card \u2014\n  never a fade to nothing mid-thought.\n\n## Checks before handing over\n\nRun them and say which ran and what they showed. A check not run is reported\nas not run, never as passed.\n\n1. `lint_timeline` and `lint_motion`; apply each fix one call at a time, lint\n   again until only judgement notes remain.\n2. `list_cuts` \u2014 every cut intended; `stillCuts` joined or deliberate.\n3. `export_range` with 12\u201324 frames over each section (one tiled sheet), and\n   a strip around every join (\u22120.3, \u22120.15, 0, +0.15, +0.35 s). Look for blank\n   frames, flashes, text over faces, captions over the wrong shot.\n4. `render_preview_frame` at the first frame, the busiest frame, the end card,\n   and behind every caption style.\n5. `probe_audio` over the whole video: voice present, `truePeak` at or below\n   \u22121 dBTP, integrated loudness near the platform target.\n6. The self-review below.\n\n## Self-review: critique it like a hard client\n\nLook at the frames from step 3 and score each line 1\u201310. Anything under 7\ngets fixed before you hand over, and you say what you changed.\n\n- **Impact** \u2014 does the first frame stop a scroll? Is there one clear idea?\n- **Hierarchy** \u2014 one dominant element per frame, a clear reading order,\n  weight and size contrast (not everything bold).\n- **Colour and type** \u2014 a deliberate palette (not default pure red, pure\n  black, pure white), at most two families, sizes from one scale.\n- **Motion** \u2014 eases with character, staggered entrances, joins that carry\n  momentum, no dead air and no wobble.\n- **Craft** \u2014 alignment to a grid, consistent margins, no clipped text, no\n  stray layers, captions consistent.\n- **Story** \u2014 hook, build, payoff; every beat earns its seconds.\n\nThen name the single weakest frame and improve it. A lint pass is not a watch:\nyou cannot hear, so ask the user to watch for lip sync and clipped words.\n\n## Failure list \u2014 what makes a video look AI-made\n\n- The same centred title-over-background layout on every beat.\n- Small subjects floating in big empty frames; whole web pages shrunk to phone\n  size.\n- Everything bold, everything the same size, everything the same colour.\n- Default palettes: pure #FF0000, #000000 and #FFFFFF together; rainbow\n  accents; a different accent per scene.\n- Linear moves, everything entering at once, every element fading up the same\n  way, crossfades between every scene.\n- Text that leaves before it can be read; captions that blink or jump styles.\n- Stock shots that only loosely match the words; AI stills used as B-roll;\n  invented numbers or redrawn logos.\n- A music bed at full level over the voice, a whoosh on every cut.\n- Ending on a fade to black in the middle of a sentence.\n\n## Talking to the user\n\n- Before a long run of edits, say the plan in two or three lines, then work\n  without stopping to ask.\n- Offer variants for open-ended requests (one sequence each: fast cut, story\n  cut, minimal cut) and call `record_choice` when they pick, so GoatEdit\n  learns their taste.\n- Never publish or post anything, never promise a video will go viral, never\n  call a draft final \u2014 the user\'s review is the last gate.\n',
+        "digest": "sha256:b5b2e12438ba7ea3bd51f4e5be2641259a022cb6584a9a352f099a0bf23e2096"
       }
     ]
   },
@@ -25501,6 +25589,7 @@ for (const [alias, name] of Object.entries(TOOL_ALIASES)) {
   const tool = BROWSER_TOOLS_BY_NAME.get(name);
   if (tool) BROWSER_TOOLS_BY_NAME.set(alias, tool);
 }
+var PROJECT_FREE_TOOLS = /* @__PURE__ */ new Set(["create_project", "begin_request", "record_choice", "set_style_brand"]);
 var SAVES_FRAMES = new Set(
   BROWSER_TOOLS.filter((t) => "saveToDisk" in (t.inputSchema.properties ?? {})).map((t) => t.name)
 );
@@ -25540,11 +25629,20 @@ async function callTool(name, args) {
   if (!tool) {
     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
   }
-  const saveToDisk = SAVES_FRAMES.has(name) && forwarded.saveToDisk === true;
-  if (saveToDisk) delete forwarded.saveToDisk;
+  const saveToDisk = SAVES_FRAMES.has(name) && forwarded.saveToDisk !== false;
+  if (SAVES_FRAMES.has(name)) forwarded.saveToDisk = false;
   const invalid = validateArgs(tool, forwarded);
   if (invalid) throw new McpError(ErrorCode.InvalidParams, invalid);
   const target = projectId ?? chosenProjectId;
+  if (!target && !READ_ONLY_TOOLS.has(tool.name) && !PROJECT_FREE_TOOLS.has(tool.name)) {
+    const open = connectedProjects();
+    if (open.length > 1) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `${open.length} projects are open, so ${tool.name} needs projectId to say which one it edits. Open: ${open.map((p) => `${p.name ?? "untitled"} (${p.projectId})`).join(", ")}. Pass projectId on the call (or once on run_tools), or call use_project first.`
+      );
+    }
+  }
   if (name === "import_local_file") return importLocalFile(forwarded, target);
   const result = await sendToBrowser(tool.method, forwarded, target);
   const withFile = saveFileToDisk(result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goatedit-mcp",
-  "version": "1.1.18",
+  "version": "1.1.20",
   "description": "Local MCP server for the GoatEdit video editor: drive your open editor tab from Claude Code or any MCP client",
   "license": "UNLICENSED",
   "type": "module",