diff --git a/README.md b/README.md
index 7ddc15baa..ca7dd7c45 100644
--- a/README.md
+++ b/README.md
@@ -578,6 +578,8 @@ PentAGI provides an interactive installer with a terminal-based UI for streamlin
 - **Windows**: amd64 [download](https://pentagi.com/downloads/windows/amd64/installer-latest.zip)
 - **macOS**: amd64 (Intel) [download](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (M-series) [download](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip)
 
+> **macOS security warning:** If macOS flags a downloaded installer, use only the official PentAGI links above, choose the archive that matches your CPU architecture, verify the source before continuing, and follow the [installer troubleshooting guide](backend/docs/installer/installer-troubleshooting.md#macos-reports-the-installer-as-malware) before allowing the app to run.
+
 **Quick Installation (Linux amd64):**
 
 ```bash
diff --git a/backend/docs/installer/installer-troubleshooting.md b/backend/docs/installer/installer-troubleshooting.md
index aa0368ac6..18eb46067 100644
--- a/backend/docs/installer/installer-troubleshooting.md
+++ b/backend/docs/installer/installer-troubleshooting.md
@@ -135,6 +135,23 @@ func (m *FormModel) ensureFocusVisible() {
 
 ## 🔧 **Common Issues & Solutions**
 
+### **macOS Reports the Installer as Malware**
+
+**Symptoms**: macOS blocks a downloaded PentAGI installer and reports that it may contain malware.
+
+**What is currently known**:
+- Use only the official PentAGI installer downloads linked from the project README.
+- Select the archive that matches your Mac CPU architecture: `darwin/amd64` for Intel Macs or `darwin/arm64` for Apple silicon.
+- Maintainer notes in [issue #249](https://github.com/vxcontrol/pentagi/issues/249) report that the installer files are signed with the project certificate and that the checked `arm64` and `amd64` builds had zero VirusTotal detections.
+- The maintainers have contacted Apple about the warning and are awaiting a response.
+
+**Recommended handling**:
+- Treat any unexpected malware warning as a reason to stop and verify the download source before continuing.
+- Re-download the installer from the official PentAGI link if the archive came from a mirror, chat attachment, or any unofficial source.
+- If you trust the official release after verification, try to open the installer once. Then open **System Settings** -> **Privacy & Security**, find the security message that says the installer was blocked, click **Open Anyway**, and confirm the follow-up prompt to allow that specific app to run.
+- If your version of macOS shows different wording, follow Apple's guidance for opening a Mac app from an unidentified developer: <https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac>.
+- Do not reuse an installer archive that was downloaded from an unknown source, even if its filename matches the official archive name.
+
 ### **Navigation Issues**
 
 #### **Navigation Stack Corruption**
@@ -593,4 +610,4 @@ This troubleshooting guide provides comprehensive solutions for:
 - **Form Problems**: Responsive design and scrolling
 - **Configuration**: Environment variable management
 - **Performance**: Optimization and resource management
-- **Recovery**: Graceful error handling and state restoration
\ No newline at end of file
+- **Recovery**: Graceful error handling and state restoration