@machinal/mcp 0.0.0-stage → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (174) hide show
  1. package/README.md +366 -2
  2. package/bin/machinal-mcp.mjs +19 -0
  3. package/bin/machinal-stdio.mjs +14 -0
  4. package/package.json +47 -4
  5. package/skills/machinal-cinema/SKILL.md +18 -0
  6. package/skills/machinal-cinema/references/film-library/DIRECTOR.md +149 -0
  7. package/skills/machinal-cinema/references/film-library/LICENSE +21 -0
  8. package/skills/machinal-cinema/references/film-library/MY-STYLES.md +139 -0
  9. package/skills/machinal-cinema/references/film-library/README.md +13 -0
  10. package/skills/machinal-cinema/references/film-library/TECHNIQUE.md +162 -0
  11. package/skills/machinal-cinema/references/film-library/core/lib.js +44 -0
  12. package/skills/machinal-cinema/references/film-library/core/post/crt.js +144 -0
  13. package/skills/machinal-cinema/references/film-library/core/three/post.js +102 -0
  14. package/skills/machinal-cinema/references/film-library/manifest.json +394 -0
  15. package/skills/machinal-cinema/references/film-library/styleboard/catalog.json +1128 -0
  16. package/skills/machinal-cinema/references/film-library/styles/README.md +126 -0
  17. package/skills/machinal-cinema/references/film-library/styles/archive-lighttable/STYLE.md +107 -0
  18. package/skills/machinal-cinema/references/film-library/styles/art-deco/STYLE.md +110 -0
  19. package/skills/machinal-cinema/references/film-library/styles/ascii-crt/STYLE.md +113 -0
  20. package/skills/machinal-cinema/references/film-library/styles/backrooms/STYLE.md +123 -0
  21. package/skills/machinal-cinema/references/film-library/styles/blueprint/STYLE.md +118 -0
  22. package/skills/machinal-cinema/references/film-library/styles/brick-toy/STYLE.md +112 -0
  23. package/skills/machinal-cinema/references/film-library/styles/briefing-board/STYLE.md +120 -0
  24. package/skills/machinal-cinema/references/film-library/styles/caption-news/STYLE.md +135 -0
  25. package/skills/machinal-cinema/references/film-library/styles/cel-anime-80s/STYLE.md +117 -0
  26. package/skills/machinal-cinema/references/film-library/styles/chalkboard/STYLE.md +153 -0
  27. package/skills/machinal-cinema/references/film-library/styles/circuit-board/STYLE.md +149 -0
  28. package/skills/machinal-cinema/references/film-library/styles/city-symphony/STYLE.md +140 -0
  29. package/skills/machinal-cinema/references/film-library/styles/countdown/STYLE.md +130 -0
  30. package/skills/machinal-cinema/references/film-library/styles/crayon-book/STYLE.md +107 -0
  31. package/skills/machinal-cinema/references/film-library/styles/dark-keynote/STYLE.md +115 -0
  32. package/skills/machinal-cinema/references/film-library/styles/data-physical/STYLE.md +117 -0
  33. package/skills/machinal-cinema/references/film-library/styles/dataviz/STYLE.md +121 -0
  34. package/skills/machinal-cinema/references/film-library/styles/desktop-flythrough/STYLE.md +145 -0
  35. package/skills/machinal-cinema/references/film-library/styles/engraving/STYLE.md +121 -0
  36. package/skills/machinal-cinema/references/film-library/styles/game-show/STYLE.md +116 -0
  37. package/skills/machinal-cinema/references/film-library/styles/glass-product/STYLE.md +108 -0
  38. package/skills/machinal-cinema/references/film-library/styles/halftone-dossier/STYLE.md +120 -0
  39. package/skills/machinal-cinema/references/film-library/styles/hd-2d/STYLE.md +109 -0
  40. package/skills/machinal-cinema/references/film-library/styles/hologram-hud/STYLE.md +127 -0
  41. package/skills/machinal-cinema/references/film-library/styles/impasto/STYLE.md +122 -0
  42. package/skills/machinal-cinema/references/film-library/styles/ink-wash/STYLE.md +118 -0
  43. package/skills/machinal-cinema/references/film-library/styles/iso-infographic/STYLE.md +115 -0
  44. package/skills/machinal-cinema/references/film-library/styles/isometric-picture-book/STYLE.md +130 -0
  45. package/skills/machinal-cinema/references/film-library/styles/kino-montage/STYLE.md +149 -0
  46. package/skills/machinal-cinema/references/film-library/styles/lidar-survey/STYLE.md +116 -0
  47. package/skills/machinal-cinema/references/film-library/styles/living-screencast/STYLE.md +122 -0
  48. package/skills/machinal-cinema/references/film-library/styles/lowpoly-island/STYLE.md +110 -0
  49. package/skills/machinal-cinema/references/film-library/styles/memphis-diorama/STYLE.md +142 -0
  50. package/skills/machinal-cinema/references/film-library/styles/microgame/STYLE.md +120 -0
  51. package/skills/machinal-cinema/references/film-library/styles/microscope/STYLE.md +106 -0
  52. package/skills/machinal-cinema/references/film-library/styles/midcentury-toon/STYLE.md +122 -0
  53. package/skills/machinal-cinema/references/film-library/styles/news-package/STYLE.md +156 -0
  54. package/skills/machinal-cinema/references/film-library/styles/newsreel/STYLE.md +134 -0
  55. package/skills/machinal-cinema/references/film-library/styles/one-line/STYLE.md +112 -0
  56. package/skills/machinal-cinema/references/film-library/styles/paper-lantern/STYLE.md +120 -0
  57. package/skills/machinal-cinema/references/film-library/styles/paper-popup/STYLE.md +117 -0
  58. package/skills/machinal-cinema/references/film-library/styles/papercut-red/STYLE.md +108 -0
  59. package/skills/machinal-cinema/references/film-library/styles/pictogram-motion/STYLE.md +119 -0
  60. package/skills/machinal-cinema/references/film-library/styles/pixel-rpg/STYLE.md +115 -0
  61. package/skills/machinal-cinema/references/film-library/styles/printed-long-take/STYLE.md +141 -0
  62. package/skills/machinal-cinema/references/film-library/styles/risograph/STYLE.md +123 -0
  63. package/skills/machinal-cinema/references/film-library/styles/rubber-hose/STYLE.md +110 -0
  64. package/skills/machinal-cinema/references/film-library/styles/satellite-briefing/STYLE.md +114 -0
  65. package/skills/machinal-cinema/references/film-library/styles/scifi-toon/STYLE.md +119 -0
  66. package/skills/machinal-cinema/references/film-library/styles/shadow-puppet/STYLE.md +122 -0
  67. package/skills/machinal-cinema/references/film-library/styles/silent-film/STYLE.md +107 -0
  68. package/skills/machinal-cinema/references/film-library/styles/silkscreen-poster/STYLE.md +138 -0
  69. package/skills/machinal-cinema/references/film-library/styles/spy-titles/STYLE.md +114 -0
  70. package/skills/machinal-cinema/references/film-library/styles/stained-glass/STYLE.md +121 -0
  71. package/skills/machinal-cinema/references/film-library/styles/swiss-motion/STYLE.md +113 -0
  72. package/skills/machinal-cinema/references/film-library/styles/teardown/STYLE.md +125 -0
  73. package/skills/machinal-cinema/references/film-library/styles/telestrator/STYLE.md +135 -0
  74. package/skills/machinal-cinema/references/film-library/styles/tilt-shift/STYLE.md +105 -0
  75. package/skills/machinal-cinema/references/film-library/styles/transit-map/STYLE.md +194 -0
  76. package/skills/machinal-cinema/references/film-library/styles/ukiyoe/STYLE.md +110 -0
  77. package/skills/machinal-cinema/references/film-library/styles/urban-sketch/STYLE.md +124 -0
  78. package/skills/machinal-cinema/references/film-library/styles/visual-investigation/STYLE.md +138 -0
  79. package/skills/machinal-cinema/references/film-library/styles/watercolor/STYLE.md +111 -0
  80. package/skills/machinal-cinema/references/film-library/styles/white-model/STYLE.md +113 -0
  81. package/skills/machinal-cinema/references/film-library/styles/whiteboard/STYLE.md +116 -0
  82. package/skills/machinal-cinema/references/film-library/styles/woodcut/STYLE.md +120 -0
  83. package/skills/machinal-cinema/references/film-library/upstream-skill.md +13 -0
  84. package/skills/machinal-cinema/references/film-styles.json +1322 -0
  85. package/skills/machinal-cinema/references/film-techniques.json +107 -0
  86. package/skills/machinal-cinema/references/workflow.md +58 -0
  87. package/skills/machinal-credits/SKILL.md +24 -0
  88. package/skills/machinal-editing/SKILL.md +43 -0
  89. package/skills/machinal-editing/references/brief.md +98 -0
  90. package/skills/machinal-editing/references/effects.md +58 -0
  91. package/skills/machinal-editing/references/looks-motion.md +37 -0
  92. package/skills/machinal-editing/references/styles.json +15 -0
  93. package/skills/machinal-editing/references/styles.md +16 -0
  94. package/skills/machinal-editing/references/transitions.md +46 -0
  95. package/skills/machinal-editing/references/workflow.md +43 -0
  96. package/skills/machinal-media/SKILL.md +23 -0
  97. package/skills/machinal-media/references/workflow.md +160 -0
  98. package/skills/machinal-recipes/SKILL.md +32 -0
  99. package/skills/machinal-recipes/references/catalog.v1.json +10445 -0
  100. package/skills/machinal-recipes/references/commands.md +45 -0
  101. package/skills/machinal-recipes/references/example.edit.yaml +26 -0
  102. package/skills/machinal-recipes/references/examples/caption-audio.yaml +28 -0
  103. package/skills/machinal-recipes/references/examples/cinematic-sequence.yaml +21 -0
  104. package/skills/machinal-recipes/references/examples/client-scene.yaml +26 -0
  105. package/skills/machinal-recipes/references/examples/generated-media.yaml +25 -0
  106. package/skills/machinal-recipes/references/examples/modify-snapshot.yaml +22 -0
  107. package/skills/machinal-recipes/references/examples/montage-v3.yaml +28 -0
  108. package/skills/machinal-recipes/references/examples/narrated-documentary.yaml +112 -0
  109. package/skills/machinal-recipes/references/examples/narration-timing.yaml +43 -0
  110. package/skills/machinal-recipes/references/examples/scene-edit.yaml +19 -0
  111. package/skills/machinal-recipes/references/examples/scene-generated-image.yaml +36 -0
  112. package/skills/machinal-recipes/references/examples/scene-generation.yaml +35 -0
  113. package/skills/machinal-recipes/references/examples/scene-image-insert.yaml +41 -0
  114. package/skills/machinal-recipes/references/examples/scene-three-explainer.yaml +38 -0
  115. package/skills/machinal-recipes/references/examples/social-hook.yaml +26 -0
  116. package/skills/machinal-recipes/references/examples/tutorial-clean.yaml +19 -0
  117. package/skills/machinal-recipes/references/examples.md +28 -0
  118. package/skills/machinal-recipes/references/jobs-scenes.md +206 -0
  119. package/skills/machinal-recipes/references/text-audio.md +118 -0
  120. package/skills/machinal-recipes/references/yaml.md +72 -0
  121. package/skills/machinal-review/SKILL.md +18 -0
  122. package/skills/machinal-review/references/production.md +146 -0
  123. package/skills/machinal-scenes/SKILL.md +44 -0
  124. package/skills/machinal-scenes/references/authoring.md +97 -0
  125. package/skills/machinal-scenes/references/runtime.md +136 -0
  126. package/skills/machinal-scenes/references/scene-templates/blueprint-mechanism.svelte +62 -0
  127. package/skills/machinal-scenes/references/scene-templates/glitch-handoff.svelte +30 -0
  128. package/skills/machinal-scenes/references/scene-templates/image-reveal.svelte +33 -0
  129. package/skills/machinal-scenes/references/scene-templates/kinetic-type.svelte +38 -0
  130. package/skills/machinal-scenes/references/scene-templates/layered-parallax.svelte +31 -0
  131. package/skills/machinal-scenes/references/scene-templates/lens-assembly-3d.svelte +57 -0
  132. package/skills/machinal-scenes/references/scene-templates/paper-stage-3d.svelte +83 -0
  133. package/skills/machinal-scenes/references/scene-templates/signal-diagram.svelte +43 -0
  134. package/skills/machinal-scenes/references/scene-templates/swiss-grid-motion.svelte +54 -0
  135. package/skills/machinal-scenes/references/scene-templates.json +178 -0
  136. package/skills/machinal-scenes/references/scene-templates.md +50 -0
  137. package/skills/machinal-scenes/references/workflow.md +206 -0
  138. package/skills/machinal-support/SKILL.md +42 -0
  139. package/src/bridge.mjs +287 -0
  140. package/src/cli.mjs +157 -0
  141. package/src/configuration.mjs +148 -0
  142. package/src/connection.mjs +187 -0
  143. package/src/credential-store.mjs +61 -0
  144. package/src/credits.mjs +86 -0
  145. package/src/docker.mjs +93 -0
  146. package/src/download.mjs +90 -0
  147. package/src/endpoints.mjs +3 -0
  148. package/src/errors.mjs +9 -0
  149. package/src/formats.mjs +140 -0
  150. package/src/keys.mjs +127 -0
  151. package/src/launch.mjs +29 -0
  152. package/src/local-setup.mjs +109 -0
  153. package/src/opencode-auth.mjs +246 -0
  154. package/src/opencode-checkpoints.mjs +90 -0
  155. package/src/opencode-configuration.mjs +53 -0
  156. package/src/opencode-media.mjs +139 -0
  157. package/src/opencode-plugin/index.mjs +7 -0
  158. package/src/opencode-plugin/package.json +5 -0
  159. package/src/opencode-recipes.mjs +130 -0
  160. package/src/opencode-routing.mjs +154 -0
  161. package/src/opencode-tools.mjs +30 -0
  162. package/src/opencode-workflow.mjs +32 -0
  163. package/src/presentation.mjs +31 -0
  164. package/src/prompts.mjs +32 -0
  165. package/src/reference-files.json +127 -0
  166. package/src/runtime.mjs +51 -0
  167. package/src/setup-options.mjs +69 -0
  168. package/src/setup-stdio.mjs +116 -0
  169. package/src/setup.mjs +173 -0
  170. package/src/skills.mjs +68 -0
  171. package/src/transfer-http.mjs +109 -0
  172. package/src/version.mjs +3 -0
  173. package/src/windows-key-prompt.mjs +37 -0
  174. package/src/windows-key-prompt.ps1 +77 -0
