@remixmate/cli 0.1.1 → 0.9.1

package/skills/gen-voice/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-voice",
   "repoName": "agent-skill-media-maker",
   "skillId": "338",
-  "version": "V6",
+  "version": "V7",
   "skillDescription": "语音合成（TTS）技能，将文字转为语音音频（调用 ab-api /tool/minimaxT2aV2，基于 Minimax TTS）。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- AI 配音、语音合成、文字转语音、TTS、文本转音频、生成语音\n- 使用 minimax 语音合成\n- 用户想要将一段文字朗读出来、生成音频\n\n即使用户没有明确说「使用 AI」，只要他们想要将文字转为语音，也要使用本 skill。"
 }

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

@@ -2,6 +2,7 @@
   "name": "prepare-video-assets",
   "toolName": "prepare_video_assets",
   "tier": "orchestration",
+  "category": "authoring",
   "title": "Video Asset Preparation",
   "description": "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. This is Phase 1 of the two-phase video pipeline; Phase 3 (Remotion render) lives in render_video.",
   "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"],

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

@@ -121,11 +121,12 @@ def start_render(
     base_url: Optional[str] = None,
     timeout: float = 120.0,
     conversation_id: Optional[str] = None,
+    path: str = "/render",
 ) -> str:
-    """POST /render；返回 taskId。"""
+    """POST <path>（默认 /render，私有模板动态渲染传 /renderDraft）；返回 taskId。"""
     result = _request(
         "POST",
-        "/render",
+        path,
         private_token=private_token,
         payload=payload,
         base_url=base_url,
@@ -135,7 +136,7 @@ def start_render(
     data = _check_code(result)
     task_id = data.get("taskId")
     if not task_id:
-        raise RemoteRenderError(f"/render did not return a taskId: {result}")
+        raise RemoteRenderError(f"{path} did not return a taskId: {result}")
     return str(task_id)
 
 
@@ -150,8 +151,9 @@ def poll_render(
     max_consecutive_errors: int = 5,
     on_progress: Optional[Callable[[dict], None]] = None,
     adaptive_interval: bool = False,
+    status_path: str = "/renderStatus",
 ) -> dict:
-    """POST /renderStatus 轮询直到完成/失败/超时。
+    """POST <status_path>（默认 /renderStatus，私有模板传 /renderDraftStatus）轮询直到完成/失败/超时。
 
     成功时返回 data dict（至少包含 fileUrl），否则抛 RemoteRenderError。
     on_progress 回调在每次成功请求后触发，参数为完整 data dict。
@@ -170,13 +172,13 @@ def poll_render(
         if elapsed > timeout:
             raise RemoteRenderError(
                 f"remote render polling timed out (waited {elapsed:.0f}s, taskId={task_id}); "
-                f"the job may still be running on the backend — query /renderStatus later"
+                f"the job may still be running on the backend — query {status_path} later"
             )
 
         try:
             result = _request(
                 "POST",
-                "/renderStatus",
+                status_path,
                 private_token=private_token,
                 payload={"taskId": task_id},
                 base_url=base_url,
@@ -201,7 +203,7 @@ def poll_render(
                 body = exc.read().decode("utf-8")
             except Exception:
                 pass
-            raise RemoteRenderError(f"HTTP {exc.code} /renderStatus: {body[:200]}") from exc
+            raise RemoteRenderError(f"HTTP {exc.code} {status_path}: {body[:200]}") from exc
 
         consecutive_errors = 0
 

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

@@ -1607,26 +1607,73 @@ def render_with_remote_api(
         template_id = render_plan.get("templateId", "")
         cover_composition_id = resolve_cover_composition_id(template_id)
 
-    payload = {
-        "compositionId": composition_id,
-        "renderConfig": config,
-        "inputProps": input_props,
-        "uploadTitle": effective_title,
-    }
-    if cover_composition_id:
-        payload["coverCompositionId"] = cover_composition_id
+    # ─── 私有模板路由 ────────────────────────────────────────────────────
+    # 仅【用户私有模板】(isBuiltin=false 且带 sourceOssKey) 源码在 OSS、不在
+    # ab-render 启动 bundle，需走动态渲染：presignSource 取临时 GET URL → /renderDraft。
+    # 内置模板即使带 sourceOssKey（builtin-template-registry 回填，仅服务
+    # derive_template 派生），渲染仍走 ab-render 预构建的 /render，绝不走 /renderDraft，
+    # 否则会用 OSS 上的旧快照 + DraftMainVideo 复刻渲染，与生产 MainVideo 漂移。
+    source_oss_key = None
+    template_id = render_plan.get("templateId", "")
+    if template_id:
+        try:
+            from registry_loader import get_template  # type: ignore
+            _meta = get_template(template_id)
+            if _meta and not _meta.get("isBuiltin"):
+                source_oss_key = _meta.get("sourceOssKey")
+        except Exception:
+            source_oss_key = None
+
+    if source_oss_key:
+        import render_job_client  # type: ignore
+        try:
+            src = render_job_client.presign_template_source(template_id, private_token)
+            tarball_url = src.get("tarballUrl")
+            if not tarball_url:
+                raise RuntimeError(f"presignSource 未返回 tarballUrl: {src}")
+        except Exception as exc:
+            LogPrint(f"❌ presignSource failed for private template {template_id}: {exc}", file=sys.stderr)
+            render_plan["status"] = "failed"
+            render_plan["errors"].append({
+                "phase": "render",
+                "message": f"presignSource failed: {exc}",
+                "timestamp": now_iso(),
+            })
+            return False
+        payload = {
+            "tarballUrl": tarball_url,
+            "inputProps": input_props,
+            "upload": True,
+            "uploadTitle": effective_title,
+        }
+        render_path = "/renderDraft"
+        status_path = "/renderDraftStatus"
+    else:
+        payload = {
+            "compositionId": composition_id,
+            "renderConfig": config,
+            "inputProps": input_props,
+            "uploadTitle": effective_title,
+        }
+        if cover_composition_id:
+            payload["coverCompositionId"] = cover_composition_id
+        render_path = "/render"
+        status_path = "/renderStatus"
 
     total_frames = config.get("totalFrames", 0)
     LogPrint(f"🎬 Submitting remote render task...", file=sys.stderr)
-    LogPrint(f"   Composition: {composition_id}", file=sys.stderr)
-    if cover_composition_id:
+    if source_oss_key:
+        LogPrint(f"   Private template (OSS dynamic bundle): {template_id}", file=sys.stderr)
+    else:
+        LogPrint(f"   Composition: {composition_id}", file=sys.stderr)
+    if cover_composition_id and not source_oss_key:
         LogPrint(f"   Cover: {cover_composition_id}", file=sys.stderr)
     LogPrint(f"   size: {config.get('width')}x{config.get('height')}", file=sys.stderr)
     LogPrint(f"   total frames: {total_frames}", file=sys.stderr)
     sys.stderr.flush()
 
     try:
-        task_id = remote_renderer_client.start_render(payload, private_token=private_token, conversation_id=conversation_id)
+        task_id = remote_renderer_client.start_render(payload, private_token=private_token, conversation_id=conversation_id, path=render_path)
     except Exception as exc:
         LogPrint(f"❌ remote render submission failed: {exc}", file=sys.stderr)
         render_plan["status"] = "failed"
@@ -1686,6 +1733,7 @@ def render_with_remote_api(
             interval=poll_interval,
             on_progress=_on_progress,
             adaptive_interval=True,
+            status_path=status_path,
         )
     except Exception as exc:
         LogPrint(f"❌ remote render polling failed: {exc}", file=sys.stderr)
@@ -1904,13 +1952,22 @@ Examples:
         LogPrint(f"📋 loaded existing RenderPlan: {args.render_plan}", file=sys.stderr)
     else:
         if not args.dsl and not args.dsl_json:
-            LogPrint("❌ pass --dsl or --dsl-json (with --template-id), or --render-plan / --job-id", file=sys.stderr)
-            parser.print_help()
+            LogPrint(
+                "❌ render_video needs a DSL source. You provided neither --dsl/--dsl-json "
+                "nor --render-plan/--job-id.\n"
+                "   Typical flow: 1) gen_script → DSL skeleton  2) prepare_video_assets "
+                "(returns a job_id)  3) render_video with job_id=<int>.\n"
+                "   Or pass the DSL inline: render_video --dsl-json '<json>' --template-id <id>.",
+                file=sys.stderr,
+            )
             sys.exit(1)
 
         if not args.template_id:
-            LogPrint("❌ pass --template-id (--binding is no longer supported; binding is now computed in-memory from --template-id)", file=sys.stderr)
-            parser.print_help()
+            LogPrint(
+                "❌ render_video needs --template-id when rendering from --dsl/--dsl-json "
+                "(binding is computed in-memory from the template id; --binding is no longer supported).",
+                file=sys.stderr,
+            )
             sys.exit(1)
 
         # 解析 DSL：优先 --dsl-json（inline），其次 --dsl（文件路径）

package/skills/render-video/skill.json

@@ -2,6 +2,7 @@
   "name": "render-video",
   "toolName": "render_video",
   "tier": "orchestration",
+  "category": "authoring",
   "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"],

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V15",
+  "version": "V18",
   "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-registry/README.md

@@ -4,30 +4,29 @@ CLI 暴露面是「列出可用模板」(`--list-templates`)。把 Video DSL 场
 
 ## 模板数据来源
 
-模板元数据维护在独立仓库 **template-library**。本 skill 通过 `scripts/registry_loader.py` 按以下顺序解析:
+模板元数据维护在独立仓库 **template-library**，发布到 ab-api，运行时由本 skill 通过 `scripts/registry_loader.py` 从 **单一数据源（ab-api HTTP）** 加载：
 
-| 优先级 | 来源 | 触发条件 | 适用场景 |
-|---|---|---|---|
-| 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_URL`（ab-api 接口） | 环境变量非空 + `PRIV_TOKEN` 有效 | 指定后端 |
+| 派生默认 URL `<MM_API_BASE_URL>/remotionTemplate/registry` | `VIDEO_TEMPLATE_REGISTRY_URL` 未设置 | 默认（含独立安装 codex / `npm i -g`，默认 `http://localhost:2999/api`） |
+
+只从 ab-api 取数，是为了避免「本地文件 / monorepo 源码 / 数据库」多源并存导致的不一致——私有 / 多租户模板只存在于 ab-api，本地源永远不全。默认 URL **内置在 remixmate-cli 自身**（按 CLI 后端约定 `MM_API_BASE_URL` 推导），不再依赖 ab-agent 等宿主在 spawn 时注入，独立运行即可找到 registry。指向你自己的 ab-api 只需设 `MM_API_BASE_URL`（或直接设 `VIDEO_TEMPLATE_REGISTRY_URL`）并配置 `PRIV_TOKEN`。
 
-`VIDEO_TEMPLATE_REGISTRY_PREFER_LOCAL=1` 开启后,#3 抢在 #2 之前——本地源码改动立即生效,不被 HTTP 缓存覆盖。
+HTTP 拉取带磁盘缓存（TTL + ETag/304）；瞬时故障时降级复用同一 URL 的上一份缓存（同源容错，非第二个数据源），无缓存则直接报错。
 
 ab-api 响应包装格式 `{code, msg, data}` 由 `registry_loader._fetch_http` 透明拆封;静态 JSON endpoint 也支持(直接返回 registry 文档)。
 
-> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包消费 registry —— 该路径已被 ab-api HTTP 取代,但保留 monorepo 文件路径作为兜底。
+> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包 / monorepo 文件消费 registry —— 这些本地来源已移除，运行时只走 ab-api HTTP。monorepo 文件仅供 `check_contracts.py` / `sync_registry.py` 等 monorepo-only 维护脚本使用。
 
 ## 新增模板工作流
 
-新增模板**不需要改 ab-skill / template-registry 代码**:
+新增模板**不需要改 remixmate / template-registry 代码**:
 
 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 的源码改动立即生效,不依赖发布周期。
+4. remixmate 端无需更新——下一次 `--list-templates` 即可看到新模板。
 
 ## 契约一致性
 
@@ -45,7 +44,7 @@ python3 <SkillDir>/scripts/check_contracts.py
 
 ## 共享 Python 模块
 
-`scripts/` 是 ab-skill 内**跨 skill 共享 Python 代码**的约定位置。当前住户:
+`scripts/` 是 remixmate 内**跨 skill 共享 Python 代码**的约定位置。当前住户:
 
 | 模块 | 谁在用 | 作用 |
 |---|---|---|

package/skills/template-registry/SKILL.md

@@ -23,9 +23,9 @@ Stores every video-template definition, loads a template by **template-id**, and
 
 ## Template registry
 
-Template metadata lives in the standalone **template-library** monorepo and ships via the `@ab-templates/metadata` package.
+Template metadata is authored in the standalone **template-library** monorepo, published to ab-api, and served to the CLI over HTTP. At runtime template-registry loads the registry from a single source — the ab-api endpoint (see the env table below) — which returns every template definition (full slotMapping, compositions, etc.) including the caller's private/tenant templates.
 
-template-registry reads `template-library/packages/metadata/registry.json` to load every template definition (with the full slotMapping, compositions, etc.).
+> The `template-library/packages/metadata/registry.json` file below is the authoring layout in the monorepo. It is **not** read at runtime anymore; only monorepo-only maintenance tooling (`check_contracts.py`, `sync_registry.py`) touches it directly.
 
 ```
 template-library/packages/
@@ -62,22 +62,21 @@ The skill itself only reads the registry; whether a token is needed depends on t
 
 | 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_URL` | ab-api endpoint returning the registry (the single source of truth). | derived from `MM_API_BASE_URL` |
+| `MM_API_BASE_URL` | ab-api base URL the CLI talks to. When `VIDEO_TEMPLATE_REGISTRY_URL` is unset, the registry endpoint is derived as `<base>/remotionTemplate/registry`. | `http://localhost:2999/api` |
+| `PRIV_TOKEN` | Sent as `X-Priv-Token` when hitting the registry endpoint. Falls back to `~/.config/remixmate/credentials.json`. | 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.
+Resolution (single source — see `scripts/registry_loader.py` for the canonical implementation):
+the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDEO_TEMPLATE_REGISTRY_URL`, otherwise `<MM_API_BASE_URL>/remotionTemplate/registry` (default `http://localhost:2999/api/...`). There is no local-file / monorepo / PREFER_LOCAL fallback: those multi-source paths were removed to avoid registry skew (private/multi-tenant templates only exist on ab-api). On a transient HTTP failure the loader degrades to the on-disk cache of the same URL; with no cache it fails loud. A standalone install (Codex / `npm i -g`) just needs `MM_API_BASE_URL` (or `VIDEO_TEMPLATE_REGISTRY_URL`) pointed at your ab-api plus a valid `PRIV_TOKEN`.
 
 ## Steps
 
-> This skill is a Python skill of the ab-skill CLI (`entry.type: python` → `scripts/list_templates.py`). The agent tool name `template_registry` is the only entry; locally reproduce via `ab-skill template-registry --list-templates`. The list command delegates to `scripts/registry_loader.py` — the same loader (with caching + stable/beta gating) that `render-video` and `gen-script` import in-process, so there is a single registry-reading implementation.
+> This skill is a Python skill of the remixmate CLI (`entry.type: python` → `scripts/list_templates.py`). The agent tool name `template_registry` is the only entry; locally reproduce via `remixmate template-registry --list-templates`. The list command delegates to `scripts/registry_loader.py` — the same loader (with caching + stable/beta gating) that `render-video` and `gen-script` import in-process, so there is a single registry-reading implementation.
 >
 > The Python binding logic that maps DSL → TemplateBinding lives in `scripts/match_template.py` but is **not exposed as a CLI** — it is only consumed as a Python library by `render-video`'s `render_video.py` via `import match_template`.
 
-1. **List available templates**: run `ab-skill template-registry --list-templates` to view the templates in the registry along with their supported aspect ratios / style tags, and decide which `templateId` to pick.
+1. **List available templates**: run `remixmate template-registry --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.
 
@@ -86,7 +85,7 @@ Resolution order (see `scripts/registry_loader.py` for the canonical implementat
 ### List available templates
 
 ```bash
-ab-skill template-registry --list-templates
+remixmate template-registry --list-templates
 ```
 
 ### Sync the registry cache (optional, used for offline / LLM prompt)
@@ -233,4 +232,4 @@ With `picture-book-en`, **narration reads English only, never Chinese**:
 
 - **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.
+- **Empty template registry**: confirm the ab-api registry endpoint (`VIDEO_TEMPLATE_REGISTRY_URL`, or the one derived from `MM_API_BASE_URL`) is reachable and that `PRIV_TOKEN` is valid.

package/skills/template-registry/scripts/list_templates.py

@@ -15,12 +15,18 @@ in-process by ``render-video``; it is intentionally NOT exposed as a CLI verb.
 
 Flags:
   --list-templates                 (accepted; listing is the only verb)
+  --list-examples                  list *.dsl.json / *.binding.json reference
+                                   examples grouped by templateId (consumed
+                                   by downstream agents that want to read a
+                                   template's reference shape before producing
+                                   new DSL)
   --filter-tag <substr>            keep templates whose styleTags match
   --filter-aspect <ratio>          keep templates supporting this aspect ratio
   --filter-language <zh|en|...>    keep templates tagged with this content lang
                                    (templates with no contentLanguage are kept)
   --include-beta                   also show beta templates (else stable-only)
-  --json-output                    emit {"templates": [...]} instead of a table
+  --json-output                    emit {"templates": [...]} or {"examples": [...]}
+                                   instead of a table
 """
 
 from __future__ import annotations
@@ -29,6 +35,7 @@ import argparse
 import json
 import os
 import sys
+from pathlib import Path
 
 # When run as `python3 <skillDir>/scripts/list_templates.py`, this script's own
 # directory is sys.path[0], so the sibling shared modules import directly.
@@ -61,17 +68,69 @@ def _status_of(tpl: dict) -> str:
     return "stable"
 
 
+# ----- Examples discovery (--list-examples) ---------------------------------
+#
+# Examples live under <SkillDir>/video_dsl/schema/examples/ as `*.dsl.json` and
+# `*.binding.json` files. Naming convention (per gen-script SKILL.md) is
+# `<templateId>.dsl.json` / `<templateId>.binding.json`, occasionally with
+# variant suffixes (`<templateId>.<variant>.dsl.json`).
+#
+# We do not parse the JSON content here (downstream agents read the raw files
+# they care about); we just enumerate paths so the agent doesn't have to guess
+# the directory layout. When the directory does not exist (e.g. inside a slim
+# package distribution), we return an empty list — non-fatal.
+
+# Resolve the examples directory relative to this script.
+#   <skill>/scripts/list_templates.py  →  <skill>/video_dsl/schema/examples/
+_EXAMPLES_DIR = Path(__file__).resolve().parent.parent / "video_dsl" / "schema" / "examples"
+
+
+def _collect_examples() -> list[dict]:
+    if not _EXAMPLES_DIR.is_dir():
+        return []
+    by_template: dict[str, dict] = {}
+    for entry in sorted(_EXAMPLES_DIR.iterdir()):
+        if not entry.is_file():
+            continue
+        name = entry.name
+        # Recognise *.dsl.json / *.binding.json
+        if name.endswith(".dsl.json"):
+            kind = "dsl"
+            base = name[: -len(".dsl.json")]
+        elif name.endswith(".binding.json"):
+            kind = "binding"
+            base = name[: -len(".binding.json")]
+        else:
+            continue
+        # Variant: 'foo.bar.dsl.json' → templateId='foo', variant='bar'
+        if "." in base:
+            template_id, variant = base.split(".", 1)
+        else:
+            template_id, variant = base, None
+        bucket = by_template.setdefault(template_id, {"templateId": template_id, "files": []})
+        bucket["files"].append({
+            "kind": kind,
+            "variant": variant,
+            "path": str(entry.relative_to(_EXAMPLES_DIR.parent.parent.parent)),  # relative to skill dir
+            "absolutePath": str(entry),
+            "sizeBytes": entry.stat().st_size,
+        })
+    return list(by_template.values())
+
+
 def main() -> None:
     ap = argparse.ArgumentParser(
         description="List available video templates from the registry.",
     )
     ap.add_argument("--list-templates", action="store_true",
                     help="List every available template (the only CLI verb).")
+    ap.add_argument("--list-examples", action="store_true",
+                    help="List reference examples (*.dsl.json / *.binding.json) grouped by templateId.")
     ap.add_argument("--filter-tag", help="Keep templates whose styleTags match this substring.")
     ap.add_argument("--filter-aspect", help="Keep templates supporting this aspect ratio (e.g. 9:16).")
     ap.add_argument("--filter-language", help="Keep templates tagged with this content language (zh|en|...).")
     ap.add_argument("--include-beta", action="store_true", help="Also show beta templates (default: stable only).")
-    ap.add_argument("--json-output", action="store_true", help='Emit {"templates": [...]} JSON instead of a table.')
+    ap.add_argument("--json-output", action="store_true", help='Emit JSON ({"templates":[...]} or {"examples":[...]}) instead of a table.')
     args = ap.parse_args()
 
     # --include-beta flips registry_loader's documented status gate via env, so
@@ -79,6 +138,32 @@ def main() -> None:
     if args.include_beta:
         os.environ["ENABLE_BETA_TEMPLATES"] = "1"
 
+    # ----- examples mode -----------------------------------------------------
+    if args.list_examples:
+        examples = _collect_examples()
+        if args.json_output:
+            print(json.dumps({"examples": examples}, ensure_ascii=False))
+            return
+        if not examples:
+            print(
+                f"⚠️  No examples found under {_EXAMPLES_DIR}.\n"
+                "   This package may have shipped without reference examples; "
+                "check the cli source repo or upgrade @remixmate/cli.",
+            )
+            return
+        print(f"\n{'Template ID':<28} Files")
+        print(f"{'-' * 28} {'-' * 60}")
+        for bucket in examples:
+            tid = str(bucket["templateId"])[:28].ljust(28)
+            files = bucket["files"]
+            for i, f in enumerate(files):
+                marker = tid if i == 0 else " " * 28
+                kind = f["kind"]
+                variant = f"@{f['variant']}" if f.get("variant") else ""
+                print(f"{marker} [{kind}{variant}] {f['path']} ({f['sizeBytes']}B)")
+        print(f"\n{sum(len(b['files']) for b in examples)} example file(s) across {len(examples)} template(s)")
+        return
+
     try:
         templates = load_visible_templates()
     except RuntimeError as exc: