@remixmate/cli 0.9.61 → 0.9.63

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.61",
-  "generatedAt": "2026-09-30T06:42:11.032Z",
+  "version": "0.9.63",
+  "generatedAt": "2026-10-04T06:46:47.501Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -940,7 +940,8 @@
       "title": "Video Template Registry",
       "summary": "List all available video templates (templateId / name / aspect ratio / style tags), or read one template's full definition with template_id. Listing returns summaries; pass template_id to get that template's authoring contract (llmHint / customPayloadSchema / slotMapping / variants). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
       "triggers": [
-        "View available templates / list every template"
+        "View available templates / list every template",
+        "Watch a template's sample videos / open its detail page"
       ],
       "entry": {
         "type": "python",
@@ -993,7 +994,11 @@
           },
           "json_output": {
             "type": "boolean",
-            "description": "Emit a JSON result instead of the human-readable table: { templates: [...] } — summaries, or full definitions when template_id / full is set — or { examples: [...] }."
+            "description": "Emit a JSON result instead of the human-readable table: { templates: [...] } — summaries, or full definitions when template_id / full is set — or { examples: [...] }. When the backend serves samples, list summaries carry showcases { count, pageUrl, items } and the template_id view carries a top-level showcases map."
+          },
+          "open": {
+            "type": "string",
+            "description": "Print the web detail page URL of <templateId> (playable samples, layouts, copy-ready prompt) and open it in the browser when run from an interactive terminal. Relay the printed URL to the user."
           }
         },
         "required": []
@@ -1009,7 +1014,8 @@
           "filter_aspect",
           "filter_language",
           "include_beta",
-          "json_output"
+          "json_output",
+          "open"
         ],
         "hidden": []
       }

package/dist/project/host.d.ts

@@ -15,7 +15,7 @@
  * which would silently group takes wrong). A host that hands us nothing simply
  * degrades one rung; see resolveTakeKey().
  *
- * See docs/cli-project-binding-design.md §5.1 and appendix A.
+ * See docs/product/cli/cli-project-binding-design.md §5.1 and appendix A.
  */
 export interface HostSessionProvider {
     /** Host identifier; becomes the namespace of the grouping key. */

package/dist/project/host.js

@@ -15,7 +15,7 @@
  * which would silently group takes wrong). A host that hands us nothing simply
  * degrades one rung; see resolveTakeKey().
  *
- * See docs/cli-project-binding-design.md §5.1 and appendix A.
+ * See docs/product/cli/cli-project-binding-design.md §5.1 and appendix A.
  */
 /**
  * Adding a host is a data-only change: append a row, touch nothing else.

package/dist/project/resolve.d.ts

@@ -15,7 +15,7 @@
  * remotes, monorepos and repos with no origin — each misfire silently filing
  * output under a project the user never made.
  *
- * See docs/cli-project-binding-design.md §3.
+ * See docs/product/cli/cli-project-binding-design.md §3.
  */
 import { type HttpContext } from '../http.js';
 export interface ResolvedProject {

package/dist/project/resolve.js

@@ -15,7 +15,7 @@
  * remotes, monorepos and repos with no origin — each misfire silently filing
  * output under a project the user never made.
  *
- * See docs/cli-project-binding-design.md §3.
+ * See docs/product/cli/cli-project-binding-design.md §3.
  */
 import { mmPost } from '../http.js';
 import { readBinding } from './store.js';

package/dist/project/store.d.ts

@@ -14,7 +14,7 @@
  *                 ~/WorkBuddy/<timestamp>) would never hit a byPath entry, so a
  *                 cwd-only design silently degrades to nothing for them.
  *
- * See docs/cli-project-binding-design.md §3.
+ * See docs/product/cli/cli-project-binding-design.md §3.
  */
 export declare const CONFIG_DIR: string;
 export declare const PROJECTS_FILE: string;

package/dist/project/store.js

@@ -14,7 +14,7 @@
  *                 ~/WorkBuddy/<timestamp>) would never hit a byPath entry, so a
  *                 cwd-only design silently degrades to nothing for them.
  *
- * See docs/cli-project-binding-design.md §3.
+ * See docs/product/cli/cli-project-binding-design.md §3.
  */
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';

package/dist/project/take.d.ts

@@ -14,7 +14,7 @@
  * separate CLI processes, sometimes concurrent, and a local cache would have to
  * solve staleness and write races that a unique index solves for free.
  *
