@clipform/mcp-server 1.48.0 → 2.0.1

package/dist/{chunk-3MTEM3VC.js → chunk-SI4C55U6.js}

@@ -6,7 +6,7 @@ import {
   getWorkflowText,
   objectType,
   registerPrompts
-} from "./chunk-BBNREY2Q.js";
+} from "./chunk-PNAMVSVO.js";
 import {
   GUIDE_TYPES,
   QUIZ_VARIANTS,
@@ -14,7 +14,7 @@ import {
   getGuideUri,
   guideFallbackText,
   registerResources
-} from "./chunk-WUORO245.js";
+} from "./chunk-DDBQDDOK.js";
 import {
   ACTIVE_NODE_TYPES,
   BUSINESS,
@@ -23,19 +23,17 @@ import {
   KEN_BURNS_EFFECTS,
   KEN_BURNS_FIT_MODES,
   KEN_BURNS_PRESETS,
-  LABS_COMPOSITION_IDS,
   MCP_TOOL_TIERS,
   NODE_TYPES,
   NON_COUNTABLE_TYPES,
-  PUBLIC_COMPOSITION_IDS,
   SLIDESHOW_TRANSITIONS,
-  SOCIAL_COMPOSITION_IDS,
   callApi,
   errorResult,
+  exposedCompositionIds,
   resolveFormType,
   structuredResult,
   textResult
-} from "./chunk-4CY5EJCR.js";
+} from "./chunk-ET43M6YO.js";
 import {
   __commonJS,
   __export,
@@ -16988,14 +16986,9 @@ import { fileURLToPath } from "url";
 var _endScreen = NODE_TYPES.end_screen.config_schema.properties;
 var END_SCREEN_ICONS = _endScreen.icon.enum;
 var END_SCREEN_CTA_TYPES = _endScreen.cta_type.enum;
-var PUBLIC_COMPOSITIONS = PUBLIC_COMPOSITION_IDS;
-var LABS_COMPOSITIONS = LABS_COMPOSITION_IDS;
-var SOCIAL_COMPOSITIONS = SOCIAL_COMPOSITION_IDS;
-var EXPOSED_COMPOSITIONS = [
-  ...PUBLIC_COMPOSITIONS,
-  ...process.env.CLIPFORM_LABS === "1" ? LABS_COMPOSITIONS : [],
-  ...process.env.CLIPFORM_SOCIAL === "1" ? SOCIAL_COMPOSITIONS : []
-];
+var EXPOSED_COMPOSITIONS = exposedCompositionIds(
+  process.env.NODE_ENV !== "production"
+);
 
 // src/lib/schemas.ts
 var ACTIVE_NODE_TYPES2 = ACTIVE_NODE_TYPES;
@@ -17039,7 +17032,7 @@ function generateConfigSummary(configSchema, typeKey) {
       parts.push(`${key} ({${childKeys}})`);
     }
   }
