aimakeall-mcp 0.10.0 → 0.12.0

package/lib/cloud-tools.mjs

@@ -26,6 +26,11 @@ import { createUsageEventId } from "./usage-event.mjs";
 import { fetchGenerationJob, GENERATION_JOB_PATH, submitGenerationJob } from "./generation-jobs.mjs";
 import { loudnessDbfsFromWav, silenceRatioFromWav } from "./wav-dsp.mjs";
 import { trimWavToSeconds } from "./wav-trim.mjs";
+import { registerComposerTools } from "./composer-tools.mjs";
+import { productionFields, visualProductionFields, sceneVisual, composerTextStyle, composerOverlay } from "./production-schemas.mjs";
+import { saveProductionContext, readProductionContext, durationReview, reviewProductionPayload } from "./production-context.mjs";
+import { TTS_PROVIDERS, buildTtsRequestBody, estimateTtsSubtitleLines, requestTtsBinary, resolveTtsSelection } from "./tts-workflow.mjs";
+import { assertI2vAllowed, findSceneWebImage, resolveVisualSettings, sceneWebSearchQuery } from "./visual-production.mjs";
 
 // 여러 파일을 base64 로 싣는 요청의 인코딩 크기 합이 서버 JSON 상한을 넘지 않게 사전 검사.
 // 서버가 전체 업로드를 받은 뒤 413 을 내는 것을 막고 행동 가능한 한국어 안내를 준다.
