@clipform/mcp-server 1.47.1 → 2.0.0

package/dist/{chunk-JT7YWEQP.js → chunk-RX7V2UCM.js}

@@ -6,7 +6,7 @@ import {
   getWorkflowText,
   objectType,
   registerPrompts
-} from "./chunk-MV27JVSL.js";
+} from "./chunk-6U3CVTLZ.js";
 import {
   GUIDE_TYPES,
   QUIZ_VARIANTS,
@@ -14,7 +14,7 @@ import {
   getGuideUri,
   guideFallbackText,
   registerResources
-} from "./chunk-UH77CDNO.js";
+} from "./chunk-AP6UGWKC.js";
 import {
   ACTIVE_NODE_TYPES,
   BUSINESS,
@@ -23,18 +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-PJNOCHKR.js";
+} from "./chunk-GDUJLYR4.js";
 import {
   __commonJS,
   __export,
@@ -16987,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;
@@ -17038,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(", ")}` : "";
@@ -17072,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."),
@@ -17131,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!" }
   ]
 }`,
@@ -17149,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: {
@@ -17257,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}`
@@ -17269,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`;
@@ -17325,6 +17325,21 @@ function registerListFormsTool(server) {
         sort: external_exports.enum(["created_at", "updated_at"]).optional().describe("Sort field (default: created_at)"),
         order: external_exports.enum(["asc", "desc"]).optional().describe("Sort order (default: desc, newest first)")
       },
+      outputSchema: {
+        forms: external_exports.array(
+          external_exports.object({
+            id: external_exports.string(),
+            title: external_exports.string(),
+            share_id: external_exports.string(),
+            is_live: external_exports.boolean(),
+            has_unpublished_changes: external_exports.boolean(),
+            created_at: external_exports.string(),
+            updated_at: external_exports.string(),
+            tags: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), color: external_exports.string().nullable() }))
+          })
+        ).describe("Matching forms (empty if none)"),
+        next_cursor: external_exports.string().nullable().describe("Pass as cursor to fetch the next page, or null when no more")
+      },
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -17346,8 +17361,21 @@ function registerListFormsTool(server) {
         return errorResult(result.error);
       }
       const data = result.data;
+      const structured = {
+        forms: data.forms.map((f) => ({
+          id: f.id,
+          title: f.title,
+          share_id: f.share_id,
+          is_live: f.is_live,
+          has_unpublished_changes: f.has_unpublished_changes,
+          created_at: f.created_at,
+          updated_at: f.updated_at,
+          tags: f.tags.map((t) => ({ id: t.id, name: t.name, color: t.color }))
+        })),
+        next_cursor: data.next_cursor
+      };
       if (data.forms.length === 0) {
-        return textResult("No forms found matching the criteria.");
+        return structuredResult("No forms found matching the criteria.", structured);
       }
       const lines = [`Found ${data.forms.length} form(s):
 `];
@@ -17361,14 +17389,36 @@ function registerListFormsTool(server) {
           `More results available. Pass cursor: "${data.next_cursor}" to get the next page.`
         );
       }
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), structured);
     }
   );
 }
 
 // src/lib/format-form.ts