- * See docs/cli-project-binding-design.md §5.
+ * See docs/product/cli/cli-project-binding-design.md §5.
  */
 import { type HttpContext } from '../http.js';
 export interface EnsuredTake {

package/dist/project/take.js

@@ -14,7 +14,7 @@
  * separate CLI processes, sometimes concurrent, and a local cache would have to
  * solve staleness and write races that a unique index solves for free.
  *
- * See docs/cli-project-binding-design.md §5.
+ * See docs/product/cli/cli-project-binding-design.md §5.
  */
 import { mmPost } from '../http.js';
 import { resolveTakeKey } from './host.js';

package/dist/project/trace.d.ts

@@ -13,7 +13,7 @@
  * reply — those live in the host's own transcript. So this module reports the
  * one thing it genuinely observes: the invocation itself.
  *
- * See docs/cli-session-record-design.md §5.
+ * See docs/product/cli/cli-session-record-design.md §5.
  */
 import { type HttpContext } from '../http.js';
 import type { ParsedArgs } from '../argv.js';

package/dist/project/trace.js

@@ -13,7 +13,7 @@
  * reply — those live in the host's own transcript. So this module reports the
  * one thing it genuinely observes: the invocation itself.
  *
- * See docs/cli-session-record-design.md §5.
+ * See docs/product/cli/cli-session-record-design.md §5.
  */
 import os from 'node:os';
 import { cleanDiagnosticText, outcomeOf } from '../diagnostics.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.61",
+  "version": "0.9.63",
   "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",
@@ -37,7 +37,8 @@
     "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",
+    "test:showcase-links": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-showcase-links.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 && npm run -s test:showcase-links",
     "integration": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/regress.py",
     "integration:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/render-template-check.py"
   },

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

@@ -1477,7 +1477,7 @@ def build_dsl(
 
     scene_images 是用户**自带的配图**（visual-overlay 模板专用），按顺序占位：第 i 张
     图给第 i 个场景，没被占到的场景照常走 gen-image 补图。这条规则不是随便定的——
-    见 docs/asset-annotation-design.md §6：另外两种立场（模型自由挑选 / 严格一一对应）
+    见 docs/product/creation/asset-annotation-design.md §6：另外两种立场（模型自由挑选 / 严格一一对应）
     都会让"只传两张图"要么失去可预期性，要么直接跑不通。
 
     speed 是旁白语速倍率，落在 global.narration.speed（不给 = 1.0）。它**不写进

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

@@ -175,3 +175,58 @@ def probe_video_duration(url: str) -> Optional[float]:
         return content_length_estimate
 
     return None
+
+
+def probe_video_meta(url: str, timeout: float = 20.0) -> dict:
+    """Probe a remote video's pixel size and duration with ffprobe (reads the URL directly).
+
+    Returns ``{"width": int, "height": int, "duration_ms": int}`` with only the fields it
+    could read; ``{}`` when ffprobe is missing or the probe fails. Callers treat every
+    field as optional.
+
+    为什么要：数字人盒子的宽高比缺省按 3:4 算，而克隆素材多是 9:16 左右的竖版
+    （实测 720×1264）。资产上没有宽高时，模板用 3:4 的盒子 object-fit: cover 裁掉
+    人物的头顶和下半身（conv_XKTQxEBLdZy3i_jIB7IG）。
+    """
+    try:
+        result = subprocess.run(
+            [
+                "ffprobe", "-v", "quiet", "-print_format", "json",
+                "-select_streams", "v:0", "-show_streams", "-show_format", url,
+            ],
+            capture_output=True, text=True, timeout=timeout, stdin=subprocess.DEVNULL,
+        )
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired) as e:
+        _log(f"   ⚠️  video meta probe unavailable: {type(e).__name__}")
+        return {}
+    if result.returncode != 0:
+        return {}
+    try:
+        info = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError:
+        return {}
+
+    meta: dict = {}
+    streams = info.get("streams") or []
+    if streams:
+        s = streams[0]
+        w, h = s.get("width"), s.get("height")
+        if isinstance(w, int) and isinstance(h, int) and w > 0 and h > 0:
+            # 手机素材常带 90° / 270° 旋转元数据：播放器按旋转后的方向显示。
+            rotation = 0
+            for side in s.get("side_data_list") or []:
+                if isinstance(side.get("rotation"), (int, float)):
+                    rotation = int(side["rotation"])
+            tags_rot = (s.get("tags") or {}).get("rotate")
+            if tags_rot and str(tags_rot).lstrip("-").isdigit():
+                rotation = int(tags_rot)
+            if abs(rotation) % 180 == 90:
+                w, h = h, w
+            meta["width"], meta["height"] = w, h
+    try:
+        dur = float((info.get("format") or {}).get("duration") or 0)
+        if dur > 0:
+            meta["duration_ms"] = int(round(dur * 1000))
+    except (TypeError, ValueError):
+        pass
+    return meta

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

@@ -1182,7 +1182,16 @@ def resolve_asset_digital_human(asset: dict, private_token: str, timeout: int) -
             for line in reversed(result.stdout.strip().split("\n")):
                 line = line.strip()
                 if line.startswith("http"):
