Gordon DHI migration (#23011)

Author: ArthurFlag

content/includes/gordondhi.md

@@ -0,0 +1,28 @@
+1. Ensure Gordon is [enabled](/manuals/ai/gordon.md#enable-ask-gordon).
+1. In Gordon's Toolbox, ensure Gordon's [Developer MCP toolkit is enabled](/manuals/ai/gordon/mcp/built-in-tools.md#configuration).
+1. In the terminal, navigate to the directory containing your Dockerfile.
+1. Start a conversation with Gordon:
+   ```bash
+   docker ai
+   ```
+1. Type:
+   ```console
+   "Migrate my dockerfile to DHI"
+   ```
+1. Follow the conversation with Gordon. Gordon will edit your Dockerfile, so when
+   it requests access to the filesystem and more, type `yes` to allow Gordon to proceed.
+
+   > [!NOTE]
+   > To learn more about Gordon's data retention and the data it
+   > can access, see [Gordon](/manuals/ai/gordon.md#what-data-does-gordon-access).
+
+When the migration is complete, you see a success message:
+
+```text
+The migration to Docker Hardened Images (DHI) is complete. The updated Dockerfile
+successfully builds the image, and no vulnerabilities were detected in the final image.
+The functionality and optimizations of the original Dockerfile have been preserved.
+```
+
+> [!IMPORTANT]
+> As with any AI tool, you must verify Gordon's edits and test your image.

content/manuals/ai/gordon/_index.md

@@ -20,12 +20,13 @@ of the Docker ecosystem.
 
 ## Key features
 
-Ask Gordon provides AI-powered assistance within Docker tools. It can:
+Ask Gordon provides AI-powered assistance in Docker tools. It can:
 
 - Improve Dockerfiles
 - Run and troubleshoot containers
 - Interact with your images and code
 - Find vulnerabilities or configuration issues
+- Migrate a Dockerfile to use [Docker Hardened Images](/manuals/dhi/_index.md)
 
 It understands your local environment, including source code, Dockerfiles, and
 images, to provide personalized and actionable guidance.
@@ -104,9 +105,10 @@ If you have concerns about data collection or usage, you can
 
 ## Using Ask Gordon
 
-The primary interfaces to Docker's AI capabilities are through the **Ask
-Gordon** view in Docker Desktop, or if you prefer to use the CLI: the `docker
-ai` CLI command.
+You can access Gordon:
+
+- In Docker Desktop, in the **Ask Gordon** view.
+- Via the Docker CLI, with the `docker ai` CLI command.
 
 Once you've enabled the Docker AI features, you'll also find references to **Ask
 Gordon** in various other places throughout the Docker Desktop user interface.
@@ -122,6 +124,7 @@ ways things you can try:
 - [Troubleshoot a crashed container](#troubleshoot-a-crashed-container)
 - [Get help with running a container](#get-help-with-running-a-container)
 - [Improve a Dockerfile](#improve-a-dockerfile)
+- [Migrate a Dockerfile to DHI](#migrate-a-dockerfile-to-dhi)
 
 For more examples, try asking Gordon directly. For example:
 
@@ -197,6 +200,17 @@ across several dimensions:
 - Portability
 - Resource efficiency
 
+### Migrate a Dockerfile to DHI
+
+Migrating your Dockerfile to use [Docker Hardened Images](/manuals/dhi/_index.md) helps you build
+more secure, minimal, and production-ready containers. DHIs are designed to
+reduce vulnerabilities, enforce best practices, and simplify compliance, making
+them a strong foundation for secure software supply chains.
+
+To request Gordon's help for the migration:
+
+{{% include "gordondhi.md" %}}
+
 ## Disable Ask Gordon
 
 ### For individual users

content/manuals/dhi/features/integration.md

@@ -78,4 +78,4 @@ and CI to scanning and deployment. They:
 - Include security metadata that plugs into your existing compliance systems
 
 This means you can adopt stronger security controls without disrupting your
-engineering workflows.
+engineering workflows.

content/manuals/dhi/how-to/migrate.md

@@ -9,7 +9,9 @@ keywords: migrate dockerfile, hardened base image, multi-stage build, non-root c
 {{< summary-bar feature_name="Docker Hardened Images" >}}
 
 This guide helps you migrate your existing Dockerfiles to use Docker Hardened
-Images (DHIs). DHIs are minimal and security-focused, which may require
+Images (DHIs) [manually](#step-1-update-the-base-image-in-your-dockerfile),
+or with [Gordon](#use-gordon).
+DHIs are minimal and security-focused, which may require
 adjustments to your base images, build process, and runtime configuration.
 
 This guide focuses on migrating framework images, such as images for building
@@ -240,3 +242,10 @@ ENTRYPOINT [ "python", "/app/image.py" ]
 
 {{< /tab >}}
 {{< /tabs >}}
+
+### Use Gordon
+
+Alternatively, you can request assistance to 
+[Gordon](/manuals/ai/gordon/_index.md), Docker's AI-powered assistant, to migrate your Dockerfile:
+
+{{% include "gordondhi.md" %}}