@remixmate/cli 0.9.30 → 0.9.31

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.30",
-  "generatedAt": "2026-09-14T14:44:43.104Z",
+  "version": "0.9.31",
+  "generatedAt": "2026-09-14T15:38:04.716Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -833,7 +833,7 @@
       "tier": "orchestration",
       "category": "authoring",
       "title": "Video Template Registry",
-      "summary": "List all available video templates (templateId / name / aspect ratio / style tags). 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.",
+      "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"
       ],
@@ -853,11 +853,19 @@
         "properties": {
           "list_templates": {
             "type": "boolean",
-            "description": "List available templates (default behavior; also implied when other flags are passed)."
+            "description": "List available templates as summaries — templateId / name / description / aspect ratios / language / status / styleTags / variantIds / key capabilities / a truncated llmHint (default behavior; also implied when other flags are passed)."
+          },
+          "template_id": {
+            "type": "string",
+            "description": "Return this template's FULL definition instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. This is the per-template authoring contract — read it before writing DSL for that template."
+          },
+          "full": {
+            "type": "boolean",
+            "description": "List mode only: emit full definitions for every listed template instead of summaries. Rejected when the result would be too large for one tool result — prefer template_id, or narrow with the filter_* parameters."
           },
           "list_examples": {
             "type": "boolean",
-            "description": "List the *.dsl.json / *.binding.json reference examples shipped under template-registry/video_dsl/schema/examples/, grouped by templateId. Useful for downstream agents (e.g. a creation agent) that want to read a template's reference shape before producing new DSL."
+            "description": "List the *.dsl.json / *.binding.json reference examples under template-registry/video_dsl/schema/examples/, grouped by templateId. That directory is optional and is not part of the published package, so this is normally empty — to read a template's reference shape, use template_id instead (the registry's own contract)."
           },
           "filter_tag": {
             "type": "string",
@@ -877,7 +885,7 @@
           },
           "json_output": {
             "type": "boolean",
-            "description": "Emit a JSON result ({ templates: [...] } or { examples: [...] }) instead of the human-readable table."
+            "description": "Emit a JSON result instead of the human-readable table: { templates: [...] } — summaries, or full definitions when template_id / full is set — or { examples: [...] }."
           }
         },
         "required": []
