beutl-agent-timeline-from-shotlist

name	beutl-agent-timeline-from-shotlist
description	Build a Beutl timeline from a shot list through the Agent Editing Toolkit MCP tools.

Beutl Agent Timeline From Shot List

Use this skill when an agent needs to turn a shot list, storyboard, or timed brief into a Beutl project through the Agent Editing Toolkit.

Workflow

Author storyboard-first: plan a fine shot breakdown, build the static layout of every shot (static storyboard) with no keyframes and no effects, lock it, then add effects, then motion. Do not animate or add effects until the static storyboard reads correctly. The phases below map to that order.

Phase -1 — Video type classification

Before classifying, check the intake. If the incoming request is terse (missing two or more of: subject specifics, target duration, mood or audience, explicit style/palette constraints, an asset inventory) or the user supplied reference images/video/URLs for the intended look, load beutl-agent-brief-expansion first and use its recorded expandedBrief as the brief for classification and Phase 0. Expanded-brief fields are derived defaults: user-stated constraints stay literal, and the derived paletteDirection feeds derive_palette inputs rather than replacing its outputs. Runs that started from brief expansion are low-effort mode and must run the visual-review convergence loop in Phase 4 (step 21a).

Classify the brief before Phase 0. Record videoType and a one-line reason in notes, then call get_started(videoType) and follow the returned type workflow. Supported values are motion-graphics, footage-cut, slideshow, lyric-captions, and logo-intro. If the brief requires source clips, photos, music, SFX, or fonts that are missing from the workspace, load beutl-agent-asset-sourcing before Phase 0, decide source-or-generate per asset, and record provenance in assets/manifest.json before placing media.

videoType	Signals
motion-graphics	Authored graphics, kinetic type, promo/explainer/infographic motion, BPM or beat-grid language, layered background grammar, no source media inventory as the main driver.
footage-cut	User supplies video clips, says edit my clips/vlog/event/interview/B-roll, asks for trim/order/source audio/music bed, or needs narrative clip coverage.
slideshow	Photos/stills plus music, photo movie/album/memories language, per-photo duration grid, gentle Ken Burns motion, consistent transitions, caption read time.
lyric-captions	Lyrics, subtitles, captions, transcript, timestamp sync, per-line timing, readability and contrast as the core deliverable.
logo-intro	Logo animation, intro, stinger, bumper, brand mark, 3-10 seconds, single subject, anticipation/reveal/settle/hold arc.

Pass the resolved videoType on every preview_quality_risks, suggest_quality_fixes, evaluate_edit_quality, and final_preflight call. Do not omit it after classification; omitted videoType intentionally means the legacy motion-graphics gate behavior. For motion-graphics and slideshow, pass the derived palette role colors to rendered Phase 4 quality calls as paletteRoleColors using #RRGGBB values, preferably as an array of { "role": string, "color": "#RRGGBB" } objects. If an MCP client cannot send that complex array reliably, pass paletteRoleColors as a JSON string containing the same array. If derive_palette returned #AARRGGBB, drop the alpha channel before calling the quality tools.

