@remixmate/cli 0.9.50 → 0.9.52

package/README.md

@@ -259,32 +259,20 @@ npm run smoke
 # CLI unit tests (argv parser + skill schema)
 npm run test:cli
 
-# ── Template regression (after changing binding / timeline / template code) ──
-# L1 (contracts) + L2 (render-plan golden snapshots), full coverage, seconds,
-# no render and no generation API calls. Run this before/after touching shared
-# template plumbing to catch "did I break some OTHER template's binding?".
-npm run regress
-
-# Accept intended render-plan changes (rewrites L2 baselines):
-npm run regress:update
-
-# Run only the render-plan snapshot layer:
-npm run test:render-plan
-
-# Narration speed wiring (gen_script → render plan → gen-voice --speed).
-# Fully offline: no registry, no TTS call.
-npm run test:narration-speed
-
-# L3 — selective, real Remotion render of chosen template(s). NOT full-library
-# by design (rendering is slow + needs asset generation). Catches crashes /
-# black frames the static layers can't. Needs PRIV_TOKEN for narration TTS;
-# pass --stub-image-url to keep image-heavy renders cheap.
-npm run check:render -- --template spotlight-card --frame
-
-# Template defs come from the registry (ab-api HTTP + /tmp cache), exactly like
-# render_video in production. A warm cache or reachable ab-api is required.
-# In a multi-repo checkout the scripts auto-detect template-library; override
-# with AB_TEMPLATES_SRC=/path/to/template-library/packages/templates/src.
+# ── Unit tests for the Python pipeline ──
+# Fully offline. They exercise the CLI's generic mechanisms against the synthetic
+# templates in scripts/fixtures/ — never against a real template library, so
+# template changes cannot turn them red.
+npm run test:unit
+
+# ── Integration: run the CLI against a real template library ──
+# Validation, binding, RenderPlan and props contracts over every template (and
+# dsl-example) in AB_TEMPLATES_SRC. Names no template; needs no ab-api or login.
+AB_TEMPLATES_SRC=/path/to/template-library/packages/templates/src npm run integration
+
+# Selective real Remotion render of chosen template(s). Needs PRIV_TOKEN for
+# narration TTS; pass --stub-image-url to keep image-heavy renders cheap.
+AB_TEMPLATES_SRC=... npm run integration:render -- --template <id> --frame
 
 # Python skills forward --help to the underlying script:
 remixmate gen-script --help

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.50",
-  "generatedAt": "2026-09-27T01:55:22.557Z",
+  "version": "0.9.52",
+  "generatedAt": "2026-09-27T14:43:11.552Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -9,7 +9,7 @@
       "tier": "tool",
       "category": "consuming",
       "title": "Document Extraction",
-      "summary": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+      "summary": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the per-page slide payload that templates declaring capabilities.payloadHydration (docKind pptx) render one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
       "triggers": [
         "Turn this PPT / slide deck into a video",
         "Extract text or speaker notes from a .pptx",
@@ -437,7 +437,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",
@@ -447,13 +447,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",
@@ -475,7 +483,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",
@@ -520,6 +528,8 @@
           "scenes",
           "voice_id",
           "speed",
+          "variant",
+          "background_preset",
           "template_id",
           "source_document_url",
           "headline",
@@ -784,7 +794,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",
@@ -934,16 +944,19 @@
           },
           "template_id": {
             "type": "string",
-            "description": "Return this template's FULL definition instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. This is the per-template authoring contract — read it before writing DSL for that template."
+            "description": "Return this template's full authoring contract instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. Multi-layout templates return slideSchemas as a MENU (per layout: description, field names, card-list key / item fields / maxItems, and whether narration must be split into items) — enough to pick layouts and draft the script. Read it once per conversation; it does not change between turns."
+          },
+          "slide_id": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "With template_id: return the FULL templateData schema for these layouts (the slideIds you chose from the menu). Call this once, right before writing templateData, with every layout the script uses. 'all' returns every layout (large — avoid)."
           },
           "full": {
             "type": "boolean",
             "description": "List mode only: emit full definitions for every listed template instead of summaries. Rejected when the result would be too large for one tool result — prefer template_id, or narrow with the filter_* parameters."
           },
