[Images] Document transformation flows

src/content/docs/images/index.mdx

@@ -67,6 +67,10 @@ If you’re new to Images, start here to learn the essentials:
 	Browse the various features for compressing, cropping, resizing, and manipulating images.
 </Feature>
 
+<Feature header="Flows" href="/images/optimization/features" cta="Use flows">
+	Create transformation flows to configure automated rules for optimizing remote images on your zone.
+</Feature>
+
 <Feature
 	header="Storage"
 	href="/images/storage/upload-images/methods"

src/content/docs/images/optimization/features.mdx

@@ -124,7 +124,7 @@ To [serve responsive images](/images/optimization/make-responsive-images/), you
 - Maximum of 960 pixels for tablets.
 - Maximum of 640 pixels for mobile phones.
 
-For example, `fit=scale-down,width=1920` sets a maximum size of 1920 px and ensures that the image will not be enlarged unnecessarily.
+For example, `fit=scale-down,width=1920` sets a maximum size of 1920px and ensures that the image will not be enlarged unnecessarily.
 
 You can detect device type by enabling the `CF-Device-Type` header [via Cache Rule](/cache/how-to/cache-rules/examples/cache-device-type/).
 

src/content/docs/images/optimization/transformations/bindings.mdx

@@ -3,7 +3,7 @@ pcx_content_type: how-to
 title: Bind to Workers API
 description: Bind the Cloudflare Images API to a Worker to transform images without requiring a public URL.
 sidebar:
-  order: 4
+  order: 5
 products:
   - images
   - workers

src/content/docs/images/optimization/transformations/control-origin-access.mdx

@@ -3,7 +3,7 @@ pcx_content_type: reference
 title: Control origin access
 description: Hide original image sources and restrict access using Cloudflare Workers with image transformations.
 sidebar:
-  order: 5
+  order: 6
 products:
   - images
   - workers

src/content/docs/images/optimization/transformations/draw-overlays.mdx

@@ -3,7 +3,7 @@ pcx_content_type: reference
 title: Draw overlays and watermarks
 description: Add watermarks, logos, and overlay images on top of transformed images using Cloudflare Workers.
 sidebar:
-  order: 6
+  order: 7
 products:
   - images
   - workers

src/content/docs/images/optimization/transformations/flows.mdx

