@remixmate/cli 0.9.50 → 0.9.52

package/skills/gen-script/scripts/gen_script.py

@@ -36,7 +36,7 @@ if os.path.isdir(_TEMPLATE_DSL_DIR):
     sys.path.insert(0, os.path.abspath(os.path.join(_TEMPLATE_DSL_DIR, "..")))
 
 # Shared Python lib lives under skills/template-registry/scripts/ — the de-facto
-# cross-skill module location (registry_loader, template_paths, etc.). See
+# cross-skill module location (registry_loader, countdown_spec, etc.). See
 # AGENTS.md for the convention.
 _SHARED_SCRIPTS_DIR = os.path.join(
     os.path.dirname(__file__), "..", "..", "template-registry", "scripts"
@@ -54,6 +54,7 @@ try:
         resolve_count as resolve_countdown_count,
         resolve_countdown_spec,
         scene_payload as countdown_scene_payload,
+        stated_counts as countdown_stated_counts,
     )
     _HAS_COUNTDOWN = True
 except ImportError:
@@ -72,6 +73,14 @@ except ImportError:
     _HAS_ENHANCER = False
     SKELETON_PREFIXES = ("[骨架待填充]", "[skeleton placeholder]")
 
+# 旁白字数预算：写进骨架占位旁白，让模型写脚本时就知道这一场放得下多少字。
+# 守护式导入同上；缺失时占位文案退回不带预算的旧格式。
+try:
+    from video_dsl.runtime import narration_budget as _nb
+    _HAS_BUDGET = True
+except ImportError:
+    _HAS_BUDGET = False
+
 # 场景数上限的唯一实现在 dsl_validator（它同时是门禁方）。守护式导入的理由同上：
 # 共享目录可能不在（单测 / 裁剪安装），那时退回历史常量 20，行为与改动前一致。
 try:
@@ -109,7 +118,8 @@ except ImportError:
 VALID_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
 VALID_PURPOSES = ["opening", "point", "example", "explanation", "highlight", "cta", "ending"]
 
-CHARS_PER_SECOND = 5.0  # 与 timeline_compiler.py 保持一致（中文约 5 字/秒）
+# 规划用语速 / 行间停顿 / 场景尾巴统一在 video_dsl.runtime.narration_budget。
+# 这里原有的 CHARS_PER_SECOND = 5.0 从未参与计算（只出现在注释里），已删。
 
 # ── Language contract (mirrors apps/ab-skill/src/handlers/template-meta.ts) ──
 # template.json may declare:
@@ -229,20 +239,25 @@ def _localize_label(language, key, **fmt):
         "label_point":   {"zh": "内容要点 {n}", "en": "Point {n}"},
         "label_cta":     {"zh": "结尾 CTA", "en": "Closing CTA"},
         "narration_opening": {
-            "zh": "[骨架待填充] 关于{topic}的开场 Hook({duration}s)",
-            "en": "[skeleton placeholder] Opening hook about {topic} ({duration}s)",
+            "zh": "[骨架待填充] 关于{topic}的开场 Hook({duration}s{budget})",
+            "en": "[skeleton placeholder] Opening hook about {topic} ({duration}s{budget})",
         },
         "narration_point": {
-            "zh": "[骨架待填充] {label}:关于{topic}的一个要点({duration}s)",
-            "en": "[skeleton placeholder] {label}: a point about {topic} ({duration}s)",
+            "zh": "[骨架待填充] {label}:关于{topic}的一个要点({duration}s{budget})",
+            "en": "[skeleton placeholder] {label}: a point about {topic} ({duration}s{budget})",
         },
         "narration_cta": {
-            "zh": "[骨架待填充] 关于{topic}的 CTA 结尾({duration}s)",
-            "en": "[skeleton placeholder] Closing CTA about {topic} ({duration}s)",
+            "zh": "[骨架待填充] 关于{topic}的 CTA 结尾({duration}s{budget})",
+            "en": "[skeleton placeholder] Closing CTA about {topic} ({duration}s{budget})",
+        },
+        # {budget} 由 _budget_suffix 填：「，整段≤32 字；分行每多一行约少 4 字」。
+        "budget_suffix": {
+            "zh": "，整段≤{chars} 字；分行旁白每多一行约少 {per_line} 字",
+            "en": ", ≤{chars} words as one block; ~{per_line} fewer per extra narration line",
         },
         "narration_default": {
-            "zh": "[骨架待填充] 关于{topic}的内容({duration}s)",
-            "en": "[skeleton placeholder] Content about {topic} ({duration}s)",
+            "zh": "[骨架待填充] 关于{topic}的内容({duration}s{budget})",
+            "en": "[skeleton placeholder] Content about {topic} ({duration}s{budget})",
         },
         # NOTE: 这里曾有 "point_description"（"关于{topic}的要点内容"）与
         # "more_about"（"更多关于{topic}的内容"）两条，用来给 no-visual 场景拼画面