+function getFormNodes(data) {
+  return data.node ?? data.nodes ?? [];
+}
+function projectFormState(data) {
+  return {
+    form_id: String(data.form_id ?? ""),
+    title: String(data.title ?? ""),
+    is_live: Boolean(data.is_live),
+    has_unpublished_changes: Boolean(data.has_unpublished_changes),
+    nodes: getFormNodes(data).map((q) => {
+      const options = q.node_options ?? q.options;
+      return {
+        id: q.id,
+        type: q.type,
+        prompt: q.prompt ?? "",
+        required: Boolean(q.required),
+        ...q.config && Object.keys(q.config).length > 0 ? { config: q.config } : {},
+        ...options && options.length > 0 ? { options: options.map((o) => ({ id: o.id, content: o.content })) } : {}
+      };
+    })
+  };
+}
 function formatFormState(data) {
-  const nodes = data.node ?? data.nodes ?? [];
+  const nodes = getFormNodes(data);
   const lines = [
     `Form: ${data.title}`,
     `Form ID: ${data.form_id}`,
@@ -17408,6 +17458,22 @@ function registerGetFormTool(server) {
       inputSchema: {
         form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)")
       },
+      outputSchema: {
+        form_id: external_exports.string().describe("Form UUID"),
+        title: external_exports.string().describe("Form title"),
+        is_live: external_exports.boolean().describe("Whether the form is published"),
+        has_unpublished_changes: external_exports.boolean().describe("Live form has edits not yet republished"),
+        nodes: external_exports.array(
+          external_exports.object({
+            id: external_exports.string(),
+            type: external_exports.string(),
+            prompt: external_exports.string(),
+            required: external_exports.boolean(),
+            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 / attach_node_media")
+      },
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -17420,7 +17486,7 @@ function registerGetFormTool(server) {
       if (!result.ok) {
         return errorResult(result.error);
       }
-      return textResult(formatFormState(result.data));
+      return structuredResult(formatFormState(result.data), projectFormState(result.data));
     }
   );
 }
@@ -17597,6 +17663,10 @@ function registerAddNodeTool(server) {
           "Insert after this node ID. Omit to append before the end screen."
         )
       },
+      outputSchema: {
+        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: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -17615,8 +17685,10 @@ function registerAddNodeTool(server) {
       if (!result.ok) {
         return errorResult(result.error);
       }
-      return textResult(
-        `Node added. ID: ${result.data.node_id} | Type: ${node.type}`
+      const nodeId = result.data.node_id;
+      return structuredResult(
+        `Node added. ID: ${nodeId} | Type: ${node.type}`,
+        { node_id: nodeId, type: node.type }
       );
     }
   );
@@ -17629,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."
   )
@@ -17644,6 +17718,16 @@ function registerUpdateNodeTool(server) {
         form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)"),
         updates: external_exports.array(NodeUpdateSchema).min(1).max(20).describe("One or more node updates to apply")
       },
+      outputSchema: {
+        results: external_exports.array(
+          external_exports.object({
+            node_id: external_exports.string(),
+            ok: external_exports.boolean(),
+            warnings: external_exports.array(external_exports.string()).optional(),
+            error: external_exports.string().optional()
+          })
+        ).describe("One result per requested update, in order")
+      },
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -17653,6 +17737,7 @@ function registerUpdateNodeTool(server) {
     },
     async ({ form_id, updates }) => {
       const allLines = [];
+      const results = [];
       for (const { node_id, prompt, label, type, required: required2, config: config2, options } of updates) {
         const body = {};
         if (prompt !== void 0) body.prompt = prompt;
@@ -17667,6 +17752,7 @@ function registerUpdateNodeTool(server) {
         );
         if (!result.ok) {
           allLines.push(`Node ${node_id}: FAILED \u2014 ${result.error}`);
+          results.push({ node_id, ok: false, error: result.error });
           continue;
         }
         const changes = [];
@@ -17682,8 +17768,9 @@ function registerUpdateNodeTool(server) {
         if (warnings?.length) {
           for (const w of warnings) allLines.push(`Node ${node_id} warning: ${w}`);
         }
+        results.push({ node_id, ok: true, ...warnings?.length ? { warnings } : {} });
       }
-      return textResult(allLines.join("\n"));
+      return structuredResult(allLines.join("\n"), { results });
     }
   );
 }
@@ -17728,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."),
@@ -17748,21 +17833,31 @@ 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({
+            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")
       },
       annotations: {
         readOnlyHint: false,
@@ -17771,20 +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) {
-          lines.push(
-            "FAILED: no workspace in context - reconnect the MCP or set CLIPFORM_API_KEY so media can land in your library."
-          );
-          lines.push("");
-          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
@@ -17795,21 +17894,105 @@ 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({ media_type: item.media_type, stored: false, ok: false, error: created.error });
           continue;
         }
         const mediaAssetId = created.data.media_asset_id;
         if (!mediaAssetId) {
-          lines.push(`FAILED: upload did not return a media asset id (route ${String(created.data.route ?? "unknown")}).`);
+          const error2 = `upload did not return a media asset id (route ${String(created.data.route ?? "unknown")}).`;
+          lines.push(`FAILED: ${error2}`);
           lines.push("");
+          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, error: attached.error });
           continue;
         }
         const presentation = {};