-                    return {"status": "generated", "url": line}
+                    out = {"status": "generated", "url": line}
+                    # 宽高 / 时长写回资产：模板按它定盒子比例（缺省 3:4 会裁人），
+                    # 按时长决定 onEnd=hide/loop 何时生效。探测失败不影响生成结果。
+                    from _video_probe import probe_video_meta
+                    meta = probe_video_meta(line)
+                    if meta.get("width") and meta.get("height"):
+                        out["width"], out["height"] = meta["width"], meta["height"]
+                    if meta.get("duration_ms"):
+                        out["duration_ms"] = meta["duration_ms"]
+                    return out
         return {"status": "failed", "error": result.stderr.strip()[:1000]}
     except subprocess.TimeoutExpired:
         return {"status": "failed", "error": f"Digital human generation timed out after {dh_timeout}s"}
@@ -1263,6 +1272,11 @@ def _resolve_single_asset(
             asset["generatedBy"]["completedAt"] = now_iso()
             if result.get("audio_length_ms") is not None:
                 asset["duration"] = result["audio_length_ms"]
+            # 视频类资产（数字人）：ms 时长 + 像素尺寸，模板的 ResolvedAsset 契约同名字段。
+            if result.get("duration_ms") is not None:
+                asset["duration"] = result["duration_ms"]
+            if result.get("width") and result.get("height"):
+                asset["width"], asset["height"] = result["width"], result["height"]
             if result.get("subtitles"):
                 asset["ttsSubtitles"] = result["subtitles"]
             # Propagate structured-narration metadata onto the resolved
@@ -2170,7 +2184,7 @@ def render_with_remote_api(
     if source_oss_key:
         # 只传 templateKey：由 ab-render 带本次的 X-Priv-Token 向 ab-api 换源码包 URL
         # 并自行下载（所有权校验在 ab-api）。源码包 URL 不经过客户端 ——
-        # 见 ab-platform/docs/template-source-protection-design.md §4.3。
+        # 见 ab-platform/docs/templates/template-source-protection-design.md §4.3。
         payload = {
             "templateKey": template_id,
             "inputProps": input_props,

package/skills/template-registry/SKILL.md

@@ -9,6 +9,7 @@ description: |
   Note: DSL→TemplateBinding is no longer a separate exposed step — once prepare_video_assets receives a template_id it builds the binding internally.
 triggers:
   - View available templates / list every template
+  - Watch a template's sample videos / open its detail page
 ---
 
 # Video Template Registry & Binding Skill
@@ -48,7 +49,8 @@ The skill itself only reads the registry; whether a token is needed depends on t
 |---------|-------------|---------|
 | `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`. | `https://api.remixmate.ai/api` |
-| `PRIV_TOKEN` | Sent as `X-Priv-Token` when hitting the registry endpoint. Falls back to `~/.config/remixmate/credentials.json`. | unset |
+| `PRIV_TOKEN` | Sent as `X-Priv-Token` to the registry and sample endpoints. Injected by the `remixmate` runner after `remixmate login`; the Python side reads only this env var. | unset |
+| `VIDEO_TEMPLATE_SHOWCASE_URL` | Sample endpoint override. Default `<MM_API_BASE_URL>/templateShowcase/listByTemplate`; not called when the registry is a `file://` URL. | derived |
 | `VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD` | `POST` (default) or `GET`. POST shape matches ab-api `{code,msg,data}`. | `POST` |
 
 Resolution (single source — see `scripts/registry_loader.py` for the canonical implementation):
@@ -74,6 +76,16 @@ the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDE
 remixmate template-registry --list-templates
 ```
 
+### Show templates to the user
+
+When the user asks to see / browse / pick templates, they decide by *watching* samples, not by reading definitions. The list adds, per template, the number of samples and a link to its web detail page (playable samples, layouts, a copy-ready prompt) whenever the backend serves them (`↳ samples: N · <url>` in the table; `showcases.count` / `showcases.pageUrl` in JSON).
+
+- Present each template as: name, aspect ratios, sample count, and its `pageUrl` as a clickable Markdown link. Keep the URL exactly as printed.
+- When the user wants to see what one template looks like, give its link, or run `remixmate template-registry --open <templateId>` (prints the URL; opens the browser only from an interactive terminal — relay the printed URL either way).
+- If the host renders images, you may add a sample's `coverImage` as a Markdown image next to the link; the link stays the primary content.
+- No sample info (older backend, or a template with no samples yet) is not an error: show the template without it.
+- The detail page's prompt is meant to be pasted back into this chat; treat it like any user request.
+
 ### Build a binding locally (debug only, not part of the render pipeline)
 
 ```python
@@ -99,7 +111,8 @@ print(json.dumps(binding, ensure_ascii=False, indent=2))
 | `--filter-aspect` | Keep only templates declaring this aspect ratio (e.g. `9:16`). | none |
 | `--filter-language` | Keep only templates whose `contentLanguage` includes this code (`zh`/`en`); language-agnostic templates always show. | none |
 | `--include-beta` | Also show `status: beta` templates (same effect as `ENABLE_BETA_TEMPLATES=1`). | off |
-| `--json-output` | List mode: emit `{ "templates": [...] }` summaries (or full definitions with `--full`) instead of the table. Detail mode (`--template-id`) is always compact JSON. | off |
+| `--json-output` | List mode: emit `{ "templates": [...] }` summaries (or full definitions with `--full`) instead of the table. Detail mode (`--template-id`) is always compact JSON. Summaries carry `showcases: { count, pageUrl, items }` and detail mode a top-level `showcases` map when the backend serves samples (absent otherwise). | off |
+| `--open <id>` | Print the template's web detail page URL (samples, layouts) and open the browser when run from an interactive terminal. Exits 1 when the backend has no link for it. Cannot be combined with `--template-id`. | — |
 
 ### List vs. detail
 

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

@@ -68,6 +68,13 @@ Flags:
   --include-beta                   also show beta templates (else stable-only)
   --json-output                    emit {"templates": [...]} or {"examples": [...]}
                                    instead of a table
+  --open <id>                      print the template's web detail page URL
+                                   (samples, layouts); also opens the browser
+                                   when stdout is an interactive terminal
+
+Samples (showcase_loader.py): list and detail views add each template's sample
+count and web detail-page link when ab-api serves them; when it does not, the
+views are unchanged apart from one stderr warning.
 """
 
 from __future__ import annotations
@@ -88,6 +95,12 @@ from registry_loader import (  # noqa: E402
     get_template,
     list_templates as load_visible_templates,
 )
+from showcase_loader import load_showcases, summarize_group  # noqa: E402
+
+# Samples per template in list views (table count + JSON items). The detail
+# view (--template-id) returns up to _DETAIL_SHOWCASES.
+_LIST_SHOWCASES = 3
+_DETAIL_SHOWCASES = 20
 
 # Summary llmHint budget: enough to tell templates apart when choosing, far
 # short of the multi-KB authoring contract (read that with --template-id).
@@ -168,6 +181,41 @@ def _summarize(tpl: dict) -> dict:
     return summary
 
 
+def _open_in_browser(url: str) -> None:
+    """Best-effort browser open after the URL has already been printed.
+
+    Only when stdout is a TTY (a human at a terminal) and REMIXMATE_NO_BROWSER
+    is unset: agent hosts run commands through pipes / sandboxes, where the
+    printed URL is what they relay to the user. Failures are swallowed.
+    """
+    if not sys.stdout.isatty() or os.environ.get("REMIXMATE_NO_BROWSER", "").strip():
+        return
+    try:
+        import webbrowser
+
+        webbrowser.open(url, new=2)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _report_unknown_ids(missing: list[str], templates: list[dict]) -> None:
+    for tid in missing:
+        # Distinguish "gated out by status" from "does not exist" —
+        # otherwise a beta template reads as a typo and the caller
+        # retries the id instead of passing --include-beta.
+        gated = get_template(tid, include_all_statuses=True)
+        if gated is not None:
+            print(
+                f"❌ Template '{tid}' exists but its status is "
+                f"'{_status_of(gated)}' — pass --include-beta to read it.",
+                file=sys.stderr,
+            )
+        else:
+            print(f"❌ Unknown template id: '{tid}'", file=sys.stderr)
+    known = ", ".join(sorted(str(t.get("templateId")) for t in templates))
+    print(f"   Available ids: {known}", file=sys.stderr)
+
+
 def _detail_hint(template_id: str = "<templateId>") -> str:
     return (
         f"Summaries only. Run --template-id {template_id} --json-output for one "
@@ -337,8 +385,14 @@ def main() -> None:
     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 JSON ({"templates":[...]} or {"examples":[...]}) instead of a table.')
+    ap.add_argument("--open", dest="open_id", metavar="ID",
+                    help="Print the web detail page URL of this template (samples, layouts) "
+                         "and open it in the browser when run from an interactive terminal.")
     args = ap.parse_args()
 
+    if args.open_id and (args.template_ids or args.list_examples or args.list_templates):
+        ap.error("--open cannot be combined with --template-id / --list-examples / --list-templates")
+
     # --include-beta flips registry_loader's documented status gate via env, so
     # the CLI and in-process callers share one gating implementation.
     if args.include_beta:
@@ -404,13 +458,35 @@ def main() -> None:
         print(f"❌ {exc}", file=sys.stderr)
         sys.exit(1)
 
+    by_id = {t.get("templateId"): t for t in templates}
+
+    # ----- open mode (--open) -------------------------------------------------
+    #
+    # The URL goes to stdout first, unconditionally: in Codex / Claude Code the
+    # command runs through a pipe and the printed link is what the agent relays.
+    if args.open_id:
+        if args.open_id not in by_id:
+            _report_unknown_ids([args.open_id], templates)
+            sys.exit(1)
+        groups = load_showcases([args.open_id], 1)
+        page_url = (groups or {}).get(args.open_id, {}).get("pageUrl")
+        if not page_url:
+            print(
+                "❌ No web detail page link for this template: the backend does not "
+                "serve sample links yet, or its site address is not configured.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        print(page_url)
+        _open_in_browser(page_url)
+        return
+
     # ----- detail mode (--template-id) ---------------------------------------
     #
     # Explicit ids win over --filter-*: the caller already chose, and silently
     # returning nothing because a stale filter excluded the pick would read as
     # "template does not exist".
     if args.template_ids:
-        by_id = {t.get("templateId"): t for t in templates}
         picked: list[dict] = []
         missing: list[str] = []
         for tid in args.template_ids:
@@ -420,21 +496,7 @@ def main() -> None:
             else:
                 picked.append(tpl)
         if missing:
-            for tid in missing:
-                # Distinguish "gated out by status" from "does not exist" —
-                # otherwise a beta template reads as a typo and the caller
-                # retries the id instead of passing --include-beta.
-                gated = get_template(tid, include_all_statuses=True)
-                if gated is not None:
-                    print(
-                        f"❌ Template '{tid}' exists but its status is "
-                        f"'{_status_of(gated)}' — pass --include-beta to read it.",
-                        file=sys.stderr,
-                    )
-                else:
-                    print(f"❌ Unknown template id: '{tid}'", file=sys.stderr)
-            known = ", ".join(sorted(str(t.get("templateId")) for t in templates))
-            print(f"   Available ids: {known}", file=sys.stderr)
+            _report_unknown_ids(missing, templates)
             sys.exit(1)
         if args.slide_ids:
             wanted = [s for s in args.slide_ids if s != _SLIDE_EXPAND_ALL]
@@ -457,7 +519,15 @@ def main() -> None:
         # tool call: indent=2 nearly doubled the size (html-slide 37 K → 65 K
         # chars), which alone pushed the plain call past the tool-result cap and
         # got it spilled to a file the agent cannot read. Humans can `| jq`.
-        print(json.dumps({"templates": picked}, ensure_ascii=False))
+        detail: dict = {"templates": picked}
+        # Samples sit beside the definitions, never inside them: the definition
+        # is the template's authoring contract, samples are web content.
+        groups = load_showcases([str(t.get("templateId")) for t in picked], _DETAIL_SHOWCASES)
+        if groups is not None:
+            detail["showcases"] = {
+                tid: summarize_group(g, _DETAIL_SHOWCASES) for tid, g in groups.items()
+            }
+        print(json.dumps(detail, ensure_ascii=False))
         return
 
     visible = [
@@ -480,9 +550,18 @@ def main() -> None:
                 sys.exit(1)
             print(payload)
             return
+        groups = load_showcases([str(t.get("templateId")) for t in visible], _LIST_SHOWCASES) if visible else {}
+        summaries = []
+        for t in visible:
+            s = _summarize(t)
+            # Absent (not null) when the endpoint is unavailable, so a consumer
+            # never mistakes "unknown" for "zero samples".
+            if groups is not None and t.get("templateId") in groups:
+                s["showcases"] = summarize_group(groups[t["templateId"]], _LIST_SHOWCASES)
+            summaries.append(s)
         print(json.dumps(
             {
-                "templates": [_summarize(t) for t in visible],
+                "templates": summaries,
                 "detailHint": _detail_hint(),
             },
             ensure_ascii=False,
@@ -496,6 +575,8 @@ def main() -> None:
         )
         return
 
+    groups = load_showcases([str(t.get("templateId")) for t in visible], _LIST_SHOWCASES)
+
     header = (
         f"\n{'Template ID':<22} {'Name':<18} {'Aspect':<12} "
         f"{'Lang':<8} {'Status':<8} Tags / LLM hint"
@@ -515,6 +596,12 @@ def main() -> None:
         hint = _truncate(tpl.get("llmHint"), _SUMMARY_HINT_CHARS)
         if hint:
             print(f"{' ' * 22}   ↳ {hint}")
+        group = (groups or {}).get(tpl.get("templateId"))
+        if group is not None:
+            line = f"samples: {int(group.get('showcaseCount') or 0)}"
+            if group.get("pageUrl"):
+                line += f" · {group['pageUrl']}"
+            print(f"{' ' * 22}   ↳ {line}")
 
     print(f"\n{len(visible)} template(s) shown")
     first_id = str(visible[0].get("templateId", "<templateId>"))
@@ -522,6 +609,8 @@ def main() -> None:
         f"Full definition of one template: --template-id {first_id} --json-output "
         "(llmHint / customPayloadSchema / slideSchemas / slotMapping / variants)",
     )
+    if groups:
+        print(f"Watch samples in the browser: --open {first_id}")
 
 
 if __name__ == "__main__":

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

@@ -186,7 +186,7 @@ def build_binding(template: dict, dsl: dict) -> dict:
     # 用户选中的字体（DSL 的 global.font）。这里只是把不透明 key 折进 typography，
     # 真正的解析（uniqId → 排印家族名 + 字重文件）在 ab-render 侧完成。
     #
-    # 优先级见 ab-platform/docs/font-selection-design.md §13.3：
+    # 优先级见 ab-platform/docs/product/creation/font-selection-design.md §13.3：
     #   用户选择 > variant.defaultFontId（预留档位，当前恒为空）
     #     > template.defaultTypography.bodyFont（现状裸 family 名）> 模板 theme 字栈
     # 下面的 variant 合并在此之后执行，所以 fontId 单独在合并后再写回，

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

@@ -106,6 +106,18 @@ _CACHE_DIR = os.environ.get(
 _DEFAULT_API_BASE_URL = "https://api.remixmate.ai/api"
 
 
+def api_base_url() -> str:
+    """ab-api base（不带尾斜杠）。registry 与其它挂在 ab-api 上的只读接口共用这一份解析。
+
+    顺序：MM_API_BASE_URL → MM_BACKEND_API_URL → 生产默认，见 ``_default_registry_url``。
+    """
+    return (
+        os.environ.get("MM_API_BASE_URL", "").strip()
+        or os.environ.get("MM_BACKEND_API_URL", "").strip()
+        or _DEFAULT_API_BASE_URL
+    ).rstrip("/")
+
+
 def _default_registry_url() -> str:
     """未显式配置 VIDEO_TEMPLATE_REGISTRY_URL 时，推导默认 ab-api registry endpoint。
 
@@ -118,12 +130,7 @@ def _default_registry_url() -> str:
         → https://api.remixmate.ai/api（生产默认，零配置）
     路径段固定为 ``/remotionTemplate/registry``（POST，返回 ``{code,msg,data}``）。
     """
-    base = (
-        os.environ.get("MM_API_BASE_URL", "").strip()
-        or os.environ.get("MM_BACKEND_API_URL", "").strip()
-        or _DEFAULT_API_BASE_URL
-    ).rstrip("/")
-    return f"{base}/remotionTemplate/registry"
+    return f"{api_base_url()}/remotionTemplate/registry"
 
 
 def _cache_path_for(url: str) -> str:

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

@@ -101,7 +101,7 @@ def create_job(priv_token: str, dsl: str = "", dsl_meta: dict = None) -> int:
     CONVERSATION_ID 已被注入而整段跳过它；兜底补绑的 jobId 末位来源是从 stdout
     正则抠的）。归属断了，成片在旁白面板里就查不到已生成的音频。
     而 CONVERSATION_ID 在这一刻本来就已经在环境里了——信息在场，以前只是没传。
-    见 ab-platform/docs/render-job-binding-fix.md。
+    见 ab-platform/docs/engineering/render-job-binding-fix.md。
 
     服务端对该字段是软失败：绑不上只记日志，不影响任务创建。
 

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

@@ -0,0 +1,175 @@
+"""Showcase (sample video) loader — per-template samples + web detail-page links.
+
+Used by ``list_templates.py`` so an agent host (Codex CLI / Codex Desktop /
+Claude Code) can show the user how many samples a template has and a link to
+the web detail page where the samples play.
+
+Contract (ab-api ``POST /templateShowcase/listByTemplate``, X-Priv-Token):
+
+    request  {"templateKeys": [...], "limitPerTemplate": N}
+    response {code, msg, data: {"templates": [
+                {"templateKey", "pageUrl"?, "showcaseCount",
+                 "showcases": [{"showcaseId", "name", "coverImage", "videoUrl",
+                                "aspectRatio", "duration", "hasDemo", "pageUrl"?, ...}]}
+             ]}}
+
+Links are built server-side; the CLI never knows the web origin or routes.
+
+Unlike the registry, samples are *enhancement* data: every failure (network,
+older ab-api without the endpoint, business error, bad JSON) returns ``None``
+with one stderr warning, and the caller keeps printing the template list.
+Auth failures are also degraded here — the registry call that precedes this
+one already surfaces them with the proper exit code.
+
+Env:
+  VIDEO_TEMPLATE_SHOWCASE_URL   explicit endpoint (tests point it at file://)
+  MM_API_BASE_URL / MM_BACKEND_API_URL   base, same resolution as the registry
+  PRIV_TOKEN                    injected by the CLI runner
+  VIDEO_TEMPLATE_REGISTRY_CACHE_DIR      shared cache dir
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import tempfile
+import time
+import urllib.request
+from typing import Optional
+
+from registry_loader import api_base_url
+
+# Never longer than the registry TTL: a sample added in ShowcaseManager should
+# show up about as fast as a template change does.
+_TTL_SECONDS = 300
+_HTTP_TIMEOUT = 5
+
+# Item fields kept in CLI output. The endpoint returns the full wizard item
+# (replicateConfig, layoutPreview, tags …) for the web; an agent only needs
+# enough to describe and link a sample.
+SUMMARY_ITEM_FIELDS = (
+    "showcaseId", "name", "coverImage", "videoUrl",
+    "aspectRatio", "duration", "hasDemo", "pageUrl",
+)
+
+
+def _endpoint() -> str:
+    """Endpoint URL, or "" when samples should not be fetched at all.
+
+    An offline registry (``VIDEO_TEMPLATE_REGISTRY_URL=file://…``, fixtures /
+    air-gapped dev) never implies a network call for samples: the registry
+    there is not ab-api's, so neither are its templates.
+    """
+    explicit = os.environ.get("VIDEO_TEMPLATE_SHOWCASE_URL", "").strip()
+    if explicit:
+        return explicit
+    if os.environ.get("VIDEO_TEMPLATE_REGISTRY_URL", "").strip().startswith("file://"):
+        return ""
+    return f"{api_base_url()}/templateShowcase/listByTemplate"
+
+
+def _cache_dir() -> str:
+    return os.environ.get(
+        "VIDEO_TEMPLATE_REGISTRY_CACHE_DIR",
+        os.path.join(tempfile.gettempdir(), "ab-template-registry"),
+    )
+
+
+def _cache_file(url: str, body: bytes, token: str) -> str:
+    # Token identity is part of the key (hashed twice, never stored): two
+    # accounts on one machine see different private templates.
+    token_id = hashlib.sha256(token.encode("utf-8")).hexdigest()[:8]
+    digest = hashlib.sha256(url.encode("utf-8") + b"\0" + body + b"\0" + token_id.encode()).hexdigest()[:16]
+    return os.path.join(_cache_dir(), f"showcases-{digest}.json")
+
+
+def _read_cache(path: str) -> Optional[dict]:
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            cached = json.load(fh)
+        if time.time() - float(cached.get("fetchedAt", 0)) < _TTL_SECONDS:
+            return cached.get("data")
+    except (OSError, ValueError, TypeError):
+        pass
+    return None
+
+
+def _write_cache(path: str, data: dict) -> None:
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path))
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump({"fetchedAt": time.time(), "data": data}, fh, ensure_ascii=False)
+        os.replace(tmp, path)
+    except OSError:
+        pass  # cache is best-effort
+
+
+def _warn(reason: str) -> None:
+    print(f"⚠️  showcase info unavailable: {reason}", file=sys.stderr)
+
+
+def load_showcases(template_keys: list[str], limit_per_template: int) -> Optional[dict[str, dict]]:
+    """Return ``{templateKey: group}`` for the visible templates, or ``None`` on any failure.
+
+    Templates the caller cannot see are simply absent from the dict.
+    """
+    keys = [k for k in dict.fromkeys(template_keys) if isinstance(k, str) and k]
+    if not keys:
+        return {}
+
+    url = _endpoint()
+    token = os.environ.get("PRIV_TOKEN", "").strip()
+    # Silent skips (not failures): offline registry, or no credential — the
+    # endpoint is authenticated and the registry step already reported auth.
+    if not url or (not token and not url.startswith("file://")):
+        return None
+    body = json.dumps(
+        {"templateKeys": keys, "limitPerTemplate": max(1, min(int(limit_per_template), 50))},
+        separators=(",", ":"),
+    ).encode("utf-8")
+    cache_path = _cache_file(url, body, token)
+
+    data = _read_cache(cache_path)
+    if data is None:
+        headers = {"Accept": "application/json", "Content-Type": "application/json"}
+        if token:
+            headers["X-Priv-Token"] = token
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as resp:
+                parsed = json.loads(resp.read().decode("utf-8"))
+        except Exception as exc:  # noqa: BLE001 — enhancement data, degrade on anything
+            # Message only: exception text never includes the token header.
+            _warn(type(exc).__name__ + (f" {exc.code}" if hasattr(exc, "code") else ""))
+            return None
+        if not isinstance(parsed, dict) or parsed.get("code") not in (0, "0"):
+            code = parsed.get("code") if isinstance(parsed, dict) else "?"
+            _warn(f"code={code}")
+            return None
+        data = parsed.get("data")
+        if not isinstance(data, dict) or not isinstance(data.get("templates"), list):
+            _warn("unexpected response shape")
+            return None
+        _write_cache(cache_path, data)
+
+    wanted = set(keys)
+    out: dict[str, dict] = {}
+    for group in data.get("templates", []):
+        if isinstance(group, dict) and group.get("templateKey") in wanted:
+            out[group["templateKey"]] = group
+    return out
+
+
+def summarize_group(group: dict, max_items: int) -> dict:
+    """The CLI's view of one template's samples: count, link, a few slim items."""
+    items = []
+    for sc in (group.get("showcases") or [])[:max_items]:
+        if isinstance(sc, dict):
+            items.append({k: sc[k] for k in SUMMARY_ITEM_FIELDS if k in sc and sc[k] not in (None, "")})
+    out: dict = {"count": int(group.get("showcaseCount") or 0), "items": items}
+    if group.get("pageUrl"):
+        out["pageUrl"] = group["pageUrl"]
+    return out

package/skills/template-registry/skill.json

@@ -19,7 +19,8 @@
       "filter_aspect": { "type": "string", "description": "Show only templates that declare this aspect ratio. E.g. '9:16' / '16:9' / '1:1'." },
       "filter_language": { "type": "string", "description": "Show only templates whose contentLanguage includes this code ('zh' or 'en'). Templates with no declared language are always shown (treated as language-agnostic)." },
       "include_beta": { "type": "boolean", "description": "Also list templates with status='beta'. Default off (only 'stable' shows). The ENABLE_BETA_TEMPLATES env var has the same effect process-wide." },
-      "json_output": { "type": "boolean", "description": "Emit a JSON result instead of the human-readable table: { templates: [...] } — summaries, or full definitions when template_id / full is set — or { examples: [...] }." }
+      "json_output": { "type": "boolean", "description": "Emit a JSON result instead of the human-readable table: { templates: [...] } — summaries, or full definitions when template_id / full is set — or { examples: [...] }. When the backend serves samples, list summaries carry showcases { count, pageUrl, items } and the template_id view carries a top-level showcases map." },
+      "open": { "type": "string", "description": "Print the web detail page URL of <templateId> (playable samples, layouts, copy-ready prompt) and open it in the browser when run from an interactive terminal. Relay the printed URL to the user." }
     },
     "required": []
   }

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V26",
+  "version": "V27",
   "skillDescription": "Video-template registry skill. Stores every video-template definition and lists the available templates (templateId / name / aspect ratio / style tags).\n\nUse this skill as soon as the user mentions any of these intents:\n- View available templates / list every template\n\nNote: DSL→TemplateBinding is no longer a separate exposed step — once prepare_video_assets receives a template_id it builds the binding internally."
 }

