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

package/dist/_skills/manimgx/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: manimgx
+description: "Write, inspect and render ManimGX scenes: math and 3D animations in Manim Community Edition's Python API, run by the nodetool.manimgx nodes. Use for equations, proofs, plots, geometry, 3D surfaces and explainer animations."
+---
+
+# Animate with ManimGX
+
+ManimGX renders animations written in Manim Community Edition's Python API on a
+Rust GPU engine. A scene is a Python module; the `nodetool.manimgx` nodes run
+it on the machine NodeTool runs on. They need `manimgx` installed there
+(ManimGX in the desktop Package Manager, or `uv tool install manimgx` with
+Python 3.13 or newer) and are absent from the hosted cloud, because a scene is
+a program.
+
+| Node | Takes | Gives |
+| :--- | :--- | :--- |
+| `nodetool.manimgx.InspectScene` | `code`, `scene_name`, `times`, `timeout` | `ok`, `problems`, `report`, `storyboard`, `duration` |
+| `nodetool.manimgx.RenderScene` | `code`, `scene_name`, `width`, `height`, `fps`, `preset`, `crf`, `timeout` | `video`, `storyboard`, `report`, `subtitles`, `duration` |
+| `nodetool.manimgx.GenerateScene` | `prompt`, `model`, `max_attempts`, `send_storyboard`, `width`, `height`, `fps`, `timeout` | `video`, `code`, `storyboard`, `report`, `attempts` |
+
+`timeout` is the limit in seconds for each ManimGX run (default 300).
+
+`GenerateScene` runs the whole loop below inside one node with a language
+model, for up to `max_attempts` rounds (default 3, at most 8). Each round is a
+paid model call, and `send_storyboard` (on by default) sends the storyboard
+pictures to it, which needs a vision model. Confirm the model with the user
+before running it. Write the scene yourself when you can see the storyboard and
+fix it.
+
+## The loop
+
+1. **Write** the module. Start from the template under
+   [Authoring](#authoring).
+2. **Inspect** it with `InspectScene`. `ok: false` means the scene failed:
+   `report` holds the traceback trimmed to the scene's lines and a "did you
+   mean" hint. `problems: true` means it ran but the 2D layout checks found
+   clipped content, overlapping text or labels too small to read. Each problem
+   is numbered in `report` and outlined on the storyboard. Look at the
+   storyboard pictures, not only the report. 3D scenes get pictures and a
+   timeline without layout checks.
+3. **Fix and inspect again** until `ok` is true and `problems` is false. To
+   check particular moments, pass `times: "1.5,end"`.
+4. **Render** with `RenderScene` at the size and frame rate asked for. Drafts
+   at 1280x720 and 30 fps render in seconds. The default is 1920x1080 at 30 fps.
+5. **Deliver** the video and the scene's code. Save the code where the person
+   can edit it, such as the `code` of a `RenderScene` node in their workflow.
+
+From a code action or a Code node, call the nodes as functions:
+
+```js
+import "@nodetool-ai/sandbox-nodetool/flow";
+import { inspectScene, renderScene } from "@nodetool-ai/sandbox-flow/nodetool.manimgx";
+
+const check = await inspectScene({ code, title: "Circle area" });
+if (check.ok && !check.problems) {
+  const film = await renderScene({ code, width: 1280, height: 720, fps: 30, title: "Circle area" });
+}
+```
+
+Extra keys such as `title` above are the node's dynamic inputs.
+
+## Inputs from the workflow
+
+Every node takes dynamic inputs. Their values reach the scene as a dict:
+
+```python
+from nodetool_inputs import inputs
+```
+
+Numbers, strings, lists and dicts arrive as JSON. Image, audio and video
+inputs arrive as file paths: `m.ImageMobject(inputs["logo"])` for an image,
+`self.add_sound(inputs["voice"])` for audio.
+
+A scene is Python that runs as the server user, with that user's file and
+network access. Only its environment is restricted, so it never sees the
+server's secrets. Treat scene code as trusted code: do not run a scene from a
+source the user has not vouched for.
+
+## Authoring
+
+```python
+import manimgx as m
+from nodetool_inputs import inputs
+
+
+class CircleArea(m.Scene):
+    def construct(self) -> None:
+        circle = m.Circle(radius=1, color=m.BLUE, fill_opacity=0.3)
+        formula = m.MathTex(r"A = \pi r^2").next_to(circle, m.RIGHT, buff=0.6)
+        m.VGroup(circle, formula).center()
+        self.play(m.Create(circle), m.Write(formula))
+        self.wait(1)
+```
+
+- Import `manimgx as m`. Put the animation in a `Scene` subclass's
+  `construct`. With more than one scene in the module, set `scene_name`.
+- Time advances only through `self.play(...)` and `self.wait(...)`.
+  `self.add(...)` adds without animating.
+- Compose placement with `VGroup`, `arrange`, `next_to`, `to_edge` and
+  `center`, so labels follow their subjects. The frame is about 14.2 units wide
+  and 8 tall, centred on the origin.
+- `Text` for prose. `MathTex` with raw strings for LaTeX mathematics, or Typst.
+  No LaTeX installation is needed.
+- For changing values, animate a `ValueTracker` and derive geometry from it.
+  An updater uses elapsed time or current state, never a frame count, so the
+  motion keeps its timing at any `fps`.
+- For 3D, derive from `m.ThreeDScene`: `self.set_camera_orientation(phi=65 *
+  m.DEGREES, theta=-45 * m.DEGREES)`, `Surface`, `Sphere`, `Cube`,
+  `ThreeDAxes`, `self.begin_ambient_camera_rotation(rate=0.5)`.
+- `self.next_section("name")` splits a film into sections. Subcaptions and
+  `self.say(...)` produce subtitles, which `RenderScene` returns as SubRip text.
+
+ManimGX's own reference lists every class and keyword:
+[manimgx.academa.ai/reference](https://manimgx.academa.ai/reference/), and
+[llms.txt](https://manimgx.academa.ai/llms.txt) links the guides as Markdown.
+Where ManimGX and Manim CE differ, ManimGX's page is right.
+
+## Where the result goes next
+
+`video` is an inline video ref. Save it as an asset, or place it on a timeline
+like any generated clip. A narrated explainer keeps its timing from the voice:
+write the script first (`script-video`), then size each scene's waits to its
+line.

package/dist/_skills/minimax-h3-prompting/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: minimax-h3-prompting
+description: Prompt MiniMax H3 — choosing between its text-to-video, first-and-last-frame and reference-to-video endpoints, assigning an explicit job to every reference image, clip and audio file, writing a timecoded shot list inside the prompt, art-directing the native stereo audio, and naming a change and its constraint together when editing a clip. Use whenever the model id names MiniMax H3 (minimax/h3/text-to-video, minimax/h3/image-to-video, minimax/h3/reference-to-video, their /lora variants, minimax/h3-max/*, minimax/h3-max-turbo/*, AtlasCloud's minimax/h3-fast and minimax/h3-developer, kie's minimax-h3/*) on generate_video, animate_image, generate_video_from_references or a TextToVideo node. Not for MiniMax Hailuo.
+---
+
+# MiniMax H3 → one context, many references
+
+H3 is a general-purpose multimodal video model rather than a set of task
+models. Text, images, video and audio all enter one context, so a single
+request can carry a character's identity from a photo, camera language and
+cutting rhythm from a clip, and a voice from a recording, and resolve them into
+one shot with native stereo audio. Base H3 runs 5 to 15 seconds in 2K on fal
+(4 to 15 on kie and AtlasCloud), with prompts up to 7,000 characters — a full
+shot list with sound design fits in one request. H3-Max and H3-Max-Turbo
+default to 768P and take prompts up to 50,000 characters.
+
+Reach text-to-video and image-to-video with `find_model` for `text_to_video`
+or `image_to_video`, then `generate_video` / `animate_image`. Reach
+reference-to-video with `find_model` for `reference_to_video`, then
+`generate_video_from_references`. Those forward the prompt, the media, the
+duration, the aspect ratio and the resolution. `generate_video_from_references`
+carries reference images and videos but no audio files, `animate_image` sends
+one image and no end frame, and none of them sets prompt expansion. Audio
+references, an end frame and the expansion switch exist only on the route's
+own node: find it with `search_nodes`, read its fields with `get_node_info`,
+and run it with `run_node`. Each run is a paid generation, so confirm the
+scope with the user before rendering several.
+
+**Turn prompt expansion off for a precise brief.** H3-Max, H3-Max-Turbo and
+the fal `/lora` routes set `prompt_expansion_mode` to `balanced` by default,
+and fal's `extend-video` and `insert-video` set `enable_prompt_expansion` true.
+An LLM then rewrites the prompt before generation, which can undo a timecoded
+shot list. AtlasCloud's `prompt_expansion` defaults to false.
+
+A timecoded shot list in one request is also what keeps the native audio
+continuous across the cuts — `video-audio-continuity` for when to fit a whole
+multi-scene piece into a single generation.
+
+## Which endpoint
+
+The rule is mechanical:
+
+- **No media in the request** → text to video. Best for anything you can fully
+  describe, and for letting the model invent the look rather than match one.
+  Distinct hand-drawn styles carry surprisingly far on prompt alone.
+- **An image that is literally the first or last frame** → first and last
+  frame, the image-to-video route. One image for the opening, or two for
+  opening and closing (`end_image_url` on fal, `end_image` on AtlasCloud),
+  with H3 generating the motion between. This is the one for animating a static poster,
+  a UI mockup or key art. Output follows the uploaded image's aspect ratio.
+- **Anything you are treating as a reference** → reference to video. Up to 9
+  images, 3 video clips of 2 to 15 seconds, and 3 audio clips, 12 files
+  maximum. Audio clips go in through the route's own node. Identity locking, motion and camera transfer, style matching, voice
+  cloning, and editing an existing clip all live here. Default to it whenever
+  you have an asset in hand.
+
+## The eight techniques
+
+**1. Assign a job to every reference.** This is the one habit that changes the
+most. "Use Image 1 for the overall mood, location and film texture; Image 2 for the
+talent; Image 3 for the bag; and Image 4 for the closing brand mark" beats four
+images and a description. It works across modalities too: "Match the camera
+move in Video 1. Make the subject in Video 2 sing, using Video 3 as the
+reference for both the vocal performance and physical delivery."
+
+**2. Write a timed shot list for anything past one beat.** Timecoded blocks
+hold the pacing: "[0 to 2 seconds] High-angle overhead shot… [2 to 4 seconds]
+Smoothly push in to her right arm… [10 to 15 seconds] As she stands, the full
+world loads around her." Without them a 15-second generation drifts into a
+slideshow.
+
+**3. Direct the audio.** It is generated natively, so art-direct it like a
+shot: "a deep sub-bass pulse, distant metallic resonance, and one restrained
+hit as the title locks into focus", or "ice tapping crystal, a faint cigar
+burn, subtle room air, clothing movement, controlled breathing". For music,
+describe instrumentation and structure over time, including where the beat
+lands.
+
+**4. State what you do not want.** No H3 route has a `negative_prompt` field,
+so negative direction is prompt text. fal's guide calls it unusually effective
+when specific. "No soft dissolves or fluid morphs." "Do not
+introduce garbled characters or misspellings." "No tearing, black frames,
+obvious VFX, or compositing seams." These keep a stylized prompt from sliding
+into a neighbouring genre.
+
+**5. Lock identity by listing the details.** "Preserve the half-up long black
+hair, openwork silver crown, indigo ribbon, layered pale hanfu, translucent
+blue outer robe, deep-blue sash, silver floral fastener, and long tassels."
+Naming features gives the model something to hold. The same works for products,
+sets and typography.
+
+**6. For edits, name the change and the constraint together.** Write
+substitutions as a list: "Replace the newspaper with a green hardcover book;
+replace the chair with a red sofa; remove the subject's sunglasses and reveal a
+clear face." Pair each change with what must stay stable and you get a
+localized edit instead of a regenerated shot.
+
+**7. Use camera and film language.** Lens choice, movement, exposure behaviour
+and stock character all translate: "subtle handheld shake, then push in quickly
+and rack focus", "wide angle with strong perspective distortion", "fine grain,
+soft highlight halation, restrained colour", "backlit exposure breathing,
+slightly coarse noise in the shadows".
+
+**8. Describe transitions as events, not names.** "Fast binocular-scan
+transitions with whip movement, motion blur, optical smearing, and brief
+exposure flicker. Cut at peak blur, then settle and snap back into focus."
+Circular vinyl-record wipes, vertical car-door cuts and oversized letter masks
+all land better described than labelled.
+
+## What it is unusually good at
+
+Reading many references at once, rendering legible text and interfaces, and
+making precise localized edits to video you already have. That combination
+covers brand films and trailers, title sequences and motion-graphics collage,
+vertical short drama, product and e-commerce spots, game and web UI motion,
+character and motion transfer, voice cloning, and green-screen replacement — all
+from the same model.
+
+H3-Max also has single-purpose routes (`3d-to-video`, `camera-controls`,
+`multi-angle`, `insert-video`, `extend-video`, `lip-sync`, `styles/*`) with
+their own fields and defaults. This guide does not cover them, so read the
+route with `get_node_info` before using one.
+
+Two shapes worth stealing. For a title sequence: name the design language, the
+transition vocabulary, the credit typography rules ("each role and each name
+appears once"), and a timed BGM brief. For a fashion or product film: assign
+mood, talent, product and brand mark to separate images, then keep the story
+simple and let the references carry the look.
+
+Check the render with `analyze_video`, `detect_video_scenes` and
+`understand_video`; `analyze_audio` for the mix you directed.
+
+Adapted from fal's MiniMax H3 prompting guide:
+https://fal.ai/learn/devs/minimax-h3-prompting-guide

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

@@ -0,0 +1,281 @@
+---
+name: motion-ad
+description: "Make a short sound-off motion-graphics ad (a 15s Facebook, Instagram or TikTok ad, 4:5 or 9:16) from a product's real screenshots and photos, with every claim checked against the page it links to. Use for an animated promo, a kinetic-type ad, a 9:16 version of one, or a revision of one (swap the hero, change the CTA, re-render). For generated footage use product-commercial, or launch-commercial for a finished spot with voice and music from a product page; for a person on camera ugc-video."
+featured: true
+---
+
+# Motion ad
+
+A motion ad animates real product imagery and short headlines on the timeline.
+Nothing in the picture is generated by default. The storyboard is the beat plan
+and holds the real image each beat shows. The timeline carries the motion, and
+`render_timeline` produces the MP4.
+
+**Load `/storyboard-core` first** for the board contract. Load `timeline-edit-ops`
+with `load_skill` before the first `edit_timeline` call: it owns every op shape
+this skill quotes, and `motion-graphics` owns the build loop.
+
+## Rules that do not bend
+
+- **Every claim matches the destination page.** Read the page before writing a
+  word. A price, a count, a speed, a guarantee, a rating or "free" appears in
+  the ad only if it appears there. When the user asks for copy the page
+  contradicts, write it and name the mismatch once in the report.
+- **Real assets only.** Use the user's files or images taken from their live
+  site. Never invent a customer, a review, a rating, a result or a logo. A beat
+  with no real proof to show is cut, not filled.
+- **Never fabricate a person.** A beat that needs more pictures of someone than
+  exist gets crops or mirrors of the real ones, and the report says so. A
+  generated face is out even when the rest of the board uses a model.
+- **The brand decides the look.** Colours, logo, tone and type come from the
+  brand, not from the beat table below. Default to plain claims: no hype, no
+  exclamation marks, no emoji unless the brand writes that way.
+- **Never overwrite a delivered version.** Each revision is a new timeline
+  version and a new rendered asset with a versioned name
+  (`<brand>-<topic>-ad-4x5-v2`).
+
+## Production policy
+
+The canonical machine-readable policy is the shot's `production` requirement.
+For social ads, choose `media_strategy` deliberately:
+
+- `still_motion_graphics` is the default. Preserve the source image and build motion, type, shapes and transitions in the Timeline.
+- `hybrid` uses generated/existing footage for atmosphere or physical motion while product, logo and exact copy remain separate protected layers.
+- `generated_video` is reserved for actor performance, lifestyle movement or scene motion that materially benefits from video generation.
+
+Put source truth in `protected_inputs`. Product/logo/source assets carry their exact `asset_id`; copy and brand colours carry their exact `value`. Declare only non-destructive `allowed_transformations`: `position`, `scale`, `crop`, `rotate`, `mask`, `opacity`, `composite`. Replacing or regenerating a protected asset, changing exact copy or colour, or applying an undeclared transform breaks the policy. The render tools enforce part of it: `render_storyboard_stills` refuses a selection holding a shot with a protected asset, and `render_storyboard_clips` refuses a `still_motion_graphics` shot. The rest is yours to keep on the timeline.
+
+Do not use `generated_video` merely because a keyframe exists. Price cards, packshots, feature callouts, carousels, comparisons, typography hooks and CTA endings normally stay `still_motion_graphics`.
+
+## The loop
+
+1. Research the page and the brand.
+2. Collect the assets and pick the hero pair.
+3. Write the board: one shot per beat, the real image attached to each.
+4. Build the timeline: pictures, type, shapes, animations.
+5. Review preview frames and fix.
+6. Render, measure, report.
+
+Stop where the request stops. "Just the storyboard" ends at step 3.
+
+## 1. Research
+
+Ask for, or infer from context: the product, the destination URL, the audience
+and the format. The format defaults to **4:5 feed (1080×1350)**. Stories and
+reels are **9:16 (1080×1920)**.
+
+- `browser {url}` on the destination page, then on the homepage and pricing
+  page. Pull the headline promise, prices, rating and review counts, speed
+  claims, and what is free versus paid. Record each fact with the page it came
+  from.
+- `http_request {url}` returns the raw HTML. Read the brand's hex values, font
+  family and logo URL from its CSS variables or stylesheet links. Tokens in the
+  source beat colours picked from a screenshot.
+- `take_screenshot {url, full_page: true}` captures the live product UI. For
+  software, that screenshot is often the best hero image. When it fails, say
+  so once and continue with downloaded images.
+
+A fact the page does not state is `[CLIENT INPUT NEEDED]`, never a guess.
+
+## 2. Assets
+
+Every image the ad shows must be a stored asset before it goes on a board or a
+timeline.
+
+- An image URL from the page: `save_asset {source: "<url>", name}` copies it
+  into the library and returns an `asset_id`. `download_file` writes a workspace
+  file instead, which is not an asset and cannot go on a timeline.
+- A user upload: find it with `asset_search` or `list_assets`. Prefer the
+  user's files over scraped ones when they offer any.
+- Logos: keep one for light backgrounds and, when the site has one, a white
+  version for the brand-colour end card.
+
+Look before choosing. `view_image` each candidate and note its pixel size.
+Site images are often thumbnails, and a 400px image on a 1080px canvas reads as
+soft. Say which images are low resolution in the report instead of upscaling
+them silently.
+
+Pick the **hero pair** for the clearest transformation. For a physical
+product, that is before and after. For software, it is the messy input and the
+finished output, as screenshots. Portrait images near 4:5 fill the hero and
+showcase slots best.
+
+`edit_image` may crop, mirror or extend a real image to fit a slot. It may not
+add a person, a product or a claim that was not in the source.
+
+## 3. The board
+
+`create_storyboard {name, brief, style, aspect_ratio: "4:5"}` (or `"9:16"`).
+Put the researched facts and their source URLs in `brief` so a later revision
+can re-check them. Put the brand palette and type in `style`.
+
+Add one shot per beat with `edit_storyboard`. Each shot carries:
+
+- `slug`: `1a`, `2a`, and so on. "Change the 3a headline" then means one shot.
+- `action`: what is on screen, in plain words.
+- `notes`: the exact on-screen copy for the beat, including line breaks.
+- `duration_seconds`: the beat length from the table below.
+- `production`: the policy from § Production policy, for example
+  `{"media_strategy": "still_motion_graphics", "protected_inputs": [{"id": "hero-after",
+  "kind": "product", "asset_id": "<hero after>", "allowed_transformations": ["position",
+  "scale", "crop", "mask"]}, {"id": "headline-2a", "kind": "exact_text", "value": "<copy>"}]}`.
+
+Then attach each beat's real image as its still:
+
+```json
+{"storyboard_id": "<id>", "ops": [
+  {"op": "add_keyframe_version", "target": "2a", "asset_id": "<hero after>"}
+]}
+```
+
+The shot moves to `keyframe_ready` with the real picture and no generation. A
+still-only board is what the user reviews before any motion work.
+
+Do not call `render_storyboard_stills` without `targets` on this board. It
+selects every shot without a still, so a beat you forgot to attach would be
+generated. Generate a shot only when the user asked for it, and only for a
+background or texture, never for the product, a screen or a person.
+
+### Beats
+
+Four or five beats in 15 seconds. One short headline per beat, at most about
+20 characters per line, sized to read muted on a phone. The shape below is a
+starting point. Cut or replace a beat that does not fit the product. A desktop
+tool with no mobile app has no phone beat, so open on the hero instead.
+
+| Slug | Time | Beat | Picture |
+|---|---|---|---|
+| `1a` | 0–2.2s | Hook headline over the product in context: a phone or browser frame scrolling a real screenshot, a pointer or tap on the input | The screenshot |
+| `2a` | 2.2–5.4s | The tapped card grows into the hero. A scan line crosses it and reveals before becoming after. Two or three benefit chips | Hero before, hero after |
+| `3a` | 5.5–8.7s | The hero shrinks into a tilted wall of more real outputs | Four to nine outputs |
+| `4a` | 8.7–11.8s | Three showcase cards, optionally with a small "before" inset, and one proof line | Showcase images, a real rating or count |
+| `5a` | 11.8–15s | Brand-colour wipe to the end card: logo, CTA headline, one chip, the button | Logo |
+
+Beat `4a` loses its proof line when the page has no number to quote. Beat `3a`
+is cut when there are not enough distinct real outputs to fill a wall without
+repeats.
+
+## 4. The timeline
+
+`assemble_storyboard_timeline` lays down rendered clips only and skips shots
+that have a still and no clip, so it builds nothing here.
+
+When the shots carry `graphics` intent (the exact copy and assets as elements),
+`finish_storyboard {storyboardId, expectedStoryboardRevision}` writes the board as
+editable timeline layers with no generation. Its default deterministic strategy
+returns an unreviewed scaffold; `layout_storyboard` composes the static layout
+with a vision model first. Review either through § 5 like a hand build.
+`storyboard-core` § Still-motion-graphics boards has the arguments. Without
+`graphics` on the shots, create the sequence directly:
+
+```json
+{"name": "acme-scan-ad-4x5-v1", "width": 1080, "height": 1350, "fps": 30}
+```
+
+`create_timeline` with those arguments. Then `create_timeline_version` before
+the first edit, and build with `edit_timeline` in batches of at most 60 ops.
+Read `get_state` for track and clip ids before animating anything.
+
+**Tracks, top to bottom.** A lower index draws on top, and `add_track` appends
+at the bottom, so add them in this order: headlines, chips and buttons, the
+scan line and wipes, pictures, background. Give every element whose timing
+overlaps another its own track. Two clips that overlap on one track dissolve
+into each other.
+
+**Pictures.** `add_media_clip {asset: "asset://<id>", trackId, startMs,
+durationMs, transform}` per image. An image has no duration of its own, so
+always pass `durationMs`. `transform.position` is in canvas pixels measured from
+the frame centre (`{x: 0, y: 0}` is centred, positive y moves down), and `scale`
+is a factor. Frame each image with `frame-composition` rules.
+
+**Type.** `add_text_clip` per headline, with the brand colour and a
+`fontFamily` NodeTool bundles: Inter, Space Grotesk, Bebas Neue, Playfair
+Display, Lora or JetBrains Mono. When the brand font is not among them, use
+the closest bundled family and say so. Put an accent word in its own text clip
+in the accent colour, aligned to the line. What the copy says and when it
+appears belongs to `caption-titles`.
+
+**Shapes.** `add_shape_clip` draws the background, chips, the button, the scan
+line and the brand-colour disc of the end-card wipe.
+
+**Motion per beat.** One easing family and one timing unit for the whole ad,
+fixed before the first animation (`motion-direction`). Durations and stagger
+come from `motion-principles`.
+
+| Beat | Build it with |
+|---|---|
+| Hook | Headline `animate_clip` `in` `pop` with a `word` stagger. The screenshot's scroll is a custom `positionY` curve inside a masked frame (`set_mask`). The tap is a small shape with `pop` then `pulse` |
+| Reveal | The "after" image sits on the track above "before". `animate_clip` `in` `wipe` on "after", with the scan line moving on the same window and easing. Benefit chips enter with `stagger_animations` |
+| Wall | Output images with `rotationY` and `perspective` on their transforms, entering with `stagger_animations`. A slow `kenBurns` loop keeps the wall alive |
+| Showcase | Cards `slide` in from one side. The proof line enters last and holds at least 1.5s |
+| End card | `set_transition` `iris` or a scaled brand-colour disc, then the logo per `logo-reveal`. The CTA holds still for the last second |
+
+Sound is optional. The ad must work muted. When the user wants a bed,
+`find_model` with `text_to_music`, `load_skill` the `prompting_skill` it
+names, then `generate_music` at the exact runtime. Put cuts on its beats with
+`beat-sync-editing`.
+
+`validate_timeline` after every batch. Fix `text_illegible`,
+`text_backing_unproven`, `font_not_portable`, `stagger_compressed` and
+`animation_exceeds_clip` before looking at frames.
+
+## 5. Review frames
+
+`preview_timeline_frame {timeline_id, times_ms, sheet: true}`, then
+`view_image` on the sheet. For the table above, sample
+`[300, 1900, 2700, 3800, 4900, 6600, 9800, 11500, 13600]`, plus the midpoint
+of every entrance you added.
+
+Look for:
+
+- text overlapping text, or a headline under a shape it should sit above
+- empty gaps where one beat ends before the next starts
+- a label that contradicts its image ("after" on the before picture)
+- the same image twice side by side in the wall
+- a headline that cannot be read at thumbnail size
+- a soft image at hero size
+
+Name each defect, fix it, and preview the same timecodes again.
+
+## 6. Render and report
+
+1. `render_timeline {timeline_id, preview_scale: 0.5, wait: true}` for a draft
+   while iterating.
+2. `render_timeline {timeline_id, wait: true}` at full size when the frames
+   are right.
+3. `analyze_video` on the result. Check duration, width, height and frame
+   count against the plan.
+4. `preview_timeline_frame` at each transition to check the frames the stills
+   review did not sample.
+
+Report:
+
+- the rendered asset and the timeline and board to open
+- the copy, beat by beat
+- every caveat: low-resolution sources, crops and mirrors, the font
+  substitution, copy that differs from the page, and any
+  `[CLIENT INPUT NEEDED]` left in the board
+- actual spend from `get_cost_summary` when anything was generated
+
+## A second format
+
+A 9:16 cut is its own timeline, not a crop. `retarget_format` derives a
+sequence by cropping, which cuts headlines and chips placed for 4:5. Create a
+1080×1920 timeline from the same board, re-space every vertical position
+(headlines, frame, hero, carousel, end card), and review and render it the
+same way. Name it `<brand>-<topic>-ad-9x16-v1`.
+
+## Revisions this loop handles
+
+```
+Swap the hero for the image I uploaded. Keep everything else.
+Change the CTA to "Start free". Check the page says free first.
+Make a 9:16 version.
+The headline in 1a is too long. Two lines, same words.
+Drop the proof line. The review count is out of date.
+Re-render as v3. Keep v2.
+```
+
+Each one is `create_timeline_version`, the smallest edit that answers it, a
+validate, a preview of the changed beats, and a new render with the next
+version number.