@@ -17826,29 +18009,18 @@ When a public URL is provided, the media is fetched and stored automatically. On
           }
         }
         successCount++;
-        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"));
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { results });
     }
   );
 }
@@ -17864,6 +18036,14 @@ function registerGetNodeMediaTool(server) {
         form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)"),
         node_id: external_exports.string().describe("The node ID")
       },
+      outputSchema: {
+        media: external_exports.object({
+          media_type: external_exports.string(),
+          status: external_exports.string(),
+          duration: external_exports.number().optional(),
+          transcription_status: external_exports.string().nullable().optional()
+        }).nullable().describe("Attached media (null if the node has none)")
+      },
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -17880,15 +18060,22 @@ function registerGetNodeMediaTool(server) {
       }
       const media = result.data.media;
       if (!media) {
-        return textResult("No media attached to this node.");
+        return structuredResult("No media attached to this node.", { media: null });
       }
-      return textResult(
+      const projected = {
+        media_type: String(media.media_type),
+        status: String(media.status),
+        ...typeof media.duration === "number" ? { duration: media.duration } : {},
+        transcription_status: media.transcription_status == null ? null : String(media.transcription_status)
+      };
+      return structuredResult(
         [
           `Type: ${media.media_type}`,
           `Status: ${media.status}`,
           media.duration ? `Duration: ${media.duration}s` : "",
           `Transcription: ${media.transcription_status}`
-        ].filter(Boolean).join("\n")
+        ].filter(Boolean).join("\n"),
+        { media: projected }
       );
     }
   );
@@ -18042,6 +18229,20 @@ Returns: article title, source, author, date, URL, description, and image URL pe
         query: external_exports.string().describe("News search query (e.g. 'Iran war 2026', 'Australian Open final', 'UK election')"),
         count: external_exports.number().min(1).max(15).default(5).optional().describe("Max results per provider (default 5)")
       },
+      outputSchema: {
+        query: external_exports.string(),
+        articles: external_exports.array(
+          external_exports.object({
+            title: external_exports.string().optional(),
+            source: external_exports.string().optional(),
+            description: external_exports.string().optional(),
+            author: external_exports.string().optional(),
+            published_at: external_exports.string().optional(),
+            url: external_exports.string(),
+            image_url: external_exports.string().optional()
+          })
+        ).describe("Matching articles (empty if none)")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ query, count }) => {
@@ -18050,7 +18251,16 @@ Returns: article title, source, author, date, URL, description, and image URL pe
       });
       if (!result.ok) return errorResult(result.error);
       const results = result.data.results;
-      if (!results.length) return textResult(`No news articles found for "${query}".`);
+      if (!results.length) return structuredResult(`No news articles found for "${query}".`, { query, articles: [] });
+      const articles = results.map((article) => ({
+        ...article.title ? { title: article.title } : {},
+        ...article.source ? { source: article.source } : {},
+        ...article.description ? { description: article.description } : {},
+        ...article.author ? { author: article.author } : {},
+        ...article.publishedAt ? { published_at: article.publishedAt } : {},
+        url: article.url,
+        ...article.imageUrl ? { image_url: article.imageUrl } : {}
+      }));
       const lines = [`Found ${results.length} articles for "${query}":
 `];
       for (const article of results) {
@@ -18062,7 +18272,7 @@ Returns: article title, source, author, date, URL, description, and image URL pe
         if (article.imageUrl) lines.push(`  Image: ${article.imageUrl}`);
         lines.push("");
       }
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { query, articles });
     }
   );
 }
@@ -18118,6 +18328,12 @@ Supports any public YouTube video with captions enabled. Does NOT work for priva
 }
 
 // src/tools/generate-tts.ts