@@ -886,6 +894,8 @@
         "primary": [],
         "advanced": [
           "list_templates",
+          "template_id",
+          "full",
           "list_examples",
           "filter_tag",
           "filter_aspect",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.30",
+  "version": "0.9.31",
   "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",

package/skills/gen-script/SKILL.md

@@ -52,7 +52,7 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 
 ### Mandatory steps
 
-1. Read the requested template's full definition from the registry — `template_registry` with `list_templates=true` and `json_output=true` emits each template whole. This is the shipping source of truth, and unlike the table view it truncates nothing.
+1. Read the requested template's full definition from the registry — `template_registry` with `template_id=<the id>` and `json_output=true` emits that one template whole. This is the shipping source of truth, and unlike the summary list it truncates nothing. Do **not** ask for every template's full definition (`list_templates=true` + `full=true`): the whole registry is far more JSON than one tool result can carry, and the call fails instead of returning the contract.
 2. Read its `llmHint` end to end — that is where the template states how its on-screen text and its layouts must be authored.
 3. Read its `customPayloadSchema`: every template-specific field lives there, including the enum of legal `customPayload.slideId` values for multi-layout templates.
 4. Combine that with the template's `slotMapping`, `requiredProps`, `optionalProps`, `propExtractors`, `assetRequirements`, `supportedAspectRatios`, `supportedDurations`, `constraints`, and `scenePatterns`.

package/skills/template-registry/SKILL.md

@@ -77,8 +77,9 @@ the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDE
 > 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 `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.
+2. **Read that template's contract**: run `remixmate template-registry --template-id <id> --json-output` for the full definition (llmHint, `customPayloadSchema` with the legal `slideId` values, `slotMapping`, `variants`). The list view only carries a 200-char llmHint preview, which is not enough to author against.
+3. **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`.
+4. **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.
 
@@ -119,12 +120,25 @@ print(json.dumps(binding, ensure_ascii=False, indent=2))
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--list-templates` | List every available template (currently the only CLI verb). | — |
+| `--list-templates` | List every available template as a **summary** (templateId / name / description / aspect ratios / language / status / styleTags / variantIds / the `capabilities` keys that drive authoring — `payloadStyle` / `needsNarration` / `durationStrategy` / `narrationDriver` — and llmHint truncated to 200 chars). | — |
+| `--template-id <id>` | Print that template's **full definition** — llmHint in full, `customPayloadSchema`, `slotMapping`, `compositions`, `variants`. Repeatable. | — |
+| `--full` | List mode: emit full definitions instead of summaries. Refuses when the result would exceed 60 K characters. | off |
 | `--filter-tag` | Keep only templates whose `styleTags` match this substring (case-insensitive). | none |
 | `--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` | Emit `{ "templates": [...] }` instead of the table. | off |
+| `--json-output` | Emit `{ "templates": [...] }` instead of the table — summaries, or full definitions under `--template-id` / `--full`. | off |
+
+### List vs. detail
+
+A registry row is 4–17 KB of JSON, so dumping every full definition at once overflows an LLM tool result (the caller sees "exceeds maximum allowed tokens" instead of the contract it asked for). The list verb therefore returns summaries — enough to *choose* a template — and `--template-id` returns the one definition you need to *author* for it:
+
+```bash
+remixmate template-registry --list-templates                         # choose
+remixmate template-registry --template-id html-slide --json-output   # then read its contract
+```
+
+This mirrors the list/detail split described in `scripts/registry_loader.py` (P1.2), realized CLI-side so it holds even while the backend still serves one merged registry payload.
 
 ## Props extraction rules
 

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

@@ -13,8 +13,32 @@ TS↔Python duplication; this is now the only place the list verb is realized.
 The DSL → TemplateBinding logic stays in ``match_template.py`` and is invoked
 in-process by ``render-video``; it is intentionally NOT exposed as a CLI verb.
 
+List vs. detail (why ``--json-output`` no longer dumps everything):
+  A registry row is 4–17 KB of JSON (customPayloadSchema + slotMapping +
+  variants dominate), so ``--list-templates --json-output`` over a real
+  registry produced a six-figure-character blob. Every caller of this CLI is
+  an LLM tool call, and that blob overflowed the tool-result budget outright —
+  the agent got an "exceeds maximum allowed tokens" error instead of the
+  template definition it asked for, i.e. the mode that existed *to* read a
+  template's contract was the one mode that could never be read.
+
+  So the list verb emits **summaries** (identity + how to choose: name,
+  description, aspects, language, status, tags, variant ids, the capability
+  keys that drive authoring, a truncated llmHint) and ``--template-id <id>``
+  emits the **full definition** of the one
+  template the agent picked. That is the shape ``registry_loader``'s P1.2 note
+  already anticipated, realized CLI-side so it works before the backend
+  list/detail endpoints exist. ``--full`` still dumps whole definitions for
+  programmatic callers, guarded by a size check so it can't silently recreate
+  the overflow.
+
 Flags:
-  --list-templates                 (accepted; listing is the only verb)
+  --list-templates                 (accepted; listing is the default verb)
+  --template-id <id>               print the FULL definition of this template
+                                   (repeatable); this is the detail verb
+  --full                           in list mode, emit full definitions instead
+                                   of summaries (size-guarded; prefer
+                                   --template-id)
   --list-examples                  list *.dsl.json / *.binding.json reference
                                    examples grouped by templateId (consumed
                                    by downstream agents that want to read a
@@ -44,9 +68,19 @@ from registry_loader import (  # noqa: E402
     EXIT_NOT_AUTHENTICATED,
     RegistryAuthError,
     RegistryUnreachableError,
+    get_template,
     list_templates as load_visible_templates,
 )
 
+# Summary llmHint budget: enough to tell templates apart when choosing, far
+# short of the multi-KB authoring contract (read that with --template-id).
+_SUMMARY_HINT_CHARS = 200
+
+# Upper bound for a multi-template full dump (--full). ~60 K chars ≈ 20 K
+# tokens: still large, but inside a tool-result budget, and the message it
+# fails with names the flag that replaces it.
+_MAX_FULL_DUMP_CHARS = 60_000
+
 
 def _matches(tpl: dict, tag: str | None, aspect: str | None, language: str | None) -> bool:
     if tag:
@@ -74,6 +108,57 @@ def _status_of(tpl: dict) -> str:
     return "stable"
 
 
+def _truncate(text: object, limit: int) -> str | None:
+    if not isinstance(text, str) or not text.strip():
+        return None
+    text = text.strip()
+    return text if len(text) <= limit else text[: limit - 3] + "..."
+
+
+def _summarize(tpl: dict) -> dict:
+    """The "choose a template" view: identity + selection criteria only.
+
+    Deliberately excludes the authoring contract (llmHint in full,
+    customPayloadSchema, slotMapping, compositions, variants' style bodies) —
+    that is what ``--template-id`` returns, one template at a time.
+    """
+    variants = tpl.get("variants")
+    # Only the scalar capability keys that change how a caller *drives* the
+    # template (narration vs typewriter caption, who decides duration). The
+    # rest of `capabilities` — payloadDefaults above all — is bulk that scales
+    # with the registry, so it stays in the detail view.
+    caps = tpl.get("capabilities") if isinstance(tpl.get("capabilities"), dict) else {}
+    caps_summary = {
+        k: caps[k]
+        for k in ("payloadStyle", "needsNarration", "durationStrategy", "narrationDriver")
+        if k in caps
+    }
+    summary = {
+        "templateId": tpl.get("templateId"),
+        "name": tpl.get("name"),
+        "description": tpl.get("description"),
+        "status": _status_of(tpl),
+        "supportedAspectRatios": tpl.get("supportedAspectRatios") or [],
+        "contentLanguage": tpl.get("contentLanguage") or [],
+        "styleTags": tpl.get("styleTags") or [],
+        "variantIds": sorted(variants.keys()) if isinstance(variants, dict) else [],
+        "capabilities": caps_summary,
+        "llmHintPreview": _truncate(tpl.get("llmHint"), _SUMMARY_HINT_CHARS),
+    }
+    hint = tpl.get("llmHint")
+    if isinstance(hint, str) and len(hint.strip()) > _SUMMARY_HINT_CHARS:
+        summary["llmHintTruncated"] = True
+    return summary
+
+
+def _detail_hint(template_id: str = "<templateId>") -> str:
+    return (
+        f"Summaries only. Run --template-id {template_id} --json-output for one "
+        "template's full definition (llmHint / customPayloadSchema / slotMapping / "
+        "variants) — that is the per-template authoring contract."
+    )
+
+
 # ----- Examples discovery (--list-examples) ---------------------------------
 #
 # Examples live under <SkillDir>/video_dsl/schema/examples/ as `*.dsl.json` and
@@ -129,7 +214,12 @@ def main() -> None:
         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).")
+                    help="List every available template (summaries; the default verb).")
+    ap.add_argument("--template-id", action="append", dest="template_ids", metavar="ID",
+                    help="Print this template's FULL definition (repeatable).")
+    ap.add_argument("--full", action="store_true",
+                    help="List mode: emit full definitions instead of summaries "
+                         "(size-guarded; prefer --template-id).")
     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.")
@@ -169,8 +259,10 @@ def main() -> None:
                 "     • llmHint            — how this template's on-screen text and layouts must be authored\n"
                 "     • customPayloadSchema — every template-specific field, incl. the legal slideId values\n"
                 "     • slotMapping        — propExtractors / requiredProps / optionalProps\n"
-                "   Read it with `--list-templates --json-output` (that mode emits each "
-                "template's full definition; the table view truncates llmHint to 200 chars).",
+                "   Read it with `--template-id <id> --json-output` (one template's full "
+                "definition). Run `--list-templates` first if you need the ids;\n"
+                "   that view is summaries only — pointing it at the whole registry "
+                "returns more JSON than a tool result can carry.",
             )
             return
         print(f"\n{'Template ID':<28} Files")
@@ -201,13 +293,74 @@ def main() -> None:
         print(f"❌ {exc}", file=sys.stderr)
         sys.exit(1)
 
+    # ----- 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:
+            tpl = by_id.get(tid)
+            if tpl is None:
+                missing.append(tid)
+            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)
+            sys.exit(1)
+        if args.json_output:
+            print(json.dumps({"templates": picked}, ensure_ascii=False))
+        else:
+            # Pretty-printed rather than tabular: the whole point of detail mode
+            # is the nested contract (customPayloadSchema / slotMapping), which
+            # a table cannot show.
+            print(json.dumps({"templates": picked}, ensure_ascii=False, indent=2))
+        return
+
     visible = [
         t for t in templates
         if _matches(t, args.filter_tag, args.filter_aspect, args.filter_language)
     ]
 
     if args.json_output:
-        print(json.dumps({"templates": visible}, ensure_ascii=False))
+        if args.full:
+            payload = json.dumps({"templates": visible}, ensure_ascii=False)
+            if len(payload) > _MAX_FULL_DUMP_CHARS and len(visible) > 1:
+                print(
+                    f"❌ Full definitions for {len(visible)} template(s) are "
+                    f"{len(payload):,} characters — past the {_MAX_FULL_DUMP_CHARS:,}-char "
+                    "cap, and past what a tool result can carry.\n"
+                    "   Read one template at a time with `--template-id <id> --json-output`, "
+                    "or narrow with --filter-tag / --filter-aspect / --filter-language.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            print(payload)
+            return
+        print(json.dumps(
+            {
+                "templates": [_summarize(t) for t in visible],
+                "detailHint": _detail_hint(),
+            },
+            ensure_ascii=False,
+        ))
         return
 
     if not visible:
@@ -233,12 +386,16 @@ def main() -> None:
         status = _status_of(tpl).ljust(8)
         tags = ", ".join((tpl.get("styleTags") or [])[:5])
         print(f"{tid} {name} {ratios} {lang} {status} {tags}")
-        hint = tpl.get("llmHint")
+        hint = _truncate(tpl.get("llmHint"), _SUMMARY_HINT_CHARS)
         if hint:
-            hint = hint if len(hint) <= 200 else hint[:197] + "..."
             print(f"{' ' * 22}   ↳ {hint}")
 
     print(f"\n{len(visible)} template(s) shown")
+    first_id = str(visible[0].get("templateId", "<templateId>"))
+    print(
+        f"Full definition of one template: --template-id {first_id} --json-output "
+        "(llmHint / customPayloadSchema / slotMapping / variants)",
+    )
 
 
 if __name__ == "__main__":

package/skills/template-registry/skill.json

@@ -4,20 +4,22 @@
   "tier": "orchestration",
   "category": "authoring",
   "title": "Video Template Registry",
-  "description": "List all available video templates (templateId / name / aspect ratio / style tags). 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.",
+  "description": "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.",
   "auth": "required",
   "envVars": ["PRIV_TOKEN", "VIDEO_TEMPLATE_REGISTRY_URL", "MM_API_BASE_URL", "VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD"],
   "entry": { "type": "python", "scriptPath": "scripts/list_templates.py" },
   "parameters": {
     "type": "object",
     "properties": {
-      "list_templates": { "type": "boolean", "description": "List available templates (default behavior; also implied when other flags are passed)." },
-      "list_examples": { "type": "boolean", "description": "List the *.dsl.json / *.binding.json reference examples shipped under template-registry/video_dsl/schema/examples/, grouped by templateId. Useful for downstream agents (e.g. a creation agent) that want to read a template's reference shape before producing new DSL." },
+      "list_templates": { "type": "boolean", "description": "List available templates as summaries — templateId / name / description / aspect ratios / language / status / styleTags / variantIds / key capabilities / a truncated llmHint (default behavior; also implied when other flags are passed)." },
+      "template_id": { "type": "string", "description": "Return this template's FULL definition instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. This is the per-template authoring contract — read it before writing DSL for that template." },
+      "full": { "type": "boolean", "description": "List mode only: emit full definitions for every listed template instead of summaries. Rejected when the result would be too large for one tool result — prefer template_id, or narrow with the filter_* parameters." },
+      "list_examples": { "type": "boolean", "description": "List the *.dsl.json / *.binding.json reference examples under template-registry/video_dsl/schema/examples/, grouped by templateId. That directory is optional and is not part of the published package, so this is normally empty — to read a template's reference shape, use template_id instead (the registry's own contract)." },
       "filter_tag": { "type": "string", "description": "Show only templates whose styleTags contain (or are contained in) this string. Case-insensitive. E.g. 'tech' / '科普' / 'walkthrough'." },
       "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 ({ templates: [...] } or { examples: [...] }) instead of the human-readable table." }
+      "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: [...] }." }
     },
     "required": []
   }