@remixmate/cli 0.9.18 → 0.9.20

package/dist/project/host.d.ts

@@ -46,7 +46,21 @@ export interface HostSession {
 }
 /** Identify the host and its root session id, or null when unrecognised. */
 export declare function detectHostSession(env?: NodeJS.ProcessEnv): HostSession | null;
-/** Host label for provenance, even when no session id could be read. */
+/**
+ * Normalise a declared host label.
+ *
+ * `video_project.client_host` is `varchar(32)`, and the value is rendered as a
+ * badge, so free-form input gets slugified rather than trusted: lowercase,
+ * non-alphanumerics collapsed to `-`, capped at 32. Anything that normalises to
+ * empty is treated as absent — an unusable label should degrade to "no badge",
+ * never to a garbage one.
+ */
+export declare function normaliseHostLabel(raw: string | undefined): string;
+/**
+ * Host label for provenance, even when no session id could be read.
+ *
+ * Declaration wins over detection: the declaring party knows, the table guesses.
+ */
 export declare function detectHostLabel(env?: NodeJS.ProcessEnv): string;
 export interface TakeKey {
     /** `<host>:<sessionId>`, or '' when nothing groups this invocation. */

package/dist/project/host.js

@@ -62,8 +62,51 @@ export function detectHostSession(env = process.env) {
     }
     return null;
 }
-/** Host label for provenance, even when no session id could be read. */
+/**
+ * Explicit host declaration, checked *before* the detection table.
+ *
+ * Two callers, both of which detection cannot serve:
+ *
+ *   - **WorkBuddy (ab-agent)** spawns this CLI itself. Sniffing our own process
+ *     would turn a fact we already know into a guess — and a fragile one, since
+ *     the generic variables it injects (CONVERSATION_ID …) are exactly the kind
+ *     another host might also set. It declares `REMIXMATE_HOST=workbuddy`.
+ *   - **Codex** does not expose anything: per the appendix-A survey it
+ *     "官方明确不通过环境变量暴露". No `detect()` we could write would be honest.
+ *     A user or the host itself can export `REMIXMATE_HOST=codex` and get the
+ *     provenance label without waiting for a CLI release.
+ *
+ * Symmetric with `REMIXMATE_TAKE_KEY`: that one overrides *grouping*, this one
+ * overrides *identity*. They are independent — declaring a host does not group,
+ * and grouping does not imply a host.
+ */
+const HOST_OVERRIDE_VAR = 'REMIXMATE_HOST';
+/**
+ * Normalise a declared host label.
+ *
+ * `video_project.client_host` is `varchar(32)`, and the value is rendered as a
+ * badge, so free-form input gets slugified rather than trusted: lowercase,
+ * non-alphanumerics collapsed to `-`, capped at 32. Anything that normalises to
+ * empty is treated as absent — an unusable label should degrade to "no badge",
+ * never to a garbage one.
+ */
+export function normaliseHostLabel(raw) {
+    return (raw ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32);
+}
+/**
+ * Host label for provenance, even when no session id could be read.
+ *
+ * Declaration wins over detection: the declaring party knows, the table guesses.
+ */
 export function detectHostLabel(env = process.env) {
+    const declared = normaliseHostLabel(env[HOST_OVERRIDE_VAR]);
+    if (declared)
+        return declared;
     return HOST_PROVIDERS.find((p) => p.detect(env))?.host ?? '';
 }
 /**
@@ -83,7 +126,9 @@ export function resolveTakeKey(jobId, env = process.env) {
     const host = detectHostLabel(env);
     const detected = detectHostSession(env);
     if (detected) {
-        return { key: `${detected.host}:${detected.sessionId}`, host: detected.host, source: 'host' };
+        // key 的命名空间用**探测到的**宿主，不用声明值：它是既有分组的命名空间，
+        // 跟着声明变会把同一会话的 take 拆成两组。而 host（溯源标签）以声明为准。
+        return { key: `${detected.host}:${detected.sessionId}`, host, source: 'host' };
     }
     const override = (env.REMIXMATE_TAKE_KEY ?? '').trim();
     if (override)

package/dist/skill-schema.d.ts

@@ -46,6 +46,28 @@ export declare const CATEGORY_VALUES: readonly ["authoring", "consuming", "asset
  */
 export type SkillAuthMode = 'required' | 'optional' | 'none';
 export declare const AUTH_VALUES: readonly ["required", "optional", "none"];
