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

package/dist/_skills/launch-commercial/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: launch-commercial
+description: Turn a product page URL into a finished launch commercial — research, storyboard, rendered stills and clips, voice, music, an assembled timeline — delivered as an editable NodeTool project with the real cost. Use when someone asks for a finished ad, launch spot or commercial with generated footage from a product page or website. For a sound-off animated ad built only from the page's real screenshots and photos, use motion-ad; for ad structure without a render, commercial-beat-sheet.
+---
+
+# Product Page → Launch Commercial Agent
+
+Take a product page URL and deliver a finished launch commercial — rendered clips, voice, music, an assembled cut — as an **editable NodeTool project** (storyboard + script + timeline), plus the real cost of making it from the ledger. Call the capability modules directly; build no workflow.
+
+This skill owns the outer loop: research → brief → entities → board → renders → voice → music → cut → cost report. The dramaturgy inside the board — hooks, beat budget, timecodes, VO discipline — belongs to the `commercial-beat-sheet` skill. Load it at phase 3 and follow it there. Do not duplicate its rules; do not skip it.
+
+When the user wants a sound-off motion-graphics ad (a 15s feed ad, kinetic type, the product's real screenshots animated on the timeline, no generated footage), this is the wrong skill: load `motion-ad`.
+
+---
+
+## Role
+
+Work as an integrated producer: a URL and a runtime in, a shot spot out. Research before writing, and never invent a brand fact — everything the spot claims comes from the page or is marked `[CLIENT INPUT NEEDED]`. Spend in ascending order: research is free, stills cost less than clips, and nothing expensive renders before the cheaper version was looked at *critically*. End every run with the deliverables, where to open them, and what the ledger says they cost.
+
+---
+
+## The contract
+
+The user gives you at minimum:
+
+```text
+PRODUCT PAGE URL:   [required]
+RUNTIME:            [15s / 30s / 60s — default 30s]
+PLATFORM:           [default: 9:16 for ≤30s, 16:9 above]
+```
+
+Everything else — brand, category, audience, pain, USP, proof, tone, CTA — you **derive from the page** and present back as a brief for sign-off. A field the page cannot answer is `[CLIENT INPUT NEEDED]`, never a guess.
+
+The user gets back: a **storyboard** (still + clip on every shot), a **script** (every line voiced), a **timeline** that validates, and a **cost report** from the ledger. All four persist. The render is not the deliverable; the editable project is.
+
+---
+
+## Tool contract — read this before writing any code
+
+The storyboard, entity and render call shapes live in `storyboard-core` § Tool contract: return fields, all fifteen `edit_storyboard` ops, every key `set_board` accepts, and what text each generator reads. `load_skill` it before phase 3. What this skill adds:
+
+**Headless only.** `ui_*` tools need a browser with that document open. From this skill you are headless: use `list_entities` / `apply_entities`, never `ui_entity_list` / `ui_entity_apply`.
+
+**Read ids by name.** `create_storyboard` → `.storyboard_id`. `create_entity` returns `{entity}`, and the entity id is **the `asset_id` you passed in**. `nodetool.media.generateImage` → `.asset_id`. `extract_script_from_storyboard` → `.script_id`. Never write `result.id || result.asset_id` and proceed. If an id is `undefined`, stop and read it back with `list_*` — do not pass it onward.
+
+**The board holds the default models.** `image_model` / `video_model` on `set_board` take the `.ref` object `find_model` returns, and `render_storyboard_stills` / `render_storyboard_clips` fall back to them. With no board model and no `provider` + `model` on the call, the render fails and says so — it never picks one. Set them on the board once in phase 3 and pass `provider` + `model` only for a shot that needs a different line.
+
+**Measure with `ffprobe`.** It takes an `asset://` uri and reports width and height — that is the aspect check, cheap enough to run on every keyframe. Grade the picture itself with `view_image` and `score_image_adherence`.
+
+**`take_screenshot` renders the page in headless Chrome on the machine NodeTool runs on**, or through the remote browser service when one is configured. If it fails, report the error once and fall back to the page's own downloaded images.
+
+---
+
+## Spend gates
+
+| Gate | After | You show | Money spent |
+| --- | --- | --- | --- |
+| **G1 Brief** | Research | Derived brief, entity plan | $0 |
+| **G2 Stills** | Keyframes + your own adversarial grade | Every keyframe, defects named | the stills (from the ledger) |
+| **G3 Cut** | Clips + voice + music + assembly | Timeline, validation, ledger cost | the real number |
+
+Never render clips before G2 is approved. Never pick a model silently. If the user says "run it end to end", G1/G2 become progress reports; the cost report is never optional. No tool prices a render before it runs: at a gate, state counts (shots, clips, voiced lines) and the models, and what the ledger shows spent so far — never a forecast dollar figure.
+
+---
+
+## Phase 1 — Research the page
+
+```js
+import { browser, take_screenshot, download_file } from "@nodetool-ai/sandbox-nodetool/web";
+
+const page = await browser({ url: productPageUrl });
+```
+
+Extract into the brief:
+
+- **Facts** — name, what it does, price, materials, claims. Verbatim or `[CLIENT INPUT NEEDED]`.
+- **Voice** — how the brand writes. The VO inherits it.
+- **Visual identity** — read hex values out of the raw HTML (design tokens beat eyeballing a screenshot), plus a live screenshot from `take_screenshot`.
+- **Product imagery** — download the hero photos. They become the prop entity's reference. The real product is the one thing the model must not reimagine.
+- **The one pain** — pages list five benefits; the spot escalates one. Take the one the page leads with.
+
+Then fill the beat-sheet skill's brief format and present it at **G1** with the entity plan.
+
+---
+
+## Phase 2 — Entities from the page
+
+Follow the beat-sheet skill's entity rules (kinds, descriptors, style-first, roster size). What this skill adds:
+
+**Priority per entity:** library (`list_entities`) → page asset → generated.
+
+**The style entity comes from the page whenever the page has a look.** A screenshot of the real site beats a generated mood frame, and for a software product it is not close — the product *is* the interface. Capture it if `take_screenshot` works; otherwise use the best downloaded hero image. Only generate a style entity when the product is physical and the page's photography cannot carry the look.
+
+**But a screenshot style anchor has one failure mode, and it is severe.** Anchored on a website screenshot, the image model will draw *the website* — navbar, hero headline, buttons, marketing paragraphs — into shots that were supposed to be scenes. This happened on four of eight plates in a real run, and every one baked legible marketing copy the spot was supposed to keep in an editable text layer. So the descriptor separates look from content, and **every scene prompt carries hard negatives**:
+
+```text
+ABSOLUTELY NO website page, NO navbar, NO marketing headline, NO gradient
+title text, NO buttons, NO paragraphs, NO wordmark or logo. No readable
+text of any kind.
+```
+
+Two shot classes, prompted differently:
+
+- **Product shots** (the mechanism, the proof) — the interface *is* the subject, edge to edge, no page around it. UI chrome (a status pill, a label) is fine; marketing copy is not.
+- **Scene shots** (hook, problem, CTA, closing) — describe the scene only. Never say "match the homepage" in a scene prompt; that phrase is what makes the model draw the homepage.
+
+Entity ids: pass `asset_id`, and use that same asset id as the entity id afterward.
+
+```js
+import { create_entity, list_entities } from "@nodetool-ai/sandbox-nodetool/entities";
+
+const styleAssetId = shot.asset_id;           // the screenshot
+await create_entity({ asset_id: styleAssetId, kind: "style", name: "...", descriptor: "...", palette: [...] });
+const styleId = styleAssetId;                 // entity id === asset id
+```
+
+---
+
+## Phase 3 — Beat sheet and board
+
+Load the **commercial-beat-sheet** skill and run its execution path with the phase-1 brief and phase-2 roster: three hooks, a recommendation, the full beat sheet. Then:
+
+```js
+import { create_storyboard, edit_storyboard } from "@nodetool-ai/sandbox-nodetool/storyboards";
+
+const board = await create_storyboard({ name, brief, style, aspect_ratio });
+const boardId = board.storyboard_id;
+
+await edit_storyboard({
+  storyboard_id: boardId,
+  ops: [{ op: "set_board", entity_ids: roster }]   // set_board, not set_entities
+});
+for (const shot of shots) {
+  await edit_storyboard({ storyboard_id: boardId, ops: [{ op: "add_shot", ...shot }] });
+}
+```
+
+Set `render_mode` per shot: `"keyframe"` where the product or a face must hold steady, `"direct"` for the one or two heavy-motion shots. A launch spot usually has exactly one direct shot.
+
+Resolve the model slate **before the shots are written**, with `find_model` for `text_to_image` and `image_to_video`. Name what you picked, put each result's `.ref` on the board with `set_board {image_model, video_model}`, and `load_skill` the `prompting_skill` each result names: the shot `action` and `motion` you are about to write are the prompt, and each model line wants them shaped differently. On-screen copy stays out of the prompt and goes on as a text layer in phase 7.
+
+---
+
+## Phase 4 — Stills, then grade them adversarially (G2)
+
+```js
+import { render_storyboard_stills, get_storyboard } from "@nodetool-ai/sandbox-nodetool/storyboards";
+
+await render_storyboard_stills({ storyboard_id: boardId });   // uses the board's image_model
+```
+
+Then grade. `get_cost_summary` shows what the stills cost. **This is the step most likely to fail, and it fails as flattery.** A previous run called its frames "astonishing" and "pixel-perfect", presented them for approval, and only found a blank-blob card, an unfinished-looking end frame, and a non-uniform aspect ratio after the user asked "did you look at the stills?".
+
+The discipline:
+
+1. **Look at every frame with `view_image`, one question per frame, asking what is *wrong*.** "Critique honestly: what is crude, off-brand, or unfinished here?" — never "does this look good?".
+2. **Score adherence** with `score_image_adherence({image, prompt})` where the shot prompt is specific enough to score against.
+3. **Compare frames to each other**, not just to their prompts. The defect that killed two frames in the real run was only visible next to a third that got it right.
+4. **Report per frame: keep, or the specific defect.** Banned words in a grade: stunning, astonishing, gorgeous, perfect, night-and-day. If you cannot name a defect, write "checked: card fidelity, baked text, palette, framing — none found".
+5. **Never claim a property you did not verify.** Measure the aspect ratio with `ffprobe` on each keyframe's `asset://` uri rather than eyeballing it; a plate that came back in the wrong ratio is a defect to name at G2, and it is still standardized at assembly.
+
+Two failure classes, two different fixes — never confuse them:
+
+- **Entity drift** (wrong product, wrong face, off-palette) → fix the *entity*: sharpen its descriptor or replace its reference, then re-render every shot using it.
+- **Shot failure** (composition, unreadable action, baked marketing copy) → fix the *shot*: rewrite its action line, re-render that shot.
+
+Present all keyframes at G2 with the clip count and video model of phase 5. No tool prices the clips in advance; do not quote a number.
+
+---
+
+## Phase 5 — Clips
+
+```js
+await render_storyboard_clips({ storyboard_id: boardId });   // uses the board's video_model
+```
+
+A clip wrong where its keyframe was right is a **motion** problem: one `revise_storyboard_clip`, never a board-wide re-render. Cap at one revision per shot before flagging. Video models overshoot the requested length and can ignore a 9:16 source: `analyze_video` on each clip reports duration and frame before you assemble (`video-audio-continuity` § Check what came back).
+
+---
+
+## Phase 6 — Voice
+
+```js
+import { extract_script_from_storyboard } from "@nodetool-ai/sandbox-nodetool/storyboards";
+import { get_script, voice_script_lines } from "@nodetool-ai/sandbox-nodetool/scripts";
+
+import { find_model } from "@nodetool-ai/sandbox-nodetool/models";
+import { edit_script } from "@nodetool-ai/sandbox-nodetool/scripts";
+
+const script = await extract_script_from_storyboard({ storyboard_id: boardId });
+const scriptId = script.script_id;
+const tts = await find_model({ capability: "text_to_speech" });
+// The extracted cast has no usable voice: Narrator comes back with none, a
+// character with at most its entity's voice_id and no provider or model. Bind
+// one per speaker, or every line reads no_voice.
+const cast = (await get_script({ script_id: scriptId })).cast;
+await edit_script({ script_id: scriptId, ops: cast.map((speaker) => ({
+  op: "set_speaker_voice", target: speaker.id,
+  provider: tts.ref.provider, model: tts.ref.id, voice: "<the provider's voice name>"
+})) });
+await voice_script_lines({ script_id: scriptId });
+const voiced = await get_script({ script_id: scriptId });
+```
+
+Pick a voice per speaker that fits the brand voice from phase 1. `voice` is the provider's own voice name (Gemini's `Aoede` or `Charon`, OpenAI's `alloy`), and `storyboard-core` § Script has the binding rules. Every line must come back `voiced`. A `stale` or `no_voice` line is a defect, not a warning. If a voiced line overruns its beat, cut the line — never speed the read.
+
+---
+
+## Phase 7 — Assemble the cut
+
+```js
+import { assemble_storyboard_timeline } from "@nodetool-ai/sandbox-nodetool/storyboards";
+import { edit_timeline, preview_timeline_frame, validate_timeline } from "@nodetool-ai/sandbox-nodetool/timelines";
+import { generate_music } from "@nodetool-ai/sandbox-nodetool/media";
+```
+
+1. Assemble the clips.
+2. **Standardize aspect here** — this is where mixed plate ratios get resolved. Pad the black-heavy minimal frames (leave them smaller than the canvas over a matching background), crop the full-bleed ones (scale the clip's `transform` up with `set_clip_params` until it fills the frame). Say which you did to which.
+3. Voice track, aligned to beats.
+4. Music bed at the spot's exact runtime, ducked under VO, with the beat sheet's deliberate pre-CTA silence kept silent.
+5. **Motion and text.** Supers, the CTA card and the end mark are a text layer over the cut, never a render prompt — no model is asked to letter them. The music bed carries this spot's continuity, so the clips render per beat and their own audio is muted under it — `video-audio-continuity` if the bed is coming out of the video model instead. `timeline-edit-ops` carries the op contract and `motion-graphics` the build loop; load `caption-titles` for the supers and their tiers, `logo-reveal` for the end mark, `beat-sync-editing` to sit the cuts on the music bed, and `color-motion` for the grade that makes mixed plates cut together. `motion-direction` fixes one easing family and one timing unit for the whole spot before the first animation goes on.
+6. **Overrun check.** Video models overshoot requested durations. If the cut runs long, trim the **last** clip — trimming an earlier one opens a gap and leaves the runtime unchanged.
+7. `validate_timeline` must come back ok. Fix and re-validate.
+8. Look at frames, not at the document: `preview_timeline_frame` at each cut and each text entry. A change nobody looked at is not done.
+
+---
+
+## Phase 8 — Report (G3)
+
+```js
+import { get_cost_summary } from "@nodetool-ai/sandbox-nodetool/costs";
+```
+
+```text
+DELIVERED
+  Storyboard / Script / Timeline — each openable and editable
+
+COST  (from the ledger, not an estimate)
+  Stills / Clips / Voice / Music / Agent / TOTAL
+
+OPEN QUESTIONS
+  Every [CLIENT INPUT NEEDED] still in the project
+```
+
+**Report ledger figures, never a forecast.** The prices on the brand's page are product facts for the brief, not production costs; quoting them back as a forecast reads as a real quote and is not one.
+
+---
+
+## Craft rules (on top of the beat-sheet skill's)
+
+* Every claim in VO or on-screen text traces to the page, or is `[CLIENT INPUT NEEDED]`.
+* The product on screen is the page's product. Drift is fixed at the entity.
+* The palette is the page's palette, read from its own tokens.
+* **No lettering the model must invent.** Claims live in the text layer; brand marks come from downloaded assets or stay out of frame. Generated legible marketing copy is a defect even when it looks good.
+* Spend ascending: read → still → clip → revision.
+* Name what was wrong before spending to fix it.
+
+---
+
+## When it goes wrong
+
+* **Page unreachable or thin** → report what you could and could not read, fill the brief with `[CLIENT INPUT NEEDED]`, stop at G1. Never fabricate a product from the URL's words.
+* **A capability errors on argument shape** → re-read the tool contract above before retrying. Two consecutive failures on the same call means read the state back with `list_*` / `get_*` and work from what actually exists, not from what you think you created.
+* **A partial action left orphans** (a board with no shots, an entity with no roster) → find them with `list_*` and finish or delete them. Do not create a second one alongside.
+* **A model is unavailable or unpriced** → say so at the gate it blocks, with alternatives. Never substitute silently.
+* **A shot will not converge** (three renders, still failing adherence) → stop spending, show the best take with what is wrong, offer: accept, rewrite, or change `render_mode`.
+* **Budget cap set** → check the ledger with `get_cost_summary` before each render phase. No tool prices the next phase, so when the remaining budget may not cover it, stop at the gate with the spend so far and the counts still to render, and let the user decide.

package/dist/_skills/launch-kit/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: launch-kit
+description: "Produce a NodeTool campaign with shared product and cast entities, stills, and multiple video cuts. Use for a coordinated asset set."
+---
+
+**Load `/storyboard-core` first.** It carries the loop, the tool contract and
+the gating this skill assumes. Everything below is what changes when the deliverable is
+a set rather than a cut.
+
+## What makes this job type its own
+
+Keep the grade and cast consistent across the requested campaign deliverables.
+Use the passes below as an organizing pattern, scaled to the brief.
+
+So: one entity set, one board `style` string, one image model, one video model, fixed
+at phase A and reused verbatim through phase D. Changing the image model mid-kit is how
+a kit ends up looking like two kits.
+
+## Produce the requested campaign
+
+Use phases as progress checkpoints. Continue within the authorized deliverables
+and budget. Pause for a user-requested review or a missing decision that changes
+the output or spending scope. Do not reconfirm authorization already given. When
+the brief does not fix the deliverable counts (frames, clips, cuts), confirm them
+with the user before the first clip pass.
+
+### A — Cast and lock
+
+1. Product entity from the flat: save the asset, `create_entity {kind: "prop"}` with a
+   descriptor of geometry and finish. Keep the other angles (three-quarter, back, top,
+   on-figure) as plain assets. An entity is one image asset, so it carries one
+   reference into a prompt.
+2. Character entity from the on-body photo. Descriptor is face, hair and build, with
+   **no wardrobe** — wardrobe belongs in shot text so the same person can change
+   outfits across the kit.
+3. Optionally a style entity: `create_entity {kind: "style", palette}`. A style entity
+   applies to every shot on every board, which is exactly what a kit wants.
+4. `find_model` once each for `text_to_image` and `image_to_video`. Write them and the
+   entities onto the board with `set_board`.
+5. `memory_save` the grade, the model ids, the board id and the entity ids, with the
+   ids in `resources`. This is what makes the kit resumable next week — `share_result`
+   would be discarded with the run.
+
+Report entity ids, the grade, and model ids. Continue with the requested assets.
+
+### B — Still campaign frames
+
+Produce the requested number and mix of stills. Use take selection when the user
+reserved that choice. A stills-only request ends here. Otherwise continue to the
+authorized video deliverables with the selected frames.
+
+Vary the crop in `camera.framing`; the still prompt reads it, with the angle and lens,
+so it needs no repeat in `action`. Give product-only frames an explicit `entity_ids` naming the product
+alone, so the model's descriptor does not season a frame she is not in.
+
+Report the selected asset ids and continue within the requested scope.
+
+### C — Social cuts
+
+Use the brief's clip count, durations, and ratios, animated from the selected
+phase-B stills. Honor any requested approval of those stills. Reuse them to keep
+the look consistent.
+
+A separate board per aspect ratio — `aspect_ratio` is a board field, not a shot field,
+so one board cannot serve 9:16 and 16:9. Same entities, same style, same models on each.
+To animate an approved phase-B still on the new board without re-rendering it,
+`edit_storyboard` → `{op: "add_keyframe_version", target, asset_id}` attaches it as the
+shot's selected still. It only fits when that still was framed for the new ratio.
+
+Report clip asset ids. Continue if the requested kit includes a longer film.
+
+### D — The long film
+
+Build the longer piece at the requested duration and aspect ratio, with stable slugs and timing. Assemble it, then finish the sound:
+`edit_timeline` → `get_state`, then `set_clip_params {muted: true}` on the "Shot Audio"
+clips under any voiceover, and add music with `generate_music` + `add_track` +
+`add_media_clip` at a low `volumeDb`.
+
+`validate_timeline` before calling it done.
+
+## Spend
+
+Report shot and frame counts per phase before each render — never a dollar figure, as
+nothing prices a render. Afterwards, `get_cost_summary` gives what the kit actually
+cost.
+
+A twelve-frame still pass is cheap; three clip passes plus a 30-second film is not.
+If the user is deciding, that is the ratio to tell them.
+
+## Recovering a kit later
+
+`list_storyboards` shows shot counts and how many shots have a still and a clip.
+`memory_search` finds the phase-A note with the grade and the entity ids. Together
+those are enough to resume without re-deriving the look.
+
+## Brief
+
+Adapt these examples to the user's brief. Example deliverables, style choices,
+and approval checkpoints apply only when the user adopts them.
+
+```
+Launch kit for [BRAND] [SKU] from the attached flat and on-body photos.
+Stop after each phase and wait for me.
+
+A. Cast and lock. Product entity from the flat (descriptor = geometry and
+   finish). Character entity from the on-body photo (descriptor = face, hair and
+   build, no wardrobe). Pick one image model and one video model with find_model
+   and write both onto the board. Grade: [cold film / warm daylight / black
+   studio]. memory_save the grade, both model ids and every entity id.
+B. Twelve still campaign frames, mixed crops, on-figure and product-only. Stills
+   only — stop before clips. Product-only frames get entity_ids naming the
+   product alone.
+C. Three 9:16 clips, 6-8s, animated from stills I approved in B. Do not
+   re-render those stills. A separate board for the vertical ratio.
+D. One 30s 16:9 film, slugged and timed. Assemble, mute the Shot Audio clips
+   under the voiceover, add a music bed low, then validate_timeline.
+
+Same grade and the same two models from A through D. Report counts before each
+render, not dollars.
+```

package/dist/_skills/logo-reveal/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: logo-reveal
+description: Animate a brand mark on a NodeTool timeline — stroke draw-on, mask wipe, staggered build, wordmark type, an idle loop, and landing the settle on a sound logo. Use for an intro sting, a sign-off, an end card, a splash, or a loader loop. Not for designing the mark itself.
+---
+
+# Logo Reveal → the sting
+
+One idea per logo. Draw it, build it, or wipe it — never all three. The whole
+reveal runs 800–2500ms and ends on the clean mark, held.
+
+`motion-graphics` is the build loop; `timeline-edit-ops` carries the op
+contract. `motion-direction` decides which personality the sting belongs to;
+a logo is usually the one place a piece is allowed its overshoot.
+
+## The same three patterns, in code
+
+**Draw-on** — a path element and `el.draw()`, which is `enter({from: {trimEnd: 0}})`:
+
+```js
+// fragment
+const mark = s.path([["M", -40, 30], ["L", 0, -30], ["L", 40, 30]], { stroke: "#111111" });
+mark.draw({ dur: 1.1, ease: "cubic-bezier(0.65,0,0.35,1)" });
+```
+
+**Wordmark stagger** — `by` and `staggerMs` on `el.enter()`, per character for
+a short mark:
+
+```js
+// fragment
+const wordmark = s.text("Northwind", { size: 64, weight: 700 });
+wordmark.enter({ from: { scale: 0.9, opacity: 0 }, dur: 0.38, by: "character", staggerMs: 45 });
+```
+
+**Lockup row** — mark beside wordmark, one flex container (`frame-composition`
+covers the container vocabulary in full):
+
+```js
+// fragment
+s.row([mark, wordmark], { gap: 16, align: "center" });
+```
+
+Reveal the container first if the mark and wordmark should feel like one
+build, or stagger the row's own children through `s.stagger()` for a build-on
+that still keeps its lockup spacing.
+
+## Pick one technique
+
+| Technique | Best for | How, on the timeline |
+|---|---|---|
+| Stroke draw-on | Line marks, monograms, signatures | A `path` shape clip, `trimStart`/`trimEnd` animated |
+| Mask wipe | Filled shapes, gradient marks | `wipe` preset, or a `set_mask` rect whose `mask.width` (or `x`) a document `styleTracks` entry animates |
+| Build-on | Multi-part marks, grids | One clip per part, in a group, `delayMs` staggered |
+| Wordmark | Logotypes | A text clip with a per-character or per-word `stagger` |
+| Idle loop | Loaders, ambient splash | `breathe` or `rotate` as a `loop` |
+| Scale settle | Anything, when in doubt | `pop` with a small `overshoot` |
+
+## Stroke draw-on
+
+`trimStart` and `trimEnd` stroke only a sub-range of a path, 0..1. Drawing is
+`trimEnd` running 0 to 1 with the stroke visible and the fill arriving after:
+
+```json
+{"op": "add_shape_clip", "shape": {"kind": "path", "d": "M0.1 0.7 L0.3 0.2 L0.5 0.7",
+ "stroke": "#111111", "strokeWidthPx": 6, "lineCap": "round",
+ "trimStart": 0, "trimEnd": 0}, "durationMs": 2000}
+```
+
+```json
+{"op": "animate_clip", "target": "Path", "animations": [
+  {"role": "in", "preset": "custom", "durationMs": 1100,
+   "easing": "cubic-bezier(0.65,0,0.35,1)",
+   "curves": [{"property": "trimEnd", "keyframes": [
+     {"t": 0, "value": 0}, {"t": 1, "value": 1}]}]}]}
+```
+
+Both trim channels fold as **replace**: one animation drives one of them, and two
+overlapping in time means the later wins and the earlier is discarded, reported
+as `replace_curves_overlap`. Draw with `trimEnd` alone; use `trimStart` chasing
+it only for a stroke that draws and erases, and put the two in separate windows.
+
+Stagger several strokes by stepping each path clip's `delayMs` by the
+clip-to-clip stagger in `motion-principles`, in the order a hand would draw
+them.
+
+`add_shape_clip` stores a path's `d` without parsing it. A `d` the renderer
+cannot parse reports `shape_path_invalid` (an error) from `validate_timeline`,
+and an unknown `kind` reports `unknown_shape_kind`. Either draws nothing — a
+mark that vanished is usually one of those two.
+
+## Mask wipe
+
+For a filled mark, reveal rather than draw. `{"role": "in", "preset": "wipe",
+"durationMs": 700, "params": {"direction": "left", "softness": 0.05}}` sweeps a
+feathered edge across the layer. `softness` 0 is a hard edge, which reads as
+graphic; 0.1 reads as light passing over.
+
+A `custom` curve driving `wipeProgress` needs a `mask` on the same animation —
+`{direction, softness}` — because a wipe with no edge to run against cannot be
+inferred. `wipeProgress` folds as **min**, so two wipes on one layer keep the
+tighter one.
+
+## Build-on
+
+One clip per part, each on its own overlay track, all parented to one group with
+`add_group`. Reveal the container first, then accents, then the wordmark last so
+the eye lands on the name.
+
+```json
+{"op": "animate_clip", "target": "Mark part 2", "animations": [
+  {"role": "in", "preset": "pop", "durationMs": 500, "delayMs": 80,
+   "params": {"overshoot": 1.12}}]}
+```
+
+Step by the clip-to-clip stagger in `motion-principles`, as the 80ms
+`delayMs` on the second part does. Then animate the **group** for anything that moves the whole
+assembly — one `fade` out on the group beats three chances for the parts to
+drift apart. The group's opacity multiplies into each child.
+
+When the parts already have animations, `{"op": "stagger_animations",
+"clip_ids": ["mark-id", "wordmark-id", "tagline-id"], "offset_ms": 80}`
+adds delay in that order without moving their media. Use clip IDs, with at
+least two, and give every selected clip an animation first. The first keeps
+its delay. For a repeating field of identical marks, the document's
+`repeater` sets copy count, position step, and time step on one clip. Use a
+repeater for a pattern, and separate clips for parts that need distinct art.
+
+Keep a follower aligned by storing `animationLinks` on its clip when it should
+read the mark's position, scale, rotation, or opacity. A link follows the
+source's authored animation and does not chain through other links. Put the mark and the wordmark in a flex row (`layout: {display: "flex",
+flexDirection: "row", gap, alignItems: "center"}` on a group clip, both as
+its real children via `parentId`) so the wordmark's position follows the
+mark's changing box; a backing plate is a third child with `flexItem:
+{position: "absolute", inset: 0}` behind the wordmark. These are document
+fields, so read and write the full document with `get_timeline` and
+`set_timeline_document`.
+`set_clip_params` refuses `repeater`, `animationLinks`, and `layout`.
+
+## Wordmark
+
+A text clip with a stagger. Per character for a short mark, per word for a
+lockup with a tagline:
+
+```json
+{"role": "in", "preset": "pop", "durationMs": 380,
+ "stagger": {"unit": "character", "offsetMs": 45, "from": "start"}}
+```
+
+Work the span out — `durationMs + offsetMs × (units − 1)` — and compare it
+against the clip. A span that does not fit is compressed silently, and a
+compressed wordmark is the reason a reveal "does not look staggered".
+`stagger_compressed` is the warning.
+
+Set the family to a bundled one — `Inter`, `Space Grotesk`, `Bebas Neue`,
+`Playfair Display`, `Lora`, `JetBrains Mono` — or the render and the editor
+resolve it differently and the lockup's width changes under you.
+
+## What not to do to a mark
+
+Scale, opacity, rotation about the mark's own anchor, and position are safe.
+`scaleX` and `scaleY` on their own are not: `squash` distorts the geometry, and a
+distorted logo is a brand problem rather than a taste one. Keep motion out of the
+clearspace — a support element sliding through the mark's margin cheapens it.
+
+## Landing on a sound logo
+
+Decide the audio first. A sound logo that does not exist yet is a 1–3 s
+effects brief — source, action, space — on ElevenLabs sound effects
+(`elevenlabs-audio-prompting`) or a `TrackType: SFX` prompt on Stable Audio
+(`stable-audio-prompting`); a 30-second request for a hit is a hit followed by
+room tone. Then `detect_audio_events` on the sting reports `onsets.times` in
+**seconds**; multiply by 1000. Time the reveal so the mark reaches full opacity
+and scale on that millisecond:
+
+`delayMs` on the `in` animation = onset ms − the clip's `startMs` −
+`durationMs`. Then add the accent on the hit itself, as a separate emphasis:
+`{"role": "emphasis", "preset": "pulse", "durationMs": 220, "delayMs": <onset −
+startMs>, "params": {"intensity": 0.04}}`.
+
+A settle that floats free of the sound reads as cheap even when both are good.
+`snap_to_beats` is the blunt version when the whole end card has to sit on the
+grid.
+
+For a mark that should stay on beat if the sequence tempo changes, put a
+`beat: {index, scope: "sequence", offsetMs?}` anchor on its animation in the
+full document. The index is one-based and `delayMs` adds to it. The
+`animate_clip` tool input does not accept `beat`. Keep the stored animation's
+`id`, `role`, `preset`, and `durationMs` when adding it. If the sound logo's measured
+onset is the source of truth, keep the absolute delay or use
+`bake_audio_animation` for audio-driven motion instead.
+
+## Idle loop
+
+For a loader or a splash that waits, a `loop` at low amplitude: `breathe` with
+`intensity` 0.02–0.04, or `rotate` on a mark that is radially symmetric. Set
+`durationMs` to the cycle, 2000–4000ms, and remember a cycle longer than the clip
+shows a fragment of the motion.
+
+Never loop a wordmark somebody is reading.
+
+## Hold the end frame
+
+The last thing on screen is the static mark. Leave the end hold
+`motion-principles` sets (at least 1000ms) after the reveal completes with
+nothing animating — an end card that cuts the instant it
+settles reads as a mistake. On a 2500ms clip with a 1100ms draw and a 220ms
+accent, that is satisfied; check it rather than assuming.
+
+## Start from a rig when it fits
+
+`list_compositions` and `get_composition` show the shipped `logo-sting` rig and
+its parameters. `insert_composition` places it as a group with fresh clip IDs.
+Inspect those IDs before changing its timing or staggering its parts. Use the
+`title-slam` or `word-cards` examples for a typographic reveal; they are
+starting documents rather than tool presets.
+
+## Check it
+
+- `validate_timeline`: `replace_curves_overlap` on the trims, `stagger_compressed`
+  on the wordmark, `animation_exceeds_clip` on a reveal longer than its clip,
+  `shape_path_invalid` or `unknown_shape_kind` on a mark that draws nothing.
+- `preview_timeline_frame` at the midpoint of the draw, a held moment, and the
+  last frame. The midpoint is where a half-drawn path or a stroke that never
+  closes shows up; the last frame is where you confirm the mark is clean and
+  complete.
+- Then `render_timeline`, because a sting is judged at speed.