docs: document the Windows Defender false positive on the bundled CLI (#5829)

Windows Security flags multica.exe inside app.asar.unpacked as
Trojan:Script/Wacatac.B!ml and quarantines it. The !ml suffix is a
machine-learning heuristic verdict, not a signature match: our Windows
builds are not Authenticode-signed (release.yml sets
CSC_IDENTITY_AUTO_DISCOVERY=false and no certificate is configured), and
an unsigned, low-prevalence Go binary that spawns background processes
and opens sockets is the classic false-positive profile.

Add a Desktop docs section (en/zh/ja/ko) covering how to verify the
binary against checksums.txt, restore it from quarantine, exclude both
the install directory and %APPDATA%\\Multica (Desktop re-downloads the
CLI there, so excluding only the install dir loops), and report the
false positive to Microsoft.

MUL-5216

Co-authored-by: Bohan-J <bohan@devv.ai>
Co-authored-by: multica-agent <github@multica.ai>

apps/docs/content/docs/desktop-app.ja.mdx

@@ -92,6 +92,38 @@ macOS ビルドは署名・公証されているため、初回起動時に「
 `desktop.json` は存在するが無効な場合、Desktop は安全側に倒して動作を停止し、Cloud に静かにフォールバックする代わりにブロック型の設定エラーを表示します。開発ビルドの場合、`electron-vite dev` 中は依然として `VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL` が優先されます。ランタイムでの Desktop セルフホスト構成は [issue #1371](https://github.com/multica-ai/multica/issues/1371) で実装されました。
 </Callout>
 
+## Windows Defender が Multica をウイルスとして検出する
+
+**症状**: Windows セキュリティが `Trojan:Script/Wacatac.B!ml` のような脅威を報告し、Desktop のインストール先にあるファイルを隔離します。対象になるのは通常、アプリ本体の実行ファイルではなく同梱の CLI です。
+
+```text
+C:\Users\<ユーザー名>\AppData\Local\Programs\@multicadesktop\resources\app.asar.unpacked\resources\bin\multica.exe
+```
+
+**これは誤検知です。** `!ml` というサフィックスは、この判定がマルウェアのシグネチャ一致ではなく Defender の機械学習ヒューリスティックによるものであることを示します。Multica の Windows ビルドはまだ Authenticode コード署名を行っておらず、公開されたばかりで署名がなく、バックグラウンドプロセスを起動してネットワーク接続を張るバイナリは、この種のヒューリスティックが最も疑わしいと判定するプロファイルそのものです。Windows 向けの成果物はすべて、このリポジトリの公開ソースから GitHub Actions でビルドされています。
+
+**自分で検証できます** — 各 GitHub リリースには、すべての CLI アーカイブを網羅した `checksums.txt` が公開されています。
+
+```powershell
+Get-FileHash .\multica-cli-<version>-windows-amd64.zip -Algorithm SHA256
+```
+
+出力されたハッシュを、[最新リリース](https://github.com/multica-ai/multica/releases/latest)の `checksums.txt` の該当行と照合してください。
+
+**対処方法**:
+
+1. **隔離されたファイルを復元する** — Windows セキュリティ → *ウイルスと脅威の防止* → *保護の履歴* → Multica の項目を選択 → *操作* → *復元*。
+2. **除外を追加する**（再び隔離されないように）— *ウイルスと脅威の防止* → *設定の管理* → *除外* → *除外の追加または削除* → *フォルダー* で、次の両方を追加します。
+   - `%LOCALAPPDATA%\Programs\@multicadesktop`
+   - `%APPDATA%\Multica`
+
+   両方が必要です。同梱の CLI が失われると Desktop は代替バイナリを `%APPDATA%\Multica\bin` にダウンロードするため、インストール先だけを除外してもダウンロードした代替バイナリが再び隔離され、同じことの繰り返しになります。
+3. **誤検知を Microsoft に報告する** — [Microsoft Security Intelligence のファイル送信ページ](https://www.microsoft.com/en-us/wdsi/filesubmission)で *Software developer* と *Incorrectly detected as malware* を選択します。すべてのユーザーに対して検出を取り下げてもらうにはこの手順が必要で、通常は数日で反映されます。
+
+<Callout type="warning">
+これらの除外を追加してよいのは、[ダウンロードページ](https://multica.ai/download)または [GitHub リリース](https://github.com/multica-ai/multica/releases)からインストールし、チェックサムが一致している場合だけです。除外を設定すると、そのフォルダー内のすべてのファイルでリアルタイム保護が無効になります。
+</Callout>
+
 ## 次のステップ
 
 - [Cloud Quickstart](/cloud-quickstart) — Desktop 向けの Cloud オンボーディングフロー

apps/docs/content/docs/desktop-app.ko.mdx

@@ -92,6 +92,38 @@ macOS 빌드는 서명 및 공증되어 있으므로, 첫 실행 시 "확인되
 `desktop.json`이 존재하지만 유효하지 않으면, Desktop은 안전하게 동작을 차단하여 Cloud로 조용히 되돌아가는 대신 차단형 설정 오류를 표시합니다. 개발 빌드의 경우, `electron-vite dev` 중에는 여전히 `VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL`이 우선합니다. 런타임 Desktop 자체 호스팅 구성은 [issue #1371](https://github.com/multica-ai/multica/issues/1371)에서 구현되었습니다.
 </Callout>
 
+## Windows Defender가 Multica를 바이러스로 탐지하는 경우
+
+**증상**: Windows 보안이 `Trojan:Script/Wacatac.B!ml` 같은 위협을 보고하고 Desktop 설치 경로 안의 파일을 격리합니다. 격리되는 대상은 보통 앱 실행 파일이 아니라 함께 포함된 CLI입니다.
+
+```text
+C:\Users\<사용자>\AppData\Local\Programs\@multicadesktop\resources\app.asar.unpacked\resources\bin\multica.exe
+```
+
+**오탐입니다.** `!ml` 접미사는 이 판정이 악성코드 시그니처 일치가 아니라 Defender의 머신러닝 휴리스틱에서 나왔다는 뜻입니다. Multica의 Windows 빌드는 아직 Authenticode 코드 서명을 하지 않았고, 갓 배포된 서명 없는 바이너리가 백그라운드 프로세스를 띄우고 네트워크 연결을 여는 형태는 이런 휴리스틱이 가장 의심스럽게 평가하는 프로필입니다. 모든 Windows 산출물은 이 저장소의 공개 소스에서 GitHub Actions로 빌드됩니다.
+
+**직접 검증할 수 있습니다** — 모든 GitHub 릴리스에는 CLI 아카이브 전체를 포함한 `checksums.txt`가 함께 게시됩니다.
+
+```powershell
+Get-FileHash .\multica-cli-<version>-windows-amd64.zip -Algorithm SHA256
+```
+
+출력된 해시를 [최신 릴리스](https://github.com/multica-ai/multica/releases/latest)의 `checksums.txt` 해당 줄과 비교하세요.
+
+**해결 방법**:
+
+1. **격리된 파일 복원** — Windows 보안 → *바이러스 및 위협 방지* → *보호 기록* → Multica 항목 선택 → *작업* → *복원*.
+2. **제외 항목 추가** (다시 격리되지 않도록) — *바이러스 및 위협 방지* → *설정 관리* → *제외* → *제외 추가 또는 제거* → *폴더*에서 다음 두 경로를 모두 추가합니다.
+   - `%LOCALAPPDATA%\Programs\@multicadesktop`
+   - `%APPDATA%\Multica`
+
+   두 경로 모두 필요합니다. 포함된 CLI가 사라지면 Desktop이 대체 바이너리를 `%APPDATA%\Multica\bin`에 내려받기 때문에, 설치 폴더만 제외하면 새로 받은 파일이 다시 격리되는 상황이 반복됩니다.
+3. **오탐을 Microsoft에 신고** — [Microsoft Security Intelligence 파일 제출 페이지](https://www.microsoft.com/en-us/wdsi/filesubmission)에서 *Software developer*와 *Incorrectly detected as malware*를 선택하세요. 모든 사용자에 대해 탐지를 철회시키는 방법은 이것이며, 보통 며칠 안에 반영됩니다.
+
+<Callout type="warning">
+이 제외 항목은 [다운로드 페이지](https://multica.ai/download) 또는 [GitHub 릴리스](https://github.com/multica-ai/multica/releases)에서 설치했고 체크섬이 일치하는 경우에만 추가하세요. 제외를 설정하면 해당 폴더 안의 모든 파일에 대해 실시간 보호가 꺼집니다.
+</Callout>
+
 ## 다음 단계
 
 - [Cloud Quickstart](/cloud-quickstart) — Desktop을 위한 Cloud 온보딩 흐름

apps/docs/content/docs/desktop-app.mdx

@@ -92,6 +92,38 @@ Minimal self-host config:
 If `desktop.json` exists but is invalid, Desktop fails closed and shows a blocking config error instead of silently falling back to Cloud. For development builds, `VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL` still take precedence during `electron-vite dev`. Runtime Desktop self-host configuration was implemented for [issue #1371](https://github.com/multica-ai/multica/issues/1371).
 </Callout>
 
+## Windows Defender flags Multica as a virus
+
+**Symptom**: Windows Security reports a threat such as `Trojan:Script/Wacatac.B!ml` and quarantines a file inside the Desktop installation. The affected item is normally the bundled CLI, not the app executable:
+
+```text
+C:\Users\<you>\AppData\Local\Programs\@multicadesktop\resources\app.asar.unpacked\resources\bin\multica.exe
+```
+
+**This is a false positive.** The `!ml` suffix means the verdict came from Defender's machine-learning heuristics rather than a malware signature. Multica's Windows builds are not Authenticode code-signed yet, and a freshly published unsigned binary that starts background processes and opens network connections is exactly the profile those heuristics score as suspicious. Every Windows artifact is built by GitHub Actions from the public source in this repository.
+
+**Verify it yourself** — each GitHub release publishes a `checksums.txt` covering every CLI archive:
+
+```powershell
+Get-FileHash .\multica-cli-<version>-windows-amd64.zip -Algorithm SHA256
+```
+
+Compare the hash with the matching line in `checksums.txt` on the [latest release](https://github.com/multica-ai/multica/releases/latest).
+
+**How to fix**:
+
+1. **Restore the quarantined file** — Windows Security → *Virus & threat protection* → *Protection history* → select the Multica item → *Actions* → *Restore*.
+2. **Add an exclusion** so it isn't quarantined again — *Virus & threat protection* → *Manage settings* → *Exclusions* → *Add an exclusion* → *Folder*, and add both:
+   - `%LOCALAPPDATA%\Programs\@multicadesktop`
+   - `%APPDATA%\Multica`
+
+   Both paths matter: when the bundled CLI goes missing, Desktop downloads a replacement into `%APPDATA%\Multica\bin`, so excluding only the install folder leaves you in a loop where the replacement gets quarantined too.
+3. **Report the false positive to Microsoft** at [Microsoft Security Intelligence — submit a file](https://www.microsoft.com/en-us/wdsi/filesubmission), choosing *Software developer* and *Incorrectly detected as malware*. That is what gets the detection withdrawn for every user, usually within a few days.
+
+<Callout type="warning">
+Only add these exclusions if you installed Multica from the [downloads page](https://multica.ai/download) or [GitHub releases](https://github.com/multica-ai/multica/releases) and the checksum matches. An exclusion disables real-time protection for everything in that folder.
+</Callout>
+
 ## Next steps
 
 - [Cloud Quickstart](/cloud-quickstart) — the Cloud onboarding flow for Desktop

apps/docs/content/docs/desktop-app.zh.mdx

@@ -92,6 +92,38 @@ macOS 版本已经签名 + 公证，第一次打开不会有"未知开发者"的
 如果 `desktop.json` 存在但内容无效，Desktop 会 fail closed，显示阻塞式配置错误，而不是悄悄回退到 Cloud。开发构建里，`electron-vite dev` 仍然优先使用 `VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL`。Desktop 运行时自部署配置能力对应 [issue #1371](https://github.com/multica-ai/multica/issues/1371)。
 </Callout>
 
+## Windows Defender 把 Multica 报成病毒
+
+**现象**：Windows 安全中心报出 `Trojan:Script/Wacatac.B!ml` 之类的威胁，并隔离 Desktop 安装目录里的某个文件。被隔离的通常是内置的 CLI，而不是应用主程序：
+
+```text
+C:\Users\<你>\AppData\Local\Programs\@multicadesktop\resources\app.asar.unpacked\resources\bin\multica.exe
+```
+
+**这是误报。** `!ml` 后缀表示这个结论来自 Defender 的机器学习启发式判断，而不是病毒特征库匹配。Multica 的 Windows 构建目前还没有做 Authenticode 代码签名，而一个刚发布、没有签名、又会拉起后台进程并建立网络连接的二进制，正好落在这类启发式最容易判可疑的画像上。所有 Windows 产物都由 GitHub Actions 从本仓库的公开源码构建。
+
+**可以自己校验** —— 每个 GitHub release 都发布了覆盖全部 CLI 压缩包的 `checksums.txt`：
+
+```powershell
+Get-FileHash .\multica-cli-<version>-windows-amd64.zip -Algorithm SHA256
+```
+
+把输出的哈希和[最新 release](https://github.com/multica-ai/multica/releases/latest) 里 `checksums.txt` 对应那一行比对。
+
+**怎么解决**：
+
+1. **把隔离的文件恢复回来** —— Windows 安全中心 → *病毒和威胁防护* → *保护历史记录* → 选中 Multica 那一条 → *操作* → *还原*。
+2. **加排除项**，避免再次被隔离 —— *病毒和威胁防护* → *管理设置* → *排除项* → *添加或删除排除项* → *文件夹*，两个都要加：
+   - `%LOCALAPPDATA%\Programs\@multicadesktop`
+   - `%APPDATA%\Multica`
+
+   两个路径缺一不可：内置 CLI 被删掉后，Desktop 会把替换版本下载到 `%APPDATA%\Multica\bin`，只排除安装目录的话，下载下来的副本还会再被隔离一次，陷入循环。
+3. **把误报提交给微软** —— 在 [Microsoft Security Intelligence 文件提交页](https://www.microsoft.com/en-us/wdsi/filesubmission)选择 *Software developer* 和 *Incorrectly detected as malware*。这一步才是让检测对所有用户撤销的办法，一般几天内生效。
+
+<Callout type="warning">
+只有在你是从[下载页](https://multica.ai/download)或 [GitHub releases](https://github.com/multica-ai/multica/releases) 安装、且校验和对得上的前提下，才加这些排除项。排除项会关闭该文件夹内所有文件的实时保护。
+</Callout>
+
 ## 下一步
 
 - [Cloud Quickstart](/cloud-quickstart) —— Desktop 版的 Cloud 接入流程