diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-deploy.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-deploy.mdx
index 578f53ae0..1f4a37e84 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-deploy.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-deploy.mdx
@@ -33,6 +33,16 @@ The command performs the following steps to deploy an app orchestrated with Aspi
 - Starts the AppHost and its resources.
 - Executes the `deploy` pipeline step, and any dependent steps, registered in the app model.
 
+### Local container image builds
+
+When your deployment pipeline containerizes a .NET project, the .NET container build step builds the image locally on the machine running `aspire deploy`, before the image is pushed to a registry or deployed to the target environment.
+
+:::caution[Match the container OS]
+When the build uses your local container runtime, its OS mode must match the OS of the image configured for the resource in your AppHost: Linux containers for Linux images, or Windows containers for Windows images. This is the container runtime's mode, not necessarily your host operating system.
+
+On Windows, if your AppHost targets Linux images, select **Switch to Linux containers** from the Docker Desktop menu before running `aspire deploy`. Leaving Docker Desktop in Windows containers mode can cause the local image build to fail, even when the deployment target runs Linux.
+:::
+
 ## Pipeline summary output
 
 After the pipeline finishes, `aspire deploy` prints a result summary and a step-by-step breakdown. The summary shows how many steps succeeded, the total pipeline duration, and a `Steps Summary:` table.
diff --git a/src/frontend/tests/unit/cli-container-builds.vitest.test.ts b/src/frontend/tests/unit/cli-container-builds.vitest.test.ts
new file mode 100644
index 000000000..4739b50aa
--- /dev/null
+++ b/src/frontend/tests/unit/cli-container-builds.vitest.test.ts
@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, test } from 'vitest';
+
+const source = readFileSync(
+  new URL('../../src/content/docs/reference/cli/commands/aspire-deploy.mdx', import.meta.url),
+  'utf8',
+);
+
+describe('CLI deployment container prerequisites', () => {
+  test('explains that .NET container images are built locally before deployment', () => {
+    expect(source).toMatch(/\.NET container build step[^.\n]*locally[^.\n]*`aspire deploy`/);
+  });
+
+  test('warns about matching the container runtime OS and switching Docker Desktop mode', () => {
+    const caution = source.match(/:::caution\[Match the container OS\]\n([\s\S]*?)\n:::/)?.[1];
+
+    expect(caution).toBeDefined();
+    expect(caution).toMatch(/OS mode must match[^.\n]*AppHost/);
+    expect(caution).toContain('Linux containers for Linux images');
+    expect(caution).toContain('Windows containers for Windows images');
+    expect(caution).toContain('Docker Desktop');
+    expect(caution).toContain('Switch to Linux containers');
+  });
+});