videoType	Existing phases as-is	Replaced or specialized phases	Skipped unless requested
motion-graphics	Everything as written today.	None.	None.
footage-cut	Phase 1 staged apply_edit, read_document_summary, measure_object_bounds, Phase 4 still/quality/preflight.	Phase 0 creative direction/palette/background grammar becomes media inventory plus cut list unless authored graphic overlays are requested; when required clips are missing, load beutl-agent-asset-sourcing and record assets/manifest.json provenance before placing media; shotBreakdownPlan becomes clip in/out/order/Start/Length; audio handling is explicit.	derive_palette and get_background_grammar unless graphic overlays are requested; motion-graphics density/beat-grid plan conformance.
slideshow	Phase 1 static storyboard, measured captions, staged apply_edit, Phase 4 still/quality/preflight.	Phase 0 becomes image ordering, per-photo duration grid, and transition vocabulary; Phase 3 uses minimal Ken Burns-style scale/translate per photo.	Background grammar and dense foreground layer planning unless captions/backing graphics need it; BPM beat-grid checks.
lyric-captions	Phase 1 layout, measured text/backing plates, Phase 4 still/quality/preflight.	beatGridPlan becomes a timestamp sync table; shotBreakdownPlan becomes one Element per line/caption with Start/Length from the sync table; type roles are hero line/echo/credit.	Motion-graphics background richness and density planning; BPM-driven tempo targets unless the brief separately requests them.
logo-intro	Phase 1 static end-frame build, Phase 2 effects, Phase 3 motion authoring, Phase 4 still/quality/preflight.	shotBreakdownPlan collapses to one 3-10 second shot with anticipation/reveal/settle/hold; storyboard subdivision reviews the internal motion arc instead of adjacent cuts.	Multi-shot cut-continuity planning, shot-count expectations, BPM tempo planning unless explicitly requested.

Phase 0 — Direction and shot breakdown

1. Author the creative direction yourself. list_creative_directions is optional divergence stimulus, not a menu to pick from.
   • Decide the concept, base hue, tonal seed, harmony scheme, type system, motion vocabulary, and shot structure from the brief (or from scratch when the brief is vague) before leaning on any tool. Do not anchor on returned seed names.
   • Record the derivation reason before any color or background authoring: why this subject, audience, mood, keywords, and delivery surface lead to this hue family, tone, material vocabulary, and motion vocabulary. Unjustified choices are disallowed; if you cannot explain a hue/tone/motion choice, derive again instead of using it.
   • Call list_creative_directions (pass a fresh seed each run to vary the stimulus) and read its recentToAvoid list. Your direction MUST differ structurally from those recent fingerprints: change the dominant motion verbs, layout, palette family, and type treatment, not just the words. Do not default to the same look every run (e.g. hero-glow-on-dark + dashed selection-marquee + magnetic letter-spacing) — that repetition is the monotony this step exists to prevent.
   • Call derive_palette with baseHueDegrees, tonalSeed, harmonyScheme, the recorded derivationReason, and structuralSignature. Resolve any hue-band or structural repeat warning by changing the direction, or record a concrete reason why the repeat is intentional for this brief before continuing.
   • Call get_background_grammar, then instantiate the grammar in notes: one base layer, one required depth layer, optional second depth layer, one motion slot, and the three depth bands background, midground, and foreground. Concrete values come from the brief and derived palette, not from the grammar ranges alone.
   • The required workflow is: derive direction with recorded reason -> derive_palette -> instantiate background grammar. Any deviation, including hand-picked colors, skipped grammar, missing depth band, static background, or ignored repeat warning, requires a recorded reason in notes before apply_edit.
   • If the user prompt specifies concrete constraints (motif, style, palette, message, audience, subject), keep them literal; use the stimulus only to make the result less generic.
   • Once the concept is locked, call record_creative_direction with its fingerprint (concept label, palette roles, motion verbs, structural signature) so future sessions steer away from it.

Contrast Exemplars - derive, don't copy

These examples describe relationships to derive with derive_palette; they are not literal palettes to reuse.

• Good: text-primary is much lighter than a dark bg-base and still clears the 4.5:1 floor against the brighter bg-accent; the saturated accent is small and clears 3.0:1 against bg-base.
• Good: on a light tonal seed, text-primary is a dark low-saturation role, foreground is the readable material color, and the bright accent is reserved for small motion cues.
• Bad: cyan text on a pale blue or bright yellow background relies on hue difference but fails luma contrast.
• Bad: three fully saturated roles at similar lightness compete; mute support colors and let one accent carry saturation.
• Bad: dark teal base plus cyan and magenta neon is only allowed when the brief explicitly asks for that look and the reason is recorded.

Phase 1 — Static storyboard

Build the static layout of every enumerated shot with NO keyframes and NO effects. The deliverable is a readable static storyboard: correct composition, hierarchy, typography, color, and layering at each shot's representative frame.

