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

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

@@ -0,0 +1,259 @@
+---
+name: motion-direction
+description: Set the motion language for a piece before anything is animated — one easing family, one timing unit, one transition family, one stagger rhythm — and audit a timeline against it. Use when starting a title pass or a whole cut, when animation feels busy, cheap or inconsistent across shots, or when turning a brand or brief into motion rules an agent can follow. Not for individual clip mechanics — that is timeline-edit-ops.
+---
+
+# Motion Direction → the rules everything else obeys
+
+Direction is the judgment layer above craft. It turns a brief into a short set of
+motion rules, so every shot reads as one hand. Most of the work is subtraction:
+deciding what does not move.
+
+`motion-principles` gives the numbers and owns them: where this page and it
+disagree, it wins. This decides which of its numbers the whole piece is
+allowed to use.
+
+## The one rule
+
+Lock the motion language first, then animate to it. Pick **one** of each row
+below and reuse it. Consistency reads as confidence; variety reads as noise. When
+in doubt, repeat rather than invent.
+
+## The motion-language spec
+
+Fill every row once, at the top of the job, and state it back to the user before
+you animate. The rows guide the timeline document; `timeline-edit-ops` owns
+the tool calls.
+
+| Row | Pick one | Example |
+|---|---|---|
+| Easing family | One entrance `easing` and one exit `easing` | `cubic-bezier(0.16,1,0.3,1)` in, `cubic-bezier(0.7,0,0.84,0)` out |
+| Base timing unit | The atomic `durationMs`; everything else is a multiple | 400 — micro 200, hero 800 |
+| Transition family | Which cut style this piece uses | `crossfade` only, hard cuts elsewhere |
+| Stagger rhythm | One `offsetMs` and one `from` | 80ms, `from: "start"` |
+| Motion intensity | The travel, scale and overshoot budget | `distance` ≤ 0.15, `overshoot` ≤ 1.05 |
+| Hold discipline | The read hold and the rest between moves | `motion-principles` § Holds: ≥ 1000ms read hold, ≥ 400ms rest |
+| Type family and weights | One bundled family and a weight for each text tier | `Inter` 800 for the hero, 400 for support |
+| Space and focus | One camera path and a depth plan, if the piece needs 2.5D | Hero at `depthPx: 0`, background farther away |
+| Shutter and texture | Which layers blur, echo, or step | Hero blur on the impact, background held |
+
+Two easings maximum: one for entrances and landings, one for exits. A third has
+to justify itself.
+
+## Match depth to the brief
+
+For a showcase, hero, launch, or "best" piece, plan each scene with a background
+bed, midground, foreground, and a grain or grade finish. Group each scene. Use
+path shapes, masks, repeaters, style tracks, animation links, and effects where
+they give the composition depth. Read the full document with `get_timeline` and
+use `set_timeline_document` for fields `edit_timeline` cannot write, including
+`styleTracks` and `repeater`.
+
+Study a shipped reference before building. Call `list_example_timelines` to
+choose a slug, then `get_example_timeline` to read its stats, scene catalog and
+first scene excerpt. Use `scene_id` to choose another scene and `clip_offset` /
+`clip_limit` to page through its layers. The CodeAct forms are
+`nodetool.timelines.examples.list()` and
+`nodetool.timelines.examples.get("kite", {clip_limit: 12})`. No library install
+or repository filesystem is needed. Kite, Prism, Voltra and Tidewater show
+different ways to group scenes and combine keyframed layers. Cadence shows a
+vertical data story built from the chart helpers and a reusable component.
+
+Build with the craft methods, not hand-keyframed fades. `video({palette,
+fonts, ...})` from `@nodetool-ai/sandbox-timeline` gives every scene
+`s.backdrop()`, `s.glow()`, `s.flash()`, `s.kicker()`, `s.pill()`,
+`s.streaks()` and `s.finish()` — the vocabulary the shipped examples build
+scenes from. A slam, a rise or a grow is `el.enter()`/`el.animate()` with the
+right `from`/props (`title.enter({from: {scale: 1.35, blur: 26, opacity: 0}})`
+is a slam), a count-up is `el.count()`, a draw-on is `el.draw()`. The depth
+plan below maps directly onto the API — reach for one of these before a bare
+`animate()` custom curve:
+
+| Plane | Built with |
+|---|---|
+| Background bed | `s.backdrop()`, `s.streaks()`, a low-amplitude `el.loop()` |
+| Midground | supporting elements, laid out in a container (`frame-composition`'s `s.stack`/`s.row`) |
+| Hero | the one element with the boldest `el.enter()`/`el.animate()`, on the beat |
+| Finish | `s.finish()` inside each scene, or `v.adjust()` for a whole-video grade after `v.series()` |
+
+Plan every showcase scene across all four before writing the hero's
+animation. Read the pack documentation
+(`nodetool.packs.docs("@nodetool-ai/sandbox-timeline")`) for every method's
+signature. A generated still or music bed can lift a showcase, but generation
+costs money. Build from the user's assets and the pack's own vocabulary by
+default. Propose a generated asset, with how many and what for, and generate
+it only after the user agrees.
+
+After saving a showcase, call
+`validate_timeline` with `{"timeline_id":"<id>","tier":"showcase"}`, or
+`nodetool.timelines.validate(id, {tier: "showcase"})`. Address its warnings
+about scene groups, custom keyframes, finish, camera and concurrent visual
+layers. These checks inspect document structure. Preview the result to judge
+composition and readability. Standard validation remains appropriate for
+ordinary edits and intentionally minimal pieces.
+
+## Typography
+
+Choose the family and weights in the motion-language spec before building text
+clips. NodeTool ships `Inter`, `Space Grotesk`, `Bebas Neue`, `Playfair Display`,
+`Lora`, and `JetBrains Mono`. Use one family across a piece and make the hero
+visibly heavier than support, such as Inter 800 against 400. `Bebas Neue` ships
+only at 400, so use size and spacing for contrast if you choose it.
+
+On a 1920×1080 frame, start a hero title at 96–160 `fontSizePx`, support at
+42–64, and a short kicker at 28–36. Keep large display tracking tight
+(`letterSpacingPx` −2 to 1); open an uppercase kicker to 2–5px. Check the
+actual words at the target frame size and adjust for fit and legibility.
+
+For an existing text clip, `edit_timeline` can set the type as a
+`set_clip_params` patch:
+
+```json
+{"timeline_id":"<id>","ops":[{"op":"set_clip_params","target":"Hero title","textStyle":{"fontFamily":"Inter","fontWeight":800,"letterSpacingPx":-1,"fontSizePx":128}}]}
+```
+
+`timeline-edit-ops` owns the full op contract. `frame-composition` handles
+placement and safe areas for each aspect ratio.
+
+## Tone and energy
+
+Place the piece on two axes and commit. Mixing cells inside one piece is the
+usual cause of "inconsistent".
+
+| | Soft (organic, eased) | Sharp (precise, snappy) |
+|---|---|---|
+| **Calm** | Luxury, wellness, editorial: long windows, generous holds, minimal stagger | Premium tech, finance: deliberate, clean, unhurried, no overshoot |
+| **Kinetic** | Lifestyle, playful, kids: overshoot and spring, loose timing | Sports, hype, gaming: short windows, hard cuts, accents on beats |
+
+## Motion personality
+
+The named preset that fills the spec's easing, timing and intensity rows. Pick
+one per project and hand it to every later step by name.
+
+| Personality | Entrance `durationMs` | Entrance `easing` | Exit `easing` | Overshoot | Presets it lives on |
+|---|---|---|---|---|---|
+| **Playful** | 400–600 | `easeOutBack` or `cubic-bezier(0.34,1.56,0.64,1)` | `easeIn` | `overshoot` 1.1–1.2 | `pop`, `bounce`, `squash`, `float` |
+| **Premium** | 400–600 | `cubic-bezier(0.16,1,0.3,1)` | `easeIn` | none | `fade`, `blur`, `kenBurns`, `breathe` |
+| **Corporate** | 300–400 | `easeOut` | `cubic-bezier(0.7,0,0.84,0)` | `overshoot` ≤ 1.03 | `fade`, `slide`, `wipe` |
+| **Energetic** | 150–250 | `easeOut` | `cubic-bezier(0.7,0,0.84,0)` | `overshoot` 1.15–1.3 | `pop`, `flash`, `shake`, `spin` |
+
+The entrance ranges come from `motion-principles`: its playful landing for
+Playful, its title and hero entrances for Premium and Corporate, and its micro
+beat for Energetic. Exits run shorter than entrances, as its quick reference
+gives.
+
+Premium sits calm-soft, Corporate calm-sharp, Playful kinetic-soft, Energetic
+kinetic-sharp. Default to Corporate for product and Playful for lifestyle.
+`easeOutElastic` and `easeOutBounce` belong to Playful alone.
+
+## Motion hierarchy
+
+Rank every element, animate down the list, and stop early.
+
+| Tier | What it is | How it moves |
+|---|---|---|
+| Hero | The one thing the moment is about | The boldest, longest, most-eased move; lands on the beat |
+| Support | Context that helps the hero land | Smaller and faster, out of the way, never competing |
+| Texture | Bed, grain, ambient drift | A `loop` preset at low amplitude; no hard events |
+
+These are the three layers `motion-principles` names Primary, Secondary and
+Ambient. If two elements compete for the eye in one frame, the direction failed:
+demote one before touching its keyframes.
+
+Hierarchy is also a track decision. Lowest track `index` renders on top, so the
+hero belongs on a low index and the bed on a high one; a scrim sits between the
+picture it darkens and the text it carries. For a camera move, set clip
+`transform.depthPx` separately from track order. The sequence's `camera2d`
+can keyframe position and depth while `focusDepthPx` and `aperturePx` decide
+which plane softens. Keep one plane legible while the others move.
+
+Use `layout` (a flex container on a group clip, its real children via
+`parentId`) for elements whose spacing should survive a text or shape
+change: `flexDirection: "row" | "column"` with `gap` keeps siblings apart,
+and a plate sized from live text is a `flexItem: {position: "absolute",
+inset: 0}` sibling in a padded container. Use
+`animationLinks` when one clip should follow another's authored position,
+scale, rotation, or opacity. Linked followers share one motion decision;
+they do not chain through a second link.
+
+## Restraint
+
+For every element ask whether the motion carries meaning. If not, hold it still.
+
+- Do not animate the whole frame at once. Leave the eye an anchor.
+- Do not stack a transition on a transition — a `wipe` cut under a `spin` in
+  under a `flash` is three ideas competing for 500ms.
+- Do not loop-animate text somebody is still reading.
+- Do not give overshoot to serious content.
+- One outsized moment per piece. A second cancels the first.
+- A clip that both dissolves in and carries a `fade` in ramps twice and reads
+  slower than either alone. Pick one.
+
+## Pacing
+
+Map energy across the whole timeline before timing any single move: a low open,
+a build, one peak, a settled end. Vary it on purpose — tension, then release.
+Stillness is pacing, not a gap. `beat-sync-editing` turns this shape into cut
+points.
+
+An animation's `beat` anchor follows the document tempo: one-based `index`,
+`scope: "clip"` or `"sequence"`, and optional `offsetMs`. A measured audio
+curve from `bake_audio_animation` follows the audio source instead. Use the
+former for a rhythmic rule and the latter when a real onset or envelope must
+drive the picture. `stagger_animations` offsets existing animations across an
+ordered list of clip IDs while leaving media timing fixed.
+
+Choose motion texture deliberately. `repeater` makes positioned, delayed
+copies of one clip; `temporalEcho` trails it with fading delayed copies;
+`steppedTime` quantizes its clock. Per-clip `motionBlur` controls its own shutter
+angle and minimum sample count. When layers request different counts, the
+scene uses the highest count up to 32 and samples each layer evenly across its
+own shutter. Give blur to the fast hero when it clarifies direction, then
+inspect the held frame for readability.
+
+## Direction notes, per shot
+
+Write intent, not keyframes. One line per shot is enough for someone else — or a
+later turn — to animate it:
+
+> Shot 3, 4s. Hero: the price plate, `pop` in on the downbeat, Corporate.
+> Support: the caption 80ms behind it, `fade`. Texture: bed holds `kenBurns`
+> from shot 2. Nothing else moves.
+
+For a repeated title or logo system, inspect `list_compositions` before
+building bare clips. `title-slam`, `word-cards`, and `logo-sting` are starting
+rigs when their timing matches the brief. `timeline-edit-ops` owns the tool
+contract. `set_clip_params` does not accept the new camera, layout, link,
+repeat, echo, step, or per-clip blur fields; author those through the full
+document with `set_timeline_document` after reading it with `get_timeline`.
+
+## The consistency audit
+
+Before calling a pass done, read the document back with `get_timeline` and check
+every clip against the spec. A miss is a direction defect, not a preference.
+
+- Same easing family on comparable moves, and no stray `linear` outside loops.
+- Every `durationMs` a multiple of the base unit.
+- Only the chosen transition types on the cut.
+- One text stagger rhythm, and one `offset_ms` order for cross-clip builds.
+- Hold discipline respected: every read hold and every rest between moves meets
+  `motion-principles` § Holds. A still hero is not a still frame: the Texture
+  bed keeps moving through the holds, so a static bed is still a finding in
+  the `motion-graphics` review pass.
+- Exactly one hero animating at any instant.
+- One font family, and it is a bundled one — `Inter`, `Space Grotesk`,
+  `Bebas Neue`, `Playfair Display`, `Lora`, `JetBrains Mono`. Anything else
+  reports `font_not_portable` and resolves differently per host.
+
+Then look: `preview_timeline_frame` over the midpoints of the moves you just
+audited. An audit that only read the document has checked the spec, not the
+picture.
+
+## Required example comparison
+
+Run the review pass `motion-graphics` owns (its `## Review pass`) once, not
+twice per piece — contact sheet, per-scene checklist, example comparison,
+`tier: "showcase"` validation, and a real revision. Judge what comes back
+against this page's spec too: does the busiest scene still respect Motion
+hierarchy, does Restraint survive under the example's density, is the chosen
+Motion personality still legible once the gaps are closed.

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

@@ -0,0 +1,217 @@
+---
+name: motion-graphics
+description: Build and review a NodeTool timeline piece — the motion agent's entry point. Covers the build loop, choosing between the code pack and edit ops, the revise-by-editing-the-script loop, and the review pass. Use for title cards, kinetic text, lower thirds, clip entrances and exits, and layered motion.
+featured: true
+---
+
+# Motion Graphics → Timeline Agent
+
+## Before the first edit of a new piece
+
+When starting a piece from a brief, load `motion-direction` and
+`motion-principles` with `load_skill` before the first timeline edit. Use them
+to set the motion language and timing for the whole piece. Do not start
+animating from this file alone.
+
+If the piece has a title layout or an end card, also load `frame-composition`
+before that first edit. If it has an end card, load `logo-reveal` too. These
+loads are required even when this skill was the only one selected from the
+catalog.
+
+For showcase, hero, launch, or "best" briefs, follow `motion-direction`'s
+depth plan and example timelines before writing scenes.
+
+Motion is built, then checked. Author with the pack or with ops (below), then
+look at the frames with `preview_timeline_frame`. A change you have not looked
+at is not done.
+
+## Load other craft skills for the job
+
+This file is the build loop and the entry point, not the op contract. After
+the required loads above, load other relevant craft skills for the job and
+come back here to pick the authoring surface.
+
+| The question | Skill |
+|---|---|
+| Where do the cuts land, how do I pace it, how do I ramp a hit | `beat-sync-editing` |
+| Which colours, in what order do I grade, what can actually move | `color-motion` |
+| A preset is close but not right; overshoot, decay, wiggle, arc, draw-on | `motion-curves` |
+| An ambient bed behind the content | `motion-background` |
+
+Three are neighbours rather than layers. `caption-titles` decides what text
+says and when it appears. `video-audio-continuity` decides, before the first
+clip renders, whether a multi-scene piece's sound comes from one generated clip
+or from a track of your own — a decision this file's ops cannot undo. The
+board skills (`explainer-storyboard`, `commercial-beat-sheet`,
+`launch-commercial`, `music-video-treatment`, `trailer-template`) decide the
+shots before there is a timeline to animate; `assemble_storyboard_timeline` is
+where their board becomes this file's document.
+
+Anything generated for the timeline — a bed, a sting, a voice, a clip — has a
+model line with its own guide. `find_model` returns `prompting_skill` on a
+route it covers; `load_skill` it before writing that prompt.
+
+## The build loop
+
+Build a piece in four moves: **direct** (fix the motion language and the
+scene list before writing anything — `motion-direction` and, when there is a
+title or end card, `frame-composition`/`logo-reveal`), **build** (write the
+scenes in code, one `v.scene` per beat), **save** (`v.save()` attaches the code; read
+`saved.code` and `saved.warnings`), **review** (the
+pass below). Revise by editing that script — see below — and repeat the
+last two steps. A piece that renders clean on the first save has not been
+looked at yet.
+
+## Choose the authoring surface
+
+Two ways to touch a timeline document. Pick by what changed, not by habit.
+
+| Situation | Surface |
+|---|---|
+| A new cut, or a scene with more than a few clips | `@nodetool-ai/sandbox-timeline` (code) |
+| A few edits to a cut that already exists — retiming a clip, swapping a preset, nudging a stagger | `edit_timeline` ops |
+
+**Code, for a new cut.** In a JS script or a Code node, `import { video } from
+"@nodetool-ai/sandbox-timeline"`. Its `video()` builds a document of scenes
+(`v.scene(name, seconds, fn)`, local time in seconds), lays them out with
+`v.series([...])`, and `v.save(nodetool.timelines, {...})` validates, creates
+the timeline, writes the whole document and validates again. It throws on any
+validation error and returns `{timeline_id, warnings}` plus `code`. A cut
+with hundreds of keyframed clips costs a handful of API calls this way,
+instead of one `edit_timeline` op per clip. NodeTool's shipped example
+timelines (Cadence, Kite, Prism, Serein, Voltra, Tidewater, T minus 30) are built with it. Its
+full signatures, options and gotchas are the pack's own skill — read
+`nodetool.packs.docs("@nodetool-ai/sandbox-timeline")` before writing scenes,
+not this file. `frame-composition` covers how to lay out what goes inside a
+scene; this file covers the build loop and the ops surface below.
+
+**Ops, for an edit.** `edit_timeline` takes a timeline ID and an `ops` array,
+run in order, up to 60 per call:
+
+```json
+{"timeline_id":"<id>","ops":[{"op":"animate_clip","target":"Title","animations":[{"role":"in","preset":"fade","durationMs":400}]}]}
+```
+
+Its full op shapes, what each op refuses, and when a change instead needs a
+whole-document `set_timeline_document` write are `timeline-edit-ops` — load it
+before a batch of ops, not this file.
+
+## A compact two-scene piece
+
+The build loop end to end: a backdrop, a laid-out title block, a counter, a
+transition, a finish pass, save, then read the warnings.
+
+```js
+import { video } from "@nodetool-ai/sandbox-timeline";
+
+const v = video({
+  width: 1920, height: 1080, fps: 30,
+  palette: { ink: "#06110e", ink2: "#0c2a21", text: "#f4fbf8", accent: "#34d399" },
+  fonts: { display: "Space Grotesk", body: "Inter" }
+});
+
+const hello = v.scene("Hello", 2.5, (s) => {
+  s.backdrop();
+  const kicker = s.kicker("LIVE");
+  const title = s.text("Round-ups", { size: 120, weight: 700, font: "display" });
+  const sub = s.text("on every card", { size: 40, color: "#8fb3a6" });
+  s.stack([kicker, title, sub], { gap: 20 }); // frame-composition: a title block
+  title.enter({ from: { scale: 1.2, opacity: 0 }, dur: 0.3, ease: "outExpo" });
+  sub.enter({ from: { offsetY: 24, opacity: 0 }, at: 0.15, dur: 0.25 });
+});
+
+const outro = v.scene("Outro", 1.8, (s) => {
+  s.backdrop({ colors: ["#0f3b2e", "#06110e"] });
+  const counter = s.text("$0.00", { size: 96, font: "display" });
+  counter.count({ from: 0, to: 1.6, dur: 1.2, prefix: "$", decimals: 2 });
+  s.finish({ vignette: 0.2, grain: 0.05 });
+});
+
+v.series([hello, v.transition("wipe", 0.3, { direction: "left" }), outro]);
+
+const saved = await v.save(nodetool.timelines, { name: "Round-ups", showcase: true });
+if (saved.warnings.length) {
+  // read them before calling this done — see Review pass below
+}
+```
+
+## Author and revise with code
+
+`v.save(nodetool.timelines, {...})` attaches the code that rebuilds the
+timeline as its source — no separate `code.set` call. The stored code is the
+retained program: the scene callbacks and the helpers they use, with every
+research result, generated asset id and loop value written in as a literal.
+The calls that produced those values ran once, in your action, and a rebake
+never repeats them. `saved.code.embedded` is false, with the reason in
+`saved.code.warnings`, when a scene callback calls `nodetool.*`, uses
+`Math.random()`/`Date.now()`, or reads a value that is not plain data. Do the
+research and generation at the top level, then build the scenes from the
+results. To attach code after the fact,
+`nodetool.timelines.code.set(timeline_id, code)` bakes the code, which must
+build the timeline without a capability call.
+
+Revising a code-backed timeline is: `code.get(id)` → `code.edit(id, edits)`
+with a few small exact string replacements (each `old` matches exactly once)
+→ read the `conflicts` and `warnings` it answers → look at frames. This is
+the review → revise → rerun loop from the build loop above, made cheap — a
+two-line diff instead of a 500-line resend. `edit_timeline` ops still apply
+for a timeline with no code, or a deliberate hand tweak — `timeline-edit-ops`
+owns that contract and what it costs a code-backed scene. The pack's own
+skill (`@nodetool-ai/sandbox-timeline`) covers what code-backed identity
+means for scene names and clip ids; `api-timelines` owns the full `code.*`
+call contract.
+
+## Review pass
+
+For a showcase, hero, launch, or "best" piece, critique like a director before
+calling it done. A render with no errors is not a finished piece — this pass is
+part of the job, not a step to skip when the frames look clean. Reserve rounds
+for it: the run budget is shared with authoring, so budget for at least one
+full pass plus one revision, not just the build.
+
+1. **Contact sheet.** `preview_timeline_frame` with `sheet: true`, sampling
+   every scene at its entrance, its hero hold, and its exit.
+2. **Per-scene checklist**, answered in writing before you touch an op:
+   - What does the eye follow first, and is that the intended hero?
+   - What moves in the background? A static bed behind the action is a
+     finding, not a pass.
+   - Does any text touch or get crossed by a shape?
+   - How much of the frame is actually used? Look yourself — the validator's
+     `showcase_frame_underfilled` check is a bounding-box proxy and can miss a
+     thin outline or ring that reads as sparse against an empty backdrop.
+   - Does every number that is supposed to count actually count, and finish
+     while it is still on screen?
+   - How does the scene exit and the next one enter? A default crossfade on a
+     showcase brief is a finding to name, not the absence of one.
+3. **Compare against a reference.** Pick the closest scene with
+   `examples.list()` / `examples.get(slug)`. Render matching-beat sheets of
+   your piece and that example with `preview_timeline_frame`, `sheet: true`,
+   mapping beats across differing durations and sampling the middle of a
+   move. Call `view_image` on both with this explicit question: "Compared
+   with the example, what is missing in layer count, secondary motion,
+   texture and light, and camera depth? Name the beat and the gap." Read how
+   the example scene was actually built with `examples.source(slug)` when the
+   clip excerpt alone does not explain a moment — a repeater's phase offsets,
+   a two-pass text effect, a shared id scheme. `compare_timeline_frames`
+   cannot target a shipped example — both its sides must be your own timeline
+   (an id, version or document) — so use it after a revision to prove which
+   frames actually changed, not to judge against a reference.
+4. **Validate at the showcase tier.** `validate_timeline` with
+   `{"timeline_id": "<id>", "tier": "showcase"}` (in code,
+   `nodetool.timelines.validate(id, {tier: "showcase"})`) returns `errors`
+   and `warnings` — there is no `issues` field.
+   Every `showcase_*` warning is a hard stop: resolve it, or state the
+   specific artistic exclusion to the user before rendering. Expect
+   `showcase_scene_groups_missing`, `showcase_custom_motion_missing`,
+   `showcase_finish_missing`, `showcase_camera_missing`,
+   `showcase_layer_density_low`, `showcase_scene_group_density_low`,
+   `showcase_custom_animation_density_low`, `showcase_effect_variety_low`,
+   `showcase_clip_density_low`, `showcase_motion_blur_missing`, plus
+   `showcase_frame_underfilled`, `showcase_text_collision`,
+   `showcase_motion_range_narrow` and `showcase_dead_motion`. Each names a
+   shipped example to study. Zero warnings is a structural floor, not a
+   craft verdict — the medians in the warning text are the design target.
+5. **Revise, then re-run this pass.** Make at least one revision that changes
+   the composition itself, not only a fix for a validator error, before
+   calling the piece done. Then repeat steps 1–4 on the result. Stopping at
+   the first clean render is the failure this pass exists to catch.