@remixmate/cli 0.9.12 → 0.9.14

package/dist/handlers/gen-digital-human.js

@@ -91,6 +91,7 @@ export async function genDigitalHuman(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl: input.api_base_url,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     // ── Mode 1: list avatars ────────────────────────────────────────────────
     if (isTrue(input.list_avatars)) {

package/dist/handlers/gen-image.js

@@ -90,6 +90,7 @@ export async function genImage(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     emitProgress({ phase: 'gen-image:request', model, size, n });
     const data = await mmPost(ctx, '/model/genImg', payload, { timeoutMs: 120_000 });

package/dist/handlers/gen-video.js

@@ -85,6 +85,7 @@ export async function genVideo(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     const payload = {
         model,

package/dist/handlers/gen-voice.js

@@ -56,6 +56,7 @@ export async function genVoice(input, ctxIn) {
         const ctx = await resolveHttpContext(ctxIn.skillName, {
             apiBaseUrl: input.api_base_url,
             privateToken: input.priv_token,
+            preflightToken: ctxIn.auth?.token,
         });
         return listVoicesRemote(ctx);
     }
@@ -74,6 +75,7 @@ export async function genVoice(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     emitProgress({ phase: 'gen-voice:request', voiceId, speed });
     const data = await mmPost(ctx, '/tool/tts', { provider: voice.provider, text, voiceSetting: { voiceId, speed }, outputFormat: 'url' }, { timeoutMs: 120_000 });

package/dist/handlers/index.d.ts

@@ -4,10 +4,17 @@
  * Only `entry.type` in ('http' | 'builtin') uses this registry; python
  * skills go through spawn() in runner.ts and bypass handlers entirely.
  */
+import type { AuthPreflight } from '../auth/ensure.js';
 export type HandlerInput = Record<string, unknown>;
 export interface HandlerContext {
     /** ISO-style skill name from the registry (e.g. `gen-image`). Used for x-invoke-skill. */
     skillName: string;
+    /**
+     * Credential resolved by the dispatcher's preflight (runner.ts). Handlers pass
+     * `auth.token` into resolveHttpContext so the device flow can't run twice for
+     * a single invocation.
+     */
+    auth?: AuthPreflight;
 }
 export type SkillHandler = (input: HandlerInput, ctx: HandlerContext) => Promise<void>;
 export declare const HANDLERS: Record<string, SkillHandler>;

package/dist/http.d.ts

@@ -15,13 +15,18 @@
  * Base URL resolution:
  *   1. opts.apiBaseUrl                  — caller override
  *   2. process.env.MM_API_BASE_URL      — process env (point at local/staging here)
- *   3. https://api.remixmate.com/api    — production default (zero-config)
+ *   3. process.env.MM_BACKEND_API_URL   — ab-agent's convention (back-compat)
+ *   4. https://api.remixmate.com/api    — production default (zero-config)
+ */
+export { SkillError, EXIT } from './errors.js';
+/**
+ * Resolve the ab-api base URL the same way for authenticated and device-flow calls.
+ *
+ * `MM_BACKEND_API_URL` is honored because several Python skills already fall back
+ * to it (registry_loader, render_job_client, _vod_polling). Since runner.ts now
+ * injects the resolved base URL into those child processes, leaving it out here
+ * would let a prod default silently override an ab-agent-injected backend.
  */
-export declare class SkillError extends Error {
-    readonly exitCode: number;
-    constructor(message: string, exitCode?: number);
-}
-/** Resolve the ab-api base URL the same way for authenticated and device-flow calls. */
 export declare function resolveApiBaseUrl(flag?: string): string;
 export interface HttpContext {
     apiBaseUrl: string;
@@ -33,6 +38,12 @@ export interface HttpContext {
 export declare function resolveHttpContext(skillName: string, opts?: {
     apiBaseUrl?: string;
     privateToken?: string;
+    /**
+     * Token already resolved by the dispatcher's auth preflight (runner.ts).
+     * Reusing it avoids a second credential-store read — and, more importantly,
+     * a second device-flow attempt — per skill invocation.
+     */
+    preflightToken?: string;
 }): Promise<HttpContext>;
 export interface MmResponse<T = unknown> {
     code: number;

package/dist/http.js

@@ -15,26 +15,36 @@
  * Base URL resolution:
  *   1. opts.apiBaseUrl                  — caller override
  *   2. process.env.MM_API_BASE_URL      — process env (point at local/staging here)
- *   3. https://api.remixmate.com/api    — production default (zero-config)
+ *   3. process.env.MM_BACKEND_API_URL   — ab-agent's convention (back-compat)
+ *   4. https://api.remixmate.com/api    — production default (zero-config)
  */
 import { resolvePrivToken, NOT_AUTHENTICATED_HINT } from './auth/resolve.js';
 import { attemptAutoLogin } from './auth/auto-login.js';
+import { EXIT, SkillError } from './errors.js';
 const DEFAULT_API_BASE_URL = 'https://api.remixmate.com/api';
-export class SkillError extends Error {
-    exitCode;
-    constructor(message, exitCode = 1) {
-        super(message);
-        this.exitCode = exitCode;
-        this.name = 'SkillError';
-    }
-}
-/** Resolve the ab-api base URL the same way for authenticated and device-flow calls. */
+// Re-exported so the many `import { SkillError } from '../http.js'` call sites
+// stay valid; the definition moved to errors.ts to break an import cycle with
+// the auth gateway (see errors.ts).
+export { SkillError, EXIT } from './errors.js';
+/**
+ * Resolve the ab-api base URL the same way for authenticated and device-flow calls.
+ *
+ * `MM_BACKEND_API_URL` is honored because several Python skills already fall back
+ * to it (registry_loader, render_job_client, _vod_polling). Since runner.ts now
+ * injects the resolved base URL into those child processes, leaving it out here
+ * would let a prod default silently override an ab-agent-injected backend.
+ */
 export function resolveApiBaseUrl(flag) {
-    return (flag ?? process.env.MM_API_BASE_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+    const fromEnv = (process.env.MM_API_BASE_URL ?? '').trim() || (process.env.MM_BACKEND_API_URL ?? '').trim();
+    return ((flag ?? '').trim() || fromEnv || DEFAULT_API_BASE_URL).replace(/\/+$/, '');
 }
 export async function resolveHttpContext(skillName, opts = {}) {
     const apiBaseUrl = resolveApiBaseUrl(opts.apiBaseUrl);
-    let resolved = await resolvePrivToken({ flag: opts.privateToken, apiBaseUrl });
+    // An explicit --token flag still wins over the preflight result.
+    let resolved = await resolvePrivToken({
+        flag: opts.privateToken ?? opts.preflightToken,
+        apiBaseUrl,
+    });
     // Only when flag/env/store are all empty do we try automatic browser auth.
     // attemptAutoLogin self-gates (cloud env / headless / disabled → returns null
     // immediately), so the env-injected path never reaches it (zero regression).
@@ -42,7 +52,7 @@ export async function resolveHttpContext(skillName, opts = {}) {
         resolved = await attemptAutoLogin(apiBaseUrl);
     }
     if (!resolved) {
-        throw new SkillError(NOT_AUTHENTICATED_HINT);
+        throw new SkillError(NOT_AUTHENTICATED_HINT, EXIT.NOT_AUTHENTICATED);
     }
     return {
         apiBaseUrl,
@@ -83,15 +93,24 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
     }
     catch (err) {
         if (err instanceof Error && err.name === 'AbortError') {
-            throw new SkillError(`❌ request timed out: ${url}`);
+            throw new SkillError(`❌ request timed out: ${url}`, EXIT.BACKEND_UNREACHABLE);
         }
-        throw new SkillError(`❌ network error: ${err.message}`);
+        throw new SkillError(`❌ network error: ${err.message}`, EXIT.BACKEND_UNREACHABLE);
     }
     finally {
         clearTimeout(timeout);
     }
     const text = await resp.text();
     if (!resp.ok) {
+        // 401/403 is not a generic API failure — it means the credential is missing,
+        // expired or revoked. Surfacing it as such (with exit code 4) is what lets a
+        // host offer to re-authorize instead of reporting an opaque backend error.
+        if (resp.status === 401 || resp.status === 403) {
+            throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 HTTP ${resp.status}）`, EXIT.NOT_AUTHENTICATED);
+        }
+        if (resp.status >= 500) {
+            throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`, EXIT.BACKEND_UNREACHABLE);
+        }
         throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`);
     }
     let parsed;
@@ -102,6 +121,11 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
         throw new SkillError(`❌ failed to parse response, body is not JSON: ${text.slice(0, 200)}`);
     }
     if (parsed.code !== 0) {
+        // ab-api reports auth failures in the envelope (HTTP 200 + code=401), so the
+        // business-code path needs the same 401 → "re-authorize" mapping as above.
+        if (parsed.code === 401 || parsed.code === 403) {
+            throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 code=${parsed.code}${parsed.msg ? `: ${parsed.msg}` : ''}）`, EXIT.NOT_AUTHENTICATED);
+        }
         throw new SkillError(`❌ API returned a business error: ${parsed.msg ?? 'unknown error'} (code=${parsed.code})`);
     }
     return parsed.data ?? undefined;

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.12",
-  "generatedAt": "2026-08-12T01:53:36.480Z",
+  "version": "0.9.14",
+  "generatedAt": "2026-08-12T07:37:21.011Z",
   "skills": [
     {
       "id": "export-jianying",

package/dist/registry.d.ts

@@ -5,15 +5,17 @@
  * the build-time manifest generator and smoke test). A record that fails
  * validation is skipped with a warning rather than crashing the whole CLI.
  */
-import { type SkillEntry } from './skill-schema.js';
+import { type SkillAuthMode, type SkillEntry } from './skill-schema.js';
 export declare const SKILLS_DIR: string;
-export type { SkillEntry } from './skill-schema.js';
+export type { SkillEntry, SkillAuthMode } from './skill-schema.js';
 export interface SkillDef {
     name: string;
     toolName: string;
     description: string;
     parameters: Record<string, unknown>;
     entry: SkillEntry;
+    /** Authorization requirement enforced by the dispatcher before invocation. */
+    auth: SkillAuthMode;
     skillDir: string;
     /** Absolute path to the python entry script (only when entry.type === 'python'). */
     scriptAbsolutePath?: string;

package/dist/registry.js

@@ -8,7 +8,7 @@
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { normalizeEntry, validateSkillJson, } from './skill-schema.js';
+import { normalizeEntry, resolveAuthMode, validateSkillJson, } from './skill-schema.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
 function loadOne(skillDir) {
@@ -37,6 +37,7 @@ function loadOne(skillDir) {
         description: raw.description,
         parameters: raw.parameters ?? {},
         entry,
+        auth: resolveAuthMode(raw),
         skillDir,
     };
     if (entry.type === 'python') {

package/dist/runner.d.ts

@@ -3,6 +3,10 @@
  *   - spawn `python3 <scriptAbsolutePath> --flag value ...` (entry.type === 'python')
  *   - call a TS handler from handlers/ (entry.type === 'http' | 'builtin')
  *
+ * Authorization happens HERE, once, before either path — see auth/ensure.ts for
+ * why. Python children receive the resolved credential through their environment
+ * and never read the credential store themselves.
+ *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
 import type { ParsedArgs } from './argv.js';

package/dist/runner.js

@@ -3,26 +3,41 @@
  *   - spawn `python3 <scriptAbsolutePath> --flag value ...` (entry.type === 'python')
  *   - call a TS handler from handlers/ (entry.type === 'http' | 'builtin')
  *
+ * Authorization happens HERE, once, before either path — see auth/ensure.ts for
+ * why. Python children receive the resolved credential through their environment
+ * and never read the credential store themselves.
+ *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { findSkill, SKILLS_DIR } from './registry.js';
 import { HANDLERS } from './handlers/index.js';
-import { SkillError } from './http.js';
+import { EXIT, SkillError } from './errors.js';
+import { authChildEnv, ensureAuth } from './auth/ensure.js';
+/** Read the token override accepted by both the TS handlers and the Python skills. */
+function tokenFlag(args) {
+    const value = args.token ?? args.priv_token;
+    return typeof value === 'string' ? value : undefined;
+}
 export async function runSkill(skillName, opts) {
     const skill = findSkill(skillName, opts.baseDir ?? SKILLS_DIR);
     if (!skill) {
         process.stderr.write(`❌ skill not found: ${skillName}\n`);
-        return 2;
+        return EXIT.USAGE;
     }
     try {
+        const auth = await ensureAuth({
+            mode: skill.auth,
+            apiBaseUrl: typeof opts.parsedArgs.api_base_url === 'string' ? opts.parsedArgs.api_base_url : undefined,
+            flagToken: tokenFlag(opts.parsedArgs),
+        });
         switch (skill.entry.type) {
             case 'python':
-                return await runPython(skill, opts.rawArgs);
+                return await runPython(skill, opts.rawArgs, auth);
             case 'http':
             case 'builtin':
-                return await runHandler(skill, opts.parsedArgs);
+                return await runHandler(skill, opts.parsedArgs, auth);
         }
     }
     catch (err) {
@@ -31,10 +46,10 @@ export async function runSkill(skillName, opts) {
             return err.exitCode;
         }
         process.stderr.write(`❌ unexpected error: ${err.message}\n`);
-        return 1;
+        return EXIT.ERROR;
     }
 }
-async function runPython(skill, rawArgs) {
+async function runPython(skill, rawArgs, auth) {
     if (!skill.scriptAbsolutePath) {
         throw new SkillError(`skill ${skill.name} has entry.type=python but no scriptAbsolutePath`);
     }
@@ -43,21 +58,21 @@ async function runPython(skill, rawArgs) {
         const proc = spawn('python3', [skill.scriptAbsolutePath, ...rawArgs], {
             cwd,
             stdio: 'inherit',
-            env: { ...process.env, PYTHONUNBUFFERED: '1' },
+            env: { ...process.env, ...authChildEnv(auth), PYTHONUNBUFFERED: '1' },
         });
-        proc.on('exit', (code) => resolve(code ?? 1));
+        proc.on('exit', (code) => resolve(code ?? EXIT.ERROR));
         proc.on('error', (err) => {
             process.stderr.write(`❌ failed to spawn python3: ${err.message}\n`);
-            resolve(127);
+            resolve(EXIT.SPAWN_FAILED);
         });
     });
 }
-async function runHandler(skill, args) {
+async function runHandler(skill, args, auth) {
     const handlerKey = skill.entry.handler;
     const handler = HANDLERS[handlerKey];
     if (!handler) {
         throw new SkillError(`handler not registered: ${handlerKey} (skill ${skill.name})`);
     }
-    await handler(args, { skillName: skill.name });
-    return 0;
+    await handler(args, { skillName: skill.name, auth });
+    return EXIT.OK;
 }

package/dist/skill-schema.d.ts

@@ -38,6 +38,14 @@ export type SkillEntry = {
  */
 export type SkillCategory = 'authoring' | 'consuming' | 'asset' | 'meta';
 export declare const CATEGORY_VALUES: readonly ["authoring", "consuming", "asset", "meta"];
+/**
+ * Authorization requirement — consumed by the dispatcher's auth preflight.
+ * Semantics are documented on `AuthMode` in src/auth/ensure.ts (kept there so
+ * the runtime behavior and its description live together); this file only owns
+ * the literal values and their validation.
+ */
+export type SkillAuthMode = 'required' | 'optional' | 'none';
+export declare const AUTH_VALUES: readonly ["required", "optional", "none"];
 export interface RawSkillJson {
     name: string;
     toolName: string;
@@ -45,11 +53,22 @@ export interface RawSkillJson {
     title?: string;
     tier?: string;
     category?: SkillCategory;
+    auth?: SkillAuthMode;
     parameters?: Record<string, unknown>;
     scriptPath?: string;
     entry?: SkillEntry;
     envVars?: string[];
 }
+/**
+ * Resolve a skill's auth mode, defaulting for records that predate the field.
+ *
+ * The default is derived from `envVars` rather than hardcoded to `'required'`:
+ * a skill that never declared PRIV_TOKEN cannot possibly need a credential, and
+ * defaulting it to `required` would make a purely local skill (web-screenshot)
+ * pop a browser. Every skill shipped in this package declares `auth` explicitly,
+ * so this only covers externally supplied skill dirs (SKILL_BASE_DIR).
+ */
+export declare function resolveAuthMode(raw: Pick<RawSkillJson, 'auth' | 'envVars'>): SkillAuthMode;
 export declare const TIER_VALUES: readonly ["atomic", "orchestration", "tool"];
 export declare const REQUIRED_SKILL_JSON_FIELDS: readonly ["name", "tier", "title", "description"];
 /**

package/dist/skill-schema.js

@@ -12,6 +12,21 @@
  * the build treats them as fatal.
  */
 export const CATEGORY_VALUES = ['authoring', 'consuming', 'asset', 'meta'];
+export const AUTH_VALUES = ['required', 'optional', 'none'];
+/**
+ * Resolve a skill's auth mode, defaulting for records that predate the field.
+ *
+ * The default is derived from `envVars` rather than hardcoded to `'required'`:
+ * a skill that never declared PRIV_TOKEN cannot possibly need a credential, and
+ * defaulting it to `required` would make a purely local skill (web-screenshot)
+ * pop a browser. Every skill shipped in this package declares `auth` explicitly,
+ * so this only covers externally supplied skill dirs (SKILL_BASE_DIR).
+ */
+export function resolveAuthMode(raw) {
+    if (raw.auth)
+        return raw.auth;
+    return raw.envVars?.includes('PRIV_TOKEN') ? 'required' : 'none';
+}
 export const TIER_VALUES = ['atomic', 'orchestration', 'tool'];
 export const REQUIRED_SKILL_JSON_FIELDS = ['name', 'tier', 'title', 'description'];
 /**
@@ -43,6 +58,9 @@ export function validateSkillJson(raw, skillId) {
     if (raw.category != null && !CATEGORY_VALUES.includes(raw.category)) {
         errors.push(`skill.json.category must be one of ${CATEGORY_VALUES.join(' | ')}, got '${raw.category}'`);
     }
+    if (raw.auth != null && !AUTH_VALUES.includes(raw.auth)) {
+        errors.push(`skill.json.auth must be one of ${AUTH_VALUES.join(' | ')}, got '${raw.auth}'`);
+    }
     if (raw.name && raw.name !== skillId) {
         errors.push(`skill.json.name='${raw.name}' does not match directory name '${skillId}'`);
     }

package/dist/text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Terminal text helpers shared by the human-facing commands.
+ */
+/**
+ * Pad to a target terminal width. CJK characters occupy two columns but count as
+ * one code unit, so String.padEnd misaligns any column that contains them.
+ */
+export declare function padDisplay(text: string, width: number): string;

package/dist/text.js

@@ -0,0 +1,15 @@
+/**
+ * Terminal text helpers shared by the human-facing commands.
+ */
+// Ranges covering the CJK / fullwidth blocks the CLI's Chinese output uses.
+const WIDE = /[ᄀ-ᅟ⺀-䳿一-鿿가-힣豈-﫿︰-﹏＀-｠￠-￦]/;
+/**
+ * Pad to a target terminal width. CJK characters occupy two columns but count as
+ * one code unit, so String.padEnd misaligns any column that contains them.
+ */
+export function padDisplay(text, width) {
+    let cols = 0;
+    for (const ch of text)
+        cols += WIDE.test(ch) ? 2 : 1;
+    return text + ' '.repeat(Math.max(1, width - cols));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "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",
@@ -21,7 +21,7 @@
     "smoke": "node scripts/smoke.mjs",
     "test:cli": "npm run build && node --test test/*.test.mjs",
     "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
-    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-template-pipeline.py",
+    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
     "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
     "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",

package/skills/export-jianying/skill.json

@@ -5,6 +5,7 @@
   "category": "consuming",
   "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"],
   "scriptPath": "scripts/gen_jianying_draft.py",
   "parameters": {

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

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "Digital-Human Talking-Head",
   "description": "Digital-human video: list available avatars; produce a talking-head video from text via TTS, or drive an avatar from an existing audio URL.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
   "entry": { "type": "http", "handler": "gen-digital-human" },
   "parameters": {

package/skills/gen-image/skill.json

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "AI Image Generation",
   "description": "AI image generation: produce an image from a text prompt. Supports Seedream and Gemini models, plus image-to-image with reference images.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME", "MM_IMAGE_MODEL"],
   "entry": { "type": "http", "handler": "gen-image" },
   "parameters": {

package/skills/gen-script/SKILL.md

@@ -9,6 +9,8 @@ description: |
   - Turn a topic into a video structure / video content plan
 
   Even when the user does not say "generate the DSL", use this skill whenever they want to turn a topic into a structured video plan.
+
+  ⚠️ Stop-and-confirm gate: after this skill returns a DSL, show the full script and wait for the user's explicit confirmation. Never call `prepare_video_assets` in the same turn.
 triggers:
   - Write a video script, generate a video script, plan a video, write storyboards
   - Create a short video, plan video content, generate a Video DSL
@@ -19,6 +21,13 @@ triggers:
 
 Turns a user-supplied **topic** into a **Video DSL v1alpha1** JSON describing what the final video should look like (scene structure, asset requirements, narration text, visual layout). It never produces any asset itself.
 
+> ⚠️ **Stop-and-confirm gate (mandatory, do not skip).**
+> This skill produces a *draft* for the user to review, not an input to chain onward automatically.
+> After it returns, show the full script and **stop your turn** — wait for the user to explicitly confirm.
+> **Never** call `prepare_video_assets` in the same turn as `gen_script`: asset generation spends
+> image and TTS credits that cannot be refunded, and a wrong narration line means paying for the
+> whole batch twice. See **"Agent behavior: script confirmation"** below for the required summary format.
+
 ## Core concepts
 
 - **Video DSL**: a declarative description language for videos — describes the final structure, not the orchestration calls.
@@ -84,9 +93,19 @@ This skill does not hit any external API; no token required. The script only doe
 ### Confirmation flow
 
 1. After the agent generates or modifies the DSL, **show the script summary first; do not pass it downstream yet**.
-2. Wait for the user to explicitly confirm (e.g. "OK", "looks good", "continue with template binding") before handing it to `prepare-video-assets` (or `template-registry` for a list-only lookup).
+2. **End your turn there and wait** for the user to explicitly confirm (e.g. "OK", "looks good", "continue with template binding") before handing it to `prepare-video-assets` (or `template-registry` for a list-only lookup).
 3. If the user asks for changes (adjust narration, add or remove scenes, change durations), the agent updates the DSL and shows the summary again, then waits for confirmation once more.
 
+> ⚠️ **Never** call `prepare_video_assets` before the user has confirmed — not even when the original
+> request was a single end-to-end instruction like "make me a video about X". That request authorizes
+> the *pipeline*, not the skipping of its review steps. "Finish the task in one go" does **not** apply
+> here: stopping for confirmation **is** the correct completion of this step.
+
+### Showing the script
+
+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.
+
 ### Summary content
 
 The agent should show the following in clear Markdown:

package/skills/gen-script/skill.json

@@ -5,6 +5,7 @@
   "category": "authoring",
   "title": "Video Script Generation",
   "description": "Video script generation: turn a topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.",
+  "auth": "none",
   "envVars": ["DEFAULT_IMAGE_MODEL", "DEFAULT_VIDEO_MODEL", "STUB_IMAGE_URL", "STUB_VIDEO_URL"],
   "scriptPath": "scripts/gen_script.py",
   "parameters": {

package/skills/gen-video/skill.json

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "AI Video Generation",
   "description": "AI video generation: produce a short video clip from a text prompt. Supports Seedance and Veo models, plus first/last frame and reference images.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME", "MM_VIDEO_MODEL"],
   "entry": { "type": "http", "handler": "gen-video" },
   "parameters": {

package/skills/gen-voice/skill.json

@@ -5,6 +5,7 @@
   "category": "asset",
   "title": "Text-to-Speech (Minimax)",
   "description": "Text-to-speech (TTS): synthesize narration audio from text via the Minimax TTS model. Returns the persisted audio URL — no download needed.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
   "entry": { "type": "http", "handler": "gen-voice" },
   "parameters": {

package/skills/prepare-video-assets/SKILL.md

@@ -9,6 +9,8 @@ description: |
   - Regenerate one asset (image / audio) for a specific scene
 
   Next step: after the user confirms the resolved assets, call `render_video` with the `job_id` returned by this skill.
+
+  ⚠️ Stop-and-confirm gate: this skill runs only after the user has confirmed the script, and after it returns you must show the resolved assets and wait for the user's explicit confirmation. Never call `render_video` in the same turn.
 triggers:
   - Generate / prepare video assets
   - Resolve missing assets in a DSL
@@ -20,6 +22,14 @@ triggers:
 
 Phase 1 of the two-phase video pipeline. Takes a Video DSL plus a template binding, walks every `AssetRef` declared in the DSL, calls the matching atomic skills to fill in missing assets (`gen-image`, `gen-voice`, `gen-video`, `gen-digital-human`), persists the resulting RenderPlan to ab-api, and prints a `job_id` for the user-confirmation step.
 
+> ⚠️ **Stop-and-confirm gate (mandatory, do not skip) — both sides of this skill.**
+> **Before**: only run this skill after the user has confirmed the script produced by `gen_script`.
+> **After**: show the resolved assets (images inline, audio as links) and **stop your turn** — wait for
+> the user to explicitly confirm before rendering. **Never** call `render_video` in the same turn as
+> `prepare_video_assets`. This is the last checkpoint where a bad image or a wrong TTS take can be
+> fixed for the price of one asset instead of a whole re-render.
+> See **"Pre-render user confirmation (Phase 2)"** below for the required summary format.
+
 > **Next step**: after the user reviews the assets and confirms, call **`render_video`** with the `job_id` returned by this skill.
 
 ## Pipeline (this skill's part only)
@@ -94,7 +104,13 @@ python3 <SkillDir>/scripts/prepare_video_assets.py \
 
 ## Pre-render user confirmation (Phase 2)
 
-This skill is the **first half** of a two-phase user-confirmation flow. After it returns, the agent must show the user the resolved assets and wait for confirmation before calling `render_video`. The recommended summary format:
+This skill is the **first half** of a two-phase user-confirmation flow. After it returns, the agent **must** show the user the resolved assets, then **end its turn and wait** for confirmation before calling `render_video`.
+
+> ⚠️ **Never** start the final render before the user confirms. An end-to-end request ("make me a video
+> about X") authorizes the pipeline, not the skipping of its review steps — stopping here **is** the
+> correct completion of this step, not an unfinished task.
+
+Read the `job_id` from the stdout line `📦 render job jobId: N` and remember it; asset URLs come from the `🔊 TTS audio:` and `🖼  Image assets:` sections. Show images inline (`![name](https://...)`) and audio as links (`[🔊 listen](http://cdn.../x.mp3)`) so the user can actually review them. The recommended summary format:
 
 ```markdown
 ## Render confirmation

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

@@ -5,6 +5,7 @@
   "category": "authoring",
   "title": "Video Asset Preparation",
   "description": "Resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a job_id for the subsequent render_video call. This is Phase 1 of the two-phase video pipeline; Phase 3 (Remotion render) lives in render_video.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "MM_BACKEND_API_URL", "AGENT_NAME", "REMOTION_RENDER_API_URL", "REMOTION_RENDER_MODE", "REMOTION_OUTPUT_DIR", "ASSET_CACHE_DIR"],
   "scriptPath": "scripts/prepare_video_assets.py",
   "parameters": {

package/skills/render-video/SKILL.md

@@ -9,6 +9,8 @@ description: |
   - Render with Remotion
 
   Prerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.
+
+  ⚠️ Stop-and-confirm gate: never call this skill until the user has explicitly confirmed the assets prepared by `prepare_video_assets`. If those assets were prepared in the current turn and the user has not replied since, stop and ask instead of rendering.
 triggers:
   - Render the video, composite the video, export the video
   - Turn the prepared assets into the final clip
@@ -22,6 +24,17 @@ Loads a persisted RenderPlan from the database (or a local file fallback), compi
 
 > **Prerequisite**: assets must already be generated via `prepare_video_assets`. That skill returns a `job_id` integer; pass it here.
 
+> ⚠️ **Stop-and-confirm gate (mandatory, do not skip).**
+> **Never** call this skill until the user has explicitly confirmed the assets shown after
+> `prepare_video_assets`. If those assets were prepared in the current turn and the user has not
+> replied since, **stop and ask** — do not render. This step spends render credits and uploads the
+> result; it is the one action in the pipeline that cannot be walked back cheaply.
+>
+> "Confirmed" means the user said so **in a message of their own** (e.g. "confirm", "go ahead",
+> "looks good", "continue"). An end-to-end instruction from earlier in the conversation
+> ("make me a video about X") is **not** confirmation — it authorizes the pipeline, not the
+> skipping of its review steps. Stopping to ask **is** the correct completion of this step.
+
 ## Render pipeline (this skill's part only)
 
 ```