5. Create or attach a session:
   • Stdio/headless: create_project or open_project with a .bep project path. Paths without an extension are normalized to .bep; .beutl is reserved for exported project packages.
   • Live editor: attach_active_editor. In the in-app host, open_project/create_project open the project in the running Beutl editor itself (the editor holds a single open project) and return a LiveEditor session — opening a project different from the one already open is rejected; attach or have the user close it first.
6. If live attach fails and the task allows headless output, switch to the stdio/headless create_project route rather than creating a custom generator.
7. When an output directory is requested, create/update notes.md there before the first edit and after every apply_edit, save_project, render_storyboard, preview_quality_risks, suggest_quality_fixes, render_still, evaluate_motion_variation, evaluate_edit_quality, compare_revisions, final_preflight, and export_video result. Record success/failure, change count or verdict/path, and the next action. While drafting a large patch before the next tool call, append a short heartbeat note every few minutes with the current stage and blocker risk.
8. Call read_document and keep the returned schemaVersion.
9. Build the static layout as a declarative document (Phase 1 — no motion, no effects):
   • Use PascalCase property names exactly as returned by get_schema.
   • New timeline Elements require $type: "[Beutl.ProjectSystem]:Element".
   • Use stable Id handles when modifying existing elements.
   • Omit Id only for genuinely new elements/objects so the toolkit can mint one.
   • Do not add a second Object to an ordinary existing Element. To place another visible item, create another Element with its own single EngineObject. Add multiple to one only for an intentional flow chain such as , , , or ; keep the parent and omit only for genuinely new child objects in that flow chain.

• Call render_storyboard to render one still per enumerated shot plus a contact-sheet PNG of the whole storyboard. Review it as a static storyboard: every planned shot present, one clear focal point per shot, readable typography, the intended layering and color, and correctly aligned text/backing-plate pairs. For a scene with many Elements the synchronous call can exceed the MCP client request timeout; pass background: true to get { status: "running", jobId } immediately, then poll read_render_job(jobId) until state is completed (its result holds the storyboard payload) — do not issue apply_edit while a background render is running; call cancel_render_job(jobId) to abort a background render you no longer need.
• For a continuous single-shot piece whose Element boundaries do not create useful auto shots, pass explicit timeSeconds to render_storyboard instead of hand-assembling contact sheets from render_still. Choose representative times for opening, reveal/development beats, settle, and final hold; use subdivisionLevel:1 or 2 to inspect the motion arc between those anchors.
• Run preview_quality_risks(videoType:<resolved>) (it does not evaluate motion). Of its categories, only elementStructure can fail the gate; shapeIntent, decorativeShapeClarity, and gradientFalloff are advisory, but fix their major findings before still rendering when they reflect a genuine accident (not a recorded creative choice). For multiple related issues, call suggest_quality_fixes(videoType:<resolved>) and apply the smallest repair. For high-tempo promos, set a styleProfile such as high-tempo-promo, kinetic-type, or high-tempo-promo 130bpm.
• Run evaluate_edit_quality(videoType:<resolved>, staticLayout:true) — the storyboard-phase gate. It skips motion checks, so the motionless storyboard is judged on composition, typography, readability, and structure only. Resolve critical/major issues before leaving this phase.
• Use measure_object_bounds for any text/backing-plate pair that looks misaligned in the contact sheet.
• Do NOT run evaluate_motion_variation, evaluate_edit_quality without , or in this phase — those are motion-phase gates and will false-block a static storyboard (identical frames read as zero motion). Iterate Phase 1 until the storyboard reads correctly; only then proceed.

Phase 2 — Effects

15. Add effect chains onto the locked storyboard, one named job at a time. Do not start motion until effects read correctly on stills.