@@ -0,0 +1,206 @@
1
+ # Generation actions and scene direction
2
+
3
+ For MCP use **current-client scene authoring**: read `get_editing_reference(topic=scene-authoring)`, write Svelte with the AI already connected in the client, and call `compile_scene`. Client-authored CODE and source compilation have no server AI generation fee. Server scene frame rendering and final video encoding ARE billed at the configured render tariff, alongside approved images, speech and captions/transcription. A saved live source is not an encoded scene video. Call `get_credits` and obtain spending/source approval before server rendering or provider actions. Catalog support does not prove runtime/provider health.
4
+
5
+ The `scene.generate`/`scene.edit` job contracts and examples below document the shared **site/server-model compatibility** path, not the current MCP submission path. MCP rejects pending server scene jobs without fallback; reuse materialized results or place the asset returned by `compile_scene` in ordinary video tracks. See example `client-scene`. Source edits use `get_scene_source` then `compile_scene(sourceFile=...)`, preserving attachments. The current client repairs diagnostics without a server model. Server video/scene rendering still requires explicit authorization to use sources and spend credits.
6
+
7
+ ## Plan animated scenes proactively
8
+
9
+ Use `get_editing_reference(topic=production)` for the director/builder/critic workflow: define observable success in a production contract, critique it before writing source, then compare the implementation with `compile_recipe.editorialReview` before final rendering. This changes the harness, not scene-engine. Subject specificity and meaningful independent action are quality criteria, not a quota of shapes/effects. Keep scene-internal choreography distinct from recipe-level transitions and do not mistake compile/layout success for visual approval.
10
+
11
+ Before choosing a visual medium for a new video, read `get_editing_reference(topic=brief)` and resolve missing type, duration, aspect/output resolution, style/materials and audio choices with the user. Use the host's native question tool (OpenCode: `question`) with one `questions` array, not a numbered chat questionnaire; use an unnumbered fallback only if no interactive tool exists. In that form, recommend 1–2 relevant options such as an existing photo, a newly generated image, an animated scene or an image inside a scene, and explain the benefit. After the user answers, summarize the direction briefly and proceed immediately with the authorized work in the same turn, without a separate plan confirmation. Include known permissions as separate explicit questions in the same form where possible; never infer consent from a cancelled form or a creative preference. Respect already-specified choices and “you decide” delegation; do not ask the same questions for each beat. Do not automatically add production labels to scenes/captions or repeat them in chat. Keep generated media truthful and agree once on any requested or specifically required disclosure.
12
+
13
+ The MCP creates the same **animated Svelte components** as the editor. The host agent writes both the art direction and the actual Svelte source, sends it through `compile_scene`, and receives a pinned live `.scene.json` asset. Server export materializes it through scene-engine without another scene-model call. It is not an alias for image generation. `component` is a compile_scene tool field, not an inline recipe field.
14
+
15
+ When planning a video, evaluate **footage, still image, ordinary text and animated scene** per meaningful beat, without waiting for the user to explicitly request a scene. Make a compact beat sheet: timeline start/duration, message, visual choice, source/attachment and why motion helps. Look for:
16
+
17
+ - A process or cause/effect explanation: independently moving objects, arrows and successive states.
18
+ - A product/image reveal: use an actual uploaded image inside an animated layout, with independent labels or objects rather than baking everything into a still.
19
+ - A comparison, relationship, journey or supplied numeric progression: motion should explain the change, not manufacture data.
20
+ - An illustrative cutaway that makes narration clearer, with a readable hold and a deliberate return to footage.
21
+
22
+ Use the supplied script/copy, verified narration/cue times or sources actually inspected with approval. Metadata alone is not visual inspection and the reference tool does not watch/transcribe a video. If content/timings are unknown, ask for the relevant content or obtain it with the client's available approved inspection tools; mark proposed beat times as provisional. Never invent what happens at a source timestamp.
23
+
24
+ A pan/zoom over a still moves the entire image; it does not animate separate objects or embed a real image in an independently changing layout. Write Svelte in the current client and use `compile_scene` for those needs instead of defaulting every visual to `image.generate`. Do not silently replace requested animation with a slideshow. Reuse existing footage/text when equally effective, preserve footage-only/no-generation requests, and never impose a scene quota or generate images merely to demonstrate a capability. An unavailable compiler requires an explanation and user agreement before substituting another medium, never a server-model fallback.
25
+
26
+ For each selected scene, specify purpose, exact supplied copy, objects and hierarchy, real image IDs, palette, layout/safe areas and **scene-local choreography**: which object moves, direction/path, entrance time, reveal/change, readable hold and exit. Distinguish scene-local prompt times from the placement's global timeline time. Tie motion to a real communication need, avoid wall-clock animation and request frame-derived Svelte scene-runtime animation. For 3D, describe procedural geometry/camera in the prompt rather than inventing DSL fields. The backend, not the MCP client, owns compilation and sandbox execution.
27
+
28
+ Do not compress the scene brief to 'cinematic CSS', a generic heading or the documentary title. Name the visible subject and action, foreground/midground/background, material/light treatment, palette, scale, exact copy and what changes over the scene. A rich scene is a coherent piece of visual storytelling, not a count of shapes or effects; respect a deliberately minimal brief. For a spatial subject or an explicit Three.js request use `visualMode: 3d` and describe genuine meshes, lighting, camera target/path and deterministic mesh action. CSS perspective and a copied rotating demo primitive are not substitutes. For complex illustrative subjects, attach approved images and animate the subject, supporting diagram and labels independently rather than using a text-only card.
29
+
30
+ Visibility is part of the brief: keep the main subject legible during the central hold and most of the shot, not permanently at opacity 0, behind a backdrop, clipped offscreen or outside a Three.js camera. Specify separate reveal/hold/exit timing and sane contrast. Repairs preserve the artwork, motion and attachments rather than deleting complexity to pass compilation. No AI-production label, disclaimer or watermark belongs on screen: do not add 'AI illustration', 'AI-generated', 'Ilustrație AI', 'Generat cu AI' or 'Narațiune sintetică' to scene text, image prompts, CSS/SVG/canvas or textures. Explanations/provenance stay outside the video. Subject copy genuinely about artificial intelligence is different from an unsolicited production notice.
31
+
32
+ For example, a proposed 16-second edit could retain footage at 0–4s, insert a six-second animated explanation at 4–10s, and return to footage at 10–16s. A six-second scene brief can introduce a real image at local 0–1s, move objects/reveal labels at 1–3s, hold at 3–5s and settle at 5–6s. These are illustrative planning times, not observations about the user's media. Fetch `get_editing_reference(topic: examples, id: scene-image-insert)` for the complete compiler-tested YAML, including real-field image attachments and placements.
33
+
34
+ Fetch `scene-generation` for a more detailed portrait SVG storyboard, or `scene-three-explainer` for a complete procedural Three.js mechanism brief with staged assembly, linked mesh action, a camera orbit and stable final hold. They are synthetic pending-generation examples, not generated media or promises of visual quality; reading/compiling them does not call providers or authorize spending.
35
+
36
+ ## Complex scene assets: images and transparency by default
37
+
38
+ When a character, animal, plant, realistic product, detailed object, texture or illustration would not read well as procedural SVG/CSS, **default to an image-backed animated scene**. Reuse an approved suitable image first; otherwise plan `image.generate` within approved generation/spending scope, without waiting for an explicit image request. Do not force intricate subjects into fragile shape stacks or replace them with generic headings. Keep SVG/CSS for simple diagrams and genuine SceneThree geometry for spatial action. Images complement independent motion, not a slideshow replacement. Explicit no-generation, footage-only and `imagePolicy: procedural-only` choices override this default.
39
+
40
+ ### Visual coverage across the video
41
+
42
+ Make the same choice when SVG/CSS would be **overly simplistic**, not just technically difficult. A history/biography mini-documentary needs subject-specific contextual views, not one reused portrait plus text, lines and nodes. Cover relevant people, geographic context, environments and period-grounded illustrative scenes using verified narration/copy; do not invent historical events or present generated images as archival evidence. Simple, geographically accurate map diagrams remain useful alongside illustrations.
43
+
44
+ Keep a compact image-coverage list with the measured beat, narrative purpose, suitable approved existing asset or proposed new image, and destination scene. For example, a biography may need a portrait, a place-setting view, an illustrative historical environment and a relevant later-life context. These are coverage roles, not invented facts or a compulsory shot list. Reframing/recoloring one portrait does not add a distinct contextual view.
45
+
46
+ **5–10 distinct images per video can be appropriate**, neither a quota nor a cap. The **four-image attachment limit is per scene, not per video**: distribute images across `compile_scene` calls or ordinary image clips according to the approved presentation. Reuse suitable successful images, but do not collapse distinct narrative contexts into a simplistic infographic solely to make the video cheap. Respect the approved budget and generation scope; if needed coverage exceeds permission or a hard spending cap, explain the tradeoff and ask rather than silently downgrading or overspending. Minimal/no-generation/procedural-only briefs still win. This visual-source decision does not authorize changing narration, captions, pacing or transitions.
47
+
48
+ ### Select the tool for the missing capability
49
+
50
+ `image.generate` is a **YAML job type, not an MCP tool**. The current client selects tools; the free `suggest_tools` catalog and optional host routing only assist selection, never execute actions or grant consent.
51
+
52
+ | Need/current stage | Actual MCP tool and boundary |
53
+ | --- | --- |
54
+ | Decide whether SVG/CSS is too complex or overly simplistic | `get_editing_reference(topic=scenes)` and `get_capabilities`; plan meaningful image coverage within approval. |
55
+ | Create missing artwork | `generate_assets` with approved `image.generate` jobs in validated YAML, after the separate timing-first checkpoint when narrated. Do not rerun successful speech/captions. |
56
+ | Materialize and reuse generated images | `wait_for_job` until completed, then `get_job_result` for actual filenames, assets and resolved recipe; no guessed filenames or regeneration. |
57
+ | Compose/animate approved images | `compile_scene` with client-authored Svelte and up to four images per scene; compilation does not generate artwork or render a video. |
58
+ | Inspect an approved scene's actual frames | `get_scene_source` for its version, then bounded `inspect_scene`; not final-composition or audio inspection. |
59
+ | Export the resolved, reviewed composition | `validate_recipe`, `compile_recipe`, then approved paid `render_video`; not a way to discover missing artwork or timing. |
60
+
61
+ Choose only the relevant stage and prerequisites, not every tool on each beat. Keep existing successful assets and normal media/spending approvals; a routing recommendation is not authorization.
62
+
63
+ For **isolated foreground subjects, sprites, cutouts and independently composited layers**, default to **`background: transparent`** on `image.generate`. Use **`openai/gpt-image-2.5-sunburst`** unless the user selected another compatible model; **`openai/gpt-image-2.5-flare`** also supports transparent backgrounds. Respect explicit model choices; do not silently substitute an incompatible model. Request a complete isolated subject, clean edges and real alpha, with no painted checkerboard, solid backdrop, frame or baked-in labels. Use `background: opaque` for full-frame environments and images whose background is part of the story; not every image should be transparent.
64
+
65
+ Example image job fragment (not a complete recipe or permission to spend):
66
+
67
+ ```yaml
68
+ before:
69
+ - id: foreground-subject
70
+ type: image.generate
71
+ model: openai/gpt-image-2.5-sunburst
72
+ aspect: '1:1'
73
+ background: transparent
74
+ prompt: >-
75
+ A complete oak sapling with detailed leaves and exposed roots,
76
+ isolated on a transparent background with real alpha and clean edges.
77
+ No painted checkerboard, solid backdrop, frame, text or labels.
78
+ ```
79
+
80
+ After the timing-first checkpoint when applicable, generate the approved image, wait for completion and attach its actual returned filename to `compile_scene.images`. The image job field is `background`, not `transparent: true`; `compile_scene.transparent` controls the scene canvas separately and does not remove an opaque image background. Preserve PNG/WebP alpha; do not flatten onto a solid background or convert cutouts to JPEG. Use separate approved images for independently moving subjects/layers, within the four-image attachment limit; moving one bitmap does not articulate its internal parts or reconstruct 3D.
81
+
82
+ A transparency request alone does not verify returned alpha. Do not claim verification from a filename, metadata or a JPEG diagnostic thumbnail. If alpha is missing or unverified, report that limitation; do not automatically regenerate a paid asset or install local background-removal pipelines. Reuse existing scope approvals rather than reconfirming each covered asset; this default does not grant media access, paid generation or rendering permission.
83
+
84
+ ## Integrate images; raise the visual ambition
85
+
86
+ Image sourcing and presentation are separate choices. “Use/find/generate images for this video” is not an instruction to exclude scenes. If presentation is undecided, ask once in the native brief form whether approved images may be integrated into animated Svelte scenes, optionally with genuine Three.js where it adds spatial meaning. Recommend a concrete subject-specific treatment versus a photo-only montage; explain the additional scene-frame rendering cost separately from image generation and final encoding. Reuse an answered choice or “you decide” delegation, preserve explicit still-only/no-scenes/no-generation choices, and do not expand standalone image searches into video work. Image-search/download/use still requires the appropriate permissions and actually available tools; do not invent a search provider or rights to a found image.
87
+
88
+ Treat a selected image as a scene attachment and visual anchor, not a reason to abandon animation. Preserve its proportions, identity and key details. Compose independently animated frames, labels, diagram elements or other approved images around it, and match palette, framing and movement to the neighboring footage/scenes. Moving a full flat image is not internal subject animation or recovered 3D geometry. Do not claim parallax-separated subjects, hidden surfaces or a realistic 3D reconstruction without actual layers/assets. New generated layers or artwork need their own approval.
89
+
90
+ For expressive/bold briefs, design a **signature visual action** at a meaningful beat: what the viewer sees change, why it expresses this subject, how the action builds, and where it settles into a readable hold. This is a design criterion, not a scene quota. Avoid a sequence of identical centered cards, headings and zooms. Use stronger subject-specific staging, depth, lighting, asymmetric compositions and contrasting motion speeds rather than covering generic content in particles, glow or camera shake. Minimal briefs remain deliberately quiet.
91
+
92
+ Choose the medium by what actually moves:
93
+
94
+ - **2D/Svelte:** editorial image collage, framed image reveals, independently moving labels, relationship diagrams and comparison layouts. Useful depth cues do not require 3D.
95
+ - **Three.js/SceneThree:** spatial assembly/disassembly, a mechanical relationship, scale/depth comparison, or a camera move that reveals genuinely different geometry. Proactively recommend it when helpful; do not wait for the user to name Three.js. Use actual meshes/materials/lights, a framed camera target/path and deterministic object action, not CSS perspective, a rotating cube or a flat photo mislabeled 3D. Check sceneMode and the live runtime first; do not promise unsupported image textures or postprocessing. For mixed image/3D scenes, approved images may remain a supported 2D layout alongside genuine spatial geometry.
96
+
97
+ These are illustrative storyboards, not preset IDs or permission to render:
98
+
99
+ | Subject/intent | Image integration and signature action | Continuity/hold |
100
+ | --- | --- | --- |
101
+ | Biography/history from verified material | Use distinct approved portrait, geographic/environmental and period-grounded illustrative images for the relevant measured beats; animate image layers and short factual labels independently. Document cards can support the story, not substitute for all historical context. | Match neighboring frames/palette; preserve readable viewing holds. No invented depth inside a portrait or generated image presented as archival evidence. |
102
+ | Product/process | A genuine 3D mechanism separates into functional parts, then linked parts engage; an approved product image and independently revealed labels provide context. | Camera moves to reveal the relationship, then holds the working assembly. Do not invent product internals or capabilities; use an explicitly schematic mechanism when appropriate. |
103
+ | Comparison/explanation | Two approved images enter separate aligned panels; relevant diagram elements move between supplied states while a restrained focus accent directs attention. | Match scale and alignment; hold the result and carry a panel edge/direction into the next shot. No invented data. |
104
+
105
+ Add to the beat sheet the signature action, independent moving elements, 2D/3D rationale, entrance/action/hold/exit cues and adjacent-shot continuity. For narrated work, finalize all times from the measured timing checkpoint, not these illustrative descriptions. Write the complete Svelte source in the current client and compile it; none of these planning labels are YAML fields.
106
+
107
+ Coordinate an **effect score** with topic `effects`: selected clip/track accents, exact catalog IDs/params, supported ramps and junction timing. Implement them on the real resolved tracks instead of stopping at a prose plan or removing them during staging. Check for duplicate grading/texture, label blur and excessive motion; scene lighting is not an excuse to indiscriminately stack a global glow. Do not add unapproved image/provider actions or paid preview/re-render loops to increase spectacle.
108
+
109
+ Before export, review source choreography and available Directional diagnostics for reveal, action, central hold and exit: is the actual subject visible, does something meaningful change independently, is there contrast in pace, and do neighboring shots feel related? Inspect representative frames/output only with deployed tools and within approved processing/access/spending scope. Compilation/layout success does not prove visual ambition or quality; state when visual inspection is unavailable rather than claiming a verified spectacular result. Repairs preserve artwork, motion and approved attachments; never downgrade to a static title card merely to pass checks.
110
+
111
+ ## Legacy site/server-model job contracts
112
+
113
+ Read `get_workflow_preferences` and `get_editing_reference(topic: scene-runtime)` before choosing a treatment. The runtime contract supplies exact embedded font families, image bindings, imports and a genuine Three.js starter. For MCP, `sceneMode: 3d` becomes `visualMode: 3d` on compile_scene, and the current client writes the component. The following job-specific prompt fields describe legacy site generation, not pending MCP scene work.
114
+
115
+ For complex characters, animals, realistic objects, textures and artwork, prefer actual images over fragile stacks of CSS/SVG shapes. Keep the image visible and animate its wrapper and other objects independently. Obtain spending approval for a new image; current-client scene code and compilation are free. Preserve `imagePolicy: procedural-only`, explicit no-generation and footage-only briefs.
116
+
117
+ All jobs use a unique `id` and exact `type`. Prefer `before` + `placements` + `after` for new staged recipes. Legacy `jobs` remains supported, with `trackId` referencing an already declared track and explicit `start`/`duration` when placing results. `start: 0` on a legacy job with an occupied track is treated as append-to-track; staged placements make zero unambiguous.
118
+
119
+ | Type | Stage | Inputs and results |
120
+ | --- | --- | --- |
121
+ | `image.generate` | before or legacy jobs | Required `prompt`; optional configured `model`, `aspect`, `background`, `imageStyle`. Use `background: transparent` for isolated composited subjects with GPT Image 2.5 Sunburst/Flare; use `opaque` when the background belongs in the image. `imageStyle` is appended prompt text, not a catalog look or nested CSS. The orchestration passes `background` through to the configured image service; a request is not verification of returned alpha. Returns `resultAssetId`. |
122
+ | `speech.generate` | before or legacy jobs | Required `text` (legacy `input` fallback); `language: ro`/`en` for the spoken language; optional `instructions`, configured `model`, `voice`, `referenceName`, `referenceTranscript`. A reference is an uploaded project filename; never fabricate a speaker identity/consent or provider voice ID. Returned speech duration is measured, not predicted. |
123
+ | `scene.generate` | before or legacy jobs | Required `prompt`; duration 1–60s, or omit it with `narrationJob` to use the measured speech duration. Optional `text` is exact on-screen copy; `narrationJob` references an earlier before speech job, and `narrationFrom` selects source-audio seconds. Optional `aspect`, dimensions, `fps`, model, images and visualMode. Creates one live animated Svelte scene with relevant content, not an unrelated title card. |
124
+ | `scene.edit` | before or legacy jobs | Same duration/dimensions limits; required `assetId` of an existing server `.scene.json` video asset and edit `prompt`. Preserve existing media/narration. Do not pass new `images` on an edit. |
125
+ | `captions.generate` | after or legacy jobs | Real audio-bearing timeline, optional `assetId`, `language`, `maxWords`, caption TextStyle `style`; returns actual `resultTextIds` and text items. Read topic `text`. |
126
+ | `analysis.transcribe` | legacy jobs only | Recognized requirement type for transcription; do not promise that the existing orchestration materializes it into caption text automatically. Prefer `captions.generate` for automatic on-video captions. |
127
+
128
+ `resultAssetId`, `resultAudioAssetId`, `audioStart`, `resultTextIds` are returned/materialized state, not placeholders to invent to bypass a requirement. Preserve them together with actual assets/texts to avoid regeneration. `assetId` on a caption job selects source audio; on a scene edit it selects the existing live scene. They do not have the same meaning as `resultAssetId`.
129
+
130
+ ## Placements and materialization
131
+
132
+ ```yaml
133
+ before:
134
+ - id: opener
135
+ type: scene.generate
136
+ duration: 6s
137
+ aspect: portrait
138
+ fps: 30
139
+ prompt: >-
140
+ A clean editorial infographic, portrait framing. Show the user-supplied
141
+ three-step process as a vertical progression. Use restrained cobalt
142
+ and white, readable type, a short entrance, a stable reading hold,
143
+ and a quiet exit. Do not invent statistics or include external media.
144
+ placements:
145
+ - job: opener
146
+ track: {type: video, role: opener}
147
+ start: 0s
148
+ duration: 6s
149
+ ```
150
+
151
+ Generated image/scene results go on a `video` role; speech on `audio`. The compiler creates `recipe/<type>/<role>` tracks and deterministic placement clip IDs. Images require at least 100ms explicit duration. For audio/video, omitted duration uses the job duration or actual asset duration; never exceed the generated asset duration. A placement `transform` only applies to video tracks. Source scene narration returned by the backend is linked automatically; do not duplicate it with another voice track.
152
+
153
+ Before generation, compilation returns requirements, **not a renderable composition**. Staged preflight can use an empty base timeline, but rules/effects/commands that target nonexistent future clips can still fail before provider calls. Safest workflow: generate only after approval; retain resolved assets/document; then add the desired look/transitions/effects/text to real tracks/IDs, validate and compile again before rendering. Never silently discard the intended final treatment to make the pending stage pass.
154
+
155
+ ## Timing-first narration, captions and visuals
156
+
157
+ For narrated work use **separate submissions**, not a complete voice/image/scene/caption recipe submitted at once. Every `before` job runs before `after` captions in the same submission. Putting speech first in `before` therefore does **not** make measured captions available to subsequent visual jobs. Do not move captions into `before` or invent a dependency/stage field.
158
+
159
+ 1. **Timing pass:** after checking credits and obtaining source-use/spending approval, call `generate_assets` with only the requested speech, its audio placement and requested `after: captions.generate`. No `image.generate`, `scene.generate` or `scene.edit` jobs belong in this first submission. Example `narration-timing` is an audio-only timing recipe, not a final video.
160
+ 2. **Timing checkpoint:** use `wait_for_job` until `status=completed`, then read `get_job_result` once. Retain the resolved `recipeYaml`, measured audio asset duration, caption `texts`, cue-local `words`, `resultAssetId` and `resultTextIds`. If timing fails or is missing, stop dependent visuals and recover successful assets; never invent word times or start everything over.
161
+ 3. **Visual pass:** only now finalize the beat sheet and image/2D/Three.js scene briefs. Derive global image holds, scene start/duration and local entrance/reveal/hold/exit times from the measured speech/caption boundaries. Caption word times are relative to their text item's start; `narrationFrom` is relative to source audio, while placements are global timeline times. Include gaps and narration placement offsets. Keep each image/prompt tied to its actual spoken excerpt, not just the video title.
162
+ 4. Add approved visual jobs to the **returned resolved composition**, preserving audio tracks/assets, speech jobs, caption jobs and actual texts. Normalization may move materialized `before`/`after` jobs into `jobs`; do not recreate unmaterialized copies. `sourceJobId` replays an **unchanged** recipe, so adding visuals requires the edited `composition` YAML instead. Use a new stable idempotency key for this intentionally different operation. Example `narrated-documentary` demonstrates the second pass using explicitly synthetic resolved timing fixtures; never copy those fixtures into a real project.
163
+ 5. Generate approved images before scenes that attach them, resolve/validate the completed visual pass, and then `render_video`. Preserve the same narration and captions rather than paying for them again. Retiming/replacing audio invalidates its old captions and dependent visual timings: resolve that change before generating/rendering dependent work. An already-approved workflow need not ask again for each covered stage; new provider actions or changed scope require approval.
164
+
165
+ ### Narration overruns an approximate target: extend visuals, not speech work
166
+
167
+ A requested or AI-proposed runtime is approximate unless the user explicitly sets a hard duration cap. A planned 30-second video with 38–40 seconds of successful narration is valid: keep the successful audio/captions and extend the video to the measured narration end, including its placement offset. Do not regenerate, truncate or speed up narration solely to match the estimate; do not rewrite its script and pay for a second voice or rerun successful captions/images.
168
+
169
+ Lengthen suitable scene holds/actions or add relevant client-authored scenes within the approved visual scope. Recompile a scene whose source duration must grow; merely extending a placement beyond the pinned asset duration is invalid. Preserve attachments/artwork, keep each scene at most 60 seconds, update placements and transition overlaps, and validate continuous picture coverage through the full narration without a blank tail or audio cutoff. Keep actual caption words/timings unchanged when audio placement is unchanged. State the adjusted runtime and continue without reconfirmation within existing permissions. Resolve an explicit hard duration cap or spending limit before replacing paid narration or exceeding approval; a flexible runtime overrun alone is not failure or a reason to restart production.
170
+
171
+ Existing approved speech/captions can satisfy the timing checkpoint without regeneration. If TTS was not requested, use the approved existing audio and generate only requested captions. If captions were not requested, do not add paid transcription or on-screen subtitles unasked: use measured speech duration for whole-section scenes, and do not claim word-accurate timing. If neither narration nor captions is needed, skip the timing pass. Music-only or footage-only edits retain their existing workflow.
172
+
173
+ Bind `scene.generate.narrationJob` to an earlier `before` speech job or a materialized speech job retained in `jobs` from the timing pass. The backend gives the scene generator the actual spoken text and measured duration, without generating a duplicate voice track. A whole narration longer than 60 seconds must be split into meaningful sections. For a window of a longer narration, set `narrationFrom` plus `duration` only after captions with real word times have been materialized; missing cues fail instead of inventing a transcript. Exact scene-local cue times and narration content are passed to the component generator.
174
+
175
+ ## Scene layout checks and recovery
176
+
177
+ New scene generation and edits are checked in a real browser at multiple representative frames before they are accepted. Off-canvas/clipped text, illegible font sizes, colliding text blocks, text in the reserved caption band, recognized visible AI-production notices and no detectable foreground across the sampled frames produce repair diagnostics. Canvas/WebGL sampling detects nonblank artwork, not its meaning. The existing single repair attempt is bounded; persistent failures are reported, not rendered as if successful. When the timeline contains captions, reserve its bottom 24% for them. This is geometry/visibility validation, not OCR or a guarantee that an arbitrary image is semantically correct or aesthetically successful.
178
+
179
+ After generation use `get_job_result` once for `recipeYaml`, or pass `sourceJobId` for unchanged continuation. Prefer `wait_for_job(timeoutSeconds:120)` to repeated progress lookups or local sleep loops; it ignores heartbeat revisions. Keep recipes as `.edit.yaml` and reuse resolved assets.
180
+
181
+ Compact job summaries may include `timing.remainingSeconds` (processing) or `timing.estimatedQueueSeconds` (before processing). Both are approximate, based on live progress or recent successful jobs, never a completion deadline or a cost quote. Missing timing means no supported estimate is available. Final cloud publication may take additional time; only `status: completed` authorizes delivery, never a progress percentage alone. The signed-in `/jobs` page can recover jobs and issue fresh S3 download links without another render.
182
+
183
+ `stage.scope` distinguishes scene capture from whole-job video, caption, audio, encoding and publication phases. Terminal jobs omit active stage/ETA fields, including stale values from older snapshots. `performance` persists wall-clock phase durations and observed cache hits/misses; `truncated` discloses a capped phase history. These metrics identify bottlenecks but do not prove a speedup. Historical timing samples can be restored from scoped completed-job performance after worker restart. `timing.sampleCount`, `remainingRangeSeconds` and `estimateUnavailableReason` explain uncertainty; weighted progress is never used as a time fraction. With no supported history, keep the estimate unavailable instead of inventing one.
184
+
185
+ ## Select a scene by communication need
186
+
187
+ - **Infographic/process:** explain a real relationship or sequence; specify hierarchy, truthful values, visual metaphor, entrance/hold/exit and readable labels. Good for tutorials, not unsupported statistics.
188
+ - **Product reveal:** use supplied product/brand images visibly, preserve logos/aspect/alpha, specify an intentional reveal and a stable benefit/call-to-action hold. Do not replace real product evidence with invented claims.
189
+ - **Comparison/split layout:** two aligned panels and consistent scales, synchronized changes, user-provided labels/data; do not claim a new YAML `splitScreen` or `scenePreset` field.
190
+ - **Map/journey/timeline:** use verified locations/events and a coherent path; no external map URLs or fabricated coordinates. Schematic illustration is acceptable when explicitly described as such.
191
+ - **Diagram/3D explainer:** use `visualMode: 3d` for genuine SceneThree geometry, lighting and deterministic camera/update; auto/2d are also supported. Read topic `scene-runtime`, rather than guessing a Three.js API. scene.edit preserves its existing mode. The DSL does **not** expose `transparent`, `videos`, `audioFile` or arbitrary component source. `text` is supported for exact on-screen copy on scene.generate; narration is a separate narrationJob binding.
192
+ - **Quiet title/quote:** prefer normal `texts` and existing footage if that communicates the same idea without paid scene generation.
193
+
194
+ These are **scene briefs**, not registered preset IDs. There is no document-level `scenes` array in this DSL; place `scene.generate`/`scene.edit` jobs correctly.
195
+
196
+ ## Images, runtime and namespace limits
197
+
198
+ Scene `images` accepts at most four uploaded JPEG/PNG/WebP sources, with unique IDs `image_1` through `image_4`, `file`, human-readable `name`, optional `description` (up to 600 characters). Each input must be at most 5 MiB/40 million pixels. Metadata is not visual inspection. Scenes preserve real attachments; don't invent URLs or binary/base64 YAML payloads.
199
+
200
+ Describe how each attachment is used and animated: for example, keep `image_1` inside a product card while labels and schematic objects enter independently. Preserve the original image's proportions, existing alpha and truthful branding. Transparent image generation uses the existing `image.generate.background: transparent` field, not a new image-job `transparent` field or the scene-canvas setting. The uploaded image is supplied as a component prop by the backend, not fetched from an external URL. A scene can also be entirely procedural without an image-generation call.
201
+
202
+ For MCP asset preparation, a new image is the only paid generation stage: generate it first, wait for its actual project filename, then attach it with `file` to the free source compilation through compile_scene. Subsequent scene-frame rendering and final encoding remain billed. In the legacy site/server-model path there are two paid stages for generation: image.generate before scene.generate can attach `{id: image_1, job: artwork-job, name: Subject}`. That legacy `job` dependency must reference an earlier image.generate. It is not a compile_scene tool field. Read example `scene-generated-image` only as server-model compatibility guidance. Never put a guessed job ID into `file` or invent resultAssetId placeholders. Keep all resolved media for reuse.
203
+
204
+ On failure, inspect `result.recovery`: a resumable `{document, bindings, assets}` envelope retains successful prior outputs. Save it and resume missing stages after resolving the error; do not regenerate successful speech/images. Recovery does not grant unrelated media access or new spending permission.
205
+
206
+ The backend creates deterministic Svelte scene source using its existing renderer. Read `scene-runtime` for all embedded scene font families, supported image bindings and the exact SceneThree API; CSS family names are **not** recipe fontFamily IDs. SceneVideo look names are another namespace, not recipe look IDs or YAML job fields. Do not install libraries, access networks or introduce wall-clock animation as a workaround. The backend owns the component sandbox.
@@ -0,0 +1,118 @@
1
+ # Typography, captions and audio
2
+
3
+ Use topics `text` and `fonts` for exact deployed preset/font IDs. Text presets contain actual default style values, not just visual names. Text fields go directly on `texts[]`; there is no nested `texts[].style` object. A generation job's `style` is a separate caption-style contract.
4
+
5
+ ## Text and caption choices
6
+
7
+ `title`/`subtitle`/`lower-third` organize information; `hook-pop`/`social-hook` introduce a truthful short hook; `step-label`/`numeric-proof`/`callout` clarify steps or supported numbers; `quote`/`quote-pull` frame supplied quotations; `caption`/`clean-phrase`/`clean-outline` emphasize reading; `active-word`/`tiktok-pop`/`tiktok-box`/`tiktok-glow` are appropriate only with real timed words when using word highlighting. Branded options include `cobalt-rail`, `signal-block`, `electric-line`, `lime-label`. Read entries before assuming their colors, animations or caption requirements. Do not render the catalog preview/sample text as the user's copy.
8
+
9
+ Every item needs a unique `id`, explicit `text`, nonnegative `start`, positive `duration`, optional `preset`, optional `sourceClipId` and `words`. Preset sample `text`, `duration`, `start`, `words` are deliberately **not** supplied as real content/timings by materialization. Overridden fields are applied on top of preset values.
10
+
11
+ With a preset, positions scale from the 1920×1080 catalog design space unless explicitly provided. Explicit text `x/y` are **output design pixels**: landscape 1920×1080, portrait 1080×1920, classic 1440×1080, independent of encoded resolution. Use safe margins and place important portrait captions clear of bottom overlays; do not use clip position percentages as text coordinates.
12
+
13
+ `anchor` is the horizontal reference point for `x`: `left`, `center` (the compatible default), or `right`. `align` only aligns lines INSIDE the text box. To begin a title at x=150, use `x: 150`, `anchor: left`, `align: left`; align:left alone still positions the box around x. `y` remains the vertical center. Preview and export load identical embedded fonts before measuring and fit text inside the frame; never compensate by guessing negative positions or inflating font sizes. UTF-8 and extended Latin are supported, including **ă â î ș ț Ă Â Î Ș Ț**. Named catalog fonts use their real embedded files; OS-specific aliases use deterministic bundled equivalents.
14
+
15
+ ```yaml
16
+ texts:
17
+ - id: step-one
18
+ text: '01 / Prepare the ingredients'
19
+ start: 0s
20
+ duration: 3s
21
+ preset: step-label
22
+ anchor: left
23
+ align: left
24
+ x: 180
25
+ y: 260
26
+ color: '#15171b'
27
+ ```
28
+
29
+ Supported flattened style fields: `x`, `y`, `fontFamily`, `fontSize` (8–600), `fontWeight` (400 or 700), `italic`, `align` (left/center/right/justify), `color`, `strokeColor`, `strokeWidth`, `backgroundColor`, `backgroundOpacity`, `backgroundPadding`, `backgroundRadius`, `bannerStyle` (none/rail/block/underline), `accentColor`, `animation` (none/slide-left/slide-right/rise/pop/drop/bounce/shake/float), `animationDuration`, `opacity`, `rotation`, `isCaption`, `highlightMode` (none/word), `highlightColor`, `highlightBackgroundColor`, `highlightBackgroundOpacity`, `highlightAnimation` (none/pop/bounce/slide-up/glow). Colors are quoted six-digit hex; opacity fields are 0–1, padding/radius/stroke width 0–200. Use registered font IDs, not downloaded font URLs or CSS family strings.
30
+
31
+ `anchor` is also a flattened style field. Keep title labels separate from captions and scene text. Do not put multiple words in one `words[].text` entry while requesting word highlighting: one measured interval must identify one display token. Grouped phrases require phrase display, not invented per-word timing. Review sentence boundaries and avoid flashing isolated one-word cues.
32
+
33
+ For `highlightMode: word`, set `isCaption: true` and supply nonempty `words: [{text, start, end}]` with **cue-local** seconds: ordered, nonoverlapping, within the text item's duration, whose joined text matches the item's text. Do not invent these timings or pretend a title is a transcript. Manual supplied/verified timings are free to author; generating a transcript/captions through the provider is paid.
34
+
35
+ ## Caption generation
36
+
37
+ ### TikTok caption font
38
+
39
+ When the brief targets **TikTok** or requests **TikTok-style captions**, NEW captions must explicitly use **`fontFamily: montserrat` and `fontWeight: 700`** unless the user explicitly chooses another font. These are the actual font values in the deployed `tiktok-pop`, `tiktok-box` and `tiktok-glow` presets. Verify `get_editing_reference(topic=fonts,id=montserrat)` and the chosen text preset. Montserrat is the supported TikTok-style choice, **not official TikTok Sans**; do not invent a `tiktok`/`tiktok-sans` font ID or claim that an unavailable font is embedded.
40
+
41
+ Set both fields in `captions.generate.style` before the timing-first pass, as in the caption job below. For newly authored manual captions, set flattened `texts[].fontFamily` and `texts[].fontWeight`. A TikTok animation/preset name alone does not select the caption font: caption generation uses `style`, not `job.preset`. Keep animation/highlighting choices separate and require real word timings for word highlighting.
42
+
43
+ **Preserve existing caption fonts/configuration** unless the user explicitly requests a font change; merely changing the destination to TikTok does not authorize restyling successful captions or regenerating them. An explicit font change alters only the requested font fields, preserving text, grouping, IDs and measured timings. A generic portrait/social brief does not imply TikTok, and mentioning TikTok does not authorize adding unrequested captions.
44
+
45
+ ### Preserve existing captions
46
+
47
+ Treat existing YAML captions as **read-only unless the user explicitly requests a caption change**. Once captions exist, adding scenes, effects, transitions or final rendering is not permission to redesign them. Preserve complete caption entries, including:
48
+
49
+ - Exact `texts[].text` and `words[].text`: spaces, line breaks, punctuation, spelling and diacritics. Do not paraphrase, trim/collapse whitespace or reconstruct strings from joined words/a transcript.
50
+ - Cue grouping/order, `id`, `resultTextIds`, `sourceClipId`, `start`, `duration` and every word's cue-local `start`/`end`. Do not split/merge/reflow cues or invent new timings.
51
+ - Positions, `anchor`/`align`, fonts/sizes, colors, stroke/background, opacity and all animation/highlighting/effects values. Do not apply a different preset or reset explicit fields to defaults.
52
+
53
+ The renderer already handles font measurement, fitting, wrapping and collision avoidance. Do not simulate layout by rewriting caption text, manually spreading words across separate text items, inserting spaces, changing line breaks or moving/resizing captions. Adapt scene labels/visuals around the existing caption band, not the other way around; keep separate captions out of Svelte source.
54
+
55
+ Existing caption configuration takes precedence over style profiles and `captionMaxWords`. Four-word/two-line defaults apply only to **NEW caption generation**, never retroactively. Use `sourceJobId` for unchanged continuation. For visual edits, patch the resolved `recipeYaml` from `get_job_result` and compare complete caption entries and `resultTextIds` against that baseline before submission; undo unintended caption changes. A successful validation/compile does not prove preservation. Do not regenerate successful captions. This is an editing rule, not a new YAML lock flag.
56
+
57
+ The encoding repairs below are limited exceptions: deterministic reversible normalization or exact recovery from an intact source, never editorial/layout changes. If a real caption diagnostic requires other caption changes, report the specific blocker and ask first; do not silently “fix” an already configured layout.
58
+
59
+ ### AI recipe text integrity
60
+
61
+ Keep caption text **UTF-8** end to end, including local `.edit.yaml` reads/writes (explicit UTF-8 on Windows). Inspect both `texts[].text` and `words[].text` before rendering: correct Romanian diacritics must not become mojibake such as `ș` or `â`. The compiler repairs known reversible Romanian encoding damage and composes Unicode text; `compile_recipe` returns the normalized document. Keep corrected text and word spellings consistent, preserving measured timings, caption IDs and `resultTextIds`. Do not rewrite a successful transcript through a legacy code page.
62
+
63
+ `invalid_text_encoding` means invalid UTF-8 or lost characters (`U+FFFD`): restore exact spelling from an intact transcript or supplied script. Never guess lost letters or remove diacritics. Do not regenerate successful speech/captions or bake captions into scenes to hide encoding damage. If no intact source is available, report the blocker before paid rendering. Revalidate the repaired recipe.
64
+
65
+ For **NEW caption generation only**, read `get_workflow_preferences`: default to **four words per caption**, especially for **1080×1920 portrait**. Do not increase this without an editorial/user reason. Preview and export fit captions using actual font measurements into at most two lines in the safe area, preserving word timings. Do not manually split/reflow existing cues to enforce these defaults. Report a genuine fitting failure instead of changing existing captions without the user's request.
66
+
67
+ Before paid work check `get_capabilities().generation.textPreparation.configured`. With `SCENE_SERVICE_URL` configured, the server prepares text internally; avoid sending large rasterized preparedText through MCP. An unset service needs deployment configuration, not a style change. `preparedText` keys/images must come from the renderer, never be invented. Do not discard requested word highlighting just to fit transport limits.
68
+
69
+ For narrated edits, materialize requested captions during an **audio-only timing-first pass**, before generating images or 2D/Three.js scenes. Use `generate_assets` with speech plus its audio placement (or approved existing audio) and the following `after` job; no visual-generation jobs yet. Wait for completion, read `get_job_result` and retain measured `texts`/`words`, audio assets and materialized job results before authoring timed visuals. All `before` jobs execute before `after` captions within one request: speech listed before scenes is not a caption-timing checkpoint. Read topic `jobs` and examples `narration-timing` then `narrated-documentary`. For footage/montage captions, continue using `after` on the resolved edit whose audio must be transcribed.
70
+
71
+ Example caption job for either pass:
72
+ ```yaml
73
+ after:
74
+ - id: spoken-captions
75
+ type: captions.generate
76
+ language: ro
77
+ maxWords: 4
78
+ style:
79
+ fontFamily: montserrat
80
+ fontWeight: 700
81
+ fontSize: 58
82
+ color: '#ffffff'
83
+ highlightMode: word
84
+ ```
85
+
86
+ `language` is a two-letter code, `auto`, or omitted; it selects transcription language, not translation. `maxWords` is 1–50 in caption materialization. `style` contains TextStyle fields, not a preset ID or nested CSS. The current caption materializer uses `style`, not `job.preset`; do not assume setting that string applies a text preset. Legacy `jobs` also permits `analysis.transcribe`; it does not automatically become `captions.generate`. Caption `input` is omitted or `montage` (version 3 montage-provenance scope), not arbitrary text. For ordinary generated narration, omit `input`; use `assetId` only when selecting a real audio-bearing asset intentionally.
87
+
88
+ Caption windows include audible audio/video clips; linked source audio is not transcribed twice. Narration tracks take priority when available. Muted clips, zero volume and sources without audio cannot produce a transcript. Preserve generated `resultTextIds` with their actual returned `texts`, rather than rerunning paid transcription.
89
+
90
+ ## Audio, volume and duration
91
+
92
+ ### Speech models and user choice
93
+
94
+ The backend, editor and MCP share `speech/catalog.json`, a curated allowlist, not an automatic import of every provider model. `list_speech_models(language: ro|en)` returns compact choices; `get_speech_model(model: exact-id, language: ro|en)` returns compatible voices and format. These lookups do not call providers or spend credits. Catalog configuration does not prove provider health; the supported language lists are a conservative subset, not all provider languages.
95
+
96
+ For Romanian, recommend `google/gemini-3.8-flash-tts` and offer `google/gemini-3.8-flash-lite-tts` for economy. For English, ask the user to choose between economical `hexgrad/kokoro-82m`, multilingual Gemini 3.8 Flash-Lite and expressive Gemini 3.8 Flash. Put this choice in the initial native brief form unless already answered/delegated. Respect an explicit model request; no silent fallback to Gemini 3.1 or to a cheaper model. Keep old 3.1 recipes unchanged. Use explicit model/language/voice in new YAML, not an implicit API default. Do not expose provider USD tariffs as commercial credit prices or promise an exact cost/latency from the tier label.
97
+
98
+ Gemini models request PCM from OpenRouter, with delivery direction in `instructions` and spoken copy in `text`; the server converts the 24 kHz mono PCM to MP3. All Gemini versions share the family adapter rather than checks specific to 3.1. Kokoro uses language-specific voices and cannot narrate Romanian; an English voice cannot be used for another narration language. A model choice alone is not source-use, cloning or spending authorization. No paid preview samples or alternative-model retries without permission.
99
+
100
+ For `speech.generate`, set `language: ro` for Romanian and `language: en` for English. `auto` conservatively recognizes Romanian/English when there is sufficient evidence; explicitly select the language for short or ambiguous copy. `instructions` supplies delivery guidance separately from the spoken `text`. The backend forwards native-pronunciation instructions, and for Gemini also its speech language configuration. Romanian without an explicit model/reference uses the multilingual Gemini voice; incompatible language-specific voices are rejected rather than silently using French/Spanish/English pronunciation. A cloned speaker can carry the original speaker's accent: choose an appropriate reference and listen to the result.
101
+
102
+ Finish speech and requested captions before fixing scene/chapter durations or submitting image/scene generation. Reuse existing approved timing results; do not add unrequested TTS or paid captions. Without captions, measured speech duration supports whole-section scenes, not invented per-word cues. Use `narrationJob` to bind a scene to its actual speech and content, or use measured captions to select a partial window. Never pad a mismatched plan with long silent holds or speed up scenes just to force provisional timing. Music mixing is available, **music generation is not**; do not promise original generated music or synthesize it with a local script without a separately approved alternative.
103
+
104
+ Declare an audio input slot, bind one actual audio asset, then:
105
+ ```yaml
106
+ audio:
107
+ - id: bed
108
+ use: music
109
+ start: 0s
110
+ from: 0s
111
+ fit: sequence
112
+ repeat: true
113
+ volume: 18
114
+ ```
115
+
116
+ `fit: sequence` uses the current sequence/timeline span minus `start`; `source`/omitted uses explicit `duration` or remaining source. `repeat` must be explicitly true if the desired span exceeds available audio. Each loop uses the selected `from` source offset. Volume is percent (0–200); start with a restrained music bed under speech and verify audibility. This is not automatic loudness normalization, ducking, beat detection, music generation or rights clearance. `sequence.each.source_audio: keep|remove` affects source audio only; don't remove narration by mistake. Explicit audio clips support fades and timeline placement through normal clip fields/overrides.
117
+
118
+ Treat requested or AI-proposed runtime as approximate unless the user explicitly sets a hard duration cap. If a planned 30-second video yields 38–40 seconds of successful speech, preserve the full voice/captions and extend the video to the measured narration end. Do not regenerate, truncate or speed up narration solely to hit an estimate, or rerun successful captions/images. Lengthen/recompile existing scenes and holds or add relevant client-authored scenes within the approved visual scope; update placements and transition overlaps so the picture covers all speech. Keep real caption words/timings unchanged when audio placement is unchanged. State the adjusted runtime and continue without reconfirmation within existing permissions. Resolve an explicit hard duration cap or spending limit before changing paid narration or exceeding approval. Do not assume character count predicts exact spoken duration. `mp3` output is audio-only; video/scene/effect choices do not turn it into a video container.
@@ -0,0 +1,72 @@
1
+ # YAML composition contract and field map
2
+
3
+ Author **one YAML mapping** and save it as `.edit.yaml`. JSON input remains accepted for backwards compatibility, but agents should not author JSON recipes. Use the complete envelope with `document`, `bindings`, `assets`, and optional `snapshot`/`preparedText`. `get_recipe_schema` describes `document`, **not the envelope**. `document` contains the edit DSL; `bindings` and `assets` are its siblings. `recipe` is a legacy envelope field, not a substitute for `document`. Use a YAML composition string in MCP tools, never a local filename as its value. For unchanged continuation after generation, `sourceJobId` replaces the composition argument; `get_job_result` returns resolved `recipeYaml` when editing is needed.
4
+
5
+ No duplicate/unknown keys, YAML anchors, aliases, merge keys or nulls. Omit optional fields instead. Quote `#RRGGBB` colors. Times are numeric seconds or strings such as `0.25s` and `250ms`, not SMPTE timecode. The compiler stores microseconds internally, but callers send seconds.
6
+
7
+ ## Select the authoring layer
8
+
9
+ | Field | Purpose and constraints |
10
+ | --- | --- |
11
+ | `version` | 1 = explicit timeline/sequence; 2 = preferred staged recipe authoring; 3 = required for `montage`. Staged fields are also accepted in explicitly versioned 1/3 documents; do not rewrite an existing version needlessly. |
12
+ | `mode` | `assemble` builds tracks/sequence. `modify` needs a real `snapshot` with nonempty `revision`; modify must not also supply `tracks`, `sequence` or `audio`. |
13
+ | `catalogVersion`, `compilerVersion` | Optional **string** compatibility pins, unlike numeric `version`. Omit unless needed; otherwise quote the deployed values (for example `'1'`, never numeric `1`). Read deployed values; do not invent or increment them. |
14
+ | `revision` | Compiler-produced document identity, not the project-save version. Preserve/refresh through compilation; do not fabricate a live revision. |
15
+ | `instanceId` | Stable namespace for generated sequence IDs (default `sequence`). Keep it stable across edits and retries. |
16
+ | `inputs` | Named slots: `kind: video|image|audio`, optional `multiple` and `optional` booleans. Required slots need matching bindings. |
17
+ | `sequence` | Uniform ordered video/image assembly. `use` names a slot, `order: input|reverse`; `each` applies one treatment per binding. |
18
+ | `tracks` | Explicit stable IDs/timing for nonuniform clips, layers and selected transitions. Types are `video` and `audio`, not `image` or `scene`. |
19
+ | `montage` | Version 3: restructure targeted existing video clips using complete source ranges/candidates. Read the montage section below. |
20
+ | `overrides` | Patch a known clip ID: `target`, optional `start`, `from`, `duration`, `rate`, `volume`, `opacity`, `fadeIn`, `fadeOut`, `transform`, `keyframes`, `look`, `motion`. |
21
+ | `commands` | Typed edits with selectors and per-command operands; see topic `commands`. |
22
+ | `rules` | Reusable selectors with unique `id`, `target` and `apply.look`, `apply.motion` or `apply.effect`. Rules target video/image clips and must match actual unlocked clips. |
23
+ | `effects` | Timed video-track effect blocks with real preset IDs and parameters; see `effects`. |
24
+ | `transitions` | Explicit adjacent same-track video pairs with matching overlap; see `transitions`. |
25
+ | `texts` | Ordinary titles, labels or verified captions. See `text`; typography fields are flattened directly onto each text item. |
26
+ | `audio` | Slot-bound audio tracks, source trim, fit, repeat and percent volume. See `audio`. |
27
+ | `jobs` | Legacy un-staged generation declarations. Placement uses an existing `trackId`; prefer staged fields for new generation recipes. |
28
+ | `before` | Image, speech, scene generation/edit jobs executed before timeline compilation. |
29
+ | `placements` | Reference a `before` job and put its result on `{type: video|audio, role: ...}` at `start`, optional `duration`, optional video `transform`. |
30
+ | `after` | Currently only `captions.generate`, after the resolved timeline/audio exists. |
31
+ | `output` | Aspect `landscape|portrait|classic` (aliases `16:9|9:16|4:3` normalize); fit `contain|cover`; resolution `480p|720p|1080p|2k|4k`; integer fps 1–120; format `mp4|avi|mp3`; quality `low|normal|high`. Defaults: landscape/contain/1080p/30/mp4/normal. Scene generation has narrower dimensions/fps limits. |
32
+
33
+ `output.fit: contain` preserves the whole source image with bars when needed (the backwards-compatible default). `output.fit: cover` fills the frame without squeezing or shrinking the whole image to fit: it preserves proportions and center-crops the excess. For landscape footage in portrait output, the left and right sides are cropped. Example: `output: {aspect: portrait, resolution: 1080p, fit: cover}`. This applies consistently to visual clips, images and live scenes, including transitions and alpha masks, in browser previews and local/server exports. Text/captions keep their output-aspect layout. Do not confuse this with audio `fit: sequence|source` or transition overlap `policy: shrink`.
34
+
35
+ For narrated edits, use a separate **timing-first** submission: speech/audio placement plus requested `after` captions, without image/scene jobs. All `before` jobs run before `after` in one request; a single all-in-one recipe cannot first expose caption timings to the host for visual planning. Wait for completion and retrieve the resolved YAML before adding timed visuals. Preserve materialized job IDs/results, texts and assets; normalization may move staged jobs into `jobs`. Adding visuals needs an edited composition, not unchanged `sourceJobId`. Read topic `jobs` and examples `narration-timing` then `narrated-documentary`.
36
+
37
+ Existing captions are **read-only unless the user explicitly requests a caption change**. Preserve complete caption entries: exact `texts[].text`/`words[].text` including spaces and line breaks, grouping/order, IDs/`resultTextIds`, source anchors, timings and all layout, animation/highlighting/effects values. Do not reword, trim, split/merge/reflow, reposition or restyle them when adding visuals or repairing unrelated fields. Existing caption configuration wins over style/profile/`captionMaxWords` defaults; four-word/two-line defaults apply only to NEW caption generation. The renderer handles fitting/wrapping/collision avoidance; adapt new scene labels around captions instead. Read topic `text` for the narrowly scoped encoding-repair exception. This is not a new YAML lock flag.
38
+
39
+ ## Assets, bindings and snapshots
40
+
41
+ An asset identifies `{id, file, version, kind, duration, width?, height?, hasAudio?, local?}`. Obtain real metadata/version from `get_asset_metadata`; never reuse `example-only` fixture versions in a real request. Bind slots to IDs, with matching kinds and cardinality. Using filenames as IDs is convenient but does not remove the need for source metadata in standalone validation/compilation. Rendering resolves existing uploaded filenames. `local` is an internal asset flag, not permission for MCP to read a caller's local path.
42
+
43
+ `snapshot` has `{revision, tracks, effects, transitions, textItems, selectedIds}` and captures the **compiler timeline**. `get_project` returns editor state, not automatically a ready compiler snapshot; obtain/construct an appropriate current snapshot rather than treating `state.timeline` as this object verbatim. `save_project` takes full editor state and its numeric current project `version`, never raw recipe YAML. `preparedText` is renderer-produced text preparation; do not fabricate its hashes/images.
44
+
45
+ ## Sequence and clips
46
+
47
+ `sequence.each`: `take: {from, duration}`; duration is **timeline** duration. A rate of 2 consumes twice that much source. `rate` is 0.25–4. `source_audio` is `keep|remove` (default keep). `volume` is 0–200 **percent**, not 0–1 gain. `look` and `motion` are exact catalog IDs. A clip must have at least 100ms timeline time and fit the real source (images can be held without a finite source duration).
48
+
49
+ Sequence track IDs are `<instanceId>/video` and, when needed, `<instanceId>/source-audio`. A generated clip ID is `<instanceId>/<slot>/<assetId>/<occurrence>`. Inspect compilation before targeting these IDs. `sequence.between` is optional: omit it for cuts. It takes `{preset, duration, policy: error|shrink}`; there is no sequence `random` field.
50
+
51
+ Explicit `tracks[]`: `{id, name?, type, muted?, hidden?, locked?, clips}`. Each clip uses `{id, assetId, start, inPoint, outPoint, playbackRate?, volume?, linkedClipId?, transform?, transformKeyframes?, opacity?, fadeIn?, fadeOut?, look?, motion?, layerEntrance?, layerExit?, provenance?}`. `start` is timeline time; `inPoint/outPoint` are source times. Timeline duration is `(outPoint-inPoint)/playbackRate`. Do not invent links/provenance; preserve real reciprocal aligned audio links. `layerEntrance/layerExit` are opaque strings in the model, not an independently advertised preset contract: use documented capabilities, not guessed CSS animations.
52
+
53
+ To place a clip for timeline duration `D`, set `outPoint = inPoint + D * playbackRate`, **not** `start + D`. For an image with `inPoint: 0` and `playbackRate: 1`, `outPoint` is its hold duration regardless of `start`. Example: `start: 2.8, inPoint: 0, outPoint: 4.77` ends at `7.57`; the next clip at `7.22` overlaps by `0.35`. Setting `outPoint: 7.57` instead would end at `10.37`. Do not blame floating-point drift for this source/timeline mix-up: the compiler compares integer microseconds.
54
+
55
+ `transform`: zoomX/zoomY 0.01–40, linkZoom (equal axes if true), positionX/positionY -100–100 (editor-relative percentages), rotation -180–180 degrees, anchorX/anchorY 0–1, pitch/yaw -90–90 degrees, flipH/flipV booleans. `transformKeyframes[]` is `{time, transform}` with strictly increasing **clip-local** times within the clip. Do not confuse these positions with text pixel coordinates.
56
+
57
+ ## Pre-submit checks
58
+
59
+ - Edit the existing resolved `.edit.yaml` with normal workspace tools. Preserve successful assets, speech/caption results and unrelated fields; do not reconstruct the whole document to repair one field.
60
+ - Compare complete caption entries and `resultTextIds` against the resolved baseline before submission; undo unintended caption changes. Preserve YAML string values, including spaces and line breaks, when choosing scalar quoting/block syntax. A successful validation/compile does not prove that captions were preserved.
61
+ - Write valid YAML directly or use an existing YAML serializer. Do not write an ad-hoc JSON-to-YAML emitter. `tracks`, each track's `clips`, `transitions`, `texts`, caption `words` and `assets` are lists: use `- ` entries or `[...]`, not repeated mapping keys. Keep numeric `version` distinct from quoted string compatibility pins.
62
+ - For every explicit transition compute `leftEnd = left.start + (left.outPoint - left.inPoint) / left.playbackRate` and require `leftEnd - right.start == transition.duration` at microsecond precision; also obey the duration bounds and no-triple-overlap rule in topic `transitions`.
63
+ - Submit the exact complete YAML string to `validate_recipe` after every edit, including after generation adds visuals. It checks timeline geometry when bindings/assets/jobs are resolved, without paid generation or rendering. Pending requirements mean geometry is not yet fully checked: resolve them and validate again. Use `compile_recipe` to inspect the normalized editing plan and duration. A successful transport response alone is not validation success: inspect `statusCode`, error diagnostics and requirements.
64
+ - Before final `render_video`, require no error diagnostics and no unresolved requirements for that same YAML. Any edit invalidates the previous check. Never use a paid render as a syntax, type, overlap or timing test.
65
+
66
+ ## Montage version 3
67
+
68
+ `target: {kind: video, ids?, trackId?, position?, index?, selected?}` must match unlocked video clips on one track and include intervening clips. Supply **either** `ranges: [{clipId, from, to}]` or scored `candidates` with score 0–100. `from/to` are source positions inside the targeted clips; ranges must not overlap. Candidates require `targetDuration`; `tolerance` bounds whole-moment selection, not arbitrary truncation of speech. Maximum range count comes from the deployed compiler limits/reference.
69
+
70
+ `between` takes `duration`, optional `policy: error|shrink` and **exactly one** of `preset` or `random: true`. `motion` similarly chooses an exact preset or `random: true`; the only supported random motion `family` is `zoom`. `seed` makes random choices deterministic; explicit IDs are preferable when the brief calls for a specific style. No `random` flags belong on ordinary effects, sequence treatments or text.
71
+
72
+ Compilation remaps montage attachments, applies overrides/commands/rules and expands looks/motions. It can normalize the result into explicit tracks and merge resolved staged jobs. Save the returned resolved document/assets when reusing generated work; do not paste a stale unmaterialized recipe over it.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: machinal-review
3
+ description: Critique a machinal production contract before scene authoring and verify the resolved edit before rendering. Use for simplistic/generic scenes, missing promised transitions/effects, visual ambition, pacing and continuity. Current-client critique plus deterministic compile_recipe editorialReview; no server critic/model, engine replacement or unapproved paid previews.
4
+ ---
5
+
6
+ # Video production critic
7
+
8
+ Read `get_editing_reference(topic: production)` (offline: `references/production.md`) after the brief. Keep the existing scene-engine. Do not repeat the brief, request a separate plan confirmation, change media scope or regenerate successful narration/captions/images. A small edit needs only a targeted review of the changed beat/junction.
9
+
10
+ 1. **Before code:** the director writes a compact production contract using actual measured cues/supplied copy: subject-specific action, medium/assets, composition/light, independent objects, local reveal/action/hold/exit, adjacent-shot handoff and exact treatment targets or a justified cut. Critique the contract before implementation. For expressive work, reject interchangeable title cards, repeated portrait zooms and the unchanged runtime demo primitive; don't confuse rich direction with decorative clutter. Respect deliberately minimal/no-generation briefs.
11
+ 2. **Focused critic:** assess subject specificity, meaningful motion, composition/craft, pacing, continuity/treatment and truth/scope separately. Report `severity | beat/junction + time | evidence | specific change | verification`; use `unverified` when evidence is missing. Correct major omissions in one focused revision; no automatic beauty score, generic praise or effect quota. This is a separate stage in the current client, not an independent model. No server critic or subagent without host/user authorization.
12
+ 3. **Before render:** validate the exact final YAML and use its successful `compile_recipe` output, including `editorialReview`. Compare actual junctions and treatment targets/intervals with the contract and Svelte source. `not_ready` cannot pass; `review_required` means the current client must review, not that the edit is approved. Implement missing promised transitions/effects or give a concrete brief-compatible reason to omit them. Existing unchanged successful compilation is reused; any edit requires new preflight.
13
+ 4. **Evidence boundary:** the report is recipe-level inventory, not visual inspection. A scene may contain internal effects/motion that do not appear in YAML; source review cannot prove pixels, smooth motion or audio sync. Inspect representative frames/video only using deployed tools and existing access/spending approval. Without them state `source/plan reviewed; visual result unverified`. Do not invent a screenshot/preview tool, install a local renderer or start paid review loops.
14
+ 5. **Preserve quality during repairs:** keep the subject, artwork, attachments and independent motion; fix the reported failure instead of replacing the scene with a heading. Follow the existing two-targeted-repair limit for recurring compiler failures. Rendering, source-use approval, credit accounting and delivery keep their normal workflow; this critic is not a render authorization token or an aesthetic guarantee.
15
+
16
+ Where deployed, compile_recipe's optional productionContract/productionReview bind beat promises to exact YAML and pinned source versions; reconcile revision_required findings and use expectedCompositionVersion before paid submission. After actual permission to inspect the named scene and return images, get_scene_source → inspect_scene supplies 1–6 explicit sampled frames as MCP images, with sourceVersion, timestamps and optional data-scene-object bounds. This bounded diagnostic costs zero machinal credits, not full scene/video rendering. Samples exclude timeline captions/final compositing and do not verify motion/audio or aesthetic quality. Read the current production reference for schemas/limits; never invent support on an older deployment or launch automatic inspection/render loops.
17
+
18
+ Where deployed, render_preview produces a short final-composition MP4 with mixed audio, but CURRENTLY processes/bills the COMPLETE timeline and full referenced scenes, not just the excerpt. Explain that cost basis before separate preview spending/source approval and check credits. It requires fully resolved assets and expectedCompositionVersion; never rerun successful generation or rewrite captions/timing for a preview. Normal job waits/delivery apply. An excerpt is not the complete final delivery, and receiving its link is not proof of playback or aesthetic review. Read topic=production. For small scene adjustments, edit_scene_parameters can preserve Svelte/media/config when the named source explicitly exposes that parameter surface; read scene-authoring and respect sourceVersion/consent.