+var CaptionSchema2 = external_exports.object({
+  start: external_exports.number(),
+  end: external_exports.number(),
+  text: external_exports.string(),
+  words: external_exports.array(external_exports.object({ word: external_exports.string(), start: external_exports.number(), end: external_exports.number() })).optional()
+});
 var TtsItemSchema = external_exports.object({
   text: external_exports.string().min(1).max(5e3).describe("Narration text"),
   voice: external_exports.enum(["ryan", "sonia", "andrew", "ava", "guy"]).optional().default("ryan").describe("Voice: ryan (British male, clear/articulate), sonia (British female, warm/bright), andrew (American male, smooth/neutral), ava (American female, vibrant/friendly), guy (American male, deep/authoritative). Pick based on the form's topic and audience."),
@@ -18138,6 +18354,16 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
       inputSchema: {
         items: external_exports.array(TtsItemSchema).min(1).max(10).describe("One or more TTS items to generate")
       },
+      outputSchema: {
+        results: external_exports.array(
+          external_exports.object({
+            ok: external_exports.boolean(),
+            audio_url: external_exports.string().optional(),
+            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")
+      },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
     },
     async ({ items }) => {
@@ -18151,6 +18377,7 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
         )
       );
       const lines = [];
+      const structured = [];
       let successCount = 0;
       for (let i = 0; i < results.length; i++) {
         const r = results[i];
@@ -18167,11 +18394,17 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
             ...Array.isArray(c.words) ? { words: c.words.map((w) => ({ word: w.word, start: w.start, end: w.end })) } : {}
           }));
           lines.push(`Captions: ${JSON.stringify(captions)}`);
+          structured.push({
+            ok: true,
+            ...data.audioUrl ? { audio_url: String(data.audioUrl) } : {},
+            captions
+          });
         } else {
           const error2 = r.status === "rejected" ? r.reason?.message || String(r.reason) : r.value.error;
           const status = r.status === "fulfilled" ? r.value.status : 0;
           const hint = status === 500 || status === 0 ? " (transient - retrying may help)" : "";
           lines.push(`FAILED: ${error2}${hint}`);
+          structured.push({ ok: false, error: String(error2) });
         }
         lines.push("");
       }
@@ -18181,7 +18414,7 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
       }
       lines.push(`Pass the complete Captions JSON as the "captions" parameter when uploading.`);
       if (successCount === 0) return errorResult(lines.join("\n"));
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { results: structured });
     }
   );
 }
@@ -18192,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: {
@@ -18205,10 +18438,30 @@ Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count:
           })
         ).min(1).max(10).describe("One or more search queries to run")
       },
+      outputSchema: {
+        searches: external_exports.array(
+          external_exports.object({
+            query: external_exports.string(),
+            kind: external_exports.enum(["image", "video"]),
+            items: external_exports.array(
+              external_exports.object({
+                title: external_exports.string().optional(),
+                url: external_exports.string(),
+                width: external_exports.number().optional(),
+                height: external_exports.number().optional(),
+                duration: external_exports.number().optional(),
+                source: external_exports.string().optional(),
+                attribution: external_exports.string().optional()
+              })
+            )
+          })
+        ).describe("Results grouped by query (items empty if a query found nothing or failed)")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ queries }) => {
       const allLines = [];
+      const searches = [];
       for (const q of queries) {
         const { query, count, orientation } = q;
         const kind = q.kind ?? "image";
@@ -18218,16 +18471,32 @@ Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count:
         if (queries.length > 1) allLines.push(`--- "${query}" (${kind}) ---`);
         if (!result.ok) {
           allLines.push(`FAILED: ${result.error}`, "");
+          searches.push({ query, kind, items: [] });
           continue;
         }
         const results = result.data.results;
         if (!results.length) {
           allLines.push(`No ${kind}s found.`, "");
+          searches.push({ query, kind, items: [] });
           continue;
         }
+        const shown = results.slice(0, 10);
+        searches.push({
+          query,
+          kind,
+          items: shown.map((item) => ({
+            ...item.title ? { title: item.title } : {},
+            url: item.url,
+            ...typeof item.width === "number" ? { width: item.width } : {},
+            ...typeof item.height === "number" ? { height: item.height } : {},
+            ...kind === "video" && typeof item.duration === "number" ? { duration: item.duration } : {},
+            ...item.source ? { source: item.source } : {},
+            ...item.attribution ? { attribution: item.attribution } : {}
+          }))
+        });
         allLines.push(`Found ${results.length} ${kind}s:
 `);
-        for (const item of results.slice(0, 10)) {
+        for (const item of shown) {
           allLines.push(`- ${item.title}`);
           allLines.push(`  URL: ${item.url}`);
           const meta = [];
@@ -18242,11 +18511,16 @@ Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count:
           allLines.push("");
         }
       }
-      return textResult(allLines.join("\n"));
+      return structuredResult(allLines.join("\n"), { searches });
     }
   );
 }
 
