@transloadit/node 6.4.0 → 6.6.0

package/src/alphalib/types/robots/_instructions-primitives.ts

@@ -828,6 +828,22 @@ const deprecatedFfmpegVersions = formatEnglishList([
   ),
 ])
 
+/** Common per-input concat fade behavior; Robot-specific transition controls stay owner-local. */
+export function getConcatFadeDescription(media: 'audio' | 'video'): string {
+  const timing =
+    media === 'audio'
+      ? 'Audio fade-outs start on a whole-second boundary and may finish before the input ends.'
+      : 'Video fade durations are rounded down to whole frames and capped at the duration of each input.'
+
+  return `
+When concatenating at least two files, a positive value fades out the ${media} of each input and fades in every input after the first. There is no fade-in at the beginning of the output, but the fade-out is also applied to the last input.
+
+The value is a duration in seconds. For example, \`0.5\` means 500 milliseconds. Omit this parameter or set it to \`0\` to disable these per-input fades. They do not overlap clips or insert additional time between them.
+
+${timing}
+`
+}
+
 export const robotParameterDocs = {
   adaptive_filtering: {
     description: `
@@ -2075,6 +2091,12 @@ export const vimeoBase = z
       .optional()
       .describe(`
 Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your Vimeo access token.
+
+For /vimeo/import, create your own app at [developer.vimeo.com/apps](https://developer.vimeo.com/apps), open \`Generate Access Token\`, choose \`Authenticated (you)\`, and select \`Public\`, \`Private\`, and \`Video Files\` (\`public private video_files\`). Generate the personal access token, then choose **Vimeo** and **Paste a personal access token** in the Console. The token is stored as \`access_token\` and is never displayed back in the Console. Saving checks your Vimeo account and the token’s scopes. Video file links also require an eligible Vimeo account and video permissions.
+
+Vimeo OAuth in the Console supports /vimeo/store. It cannot grant \`video_files\` for other members’ accounts because Transloadit is not a Vimeo partner. Imports require your own personal access token. To use that token for /vimeo/store too, also grant \`Upload\`, \`Edit\`, and \`Interact\` (\`upload edit interact\`) and ensure your Vimeo app has upload access.
+
+Updating a credential does not run OAuth again or add permissions. To reconnect, **Remove** the credential (which revokes its token at Vimeo), then create a new credential with the same name. For a personal token, generate a new one before saving it again. Revocation also affects any other use of that token. See the [Vimeo credential instructions](/docs/topics/template-credentials/#vimeo).
 `),
   })
   .strict()
@@ -2172,6 +2194,9 @@ While we recommend to use <dfn>Template Credentials</dfn> at all times, some use
   })
   .strict()
 
+/** Default SSH/SFTP port when no explicit connection port is supplied. */
+export const sftpDefaultPort = 22
+
 export type SftpBase = z.infer<typeof sftpBase>
 export const sftpBase = z
   .object({
@@ -2184,7 +2209,7 @@ Please create your associated <dfn>Template Credentials</dfn> in your Transloadi
 While we recommend to use <dfn>Template Credentials</dfn> at all times, some use cases demand dynamic credentials for which using <dfn>Template Credentials</dfn> is too unwieldy because of their static nature. If you have this requirement, feel free to use the following parameters instead: \`"host"\`, \`"port"\`, \`"user"\`, \`"public_key"\` (optional).
 `),
     host: z.string().optional(),
-    port: port.default(21).describe('The port to use for the FTP connection.'),
+    port: port.default(sftpDefaultPort).describe('The port to use for the SFTP connection.'),
     user: z.string().optional(),
     public_key: z.string().optional(),
   })