@@ -162,6 +167,7 @@ function trimPlanScenes(scenes) {
     durationSec: scene?.durationSec,
     idx: scene?.idx,
     imagePrompt: scene?.imagePrompt,
+    webSearchQuery: sceneWebSearchQuery(scene),
     label: scene?.label,
     ratio: scene?.ratio,
     sceneNarration: scene?.sceneNarration,
@@ -180,11 +186,13 @@ function trimAnalysis(analysis) {
 }
 
 export function registerCloudTools(server, config, api) {
+  registerComposerTools(server, config, api);
   async function completedGenerationResult(job, includePreview) {
     const payload = job.result || {};
     const resultBody = { generationJobId: job.id, status: job.status, kind: job.kind,
       model: payload.model, taskId: payload.taskId, providerTasks: job.providerTasks };
     if (job.kind === "image") {
+      resultBody.source = "ai";
       resultBody.imageUrl = payload.imageUrl || undefined;
       let inlineImage = null;
       if (!payload.imageUrl && payload.imageDataUrl) {
@@ -281,10 +289,11 @@ export function registerCloudTools(server, config, api) {
       videoModel: z.string().optional().describe("기본 kie-grok-imagine"),
       videoSecondsPerScene: z.number().min(0).max(30).optional().describe("씬당 영상 초 (0이면 영상 미포함)"),
       videoQuality: z.string().optional().describe("기본 720p"),
-      ttsProvider: z.enum(["typecast", "elevenlabs", "supertone"]).optional().describe("기본 typecast"),
+      ttsProvider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 계정별 자동 우선순위. Edge/Supertonic2는 TTS 공급자 비용 0"),
       ttsChars: z.number().int().min(0).max(20000).optional().describe("내레이션 글자 수"),
     },
     wrapCloudHandler(config, async (input) => {
+      if (input.ttsChars > 0) input = { ...input, ttsProvider: (await resolveTtsSelection(api, config, { provider: input.ttsProvider })).provider };
       const payload = await api.request("/api/tracker/cost/estimate", { body: input, method: "POST", timeoutMs: 30_000 });
       return jsonResult(payload);
     }),
@@ -294,6 +303,9 @@ export function registerCloudTools(server, config, api) {
     "plan_shorts_video",
     "쇼츠 영상 기획(시나리오·씬별 이미지 프롬프트·내레이션)을 생성합니다. topic 또는 copy 중 하나는 필수. 결과 scenes의 imagePrompt는 generate_scene_image로, skill은 씬 영상 프롬프트의 videoStylePreset으로, emphasisKeywords는 stitch_timeline의 emphasisKeywords로 이어집니다(하단자막 단어 강조).",
     {
+      productionProfile: productionFields.productionProfile,
+      ...visualProductionFields,
+      durationTargetSec: z.number().positive().max(180).optional().describe("사용자가 요청한 목표 길이(예:40). 음성 길이로 덮어쓰지 않습니다."),
       topic: z.string().optional().describe("영상 주제"),
       copy: z.string().optional().describe("핵심 카피/대사"),
       categoryId: z.enum(["community-shorts", "viral-shorts", "insight"]).optional().describe("기본 community-shorts. insight=명언(통찰) 쇼츠"),
@@ -322,13 +334,17 @@ export function registerCloudTools(server, config, api) {
         forbidden: z.string().optional().describe("금지 변형 (기본: different face, different hairstyle)"),
       })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
     },
-    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 0, characters = [], channelFingerprint = null }) => {
+    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 0, characters = [], channelFingerprint = null, productionProfile, durationTargetSec, imageSourceMode, visualMotionMode }) => {
       if (!String(topic).trim() && !String(copy).trim()) {
         return textResult("topic 또는 copy 중 하나는 입력해야 합니다.", { isError: true });
       }
+      const visualSettings = resolveVisualSettings(null, { productionProfile, imageSourceMode, visualMotionMode });
       const payload = await api.request("/api/tracker/shorts-video/plan", {
         body: {
+          ...visualSettings,
           categoryId,
+          productionProfile,
+          durationTargetSec,
           channelFingerprint,
           copy,
           operationId: createUsageEventId("shorts-plan"),
@@ -343,7 +359,18 @@ export function registerCloudTools(server, config, api) {
         method: "POST",
         timeoutMs: 240_000,
       });
+      const productionPath = saveProductionContext(config.stateDir, {
+        topic, visualSettings, autoCompose: productionProfile?.autoComposeEnabled ?? true,
+        productionProfile: payload?.productionProfile, narrationScript: payload?.narrationScript,
+        narrationSource: payload?.narrationSource, tagline: payload?.tagline, emphasisKeywords: payload?.emphasisKeywords || [],
+        channelFingerprint, scenes: trimPlanScenes(payload?.scenes),
+      });
       return jsonResult({
+        productionPath,
+        ...visualSettings,
+        productionProfile: payload?.productionProfile,
+        narrationSource: payload?.narrationSource,
+        next: `productionPath를 이미지 준비·보이스 추천·TTS·스티치에 계속 전달하세요. ${visualSettings.visualMotionMode === "image-motion" ? "I2V 프롬프트/영상 생성은 생략하고 이미지 URL을 stitch_timeline.sceneVisuals(kind=image)에 넣으세요." : "이미지 확인 후 I2V 영상 생성으로 진행하세요."} 대본을 뉴스체로 바꾸지 말고 컷컴포저 소재도 활용하세요.`,
         charactersUsed: Array.isArray(payload?.charactersUsed) ? payload.charactersUsed : undefined,
         ctaText: payload?.ctaText,
         emphasisKeywords: Array.isArray(payload?.emphasisKeywords) ? payload.emphasisKeywords : [],
@@ -438,6 +465,8 @@ export function registerCloudTools(server, config, api) {
     "plan_commerce_video",
     "제품 홍보 영상 기획을 생성합니다. 제품 사진 파일 경로가 최소 1장 필요합니다 (이 PC의 로컬 경로).",
     {
+      ...visualProductionFields,
+      productionProfile: productionFields.productionProfile,
       productName: z.string().describe("제품명 (필수)"),
       productImagePaths: z.array(z.string()).min(1).describe("제품/자산 사진의 로컬 파일 경로 (1장 이상)"),
       modelImagePath: z.string().optional().describe("모델 사진 로컬 경로 (선택)"),
@@ -455,7 +484,8 @@ export function registerCloudTools(server, config, api) {
         forbidden: z.string().optional().describe("금지 변형 (기본: different face, different hairstyle)"),
       })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
     },
-    wrapCloudHandler(config, async ({ productName, productImagePaths, modelImagePath = "", description = "", targetCustomer = "", tone = "자동 추천", categoryId = "ecommerce", sceneCount = 6, researchBrief = "" , characters = [] }) => {
+    wrapCloudHandler(config, async ({ productName, productImagePaths, modelImagePath = "", description = "", targetCustomer = "", tone = "자동 추천", categoryId = "ecommerce", sceneCount = 6, researchBrief = "" , characters = [], productionProfile, imageSourceMode, visualMotionMode }) => {
+      const visualSettings = resolveVisualSettings(null, { productionProfile, imageSourceMode, visualMotionMode });
       // 확장자 검증(임의 파일 업로드 차단) + 합산 크기 예산(서버 413 사전 차단).
       for (const filePath of productImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "이미지" });
       if (modelImagePath) assertAllowedInputFile(modelImagePath, ALLOWED_IMAGE_EXTS, { kind: "모델 이미지" });
@@ -463,6 +493,7 @@ export function registerCloudTools(server, config, api) {
 
       const payload = await api.request("/api/tracker/commerce-video/plan", {
         body: {
+          ...visualSettings, productionProfile,
           categoryId,
           description,
           modelImage: modelImagePath ? fileToImagePayload(modelImagePath) : null,
@@ -480,7 +511,14 @@ export function registerCloudTools(server, config, api) {
         method: "POST",
         timeoutMs: 300_000,
       });
+      const productionPath = saveProductionContext(config.stateDir, {
+        topic: productName, visualSettings, autoCompose: productionProfile?.autoComposeEnabled ?? true,
+        productionProfile: payload?.productionProfile || productionProfile,
+        tagline: payload?.tagline, narrationScript: payload?.narrationScript,
+        scenes: trimPlanScenes(payload?.scenes), featureKey: "commerceVideo",
+      });
       return jsonResult({
+        productionPath, ...visualSettings, productionProfile: payload?.productionProfile || productionProfile,
         analysis: trimAnalysis(payload?.analysis),
         ctaText: payload?.ctaText,
         ok: payload?.ok,
@@ -493,8 +531,13 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_image",
-    "씬 이미지 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed 결과의 imageUrl을 받은 뒤 씬 영상 입력에 쓰세요. 첫 씬/캐릭터/제품 이미지를 referenceImageUrls·referenceImagePaths로 전달하면 일관성 유지에 도움이 됩니다. 완료 이미지는 직접 확인하거나 verify_scene_image로 검증하세요.",
+    "선택한 방식으로 장면 이미지를 준비합니다. productionPath의 web은 사용자 키로 Pexels/Pixabay 검색만, ai는 AI 생성만, mixed는 웹 검색 후 없을 때 AI 생성합니다. 웹 결과는 즉시 imageUrl·출처를 반환하며 AI만 generationJobId를 get_generation_job으로 조회합니다. image-motion이면 I2V를 생략하고 sceneVisual을 스티치에 사용하세요.",
     {
+      ...productionFields,
+      ...visualProductionFields,
+      sceneIdx: z.number().int().min(0).optional().describe("기획 장면 idx. 저장된 장면 검색어와 출처를 연결합니다."),
+      webSearchQuery: z.string().max(160).optional().describe("장면에 맞는 짧은 웹 검색 키워드. plan.scenes[].webSearchQuery를 사용하세요."),
+      excludeImageUrls: z.array(z.string()).max(100).optional().describe("이미 사용한 웹 이미지 URL. 반복 장면을 피합니다."),
       requestId: z.string().optional().describe("접수 응답 유실 후 같은 작업을 재확인할 때 기존 generationJobId를 지정합니다. 동일 ID·입력은 중복 생성하지 않습니다."),
       prompt: z.string().describe("이미지 프롬프트 (plan 결과의 imagePrompt)"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
@@ -505,7 +548,46 @@ export function registerCloudTools(server, config, api) {
       referenceImageUrls: z.array(z.string()).max(6).optional().describe("참조 이미지 URL (씬1 앵커 등)"),
       referenceImagePaths: z.array(z.string()).max(4).optional().describe("참조 이미지 로컬 경로 (제품 사진 등)"),
     },
-    wrapCloudHandler(config, async ({ requestId, prompt, aspectRatio = "9:16", model = "gpt-image-2-beta", resolution = "1K", referenceImageUrls = [], referenceImagePaths = [], returnImage = true, identityLock = "" }) => {
+    wrapCloudHandler(config, async ({ requestId, prompt, aspectRatio = "9:16", model = "gpt-image-2-beta", resolution = "1K", referenceImageUrls = [], referenceImagePaths = [], returnImage = true, identityLock = "", productionPath, productionProfile, imageSourceMode, visualMotionMode, sceneIdx = 0, webSearchQuery, excludeImageUrls = [] }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      productionProfile = context?.productionProfile || productionProfile;
+      const plannedScene = context?.scenes?.find((entry) => entry.idx === sceneIdx) || {};
+      const saveSource = (source) => saveProductionContext(config.stateDir, {
+        ...context, productionProfile, visualSettings,
+        sceneSources: [...(context?.sceneSources || []).filter((entry) => entry.idx !== sceneIdx), { ...source, idx: sceneIdx }],
+      });
+      let fallbackReason;
+      if (visualSettings.imageSourceMode !== "ai") {
+        // A retry of a possibly accepted paid job must recover it before another
+        // stock selection can hide it. Unknown IDs continue the original flow.
+        if (requestId) {
+          try {
+            const job = await fetchGenerationJob(api, requestId);
+            if (job.kind !== "image") throw new Error("requestId는 이미지 생성 작업 ID여야 합니다. 영상 작업은 get_generation_job으로 조회하세요.");
+            return job.status === "completed" ? completedGenerationResult(job, returnImage)
+              : jsonResult({ generationJobId: job.id, status: job.status, kind: job.kind, existing: true, nextTool: "get_generation_job" });
+          } catch (error) { if (Number(error?.status) !== 404) throw error; }
+        }
+        const query = webSearchQuery || sceneWebSearchQuery(plannedScene) || sceneWebSearchQuery({ imagePrompt: prompt });
+        const selected = await findSceneWebImage(api, {
+          query,
+          excludeImageUrls: [...excludeImageUrls, ...(context?.sceneSources || []).filter((entry) => entry.idx !== sceneIdx).map((entry) => entry.url).filter(Boolean)],
+        });
+        if (selected) {
+          const visual = { ...selected, idx: sceneIdx, label: plannedScene.label || selected.label, durationSec: Number(plannedScene.durationSec) || 6 };
+          return jsonResult({ ok: true, status: "completed", ...visualSettings, source: "web", imageUrl: selected.url,
+            sceneVisual: visual, sourcePage: selected.sourcePage, attribution: selected.attribution, license: selected.license,
+            productionPath: saveSource(visual),
+            guidance: visualSettings.visualMotionMode === "image-motion" ? "sceneVisual을 stitch_timeline.sceneVisuals에 넣으세요. I2V 호출은 하지 않습니다." : "웹 이미지의 내용·출처를 확인한 뒤 I2V 입력으로 사용하세요. 생성 영상에도 이 출처 정보를 보존하세요.",
+          });
+        }
+        if (visualSettings.imageSourceMode === "web") {
+          return { ...jsonResult({ ok: false, code: "WEB_IMAGE_NOT_FOUND", ...visualSettings,
+            message: "사용 가능한 새 웹 이미지를 찾지 못했습니다. 스톡 검색 키·검색어를 확인하거나 직접 이미지를 선택하세요. 웹만 선택했으므로 AI 생성은 실행하지 않았습니다." }), isError: true };
+        }
+        fallbackReason = "혼합 모드: 사용 가능한 새 웹 이미지가 없어 선택한 AI 생성으로 진행합니다.";
+      }
       // identity_lock 리터럴 부착 — 이미 포함돼 있으면 재부착하지 않는다(멱등: 프롬프트 캐시 보존).
       const lock = String(identityLock || "").trim();
       if (lock && !prompt.includes(lock)) prompt = `${prompt.trim()}, ${lock}`;
@@ -519,18 +601,22 @@ export function registerCloudTools(server, config, api) {
         ...referenceImageUrls.map((url, index) => ({ name: `ref-${index + 1}`, previewUrl: url })),
       ].slice(0, 6);
 
-      return jsonResult(await submitGenerationJob(api, {
+      const job = await submitGenerationJob(api, {
         kind: "image", includePreview: returnImage, requestId,
         input: {
+          productionProfile, ...visualSettings,
           aspectRatio,
           model,
           prompt,
           referenceImages,
-          referenceSearchEnabled: true,
+          referenceSearchEnabled: false,
           resolution,
-          webSearchEnabled: true,
+          webSearchEnabled: false,
         },
-      }));
+      });
+      return jsonResult({ ...job, ...visualSettings, source: "ai", fallbackReason,
+        productionPath: saveSource({ source: "ai", generationJobId: job.generationJobId }),
+      });
     }),
   );
 
@@ -538,6 +624,8 @@ export function registerCloudTools(server, config, api) {
     "generate_scene_video_prompt",
     "씬 이미지 기반 영상 프롬프트를 생성합니다. 결과 videoPrompt를 generate_scene_video의 prompt로 넘기세요.",
     {
+      ...productionFields,
+      ...visualProductionFields,
       imagePrompt: z.string().describe("씬의 이미지 프롬프트"),
       sceneImageUrl: z.string().optional().describe("generate_scene_image가 반환한 imageUrl"),
       sceneScript: z.string().optional().describe("씬 대사/설명 (plan 결과의 label)"),
@@ -548,9 +636,13 @@ export function registerCloudTools(server, config, api) {
       kind: z.enum(["shorts_scene", "commerce_video_scene", "music_video_scene"]).optional(),
       modelId: z.string().optional().describe("대상 영상 모델 (기본 kie-grok-imagine — generate_scene_video와 동일하게 맞추세요)"),
     },
-    wrapCloudHandler(config, async ({ imagePrompt, sceneImageUrl = "", sceneScript = "", sceneTitle = "", aspectRatio = "9:16", durationSec = 8, videoStylePreset = "", kind = "shorts_scene", modelId = "kie-grok-imagine" }) => {
+    wrapCloudHandler(config, async ({ imagePrompt, sceneImageUrl = "", sceneScript = "", sceneTitle = "", aspectRatio = "9:16", durationSec = 8, videoStylePreset = "", kind = "shorts_scene", modelId = "kie-grok-imagine", productionPath, productionProfile, imageSourceMode, visualMotionMode }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      assertI2vAllowed(visualSettings);
       const payload = await api.request("/api/tracker/gemini/storyboard-video-prompt", {
         body: {
+          productionProfile: context?.productionProfile || productionProfile, ...visualSettings,
           aspectRatio,
           durationLabel: `${Math.max(1, Math.round(durationSec))}s`,
           generationPlan: {
@@ -579,6 +671,8 @@ export function registerCloudTools(server, config, api) {
     "generate_scene_video",
     "씬 영상 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed가 될 때까지 조회한 뒤 videoUrl을 stitch_timeline에 넣으세요. 접수만 된 상태에서 새로 생성하지 마세요.",
     {
+      ...productionFields,
+      ...visualProductionFields,
       requestId: z.string().optional().describe("접수 응답 유실 후 동일 입력을 재접수할 때 기존 generationJobId를 지정합니다."),
       prompt: z.string().describe("영상 프롬프트 (generate_scene_video_prompt의 videoPrompt)"),
       sceneImageUrl: z.string().optional().describe("씬 이미지 URL (i2v 입력)"),
@@ -588,10 +682,14 @@ export function registerCloudTools(server, config, api) {
       quality: z.string().optional().describe("기본 720p"),
       returnFrames: z.boolean().optional().describe("기본 true — 결과 영상의 대표 프레임 3장을 직접 보고 QC 할 수 있게 이미지 블록으로 반환"),
     },
-    wrapCloudHandler(config, async ({ requestId, prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true }) => {
+    wrapCloudHandler(config, async ({ requestId, prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true, productionPath, productionProfile, imageSourceMode, visualMotionMode }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      assertI2vAllowed(visualSettings);
       return jsonResult(await submitGenerationJob(api, {
         kind: "video", includePreview: returnFrames, requestId,
         input: {
+          productionProfile: context?.productionProfile || productionProfile, ...visualSettings,
           aspectRatio,
           durationLabel: `${Math.max(1, Math.ceil(durationSec))}s`,
           generationPlan: {
@@ -613,55 +711,41 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "tts_narration",
-    "내레이션 TTS를 합성해 이 PC에 mp3로 저장하고 파일 경로를 반환합니다. stitch_timeline의 ttsAudioPath로 쓰세요. 사용자가 보이스를 직접 지정하지 않았다면 먼저 recommend_voice로 주제·샘플 영상에 맞는 보이스를 자동 선정해 voice에 넣으세요.",
+    "내레이션 TTS를 합성해 이 PC에 오디오 파일로 저장합니다. 자동 순서: Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2. 키/런타임이 없을 때 다음 공급자를 고려하며, 합성 실패 후 다른 유료 공급자로 재시도하지 않습니다. 먼저 recommend_voice로 제작 톤에 맞는 보이스를 선택하세요.",
     {
-      text: z.string().describe("내레이션 텍스트"),
-      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+      ...productionFields,
+      text: z.string().optional().describe("생략 시 productionPath의 기획 대본"),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 명시 선택/저장된 보이스는 유지"),
       voice: z.string().optional().describe("보이스 이름(라벨)"),
       speed: z.number().optional().describe("기본 1"),
+      stability: z.number().min(0).max(1).optional(), style: z.number().min(0).max(1).optional(),
+      modelId: z.string().optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, provider = "typecast", voice = "", speed = 1 }) => {
-      const body = provider === "typecast"
-        ? {
-            breath: 0.3,
-            costEventId: createUsageEventId("mcp-tts-typecast"),
-            emotion: "neutral",
-            fileName: "mcp-narration",
-            language: "kor",
-            modelId: "",
-            pitch: 0,
-            smartEmotion: true,
-            speed,
-            text,
-            voice,
-            volume: 100,
-          }
-        : {
-            costEventId: createUsageEventId("mcp-tts-elevenlabs"),
-            fileName: "mcp-narration",
-            languageCode: "ko",
-            modelId: "",
-            similarityBoost: 0.8,
-            speakerBoost: true,
-            speed,
-            stability: 0.45,
-            style: 0.35,
-            text,
-            voice,
-          };
-      const result = await api.requestBinary(`/api/tracker/tts/${provider}`, {
-        body,
-        method: "POST",
-        timeoutMs: 120_000,
-      });
-      const saved = saveMediaBuffer(config.stateDir, "narration.mp3", result.buffer, { contentType: result.contentType });
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      text ??= context?.narrationScript;
+      const selection = await resolveTtsSelection(api, config, { provider, context });
+      provider = selection.provider;
+      if (!voice && context?.voice?.provider && context.voice.provider !== provider) return textResult("보이스 공급자가 다릅니다. 선택한 provider용 voice를 다시 선정하세요.", { isError: true });
+      voice ||= context?.voice?.voiceId || "";
+      if (!text?.trim()) return textResult("대본(text/productionPath)이 필요합니다.", { isError: true });
+      if (productionProfile?.deliveryStyle === "casual-social" && !voice) return textResult("먼저 recommend_voice에 productionPath를 전달해 커뮤니티형 보이스를 선정하세요.", { isError: true });
+      const body = buildTtsRequestBody(provider, { productionProfile, costEventId: createUsageEventId(`mcp-tts-${provider}`), modelId, similarityBoost, speakerBoost, speed, stability, style, text, voice });
+      const result = await requestTtsBinary(api, config, selection, body);
+      const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration.wav" : "narration.mp3", result.buffer, { contentType: result.contentType });
+      const durationSec = audioDurationSecFromFile(saved.filePath);
       return jsonResult({
+        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text, tts: { provider, filePath: saved.filePath, durationSec, voiceId: voice } }),
+        provider,
+        executionTarget: selection.executionTarget,
+        durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
         bytes: saved.bytes,
         // 실측 mp3 길이 — stitch_timeline 의 audioDurationSec 로 그대로 쓰면 타임라인이 정확하다.
-        durationSec: audioDurationSecFromFile(saved.filePath),
+        durationSec,
         filePath: saved.filePath,
         voiceName: decodeHeaderValue(
-          result.headers.get("x-typecast-voice-name") || result.headers.get("x-elevenlabs-voice-name") || "",
+          result.headers.get("x-typecast-voice-name") || result.headers.get("x-elevenlabs-voice-name") || result.headers.get("x-supertone-voice-name") || result.headers.get("x-edge-tts-voice-name") || result.headers.get("x-supertonic2-voice-name") || "",
         ),
       });
     }),
@@ -735,14 +819,23 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "stitch_timeline",
-    "씬 영상들과 오디오를 서버에서 타임라인 매니페스트로 합칩니다. 결과는 파일 핸들(payloadPath)로 반환되며, 이를 render_start에 넘기면 이 PC에서 mp4가 렌더됩니다. 서버는 렌더하지 않습니다. 하단자막 강조: emphasisKeywords 를 주면 자막 라인 안의 해당 단어만 다른 색/크기로 강조되고, subtitleLines[].style 로 라인별 디자인도 바꿀 수 있습니다.",
+    "씬 이미지/영상과 오디오를 타임라인 매니페스트로 합칩니다. image-motion은 sceneVisuals(kind=image)에 인스펙터 imageMotionPreset/Intensity를 적용해 I2V 없이 렌더합니다. autoCompose 기본 true는 문맥별 모션·자막 디자인·적합한 라이브러리 소재를 배치하며 명시 편집을 우선합니다. 결과 payloadPath를 로컬 render_start에 넘기세요.",
     {
+      ...productionFields,
+      ...visualProductionFields,
+      autoCompose: z.boolean().optional().describe("기본 true. 실제 인스펙터 모션·자막 계층·문맥별 라이브러리 자동 편집. false는 수동 편집을 유지합니다."),
+      sceneVisuals: z.array(sceneVisual).min(1).max(200).optional().describe("장면 이미지/영상과 출처 메타데이터. sceneVideos와 동시에 전달하지 마세요."),
+      titleStylePresetId: z.string().optional(), subtitleStylePresetId: z.string().optional(),
+      titleStyle: composerTextStyle.optional(), subtitleStyle: composerTextStyle.optional(),
+      titleSegments: z.array(z.object({ text: z.string(), color: z.string().optional() })).max(20).optional(),
+      overlays: z.array(composerOverlay).max(40).optional().describe("검색한 소재를 장면에 맞는 시간/위치에 배치. 배경 이미지에 그려진 문양은 편집 소재 사용으로 세지 않습니다."),
+      decorationRationale: z.string().max(500).optional().describe("소재를 생략한 이유. 피해자 희화화·권리 위험이면 밈 대신 중립적 아이콘을 검토하세요."),
       sceneVideos: z.array(z.object({
         durationSec: z.number(),
         idx: z.number().int(),
         label: z.string().optional(),
         url: z.string(),
-      })).min(1).describe("씬 순서대로 idx=0부터. url은 generate_scene_video의 videoUrl"),
+      })).min(1).optional().describe("구버전 영상 전용 입력. 새 제작은 sceneVisuals를 권장합니다. image-motion에서는 사용할 수 없습니다."),
       featureKey: z.enum(["shortsVideo", "commerceVideo", "musicVideo"]).optional().describe("기본 commerceVideo"),
       projectTitle: z.string().optional(),
       aspectRatio: z.string().optional().describe("기본 9:16"),
@@ -756,17 +849,8 @@ export function registerCloudTools(server, config, api) {
         endSec: z.number(),
         startSec: z.number(),
         text: z.string(),
-        style: z.object({
-          fontSize: z.number().optional(),
-          fontWeight: z.enum(["bold", "normal"]).optional(),
-          strokeColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional(),
-          strokeWidth: z.number().optional(),
-          textBackgroundColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional(),
-          textBackgroundEnabled: z.boolean().optional(),
-          textBackgroundOpacity: z.number().optional(),
-          textColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional(),
-          textEffectVariant: z.string().optional(),
-        }).optional().describe("이 라인만의 디자인 오버라이드 (내용에 따라 라인별 디자인을 달리할 때)"),
+        stylePresetId: z.string().optional(),
+        style: composerTextStyle.optional(),
       })).optional().describe("자막 타이밍 (쇼츠 하단자막) — tts_narration_with_captions의 subtitleLines를 그대로 사용"),
       emphasisKeywords: z.array(z.string()).max(12).optional().describe("강조 단어 목록 — 자막 라인 안에서 해당 단어만 다른 색/크기로 렌더 (plan_shorts_video의 emphasisKeywords 를 그대로 전달)"),
       emphasisColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional().describe("강조 색 #RRGGBB (기본 #facc15 노랑)"),
@@ -778,7 +862,23 @@ export function registerCloudTools(server, config, api) {
       }).passthrough().optional().describe("measure_channel_spec 이 반환한 fingerprint — 자막 세로 위치·BGM 유무를 참고 채널에 맞춥니다"),
       transitionMode: z.enum(["fade", "none"]).optional().describe("기본 none(하드컷). fade 는 씬이 맞대기로 붙는 배치에서 컷마다 검은 딥을 만든다 — 명시 요청 시에만 쓸 것"),
     },
-    wrapCloudHandler(config, async ({ sceneVideos, featureKey = "commerceVideo", projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines = [], emphasisKeywords = [], emphasisColor = "", emphasisSizeScale = 0, transitionMode = "none", channelFingerprint = null }) => {
+    wrapCloudHandler(config, async ({ sceneVideos, sceneVisuals, autoCompose, imageSourceMode, visualMotionMode, featureKey, projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines, emphasisKeywords, emphasisColor = "", emphasisSizeScale = 0, transitionMode = "none", channelFingerprint = null, productionPath, productionProfile, titleStylePresetId, subtitleStylePresetId, titleStyle, subtitleStyle, titleSegments, overlays, decorationRationale }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      if ((!sceneVisuals?.length && !sceneVideos?.length) || (sceneVisuals?.length && sceneVideos?.length)) {
+        return textResult("sceneVisuals 또는 구버전 sceneVideos 중 하나만 전달하세요.", { isError: true });
+      }
+      if (visualSettings.visualMotionMode === "image-motion" && (sceneVideos?.length || sceneVisuals.some((scene) => scene.kind !== "image"))) {
+        return textResult("IMAGE_MOTION_ONLY: 이미지 모션 제작에는 sceneVisuals(kind=image)만 사용할 수 있습니다.", { isError: true });
+      }
+      autoCompose ??= context?.autoCompose ?? productionProfile?.autoComposeEnabled ?? true;
+      ttsAudioPath ||= context?.tts?.filePath || "";
+      titleText ||= context?.tagline || "";
+      subtitleLines ??= context?.tts?.subtitleLines || [];
+      emphasisKeywords ??= context?.emphasisKeywords || [];
+      featureKey ||= context?.featureKey || (productionProfile?.categoryId?.endsWith("shorts") ? "shortsVideo" : "commerceVideo");
+      channelFingerprint ||= context?.channelFingerprint;
       // 오디오 확장자 검증 + 합산 크기 예산(서버 413 사전 차단).
       if (ttsAudioPath) assertAllowedInputFile(ttsAudioPath, new Set([".mp3", ".wav"]), { kind: "TTS 오디오" });
       if (bgmAudioPath) assertAllowedInputFile(bgmAudioPath, new Set([".mp3", ".wav"]), { kind: "BGM 오디오" });
@@ -788,6 +888,8 @@ export function registerCloudTools(server, config, api) {
         ? audioDurationSec
         : (ttsAudioPath ? audioDurationSecFromFile(ttsAudioPath) : 0);
       const body = {
+        ...visualSettings, autoCompose,
+        productionProfile, titleStylePresetId, subtitleStylePresetId, titleStyle, subtitleStyle, titleSegments, overlays,
         aspectRatio,
         audioDurationSec: resolvedAudioDurationSec,
         bgmAudioUrl: bgmAudioPath ? fileToDataUrl(bgmAudioPath) : "",
@@ -795,12 +897,14 @@ export function registerCloudTools(server, config, api) {
         featureKey,
         muteVideoAudio,
         projectTitle,
-        sceneVideos: sceneVideos.map((scene, index) => ({
+        ...(sceneVisuals ? { sceneVisuals: sceneVisuals.map((scene, index) => ({
+          ...scene, idx: index, label: scene.label || `scene-${index + 1}`,
+        })) } : { sceneVideos: sceneVideos.map((scene, index) => ({
           durationSec: scene.durationSec,
           idx: index,
           label: scene.label || `scene-${index + 1}`,
           url: scene.url,
-        })),
+        })) }),
         emphasisColor,
         emphasisKeywords,
         channelFingerprint,
@@ -818,11 +922,19 @@ export function registerCloudTools(server, config, api) {
       if (!response?.ok || !response?.payload) {
         return textResult(`스티치 실패: ${response?.error || "매니페스트가 비어 있습니다."}`, { isError: true });
       }
+      const autoComposition = response.payload.compositionReport?.autoComposition;
+      if (!decorationRationale && autoComposition?.enabled && autoComposition?.omissions?.length) {
+        decorationRationale = autoComposition.omissions.map((item) => typeof item === "string" ? item : item?.reason || item?.message || "").filter(Boolean).join(" ").slice(0, 500);
+      }
+      if (context || productionProfile) response.payload.productionContext = { ...context, productionProfile, visualSettings, decorationRationale };
+      const qualityReview = reviewProductionPayload(response.payload);
       const handle = savePayloadHandle(config.stateDir, response.payload, "stitch");
       return jsonResult({
         assetCount: Array.isArray(response.payload.assets) ? response.payload.assets.length : 0,
         clipCount: Array.isArray(response.payload.studio?.clips) ? response.payload.studio.clips.length : 0,
-        next: "render_start에 payloadPath를 넘겨 이 PC에서 렌더하세요.",
+        next: qualityReview.pass ? "qualityReview 경고를 검토한 뒤 render_start에 payloadPath를 전달하세요. 최종 영상 프레임과 음성도 검토해야 합니다." : "qualityReview.errors의 길이·소재 선택 검토 문제를 먼저 해결하세요. render_start는 제작 규격 불일치를 차단합니다.",
+        qualityReview,
+        compositionReport: response.payload.compositionReport,
         payloadPath: handle.filePath,
         projectTitle: response.payload.projectTitle,
         sizeBytes: handle.bytes,
@@ -1114,6 +1226,8 @@ export function registerCloudTools(server, config, api) {
     "plan_music_video",
     "뮤직비디오 씬 플랜을 생성합니다. suno_music_download로 받은 곡의 가사·길이(durationSec)를 입력하세요. 결과 scenes의 imagePrompt는 generate_scene_image로 이어집니다.",
     {
+      ...visualProductionFields,
+      productionProfile: productionFields.productionProfile,
       durationSec: z.number().min(10).describe("곡 길이(초) — suno_music_download 결과의 durationSec"),
       lyrics: z.string().optional().describe("가사 전체 (instrumental이면 생략 가능)"),
       conceptBrief: z.string().optional().describe("영상 컨셉 브리프"),
@@ -1130,12 +1244,14 @@ export function registerCloudTools(server, config, api) {
       })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
     },
-    wrapCloudHandler(config, async ({ durationSec, lyrics = "", conceptBrief = "", instrumental = false, sceneSeconds = 5, splitMode = "fixed", videoStylePreset = "seedance-music-video", aspectRatio = "9:16" , characters = [] }) => {
+    wrapCloudHandler(config, async ({ durationSec, lyrics = "", conceptBrief = "", instrumental = false, sceneSeconds = 5, splitMode = "fixed", videoStylePreset = "seedance-music-video", aspectRatio = "9:16" , characters = [], productionProfile, imageSourceMode, visualMotionMode }) => {
       if (!instrumental && !String(lyrics).trim()) {
         return textResult("lyrics를 입력하거나 instrumental=true로 지정하세요.", { isError: true });
       }
+      const visualSettings = resolveVisualSettings(null, { productionProfile, imageSourceMode, visualMotionMode });
       const payload = await api.request("/api/tracker/music-video/plan", {
         body: {
+          ...visualSettings, productionProfile,
           alignedLines: [],
           aspectRatio,
           conceptBrief,
@@ -1154,7 +1270,13 @@ export function registerCloudTools(server, config, api) {
       });
       // usage/원장 이벤트 등 컨텍스트 낭비 필드는 제거하고 기획 본문만 돌려준다.
       const { accountCostEvents, providerUsage, usage, ...plan } = payload && typeof payload === "object" ? payload : {};
-      return jsonResult(plan);
+      const scenes = trimPlanScenes(plan.scenes);
+      const productionPath = saveProductionContext(config.stateDir, {
+        topic: conceptBrief, visualSettings, autoCompose: productionProfile?.autoComposeEnabled ?? true,
+        productionProfile: plan.productionProfile || productionProfile,
+        scenes, featureKey: "musicVideo",
+      });
+      return jsonResult({ ...plan, scenes, ...visualSettings, productionPath });
     }),
   );
 
@@ -1271,17 +1393,31 @@ export function registerCloudTools(server, config, api) {
           endMs: z.number().describe("원본에서 자를 끝(ms)"),
         })).min(1).max(6).describe("이 행에 이어 붙일 원본 구간들"),
       })).min(1).max(40).describe("타임라인 행 — 순서대로 이어 붙습니다"),
-      provider: z.enum(["typecast", "elevenlabs", "supertone"]).optional().describe("TTS 공급자, 기본 typecast (recommend_voice 로 보이스를 먼저 고르세요)"),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. recommend_voice로 보이스를 먼저 고르세요."),
       voiceId: z.string().optional().describe("보이스 ID (생략 시 공급자 기본)"),
       aspectRatio: z.enum(["9:16", "16:9", "1:1"]).optional().describe("기본 9:16"),
       subtitleCropMode: z.enum(["off", "always", "auto"]).optional().describe("원본 박힌 자막 하단 크롭 — auto 는 burnedSubtitle.present 소스만"),
     },
-    wrapCloudHandler(config, async ({ title = "", sourceVideos, rows, provider = "typecast", voiceId = "", aspectRatio = "9:16", subtitleCropMode = "off" }) => {
+    wrapCloudHandler(config, async ({ title = "", sourceVideos, rows, provider, voiceId = "", aspectRatio = "9:16", subtitleCropMode = "off" }) => {
       const sourceIds = new Set(sourceVideos.map((source) => source.id));
       const badRef = rows.flatMap((row) => row.clipRefs).find((ref) => !sourceIds.has(ref.videoId));
       if (badRef) {
         return textResult(`clipRefs 의 videoId "${badRef.videoId}" 가 sourceVideos 에 없습니다.`, { isError: true });
       }
+      const hasNarration = rows.some((row) => ["N", "SN"].includes(row.mode) && row.audioContent?.trim());
+      const selection = hasNarration ? await resolveTtsSelection(api, config, { provider }) : { provider: "typecast", executionTarget: "server" };
+      provider = selection.provider;
+      let preSynthesizedNarrations;
+      if (selection.executionTarget === "companion") {
+        const narrations = {};
+        for (const [rowIndex, row] of rows.entries()) {
+          if (!["N", "SN"].includes(row.mode) || !row.audioContent?.trim()) continue;
+          const text = row.audioContent.trim();
+          const result = await requestTtsBinary(api, config, selection, buildTtsRequestBody(provider, { text, voice: voiceId }));
+          narrations[rowIndex] = { dataUrl: `data:${result.contentType};base64,${result.buffer.toString("base64")}`, charCount: Array.from(text).length, voiceId };
+        }
+        preSynthesizedNarrations = { narrations, attempted: Object.keys(narrations).length, succeeded: Object.keys(narrations).length, lastError: "" };
+      }
       const version = {
         id: "mcp-remake",
         title,
@@ -1299,6 +1435,7 @@ export function registerCloudTools(server, config, api) {
           aspectRatio,
           costEventId: createUsageEventId("mcp-remake-tts"),
           provider,
+          ...(preSynthesizedNarrations ? { preSynthesizedNarrations } : {}),
           subtitleCropMode,
           version,
           voiceId,
@@ -1327,15 +1464,50 @@ export function registerCloudTools(server, config, api) {
   // ── 시간 동기 자막 TTS — 쇼츠 하단자막용 ─────────────────────────────────────
   server.tool(
     "tts_narration_with_captions",
-    "ElevenLabs TTS를 char-level 타이밍과 함께 합성해 mp3 파일 + 시간 동기 자막 라인(subtitleLines)을 만듭니다. 쇼츠 하단자막이 필요하면 tts_narration 대신 이걸 쓰고, 결과 subtitleLines·durationSec·filePath를 stitch_timeline에 그대로 넘기세요 (웹 쇼츠 스튜디오와 동일한 정렬 방식). 사용자가 보이스를 지정하지 않았다면 먼저 recommend_voice(provider=elevenlabs)로 자동 선정하세요.",
+    "TTS 오디오와 자막을 만듭니다. 자동 순서: Typecast→ElevenLabs→Supertone→Edge→Supertonic2, 명시 보이스/공급자는 유지. ElevenLabs는 실제 char-level 타이밍, 나머지는 실측 오디오 길이에 비례한 추정 자막(timingSource 확인)입니다. 먼저 recommend_voice로 제작 톤에 맞는 보이스를 고르세요. 자동 추가 STT 과금이나 다른 공급자로의 재합성은 하지 않습니다.",
     {
-      text: z.string().describe("내레이션 텍스트"),
+      ...productionFields,
+      text: z.string().optional().describe("생략 시 제작 핸들의 기획 대본 그대로 합성. 사실·인용을 바꾸거나 뉴스체로 재작성하지 마세요."),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동 선택 또는 제작 핸들에 선정된 공급자"),
       voice: z.string().optional().describe("보이스 이름 또는 ID (생략 시 기본 보이스)"),
       speed: z.number().optional().describe("기본 1 (0.7~1.2)"),
+      modelId: z.string().optional(), stability: z.number().min(0).max(1).optional(),
+      style: z.number().min(0).max(1).optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, voice = "", speed = 1 }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      text ??= context?.narrationScript;
+      const selection = await resolveTtsSelection(api, config, { provider, context });
+      provider = selection.provider;
+      if (!voice && context?.voice?.provider && context.voice.provider !== provider) {
+        return textResult("보이스 공급자가 다릅니다. 선택한 provider용 voice를 다시 선정하세요.", { isError: true });
+      }
+      voice ||= context?.voice?.voiceId || "";
+      if (!text?.trim()) return textResult("text 또는 기획 대본이 있는 productionPath가 필요합니다.", { isError: true });
+      if (productionProfile?.deliveryStyle === "casual-social" && !voice) {
+        return textResult("커뮤니티형 음성을 위해 먼저 recommend_voice에 productionPath를 전달하고, 반환된 productionPath 또는 보이스 ID를 사용하세요.", { isError: true });
+      }
+      if (provider !== "elevenlabs") {
+        const body = buildTtsRequestBody(provider, { productionProfile, text, voice, speed, modelId, costEventId: createUsageEventId(`mcp-tts-${provider}-captions`) });
+        const result = await requestTtsBinary(api, config, selection, body);
+        const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration-captions.wav" : "narration-captions.mp3", result.buffer, { contentType: result.contentType });
+        const durationSec = audioDurationSecFromFile(saved.filePath);
+        const subtitleLines = estimateTtsSubtitleLines(text, durationSec);
+        const timingSource = "estimated-from-audio-duration";
+        const updatedProductionPath = saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text,
+          tts: { provider, durationSec, filePath: saved.filePath, subtitleLines, voiceId: voice, timingSource },
+        });
+        return jsonResult({ productionPath: updatedProductionPath, productionProfile, provider, executionTarget: selection.executionTarget,
+          durationSec, durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec), filePath: saved.filePath,
+          lineCount: subtitleLines.length, subtitleLines, timingSource,
+          warnings: [durationSec > 0 ? "자막은 실측 오디오 길이 기준 추정입니다. 최종 렌더 전 발화와 동기를 확인하세요." : "오디오 길이를 측정하지 못해 자막을 만들지 않았습니다. 저장된 오디오를 확인하세요. 자동 재합성하지 않습니다."],
+          next: "이 productionPath를 stitch_timeline에 전달하세요. 추정 자막의 발화 동기는 최종 미리보기에서 확인하세요.",
+        });
+      }
       const payload = await api.request("/api/tracker/tts/elevenlabs-with-timestamps", {
         body: {
+          productionProfile, modelId, stability, style, similarityBoost, speakerBoost,
           costEventId: createUsageEventId("mcp-tts-elevenlabs-ts"),
           languageCode: "ko",
           speed,
@@ -1361,7 +1533,18 @@ export function registerCloudTools(server, config, api) {
       const durationSec = Array.isArray(charEnds) && charEnds.length
         ? Math.round(Number(charEnds[charEnds.length - 1]) * 10) / 10
         : audioDurationSecFromFile(saved.filePath);
+      const updatedProductionPath = saveProductionContext(config.stateDir, {
+        ...context, productionProfile, narrationScript: text,
+        tts: { provider, durationSec, filePath: saved.filePath, subtitleLines, voiceId: payload?.voiceId || voice, deliverySettings: payload?.deliverySettings, timingSource: "provider-character-alignment" },
+      });
       return jsonResult({
+        productionPath: updatedProductionPath,
+        provider,
+        timingSource: "provider-character-alignment",
+        productionProfile,
+        deliverySettings: payload?.deliverySettings,
+        durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
+        next: "이 productionPath를 stitch_timeline으로 전달하세요. 목표보다 짧으면 자동 재과금 없이 먼저 대본/말속도와 재합성 비용을 검토하세요. 자막은 실제 발화에 맞추고 강조는 편집 스타일로 적용하세요.",
         durationSec,
         filePath: saved.filePath,
         lineCount: subtitleLines.length,
@@ -1375,10 +1558,12 @@ export function registerCloudTools(server, config, api) {
     "tts_list_voices",
     "TTS 보이스 목록을 조회합니다. 사용자가 목록에서 직접 고르고 싶어할 때 쓰세요 — 주제·샘플 영상 기반 자동 선정은 recommend_voice가 담당합니다. (voice를 생략하면 서버가 기본 보이스로 합성합니다)",
     {
-      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2"),
     },
-    wrapCloudHandler(config, async ({ provider = "typecast" }) => {
-      const payload = await api.request(`/api/tracker/tts/${provider}/voices`, { method: "GET", timeoutMs: 30_000 });
+    wrapCloudHandler(config, async ({ provider }) => {
+      const selection = await resolveTtsSelection(api, config, { provider });
+      provider = selection.provider;
+      const payload = selection.localVoices ? { voices: selection.localVoices } : await api.request(`/api/tracker/tts/${provider}/voices`, { method: "GET", timeoutMs: 30_000 });
       // ElevenLabs 는 gender/age 가 labels 객체 안에 있다 — 두 공급자 형태 모두 지원.
       const voices = (Array.isArray(payload?.voices) ? payload.voices : []).slice(0, 80).map((voice) => ({
         age: voice?.age || voice?.labels?.age,
@@ -1388,7 +1573,7 @@ export function registerCloudTools(server, config, api) {
         nameKo: voice?.voiceNameKo,
         voiceId: voice?.voiceId,
       }));
-      return jsonResult({ count: voices.length, provider, voices });
+      return jsonResult({ count: voices.length, provider, executionTarget: selection.executionTarget, voices });
     }),
   );
 
@@ -1396,13 +1581,20 @@ export function registerCloudTools(server, config, api) {
     "recommend_voice",
     "주제·대본과 사용자가 샘플로 지정한 영상(유튜브)에 어울리는 TTS 보이스를 LLM이 자동 선정합니다. 사용자가 보이스를 직접 지정하지 않았다면 tts_narration/tts_narration_with_captions 전에 이 도구를 호출해 recommendations[0].voiceId를 voice로 쓰세요. 샘플 영상이 있으면 컴패니언 앱이 화자 음성을 추출·분석해 가장 비슷한 보이스를 우선합니다(컴패니언 미실행 시 주제 기반으로만 추천).",
     {
+      ...productionFields,
       topic: z.string().optional().describe("영상 주제·타깃 시청층 (예: 시니어 건강 정보, 커머스 쇼츠)"),
       scriptExcerpt: z.string().optional().describe("대본 앞부분 발췌 (선택)"),
       sampleVideoUrl: z.string().optional().describe("사용자가 샘플로 지정한 유튜브 URL 또는 11자 영상 ID"),
-      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 키가 없으면 다음 후보, 합성 실패 후 자동 재과금 없음"),
       sampleVoiceHints: z.string().optional().describe("사용자가 말한 보이스 요구 (예: 차분한 중년 남성)"),
     },
-    wrapCloudHandler(config, async ({ topic = "", scriptExcerpt = "", sampleVideoUrl = "", provider = "typecast", sampleVoiceHints = "" }) => {
+    wrapCloudHandler(config, async ({ topic = "", scriptExcerpt = "", sampleVideoUrl = "", provider, sampleVoiceHints = "", productionPath, productionProfile }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      const selection = await resolveTtsSelection(api, config, { provider, context });
+      provider = selection.provider;
+      topic ||= context?.topic || "";
+      scriptExcerpt ||= context?.narrationScript?.slice(0, 2000) || "";
       const notes = [];
       let sampleAudioBase64 = "";
       const rawSample = String(sampleVideoUrl || "").trim();
@@ -1431,7 +1623,7 @@ export function registerCloudTools(server, config, api) {
         return textResult("topic, scriptExcerpt, sampleVoiceHints, sampleVideoUrl 중 하나는 필요합니다.", { isError: true });
       }
       const payload = await api.request("/api/tracker/tts/recommend-voice", {
-        body: { provider, sampleAudioBase64, sampleVoiceHints, scriptExcerpt, topic },
+        body: { provider, sampleAudioBase64, sampleVoiceHints, scriptExcerpt, topic, productionProfile, ...(selection.localVoices ? { localVoiceCatalog: selection.localVoices } : {}) },
         method: "POST",
         timeoutMs: 180_000,
       });
@@ -1442,6 +1634,8 @@ export function registerCloudTools(server, config, api) {
         );
       }
       return jsonResult({
+        productionPath: context || productionProfile ? saveProductionContext(config.stateDir, { ...context, productionProfile, voice: { ...payload?.recommendations?.[0], provider } }) : undefined,
+        productionProfile,
         next: "recommendations[0].voiceId를 tts_narration 또는 tts_narration_with_captions의 voice로 사용하세요.",
         notes: [...notes, ...(Array.isArray(payload?.notes) ? payload.notes : [])],
         provider: payload?.provider || provider,