transloadit 6.5.0 → 6.6.1

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:

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

@@ -12,6 +12,7 @@ import {
   complexWidthSchema,
   createProcessingExample,
   defineRobot,
+  imageQualityValueSchema,
   optimize_priority,
   resize_strategy,
   robotBase,
@@ -19,6 +20,17 @@ import {
   robotUse,
 } from './_instructions-primitives.ts'
 
+/** Fallback order shared by schema defaults, published examples and worker normalization. */
+export const filePreviewStrategyDefaults = {
+  archive: ['icon'],
+  audio: ['artwork', 'waveform', 'icon'],
+  document: ['page', 'icon'],
+  image: ['image', 'embedded-preview', 'icon'],
+  unknown: ['icon'],
+  video: ['artwork', 'frame', 'icon'],
+  webpage: ['render', 'icon'],
+}
+
 export const meta: RobotMetaInput = {
   ...robotMediaCatalogingMeta,
   example_code: createProcessingExample('previewed', '/file/preview', {
@@ -44,17 +56,20 @@ export const robotFilePreviewInstructionsSchema = robotBase
   .merge(robotUse)
   .extend({
     robot: z.literal('/file/preview').describe(`
-This <dfn>Robot</dfn>'s purpose is to generate a meaningful preview image for any file, in such a way that the resulting thumbnail highlights the file's content. The goal is not to losslessly present the original media in a smaller way. Instead, it is to maximize the chance of a person recognizing the media at a glance, while being visually pleasing and consistent with other previews. The generation process depends on the file type. For example, the <dfn>Robot</dfn> can extract artwork from media files, frames from videos, generate a waveform for audio files, and preview the content of documents and images. The details of all available strategies are provided in the next section.
+This <dfn>Robot</dfn>'s purpose is to generate a meaningful preview image for any file, in such a way that the resulting thumbnail highlights the file's content. The goal is not to losslessly present the original media in a smaller way. Instead, it is to maximize the chance of a person recognizing the media at a glance, while being visually pleasing and consistent with other previews. The generation process depends on the file type. For example, the <dfn>Robot</dfn> can extract artwork from media files, frames from videos, generate a waveform for audio files, and preview the content of documents and images. The [\`strategy\` parameter](#strategy) lists the available strategies and controls their fallback order.
 
-If no file-specific thumbnail can be generated because the file type is not supported, a generic icon containing the file extension will be generated.
+With the default strategy configuration, a generic icon is the fallback when no file-specific thumbnail can be generated. The default \`with-text\` icon style includes the file extension; \`icon_style\` and \`icon_text_content\` control its appearance.
 
-The default parameters ensure that the <dfn>Robot</dfn> always generates a preview image with the predefined dimensions and formats, to allow an easy integration into your application's UI. In addition, the generated preview images are optimized by default to reduce their file size while keeping their quality.
+The default parameters produce still previews at the configured dimensions and format for integration into your application's UI. The optional \`clip\` strategy produces animated previews using \`clip_format\`. Preview images are optimized by default to reduce their file size while maintaining visual quality.
 `),
     format: z
       .enum(['avif', 'gif', 'jpeg', 'jpg', 'png', 'webp'])
       .default('png')
       .describe(`
-The output format for the generated thumbnail image. AVIF and WebP are also supported. If a short video clip is generated using the \`clip\` strategy, its format is defined by \`clip_format\`.
+The output format for the generated thumbnail image. If a short video clip is generated using the \`clip\` strategy, its format is defined by \`clip_format\`.
+`),
+    quality: imageQualityValueSchema.optional().describe(`
+Compression quality for still previews, from 1 to 100. When specified, the final image resize encodes directly into the requested format at this quality and strips embedded metadata. Omit it to retain the default encoding behavior. Animated clips use their own encoding settings. If \`optimize\` is enabled, optimization runs after this encoding.
 `),
     width: complexWidthSchema.default(300).describe(`
 Width of the thumbnail, in pixels.
@@ -80,32 +95,36 @@ Note that this parameter only affects strategies that produce a still image. Ani
 `),
     strategy: z
       .object({
-        archive: z.array(z.string()).default(['icon']),
-        audio: z.array(z.string()).default(['artwork', 'waveform', 'icon']),
-        document: z.array(z.string()).default(['page', 'icon']),
-        image: z.array(z.string()).default(['image', 'icon']),
-        unknown: z.array(z.string()).default(['icon']),
-        video: z.array(z.string()).default(['artwork', 'frame', 'icon']),
-        webpage: z.array(z.string()).default(['render', 'icon']),
+        archive: z.array(z.string()).default(filePreviewStrategyDefaults.archive),
+        audio: z.array(z.string()).default(filePreviewStrategyDefaults.audio),
+        document: z.array(z.string()).default(filePreviewStrategyDefaults.document),
+        image: z.array(z.string()).default(filePreviewStrategyDefaults.image),
+        unknown: z.array(z.string()).default(filePreviewStrategyDefaults.unknown),
+        video: z.array(z.string()).default(filePreviewStrategyDefaults.video),
+        webpage: z.array(z.string()).default(filePreviewStrategyDefaults.webpage),
       })
       .optional()
       .describe(`
-Definition of the thumbnail generation process per file category. The parameter must be an object whose keys can be one of the file categories: \`audio\`, \`video\`, \`image\`, \`document\`, \`archive\`, \`webpage\`, and \`unknown\`. The corresponding value is an array of strategies for the specific file category. See the above section for a list of all available strategies.
+Definition of the thumbnail generation process per file category. Each key selects a file category and its value is an ordered array of strategies:
+
+| File category | Available strategies |
+|---------------|----------------------|
+| \`audio\` | \`artwork\`, \`waveform\`, \`icon\` |
+| \`video\` | \`artwork\`, \`frame\`, \`clip\`, \`icon\` |
+| \`image\` | \`image\`, \`embedded-preview\`, \`icon\` |
+| \`document\` | \`page\`, \`icon\` |
+| \`archive\` | \`icon\` |
+| \`webpage\` | \`render\`, \`icon\` |
+| \`unknown\` | \`icon\` |
+
+\`artwork\` extracts embedded artwork, \`waveform\` draws an audio waveform, \`frame\` extracts a video frame, and \`clip\` creates an animated video preview. For images, \`image\` resizes the original and \`embedded-preview\` extracts an embedded preview when available. \`page\` renders the first document page, \`render\` captures a webpage, and \`icon\` generates a file-type icon.
 
 For each file, the <dfn>Robot</dfn> will attempt to use the first strategy to generate the thumbnail. If this process fails (e.g., because no artwork is available in a video file), the next strategy is attempted. This is repeated until either a thumbnail is generated or the list is exhausted. Selecting the \`icon\` strategy as the last entry provides a fallback mechanism to ensure that an appropriate strategy is always available.
 
 The parameter defaults to the following definition:
 
 \`\`\`json
-{
-  "audio": ["artwork", "waveform", "icon"],
-  "video": ["artwork", "frame", "icon"],
-  "document": ["page", "icon"],
-  "image": ["image", "icon"],
-  "webpage": ["render", "icon"],
-  "archive": ["icon"],
-  "unknown": ["icon"]
-}
+${JSON.stringify(filePreviewStrategyDefaults, null, 2)}
 \`\`\`
 `),
     artwork_outer_color: color_with_alpha.optional().describe(`
@@ -163,13 +182,13 @@ The font family of the text used in the icon. Only used if the \`icon\` strategy
       .enum(['extension', 'none'])
       .default('extension')
       .describe(`
-The content of the text box in generated icons. Only used if the \`icon_style\` parameter is set to \`with-text\`. The default value, \`extension\`, adds the file extension (e.g. MP4, JPEG) to the icon. The value \`none\` can be used to render an empty text box, which is useful if no text should not be included in the raster image, but some place should be reserved in the image for later overlaying custom text over the image using HTML etc.
+The content of the text box in generated icons. Only used if the \`icon_style\` parameter is set to \`with-text\`. The default value, \`extension\`, adds the file extension (e.g. MP4, JPEG) to the icon. The value \`none\` leaves the text box empty while reserving space for a custom text overlay, for example using HTML in your application.
 `),
     optimize: z
       .boolean()
       .default(true)
       .describe(`
-Specifies whether the generated preview image should be optimized to reduce the image's file size while keeping their quaility. If enabled, the images will be optimized using [🤖/image/optimize](/docs/robots/image-optimize/).
+Specifies whether the generated preview image should be optimized to reduce its file size while maintaining visual quality. If enabled, the image will be optimized using [🤖/image/optimize](/docs/robots/image-optimize/).
 `),
     optimize_priority: optimize_priority.default('conversion-speed').describe(`
 Specifies whether conversion speed or compression ratio is prioritized when optimizing images. Only used if \`optimize\` is enabled. Please see the [🤖/image/optimize documentation](/docs/robots/image-optimize/#priority) for more details.
@@ -186,14 +205,14 @@ Specifies whether images should be interlaced, which makes the result image load
       .describe(`
 The animated image format for the generated video clip. Only used if the \`clip\` strategy for video files is applied.
 
-Please consult the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types) for detailed information about the image formats and their characteristics. GIF enjoys the broadest support in software, but only supports a limit color palette. APNG supports a variety of color depths, but its lossless compression produces large images for videos. AVIF is a modern image format that offers great compression, but proper support for animations is still lacking in some browsers. WebP on the other hand, enjoys broad support while offering a great balance between small file sizes and good visual quality, making it the default clip format.
+Please consult the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types) for detailed information about the image formats and their characteristics. GIF enjoys broad support in software, but only supports a limited color palette. APNG supports a variety of color depths, but its lossless compression produces large images for videos. AVIF offers efficient compression, but animation support varies between browsers. WebP offers a balance between small file sizes and visual quality and is the default clip format.
 `),
     clip_offset: z
       .number()
       .min(0)
       .default(1)
       .describe(`
-The start position in seconds of where the clip is cut. Only used if the \`clip\` strategy for video files is applied. Be aware that for larger video only the first few MBs of the file may be imported to improve speed. Larger offsets may seek to a position outside of the imported part and thus fail to generate a clip.
+The start position in seconds of where the clip is cut. Only used if the \`clip\` strategy for video files is applied. For large videos, only portions of the file may be imported to improve speed. An offset outside the available media data can prevent clip generation.
 `),
     clip_duration: z
       .number()

package/src/alphalib/types/robots/http-request.ts

@@ -7,6 +7,7 @@ import type {
 import { z } from 'zod'
 
 import {
+  createProcessingExample,
   defineRobot,
   httpHeaderSafetyDescription,
   httpUrlSchema,
@@ -17,17 +18,11 @@ import {
 
 export const meta: RobotMetaInput = {
   ...robotCodeEvaluationMeta,
-  example_code: {
-    steps: {
-      request: {
-        robot: '/http/request',
-        method: 'POST',
-        payload: 'metadata',
-        url: 'https://example.com/transloadit/files',
-        use: [],
-      },
-    },
-  },
+  example_code: createProcessingExample('request', '/http/request', {
+    method: 'POST',
+    payload: 'metadata',
+    url: 'https://example.com/transloadit/files',
+  }),
   example_code_description: 'Ask your application which input files should continue:',
   extended_description: `
 Use this <dfn>Robot</dfn> when your application should inspect the current Assembly state or input
@@ -56,7 +51,7 @@ in the Assembly Template and use this Step as their input.
 `,
   override_lvl1: 'Workflow Automation',
   purpose_sentence:
-    'calls your application during an Assembly and emits returned input file references',
+    'calls your application during an Assembly and emits selected input files or downloads returned result-file URLs',
   purpose_verb: 'run',
   purpose_word: 'HTTP endpoint',
   purpose_words: 'Call HTTP endpoints',
@@ -100,7 +95,8 @@ Controls what is sent to your endpoint.
 - \`file\`: Send multipart form data with a \`payload\` JSON field and the first input file as a
   \`file\` part.
 - \`files\`: Send multipart form data with a \`payload\` JSON field and all input files as repeated
-  \`files[]\` parts. Useful with \`bundle_steps\`.
+  \`files[]\` parts. To send several input files in one request, set \`bundle_steps: true\` in the
+  advanced [\`use\` options](/docs/topics/use-parameter/#step-bundling).
 
 The \`payload\` JSON object contains \`assembly\`, \`fields\`, \`previous_step\`, \`file\`, and
 \`files\`. \`file\` is the first input file’s metadata or \`null\`; \`files\` is an array of input

package/src/alphalib/types/robots/image-enhance.ts

@@ -77,11 +77,11 @@ export const robotImageEnhanceInstructionsSchema = robotBase
   .merge(robotImagemagick)
   .extend({
     robot: z.literal('/image/enhance').describe(`
-With this <dfn>Robot</dfn> you can automatically enhance images with one click — adjusting levels, contrast, saturation, sharpness, and white balance to produce an optimally balanced image. It also supports a library of named photo filter presets (e.g. \`warm\`, \`cool\`, \`vintage\`, \`vivid\`) that apply curated color grading and tone adjustments.
+With this <dfn>Robot</dfn> you can automatically enhance images by adjusting levels, gamma, and sharpness. The selected enhancement mode determines which adjustments are applied. It also supports named photo filter presets (e.g. \`warm\`, \`cool\`, \`vintage\`, \`vivid\`) for color grading and tone adjustments.
 
 It works well together with [🤖/image/resize](/docs/robots/image-resize/) — you can enhance first, then resize, or vice versa.
 
-This <dfn>Robot</dfn> accepts all image types supported by ImageMagick and passes unsupported types through unchanged. \`engine: "classic"\` uses \`enhance\`, \`preset\`, \`sharpen\`, and \`denoise\`, while \`engine: "ai"\` uses \`ai_preset\` and \`quality\`; classic controls are ignored in AI mode. Output keeps the original file extension when possible. In AI mode, if the target extension is not writable by the selected \`imagemagick_stack\`, the file is passed through unchanged.
+This <dfn>Robot</dfn> accepts all image types supported by ImageMagick and passes unsupported image types through unchanged. \`engine: "classic"\` uses \`enhance\`, \`preset\`, \`sharpen\`, and \`denoise\`, while \`engine: "ai"\` uses \`ai_preset\`; classic controls are ignored in AI mode. Both engines use \`quality\` for the output image. Output keeps the original file extension when possible. In AI mode, if the target extension is not writable by the selected \`imagemagick_stack\`, the file is passed through unchanged.
 `),
     enhance: enhanceModeSchema.describe(`
 The auto-enhancement mode. \`"auto"\` applies balanced auto-levels, gamma correction, and subtle sharpening. \`"auto_gentle"\` is more conservative (good for already-decent photos). \`"auto_aggressive"\` applies stronger normalization and contrast. \`"none"\` skips auto-enhance (useful when only applying a preset filter).

package/src/alphalib/types/robots/image-resize.ts

@@ -443,7 +443,7 @@ Changes the hue by rotating the color of the image. The value \`100\` would prod
       .max(2)
       .default(1)
       .describe(`
-Adjusts the contrast of the image. A value of \`1\` produces no change. Values below \`1\` decrease contrast (with \`0\` being minimum contrast), and values above \`1\` increase contrast (with \`2\` being maximum contrast). This works like the \`brightness\` parameter.
+Adjusts the contrast of the image. A value of \`1\` produces no change. Values below \`1\` decrease contrast, and values above \`1\` increase it. Start with small adjustments, such as \`0.9\` or \`1.1\`. Larger increases can clip shadows and highlights.
 `),
     watermark_url: httpUrlSchema.optional().describe(`
 A URL indicating a PNG image to be overlaid above this image. Please note that you can also  [supply the watermark via another Assembly Step](/docs/topics/use-parameter/#supplying-the-watermark-via-an-assembly-step). With watermarking you can add an image onto another image. This is usually used for logos.
@@ -480,6 +480,8 @@ Values can be both positive and negative and yield different results depending o
 The size of the watermark, as a percentage.
 
 For example, a value of \`"50%"\` means that size of the watermark will be 50% of the size of image on which it is placed. The exact sizing depends on \`watermark_resize_strategy\`, too.
+
+With \`watermark_repeat_x\` or \`watermark_repeat_y\`, this sizes each tile relative to the output image, before repeating it. It does not set the percentage of the image covered by the whole pattern. Smaller values produce more, smaller tiles. If omitted, the watermark keeps its original pixel dimensions.
 `),
     watermark_resize_strategy: z
       .enum(['area', 'fit', 'min_fit', 'stretch'])

package/src/alphalib/types/robots/image-upscale.ts

@@ -70,7 +70,7 @@ export const robotImageUpscaleInstructionsSchema = robotBase
     face_enhance: upscaleFaceEnhanceSchema
       .optional()
       .describe(
-        `Enable face enhancement for better face restoration. Defaults to ${upscaleFaceEnhanceSchema.parse(undefined)}.`,
+        `Enable face enhancement with Real-ESRGAN or face upsampling with CodeFormer. GFPGAN always performs face restoration and ignores this parameter. Defaults to ${upscaleFaceEnhanceSchema.parse(undefined)}.`,
       ),
   })
   .strict()

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

@@ -43,40 +43,39 @@ export const robotS3ImportInstructionsSchema = robotBase
     robot: z.literal('/s3/import').describe(`
 If you are new to Amazon S3, see our tutorial on [using your own S3 bucket](/docs/faq/how-to-set-up-an-amazon-s3-bucket/).
 
-The URL to the result file in your S3 bucket will be returned in the <dfn>Assembly Status JSON</dfn>.
-
-> [!Warning]
-> **Use DNS-compliant bucket names**. Your bucket name [must be DNS-compliant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) and must not contain uppercase letters. Any non-alphanumeric characters in the file names will be replaced with an underscore, and spaces will be replaced with dashes. If your existing S3 bucket contains uppercase letters or is otherwise not DNS-compliant, rewrite the result URLs using the <dfn>Robot</dfn>’s \`url_prefix\` parameter.
-
 <span id="minimum-s3-iam-permissions" aria-hidden="true"></span>
 
 ## Limit access
 
-You will also need to add permissions to your bucket so that Transloadit can access it properly. Here is an example IAM policy that you can use. Following the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), it contains the **minimum required permissions** to import a file from your S3 bucket using Transloadit. You may require more permissions (especially viewing permissions) depending on your application.
+Use dedicated AWS credentials in your <dfn>Template Credentials</dfn> and grant that IAM identity access only to the bucket and objects it needs. The following example is an **identity-based IAM policy** for reading current objects from one general purpose S3 bucket. Attach it to the IAM user or role whose credentials you supply to Transloadit, not to the bucket. An identity-based policy has no \`Principal\` element: it applies to the identity it is attached to.
 
-Please change \`{BUCKET_NAME}\` in the values for \`Sid\` and \`Resource\` accordingly. Also, this policy will grant the minimum required permissions to all your users. We advise you to create a separate Amazon IAM user, and use its User ARN (can be found in the "Summary" tab of a user [here](https://console.aws.amazon.com/iam/home#users)) for the \`Principal\` value. More information about this can be found [here](https://docs.aws.amazon.com/AmazonS3/latest/dev/AccessPolicyLanguage_UseCases_s3_a.html).
+Replace \`{BUCKET_NAME}\` in both \`Resource\` values with your bucket name. The bucket-level statement permits listing objects and discovering the bucket's region; the object-level statement permits downloading them. See [AWS's S3 operation permissions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-policy-actions.html) and [identity-based versus resource-based policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html).
 
 \`\`\`json
 {
   "Version": "2012-10-17",
   "Statement": [
     {
-      "Sid": "AllowTransloaditToImportFilesIn{BUCKET_NAME}Bucket",
+      "Sid": "ReadBucketMetadata",
       "Effect": "Allow",
       "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
-      "Resource": ["arn:aws:s3:::{BUCKET_NAME}", "arn:aws:s3:::{BUCKET_NAME}/*"]
+      "Resource": "arn:aws:s3:::{BUCKET_NAME}"
+    },
+    {
+      "Sid": "ReadBucketObjects",
+      "Effect": "Allow",
+      "Action": "s3:GetObject",
+      "Resource": "arn:aws:s3:::{BUCKET_NAME}/*"
     }
   ]
 }
 \`\`\`
 
-The \`Sid\` value is just an identifier for you to recognize the rule later. You can name it anything you like.
-
-The policy needs to be separated into two parts, because the \`ListBucket\` action requires permissions on the bucket while the other actions require permissions on the objects in the bucket. When targeting the objects there's a trailing slash and an asterisk in the \`Resource\` parameter, whereas when the policy targets the bucket, the slash and the asterisk are omitted.
+The \`Sid\` values are labels for recognizing statements. Supplying the correct \`bucket_region\` avoids automatic region discovery and its \`s3:GetBucketLocation\` permission. The example still grants bucket-wide listing and reads: narrow its object resources and listing conditions when your workflow needs only a specific prefix.
 
-In order to build proper result URLs we need to know the region in which your S3 bucket resides. For this we require the \`GetBucketLocation\` permission. Figuring out your bucket's region this way will also slow down your Assemblies. To make this much faster and to also not require the \`GetBucketLocation\` permission, we have added the \`bucket_region\` parameter to the /s3/store and /s3/import Robots. We recommend using them at all times.
+This example is not a guarantee of access. Explicit denies, organization policies, permission boundaries, cross-account bucket policies, and object ownership can affect the result. For cross-account access, review [AWS's policy evaluation guidance](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic-cross-account.html).
 
-Please keep in mind that if you use bucket encryption you may also need to add \`"sts:*"\` and \`"kms:*"\` to the bucket policy. Please read [here](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html) and [here](https://aws.amazon.com/blogs/security/how-to-restrict-amazon-s3-bucket-access-to-a-specific-iam-role/) in case you run into trouble with our example bucket policy.
+For SSE-KMS-encrypted objects, also configure the IAM identity and KMS key policy with the key permissions required by [AWS's GetObject documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html), scoped to the intended key. KMS actions belong in IAM identity policies and KMS key policies, **not S3 bucket policies**. Do not grant broad \`sts:*\` or \`kms:*\` permissions as a workaround.
 `),
     path: path.describe(`
 The path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example: \`images/avatar.jpg\`.
@@ -85,7 +84,7 @@ If it points to a directory, indicated by a trailing slash (\`/\`), then all fil
 
 Directories are **not** imported recursively. If you want to import files from subdirectories and sub-subdirectories, enable the \`recursive\` parameter.
 
-If you want to import all files from the root directory, please use \`/\` as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with \`/\`, you'll receive an error: \`A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.\`
+Use \`/\` to import files from the bucket root. Object keys do not need a leading slash. Enable \`recursive\` to include files under nested prefixes.
 
 You can also use an array of path strings here to import multiple paths in the same <dfn>Robot</dfn>'s <dfn>Step</dfn>.
 `),

package/src/alphalib/types/robots/supabase-store.ts

@@ -33,8 +33,30 @@ export const robotSupabaseStoreInstructionsSchema = robotBase
   .merge(robotUse)
   .merge(supabaseBase)
   .extend({
-    robot: z.literal('/supabase/store'),
+    robot: z.literal('/supabase/store').describe(`
+## Upload as a Supabase user
+
+For [Supabase session-token authentication](https://supabase.com/docs/guides/storage/s3/authentication#session-token), supply your project ref as \`key\`, your project’s anon key as \`secret\`, and the user’s access-token JWT as \`session_token\`. Supabase applies the authenticated user’s Row Level Security (RLS) policies to these uploads. Choose a \`path\` those policies permit, and use the endpoint and region from your project’s S3 connection settings.
+
+Send the user’s JWT with each Assembly from your trusted backend. It must remain valid through queuing, processing, and upload retries; the Robot does not refresh it. Without \`session_token\`, continue using your generated Supabase S3 access key and secret. Those generated S3 access keys bypass RLS.
+
+Supply \`session_token\` inline in the Step. Assembly Status returns \`fields\` unchanged, so passing the JWT through Assembly \`fields\` exposes it in the status response.
+
+The result URL uses Supabase’s public-object URL format. It does not grant read access to a private bucket; use Supabase’s download authorization for private objects.
+`),
+    credentials: supabaseBase.shape.credentials.describe(`
+The name of your Supabase <dfn>Template Credentials</dfn>, containing the bucket, host, key, secret, and bucket region. You can instead supply those parameters directly in the Step.
+
+For generated S3 access-key authentication, use the endpoint and S3 access keys from your Supabase project’s S3 connection settings. For user-scoped session-token authentication, use the project ref as \`key\` and the project’s anon key as \`secret\`, then supply the user’s access-token JWT as \`session_token\` with each Assembly.
+`),
     path: storeFilePath,
+    session_token: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(`
+The user’s Supabase access-token JWT for [session-token authentication](https://supabase.com/docs/guides/storage/s3/authentication#session-token). Use the Supabase project ref as \`key\` and the project’s anon key as \`secret\` so Supabase applies that user’s RLS policies. The JWT must remain valid through queuing, processing, and upload retries; the Robot does not refresh it. Supply this value directly in the Step; Assembly Status exposes values in \`fields\`.
+`),
     headers: z
       .record(z.string())
       .default({ 'Content-Type': '${file.mime}' })