-          "list_examples": {
-            "type": "boolean",
-            "description": "List the *.dsl.json / *.binding.json reference examples under template-registry/video_dsl/schema/examples/, grouped by templateId. That directory is optional and is not part of the published package, so this is normally empty — to read a template's reference shape, use template_id instead (the registry's own contract)."
-          },
           "filter_tag": {
             "type": "string",
             "description": "Show only templates whose styleTags contain (or are contained in) this string. Case-insensitive. E.g. 'tech' / '科普' / 'walkthrough'."
@@ -972,8 +985,8 @@
         "advanced": [
           "list_templates",
           "template_id",
+          "slide_id",
           "full",
-          "list_examples",
           "filter_tag",
           "filter_aspect",
           "filter_language",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.50",
+  "version": "0.9.52",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -20,29 +20,26 @@
     "list": "node dist/cli.js --list",
     "smoke": "node scripts/smoke.mjs",
     "test:cli": "npm run build && node --test test/*.test.mjs",
-    "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
     "test:web-read": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read.py",
     "test:web-read:browser": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read-browser.py",
-    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
-    "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
-    "test:card-array-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-card-array-keys.py",
     "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",
+    "test:template-look": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-template-look.py",
     "test:narration-tts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-tts.py",
     "test:render-resume": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-resume.py",
     "test:required-props": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-required-props.py",
-    "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
-    "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",
-    "test:contracts": "PYTHONDONTWRITEBYTECODE=1 python3 skills/template-registry/scripts/check_contracts.py",
-    "regress": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/regress.py",
-    "regress:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/regress.py --update",
-    "check:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/render-template-check.py",
     "clean": "node scripts/clean.mjs",
     "test:countdown": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-countdown-strategy.py",
     "test:prepare-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-prepare-contracts.py",
     "test:image-sequence": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-sequence.py",
-    "test:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py",
     "test:image-prompt-compose": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-prompt-compose.py",
-    "test:picture-book-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-picture-book-contract.py"
+    "test:page-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-page-contracts.py",
+    "test:declared-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-declared-keys.py",
+    "test:payload-hydration": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-payload-hydration.py",
+    "test:sentence-alignment": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-sentence-alignment.py",
+    "test:authoring-budget": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-authoring-budget.py",
+    "test:unit": "npm run -s test:narration-speed && npm run -s test:template-look && npm run -s test:narration-tts && npm run -s test:render-resume && npm run -s test:required-props && npm run -s test:countdown && npm run -s test:prepare-contracts && npm run -s test:image-sequence && npm run -s test:image-prompt-compose && npm run -s test:page-contracts && npm run -s test:declared-keys && npm run -s test:payload-hydration && npm run -s test:sentence-alignment && npm run -s test:authoring-budget",
+    "integration": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/regress.py",
+    "integration:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/render-template-check.py"
   },
   "keywords": [
     "claude-code",

package/skills/doc-parse/SKILL.md

@@ -5,7 +5,7 @@ description: |
 
   Two layers, picked with `--fields`:
   - **content** — per-page `title`, `text[]`, and `rawNotes` (the speaker notes). Small, no base64. This is the narration source material.
-  - **layout** — the full `slide` payload the `ppt-to-video` template renders from: every shape, coordinate, color, clip path and the animation `beats`, plus the `mode` verdict. Large (icons are embedded as data URIs).
+  - **layout** — the full per-page `slide` payload: every shape, coordinate, color, clip path and the animation `beats`, plus the `mode` verdict. This is what templates declaring `capabilities.payloadHydration` with `docKind: pptx` render from. Large (icons are embedded as data URIs).
 
   Deterministic: the endpoint parses OOXML, it does **not** call a model. Notes come back verbatim — rewriting them into narration is your job, not the endpoint's.
 
@@ -14,7 +14,7 @@ description: |
   - Read / extract / summarize a .pptx, pull the text or the speaker notes out of a deck
   - Use a PowerPoint file as source material for a script
 
-  You call this skill for the **words** (notes, body text) and for the **page inventory** (how many pages, each page's animation tier and beat count). You do not call it to obtain `customPayload.slide` — that payload never passes through you; see "Using the result".
+  You call this skill for the **words** (notes, body text) and for the **page inventory** (how many pages, each page's animation tier and beat count). You do not call it to obtain the layout payload for a template — that payload never passes through you; see "Using the result".
 triggers:
   - Turn this PPT / slide deck into a video
   - Extract text or speaker notes from a .pptx
@@ -108,12 +108,12 @@ So the picture travels **by reference**:
 doc_parse  --url "https://…/deck.pptx"
 
 # 2. pass the SAME url to gen_script, plus one scene per page
-gen_script --template-id ppt-to-video \
+gen_script --template-id <templateId> \
            --source-document-url "https://…/deck.pptx" \
            --scenes 23
 ```
 
-`gen_script` records it at `meta.sourceDocument`, and `prepare_video_assets` then fetches the layout itself and fills every scene's `customPayload.slide` before validation. You never see that data, and you never hand-write it.
+`<templateId>` is a template that declares `capabilities.payloadHydration` with `docKind: pptx`. `gen_script` records the URL at `meta.sourceDocument`, and `prepare_video_assets` then fetches the layout itself and fills every scene's `customPayload.<payloadHydration.payloadField>` before validation. You never see that data, and you never hand-write it.
 
 What you *do* own from this result:
 
@@ -124,9 +124,9 @@ What you *do* own from this result:
 | `mode` + beat count per page | cut the narration into that many sentences |
 | `flags` | tell the user which elements the extractor could not reconstruct |
 
-Do not raise `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). You may lower it by writing `customPayload.mode`. Raising it requires `trustMeMode: true` and means you have personally checked that page.
+Do not second-guess `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). Whether and how a template lets you override it is in that template's `llmHint`.
 
-> If `prepare_video_assets` ever tells you `customPayload.slide (required)`, the missing thing is not the payload — it is the **reference**. Re-run `gen_script` with `--source-document-url`, or pass `source_document_url` to `prepare_video_assets` to recover without regenerating the script.
+> If `prepare_video_assets` ever reports that hydrated field as `(required)`, the missing thing is not the payload — it is the **reference**. Re-run `gen_script` with `--source-document-url`, or pass `source_document_url` to `prepare_video_assets` to recover without regenerating the script.
 
 **For the words** — `rawNotes` and `text` are two different kinds of raw material, and they need different treatment:
 

package/skills/doc-parse/scripts/extract_via_render.py

@@ -16,8 +16,9 @@
 
 ⚠️ 关于 layout 层的用法，看清楚这一条：**它不是给你读的**。在 ab-agent 里模型没有
 任何文件读取工具（这是有意的安全收窄），所以落盘的那个文件你打不开。需要 layout 的
-模板（ppt-to-video）按引用取数：把同一个文档 URL 传给 ``gen_script --source-document-url``，
-渲染管线会自己把每一页填进 ``customPayload.slide``。见 SKILL.md「Using the result」。
+模板（声明了 capabilities.payloadHydration）按引用取数：把同一个文档 URL 传给
+``gen_script --source-document-url``，渲染管线会自己把每一页填进模板声明的 customPayload
+字段。见 SKILL.md「Using the result」。
 
 必要环境变量（由 ab-agent 自动注入）：
   RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.ai）

package/skills/doc-parse/skill.json

@@ -4,7 +4,7 @@
   "tier": "tool",
   "category": "consuming",
   "title": "Document Extraction",
-  "description": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+  "description": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the per-page slide payload that templates declaring capabilities.payloadHydration (docKind pptx) render one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
   "auth": "required",
   "envVars": [
     "RENDER_API_URL",

package/skills/gen-script/SKILL.md

@@ -39,7 +39,7 @@ Turns a user-supplied **topic** into a **Video DSL v1alpha1** JSON describing wh
 
 The full schema is `template-registry` skill's `video_dsl/schema/video-dsl-v1alpha1.json`.
 
-**Per-template reference DSLs do not ship with this package.** `video_dsl/schema/examples/` is a local-only directory: it is absent from the published npm package (and has never existed in the repo), so `template_registry list_examples=true` normally returns nothing. Do not read "no examples found" as "this template is unsupported" — the authoritative per-template contract ships inside the registry's `template.json`, see below.
+**Per-template reference DSLs do not ship with this package.** `video_dsl/schema/examples/` is a local-only directory: it is absent from the published npm package (and has never existed in the repo). Do not go looking for examples — the authoritative per-template contract ships inside the registry's `template.json`, see below.
 
 ## Agent behavior: DSL generation when a template is selected
 
@@ -52,24 +52,23 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 
 ### Mandatory steps
 
-1. Read the requested template's full definition from the registry — `template_registry` with `template_id=<the id>` and `json_output=true` emits that one template whole. This is the shipping source of truth, and unlike the summary list it truncates nothing. Do **not** ask for every template's full definition (`list_templates=true` + `full=true`): the whole registry is far more JSON than one tool result can carry, and the call fails instead of returning the contract.
+1. Read the requested template's full definition from the registry — `template_registry` with `template_id=<the id>` emits that one template's contract. This is the shipping source of truth. Read it **once per conversation**: it is still in context on the next turn, so do not re-fetch it after the user confirms the script. Do **not** ask for every template's full definition (`list_templates=true` + `full=true`): the whole registry is far more JSON than one tool result can carry, and the call fails instead of returning the contract.
 2. Read its `llmHint` end to end — that is where the template states how its on-screen text and its layouts must be authored.
 3. Read its `customPayloadSchema`: every template-specific field lives there, including the enum of legal `customPayload.slideId` values for multi-layout templates.
-3b. If the template ships `slideSchemas` (multi-layout templates do), **author `templateData` straight from `slideSchemas[slideId]`** — it is the only place the per-layout field names exist. Do not infer them: the same concept is named `name` in one layout, `label` in another and `era` in a third, and a wrong name is dropped in silence (see below).
+3b. If the template ships `slideSchemas` (multi-layout templates do), step 1 returns them as a **menu** — per layout: description, field names, card-list key / item fields / `maxItems`, and a `narration` note. Pick layouts and draft the script from the menu. Then, before writing `templateData`, call `template_registry` once with `template_id` and `slide_id=[every chosen layout]`, and **author `templateData` straight from those `slideSchemas[slideId]`** — it is the only place the per-layout field names exist. Do not infer them: the same concept is named `name` in one layout, `label` in another and `era` in a third, and a wrong name is dropped in silence (see below).
 4. Combine that with the template's `slotMapping`, `requiredProps`, `optionalProps`, `propExtractors`, `assetRequirements`, `supportedAspectRatios`, `supportedDurations`, `constraints`, and `scenePatterns`.
 5. Generate the DSL in the template's native shape — not the generic DSL shape.
 6. Make sure the DSL explicitly contains every template-specific field, e.g. `templateData.words`, `customPayload.slideId`, `visuals.avatar.assetRef`.
-7. If `template_registry list_examples=true` does return files locally, read them as an extra sample — never as a substitute for step 1.
-8. After generation, run the schema check and show the script summary to the user for confirmation.
+7. After generation, run the schema check and show the script summary to the user for confirmation.
 
 ### Document-driven templates: pass the source URL, don't author the payload
 
-Some templates build each scene's picture from a source file rather than from JSON you write. They declare it as `capabilities.payloadHydration` (today: `ppt-to-video`, which fills `customPayload.slide` from a `.pptx`).
+Some templates build each scene's picture from a source file rather than from JSON you write. They declare it as `capabilities.payloadHydration` — `payloadField` names the `customPayload` field the pipeline fills, `docKind` the kind of source file (e.g. `.pptx`).
 
 For those, pass **`--source-document-url`** — the same URL you gave `doc_parse`:
 
 ```bash
-gen_script --template-id ppt-to-video \
+gen_script --template-id <templateId> \
            --source-document-url "https://…/deck.pptx" \
            --scenes 23 --duration 600
 ```
@@ -93,7 +92,7 @@ If the count you need is above the template's maximum, say so and stop — do no
 
 ### Multi-layout templates: pick a layout per scene
 
-When a template's `customPayloadSchema.slideId.enum` holds more than one value (today `html-slide` and `html-slide-blackboard`, 16 layouts each), **every scene must name one**, chosen to fit that scene's information shape — a comparison, a timeline, a code walkthrough and a set of numbers are four different layouts.
+When a template's `customPayloadSchema.slideId.enum` holds more than one value, **every scene must name one**, chosen to fit that scene's information shape — a comparison, a timeline, a code walkthrough and a set of numbers are four different layouts.
 
 `gen_script.py` cannot make that choice: it emits the placeholder `"slideId": "__CHOOSE_SLIDE__"`, and the DSL validator rejects any DSL that still carries it, listing the legal values in the error. Replace every placeholder, and do not reuse one layout for the whole video.
 
@@ -103,7 +102,7 @@ A missing `slideId` is the quietest failure in the pipeline: the renderer drops
 
 Picking the layout is only half of it. Each layout reads its own field names out of `templateData`, and a field the layout does not read is **dropped without a word** — that slot renders empty, or shows the component's built-in placeholder text, and the render still reports success.
 
-This has shipped broken videos: a 7-scene deck wrote `items[].title` where `html-slide`'s `feature-grid` reads `name`, `items[].description` where `timeline-axis` reads `detail`, and `title` / `subtitle` / `ctaText` where `closing-cta` reads `headline` / `actionLine` / `ctaLabel` / `ctaUrl`. Five of seven scenes rendered as empty cards and placeholder copy — after paying for TTS and the render.
+This has shipped broken videos: a 7-scene deck guessed generic names (`title`, `description`, `ctaText`) where the chosen layouts read different ones. Five of seven scenes rendered as empty cards and placeholder copy — after paying for TTS and the render. Which names each layout reads is the template's fact; the template's `llmHint` calls out the usual traps.
 
 So: **copy the field names out of `slideSchemas[slideId]`.** The DSL validator now rejects unknown field names before any asset is generated and tells you the declared ones, but that check only fires for templates that ship `slideSchemas` — reading the contract is still the primary move, not the fallback.
 
@@ -257,7 +256,7 @@ Every URL the user gave becomes one carousel item, in order. How long each item
 ## Agent behavior: user-supplied images for scene-based templates (`--scene-images`)
 
 The section above covers `carousel-caption` templates. Templates whose `payloadStyle` is
-`visual-overlay` (image-slide and friends) have **real scenes**, each with its own background
+`visual-overlay` have **real scenes**, each with its own background
 image and its own narration — for those, user-supplied images go through `--scene-images`,
 not `--carousel-items`.
 
@@ -342,13 +341,13 @@ describes an `ai:` prompt as if it were a picture you have seen.
 
 ### Command example
 
-User: "用 image-slide 做一条讲 RAG 的视频，配图用这两张"
+User: "用这个模板做一条讲 RAG 的视频，配图用这两张"（a `visual-overlay` template）
 + two asset lines with `desc:`
 
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "三分钟看懂 RAG" \
-  --template-id image-slide \
+  --template-id <templateId> \
   --scene-images "https://cdn.example.com/a.png" \
   --scene-images "ai: 赛博朋克风格的服务器机房" \
   --scene-images "https://cdn.example.com/b.png"
@@ -388,14 +387,14 @@ Typical phrasings (non-exhaustive):
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "English picture-book story" \
-  --template-id picture-book-en \
+  --template-id <templateId> \
   --stub-image-url "https://cdn.example.com/placeholder.jpg"
 ```
 
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "GitHub project tour" \
-  --template-id screen-walkthrough \
+  --template-id <templateId> \
   --stub-image-url "https://cdn.example.com/img.jpg" \
   --stub-video-url "https://cdn.example.com/demo.mp4"
 ```
@@ -407,7 +406,7 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Every command below uses `<SkillDir>/scripts/gen_script.py`; never hard-code paths.
 2. **Understand the request**: extract topic, duration, style, audience, etc.
 3. **If the user specifies a template, read it first**: load the matching `template.json` via `template-registry` and confirm its template-specific fields and asset requirements. Do not skip this step.
-4. **Generate the DSL**: pick the right command or DSL shape for the target template (see the per-template commands below).
+4. **Generate the DSL**: pick the flags the target template's `capabilities` call for (see *Common CLI flags*); the template's `llmHint` says what to fill in afterwards.
 5. **Schema validation**: make sure the output DSL conforms to v1alpha1.
 6. **User confirmation**: show the script summary and wait for confirmation, per the rules above.
 
@@ -454,6 +453,8 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--scenes` | Scene count. | auto-planned |
 | `--voice-id` | Narration voice id. | resolved from template + language fallback |
 | `--speed` | Narration speech rate (0.5–2.0), written to `global.narration.speed` and applied when `prepare_video_assets` calls gen-voice. Pass it whenever the user picked a speed (the replicate form's 语速 field sends one). Above ~1.3 subtitle alignment drifts and the delivery turns mechanical — shorten the script instead. | `1.0` |
+| `--variant` | Template visual variant id (a key of the template's `variants`; `template-registry --list-templates` prints them as `variantIds`). Written to `meta.templateVariant`, which takes precedence over the fuzzy `--style` match. Pass it whenever the user picked a style — the replicate card shows it as `名字（id）`, e.g. `视觉风格: 紫色科技（tech-purple）`; pass the id in the parentheses. Requires `--template-id`; unknown ids are rejected. | template default |
+| `--background-preset` | Scene background preset, one of the template's `customPayloadSchema.background.preset` values. Written to every scene's `customPayload.background.preset` (other keys of the template's default background are kept). Pass it whenever the user picked a background, e.g. `背景样式: 纯色（solid）` → `solid`. `image` / `video` also need `customPayload.background.assetRef`. Requires `--template-id`; unsupported values are rejected. | template default |
 | `--allow-digital-human` | Whether to allow digital-human assets. | off |
 | `--allow-ai-video` | Whether to allow AI-generated video assets. | off |
 | `--validate` | Validate-only mode: only validate the input DSL. | — |
@@ -462,7 +463,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--stub-image-url` | Test mode: every image AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_IMAGE_URL`). | — |
 | `--stub-video-url` | Test mode: every video AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_VIDEO_URL`). | — |
 | `--carousel-items` | Repeatable. Media URL placed directly into `customPayload.carousel.items` for `carousel-caption` templates. Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
-| `--scene-images` | Repeatable. One scene's visual for a **`visual-overlay`** template (image-slide etc.), mapped **positionally**. Each entry is a URL (that existing asset) or `ai` / `ai:<prompt>` (that scene goes to gen-image, optionally with the user's own prompt) — so an AI scene can sit anywhere in the order. Scenes past the last entry still get AI images. Scene count is raised (never lowered) to fit the entries when `--scenes` is absent. **Required** whenever the user supplies images for such a template — omitting it silently ignores every image they gave. | — |
+| `--scene-images` | Repeatable. One scene's visual for a **`visual-overlay`** template, mapped **positionally**. Each entry is a URL (that existing asset) or `ai` / `ai:<prompt>` (that scene goes to gen-image, optionally with the user's own prompt) — so an AI scene can sit anywhere in the order. Scenes past the last entry still get AI images. Scene count is raised (never lowered) to fit the entries when `--scenes` is absent. **Required** whenever the user supplies images for such a template — omitting it silently ignores every image they gave. | — |
 | `--caption-lines` | Repeatable. On-screen caption line for `carousel-caption` templates → `customPayload.caption.lines`. Line limits and `**emphasis**` support are declared per template (see its `llmHint`). **Required** for `durationStrategy: fit-caption` templates — write the lines yourself if the user did not supply them. Optional only for `fit-images` templates. | — |
 
 ## DSL generation principles
@@ -471,7 +472,7 @@ Apply the following principles when producing the DSL:
 
 1. **Narrative-first**: opening hook → point expansion → CTA close.
 2. **Assets are declared, not executed**: every asset starts as `AssetRef` with `status: planned`; no generation API call from this skill.
-3. **Narration drives duration**: each scene's duration should match its narration reading time (≈ 3–4 zh chars/sec, or ~2 words/sec for English).
+3. **Narration drives duration**: the rendered length of a scene is its narration's reading time plus a short tail, not `scenes[].duration`. Each skeleton placeholder states the scene's budget (e.g. `(8s，整段≤32 字；分行旁白每多一行约少 4 字)`) — write inside it. The budget comes from `video_dsl/runtime/narration_budget.py` (≈4.5 zh chars/s at 1.0× speed, ~0.9s pause per extra narration line, 1.5s tail per scene unless the template declares `capabilities.defaultTailPadSec`). If you go over, report the longer estimated length at script confirmation; `prepare_video_assets` also warns when the estimate exceeds `meta.targetDuration` by more than 30%.
 4. **One complete thought per line — do NOT pre-split at subtitle width.** Separate lines inside `audio.narration.text` with `\n`, and put **one full clause or sentence** on each line (roughly 15–30 Chinese characters, or an equivalent number of English words). A `\n` is a hard cut in the *audio*: TTS treats each line as its own segment and returns a timestamp for it, so lines should fall where a human would actually pause for breath.
 
    **Do not cut mid-phrase to make lines "subtitle-sized".** The renderer splits each line into on-screen subtitles itself, and it does that better than you can from the text alone: it measures the real glyph widths for the actual font size and frame (`HNSW` is not as wide as four Chinese characters), knows how many characters fit on one line of *this* template and aspect ratio, and picks cut points by punctuation strength (sentence end → colon → comma → enumeration comma → space). It also guarantees no wrapping. Pre-splitting takes all of that away and just makes the captions choppy.
@@ -524,4 +525,4 @@ prefix and version — not a short alias:
 |------|---------|
 | `gen_script.py` | Core script — produces the Video DSL JSON from a topic. |
 
-The authoritative per-template contract is the registry's `template.json` (`llmHint` + `customPayloadSchema` + `slideSchemas` + `slotMapping`) — everything you need to author against is in there, so read it rather than inferring field names from the template's name or from another template. `template_registry list_examples=true` lists local reference DSLs when any exist, but that directory does not ship — see *DSL schema* above.
+The authoritative per-template contract is the registry's `template.json` (`llmHint` + `customPayloadSchema` + `slideSchemas` + `slotMapping`) — everything you need to author against is in there, so read it rather than inferring field names from the template's name or from another template.