-  if (typeKey === "contact") {
+  if (typeKey === "details") {
     parts.push(`Available field IDs: ${CONTACT_FIELD_IDS.join(", ")}`);
   }
   return parts.length > 0 ? `Config: ${parts.join(", ")}` : "";
@@ -17073,6 +17066,12 @@ var NODE_TYPES_DESCRIPTION = (() => {
 })();
 var CONFIG_FIELD_DESCRIPTION = "Type-specific configuration keyed by node type. Omit to use defaults. Per-type keys, shapes, and defaults are listed in the clipform_create_form description; craft guidance via clipform_get_guide.";
 var STYLE_PRESET_ENUM = external_exports.enum(KEN_BURNS_PRESETS).describe(`Ken Burns style preset: ${KEN_BURNS_PRESETS.join(", ")}`);
+var CaptionSchema = external_exports.object({
+  start: external_exports.number().describe("Segment start time in seconds"),
+  end: external_exports.number().describe("Segment end time in seconds"),
+  text: external_exports.string().describe("Full segment text"),
+  words: external_exports.array(external_exports.object({ word: external_exports.string(), start: external_exports.number(), end: external_exports.number() })).optional().describe("Per-word timestamps within the segment")
+});
 var OptionSchema = external_exports.object({
   content: external_exports.string().describe("Option text"),
   score: external_exports.number().optional().describe("Score value for this option (for scored quizzes). Use 1 for correct, 0 for wrong. Scored options automatically enable correct-answer marking (record_scores) on the node."),
@@ -17132,7 +17131,7 @@ Example: A form that asks a question, collects contact info, then finishes:
   title: "Quick Survey",
   nodes: [
     { type: "open", prompt: "What's your biggest challenge?" },
-    { type: "contact", prompt: "Leave your details", config: { fields: [{ id: "first_name", required: true }, { id: "email", required: true }] } },
+    { type: "details", prompt: "Leave your details", config: { fields: [{ id: "first_name", required: true }, { id: "email", required: true }] } },
     { type: "end_screen", prompt: "Thanks for your response!" }
   ]
 }`,
@@ -17150,7 +17149,7 @@ Example: A form that asks a question, collects contact info, then finishes:
         form_id: external_exports.string().describe("Form UUID - pass to follow-up tools"),
         viewer_url: external_exports.string().describe("Live form URL for respondents"),
         dashboard_url: external_exports.string().optional().describe("Builder URL (sign in to edit)"),
-        nodes: external_exports.array(external_exports.object({ id: external_exports.string(), type: external_exports.string(), prompt: external_exports.string() })).describe("Created nodes in order - IDs for upload_node_media / update_node"),
+        nodes: external_exports.array(external_exports.object({ id: external_exports.string(), type: external_exports.string(), prompt: external_exports.string() })).describe("Created nodes in order - IDs for attach_node_media / update_node"),
         plan: external_exports.object({ name: external_exports.string(), auth_mode: external_exports.string() }).optional().describe("Plan and auth context for this session")
       },
       annotations: {
@@ -17258,7 +17257,7 @@ Example: A form that asks a question, collects contact info, then finishes:
         `Title: ${title}`,
         `Form ID: ${formId}`,
         ``,
-        `Node IDs (use directly with upload_node_media / update_node - no get_form round-trip needed):`,
+        `Node IDs (use directly with attach_node_media / update_node - no get_form round-trip needed):`,
         ...createdNodes.map((n) => `- [${n.type}] "${truncate(n.prompt)}": ${n.id}`),
         ``,
         `FORM URL (live - share this with respondents): ${data.viewer_url}`
@@ -17270,7 +17269,7 @@ Example: A form that asks a question, collects contact info, then finishes:
         ``,
         `The form is live and accessible at the FORM URL above. Continue with media/narration steps if needed - changes appear immediately.`,
         `The URLs above are exact values; constructed or guessed URLs return 404. Use the FORM URL and DASHBOARD URL as shown.`,
-        `Pass form_id on follow-up tools (get_form, add_node, upload_node_media, etc.).`
+        `Pass form_id on follow-up tools (get_form, add_node, attach_node_media, etc.).`
       );
       if (planContext) {
         const nodePart = planContext.node_limit === null ? "unlimited nodes" : `up to ${planContext.node_limit} nodes per form`;
@@ -17473,7 +17472,7 @@ function registerGetFormTool(server) {
             config: external_exports.record(external_exports.unknown()).optional(),
             options: external_exports.array(external_exports.object({ id: external_exports.string(), content: external_exports.string() })).optional()
           })
-        ).describe("Nodes in sequential order - IDs for update_node / upload_node_media")
+        ).describe("Nodes in sequential order - IDs for update_node / attach_node_media")
       },
       annotations: {
         readOnlyHint: true,
@@ -17665,7 +17664,7 @@ function registerAddNodeTool(server) {
         )
       },
       outputSchema: {
-        node_id: external_exports.string().describe("ID of the created node - pass to update_node / upload_node_media"),
+        node_id: external_exports.string().describe("ID of the created node - pass to update_node / attach_node_media"),
         type: external_exports.string().describe("Node type that was added")
       },
       annotations: {
@@ -17702,7 +17701,9 @@ var NodeUpdateSchema = external_exports.object({
   label: external_exports.string().optional().describe("Short label for the node (used in logic builder)"),
   type: external_exports.enum(ACTIVE_NODE_TYPES2).optional().describe("Change the node type"),
   required: external_exports.boolean().optional().describe("Whether an answer is required"),
-  config: external_exports.record(external_exports.unknown()).optional().describe(CONFIG_FIELD_DESCRIPTION),
+  config: external_exports.record(external_exports.unknown()).optional().describe(
+    `${CONFIG_FIELD_DESCRIPTION} Merged shallowly into the stored config - only the keys you pass are changed. Set a key to null to delete it; nested objects are replaced wholesale. When type is changed in the same call, config replaces the stored configuration instead of merging.`
+  ),
   options: external_exports.array(OptionSchema).optional().describe(
     "Replace all options (for choice nodes). Omit to keep existing options."
   )
@@ -17814,10 +17815,8 @@ function registerDeleteNodeTool(server) {
   );
 }
 
-// src/tools/upload-node-media.ts
-var MEDIA_SUPPORTED_TYPES = Object.entries(NODE_TYPES).filter(([, def]) => def.supports_media).map(([type]) => type);
-var MediaItemSchema = external_exports.object({
-  node_id: external_exports.string().describe("The node ID"),
+// src/tools/upload-media-asset.ts
+var MediaAssetItemSchema = external_exports.object({
   media_type: external_exports.enum(["video", "still"]).describe("Type of media"),
   media_source: external_exports.enum(["uploaded", "recorded"]).default("uploaded").describe("How the media was created"),
   url: external_exports.string().url().optional().describe("Public URL of the media file. When provided, the server fetches and stores it directly."),
@@ -17834,30 +17833,28 @@ var MediaItemSchema = external_exports.object({
         })
       ).optional().describe("Per-word timestamps within the segment")
     })
-  ).optional().describe("Word-level captions from clipform_generate_tts. Required for per-word highlighting - pass the full objects including 'words' arrays."),
-  show_captions: external_exports.boolean().optional().describe("Display captions/subtitles on the node. Defaults to on; pass false to hide them."),
-  fit_media: external_exports.boolean().optional().describe("Show the whole frame (contain) instead of cover-cropping. ALWAYS set true when attaching renders from clipform_render_composition or clipform_generate_video - they are composed 9:16 frames that must never be cropped. Leave unset for user-supplied media (arbitrary aspect ratios want the cover default).")
+  ).optional().describe("Word-level captions from clipform_generate_tts. Required for per-word highlighting - pass the full objects including 'words' arrays.")
 });
-function registerUploadNodeMediaTool(server) {
+function registerUploadMediaAssetTool(server) {
   server.registerTool(
-    "clipform_upload_node_media",
+    "clipform_upload_media_asset",
     {
-      title: "Upload Node Media",
-      description: `Upload media for one or more nodes. Pass one item or many (max 10). Multiple items upload sequentially.
+      title: "Upload Media Asset",
+      description: `Put one or more media files into your workspace media library (max 10, uploaded sequentially). This is step one of attaching media to a node - follow up with clipform_attach_node_media to place the returned media_asset_id on a node.
 
-When a public URL is provided, the media is fetched and stored automatically. Only works on node types that support media (${MEDIA_SUPPORTED_TYPES.join(", ")}). For video: ingested via Mux. For image: stored in Supabase. Each upload lands in your workspace media library and is then attached to the node (so it is reusable across nodes), matching the builder. Captions from clipform_generate_tts enable per-word highlighting in the viewer. When attaching renders from clipform_render_composition or clipform_generate_video, set fit_media: true on each item.`,
+When a public URL is provided, the media is fetched and stored automatically. For video: ingested via Mux. For image: stored in Supabase. Captions from clipform_generate_tts enable per-word highlighting in the viewer once attached.`,
       inputSchema: {
-        form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)"),
-        items: external_exports.array(MediaItemSchema).min(1).max(10).describe("One or more media items to upload")
+        items: external_exports.array(MediaAssetItemSchema).min(1).max(10).describe("One or more media items to create as workspace library assets")
       },
       outputSchema: {
         results: external_exports.array(
           external_exports.object({
-            node_id: external_exports.string(),
-            ok: external_exports.boolean(),
+            media_asset_id: external_exports.string().optional(),
+            media_type: external_exports.string(),
             stored: external_exports.boolean().describe("Bytes already stored (URL-based); false when an upload_url is pending"),
             upload_url: external_exports.string().optional(),
             upload_method: external_exports.string().optional(),
+            ok: external_exports.boolean(),
             error: external_exports.string().optional()
           })
         ).describe("One result per item, in order")
@@ -17869,21 +17866,24 @@ When a public URL is provided, the media is fetched and stored automatically. On
         openWorldHint: false
       }
     },
-    async ({ form_id, items }) => {
-      const workspaceId = getMcpAuth()?.workspace_id;
+    async ({ items }) => {
+      const meResult = await callApi("/me", { method: "GET" });
+      if (!meResult.ok) {
+        return errorResult(`Unable to determine workspace: ${meResult.error}`);
+      }
+      const me = meResult.data;
+      const workspaceId = me.workspace?.id ?? null;
+      if (!workspaceId) {
+        return errorResult(
+          "No workspace available. This usually means authentication is misconfigured - check your API key or OAuth connection."
+        );
+      }
       const lines = [];
       const results = [];
       let successCount = 0;
       for (let i = 0; i < items.length; i++) {
         const item = items[i];
-        if (items.length > 1) lines.push(`--- Item ${i + 1} (node ${item.node_id}) ---`);
-        if (!workspaceId) {
-          const error2 = "no workspace in context - reconnect the MCP or set CLIPFORM_API_KEY so media can land in your library.";
-          lines.push(`FAILED: ${error2}`);
-          lines.push("");
-          results.push({ node_id: item.node_id, ok: false, stored: false, error: error2 });
-          continue;
-        }
+        if (items.length > 1) lines.push(`--- Item ${i + 1} (${item.media_type}) ---`);
         const createBody = {
           media_type: item.media_type,
           media_source: item.media_source
@@ -17894,7 +17894,7 @@ When a public URL is provided, the media is fetched and stored automatically. On
         if (!created.ok) {
           lines.push(`FAILED: ${created.error}`);
           lines.push("");
-          results.push({ node_id: item.node_id, ok: false, stored: false, error: created.error });
+          results.push({ media_type: item.media_type, stored: false, ok: false, error: created.error });
           continue;
         }
         const mediaAssetId = created.data.media_asset_id;
@@ -17902,17 +17902,97 @@ When a public URL is provided, the media is fetched and stored automatically. On
           const error2 = `upload did not return a media asset id (route ${String(created.data.route ?? "unknown")}).`;
           lines.push(`FAILED: ${error2}`);
           lines.push("");
-          results.push({ node_id: item.node_id, ok: false, stored: false, error: error2 });
+          results.push({ media_type: item.media_type, stored: false, ok: false, error: error2 });
           continue;
         }
+        successCount++;
+        const uploadUrl = created.data.upload_url;
+        const uploadMethod = created.data.upload_method;
+        results.push({
+          media_asset_id: mediaAssetId,
+          media_type: item.media_type,
+          ok: true,
+          stored: !uploadUrl,
+          ...uploadUrl ? { upload_url: uploadUrl } : {},
+          ...uploadUrl && uploadMethod ? { upload_method: uploadMethod } : {}
+        });
+        const resultLines = [`Media asset ID: ${mediaAssetId}`];
+        if (uploadUrl) {
+          resultLines.push(
+            `Upload URL: ${uploadUrl}`,
+            `Upload method: ${uploadMethod}`,
+            `Upload the file directly to the upload URL using ${uploadMethod === "tus" ? "TUS resumable upload" : "HTTP PUT"}.`
+          );
+        } else {
+          resultLines.push(`Media stored in the workspace library.`);
+        }
+        if (item.captions) {
+          resultLines.push(`Captions: ${item.captions.length} segments saved`);
+        }
+        lines.push(resultLines.join("\n"));
+        lines.push("");
+      }
+      if (items.length > 1) {
+        lines.unshift(`Media asset upload: ${successCount}/${items.length} succeeded
+`);
+      }
+      lines.push(`Attach these to nodes with clipform_attach_node_media.`);
+      if (successCount === 0) return errorResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { results });
+    }
+  );
+}
+
+// src/tools/attach-node-media.ts
+var MEDIA_SUPPORTED_TYPES = Object.entries(NODE_TYPES).filter(([, def]) => def.supports_media).map(([type]) => type);
+var AttachMediaItemSchema = external_exports.object({
+  node_id: external_exports.string().describe("The node ID"),
+  media_asset_id: external_exports.string().describe("A media asset ID returned by clipform_upload_media_asset"),
+  fit_media: external_exports.boolean().optional().describe("Show the whole frame (contain) instead of cover-cropping. ALWAYS set true when attaching renders from clipform_render_composition or clipform_generate_video - they are composed 9:16 frames that must never be cropped. Leave unset for user-supplied media (arbitrary aspect ratios want the cover default)."),
+  show_captions: external_exports.boolean().optional().describe("Display captions/subtitles on the node. Defaults to on; pass false to hide them.")
+});
+function registerAttachNodeMediaTool(server) {
+  server.registerTool(
+    "clipform_attach_node_media",
+    {
+      title: "Attach Node Media",
+      description: `Attach an existing workspace media asset (from clipform_upload_media_asset) to one or more nodes (max 10). Pass one item or many; multiple items attach sequentially. Only works on node types that support media (${MEDIA_SUPPORTED_TYPES.join(", ")}). A media asset is reusable - attach the same media_asset_id to several nodes.`,
+      inputSchema: {
+        form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)"),
+        items: external_exports.array(AttachMediaItemSchema).min(1).max(10).describe("One or more attachments to make")
+      },
+      outputSchema: {
+        results: external_exports.array(
+          external_exports.object({
+            node_id: external_exports.string(),
+            ok: external_exports.boolean(),
+            media_asset_id: external_exports.string().optional(),
+            error: external_exports.string().optional()
+          })
+        ).describe("One result per item, in order")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    async ({ form_id, items }) => {
+      const lines = [];
+      const results = [];
+      let successCount = 0;
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (items.length > 1) lines.push(`--- Item ${i + 1} (node ${item.node_id}) ---`);
         const attached = await callApi(`/forms/${form_id}/nodes/${item.node_id}/media/attach`, {
           method: "POST",
-          body: { media_asset_id: mediaAssetId }
+          body: { media_asset_id: item.media_asset_id }
         });
         if (!attached.ok) {
-          lines.push(`FAILED to attach the uploaded media to the node: ${attached.error}`);
+          lines.push(`FAILED to attach media to the node: ${attached.error}`);
           lines.push("");
-          results.push({ node_id: item.node_id, ok: false, stored: false, error: attached.error });
+          results.push({ node_id: item.node_id, ok: false, error: attached.error });
           continue;
         }
         const presentation = {};
@@ -17929,34 +18009,14 @@ When a public URL is provided, the media is fetched and stored automatically. On
           }
         }
         successCount++;
-        const uploadUrl = created.data.upload_url;
-        const uploadMethod = created.data.upload_method;
-        results.push({
-          node_id: item.node_id,
-          ok: true,
-          stored: !uploadUrl,
-          ...uploadUrl ? { upload_url: uploadUrl } : {},
-          ...uploadUrl && uploadMethod ? { upload_method: uploadMethod } : {}
-        });
-        const resultLines = [];
-        if (created.data.upload_url) {
-          resultLines.push(
-            `Upload URL: ${created.data.upload_url}`,
-            `Upload method: ${created.data.upload_method}`,
-            `Upload the file directly to the upload URL using ${created.data.upload_method === "tus" ? "TUS resumable upload" : "HTTP PUT"}.`
-          );
-        } else {
-          resultLines.push(`Media stored in the workspace library and attached to the node.`);
-        }
-        if (item.captions) {
-          resultLines.push(`Captions: ${item.captions.length} segments saved`);
-        }
+        results.push({ node_id: item.node_id, ok: true, media_asset_id: item.media_asset_id });
+        const resultLines = [`Media attached to the node.`];
         if (presentationNote) resultLines.push(presentationNote);
         lines.push(resultLines.join("\n"));
         lines.push("");
       }
       if (items.length > 1) {
-        lines.unshift(`Media upload: ${successCount}/${items.length} succeeded
+        lines.unshift(`Media attach: ${successCount}/${items.length} succeeded
 `);
       }
       if (successCount === 0) return errorResult(lines.join("\n"));
@@ -18268,7 +18328,7 @@ Supports any public YouTube video with captions enabled. Does NOT work for priva
 }
 
 // src/tools/generate-tts.ts