+// 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) {
@@ -18303,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 = {
@@ -18315,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) {
@@ -18339,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
@@ -18355,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) {
@@ -18370,59 +18797,130 @@ 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_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(),
+            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) }));
-        return textResult(
+        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")
+          ].join("\n"),
+          {
+            jobs: jobs2.map(({ item, job }) => ({
+              status: "rendering",
+              job_id: job.id,
+              composition_id: item.compositionId,
+              output_format: item.outputFormat
+            }))
+          }
         );
       }
       if (wait === false) {
-        const job = fireRender({ compositionId, outputFormat, inputProps });
-        return textResult(
+        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}.`
-          ].join("\n")
+            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;
-      return textResult(
+      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).`
-        ].join("\n")
+          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: [
+            {
+              status: "complete",
+              ...data.public_url ? { public_url: data.public_url } : {},
+              composition_id: compositionId,
+              output_format: outputFormat,
+              ...attachStructuredFields(attach)
+            }
+          ]
+        }
       );
     }
   );
@@ -18443,6 +18941,19 @@ function registerSearchMusicTool(server) {
         maxDuration: external_exports.number().optional().describe("Maximum duration in seconds"),
         tags: external_exports.array(external_exports.string()).optional().describe("Genre/mood tags to filter by")
       },
+      outputSchema: {
+        query: external_exports.string(),
+        tracks: external_exports.array(
+          external_exports.object({
+            title: external_exports.string().optional(),
+            artist: external_exports.string().optional(),
+            url: external_exports.string(),
+            duration: external_exports.number().optional(),
+            source: external_exports.string().optional(),
+            license: external_exports.string().optional()
+          })
+        ).describe("Matching tracks (empty if none); pass a url as the audio track to generate_video")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ query, count, instrumentalOnly, minDuration, maxDuration, tags }) => {
@@ -18451,7 +18962,15 @@ function registerSearchMusicTool(server) {
       });
       if (!result.ok) return errorResult(result.error);
       const results = result.data.results;
-      if (!results.length) return textResult(`No music found for "${query}".`);
+      if (!results.length) return structuredResult(`No music found for "${query}".`, { query, tracks: [] });
+      const tracks = results.map((item) => ({
+        ...item.title ? { title: item.title } : {},
+        ...item.artist ? { artist: item.artist } : {},
+        url: item.url,
+        ...typeof item.duration === "number" ? { duration: item.duration } : {},
+        ...item.source ? { source: item.source } : {},
+        ...item.license ? { license: item.license } : {}
+      }));
       const lines = [`Found ${results.length} tracks for "${query}":
 `];
       for (const item of results) {
@@ -18462,7 +18981,7 @@ function registerSearchMusicTool(server) {
         if (item.license) lines.push(`  License: ${item.license}`);
         lines.push("");
       }
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { query, tracks });
     }
   );
 }