• Every effect chain needs a named job: material texture, hierarchy separation, transition energy, color grade, or text legibility. Remove decorative stacks that do not serve one.
• For organic heat, ink, glass, smoke, grain, caustic, or atmospheric fields, prefer SKSLScriptEffect (from list_effect_recipes) over stacking only blurred gradient shapes; SKSL is CPU-safe in still renders. Prefer SKSL over GLSL for low-context file sessions. The fine-film-grain-field recipe ships a monochrome film-grain shader; organic-shader-field ships a colored field shader — pick by intent, and validate_shader any custom SKSL before apply_edit.
• GPU/stylize effects (GLSL, PixelSortEffect, ColorShift on split-character text) are render-guarded to skip degenerate targets rather than crash, and run on the SwiftShader software fallback when no hardware GPU is present (slower, not skipped); confirm every effect with render_still/render_storyboard. Vary the effect vocabulary instead of over-restricting to one safe effect.
• For masked reveals, knockouts, alpha mattes, and wipes, use the real masking mechanisms rather than covering rectangles: every Drawable has an animatable BlendMode whose Porter-Duff modes (SrcIn, DstIn, SrcOut, DstOut, Modulate) composite it against the content below it in the same flow — scope the matte by putting mask and content inside one DrawableGroup/DrawableDecorator Element so it does not knock out the whole frame — and the Clipping FilterEffect (animatable Left/Top/Right/Bottom) is the rectangular wipe/crop primitive. Blend-mode matte behavior depends on flow order, so source-ground the exact compositing rule (beutl-agent-source-grounding) and verify with render_still before building a sequence on it.
• For a true emissive glow/bloom (light that adds over the original, not a DropShadow fake), duplicate the drawable with duplicate_object passing wrapInGroup=true, then apply_edit the additive-bloom recipe (blur + BlendMode Plus + reduced Opacity) onto the returned so the copy glows over the untouched original. puts the original and copy under a (an ) so 's check stays clean; move the copy to a separate Element at a higher instead when it needs independent timing or z-order. Lower or switch to for bright footage that blows out.

Phase 3 — Motion

16. Add keyframes and animation on top of the locked storyboard and effects. Build the reveal, development, and resolution phases from motionContinuityPlan, and animate multiple property families (transform, opacity, brush/gradient, effect parameters, text spacing) — not just X plus opacity. Vary easing families per the 12 principles: use cubic/quintic ease-out for entrances, ease-in-out for moves, and reserve linear motion for deliberate mechanical travel. The easing catalog is much wider than cubic/sine — BackEase*/ElasticEase* give overshoot and anticipation, BounceEase* gives physical settles, and SplineEasing takes custom cubic-bezier control points; use them deliberately on accents (a bounce on every element turns cartoonish). Stagger related element starts by about 0.1-0.3 seconds and vary durations/directions so follow-through and overlapping action are visible. Apply motion in small apply_edit stages per beat and inspect validation after each; pass quiet: true for large patches.

• Author the camera moves from cameraPlan first, before per-element accents: keyframe the [role:camera-rig] DrawableGroup's TransformGroup children — TranslateTransform.X/Y for pans and whip-pans, ScaleTransform.Scale for push-in/pull-back (set TransformOrigin so the zoom centers on the shot's focal point), RotationTransform.Rotation for roll. Fetch get_examples for insert-camera-rig-push-in (nested rig) or insert-camera-rig-portal (timeline rig) and reuse its structure. Camera moves are slow and eased by default (a push-in of roughly 3-8% scale over the shot already defeats the static-slide feel); whip-pan bridges are the fast exception. For parallax, keyframe each depth-band rig's translate at a different amplitude (background slowest). Remember the inverse: camera-left = rig-right, camera-in = scale-up. For a true 3D dolly or orbit, use a Scene3D object and keyframe its Camera.Position/Camera.Target instead of faking perspective with 2D scale.
• For perspective moves on 2D content (card flips, page turns, tilted reveals), use Rotation3DTransform (RotationX/RotationY/RotationZ, CenterX/Y/Z, and Depth — the perspective distance, default 500) inside the TransformGroup instead of faking depth with 2D scale alone.
• For kinetic type, set TextBlock.SplitByCharacters=true (animatable) so glyphs composite individually — this is the enabling property behind "split-character" effects such as per-glyph ColorShift fringing or PartsSplitEffect shatter — and animate TextBlock.Spacing for tracking-in/out reveals. Stagger per-character timing rather than moving the whole block as one unit.
• For line-drawing reveals ("the stroke draws itself on"), animate Pen.TrimStart/Pen.TrimEnd (0-100) on a GeometryShape/shape/text stroke; for marching-dash accents set Pen.DashArray (a static float list) and animate Pen.DashOffset.
• Audio is authorable, not analysis-only: keyframe Sound.Gain (percent: 100 = unity, values above 100 amplify) for fade-ins/outs and ducking under narration, set Sound.Effect to an with /// children for echo/EQ/dynamics, and use (an — the pairing rule applies) to submix multiple audio Elements.