-var CaptionSchema = external_exports.object({
+var CaptionSchema2 = external_exports.object({
   start: external_exports.number(),
   end: external_exports.number(),
   text: external_exports.string(),
@@ -18299,7 +18359,7 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
           external_exports.object({
             ok: external_exports.boolean(),
             audio_url: external_exports.string().optional(),
-            captions: external_exports.array(CaptionSchema).optional().describe("Pass as the captions param to upload_node_media"),
+            captions: external_exports.array(CaptionSchema2).optional().describe("Pass as the captions param to upload_media_asset"),
             error: external_exports.string().optional()
           })
         ).describe("One result per item, in order")
@@ -18365,7 +18425,7 @@ function registerSearchMediaTool(server) {
     "clipform_search_media",
     {
       title: "Search Media",
-      description: `Search images or stock video clips. Pass one query or many (max 10) - multiple queries run in one call instead of separate tool calls. Use results to feed into clipform_generate_video for narrated slideshow videos, or upload directly as still images via clipform_upload_node_media. All results are pre-cleared for commercial use. Results include a description (alt text where the provider has it) - use it to pick visually distinct images.
+      description: `Search images or stock video clips. Pass one query or many (max 10) - multiple queries run in one call instead of separate tool calls. Use results to feed into clipform_generate_video for narrated slideshow videos, or upload directly as still images via clipform_upload_media_asset then clipform_attach_node_media. All results are pre-cleared for commercial use. Results include a description (alt text where the provider has it) - use it to pick visually distinct images.
 
 Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count: 3 }] } returns portrait images for both.`,
       inputSchema: {
@@ -18456,6 +18516,11 @@ Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count:
   );
 }
 
+// src/lib/render-routing.ts
+var RENDER_ROUTING_RULE = `Choosing a render tool: for a recognisable form/quiz beat (guess-the-city, this-or-that, mystery reveal, multiple choice, photo montage...) reach for a video template first (clipform_list_video_templates + clipform_render_video_template) - it is a one-call recipe. Use clipform_generate_video for a narrated or audio-synced media montage (images/clips timed to a voice track). Use clipform_render_composition only when neither fits and you need a custom layer stack.`;
+var MONTAGE_NARRATION_RULE = `Montage disambiguation: choose clipform_generate_video when the montage is narrated or synced to an audio track; choose the slideshow video template when it is silent (motion + transitions only, no voice-over).`;
+var RENDER_ATTACH_RULE = `A render for a form node is not done until it is attached to that node. Pass node_id (and form_id) so the completed render attaches itself automatically - do not poll clipform_check_render to completion or manually chain clipform_upload_media_asset + clipform_attach_node_media; fire the render and move on.`;
+
 // ../../node_modules/.pnpm/uuid@11.1.1/node_modules/uuid/dist/esm/stringify.js
 var byteToHex = [];
 for (let i = 0; i < 256; ++i) {
@@ -18512,7 +18577,11 @@ var jobs = /* @__PURE__ */ new Map();
 var MAX_AGE_MS = 30 * 60 * 1e3;
 var RENDER_TIMING = {
   expectedRange: "15-120 seconds",
-  pollDelay: "~15 seconds"
+  pollDelay: "~15 seconds",
+  /** Rounder phrasing for chat/email ETA acks (#1964) - not exact enough for
+   *  a poll instruction like the two above, but right for "still rendering,
+   *  you'll hear back in..." copy. Never hardcode minutes in api code. */
+  etaPhrase: "a couple of minutes"
 };
 function createJob(tool) {
   const job = {
@@ -18524,11 +18593,12 @@ function createJob(tool) {
   jobs.set(job.id, job);
   return job;
 }
-function completeJob(id, result) {
+function completeJob(id, result, attach) {
   const job = jobs.get(id);
   if (job) {
     job.status = "complete";
     job.result = result;
+    if (attach) job.attach = attach;
   }
 }
 function failJob(id, error2) {
@@ -18548,14 +18618,133 @@ function pruneJobs() {
   }
 }
 
+// src/lib/auto-attach.ts
+async function createRenderPlaceholder(input) {
+  try {
+    const me = await callApi("/me", { method: "GET" });
+    if (!me.ok) return void 0;
+    const workspaceId = me.data?.workspace?.id;
+    if (!workspaceId) return void 0;
+    const created = await callApi(`/workspaces/${workspaceId}/media`, {
+      method: "POST",
+      body: { media_type: input.mediaType, media_source: "uploaded", pending: true }
+    });
+    if (!created.ok) return void 0;
+    const assetId = created.data?.media_asset_id;
+    if (!assetId) return void 0;
+    const attached = await callApi(`/forms/${input.formId}/nodes/${input.nodeId}/media/attach`, {
+      method: "POST",
+      body: { media_asset_id: assetId }
+    });
+    if (!attached.ok) return void 0;
+    await callApi(`/forms/${input.formId}/nodes/${input.nodeId}/media`, {
+      method: "PATCH",
+      body: { fit_media: true, show_captions: true }
+    }).catch(() => void 0);
+    return { workspaceId, assetId };
+  } catch {
+    return void 0;
+  }
+}
+async function failPlaceholder(placeholder, error2) {
+  try {
+    await callApi(`/workspaces/${placeholder.workspaceId}/media/${placeholder.assetId}/complete`, {
+      method: "POST",
+      body: { error: error2 }
+    });
+  } catch {
+  }
+}
+async function autoAttachRender(input) {
+  if (input.placeholder) {
+    const completed = await completeViaPlaceholder(input.placeholder, input);
+    if (completed) return completed;
+  }
+  return legacyAutoAttach(input);
+}
+async function completeViaPlaceholder(placeholder, input) {
+  try {
+    const body = { url: input.publicUrl };
+    if (input.captions?.length) body.captions = input.captions;
+    const completed = await callApi(`/workspaces/${placeholder.workspaceId}/media/${placeholder.assetId}/complete`, {
+      method: "POST",
+      body
+    });
+    if (!completed.ok) return void 0;
+    let republished = false;
+    const form = await callApi(`/forms/${input.formId}`, { method: "GET" });
+    if (form.ok && form.data?.is_live === true) {
+      const republish = await callApi(`/forms/${input.formId}`, { method: "PATCH", body: { is_live: true } });
+      republished = republish.ok;
+    }
+    return { attached: true, media_asset_id: placeholder.assetId, republished };
+  } catch {
+    return void 0;
+  }
+}
+async function legacyAutoAttach(input) {
+  try {
+    const me = await callApi("/me", { method: "GET" });
+    if (!me.ok) return { attached: false, error: `Unable to determine workspace: ${me.error}` };
+    const workspaceId = me.data?.workspace?.id;
+    if (!workspaceId) return { attached: false, error: "No workspace available for auto-attach." };
+    const createBody = {
+      media_type: input.mediaType,
+      media_source: "uploaded",
+      url: input.publicUrl
+    };
+    if (input.captions?.length) createBody.captions = input.captions;
+    const created = await callApi(`/workspaces/${workspaceId}/media`, { method: "POST", body: createBody });
+    if (!created.ok) return { attached: false, error: `Failed to create media asset: ${created.error}` };
+    const mediaAssetId = created.data?.media_asset_id;
+    if (!mediaAssetId) return { attached: false, error: "Media asset creation did not return an id." };
+    const attached = await callApi(`/forms/${input.formId}/nodes/${input.nodeId}/media/attach`, {
+      method: "POST",
+      body: { media_asset_id: mediaAssetId }
+    });
+    if (!attached.ok) {
+      return { attached: false, media_asset_id: mediaAssetId, error: `Failed to attach to node: ${attached.error}` };
+    }
+    await callApi(`/forms/${input.formId}/nodes/${input.nodeId}/media`, {
+      method: "PATCH",
+      body: { fit_media: true, show_captions: true }
+    }).catch(() => void 0);
+    let republished = false;
+    const form = await callApi(`/forms/${input.formId}`, { method: "GET" });
+    if (form.ok && form.data?.is_live === true) {
+      const republish = await callApi(`/forms/${input.formId}`, { method: "PATCH", body: { is_live: true } });
+      republished = republish.ok;
+    }
+    return { attached: true, media_asset_id: mediaAssetId, republished };
+  } catch (err) {
+    return { attached: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function attachStructuredFields(attach) {
+  if (!attach) return {};
+  return {
+    attached: attach.attached,
+    ...attach.media_asset_id ? { media_asset_id: attach.media_asset_id } : {},
+    ...attach.republished !== void 0 ? { republished: attach.republished } : {},
+    ...attach.error ? { attach_error: attach.error } : {}
+  };
+}
+function attachSummaryLine(nodeId, attach) {
+  return attach.attached ? `Attached to node ${nodeId}${attach.republished ? " and republished." : "."}` : `Auto-attach to node ${nodeId} failed: ${attach.error}. Attach manually via clipform_upload_media_asset then clipform_attach_node_media.`;
+}
+
 // src/tools/render-composition.ts
 var RenderItemSchema = external_exports.object({
   compositionId: external_exports.string().describe("The composition ID (see clipform_list_compositions)"),
   outputFormat: external_exports.enum(["mp4", "png"]).default("mp4").describe("Output format (default: mp4)"),
-  inputProps: external_exports.record(external_exports.unknown()).optional().describe("Props matching the composition's schema - validated strictly")
+  inputProps: external_exports.record(external_exports.unknown()).optional().describe("Props matching the composition's schema - validated strictly"),
+  node_id: external_exports.string().optional().describe("Form node to attach this item's render to automatically once it completes. Requires the batch's top-level form_id."),
+  captions: external_exports.array(CaptionSchema).optional().describe("Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set.")
 });
-function fireRender(item) {
+function fireRender(item, formId) {
   const job = createJob("clipform_render_composition");
+  const mediaType = item.outputFormat === "png" ? "still" : "video";
+  const placeholderPromise = item.node_id && formId ? createRenderPlaceholder({ formId, nodeId: item.node_id, mediaType }) : Promise.resolve(void 0);
   callApi("/internal/render", {
     timeoutMs: 3e5,
     // local renders pay a cold webpack bundle; Lambda is fast but bursty
@@ -18564,10 +18753,39 @@ function fireRender(item) {
       outputFormat: item.outputFormat,
       inputProps: item.inputProps ?? {}
     }
-  }).then((r) => {
-    if (r.ok) completeJob(job.id, r.data);
-    else failJob(job.id, r.error);
-  }).catch((err) => failJob(job.id, err instanceof Error ? err.message : String(err)));
+  }).then(async (r) => {
+    if (!r.ok) {
+      failJob(job.id, r.error);
+      const placeholder = await placeholderPromise;
+      if (placeholder) await failPlaceholder(placeholder, r.error);
+      return;
+    }
+    let attach;
+    if (item.node_id && formId) {
+      const publicUrl = r.data.public_url;
+      const placeholder = await placeholderPromise;
+      if (publicUrl) {
+        attach = await autoAttachRender({
+          formId,
+          nodeId: item.node_id,
+          publicUrl,
+          mediaType,
+          captions: item.captions,
+          placeholder
+        });
+      } else {
+        const message = "Render completed without a public_url; nothing to attach.";
+        attach = { attached: false, error: message };
+        if (placeholder) await failPlaceholder(placeholder, message);
+      }
+    }
+    completeJob(job.id, r.data, attach);
+  }).catch(async (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    failJob(job.id, message);
+    const placeholder = await placeholderPromise;
+    if (placeholder) await failPlaceholder(placeholder, message);
+  });
   return job;
 }
 function registerRenderCompositionTool(server) {
@@ -18579,44 +18797,60 @@ function registerRenderCompositionTool(server) {
 
 For narrated Ken Burns slideshows from images, use clipform_generate_video instead. Output formats: mp4 (H.264, best for social media) or png (single frame). Returns a public URL when complete.
 
-For multi-render builds (e.g. one clip per quiz question), pass everything in ONE call via items (max 10): all renders fire in parallel and you get one job ID each - then collect the URLs in a single clipform_check_render call with job_ids. Single render: pass compositionId/inputProps at the top level (wait: true blocks and returns the URL; wait: false returns a job ID).`,
+For multi-render builds (e.g. one clip per quiz question), pass everything in ONE call via items (max 10): all renders fire in parallel and you get one job ID each - then collect the URLs in a single clipform_check_render call with job_ids. Single render: pass compositionId/inputProps at the top level (wait: true blocks and returns the URL; wait: false returns a job ID).
+
+${RENDER_ROUTING_RULE}
+${RENDER_ATTACH_RULE} In batch mode, set node_id per item (see items) and form_id once at the top level.`,
       inputSchema: {
         compositionId: external_exports.string().optional().describe(`Single render: the composition ID. Call clipform_list_compositions to see available options (e.g. ${EXPOSED_COMPOSITIONS.map((id) => `'${id}'`).join(", ")}). Use items instead for multiple renders.`),
         outputFormat: external_exports.enum(["mp4", "png"]).default("mp4").describe("Single render: output format (default: mp4)"),
         inputProps: external_exports.record(external_exports.unknown()).optional().describe("Single render: props object matching the composition's schema from clipform_list_compositions. Validated STRICTLY - unknown or missing props fail with the schema in the error, nothing renders silently with defaults. For map compositions (Map), wide shots (camera.zoom < 9) may round lat/lng to 1 decimal place to improve cache hit rates; close shots and pin drops should keep full precision \u2014 the pin lands exactly on `target`."),
         wait: external_exports.boolean().optional().default(true).describe("Single render only: true (default) blocks until the render is ready and returns its URL; false returns a job ID for clipform_check_render. Batch items always run fire-and-poll."),
-        items: external_exports.array(RenderItemSchema).min(1).max(10).optional().describe("Batch mode: multiple renders in one call. All fire in parallel; returns one job ID per item - collect with clipform_check_render (job_ids). Use this whenever rendering more than one clip.")
+        items: external_exports.array(RenderItemSchema).min(1).max(10).optional().describe("Batch mode: multiple renders in one call. All fire in parallel; returns one job ID per item - collect with clipform_check_render (job_ids). Use this whenever rendering more than one clip."),
+        node_id: external_exports.string().optional().describe("Single render only: form node to attach this render to automatically once it completes. Requires form_id. For batch mode, set node_id per item instead."),
+        form_id: external_exports.string().uuid().optional().describe("The form UUID - required when node_id is set (single render) or any item sets node_id (batch)."),
+        captions: external_exports.array(CaptionSchema).optional().describe("Single render only: word-level captions from clipform_generate_tts, carried onto the attached media asset. Only used when node_id is set. For batch mode, set captions per item instead.")
       },
       outputSchema: {
         jobs: external_exports.array(
           external_exports.object({
             status: external_exports.enum(["rendering", "complete"]),
             job_id: external_exports.string().optional().describe("Present when status is 'rendering' - pass to check_render"),
-            public_url: external_exports.string().optional().describe("Present when status is 'complete' - attach via upload_node_media (fit_media: true)"),
+            public_url: external_exports.string().optional().describe("Present when status is 'complete' - attach via upload_media_asset then attach_node_media (fit_media: true), unless node_id was set (auto-attached)"),
             composition_id: external_exports.string().optional(),
-            output_format: external_exports.string().optional()
+            output_format: external_exports.string().optional(),
+            attached: external_exports.boolean().optional().describe("True when node_id was provided and the render was attached to the node automatically (present once the attach outcome is known)."),
+            media_asset_id: external_exports.string().optional().describe("The workspace media asset created from this render, when attached."),
+            republished: external_exports.boolean().optional().describe("True when the form was live and was republished to include this media."),
+            attach_error: external_exports.string().optional().describe("Present when node_id was provided but auto-attach failed - the render itself still succeeded.")
           })
         ).describe("One entry per render (single or batch)")
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
     },
-    async ({ compositionId, outputFormat, inputProps, wait, items }) => {
+    async ({ compositionId, outputFormat, inputProps, wait, items, node_id, form_id, captions }) => {
       if (items?.length && compositionId) {
         return errorResult("Pass EITHER items (batch) OR compositionId (single render), not both.");
       }
       if (!items?.length && !compositionId) {
         return errorResult("Pass compositionId for a single render, or items for a batch.");
       }
+      if (node_id && !form_id) {
+        return errorResult("form_id is required when node_id is set.");
+      }
+      if (items?.some((i) => i.node_id) && !form_id) {
+        return errorResult("form_id is required when any item sets node_id.");
+      }
       const unknown2 = (items ?? [{ compositionId, outputFormat, inputProps }]).map((i) => i.compositionId).filter((id) => !EXPOSED_COMPOSITIONS.includes(id));
       if (unknown2.length) {
         return errorResult(`Composition${unknown2.length > 1 ? "s" : ""} ${unknown2.map((id) => `"${id}"`).join(", ")} not available. Call clipform_list_compositions to see available options.`);
       }
       if (items?.length) {
-        const jobs2 = items.map((item) => ({ item, job: fireRender(item) }));
+        const jobs2 = items.map((item) => ({ item, job: fireRender(item, form_id) }));
         return structuredResult(
           [
             `${jobs2.length} renders started in parallel:`,
-            ...jobs2.map(({ item, job }) => `- ${item.compositionId} (${item.outputFormat}): job ${job.id}`),
+            ...jobs2.map(({ item, job }) => `- ${item.compositionId} (${item.outputFormat}): job ${job.id}${item.node_id ? ` -> attaches to node ${item.node_id}` : ""}`),
             ``,
             `Collect with ONE clipform_check_render call (job_ids: [...]). Renders typically take ${RENDER_TIMING.expectedRange}.`
           ].join("\n"),
@@ -18631,28 +18865,50 @@ For multi-render builds (e.g. one clip per quiz question), pass everything in ON
         );
       }
       if (wait === false) {
-        const job = fireRender({ compositionId, outputFormat, inputProps });
+        const job = fireRender({ compositionId, outputFormat, inputProps, node_id, captions }, form_id);
         return structuredResult(
           [
             `Render started (${compositionId}).`,
             `Job ID: ${job.id}`,
-            `Fire any remaining renders now, then poll clipform_check_render. Renders typically take ${RENDER_TIMING.expectedRange}.`
+            node_id ? `Will attach to node ${node_id} automatically once it completes - no need to poll to completion.` : `Fire any remaining renders now, then poll clipform_check_render. Renders typically take ${RENDER_TIMING.expectedRange}.`
           ].join("\n"),
           {
             jobs: [{ status: "rendering", job_id: job.id, composition_id: compositionId, output_format: outputFormat }]
           }
         );
       }
+      const mediaTypeSingle = outputFormat === "png" ? "still" : "video";
+      const placeholderPromise = node_id && form_id ? createRenderPlaceholder({ formId: form_id, nodeId: node_id, mediaType: mediaTypeSingle }) : Promise.resolve(void 0);
       const result = await callApi("/internal/render", {
         timeoutMs: 3e5,
         body: { compositionId, outputFormat, inputProps: inputProps ?? {} }
       });
-      if (!result.ok) return errorResult(result.error);
+      if (!result.ok) {
+        const placeholder = await placeholderPromise;
+        if (placeholder) await failPlaceholder(placeholder, result.error);
+        return errorResult(result.error);
+      }
       const data = result.data;
+      let attach;
+      if (node_id && form_id) {
+        const placeholder = await placeholderPromise;
+        if (data.public_url) {
+          attach = await autoAttachRender({
+            formId: form_id,
+            nodeId: node_id,
+            publicUrl: data.public_url,
+            mediaType: mediaTypeSingle,
+            captions,
+            placeholder
+          });
+        } else if (placeholder) {
+          await failPlaceholder(placeholder, "Render completed without a public_url; nothing to attach.");
+        }
+      }
       return structuredResult(
         [
           `Render complete. Public URL: ${data.public_url}`,
-          `Attach via clipform_upload_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
+          attach ? attachSummaryLine(node_id, attach) : `Attach via clipform_upload_media_asset then clipform_attach_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
         ].join("\n"),
         {
           jobs: [
@@ -18660,7 +18916,8 @@ For multi-render builds (e.g. one clip per quiz question), pass everything in ON
               status: "complete",
               ...data.public_url ? { public_url: data.public_url } : {},
               composition_id: compositionId,
-              output_format: outputFormat
+              output_format: outputFormat,
+              ...attachStructuredFields(attach)
             }
           ]
         }
@@ -18818,6 +19075,182 @@ function registerListCompositionsTool(server) {
   );
 }
 
+// src/tools/list-video-templates.ts
+function registerListVideoTemplatesTool(server) {
+  server.registerTool(
+    "clipform_list_video_templates",
+    {
+      title: "List Video Templates",
+      description: `Browse available video templates - curated Scene arrangements (bed + overlay + sane defaults) that render through the Scene composition from a small controls object. Call this before clipform_render_video_template to see template names and their exposed controls. For a fully custom layer stack, assemble Scene layers directly via clipform_render_composition instead.`,
+      inputSchema: {},
+      outputSchema: {
+        templates: external_exports.array(
+          external_exports.object({
+            name: external_exports.string(),
+            tier: external_exports.string(),
+            description: external_exports.string(),
+            keywords: external_exports.array(external_exports.string()).describe("Natural-language phrases a user's intent might match against this template"),
+            controls: external_exports.array(external_exports.string()).describe("Control names, '?'-suffixed when optional"),
+            exampleControls: external_exports.record(external_exports.unknown()).optional().describe("A worked, ready-to-render controls object for this template - copy and adapt it")
+          })
+        ).describe("Available video templates - pass a name + controls to clipform_render_video_template")
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    async () => {
+      const result = await callApi("/internal/video-templates", { method: "GET" });
+      if (!result.ok) {
+        if (result.status === 0 || result.status === 404) {
+          return errorResult("Video templates are not available (API server may not be running). Start the API with 'npm run dev --workspace=apps/api'.");
+        }
+        return errorResult(result.error);
+      }
+      const templates = result.data.templates ?? [];
+      if (!templates.length) {
+        return structuredResult("No video templates found.", { templates: [] });
+      }
+      const lines = [`Available video templates (${templates.length}):
+`];
+      for (const t of templates) {
+        lines.push(`- **${t.name}** - ${t.description}`);
+        lines.push(`  use when: ${t.keywords.join(", ")}`);
+        lines.push(`  controls: ${t.controls.join(", ")}`);
+        if (t.exampleControls) {
+          lines.push(`  example: ${JSON.stringify(t.exampleControls)}`);
+        }
+      }
+      lines.push("");
+      lines.push("Match the user's intent against each template's description/use-when keywords before picking one. Use clipform_render_video_template with a template name + controls to render (renders through Scene).");
+      return structuredResult(lines.join("\n"), {
+        templates: templates.map((t) => ({
+          name: t.name,
+          tier: t.tier,
+          description: t.description,
+          keywords: t.keywords,
+          controls: t.controls,
+          ...t.exampleControls ? { exampleControls: t.exampleControls } : {}
+        }))
+      });
+    }
+  );
+}
+
+// src/tools/render-video-template.ts
+function registerRenderVideoTemplateTool(server) {
+  server.registerTool(
+    "clipform_render_video_template",
+    {
+      title: "Render Video Template",
+      description: `Render a curated video template (a pre-arranged Scene: bed + overlay + sane defaults) to MP4 or PNG from a small controls object, instead of hand-assembling Scene layers. Call clipform_list_video_templates first for available template names and their controls. Renders through the Scene composition under the hood.
+
+${RENDER_ROUTING_RULE}
+${RENDER_ATTACH_RULE}`,
+      inputSchema: {
+        template: external_exports.string().describe("Video template name (see clipform_list_video_templates)."),
+        controls: external_exports.record(external_exports.unknown()).describe("Template-specific controls (see clipform_list_video_templates for the exposed control surface)."),
+        outputFormat: external_exports.enum(["mp4", "png"]).default("mp4").describe("Output format (default: mp4)"),
+        wait: external_exports.boolean().optional().default(true).describe("true (default) blocks until the render is ready and returns its URL; false returns a job ID for clipform_check_render."),
+        node_id: external_exports.string().optional().describe("Form node to attach this render to automatically once it completes - skips the manual clipform_upload_media_asset + clipform_attach_node_media steps and republishes the form if it's currently live. Requires form_id."),
+        form_id: external_exports.string().uuid().optional().describe("The form UUID (required when node_id is set)."),
+        captions: external_exports.array(CaptionSchema).optional().describe("Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set.")
+      },
+      outputSchema: {
+        status: external_exports.enum(["rendering", "complete"]),
+        job_id: external_exports.string().optional().describe("Present when status is 'rendering' - pass to clipform_check_render"),
+        public_url: external_exports.string().optional().describe("Present when status is 'complete' - attach via upload_media_asset then attach_node_media (fit_media: true), unless node_id was set (auto-attached)"),
+        template: external_exports.string().optional(),
+        output_format: external_exports.string().optional(),
+        attached: external_exports.boolean().optional().describe("True when node_id was provided and the render was attached to the node automatically (present once the attach outcome is known)."),
+        media_asset_id: external_exports.string().optional().describe("The workspace media asset created from this render, when attached."),
+        republished: external_exports.boolean().optional().describe("True when the form was live and was republished to include this media."),
+        attach_error: external_exports.string().optional().describe("Present when node_id was provided but auto-attach failed - the render itself still succeeded.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    async ({ template, controls, outputFormat, wait, node_id, form_id, captions }) => {
+      if (node_id && !form_id) {
+        return errorResult("form_id is required when node_id is set.");
+      }
+      const renderBody = { template, controls: controls ?? {}, outputFormat };
+      const mediaType = outputFormat === "png" ? "still" : "video";
+      if (wait === false) {
+        const job = createJob("clipform_render_video_template");
+        const placeholderPromise2 = node_id && form_id ? createRenderPlaceholder({ formId: form_id, nodeId: node_id, mediaType }) : Promise.resolve(void 0);
+        callApi("/internal/render-template", {
+          timeoutMs: 3e5,
+          body: renderBody
+        }).then(async (r) => {
+          if (!r.ok) {
+            failJob(job.id, r.error);
+            const placeholder = await placeholderPromise2;
+            if (placeholder) await failPlaceholder(placeholder, r.error);
+            return;
+          }
+          let attach2;
+          if (node_id && form_id) {
+            const publicUrl = r.data.public_url;
+            const placeholder = await placeholderPromise2;
+            if (publicUrl) {
+              attach2 = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl, mediaType, captions, placeholder });
+            } else {
+              const message = "Render completed without a public_url; nothing to attach.";
+              attach2 = { attached: false, error: message };
+              if (placeholder) await failPlaceholder(placeholder, message);
+            }
+          }
+          completeJob(job.id, r.data, attach2);
+        }).catch(async (err) => {
+          const message = err instanceof Error ? err.message : String(err);
+          failJob(job.id, message);
+          const placeholder = await placeholderPromise2;
+          if (placeholder) await failPlaceholder(placeholder, message);
+        });
+        return structuredResult(
+          [
+            `Render started (template: ${template}).`,
+            `Job ID: ${job.id}`,
+            node_id ? `Will attach to node ${node_id} automatically once it completes - no need to poll to completion.` : `Poll clipform_check_render. Renders typically take ${RENDER_TIMING.expectedRange}.`
+          ].join("\n"),
+          { status: "rendering", job_id: job.id, template, output_format: outputFormat }
+        );
+      }
+      const placeholderPromise = node_id && form_id ? createRenderPlaceholder({ formId: form_id, nodeId: node_id, mediaType }) : Promise.resolve(void 0);
+      const result = await callApi("/internal/render-template", {
+        timeoutMs: 3e5,
+        body: renderBody
+      });
+      if (!result.ok) {
+        const placeholder = await placeholderPromise;
+        if (placeholder) await failPlaceholder(placeholder, result.error);
+        return errorResult(result.error);
+      }
+      const data = result.data;
+      let attach;
+      if (node_id && form_id) {
+        const placeholder = await placeholderPromise;
+        if (data.public_url) {
+          attach = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl: data.public_url, mediaType, captions, placeholder });
+        } else if (placeholder) {
+          await failPlaceholder(placeholder, "Render completed without a public_url; nothing to attach.");
+        }
+      }
+      return structuredResult(
+        [
+          `Render complete. Public URL: ${data.public_url}`,
+          attach ? attachSummaryLine(node_id, attach) : `Attach via clipform_upload_media_asset then clipform_attach_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
+        ].join("\n"),
+        {
+          status: "complete",
+          ...data.public_url ? { public_url: data.public_url } : {},
+          template,
+          output_format: outputFormat,
+          ...attachStructuredFields(attach)
+        }
+      );
+    }
+  );
+}
+
 // src/tools/list-assets.ts
 function registerListAssetsTool(server) {
   server.registerTool(
@@ -18887,7 +19320,11 @@ function registerGenerateVideoTool(server) {
 
 Items: type "image" (Ken Burns motion) or "video" (cover-cropped, muted by default). Duration matches audio_url or set duration_seconds explicitly.
 
-For multi-question builds, pass wait: false on every render: each call returns a job ID immediately, so all renders run in parallel - then collect URLs with clipform_check_render. Sequential waiting renders take ${RENDER_TIMING.expectedRange} EACH.`,
+For multi-question builds, pass wait: false on every render: each call returns a job ID immediately, so all renders run in parallel - then collect URLs with clipform_check_render. Sequential waiting renders take ${RENDER_TIMING.expectedRange} EACH.
+
+${RENDER_ROUTING_RULE}
+${MONTAGE_NARRATION_RULE}
+${RENDER_ATTACH_RULE}`,
       inputSchema: {
         items: external_exports.array(
           external_exports.object({
@@ -18921,17 +19358,27 @@ For multi-question builds, pass wait: false on every render: each call returns a
           contrast: external_exports.number().positive().optional().describe("Contrast boost before mapping (default 1.1)")
         }).optional().describe("Two-tone editorial recolour on image items - desaturates then maps to a shadow->highlight palette. Pair with a halftone texture for a screen-print poster look."),
         background_color: external_exports.string().optional().describe("Background color (default '#000')"),
-        wait: external_exports.boolean().optional().default(true).describe("true (default) blocks until the video is ready and returns its URL. false returns a job ID immediately - fire all renders first, then poll clipform_check_render. Use false whenever rendering more than one video.")
+        wait: external_exports.boolean().optional().default(true).describe("true (default) blocks until the video is ready and returns its URL. false returns a job ID immediately - fire all renders first, then poll clipform_check_render. Use false whenever rendering more than one video."),
+        node_id: external_exports.string().optional().describe("Form node to attach this render to automatically once it completes - skips the manual clipform_upload_media_asset + clipform_attach_node_media steps and republishes the form if it's currently live. Requires form_id."),
+        form_id: external_exports.string().uuid().optional().describe("The form UUID (required when node_id is set)."),
+        captions: external_exports.array(CaptionSchema).optional().describe("Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set.")
       },
       outputSchema: {
         status: external_exports.enum(["rendering", "complete"]).describe("'rendering' when wait:false (poll check_render); 'complete' with a public_url when wait:true"),
         job_id: external_exports.string().optional().describe("Present when status is 'rendering' - pass to check_render"),
-        public_url: external_exports.string().optional().describe("Present when status is 'complete' - attach via upload_node_media (fit_media: true)"),
-        duration_seconds: external_exports.number().optional()
+        public_url: external_exports.string().optional().describe("Present when status is 'complete' - attach via upload_media_asset then attach_node_media (fit_media: true), unless node_id was set (auto-attached)"),
+        duration_seconds: external_exports.number().optional(),
+        attached: external_exports.boolean().optional().describe("True when node_id was provided and the render was attached to the node automatically (present once the attach outcome is known)."),
+        media_asset_id: external_exports.string().optional().describe("The workspace media asset created from this render, when attached."),
+        republished: external_exports.boolean().optional().describe("True when the form was live and was republished to include this media."),
+        attach_error: external_exports.string().optional().describe("Present when node_id was provided but auto-attach failed - the render itself still succeeded.")
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
     },
-    async ({ items, audio_url, background_audio_url, background_audio_volume, duration_seconds, random_effects, transition, style_preset, texture, duotone, background_color, wait }) => {
+    async ({ items, audio_url, background_audio_url, background_audio_volume, duration_seconds, random_effects, transition, style_preset, texture, duotone, background_color, wait, node_id, form_id, captions }) => {
+      if (node_id && !form_id) {
+        return errorResult("form_id is required when node_id is set.");
+      }
       const workspace_id = getMcpAuth()?.workspace_id;
       const default_style = style_preset || texture || duotone ? {
         ...style_preset ? { preset: style_preset } : {},
@@ -18956,33 +19403,71 @@ For multi-question builds, pass wait: false on every render: each call returns a
       });
       if (wait === false) {
         const job = createJob("clipform_generate_video");
-        apiCall().then((r) => {
-          if (r.ok) completeJob(job.id, r.data);
-          else failJob(job.id, r.error);
-        }).catch((err) => failJob(job.id, err instanceof Error ? err.message : String(err)));
+        const placeholderPromise2 = node_id && form_id ? createRenderPlaceholder({ formId: form_id, nodeId: node_id, mediaType: "video" }) : Promise.resolve(void 0);
+        apiCall().then(async (r) => {
+          if (!r.ok) {
+            failJob(job.id, r.error);
+            const placeholder = await placeholderPromise2;
+            if (placeholder) await failPlaceholder(placeholder, r.error);
+            return;
+          }
+          let attach2;
+          if (node_id && form_id) {
+            const publicUrl = r.data.public_url;
+            const placeholder = await placeholderPromise2;
+            if (publicUrl) {
+              attach2 = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl, mediaType: "video", captions, placeholder });
+            } else {
+              const message = "Render completed without a public_url; nothing to attach.";
+              attach2 = { attached: false, error: message };
+              if (placeholder) await failPlaceholder(placeholder, message);
+            }
+          }
+          completeJob(job.id, r.data, attach2);
+        }).catch(async (err) => {
+          const message = err instanceof Error ? err.message : String(err);
+          failJob(job.id, message);
+          const placeholder = await placeholderPromise2;
+          if (placeholder) await failPlaceholder(placeholder, message);
+        });
         return structuredResult(
           [
             `Render started (${items.length} item${items.length > 1 ? "s" : ""}).`,
             `Job ID: ${job.id}`,
-            `Fire any remaining renders now, then poll clipform_check_render. Renders typically take ${RENDER_TIMING.expectedRange}.`
+            node_id ? `Will attach to node ${node_id} automatically once it completes - no need to poll to completion.` : `Fire any remaining renders now, then poll clipform_check_render. Renders typically take ${RENDER_TIMING.expectedRange}.`
           ].join("\n"),
           { status: "rendering", job_id: job.id }
         );
       }
+      const placeholderPromise = node_id && form_id ? createRenderPlaceholder({ formId: form_id, nodeId: node_id, mediaType: "video" }) : Promise.resolve(void 0);
       const result = await apiCall();
-      if (!result.ok) return errorResult(result.error);
+      if (!result.ok) {
+        const placeholder = await placeholderPromise;
+        if (placeholder) await failPlaceholder(placeholder, result.error);
+        return errorResult(result.error);
+      }
       const data = result.data;
+      let attach;
+      if (node_id && form_id) {
+        const placeholder = await placeholderPromise;
+        if (data.public_url) {
+          attach = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl: data.public_url, mediaType: "video", captions, placeholder });
+        } else if (placeholder) {
+          await failPlaceholder(placeholder, "Render completed without a public_url; nothing to attach.");
+        }
+      }
       return structuredResult(
         [
           `Video rendered (${items.length} item${items.length > 1 ? "s" : ""}).`,
           `Public URL: ${data.public_url}`,
           data.duration_seconds ? `Duration: ${data.duration_seconds}s` : "",
-          `Attach via clipform_upload_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
+          attach ? attachSummaryLine(node_id, attach) : `Attach via clipform_upload_media_asset then clipform_attach_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
         ].filter(Boolean).join("\n"),
         {
           status: "complete",
           ...data.public_url ? { public_url: data.public_url } : {},
-          ...typeof data.duration_seconds === "number" ? { duration_seconds: data.duration_seconds } : {}
+          ...typeof data.duration_seconds === "number" ? { duration_seconds: data.duration_seconds } : {},
+          ...attachStructuredFields(attach)
         }
       );
     }