+/**
+ * 参数的**展示分级** —— 给人填表用的，不影响调度。
+ *
+ * `parameters` 是给 agent 的完整契约（十几个字段很正常）；把它整份渲染成表单
+ * 就是把门槛从"不知道说什么"换成"不知道填什么"。所以每个 skill 自己声明哪些
+ * 字段该直出、哪些折叠、哪些**根本不该给人看见**（`json_output` / `seed` 这类
+ * 是给调用方的开关，不是给人的选项）。
+ *
+ * 它和 schema 同住 skill.json，是刻意的：跨仓库的第二份名单必然漂移——
+ * ab-web 曾经用硬编码的 `ARCHETYPES` 常量对着后端字典表，最后两边对不上。
+ *
+ * 未声明的字段自动落进 `advanced`（见 build-manifest 的 resolveUiHints）：
+ * 新加一个参数时，最坏情况是它多显示了一层，而不是静默消失。
+ */
+export interface SkillUiHints {
+    /** 表单展开即可见 */
+    primary?: string[];
+    /** 折叠在「高级」里 */
+    advanced?: string[];
+    /** 不渲染给人类 */
+    hidden?: string[];
+}
 export interface RawSkillJson {
     name: string;
     toolName: string;
@@ -55,6 +77,8 @@ export interface RawSkillJson {
     category?: SkillCategory;
     auth?: SkillAuthMode;
     parameters?: Record<string, unknown>;
+    /** 参数的展示分级；缺省时按 required → primary、其余 → advanced 推导。 */
+    ui?: SkillUiHints;
     scriptPath?: string;
     entry?: SkillEntry;
     envVars?: string[];
@@ -100,6 +124,13 @@ export declare const REQUIRED_SKILL_JSON_FIELDS: readonly ["name", "tier", "titl
  * skills keep working untouched. Returns null when neither is present.
  */
 export declare function normalizeEntry(raw: Pick<RawSkillJson, 'entry' | 'scriptPath'>): SkillEntry | null;
+/**
+ * 把 `ui` 声明补全成三个互斥的完整分桶。没声明 `ui` 时按 required 推导。
+ *
+ * **未提及的字段一律落进 advanced**：新增参数时最坏是多折一层，而不是消失。
+ * 返回 null 表示这个 skill 没有可填的参数（不该弹表单）。
+ */
+export declare function resolveUiHints(raw: Pick<RawSkillJson, 'parameters' | 'ui'>): Required<SkillUiHints> | null;
 /**
  * Validate a parsed skill.json against the directory it lives in. Returns an
  * array of problem strings; an empty array means the record is well-formed.

package/dist/skill-schema.js

@@ -41,6 +41,97 @@ export function normalizeEntry(raw) {
         return { type: 'python', scriptPath: raw.scriptPath };
     return null;
 }
+/** `parameters.properties` 的键；非对象 / 无 properties 时返回空数组。 */
+function parameterKeys(parameters) {
+    if (!parameters || typeof parameters !== 'object')
+        return [];
+    const props = parameters.properties;
+    if (!props || typeof props !== 'object')
+        return [];
+    return Object.keys(props);
+}
+/** `parameters.required`；缺失或格式不对时返回空数组。 */
+function requiredKeys(parameters) {
+    if (!parameters || typeof parameters !== 'object')
+        return [];
+    const req = parameters.required;
+    return Array.isArray(req) ? req.filter((k) => typeof k === 'string') : [];
+}
+/**
+ * 把 `ui` 声明补全成三个互斥的完整分桶。没声明 `ui` 时按 required 推导。
+ *
+ * **未提及的字段一律落进 advanced**：新增参数时最坏是多折一层，而不是消失。
+ * 返回 null 表示这个 skill 没有可填的参数（不该弹表单）。
+ */
+export function resolveUiHints(raw) {
+    const keys = parameterKeys(raw.parameters);
+    if (keys.length === 0)
+        return null;
+    if (!raw.ui) {
+        const required = new Set(requiredKeys(raw.parameters));
+        return {
+            primary: keys.filter((k) => required.has(k)),
+            advanced: keys.filter((k) => !required.has(k)),
+            hidden: [],
+        };
+    }
+    const declared = raw.ui;
+    const keySet = new Set(keys);
+    // 只保留真实存在的字段：schema 删了某个参数但 ui 忘了同步时，
+    // 不至于让下游渲染出一个没有定义的表单项。
+    const keep = (list) => (list ?? []).filter((k) => keySet.has(k));
+    const primary = keep(declared.primary);
+    const advanced = keep(declared.advanced);
+    const hidden = keep(declared.hidden);
+    const mentioned = new Set([...primary, ...advanced, ...hidden]);
+    return {
+        primary,
+        advanced: [...advanced, ...keys.filter((k) => !mentioned.has(k))],
+        hidden,
+    };
+}
+/**
+ * `ui` 分级的自检。三条规则，每条都对应一种"表单看起来正常但填不出东西"的坏状态。
+ */
+function validateUiHints(raw) {
+    if (raw.ui == null)
+        return [];
+    const errors = [];
+    if (typeof raw.ui !== 'object' || Array.isArray(raw.ui)) {
+        return ['skill.json.ui must be an object with primary / advanced / hidden arrays'];
+    }
+    const keys = new Set(parameterKeys(raw.parameters));
+    const seen = new Map(); // 字段 → 首次出现的桶
+    for (const bucket of ['primary', 'advanced', 'hidden']) {
+        const list = raw.ui[bucket];
+        if (list == null)
+            continue;
+        if (!Array.isArray(list) || list.some((k) => typeof k !== 'string' || k === '')) {
+            errors.push(`skill.json.ui.${bucket} must be an array of non-empty parameter names`);
+            continue;
+        }
+        for (const key of list) {
+            // 引用了不存在的参数：多半是 schema 改名后 ui 没跟着改。
+            if (!keys.has(key)) {
+                errors.push(`skill.json.ui.${bucket} references unknown parameter '${key}'`);
+            }
+            const first = seen.get(key);
+            if (first) {
+                errors.push(`skill.json.ui lists '${key}' in both '${first}' and '${bucket}'`);
+            }
+            else {
+                seen.set(key, bucket);
+            }
+        }
+    }
+    // 必填字段被藏起来 = 表单永远填不完整，且没有任何提示。
+    for (const key of requiredKeys(raw.parameters)) {
+        if (raw.ui.hidden?.includes(key)) {
+            errors.push(`skill.json.ui.hidden contains required parameter '${key}' — it could never be filled`);
+        }
+    }
+    return errors;
+}
 /**
  * Validate a parsed skill.json against the directory it lives in. Returns an
  * array of problem strings; an empty array means the record is well-formed.
@@ -92,6 +183,7 @@ export function validateSkillJson(raw, skillId) {
     if ((raw.createsTake === true || raw.joinsTake === true) && resolveAuthMode(raw) === 'none') {
         errors.push("skill.json declares createsTake/joinsTake but auth='none' — a purely local skill has nothing to attribute");
     }
+    errors.push(...validateUiHints(raw));
     if (raw.name && raw.name !== skillId) {
         errors.push(`skill.json.name='${raw.name}' does not match directory name '${skillId}'`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.18",
+  "version": "0.9.20",
   "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/export-jianying/skill.json

@@ -6,21 +6,73 @@
   "title": "Jianying (CapCut) Draft Export",
   "description": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. Supports automatic conversion from a RenderPlan.",
   "auth": "required",
-  "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
+  "envVars": [
+    "PRIV_TOKEN",
+    "MM_API_BASE_URL",
+    "AGENT_NAME"
+  ],
   "scriptPath": "scripts/gen_jianying_draft.py",
   "parameters": {
     "type": "object",
     "properties": {
-      "from_render_plan": { "type": "string", "description": "Build the draft from a RenderPlan JSON (replaces --scenes)" },
-      "scenes": { "type": "string", "description": "Scene array as JSON (inline string or file path)" },
-      "title": { "type": "string", "description": "Draft title" },
-      "width": { "type": "number", "description": "Canvas width in pixels (default 1080)" },
-      "height": { "type": "number", "description": "Canvas height in pixels (default 1920)" },
-      "system": { "type": "string", "enum": ["mac", "windows"], "description": "Draft-root preset" },
-      "draft_root_path": { "type": "string", "description": "Explicit Jianying draft root path (overrides --system)" },
-      "no_download": { "type": "boolean", "description": "Do not download the ZIP; print the URL only" },
-      "output": { "type": "string", "description": "Local download path" }
+      "from_render_plan": {
+        "type": "string",
+        "description": "Build the draft from a RenderPlan JSON (replaces --scenes)"
+      },
+      "scenes": {
+        "type": "string",
+        "description": "Scene array as JSON (inline string or file path)"
+      },
+      "title": {
+        "type": "string",
+        "description": "Draft title"
+      },
+      "width": {
+        "type": "number",
+        "description": "Canvas width in pixels (default 1080)"
+      },
+      "height": {
+        "type": "number",
+        "description": "Canvas height in pixels (default 1920)"
+      },
+      "system": {
+        "type": "string",
+        "enum": [
+          "mac",
+          "windows"
+        ],
+        "description": "Draft-root preset"
+      },
+      "draft_root_path": {
+        "type": "string",
+        "description": "Explicit Jianying draft root path (overrides --system)"
+      },
+      "no_download": {
+        "type": "boolean",
+        "description": "Do not download the ZIP; print the URL only"
+      },
+      "output": {
+        "type": "string",
+        "description": "Local download path"
+      }
     },
     "required": []
+  },
+  "ui": {
+    "primary": [
+      "title"
+    ],
+    "advanced": [
+      "system",
+      "width",
+      "height",
+      "output"
+    ],
+    "hidden": [
+      "from_render_plan",
+      "scenes",
+      "draft_root_path",
+      "no_download"
+    ]
   }
 }

package/skills/gen-digital-human/skill.json

@@ -89,5 +89,28 @@
       }
     },
     "required": []
+  },
+  "ui": {
+    "primary": [
+      "avatar_id",
+      "text"
+    ],
+    "advanced": [
+      "source",
+      "voice_id",
+      "aspect_ratio",
+      "prompt",
+      "audio_url"
+    ],
+    "hidden": [
+      "json_output",
+      "list_avatars",
+      "mine",
+      "name",
+      "gender",
+      "check_status",
+      "generation_id",
+      "voice_name"
+    ]
   }
 }

package/skills/gen-image/SKILL.md

@@ -1,25 +1,25 @@
 ---
 name: gen-image
 description: |
-  AI image generation skill: produce an image from a text prompt, or do image-to-image with reference images. Backed by ab-api's `/model/genImg` (Seedream and Gemini families).
+  AI image generation skill: produce an image from a text prompt, or do image-to-image with reference images. Backed by ab-api's `/model/genImg` (the Seedream 5.0 family).
 
   Use this skill immediately whenever the user asks for any of:
   - AI image generation, text-to-image, "draw me ...", "generate an image of ..."
   - Image-to-image, reference image, style transfer, image variation
-  - Generate an image with Doubao / Seedream / Gemini
+  - Generate an image with Doubao / Seedream
   - Provide a prompt and ask for an image
 
   Even without an explicit "use AI", any request that turns a description into an image should route here.
 triggers:
   - AI image generation, text-to-image, "draw me ...", "generate an image of ..."
   - Image-to-image, reference image, style transfer, image variation
-  - Generate an image with Doubao / Seedream / Gemini
+  - Generate an image with Doubao / Seedream
   - Provide a prompt and ask for an image
 ---
 
 # AI Image Generation Skill
 
-Wraps ab-api's `POST /model/genImg` (the same endpoint the web studio uses), authenticated with the **Tianyan privateToken**, routed through LiteLLM to **Seedream** or **Gemini**.
+Wraps ab-api's `POST /model/genImg` (the same endpoint the web studio uses), authenticated with the **Tianyan privateToken**, routed through LiteLLM to the **Seedream 5.0** family.
 
 ## Models and sizes
 
@@ -31,7 +31,6 @@ the names below are the stable aliases to use.
 |-----------|------------|------------------|
 | `seedream` | Default. General-purpose, highest output resolution. | up to 14 |
 | `seedream-pro` | High-fidelity variant: better placement/element control, more faithful text rendering. Costs more per image. | up to 10 |
-| `gemini` | Gemini 3 Pro. | up to 4 |
 
 - **Seedream**: `--size` is an aspect ratio (e.g. `1:1`, `9:16`) or `WxH`. The backend maps the
   ratio to that model's own pixel preset and rescales out-of-range sizes, so prefer a ratio
@@ -39,8 +38,8 @@ the names below are the stable aliases to use.
 - **`seedream-pro`** additionally supports `3:2` / `2:3` / `21:9`, and caps output at ~2K
   (about 4.6 MP). Asking it for 4K pixels gets scaled down, not rejected — use `seedream`
   when you need a genuinely larger image.
-- **Gemini**: `--size` is a backend-allowed aspect ratio (e.g. `1:1`, `16:9`); add
-  `--resolution`: `1K` / `2K` / `4K` (default `1K`). `--resolution` is ignored by Seedream.
+- **`--resolution`** is inert today: it only ever applied to Gemini, which is not wired up on
+  the gateway. Control image dimensions with `--size`.
 
 ## Auth & environment
 
@@ -71,14 +70,6 @@ remixmate gen-image \
   --size "9:16"
 ```
 
-```bash
-remixmate gen-image \
-  --prompt "<image description>" \
-  --model gemini \
-  --size "16:9" \
-  --resolution "2K"
-```
-
 ```bash
 # High-fidelity: precise placement, legible on-image text
 remixmate gen-image \
@@ -95,7 +86,6 @@ Reference images accept local file paths, HTTPS URLs, or data URIs. Pass `--refe
 - **`seedream-pro`**: up to **10** reference images. Best choice when the edit has to land in a
   specific spot — describe the target region in the prompt (e.g. "in the marked area at the
   bottom left") and it holds position far better than `seedream`.
-- **`gemini`**: up to **4** reference images.
 
 Over-the-limit runs fail fast in the CLI, before spending credits.
 
@@ -129,13 +119,12 @@ remixmate gen-image \
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p` / `--prompt` | Description (required) | — |
-| `-m` / `--model` | `seedream` / `seedream-pro` / `gemini` | see `MM_IMAGE_MODEL` |
-| `-s` / `--size` | Seedream: ratio or WxH; Gemini: ratio | `1:1` |
-| `--resolution` | Gemini only: `1K` / `2K` / `4K` | `1K` |
+| `-m` / `--model` | `seedream` / `seedream-pro` | see `MM_IMAGE_MODEL` |
+| `-s` / `--size` | Aspect ratio or WxH | `1:1` |
 | `-n` | Number of images, 1–4 | `1` |
 | `-g` / `--guidance-scale` | Guidance scale (when supported) | backend default |
 | `--reference` | Reference image (repeatable; local path / URL / data URI) | none |
-| `--image-strength` | Reference strength 0–1 (Seedream only) | backend default |
+| `--image-strength` | Reference strength 0–1 | backend default |
 | `--negative-prompt` | Things to avoid | none |
 | `--seed` | Random seed (reproducibility) | none |
 | `--watermark` | Add a watermark (no `--no-watermark` opt-out) | backend default |

package/skills/gen-image/skill.json

@@ -4,7 +4,7 @@
   "tier": "atomic",
   "category": "asset",
   "title": "AI Image Generation",
-  "description": "AI image generation: produce an image from a text prompt. Supports the Seedream family (including a high-fidelity 'pro' variant) and Gemini, plus image-to-image with reference images.",
+  "description": "AI image generation: produce an image from a text prompt. Supports the Seedream 5.0 family (Lite and a high-fidelity 'pro' variant), plus image-to-image with reference images.",
   "auth": "required",
   "joinsTake": true,
   "envVars": [
@@ -26,7 +26,7 @@
       },
       "model": {
         "type": "string",
-        "description": "Model: 'seedream' (default), 'seedream-pro' (high fidelity, precise placement and on-image text; costs more per image), or 'gemini'"
+        "description": "Model: 'seedream' (default, Seedream 5.0 Lite) or 'seedream-pro' (high fidelity, precise placement and on-image text; costs more per image)"
       },
       "size": {
         "type": "string",
@@ -39,7 +39,7 @@
           "2K",
           "4K"
         ],
-        "description": "Output resolution (Gemini only)"
+        "description": "Output resolution tier. Currently inert: the only backend model that read it (Gemini) is not wired up, so this is ignored — use `size` for image dimensions."
       },
       "n": {
         "type": "number",
@@ -50,7 +50,7 @@
         "items": {
           "type": "string"
         },
-        "description": "Reference images for image-to-image: local file path, https URL, or data URI. Pass multiple to blend several references (seedream: max 14, seedream-pro: max 10, gemini: max 4 — over the limit fails before spending credits)."
+        "description": "Reference images for image-to-image: local file path, https URL, or data URI. Pass multiple to blend several references (seedream: max 14, seedream-pro: max 10 — over the limit fails before spending credits)."
       },
       "image_strength": {
         "type": "number",
@@ -80,5 +80,25 @@
     "required": [
       "prompt"
     ]
+  },
+  "ui": {
+    "primary": [
+      "prompt",
+      "model",
+      "size"
+    ],
+    "advanced": [
+      "n",
+      "reference",
+      "negative_prompt",
+      "image_strength"
+    ],
+    "hidden": [
+      "json_output",
+      "seed",
+      "guidance_scale",
+      "watermark",
+      "resolution"
+    ]
   }
 }

package/skills/gen-image/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-image",
   "repoName": "agent-skill-media-maker",
   "skillId": "337",
-  "version": "V9",
-  "skillDescription": "AI image generation skill: produce an image from a text prompt, or do image-to-image with reference images. Backed by ab-api's `/model/genImg` (Seedream and Gemini families).\n\nUse this skill immediately whenever the user asks for any of:\n- AI image generation, text-to-image, \"draw me ...\", \"generate an image of ...\"\n- Image-to-image, reference image, style transfer, image variation\n- Generate an image with Doubao / Seedream / Gemini\n- Provide a prompt and ask for an image\n\nEven without an explicit \"use AI\", any request that turns a description into an image should route here."
+  "version": "V10",
+  "skillDescription": "AI image generation skill: produce an image from a text prompt, or do image-to-image with reference images. Backed by ab-api's `/model/genImg` (the Seedream 5.0 family).\n\nUse this skill immediately whenever the user asks for any of:\n- AI image generation, text-to-image, \"draw me ...\", \"generate an image of ...\"\n- Image-to-image, reference image, style transfer, image variation\n- Generate an image with Doubao / Seedream\n- Provide a prompt and ask for an image\n\nEven without an explicit \"use AI\", any request that turns a description into an image should route here."
 }

package/skills/gen-script/SKILL.md

@@ -106,6 +106,18 @@ This skill does not hit any external API; no token required. The script only doe
 Show **every scene in full** — do not collapse them with phrases like "scenes 2–6 same as above".
 The user is reviewing the narration word by word; a summary they cannot proofread defeats the gate.
 
+> ⚠️ **Read every value back from the returned DSL, never from what you meant to pass.**
+> The summary exists so the user can catch a wrong tool call; a summary written from intent hides
+> exactly the bug it should surface.
+> - Durations ← `scenes[].duration`, **not** your `--duration` argument (`fit-caption` / `fit-narration`
+>   templates recompute it and ignore the target you passed).
+> - On-screen text ← `textLayers[]`, `customPayload.caption.lines`, `customPayload.carousel.items` —
+>   quoted verbatim, with the counts you actually see.
+> - If something you intended to set is missing or empty in the returned DSL, that is a failed call:
+>   say so and re-run `gen_script.py` with the right flags. Listing caption lines that are not in
+>   `customPayload.caption.lines` means the user confirms a script that does not exist and pays to
+>   render something else.
+
 ### Summary content
 
 The agent should show the following in clear Markdown:
@@ -156,9 +168,12 @@ For these templates the picture comes from `customPayload.carousel.items`, which
 When the user selects a `carousel-caption` template (or any template whose `assetRequirements` is image/video-only and whose `payloadStyle` is `carousel-caption`):
 
 1. **Extract every media URL the user provided** (image or video links in the prompt) and pass each one as a separate `--carousel-items <url>` flag — preserve the user's order, and pass the URLs **verbatim** (do not rewrite host/path/query).
-2. If the user wants on-screen text, pass each caption line as `--caption-lines '<text>'`. For purely visual templates like `adaptive-image-video` (no text, `needsNarration: false`), captions are optional.
+2. Pass each on-screen caption line as `--caption-lines '<text>'`. Whether this is optional depends on the template's `capabilities.durationStrategy`, **not** on `needsNarration` (every `carousel-caption` template has `needsNarration: false`):
+   - `durationStrategy: fit-caption` (e.g. `spotlight-card`) → **caption lines are mandatory.** The template has no narration and the typewriter copy is both the content and the clock: it is what the video says *and* what decides how long it runs. **If the user did not supply the copy, write it yourself** from the material you researched (repo README, page screenshots, the topic) and pass it. `gen_script.py` hard-fails on an empty caption for these templates.
+   - `durationStrategy: fit-images` (e.g. `adaptive-image-video` / `image-to-video`) → purely visual, captions genuinely optional; duration comes from the image count.
 3. **Never call gen_script for a `carousel-caption` template without `--carousel-items`.** If the user picked such a template but provided no media, ask them for the image/video URLs first — do not generate an empty carousel.
 4. Do **not** route these user-provided images through `gen-image`; they are existing assets and go straight into the carousel.
+5. Nothing downstream fills these in for you. `gen_script.py` routes on `capabilities.payloadStyle` alone — omitting the flags does **not** fall back to a generic path that generates images or writes copy; it assembles an empty carousel / empty caption. There is no auto-generation of caption text anywhere in the pipeline.
 
 ### Command example
 
@@ -266,7 +281,9 @@ python3 <SkillDir>/scripts/gen_script.py \
 |------|-------------|---------|
 | `--topic` | Video topic (required unless `--validate`). | — |
 | `--platform` | Target platform: `douyin` / `xiaohongshu` / `bilibili` / `wechat` / `youtube` / `generic`. | `generic` |
-| `--duration` | Target duration (seconds). | `30` |
+| `--headline` | On-screen main title (4–12 chars / ~3 words). Written to `meta.headline` + `textLayers[role=headline]`. **Pass it whenever the user gave a title** — otherwise headline falls back to the long-form topic and overflows the top text layer. | falls back to `--topic` |
+| `--subheadline` | On-screen subtitle / project name / slogan. Written to `meta.subheadline` + `textLayers[role=subheadline]`. Not the same thing as CC subtitles (`global.subtitle`). | `""` |
+| `--duration` | Target duration (seconds). Templates whose `durationStrategy` is `fit-caption` / `fit-narration` recompute the real duration and ignore this value. | `30` |
 | `--style` | Style tag. | — |
 | `--ratio` | Aspect ratio. | `16:9` |
 | `--scenes` | Scene count. | auto-planned |
@@ -279,7 +296,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--stub-image-url` | Test mode: every image AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_IMAGE_URL`). | — |
 | `--stub-video-url` | Test mode: every video AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_VIDEO_URL`). | — |
 | `--carousel-items` | Repeatable. Media URL placed directly into `customPayload.carousel.items` for `carousel-caption` templates (e.g. `adaptive-image-video`, `spotlight-card`). Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
-| `--caption-lines` | Repeatable. On-screen typewriter caption line for `carousel-caption` templates → `customPayload.caption.lines`. Supports `**emphasis**`. Optional for purely visual templates. | — |
+| `--caption-lines` | Repeatable. On-screen typewriter caption line for `carousel-caption` templates → `customPayload.caption.lines` (max 10 lines). Supports `**emphasis**`. **Required** for `durationStrategy: fit-caption` templates (`spotlight-card`) — write the lines yourself if the user did not supply them. Optional only for `fit-images` templates. | — |
 
 ## DSL generation principles
 
@@ -295,7 +312,7 @@ Apply the following principles when producing the DSL:
    instead of one continuous paragraph.
 5. **Moderate scene count**: 30-second videos work well with 4–6 scenes, 60-second videos with 6–10.
 6. **Leave room for templates**: pick generic layouts; do not assume a specific template implementation.
-7. **Image model allowlist**: every `type: image` + `source: gen-image` `AssetRef`'s `payload.model` **must** be one of the values in the table below. **Never** use display names, short forms, or made-up ids (e.g. `seedream`, `gemini-flash`, etc.).
+7. **Image model allowlist**: every `type: image` + `source: gen-image` `AssetRef`'s `payload.model` **must** be one of the values in the table below. **Never** use display names, short forms, or made-up ids (e.g. `seedream`, `seedream-5`, etc.).
 
 ### Allowlist `model` values aligned with gen-image
 
@@ -307,12 +324,11 @@ prefix and version — not a short alias:
 |-----------------|--------------|----------|-------|
 | `doubao/doubao-seedream-5-0-260128` | Seedream 5.0 Lite | Volcano | Default. Highest output resolution, up to 14 reference images. |
 | `doubao/doubao-seedream-5-0-pro-260628` | Seedream 5.0 Pro | Volcano | High fidelity: precise element placement, faithful on-image text. Up to 10 reference images, caps out around 2K. Costs noticeably more per image. |
-| `gemini-3-pro` | Gemini 3 Pro | Google | Up to 4 reference images. |
 
 **Agent behavior (avoid accidentally rewriting `model`)**:
 
 - `gen_script.py` already writes a valid `payload.model` (`doubao/doubao-seedream-5-0-260128` unless `DEFAULT_IMAGE_MODEL` overrides it). When the user only asks to refine narration, change `payload.prompt`, add or remove scenes, etc. and does **not** ask to change the image model, the agent **must keep** each image asset's original `payload.model` — do not replace it under the guise of "polishing the script".
-- **Only when the user explicitly asks to change the image model** (e.g. switches to the Pro variant or to Gemini), update the corresponding image `AssetRef`'s `payload.model` to the matching row id from the table. Writing a display name or an alias into JSON is wrong.
+- **Only when the user explicitly asks to change the image model** (e.g. switches to the Pro variant), update the corresponding image `AssetRef`'s `payload.model` to the matching row id from the table. Writing a display name or an alias into JSON is wrong.
 - When creating a new image `AssetRef`, pick one of the values above for `payload.model`; default to `doubao/doubao-seedream-5-0-260128` to match the script, or to whichever value the user specified.
 - If a run fails with an unknown-model error, the catalog has moved on from this table — check `/model/capabilities` rather than guessing a version string.
 
@@ -321,6 +337,9 @@ prefix and version — not a short alias:
 - **Schema validation failed**: check the DSL JSON shape and required fields against the schema.
 - **Scene duration mismatch**: adjust the narration length or the scene duration.
 - **Invalid platform**: look at the supported-platform list.
+- **`carousel-caption template ... needs visual or text content`**: you passed neither `--carousel-items` nor `--caption-lines`. Pass the user's media URLs (and caption lines where the template requires them).
+- **`template ... is typewriter-driven ... but --caption-lines is empty`**: a `fit-caption` template (e.g. `spotlight-card`) got no caption. Write the copy yourself if the user did not supply it, then pass one `--caption-lines` per line.
+- **`duration Ns is below/above template ... supportedDurations`**: the assembled DSL falls outside the range the template declares it was designed for. Below the minimum usually means the content is too thin (add caption lines / narration / scenes); above the maximum means trimming content or lowering `--duration`. This is enforced at generation time on purpose — a degenerate video still costs full render credits.
 
 ## scripts/ contents