@@ -2333,6 +2358,11 @@ export const filterConditionPartSchema = z.tuple([
 export type FilterCondition = z.infer<typeof filterCondition>
 export const filterCondition = z.union([z.null(), z.string(), z.array(filterConditionPartSchema)])
 
+/** English Turbo guidance shared by the public parameter and supporting video FAQ. */
+export const videoTurboParameterDocumentation = `Splits the video into multiple chunks so that each chunk can be encoded in parallel before all encoded chunks are stitched back together to form the result video. This comes at the expense of extra Priority Job Slots and may prove to be counter-productive for very small video files.
+
+VP8 output and unresolved video-codec expressions use normal encoding even when \`turbo\` is \`true\`.`
+
 /**
  * Parameters specific to the /video/encode robot. Useful for typing robots that pass files to /video/encode.
  */
@@ -2391,12 +2421,7 @@ Forces the video to be rotated by the specified degree integer. Currently, only
       .describe(`
 Enables hinting for mp4 files, for RTP/RTSP streaming.
 `),
-    turbo: z
-      .boolean()
-      .default(false)
-      .describe(`
-Splits the video into multiple chunks so that each chunk can be encoded in parallel before all encoded chunks are stitched back together to form the result video. This comes at the expense of extra <dfn>Priority Job Slots</dfn> and may prove to be counter-productive for very small video files.
-`),
+    turbo: z.boolean().default(false).describe(videoTurboParameterDocumentation),
     chunk_duration: z
       .number()
       .int()
@@ -2404,6 +2429,8 @@ Splits the video into multiple chunks so that each chunk can be encoded in paral
       .optional()
       .describe(`
 Allows you to specify the duration of each chunk when \`turbo\` is set to \`true\`. This means you can take advantage of that feature while using fewer <dfn>Priority Job Slots</dfn>. For instance, the longer each chunk is, the fewer <dfn>Encoding Jobs</dfn> will need to be used.
+
+Requested durations below 5 seconds are treated as 5 seconds.
 `),
     watermark_url: z
       .union([z.literal(''), httpUrlSchema])

package/src/alphalib/types/robots/_video-generate.ts

@@ -0,0 +1,211 @@
+import type { RobotVideoGenerateInstructions } from './video-generate.ts'
+
+import { videoGenerateDefaultModelIdentifier } from './_ai-models.ts'
+
+// Keep the schema wording portable without exposing the server's provider policy to SDKs.
+export { videoGenerationParameterEnforcementDate } from './_video-generate-description.ts'
+
+const optionalVideoParameters = [
+  'seed',
+  'aspect_ratio',
+  'height',
+  'width',
+  'style',
+  'duration',
+  'fps',
+  'motion_amount',
+  'camera_motion',
+  'negative_prompt',
+  'reference_strength',
+] satisfies (keyof RobotVideoGenerateInstructions)[]
+
+const ltxAspectRatioError = 'aspect_ratio must be a nonempty string for lightricks/ltx-video.'
+
+/** Stable code included in Assembly warning text and structured server logs. */
+export const videoGenerationParameterWarningCode = 'VIDEO_GENERATE_PARAMETER_IGNORED'
+
+/** Flip this one flag on the enforcement date; both policy paths have regression coverage. */
+export const videoGenerationParameterValidation = { enforceUnsupportedParameters: false }
+
+type VideoGenerationParameters = Pick<
+  RobotVideoGenerateInstructions,
+  'model' | 'prompt' | (typeof optionalVideoParameters)[number]
+>
+
+interface VideoGenerationModel {
+  replicateModel: `${string}/${string}`
+  parameters: readonly (typeof optionalVideoParameters)[number][]
+  imageInput?: string
+  imageMimeTypes?: readonly string[]
+  requiresImage?: boolean
+}
+
+// https://platform.minimax.io/docs/api-reference/video-generation-i2v#body-first-frame-image
+const minimaxImageMimeTypes = ['image/jpeg', 'image/png', 'image/webp']
+
+/** Verified Replicate video capabilities; model schemas do not accept a generic video input. */
+// Unavailable luma/ray and image-only luma/photon stay excluded in both modes. The transition
+// applies to ignored settings on supported video models, preserving the other validation fixes.
+export const videoGenerationModels: Record<string, VideoGenerationModel> = {
+  // https://replicate.com/minimax/video-01/api/schema: fixed six-second output, no duration input.
+  'minimax/video-01': {
+    replicateModel: 'minimax/video-01',
+    parameters: [],
+    imageInput: 'first_frame_image',
+    imageMimeTypes: minimaxImageMimeTypes,
+  },
+  'minimax/video-01-live': {
+    replicateModel: 'minimax/video-01-live',
+    parameters: [],
+    imageInput: 'first_frame_image',
+    imageMimeTypes: minimaxImageMimeTypes,
+    requiresImage: true,
+  },
+  // https://replicate.com/tencent/hunyuan-video/api/schema: length is specified in frames.
+  'tencent/hunyuan-video': {
+    replicateModel: 'tencent/hunyuan-video',
+    parameters: ['seed', 'height', 'width', 'fps'],
+  },
+  // https://replicate.com/lightricks/ltx-video/api/schema: length is specified in frames.
+  'lightricks/ltx-video': {
+    replicateModel: 'lightricks/ltx-video',
+    parameters: ['seed', 'aspect_ratio', 'negative_prompt'],
+    imageInput: 'image',
+  },
+}
+
+/** Looks up only configured model names, excluding inherited object properties. */
+export function getVideoGenerationModel(model: string): VideoGenerationModel | undefined {
+  return Object.hasOwn(videoGenerationModels, model) ? videoGenerationModels[model] : undefined
+}
+
+/** Identifies known unsupported frame formats without rejecting legacy CLI inputs lacking MIME. */
+export function getVideoGenerationImageFormatError(
+  modelName: string,
+  mime: string | null | undefined,
+): string | undefined {
+  const supported = getVideoGenerationModel(modelName)?.imageMimeTypes
+  if (!mime || !supported || supported.includes(mime)) return undefined
+  return `Model ${modelName} supports only JPEG, PNG, or WebP input images. Convert the image before using it.`
+}
+
+/** Shares safe value constraints between migration warnings and later enforcement errors. */
+export function getPreviouslyOmittedVideoGenerationValueError(
+  instructions: VideoGenerationParameters,
+  parameter: (typeof optionalVideoParameters)[number],
+  hasImage: boolean,
+): string | undefined {
+  if (instructions.model === 'tencent/hunyuan-video') {
+    if (
+      parameter === 'fps' &&
+      instructions.fps != null &&
+      (!Number.isInteger(instructions.fps) || instructions.fps < 1)
+    ) {
+      return 'fps must be a positive integer for tencent/hunyuan-video.'
+    }
+    if (parameter === 'height' || parameter === 'width') {
+      const value = instructions[parameter]
+      if (value != null && (value < 16 || value > 1280 || value % 16 !== 0)) {
+        return `${parameter} must be a multiple of 16 between 16 and 1280 for tencent/hunyuan-video.`
+      }
+    }
+  }
+  if (
+    instructions.model === 'lightricks/ltx-video' &&
+    parameter === 'aspect_ratio' &&
+    !hasImage &&
+    instructions.aspect_ratio === ''
+  ) {
+    return ltxAspectRatioError
+  }
+  return undefined
+}
+
+/** Enumerates ignored scalar settings without including customer-supplied values. */
+export function getUnsupportedVideoGenerationParameters(
+  instructions: VideoGenerationParameters,
+  hasImage = false,
+): (typeof optionalVideoParameters)[number][] {
+  const model = getVideoGenerationModel(instructions.model ?? videoGenerateDefaultModelIdentifier)
+  if (!model) return []
+  return optionalVideoParameters.filter(
+    (parameter) =>
+      instructions[parameter] != null &&
+      (!model.parameters.includes(parameter) ||
+        (hasImage && parameter === 'aspect_ratio') ||
+        getPreviouslyOmittedVideoGenerationValueError(instructions, parameter, hasImage) != null),
+  )
+}
+
+/** Enforces model constraints and, after the transition, rejects ignored scalar settings. */
+export function getVideoGenerationParameterError(
+  instructions: VideoGenerationParameters,
+  hasImage = false,
+): string | undefined {
+  const modelName = instructions.model ?? videoGenerateDefaultModelIdentifier
+  const model = getVideoGenerationModel(modelName)
+  if (!model) return `Model ${modelName} is not supported for video generation.`
+  const unsupported = getUnsupportedVideoGenerationParameters(instructions, hasImage)
+  if (videoGenerationParameterValidation.enforceUnsupportedParameters && unsupported.length > 0) {
+    const parameter = unsupported[0]
+    const valueError = getPreviouslyOmittedVideoGenerationValueError(
+      instructions,
+      parameter,
+      hasImage,
+    )
+    if (valueError) return valueError
+    const imageConstraint =
+      hasImage && parameter === 'aspect_ratio' && model.parameters.includes(parameter)
+        ? ' with an input image'
+        : ''
+    return `Model ${modelName} does not support ${parameter}${imageConstraint}. Omit this parameter or select a model that supports it.`
+  }
+  // Whitespace was forwarded before this change, unlike the previously omitted empty string.
+  if (
+    modelName === 'lightricks/ltx-video' &&
+    !hasImage &&
+    instructions.aspect_ratio != null &&
+    instructions.aspect_ratio !== '' &&
+    instructions.aspect_ratio.trim() === ''
+  ) {
+    return ltxAspectRatioError
+  }
+  return undefined
+}
+
+/** Requires necessary images immediately; unsupported inputs share the compatibility window. */
+export function getVideoGenerationImageError(
+  instructions: Pick<VideoGenerationParameters, 'model' | 'aspect_ratio'>,
+  hasImage: boolean,
+): string | undefined {
+  const modelName = instructions.model ?? videoGenerateDefaultModelIdentifier
+  const model = getVideoGenerationModel(modelName)
+  if (!model) return `Model ${modelName} is not supported for video generation.`
+  if (model.requiresImage && !hasImage) return `Model ${modelName} requires an input image.`
+  if (
+    videoGenerationParameterValidation.enforceUnsupportedParameters &&
+    hasImage &&
+    !model.imageInput
+  ) {
+    return `Model ${modelName} does not support an input image.`
+  }
+  return undefined
+}
+
+/** Builds only model-supported provider fields, preserving explicit zero values. */
+export function buildVideoGenerationInput(
+  instructions: VideoGenerationParameters,
+  hasImage = false,
+): Record<string, unknown> {
+  const error = getVideoGenerationParameterError(instructions, hasImage)
+  if (error) throw new Error(error)
+  const model = getVideoGenerationModel(instructions.model ?? videoGenerateDefaultModelIdentifier)
+  if (!model) throw new Error('Missing video generation model configuration.')
+  const unsupported = getUnsupportedVideoGenerationParameters(instructions, hasImage)
+  const input: Record<string, unknown> = { prompt: instructions.prompt }
+  for (const parameter of model.parameters) {
+    const value = instructions[parameter]
+    if (value != null && !unsupported.includes(parameter)) input[parameter] = value
+  }
+  return input
+}

package/src/alphalib/types/robots/ai-chat.ts

@@ -472,6 +472,9 @@ export const vendorModelSchema = z.enum([firstSupportedModel, ...remainingSuppor
 
 export type VendorModel = z.infer<typeof vendorModelSchema>
 
+/** Reasoning effort used when the caller leaves the model on automatic selection. */
+export const AI_CHAT_AUTO_REASONING_EFFORT = 'xhigh'
+
 export const robotAiChatInstructionsSchema = robotBase
   .merge(robotUse)
   .extend({
@@ -485,7 +488,7 @@ export const robotAiChatInstructionsSchema = robotBase
       .union([vendorModelSchema, z.literal('auto')])
       .default('auto')
       .describe(
-        'The model to use. Transloadit can pick the best model for the job if you set this to "auto".',
+        'The model to use. The default, "auto", uses Transloadit\'s configured default model; it does not select a model based on the attached file. Choose a model that supports your input files.',
       ),
     format: z.enum(['json', 'text', 'meta']).default('json'),
     return_messages: z.enum(['all', 'last']).default('last'),
@@ -503,19 +506,19 @@ export const robotAiChatInstructionsSchema = robotBase
       .enum(['xhigh', 'high', 'medium', 'low'])
       .optional()
       .describe(
-        'Controls how much effort the model spends on reasoning. Higher values produce more thorough responses but cost more tokens. Applies to models that support extended thinking (OpenAI o-series, GPT-5.x, GPT-6, Anthropic Claude with thinking). If omitted, the model default is used.',
+        `Controls how much effort the model spends on reasoning. Higher values produce more thorough responses but cost more tokens. Applies to models that support extended thinking (OpenAI o-series, GPT-5.x, GPT-6, Anthropic Claude with thinking). If omitted with model: "auto" (the default), Transloadit uses "${AI_CHAT_AUTO_REASONING_EFFORT}". With an explicitly selected model, omitting this parameter leaves reasoning effort to that model's default.`,
       ),
     credentials: z
       .union([z.string(), z.array(z.string())])
       .optional()
       .describe(
-        'Names of template credentials to make available to the robot. When using your own AI provider keys, Transloadit charges a 30% markup (minimum $0.0005 per request).',
+        'Names of Template Credentials to make available to the Robot. When using your own AI provider keys, you pay the provider directly and Transloadit charges a fee equal to 30% of the provider cost, with a minimum fee of $0.0005 per request.',
       ),
     test_credentials: z
       .boolean()
       .optional()
       .describe(
-        'Use Transloadit-provided credentials for testing. Usage is billed at provider cost plus a 30% markup (minimum $0.0005 per request).',
+        'Use Transloadit-provided credentials for testing. Transloadit bills the provider cost plus a 30% markup, with a minimum markup of $0.0005 per request.',
       ),
     mcp_servers: z
       .array(
@@ -534,7 +537,7 @@ export const robotAiChatInstructionsSchema = robotBase
       )
       .optional()
       .describe(
-        'The MCP servers to use for tool calling. You can use any MCP server reachable from your environment. Use `headers` to pass server-specific auth (for example `Authorization: Bearer <token>`). For Transloadit\'s MCP server: Bearer tokens minted via `/token` satisfy Signature Authentication (signature checks apply only to key/secret requests). `auth: "transloadit"` is reserved for API2-managed auth to Transloadit-hosted MCP servers.',
+        'The MCP servers to use for tool calling. The servers must be reachable from Transloadit\'s workers, not just from your own network. Use `headers` to pass server-specific auth (for example `Authorization: Bearer <token>`). For Transloadit\'s MCP server: Bearer tokens minted via `/token` satisfy Signature Authentication (signature checks apply only to key/secret requests). `auth: "transloadit"` is reserved for Transloadit-managed auth to Transloadit-hosted MCP servers.',
       ),
   })
   .strict()

package/src/alphalib/types/robots/audio-concat.ts

@@ -5,6 +5,7 @@ import { z } from 'zod'
 import { stackVersions } from '../stackVersions.ts'
 import {
   bitrateSchema,
+  getConcatFadeDescription,
   inputSortBySchema,
   interpolateRobot,
   robotAudioEncodingMeta,
@@ -73,11 +74,11 @@ This Robot can concatenate an almost infinite number of audio files.
       .describe(robotParameterDocs.audio_sample_rate.description),
     audio_fade_seconds: z
       .number()
-      .default(1)
+      .default(0)
       .describe(`
-When used this adds an audio fade in and out effect between each section of your concatenated audio file. The float value is used, so if you want an audio delay effect of 500 milliseconds between each video section, you would select 0.5. Integer values can also be represented.
+${getConcatFadeDescription('audio')}
 
-This parameter does not add an audio fade effect at the beginning or end of your result audio file. If you want to do so, create an additional [🤖/audio/encode](/docs/robots/audio-encode/) <dfn>Step</dfn> and use our \`ffmpeg\` parameter as shown in this [demo](/demos/audio-encoding/ffmpeg-fade-in-and-out/).
+When \`crossfade\` is \`true\`, this parameter controls the overlap between inputs instead of these separate fades. To add a fade-in at the beginning of the output, use an additional [audio encoding Step](/docs/robots/audio-encode/) with the \`ffmpeg\` parameter, as shown in the [fade-in and fade-out demo](/demos/audio-encoding/ffmpeg-fade-in-and-out/).
 `),
     crossfade: z
       .boolean()
@@ -85,7 +86,7 @@ This parameter does not add an audio fade effect at the beginning or end of your
       .describe(`
 When set to \`true\`, this parameter enables crossfading between concatenated audio files using FFmpeg's \`acrossfade\` filter. This creates a smooth transition where the end of one audio file overlaps and blends with the beginning of the next file.
 
-The duration of the crossfade is controlled by the \`audio_fade_seconds\` parameter (defaults to 1 second if \`audio_fade_seconds\` is 0).
+The \`audio_fade_seconds\` parameter controls the overlap duration. Omitting it or setting it to \`0\` uses a 1-second crossfade. Each overlap shortens the output by that duration; this mode does not add a fade-in at the beginning or a fade-out at the end.
 
 Note: This parameter requires at least 2 audio files to concatenate and only works with audio files, not video files.
 `),

package/src/alphalib/types/robots/azure-import.ts

@@ -22,8 +22,7 @@ import {
 export const meta: RobotMetaInput = {
   ...robotImportMeta,
   example_code: createStorageImportExample('/azure/import', 'YOUR_AZURE_CREDENTIALS', false),
-  example_code_description:
-    'Import files from the `path/to/files` directory and its subdirectories:',
+  example_code_description: 'Import files from the `path/to/files` directory:',
   has_small_icon: true,
   purpose_sentence: 'imports whole directories of files from your Azure container',
   purpose_word: 'Azure',
@@ -41,14 +40,14 @@ export const robotAzureImportInstructionsSchema = robotBase
     path: path.describe(`
 The path in your container to the specific file or directory. If the path points to a file, only this file will be imported. For example: \`images/avatar.jpg\`.
 
-If it points to a directory, indicated by a trailing slash (\`/\`), then all files that are descendants of this directory are recursively imported. For example: \`images/\`.
+If it points to a directory, indicated by a trailing slash (\`/\`), then files directly inside this directory are imported. For example: \`images/\`. Set \`recursive: true\` to include subdirectories.
 
 If you want to import all files from the root directory, please use \`/\` as the value here.
 
 You can also use an array of path strings here to import multiple paths in the same <dfn>Robot</dfn>'s <dfn>Step</dfn>.
 `),
     recursive: recursive.describe(`
-  Setting this to \`true\` will enable importing files from subdirectories and sub-subdirectories (etc.) of the given path.
+  Setting this to \`true\` will enable importing files from subdirectories and sub-subdirectories (etc.) of the given path. By default, only files directly inside the given directory are imported.
   `),
     next_page_token: next_page_token.describe(`
 A string token used for pagination. The returned files of one paginated call have the next page token inside of their meta data, which needs to be used for the subsequent paging call.

package/src/alphalib/types/robots/document-convert.ts

@@ -38,6 +38,11 @@ A generic LibreOffice load refusal returns \`USER_COMMAND_ERROR\` with the reaso
 When diagnostics identify a problem in the conversion service, the load failure returns \`INTERNAL_COMMAND_ERROR\` with the reason “${documentConvertLoadInternalErrorReason}” Private diagnostics are not included in either response.
 `
 
+const pdfAlternativesDocumentation = `
+> [!Note]
+> This <dfn>Robot</dfn> converts supported files to PDF, but does not convert PDF input to other formats. To render PDF pages as images, use [🤖/image/resize](/docs/robots/image-resize/). For native text extraction or OCR of PDF documents, use [🤖/document/extract](/docs/robots/document-extract/) and review its provider and input requirements. For OCR of images, use [🤖/image/ocr](/docs/robots/image-ocr/). These extraction Robots return recognized text; they do not add a searchable text layer to the original PDF.
+`
+
 export const meta: RobotMetaInput = {
   ...robotDocumentProcessingMeta,
   example_code: createProcessingExample('converted', '/document/convert', {
@@ -45,14 +50,13 @@ export const meta: RobotMetaInput = {
   }),
   example_code_description: 'Convert uploaded files to PDF documents:',
   extended_description: `
-> [!Note]
-> This <dfn>Robot</dfn> can convert files to PDF, but cannot convert PDFs to different formats. If you want to convert PDFs to say, JPEG or TIFF, use [🤖/image/resize](/docs/robots/image-resize/). If you want to turn them into text files or recognize (OCR) them to make them searchable, reach out, as we have a new <dfn>Robot</dfn> in the works for this.
+${pdfAlternativesDocumentation}
 
 Sometimes, a certain file type might not support what you are trying to accomplish. Perhaps your company is trying to automate document formatting, but it only works with docx, so all your docs need to be converted. Or maybe your stored jpg files are taking up too much space and you want a lighter format. Whatever the case, we have you covered.
 
 Using this <dfn>Robot</dfn>, you can bypass the issues that certain file types may bring, by converting your file into the most suitable format. This also works in conjunction with our other <dfn>Robots</dfn>, allowing for even greater versatility when using our services.
 
-> ![Warning]
+> [!Warning]
 > A general rule of this <dfn>Robot</dfn> is that converting files into an alien format category will result in an error. For example, SRT files can be converted into the VTT format, but not to an image.
 
 ${documentLoadErrorDocumentation}
@@ -122,8 +126,7 @@ export const robotDocumentConvertInstructionsSchema = robotBase
     robot: z.literal('/document/convert').describe(`
 ${htmlPdfReadinessDescription}
 
-> [!Note]
-> This Robot can convert files to PDF, but cannot convert PDFs to different formats. If you want to convert PDFs to say, JPEG or TIFF, use [🤖/image/resize](/docs/robots/image-resize/). If you want to turn them into text files or recognize (OCR) them to make them searchable, reach out, as we have a new Robot in the works for this.
+${pdfAlternativesDocumentation}
 
 Sometimes, a certain file type might not support what you are trying to accomplish. Perhaps your company is trying to automate document formatting, but it only works with docx, so all your docs need to be converted. Or maybe your stored jpg files are taking up too much space and you want a lighter format. Whatever the case, we have you covered.
 

package/src/alphalib/types/robots/document-extract.ts

@@ -19,7 +19,7 @@ import {
 const extractTargets = z.enum(['text', 'images'])
 const imageFormats = z.enum(['auto', 'original', 'png', 'jpg'])
 const ocrProviders = z.enum(['aws', 'gcp'])
-const textFormats = z.enum(['txt', 'json'])
+const textFormats = z.enum(['txt', 'json', 'md', 'html'])
 const textGranularities = z.enum(['document', 'page'])
 const textMethods = z.enum(['native', 'ocr', 'auto'])
 
@@ -120,6 +120,10 @@ export const robotDocumentExtractInstructionsSchema = robotBase
     robot: z.literal('/document/extract').describe(`
 Extracts native/selectable text and embedded raster image assets from PDF documents.
 
+For DOCX files, first use \`/document/convert\` with \`format: "pdf"\`, then pass its output to this Robot.
+
+Markdown and HTML output are in beta and aim for readable structure, not a pixel-perfect copy. Native extraction detects paragraphs, larger-font headings, simple lists and aligned tables where possible. Multi-column text can interleave, prose can be mistaken for tables, and merged cells may need adjustment. HTML escapes extracted text and omits source scripts, links and event handlers.
+
 This robot does not render full pages. If you need page images, use \`/document/thumbs\`. Vector graphics, charts, and page backgrounds are not always embedded raster images and may therefore not be returned by this robot.
 `),
     extract: z
@@ -163,7 +167,19 @@ OCR modes currently cannot be combined with \`password\`.
 OCR provider to use when \`text_method\` is \`"ocr"\` or \`"auto"\`. Valid values are \`"aws"\` and \`"gcp"\`.
 `),
     text_format: textFormats.default('txt').describe(`
-Output format for extracted text. Use \`"txt"\` for plain text or \`"json"\` for structured output.
+Output format for extracted text. Plain text and JSON retain the existing extraction behavior. Markdown and HTML output are in beta and infer basic structure from native text positions and font sizes.
+
+Native Markdown and HTML extraction limits layout data to 8 MiB per input document, summed across its selected page ranges. For larger documents, use separate extraction Steps with fewer pages in each Step’s \`page_range\`.
+
+If native extraction cannot confirm the reading order of bidirectional text, it returns a validation error. Try fewer pages or use \`text_method: "ocr"\` with an OCR provider.
+
+When \`extract\` includes images, Markdown and HTML reference retained image results inline using relative, URL-encoded filenames matching each image result’s \`name\`. Save the text and image results together to resolve the references. Filtered images have no references; repeated images can reference the same deduplicated result. Images with unavailable or inconsistent positions, including retained image masks, are appended after their page’s text. Embedded base64 images are not produced.
+
+When exporting, preserve result names in a shared directory per input document. For example, set \`/s3/store\`’s \`path\` to \`"\${assembly.id}/\${file.original_id}/\${file.name}"\`. Default storage paths using \`\${unique_prefix}/\${file.url_name}\` separate and rename files, so they do not preserve these relative image links.
+
+Some native image encodings cannot be displayed by browsers or Markdown viewers. Set \`image_format\` to \`"png"\` or \`"jpg"\` for broadly viewable image results.
+
+OCR Markdown and HTML preserve readable text with minimal structure detection and append extracted images in source order, since reliable text positions are unavailable.
 `),
     text_granularity: textGranularities.default('document').describe(`
 Controls text output grouping for native extraction.

package/src/alphalib/types/robots/document-split.ts

@@ -6,6 +6,7 @@ import type {
 
 import { z } from 'zod'
 
+import { expressionEvaluationUsageMebibytes } from '../templateValues.ts'
 import {
   createProcessingExample,
   defineRobot,
@@ -32,13 +33,27 @@ export const meta: RobotMetaInput = {
 export const robotDocumentSplitInstructionsSchema = robotBase
   .merge(robotUse)
   .extend({
-    robot: z.literal('/document/split'),
+    robot: z.literal('/document/split').describe(`
+By default, this Robot returns one PDF containing the selected pages and keeps the input file name. If \`pages\` is omitted, that PDF contains every page.
+
+Set \`split: true\` to return separate PDFs. Without \`pages\`, each page becomes its own PDF. With \`pages\`, each entry becomes one PDF: \`pages: ["1", "2-3"]\` returns a one-page PDF and a two-page PDF. For an input named \`document.pdf\`, these files are named \`document_page_1.pdf\` and \`document_pages_2-3.pdf\`. Repeated selections receive an additional numeric suffix to keep file names unique, such as \`document_page_1_2.pdf\`.
+
+Page numbers start at 1. When the page count is known, ranges are clamped to it and selections entirely beyond it are skipped. Split file names use the resulting page or range. An empty \`pages\` array is invalid in split mode; omit \`pages\` to split every page. If all selections exceed the page count, processing fails with a validation error.
+`),
     pages: z
       .union([z.string(), z.array(z.string())])
       .describe(
-        'The pages to select from the input PDF and to be included in the output PDF. Each entry can be a single page number (e.g. 5), or a range (e.g. `5-10`). Page numbers start at 1. By default all pages are extracted.',
+        `The pages to select from the input PDF. Each entry can be a single page number (e.g. \`5\`) or a range (e.g. \`5-10\`). Page numbers start at 1. Accepts an array or a comma-separated string. By default, all selected pages are combined into one PDF; with \`split: true\`, each entry produces a separate PDF. If omitted, selects all pages.
+
+For a PDF with at least three pages, \`pages: ["\${file.meta.page_count - 2}-\${file.meta.page_count}"]\` selects the last three pages. Each dynamically evaluated expression adds ${expressionEvaluationUsageMebibytes} MiB of usage per input file; simple variable references such as \`\${file.meta.page_count}\` are free.`,
       )
       .optional(),
+    split: z
+      .boolean()
+      .default(false)
+      .describe(
+        'Return one PDF per `pages` entry, or one PDF per page when `pages` is omitted. File names include a page or range suffix, such as `document_page_1.pdf` or `document_pages_2-3.pdf`. Split selections and output PDFs are subject to the service’s per-Job file limit. By default, returns one PDF containing all selected pages and keeps the input file name.',
+      ),
   })
   .strict()
 

package/src/alphalib/types/robots/file-decompress.ts

@@ -69,6 +69,8 @@ This <dfn>Robot</dfn> also detects and handles any of the following before evalu
 
 For security reasons, archives containing symlinks that point outside the archived directory will cause the <dfn>Assembly</dfn> to fail.
 
+Extracted file and directory names are transliterated for supported accented Latin and Cyrillic characters. For example, \`café.pdf\` becomes \`cafe.pdf\`.
+
 Password-protected archives (ZIP with ZipCrypto or AES encryption, RAR encrypted, 7z with AES-256) are supported via the \`password\` parameter.
 `),
     ignore_errors: