@nodetool-ai/agents 0.8.4-a24.3 → 0.8.5

package/dist/_skills/motion-principles/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: motion-principles
+description: Choose timing, easing, stagger, anticipation, and follow-through for a NodeTool timeline. Use when motion feels stiff, floaty, busy, or late, or when an entrance, transition, or beat-bound animation needs a duration and curve. The op contract lives in timeline-edit-ops; the build loop is motion-graphics.
+---
+
+# Motion Principles → the numbers before the call
+
+`timeline-edit-ops` is how to write an animation onto a clip with
+`edit_timeline`. This is how to decide what to write. Every number here is in
+the units `animate_clip` takes: milliseconds, a normalized 0..1 distance, an
+easing string.
+
+## The same numbers, written as code
+
+Building with `@nodetool-ai/sandbox-timeline` instead (`motion-graphics`
+picks the surface)? Every number below still applies — only the unit
+changes. `durationMs` becomes `dur` in seconds (divide by 1000: 400ms is
+`dur: 0.4`). A normalized 0..1 distance becomes actual px, against the
+frame's own `width`/`height` (0.3 on a 1920-wide frame is `offsetX: 576` in
+`from`). Easing strings are identical — `ease: "outExpo"` or a raw curve —
+and every role still means the same thing: `el.enter()` is `in`, `el.exit()`
+is `out`, `el.animate()` covers `emphasis` and general keyframing,
+`el.loop()` is `loop`. `el.count()`, `el.draw()`, `el.scramble()`,
+`el.typewriter()`, `el.expr()` and `el.morph()` have no ops equivalent
+below; they are shortcuts for a ticker, a `trimEnd` draw-on, a scramble
+reveal, a whole-clip typewriter entrance, a hand-written keyframe function,
+and a path outline morph.
+
+## Settle three things before picking a number
+
+| Pillar | The question | What it decides |
+|---|---|---|
+| Emotional intent | What should the viewer feel? | Easing, duration, overshoot |
+| Visual narrative | Setup, action, resolution — what enters when? | Sequencing, `delayMs`, stagger |
+| Motion craft | Why does it look believable? | Anticipation, follow-through, arcs |
+
+A number chosen before the intent is a number you will change twice.
+
+## Three layers, or the frame reads flat
+
+Plan three levels of attention. Track index controls their z-order, while
+timing decides which one the eye follows:
+
+- **Primary** — the one move the eye follows. The clip the shot is about.
+- **Secondary** — supporting motion reacting to the primary: a scrim settling
+  late, a label arriving 80ms after the plate.
+- **Ambient** — background life that never asks for attention. A `loop` preset
+  at low amplitude on the bed.
+
+`motion-direction` ranks the same three as Hero / Support / Texture and decides
+which elements earn each. Two clips carrying primary motion at once is the most
+common cause of a busy frame.
+
+## Easing is the biggest lever
+
+`linear` reads as robotic. Keep it for motion that never lands: the `loop`
+presets `float`, `rotate` and `hueShift`, and the `shake` emphasis, whose
+zig-zag is linear by default. Everything the eye reads as an event decelerates
+into rest.
+
+| Action | Easing | Why |
+|---|---|---|
+| Entrance (`in`) | `easeOut`, or `cubic-bezier(0.16,1,0.3,1)` for a sharper landing | Arrives with energy, settles |
+| Exit (`out`) | `easeIn`, or `cubic-bezier(0.7,0,0.84,0)` | Accelerates away |
+| A move that stays on screen | `easeInOut`, or `cubic-bezier(0.65,0,0.35,1)` | Symmetric, no false weight |
+| Playful landing | `easeOutBack`, or `cubic-bezier(0.34,1.56,0.64,1)` | The value past 1 is the overshoot |
+| Physical settle | `spring(180,12,1)` one overshoot, `spring(180,26,1)` none | Solves a real spring; all three constants positive |
+| Held pose, then jump | `hold` on the ending keyframe's segment | Keeps the prior value until the segment ends |
+
+The role defaults already do the right thing: `in` gets `easeOut`, `out` gets
+`easeIn`. Leave `easing` unset unless you want something the default is not.
+A string the parser cannot read eases linearly and reports `unknown_easing` —
+`easeOut`, never `ease-out`.
+
+Overshoot reads as toy-like. Keep `easeOutBack`, `easeOutElastic` and
+`easeOutBounce` off anything financial, medical or corporate.
+
+## Duration carries weight
+
+| Element | `durationMs` |
+|---|---|
+| Micro beat: a `flash`, a `pulse` on a small element | 150–250 |
+| Title, lower third, overlay entrance | 300–500 |
+| Hero element, full-frame plate, a `blur` rack | 500–800 |
+| Camera move: a slow push or drift | 1500–4000 |
+
+Distance and area scale it. A caption travelling `distance: 0.05` and a
+full-bleed plate travelling `0.5` must not share 400ms — the plate looks
+weightless. Add roughly 30–50% when the travel or the area doubles.
+
+Two limits the engine enforces rather than warns about in prose:
+
+- `in` + `out` must fit the clip with hold left over. Over-long windows report
+  `animation_exceeds_clip`.
+- A `loop` cycle longer than the clip shows a fragment. `kenBurns` is the
+  exception: it ignores `durationMs` and always spans the whole clip, so the
+  clip's length is its duration. Give a Ken Burns move a clip in the camera-move
+  range above.
+
+## Holds
+
+These are the hold values every other motion skill defers to:
+
+- **Read hold.** Anything meant to be read — a title, a lower third, an end
+  card, a logo — rests at least 1000ms between its `in` settling and its `out`
+  starting, or before the cut. A 3000ms title with 500ms each way holds 2000ms.
+  Under 1000ms the element never settles and reads as a glitch.
+- **Rest between moves.** Two consecutive moves on the same hero or support
+  element leave at least 400ms with that element still. Ambient `loop` motion
+  on the bed does not count against it and keeps running.
+
+## Stagger is rhythm, and it is clamped
+
+Never reveal a group in one event. On a text clip, `stagger` splits the
+animation per word, grapheme or wrapped line. Which `unit` counts what, and how
+the count changes with the frame, is in `timeline-edit-ops`.
+
+| Content | `offsetMs` |
+|---|---|
+| A short mark or word revealed per character | 30–50 |
+| A phrase that should arrive with texture | 60–100 |
+| A short punchline landing word by word | 150–250 |
+| More than five words | do not stagger — the reader is waiting on the sentence |
+
+The span is `durationMs + offsetMs × (units − 1)`, halved for `from: "center"`.
+Work it out and compare it against the clip's `durationMs` minus `delayMs`. A
+span that does not fit is **compressed silently**: the engine shrinks the offset,
+never the per-unit duration, so the line lands flatter than written and only
+`validate_timeline` says so, as `stagger_compressed`.
+
+For a group of separate clips — three lower-third parts, five icons — stagger by
+giving each clip's `in` animation a `delayMs` 60–80ms apart, and start the last
+clip no more than about 700ms after the first. Past that the tail drags. This
+step applies to every clip-to-clip build, including logo parts and strokes.
+
+## The 1/3 rule, in both forms
+
+- **Distance.** Nothing travels more than about a third of the frame in one
+  unbroken move. `slide` with `distance` above 0.35 reads as "the template
+  moved". Break it with a scale or opacity change on the same window, or shorten
+  the travel.
+- **Simultaneity.** With three or more elements, keep at most a third in active
+  motion at any instant. The rest hold, or run ambient loops.
+
+## Anticipation, follow-through, arcs
+
+The three that separate animated from moved. None has a preset; each is a
+`custom` animation, which is where a short `code` body earns its place.
+
+**Anticipation** — a counter-move of 60–120ms before the main action. Ask for a
+dip before a pop:
+
+```json
+{"role": "in", "preset": "custom", "durationMs": 520,
+ "curves": [{"property": "scale", "keyframes": [
+   {"t": 0, "value": 1}, {"t": 0.2, "value": 0.94, "easing": "easeInOut"},
+   {"t": 0.75, "value": 1.06, "easing": "easeOut"}, {"t": 1, "value": 1}]}]}
+```
+
+**Follow-through** — attached parts settle 40–80ms after the body. Give the
+child clip the same preset and a `delayMs` 60ms later, rather than animating the
+whole group as one block.
+
+**Arcs** — straight-line translation of anything organic looks mechanical. Drive
+`offsetX` linearly and `offsetY` as a shallow curve over the same window; the
+two fold as `add`, so they compose.
+
+A decaying bounce, an arc, or a settle written as a function of time is a `code`
+body returning `samples` — one bag per point, `{t, offsetY}`, at
+`inputs.sampleCount` points. The body runs once at author time, hermetically, and
+reads `role`, `durationMs`, `clipDurationMs`, `canvasWidth`, `canvasHeight`,
+`params`, `staggerCount` and `sampleCount` off `inputs`:
+
+```js
+// fragment
+const n = inputs.sampleCount;
+const h = 0.06 * inputs.canvasHeight;
+const samples = [];
+for (let i = 0; i < n; i++) {
+  const t = i / (n - 1);
+  // three decaying hops, ending exactly at rest
+  const y = -h * Math.abs(Math.sin(Math.PI * 3 * t)) * (1 - t);
+  samples.push({ t, offsetY: y });
+}
+return { samples };
+```
+
+Land the last sample on the identity value — 0 for an offset, 1 for a scale or
+an opacity — when the motion should settle. An `in` curve contributes nothing
+after its window, an `out` curve holds its last value after the window, and an
+`emphasis` curve returns to its base outside the window.
+
+## Rhythm against audio
+
+Land impact keyframes on the beat. At 120 BPM a beat is 500ms and the eighth
+grid is 250ms. `beat-sync-editing` turns detected onsets into markers and
+snaps. For motion that should follow later tempo edits, store `beat` on the
+animation in the full timeline document. Its `index` is one-based, `scope`
+is `clip` or `sequence`, and `offsetMs` can place anticipation before the hit.
+`edit_timeline`'s `animate_clip` input does not author this field; use
+`get_timeline` and `set_timeline_document` as described in `timeline-edit-ops`.
+
+```json
+{"id":"impact","role":"emphasis","preset":"pulse","durationMs":240,"beat":{"index":3,"scope":"sequence","offsetMs":-20}}
+```
+
+A move ending 80ms after a hit reads late, and one ending 80ms before it can
+weaken the impact. Use `offsetMs` deliberately for anticipation.
+
+With no music, keep one major event per 500–800ms so the piece breathes at a
+constant pulse.
+
+## Spring or duration
+
+`spring(stiffness,damping,mass)` shapes the motion inside the animation's
+`durationMs`; it is scaled to settle near the end of that window. Use it for a
+physical-looking landing, then set `durationMs` against the cut as you would
+for any other easing. For a precise held pose or hard timecode, write
+keyframes and put `hold` on the segment that should stay still.
+
+## Frame texture
+
+Use per-clip `motionBlur` when a fast move strobes. Start with a 180-degree
+shutter and raise `samplesPerFrame` only as far as the frame needs; the highest
+requested sample count is shared by the scene. Use `steppedTime.fps` for a
+deliberate low-frame-rate look, or `temporalEcho` for delayed copies. These are
+stored clip fields written through `set_timeline_document`, not
+`animate_clip` parameters.
+
+## Diagnosing
+
+| It feels | Because | Fix |
+|---|---|---|
+| Stiff, robotic | `linear` or a symmetric curve on an entrance | `easeOut`, or drop `easing` and take the role default |
+| Floaty, slow | Duration too long, curve too gentle | Cut 30%, sharpen to `cubic-bezier(0.16,1,0.3,1)` |
+| Cheap, janky | Everything arrives at once, one duration for every size | Stagger, and scale duration with area |
+| Mechanical despite easing | No anticipation, no overlap, straight-line paths | A `custom` dip before the move; 60ms offsets on attached parts |
+| Busy | Two primary moves in one frame | Demote one to a loop or hold it still |
+| Staggered text does not look staggered | Span exceeded the clip and was compressed | Lengthen the clip or lower `offsetMs` yourself |
+
+## Quick reference
+
+| Need | Value |
+|---|---|
+| Entrance | `easeOut` / `cubic-bezier(0.16,1,0.3,1)`, 300–500ms |
+| Exit | `easeIn` / `cubic-bezier(0.7,0,0.84,0)`, 200–300ms |
+| Move in place | `easeInOut`, 300–400ms |
+| Playful landing | `easeOutBack`, 400–600ms |
+| Word stagger | 60–100ms, five words or fewer |
+| Character stagger | 30–50ms |
+| Clip-to-clip stagger | 60–80ms `delayMs` steps, last clip starts ≤ 700ms after the first |
+| Read hold | ≥ 1000ms at rest before the `out` or the cut |
+| Rest between moves | ≥ 400ms still between two moves of one element |
+| Continuous loop | `linear` when constant speed is intended |
+| Travel cap | `distance` ≤ 0.35 without a second channel |

package/dist/_skills/music-video-treatment/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: music-video-treatment
+description: Turn confirmed track metadata into a shootable, beat-synced music-video treatment and NodeTool storyboard. Use for a music video cut to a track, not ads or promos (commercial-beat-sheet, motion-ad), workflows, pipelines, or finished renders.
+---
+
+# Music Video Treatment → Storyboard Agent
+
+Create a complete, shootable music-video treatment as a NodeTool storyboard. Work directly through storyboard and entity capabilities. Do not build a workflow or pipeline. Do not render or assemble a timeline unless asked.
+
+## Brief and truthfulness
+
+Require artist and persona, track title, genre, BPM, time signature, track length, a timecoded section map, performance-to-narrative ratio, platform, tone, and any mandatory or forbidden content. BPM and section map are hard inputs. If neither a section map nor audio is available, ask rather than invent bar counts. Mark unknown artist, label, release, lyric, or production facts as `[ARTIST INPUT NEEDED]`.
+
+## Entity roster
+
+Resolve the roster before drafting sections: user references first, then `list_entities`, then generate only missing references. The artist is always a character entity and a provided press image is never regenerated. Resolve style first; apply it to generated artist, locations, and props. Keep a typical roster to 4–7 entities: style, artist, 1–2 locations, and 0–2 signature props. Show the roster and flag a generated artist as a stand-in before treatment drafting.
+
+## Music grid and treatment
+
+Compute seconds per bar as `(60 / BPM) × beats per bar`, convert every section into bars and timecodes, and make every transition land on a bar, beat, or lyric. Build three distinct directions with a performance/narrative ratio, repeatable chorus hook shot, drop event, risk, and entity roster. Recommend one in two sentences or fewer.
+
+For each section, provide timecode and bar range, musical and visual jobs, framing, lens/angle, movement, visual/action, sync point, entities, performance, lyric text when applicable, lighting, grade/effect, transition, and why it cuts. Interleave performance and narrative. The biggest event lands on the drop or first chorus downbeat; every chorus repeats the hook shot; include one deliberate rhythmic break before the final chorus; the outro echoes the intro.
+
+## Persist the board
+
+Create a storyboard with `create_storyboard({ name, brief, style, aspect_ratio })`, using `storyboard_id` from its result. Put the full brief, lyrics, section map, bar grid, and roster in `brief`. The call shapes every board skill shares — entity id equals the asset id you passed in, the fifteen `edit_storyboard` ops, what `set_board` accepts, what text the generator actually reads — are in `storyboard-core` § Tool contract.
+
+Attach entity ids with `edit_storyboard({ storyboard_id, ops: [{ op: "set_board", entity_ids, image_model, video_model }] })` (`set_entities` is only an alias). The two models are the `.ref` of a `find_model` call each, for `text_to_image` and `image_to_video`; load the `prompting_skill` each one names before writing shot text, since `motion`, `action` and the camera movement are the keyframe clip prompt and a performance section is worded differently for Kling's shot list, Hailuo's ordered beats or Seedance's sound brief.
+
+A section usually runs longer than one generated clip (a 20s chorus against a 5–10s clip), so give each section several `add_shot` ops, one per phrase or bar group, each with its slice of the section's duration rounded to 0.5 seconds and the section name in its `slug`. Each action names visible entities in brackets and includes its sync point. The render attaches the artist or a prop to a shot only when its name appears in that shot's text (style and location always apply), so the artist's name goes in every performance shot, or on that shot's own `entity_ids`. Lyric text on screen is a note for the cut and goes on as a text clip after assembly (`caption-titles`), not into the render prompt.
+
+Stop at the planned board unless asked to render. Report the directions, selected treatment, and entity roster.
+
+## Render (only on request)
+
+Stills first with `render_storyboard_stills`; look at each with `view_image` asking what is wrong, and fix a drifting artist at the entity, never in one shot's prompt. Clips with `render_storyboard_clips` at each shot's own `duration_seconds`; the model snaps it to the lengths it offers, which usually leaves frames to trim on the beat. Asking for longer clips than the shots need buys footage the cut throws away: report the extra clip seconds and get the user's go-ahead first (`storyboard-core` § Fusing shots). A clip wrong where its still was right is one `revise_storyboard_clip`. Then `assemble_storyboard_timeline`.
+
+## When the treatment becomes a cut
+
+The bar grid computed above is the plan; `beat-sync-editing` derives the real one from the track with `detect_audio_events` and snaps the cuts to it, so the two must agree before anything is trimmed. The track is the continuity here, so section clips render separately and mute their own audio — `video-audio-continuity` for the case where a piece has no track of its own. `timeline-edit-ops` carries the timeline op contract, `motion-graphics` the build loop, `color-motion` the per-section grade and any colour that moves on the drop, `frame-composition` the repeated hook framing across choruses, and `caption-titles` any lyric or artist card on screen.