Phase 4 — Motion verification and export

17. Re-render the storyboard with subdivisionLevel: 1 after Phase 3 motion authoring; raise to subdivisionLevel: 2 for suspicious gaps. READ the contact sheet, including every kind: "inbetween" frame, and check cutEyeTrace before judging continuity. For multi-shot types (motion-graphics, footage-cut, slideshow, lyric-captions), every adjacent shot pair must show the planned continuity: an element crossing the cut, a camera move continuing across it (matched push-in, whip-pan), a sweep, shared background continuity, an overlapping transform/opacity ramp, a deliberate hard-cut reason, or a consistent slideshow transition. Also verify the cameraPlan executed: shots planned as push-in/pan/parallax must show visible framing change between their in-between frames — identical framing on a non-locked shot is a rework finding. If the in-between frames look identical to the anchors except for an unplanned hard swap, treat it as a rework finding and add bridge animation or transition consistency. If cutEyeTrace.exceedsEyeTraceBudget is true and no planned bridge or hard-cut reason exists for that pair, treat it as a rework finding: add a bridging element, sweep, or focal-point realignment. For logo-intro, review the single-shot motion arc instead of cuts: anticipation, reveal, easing, settle, and the final hold. Record cutContinuityActuals or motionArcActuals in notes with pass/fail, evidence frame names, cutEyeTrace displacement when present, and the repair when needed.
18. Verify with render_still at representative shot boundaries. Treat any returned warnings as a blocker for export until you have either revised the scene or recorded why the warning is acceptable. In live-editor sessions, renders honor the editor's layer state — TimelineLayer lock/solo/audio-mute/video-mute and Element.IsEnabled — so if an expected layer is missing from a still, check those flags before diagnosing your own edit as the cause. For each still, record visibilityAnalysis.visiblePixelRatio, foregroundPixelRatio, occupiedBoundsRatio, and maxQuadrantForegroundRatio; compare activeElements against the planned visible elements; note the primary focal point, whether text/title elements are readable for their duration, whether effect chains still serve their named jobs, and whether foreground/background/accent density is present. Development and resolution stills should show at least three visible layer types, such as background/surface, primary motion, accent/detail, and typography; if text is present, it must have clear contrast against the background.

• If a large decorative RectShape remains active behind several unrelated text shots, treat it as a likely text-background-fit problem before quality review. Limit it to the shot where it belongs, move it clearly into the background/surface role, or replace it with stroke/ellipse/path/procedural texture.

