@remixmate/cli 0.9.72 → 0.9.73

package/skills/gen-script/SKILL.md

@@ -41,6 +41,25 @@ The full schema is `template-registry` skill's `video_dsl/schema/video-dsl-v1alp
 
 **Per-template reference DSLs do not ship with this package.** `video_dsl/schema/examples/` is a local-only directory: it is absent from the published npm package (and has never existed in the repo). Do not go looking for examples — the authoritative per-template contract ships inside the registry's `template.json`, see below.
 
+## Agent behavior: template selection comes before the script
+
+The template decides the scene structure, the layouts and the fields the script must fill, so it is settled **before** `gen_script` runs — swapping templates after the user has read a script means rewriting all of it. Every call that passes `--template-id` also passes `--template-source`:
+
+| How the template was chosen | `--template-source` | Confirm with the user? |
+|---|---|---|
+| The user named it: its id or name, a pasted template detail-page prompt or link, or it was settled earlier in this conversation | `user-explicit` | No — go straight to the script |
+| The user named none; you offered candidates and the user picked or approved one in the chat | `user-confirmed` (+ `--template-candidates` for each id you offered) | Already done |
+| You picked it and the user has not seen it yet | — | **Yes — do not call gen_script.** `--template-source auto` is refused |
+
+When the user named no template:
+
+1. List templates with `template_registry` and let its hard constraints drop the ones that cannot serve the request: `filter_aspect` / `filter_language`, `user_media` (the user handed over images / videos, or did not), `source_doc` (a source document, by kind), `narration`. Set only what the request pins down. Each dropped template comes back in `excluded` with its reason.
+2. Rank what is left against the request using each template's `llmHint`, `description` and `styleTags`; its `notFor` lists the requests it is the wrong pick for, which is what separates close siblings. A Top-N / countdown-shaped request favours templates whose `capabilities.sceneStrategy` is `countdown`. Use coarse levels (recommended / also fits), not precise numeric scores — they suggest more certainty than the ranking has.
+3. Show 2–3 candidates, recommended first: name, one line on why it fits, its detail-page link (`pageUrl`) so the user can watch samples. When two candidates differ mainly in look, say so — that is a choice for the user's eyes, not yours. When only one template fits, still say which one you will use and ask. **End the turn.**
+4. After the user answers, call `gen_script` with that template, `--template-source user-confirmed` and `--template-candidates` for every id you offered. If the user names a template outside the shortlist, that is `user-explicit`.
+
+Never mark a template `user-confirmed` the user has not seen and approved. The value is recorded at `meta.templateSelection` and is how a later turn knows the template is already settled.
+
 ## Agent behavior: DSL generation when a template is selected
 
 **When the user explicitly specifies a template id, the agent must first read that template's full definition from the registry, then generate the DSL in the template's native shape. The agent must not generate the DSL from scratch ignoring the template definition, and must not produce a generic DSL first and rely on `template-registry` to force-match the template later.**
@@ -405,7 +424,8 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 
 1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Every command below uses `<SkillDir>/scripts/gen_script.py`; never hard-code paths.
 2. **Understand the request**: extract topic, duration, style, audience, etc.
-3. **If the user specifies a template, read it first**: load the matching `template.json` via `template-registry` and confirm its template-specific fields and asset requirements. Do not skip this step.
+3. **Settle the template**: if the user named one, that is `--template-source user-explicit`; otherwise offer candidates and wait for the user's pick (`user-confirmed`) — see "Agent behavior: template selection comes before the script".
+3b. **Read the template first**: load the matching `template.json` via `template-registry` and confirm its template-specific fields and asset requirements. Do not skip this step.
 4. **Generate the DSL**: pick the flags the target template's `capabilities` call for (see *Common CLI flags*); the template's `llmHint` says what to fill in afterwards.
 5. **Schema validation**: make sure the output DSL conforms to v1alpha1.
 6. **User confirmation**: show the script summary and wait for confirmation, per the rules above.
@@ -455,6 +475,8 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--speed` | Narration speech rate (0.5–2.0), written to `global.narration.speed` and applied when `prepare_video_assets` calls gen-voice. Pass it whenever the user picked a speed (the replicate form's 语速 field sends one). Above ~1.3 subtitle alignment drifts and the delivery turns mechanical — shorten the script instead. | `1.0` |
 | `--variant` | Template visual variant id (a key of the template's `variants`; `template-registry --list-templates` prints them as `variantIds`). Written to `meta.templateVariant`, which takes precedence over the fuzzy `--style` match. Pass it whenever the user picked a style — the replicate card shows it as `名字（id）`, e.g. `视觉风格: 紫色科技（tech-purple）`; pass the id in the parentheses. Requires `--template-id`; unknown ids are rejected. | template default |
 | `--background-preset` | Scene background preset, one of the template's `customPayloadSchema.background.preset` values. Written to every scene's `customPayload.background.preset` (other keys of the template's default background are kept). Pass it whenever the user picked a background, e.g. `背景样式: 纯色（solid）` → `solid`. `image` / `video` also need `customPayload.background.assetRef`. Requires `--template-id`; unsupported values are rejected. | template default |
+| `--template-source` | How `--template-id` was chosen: `user-explicit` / `user-confirmed` / `auto`, written to `meta.templateSelection.source`. `auto` is refused — confirm with the user first (see "Agent behavior: template selection comes before the script"). Omitted = not recorded, with a stderr notice. Requires `--template-id`. | — |
+| `--template-candidates` | Repeatable. Template ids offered to the user, recommended first → `meta.templateSelection.candidates`. With `user-confirmed`, `--template-id` must be one of them. | — |
 | `--allow-digital-human` | Whether to allow digital-human assets. | off |
 | `--allow-ai-video` | Whether to allow AI-generated video assets. | off |
 | `--validate` | Validate-only mode: only validate the input DSL. | — |