@@ -19003,7 +19488,8 @@ function projectJob(id, job) {
     job_id: id,
     status: "complete",
     ...data?.public_url ? { public_url: data.public_url } : {},
-    ...typeof data?.duration_seconds === "number" ? { duration_seconds: data.duration_seconds } : {}
+    ...typeof data?.duration_seconds === "number" ? { duration_seconds: data.duration_seconds } : {},
+    ...attachStructuredFields(job.attach)
   };
 }
 var LOST_JOB_RECOVERY = [
@@ -19028,16 +19514,17 @@ function describeJob(id, job) {
     ...data.public_url ? [data.public_url] : [],
     ...data.duration_seconds ? [`${data.duration_seconds}s`] : []
   ].join(" | ");
-  return { line: `- ${id}: complete${extras ? ` - ${extras}` : ""}`, done: true, failed: false };
+  const attachNote = job.attach ? job.attach.attached ? ` (attached${job.attach.republished ? " + republished" : ""})` : ` (attach FAILED: ${job.attach.error})` : "";
+  return { line: `- ${id}: complete${extras ? ` - ${extras}` : ""}${attachNote}`, done: true, failed: false };
 }
 function registerCheckRenderTool(server) {
   server.registerTool(
     "clipform_check_render",
     {
       title: "Check Render Status",
-      description: `Check the status of render jobs started by clipform_generate_video or clipform_render_composition.
+      description: `Check the status of render jobs started by clipform_generate_video, clipform_render_video_template, or clipform_render_composition.
 
-Pass job_ids to check a whole batch in ONE call - one line of status per job. Pass job_id for a single job. Returns the output URL for each completed render. Typical render time: 10-60 seconds.`,
+Pass job_ids to check a whole batch in ONE call - one line of status per job. Pass job_id for a single job. Returns the output URL for each completed render. Typical render time: 10-60 seconds. Attach is automatic when node_id was provided to the render tool - no need to poll to completion, and the attach outcome is reported here once known.`,
       inputSchema: {
         job_id: external_exports.string().uuid().optional().describe("A single job ID returned by the render tool"),
         job_ids: external_exports.array(external_exports.string().uuid()).min(1).max(20).optional().describe("Multiple job IDs - check the whole batch in one call instead of one call per job")
@@ -19050,9 +19537,13 @@ Pass job_ids to check a whole batch in ONE call - one line of status per job. Pa
             public_url: external_exports.string().optional(),
             duration_seconds: external_exports.number().optional(),
             elapsed_seconds: external_exports.number().optional(),
-            error: external_exports.string().optional()
+            error: external_exports.string().optional(),
+            attached: external_exports.boolean().optional().describe("True when the render's node_id was set and it attached to the node automatically."),
+            media_asset_id: external_exports.string().optional().describe("The workspace media asset created from this render, when attached."),
+            republished: external_exports.boolean().optional().describe("True when the form was live and was republished to include this media."),
+            attach_error: external_exports.string().optional().describe("Present when node_id was set but auto-attach failed - the render itself still succeeded.")
           })
-        ).describe("One entry per queried job; attach completed public_urls via upload_node_media")
+        ).describe("One entry per queried job; attach completed public_urls via upload_media_asset then attach_node_media unless already auto-attached")
       },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