19. Run evaluate_motion_variation across 4-6 samples. If it reports low-motion-variation or poor-frame-coverage, or if the still review shows planned elements are never visible/readable, revise the edit.
20. Run evaluate_edit_quality(videoType:<resolved>) with the same sample set (the full motion gate; leave staticLayout off here). For motion graphics, pass plannedForegroundElementsPerShot from quantitativePlanSheet; for motion-graphics and slideshow flows, also pass paletteRoleColors from the derive_palette roles so paletteBalance can report the authored 60-30-10 area mix. Use an array of { "role": string, "color": "#RRGGBB" } objects, or a JSON string containing that same array when the MCP client cannot send complex arrays reliably. When beatGridPlan came from analyze_audio_rhythm, also pass beatTimesSeconds so audioSync advisories can flag near-miss cuts. Pass allowMinimalDensity=true only when the brief explicitly asks for minimal/negative-space density and the deviation is recorded. Only gate-failing issues (typographyReadTime, rendered typographyContrast, elementStructure, motionContinuity, and supplied-plan layerDensity) block export; shapeIntent, motionIntent, decorativeShapeClarity, gradientFalloff, tempoRhythm, paletteHarmony, and backgroundRichness major issues are advisory and do not block. Revise and re-run until passesQualityGate is true; fix genuine-accident advisory findings when time permits, or record the explicit user reason for allowing an issue.

• For motion-graphics deliverables, animatedPropertyCount: 0 is a blocker even when evaluate_edit_quality.passesQualityGate is true. Add explicit transform, opacity, spacing, brush, or effect animation before export.
• For textBackgroundFit issues involving decorative glass/light/texture rectangles, prefer a real design fix over suppressing the issue: constrain the rectangle's Start/Length to the intended beat, align it as a named backing plate with measure_object_bounds, lower it into the background, or replace it with a non-plate visual treatment.
• For high-tempo/BPM briefs, inspect metrics.tempo.RequiredTimelineEventsPerSecond, TimelineEventsPerSecond, RequiredTotalEventsPerSecond, LongForegroundGapCount, and LongestForegroundEventGapSeconds. A scene is too slow if background motion hides sparse foreground changes or long foreground gaps.
• After each revision apply_edit made in response to Phase 4 quality or visual-review findings, call compare_revisions before the next broad fix. Record a delta ledger in notes with metric deltas, issues resolved, issues introduced, regression, and the paired still paths. If regression=true, treat the introduced/worsened axis as a rework finding before export.

21. Plan-conformance check (before finishing). Before final_preflight/export, compare the authored result against your quantitativePlanSheet on the same four axes — not just the pass/fail gate. Gather actuals from read_document_summary for shot/Element count, evaluate_edit_quality metrics.tempo (TimelineEventsPerSecond, SlowHoldCount, LongestForegroundHoldSeconds), metrics.layerDensity (Bands, AverageForegroundLayerCount, MinimumForegroundLayerCount, BandsBelowHalfPlannedForegroundLayerCount), and evaluate_motion_variation. Confirm all four: actual shot/Element count ≥ planned shot count; actual TimelineEventsPerSecond ≥ planned edits/sec target (and ≥ RequiredTimelineEventsPerSecond); every hold ≤ its planned ceiling (no SlowHoldCount beyond named resolves); every measured time band's ForegroundLayerCount meets the planned density floor, with a Major layerDensity issue if authored density falls below half the supplied plan. Any axis short of the plan is a rework blocker — add the missing shots/events/layers and re-verify, or record a true minimal-density brief and pass allowMinimalDensity. Record a conformance summary in notes: per axis, planned vs actual vs pass/fail. 21a. Convergence loop for low-effort runs. When the run started from beutl-agent-brief-expansion (or the coordinator explicitly requests convergence), run beutl-agent-visual-review in its convergence loop mode after the deterministic gates pass and before final_preflight: iterate revision passes until every rubric axis scores ≥ 3 or the pass budget (default 3) is exhausted, phrasing every directive in the expanded brief's own concept vocabulary. An unconverged result hands off to the human with the delta ledger instead of exporting silently.
22. Prefer final_preflight(videoType:<resolved>) before export when the tool is available. For motion graphics, pass requireAnimatedProperties=true and plannedForegroundElementsPerShot from quantitativePlanSheet; for motion-graphics and slideshow flows, pass the same paletteRoleColors shape used in evaluate_edit_quality; pass beatTimesSeconds from when a music bed was analyzed. Export only when is true. If is unavailable, use the separate + + sequence above.

Motion Graphics Quality Bar