@@ -256,6 +271,9 @@ def _localize_label(language, key, **fmt):
     }
     entry = table.get(key, {})
     template = entry.get(language) or entry.get(DEFAULT_LANGUAGE) or ""
+    # 字数预算只有按场景规划的路径才算得出来（轮播 / 按字幕定时长的模板没有
+    # 「每场秒数」这个前提），没给就是不带预算的旧格式。
+    fmt.setdefault("budget", "")
     return template.format(**fmt)
 
 
@@ -362,17 +380,47 @@ def plan_scenes(
     return scenes
 
 
-def estimate_narration_text(label: str, purpose: str, duration: int, topic: str, language: str = DEFAULT_LANGUAGE) -> str:
+def _budget_suffix(duration: int, language: str, speed: float, tail_pad_sec: float | None) -> str:
+    """占位旁白里的字数预算。拿不到预算模块时返回空串（退回旧格式）。
+
+    为什么写进占位文案而不是单独字段：模型填旁白时一定会读到这一句，而骨架多一个
+    字段就得在校验白名单、TTS payload 两头都处理，漏一头就是新的静默问题。
+    """
+    if not _HAS_BUDGET:
+        return ""
+    tail = _nb.DEFAULT_TAIL_PAD_SEC if tail_pad_sec is None else tail_pad_sec
+    lang = "zh" if language == "zh" else "en"
+    chars = _nb.speech_budget(duration, speed, lang, lines=1, tail_pad_sec=tail)
+    per_line = max(1, round(_nb.LINE_PAUSE_SEC * _nb.speech_rate(lang, speed)))
+    return _localize_label(language, "budget_suffix", chars=chars, per_line=per_line)
+
+
+def estimate_narration_text(
+        label: str,
+        purpose: str,
+        duration: int,
+        topic: str,
+        language: str = DEFAULT_LANGUAGE,
+        speed: float = 1.0,
+        tail_pad_sec: float | None = None,
+) -> str:
     """Generate a short skeleton narration hint for a scene.
 
     This returns a *skeleton only* — the agent is expected to replace this
     text with real narration before submitting DSL to prepare_video_assets. We
     deliberately return a short, clearly-placeholder-looking string rather
-    than padding to duration × CHARS_PER_SECOND, because padding with a
+    than padding to the scene's length, because padding with a
     repeating filler sentence historically caused the skeleton to be
     submitted verbatim to TTS (audio narration mismatch bug).
+
+    It does carry the scene's narration *budget* (see narration_budget): the
+    one number the agent needs while writing, and never had — a 2026-09-27
+    session wrote 45–58 chars into 8s scenes and shipped 117s for a 75s target.
     """
-    fmt = {"label": label, "topic": topic, "duration": duration}
+    fmt = {
+        "label": label, "topic": topic, "duration": duration,
+        "budget": _budget_suffix(duration, language, speed, tail_pad_sec),
+    }
     if purpose == "opening":
         return _localize_label(language, "narration_opening", **fmt)
     if purpose == "point":
@@ -1267,31 +1315,18 @@ def _plan_countdown_scenes(spec: dict, count: int, duration: float, headline: st
     ]
 
 
-def _warn_on_count_mismatch(headline: str, subheadline: str, count: int) -> None:
+def _warn_on_count_mismatch(spec: dict, headline: str, subheadline: str, count: int) -> None:
     """画面文字里写的数量与实际节拍数不一致时出声提醒（不阻断、不改写）。
 
-    **刻意只 warn 不改写。** 这里曾经有一对 ``_rank_copy`` / ``_rank_title``，是
-    github-repo-rank 的 ``payload.ts`` 里 ``formatRankCopy`` / ``formatRankTitle``
-    的逐行 Python 移植 —— 同样的三个正则，在两个仓库、两种语言里各存一份。那是本文件
-    在 ``_echo_template_llm_hint`` 里写明要避免的事：**CLI 出机制，模板出内容**。标题
-    该怎么写、数量该以什么措辞出现（``Top 5`` / ``前 5 名`` / ``5 个项目``）是模板的
-    版式事实，真源是模板自己。
-
-    去掉那份移植不会让成片出错：模板在渲染时本来就会同步（github-repo-rank 在
-    ``Opening.tsx`` / ``Cover.tsx`` 里做），而且它**必须**保留这个能力 —— 手写 DSL、
-    历史计划、ab-web 改过的标题都不经过 gen_script。CLI 这一份自始至终只影响用户在
-    确认脚本那一步看到的文字，为它复制一套会漂移的正则不值得。
+    **刻意只 warn 不改写。** 标题该怎么写、数量以什么措辞出现是模板的版式事实，
+    模板在渲染时本来就会同步；手写 DSL、历史计划、ab-web 改过的标题都不经过
+    gen_script，所以这里替它改既不必要，也会静默改掉调用方给的文案。
 
-    换成告警的另一个好处：静默改写调用方给的文案本身就不妥（同 ``_warn_on_url_text_layer``
-    的分寸）。把数量告诉它，让它自己把文案写对，比替它改更不容易出意外。
-
-    这里认的措辞（``Top N`` / ``N 个项目`` / ``前 N 名``）只用来**发现不一致**，
-    不用来生成文案，所以它不构成一份需要跟模板同步的版式规则。
+    认哪些措辞由模板的 ``countdown.countPatterns`` 声明（见 countdown_spec），
+    CLI 不内置任何词表；没声明的模板不做这项检查。
     """
-    pattern = r"(?<![a-zA-Z0-9_])top\s*([0-9]+)(?![a-zA-Z0-9_])|(?:^|[^0-9])([0-9]+)\s*(?:个(?=\s*(?:开源项目|项目|仓库|工具))|(?=\s*名))"
     for flag, value in (("--headline", headline), ("--subheadline", subheadline)):
-        stated = {int(g) for match in re.finditer(pattern, value or "", flags=re.I)
-                  for g in match.groups() if g is not None}
+        stated = countdown_stated_counts(spec, value)
         if stated and count not in stated:
             print(
                 f"⚠️  {flag} says {sorted(stated)} item(s) but --item-count is {count}. "
@@ -1305,6 +1340,73 @@ def _warn_on_count_mismatch(headline: str, subheadline: str, count: int) -> None
             )
 
 
+def _template_background_presets(template_config: dict | None) -> list[str]:
+    """模板在 ``customPayloadSchema.background.preset`` 声明的背景取值（没声明 = 空表）。
+
+    背景词汇是**模板自己的**：同样叫「网格」，不同模板的取值名各不相同，默认值也
+    各不相同。所以这里只读声明，不在 CLI 里维护任何取值表。
+    """
+    schema = (template_config or {}).get("customPayloadSchema") or {}
+    background = schema.get("background") if isinstance(schema, dict) else None
+    props = background.get("properties") if isinstance(background, dict) else None
+    preset = props.get("preset") if isinstance(props, dict) else None
+    enum = preset.get("enum") if isinstance(preset, dict) else None
+    return [str(v) for v in enum] if isinstance(enum, list) else []
+
+
+def _apply_look(
+    dsl: dict,
+    template_config: dict | None,
+    template_id: str | None,
+    variant: str | None,
+    background_preset: str | None,
+) -> None:
+    """把用户选的视觉风格 / 背景样式写进 DSL（就地改）。
+
+    这两个值以前没有任何一跳能落进管线：复刻弹窗让用户选了，gen_script 却只写模板
+    默认背景，merge 模式又只替换旁白——成片照出、不报错，用户只觉得「好像没生效」。
+
+    - ``--variant`` → ``meta.templateVariant``：match_template 把它当**显式**选择，
+      优先于 meta.style 的模糊匹配，最终成为 inputProps.variantId；
+    - ``--background-preset`` → 每个场景 ``customPayload.background.preset``：
+      customPayload 原样透传给模板，模板读的正是这个字段。保留模板默认背景里的其它键。
+
+    取值不在模板声明里就直接退出：静默丢掉用户的选择，正是这里要修的那个 bug。
+    """
+    if not variant and not background_preset:
+        return
+    if not template_id or template_config is None:
+        raise ValueError("--variant / --background-preset need --template-id: the allowed values come from the template.")
+
+    if variant:
+        variants = list((template_config.get("variants") or {}).keys())
+        if variant not in variants:
+            raise ValueError(
+                f"--variant {variant!r} is not a variant of template {template_id!r}; "
+                f"choose one of: {', '.join(variants) or '(this template declares no variants)'}"
+            )
+        dsl.setdefault("meta", {})["templateVariant"] = variant
+
+    if background_preset:
+        presets = _template_background_presets(template_config)
+        if background_preset not in presets:
+            raise ValueError(
+                f"--background-preset {background_preset!r} is not supported by template {template_id!r}; "
+                f"choose one of: {', '.join(presets) or '(this template has no background option)'}"
+            )
+        for scene in dsl.get("scenes", []):
+            payload = scene.setdefault("customPayload", {})
+            existing = payload.get("background") if isinstance(payload.get("background"), dict) else {}
+            payload["background"] = {**existing, "preset": background_preset}
+        if background_preset in ("image", "video"):
+            print(
+                f"ℹ️  background preset {background_preset!r} needs a user asset: set "
+                f"customPayload.background.assetRef on each scene to that asset's id, "
+                f"otherwise the template falls back to its default background.",
+                file=sys.stderr,
+            )
+
+
 def build_dsl(
         topic: str,
         duration: int,
@@ -1393,7 +1495,7 @@ def build_dsl(
     _echo_template_llm_hint(template_config, template_id)
     _warn_on_url_text_layer(effective_headline, effective_subheadline)
     if beat_count is not None:
-        _warn_on_count_mismatch(effective_headline, effective_subheadline, beat_count)
+        _warn_on_count_mismatch(countdown, effective_headline, effective_subheadline, beat_count)
 
     # ── carousel-caption 模板（单场景、图/视频轮播 + 打字机）单独装配并直接返回 ──
     if payload_style == "carousel-caption":
@@ -1522,6 +1624,7 @@ def build_dsl(
     image_compose = _HAS_ENHANCER and is_compose_mode(image_style_guide)
     image_ratio = image_style_guide.get("ratio") or ratio
 
+    tail_pad_sec = _nb.template_tail_pad_sec(template_config) if _HAS_BUDGET else None
     for idx, plan in enumerate(scene_plans):
         scene_id = f"scene-{idx + 1:02d}"
         # 视觉素材的 assetId 命名遵循类型前缀：image → img-，video → video-
@@ -1531,7 +1634,10 @@ def build_dsl(
             visual_asset_id = f"img-{scene_id}"
         narration_asset_id = f"narration-{scene_id}" if needs_narration else None
         narration_text = (
-            estimate_narration_text(plan["label"], plan["purpose"], plan["duration"], topic, language=output_language)
+            estimate_narration_text(
+                plan["label"], plan["purpose"], plan["duration"], topic, language=output_language,
+                speed=narration_speed, tail_pad_sec=tail_pad_sec,
+            )
             if needs_narration else ""
         )
 
@@ -1817,7 +1923,9 @@ def build_dsl(
             f"is only a placeholder.\n"
             f"   Write the full DSL yourself from the user's material (scenes, assets, visuals, "
             f"customPayload) and submit all of it to prepare_video_assets — it is used as-is, "
-            f"not merged onto this skeleton. Keep meta.templateId.",
+            f"not merged onto this skeleton. Keep meta.templateId, and copy meta.templateVariant and "
+            f"each scene's customPayload.background from this skeleton when present (they carry the "
+            f"user's --variant / --background-preset choice).",
             file=sys.stderr,
         )
 
@@ -1846,7 +1954,7 @@ Examples:
     parser.add_argument(
         "--source-document-url", default=None,
         help="Source document URL (.pptx) for templates that build their per-scene payload from a "
-             "document (capabilities.payloadHydration, e.g. ppt-to-video). Recorded at "
+             "document (capabilities.payloadHydration). Recorded at "
              "meta.sourceDocument; prepare_video_assets then fetches the layout itself and fills "
              "every scene's customPayload. Pass the same URL you gave doc_parse. Without it such a "
              "template's DSL is rejected downstream.",
@@ -1875,6 +1983,19 @@ Examples:
         ),
     )
     parser.add_argument("--font-name", default=None, help="Human-readable font name. Logged and stored for display only; never used for rendering.")
+    parser.add_argument(
+        "--variant", default=None,
+        help="Template visual variant id (a key of the template's `variants`, listed as variantIds by "
+             "template-registry --list-templates). Written to meta.templateVariant, which overrides the "
+             "fuzzy --style match. When the user picked a style in the replicate card (shown as "
+             "`名字（id）`, e.g. `紫色科技（tech-purple）`), pass that id. Requires --template-id.",
+    )
+    parser.add_argument(
+        "--background-preset", default=None,
+        help="Scene background preset (one of the template's customPayloadSchema.background.preset enum). "
+             "Written to every scene's customPayload.background.preset. When the user picked a background in "
+             "the replicate card (e.g. `纯色（solid）`), pass that id. Requires --template-id.",
+    )
     parser.add_argument("--allow-digital-human", action="store_true", help="Allow digital-human assets")
     parser.add_argument("--allow-ai-video", action="store_true", help="Allow AI-generated video assets")
     parser.add_argument("--template-id", default=None, help="Template id. The template owns outputLanguage and may declare a defaultVoiceId.")
@@ -1920,7 +2041,7 @@ Examples:
         "--scene-images",
         action="append",
         default=None,
-        help="One scene's visual for a visual-overlay template (image-slide etc.). "
+        help="One scene's visual for a visual-overlay template (capabilities.payloadStyle). "
              "Can be repeated: --scene-images url1 --scene-images ai --scene-images url2. "
              "Each entry is either a URL (use that existing asset) or the literal 'ai' / "
              "'ai:<prompt>' (leave this scene to gen-image, optionally with the user's prompt). "
@@ -2073,6 +2194,17 @@ Examples:
         # as a message instead of a traceback.
         parser.error(str(exc))
 
+    try:
+        _apply_look(
+            dsl,
+            _load_template_config(args.template_id) if args.template_id else None,
+            args.template_id,
+            args.variant,
+            args.background_preset,
+        )
+    except ValueError as exc:
+        parser.error(str(exc))
+
     # Post-process for --skip-asset-generation: rewrite all gen-voice / gen-digital-human
     # assets to be already-generated stubs. Image / video are already covered by the
     # stub_image_url / stub_video_url params threaded through build_dsl above.

package/skills/gen-script/skill.json

@@ -34,7 +34,7 @@
       },
       "scenes": {
         "type": "number",
-        "description": "Scene count. Only applies to templates with capabilities.sceneStrategy=arc (the default); single / fixed / countdown templates own their own count. Bounded below by 3 and above by the template's capabilities.maxScenes (default 20) — a clamp is reported on stderr and is NOT an error, so always read the real count back from the returned DSL (scenes[].length) before describing the script to the user. For a template that maps one scene per source page (e.g. ppt-to-video), pass the page count you saw in doc_parse's summary."
+        "description": "Scene count. Only applies to templates with capabilities.sceneStrategy=arc (the default); single / fixed / countdown templates own their own count. Bounded below by 3 and above by the template's capabilities.maxScenes (default 20) — a clamp is reported on stderr and is NOT an error, so always read the real count back from the returned DSL (scenes[].length) before describing the script to the user. For a template that maps one scene per source page (capabilities.payloadHydration), pass the page count you saw in doc_parse's summary."
       },
       "voice_id": {
         "type": "string",
@@ -44,13 +44,21 @@
         "type": "number",
         "description": "Narration speech rate, 0.5-2.0 (default 1.0). Stored at global.narration.speed and applied when prepare_video_assets synthesizes the voice-over. **Must** pass when the user picked a speech rate — a template's 语速 / speed parameter arrives as a multiplier like 1.1, and without this flag it is silently dropped and the narration comes back at 1.0. Above ~1.3 subtitle alignment drifts and the delivery sounds mechanical; suggest shortening the script instead of raising it further."
       },
+      "variant": {
+        "type": "string",
+        "description": "Template visual variant id (a key of the template's variants; template_registry lists them as variantIds). Written to meta.templateVariant, which beats the fuzzy `style` match. **Must** pass when the user picked a style: the replicate card shows it as `名字（id）` — e.g. `视觉风格: 紫色科技（tech-purple）` or `板面颜色: 黑板（black-board）` → pass the id in the parentheses. Without it the choice is silently dropped. Requires template_id; an id the template does not declare is rejected."
+      },
+      "background_preset": {
+        "type": "string",
+        "description": "Scene background preset, one of the template's customPayloadSchema.background.preset values. Written to every scene's customPayload.background.preset. **Must** pass when the user picked a background: the replicate card shows `背景样式: 纯色（solid）` → pass `solid`. Without it the scene keeps the template default. Requires template_id; unsupported values are rejected. `image` / `video` also need customPayload.background.assetRef on each scene."
+      },
       "template_id": {
         "type": "string",
-        "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
+        "description": "Template id (from template_registry). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
       },
       "source_document_url": {
         "type": "string",
-        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). **Must** pass it for such a template: it is recorded at meta.sourceDocument, and prepare_video_assets then fetches the layout itself and fills every scene's customPayload.slide. Pass the same URL you gave doc_parse. You are NOT expected to author or even read that layout data — one page is hundreds of KB, so it never travels through the conversation; without this reference the DSL is rejected downstream after you have already written all the narration."
+        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration). **Must** pass it for such a template: it is recorded at meta.sourceDocument, and prepare_video_assets then fetches the layout itself and fills the customPayload field the template declares (payloadHydration.payloadField) on every scene. Pass the same URL you gave doc_parse. You are NOT expected to author or even read that layout data — one page is hundreds of KB, so it never travels through the conversation; without this reference the DSL is rejected downstream after you have already written all the narration."
       },
       "headline": {
         "type": "string",
@@ -72,7 +80,7 @@
         "items": {
           "type": "string"
         },
-        "description": "Per-scene visuals for a visual-overlay template (image-slide etc.) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
+        "description": "Per-scene visuals for a visual-overlay template (capabilities.payloadStyle=visual-overlay) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
       },
       "caption_lines": {
         "type": "array",
@@ -117,6 +125,8 @@
       "scenes",
       "voice_id",
       "speed",
+      "variant",
+      "background_preset",
       "template_id",
       "source_document_url",
       "headline",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V16",
+  "version": "V18",
   "skillDescription": "Video-script generation skill. Turns a user-supplied topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.\n\nUse this skill as soon as the user mentions any of these intents:\n- Write a video script, generate a video script, plan a video, write storyboards\n- Create a short video, plan video content, generate a Video DSL\n- Turn a topic into a video structure / video content plan\n\nEven when the user does not say \"generate the DSL\", use this skill whenever they want to turn a topic into a structured video plan.\n\n⚠️ Stop-and-confirm gate: after this skill returns a DSL, show the full script and wait for the user's explicit confirmation. Never call `prepare_video_assets` in the same turn."
 }

package/skills/prepare-video-assets/SKILL.md

@@ -73,7 +73,7 @@ The asset resolver invokes the following skills based on `AssetRef` declarations
 ```bash
 python3 <SkillDir>/scripts/prepare_video_assets.py \
   --dsl-json '<DSL_JSON_STRING>' \
-  --template-id html-slide
+  --template-id <templateId>
 ```
 
 - `<DSL_JSON_STRING>` is the JSON the agent received from `gen_script` — pass inline; **do not** write it to disk.
@@ -86,7 +86,7 @@ python3 <SkillDir>/scripts/prepare_video_assets.py \
 ```bash
 python3 <SkillDir>/scripts/prepare_video_assets.py \
   --dsl my-video.dsl.json \
-  --template-id html-slide
+  --template-id <templateId>
 ```
 
 `--template-id` automatically calls template-registry internally; or pass `--binding my-video.binding.json` if you have a pre-generated binding.
@@ -162,7 +162,7 @@ During dev / debug the user may want to exercise the pipeline without burning ge
 ```bash
 python3 <SkillDir>/scripts/prepare_video_assets.py \
   --dsl-json '<DSL_JSON_STRING>' \
-  --template-id picture-book-en \
+  --template-id <templateId> \
   --stub-image-url "https://cdn.example.com/placeholder.jpg"
 ```
 

package/skills/prepare-video-assets/skill.json

@@ -35,7 +35,7 @@
       },
       "source_document_url": {
         "type": "string",
-        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). Normally unnecessary: gen_script already recorded it at meta.sourceDocument when you passed source_document_url there, and the cached skeleton carries it through. Pass it here only to recover when the skeleton lacks the reference — it saves a full gen_script round trip. The layout data is fetched here and written into every scene's customPayload.slide; you neither author nor see it."
+        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration). Normally unnecessary: gen_script already recorded it at meta.sourceDocument when you passed source_document_url there, and the cached skeleton carries it through. Pass it here only to recover when the skeleton lacks the reference — it saves a full gen_script round trip. The layout data is fetched here and written into the customPayload field the template declares (payloadHydration.payloadField) on every scene; you neither author nor see it."
       },
       "binding_json": {
         "type": "string",

package/skills/prepare-video-assets/version.json

@@ -2,6 +2,6 @@
   "skillName": "prepare-video-assets",
   "repoName": "agent-skill-media-maker",
   "skillId": "476",
-  "version": "V3",
+  "version": "V4",
   "skillDescription": "Asset-preparation skill: resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a `job_id` for the subsequent `render_video` call.\n\nUse this skill as soon as the user mentions any of these intents:\n- Generate / prepare video assets, resolve assets, render-ready\n- \"Make me a video about X\" (the agent calls gen_script → prepare_video_assets → render_video)\n- Regenerate one asset (image / audio) for a specific scene\n\nNext step: after the user confirms the resolved assets, call `render_video` with the `job_id` returned by this skill.\n\n⚠️ Stop-and-confirm gate: this skill runs only after the user has confirmed the script, and after it returns you must show the resolved assets and wait for the user's explicit confirmation. Never call `render_video` in the same turn."
 }