@pixeldojo/mcp 0.12.0 → 0.13.1

package/dist/cli.js

@@ -111,7 +111,8 @@ var init_types = __esm({
   "src/skills/types.ts"() {
   }
 });
-async function uploadLocalFile(path, client) {
+async function uploadLocalFile(path, ctx) {
+  if (ctx.localFiles !== true) throw new SkillUploadError(HOSTED_LOCAL_PATH_MESSAGE);
   const ext = extname(path).toLowerCase();
   const mime = EXT_TO_MIME[ext];
   if (!mime) {
@@ -150,13 +151,13 @@ async function uploadLocalFile(path, client) {
   const buffer = await readFile(path);
   const blob = new Blob([new Uint8Array(buffer)], { type: mime });
   const filename = basename(path);
-  const response = await client.uploadImage(blob, filename);
+  const response = await ctx.client.uploadImage(blob, filename);
   return response.url;
 }
-async function uploadLocalFiles(paths, client) {
-  return Promise.all(paths.map((p) => uploadLocalFile(p, client)));
+async function uploadLocalFiles(paths, ctx) {
+  return Promise.all(paths.map((p) => uploadLocalFile(p, ctx)));
 }
-var MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, EXT_TO_MIME, SkillUploadError;
+var MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, EXT_TO_MIME, SkillUploadError, HOSTED_LOCAL_PATH_MESSAGE;
 var init_upload_helpers = __esm({
   "src/skills/upload-helpers.ts"() {
     MAX_IMAGE_BYTES = 50 * 1024 * 1024;
@@ -179,6 +180,7 @@ var init_upload_helpers = __esm({
       }
       userMessage;
     };
+    HOSTED_LOCAL_PATH_MESSAGE = "Local file paths are not available on the hosted PixelDojo MCP server (it cannot see your disk). Pass a public http(s) URL instead (image_url / image_urls / video_url / audio_urls / product_image_urls), or install the local server (npx @pixeldojo/mcp init) to use files on your machine.";
   }
 });
 
@@ -450,10 +452,10 @@ async function run(input, ctx) {
   let resolved = input;
   let referenceUrls = [];
   try {
-    const singleUrl = input.image_url ?? (input.image_path ? await uploadLocalFile(input.image_path, ctx.client) : void 0);
+    const singleUrl = input.image_url ?? (input.image_path ? await uploadLocalFile(input.image_path, ctx) : void 0);
     const manyUrls = [...input.image_urls ?? []];
     for (const p of input.image_paths ?? []) {
-      manyUrls.push(await uploadLocalFile(p, ctx.client));
+      manyUrls.push(await uploadLocalFile(p, ctx));
     }
     referenceUrls = [...singleUrl ? [singleUrl] : [], ...manyUrls].filter(
       (u, i, all) => all.indexOf(u) === i
@@ -538,19 +540,19 @@ var init_generate = __esm({
     InputSchema = z.object({
       prompt: z.string().min(1).max(8e3).describe("Prompt describing what to generate."),
       model: z.string().optional().describe(
-        'Override the model. Any apiId from /api/v1/models (e.g. "flux", "google-nano-banana", "veo-3.1-fast", "kling-video-v3-standard-text"). Omit to use the default.'
+        `Model apiId, e.g. "flux", "google-nano-banana", "veo-3.1-fast", "kling-video-v3-standard-text". Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for google-nano-banana, which makes still images only; name a video model to get a video.`
       ),
       preset: z.string().optional().describe(
-        'Preset slug to seed the params (e.g. "cinematic-portrait", "product-floating-clean", "magazine-cover-text"). Browse the catalog at https://pixeldojo.ai/presets. Explicit fields override preset values.'
+        "Preset slug that seeds the running model's settings; explicit fields and params override it. Each preset belongs to one model (browse them by model at https://pixeldojo.ai/presets), so set `model` to that preset's model: a slug the running model has no preset for is rejected with a 400 before any charge."
       ),
-      aspect_ratio: z.string().optional().describe('Aspect ratio supported by the chosen model (e.g. "1:1", "16:9", "9:16").'),
-      duration: z.number().int().positive().optional().describe("Video duration in seconds, when applicable."),
+      aspect_ratio: z.string().optional().describe('e.g. "1:1", "16:9", "9:16". Snapped to the nearest ratio the model supports, and dropped if the model has no aspect_ratio field.'),
+      duration: z.number().int().positive().optional().describe("Video length in seconds. Snapped or clamped to what the model allows, and dropped if the model has no duration field. Required for grok-video-extend (the extension length)."),
       resolution: z.string().optional().describe(
         'Output resolution when the model supports it (e.g. "480p", "720p", "1080p", "4k"). Lower tiers cost fewer credits. Omit to use the model default.'
       ),
-      image_url: z.string().url().optional().describe("Reference image URL for image-to-image / image-to-video tools."),
+      image_url: z.string().url().optional().describe("Reference still for image-to-image / image-to-video. A clip URL (.mp4/.mov/.webm) or an audio track URL (.mp3/.wav/.m4a/...) here is detected by extension and routed as that kind of media instead."),
       video_url: z.string().url().optional().describe(
-        "Source video clip to animate / restyle / extend. Use this for videos; image_url is for still frames. A clip routes to a model that can actually read one."
+        "Source video clip to animate / restyle / extend. Use this for videos; image_url is for still frames. With no model, a clip runs on seedance-2-reference; a named model with no clip input is swapped for it and the result says so."
       ),
       params: ParamsInput,
       image_path: z.string().min(1).optional().describe(
@@ -577,45 +579,56 @@ var init_generate = __esm({
         prompt: { type: "string", description: "Prompt describing what to generate." },
         model: {
           type: "string",
-          description: 'Override the model. Any apiId from /api/v1/models (e.g. "flux", "google-nano-banana", "veo-3.1-fast", "kling-video-v3-standard-text"). Omit to use the default.'
+          description: `Model apiId, e.g. "flux", "google-nano-banana", "veo-3.1-fast", "kling-video-v3-standard-text". Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for google-nano-banana, which makes still images only; name a video model to get a video.`
         },
         preset: {
           type: "string",
-          description: 'Preset slug to seed the params (e.g. "cinematic-portrait", "product-floating-clean"). Explicit fields override preset values.'
+          description: "Preset slug that seeds the running model's settings; explicit fields and params override it. Each preset belongs to one model (browse them by model at https://pixeldojo.ai/presets), so set `model` to that preset's model: a slug the running model has no preset for is rejected with a 400 before any charge."
+        },
+        aspect_ratio: {
+          type: "string",
+          description: 'e.g. "1:1", "16:9", "9:16". Snapped to the nearest ratio the model supports, and dropped if the model has no aspect_ratio field.'
+        },
+        duration: {
+          type: "integer",
+          description: "Video length in seconds. Snapped or clamped to what the model allows, and dropped if the model has no duration field. Required for grok-video-extend (the extension length)."
         },
-        aspect_ratio: { type: "string" },
-        duration: { type: "integer" },
         resolution: {
           type: "string",
-          description: 'Output resolution when supported (e.g. "480p", "720p", "1080p", "4k"). Lower tiers cost fewer credits.'
+          description: 'Output resolution when the model supports it (e.g. "480p", "720p", "1080p", "4k"). Snapped to the nearest tier the model offers, and dropped if the model has no resolution field. Lower tiers cost fewer credits.'
+        },
+        image_url: {
+          type: "string",
+          format: "uri",
+          description: "Reference still for image-to-image / image-to-video. A clip URL (.mp4/.mov/.webm) or an audio track URL (.mp3/.wav/.m4a/...) here is detected by extension and routed as that kind of media instead."
         },
-        image_url: { type: "string", format: "uri" },
         video_url: {
           type: "string",
           format: "uri",
-          description: "Source video clip to animate / restyle / extend. Use this for videos; image_url is for still frames."
+          description: "Source video clip to animate / restyle / extend. Use this for videos; image_url is for still frames. With no model, a clip runs on seedance-2-reference; a named model with no clip input is swapped for it and the result says so."
         },
         params: PARAMS_JSON_SCHEMA,
         image_urls: {
           type: "array",
           items: { type: "string", format: "uri" },
-          description: "Multiple reference image URLs for models that accept a reference set. Single-reference models use the first."
+          description: "Multiple reference image URLs for models that accept a reference set (character + wardrobe + location, for example). Single-reference models use the first and ignore the rest."
         },
         image_paths: {
           type: "array",
           items: { type: "string" },
-          description: "Multiple absolute local file paths, each uploaded to 24h temp storage and used as a reference."
+          description: "Multiple absolute local file paths (JPEG, PNG, WebP, GIF, MP4, WebM, MOV), each uploaded to 24h temp storage and used as a reference, same rules as image_urls."
         },
         image_path: {
           type: "string",
-          description: "Absolute local file path. The skill uploads it to PixelDojo (24h temp storage) and uses the resulting URL as the reference image. Prefer this over image_url when the user has a local file."
+          description: "Absolute local file path to a reference image or clip (JPEG, PNG, WebP, GIF, MP4, WebM, MOV; no audio). The skill uploads it to 24h temp storage and uses the URL as image_url. Ignored when image_url is also set."
         }
       },
       required: ["prompt"]
     };
     generateSkill = {
       name: "pixeldojo_generate",
-      description: "Generate any image or video from a prompt. Auto-routes to a sensible default model; pass `model` to pick a specific apiId from the catalog. For reference flows: pass `image_url` for a still, `video_url` for a source clip, or `image_path` (absolute local path) and the skill uploads it to 24h temp storage automatically. A clip or an audio reference routes to an engine that can read one. Model-specific settings go in `params` alongside an explicit `model`.",
+      description: "Generate an image or video from a prompt with any model in the PixelDojo catalog. With no `model`, a text prompt runs on google-nano-banana, which makes still images only; for a video, name a video model such as veo-3.1-fast. References: `image_url`/`image_urls` for stills, `video_url` for a source clip, `image_path`/`image_paths` for absolute local files (uploaded to 24h temp storage first). A clip or an audio track URL with no `model` runs on seedance-2-reference; a named model that cannot read a clip is swapped for it and the result says so, while a named model with no audio input drops the track. Model-specific settings go in `params` alongside an explicit `model`. Returns asset URLs, or a jobId for pixeldojo_status when the job outlasts the 30s wait.",
+      hostedDescription: "Generate an image or video from a prompt with any model in the PixelDojo catalog. With no `model`, a text prompt runs on google-nano-banana, which makes still images only; for a video, name a video model such as veo-3.1-fast. References: `image_url`/`image_urls` for stills and `video_url` for a source clip, all public http(s) URLs. A clip or an audio track URL with no `model` runs on seedance-2-reference; a named model that cannot read a clip is swapped for it and the result says so, while a named model with no audio input drops the track. Model-specific settings go in `params` alongside an explicit `model`. Returns asset URLs, or a jobId for pixeldojo_status when the job outlasts the 30s wait.",
       inputZod: InputSchema,
       inputJsonSchema: InputJsonSchema,
       allowedModels: null,
@@ -691,13 +704,13 @@ async function run2(input, ctx) {
   let resolved = input;
   try {
     if (input.image_paths && input.image_paths.length > 0) {
-      const urls = await uploadLocalFiles(input.image_paths, ctx.client);
+      const urls = await uploadLocalFiles(input.image_paths, ctx);
       resolved = {
         ...input,
         image_urls: [...input.image_urls ?? [], ...urls]
       };
     } else if (input.image_path && !input.image_url) {
-      const url = await uploadLocalFile(input.image_path, ctx.client);
+      const url = await uploadLocalFile(input.image_path, ctx);
       resolved = { ...input, image_url: url };
     }
   } catch (err) {
@@ -779,32 +792,35 @@ var init_edit = __esm({
         image_url: {
           type: "string",
           format: "uri",
-          description: "Single reference image. Pass image_urls for multi-image edits."
+          description: "Single image to edit. Ignored when image_urls is set; pass image_urls for multi-image edits."
         },
         image_urls: {
           type: "array",
           items: { type: "string", format: "uri" },
           minItems: 1,
           maxItems: 9,
-          description: "Multiple reference images (1-9)."
+          description: "Multiple reference images (1-9), most important first. Models that take fewer keep the first ones and the result says how many were dropped."
         },
         image_path: {
           type: "string",
-          description: "Absolute local file path. Skill uploads it (24h temp storage) and edits the resulting URL. Prefer over image_url when the user has a local file."
+          description: "Absolute local image path (JPEG, PNG, WebP, GIF). Skill uploads it (24h temp storage) and edits the resulting URL. Ignored when image_url or image_paths is set."
         },
         image_paths: {
           type: "array",
           items: { type: "string" },
           minItems: 1,
           maxItems: 9,
-          description: "Multiple absolute local file paths (1-9). Each uploaded before dispatch."
+          description: "Multiple absolute local image paths (1-9). Each is uploaded to 24h temp storage and appended after any image_urls."
         },
         model: {
           type: "string",
           enum: [...ALLOWED_MODELS],
           description: "Override edit model. Default: wan-2.7-image-edit."
         },
-        aspect_ratio: { type: "string" },
+        aspect_ratio: {
+          type: "string",
+          description: 'Output aspect ratio, e.g. "1:1", "16:9", "match_input_image". Snapped to the nearest ratio the model supports, and dropped if the model has no aspect_ratio field.'
+        },
         params: PARAMS_JSON_SCHEMA
       },
       required: ["prompt"]
@@ -812,6 +828,7 @@ var init_edit = __esm({
     editSkill = {
       name: "pixeldojo_edit",
       description: "Edit an existing image with a text instruction. Defaults to wan-2.7-image-edit; pass `model` to pick another edit-capable apiId. Supports up to 9 reference images for multi-image composition. For reference images: pass image_url(s) for hosted URLs or image_path(s) for absolute local file paths (skill uploads to 24h temp storage automatically).",
+      hostedDescription: "Edit an existing image with a text instruction. Defaults to wan-2.7-image-edit; pass `model` to pick another edit-capable apiId. Supports up to 9 reference images for multi-image composition. Pass reference images as public http(s) URLs via image_url or image_urls.",
       inputZod: InputSchema2,
       inputJsonSchema: InputJsonSchema2,
       allowedModels: [...ALLOWED_MODELS],
@@ -922,7 +939,7 @@ var init_character = __esm({
     InputJsonSchema3 = {
       type: "object",
       properties: {
-        prompt: { type: "string" },
+        prompt: { type: "string", description: "The shot to render: scene, pose, wardrobe, framing. The references supply the identity." },
         model: {
           type: "string",
           enum: ALLOWED,
@@ -931,16 +948,19 @@ var init_character = __esm({
         reference_image_url: {
           type: "string",
           format: "uri",
-          description: "Single reference. Prefer reference_image_urls."
+          description: "Single still of the character. Ignored when reference_image_urls is set; prefer that, since more angles lock the face better."
         },
         reference_image_urls: {
           type: "array",
           items: { type: "string", format: "uri" },
           minItems: 1,
           maxItems: MAX_REFERENCES,
-          description: "All references for this shot, most important first. Multiple angles of the same person lock the face far better than one photo."
+          description: "All reference stills for this shot (1-9), most important first. Multiple angles of the same person lock the face far better than one photo. Models that take fewer keep the first ones and the result says how many were dropped. Required for wan-2.7-image-edit; clips and audio are refused."
+        },
+        aspect_ratio: {
+          type: "string",
+          description: 'e.g. "1:1", "16:9", "9:16". Snapped to the nearest ratio the model supports, and dropped for models with no aspect_ratio field (including the default seedream-5, which sizes by image_size: set that in params with an explicit model).'
         },
-        aspect_ratio: { type: "string" },
         params: PARAMS_JSON_SCHEMA
       },
       required: ["prompt"]
@@ -1037,24 +1057,30 @@ var init_storyboard = __esm({
       properties: {
         brief: {
           type: "string",
-          description: "Storyboard brief: scene, shots, mood, action."
+          description: "Scene brief: setting, action, camera, mood. Sent to the video model as its prompt."
         },
         model: {
           type: "string",
           enum: ALLOWED2,
-          description: `One of: ${ALLOWED2.join(", ")}. Defaults to ${DEFAULT_MODEL4}.`
+          description: `One of: ${ALLOWED2.join(", ")}. Defaults to ${DEFAULT_MODEL4}, or ${VIDEO_REFERENCE_MODEL} when image_url or video_url is given.`
+        },
+        aspect_ratio: {
+          type: "string",
+          description: 'e.g. "16:9", "9:16", "1:1". Snapped to the nearest ratio the model supports, and dropped if the model has no aspect_ratio field.'
+        },
+        duration: {
+          type: "integer",
+          description: "Clip length in seconds. Snapped or clamped to what the model allows."
         },
-        aspect_ratio: { type: "string" },
-        duration: { type: "integer" },
         image_url: {
           type: "string",
           format: "uri",
-          description: "Reference still to build the shot from."
+          description: "Reference still to build the shot from (character, product, location). A clip or audio URL here is detected by extension and routed as that kind of media."
         },
         video_url: {
           type: "string",
           format: "uri",
-          description: "Source clip to work from. Use this for videos; image_url is for stills."
+          description: "Source clip to work from. Use this for videos; image_url is for stills. A named model with no clip input is swapped for seedance-2-reference and the result says so."
         },
         params: PARAMS_JSON_SCHEMA
       },
@@ -1062,7 +1088,7 @@ var init_storyboard = __esm({
     };
     storyboardSkill = {
       name: "pixeldojo_storyboard",
-      description: "Generate a video storyboard preview from a single brief. Pass image_url for a reference still or video_url for a source clip. v1: single-shot preview; multi-shot orchestration coming.",
+      description: "Generate one short video clip (a single shot, not a multi-panel storyboard) from a scene brief. A text-only brief runs on veo-3.1-fast unless `model` names another allowed video model. With image_url (reference still) or video_url (source clip) and no `model`, it runs on seedance-2-reference, with the same reference routing as pixeldojo_generate. For a multi-shot film with dialogue and a soundtrack, use pixeldojo_film.",
       inputZod: InputSchema4,
       inputJsonSchema: InputJsonSchema4,
       allowedModels: [...ALLOWED2],
@@ -1152,27 +1178,49 @@ var init_upscale = __esm({
       scale_factor: z.number().min(1).max(16).optional().describe(
         "Image models only. Magnific snaps to the nearest of 2/4/8/16 (default 2); creative-upscale accepts 1-10 (default 2); face-enhance accepts 1-8 (default 4)."
       ),
-      creativity: z.number().min(0).max(1).optional().describe("Magnific only: 0 (preserve) \u2192 1 (creative). Defaults to 0."),
+      creativity: z.number().int().min(-10).max(10).optional().describe("Magnific only: integer -10 (preserve) \u2192 10 (creative). Defaults to 0."),
       video_duration: z.number().positive().optional().describe("video-upscaler only, REQUIRED there: source clip length in seconds (its credit meter)."),
       target_resolution: z.enum(VIDEO_RESOLUTIONS).optional().describe("video-upscaler only: target output resolution. Defaults to 1080p.")
     });
     InputJsonSchema5 = {
       type: "object",
       properties: {
-        image_url: { type: "string", format: "uri" },
+        image_url: {
+          type: "string",
+          format: "uri",
+          description: "Source image to upscale (image models). A clip URL here (.mp4/.mov/.webm) is treated as video_url."
+        },
         video_url: {
           type: "string",
           format: "uri",
-          description: "Source video clip \u2014 routes to video-upscaler."
+          description: "Source video clip (MP4, max 500 MB). Routes to video-upscaler when no model is named; needs video_duration."
+        },
+        model: {
+          type: "string",
+          enum: ALLOWED3,
+          description: `Defaults to ${DEFAULT_MODEL5}, or ${VIDEO_MODEL} when the source is a clip. face-enhance is for portraits.`
+        },
+        scale_factor: {
+          type: "number",
+          minimum: 1,
+          maximum: 16,
+          description: "Image models only. magnific-upscaler snaps to the nearest of 2/4/8/16 (default 2); creative-upscale clamps to 1-10 (default 2); face-enhance clamps to 1-8 (default 4)."
+        },
+        creativity: {
+          type: "integer",
+          minimum: -10,
+          maximum: 10,
+          description: "magnific-upscaler only: sent unchanged as its creativity setting, an integer from -10 to 10 (default 0; lower preserves the source, higher invents more detail)."
         },
-        model: { type: "string", enum: ALLOWED3 },
-        scale_factor: { type: "number", minimum: 1, maximum: 16 },
-        creativity: { type: "number", minimum: 0, maximum: 1 },
         video_duration: {
           type: "number",
-          description: "video-upscaler only, required there: source clip length in seconds."
+          description: "video-upscaler only, required there: source clip length in seconds. It sets the cost (1 credit per second)."
         },
-        target_resolution: { type: "string", enum: VIDEO_RESOLUTIONS }
+        target_resolution: {
+          type: "string",
+          enum: VIDEO_RESOLUTIONS,
+          description: "video-upscaler only: output resolution. Defaults to 1080p."
+        }
       }
     };
     upscaleSkill = {
@@ -1261,7 +1309,7 @@ var init_status = __esm({
       properties: {
         jobId: {
           type: "string",
-          description: "Job id returned from a prior pixeldojo_* skill handoff."
+          description: "The jobId a generation tool returned instead of an asset (a job_... id)."
         }
       },
       required: ["jobId"]
@@ -1270,7 +1318,7 @@ var init_status = __esm({
     ABANDON_HINT_MS = 12 * 60 * 1e3;
     statusSkill = {
       name: "pixeldojo_status",
-      description: "Check the status of a long-running job after a 30s sync handoff. Returns assets when ready, failure reason if failed, or current state if still running.",
+      description: 'Check once, without waiting, on a jobId that a generation tool returned instead of an asset after its 30s wait. Free. Returns asset URLs when complete, the failure reason if it failed, or the current state and job age if still running. Campaign ids go to pixeldojo_campaign_status; films report progress through pixeldojo_film with action "status".',
       inputZod: InputSchema6,
       inputJsonSchema: InputJsonSchema6,
       // status is special — it doesn't dispatch to a model
@@ -1315,7 +1363,7 @@ var init_from_url = __esm({
     };
     fromUrlSkill = {
       name: "pixeldojo_from_url",
-      description: "Extract product info (name, description, images) from any product page URL. Use this as the first step before pixeldojo_campaign / :ad / :lookbook so the agent has structured product data instead of a free-text description.",
+      description: "Extract a product profile from a product page URL: name, description, image URLs (the first three are listed), and the extraction method used. Works on Shopify, BigCommerce, WooCommerce, or any page with JSON-LD / OpenGraph product metadata. Free. pixeldojo_campaign and pixeldojo_ad accept a product URL and run this extraction themselves; call this directly to check the product data first, or to reuse its images in other tools.",
       inputZod: InputSchema7,
       inputJsonSchema: InputJsonSchema7,
       // No model dispatch — this skill calls a server-side scrape, not a generation.
@@ -1520,20 +1568,31 @@ var init_film = __esm({
       film_id: z.string().max(40).optional().describe("Existing film id (from a previous call) for produce/status."),
       action: z.enum(["plan", "produce", "status"]).default("plan").describe("'plan' creates + storyboards (free). 'produce' starts charged generation. 'status' advances production and reports progress; poll it every ~30s until it returns the finished film."),
       soundtrack: z.enum(["scene-synced", "flat", "none"]).default("scene-synced").describe("scene-synced composes one musical section per scene, pinned to the scene lengths (default). flat is a single cohesive bed. none skips music."),
-      music_job_id: z.string().max(80).optional().describe("Internal: pass back the music job id from a previous status reply so the composing score is attached instead of re-charged.")
+      music_job_id: z.string().max(80).optional().describe("The music_job_id from the previous status reply while the score is composing, so that score is attached. A status call without it, once all clips are ready and no score is attached, starts and charges for a new score.")
     });
     InputJsonSchema8 = {
       type: "object",
       properties: {
-        idea: { type: "string", description: "One-to-three sentence film idea. The studio writes the screenplay (free)." },
-        script: { type: "string", description: "A full screenplay to plan instead of an idea." },
-        look: { type: "string", enum: [...LOOKS], description: "Visual style. Default live-action." },
-        aspect: { type: "string", enum: ["16:9", "9:16"], description: "Default 16:9." },
-        length: { type: "string", enum: ["30s", "60s", "2-3min", "5min"], description: "Target length (~6/12/24/60 shots). Default 60s." },
-        film_id: { type: "string", description: "Existing film id for produce/status." },
-        action: { type: "string", enum: ["plan", "produce", "status"], description: "plan (free) | produce (charged) | status (poll every ~30s)." },
-        soundtrack: { type: "string", enum: ["scene-synced", "flat", "none"], description: "Default scene-synced." },
-        music_job_id: { type: "string", description: "Pass back from a previous status reply while the score is composing." }
+        idea: { type: "string", description: "Plan step: one-to-three sentence film idea. The studio writes the screenplay (free). Provide idea or script." },
+        script: { type: "string", description: "Plan step: a full screenplay (sluglines, action lines, dialogue) to plan instead of an idea." },
+        look: { type: "string", enum: [...LOOKS], description: "Plan step: visual style carried through frames, clips and soundtrack. Default live-action." },
+        aspect: { type: "string", enum: ["16:9", "9:16"], description: "Plan step: frame aspect ratio. Default 16:9." },
+        length: { type: "string", enum: ["30s", "60s", "2-3min", "5min"], description: "Plan step: target length, which sets the shot count (~6/12/24/60 shots). Default 60s." },
+        film_id: { type: "string", description: 'The film_id returned by the plan step. Required for produce and status; with it, action "plan" is treated as "status".' },
+        action: {
+          type: "string",
+          enum: ["plan", "produce", "status"],
+          description: "plan (default, free): writes the script and plans shots, returns film_id and a cost estimate. produce (charged): starts rendering frames. status: advances production one step and reports progress; call it every ~30s until it returns the finished film URL."
+        },
+        soundtrack: {
+          type: "string",
+          enum: ["scene-synced", "flat", "none"],
+          description: "Read on status calls once all clips are ready. scene-synced (default): one musical section per scene. flat: one cohesive bed. none: export without music."
+        },
+        music_job_id: {
+          type: "string",
+          description: "The music_job_id from the previous status reply while the score is composing. A status call without it, once all clips are ready and no score is attached, starts and charges for a new score."
+        }
       }
     };
     shots = (f) => f.scenes.flatMap((s) => s.shots);
@@ -1570,11 +1629,11 @@ var init_film = __esm({
 async function run9(input, ctx) {
   const productImages = [
     ...input.product_image_urls ?? [],
-    ...await Promise.all((input.product_image_paths ?? []).map((p) => uploadLocalFile(p, ctx.client)))
+    ...await Promise.all((input.product_image_paths ?? []).map((p) => uploadLocalFile(p, ctx)))
   ];
   const characterImages = [
     ...input.character_image_urls ?? [],
-    ...await Promise.all((input.character_image_paths ?? []).map((p) => uploadLocalFile(p, ctx.client)))
+    ...await Promise.all((input.character_image_paths ?? []).map((p) => uploadLocalFile(p, ctx)))
   ];
   const body = {
     style: input.style,
@@ -1652,16 +1711,24 @@ var init_ad = __esm({
         product_url: {
           type: "string",
           format: "uri",
-          description: "Product page URL. Name, description, and images are extracted automatically."
+          description: "Product page URL. Name, description, and images are extracted automatically. Pass this, or product_name plus product images; when set, the product_* fields are ignored."
+        },
+        product_name: {
+          type: "string",
+          description: "Product name. Required with product_image_urls / product_image_paths when there is no product_url."
+        },
+        product_description: { type: "string", description: "Optional product description (no product_url case)." },
+        product_image_urls: {
+          type: "array",
+          items: { type: "string", format: "uri" },
+          maxItems: 5,
+          description: "Up to 5 hosted product photos (no product_url case)."
         },
-        product_name: { type: "string" },
-        product_description: { type: "string" },
-        product_image_urls: { type: "array", items: { type: "string", format: "uri" }, maxItems: 5 },
         product_image_paths: {
           type: "array",
           items: { type: "string" },
           maxItems: 5,
-          description: "Absolute local file paths; uploaded to 24h temp storage automatically."
+          description: "Up to 5 absolute local product image paths; uploaded to 24h temp storage automatically."
         },
         character_image_urls: {
           type: "array",
@@ -1669,12 +1736,21 @@ var init_ad = __esm({
           maxItems: 4,
           description: "Presenter reference images for a consistent on-camera character."
         },
-        character_image_paths: { type: "array", items: { type: "string" }, maxItems: 4 },
+        character_image_paths: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 4,
+          description: "Absolute local presenter image paths; uploaded to 24h temp storage automatically."
+        },
         location_description: {
           type: "string",
           description: 'Where the ad takes place ("a sunlit Parisian cafe"). Text is enough.'
         },
-        location_image_url: { type: "string", format: "uri" },
+        location_image_url: {
+          type: "string",
+          format: "uri",
+          description: "Optional reference photo of the location."
+        },
         hook: {
           type: "string",
           description: "The opening visual beat (first 1-2 seconds). Omit to use the style default."
@@ -1683,21 +1759,34 @@ var init_ad = __esm({
           type: "string",
           description: "The exact spoken line, voiced word for word. Omit and the presenter improvises."
         },
-        quality: { type: "string", enum: ["mini", "fast", "high"] },
+        quality: {
+          type: "string",
+          enum: ["mini", "fast", "high"],
+          description: "Render tier. Omitted or unsupported by the ad engine, the engine's default tier is used."
+        },
         resolution: {
           type: "string",
           enum: ["480p", "720p", "1080p", "4k"],
-          description: '1080p/4k require quality "high".'
+          description: '1080p/4k require quality "high"; without it, or when the engine lacks the value, the engine default resolution is used.'
+        },
+        aspect_ratio: {
+          type: "string",
+          enum: ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9"],
+          description: "Defaults to the style's own aspect ratio; a value the engine does not support falls back to it."
         },
-        aspect_ratio: { type: "string", enum: ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9"] },
-        duration: { type: "integer", minimum: 4, maximum: 15 }
+        duration: {
+          type: "integer",
+          minimum: 4,
+          maximum: 15,
+          description: "Ad length in seconds. Defaults to the style's length; clamped to what the engine allows."
+        }
       }
       // "product_url OR product_name+images" is enforced by the server and the
       // Zod refine; no root-level oneOf (Grok rejects non-object root unions).
     };
     adSkill = {
       name: "pixeldojo_ad",
-      description: "Marketing Studio: turn any product into a video ad. Pass a product URL (auto-extracted) or product images, pick an ad style (UGC testimonial, unboxing, try-on, showcase, TV spot, and more via GET /api/v1/marketing/presets), optionally add presenter reference images, a location, a hook, and the exact spoken script. Renders with voiceover; returns the video or a statusUrl handoff to poll via pixeldojo_status. Ideal for automated generate-and-post workflows.",
+      description: "Marketing Studio: turn a product into a rendered video ad with voiceover. Requires `product_url` (name, description and images are extracted), or `product_name` plus product_image_urls / product_image_paths. Pick a `style` slug (default ugc-testimonial; full catalog at GET https://pixeldojo.ai/api/v1/marketing/presets), and optionally add presenter reference images, a location, a hook, and the exact spoken script. Returns the video URL, or a jobId to check with pixeldojo_status.",
       inputZod: InputSchema9,
       inputJsonSchema: InputJsonSchema9,
       // Composition skill — the server routes to the ad engine internally.
@@ -1759,27 +1848,47 @@ var init_campaign = __esm({
         productUrl: {
           type: "string",
           format: "uri",
-          description: "Product page URL. We extract name + description + images automatically."
+          description: "Product page URL; name, description and images are extracted automatically. Pass this or `product` (one is required); when both are set, productUrl wins."
         },
         product: {
           type: "object",
+          description: "Manual product profile, used when productUrl is omitted.",
           properties: {
-            name: { type: "string" },
-            description: { type: "string" },
-            images: { type: "array", items: { type: "string", format: "uri" } }
+            name: { type: "string", description: "Product name (required)." },
+            description: { type: "string", description: "Optional product description." },
+            images: {
+              type: "array",
+              items: { type: "string", format: "uri" },
+              maxItems: 5,
+              description: "Up to 5 hosted product photo URLs."
+            }
           },
           required: ["name"]
         },
         tone: {
           type: "string",
-          description: "Creative direction threaded through every prompt."
+          description: 'Optional creative direction ("premium minimalist", "playful Y2K"), threaded through every prompt.'
         },
-        variants: { type: "integer", minimum: 1, maximum: 8 },
-        includeVideo: { type: "boolean" },
-        videoAspectRatio: { type: "string", enum: ["9:16", "16:9", "1:1"] },
-        videoMode: { type: "string", enum: ["lifestyle", "cgi", "ugc", "skip"] }
-      },
-      oneOf: [{ required: ["productUrl"] }, { required: ["product"] }]
+        variants: {
+          type: "integer",
+          minimum: 1,
+          maximum: 8,
+          description: "Lifestyle shots in addition to the hero (default 4)."
+        },
+        includeVideo: { type: "boolean", description: "Also render a launch video (default true)." },
+        videoAspectRatio: {
+          type: "string",
+          enum: ["9:16", "16:9", "1:1"],
+          description: "Launch video aspect ratio (default 9:16)."
+        },
+        videoMode: {
+          type: "string",
+          enum: ["lifestyle", "cgi", "ugc", "skip"],
+          description: "Launch video styling: lifestyle (default), cgi, ugc, or skip for no video."
+        }
+      }
+      // productUrl-or-product is enforced by the Zod refine and the server; no
+      // root-level oneOf (some clients reject root unions — see ad.ts).
     };
     campaignSkill = {
       name: "pixeldojo_campaign",
@@ -1854,7 +1963,7 @@ var init_campaign_status = __esm({
 async function run12(input, ctx) {
   let url;
   try {
-    url = await uploadLocalFile(input.path, ctx.client);
+    url = await uploadLocalFile(input.path, ctx);
   } catch (err) {
     if (err instanceof SkillUploadError) {
       return { kind: "text", text: `pixeldojo_upload: ${err.userMessage}` };
@@ -1864,7 +1973,7 @@ async function run12(input, ctx) {
   return {
     kind: "text",
     text: `Uploaded ${basename(input.path)} \u2192 ${url}
-(temp storage; auto-deletes in ~24h \u2014 pass this URL as image_url to :generate or :edit)`
+(temp storage; auto-deletes in ~24h. Pass this URL as image_url, or video_url for a clip, to any pixeldojo tool that takes one.)`
   };
 }
 var InputSchema12, InputJsonSchema12, uploadSkill;
@@ -1888,7 +1997,7 @@ var init_upload = __esm({
     };
     uploadSkill = {
       name: "pixeldojo_upload",
-      description: "Upload a local image or video file and get back a public URL you can pass to :generate or :edit as image_url. Use when the user has a reference image on disk (drag-dropped into Claude Code, screenshot, etc.) and you need a URL. Storage auto-expires after 24 hours.",
+      description: "Upload a local image or video (JPEG, PNG, WebP, GIF up to 50MB; MP4, WebM, MOV up to 200MB) and get back a public URL that expires after 24 hours. Free. Audio files are not accepted. Pass the URL as image_url (stills) or video_url (clips) to tools that take hosted URLs only, such as pixeldojo_character, pixeldojo_storyboard and pixeldojo_upscale. pixeldojo_generate, pixeldojo_edit and pixeldojo_ad take local paths directly and need no separate upload.",
       inputZod: InputSchema12,
       inputJsonSchema: InputJsonSchema12,
       allowedModels: [],
@@ -1906,18 +2015,7 @@ async function run13(input, ctx) {
     };
   }
   const apiId = requested;
-  let audioUrls = input.audio_urls ?? [];
-  if (input.audio_paths?.length) {
-    try {
-      const uploaded = await uploadLocalFiles(input.audio_paths, ctx.client);
-      audioUrls = [...audioUrls, ...uploaded].slice(0, 3);
-    } catch (err) {
-      if (err instanceof SkillUploadError) {
-        return { kind: "text", text: `pixeldojo_audio (upload): ${err.userMessage}` };
-      }
-      throw err;
-    }
-  }
+  const audioUrls = input.audio_urls ?? [];
   const body = { prompt: input.prompt };
   if (apiId === "seed-audio") {
     if (input.voice) body.voice = input.voice;
@@ -1950,37 +2048,57 @@ var ALLOWED4, DEFAULT_MODEL6, InputSchema13, InputJsonSchema13, audioSkill;
 var init_audio = __esm({
   "src/skills/audio.ts"() {
     init_poll();
-    init_upload_helpers();
     init_types();
     ALLOWED4 = ["seed-audio", "text-to-speech"];
     DEFAULT_MODEL6 = "seed-audio";
     InputSchema13 = z.object({
       prompt: z.string().min(1).describe(
-        "A script for speech, or a scene description for cinematic audio (dialogue + effects + music). Reference uploaded clips as @Audio1..@Audio3."
+        "seed-audio: a script to speak, or a scene description (dialogue, sound effects, music), up to 2048 characters; refer to audio_urls clips in order as @Audio1..@Audio3. text-to-speech: the exact text to speak, up to 10,000 characters."
       ),
-      model: z.string().optional().describe(`One of: ${ALLOWED4.join(", ")}. Defaults to ${DEFAULT_MODEL6}.`),
-      voice: z.string().optional().describe("Optional voice preset name or cloned-voice id (seed-audio) / voice_id (text-to-speech)."),
-      audio_urls: z.array(z.string().url()).max(3).optional().describe("seed-audio only: up to 3 reference audio URLs (30s / 10MB max each)."),
-      audio_paths: z.array(z.string()).max(3).optional().describe("seed-audio only: absolute local paths to reference clips; uploaded automatically (24h temp storage)."),
-      output_format: z.string().optional().describe("seed-audio: mp3 (default), wav, pcm, ogg_opus. text-to-speech: mp3, wav, flac, pcm."),
-      speed: z.number().min(0.5).max(2).optional().describe("Speech speed multiplier (0.5\u20132).")
+      model: z.string().optional().describe(`${DEFAULT_MODEL6} (default): speech, multi-voice dialogue, effects and music in one clip, and voice cloning from audio_urls. text-to-speech: plain narration with preset voices.`),
+      voice: z.string().optional().describe("text-to-speech only: voice preset (e.g. Wise_Woman, Calm_Woman, Friendly_Person; default Wise_Woman). seed-audio ignores it: describe the voice in the prompt, or clone one with audio_urls."),
+      audio_urls: z.array(z.string().url()).max(3).optional().describe("seed-audio only: up to 3 hosted reference clips (wav, mp3, pcm or ogg_opus, 30s / 10MB max each) for voice cloning, referenced in the prompt as @Audio1..@Audio3. Local audio files cannot be uploaded; pass URLs. Ignored by text-to-speech."),
+      output_format: z.string().optional().describe("Output format. seed-audio: mp3 (default), wav, pcm, ogg_opus. text-to-speech: mp3 (default), wav, flac, pcm."),
+      speed: z.number().min(0.5).max(2).optional().describe("Speech speed multiplier, 0.5-2 (default 1). Both models.")
     });
     InputJsonSchema13 = {
       type: "object",
       properties: {
-        prompt: { type: "string" },
-        model: { type: "string", enum: ALLOWED4 },
-        voice: { type: "string" },
-        audio_urls: { type: "array", items: { type: "string", format: "uri" }, maxItems: 3 },
-        audio_paths: { type: "array", items: { type: "string" }, maxItems: 3 },
-        output_format: { type: "string" },
-        speed: { type: "number", minimum: 0.5, maximum: 2 }
+        prompt: {
+          type: "string",
+          description: "seed-audio: a script to speak, or a scene description (dialogue, sound effects, music), up to 2048 characters; refer to audio_urls clips in order as @Audio1..@Audio3. text-to-speech: the exact text to speak, up to 10,000 characters."
+        },
+        model: {
+          type: "string",
+          enum: ALLOWED4,
+          description: `${DEFAULT_MODEL6} (default): speech, multi-voice dialogue, effects and music in one clip, and voice cloning from audio_urls. text-to-speech: plain narration with preset voices.`
+        },
+        voice: {
+          type: "string",
+          description: "text-to-speech only: voice preset (e.g. Wise_Woman, Calm_Woman, Friendly_Person; default Wise_Woman). seed-audio ignores it: describe the voice in the prompt, or clone one with audio_urls."
+        },
+        audio_urls: {
+          type: "array",
+          items: { type: "string", format: "uri" },
+          maxItems: 3,
+          description: "seed-audio only: up to 3 hosted reference clips (wav, mp3, pcm or ogg_opus, 30s / 10MB max each) for voice cloning, referenced in the prompt as @Audio1..@Audio3. Local audio files cannot be uploaded; pass URLs. Ignored by text-to-speech."
+        },
+        output_format: {
+          type: "string",
+          description: "Output format. seed-audio: mp3 (default), wav, pcm, ogg_opus. text-to-speech: mp3 (default), wav, flac, pcm."
+        },
+        speed: {
+          type: "number",
+          minimum: 0.5,
+          maximum: 2,
+          description: "Speech speed multiplier, 0.5-2 (default 1). Both models."
+        }
       },
       required: ["prompt"]
     };
     audioSkill = {
       name: "pixeldojo_audio",
-      description: "Generate audio: speech, multi-character dialogue, sound effects, and background music from one prompt (Seed Audio 1.0 by default; plain TTS available).",
+      description: "Generate audio: speech, multi-character dialogue, sound effects, and background music from one prompt (Seed Audio 1.0 by default; plain text-to-speech available). Voice cloning takes hosted reference clip URLs in audio_urls; local audio files are not accepted. Returns an audio URL, or a jobId for pixeldojo_status.",
       inputZod: InputSchema13,
       inputJsonSchema: InputJsonSchema13,
       allowedModels: [...ALLOWED4],
@@ -2017,7 +2135,7 @@ async function run14(input, ctx) {
     text: `${res.items.length} library item(s):
 ${lines.join("\n")}
 
-Pass any URL back into :generate, :edit, :character, or :upscale as a reference input.`
+Pass any URL back into pixeldojo_generate, pixeldojo_edit, pixeldojo_character, or pixeldojo_upscale as a reference input.`
   };
 }
 var InputSchema14, InputJsonSchema14, librarySkill;
@@ -2032,10 +2150,17 @@ var init_library = __esm({
     InputJsonSchema14 = {
       type: "object",
       properties: {
-        q: { type: "string" },
-        model: { type: "string" },
-        modality: { type: "string", enum: ["image", "video", "audio"] },
-        limit: { type: "integer", minimum: 1, maximum: 50 }
+        q: {
+          type: "string",
+          description: "Substring match against the prompt that produced the asset. Omit to list the newest items."
+        },
+        model: { type: "string", description: "Only assets from this model apiId." },
+        modality: {
+          type: "string",
+          enum: ["image", "video", "audio"],
+          description: "Only this output type."
+        },
+        limit: { type: "integer", minimum: 1, maximum: 50, description: "Max results (default 10)." }
       },
       required: []
     };
@@ -2177,7 +2302,7 @@ async function runWorkflow(input, ctx) {
 ${outputs.join("\n")}`
   };
 }
-var WORKFLOW_STEP_EXTRA_BUDGET_MS, StepSchema, SaveInputSchema, RunInputSchema, ListInputSchema, stepJson, saveWorkflowSkill, runWorkflowSkill, listWorkflowsSkill;
+var WORKFLOW_STEP_EXTRA_BUDGET_MS, StepSchema, SaveInputSchema, RunInputSchema, ListInputSchema, STEP_SKILLS, stepJson, saveWorkflowSkill, runWorkflowSkill, listWorkflowsSkill;
 var init_workflows = __esm({
   "src/skills/workflows.ts"() {
     init_poll();
@@ -2201,11 +2326,28 @@ var init_workflows = __esm({
       inputs: z.record(z.string(), z.string()).optional().describe("Values for {{input.<key>}} placeholders in the workflow steps.")
     });
     ListInputSchema = z.object({});
+    STEP_SKILLS = [
+      "pixeldojo_generate",
+      "pixeldojo_edit",
+      "pixeldojo_character",
+      "pixeldojo_storyboard",
+      "pixeldojo_upscale",
+      "pixeldojo_audio",
+      "pixeldojo_upload",
+      "pixeldojo_from_url"
+    ];
     stepJson = {
       type: "object",
       properties: {
-        skill: { type: "string" },
-        args: { type: "object" }
+        skill: {
+          type: "string",
+          enum: STEP_SKILLS,
+          description: "Tool this step runs. Steps run in order when the workflow runs, and each is charged at that tool's own rate."
+        },
+        args: {
+          type: "object",
+          description: "That tool's own arguments, exactly as you would pass them calling it directly. Any string value, at any depth, may contain {{input.<key>}} (filled from pixeldojo_run_workflow inputs) or {{prev}} (the first asset URL the previous step produced)."
+        }
       },
       required: ["skill"]
     };
@@ -2216,9 +2358,19 @@ var init_workflows = __esm({
       inputJsonSchema: {
         type: "object",
         properties: {
-          name: { type: "string", pattern: "^[a-z0-9][a-z0-9-]{1,40}$" },
-          description: { type: "string" },
-          steps: { type: "array", items: stepJson, minItems: 1, maxItems: 8 }
+          name: {
+            type: "string",
+            pattern: "^[a-z0-9][a-z0-9-]{1,40}$",
+            description: 'Kebab-case handle, 2-41 chars (e.g. "product-launch-pack"). Saving to an existing name overwrites it.'
+          },
+          description: { type: "string", description: "Optional note on what the workflow does (max 500 chars)." },
+          steps: {
+            type: "array",
+            items: stepJson,
+            minItems: 1,
+            maxItems: 8,
+            description: "The chain, 1-8 steps, run in order. Saving charges nothing; running charges each step."
+          }
         },
         required: ["name", "steps"]
       },
@@ -2233,8 +2385,12 @@ var init_workflows = __esm({
       inputJsonSchema: {
         type: "object",
         properties: {
-          name: { type: "string" },
-          inputs: { type: "object", additionalProperties: { type: "string" } }
+          name: { type: "string", description: "Saved workflow name (see pixeldojo_list_workflows)." },
+          inputs: {
+            type: "object",
+            additionalProperties: { type: "string" },
+            description: `String values for the workflow's {{input.<key>}} placeholders, e.g. {"product": "red sneaker"}. A step whose placeholder has no value stops the run before that step.`
+          }
         },
         required: ["name"]
       },
@@ -2258,6 +2414,7 @@ var init_workflows = __esm({
 var skills_exports = {};
 __export(skills_exports, {
   ALL_SKILLS: () => ALL_SKILLS,
+  HOSTED_SKILLS: () => HOSTED_SKILLS,
   adSkill: () => adSkill,
   audioSkill: () => audioSkill,
   campaignSkill: () => campaignSkill,
@@ -2265,6 +2422,7 @@ __export(skills_exports, {
   characterSkill: () => characterSkill,
   editSkill: () => editSkill,
   filmSkill: () => filmSkill,
+  findHostedSkill: () => findHostedSkill,
   findSkill: () => findSkill,
   fromUrlSkill: () => fromUrlSkill,
   generateSkill: () => generateSkill,
@@ -2277,11 +2435,15 @@ __export(skills_exports, {
   uploadSkill: () => uploadSkill,
   upscaleSkill: () => upscaleSkill
 });
+function findHostedSkill(name) {
+  const wanted = name.replace(/^pixeldojo:/, "pixeldojo_");
+  return HOSTED_SKILLS.find((s) => s.name === wanted);
+}
 function findSkill(name) {
   const wanted = name.replace(/^pixeldojo:/, "pixeldojo_");
   return ALL_SKILLS.find((s) => s.name === wanted);
 }
-var ALL_SKILLS;
+var ALL_SKILLS, isLocalPathField, HOSTED_SKILLS;
 var init_skills = __esm({
   "src/skills/index.ts"() {
     init_generate();
@@ -2318,6 +2480,20 @@ var init_skills = __esm({
       campaignStatusSkill,
       filmSkill
     ];
+    isLocalPathField = (key) => /_paths?$/.test(key);
+    HOSTED_SKILLS = ALL_SKILLS.filter(
+      (s) => s.name !== uploadSkill.name
+    ).map((s) => {
+      const props = s.inputJsonSchema.properties ?? {};
+      return {
+        ...s,
+        description: s.hostedDescription ?? s.description,
+        inputJsonSchema: {
+          ...s.inputJsonSchema,
+          properties: Object.fromEntries(Object.entries(props).filter(([k]) => !isLocalPathField(k)))
+        }
+      };
+    });
   }
 });
 function makeAttributedClient(options) {
@@ -2371,7 +2547,8 @@ function makeRedactedLogger(target = console) {
 }
 
 // src/server.ts
-var PACKAGE_VERSION = "0.12.0" ;
+var PACKAGE_VERSION = "0.13.1" ;
+var SERVER_INSTRUCTIONS = "PixelDojo generates images, video, audio and short films across 100+ models, billed in credits from the connected PixelDojo account. A job that runs past the 30-second wait returns a jobId to check later; check it rather than submitting again, since every new submission is charged. Generated asset URLs are deleted one hour after they are created, so download anything the user wants to keep. Finished films are the exception and stay in the account library.";
 function buildServer(options) {
   if (!options.apiKey) {
     throw new Error(
@@ -2389,7 +2566,8 @@ function buildServer(options) {
     {
       capabilities: {
         tools: {}
-      }
+      },
+      instructions: SERVER_INSTRUCTIONS
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -2441,6 +2619,8 @@ function buildServer(options) {
       apiKey: options.apiKey,
       baseUrl,
       mcpVersion: version,
+      localFiles: true,
+      // stdio: the caller's own machine
       logger,
       buildStatusUrl: (jobId) => `${baseUrl}/api/v1/jobs/${encodeURIComponent(jobId)}`
     };