• Author storyboard-first: build and verify the static layout of every shot (Phase 1, via render_storyboard + evaluate_edit_quality(staticLayout:true)) before adding effects (Phase 2) or motion (Phase 3). A storyboard that does not read clearly will not improve by animating it.
• Use at least three timing phases: reveal, development, and resolution. Avoid a single continuous drift.
• After Phase 3 motion authoring, verify adjacent cuts with render_storyboard(subdivisionLevel:1) and raise to 2 for suspicious gaps on multi-shot types. In-between frames must show bridge motion, transition consistency, or recorded hard-cut intent, and cutEyeTrace must not exceed the budget without a planned bridge or hard-cut reason. For logo-intro or any continuous single-shot piece, pass explicit timeSeconds anchors and inspect the subdivided frames as a motion arc instead of a cut-continuity pass.
• Build fast tempo through contrast between quick accents and held readability beats. Do not make every layer move at the same speed.
• Avoid motion monotony: do not leave most keyframe transitions linear, and do not start every animated element at the same time with the same duration and direction.
• For 120-140 BPM briefs, work from a beat grid instead of the vague word "fast". At 130 BPM, 1 beat is about 462 ms, 2 beats about 923 ms, and 4 beats about 1.85 s. Plan enough foreground element boundaries and keyframes for the piece to read as fast in tempoRhythm metrics.
• Keep normal foreground beats near 2-4 beats. Longer holds are acceptable only for named background texture, ambient support, or a deliberate final resolve; add visible foreground events when readability requires a longer text hold. Background-only drift does not satisfy a fast-tempo brief.
• Animate multiple property families across the piece, such as transform, opacity, brush/gradient, effect parameters, and text spacing. Do not rely only on X movement plus opacity.
• Move the camera, not just the elements. A piece whose viewpoint never moves — every shot a static composition with only element-level animation, swapped by cuts — reads as a slide deck. Use [role:camera-rig] DrawableGroup transforms for push-ins, pans, parallax, and whip-pan cut bridges per cameraPlan; an all-locked-off piece needs an explicit recorded brief reason.
• Keep ordinary timeline Elements to one EngineObject. Multiple objects in one Element are reserved for IFlowOperator chains such as DrawableGroup, DrawableDecorator, SoundGroup, or ; otherwise split each visual object into its own Element.

Originality Rules

• For creative briefs, build an original timeline with small staged apply_edit calls; do not use list_compositions, plan_composition, or empty-scene examples as the default output path. To bootstrap from a non-template original starting point, plan_original_scaffold returns a one-call seed-derived scaffold (background/headline/subtitle/decorative foreground) whose placeholder copy and structure you then rewrite for the brief — it is an original starting point, not a reusable template.
• Treat list_creative_directions output as raw inspiration only. Do not copy returned seed names as the final concept title, Element/Object names, layer order, or file basename.
• Use composition templates only when the user explicitly asks for a template, starter, quick draft, or named template style.
• When a template is explicitly requested, pick a specific returned template name from list_compositions; do not rely on an implicit first template selection.
• Treat examples as schema snippets or fallbacks. Adapt their structure to the brief instead of copying a full starter scene unchanged.
• Avoid overused no-context motifs such as orbit rings, radar sweeps, map/atlas labels, signal nodes, dashboard bars, and dark teal cyan/magenta neon unless the user asks for them.
• Cross-session variety is a hard requirement: the same brief should NOT keep producing the same video. Before locking a direction, compare it against recentToAvoid, pass the structural signature into derive_palette, and deliberately change the structural language (motion verbs, layout grid, palette family, type treatment, transition style) from recent runs; then record_creative_direction so the next run can diverge too.
• Pass quiet: true to apply_edit for large staged patches; the full echoed change set can exceed the response size limit, so keep individual patches small and use the compact summary while authoring.

Shot List Mapping