@@ -0,0 +1,135 @@
+---
+pcx_content_type: reference
+title: Create transformation flows
+sidebar:
+  order: 3
+  products:
+    - images
+---
+import { Description, Render } from "~/components";
+
+<Description>
+	Define automated rules to optimize remote images without writing any code or changing your existing URLs.
+</Description>
+
+Flows let you automatically apply image optimization to requests on your zone.
+
+Each flow pairs a set of conditional triggers (for example, image is a JPEG or PNG) with optimization parameters (for example, transcode to AVIF).
+
+When an image request matches a flow, Cloudflare transparently rewrites it through the Images service and serves the optimized result.
+
+## Types of flows
+
+You can use pre-built flows to handle migrations from other image optimization services (like Fastly) or create your own custom flows.
+
+A **provider flow** is a translation layer that maps image URLs from another image optimization service to Cloudflare. Your existing URLs — including provider-specific parameters — continue to work without any changes.
+
+Currently, Cloudflare supports flows for Fastly Image Optimizer. When enabled, Cloudflare automatically translates Fastly's parameters to their Cloudflare equivalents. For example:
+
+- Fastly's `brightness` parameter accepts a range from `-100` to `100`, while Cloudflare's `brightness` works as a multiplier. The value is scaled accordingly.
+- Fastly's `orient` parameter is mapped to Cloudflare's `flip` and `rotate` parameters.
+
+A **custom flow** lets you define your own conditions and actions for image optimization.
+
+This is well-suited for situations where you want to optimize your images broadly and consistently, such as:
+- **Automatic format conversion** — Transcode all images to modern formats like AVIF or WebP across your entire site.
+- **Responsive sizing** — Automatically resize images based on each user's device.
+- **Directory-based optimization** — Enforce a consistent size for all images in a particular path, such as 100x100 for images where the path contains `/thumbnail`.
+
+## How flows work
+
+Before setting up a flow, make sure that transformations are turned on for your zone under **Images** > **Transformations** in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/images/transformations).
+
+When an image is requested on your zone, Cloudflare checks to see whether the request matches the conditions for any of your configured flows:
+- Flows are evaluated from top to bottom in the order that they appear in the dashboard.
+- If a request matches more than one flow, only the first matching flow will run.
+- If no flow matches, then the request passes through to your origin unmodified.
+- To control priority, you can reorder flows in the dashboard.
+
+If the request matches a flow's conditions, then Cloudflare rewrites the URL to pass through the Images service with the specified parameters:
+- A custom flow triggers only on requests for [supported image extensions](/images/get-started/limits/). HTML pages, CSS files, and other non-images are never affected.
+- A provider flow evaluates requests based on provider-specific optimization parameters. For example, a Fastly provider flow triggers only when the request contains parameters like `?width`, `?height`, or `?fit`. Cloudflare will ignore any unrecognized parameters.
+
+In your request lifecycle, flows are evaluated after standard HTTP [redirect rules](/rules/url-forwarding/):
+- Any existing URL rewrites or redirect rules will be applied before Images evaluates the request, which may affect matching behavior.
+- Flows include built-in loop prevention. If the request is already coming from the Images service, then the flow will not re-trigger on that subrequest.
+
+## Set up a provider flow
+
+Currently, Cloudflare supports flows to handle migrations from Fastly Image Optimizer.
+
+To add a provider flow:
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
+2. Go to **Images** > **Transformations** and select your zone.
+3. Select the **Automation** tab, then select **Add provider flow**.
+4. Choose **Fastly** as the provider.
+5. **Save** your flow.
+
+## Set up a custom flow
+
+### 1. Create a new flow
+
+In the Cloudflare dashboard, go to [**Images** > **Transformations**](https://dash.cloudflare.com/?to=/:account/images/transformations) and select the zone where you want to set up the custom flow.
+
+Go to the **Automation** tab and select **Add custom flow** to open the side panel where you can configure your flow.
+
+![Custom flow configuration panel](~/assets/images/images/custom-flow.png)
+
+### 2. Configure the conditions
+
+A custom flow is triggered when an incoming request matches all of the configured conditions in the flow:
+
+- **File extension** — Match requests for all image formats or only specific file extensions, such as JPEG, PNG, or WebP.
+- **URL path** — Match requests where the URL path matches a specified pattern, such as `/images/*` or `/assets/thumbnails/*`.
+- **Query parameter** — Match requests where the query string contains a specified parameter, such as `orient`.
+
+### 3. Configure the actions
+
+Next, define the optimization parameters that should be applied when the flow is triggered.
+
+You can apply multiple actions within a single flow. For the full list of available parameters, refer to [Features](/images/optimization/features/).
+
+The key parameters for most use cases are:
+
+#### `format` | `f`
+
+Set `format=auto` to automatically serve images in the most efficient format (e.g. AVIF, WebP) for each requesting browser.
+
+If the browser doesn't support AVIF, then Cloudflare will fall back to WebP or a standard format.
+
+Refer to [`format`](/images/optimization/features/#format)
+
+#### `quality` | `q`
+
+Control the compression quality of the output image. Accepts either:
+
+- A **fixed value** from `1` (low quality, small file size) to `100` (high quality, large file size).
+- A **perceptual quality level**: `high`, `medium-high`, `medium-low`, or `low`.
+
+Refer to [`quality`](/images/optimization/features/#quality)
+
+#### `slow-connection-quality` | `scq`
+
+Override `quality` when a slow connection is detected via client hints. Accepts the same fixed or perceptual values as `quality`. This serves lower-quality (and smaller) images to users on slow networks without affecting users on fast connections.
+
+Refer to [`slow-connection-quality`](/images/optimization/features/#slow-connection-quality)
+
+#### `width` | `w`
+
+Set [`width=auto`](/images/optimization/features/#width) to automatically size images based on the requesting device.
+
+Cloudflare determines the optimal width using either [client hints](/images/optimization/make-responsive-images/#client-hints-preferred) (sent by the browser) or user-agent detection as a fallback.
+
+You can fine-tune the `width=auto` behavior with the following sub-parameters:
+
+| Sub-parameter | Description | Default |
+| --- | --- | --- |
+| `wbreakpoints` | Override default breakpoint widths, in pixels (client hints) | `320;768;960;1200` |
+| `wmobile` | Override default width, in pixels, for mobile devices (user-agent detection) | `768` |
+| `wdesktop` | Override default width, in pixels, for desktop devices (user-agent detection) | `1200` |
+
+To learn how `width=auto` works, refer to our guide on [serving responsive images](/images/optimization/make-responsive-images/).
+
+### 4. Publish your flow
+
+Select **Save** on the side panel to add your custom flow, then select **Save** on your list of flows to turn on your flow.

src/content/docs/images/optimization/transformations/overview.mdx

@@ -41,5 +41,6 @@ Each unique combination of source image and parameters is cached and billed sepa
 After enabling transformations on your zone, you can configure how Cloudflare handles transformation requests:
 
 - **[Define source origins](/images/optimization/transformations/sources)** — Specify which origins Cloudflare can pull source images from. By default, Cloudflare only accepts source images from the same zone where transformations are served.
+- **[Create transformation flows](/images/optimization/transformations/flows)** — Set up automated rules that apply image optimization to matching requests without requiring URL changes or custom code.
 - **[Control origin access](/images/optimization/transformations/control-origin-access)** — Use Workers to add custom logic for validating and controlling access to source images.
 - **[Set up rewrite rules](/images/optimization/transformations/rewrite-rules)** — Use Transform Rules to rewrite image URLs and serve transformations from custom paths.

src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx

@@ -3,7 +3,7 @@ pcx_content_type: reference
 title: Preserve Content Credentials
 description: Retain C2PA metadata and provenance data when transforming remote images with Cloudflare Images.
 sidebar:
-  order: 7
+  order: 10
 products:
   - images
 ---

src/content/docs/images/optimization/transformations/transform-via-workers.mdx

@@ -3,7 +3,7 @@ pcx_content_type: how-to
 title: Transform via Workers
 description: Use Cloudflare Workers to programmatically resize, format, and optimize images with custom URL schemes.
 sidebar:
-  order: 3
+  order: 4
 products:
   - images
   - workers

src/content/partials/images/dpr.mdx

@@ -9,7 +9,7 @@ import dpr2Img from "~/assets/images/images/examples/dpr-2.jpg";
 
 Scales the output resolution by a multiplier to match a user's specific screen density (for example, Retina or 4K). The default is `1`, which delivers the image at the exact width and height requested. The maximum supported value is `2`.
 
-Modern devices have more physical pixels than CSS pixels. If you serve a 300 px image in a 300 px container on a high-DPR smartphone, then it will look blurry. Using `dpr=2` tells Cloudflare to send a 600 px image for the same 300 px container, which results in a clearer, crisper image.
+Modern devices have more physical pixels than CSS pixels. If you serve a 300px image in a 300px container on a high-DPR smartphone, then it will look blurry. Using `dpr=2` tells Cloudflare to send a 600px image for the same 300px container, which results in a clearer, crisper image.
 
 The `dpr` parameter can be used with `srcset` to [serve responsive images](/images/optimization/make-responsive-images/).
 

src/content/partials/images/fit.mdx

@@ -16,34 +16,38 @@ import squeezePete from "~/assets/images/images/examples/fit/pete-squeeze.jpg";
 
 Specifies how the image is fit to the target area.
 
-Fit is performed after setting the [`width`](/images/optimization/features/#width) and [`height`](/images/optimization/features/#height) dimensions of the image.
+Fit is performed after setting the [`width`](#width) and [`height`](#height) dimensions of the image.
 
 | Option | Result | Match original aspect ratio | Upscales |
 | --- | --- | --- | --- |
-| `contain` (default) | Show entire image without cropping | Yes | Yes |
+| `scale-down` (default) | Show entire image without cropping or upscaling | Yes | No |
+| `contain` | Show entire image without cropping | Yes | Yes |
 | `cover` | Fill the entire requested area, cropping if needed | No | Yes |
-| `crop` | Same as `cover`, but never upscales | No | No |
+| `crop` | Fill the entire requested area, but never upscales | No | No |
 | `pad` | Fit within the target area, adding space for remaining area | Yes | Yes |
-| `scale-down` | Same as `contain`, but never upscales | Yes | No |
 | `squeeze` | Scale to exact dimensions, distorting if needed | No | Yes |
 
 <Tabs>
   <TabItem label="URL format">
     ```txt
-    fit=scale-down
+    fit=pad
     ```
   </TabItem>
   <TabItem label="Workers">
   ```js
-  cf: {image: {fit: "scale-down"}}
+  cf: {image: {fit: "pad"}}
   ```
   </TabItem>
 </Tabs>
 
-#### `contain`
-Resizes the image to be as large as possible within the target `width` and `height` dimensions while preserving its original aspect ratio. This is the default `fit` behavior.
+#### `scale-down`
+Resizes the image to fit within the specified dimensions while preserving its original aspect ratio, but never upscales the image. This is the default `fit` behavior.
+
+When the original image is smaller than the target area, it is returned at its original dimensions. For example, a request to serve a 1080x720 image at 2000x2000 will return the image at 1080x720.
 
-In the example below, the 1080x720 image is resized to fit within the target 500x500 area. Since `contain` preserves original aspect ratio (3:2), the final dimensions of the output image are 500x333.
+When larger, it downscales the image to fit the target area while matching the original aspect ratio.
+
+In the example below, the 1080x720 image is resized to fit within the target 500x500 area. Since `scale-down` preserves the original aspect ratio (3:2), the final dimensions of the output image are 500x333.
 
 <table style="width:100%; text-align:center; border:none">
   <tr style="border:none; background:none">
@@ -54,7 +58,7 @@ In the example below, the 1080x720 image is resized to fit within the target 500
       <img src={lg.src} alt="target area" style="width:100%; height:auto" />
     </td>
     <td style="border:none; width:24%; vertical-align:bottom">
-      <img src={peteContain.src} alt="fit=contain output" style="width:100%; height:auto" />
+      <img src={peteContain.src} alt="fit=scale-down output" style="width:100%; height:auto" />
     </td>
   </tr>
   <tr style="border:none; background:none">
@@ -73,12 +77,17 @@ In the example below, the 1080x720 image is resized to fit within the target 500
   </tr>
 </table>
 
-When the original image is smaller than the target area, it upscales instead, which may reduce image quality. To avoid upscaling, use `scale-down`.
+#### `contain`
+Resizes the image to be as large as possible within the target `width` and `height` dimensions while preserving its original aspect ratio.
+
+When the original image is larger than the target area, it downscales to fit the target area (like `scale-down`).
+
+When smaller, it upscales instead, which may reduce image quality. To avoid upscaling, use `scale-down`.
 
 #### `cover`
 Fills the entire target area, shrinking or enlarging the image if needed. The output area always matches the requested `width` and `height` dimensions exactly.
 
-When the original and target aspect ratios differ, the image is resized to cover the full target area and any overflow is cropped. Use the [`gravity`](/images/optimization/features/#gravity) parameter to control which part of the image is preserved during cropping.
+When the original and target aspect ratios differ, the image is resized to cover the full target area and any overflow is cropped. Use the [`gravity`](#gravity) parameter to control which part of the image is preserved during cropping.
 
 In the example below, the 1080×720 image is first resized to 750×500 (matching the requested height) to fit the target area, then cropped from the left and right edges to its final 500x500 dimensions.
 
@@ -115,7 +124,7 @@ When the original image is smaller than the target area, it upscales instead. To
 #### `crop`
 Resizes the image to fill the target area without upscaling.
 
-When the original image is smaller than the target area, it is returned at its original dimensions and does not upscale.
+When the original image is smaller than the target area, it keeps its original size and aspect ratio (like `scale-down`).
 
 In the example below, the original image (1080x720) is smaller than the target area (1296x1296), so it preserves its original size and aspect ratio.
 
@@ -184,15 +193,10 @@ In the example below, the original image (1080x720) is smaller than the target a
   </tr>
 </table>
 
-#### `scale-down`
-Resizes the image to fit within the specified dimensions while preserving its original aspect ratio, but never upscales the image.
-
-When the original image is smaller than the target area, it behaves like `crop` (keeps original size and aspect ratio). When larger, it behaves like `contain` (downscaled to fill the target area).
-
 #### `squeeze`
 Resizes the image to exactly match the requested width and height, without cropping the edges or constraining the portions.
 
-When the original and target aspect ratios differ, the image will be distorted to fit the target area. 
+When the original and target aspect ratios differ, the image will be distorted to fit the target area.
 
 <table style="width:100%; text-align:center; border:none">
   <tr style="border:none; background:none">
@@ -234,4 +238,4 @@ When the original and target aspect ratios differ, the image will be distorted t
       1080 x 540
     </td>
   </tr>
-</table>
+</table>

src/content/partials/images/slow-connection-quality.mdx

@@ -8,7 +8,7 @@ import { Tabs, TabItem} from "~/components";
 
 ### `slow-connection-quality` | `scq`
 
-Overrides the `quality` value whenever a slow connection is detected. Accepts the same fixed or perceptual settings as [quality](/images/optimization/features/#quality). The default is none.
+Overrides the `quality` value whenever a slow connection is detected. Accepts the same fixed or perceptual settings as [quality](#quality). The default is none.
 
 :::note
 This feature is available only when optimizing through the URL interface on Chromium-based browsers such as Chrome, Edge, and Opera.

src/content/partials/images/trim.mdx

@@ -9,7 +9,7 @@ Removes pixels around the sides of an image.
 
 This feature can be used to trim an image by its border colors or by a specified number of pixels from its side(s).
 
-Trim takes into account the [`dpr`](/images/optimization/features/#dpr) parameter and is performed before resizing and rotation.
+Trim takes into account the [`dpr`](#dpr) parameter and is performed before resizing and rotation.
 
 #### `border`