@remixmate/cli 0.1.0

package/skills/render-video/scripts/upload_video.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+视频上传工具 - 将本地 MP4 文件通过 multipart/form-data 上传到 ab-api，
+获取可用 URL（直传阿里云 OSS，同步返回）。
+
+默认行为:
+  读取本地文件，以 multipart/form-data 形式 POST 到
+  `<MM_API_BASE_URL>/file/uploadMediaFile`，解析响应 JSON，输出 fileUrl。
+
+用法:
+  python3 upload_video.py --file output/video.mp4
+  python3 upload_video.py --file output/video.mp4 --title "我的视频"
+  python3 upload_video.py --file output/video.mp4 --json-output
+
+环境变量:
+  MM_API_BASE_URL - API 根地址（默认 MM_API_BASE_URL 环境变量或 http://localhost:3001/api）
+
+注意:
+  - `uploadMediaFile` 接口视频大小限制 ≤ 50MB，音频 ≤ 15MB
+  - 进度信息输出到 stderr，最终 URL 输出到 stdout（最后一行）
+"""
+
+import argparse
+import http.client
+import json
+import mimetypes
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+# DEFAULT_API_BASE_URL = "http://localhost:3001/api"
+
+
+def _guess_content_type(file_path: str) -> str:
+    ctype, _ = mimetypes.guess_type(file_path)
+    return ctype or "application/octet-stream"
+
+
+def _build_multipart_body(file_path: str, title: str = None) -> (bytes, str):
+    """
+    手动构建 multipart/form-data body。
+
+    返回 (body_bytes, content_type_header)。
+    """
+    boundary = "----MediaMakerBoundary" + uuid.uuid4().hex
+    crlf = b"\r\n"
+    parts = []
+
+    # title 字段（可选）
+    if title:
+        parts.append(("--" + boundary).encode("utf-8"))
+        parts.append(b'Content-Disposition: form-data; name="title"')
+        parts.append(b"")
+        parts.append(title.encode("utf-8"))
+
+    # file 字段
+    file_name = os.path.basename(file_path)
+    content_type = _guess_content_type(file_path)
+    with open(file_path, "rb") as f:
+        file_data = f.read()
+
+    parts.append(("--" + boundary).encode("utf-8"))
+    parts.append(
+        (
+            'Content-Disposition: form-data; name="file"; filename="%s"'
+            % file_name
+        ).encode("utf-8")
+    )
+    parts.append(("Content-Type: %s" % content_type).encode("utf-8"))
+    parts.append(b"")
+    parts.append(file_data)
+
+    # 结尾 boundary
+    parts.append(("--" + boundary + "--").encode("utf-8"))
+    parts.append(b"")
+
+    body = crlf.join(parts)
+    ct_header = "multipart/form-data; boundary=%s" % boundary
+    return body, ct_header
+
+
+def upload_media_file(
+    file_path: str,
+    api_base_url: str = None,
+    title: str = None,
+    timeout: int = 600,
+) -> dict:
+    """
+    将本地媒体文件以 multipart/form-data 形式上传到 ab-api。
+
+    返回服务端 data 字段，通常形如 {"fileUrl": "https://..."}。
+    上传失败会抛出异常。
+    """
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"file not found: {file_path}")
+
+    api_base_url = (api_base_url or os.environ.get("MM_API_BASE_URL") or DEFAULT_API_BASE_URL).rstrip("/")
+    url = f"{api_base_url}/file/uploadMediaFile"
+
+    file_size = os.path.getsize(file_path)
+    print(f"📤 Uploading: {file_path} ({file_size / 1024 / 1024:.2f} MB)", file=sys.stderr)
+    print(f"   target: {url}", file=sys.stderr)
+
+    body, content_type = _build_multipart_body(file_path, title=title)
+    headers = {
+        "Content-Type": content_type,
+        "Content-Length": str(len(body)),
+    }
+
+    # Use http.client directly to avoid urllib RemoteDisconnected issues
+    # with servers that return 'connection: close'
+    parsed = urllib.parse.urlparse(url)
+    host = parsed.hostname
+    port = parsed.port
+    path = parsed.path
+
+    if parsed.scheme == "https":
+        import ssl
+        conn = http.client.HTTPSConnection(host, port, timeout=timeout,
+                                           context=ssl.create_default_context())
+    else:
+        conn = http.client.HTTPConnection(host, port, timeout=timeout)
+
+    try:
+        conn.request("POST", path, body=body, headers=headers)
+        resp = conn.getresponse()
+        resp_body = resp.read().decode("utf-8")
+
+        if resp.status >= 400:
+            raise RuntimeError(f"upload failed (HTTP {resp.status}): {resp_body}")
+    except http.client.RemoteDisconnected as e:
+        raise RuntimeError(f"server disconnected: {e}") from e
+    except (OSError, Exception) as e:
+        if isinstance(e, RuntimeError):
+            raise
+        raise RuntimeError(f"network error: {e}") from e
+    finally:
+        conn.close()
+
+    try:
+        result = json.loads(resp_body)
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"failed to parse response: {resp_body}") from e
+
+    # ab-api shared response: { code: 0, data: {...}, msg: "..." }
+    if isinstance(result, dict) and result.get("code") not in (0, 200):
+        raise RuntimeError(f"server returned an error: code={result.get('code')}, msg={result.get('msg')}")
+
+    data = result.get("data") if isinstance(result, dict) else None
+    if not isinstance(data, dict) or not data.get("fileUrl"):
+        raise RuntimeError(f"response is missing fileUrl: {resp_body}")
+
+    print(f"✅ uploaded: {data['fileUrl']}", file=sys.stderr)
+    return data
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Upload a media file to ab-api / Alibaba Cloud OSS")
+    parser.add_argument("--file", required=True, help="Local file path")
+    parser.add_argument("--title", default=None, help="File title (optional, defaults to filename)")
+    parser.add_argument(
+        "--api-base-url",
+        default=None,
+        help="API root URL (defaults to MM_API_BASE_URL env var or http://localhost:3001/api)",
+    )
+    parser.add_argument("--timeout", type=int, default=600, help="Upload timeout in seconds (default 600)")
+    parser.add_argument("--json-output", action="store_true", help="Emit the full response as JSON on stdout")
+
+    args = parser.parse_args()
+
+    try:
+        data = upload_media_file(
+            file_path=args.file,
+            api_base_url=args.api_base_url,
+            title=args.title,
+            timeout=args.timeout,
+        )
+    except Exception as e:
+        print(f"❌ {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json_output:
+        print(json.dumps(data, ensure_ascii=False))
+    else:
+        # 最终 URL 输出到 stdout（最后一行），方便其他脚本捕获
+        print(data["fileUrl"])
+
+
+if __name__ == "__main__":
+    main()

package/skills/render-video/skill.json

@@ -0,0 +1,21 @@
+{
+  "name": "render-video",
+  "toolName": "render_video",
+  "tier": "orchestration",
+  "title": "Remotion Video Renderer",
+  "description": "Loads a persisted RenderPlan by job_id and drives the Remotion engine to produce the final video. Assets must already be generated via prepare_video_assets — this skill never resolves or regenerates assets.",
+  "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "MM_BACKEND_API_URL", "AGENT_NAME", "REMOTION_RENDER_API_URL", "REMOTION_RENDER_MODE", "REMOTION_OUTPUT_DIR", "ASSET_CACHE_DIR"],
+  "scriptPath": "scripts/render_video.py",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "job_id": { "type": "number", "minimum": 1, "description": "Render job id (positive integer, e.g. 8). This is the integer N parsed from prepare_video_assets's stdout line '📦 render job jobId: N' (also tolerated: legacy zh '📦 渲染任务 jobId: N'). Never pass 0, a placeholder string, or descriptive text." },
+      "save_job": { "type": "boolean", "description": "Persist the render Manifest back to the database under the same jobId (default true). Auto-degrades to false when PRIV_TOKEN is missing. Pass false to opt out explicitly." },
+      "upload_title": { "type": "string", "description": "Upload title for the resulting video file. Defaults to the local output filename." },
+      "no_upload": { "type": "boolean", "description": "Skip the upload step. Only effective for local rendering; remote rendering uploads server-side." },
+      "renderer": { "type": "string", "enum": ["local", "remote"], "description": "Render mode: local runs the Remotion CLI on this host; remote calls the standalone remotion-renderer service. Defaults to REMOTION_RENDER_MODE." },
+      "render_plan": { "type": "string", "description": "Existing RenderPlan file path. Local / single-user fallback used only when job_id is unavailable; prefer job_id." }
+    },
+    "required": ["job_id"]
+  }
+}

package/skills/render-video/version.json

@@ -0,0 +1,7 @@
+{
+  "skillName": "render-video",
+  "repoName": "agent-skill-media-maker",
+  "skillId": "473",
+  "version": "V15",
+  "skillDescription": "Final-render skill (Phase 3 of the two-phase video pipeline). Loads a persisted RenderPlan by job_id and drives Remotion to produce the final video. Assets must already be generated via prepare_video_assets."
+}

package/skills/template-bind/README.md

@@ -0,0 +1,63 @@
+# template-bind
+
+CLI 暴露面是「列出可用模板」(`--list-templates`)。把 Video DSL 场景绑到具体模板 / 生成 TemplateBinding 的 Python 逻辑由本 skill 提供为**库**(`scripts/match_template.py`),被 `render-video` / `prepare-video-assets` 通过 `sys.path` 内联 import,**没有独立 CLI**。
+
+## 模板数据来源
+
+模板元数据维护在独立仓库 **template-library**。本 skill 通过 `scripts/registry_loader.py` 按以下顺序解析:
+
+| 优先级 | 来源 | 触发条件 | 适用场景 |
+|---|---|---|---|
+| 1 | `VIDEO_TEMPLATE_REGISTRY` 指向的本地 JSON 文件 | 环境变量非空 | CI / 离线 / pinned 调试 |
+| 2 | `VIDEO_TEMPLATE_REGISTRY_URL`(ab-api 接口) | URL 设置 + `PRIV_TOKEN` 有效 | **生产** —— 多租户隔离由 ab-api 做 |
+| 3 | monorepo `template-library/packages/metadata/registry.json` | 本地源码可见 | 本地 dev / 单仓部署 |
+
+`VIDEO_TEMPLATE_REGISTRY_PREFER_LOCAL=1` 开启后,#3 抢在 #2 之前——本地源码改动立即生效,不被 HTTP 缓存覆盖。
+
+ab-api 响应包装格式 `{code, msg, data}` 由 `registry_loader._fetch_http` 透明拆封;静态 JSON endpoint 也支持(直接返回 registry 文档)。
+
+> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包消费 registry —— 该路径已被 ab-api HTTP 取代,但保留 monorepo 文件路径作为兜底。
+
+## 新增模板工作流
+
+新增模板**不需要改 ab-skill / template-bind 代码**:
+
+1. 在 template-library 仓库定义新模板(`template.json` + 组件代码)。
+2. template-library CI 校验 schema + 契约。
+3. 合并后 template-library 的发布流水线将新 registry 推到 ab-api。
+4. ab-skill 端无需更新——下一次 `--list-templates` 即可看到新模板。
+
+本地调试时可通过 `VIDEO_TEMPLATE_REGISTRY_PREFER_LOCAL=1` 让 template-library 的源码改动立即生效,不依赖发布周期。
+
+## 契约一致性
+
+template-library 仓库内置契约验证器,确保:
+
+- 每个 `template.json` 中引用的 `compositionId` 都存在于 remotion-renderer 的 `manifest.ts`
+- manifest 中的每个 compositionId 都被某个 `template.json` 引用
+- 所有 `template.json` 通过 JSON Schema 校验
+
+本地可运行 `check_contracts.py` 做跨仓库一致性检查(从 monorepo `<repo>/remotion-renderer/src/core/compositions/manifest.ts` 读 manifest):
+
+```bash
+python3 <SkillDir>/scripts/check_contracts.py
+```
+
+## 共享 Python 模块
+
+`scripts/` 是 ab-skill 内**跨 skill 共享 Python 代码**的约定位置。当前住户:
+
+| 模块 | 谁在用 | 作用 |
+|---|---|---|
+| `template_paths.py` | registry_loader / template_binder / gen-script / check_contracts | 统一计算 monorepo / template-library 路径,代替 4 个 caller 各自数 `..` |
+| `registry_loader.py` | template-bind handler / match_template / render-video / gen-script / dsl_validator | 加载 registry(HTTP + cache + file) |
+| `match_template.py` | render-video(`auto_bind_template`) | DSL → TemplateBinding 算法 |
+| `render_job_client.py` | render-video / export-jianying | ab-api renderJob HTTP 客户端 |
+| `check_contracts.py` | 维护脚本 | template-library ↔ remotion-renderer 契约校验 |
+| `sync_registry.py` | 维护脚本 | 把 registry 摘要落盘供 LLM prompt 使用 |
+
+sibling skill 通过 `sys.path.insert(0, "<…>/template-bind/scripts")` 然后直接 `import` 模块名,模式见 `render_video.py` 顶部的"Single sys.path setup"段。
+
+## 详细使用说明
+
+完整的 CLI 参数、Props 提取规则、多项卡片配音写法等操作细节请参阅 [SKILL.md](./SKILL.md)。

package/skills/template-bind/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: template-bind
+description: |
+  Video-template registry and binding skill. Stores every video-template definition and produces a TemplateBinding for a given template id.
+
+  Use this skill as soon as the user mentions any of these intents:
+  - View available templates / list every template
+  - Bind a template to a DSL (a template-id must be supplied)
+
+  Also use this skill whenever the agent has a Video DSL and needs to produce a TemplateBinding.
+triggers:
+  - View available templates / list every template
+  - Bind a template to a DSL (a template-id must be supplied)
+  - Agent has a Video DSL and needs a TemplateBinding
+---
+
+# Video Template Registry & Binding Skill
+
+Stores every video-template definition, loads a template by **template-id**, and produces a **TemplateBinding** for a **Video DSL**, mapping each scene to a template slot.
+
+## Core concepts
+
+- **Template Manifest**: template metadata describing supported aspect ratios, durations, styles, and scene patterns.
+- **TemplateBinding**: the binding result — maps each DSL scene to a template slot + Remotion Composition.
+- **Template registry**: `registry.json` shipped by the `@ab-templates/metadata` package (housed in the template-library repo).
+
+## Template registry
+
+Template metadata lives in the standalone **template-library** monorepo and ships via the `@ab-templates/metadata` package.
+
+template-bind reads `template-library/packages/metadata/registry.json` to load every template definition (with the full slotMapping, compositions, etc.).
+
+```
+template-library/packages/
+├── templates/src/
+│   ├── html-slide/        # Knowledge-board template
+│   │   ├── Composition.tsx
+│   │   └── template.json
+│   ├── image-slide/       # Basic image + narration template (includes the tech variant)
+│   │   └── ...
+│   ├── picture-book-en/   # English picture-book video template
+│   │   └── ...
+│   └── screen-walkthrough/ # Screen-recording walkthrough template
+│       └── ...
+└── metadata/
+    └── registry.json      # Aggregated registry (every template.json merged)
+```
+
+## Agent behavior: image URL handling
+
+**DSL AssetRef entries must use HTTPS URLs. Local file paths are forbidden.**
+
+HTTPS URLs serve two phases:
+1. **Resolve phase** (`--resolve-only`): the agent previews already-generated images via the HTTPS URL and asks the user to confirm.
+2. **Render phase** (`--render-plan`): `render_video.py` automatically downloads each image from its HTTPS URL into `output/public-assets/` before launching Remotion, then exposes it through `--public-dir` so Remotion loads everything locally with no external network.
+
+- **Forbidden**: writing local paths like `./image_1.png` or `/tmp/image_1.png` into the DSL (the resolve phase cannot preview them and the script cannot reuse them).
+- **Forbidden**: using WebFetch against internal image domains (blocked by security policy).
+- **Allowed**: writing raw HTTPS URLs directly into the DSL AssetRef.
+- **Allowed**: downloading an image locally with `curl` when you need to read the content, but the DSL still carries the original HTTPS URL.
+
+## Authentication & environment
+
+The skill itself only reads the registry; whether a token is needed depends on the configured source.
+
+| Env var | Description | Default |
+|---------|-------------|---------|
+| `VIDEO_TEMPLATE_REGISTRY_URL` | ab-api endpoint returning the registry (production source of truth). | unset |
+| `PRIV_TOKEN` | Sent as `X-Priv-Token` when hitting `VIDEO_TEMPLATE_REGISTRY_URL`. | unset |
+| `VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD` | `POST` (default) or `GET`. POST shape matches ab-api `{code,msg,data}`. | `POST` |
+| `VIDEO_TEMPLATE_REGISTRY` | Explicit local file path — bypasses HTTP/fallback entirely (CI / pinned debug). | unset |
+| `VIDEO_TEMPLATE_REGISTRY_PREFER_LOCAL` | When `1`, monorepo `template-library/packages/metadata/registry.json` wins over HTTP. Defaults to HTTP-first. | unset |
+
+Resolution order (see `scripts/registry_loader.py` for the canonical implementation):
+`VIDEO_TEMPLATE_REGISTRY` → (optional PREFER_LOCAL fast-path to monorepo registry) → `VIDEO_TEMPLATE_REGISTRY_URL` → monorepo `template-library/packages/metadata/registry.json` fallback.
+
+## Steps
+
+> This skill is now a built-in handler of the ab-skill CLI (`entry.type: builtin`). The agent tool name `template_bind` is still the only entry; locally reproduce via `ab-skill template-bind --list-templates`.
+>
+> The Python binding logic that maps DSL → TemplateBinding lives in `scripts/match_template.py` but is **no longer exposed as a CLI** — it is only consumed as a Python library by `render-video`'s `render_video.py` via `import match_template`. The `template-bind` skill itself no longer has a Python entry script.
+
+1. **List available templates**: run `ab-skill template-bind --list-templates` to view the templates in the registry along with their supported aspect ratios / style tags, and decide which `templateId` to pick.
+2. **Write the DSL**: when generating the Video DSL, put the chosen `templateId` into `meta.templateId` (the canonical location). Use `meta.templateVariant` / `renderHints.templateVariant` to explicitly select a variant. The legacy `renderHints.templatePreference[0]` is still tolerated by `match_template.py` and `dsl_validator._pick_template_id` during transition, but new authors should write `meta.templateId`.
+3. **Produce the TemplateBinding**: there is no standalone CLI for DSL → TemplateBinding; `prepare_video_assets` calls `match_template.build_binding(template, dsl)` inline during the asset-resolution pipeline and embeds the binding into the RenderPlan it hands to the renderer — no separate `*.binding.json` file is written.
+
+> Design trade-off: collapsing the binding step into the asset-prep pipeline (no CLI, no on-disk artifact) avoids binding files drifting between the agent, the database, and the file system; any hand-edited `.binding.json` would never be consumed by the renderer anyway. For local debugging you can still `import match_template.build_binding` from Python.
+
+### List available templates
+
+```bash
+ab-skill template-bind --list-templates
+```
+
+### Sync the registry cache (optional, used for offline / LLM prompt)
+
+```bash
+python3 <SkillDir>/scripts/sync_registry.py
+```
+
+`sync_registry.py` and `check_contracts.py` are **maintenance helpers** for template-library, not skill entry points. Keep invoking them directly via `python3`.
+
+### Verify template / Remotion contract consistency
+
+```bash
+python3 <SkillDir>/scripts/check_contracts.py
+```
+
+### Build a binding locally (debug only, not part of the render pipeline)
+
+```python
+import json, sys
+sys.path.insert(0, "<SkillDir>/scripts")
+from match_template import build_binding, load_full_template, load_registry
+
+dsl = json.load(open("my-video.dsl.json"))
+template = next(t for t in load_registry() if t["templateId"] == "image-slide")
+binding = build_binding(load_full_template(template), dsl)
+print(json.dumps(binding, ensure_ascii=False, indent=2))
+```
+
+## Common CLI flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--list-templates` | List every available template and exit (currently the only CLI verb). | — |
+
+## Props extraction rules
+
+`match_template.py` converts each DSL scene into a `props` dict for the renderer. Extraction runs through **two paths** (highest priority first). Earlier versions also had two fallback layers that did "implicit pass-through of fields named in `requiredProps ∪ optionalProps`"; those were removed in P1.3 because the priority conflict between the allowlist and propExtractors confused authors. Only the two most explicit paths remain:
+
+### Extraction paths
+
+1. **`slotMapping[purpose].propExtractors` (explicit extraction)**
+   - Looks like `"titleText": { "from": "textLayers", "role": "headline" }`.
+   - Two forms are supported: `{ from: "textLayers", role: "..." }` matches a textLayer by role; `{ from: "a.b.c" }` reads a value from the scene by dotted path.
+2. **`customPayload` full-field pass-through (no allowlist check)**
+   - First `scene.customPayload.templateData.*` is injected; then `scene.customPayload.*` (except `templateData` itself). The latter overrides same-named values from the former, but neither can override fields already produced by propExtractors.
+   - This is the channel for templates such as html-slide that define their own sub-schema and need to pass `slideId` / `items` / `highlightMap`, etc.
+   - `scene.templateData` (without the `customPayload` wrapper) is also recognized as a `templateData` source — equivalent shorthand.
+   - **Note**: `requiredProps` / `optionalProps` are currently **just template-schema documentation**; they trigger no implicit pass-through. A field reaches `props` either through a propExtractor or through `customPayload`.
+
+### Which form to use
+
+| Field type | Form | Example |
+|---|---|---|
+| Comes from the standard DSL shape (textLayers, audio.narration.assetRef) and needs **renaming / re-routing** | declare in `propExtractors` | `titleText ← textLayers[role=headline]` |
+| Comes from a scene-level custom field whose name matches a prop directly | put it in `customPayload.<propName>` | `customPayload.slideId`, `customPayload.background`, `customPayload.bullets` |
+| Structured data internal to the template (arrays, sub-objects, etc.) | use `customPayload.templateData.*` | `templateData.concepts`, `templateData.items` (shared by feature-grid / timeline / column-compare) |
+
+**Common pitfall**: writing the same field in both `propExtractors` and `customPayload` — when they collide, `propExtractors` wins. Keep each field in exactly one place.
+
+> Historical issue: an early html-slide `point` slot declared `slideId` as `propExtractors.slideId={from:"templateData.slideId"}` and also marked it as `requiredProps`. But every existing DSL wrote `slideId` at `customPayload.slideId` (top-level, not inside templateData), so the propExtractor returned nothing and rendering fell back to the generic layout. The convention now is unified: **slideId flows through customPayload top-level pass-through**, propExtractors no longer declares it. New templates must follow the same convention.
+
+## Narration for multi-card scenes (html-slide template)
+
+When `html-slide` selects `demo-concept-overview` / `feature-grid` / `timeline` / `column-compare` (all "many-card sequential highlight" slides), you **must** use structured narration to avoid highlight/audio drift:
+
+```jsonc
+"audio": {
+  "narration": {
+    "intro": "Hermes Agent has five core capabilities.",   // optional: while this line plays, no card is highlighted
+    "items": [                                              // one line per card
+      "Persistent memory remembers everything across sessions.",
+      "More than forty built-in tools cover search, files, image generation, and more.",
+      "Plugs into Telegram, WeChat, and other channels.",
+      "Built-in task scheduling.",
+      "Extends to unlimited capabilities via the MCP protocol."
+    ],
+    "outro": "",                                            // optional
+    "assetRef": "narration-overview"
+  }
+}
+```
+
+Rules:
+- `items.length` must equal `customPayload.templateData.<concepts|items>.length` (demo-concept-overview uses `concepts`; the other three slides use `items`), otherwise `dsl_validator` rejects it.
+- Do not write `templateData.highlightMap`; `render_video.py` builds it automatically from the per-line timestamps that TTS returns.
+- If the author explicitly provides a `highlightMap`, the system keeps it as-is.
+- The legacy flat `narration.text` form still works but the author then has to keep `highlightMap` in sync with the subtitle segmentation (error-prone, not recommended).
+
+## Image sources (picture-book-en and every other template)
+
+Image assets support two source forms:
+
+### AI-generated image
+
+```jsonc
+{
+  "assetId": "img-page1",
+  "type": "image",
+  "source": "gen-image",
+  "status": "planned",
+  "payload": {
+    "prompt": "Children's picture book illustration...",
+    "ratio": "1:1"
+  }
+}
+```
+
+### User-supplied link (use an existing image directly)
+
+```jsonc
+{
+  "assetId": "img-page1",
+  "type": "image",
+  "source": "existing",
+  "status": "ready",
+  "url": "https://cdn.example.com/my-image.jpg"
+}
+```
+
+**Rules:**
+- `source: "existing"` + `status: "ready"` + top-level `url` → resolver uses the URL as-is, no generation API call.
+- `source: "gen-image"` + `status: "planned"` + `payload.prompt` → resolver calls the gen-image skill.
+- Local paths (`./image.png`, `/tmp/...`) are forbidden; HTTPS URLs only.
+- Both forms can be mixed inside the same DSL — each asset decides independently.
+
+## Picture-book narration rule (picture-book-en template)
+
+With `picture-book-en`, **narration reads English only, never Chinese**:
+
+- `audio.narration.text` and the corresponding `gen-voice` asset's `payload.text` **must contain only the English source** (ASCII letters + standard English punctuation); any CJK character or Chinese punctuation is forbidden.
+- The Chinese translation appears only on screen via `textLayers[role=subheadline].content` (mapped to `chineseTitle` / `chineseText`); it never enters TTS.
+- Layout is fixed:
+  - **Cover**: top half is the title area (English `englishTitle` on top in a large round-bold font; Chinese `chineseTitle` below in a smaller font); bottom half is the cover image / video.
+  - **Content page**: top half is the text area (English `englishText` on top in a large round-bold font; Chinese `chineseText` below); bottom half is the illustration.
+- `textLayers` role mapping is mandatory: `role=headline` carries the English text, `role=subheadline` carries the Chinese text.
+
+## Error handling
+
+- **No template specified**: the DSL must set `meta.templateId` (or, for legacy DSLs only, `renderHints.templatePreference[0]`); otherwise `prepare_video_assets` refuses to build a binding and prints the list of available templates.
+- **Malformed DSL**: validate first with `gen-script --validate` (delegates to `video_dsl.runtime.dsl_validator.validate_structural`).
+- **Empty template registry**: confirm `VIDEO_TEMPLATE_REGISTRY_URL` is reachable, or that the monorepo `template-library/packages/metadata/registry.json` fallback exists.