docs: add troubleshooting guide for Docker.app is damaged dialog on macOS (#23523)

<!--Delete sections as needed -->

## Description

Addresses the non-atomic copy issue when other apps use Docker CLI
during a DMG drag-and-drop installation on macOS by:
- Adding a pre-install callout to the Mac install page with warnings
about closing apps that call Docker
- Created a dedicated troubleshooting page for the macOS "damaged app"
dialog issue
- Added cross-references from troubleshoot index and known issues pages

## Related issues or tickets

DKP-2447

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [x] Technical review
- [x] Editorial review
- [ ] Product review

---------

Co-authored-by: aevesdocker <[email protected]>

Author: andrei-z-albu

content/manuals/desktop/setup/install/mac-install.md

@@ -63,6 +63,16 @@ This page provides download links, system requirements, and step-by-step install
 {{< /tab >}}
 {{< /tabs >}}
 
+> **Before you install or update**
+>
+> - Quit tools that might call Docker in the background (Visual Studio Code, terminals, agent apps).
+>
+> - If you manage fleets or install via MDM, use the [**PKG installer**](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md).
+>
+> - Keep the installer volume mounted until the installation completes.
+>
+> If you encounter a "Docker.app is damaged" dialog, see [Fix "Docker.app is damaged" on macOS](/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md).
+
 ## Install and run Docker Desktop on Mac
 
 > [!TIP]

content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md

@@ -261,3 +261,4 @@ to learn how to view the Docker Daemon logs.
 
 - View specific [troubleshoot topics](topics.md).
 - View information on [known issues](known-issues.md)
+- [Fix "Docker.app is damaged" on macOS](mac-damaged-dialog.md) - Resolve macOS installation issues

content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md

@@ -3,7 +3,7 @@ description: Find known issues for Docker Desktop
 keywords: mac, troubleshooting, known issues, Docker Desktop
 title: Known issues
 tags: [ Troubleshooting ]
-weight: 30
+weight: 20
 aliases:
  - /desktop/troubleshoot/known-issues/
 ---
@@ -12,6 +12,8 @@ aliases:
 {{< tab name="For Mac with Intel chip" >}}
 - The Mac Activity Monitor reports that Docker is using twice the amount of memory it's actually using. This is due to a [bug in macOS].(https://docs.google.com/document/d/17ZiQC1Tp9iH320K-uqVLyiJmk4DHJ3c4zgQetJiKYQM/edit?usp=sharing) on this.
 
+- **"Docker.app is damaged" dialog**: If you see a "Docker.app is damaged and can't be opened" dialog during installation or updates, this is typically caused by non-atomic copy operations when other applications are using the Docker CLI. See [Fix "Docker.app is damaged" on macOS](mac-damaged-dialog.md) for resolution steps.
+
 - Force-ejecting the `.dmg` after running `Docker.app` from it can cause the
   whale icon to become unresponsive, Docker tasks to show as not responding in the Activity Monitor, and for some processes to consume a large amount of CPU resources. Reboot and restart Docker to resolve these issues.
 

content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md

@@ -0,0 +1,70 @@
+---
+description: Fix "Docker.app is damaged and can't be opened. You should move it to the Trash" dialog on macOS
+keywords: docker desktop mac, damaged app, move to trash, gatekeeper, installation issues, troubleshooting
+title: Fix "Docker.app is damaged and can't be opened" on macOS
+linkTitle: MacOS app damaged dialog
+tags: [Troubleshooting]
+weight: 30
+---
+
+## Error message
+
+macOS shows the following dialog when you try to open Docker Desktop:
+
+```text
+Docker.app is damaged and can't be opened. You should move it to the Trash.
+```
+
+This error prevents Docker Desktop from launching and can occur during installation or after updates.
+
+## Possible cause
+
+This issue occurs due to a non-atomic copy during a drag/drop installation. When you drag and drop `Docker.app` from a DMG file while another application, like VS Code, is invoking the Docker CLI through symlinks, the copy operation may be interrupted, leaving the app in a partially copied state that Gatekeeper marks as "damaged".
+
+## Solution
+
+Follow these steps to resolve the issue:
+
+### Step one: Quit third-party software
+
+Close any applications that might call Docker in the background:
+- Visual Studio Code and other IDEs
+- Terminal applications
+- Agent apps or development tools
+- Any scripts or processes that use the Docker CLI
+
+### Step two: Remove any partial installation
+
+1. Move `/Applications/Docker.app` to Trash and empty Trash.
+2. If you used a DMG installer, eject and re-mount the Docker DMG.
+
+### Step three: Reinstall Docker Desktop
+
+Follow the instructions in the [macOS installation guide](/manuals/desktop/setup/install/mac-install.md) to reinstall Docker Desktop.
+
+### If the dialog persists
+
+If you continue to see the "damaged" dialog after following the recovery steps:
+
+1. Gather diagnostics using the terminal. Follow the instructions in [Diagnose from the terminal](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-terminal).
+   - Note down the your diagnostics ID displayed in the terminal after running diagnostics.
+
+2. Get help:
+   - If you have a paid Docker subscription, [contact support](/manuals/desktop/troubleshoot-and-support/support.md) and include your diagnostics ID
+   - For community users, [open an issue on GitHub](https://github.com/docker/for-mac/issues) and include your diagnostics ID
+
+## Prevention
+
+To avoid this issue in the future:
+
+- If your organization allows, update Docker Desktop via the in-app update flow
+- Always quit applications that use Docker before installing Docker Desktop via the DMG installer drag-and-drop approach
+- In managed environments, use PKG installations over DMG drag-and-drop
+- Keep installer volumes mounted until installation is complete
+
+## Related information
+
+- [Install Docker Desktop on Mac](/manuals/desktop/setup/install/mac-install.md)
+- [PKG installer documentation](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md)
+- [Troubleshoot Docker Desktop](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md)
+- [Known issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md)