@@ -19083,12 +19574,15 @@ Pass job_ids to check a whole batch in ONE call - one line of status per job. Pa
           return errorResult(`Render failed: ${job.error}`);
         }
         const data = job.result;
+        const attachLines = job.attach ? [
+          job.attach.attached ? `Attached to node automatically${job.attach.republished ? " and republished." : "."}` : `Auto-attach failed: ${job.attach.error}. Attach manually via clipform_upload_media_asset then clipform_attach_node_media.`
+        ] : [`Attach via clipform_upload_media_asset then clipform_attach_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`];
         return structuredResult(
           [
             `Render complete.`,
             ...data.public_url ? [`Public URL: ${data.public_url}`] : [],
             ...data.duration_seconds ? [`Duration: ${data.duration_seconds}s`] : [],
-            `Attach via clipform_upload_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
+            ...attachLines
           ].join("\n"),
           { jobs: [projectJob(ids[0], job)] }
         );
@@ -19100,7 +19594,7 @@ Pass job_ids to check a whole batch in ONE call - one line of status per job. Pa
         [
           `Render batch: ${results.length - pending}/${results.length} finished${pending ? ` - check again in ${RENDER_TIMING.pollDelay}` : ""}.`,
           ...results.map((r) => r.line),
-          ...pending === 0 ? [``, `Attach completed renders via clipform_upload_node_media with fit_media: true (composed 9:16 frames - contain, never crop).`] : [],
+          ...pending === 0 ? [``, `Attach any renders not already auto-attached (see above) via clipform_upload_media_asset then clipform_attach_node_media with fit_media: true (composed 9:16 frames - contain, never crop).`] : [],
           ...lost ? [``, LOST_JOB_RECOVERY] : []
         ].join("\n"),
         { jobs: ids.map((id) => projectJob(id, getJob(id))) }
@@ -19392,7 +19886,8 @@ function createServer(options) {
   registerAddNodeTool(server);
   registerUpdateNodeTool(server);
   registerDeleteNodeTool(server);
-  registerUploadNodeMediaTool(server);
+  registerUploadMediaAssetTool(server);
+  registerAttachNodeMediaTool(server);
   registerGetNodeMediaTool(server);
   registerDeleteNodeMediaTool(server);
   registerSetNodeLogicTool(server);
@@ -19405,6 +19900,8 @@ function createServer(options) {
   registerRenderCompositionTool(server);
   registerSearchMusicTool(server);
   registerListCompositionsTool(server);
+  registerListVideoTemplatesTool(server);
+  registerRenderVideoTemplateTool(server);
   registerListAssetsTool(server);
   registerCheckRenderTool(server);
   registerFetchBoundaryTool(server);
@@ -19417,6 +19914,7 @@ function createServer(options) {
 
 export {
   JSONRPCMessageSchema,
+  RENDER_TIMING,
   createServer
 };
-//# sourceMappingURL=chunk-3MTEM3VC.js.map
+//# sourceMappingURL=chunk-SI4C55U6.js.map