package/skills/template-registry/video_dsl/schema/video-dsl-v1alpha1.json

@@ -108,7 +108,7 @@
           "properties": {
             "fontId": {
               "type": "string",
-              "description": "字体库的不透明 key（font.uniq_id）。**不要在这里写 CSS family 名**：family 名是渲染细节，由 ab-render 调 /font/resolve 解析；写成 family 名一旦拼错就静默退回默认字体，没有任何报错。见 ab-platform/docs/font-selection-design.md §8.1。"
+              "description": "字体库的不透明 key（font.uniq_id）。**不要在这里写 CSS family 名**：family 名是渲染细节，由 ab-render 调 /font/resolve 解析；写成 family 名一旦拼错就静默退回默认字体，没有任何报错。见 ab-platform/docs/product/creation/font-selection-design.md §8.1。"
             },
             "fontName": { "type": "string", "description": "展示名，仅供人读与日志，渲染不使用" }
           }

package/skills/web-screenshot/scripts/_media_upload.py

@@ -271,7 +271,7 @@ def annotate_asset(
     """把录屏的语义写进 ab-api 素材库（POST /asset/annotate）：分镜文本 + 来源页面。
 
     分镜里没有逐场景时间戳，整条录屏作为一个片段。失败抛 FinalizeError，调用方只记日志——
-    语义是附加信息，不能让「录屏已完成」失败。见 ab-platform/docs/asset-semantic-library-design.md §6.1。
+    语义是附加信息，不能让「录屏已完成」失败。见 ab-platform/docs/product/creation/asset-semantic-library-design.md §6.1。
     """
     if not private_token or not (file_id or file_url):
         return