@@ -18503,6 +19022,19 @@ function registerListCompositionsTool(server) {
       title: "List Compositions",
       description: `Browse available video compositions and their expected props schemas. Call this before using clipform_render_composition to discover visual styles and their input props. For narrated slideshows from images, use clipform_generate_video instead.`,
       inputSchema: {},
+      outputSchema: {
+        compositions: external_exports.array(
+          external_exports.object({
+            id: external_exports.string(),
+            width: external_exports.number(),
+            height: external_exports.number(),
+            fps: external_exports.number(),
+            durationInFrames: external_exports.number(),
+            props: external_exports.string().describe("Compact props summary (name*: type)"),
+            propsSchema: external_exports.record(external_exports.unknown()).optional().describe("Full JSON Schema for inputProps")
+          })
+        ).describe("Available compositions - pass an id to render_composition")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async () => {
@@ -18517,7 +19049,18 @@ function registerListCompositionsTool(server) {
       }
       const all = result.data.compositions;
       const compositions = all.filter((c) => EXPOSED_COMPOSITIONS.includes(c.id));
-      if (!compositions.length) return textResult("No compositions found.");
+      if (!compositions.length) return structuredResult("No compositions found.", { compositions: [] });
+      const structured = {
+        compositions: compositions.map((comp) => ({
+          id: comp.id,
+          width: comp.width,
+          height: comp.height,
+          fps: comp.fps,
+          durationInFrames: comp.durationInFrames,
+          props: summarizeSchema(comp.propsSchema),
+          ...comp.propsSchema ? { propsSchema: comp.propsSchema } : {}
+        }))
+      };
       const lines = [`Available compositions (${compositions.length}):
 `];
       for (const comp of compositions) {
@@ -18527,7 +19070,183 @@ function registerListCompositionsTool(server) {
       }
       lines.push("");
       lines.push("Use clipform_render_composition with a compositionId to render. inputProps are validated strictly against the schema - unknown or missing props fail.");
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), structured);
+    }
+  );
+}
+
+// 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)
+        }
+      );
     }
   );
 }
@@ -18542,6 +19261,11 @@ function registerListAssetsTool(server) {
       inputSchema: {
         type: external_exports.enum(["sfx", "animation", "font", "all"]).default("all").optional().describe("Asset type to list (default: all)")
       },
+      outputSchema: {
+        sfx: external_exports.array(external_exports.object({ name: external_exports.string(), description: external_exports.string().nullable().optional(), path: external_exports.string().optional() })),
+        animations: external_exports.array(external_exports.object({ name: external_exports.string(), description: external_exports.string().nullable().optional(), path: external_exports.string().optional() })),
+        fonts: external_exports.array(external_exports.object({ name: external_exports.string(), weights: external_exports.array(external_exports.union([external_exports.string(), external_exports.number()])).optional() }))
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ type }) => {
@@ -18552,6 +19276,11 @@ function registerListAssetsTool(server) {
       if (!result.ok) return errorResult(result.error);
       const data = result.data;
       const lines = [];
+      const structured = {
+        sfx: (data.sfx ?? []).map((s) => ({ name: s.name, description: s.description ?? null, path: s.path })),
+        animations: (data.animations ?? []).map((a) => ({ name: a.name, description: a.description ?? null, path: a.path })),
+        fonts: (data.fonts ?? []).map((f) => ({ name: f.name, ...Array.isArray(f.weights) ? { weights: f.weights } : {} }))
+      };
       if (data.sfx?.length) {
         lines.push(`## Sound Effects (${data.sfx.length})
 `);
@@ -18576,7 +19305,7 @@ function registerListAssetsTool(server) {
         }
         lines.push("");
       }
-      return textResult(lines.length ? lines.join("\n") : "No assets found.");
+      return structuredResult(lines.length ? lines.join("\n") : "No assets found.", structured);
     }
   );
 }
@@ -18591,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({
@@ -18625,11 +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_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 } : {},
@@ -18654,34 +19403,95 @@ 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)));
-        return textResult(
+        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}.`
-          ].join("\n")
+            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;
-      return textResult(
+      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).`
-        ].filter(Boolean).join("\n")
+          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 } : {},
+          ...attachStructuredFields(attach)
+        }
       );
     }
   );
 }
 
 // src/tools/check-render.ts