package/dist/_skills/nano-banana-pro-prompting/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: nano-banana-pro-prompting
+description: Prompt Google's Nano Banana Pro image model — the art-director brief it plans against, the lock/change/amount/constraints shape every edit needs, and the patterns for typography, diagrams, product mockups and storyboards. Use whenever the model id contains nano-banana-pro (fal-ai/nano-banana-pro, fal-ai/nano-banana-pro/edit, google/nano-banana-pro/text-to-image, google/nano-banana-pro/edit, google/nano-banana-pro/edit-ultra, google/nano-banana-pro/text-to-image-ultra, kie's nano-banana-pro, and Gemini's own gemini-3-pro-image) on generate_image, edit_image or a TextToImage node. Not for Nano Banana 2 or plain Nano Banana.
+---
+
+# Nano Banana Pro → write the brief, not the adjectives
+
+Google describes Nano Banana Pro as planning a composition before it paints
+one: it settles the layout and the lighting, and only then commits to pixels.
+Two things follow. It can reason a picture out — a solved equation on a whiteboard, a process diagram in
+the right order — and it gets sharper the more it knows about the job, so one
+sentence of context beats one more adjective.
+
+Reach it with `find_model` for `text_to_image` or `image_to_image`, then
+`generate_image` / `edit_image`. Nothing below is a parameter; it is all prompt
+text.
+
+## The generation brief
+
+Eight slots. Fill the ones the shot needs, in this order:
+
+| Slot | What goes in it |
+| :--- | :--- |
+| Subject | Who or what, in concrete terms |
+| Action | What the subject is doing |
+| Setting | Place, time of day, the light in the room |
+| Style | The finished look, photoreal through flat illustration |
+| Composition and camera | Framing, angle, lens behaviour — brief it like a photographer |
+| Lighting and colour | How it is lit, and the grade |
+| Text | Any words on the image, in quotes |
+| Constraints | What stays out of frame ("no hands, no logos, no hotspots") |
+
+A filled brief:
+
+> A matte-black stainless steel insulated water bottle, 750ml, slim cylindrical
+> body, brushed metal cap. It stands upright on a wet slate countertop, a few
+> condensation droplets sliding down its side, mid-morning, in a quiet kitchen
+> by a north-facing window, soft overcast daylight from the left. Photoreal
+> high-end commercial product photography. Tight three-quarter hero shot,
+> slightly below eye level so the bottle reads tall, 85mm at f/8 so the whole
+> product stays sharp while the background falls into soft blur. One large
+> softbox left, a subtle reflector right to control falloff; cool desaturated
+> grade, clean neutral whites, a faint blue cast in the shadows. The words
+> "STAY COLD. 24 HOURS." in small caps along the lower third. No other props,
+> no hands, no visible brand logos, no harsh specular hotspots on the metal.
+
+Add a line about who the image is for when you have one. "This is for a
+high-end cookbook" sends the planning step toward shallow focus and careful
+plating on its own.
+
+## The edit brief
+
+Edits drift the moment you stop describing what stays. Four slots, and the
+first one is the whole trick:
+
+- **Lock** — everything that must not move. Face and layout first, then the
+  details you would notice missing: a finish, a text line, the droplets, the
+  angle.
+- **Change** — the single thing you are altering.
+- **Amount** — how far to take it.
+- **Constraints** — what the edit must not break.
+
+> Lock: the water bottle — matte-black finish, brushed cap, slim cylindrical
+> body, the "STAY COLD. 24 HOURS." text, the condensation droplets, its size
+> and position in frame, the three-quarter hero angle. Change: swap the
+> kitchen-counter background for a flat grey boulder beside a sunlit mountain
+> trail. Amount: full environment swap, understated — soft natural daylight,
+> not golden hour; shot on location, not composited. Constraints: don't relight
+> or recolour the bottle beyond the new ambient light; no new reflections or
+> hotspots on the metal; keep the original cool grade; don't touch the cap,
+> droplets or text; no hands, people or gear in frame.
+
+**One change per call.** Ten edits in one sentence is how you lose track of
+which one broke the image. Re-state the lock list on every pass.
+
+## Rules that keep it from reading as AI
+
+- Adjectives do not render. "Stunning" draws nothing; overcast light and
+  chipped paint draw something.
+- Pin style words to something concrete. "Cinematic" drifts; "a teal-and-amber
+  grade with hard shadows" does not.
+- Name the real thing. If the shot needs a boarding pass, the words "boarding
+  pass" beat any amount of mood language.
+- Wrap on-image text in quotes and call out the typeface and its position. When
+  the model keeps dropping a letter, spell the word out. That is for a poster or
+  a mockup that ships as an image; a still headed for a timeline, or a
+  storyboard keyframe, keeps its copy off the picture and gets it as a text clip
+  afterwards (`caption-titles`), where it stays editable.
+
+The contrast is the whole lesson. "A gorgeous hyper-detailed photo of a potter,
+masterpiece, cinematic, 8k" gives the model nothing to decide against. "A
+ceramicist in her 40s centering wet clay on a spinning wheel in a cluttered
+studio, late-afternoon light raking across the workbench, grey slip drying on
+her forearms, a row of unglazed bowls on the shelf behind her, eye-level at
+50mm with shallow focus, muted earth tones" is a list of decisions the model no
+longer has to invent.
+
+## Patterns worth reaching for
+
+- **Typography and posters** — name the print process, the ink colours, the
+  exact words in quotes, the type class and its position: "risograph gig
+  poster, two-colour overprinted teal and burnt orange, visible halftone,
+  'BLUE ROOM SESSIONS' large in a condensed slab serif across the top,
+  'Thursdays, 9pm' in small monospace at the bottom, slightly misregistered".
+- **Infographics and diagrams** — this is where the planning step pays. Ask for
+  a labelled cross-section or a bar comparison, name the palette and the type
+  class, and end with "keep every label legible".
+- **Directing the shot** — one hard light source, named falloff, a named lens:
+  "lit by one hard source from a window at camera left, deep falloff into
+  shadow, a thin rim along the fruit's edge, macro so the waxy skin reads".
+- **Wireframe to screen (edit)** — "use the attached pencil wireframe as the
+  exact layout"; then the palette, the type class and the copy.
+- **Storyboards** — ask for N panels in one image, name the medium ("loose
+  black-and-white marker sketches") and vary the framing across the panels.
+- **Object swap (edit)** — swap the object, then list the scene, the light, the
+  depth of field, the palette and the existing shadows as unchanged, and ask
+  for matched scale, texture and contact shadows.
+
+## What the model brings
+
+The vendor's guide says resemblance holds for up to 5 people across
+generations and edits, so recurring characters in a campaign or a storyboard
+are workable. Several reference images combine in one generation for style or
+a multi-image scene: Replicate's `google/nano-banana-pro` takes up to 14 and
+kie's `nano-banana-pro` up to 8. Text-to-image and edit are the same model.
+Google states that outputs carry SynthID watermarking.
+
+Grade the result rather than eyeballing it: `critique_image` for a written
+read, `score_image_adherence` when you need the prompt checked against the
+render.
+
+Adapted from fal's Nano Banana Pro prompting guide:
+https://fal.ai/learn/tools/nano-banana-pro-prompting-guide