@sogni-ai/sogni-creative-agent-skill 2.0.0

package/sogni-agent.mjs

@@ -0,0 +1,4866 @@
+#!/usr/bin/env node
+/**
+ * sogni-agent - Generate images and videos using Sogni AI
+ * Usage: sogni-agent [options] "prompt"
+ */
+
+import { SogniClientWrapper, ClientEvent, getMaxContextImages } from '@sogni-ai/sogni-client-wrapper';
+import JSON5 from 'json5';
+import { createHash, randomBytes } from 'crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, mkdtempSync, statSync, readdirSync, realpathSync, lstatSync, unlinkSync, rmdirSync } from 'fs';
+import { join, dirname, basename, extname, sep } from 'path';
+import { homedir, tmpdir } from 'os';
+import sharp from 'sharp';
+import { getEnv, hasEnv } from './env.mjs';
+import { PACKAGE_VERSION } from './version.mjs';
+import { assertSafeUrl } from './ssrf-guard.mjs';
+
+// ---------------------------------------------------------------------------
+// Path sanitization — defense-in-depth for any value that becomes a file path
+// or process argument. execaSync runs argument arrays without shell expansion,
+// so classic shell injection is not possible. These checks guard against:
+//   • null-byte injection (can truncate paths at the C level)
+//   • control-character injection
+//   • FFMPEG_PATH pointing to a non-ffmpeg binary
+// ---------------------------------------------------------------------------
+
+/**
+ * Reject null bytes and control characters in a path string.
+ * Returns the path unchanged when valid; throws otherwise.
+ */
+function sanitizePath(p, label) {
+  if (typeof p !== 'string') {
+    const err = new Error(`${label || 'Path'} must be a string.`);
+    err.code = 'INVALID_PATH';
+    throw err;
+  }
+  if (p.includes('\0')) {
+    const err = new Error(`${label || 'Path'} contains a null byte.`);
+    err.code = 'INVALID_PATH';
+    throw err;
+  }
+  // Reject ASCII control characters except tab (\x09), newline (\x0a), carriage return (\x0d)
+  if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(p)) {
+    const err = new Error(`${label || 'Path'} contains invalid control characters.`);
+    err.code = 'INVALID_PATH';
+    throw err;
+  }
+  return p;
+}
+
+const DEFAULT_CREDENTIALS_PATH = join(homedir(), '.config', 'sogni', 'credentials');
+const DEFAULT_LAST_RENDER_PATH = join(homedir(), '.config', 'sogni', 'last-render.json');
+const DEFAULT_OPENCLAW_CONFIG_PATH = join(homedir(), '.openclaw', 'openclaw.json');
+const DEFAULT_MEDIA_INBOUND_DIR = join(homedir(), '.clawdbot', 'media', 'inbound');
+const DEFAULT_MEMORIES_PATH = join(homedir(), '.config', 'sogni', 'memories.json');
+const DEFAULT_PERSONALITY_PATH = join(homedir(), '.config', 'sogni', 'personality.txt');
+const DEFAULT_PERSONAS_DIR = join(homedir(), '.config', 'sogni', 'personas');
+const DEFAULT_PERSONAS_INDEX_PATH = join(homedir(), '.config', 'sogni', 'personas', 'index.json');
+const OPENCLAW_CONFIG_PATH = getEnv('OPENCLAW_CONFIG_PATH') || DEFAULT_OPENCLAW_CONFIG_PATH;
+const IS_OPENCLAW_INVOCATION = Boolean(getEnv('OPENCLAW_PLUGIN_CONFIG'));
+const RAW_ARGS = process.argv.slice(2);
+const CLI_WANTS_JSON = RAW_ARGS.includes('--json');
+const JSON_ERROR_MODE = CLI_WANTS_JSON || IS_OPENCLAW_INVOCATION;
+const LTX23_WORKFLOW_MODELS = {
+  t2v: 'ltx23-22b-fp8_t2v_distilled',
+  i2v: 'ltx23-22b-fp8_i2v_distilled',
+  ia2v: 'ltx23-22b-fp8_ia2v_distilled',
+  a2v: 'ltx23-22b-fp8_a2v_distilled',
+  v2v: 'ltx23-22b-fp8_v2v_distilled'
+};
+
+const SEEDANCE_WORKFLOW_MODELS = {
+  t2v: 'seedance-2-0_t2v',
+  t2vFast: 'seedance-2-0-fast_t2v',
+  ia2v: 'seedance-2-0_ia2v',
+  v2v: 'seedance-2-0_v2v'
+};
+
+const VIDEO_MODEL_REGISTRY = {
+  [LTX23_WORKFLOW_MODELS.t2v]: {
+    workflow: 't2v',
+    family: 'ltx23',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 640,
+    maxDimension: 3840,
+    dimensionMultiple: 64,
+    steps: 8,
+    guidance: 1.0,
+    fps: 24,
+    frameStep: 8,
+    minFrames: 25,
+    maxFrames: 505,
+    sampler: 'euler_ancestral',
+    scheduler: 'simple',
+    supportsNativeAudio: true
+  },
+  [LTX23_WORKFLOW_MODELS.i2v]: {
+    workflow: 'i2v',
+    family: 'ltx23',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 640,
+    maxDimension: 3840,
+    dimensionMultiple: 64,
+    steps: 8,
+    guidance: 1.0,
+    fps: 24,
+    frameStep: 8,
+    minFrames: 25,
+    maxFrames: 505,
+    sampler: 'euler_ancestral',
+    scheduler: 'simple',
+    supportsNativeAudio: true
+  },
+  [LTX23_WORKFLOW_MODELS.ia2v]: {
+    workflow: 'ia2v',
+    family: 'ltx23',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 640,
+    maxDimension: 3840,
+    dimensionMultiple: 64,
+    steps: 8,
+    guidance: 1.0,
+    fps: 24,
+    frameStep: 8,
+    minFrames: 25,
+    maxFrames: 505,
+    sampler: 'euler_ancestral',
+    scheduler: 'simple'
+  },
+  [LTX23_WORKFLOW_MODELS.a2v]: {
+    workflow: 'a2v',
+    family: 'ltx23',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 640,
+    maxDimension: 3840,
+    dimensionMultiple: 64,
+    steps: 8,
+    guidance: 1.0,
+    fps: 24,
+    frameStep: 8,
+    minFrames: 25,
+    maxFrames: 505,
+    sampler: 'euler_ancestral',
+    scheduler: 'simple'
+  },
+  [LTX23_WORKFLOW_MODELS.v2v]: {
+    workflow: 'v2v',
+    family: 'ltx23',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 640,
+    maxDimension: 3840,
+    dimensionMultiple: 64,
+    steps: 8,
+    guidance: 1.0,
+    fps: 25,
+    frameStep: 8,
+    minFrames: 25,
+    maxFrames: 505,
+    sampler: 'euler_ancestral',
+    scheduler: 'simple'
+  },
+  'wan_v2.2-14b-fp8_t2v_lightx2v': {
+    workflow: 't2v',
+    family: 'wan22',
+    defaultWidth: 640,
+    defaultHeight: 640,
+    minDimension: 480,
+    maxDimension: 1536,
+    dimensionMultiple: 16,
+    steps: 4,
+    guidance: 1.0,
+    fps: 32,
+    internalFps: 16,
+    frameStep: 1,
+    minFrames: 17,
+    maxFrames: 161,
+    sampler: 'euler',
+    scheduler: 'simple',
+    shift: 5.0
+  },
+  'wan_v2.2-14b-fp8_i2v_lightx2v': {
+    workflow: 'i2v',
+    family: 'wan22',
+    defaultWidth: 832,
+    defaultHeight: 480,
+    minDimension: 480,
+    maxDimension: 1536,
+    dimensionMultiple: 16,
+    steps: 4,
+    guidance: 1.0,
+    fps: 32,
+    internalFps: 16,
+    frameStep: 1,
+    minFrames: 17,
+    maxFrames: 321,
+    sampler: 'euler',
+    scheduler: 'simple',
+    shift: 8.0
+  },
+  'wan_v2.2-14b-fp8_s2v_lightx2v': {
+    workflow: 's2v',
+    family: 'wan22',
+    defaultWidth: 832,
+    defaultHeight: 480,
+    minDimension: 480,
+    maxDimension: 1536,
+    dimensionMultiple: 16,
+    steps: 4,
+    guidance: 1.0,
+    fps: 32,
+    internalFps: 16,
+    frameStep: 1,
+    minFrames: 17,
+    maxFrames: 321,
+    sampler: 'uni_pc',
+    scheduler: 'simple',
+    shift: 8.0
+  },
+  'wan_v2.2-14b-fp8_animate-move_lightx2v': {
+    workflow: 'animate-move',
+    family: 'wan22',
+    defaultWidth: 832,
+    defaultHeight: 480,
+    minDimension: 480,
+    maxDimension: 1536,
+    dimensionMultiple: 16,
+    steps: 4,
+    guidance: 1.0,
+    fps: 32,
+    internalFps: 16,
+    frameStep: 1,
+    minFrames: 17,
+    maxFrames: 321,
+    sampler: 'euler',
+    scheduler: 'simple',
+    shift: 8.0
+  },
+  'wan_v2.2-14b-fp8_animate-replace_lightx2v': {
+    workflow: 'animate-replace',
+    family: 'wan22',
+    defaultWidth: 832,
+    defaultHeight: 480,
+    minDimension: 480,
+    maxDimension: 1536,
+    dimensionMultiple: 16,
+    steps: 4,
+    guidance: 1.0,
+    fps: 32,
+    internalFps: 16,
+    frameStep: 1,
+    minFrames: 17,
+    maxFrames: 321,
+    sampler: 'euler',
+    scheduler: 'simple',
+    shift: 8.0
+  },
+  [SEEDANCE_WORKFLOW_MODELS.t2v]: {
+    workflow: 't2v',
+    family: 'seedance2',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 1,
+    maxDimension: 99999,
+    dimensionMultiple: 1,
+    fps: 24,
+    frameStep: 1,
+    minFrames: 97,
+    maxFrames: 361,
+    supportsNativeAudio: true
+  },
+  [SEEDANCE_WORKFLOW_MODELS.t2vFast]: {
+    workflow: 't2v',
+    family: 'seedance2',
+    defaultWidth: 1280,
+    defaultHeight: 720,
+    minDimension: 1,
+    maxDimension: 1280,
+    dimensionMultiple: 1,
+    fps: 24,
+    frameStep: 1,
+    minFrames: 97,
+    maxFrames: 361,
+    supportsNativeAudio: true
+  },
+  [SEEDANCE_WORKFLOW_MODELS.ia2v]: {
+    workflow: 'ia2v',
+    family: 'seedance2',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 1,
+    maxDimension: 99999,
+    dimensionMultiple: 1,
+    fps: 24,
+    frameStep: 1,
+    minFrames: 97,
+    maxFrames: 361
+  },
+  [SEEDANCE_WORKFLOW_MODELS.v2v]: {
+    workflow: 'v2v',
+    family: 'seedance2',
+    defaultWidth: 1920,
+    defaultHeight: 1088,
+    minDimension: 1,
+    maxDimension: 99999,
+    dimensionMultiple: 1,
+    fps: 24,
+    frameStep: 1,
+    minFrames: 96,
+    maxFrames: 360
+  }
+};
+
+for (const workflow of ['t2v', 'i2v', 'ia2v', 'a2v', 'v2v']) {
+  const ltx2Distilled = `ltx2-19b-fp8_${workflow}_distilled`;
+  const ltx2Quality = `ltx2-19b-fp8_${workflow}`;
+  const base = VIDEO_MODEL_REGISTRY[LTX23_WORKFLOW_MODELS[workflow]];
+  if (!base) continue;
+  VIDEO_MODEL_REGISTRY[ltx2Distilled] = {
+    ...base,
+    family: 'ltx2',
+    defaultWidth: 768,
+    defaultHeight: 768,
+    minDimension: 480,
+    maxDimension: 1536,
+    steps: 8,
+    supportsNativeAudio: workflow === 't2v' || workflow === 'i2v'
+  };
+  VIDEO_MODEL_REGISTRY[ltx2Quality] = {
+    ...VIDEO_MODEL_REGISTRY[ltx2Distilled],
+    steps: 20
+  };
+}
+
+const VIDEO_WORKFLOW_DEFAULT_MODELS = {
+  't2v': LTX23_WORKFLOW_MODELS.t2v,
+  'i2v': 'wan_v2.2-14b-fp8_i2v_lightx2v',
+  's2v': 'wan_v2.2-14b-fp8_s2v_lightx2v',
+  'ia2v': LTX23_WORKFLOW_MODELS.ia2v,
+  'a2v': LTX23_WORKFLOW_MODELS.a2v,
+  'animate-move': 'wan_v2.2-14b-fp8_animate-move_lightx2v',
+  'animate-replace': 'wan_v2.2-14b-fp8_animate-replace_lightx2v',
+  'v2v': LTX23_WORKFLOW_MODELS.v2v
+};
+
+function isLtx2Model(modelId) { return modelId?.startsWith('ltx2-') || modelId?.startsWith('ltx23-') || false; }
+function isWanModel(modelId) { return modelId?.startsWith('wan_') || false; }
+function isSeedanceModel(modelId) { return modelId?.startsWith('seedance-2-0') || false; }
+
+function resolveVideoControlNetStrength(name, explicitStrength) {
+  if (explicitStrength !== null && explicitStrength !== undefined) return explicitStrength;
+  return name === 'detailer' ? 1.0 : 0.85;
+}
+
+const VIDEO_MODEL_ALIASES = {
+  ltx23: LTX23_WORKFLOW_MODELS.t2v,
+  'ltx23-t2v': LTX23_WORKFLOW_MODELS.t2v,
+  'ltx23-i2v': LTX23_WORKFLOW_MODELS.i2v,
+  'ltx23-ia2v': LTX23_WORKFLOW_MODELS.ia2v,
+  'ltx23-a2v': LTX23_WORKFLOW_MODELS.a2v,
+  'ltx23-v2v': LTX23_WORKFLOW_MODELS.v2v,
+  wan22: 'wan_v2.2-14b-fp8_t2v_lightx2v',
+  'wan22-t2v': 'wan_v2.2-14b-fp8_t2v_lightx2v',
+  'wan22-i2v': 'wan_v2.2-14b-fp8_i2v_lightx2v',
+  'wan22-s2v': 'wan_v2.2-14b-fp8_s2v_lightx2v',
+  'wan22-animate-move': 'wan_v2.2-14b-fp8_animate-move_lightx2v',
+  'wan22-animate-replace': 'wan_v2.2-14b-fp8_animate-replace_lightx2v',
+  seedance2: SEEDANCE_WORKFLOW_MODELS.t2v,
+  'seedance2-t2v': SEEDANCE_WORKFLOW_MODELS.t2v,
+  'seedance2-fast': SEEDANCE_WORKFLOW_MODELS.t2vFast,
+  'seedance2-fast-t2v': SEEDANCE_WORKFLOW_MODELS.t2vFast,
+  'seedance2-ia2v': SEEDANCE_WORKFLOW_MODELS.ia2v,
+  'seedance2-v2v': SEEDANCE_WORKFLOW_MODELS.v2v
+};
+
+function resolveVideoModelAlias(modelId, workflow) {
+  if (!modelId) return modelId;
+  const key = String(modelId).trim().toLowerCase();
+  if (key === 'ltx23' && workflow && LTX23_WORKFLOW_MODELS[workflow]) {
+    return LTX23_WORKFLOW_MODELS[workflow];
+  }
+  if (key === 'wan22' && workflow) {
+    return VIDEO_WORKFLOW_DEFAULT_MODELS[workflow] || VIDEO_MODEL_ALIASES.wan22;
+  }
+  if (key === 'seedance2' && workflow && SEEDANCE_WORKFLOW_MODELS[workflow]) {
+    return SEEDANCE_WORKFLOW_MODELS[workflow];
+  }
+  return VIDEO_MODEL_ALIASES[key] || modelId;
+}
+
+function getBuiltinVideoModelConfig(modelId) {
+  if (!modelId) return null;
+  const id = resolveVideoModelAlias(modelId);
+  if (VIDEO_MODEL_REGISTRY[id]) return VIDEO_MODEL_REGISTRY[id];
+  const workflow = inferVideoWorkflowFromModel(id);
+  if (!workflow) return null;
+  if (id.startsWith('ltx23-') && LTX23_WORKFLOW_MODELS[workflow]) {
+    return VIDEO_MODEL_REGISTRY[LTX23_WORKFLOW_MODELS[workflow]] || null;
+  }
+  if (id.startsWith('ltx2-')) {
+    return {
+      workflow,
+      family: 'ltx2',
+      defaultWidth: 768,
+      defaultHeight: 768,
+      minDimension: 480,
+      maxDimension: 1536,
+      dimensionMultiple: 64,
+      steps: id.includes('distilled') ? 8 : 20,
+      guidance: 1.0,
+      fps: workflow === 'v2v' ? 25 : 24,
+      frameStep: 8,
+      minFrames: 25,
+      maxFrames: 321,
+      sampler: 'euler_ancestral',
+      scheduler: 'simple'
+    };
+  }
+  if (isWanModel(id)) {
+    return {
+      workflow,
+      family: 'wan22',
+      defaultWidth: workflow === 't2v' ? 640 : 832,
+      defaultHeight: workflow === 't2v' ? 640 : 480,
+      minDimension: 480,
+      maxDimension: 1536,
+      dimensionMultiple: 16,
+      steps: id.includes('lightx2v') ? 4 : 20,
+      guidance: 1.0,
+      fps: 32,
+      internalFps: 16,
+      frameStep: 1,
+      minFrames: 17,
+      maxFrames: workflow === 't2v' ? 161 : 321,
+      sampler: workflow === 's2v' ? 'uni_pc' : 'euler',
+      scheduler: 'simple',
+      shift: workflow === 't2v' ? 5.0 : 8.0
+    };
+  }
+  return null;
+}
+
+function expandHomePath(rawPath) {
+  if (typeof rawPath !== 'string') return rawPath;
+  if (rawPath === '~') return homedir();
+  if (rawPath.startsWith('~/') || rawPath.startsWith('~\\')) {
+    return join(homedir(), rawPath.slice(2));
+  }
+  return rawPath;
+}
+
+function resolveConfiguredPath(rawPath, fallbackPath, label) {
+  const candidate = expandHomePath(rawPath) || fallbackPath;
+  return sanitizePath(candidate, label);
+}
+
+function isPathWithinBase(basePath, targetPath) {
+  return targetPath === basePath || targetPath.startsWith(`${basePath}${sep}`);
+}
+
+function buildCliErrorPayload({ message, code, details, hint, prompt }) {
+  const payload = {
+    success: false,
+    error: message || 'Unknown error',
+    prompt: prompt ?? null
+  };
+  if (code) payload.errorCode = code;
+  if (details) payload.errorDetails = details;
+  if (hint) payload.hint = hint;
+  payload.timestamp = new Date().toISOString();
+  payload.node = process.versions.node;
+  payload.cwd = process.cwd();
+  if (IS_OPENCLAW_INVOCATION) payload.openclaw = true;
+  return payload;
+}
+
+function fatalCliError(message, opts = {}) {
+  let prompt = opts.prompt;
+  if (prompt === undefined) {
+    try {
+      // If parsing already populated options, include prompt for better downstream reporting.
+      prompt = options?.prompt ?? null;
+    } catch (e) {
+      prompt = null;
+    }
+  }
+  const payload = buildCliErrorPayload({
+    message,
+    code: opts.code,
+    details: opts.details,
+    hint: opts.hint,
+    prompt
+  });
+
+  if (JSON_ERROR_MODE) {
+    console.log(JSON.stringify(payload));
+    if (!CLI_WANTS_JSON) {
+      // OpenClaw expects JSON, but humans still benefit from stderr.
+      console.error(`Error: ${payload.error}`);
+      if (payload.hint) console.error(`Hint: ${payload.hint}`);
+    }
+  } else {
+    console.error(`Error: ${payload.error}`);
+    if (payload.hint) console.error(`Hint: ${payload.hint}`);
+  }
+  process.exit(1);
+}
+
+function normalizeVideoWorkflow(value) {
+  if (!value) return null;
+  const normalized = value.toLowerCase();
+  if (normalized === 't2v' || normalized === 'text-to-video') return 't2v';
+  if (normalized === 'i2v' || normalized === 'image-to-video') return 'i2v';
+  if (normalized === 's2v' || normalized === 'sound-to-video') return 's2v';
+  if (normalized === 'ia2v' || normalized === 'image-audio-to-video' || normalized === 'image+audio-to-video') return 'ia2v';
+  if (normalized === 'a2v' || normalized === 'audio-to-video') return 'a2v';
+  if (normalized === 'animate-move' || normalized === 'animate_move') return 'animate-move';
+  if (normalized === 'animate-replace' || normalized === 'animate_replace') return 'animate-replace';
+  if (normalized === 'v2v' || normalized === 'video-to-video') return 'v2v';
+  return null;
+}
+
+function inferVideoWorkflowFromModel(modelId) {
+  if (!modelId) return null;
+  const id = resolveVideoModelAlias(modelId).toLowerCase();
+  if (id.includes('animate-move')) return 'animate-move';
+  if (id.includes('animate-replace')) return 'animate-replace';
+  if (id.includes('_v2v')) return 'v2v';
+  if (id.includes('_ia2v')) return 'ia2v';
+  if (id.includes('_a2v')) return 'a2v';
+  if (id.includes('_t2v') || id.includes('-t2v')) return 't2v';
+  if (id.includes('_i2v') || id.includes('-i2v')) return 'i2v';
+  if (id.includes('_s2v') || id.includes('-s2v')) return 's2v';
+  return null;
+}
+
+function promptExplicitlyDisablesSpeech(prompt) {
+  return /\b(no dialogue|no speech|without dialogue|without speech|silent|no voiceover|no voice-over)\b/i.test(prompt || '');
+}
+
+function containsQuotedDialogue(prompt) {
+  return /"[^"]{1,400}"/.test(prompt || '');
+}
+
+function promptMentionsSpeech(prompt) {
+  if (!prompt || promptExplicitlyDisablesSpeech(prompt)) return false;
+  return /\b(dialogue|speaks?|speaking|says?|said|asks?|asked|whispers?|shouts?|yells?|narrates?|narration|voiceover|voice-over|conversation|monologue|interview|talking|tells? (?:a )?story)\b/i.test(prompt);
+}
+
+function promptMentionsAudio(prompt) {
+  if (!prompt) return false;
+  return /\b(audio|sound|sounds|ambient sound|music|song|singing|sings|voice|voices|dialogue|speech|voiceover|voice-over|narration|foley)\b/i.test(prompt);
+}
+
+function promptLooksLikeLongFormStory(prompt) {
+  return /\b(story|screenplay|script|scene|episode|short film|commercial|storyboard|chapter|narrative)\b/i.test(prompt || '');
+}
+
+function promptLooksLikeLipSync(prompt) {
+  return /\b(lip[- ]?sync|lipsync|talking head|mouth movement|sync(?:hronize)? (?:the )?(?:lips|mouth|speech)|face speaks|sing along)\b/i.test(prompt || '');
+}
+
+function promptNeedsLtxNativeAudio(prompt) {
+  return !promptExplicitlyDisablesSpeech(prompt) && (
+    containsQuotedDialogue(prompt) ||
+    promptMentionsSpeech(prompt) ||
+    promptMentionsAudio(prompt) ||
+    promptLooksLikeLongFormStory(prompt)
+  );
+}
+
+function normalizeScreenplayDialogueQuotes(prompt) {
+  if (!prompt) return prompt;
+  return prompt
+    .replace(/^(\s*[A-Za-z][A-Za-z0-9 _.-]{0,48}:\s*)'([^'\n]{1,300})'/gm, '$1"$2"')
+    .replace(/([\s(])'([^'\n]{1,180})'(?=[\s).,!?:;]|$)/g, '$1"$2"');
+}
+
+function extractQuotedDialogueSegments(prompt) {
+  const matches = [];
+  const pattern = /"([^"]{1,800})"/g;
+  let match;
+  while ((match = pattern.exec(prompt || '')) !== null) {
+    matches.push(match[1]);
+  }
+  return matches;
+}
+
+function countWords(text) {
+  const words = String(text || '').trim().match(/\b[\w'-]+\b/g);
+  return words ? words.length : 0;
+}
+
+function quotedDialogueWordCount(prompt) {
+  return extractQuotedDialogueSegments(prompt).reduce((sum, segment) => sum + countWords(segment), 0);
+}
+
+function suggestedDurationForDialogue(prompt, currentDuration) {
+  const words = quotedDialogueWordCount(prompt);
+  if (words <= 0) return currentDuration;
+  const speechSeconds = Math.ceil(words / 2.5) + 2;
+  return Math.max(currentDuration, Math.min(20, speechSeconds));
+}
+
+function formatAudioIdPrompt(prompt, voiceName) {
+  if (!prompt || /\[VISUAL\]|\[SPEECH\]|\[SOUNDS\]/i.test(prompt)) return prompt;
+  const dialogue = extractQuotedDialogueSegments(prompt);
+  const speechLines = dialogue.length > 0
+    ? dialogue.map((line, index) => `${voiceName || `SPEAKER_${index + 1}`}: "${line}"`).join('\n')
+    : 'No spoken dialogue unless exact quoted words are present in the visual prompt.';
+  return [
+    '[VISUAL]',
+    prompt.trim(),
+    '',
+    '[SPEECH]',
+    speechLines,
+    '',
+    '[SOUNDS]',
+    'Use natural ambient sound that matches the scene unless the prompt specifies silence.'
+  ].join('\n');
+}
+
+function applyVideoPromptGuardrails() {
+  if (!options.video || !options.prompt) return;
+
+  const normalizedPrompt = normalizeScreenplayDialogueQuotes(options.prompt);
+  if (normalizedPrompt !== options.prompt) {
+    options.prompt = normalizedPrompt;
+    if (!options.quiet) {
+      console.error('Normalized screenplay dialogue to double quotes for video prompting.');
+    }
+  }
+
+  if (promptMentionsSpeech(options.prompt) && !containsQuotedDialogue(options.prompt) && !options.quiet) {
+    console.error(
+      'Warning: video prompt mentions speech/dialogue but has no exact spoken words in double quotes. ' +
+      'LTX native audio works best with concrete quoted dialogue.'
+    );
+  }
+
+  if (!options.frames && !cliSet.duration) {
+    const suggested = suggestedDurationForDialogue(options.prompt, options.duration);
+    if (suggested > options.duration) {
+      if (!options.quiet) {
+        console.error(`Auto-extended video duration from ${options.duration}s to ${suggested}s to fit quoted dialogue.`);
+      }
+      options.duration = suggested;
+    }
+  } else if (!options.quiet) {
+    const dialogueWords = quotedDialogueWordCount(options.prompt);
+    const hardBudget = Math.floor((options.frames ? options.frames / options.fps : options.duration) * 3.75);
+    if (dialogueWords > hardBudget) {
+      console.error(
+        `Warning: quoted dialogue has about ${dialogueWords} words, which may not fit in ` +
+        `${options.frames ? `${options.frames} frames` : `${options.duration}s`}.`
+      );
+    }
+  }
+
+  if (options.referenceAudioIdentity) {
+    options.prompt = formatAudioIdPrompt(options.prompt, options._voicePersonaResolvedName || options.voicePersonaName || 'SPEAKER');
+  }
+}
+
+function inferVideoWorkflowFromAssets(opts) {
+  if (opts.refVideo && opts.videoControlNetName) return 'v2v';
+  if (opts.refVideo) return 'animate-move';
+  if (opts.refAudio && !opts.refImage && !opts.refImageEnd) return 'a2v';
+  if (opts.refAudio && opts.refImage) return promptLooksLikeLipSync(opts.prompt) ? 's2v' : 'ia2v';
+  if (opts.refAudio) return 's2v';
+  if (opts.refImage || opts.refImageEnd) return 'i2v';
+  return null;
+}
+
+function workflowRequiresImage(workflow) {
+  return workflow === 'i2v' || workflow === 's2v' || workflow === 'ia2v' || workflow === 'animate-move' || workflow === 'animate-replace';
+}
+
+function normalizeSeedStrategy(value) {
+  if (!value) return null;
+  const normalized = value.toLowerCase();
+  if (normalized === 'random') return 'random';
+  if (normalized === 'prompt-hash' || normalized === 'prompt_hash') return 'prompt-hash';
+  return null;
+}
+
+function generateRandomSeed() {
+  return randomBytes(4).readUInt32BE(0);
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic prompt variations — {option1|option2|option3} syntax
+// For count > 1, cycles through options sequentially per image.
+// ---------------------------------------------------------------------------
+const VARIATION_PATTERN = /\{([^}]+)\}/g;
+
+function hasPromptVariations(prompt) {
+  return /\{[^}]+\}/.test(prompt);
+}
+
+function expandPromptVariation(prompt, index) {
+  return prompt.replace(VARIATION_PATTERN, (_match, group) => {
+    const options = group.split('|').map(s => s.trim());
+    return options[index % options.length];
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Prompt sanitization — strip grid/collage-causing phrases for batch generation
+// Prevents models from rendering grids inside single images when count > 1.
+// ---------------------------------------------------------------------------
+const BATCH_SANITIZE_PATTERNS = [
+  /\b\d+\s+different\b/gi,
+  /\b\d+\s+versions?\b/gi,
+  /\b\d+\s+variations?\b/gi,
+  /\b\d+\s+separate\b/gi,
+  /\bdifferent\s+(?:expressions?|poses?|angles?|versions?|styles?)\b/gi,
+  /\bvarious\s+(?:expressions?|poses?|angles?)\b/gi,
+  /\bmultiple\s+(?:versions?|images?|photos?)\b/gi,
+  /\b(?:grid|collage|montage|triptych|side-by-side|split-screen|mood\s*board)\b/gi,
+  /\beach\s+(?:with|one|showing)\b/gi,
+  /\b(?:switch|mix)\s+up\b/gi,
+  /\bput\s+them\s+(?:all\s+)?together\b/gi,
+  /\ball\s+together\b/gi,
+  /\bin\s+one\s+image\b/gi,
+  /\brepeated?\s*(?:\d+\s*times?)?\b/gi,
+];
+
+function sanitizeBatchPrompt(prompt) {
+  let result = prompt;
+  for (const pattern of BATCH_SANITIZE_PATTERNS) {
+    result = result.replace(pattern, '');
+  }
+  // Clean up extra whitespace
+  return result.replace(/\s{2,}/g, ' ').trim();
+}
+
+function computePromptHashSeed(opts) {
+  const payload = {
+    prompt: opts.prompt || '',
+    model: opts.model || '',
+    workflow: opts.video ? opts.videoWorkflow : 'image',
+    width: opts.width,
+    height: opts.height,
+    azimuth: opts.azimuth || '',
+    elevation: opts.elevation || '',
+    distance: opts.distance || '',
+    angleDescription: opts.angleDescription || '',
+    outputFormat: opts.outputFormat || '',
+    sampler: opts.sampler || '',
+    scheduler: opts.scheduler || '',
+    targetResolution: opts.targetResolution ?? null,
+    loras: opts.loras || [],
+    loraStrengths: opts.loraStrengths || [],
+    refImage: opts.refImage || '',
+    refImageEnd: opts.refImageEnd || '',
+    refAudio: opts.refAudio || '',
+    audioStart: opts.audioStart ?? null,
+    audioDuration: opts.audioDuration ?? null,
+    referenceAudioIdentity: opts.referenceAudioIdentity || '',
+    refVideo: opts.refVideo || '',
+    videoStart: opts.videoStart ?? null,
+    contextImages: opts.contextImages || [],
+    autoResizeVideoAssets: opts.autoResizeVideoAssets,
+    tokenType: opts.tokenType || '',
+    steps: opts.steps ?? null,
+    guidance: opts.guidance ?? null
+  };
+  const hash = createHash('sha256').update(JSON.stringify(payload)).digest();
+  return hash.readUInt32BE(0);
+}
+
+function parseCsv(value) {
+  if (!value) return [];
+  return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function parseNumberValue(raw, flagName) {
+  const num = Number(raw);
+  if (!Number.isFinite(num)) {
+    fatalCliError(`${flagName} must be a number.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName, value: raw }
+    });
+  }
+  return num;
+}
+
+function parseNonNegativeNumberValue(raw, flagName) {
+  const num = parseNumberValue(raw, flagName);
+  if (num < 0) {
+    fatalCliError(`${flagName} must be >= 0.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName, value: raw, min: 0 }
+    });
+  }
+  return num;
+}
+
+function parseNumberList(raw, flagName) {
+  const entries = parseCsv(raw);
+  return entries.map((entry) => parseNumberValue(entry, flagName));
+}
+
+function requireFlagValue(argv, index, flagName) {
+  const value = argv[index + 1];
+  if (value === undefined) {
+    fatalCliError(`${flagName} requires a value.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName }
+    });
+  }
+  return value;
+}
+
+function parseIntegerValue(raw, flagName) {
+  const num = Number(raw);
+  if (!Number.isInteger(num)) {
+    fatalCliError(`${flagName} must be an integer.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName, value: raw }
+    });
+  }
+  return num;
+}
+
+function parsePositiveIntegerValue(raw, flagName, min = 1) {
+  const num = parseIntegerValue(raw, flagName);
+  if (num < min) {
+    fatalCliError(`${flagName} must be >= ${min}.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName, value: raw, min }
+    });
+  }
+  return num;
+}
+
+function parseSeedValue(raw, flagName) {
+  const num = parseIntegerValue(raw, flagName);
+  if (num < 0 || num > 0xFFFFFFFF) {
+    fatalCliError(`${flagName} must be between 0 and 4294967295.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName, value: raw }
+    });
+  }
+  return num;
+}
+
+function getModelDefaults(modelId, config) {
+  if (!modelId) return null;
+  const normalizedModelId = resolveVideoModelAlias(modelId);
+  const builtin = getBuiltinVideoModelConfig(normalizedModelId);
+  const entry = config?.modelDefaults?.[normalizedModelId] || config?.modelDefaults?.[modelId];
+  if (!entry || typeof entry !== 'object') return builtin;
+  return { ...(builtin || {}), ...entry };
+}
+
+function selectDefaultVideoModel(workflow, opts, config) {
+  if (!workflow) return null;
+  const configured = config?.videoModels?.[workflow];
+  if (configured) return resolveVideoModelAlias(configured, workflow);
+  if (workflow === 'ia2v') return LTX23_WORKFLOW_MODELS.ia2v;
+  if (workflow === 'a2v') return LTX23_WORKFLOW_MODELS.a2v;
+  if (workflow === 'v2v') return LTX23_WORKFLOW_MODELS.v2v;
+  if (workflow === 't2v') return LTX23_WORKFLOW_MODELS.t2v;
+  if (workflow === 'i2v' && (opts.referenceAudioIdentity || promptNeedsLtxNativeAudio(opts.prompt) || opts.quality === 'hq' || opts.quality === 'pro')) {
+    return LTX23_WORKFLOW_MODELS.i2v;
+  }
+  return VIDEO_WORKFLOW_DEFAULT_MODELS[workflow] || null;
+}
+
+function dimensionsWithShortSide(width, height, shortSide) {
+  const w = Number(width);
+  const h = Number(height);
+  const s = Number(shortSide);
+  if (!Number.isFinite(w) || !Number.isFinite(h) || !Number.isFinite(s) || w <= 0 || h <= 0 || s <= 0) {
+    return { width, height };
+  }
+  const currentShort = Math.min(w, h);
+  const scale = s / currentShort;
+  return {
+    width: Math.round(w * scale),
+    height: Math.round(h * scale)
+  };
+}
+
+function formatTokenValue(value) {
+  if (!Number.isFinite(value)) return 'unknown';
+  return value.toFixed(2);
+}
+
+function inferDefaultVideoSteps(modelId) {
+  const id = (modelId || '').toLowerCase();
+  if (isSeedanceModel(id)) return undefined;
+  if (isLtx2Model(id) && id.includes('distilled')) return 8;
+  if (id.includes('lightx2v')) return 4;
+  if (id.includes('lightning') || id.includes('turbo') || id.includes('lcm')) return 4;
+  if (isLtx2Model(id)) return 20;
+  return 20;
+}
+
+function resolveVideoSteps(modelId, modelDefaults, explicitSteps) {
+  if (Number.isFinite(explicitSteps)) return explicitSteps;
+  if (Number.isFinite(modelDefaults?.steps)) return modelDefaults.steps;
+  return inferDefaultVideoSteps(modelId);
+}
+
+function parseCostEstimate(estimate, tokenType) {
+  if (!estimate) return null;
+  const raw = tokenType === 'sogni'
+    ? estimate.sogni ?? estimate.token
+    : estimate.spark ?? estimate.token;
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) ? value : null;
+}
+
+function buildBalanceError(message, details) {
+  const err = new Error(message);
+  err.code = 'INSUFFICIENT_BALANCE';
+  err.details = details || null;
+  return err;
+}
+
+function gcdInt(a, b) {
+  let x = Math.abs(Math.trunc(a));
+  let y = Math.abs(Math.trunc(b));
+  while (y !== 0) {
+    const t = y;
+    y = x % y;
+    x = t;
+  }
+  return x || 1;
+}
+
+function isHttpUrl(value) {
+  return typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://'));
+}
+
+function getPngDimensions(buffer) {
+  if (!buffer || buffer.length < 24) return null;
+  // PNG signature: 89 50 4E 47 0D 0A 1A 0A
+  if (
+    buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4E || buffer[3] !== 0x47 ||
+    buffer[4] !== 0x0D || buffer[5] !== 0x0A || buffer[6] !== 0x1A || buffer[7] !== 0x0A
+  ) {
+    return null;
+  }
+  try {
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    if (!width || !height) return null;
+    return { width, height, type: 'png' };
+  } catch {
+    return null;
+  }
+}
+
+function getJpegDimensions(buffer) {
+  if (!buffer || buffer.length < 4) return null;
+  // JPEG SOI: FF D8
+  if (buffer[0] !== 0xFF || buffer[1] !== 0xD8) return null;
+
+  // Walk segments until we find a Start Of Frame marker that contains dimensions.
+  // Common SOF markers: C0 (baseline), C1, C2 (progressive), C3, C5-C7, C9-CB, CD-CF
+  let i = 2;
+  while (i + 9 < buffer.length) {
+    // Find marker prefix 0xFF
+    if (buffer[i] !== 0xFF) {
+      i++;
+      continue;
+    }
+    // Skip fill bytes 0xFF
+    while (i < buffer.length && buffer[i] === 0xFF) i++;
+    if (i >= buffer.length) break;
+    const marker = buffer[i];
+    i++;
+
+    // Markers without a length field
+    if (marker === 0xD9 || marker === 0xDA) break; // EOI or SOS
+    if (marker >= 0xD0 && marker <= 0xD7) continue; // RSTn
+
+    if (i + 1 >= buffer.length) break;
+    const segmentLength = buffer.readUInt16BE(i);
+    if (segmentLength < 2) break;
+    const segmentStart = i + 2;
+
+    const isSof =
+      (marker >= 0xC0 && marker <= 0xC3) ||
+      (marker >= 0xC5 && marker <= 0xC7) ||
+      (marker >= 0xC9 && marker <= 0xCB) ||
+      (marker >= 0xCD && marker <= 0xCF);
+
+    if (isSof) {
+      if (segmentStart + 7 >= buffer.length) break;
+      try {
+        const height = buffer.readUInt16BE(segmentStart + 1);
+        const width = buffer.readUInt16BE(segmentStart + 3);
+        if (!width || !height) return null;
+        return { width, height, type: 'jpg' };
+      } catch {
+        return null;
+      }
+    }
+
+    i = segmentStart + (segmentLength - 2);
+  }
+
+  return null;
+}
+
+function getImageDimensionsFromBuffer(buffer) {
+  return getPngDimensions(buffer) || getJpegDimensions(buffer);
+}
+
+const DEFAULT_VIDEO_DIMENSION_RULES = {
+  minDimension: 480,
+  maxDimension: 1536,
+  dimensionMultiple: 16
+};
+const VIDEO_DIMENSION_MULTIPLE = DEFAULT_VIDEO_DIMENSION_RULES.dimensionMultiple;
+
+function videoDimensionRulesFromDefaults(modelDefaults) {
+  return {
+    minDimension: modelDefaults?.minDimension || DEFAULT_VIDEO_DIMENSION_RULES.minDimension,
+    maxDimension: modelDefaults?.maxDimension || DEFAULT_VIDEO_DIMENSION_RULES.maxDimension,
+    dimensionMultiple: modelDefaults?.dimensionMultiple || DEFAULT_VIDEO_DIMENSION_RULES.dimensionMultiple
+  };
+}
+
+/**
+ * Resizes an image buffer to model-compatible dimensions while maintaining aspect ratio.
+ * Uses sharp's fit:inside to preserve aspect, then rounds to the model divisor.
+ */
+async function resizeImageBufferForVideo(buffer, originalWidth, originalHeight, rules = DEFAULT_VIDEO_DIMENSION_RULES) {
+  const multiple = rules.dimensionMultiple || VIDEO_DIMENSION_MULTIPLE;
+  const roundToMultiple = (n) => Math.max(multiple, Math.round(n / multiple) * multiple);
+  const targetWidth = Math.max(rules.minDimension, Math.min(rules.maxDimension, roundToMultiple(originalWidth)));
+  const targetHeight = Math.max(rules.minDimension, Math.min(rules.maxDimension, roundToMultiple(originalHeight)));
+
+  // Resize using sharp with fit:inside (maintains aspect ratio)
+  const resizedBuffer = await sharp(buffer)
+    .resize(targetWidth, targetHeight, { fit: 'inside', withoutEnlargement: false })
+    .toBuffer();
+
+  // Get actual dimensions after resize
+  const metadata = await sharp(resizedBuffer).metadata();
+  const actualWidth = roundToMultiple(metadata.width);
+  const actualHeight = roundToMultiple(metadata.height);
+
+  // If dimensions aren't exactly model-compatible, do a final resize/crop.
+  if (metadata.width !== actualWidth || metadata.height !== actualHeight) {
+    return await sharp(resizedBuffer)
+      .resize(actualWidth, actualHeight, { fit: 'cover' })
+      .toBuffer();
+  }
+
+  return resizedBuffer;
+}
+
+function normalizeVideoDimensionsLikeWrapper(width, height, rules = DEFAULT_VIDEO_DIMENSION_RULES) {
+  let targetWidth = Number(width);
+  let targetHeight = Number(height);
+  let adjusted = false;
+
+  const effectiveMin = rules.minDimension || DEFAULT_VIDEO_DIMENSION_RULES.minDimension;
+  const effectiveMax = rules.maxDimension || DEFAULT_VIDEO_DIMENSION_RULES.maxDimension;
+  const effectiveMultiple = rules.dimensionMultiple || DEFAULT_VIDEO_DIMENSION_RULES.dimensionMultiple;
+
+  if (!Number.isFinite(targetWidth) || !Number.isFinite(targetHeight)) {
+    return { width: targetWidth, height: targetHeight, adjusted: false };
+  }
+
+  if (targetWidth > effectiveMax || targetHeight > effectiveMax) {
+    const scaleFactor = Math.min(effectiveMax / targetWidth, effectiveMax / targetHeight);
+    targetWidth = Math.floor(targetWidth * scaleFactor);
+    targetHeight = Math.floor(targetHeight * scaleFactor);
+    adjusted = true;
+  }
+
+  if (targetWidth < effectiveMin || targetHeight < effectiveMin) {
+    const scaleFactor = Math.max(effectiveMin / targetWidth, effectiveMin / targetHeight);
+    targetWidth = Math.floor(targetWidth * scaleFactor);
+    targetHeight = Math.floor(targetHeight * scaleFactor);
+    adjusted = true;
+    if (targetWidth > effectiveMax || targetHeight > effectiveMax) {
+      const downscaleFactor = Math.min(effectiveMax / targetWidth, effectiveMax / targetHeight);
+      targetWidth = Math.floor(targetWidth * downscaleFactor);
+      targetHeight = Math.floor(targetHeight * downscaleFactor);
+    }
+  }
+
+  const roundedWidth = Math.floor(targetWidth / effectiveMultiple) * effectiveMultiple;
+  const roundedHeight = Math.floor(targetHeight / effectiveMultiple) * effectiveMultiple;
+  if (roundedWidth !== targetWidth || roundedHeight !== targetHeight) {
+    adjusted = true;
+  }
+  targetWidth = roundedWidth;
+  targetHeight = roundedHeight;
+
+  if (targetWidth < effectiveMin) {
+    targetWidth = Math.ceil(effectiveMin / effectiveMultiple) * effectiveMultiple;
+    adjusted = true;
+  }
+  if (targetHeight < effectiveMin) {
+    targetHeight = Math.ceil(effectiveMin / effectiveMultiple) * effectiveMultiple;
+    adjusted = true;
+  }
+
+  return { width: targetWidth, height: targetHeight, adjusted };
+}
+
+function predictSharpInsideResizeDims(refWidth, refHeight, targetWidth, targetHeight) {
+  const rw = Number(refWidth);
+  const rh = Number(refHeight);
+  const tw = Number(targetWidth);
+  const th = Number(targetHeight);
+  if (!Number.isFinite(rw) || !Number.isFinite(rh) || !Number.isFinite(tw) || !Number.isFinite(th) || rw <= 0 || rh <= 0 || tw <= 0 || th <= 0) {
+    return null;
+  }
+
+  // Matches sharp(vips) behavior in SogniClientWrapper.resizeImageBuffer(..., fit: 'inside'):
+  // Choose limiting dimension; keep it exact; compute the other dimension with Math.round().
+  const scaleW = tw / rw;
+  const scaleH = th / rh;
+  const widthLimited = scaleW <= scaleH;
+  if (widthLimited) {
+    return { width: tw, height: Math.round(rh * tw / rw) };
+  }
+  return { width: Math.round(rw * th / rh), height: th };
+}
+
+function pickCompatibleI2vBoundingBox(refWidth, refHeight, desiredWidth, desiredHeight, { allowImperfect = false, rules = DEFAULT_VIDEO_DIMENSION_RULES } = {}) {
+  const effectiveMin = rules.minDimension || DEFAULT_VIDEO_DIMENSION_RULES.minDimension;
+  const effectiveMax = rules.maxDimension || DEFAULT_VIDEO_DIMENSION_RULES.maxDimension;
+  const effectiveMultiple = rules.dimensionMultiple || DEFAULT_VIDEO_DIMENSION_RULES.dimensionMultiple;
+  const desiredW = Number.isFinite(Number(desiredWidth)) ? Number(desiredWidth) : 512;
+  const desiredH = Number.isFinite(Number(desiredHeight)) ? Number(desiredHeight) : 512;
+  const desiredMax = Math.max(effectiveMin, Math.min(effectiveMax, Math.max(desiredW, desiredH)));
+  let best = null;
+  let bestImperfect = null;
+
+  for (let w = effectiveMin; w <= effectiveMax; w += effectiveMultiple) {
+    for (let h = effectiveMin; h <= effectiveMax; h += effectiveMultiple) {
+      const normalized = normalizeVideoDimensionsLikeWrapper(w, h, rules);
+      if (!Number.isFinite(normalized.width) || !Number.isFinite(normalized.height)) continue;
+      const out = predictSharpInsideResizeDims(refWidth, refHeight, normalized.width, normalized.height);
+      if (!out) continue;
+      // Require both output dimensions >= model minimum for API compatibility.
+      if (out.width < effectiveMin || out.height < effectiveMin) continue;
+
+      const isPerfect = out.width % effectiveMultiple === 0 && out.height % effectiveMultiple === 0;
+
+      const outMax = Math.max(out.width, out.height);
+      const distance = Math.abs(normalized.width - desiredW) + Math.abs(normalized.height - desiredH);
+      // Prefer a bounding box close to what the user asked for, then output close to requested max, then maximize output area.
+      const score = -distance * 1e9 - Math.abs(outMax - desiredMax) * 1e8 + out.width * out.height * 1e3 - (normalized.width * normalized.height);
+
+      if (isPerfect) {
+        if (!best || score > best.score) {
+          best = { width: normalized.width, height: normalized.height, output: out, score, perfect: true };
+        }
+      } else if (allowImperfect) {
+        // Track imperfect candidates: prefer those closest to the model divisor.
+        const widthRemainder = out.width % effectiveMultiple;
+        const heightRemainder = out.height % effectiveMultiple;
+        const divisorDistance = Math.min(widthRemainder, effectiveMultiple - widthRemainder) +
+                            Math.min(heightRemainder, effectiveMultiple - heightRemainder);
+        const imperfectScore = -divisorDistance * 1e10 + score;
+        if (!bestImperfect || imperfectScore > bestImperfect.score) {
+          const adjustedWidth = Math.round(out.width / effectiveMultiple) * effectiveMultiple;
+          const adjustedHeight = Math.round(out.height / effectiveMultiple) * effectiveMultiple;
+          bestImperfect = {
+            width: normalized.width,
+            height: normalized.height,
+            output: out,
+            adjustedOutput: { width: adjustedWidth, height: adjustedHeight },
+            score: imperfectScore,
+            perfect: false
+          };
+        }
+      }
+    }
+  }
+
+  return best || (allowImperfect ? bestImperfect : null);
+}
+
+const MULTI_ANGLE_AZIMUTHS = [
+  { key: 'front', prompt: 'front view' },
+  { key: 'front-right', prompt: 'front-right quarter view' },
+  { key: 'right', prompt: 'right side view' },
+  { key: 'back-right', prompt: 'back-right quarter view' },
+  { key: 'back', prompt: 'back view' },
+  { key: 'back-left', prompt: 'back-left quarter view' },
+  { key: 'left', prompt: 'left side view' },
+  { key: 'front-left', prompt: 'front-left quarter view' }
+];
+
+const MULTI_ANGLE_ELEVATIONS = [
+  { key: 'low-angle', prompt: 'low-angle shot' },
+  { key: 'eye-level', prompt: 'eye-level shot' },
+  { key: 'elevated', prompt: 'elevated shot' },
+  { key: 'high-angle', prompt: 'high-angle shot' }
+];
+
+const MULTI_ANGLE_DISTANCES = [
+  { key: 'close-up', prompt: 'close-up' },
+  { key: 'medium', prompt: 'medium shot' },
+  { key: 'wide', prompt: 'wide shot' }
+];
+
+const MULTI_ANGLE_AZIMUTH_ALIASES = new Map([
+  ['front-right quarter', 'front-right'],
+  ['front right quarter', 'front-right'],
+  ['back-right quarter', 'back-right'],
+  ['back right quarter', 'back-right'],
+  ['back-left quarter', 'back-left'],
+  ['back left quarter', 'back-left'],
+  ['front-left quarter', 'front-left'],
+  ['front left quarter', 'front-left']
+]);
+
+const MULTI_ANGLE_ELEVATION_ALIASES = new Map([
+  ['low angle', 'low-angle'],
+  ['eye level', 'eye-level'],
+  ['high angle', 'high-angle']
+]);
+
+const MULTI_ANGLE_DISTANCE_ALIASES = new Map([
+  ['close up', 'close-up'],
+  ['medium shot', 'medium'],
+  ['wide shot', 'wide']
+]);
+
+function normalizeMultiAngleValue(value, aliases, allowedKeys, label) {
+  if (!value) return null;
+  const normalized = value.toLowerCase().replace(/_/g, '-').replace(/\s+/g, ' ').trim();
+  const aliased = aliases.get(normalized) || normalized;
+  if (!allowedKeys.includes(aliased)) {
+    fatalCliError(`Invalid ${label} "${value}".`, {
+      code: 'INVALID_ARGUMENT',
+      details: { field: label, value, allowed: allowedKeys }
+    });
+  }
+  return aliased;
+}
+
+function buildMultiAnglePrompt({ azimuth, elevation, distance, description }) {
+  const azimuthPrompt = MULTI_ANGLE_AZIMUTHS.find((a) => a.key === azimuth)?.prompt;
+  const elevationPrompt = MULTI_ANGLE_ELEVATIONS.find((e) => e.key === elevation)?.prompt;
+  const distancePrompt = MULTI_ANGLE_DISTANCES.find((d) => d.key === distance)?.prompt;
+  const parts = ['<sks>', azimuthPrompt, elevationPrompt, distancePrompt].filter(Boolean);
+  if (description) parts.push(description);
+  return parts.join(' ');
+}
+
+function loadOpenClawPluginConfig() {
+  const openclawPluginConfig = getEnv('OPENCLAW_PLUGIN_CONFIG');
+  if (openclawPluginConfig) {
+    try {
+      return JSON5.parse(openclawPluginConfig);
+    } catch (e) {
+      return null;
+    }
+  }
+  if (!existsSync(OPENCLAW_CONFIG_PATH)) return null;
+  try {
+    const raw = readFileSync(OPENCLAW_CONFIG_PATH, 'utf8');
+    const parsed = JSON5.parse(raw);
+    return parsed?.plugins?.entries?.['sogni-creative-agent-skill']?.config || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+const openclawConfig = loadOpenClawPluginConfig();
+const CREDENTIALS_PATH = resolveConfiguredPath(
+  getEnv('SOGNI_CREDENTIALS_PATH') || openclawConfig?.credentialsPath,
+  DEFAULT_CREDENTIALS_PATH,
+  'SOGNI credentials path'
+);
+const LAST_RENDER_PATH = resolveConfiguredPath(
+  getEnv('SOGNI_LAST_RENDER_PATH') || openclawConfig?.lastRenderPath,
+  DEFAULT_LAST_RENDER_PATH,
+  'SOGNI last render path'
+);
+const MEDIA_INBOUND_DIR = resolveConfiguredPath(
+  getEnv('SOGNI_MEDIA_INBOUND_DIR') || openclawConfig?.mediaInboundDir,
+  DEFAULT_MEDIA_INBOUND_DIR,
+  'SOGNI media inbound path'
+);
+
+// Parse arguments
+const args = process.argv.slice(2);
+const options = {
+  prompt: null,
+  output: null,
+  model: null, // Will be set based on type
+  width: 512,
+  height: 512,
+  count: 1,
+  json: false,
+  quiet: false,
+  timeout: 30000,
+  strictSize: false,
+  quality: null, // Quality tier: fast|hq|pro — auto-selects model, steps, dimensions
+  tokenType: null,
+  steps: null,
+  guidance: null,
+  outputFormat: null,
+  sampler: null,
+  scheduler: null,
+  loras: [],
+  loraStrengths: [],
+  multiAngle: false,
+  angles360: false,
+  azimuth: 'front',
+  elevation: 'eye-level',
+  distance: 'medium',
+  angleStrength: null,
+  angleDescription: '',
+  seed: null,
+  lastSeed: false,
+  seedStrategy: null,
+  video: false,
+  videoWorkflow: null,
+  fps: 16,
+  duration: 5,
+  frames: null,
+  targetResolution: null, // Short-side target for video, preserving aspect ratio
+  autoResizeVideoAssets: null,
+  estimateVideoCost: false,
+  showBalance: false,
+  showVersion: false,
+  angles360Video: null,
+  refImage: null, // Reference image for video (start frame)
+  refImageEnd: null, // End frame for video interpolation
+  refAudio: null, // Uploaded/generated audio for ia2v/a2v, or s2v lip-sync
+  audioStart: null, // Optional start offset into reference audio
+  audioDuration: null, // Optional duration slice for reference audio
+  referenceAudioIdentity: null, // Voice identity reference for LTX native audio
+  voicePersonaName: null,
+  refVideo: null, // Reference video for animate workflows
+  videoStart: null, // Optional start offset into reference video
+  contextImages: [], // Context images for image editing
+  looping: false, // Create looping video (i2v only): generate A→B then B→A and concatenate
+  photobooth: false, // Photobooth mode (InstantID face transfer)
+  cnStrength: null, // ControlNet strength override
+  cnGuidanceEnd: null, // ControlNet guidance end override
+  videoControlNetName: null, // ControlNet name for v2v: canny|pose|depth|detailer
+  videoControlNetStrength: null, // ControlNet strength for v2v (0.0-1.0)
+  sam2Coordinates: null, // SAM2 coordinates for animate-replace [{x,y}]
+  trimEndFrame: false, // Trim last frame for seamless stitching
+  firstFrameStrength: null, // Keyframe interpolation (0.0-1.0)
+  lastFrameStrength: null, // Keyframe interpolation (0.0-1.0)
+  extractLastFrame: null, // --extract-last-frame <video> <image>
+  extractLastFrameOutput: null,
+  concatVideos: null, // --concat-videos <out> <clip1> <clip2> [...]
+  concatVideosClips: null,
+  concatAudio: null, // Optional audio file to mux over concatenated clips
+  concatAudioStart: null,
+  listMedia: null, // --list-media [images|audio|all]
+  // Memory, personality, persona commands
+  memoryAction: null, // set|get|list|remove
+  memoryKey: null,
+  memoryValue: null,
+  memoryCategory: null,
+  personalityAction: null, // set|get|clear
+  personalityText: null,
+  personaAction: null, // add|list|remove|resolve
+  personaName: null,
+  personaRelationship: null,
+  personaDescription: null,
+  personaTags: null,
+  personaVoice: null,
+  personaVoiceClip: null,
+  personaPhoto: null, // alias for --ref when used with --persona-add
+  noFilter: false // Disable NSFW content filter
+};
+const cliSet = {
+  output: false,
+  model: false,
+  width: false,
+  height: false,
+  count: false,
+  timeout: false,
+  strictSize: false,
+  quality: false,
+  tokenType: false,
+  steps: false,
+  guidance: false,
+  outputFormat: false,
+  sampler: false,
+  scheduler: false,
+  loras: false,
+  loraStrengths: false,
+  multiAngle: false,
+  azimuth: false,
+  elevation: false,
+  distance: false,
+  angleStrength: false,
+  angleDescription: false,
+  seed: false,
+  seedStrategy: false,
+  video: false,
+  workflow: false,
+  fps: false,
+  duration: false,
+  frames: false,
+  targetResolution: false,
+  autoResizeVideoAssets: false,
+  angles360Video: false,
+  videoModel: false,
+  refImage: false,
+  refImageEnd: false,
+  refAudio: false,
+  audioStart: false,
+  audioDuration: false,
+  referenceAudioIdentity: false,
+  voicePersonaName: false,
+  refVideo: false,
+  videoStart: false,
+  context: false,
+  looping: false,
+  photobooth: false,
+  cnStrength: false,
+  cnGuidanceEnd: false,
+  videoControlNetName: false,
+  videoControlNetStrength: false,
+  sam2Coordinates: false,
+  trimEndFrame: false,
+  firstFrameStrength: false,
+  lastFrameStrength: false
+};
+
+// Parse CLI args
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '-o' || arg === '--output') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.output = raw;
+    cliSet.output = true;
+  } else if (arg === '-m' || arg === '--model') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.model = raw;
+    cliSet.model = true;
+  } else if (arg === '-w' || arg === '--width') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.width = parsePositiveIntegerValue(raw, arg);
+    cliSet.width = true;
+  } else if (arg === '-h' || arg === '--height') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.height = parsePositiveIntegerValue(raw, arg);
+    cliSet.height = true;
+  } else if (arg === '-n' || arg === '--count') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.count = parsePositiveIntegerValue(raw, arg);
+    cliSet.count = true;
+  } else if (arg === '-t' || arg === '--timeout') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.timeout = parsePositiveIntegerValue(raw, arg) * 1000;
+    cliSet.timeout = true;
+  } else if (arg === '--quality' || arg === '-Q') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.quality = raw.toLowerCase();
+    cliSet.quality = true;
+  } else if (arg === '--token-type' || arg === '--token') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.tokenType = raw;
+    cliSet.tokenType = true;
+  } else if (arg === '--steps') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.steps = parsePositiveIntegerValue(raw, arg);
+    cliSet.steps = true;
+  } else if (arg === '--guidance') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.guidance = parseNumberValue(raw, arg);
+    cliSet.guidance = true;
+  } else if (arg === '--output-format' || arg === '--format') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.outputFormat = raw;
+    cliSet.outputFormat = true;
+  } else if (arg === '--sampler') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.sampler = raw;
+    cliSet.sampler = true;
+  } else if (arg === '--scheduler') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.scheduler = raw;
+    cliSet.scheduler = true;
+  } else if (arg === '--multi-angle' || arg === '--multiple-angles') {
+    options.multiAngle = true;
+    cliSet.multiAngle = true;
+  } else if (arg === '--angles-360') {
+    options.angles360 = true;
+    options.multiAngle = true;
+    cliSet.multiAngle = true;
+  } else if (arg === '--angles-360-video') {
+    options.angles360Video = true;
+    cliSet.angles360Video = true;
+    if (args[i + 1] && !args[i + 1].startsWith('-')) {
+      options.angles360Video = args[++i];
+    }
+  } else if (arg === '--video-model' || arg === '--i2v-model') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.videoModel = raw;
+    cliSet.videoModel = true;
+  } else if (arg === '--azimuth') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.azimuth = raw;
+    cliSet.azimuth = true;
+  } else if (arg === '--elevation') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.elevation = raw;
+    cliSet.elevation = true;
+  } else if (arg === '--distance') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.distance = raw;
+    cliSet.distance = true;
+  } else if (arg === '--angle-strength' || arg === '--strength') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.angleStrength = parseNumberValue(raw, arg);
+    cliSet.angleStrength = true;
+  } else if (arg === '--angle-description' || arg === '--angle-anchor' || arg === '--description' || arg === '--anchor') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.angleDescription = raw;
+    cliSet.angleDescription = true;
+  } else if (arg === '--lora' || arg === '--lora-model') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.loras.push(raw);
+    cliSet.loras = true;
+  } else if (arg === '--loras') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.loras.push(...parseCsv(raw));
+    cliSet.loras = true;
+  } else if (arg === '--lora-strength') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.loraStrengths.push(parseNumberValue(raw, arg));
+    cliSet.loraStrengths = true;
+  } else if (arg === '--lora-strengths') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.loraStrengths.push(...parseNumberList(raw, arg));
+    cliSet.loraStrengths = true;
+  } else if (arg === '-s' || arg === '--seed') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.seed = parseSeedValue(raw, arg);
+    cliSet.seed = true;
+  } else if (arg === '--seed-strategy') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.seedStrategy = raw;
+    cliSet.seedStrategy = true;
+  } else if (arg === '--last-seed' || arg === '--reseed') {
+    options.lastSeed = true;
+  } else if (arg === '--video' || arg === '-v') {
+    options.video = true;
+    cliSet.video = true;
+  } else if (arg === '--workflow') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.videoWorkflow = raw;
+    cliSet.workflow = true;
+  } else if (arg === '--fps') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.fps = parsePositiveIntegerValue(raw, arg);
+    cliSet.fps = true;
+  } else if (arg === '--duration') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.duration = parsePositiveIntegerValue(raw, arg);
+    cliSet.duration = true;
+  } else if (arg === '--frames') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.frames = parsePositiveIntegerValue(raw, arg);
+    cliSet.frames = true;
+  } else if (arg === '--target-resolution' || arg === '--short-side') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.targetResolution = parsePositiveIntegerValue(raw, arg);
+    cliSet.targetResolution = true;
+  } else if (arg === '--auto-resize-assets') {
+    options.autoResizeVideoAssets = true;
+    cliSet.autoResizeVideoAssets = true;
+  } else if (arg === '--no-auto-resize-assets') {
+    options.autoResizeVideoAssets = false;
+    cliSet.autoResizeVideoAssets = true;
+  } else if (arg === '--ref' || arg === '--reference') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.refImage = raw;
+    cliSet.refImage = true;
+  } else if (arg === '--ref-end' || arg === '--end') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.refImageEnd = raw;
+    cliSet.refImageEnd = true;
+  } else if (arg === '--ref-audio' || arg === '--audio') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.refAudio = raw;
+    cliSet.refAudio = true;
+  } else if (arg === '--audio-start') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.audioStart = parseNonNegativeNumberValue(raw, arg);
+    cliSet.audioStart = true;
+  } else if (arg === '--audio-duration') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.audioDuration = parseNonNegativeNumberValue(raw, arg);
+    cliSet.audioDuration = true;
+  } else if (arg === '--reference-audio-identity' || arg === '--voice-identity') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.referenceAudioIdentity = raw;
+    cliSet.referenceAudioIdentity = true;
+  } else if (arg === '--voice-persona') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.voicePersonaName = raw;
+    cliSet.voicePersonaName = true;
+  } else if (arg === '--ref-video') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.refVideo = raw;
+    cliSet.refVideo = true;
+  } else if (arg === '--video-start' || arg === '--video-start-offset') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.videoStart = parseNonNegativeNumberValue(raw, arg);
+    cliSet.videoStart = true;
+  } else if (arg === '--looping' || arg === '--loop') {
+    options.looping = true;
+    cliSet.looping = true;
+  } else if (arg === '-c' || arg === '--context') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.contextImages.push(raw);
+    cliSet.context = true;
+  } else if (arg === '--photobooth') {
+    options.photobooth = true;
+    cliSet.photobooth = true;
+  } else if (arg === '--cn-strength') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.cnStrength = parseNumberValue(raw, arg);
+    cliSet.cnStrength = true;
+  } else if (arg === '--cn-guidance-end') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.cnGuidanceEnd = parseNumberValue(raw, arg);
+    cliSet.cnGuidanceEnd = true;
+  } else if (arg === '--controlnet-name') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.videoControlNetName = raw;
+    cliSet.videoControlNetName = true;
+  } else if (arg === '--controlnet-strength') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.videoControlNetStrength = parseNumberValue(raw, arg);
+    cliSet.videoControlNetStrength = true;
+  } else if (arg === '--sam2-coordinates') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    // Parse "x,y" or "x1,y1;x2,y2" format
+    options.sam2Coordinates = raw.split(';').map(pair => {
+      const [x, y] = pair.split(',').map(Number);
+      if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        fatalCliError(`Invalid --sam2-coordinates format "${raw}". Use x,y or x1,y1;x2,y2.`, {
+          code: 'INVALID_ARGUMENT',
+          details: { flag: '--sam2-coordinates', value: raw }
+        });
+      }
+      return { x, y };
+    });
+    cliSet.sam2Coordinates = true;
+  } else if (arg === '--trim-end-frame') {
+    options.trimEndFrame = true;
+    cliSet.trimEndFrame = true;
+  } else if (arg === '--first-frame-strength') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.firstFrameStrength = parseNumberValue(raw, arg);
+    cliSet.firstFrameStrength = true;
+  } else if (arg === '--last-frame-strength') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.lastFrameStrength = parseNumberValue(raw, arg);
+    cliSet.lastFrameStrength = true;
+  } else if (arg === '--extract-last-frame') {
+    const videoArg = requireFlagValue(args, i, arg);
+    i++;
+    const imageArg = requireFlagValue(args, i, arg + ' (output image)');
+    i++;
+    options.extractLastFrame = videoArg;
+    options.extractLastFrameOutput = imageArg;
+  } else if (arg === '--concat-videos') {
+    // Consume remaining positional args: <output> <clip1> <clip2> [clip3...]
+    const outArg = requireFlagValue(args, i, arg + ' (output path)');
+    i++;
+    const clips = [];
+    while (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+      i++;
+      clips.push(args[i]);
+    }
+    if (clips.length < 2) {
+      fatalCliError('--concat-videos requires at least 2 clip paths after the output path.', {
+        code: 'INVALID_ARGUMENT',
+        details: { flag: '--concat-videos', clipsProvided: clips.length }
+      });
+    }
+    options.concatVideos = outArg;
+    options.concatVideosClips = clips;
+  } else if (arg === '--concat-audio') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.concatAudio = raw;
+  } else if (arg === '--concat-audio-start') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.concatAudioStart = parseNonNegativeNumberValue(raw, arg);
+  } else if (arg === '--list-media') {
+    // Optional type argument (images|audio|all), default: images
+    const next = args[i + 1];
+    if (next && !next.startsWith('-') && ['images', 'audio', 'all'].includes(next)) {
+      i++;
+      options.listMedia = next;
+    } else {
+      options.listMedia = 'images';
+    }
+  // --- Memory commands ---
+  } else if (arg === '--memory-set') {
+    options.memoryAction = 'set';
+    options.memoryKey = requireFlagValue(args, i, arg); i++;
+    options.memoryValue = requireFlagValue(args, i, arg + ' (value)'); i++;
+  } else if (arg === '--memory-get') {
+    options.memoryAction = 'get';
+    options.memoryKey = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--memory-list') {
+    options.memoryAction = 'list';
+  } else if (arg === '--memory-remove' || arg === '--memory-delete') {
+    options.memoryAction = 'remove';
+    options.memoryKey = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--memory-category') {
+    options.memoryCategory = requireFlagValue(args, i, arg); i++;
+  // --- Personality commands ---
+  } else if (arg === '--personality-set') {
+    options.personalityAction = 'set';
+    options.personalityText = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--personality-get') {
+    options.personalityAction = 'get';
+  } else if (arg === '--personality-clear') {
+    options.personalityAction = 'clear';
+  // --- Persona commands ---
+  } else if (arg === '--persona-add') {
+    options.personaAction = 'add';
+    options.personaName = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--persona-list') {
+    options.personaAction = 'list';
+  } else if (arg === '--persona-remove' || arg === '--persona-delete') {
+    options.personaAction = 'remove';
+    options.personaName = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--persona-resolve') {
+    options.personaAction = 'resolve';
+    options.personaName = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--persona') {
+    // Shorthand: resolve persona + generate with context
+    options.personaAction = 'generate';
+    options.personaName = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--relationship') {
+    options.personaRelationship = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--description') {
+    options.personaDescription = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--tags') {
+    options.personaTags = requireFlagValue(args, i, arg).split(',').map(s => s.trim()); i++;
+  } else if (arg === '--voice') {
+    options.personaVoice = requireFlagValue(args, i, arg); i++;
+  } else if (arg === '--voice-clip') {
+    options.personaVoiceClip = requireFlagValue(args, i, arg); i++;
+  // --- Content filter ---
+  } else if (arg === '--no-filter') {
+    options.noFilter = true;
+  } else if (arg === '--last-image') {
+    // Use image from last render as reference/context
+    if (existsSync(LAST_RENDER_PATH)) {
+      const lastRender = JSON.parse(readFileSync(LAST_RENDER_PATH, 'utf8'));
+      let lastImagePath = null;
+      if (lastRender.localPath && existsSync(lastRender.localPath)) {
+        lastImagePath = lastRender.localPath;
+      } else if (lastRender.urls?.[0]) {
+        lastImagePath = lastRender.urls[0];
+      }
+      if (lastImagePath) {
+        // Will be resolved later: video uses refImage, image editing uses contextImages
+        options._lastImagePath = lastImagePath;
+      }
+    }
+  } else if (arg === '--last') {
+    // Show last render info
+    if (existsSync(LAST_RENDER_PATH)) {
+      console.log(readFileSync(LAST_RENDER_PATH, 'utf8'));
+    } else {
+      console.error('No previous render found.');
+    }
+    process.exit(0);
+  } else if (arg === '--json') {
+    options.json = true;
+  } else if (arg === '--strict-size') {
+    options.strictSize = true;
+    cliSet.strictSize = true;
+  } else if (arg === '-q' || arg === '--quiet') {
+    options.quiet = true;
+  } else if (arg === '--estimate-video-cost') {
+    options.estimateVideoCost = true;
+  } else if (arg === '--balance' || arg === '--balances') {
+    options.showBalance = true;
+  } else if (arg === '--version' || arg === '-V') {
+    options.showVersion = true;
+  } else if (arg === '--help') {
+    console.log(`
+sogni-agent - Generate images and videos using Sogni AI
+
+Usage: sogni-agent [options] "prompt"
+
+Image Options:
+  -o, --output <path>   Save to file (otherwise prints URL)
+  -Q, --quality <tier>  Quality preset: fast|hq|pro (auto-selects model/steps/size)
+  -m, --model <id>      Model (default: z_image_turbo_bf16, overrides --quality)
+  -w, --width <px>      Width (default: 512)
+  -h, --height <px>     Height (default: 512)
+  -n, --count <num>     Number of images (default: 1)
+  -s, --seed <num>      Use specific seed
+  --last-seed           Reuse seed from previous render
+  --seed-strategy <s>   Seed strategy: random|prompt-hash
+  --multi-angle         Multiple angles LoRA mode (Qwen Image Edit)
+  --angles-360          Generate 8 azimuths (front -> front-left)
+  --angles-360-video [path]  Assemble a looping 360 mp4 using i2v between angles (requires ffmpeg)
+  --video-model <id>    Override i2v model for 360 video (e.g. wan_v2.2-14b-fp8_i2v for higher quality)
+  --azimuth <key>       front|front-right|right|back-right|back|back-left|left|front-left
+  --elevation <key>     low-angle|eye-level|elevated|high-angle
+  --distance <key>      close-up|medium|wide
+  --angle-strength <n>  LoRA strength for multiple_angles (default: 0.9)
+  --angle-description <text>  Optional subject description
+  --output-format <f>   Image output format: png|jpg
+  --sampler <name>      Sampler (model-dependent)
+  --scheduler <name>    Scheduler (model-dependent)
+  --lora <id>           LoRA id (repeatable, edit only)
+  --loras <ids>         Comma-separated LoRA ids
+  --lora-strength <n>   LoRA strength (repeatable)
+  --lora-strengths <n>  Comma-separated LoRA strengths
+  -c, --context <path>  Context image for editing (can use multiple)
+  --last-image          Use last generated image as context
+
+Photobooth (Face Transfer):
+  --photobooth            Face transfer mode (InstantID + SDXL Turbo)
+  --ref <path|url>        Face image (required with --photobooth)
+  --cn-strength <n>       ControlNet strength (default: 0.8)
+  --cn-guidance-end <n>   ControlNet guidance end point (default: 0.3)
+
+Video Options:
+  --video, -v           Generate video instead of image
+  --workflow <type>     Video workflow: t2v|i2v|s2v|ia2v|a2v|v2v|animate-move|animate-replace
+  --fps <num>           Frames per second (model default unless set)
+  --duration <sec>      Duration in seconds (default: 5)
+  --frames <num>        Override total frames (optional)
+  --target-resolution <px> Short-side target that preserves aspect ratio
+  --auto-resize-assets  Auto-resize video reference assets (default)
+  --no-auto-resize-assets  Disable auto-resize for video assets
+  --estimate-video-cost Estimate video cost and exit (requires --steps)
+  --ref <path|url>      Reference image for video (start frame)
+  --ref-end <path|url>  End frame for interpolation/morphing
+  --ref-audio <path>    Uploaded/generated audio for ia2v/a2v, or s2v lip-sync
+  --audio-start <sec>   Start offset into --ref-audio for audio-driven clips
+  --audio-duration <sec> Duration slice from --ref-audio
+  --reference-audio-identity <path>  Voice identity clip for LTX native audio
+  --voice-persona <name>  Use saved persona voice clip as LTX voice identity
+  --ref-video <path>    Reference video for animate/v2v workflows
+  --video-start <sec>   Start offset into --ref-video for segmented V2V/animate
+  --controlnet-name <n> ControlNet type for v2v: canny|pose|depth|detailer
+  --controlnet-strength <n>  ControlNet strength for v2v (0.0-1.0, default: 0.8)
+  --sam2-coordinates <coords>  SAM2 click coords for animate-replace (x,y or x1,y1;x2,y2)
+  --trim-end-frame      Trim last frame for seamless video stitching
+  --first-frame-strength <n>  Keyframe strength for start frame (0.0-1.0)
+  --last-frame-strength <n>   Keyframe strength for end frame (0.0-1.0)
+  --looping, --loop     Create seamless loop (i2v only): A→B→A
+  --last-image          Use last generated image as reference
+
+General:
+  -t, --timeout <sec>   Timeout in seconds (default: 30, video: 300)
+  --steps <num>         Override steps (model-dependent)
+  --guidance <num>      Override guidance (model-dependent)
+  --token-type <type>   Token type: spark|sogni|auto (default: spark, auto retries with alternate)
+  --balance, --balances Show SPARK/SOGNI balances and exit
+  --version, -V         Show sogni-agent version and exit
+  --extract-last-frame <video> <image>  Extract last frame from a video (safe ffmpeg wrapper)
+  --concat-videos <out> <clips...>      Concatenate video clips (safe ffmpeg wrapper, min 2 clips)
+  --concat-audio <path> Optional audio track to mux over --concat-videos output
+  --concat-audio-start <sec> Start offset into --concat-audio
+  --list-media [type]   List recent inbound media files (images|audio|all, default: images)
+  --no-filter           Disable NSFW content filter
+  --last                Show last render info (JSON)
+  --json                Output JSON with all details
+  --strict-size         Do not auto-adjust video size to satisfy i2v reference resizing constraints
+  -q, --quiet           Suppress progress output
+
+Memory (persistent user preferences):
+  --memory-set <key> <value>  Save a preference (e.g. --memory-set preferred_style "watercolor")
+  --memory-get <key>          Get a specific memory
+  --memory-list               List all saved memories
+  --memory-remove <key>       Delete a memory
+  --memory-category <cat>     Category for --memory-set: preference|fact|context (default: preference)
+
+Personality (custom agent instructions):
+  --personality-set <text>    Set personality (e.g. --personality-set "Be concise, use cinematic lighting")
+  --personality-get           Show current personality
+  --personality-clear         Reset to default personality
+
+Personas (named people with reference photos):
+  --persona-add <name>        Add a persona (combine with --ref, --relationship, --description, --voice-clip)
+  --persona-list              List all saved personas
+  --persona-remove <name>     Remove a persona and its files
+  --persona-resolve <name>    Show persona details and file paths
+  --persona <name>            Generate using a persona's reference photo (image context, video ref frame)
+  --relationship <type>       Persona relationship: self|partner|child|friend|pet (default: friend)
+  --description <text>        Persona appearance description
+  --tags <names>              Comma-separated nicknames/aliases
+  --voice <text>              Voice description (accent, tone, pitch)
+  --voice-clip <path>         Voice clip audio file for LTX 2.3 voice cloning
+
+Image Models:
+  z_image_turbo_bf16              Fast, general purpose (default)
+  flux1-schnell-fp8               Very fast
+  flux2_dev_fp8                   High quality (slow)
+  qwen_image_edit_2511_fp8        Image editing with context (up to 3 images)
+  qwen_image_edit_2511_fp8_lightning  Fast image editing
+
+Recommended LTX 2.3 Video Models:
+  ltx23-22b-fp8_t2v_distilled     Text-to-video with native dialogue/audio
+  ltx23-22b-fp8_i2v_distilled     Image-to-video with native dialogue/audio
+  ltx23-22b-fp8_ia2v_distilled    Image+audio-to-video
+  ltx23-22b-fp8_a2v_distilled     Audio-to-video
+  ltx23-22b-fp8_v2v_distilled     Video-to-video with ControlNet
+
+Seedance 2.0 Video Aliases:
+  seedance2                         Text-to-video, 4-15s, native audio
+  seedance2-fast                    Fast 720p-capped text-to-video
+  seedance2-ia2v                    Image+audio-to-video
+  seedance2-v2v                     Video-to-video without ControlNet
+
+WAN 2.2 Video Models:
+  wan_v2.2-14b-fp8_t2v_lightx2v   Text-to-video (fast)
+  wan_v2.2-14b-fp8_i2v_lightx2v   Fast simple image-to-video
+  wan_v2.2-14b-fp8_i2v            Higher quality
+  wan_v2.2-14b-fp8_s2v_lightx2v   Face lip-sync with uploaded audio (fast)
+  wan_v2.2-14b-fp8_s2v            Sound-to-video (quality)
+  wan_v2.2-14b-fp8_animate-move_lightx2v     Animate-move (fast)
+  wan_v2.2-14b-fp8_animate-replace_lightx2v  Animate-replace (fast)
+
+LTX-2 / LTX-2.3 Video Models:
+  ltx2-19b-fp8_t2v_distilled      Text-to-video, fast 8-step
+  ltx2-19b-fp8_t2v                Text-to-video, quality 20-step
+  ltx2-19b-fp8_i2v_distilled      Image-to-video, fast 8-step
+  ltx2-19b-fp8_i2v                Image-to-video, quality 20-step
+  ltx2-19b-fp8_ia2v_distilled     Image+audio-to-video, fast 8-step
+  ltx2-19b-fp8_a2v_distilled      Audio-to-video, fast 8-step
+  ltx2-19b-fp8_v2v_distilled      Video-to-video with ControlNet (fast)
+  ltx2-19b-fp8_v2v                Video-to-video with ControlNet (quality)
+
+Examples:
+  sogni-agent "a cat wearing a hat"
+  sogni-agent -o cat.jpg "a cat" 
+  sogni-agent --multi-angle -c subject.jpg --azimuth front-right --elevation eye-level --distance medium "studio portrait"
+  sogni-agent --angles-360 -c subject.jpg "studio portrait"
+  sogni-agent --video --ref cat.jpg -o cat.mp4 "cat walks around"
+  sogni-agent --video "A narrator says \"welcome to the story\" as ocean waves crash"
+  sogni-agent --video --ref cat.jpg --ref-audio speech.m4a -m wan_v2.2-14b-fp8_s2v_lightx2v "lip sync"
+  sogni-agent --video --ref cover.jpg --ref-audio song.mp3 "music video"
+  sogni-agent --video --ref-audio song.mp3 "abstract music visualizer"
+  sogni-agent --video --reference-audio-identity voice.webm "NARRATOR: \"This is my voice.\""
+  sogni-agent --video -m ltx23-22b-fp8_t2v_distilled --duration 20 "A wide cinematic aerial shot opens over steep tropical cliffs at golden hour, warm sunlight grazing the rock faces while sea mist drifts above the water below. Palm trees bend gently along the ridge as waves roll against the shoreline, leaving bright bands of foam across the dark stone. The camera glides forward in one continuous pass, revealing more of the coastline as sunlight flickers across wet surfaces and distant birds wheel through the haze. The scene holds a calm, upscale travel-film mood with smooth stabilized motion and crisp environmental detail."
+  sogni-agent --video --ref subject.jpg --ref-video motion.mp4 --workflow animate-move "transfer motion"
+  sogni-agent --video --last-image "gentle camera pan"
+  sogni-agent -c photo.jpg "make the background a beach" -m qwen_image_edit_2511_fp8
+  sogni-agent -c subject.jpg -c style.jpg "apply the style to the subject"
+  sogni-agent --photobooth --ref face.jpg "80s fashion portrait"
+  sogni-agent --photobooth --ref face.jpg -n 4 "LinkedIn professional headshot"
+  sogni-agent -Q pro "a beautiful mountain landscape at sunset"
+  sogni-agent -n 3 "a {red|blue|green} sports car on a highway"
+`);
+    process.exit(0);
+  } else if (arg === '--') {
+    if (!options.prompt && args[i + 1] !== undefined) {
+      options.prompt = args[i + 1];
+    }
+    break;
+  } else if (arg.startsWith('-')) {
+    fatalCliError(`Unknown option: ${arg}`, {
+      code: 'INVALID_ARGUMENT',
+      hint: 'Use --help to see supported options.'
+    });
+  } else if (!options.prompt) {
+    options.prompt = arg;
+  }
+}
+
+let timeoutFromConfig = false;
+let widthFromConfig = false;
+let heightFromConfig = false;
+let fpsFromConfig = false;
+let configuredDefaultVideoWorkflow = null;
+if (openclawConfig) {
+  const isNumber = (value) => Number.isFinite(value);
+  if (!cliSet.width && isNumber(openclawConfig.defaultWidth)) {
+    options.width = openclawConfig.defaultWidth;
+    widthFromConfig = true;
+  }
+  if (!cliSet.height && isNumber(openclawConfig.defaultHeight)) {
+    options.height = openclawConfig.defaultHeight;
+    heightFromConfig = true;
+  }
+  if (!cliSet.count && isNumber(openclawConfig.defaultCount)) {
+    options.count = openclawConfig.defaultCount;
+  }
+  if (!cliSet.tokenType && openclawConfig.defaultTokenType) {
+    options.tokenType = openclawConfig.defaultTokenType;
+  }
+  if (!cliSet.seedStrategy && openclawConfig.seedStrategy) {
+    options.seedStrategy = openclawConfig.seedStrategy;
+  }
+  if (options.video) {
+    if (!cliSet.workflow && openclawConfig.defaultVideoWorkflow) {
+      configuredDefaultVideoWorkflow = openclawConfig.defaultVideoWorkflow;
+    }
+    if (!cliSet.fps && isNumber(openclawConfig.defaultFps)) {
+      options.fps = openclawConfig.defaultFps;
+      fpsFromConfig = true;
+    }
+    if (!cliSet.frames && !cliSet.duration && isNumber(openclawConfig.defaultDurationSec)) {
+      options.duration = openclawConfig.defaultDurationSec;
+    }
+    if (!cliSet.timeout && isNumber(openclawConfig.defaultVideoTimeoutSec)) {
+      options.timeout = openclawConfig.defaultVideoTimeoutSec * 1000;
+      timeoutFromConfig = true;
+    }
+  } else if (!cliSet.timeout && isNumber(openclawConfig.defaultImageTimeoutSec)) {
+    options.timeout = openclawConfig.defaultImageTimeoutSec * 1000;
+    timeoutFromConfig = true;
+  }
+}
+
+if (options.tokenType) {
+  const token = options.tokenType.toLowerCase();
+  if (token !== 'spark' && token !== 'sogni' && token !== 'auto') {
+    fatalCliError('--token-type must be "spark", "sogni", or "auto".', {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: '--token-type', value: options.tokenType }
+    });
+  }
+  options.tokenType = token;
+}
+
+// ---------------------------------------------------------------------------
+// Quality tier presets — auto-select model, steps, and dimensions
+// ---------------------------------------------------------------------------
+const QUALITY_TIERS = {
+  fast: {
+    model: 'z_image_turbo_bf16',
+    steps: 8,
+    shortSide: null,
+    video: { steps: 8, shortSide: null }
+  },
+  hq: {
+    model: 'z_image_turbo_bf16',
+    steps: null,
+    shortSide: 768,
+    video: { steps: 8, shortSide: 1088 }
+  },
+  pro: {
+    model: 'flux2_dev_fp8',
+    steps: 40,
+    shortSide: 1024,
+    video: { steps: 20, shortSide: 1920 }
+  }
+};
+
+if (options.quality) {
+  if (!QUALITY_TIERS[options.quality]) {
+    fatalCliError('--quality must be "fast", "hq", or "pro".', {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: '--quality', value: options.quality }
+    });
+  }
+  const tier = QUALITY_TIERS[options.quality];
+  if (!options.video) {
+    // Only apply model if user didn't explicitly set one.
+    if (!cliSet.model) {
+      options.model = tier.model;
+    }
+    // Only apply steps if user didn't explicitly set them.
+    if (!cliSet.steps && tier.steps) {
+      options.steps = tier.steps;
+    }
+    // Auto-target short-side dimension if user didn't set width/height.
+    if (tier.shortSide && !cliSet.width && !cliSet.height) {
+      options.width = tier.shortSide;
+      options.height = tier.shortSide;
+    }
+  }
+}
+
+if (options.seedStrategy) {
+  const normalizedStrategy = normalizeSeedStrategy(options.seedStrategy);
+  if (!normalizedStrategy) {
+    fatalCliError('--seed-strategy must be "random" or "prompt-hash".', {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: '--seed-strategy', value: options.seedStrategy }
+    });
+  }
+  options.seedStrategy = normalizedStrategy;
+}
+
+if (cliSet.steps && !Number.isFinite(options.steps)) {
+  fatalCliError('--steps must be a number.', {
+    code: 'INVALID_ARGUMENT',
+    details: { flag: '--steps', value: options.steps }
+  });
+}
+
+if (cliSet.guidance && !Number.isFinite(options.guidance)) {
+  fatalCliError('--guidance must be a number.', {
+    code: 'INVALID_ARGUMENT',
+    details: { flag: '--guidance', value: options.guidance }
+  });
+}
+
+if (options.multiAngle) {
+  if (options.video) {
+    fatalCliError('--multi-angle is only for image editing.', { code: 'INVALID_ARGUMENT' });
+  }
+  if (options.angles360Video && !options.angles360) {
+    fatalCliError('--angles-360-video requires --angles-360.', { code: 'INVALID_ARGUMENT' });
+  }
+  if (options.angles360Video && options.count !== 1) {
+    fatalCliError('--angles-360-video requires --count 1.', {
+      code: 'INVALID_ARGUMENT',
+      details: { count: options.count }
+    });
+  }
+  if (options._lastImagePath && options.contextImages.length === 0) {
+    options.contextImages.push(options._lastImagePath);
+    delete options._lastImagePath;
+  }
+  if (options.contextImages.length === 0) {
+    fatalCliError('--multi-angle requires a reference image (--context or --last-image).', {
+      code: 'INVALID_ARGUMENT'
+    });
+  }
+  const azimuthKeys = MULTI_ANGLE_AZIMUTHS.map((a) => a.key);
+  const elevationKeys = MULTI_ANGLE_ELEVATIONS.map((e) => e.key);
+  const distanceKeys = MULTI_ANGLE_DISTANCES.map((d) => d.key);
+
+  if (!options.angles360) {
+    options.azimuth = normalizeMultiAngleValue(options.azimuth, MULTI_ANGLE_AZIMUTH_ALIASES, azimuthKeys, 'azimuth');
+  } else if (!options.quiet && cliSet.azimuth) {
+    console.error('Warning: --azimuth ignored for --angles-360.');
+  }
+  options.elevation = normalizeMultiAngleValue(options.elevation, MULTI_ANGLE_ELEVATION_ALIASES, elevationKeys, 'elevation');
+  options.distance = normalizeMultiAngleValue(options.distance, MULTI_ANGLE_DISTANCE_ALIASES, distanceKeys, 'distance');
+
+  if (options.model && !options.model.includes('qwen_image_edit_2511')) {
+    fatalCliError('--multi-angle requires a Qwen Image Edit 2511 model.', {
+      code: 'INVALID_ARGUMENT',
+      details: { model: options.model }
+    });
+  }
+  if (!options.model) {
+    options.model = 'qwen_image_edit_2511_fp8_lightning';
+  }
+  if (!options.outputFormat) {
+    options.outputFormat = 'jpg';
+  }
+  if (!options.sampler) {
+    options.sampler = 'euler';
+  }
+  if (!options.scheduler) {
+    options.scheduler = 'simple';
+  }
+  if (!options.angleDescription && options.prompt) {
+    options.angleDescription = options.prompt;
+  }
+  if (options.loras.length === 0 && options.loraStrengths.length > 0) {
+    if (options.loraStrengths.length > 1) {
+      fatalCliError('--lora-strengths requires explicit --loras when using --multi-angle.', {
+        code: 'INVALID_ARGUMENT'
+      });
+    }
+    if (options.angleStrength === null || options.angleStrength === undefined) {
+      options.angleStrength = options.loraStrengths[0];
+    }
+    options.loraStrengths = [];
+  }
+  if (!cliSet.guidance && (options.guidance === null || options.guidance === undefined)) {
+    options.guidance = options.model.includes('lightning') ? 1.0 : 4.0;
+  }
+  if (options.angleStrength === null || options.angleStrength === undefined) {
+    options.angleStrength = 0.9;
+  }
+
+  const multiAngleStrength = options.angleStrength;
+  let multiAngleIndex = options.loras.indexOf('multiple_angles');
+  if (multiAngleIndex === -1) {
+    options.loras.push('multiple_angles');
+    multiAngleIndex = options.loras.length - 1;
+    if (options.loraStrengths.length > 0) {
+      options.loraStrengths.push(multiAngleStrength);
+    }
+  }
+
+  if (options.loraStrengths.length === 0 && options.loras.length > 0) {
+    options.loraStrengths = options.loras.map((id) => (id === 'multiple_angles' ? multiAngleStrength : 1.0));
+  } else if (options.loraStrengths.length === options.loras.length) {
+    if (options.loraStrengths[multiAngleIndex] === undefined || options.loraStrengths[multiAngleIndex] === null) {
+      options.loraStrengths[multiAngleIndex] = multiAngleStrength;
+    }
+  }
+}
+
+if (options.outputFormat) {
+  const normalized = options.outputFormat.toLowerCase();
+  options.outputFormat = normalized === 'jpeg' ? 'jpg' : normalized;
+  if (options.video) {
+    if (options.outputFormat !== 'mp4') {
+      fatalCliError('Video output format must be "mp4".', {
+        code: 'INVALID_ARGUMENT',
+        details: { outputFormat: options.outputFormat }
+      });
+    }
+  } else if (!['png', 'jpg'].includes(options.outputFormat)) {
+    fatalCliError('Image output format must be "png" or "jpg".', {
+      code: 'INVALID_ARGUMENT',
+      details: { outputFormat: options.outputFormat }
+    });
+  }
+}
+
+if (options.loraStrengths.length > 0 && options.loras.length === 0) {
+  fatalCliError('--lora-strength requires at least one --lora.', { code: 'INVALID_ARGUMENT' });
+}
+
+if (options.loraStrengths.length > 0 && options.loras.length > 0 &&
+    options.loraStrengths.length !== options.loras.length) {
+  fatalCliError('--lora-strengths count must match --loras count.', {
+    code: 'INVALID_ARGUMENT',
+    details: { loras: options.loras.length, loraStrengths: options.loraStrengths.length }
+  });
+}
+
+if (options.video && options.loras.length > 0) {
+  fatalCliError('--lora options are image-only.', { code: 'INVALID_ARGUMENT' });
+}
+
+if (options.video && (options.sampler || options.scheduler)) {
+  fatalCliError('--sampler/--scheduler are image-only options.', { code: 'INVALID_ARGUMENT' });
+}
+
+applyPersonaAndVoiceReferences();
+
+if (!options.video && options.autoResizeVideoAssets !== null) {
+  fatalCliError('--auto-resize-assets is only valid with --video.', { code: 'INVALID_ARGUMENT' });
+}
+
+if (options.estimateVideoCost && !options.video) {
+  fatalCliError('--estimate-video-cost requires --video.', { code: 'INVALID_ARGUMENT' });
+}
+
+if (options.angles360Video && !options.angles360) {
+  fatalCliError('--angles-360-video requires --angles-360.', { code: 'INVALID_ARGUMENT' });
+}
+
+// Normalize/validate video workflow before applying defaults
+if (options.video) {
+  if (options.videoWorkflow) {
+    const normalized = normalizeVideoWorkflow(options.videoWorkflow);
+    if (!normalized) {
+      fatalCliError(`Unknown workflow "${options.videoWorkflow}". Use t2v|i2v|s2v|ia2v|a2v|v2v|animate-move|animate-replace.`, {
+        code: 'INVALID_ARGUMENT',
+        details: { workflow: options.videoWorkflow }
+      });
+    }
+    options.videoWorkflow = normalized;
+  }
+
+  const workflowFromModel = inferVideoWorkflowFromModel(resolveVideoModelAlias(options.model, options.videoWorkflow));
+  if (options.videoWorkflow && workflowFromModel && options.videoWorkflow !== workflowFromModel) {
+    fatalCliError(`Workflow "${options.videoWorkflow}" does not match model "${options.model}".`, {
+      code: 'INVALID_ARGUMENT',
+      details: { workflow: options.videoWorkflow, model: options.model }
+    });
+  }
+  if (!options.videoWorkflow) {
+    options.videoWorkflow = workflowFromModel || inferVideoWorkflowFromAssets(options) || configuredDefaultVideoWorkflow || 't2v';
+  }
+  if (options.model) {
+    options.model = resolveVideoModelAlias(options.model, options.videoWorkflow);
+  }
+}
+
+// Resolve --last-image after workflow is known
+if (options._lastImagePath) {
+  if (options.video) {
+    if (workflowRequiresImage(options.videoWorkflow)) {
+      if (!options.refImage) options.refImage = options._lastImagePath;
+    } else if (!options.quiet) {
+      console.error(`Warning: --last-image ignored for ${options.videoWorkflow || 'current'} workflow.`);
+    }
+  } else if (options.photobooth) {
+    if (!options.refImage) options.refImage = options._lastImagePath;
+  } else {
+    options.contextImages.push(options._lastImagePath);
+  }
+  delete options._lastImagePath;
+}
+
+// Set defaults based on type and context
+if (options.video) {
+  options.model = options.model || selectDefaultVideoModel(options.videoWorkflow, options, openclawConfig) || 'wan_v2.2-14b-fp8_i2v_lightx2v';
+  options.model = resolveVideoModelAlias(options.model, options.videoWorkflow);
+  const videoModelDefaults = getModelDefaults(options.model, openclawConfig);
+  const isSeedanceVideo = isSeedanceModel(options.model);
+  if (!cliSet.width && !widthFromConfig && Number.isFinite(videoModelDefaults?.defaultWidth)) {
+    options.width = videoModelDefaults.defaultWidth;
+  }
+  if (!cliSet.height && !heightFromConfig && Number.isFinite(videoModelDefaults?.defaultHeight)) {
+    options.height = videoModelDefaults.defaultHeight;
+  }
+  if (!cliSet.fps && !fpsFromConfig && Number.isFinite(videoModelDefaults?.fps)) {
+    options.fps = videoModelDefaults.fps;
+  }
+  const videoQuality = options.quality ? QUALITY_TIERS[options.quality]?.video : null;
+  if (videoQuality) {
+    if (!isSeedanceVideo && !cliSet.steps && Number.isFinite(videoQuality.steps)) {
+      options.steps = videoQuality.steps;
+    }
+  }
+  const videoShortSide = cliSet.targetResolution
+    ? options.targetResolution
+    : (!isSeedanceVideo ? videoQuality?.shortSide : null);
+  if (videoShortSide && !cliSet.width && !cliSet.height && !widthFromConfig && !heightFromConfig) {
+    const dims = dimensionsWithShortSide(options.width, options.height, videoShortSide);
+    options.width = dims.width;
+    options.height = dims.height;
+  }
+  if (!cliSet.timeout && !timeoutFromConfig && options.timeout === 30000) {
+    options.timeout = 300000; // 5 min for video
+  }
+} else if (options.photobooth) {
+  // Photobooth uses SDXL Turbo + InstantID ControlNet
+  options.model = options.model || openclawConfig?.defaultPhotoboothModel || 'coreml-sogniXLturbo_alpha1_ad';
+  if (!cliSet.width) options.width = 1024;
+  if (!cliSet.height) options.height = 1024;
+  if (!cliSet.timeout && !timeoutFromConfig && options.timeout === 30000) {
+    options.timeout = 60000;
+  }
+} else if (options.contextImages.length > 0) {
+  // Use qwen edit model when context images provided (unless model explicitly set)
+  options.model = options.model || openclawConfig?.defaultEditModel || 'qwen_image_edit_2511_fp8_lightning';
+  if (!cliSet.timeout && !timeoutFromConfig && options.timeout === 30000) {
+    options.timeout = 60000; // 1 min for editing
+  }
+} else {
+  options.model = options.model || openclawConfig?.defaultImageModel || 'z_image_turbo_bf16';
+}
+
+if (!options.prompt && !options.estimateVideoCost && !options.multiAngle && !options.showBalance && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && !options.memoryAction && !options.personalityAction && !(options.personaAction && options.personaAction !== 'generate')) {
+  fatalCliError('No prompt provided. Use --help for usage.', { code: 'INVALID_ARGUMENT' });
+}
+
+if (!options.video && (options.refAudio || options.refVideo || options.referenceAudioIdentity || options.voicePersonaName || options.videoWorkflow || options.frames || options.targetResolution || options.audioStart !== null || options.audioDuration !== null || options.videoStart !== null)) {
+  fatalCliError('Video-only options (--workflow/--frames/--target-resolution/--ref-audio/--ref-video/--reference-audio-identity/--voice-persona) require --video.', {
+    code: 'INVALID_ARGUMENT'
+  });
+}
+
+if (options.photobooth) {
+  if (!options.refImage) {
+    fatalCliError('--photobooth requires --ref <face-image>.', { code: 'INVALID_ARGUMENT' });
+  }
+  if (options.video) {
+    fatalCliError('--photobooth cannot be combined with --video.', { code: 'INVALID_ARGUMENT' });
+  }
+  if (options.contextImages.length > 0) {
+    fatalCliError('--photobooth cannot be combined with -c/--context.', { code: 'INVALID_ARGUMENT' });
+  }
+}
+
+if (options.video) {
+  if (options.videoWorkflow === 't2v') {
+    if (options.refImage || options.refImageEnd || options.refAudio || options.refVideo) {
+      fatalCliError('t2v does not accept reference image/audio/video.', {
+        code: 'INVALID_ARGUMENT'
+      });
+    }
+  } else if (options.videoWorkflow === 'i2v') {
+    if (!options.refImage && !options.refImageEnd) {
+      fatalCliError('i2v requires --ref and/or --ref-end.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.refAudio || options.refVideo) {
+      fatalCliError('i2v does not accept reference audio/video.', { code: 'INVALID_ARGUMENT' });
+    }
+  } else if (options.videoWorkflow === 's2v') {
+    if (!options.refImage || !options.refAudio) {
+      fatalCliError('s2v requires both --ref and --ref-audio.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.refVideo) {
+      fatalCliError('s2v does not accept reference video.', { code: 'INVALID_ARGUMENT' });
+    }
+  } else if (options.videoWorkflow === 'ia2v') {
+    if (!options.refImage || !options.refAudio) {
+      fatalCliError('ia2v requires both --ref and --ref-audio.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.refImageEnd || options.refVideo) {
+      fatalCliError('ia2v does not accept --ref-end or --ref-video.', { code: 'INVALID_ARGUMENT' });
+    }
+  } else if (options.videoWorkflow === 'a2v') {
+    if (!options.refAudio) {
+      fatalCliError('a2v requires --ref-audio.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.refImage || options.refImageEnd || options.refVideo) {
+      fatalCliError('a2v does not accept reference image/video.', { code: 'INVALID_ARGUMENT' });
+    }
+  } else if (options.videoWorkflow === 'v2v') {
+    if (!options.refVideo) {
+      fatalCliError('v2v requires --ref-video.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (!options.videoControlNetName && !isSeedanceModel(options.model)) {
+      fatalCliError('v2v requires --controlnet-name (canny|pose|depth|detailer).', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.refAudio) {
+      fatalCliError('v2v does not accept reference audio.', { code: 'INVALID_ARGUMENT' });
+    }
+  } else if (options.videoWorkflow === 'animate-move' || options.videoWorkflow === 'animate-replace') {
+    if (!options.refImage || !options.refVideo) {
+      fatalCliError('animate workflows require both --ref and --ref-video.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.refAudio) {
+      fatalCliError('animate workflows do not accept reference audio.', { code: 'INVALID_ARGUMENT' });
+    }
+  }
+
+  if ((options.audioStart !== null || options.audioDuration !== null) && !options.refAudio) {
+    fatalCliError('--audio-start/--audio-duration require --ref-audio.', { code: 'INVALID_ARGUMENT' });
+  }
+  if (options.videoStart !== null && !options.refVideo) {
+    fatalCliError('--video-start requires --ref-video.', { code: 'INVALID_ARGUMENT' });
+  }
+
+  if (options.referenceAudioIdentity && !['t2v', 'i2v'].includes(options.videoWorkflow)) {
+    fatalCliError('--reference-audio-identity/--voice-persona is only supported for LTX native-audio t2v/i2v workflows.', {
+      code: 'INVALID_ARGUMENT'
+    });
+  }
+  if (options.referenceAudioIdentity && !isLtx2Model(options.model)) {
+    fatalCliError('--reference-audio-identity/--voice-persona requires an LTX video model.', {
+      code: 'INVALID_ARGUMENT',
+      hint: `Use -m ${LTX23_WORKFLOW_MODELS[options.videoWorkflow] || LTX23_WORKFLOW_MODELS.t2v}`
+    });
+  }
+
+  // Validate controlnet-name values
+  if (options.videoControlNetName) {
+    const validControlNets = ['canny', 'pose', 'depth', 'detailer'];
+    if (!validControlNets.includes(options.videoControlNetName)) {
+      fatalCliError(`Unknown --controlnet-name "${options.videoControlNetName}". Use: ${validControlNets.join('|')}`, {
+        code: 'INVALID_ARGUMENT',
+        details: { flag: '--controlnet-name', value: options.videoControlNetName, allowed: validControlNets }
+      });
+    }
+  }
+
+  // Validate SAM2 coordinates (only for animate-replace)
+  if (options.sam2Coordinates && options.videoWorkflow !== 'animate-replace') {
+    fatalCliError('--sam2-coordinates is only supported with animate-replace workflow.', { code: 'INVALID_ARGUMENT' });
+  }
+
+  // Validate looping flag
+  if (options.looping) {
+    if (!options.video) {
+      fatalCliError('--looping requires --video.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.videoWorkflow !== 'i2v') {
+      fatalCliError('--looping is only supported with i2v workflow.', { code: 'INVALID_ARGUMENT' });
+    }
+    if (!options.refImage) {
+      fatalCliError('--looping requires --ref (reference image).', { code: 'INVALID_ARGUMENT' });
+    }
+    if (options.refImageEnd) {
+      fatalCliError('--looping cannot be used with --ref-end (end frame is auto-generated).', { code: 'INVALID_ARGUMENT' });
+    }
+  }
+}
+
+applyVideoPromptGuardrails();
+
+if (options.video && isSeedanceModel(options.model) && !options.frames) {
+  const clampedDuration = Math.max(4, Math.min(15, options.duration));
+  if (clampedDuration !== options.duration) {
+    if (!options.quiet) {
+      console.error(`Adjusted Seedance video duration from ${options.duration}s to ${clampedDuration}s (supported range: 4-15s).`);
+    }
+    options.duration = clampedDuration;
+  }
+}
+
+// Video dimensions:
+// - Sogni video pipelines have model-specific min/max dimensions and divisors.
+// - When using i2v (or any ref-based workflow), the Sogni client wrapper will *resize the reference image*
+//   with sharp `fit: inside` and then override the project width/height with the resized reference dims.
+//   That means a "valid" requested size can still fail if the resized ref lands off the model divisor.
+if (options.video) {
+  const videoDimensionRules = videoDimensionRulesFromDefaults(getModelDefaults(options.model, openclawConfig));
+  if (!Number.isFinite(options.width) || options.width <= 0 || !Number.isFinite(options.height) || options.height <= 0) {
+    fatalCliError('Video width/height must be positive numbers.', {
+      code: 'INVALID_ARGUMENT',
+      details: { width: options.width, height: options.height }
+    });
+  }
+
+  const originalVideoWidth = options.width;
+  const originalVideoHeight = options.height;
+  const normalizedVideoDims = normalizeVideoDimensionsLikeWrapper(options.width, options.height, videoDimensionRules);
+  options.width = normalizedVideoDims.width;
+  options.height = normalizedVideoDims.height;
+  if (normalizedVideoDims.adjusted && !options.quiet) {
+    console.error(
+      `Auto-adjusted video dimensions from ${originalVideoWidth}x${originalVideoHeight} ` +
+      `to ${options.width}x${options.height} to meet video requirements.`
+    );
+  }
+
+  if (options.videoWorkflow === 'i2v' && (options.refImage || options.refImageEnd)) {
+    const references = [
+      {
+        key: 'refImage',
+        path: options.refImage,
+        label: 'Reference image',
+        resizeFlag: '_needsRefResize'
+      },
+      {
+        key: 'refImageEnd',
+        path: options.refImageEnd,
+        label: 'End reference image',
+        resizeFlag: '_needsRefEndResize'
+      }
+    ];
+    const localRefDims = new Map();
+
+    const isIncompatible = (predicted) => Boolean(predicted) && (
+      predicted.width % videoDimensionRules.dimensionMultiple !== 0 ||
+      predicted.height % videoDimensionRules.dimensionMultiple !== 0 ||
+      predicted.width < videoDimensionRules.minDimension ||
+      predicted.height < videoDimensionRules.minDimension
+    );
+
+    for (const ref of references) {
+      if (!ref.path || isHttpUrl(ref.path) || !existsSync(ref.path)) continue;
+      const buffer = readFileSync(ref.path);
+      const dims = getImageDimensionsFromBuffer(buffer);
+      if (!dims?.width || !dims?.height) continue;
+      localRefDims.set(ref.key, dims);
+
+      const predicted = predictSharpInsideResizeDims(dims.width, dims.height, options.width, options.height);
+      if (!isIncompatible(predicted)) continue;
+
+      const candidate = pickCompatibleI2vBoundingBox(dims.width, dims.height, options.width, options.height, { allowImperfect: true, rules: videoDimensionRules });
+      if (!candidate) {
+        options[ref.resizeFlag] = true;
+        if (!options.quiet) {
+          console.error(
+            `${ref.label} ${dims.width}x${dims.height} will be pre-resized to model-compatible dimensions ` +
+            'because no compatible bounding box exists for i2v workflow.'
+          );
+        }
+        continue;
+      }
+
+      if ((cliSet.width || cliSet.height) && options.strictSize) {
+        fatalCliError(
+          `${ref.label} ${dims.width}x${dims.height} would resize to ${predicted.width}x${predicted.height}, ` +
+          `but both dimensions must be divisible by ${videoDimensionRules.dimensionMultiple}.`,
+          {
+            code: 'INVALID_VIDEO_SIZE',
+            details: {
+              referenceType: ref.key,
+              referencePath: ref.path,
+              reference: { width: dims.width, height: dims.height },
+              requested: { width: options.width, height: options.height },
+              resized: predicted
+            },
+            hint: `Try: --width ${candidate.width} --height ${candidate.height} (or omit --strict-size)`
+          }
+        );
+      }
+
+      const beforeW = options.width;
+      const beforeH = options.height;
+      options.width = candidate.width;
+      options.height = candidate.height;
+
+      const predictedAfter = predictSharpInsideResizeDims(dims.width, dims.height, options.width, options.height);
+      options._adjustedVideoDims = {
+        reason: 'i2v-ref-model-divisor',
+        referenceType: ref.key,
+        requested: { width: beforeW, height: beforeH },
+        adjusted: { width: options.width, height: options.height },
+        resizedFrom: predicted,
+        resizedTo: predictedAfter || null
+      };
+      if (!options.quiet) {
+        const mode = cliSet.width || cliSet.height ? 'Warning: Adjusted' : 'Auto-adjusted';
+        console.error(
+          `${mode} i2v video size from ${beforeW}x${beforeH} to ${options.width}x${options.height} ` +
+          `because resized reference would be ${predicted.width}x${predicted.height}.`
+        );
+      }
+    }
+
+    for (const ref of references) {
+      const dims = localRefDims.get(ref.key);
+      if (!dims) continue;
+      const predicted = predictSharpInsideResizeDims(dims.width, dims.height, options.width, options.height);
+      if (isIncompatible(predicted)) {
+        options[ref.resizeFlag] = true;
+      }
+    }
+
+    const effectiveDimsSource = localRefDims.get('refImage') || localRefDims.get('refImageEnd') || null;
+    if (effectiveDimsSource) {
+      const predicted = predictSharpInsideResizeDims(
+        effectiveDimsSource.width,
+        effectiveDimsSource.height,
+        options.width,
+        options.height
+      );
+      if (predicted) {
+        options._effectiveVideoDims = {
+          width: predicted.width,
+          height: predicted.height,
+          refWidth: effectiveDimsSource.width,
+          refHeight: effectiveDimsSource.height,
+          requestedWidth: options.width,
+          requestedHeight: options.height
+        };
+      }
+    }
+
+    if ((options._needsRefResize || options._needsRefEndResize) && !options.quiet) {
+      console.error('One or more i2v references require pre-resize to ensure model-compatible dimensions.');
+    }
+  }
+}
+
+// Validate context images against model limits
+if (options.contextImages.length > 0 && !options.video) {
+  const maxImages = getMaxContextImages(options.model);
+  if (maxImages === 0) {
+    fatalCliError(`Model ${options.model} does not support context images.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { model: options.model },
+      hint: 'Try: qwen_image_edit_2511_fp8 or qwen_image_edit_2511_fp8_lightning'
+    });
+  }
+  if (options.contextImages.length > maxImages) {
+    fatalCliError(`Model ${options.model} supports max ${maxImages} context images, got ${options.contextImages.length}.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { model: options.model, maxImages, provided: options.contextImages.length }
+    });
+  }
+}
+
+// Load last render seed if requested
+if (options.lastSeed) {
+  if (existsSync(LAST_RENDER_PATH)) {
+    try {
+      const lastRender = JSON.parse(readFileSync(LAST_RENDER_PATH, 'utf8'));
+      if (lastRender.seed) {
+        options.seed = lastRender.seed;
+        if (!options.quiet) console.error(`Using seed from last render: ${options.seed}`);
+      }
+    } catch (e) {
+      console.error('Warning: Could not load last render seed');
+    }
+  } else {
+    console.error('Warning: No previous render found, generating seed');
+  }
+}
+
+if (!options.estimateVideoCost && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && (options.seed === null || options.seed === undefined)) {
+  const strategy = options.seedStrategy || openclawConfig?.seedStrategy || 'prompt-hash';
+  const normalized = normalizeSeedStrategy(strategy) || 'prompt-hash';
+  options.seedStrategy = normalized;
+  options.seed = normalized === 'random'
+    ? generateRandomSeed()
+    : computePromptHashSeed(options);
+  if (!options.quiet) console.error(`Using ${normalized} seed: ${options.seed}`);
+}
+
+// Load credentials
+function loadCredentials() {
+  if (existsSync(CREDENTIALS_PATH)) {
+    const content = readFileSync(CREDENTIALS_PATH, 'utf8');
+    const creds = {};
+    for (const line of content.split('\n')) {
+      const [key, val] = line.split('=');
+      if (key && val) creds[key.trim()] = val.trim();
+    }
+    if (creds.SOGNI_API_KEY) {
+      return {
+        SOGNI_API_KEY: creds.SOGNI_API_KEY
+      };
+    }
+    if (creds.SOGNI_USERNAME && creds.SOGNI_PASSWORD) {
+      return creds;
+    }
+  }
+
+  if (hasEnv('SOGNI_API_KEY')) {
+    return {
+      SOGNI_API_KEY: getEnv('SOGNI_API_KEY')
+    };
+  }
+  
+  if (hasEnv('SOGNI_USERNAME') && hasEnv('SOGNI_PASSWORD')) {
+    return {
+      SOGNI_USERNAME: getEnv('SOGNI_USERNAME'),
+      SOGNI_PASSWORD: getEnv('SOGNI_PASSWORD')
+    };
+  }
+
+  const err = new Error('No Sogni credentials found.');
+  err.code = 'MISSING_CREDENTIALS';
+  err.hint = 'Set SOGNI_API_KEY or SOGNI_USERNAME/SOGNI_PASSWORD, or configure SOGNI_CREDENTIALS_PATH.';
+  err.details = {
+    triedEnv: ['SOGNI_API_KEY', 'SOGNI_USERNAME', 'SOGNI_PASSWORD'],
+    triedFile: CREDENTIALS_PATH
+  };
+  throw err;
+}
+
+// Save last render info
+function saveLastRender(info) {
+  try {
+    const dir = dirname(LAST_RENDER_PATH);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(LAST_RENDER_PATH, JSON.stringify(info, null, 2));
+  } catch (e) {
+    // Ignore save errors
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Memory system — persistent user preferences on disk
+// ---------------------------------------------------------------------------
+const MEMORIES_PATH = getEnv('SOGNI_MEMORIES_PATH') || DEFAULT_MEMORIES_PATH;
+
+function loadMemories() {
+  try {
+    if (existsSync(MEMORIES_PATH)) return JSON.parse(readFileSync(MEMORIES_PATH, 'utf8'));
+  } catch {}
+  return [];
+}
+
+function saveMemories(memories) {
+  const dir = dirname(MEMORIES_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(MEMORIES_PATH, JSON.stringify(memories, null, 2));
+}
+
+function memorySet(key, value, category = 'preference', source = 'user') {
+  const memories = loadMemories();
+  const existing = memories.findIndex(m => m.key === key);
+  const entry = { key, value, category, source, updatedAt: Date.now() };
+  if (existing >= 0) { memories[existing] = { ...memories[existing], ...entry }; }
+  else { memories.push({ id: randomBytes(8).toString('hex'), ...entry, createdAt: Date.now() }); }
+  saveMemories(memories);
+  return existing >= 0 ? 'updated' : 'created';
+}
+
+function memoryRemove(key) {
+  const memories = loadMemories();
+  const filtered = memories.filter(m => m.key !== key);
+  if (filtered.length === memories.length) return false;
+  saveMemories(filtered);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Personality system — custom instructions for agent behavior
+// ---------------------------------------------------------------------------
+const PERSONALITY_PATH = getEnv('SOGNI_PERSONALITY_PATH') || DEFAULT_PERSONALITY_PATH;
+
+function loadPersonality() {
+  try {
+    if (existsSync(PERSONALITY_PATH)) return readFileSync(PERSONALITY_PATH, 'utf8').trim();
+  } catch {}
+  return null;
+}
+
+function savePersonality(text) {
+  const dir = dirname(PERSONALITY_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(PERSONALITY_PATH, text);
+}
+
+function clearPersonality() {
+  try { if (existsSync(PERSONALITY_PATH)) unlinkSync(PERSONALITY_PATH); } catch {}
+}
+
+// ---------------------------------------------------------------------------
+// Persona system — named people with reference photos and voice clips
+// ---------------------------------------------------------------------------
+const PERSONAS_DIR = getEnv('SOGNI_PERSONAS_DIR') || DEFAULT_PERSONAS_DIR;
+const PERSONAS_INDEX_PATH = join(PERSONAS_DIR, 'index.json');
+
+function loadPersonas() {
+  try {
+    if (existsSync(PERSONAS_INDEX_PATH)) return JSON.parse(readFileSync(PERSONAS_INDEX_PATH, 'utf8'));
+  } catch {}
+  return [];
+}
+
+function savePersonasIndex(personas) {
+  if (!existsSync(PERSONAS_DIR)) mkdirSync(PERSONAS_DIR, { recursive: true });
+  writeFileSync(PERSONAS_INDEX_PATH, JSON.stringify(personas, null, 2));
+}
+
+function personaSlug(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+}
+
+function addPersona({ name, relationship, description, tags, voice, photoPath, voiceClipPath }) {
+  const personas = loadPersonas();
+  if (personas.find(p => p.name.toLowerCase() === name.toLowerCase())) {
+    throw new Error(`Persona "${name}" already exists. Remove it first or use a different name.`);
+  }
+  const slug = personaSlug(name);
+  const personaDir = join(PERSONAS_DIR, slug);
+  if (!existsSync(personaDir)) mkdirSync(personaDir, { recursive: true });
+
+  // Copy photo
+  let savedPhotoPath = null;
+  if (photoPath) {
+    const resolvedPhoto = expandHomePath(photoPath);
+    if (!existsSync(resolvedPhoto)) throw new Error(`Photo not found: ${resolvedPhoto}`);
+    const ext = extname(resolvedPhoto).toLowerCase() || '.jpg';
+    savedPhotoPath = join(personaDir, `photo${ext}`);
+    writeFileSync(savedPhotoPath, readFileSync(resolvedPhoto));
+  }
+
+  // Copy voice clip
+  let savedVoicePath = null;
+  if (voiceClipPath) {
+    const resolvedVoice = expandHomePath(voiceClipPath);
+    if (!existsSync(resolvedVoice)) throw new Error(`Voice clip not found: ${resolvedVoice}`);
+    const ext = extname(resolvedVoice).toLowerCase() || '.webm';
+    savedVoicePath = join(personaDir, `voice-clip${ext}`);
+    writeFileSync(savedVoicePath, readFileSync(resolvedVoice));
+  }
+
+  const persona = {
+    id: randomBytes(8).toString('hex'),
+    name,
+    slug,
+    relationship: relationship || 'friend',
+    description: description || '',
+    tags: tags || [],
+    voice: voice || null,
+    photoPath: savedPhotoPath,
+    voiceClipPath: savedVoicePath,
+    createdAt: Date.now(),
+    updatedAt: Date.now()
+  };
+  personas.push(persona);
+  savePersonasIndex(personas);
+  return persona;
+}
+
+function removePersona(name) {
+  const personas = loadPersonas();
+  const idx = personas.findIndex(p => p.name.toLowerCase() === name.toLowerCase());
+  if (idx < 0) return false;
+  const persona = personas[idx];
+  // Remove persona directory
+  const personaDir = join(PERSONAS_DIR, persona.slug);
+  try {
+    if (existsSync(personaDir)) {
+      const entries = readdirSync(personaDir);
+      for (const entry of entries) {
+        const fp = join(personaDir, entry);
+        if (statSync(fp).isFile()) unlinkSync(fp);
+      }
+      rmdirSync(personaDir);
+    }
+  } catch {}
+  personas.splice(idx, 1);
+  savePersonasIndex(personas);
+  return true;
+}
+
+function resolvePersonaByName(name) {
+  const personas = loadPersonas();
+  // Match by name (case-insensitive)
+  let match = personas.find(p => p.name.toLowerCase() === name.toLowerCase());
+  if (match) return match;
+  // Match by tag
+  match = personas.find(p => p.tags?.some(t => t.toLowerCase() === name.toLowerCase()));
+  if (match) return match;
+  // Match implicit pronouns
+  const lower = name.toLowerCase();
+  if (lower === 'me' || lower === 'myself' || lower === 'i') {
+    match = personas.find(p => p.relationship === 'self');
+  } else if (lower.includes('wife') || lower.includes('husband') || lower.includes('partner')) {
+    match = personas.find(p => p.relationship === 'partner');
+  } else if (lower.includes('son') || lower.includes('daughter') || lower.includes('kid') || lower.includes('child')) {
+    match = personas.find(p => p.relationship === 'child');
+  } else if (lower.includes('dog') || lower.includes('cat') || lower.includes('pet')) {
+    match = personas.find(p => p.relationship === 'pet');
+  }
+  return match || null;
+}
+
+function applyPersonaAndVoiceReferences() {
+  if (options.voicePersonaName) {
+    const voicePersona = resolvePersonaByName(options.voicePersonaName);
+    if (!voicePersona) {
+      fatalCliError(`Voice persona "${options.voicePersonaName}" not found. Use --persona-list to see available personas.`, {
+        code: 'PERSONA_NOT_FOUND'
+      });
+    }
+    if (!voicePersona.voiceClipPath || !existsSync(voicePersona.voiceClipPath)) {
+      fatalCliError(`Voice persona "${voicePersona.name}" does not have a saved voice clip.`, {
+        code: 'PERSONA_VOICE_NOT_FOUND'
+      });
+    }
+    if (!options.referenceAudioIdentity) {
+      options.referenceAudioIdentity = voicePersona.voiceClipPath;
+      cliSet.referenceAudioIdentity = true;
+    }
+    options._voicePersonaResolvedName = voicePersona.name;
+  }
+
+  if (options.personaAction !== 'generate' || !options.personaName) return;
+
+  const persona = resolvePersonaByName(options.personaName);
+  if (!persona) {
+    fatalCliError(`Persona "${options.personaName}" not found. Use --persona-list to see available personas.`, {
+      code: 'PERSONA_NOT_FOUND'
+    });
+  }
+
+  options._resolvedPersona = persona;
+
+  if (persona.photoPath && existsSync(persona.photoPath)) {
+    if (options.video) {
+      if (!options.refImage) {
+        options.refImage = persona.photoPath;
+      }
+    } else {
+      options.contextImages.push(persona.photoPath);
+    }
+  }
+
+  if (options.video && persona.voiceClipPath && existsSync(persona.voiceClipPath) && !options.referenceAudioIdentity) {
+    options.referenceAudioIdentity = persona.voiceClipPath;
+    options.voicePersonaName = options.voicePersonaName || persona.name;
+    options._voicePersonaResolvedName = persona.name;
+  }
+}
+
+// Fetch image as buffer
+async function fetchMediaBuffer(pathOrUrl) {
+  if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) {
+    await assertSafeUrl(pathOrUrl);
+    const response = await fetch(pathOrUrl);
+    if (!response.ok) {
+      const err = new Error(`Failed to fetch media (${response.status} ${response.statusText})`);
+      err.code = 'FETCH_FAILED';
+      err.details = { url: pathOrUrl, status: response.status, statusText: response.statusText };
+      throw err;
+    }
+    return Buffer.from(await response.arrayBuffer());
+  }
+  try {
+    return readFileSync(pathOrUrl);
+  } catch (e) {
+    const err = new Error(`Failed to read media file: ${pathOrUrl}`);
+    err.code = 'MISSING_FILE';
+    err.hint = 'Check the path or use a URL.';
+    err.details = { path: pathOrUrl, cause: e?.message || String(e) };
+    throw err;
+  }
+}
+
+function resolveMultiAngleOutputConfig(outputPath, outputFormat) {
+  if (!outputPath) return null;
+  const ext = extname(outputPath);
+  const desiredExt = (outputFormat || 'jpg').replace('.', '');
+  if (!ext) {
+    return { dir: outputPath, prefix: '', ext: desiredExt };
+  }
+  const dir = dirname(outputPath);
+  const prefix = basename(outputPath, ext);
+  return { dir, prefix, ext: ext.replace('.', '') || desiredExt };
+}
+
+async function downloadUrlToFile(url, filePath) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download image: ${response.statusText}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  writeFileSync(filePath, buffer);
+}
+
+function removeClientListener(client, event, handler) {
+  if (typeof client.off === 'function') {
+    client.off(event, handler);
+  } else {
+    client.removeListener(event, handler);
+  }
+}
+
+let execaPromise = null;
+async function loadExeca() {
+  if (!execaPromise) {
+    execaPromise = import('execa');
+  }
+  return execaPromise;
+}
+
+async function ensureFfmpegAvailable() {
+  const ffmpegPath = getEnv('FFMPEG_PATH') || 'ffmpeg';
+  sanitizePath(ffmpegPath, 'FFMPEG_PATH');
+  const result = await runCommand(ffmpegPath, ['-version'], { captureOutput: true });
+  if (result.error || result.status !== 0) {
+    const err = new Error('ffmpeg is required to assemble the 360 video.');
+    err.code = 'MISSING_FFMPEG';
+    err.hint = 'Install ffmpeg or set FFMPEG_PATH to a working ffmpeg binary.';
+    err.details = { ffmpegPath };
+    throw err;
+  }
+  // Verify the binary actually is ffmpeg (not an arbitrary executable)
+  const stdout = result.stdout || '';
+  if (!stdout.toLowerCase().includes('ffmpeg')) {
+    const err = new Error('FFMPEG_PATH does not point to an ffmpeg binary.');
+    err.code = 'INVALID_FFMPEG';
+    err.hint = 'Ensure FFMPEG_PATH points to a real ffmpeg installation.';
+    err.details = { ffmpegPath };
+    throw err;
+  }
+  return ffmpegPath;
+}
+
+function writeConcatList(filePath, frames, frameDuration) {
+  const lines = [];
+  frames.forEach((frame) => {
+    lines.push(`file '${frame.replace(/'/g, "'\\''")}'`);
+    lines.push(`duration ${frameDuration}`);
+  });
+  if (frames.length > 0) {
+    const last = frames[frames.length - 1];
+    lines.push(`file '${last.replace(/'/g, "'\\''")}'`);
+  }
+  writeFileSync(filePath, lines.join('\n'));
+}
+
+function isNonEmptyFile(filePath) {
+  try {
+    if (!existsSync(filePath)) return false;
+    const stat = statSync(filePath);
+    return stat.isFile() && stat.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function runCommand(command, args, { captureOutput = false } = {}) {
+  const options = { reject: false };
+  if (captureOutput) {
+    options.stdout = 'pipe';
+    options.stderr = 'pipe';
+  } else {
+    options.stdout = 'inherit';
+    options.stderr = 'inherit';
+  }
+
+  try {
+    const { execa } = await loadExeca();
+    const result = await execa(command, args, options);
+    return {
+      status: result.exitCode,
+      error: null,
+      stdout: result.stdout || '',
+      stderr: result.stderr || ''
+    };
+  } catch (error) {
+    return {
+      status: Number.isInteger(error?.exitCode) ? error.exitCode : null,
+      error,
+      stdout: error?.stdout || '',
+      stderr: error?.stderr || ''
+    };
+  }
+}
+
+async function buildAngles360Video(outputPath, frames, fps) {
+  sanitizePath(outputPath, '--angles-360-video output path');
+  frames.forEach((f, i) => sanitizePath(f, `frame[${i}]`));
+  const ffmpegPath = await ensureFfmpegAvailable();
+  const tempListPath = outputPath.replace(/\.mp4$/i, '') + '.concat.txt';
+  const frameDuration = 1 / fps;
+  writeConcatList(tempListPath, frames, frameDuration);
+
+  const args = [
+    '-y',
+    '-f', 'concat',
+    '-safe', '0',
+    '-i', tempListPath,
+    '-r', String(fps),
+    '-pix_fmt', 'yuv420p',
+    outputPath
+  ];
+  const result = await runCommand(ffmpegPath, args);
+  if (result.error || result.status !== 0) {
+    // ffmpeg sometimes exits non-zero even when the output file is usable.
+    // Treat it as success if the output exists and is non-empty.
+    if (isNonEmptyFile(outputPath)) {
+      console.warn('Warning: ffmpeg exited non-zero, but output video exists and is non-empty. Continuing.');
+      return;
+    }
+    const err = new Error('ffmpeg failed to build 360 video.');
+    err.code = 'FFMPEG_FAILED';
+    err.details = { outputPath };
+    throw err;
+  }
+}
+
+async function extractLastFrameFromVideo(videoPath, outputImagePath) {
+  sanitizePath(videoPath, 'video path');
+  sanitizePath(outputImagePath, 'output image path');
+  const ffmpegPath = await ensureFfmpegAvailable();
+
+  // Extract the last frame by reading through the video with update mode
+  // This processes all frames but only keeps the last one
+  const args = [
+    '-i', videoPath,
+    '-vf', 'select=gte(n\\,0)',  // Select all frames (just pass-through)
+    '-vsync', '0',
+    '-update', '1',  // Update same output file (keeps only last frame)
+    '-q:v', '1',  // Best quality
+    '-y',
+    outputImagePath
+  ];
+
+  const result = await runCommand(ffmpegPath, args, { captureOutput: true });
+
+  if (result.error || result.status !== 0 || !isNonEmptyFile(outputImagePath)) {
+    const stderr = result.stderr || '';
+    const stdout = result.stdout || '';
+    console.error('FFmpeg extraction failed:');
+    console.error('  Video path:', videoPath);
+    console.error('  Output path:', outputImagePath);
+    console.error('  Exit code:', result.status);
+    console.error('  Error:', result.error?.message || 'none');
+    if (stderr) console.error('  Stderr:', stderr);
+    if (stdout) console.error('  Stdout:', stdout);
+    console.error('  Output file exists:', existsSync(outputImagePath));
+    if (existsSync(outputImagePath)) {
+      console.error('  Output file size:', statSync(outputImagePath).size);
+    }
+
+    const err = new Error('Failed to extract last frame from video.');
+    err.code = 'FFMPEG_EXTRACT_FAILED';
+    err.details = { videoPath, outputImagePath, stderr, stdout, status: result.status };
+    throw err;
+  }
+}
+
+async function buildConcatVideoFromClips(outputPath, clips, { audioPath = null, audioStart = null } = {}) {
+  sanitizePath(outputPath, '--output path');
+  clips.forEach((c, i) => sanitizePath(c, `clip[${i}]`));
+  if (audioPath) sanitizePath(audioPath, '--concat-audio');
+  const ffmpegPath = await ensureFfmpegAvailable();
+  const tempListPath = outputPath.replace(/\.mp4$/i, '') + '.concat.txt';
+  const lines = clips.map((clip) => `file '${clip.replace(/'/g, "'\\''")}'`);
+  writeFileSync(tempListPath, lines.join('\n'));
+
+  const args = [
+    '-y',
+    '-f', 'concat',
+    '-safe', '0',
+    '-i', tempListPath,
+  ];
+  if (audioPath) {
+    if (Number.isFinite(audioStart) && audioStart > 0) {
+      args.push('-ss', String(audioStart));
+    }
+    args.push('-i', audioPath, '-map', '0:v:0', '-map', '1:a:0');
+  }
+  args.push(
+    '-c:v', 'libx264',
+    '-pix_fmt', 'yuv420p',
+    '-c:a', 'aac',
+    '-b:a', '192k',
+    '-movflags', '+faststart'
+  );
+  if (audioPath) args.push('-shortest');
+  args.push(outputPath);
+
+  const result = await runCommand(ffmpegPath, args);
+  if (result.error || result.status !== 0) {
+    if (isNonEmptyFile(outputPath)) {
+      console.warn('Warning: ffmpeg exited non-zero, but output video exists and is non-empty. Continuing.');
+      return;
+    }
+    const err = new Error('ffmpeg failed to concatenate 360 video clips.');
+    err.code = 'FFMPEG_FAILED';
+    err.details = { outputPath, clips: clips?.length ?? null };
+    throw err;
+  }
+}
+
+async function runImageEditProjectWithEvents(client, editConfig, expectedCount, log, timeoutMs, label) {
+  const results = [];
+  let completed = 0;
+  let projectId = null;
+
+  let resolvePromise;
+  let rejectPromise;
+  const completionPromise = new Promise((resolve, reject) => {
+    resolvePromise = resolve;
+    rejectPromise = reject;
+  });
+
+  const onCompleted = (data) => {
+    if (projectId && data.projectId !== projectId) return;
+    if (!projectId) projectId = data.projectId;
+    const jobData = data.job?.data || {};
+    results.push({
+      imageUrl: data.imageUrl,
+      seed: jobData.seed,
+      jobIndex: data.jobIndex,
+      projectId: data.projectId
+    });
+    completed++;
+    log(`Image ${completed}/${expectedCount}${label ? ` (${label})` : ''} completed`);
+    if (completed >= expectedCount) {
+      cleanup();
+      resolvePromise({ results, projectId });
+    }
+  };
+
+  const onFailed = (data) => {
+    if (projectId && data.projectId !== projectId) return;
+    if (!projectId) projectId = data.projectId;
+    cleanup();
+    rejectPromise(new Error(data.error || 'Job failed'));
+  };
+
+  const cleanup = () => {
+    clearTimeout(timeout);
+    removeClientListener(client, ClientEvent.JOB_COMPLETED, onCompleted);
+    removeClientListener(client, ClientEvent.JOB_FAILED, onFailed);
+  };
+
+  const timeout = setTimeout(() => {
+    cleanup();
+    rejectPromise(new Error(`Timeout after ${timeoutMs / 1000}s`));
+  }, timeoutMs);
+
+  client.on(ClientEvent.JOB_COMPLETED, onCompleted);
+  client.on(ClientEvent.JOB_FAILED, onFailed);
+
+  try {
+    const projectResult = await client.createImageEditProject(editConfig);
+    projectId = projectResult?.project?.id || projectId;
+
+    // Check for errors in the response (e.g., insufficient tokens)
+    if (projectResult?.error || projectResult?.message) {
+      cleanup();
+      throw new Error(projectResult.error || projectResult.message);
+    }
+    if (!projectId) {
+      cleanup();
+      throw new Error('Failed to create project: no project ID returned');
+    }
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+
+  return completionPromise;
+}
+
+async function runMultiAngleFlow(client, log) {
+  const contextBuffer = await fetchMediaBuffer(options.contextImages[0]);
+  const azimuths = options.angles360
+    ? MULTI_ANGLE_AZIMUTHS.map((a) => a.key)
+    : [options.azimuth];
+  const modelDefaults = getModelDefaults(options.model, openclawConfig);
+  const steps = options.steps ?? modelDefaults?.steps ?? (options.model.includes('lightning') ? 4 : 20);
+  const guidance = options.guidance ?? modelDefaults?.guidance ?? (options.model.includes('lightning') ? 1.0 : 4.0);
+
+  let outputConfig = resolveMultiAngleOutputConfig(options.output, options.outputFormat);
+  let tempOutputDir = null;
+  if (options.output && !outputConfig && !options.quiet) {
+    console.error('Warning: Could not resolve output path for multi-angle output.');
+  }
+  if (options.angles360Video && !outputConfig) {
+    tempOutputDir = mkdtempSync(join(tmpdir(), 'sogni-angles-'));
+    outputConfig = {
+      dir: tempOutputDir,
+      prefix: 'angles-360',
+      ext: (options.outputFormat || 'jpg').replace('.', '')
+    };
+  }
+  let videoOutputPath = null;
+  if (options.angles360Video) {
+    if (typeof options.angles360Video === 'string') {
+      videoOutputPath = options.angles360Video;
+    } else if (options.output && outputConfig && outputConfig.ext === 'mp4') {
+      videoOutputPath = options.output;
+    } else if (outputConfig) {
+      const baseName = outputConfig.prefix ? outputConfig.prefix : 'angles-360';
+      videoOutputPath = join(outputConfig.dir, `${baseName}.mp4`);
+    } else {
+      videoOutputPath = join(process.cwd(), 'angles-360.mp4');
+    }
+    if (!videoOutputPath.toLowerCase().endsWith('.mp4')) {
+      videoOutputPath += '.mp4';
+    }
+  }
+  if (outputConfig) {
+    if (outputConfig.ext === 'mp4') {
+      outputConfig.ext = (options.outputFormat || 'jpg').replace('.', '');
+    }
+    if (!existsSync(outputConfig.dir)) {
+      mkdirSync(outputConfig.dir, { recursive: true });
+    }
+  }
+
+  const angleResults = [];
+  const videoFrames = [];
+  for (const azimuth of azimuths) {
+    const prompt = buildMultiAnglePrompt({
+      azimuth,
+      elevation: options.elevation,
+      distance: options.distance,
+      description: options.angleDescription
+    });
+    const editConfig = {
+      modelId: options.model,
+      positivePrompt: prompt,
+      contextImages: [contextBuffer],
+      numberOfMedia: options.count,
+      width: options.width,
+      height: options.height,
+      steps,
+      guidance,
+      tokenType: options.tokenType || 'spark',
+      waitForCompletion: false,
+      disableNSFWFilter: options.noFilter === true
+    };
+    if (options.outputFormat) {
+      editConfig.outputFormat = options.outputFormat;
+    }
+    if (options.sampler) {
+      editConfig.sampler = options.sampler;
+    }
+    if (options.scheduler) {
+      editConfig.scheduler = options.scheduler;
+    }
+    if (options.loras.length > 0) {
+      editConfig.loras = options.loras;
+    }
+    if (options.loraStrengths.length > 0) {
+      editConfig.loraStrengths = options.loraStrengths;
+    }
+    if (options.seed !== null && options.seed !== undefined) {
+      editConfig.seed = options.seed;
+    }
+
+    const { results } = await runImageEditProjectWithEvents(
+      client,
+      editConfig,
+      options.count,
+      log,
+      options.timeout,
+      azimuth
+    );
+    const urls = results.map((r) => r.imageUrl).filter(Boolean);
+    const seeds = results.map((r) => r.seed ?? options.seed);
+
+    if (outputConfig) {
+      const safeAzimuth = azimuth.replace(/[^a-z0-9-]/gi, '-');
+      for (let i = 0; i < urls.length; i++) {
+        const suffix = urls.length > 1 ? `-${i + 1}` : '';
+        const prefix = outputConfig.prefix ? `${outputConfig.prefix}-` : '';
+        const filename = `${prefix}${safeAzimuth}${suffix}.${outputConfig.ext}`;
+        const filePath = join(outputConfig.dir, filename);
+        await downloadUrlToFile(urls[i], filePath);
+        if (options.angles360Video && i === 0) {
+          videoFrames.push(filePath);
+        }
+      }
+    }
+
+    angleResults.push({
+      azimuth,
+      elevation: options.elevation,
+      distance: options.distance,
+      prompt,
+      urls,
+      seeds
+    });
+  }
+
+  const renderInfo = {
+    timestamp: new Date().toISOString(),
+    type: options.angles360 ? 'multi-angle-360' : 'multi-angle',
+    model: options.model,
+    width: options.width,
+    height: options.height,
+    count: options.count,
+    tokenType: options.tokenType || 'spark',
+    seed: options.seed,
+    seedStrategy: options.seedStrategy || null,
+    outputFormat: options.outputFormat || null,
+    sampler: options.sampler || null,
+    scheduler: options.scheduler || null,
+    loras: options.loras.length > 0 ? options.loras : null,
+    loraStrengths: options.loraStrengths.length > 0 ? options.loraStrengths : null,
+    angles: angleResults,
+    localPath: options.output || null
+  };
+
+  let videoModelId = null;
+  if (videoOutputPath) {
+    if (videoFrames.length === 0) {
+      const err = new Error('No local frames available to assemble 360 video.');
+      err.code = 'MISSING_FRAMES';
+      err.hint = 'Ensure the frames were downloaded locally (provide --output dir or check permissions).';
+      throw err;
+    }
+    const clipDir = mkdtempSync(join(tmpdir(), 'sogni-angles-clips-'));
+    videoModelId = resolveVideoModelAlias(options.videoModel || openclawConfig?.videoModels?.i2v || VIDEO_WORKFLOW_DEFAULT_MODELS.i2v, 'i2v');
+    const videoDefaults = getModelDefaults(videoModelId, openclawConfig);
+    const videoDimensionRules = videoDimensionRulesFromDefaults(videoDefaults);
+    const videoSteps = options.steps ?? videoDefaults?.steps;
+    const videoGuidance = options.guidance ?? videoDefaults?.guidance;
+    const segmentCount = videoFrames.length;
+    let segmentDuration = options.duration;
+    let segmentFrames = null;
+    if (options.frames) {
+      segmentFrames = Math.max(17, Math.round(options.frames / segmentCount));
+    } else {
+      segmentDuration = Math.max(1, Math.round(options.duration / segmentCount));
+    }
+    const videoPrompt = options.angleDescription || options.prompt || 'smooth camera rotation';
+    const clipPaths = [];
+
+    for (let i = 0; i < videoFrames.length; i++) {
+      const startPath = videoFrames[i];
+      const endPath = videoFrames[(i + 1) % videoFrames.length];
+
+      // Validate i2v reference resizing constraints for this clip
+      let startBuffer = readFileSync(startPath);
+      let endBuffer = readFileSync(endPath);
+      const startDims = getImageDimensionsFromBuffer(startBuffer);
+      let clipWidth = options.width;
+      let clipHeight = options.height;
+      let needsResize = false;
+
+      if (startDims?.width && startDims?.height) {
+        const predicted = predictSharpInsideResizeDims(startDims.width, startDims.height, clipWidth, clipHeight);
+        if (predicted && (predicted.width % videoDimensionRules.dimensionMultiple !== 0 || predicted.height % videoDimensionRules.dimensionMultiple !== 0)) {
+          // The resized reference will miss the model divisor, so adjust.
+          const candidate = pickCompatibleI2vBoundingBox(startDims.width, startDims.height, clipWidth, clipHeight, { rules: videoDimensionRules });
+          if (!candidate) {
+            // No perfect match - will pre-resize the reference frames
+            needsResize = true;
+            if (i === 0 && !options.quiet) {
+              console.error(
+                `360 video reference frames will be pre-resized to model-compatible dimensions ` +
+                `because no compatible bounding box exists.`
+              );
+            }
+          } else {
+            // Auto-adjust to compatible size
+            if (!cliSet.width && !cliSet.height && !options.strictSize) {
+              clipWidth = candidate.width;
+              clipHeight = candidate.height;
+              if (i === 0 && !options.quiet) {
+                console.error(
+                  `Auto-adjusted 360 video clip size from ${options.width}x${options.height} ` +
+                  `to ${clipWidth}x${clipHeight} so resized reference is divisible by ${videoDimensionRules.dimensionMultiple} ` +
+                  `(would have been ${predicted.width}x${predicted.height}).`
+                );
+              }
+            } else if (options.strictSize) {
+              fatalCliError(
+                `Reference frame ${startDims.width}x${startDims.height} would resize to ${predicted.width}x${predicted.height}, ` +
+                `but both dimensions must be divisible by ${videoDimensionRules.dimensionMultiple}.`,
+                {
+                  code: 'INVALID_VIDEO_SIZE',
+                  details: {
+                    clipIndex: i + 1,
+                    reference: { width: startDims.width, height: startDims.height },
+                    requested: { width: clipWidth, height: clipHeight },
+                    resized: predicted
+                  },
+                  hint: `Try: --width ${candidate.width} --height ${candidate.height} (or omit --strict-size)`
+                }
+              );
+            } else {
+              // User specified explicit dimensions but not --strict-size, auto-adjust anyway
+              clipWidth = candidate.width;
+              clipHeight = candidate.height;
+              if (i === 0 && !options.quiet) {
+                console.error(
+                  `Warning: Adjusted 360 video clip size from ${options.width}x${options.height} ` +
+                  `to ${clipWidth}x${clipHeight} because resized reference would be ${predicted.width}x${predicted.height} ` +
+                  `(not divisible by ${videoDimensionRules.dimensionMultiple}). Use --strict-size to fail instead.`
+                );
+              }
+            }
+          }
+        }
+      }
+
+      // Pre-resize reference frames if needed
+      if (needsResize && startDims?.width && startDims?.height) {
+        startBuffer = await resizeImageBufferForVideo(startBuffer, startDims.width, startDims.height, videoDimensionRules);
+        const endDims = getImageDimensionsFromBuffer(endBuffer);
+        if (endDims?.width && endDims?.height) {
+          endBuffer = await resizeImageBufferForVideo(endBuffer, endDims.width, endDims.height, videoDimensionRules);
+        }
+        const resizedDims = getImageDimensionsFromBuffer(startBuffer);
+        if (i === 0 && !options.quiet) {
+          console.error(
+            `Pre-resized 360 video frames from ${startDims.width}x${startDims.height} to ${resizedDims.width}x${resizedDims.height} ` +
+            `(divisible by ${videoDimensionRules.dimensionMultiple}) to ensure i2v compatibility.`
+          );
+        }
+      }
+
+      const clipConfig = {
+        modelId: videoModelId,
+        positivePrompt: videoPrompt,
+        negativePrompt: '',
+        stylePrompt: '',
+        numberOfMedia: 1,
+        referenceImage: startBuffer,
+        referenceImageEnd: endBuffer,
+        fps: options.fps,
+        width: clipWidth,
+        height: clipHeight,
+        tokenType: options.tokenType || 'spark',
+        waitForCompletion: true,
+        disableNSFWFilter: options.noFilter === true
+      };
+      if (segmentFrames) {
+        clipConfig.frames = segmentFrames;
+      } else {
+        clipConfig.duration = segmentDuration;
+      }
+      if (videoSteps) {
+        clipConfig.steps = videoSteps;
+      }
+      if (videoGuidance !== null && videoGuidance !== undefined) {
+        clipConfig.guidance = videoGuidance;
+      }
+      if (options.autoResizeVideoAssets !== null) {
+        clipConfig.autoResizeVideoAssets = options.autoResizeVideoAssets;
+      }
+      const clipResult = await client.createVideoProject(clipConfig);
+
+      // Check for errors in the response (e.g., insufficient tokens)
+      if (clipResult?.error || clipResult?.message) {
+        throw new Error(clipResult.error || clipResult.message);
+      }
+
+      const clipUrl = clipResult?.videoUrls?.[0];
+      if (!clipUrl) {
+        throw new Error('No video URL returned for 360 segment.');
+      }
+      const clipPath = join(clipDir, `segment-${i + 1}.mp4`);
+      await downloadUrlToFile(clipUrl, clipPath);
+      clipPaths.push(clipPath);
+    }
+
+    await buildConcatVideoFromClips(videoOutputPath, clipPaths);
+    if (!options.quiet) {
+      console.error(`Saved 360 video: ${videoOutputPath}`);
+    }
+  }
+  if (videoOutputPath) {
+    renderInfo.videoPath = videoOutputPath;
+    renderInfo.videoModel = videoModelId;
+  }
+  saveLastRender(renderInfo);
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      success: true,
+      type: renderInfo.type,
+      model: renderInfo.model,
+      width: renderInfo.width,
+      height: renderInfo.height,
+      count: renderInfo.count,
+      tokenType: renderInfo.tokenType,
+      seed: renderInfo.seed,
+      seedStrategy: renderInfo.seedStrategy,
+      outputFormat: renderInfo.outputFormat,
+      sampler: renderInfo.sampler,
+      scheduler: renderInfo.scheduler,
+      loras: renderInfo.loras,
+      loraStrengths: renderInfo.loraStrengths,
+      videoPath: renderInfo.videoPath || null,
+      videoModel: renderInfo.videoModel || null,
+      angles: angleResults
+    }));
+  } else {
+    if (videoOutputPath) {
+      console.log(`video: ${videoOutputPath}`);
+    }
+    angleResults.forEach((angle) => {
+      angle.urls.forEach((url, index) => {
+        const suffix = angle.urls.length > 1 ? `#${index + 1}` : '';
+        console.log(`${angle.azimuth}${suffix}: ${url}`);
+      });
+    });
+  }
+}
+
+async function ensureSufficientVideoBalance(client, log) {
+  if (!options.video || options.estimateVideoCost) return;
+  const tokenType = options.tokenType || 'spark';
+  const tokenLabel = tokenType.toUpperCase();
+  let balance;
+  try {
+    balance = await client.getBalance();
+  } catch (err) {
+    if (!options.quiet) {
+      log(`Warning: Could not fetch balance (${err?.message || 'error'})`);
+    }
+    return;
+  }
+  const available = tokenType === 'sogni' ? balance.sogni : balance.spark;
+  if (!Number.isFinite(available)) return;
+  if (available <= 0) {
+    throw buildBalanceError(
+      `Insufficient ${tokenLabel} balance (have ${formatTokenValue(available)}).`,
+      { tokenType, available }
+    );
+  }
+
+  const modelDefaults = getModelDefaults(options.model, openclawConfig);
+  const steps = resolveVideoSteps(options.model, modelDefaults, options.steps);
+  if (!Number.isFinite(steps) || steps <= 0) return;
+
+  let estimate;
+  try {
+    estimate = await client.estimateVideoCost({
+      modelId: options.model,
+      width: options.width,
+      height: options.height,
+      fps: options.fps,
+      steps,
+      numberOfMedia: options.count,
+      tokenType,
+      ...(options.frames ? { frames: options.frames } : { duration: options.duration })
+    });
+  } catch (err) {
+    if (!options.quiet) {
+      log(`Warning: Could not estimate video cost (${err?.message || 'error'})`);
+    }
+    return;
+  }
+  const required = parseCostEstimate(estimate, tokenType);
+  if (Number.isFinite(required) && available < required) {
+    throw buildBalanceError(
+      `Insufficient ${tokenLabel} balance for video render (need ~${formatTokenValue(required)}, ` +
+      `have ${formatTokenValue(available)}).`,
+      { tokenType, available, required }
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Token auto-fallback: resolve 'auto' to 'spark', retry with 'sogni' on
+// insufficient balance errors.
+// ---------------------------------------------------------------------------
+const _isAutoToken = options.tokenType === 'auto';
+if (_isAutoToken) {
+  options.tokenType = 'spark';
+}
+
+async function main() {
+  let exitCode = 0;
+  const log = options.quiet ? () => {} : console.error.bind(console);
+  let client = null;
+
+  try {
+    if (options.showVersion) {
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          type: 'version',
+          name: 'sogni-creative-agent-skill',
+          version: PACKAGE_VERSION,
+          timestamp: new Date().toISOString()
+        }));
+      } else {
+        console.log(PACKAGE_VERSION);
+      }
+      return;
+    }
+
+    // --- Utility commands (no Sogni auth required) ---
+
+    // Memory commands
+    if (options.memoryAction) {
+      const jsonOut = options.json || JSON_ERROR_MODE;
+      if (options.memoryAction === 'list') {
+        const memories = loadMemories();
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'memory-list', memories, timestamp: new Date().toISOString() }));
+        } else {
+          if (memories.length === 0) { console.log('No memories saved.'); }
+          else { memories.forEach(m => console.log(`  ${m.key}: ${m.value} [${m.category || 'preference'}]`)); }
+        }
+      } else if (options.memoryAction === 'get') {
+        const memories = loadMemories();
+        const found = memories.find(m => m.key === options.memoryKey);
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'memory-get', key: options.memoryKey, found: !!found, memory: found || null, timestamp: new Date().toISOString() }));
+        } else {
+          console.log(found ? `${found.key}: ${found.value}` : `Memory "${options.memoryKey}" not found.`);
+        }
+      } else if (options.memoryAction === 'set') {
+        const action = memorySet(options.memoryKey, options.memoryValue, options.memoryCategory || 'preference');
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'memory-set', action, key: options.memoryKey, value: options.memoryValue, timestamp: new Date().toISOString() }));
+        } else {
+          console.log(`Memory "${options.memoryKey}" ${action}.`);
+        }
+      } else if (options.memoryAction === 'remove') {
+        const removed = memoryRemove(options.memoryKey);
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'memory-remove', removed, key: options.memoryKey, timestamp: new Date().toISOString() }));
+        } else {
+          console.log(removed ? `Memory "${options.memoryKey}" removed.` : `Memory "${options.memoryKey}" not found.`);
+        }
+      }
+      return;
+    }
+
+    // Personality commands
+    if (options.personalityAction) {
+      const jsonOut = options.json || JSON_ERROR_MODE;
+      if (options.personalityAction === 'get') {
+        const text = loadPersonality();
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'personality-get', personality: text, timestamp: new Date().toISOString() }));
+        } else {
+          console.log(text || '(no personality set — using default)');
+        }
+      } else if (options.personalityAction === 'set') {
+        savePersonality(options.personalityText);
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'personality-set', personality: options.personalityText, timestamp: new Date().toISOString() }));
+        } else {
+          console.log('Personality saved.');
+        }
+      } else if (options.personalityAction === 'clear') {
+        clearPersonality();
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'personality-clear', timestamp: new Date().toISOString() }));
+        } else {
+          console.log('Personality cleared.');
+        }
+      }
+      return;
+    }
+
+    // Persona commands (non-generate)
+    if (options.personaAction && options.personaAction !== 'generate') {
+      const jsonOut = options.json || JSON_ERROR_MODE;
+      if (options.personaAction === 'list') {
+        const personas = loadPersonas();
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'persona-list', personas, timestamp: new Date().toISOString() }));
+        } else {
+          if (personas.length === 0) { console.log('No personas saved.'); }
+          else { personas.forEach(p => console.log(`  ${p.name} (${p.relationship}) — ${p.description || 'no description'}${p.voiceClipPath ? ' [has voice]' : ''}`)); }
+        }
+      } else if (options.personaAction === 'add') {
+        const photoPath = options.personaPhoto || options.refImage;
+        if (!photoPath) {
+          fatalCliError('--persona-add requires a reference photo (--ref <path>).', { code: 'INVALID_ARGUMENT' });
+        }
+        const persona = addPersona({
+          name: options.personaName,
+          relationship: options.personaRelationship,
+          description: options.personaDescription,
+          tags: options.personaTags,
+          voice: options.personaVoice,
+          photoPath,
+          voiceClipPath: options.personaVoiceClip
+        });
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'persona-add', persona, timestamp: new Date().toISOString() }));
+        } else {
+          console.log(`Persona "${persona.name}" saved (${persona.relationship}).`);
+          if (persona.photoPath) console.log(`  Photo: ${persona.photoPath}`);
+          if (persona.voiceClipPath) console.log(`  Voice: ${persona.voiceClipPath}`);
+        }
+      } else if (options.personaAction === 'remove') {
+        const removed = removePersona(options.personaName);
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'persona-remove', removed, name: options.personaName, timestamp: new Date().toISOString() }));
+        } else {
+          console.log(removed ? `Persona "${options.personaName}" removed.` : `Persona "${options.personaName}" not found.`);
+        }
+      } else if (options.personaAction === 'resolve') {
+        const persona = resolvePersonaByName(options.personaName);
+        if (jsonOut) {
+          console.log(JSON.stringify({ success: true, type: 'persona-resolve', found: !!persona, persona: persona || null, timestamp: new Date().toISOString() }));
+        } else {
+          if (!persona) { console.log(`Persona "${options.personaName}" not found.`); }
+          else {
+            console.log(`  Name: ${persona.name}`);
+            console.log(`  Relationship: ${persona.relationship}`);
+            if (persona.description) console.log(`  Description: ${persona.description}`);
+            if (persona.tags?.length) console.log(`  Tags: ${persona.tags.join(', ')}`);
+            if (persona.voice) console.log(`  Voice: ${persona.voice}`);
+            if (persona.photoPath) console.log(`  Photo: ${persona.photoPath}`);
+            if (persona.voiceClipPath) console.log(`  Voice clip: ${persona.voiceClipPath}`);
+          }
+        }
+      }
+      return;
+    }
+
+    if (options._resolvedPersona) {
+      const persona = options._resolvedPersona;
+      if (persona.photoPath && existsSync(persona.photoPath)) {
+        log(`Using persona "${persona.name}" (${persona.relationship}) ${options.video ? 'photo as reference frame' : 'photo as context'}`);
+      }
+      if (options.video && options.referenceAudioIdentity) {
+        log(`Using persona "${options._voicePersonaResolvedName || persona.name}" voice identity`);
+      }
+    }
+
+    if (options.extractLastFrame) {
+      const videoPath = sanitizePath(options.extractLastFrame, '--extract-last-frame video');
+      const outputPath = sanitizePath(options.extractLastFrameOutput, '--extract-last-frame output');
+      if (!existsSync(videoPath)) {
+        const err = new Error(`Video file not found: ${videoPath}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      await extractLastFrameFromVideo(videoPath, outputPath);
+      if (options.json || JSON_ERROR_MODE) {
+        console.log(JSON.stringify({
+          success: true,
+          type: 'extract-last-frame',
+          outputPath,
+          timestamp: new Date().toISOString()
+        }));
+      } else {
+        console.log(`Extracted last frame to: ${outputPath}`);
+      }
+      return;
+    }
+
+    if (options.concatVideos) {
+      const outputPath = sanitizePath(options.concatVideos, '--concat-videos output');
+      const clips = options.concatVideosClips.map((c, i) => sanitizePath(c, `clip[${i}]`));
+      const concatAudio = options.concatAudio ? sanitizePath(options.concatAudio, '--concat-audio') : null;
+      for (const clip of clips) {
+        if (!existsSync(clip)) {
+          const err = new Error(`Clip file not found: ${clip}`);
+          err.code = 'FILE_NOT_FOUND';
+          throw err;
+        }
+      }
+      if (concatAudio && !existsSync(concatAudio)) {
+        const err = new Error(`Audio file not found: ${concatAudio}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      await buildConcatVideoFromClips(outputPath, clips, {
+        audioPath: concatAudio,
+        audioStart: options.concatAudioStart
+      });
+      if (options.json || JSON_ERROR_MODE) {
+        console.log(JSON.stringify({
+          success: true,
+          type: 'concat-videos',
+          outputPath,
+          clipCount: clips.length,
+          audioPath: concatAudio || null,
+          audioStart: options.concatAudioStart ?? null,
+          timestamp: new Date().toISOString()
+        }));
+      } else {
+        console.log(`Concatenated ${clips.length} clips to: ${outputPath}${concatAudio ? ` with audio ${concatAudio}` : ''}`);
+      }
+      return;
+    }
+
+    if (options.listMedia) {
+      const mediaType = options.listMedia;
+      const baseDir = MEDIA_INBOUND_DIR;
+
+      const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.webp', '.gif']);
+      const AUDIO_EXTS = new Set(['.m4a', '.mp3', '.wav', '.ogg']);
+
+      let allowedExts;
+      if (mediaType === 'images') allowedExts = IMAGE_EXTS;
+      else if (mediaType === 'audio') allowedExts = AUDIO_EXTS;
+      else allowedExts = new Set([...IMAGE_EXTS, ...AUDIO_EXTS]);
+
+      const files = [];
+      if (existsSync(baseDir)) {
+        // Validate the base directory itself isn't a symlink pointing outside its expected parent.
+        const allowedRoot = realpathSync(dirname(baseDir));
+        const resolvedBase = realpathSync(baseDir);
+        if (!isPathWithinBase(allowedRoot, resolvedBase)) {
+          const err = new Error('Media directory resolves outside of its expected root.');
+          err.code = 'INVALID_PATH';
+          throw err;
+        }
+
+        const entries = readdirSync(baseDir);
+        for (const entry of entries) {
+          const ext = extname(entry).toLowerCase();
+          if (!allowedExts.has(ext)) continue;
+          const fullPath = join(baseDir, entry);
+          // Skip symlinks
+          const lstats = lstatSync(fullPath);
+          if (lstats.isSymbolicLink()) continue;
+          if (!lstats.isFile()) continue;
+          files.push({
+            path: fullPath,
+            name: entry,
+            size: lstats.size,
+            modified: lstats.mtime.toISOString()
+          });
+        }
+        // Sort by mtime descending, return top 5
+        files.sort((a, b) => b.modified.localeCompare(a.modified));
+        files.splice(5);
+      }
+
+      if (options.json || JSON_ERROR_MODE) {
+        console.log(JSON.stringify({
+          success: true,
+          type: 'list-media',
+          mediaType,
+          files,
+          timestamp: new Date().toISOString()
+        }));
+      } else {
+        if (files.length === 0) {
+          console.log(`No ${mediaType} files found in ${baseDir}`);
+        } else {
+          console.log(`Recent ${mediaType} (${files.length}):`);
+          for (const f of files) {
+            console.log(`  ${f.name}  (${f.size} bytes, ${f.modified})`);
+          }
+        }
+      }
+      return;
+    }
+
+    const creds = loadCredentials();
+    log('Connecting to Sogni...');
+    client = new SogniClientWrapper({
+      network: openclawConfig?.defaultNetwork || 'fast',
+      autoConnect: false,
+      ...(creds.SOGNI_API_KEY
+        ? { apiKey: creds.SOGNI_API_KEY, authType: 'apiKey' }
+        : {
+            username: creds.SOGNI_USERNAME,
+            password: creds.SOGNI_PASSWORD,
+            authType: 'token'
+          })
+    });
+
+    await client.connect();
+    log('Connected.');
+
+    if (options.showBalance) {
+      const balance = await client.getBalance();
+      const spark = Number.parseFloat(balance?.spark);
+      const sogni = Number.parseFloat(balance?.sogni);
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          type: 'balance',
+          spark: Number.isFinite(spark) ? spark : null,
+          sogni: Number.isFinite(sogni) ? sogni : null,
+          tokenType: options.tokenType || 'spark',
+          timestamp: new Date().toISOString()
+        }));
+      } else {
+        console.log(`SPARK: ${formatTokenValue(spark)}`);
+        console.log(`SOGNI: ${formatTokenValue(sogni)}`);
+      }
+      return;
+    }
+
+    await ensureSufficientVideoBalance(client, log);
+
+    if (options.estimateVideoCost) {
+      const modelDefaults = getModelDefaults(options.model, openclawConfig);
+      const steps = resolveVideoSteps(options.model, modelDefaults, options.steps);
+      if (!Number.isFinite(steps) || steps <= 0) {
+        const err = new Error('--estimate-video-cost requires --steps (or modelDefaults for this model).');
+        err.code = 'MISSING_STEPS';
+        err.hint = 'Pass --steps explicitly (e.g. --steps 4 for lightx2v models).';
+        throw err;
+      }
+      const estimateParams = {
+        modelId: options.model,
+        width: options.width,
+        height: options.height,
+        fps: options.fps,
+        steps,
+        numberOfMedia: options.count,
+        tokenType: options.tokenType || 'spark'
+      };
+      if (options.frames) {
+        estimateParams.frames = options.frames;
+      } else {
+        estimateParams.duration = options.duration;
+      }
+      const estimate = await client.estimateVideoCost(estimateParams);
+      if (options.json) {
+        const duration = options.frames ? Math.max(1, Math.round((options.frames - 1) / options.fps)) : options.duration;
+        console.log(JSON.stringify({
+          success: true,
+          type: 'video-cost',
+          model: options.model,
+          width: options.width,
+          height: options.height,
+          fps: options.fps,
+          frames: options.frames ?? null,
+          duration,
+          steps,
+          tokenType: options.tokenType || 'spark',
+          count: options.count,
+          estimate
+        }));
+      } else {
+        console.log(`Estimated cost: ${JSON.stringify(estimate)}`);
+      }
+      return;
+    }
+
+    if (options.multiAngle) {
+      if (options.contextImages.length > 1 && !options.quiet) {
+        console.error('Warning: --multi-angle uses the first context image only.');
+      }
+      await runMultiAngleFlow(client, log);
+      return;
+    }
+    
+    const results = [];
+    let completedJobs = 0;
+    let loopingStartImageBuffer;
+    
+    const completionPromise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`Timeout after ${options.timeout / 1000}s`));
+      }, options.timeout);
+      
+      client.on(ClientEvent.JOB_COMPLETED, (data) => {
+        const jobData = data.job?.data || {};
+        results.push({
+          imageUrl: data.imageUrl,
+          videoUrl: data.videoUrl,
+          seed: jobData.seed,
+          jobIndex: data.jobIndex,
+          projectId: data.projectId
+        });
+        completedJobs++;
+        log(`${options.video ? 'Video' : 'Image'} ${completedJobs}/${options.count} completed`);
+        
+        if (completedJobs >= options.count) {
+          clearTimeout(timeout);
+          resolve();
+        }
+      });
+      
+      client.on(ClientEvent.JOB_FAILED, (data) => {
+        clearTimeout(timeout);
+        reject(new Error(data.error || 'Job failed'));
+      });
+
+      client.on(ClientEvent.PROJECT_FAILED, (data) => {
+        clearTimeout(timeout);
+        const message = data?.message || data?.error || 'Project failed';
+        reject(new Error(message));
+      });
+
+      client.on(ClientEvent.PROJECT_EVENT, (event) => {
+        if (event?.type !== 'error') return;
+        clearTimeout(timeout);
+        const message = event?.error?.message || event?.error?.error || 'Project failed';
+        reject(new Error(message));
+      });
+
+      client.on(ClientEvent.JOB_EVENT, (event) => {
+        if (event?.type !== 'error') return;
+        clearTimeout(timeout);
+        const message = event?.error?.message || event?.error?.error || 'Job failed';
+        reject(new Error(message));
+      });
+      
+      // Progress for video
+      if (options.video) {
+        client.on(ClientEvent.PROJECT_PROGRESS, (data) => {
+          if (data.percentage && data.percentage > 0) {
+            log(`Progress: ${Math.round(data.percentage)}%`);
+          }
+        });
+      }
+    });
+    
+    if (options.video) {
+      // Video generation
+      log(`Generating video (${options.videoWorkflow}) with ${options.model}...`);
+      if (options.refImage) log(`Reference image: ${options.refImage}`);
+      if (options.refImageEnd) log(`End frame: ${options.refImageEnd}`);
+      if (options.refAudio) log(`Reference audio: ${options.refAudio}`);
+      if (options.referenceAudioIdentity) log(`Voice identity: ${options._voicePersonaResolvedName || options.referenceAudioIdentity}`);
+      if (options.refVideo) log(`Reference video: ${options.refVideo}`);
+      
+      let imageBuffer = options.refImage ? await fetchMediaBuffer(options.refImage) : undefined;
+      let endImageBuffer = options.refImageEnd ? await fetchMediaBuffer(options.refImageEnd) : undefined;
+      const audioBuffer = options.refAudio ? await fetchMediaBuffer(options.refAudio) : undefined;
+      const videoBuffer = options.refVideo ? await fetchMediaBuffer(options.refVideo) : undefined;
+      const audioIdentityBuffer = options.referenceAudioIdentity ? await fetchMediaBuffer(options.referenceAudioIdentity) : undefined;
+      const modelDefaults = getModelDefaults(options.model, openclawConfig);
+      const videoDimensionRules = videoDimensionRulesFromDefaults(modelDefaults);
+
+      // Pre-resize reference images to model-compatible dimensions if needed for i2v workflow.
+      if (options.videoWorkflow === 'i2v' && imageBuffer && options._needsRefResize) {
+        const dims = getImageDimensionsFromBuffer(imageBuffer);
+        if (dims?.width && dims?.height) {
+          const resizedBuffer = await resizeImageBufferForVideo(imageBuffer, dims.width, dims.height, videoDimensionRules);
+          const resizedDims = getImageDimensionsFromBuffer(resizedBuffer);
+          if (!options.quiet) {
+            console.error(
+              `Pre-resized reference image from ${dims.width}x${dims.height} to ${resizedDims.width}x${resizedDims.height} ` +
+              `(divisible by ${videoDimensionRules.dimensionMultiple}) to ensure i2v compatibility.`
+            );
+          }
+          imageBuffer = resizedBuffer;
+        }
+      }
+      if (options.videoWorkflow === 'i2v' && endImageBuffer && options._needsRefEndResize) {
+        const dims = getImageDimensionsFromBuffer(endImageBuffer);
+        if (dims?.width && dims?.height) {
+          const resizedBuffer = await resizeImageBufferForVideo(endImageBuffer, dims.width, dims.height, videoDimensionRules);
+          const resizedDims = getImageDimensionsFromBuffer(resizedBuffer);
+          if (!options.quiet) {
+            console.error(
+              `Pre-resized end reference image from ${dims.width}x${dims.height} to ${resizedDims.width}x${resizedDims.height} ` +
+              `(divisible by ${videoDimensionRules.dimensionMultiple}) to ensure i2v compatibility.`
+            );
+          }
+          endImageBuffer = resizedBuffer;
+        }
+      }
+      // Preserve the prepared start-frame buffer so looping (A->B->A) can reuse it later.
+      loopingStartImageBuffer = imageBuffer;
+
+      const steps = resolveVideoSteps(options.model, modelDefaults, options.steps);
+      const guidance = options.guidance ?? modelDefaults?.guidance;
+      
+      const projectConfig = {
+        modelId: options.model,
+        positivePrompt: options.prompt,
+        negativePrompt: '',
+        stylePrompt: '',
+        numberOfMedia: options.count,
+        referenceImage: imageBuffer,
+        fps: options.fps,
+        width: options.width,
+        height: options.height,
+        tokenType: options.tokenType || 'spark',
+        waitForCompletion: false,
+        disableNSFWFilter: options.noFilter === true
+      };
+
+      if (options.outputFormat) {
+        projectConfig.outputFormat = options.outputFormat;
+      }
+      if (options.autoResizeVideoAssets !== null) {
+        projectConfig.autoResizeVideoAssets = options.autoResizeVideoAssets;
+      }
+
+      if (options.frames) {
+        projectConfig.frames = options.frames;
+      } else {
+        projectConfig.duration = options.duration;
+      }
+      
+      // Add end frame for interpolation if provided
+      if (endImageBuffer) {
+        projectConfig.referenceImageEnd = endImageBuffer;
+      }
+      if (audioBuffer) {
+        projectConfig.referenceAudio = audioBuffer;
+      }
+      if (options.audioStart !== null) {
+        projectConfig.audioStart = options.audioStart;
+      }
+      if (options.audioDuration !== null) {
+        projectConfig.audioDuration = options.audioDuration;
+      }
+      if (audioIdentityBuffer) {
+        projectConfig.referenceAudioIdentity = audioIdentityBuffer;
+      }
+      if (videoBuffer) {
+        projectConfig.referenceVideo = videoBuffer;
+      }
+      if (options.videoStart !== null) {
+        projectConfig.videoStart = options.videoStart;
+      }
+      if (options.seed !== null && options.seed !== undefined) {
+        projectConfig.seed = options.seed;
+      }
+      if (Number.isFinite(steps)) {
+        projectConfig.steps = steps;
+      }
+      if (guidance !== null && guidance !== undefined) {
+        projectConfig.guidance = guidance;
+      }
+      if (modelDefaults?.sampler) {
+        projectConfig.sampler = modelDefaults.sampler;
+      }
+      if (modelDefaults?.scheduler) {
+        projectConfig.scheduler = modelDefaults.scheduler;
+      }
+      if (modelDefaults?.shift !== null && modelDefaults?.shift !== undefined) {
+        projectConfig.shift = modelDefaults.shift;
+      }
+      if (options.videoControlNetName && !isSeedanceModel(options.model)) {
+        const controlNetStrength = resolveVideoControlNetStrength(options.videoControlNetName, options.videoControlNetStrength);
+        projectConfig.controlNet = {
+          name: options.videoControlNetName,
+          strength: controlNetStrength
+        };
+        if (options.videoControlNetName !== 'detailer') {
+          projectConfig.detailerStrength = 0.6;
+        }
+      } else if (options.videoControlNetName && isSeedanceModel(options.model) && !options.quiet) {
+        console.error('Warning: --controlnet-name ignored for Seedance V2V models.');
+      }
+      if (options.sam2Coordinates) {
+        projectConfig.sam2Coordinates = options.sam2Coordinates;
+      }
+      if (options.trimEndFrame) {
+        projectConfig.trimEndFrame = true;
+      }
+      if (options.firstFrameStrength != null) {
+        projectConfig.firstFrameStrength = options.firstFrameStrength;
+      }
+      if (options.lastFrameStrength != null) {
+        projectConfig.lastFrameStrength = options.lastFrameStrength;
+      }
+
+      const videoResult = await client.createVideoProject(projectConfig);
+
+      // Check for errors in the response (e.g., insufficient tokens)
+      if (videoResult?.error || videoResult?.message) {
+        throw new Error(videoResult.error || videoResult.message);
+      }
+    } else if (options.contextImages.length > 0) {
+      // Image editing with context images
+      log(`Editing with ${options.model}...`);
+      log(`Context images: ${options.contextImages.length}`);
+      if (options.seed !== null && options.seed !== undefined) log(`Using seed: ${options.seed}`);
+      
+      // Load all context images as buffers
+      const contextBuffers = await Promise.all(
+        options.contextImages.map(img => fetchMediaBuffer(img))
+      );
+      const modelDefaults = getModelDefaults(options.model, openclawConfig);
+      const steps = options.steps ?? modelDefaults?.steps ?? (options.model.includes('lightning') ? 4 : 20);
+      const guidance = options.guidance ?? modelDefaults?.guidance ?? (options.model.includes('lightning') ? 3.5 : 7.5);
+      
+      const editConfig = {
+        modelId: options.model,
+        positivePrompt: options.prompt,
+        contextImages: contextBuffers,
+        numberOfMedia: options.count,
+        width: options.width,
+        height: options.height,
+        steps,
+        guidance,
+        tokenType: options.tokenType || 'spark',
+        disableNSFWFilter: options.noFilter === true
+      };
+
+      if (options.outputFormat) {
+        editConfig.outputFormat = options.outputFormat;
+      }
+      if (options.sampler) {
+        editConfig.sampler = options.sampler;
+      }
+      if (options.scheduler) {
+        editConfig.scheduler = options.scheduler;
+      }
+      if (options.loras.length > 0) {
+        editConfig.loras = options.loras;
+      }
+      if (options.loraStrengths.length > 0) {
+        editConfig.loraStrengths = options.loraStrengths;
+      }
+      
+      if (options.seed !== null && options.seed !== undefined) {
+        editConfig.seed = options.seed;
+      }
+      
+      await client.createImageEditProject(editConfig);
+    } else if (options.photobooth) {
+      // Photobooth: face transfer with InstantID ControlNet
+      log(`Photobooth with ${options.model}...`);
+      if (options.seed !== null && options.seed !== undefined) log(`Using seed: ${options.seed}`);
+
+      const faceBuffer = await fetchMediaBuffer(options.refImage);
+      const modelDefaults = getModelDefaults(options.model, openclawConfig);
+      const steps = options.steps ?? modelDefaults?.steps ?? 7;
+      const guidance = options.guidance ?? modelDefaults?.guidance ?? 2;
+
+      const projectConfig = {
+        modelId: options.model,
+        positivePrompt: options.prompt,
+        negativePrompt: '',
+        stylePrompt: '',
+        numberOfMedia: options.count,
+        tokenType: options.tokenType || 'spark',
+        waitForCompletion: false,
+        sizePreset: 'custom',
+        width: options.width,
+        height: options.height,
+        steps,
+        guidance,
+        disableNSFWFilter: options.noFilter === true,
+        sampler: options.sampler || 'dpmpp_sde',
+        scheduler: options.scheduler || 'karras',
+        controlNet: {
+          name: 'instantid',
+          image: faceBuffer,
+          strength: options.cnStrength ?? 0.7,
+          mode: 'balanced',
+          guidanceStart: 0,
+          guidanceEnd: options.cnGuidanceEnd ?? 0.6,
+        }
+      };
+
+      if (options.outputFormat) projectConfig.outputFormat = options.outputFormat;
+      if (options.seed !== null && options.seed !== undefined) projectConfig.seed = options.seed;
+      if (options.loras.length > 0) projectConfig.loras = options.loras;
+      if (options.loraStrengths.length > 0) projectConfig.loraStrengths = options.loraStrengths;
+
+      const projectResult = await client.createImageProject(projectConfig);
+
+      // Check for errors in the response (e.g., insufficient tokens)
+      if (projectResult?.error || projectResult?.message) {
+        throw new Error(projectResult.error || projectResult.message);
+      }
+    } else {
+      // Standard image generation
+      log(`Generating with ${options.model}...`);
+      if (options.seed !== null && options.seed !== undefined) log(`Using seed: ${options.seed}`);
+      const modelDefaults = getModelDefaults(options.model, openclawConfig);
+      const guidance = options.guidance ?? modelDefaults?.guidance ?? 1.0;
+      const steps = options.steps ?? modelDefaults?.steps;
+
+      const useVariations = options.count > 1 && hasPromptVariations(options.prompt);
+      const variationCount = useVariations ? options.count : 1;
+      const imagesPerCall = useVariations ? 1 : options.count;
+
+      for (let vi = 0; vi < variationCount; vi++) {
+        let expandedPrompt = useVariations
+          ? expandPromptVariation(options.prompt, vi)
+          : options.prompt;
+        // Sanitize batch prompts to prevent grid/collage artifacts
+        if (imagesPerCall > 1) expandedPrompt = sanitizeBatchPrompt(expandedPrompt);
+        if (useVariations) {
+          log(`Variation ${vi + 1}/${variationCount}: "${expandedPrompt}"`);
+        }
+
+        const projectConfig = {
+          modelId: options.model,
+          positivePrompt: expandedPrompt,
+          negativePrompt: '',
+          stylePrompt: '',
+          numberOfMedia: imagesPerCall,
+          tokenType: options.tokenType || 'spark',
+          waitForCompletion: false,
+          sizePreset: 'custom',
+          width: options.width,
+          height: options.height,
+          guidance,
+          disableNSFWFilter: options.noFilter === true
+        };
+        if (options.outputFormat) {
+          projectConfig.outputFormat = options.outputFormat;
+        }
+        if (options.sampler) {
+          projectConfig.sampler = options.sampler;
+        }
+        if (options.scheduler) {
+          projectConfig.scheduler = options.scheduler;
+        }
+        if (steps) {
+          projectConfig.steps = steps;
+        }
+
+        if (options.seed !== null && options.seed !== undefined) {
+          projectConfig.seed = options.seed;
+        }
+
+        await client.createImageProject(projectConfig);
+      }
+    }
+    
+    // Wait for completion via events
+    await completionPromise;
+    
+    if (results.length > 0) {
+      const urls = results.map(r => options.video ? r.videoUrl : r.imageUrl).filter(Boolean);
+      const firstResult = results[0];
+      
+      // Save last render info
+      const seeds = results.map(r => r.seed ?? options.seed);
+      const renderInfo = {
+        timestamp: new Date().toISOString(),
+        type: options.video ? 'video' : 'image',
+        prompt: options.prompt,
+        model: options.model,
+        width: options.width,
+        height: options.height,
+        seed: firstResult.seed ?? options.seed,
+        seedStrategy: options.seedStrategy || null,
+        seeds,
+        projectId: firstResult.projectId,
+        urls: urls,
+        localPath: options.output || null,
+        tokenType: options.tokenType || 'spark',
+        quality: options.quality || null
+      };
+      if (options.outputFormat) {
+        renderInfo.outputFormat = options.outputFormat;
+      }
+      if (options.sampler) {
+        renderInfo.sampler = options.sampler;
+      }
+      if (options.scheduler) {
+        renderInfo.scheduler = options.scheduler;
+      }
+      if (options.loras.length > 0) {
+        renderInfo.loras = options.loras;
+      }
+      if (options.loraStrengths.length > 0) {
+        renderInfo.loraStrengths = options.loraStrengths;
+      }
+      if (options.video) {
+        renderInfo.workflow = options.videoWorkflow;
+        renderInfo.fps = options.fps;
+        renderInfo.duration = options.frames ? options.frames / options.fps : options.duration;
+        if (options.frames) renderInfo.frames = options.frames;
+        if (options.targetResolution) renderInfo.targetResolution = options.targetResolution;
+        if (options.autoResizeVideoAssets !== null) {
+          renderInfo.autoResizeVideoAssets = options.autoResizeVideoAssets;
+        }
+        renderInfo.refImage = options.refImage;
+        renderInfo.refImageEnd = options.refImageEnd;
+        if (options.refAudio) {
+          renderInfo.refAudio = options.refAudio;
+          if (options.audioStart !== null) renderInfo.audioStart = options.audioStart;
+          if (options.audioDuration !== null) renderInfo.audioDuration = options.audioDuration;
+        }
+        if (options.referenceAudioIdentity) {
+          renderInfo.referenceAudioIdentity = options.referenceAudioIdentity;
+          if (options._voicePersonaResolvedName || options.voicePersonaName) {
+            renderInfo.voicePersonaName = options._voicePersonaResolvedName || options.voicePersonaName;
+          }
+        }
+        if (options.refVideo) {
+          renderInfo.refVideo = options.refVideo;
+          if (options.videoStart !== null) renderInfo.videoStart = options.videoStart;
+        }
+        if (options.videoControlNetName && !isSeedanceModel(options.model)) {
+          renderInfo.controlNet = {
+            name: options.videoControlNetName,
+            strength: resolveVideoControlNetStrength(options.videoControlNetName, options.videoControlNetStrength)
+          };
+        }
+        if (options.sam2Coordinates) renderInfo.sam2Coordinates = options.sam2Coordinates;
+        if (options.trimEndFrame) renderInfo.trimEndFrame = true;
+        if (options.firstFrameStrength != null) renderInfo.firstFrameStrength = options.firstFrameStrength;
+        if (options.lastFrameStrength != null) renderInfo.lastFrameStrength = options.lastFrameStrength;
+      }
+      if (options.contextImages.length > 0) {
+        renderInfo.contextImages = options.contextImages;
+      }
+      if (options.photobooth) {
+        renderInfo.photobooth = true;
+        renderInfo.refImage = options.refImage;
+      }
+      saveLastRender(renderInfo);
+      
+      // Save to file if requested
+      if (options.output && urls[0]) {
+        const response = await fetch(urls[0]);
+        const buffer = Buffer.from(await response.arrayBuffer());
+
+        const dir = dirname(options.output);
+        if (dir && dir !== '.' && !existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+        // Handle looping for i2v workflow
+        if (options.looping && options.videoWorkflow === 'i2v' && options.refImage) {
+          log('Creating looping video (A→B→A)...');
+
+          // Save first clip temporarily
+          const tempDir = mkdtempSync(join(tmpdir(), 'sogni-loop-'));
+          const clip1Path = join(tempDir, 'clip1.mp4');
+          const lastFramePath = join(tempDir, 'last-frame.png');
+          const clip2Path = join(tempDir, 'clip2.mp4');
+
+          writeFileSync(clip1Path, buffer);
+          log('Extracting last frame...');
+          await extractLastFrameFromVideo(clip1Path, lastFramePath);
+
+          // Generate second clip (last frame → original image)
+          log('Generating return clip (B→A)...');
+
+          // Get model defaults for steps and guidance
+          const modelDefaults2 = getModelDefaults(options.model, openclawConfig);
+          const steps2 = resolveVideoSteps(options.model, modelDefaults2, options.steps);
+          const guidance2 = options.guidance ?? modelDefaults2?.guidance;
+
+          const projectConfig2 = {
+            modelId: options.model,
+            positivePrompt: options.prompt,
+            negativePrompt: '',
+            stylePrompt: '',
+            numberOfMedia: 1,
+            referenceImage: readFileSync(lastFramePath),
+            referenceImageEnd: loopingStartImageBuffer,
+            fps: options.fps,
+            width: options.width,
+            height: options.height,
+            tokenType: options.tokenType || 'spark',
+            waitForCompletion: false,
+            disableNSFWFilter: options.noFilter === true
+          };
+
+          if (options.frames) projectConfig2.frames = options.frames;
+          else if (options.duration) projectConfig2.duration = options.duration;
+          if (Number.isFinite(steps2)) projectConfig2.steps = steps2;
+          if (guidance2 !== null && guidance2 !== undefined) projectConfig2.guidance = guidance2;
+
+          // Create a new client for second clip to avoid event conflicts
+          const creds = loadCredentials();
+          const client2 = new SogniClientWrapper({
+            network: openclawConfig?.defaultNetwork || 'fast',
+            autoConnect: false,
+            ...(creds.SOGNI_API_KEY
+              ? { apiKey: creds.SOGNI_API_KEY, authType: 'apiKey' }
+              : {
+                  username: creds.SOGNI_USERNAME,
+                  password: creds.SOGNI_PASSWORD,
+                  authType: 'token'
+                })
+          });
+          await client2.connect();
+
+          // Create second clip and wait for completion via events
+          const clip2Promise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+              reject(new Error('Second clip generation timed out'));
+            }, options.timeout);
+
+            client2.on(ClientEvent.JOB_COMPLETED, async (data) => {
+              try {
+                clearTimeout(timeout);
+                const clip2Url = data.videoUrl;
+                if (!clip2Url) {
+                  reject(new Error('No video URL returned for second clip.'));
+                  return;
+                }
+
+                // Download second clip
+                const response2 = await fetch(clip2Url);
+                const buffer2 = Buffer.from(await response2.arrayBuffer());
+                writeFileSync(clip2Path, buffer2);
+
+                await client2.disconnect();
+                resolve();
+              } catch (err) {
+                clearTimeout(timeout);
+                reject(err);
+              }
+            });
+
+            client2.on(ClientEvent.JOB_FAILED, (data) => {
+              clearTimeout(timeout);
+              reject(new Error(data.error || 'Second clip generation failed'));
+            });
+
+            client2.on(ClientEvent.PROJECT_FAILED, (data) => {
+              clearTimeout(timeout);
+              reject(new Error(data?.message || 'Second clip project failed'));
+            });
+
+            // Show progress for second clip
+            client2.on(ClientEvent.PROJECT_PROGRESS, (data) => {
+              if (data.percentage && data.percentage > 0) {
+                log(`Progress: ${Math.round(data.percentage)}%`);
+              }
+            });
+          });
+
+          const clip2Result = await client2.createVideoProject(projectConfig2);
+
+          // Check for errors in the response (e.g., insufficient tokens)
+          if (clip2Result?.error || clip2Result?.message) {
+            throw new Error(clip2Result.error || clip2Result.message);
+          }
+
+          await clip2Promise;
+
+          log('Concatenating clips...');
+          await buildConcatVideoFromClips(options.output, [clip1Path, clip2Path]);
+          log(`Saved looping video to ${options.output}`);
+        } else {
+          writeFileSync(options.output, buffer);
+          log(`Saved to ${options.output}`);
+        }
+      }
+      
+      // Output result
+      if (options.json) {
+        const output = {
+          success: true,
+          type: options.video ? 'video' : 'image',
+          prompt: options.prompt,
+          model: options.model,
+          width: options.width,
+          height: options.height,
+          seed: firstResult.seed ?? options.seed,
+          seedStrategy: options.seedStrategy || null,
+          seeds,
+          urls: urls,
+          localPath: options.output || null,
+          tokenType: options.tokenType || 'spark'
+        };
+        if (options.outputFormat) {
+          output.outputFormat = options.outputFormat;
+        }
+        if (options.sampler) {
+          output.sampler = options.sampler;
+        }
+        if (options.scheduler) {
+          output.scheduler = options.scheduler;
+        }
+        if (options.loras.length > 0) {
+          output.loras = options.loras;
+        }
+        if (options.loraStrengths.length > 0) {
+          output.loraStrengths = options.loraStrengths;
+        }
+        if (options.video) {
+          output.workflow = options.videoWorkflow;
+          output.fps = options.fps;
+          output.duration = options.frames ? options.frames / options.fps : options.duration;
+          if (options.frames) output.frames = options.frames;
+          if (options.targetResolution) output.targetResolution = options.targetResolution;
+          output.strictSize = options.strictSize || false;
+          if (options.autoResizeVideoAssets !== null) {
+            output.autoResizeVideoAssets = options.autoResizeVideoAssets;
+          }
+          if (options.refImage) output.refImage = options.refImage;
+          if (options.refImageEnd) output.refImageEnd = options.refImageEnd;
+          if (options.refAudio) {
+            output.refAudio = options.refAudio;
+            if (options.audioStart !== null) output.audioStart = options.audioStart;
+            if (options.audioDuration !== null) output.audioDuration = options.audioDuration;
+          }
+          if (options.referenceAudioIdentity) {
+            output.referenceAudioIdentity = options.referenceAudioIdentity;
+            if (options._voicePersonaResolvedName || options.voicePersonaName) {
+              output.voicePersonaName = options._voicePersonaResolvedName || options.voicePersonaName;
+            }
+          }
+          if (options.refVideo) {
+            output.refVideo = options.refVideo;
+            if (options.videoStart !== null) output.videoStart = options.videoStart;
+          }
+          if (options.videoControlNetName && !isSeedanceModel(options.model)) {
+            output.controlNet = {
+              name: options.videoControlNetName,
+              strength: resolveVideoControlNetStrength(options.videoControlNetName, options.videoControlNetStrength)
+            };
+          }
+          if (options.sam2Coordinates) output.sam2Coordinates = options.sam2Coordinates;
+          if (options.trimEndFrame) output.trimEndFrame = true;
+          if (options.firstFrameStrength != null) output.firstFrameStrength = options.firstFrameStrength;
+          if (options.lastFrameStrength != null) output.lastFrameStrength = options.lastFrameStrength;
+          if (options._effectiveVideoDims?.width && options._effectiveVideoDims?.height) {
+            output.effectiveWidth = options._effectiveVideoDims.width;
+            output.effectiveHeight = options._effectiveVideoDims.height;
+            output.effectiveFromReference = {
+              width: options._effectiveVideoDims.refWidth,
+              height: options._effectiveVideoDims.refHeight
+            };
+          }
+          if (options._adjustedVideoDims) {
+            output.adjustedVideoDims = options._adjustedVideoDims;
+          }
+        }
+        if (options.contextImages.length > 0) {
+          output.contextImages = options.contextImages;
+        }
+        if (options.photobooth) {
+          output.photobooth = true;
+          output.refImage = options.refImage;
+          output.controlNet = {
+            name: 'instantid',
+            strength: options.cnStrength ?? 0.7,
+            guidanceEnd: options.cnGuidanceEnd ?? 0.6,
+          };
+        }
+        console.log(JSON.stringify(output));
+      } else {
+        urls.forEach(url => console.log(url));
+      }
+    } else {
+      throw new Error('No output generated - may have been filtered');
+    }
+    
+  } catch (error) {
+    // Token auto-fallback: if using auto mode and got insufficient balance, retry with the other token
+    const isBalanceError = error.code === 'INSUFFICIENT_BALANCE' || /insufficient/i.test(error.message);
+    if (_isAutoToken && isBalanceError && options.tokenType === 'spark') {
+      log('Insufficient SPARK balance — retrying with SOGNI tokens...');
+      options.tokenType = 'sogni';
+      try {
+        if (client?.isConnected?.()) {
+          await Promise.race([client.disconnect(), new Promise(r => setTimeout(r, 1000))]);
+        }
+      } catch (_) {}
+      return main();
+    }
+
+    exitCode = 1;
+    const shouldJson = options.json || IS_OPENCLAW_INVOCATION;
+    if (shouldJson) {
+      const payload = {
+        success: false,
+        error: error.message,
+        prompt: options.prompt ?? null
+      };
+      if (error.code) payload.errorCode = error.code;
+      if (error.details) payload.errorDetails = error.details;
+      if (error.hint) payload.hint = error.hint;
+      payload.timestamp = new Date().toISOString();
+      payload.node = process.versions.node;
+      payload.cwd = process.cwd();
+      payload.context = {
+        video: options.video || false,
+        workflow: options.video ? (options.videoWorkflow || null) : null,
+        model: options.model || null,
+        width: Number.isFinite(options.width) ? options.width : null,
+        height: Number.isFinite(options.height) ? options.height : null,
+        strictSize: options.video ? (options.strictSize || false) : null,
+        count: Number.isFinite(options.count) ? options.count : null,
+        tokenType: options.tokenType || 'spark',
+        fps: options.video ? options.fps : null,
+        duration: options.video ? (options.frames ? options.frames / options.fps : options.duration) : null,
+        frames: options.video ? (options.frames ?? null) : null,
+        autoResizeVideoAssets: options.video ? (options.autoResizeVideoAssets ?? null) : null,
+        refImage: options.video ? (options.refImage ?? null) : null,
+        refImageEnd: options.video ? (options.refImageEnd ?? null) : null,
+        refAudio: options.video ? (options.refAudio ?? null) : null,
+        referenceAudioIdentity: options.video ? (options.referenceAudioIdentity ?? null) : null,
+        refVideo: options.video ? (options.refVideo ?? null) : null,
+        effectiveWidth: options.video ? (options._effectiveVideoDims?.width ?? null) : null,
+        effectiveHeight: options.video ? (options._effectiveVideoDims?.height ?? null) : null,
+        adjustedVideoDims: options.video ? (options._adjustedVideoDims ?? null) : null
+      };
+      if (IS_OPENCLAW_INVOCATION) payload.openclaw = true;
+      console.log(JSON.stringify(payload));
+      if (!options.json) {
+        console.error(`Error: ${error.message}`);
+        if (error.hint) console.error(`Hint: ${error.hint}`);
+      }
+    } else {
+      console.error(`Error: ${error.message}`);
+      if (error.hint) console.error(`Hint: ${error.hint}`);
+    }
+  } finally {
+    try {
+      if (client?.isConnected?.()) {
+        await Promise.race([
+          client.disconnect(),
+          new Promise(resolve => setTimeout(resolve, 1000))
+        ]);
+      }
+    } catch (e) {}
+  }
+  process.exit(exitCode);
+}
+
+main();