+function projectJob(id, job) {
+  if (!job) return { job_id: id, status: "not_found" };
+  if (job.status === "rendering") {
+    return { job_id: id, status: "rendering", elapsed_seconds: Math.round((Date.now() - job.createdAt) / 1e3) };
+  }
+  if (job.status === "failed") {
+    return { job_id: id, status: "failed", ...job.error ? { error: job.error } : {} };
+  }
+  const data = job.result;
+  return {
+    job_id: id,
+    status: "complete",
+    ...data?.public_url ? { public_url: data.public_url } : {},
+    ...typeof data?.duration_seconds === "number" ? { duration_seconds: data.duration_seconds } : {},
+    ...attachStructuredFields(job.attach)
+  };
+}
 var LOST_JOB_RECOVERY = [
   `Jobs expire after 30 minutes and are lost if the server restarts - the render itself may still have completed.`,
   `To recover, re-run the original render call with identical arguments:`,
@@ -18704,20 +19514,37 @@ 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")
       },
+      outputSchema: {
+        jobs: external_exports.array(
+          external_exports.object({
+            job_id: external_exports.string(),
+            status: external_exports.enum(["rendering", "complete", "failed", "not_found"]),
+            public_url: external_exports.string().optional(),
+            duration_seconds: external_exports.number().optional(),
+            elapsed_seconds: external_exports.number().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_media_asset then attach_node_media unless already auto-attached")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ job_id, job_ids }) => {
@@ -18733,38 +19560,44 @@ Pass job_ids to check a whole batch in ONE call - one line of status per job. Pa
         }
         if (job.status === "rendering") {
           const elapsed = Math.round((Date.now() - job.createdAt) / 1e3);
-          return textResult(
+          return structuredResult(
             [
               `Status: rendering (${elapsed}s elapsed)`,
               `Tool: ${job.tool}`,
               ``,
               `Still in progress. Check again in ${RENDER_TIMING.pollDelay}.`
-            ].join("\n")
+            ].join("\n"),
+            { jobs: [projectJob(ids[0], job)] }
           );
         }
         if (job.status === "failed") {
           return errorResult(`Render failed: ${job.error}`);
         }
         const data = job.result;
-        return textResult(
+        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).`
-          ].join("\n")
+            ...attachLines
+          ].join("\n"),
+          { jobs: [projectJob(ids[0], job)] }
         );
       }
       const results = ids.map((id) => describeJob(id, getJob(id)));
       const pending = results.filter((r) => !r.done).length;
       const lost = results.some((r) => r.line.includes("NOT FOUND"));
-      return textResult(
+      return structuredResult(
         [
           `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")
+        ].join("\n"),
+        { jobs: ids.map((id) => projectJob(id, getJob(id))) }
       );
     }
   );
@@ -19053,7 +19886,8 @@ function createServer(options) {
   registerAddNodeTool(server);
   registerUpdateNodeTool(server);
   registerDeleteNodeTool(server);
-  registerUploadNodeMediaTool(server);
+  registerUploadMediaAssetTool(server);
+  registerAttachNodeMediaTool(server);
   registerGetNodeMediaTool(server);
   registerDeleteNodeMediaTool(server);
   registerSetNodeLogicTool(server);
@@ -19066,6 +19900,8 @@ function createServer(options) {
   registerRenderCompositionTool(server);
   registerSearchMusicTool(server);
   registerListCompositionsTool(server);
+  registerListVideoTemplatesTool(server);
+  registerRenderVideoTemplateTool(server);
   registerListAssetsTool(server);
   registerCheckRenderTool(server);
   registerFetchBoundaryTool(server);
@@ -19078,6 +19914,7 @@ function createServer(options) {
 
 export {
   JSONRPCMessageSchema,
+  RENDER_TIMING,
   createServer
 };
-//# sourceMappingURL=chunk-JT7YWEQP.js.map
+//# sourceMappingURL=chunk-RX7V2UCM.js.map