• Drive Element boundaries from the enumerated shotBreakdownPlan. One shot normally maps to one or more Element entries with explicit Start, Length, and ZIndex; each ordinary Element contains exactly one drawable/audio EngineObject.
• Use multiple Objects inside one Element only for explicit IFlowOperator flow chains such as DrawableGroup, DrawableDecorator, SoundGroup, or Scene3D; otherwise split compound visuals into separate Elements.
• A shot with a planned camera move maps to one [role:camera-rig] rig Element — either a portal rig (PortalObject.Count = N) pulling the shot's N contiguous content layers directly above it, or a nested DrawableGroup parenting the content as Children — with locked background plates as separate Elements below the rig, outside the portal's ZIndex range.
• Background plates should be lower ZIndex; titles, logos, and overlays should be higher.
• Prefer explicit durations over relying on media original duration unless the brief explicitly asks to preserve source timing.
• For repeated visual treatments, duplicate structure deliberately; do not rely on implied defaults when the brief gives concrete values.

Merge-Patch Rules

• Arrays of objects with Id are id-keyed. A bare id-less array merges/appends into the existing members; it does NOT replace them.
• Use { "Id": "...", "$delete": true } for removals.
• To wholesale-replace an id-keyed array in one patch (e.g. swap a FilterEffectGroup.Children chain instead of appending to it), make the FIRST element the sentinel { "$replace": true }; the following elements rebuild the array in order (omit Id to mint fresh, or reuse an Id to keep that child), and [{ "$replace": true }] alone clears it. Replacement elements cannot also carry $delete/$index/$after/$before. Keep the group's own Id so only its children change.
• Use $index, $after, or $before for ordering; do not combine ordering directives.
• Unknown Id means stale handle; call read_document again instead of guessing.
• Existing parent with new flow child example: { "Elements": [{ "Id": "<existing-flow-element-id>", "Objects": [{ "$type": "<discriminator-from-get_schema>", "Name": "new-flow-child" }] }] }. Use this only when the existing Element is an intentional IFlowOperator flow chain. Ordinary Elements should not receive a second Object.
• New Element example: { "Elements": [{ "$type": "[Beutl.ProjectSystem]:Element", "Name": "new-element", "Start": "00:00:00", "Length": "00:00:02", "Objects": [{ "$type": "<drawable-discriminator-from-get_schema>", "Name": "new-object" }] }] }. New Elements and Objects omit Id.
• New flow-operator Element (e.g. a [role:camera-rig] DrawableGroup): the Objects array must pair a PortalObject immediately before the flow operator — "Objects": [{ "$type": "[Beutl.ProjectSystem]:PortalObject", "Count": <N> }, { "$type": "<DrawableGroup-discriminator>", "Name": "[role:camera-rig] ...", "Children": [...] }]. A bare flow operator without the PortalObject is rejected. Count is an inclusive ZIndex span, not an element count: every active Element with ZIndex in rig+1..rig+Count is pulled into the operator (leave Children empty then; empty rows contribute nothing). pulls no timeline rows, so with the portal as the Element's first object the operator consumes only its nested ; set to explicitly discard earlier same-Element flow. Applies to all s: , , , . See (nested) and (timeline).

Progress Watchdog

• Keep notes.md granular enough for another observer to reconstruct the route: every apply, save, render, evaluate, export, validation failure, and route change gets an entry.
• During long patch authoring between tool calls, update notes.md before the three-minute mark with a heartbeat such as drafting stage N patch; next tool: apply_edit; if you cannot do that, stop and report a blocker.
• If no tool success, saved project artifact, render/export artifact, or notes update happens for about three minutes while editing, stop and report the blocker/status instead of silently continuing.
• If the user or coordinator asks for status, call read_operation_status when available and respond immediately with the current session/source, last successful stage, and blocker before continuing.

Safety Rules

• Keep values in documented ranges. If apply_edit reports coercion or rejection, adjust the request and retry the same small stage.
• Confirm destructive output overwrites only when the user explicitly asked for overwrite.
• Do not write outside BEUTL_WORKSPACE.