From 00ce813845123c51b77f79234c84e1206497f1e3 Mon Sep 17 00:00:00 2001
From: javis-bot <claude@tkrmagid.kr>
Date: Mon, 22 Jun 2026 23:13:33 +0900
Subject: [PATCH] docs: warn that COMPOSE_FILE uses ';' on Windows, ':' on
 Linux/macOS

Windows users following the docs hit "The system cannot find the file
specified" because COMPOSE_FILE's separator is OS-specific (':' collides
with the C: drive letter). Fix every Windows example to use ';', add an
explicit OS-separator warning in .env.example, README, DEPLOY.md and the
gpu-windows compose comment, and point users at the explicit `-f` form as
a separator-agnostic alternative.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .env.example                   | 13 ++++++++++---
 README.md                      |  8 +++++---
 docker-compose.gpu-windows.yml |  5 +++--
 docs/DEPLOY.md                 | 14 ++++++++++----
 4 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/.env.example b/.env.example
index 8f304b3..0c4f9d5 100644
--- a/.env.example
+++ b/.env.example
@@ -190,11 +190,18 @@ VOICE_SILENCE_MS=800
 JARVIS_ROLE=full
 
 # --- GPU per OS: pick the matching compose override via COMPOSE_FILE ---
-# Ubuntu (nvidia-container-toolkit / CDI):
+# IMPORTANT: the file separator is OS-specific. Linux/macOS use ":" (colon);
+# Windows uses ";" (semicolon), because ":" is taken by the drive letter (C:).
+# Using the wrong one makes Docker treat the whole string as a single missing
+# filename ("...gpu-windows.yml: The system cannot find the file specified").
+# Ubuntu / macOS (nvidia-container-toolkit / CDI):
 #   COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-linux.yml
-# Windows 11 (Docker Desktop + WSL2 + NVIDIA):
-#   COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-windows.yml
+# Windows 11 (Docker Desktop + WSL2 + NVIDIA) — note the ";" separator:
+#   COMPOSE_FILE=docker-compose.yml;docker-compose.gpu-windows.yml
 # Browser-only host (no GPU needed): leave COMPOSE_FILE unset (base only).
+# Default below is the Linux form; Windows users must change ":" to ";" AND
+# swap gpu-linux for gpu-windows. If unsure, comment this out and pass the
+# files explicitly: docker compose -f docker-compose.yml -f <gpu-override> ...
 COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-linux.yml
 
 # --- Browser HOST (JARVIS_ROLE=browser) — e.g. this LAN machine ---
diff --git a/README.md b/README.md
index 9789f8a..ac4e2ca 100644
--- a/README.md
+++ b/README.md
@@ -76,12 +76,14 @@ docker compose up -d --build
 매번 `-f`를 치기 싫으면 `.env`에 한 줄 넣어두면 그냥 `docker compose up -d`로 됩니다(override가 자동 적용):
 
 ```bash
-# Linux
+# Linux / macOS  (구분자 = 콜론 ":")
 COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-linux.yml
-# Windows 11
-COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-windows.yml
+# Windows 11     (구분자 = 세미콜론 ";" — 콜론은 드라이브 문자 C: 와 충돌)
+COMPOSE_FILE=docker-compose.yml;docker-compose.gpu-windows.yml
 ```
 
+> ⚠️ `COMPOSE_FILE`의 파일 구분자는 OS마다 다릅니다: Linux/macOS는 `:`, Windows는 `;`. Windows에서 `:`를 쓰면 Docker가 전체를 파일 하나 이름으로 읽어 `... The system cannot find the file specified` 에러가 납니다. 헷갈리면 `COMPOSE_FILE`을 비워두고 실행 시 직접 지정하세요: `docker compose -f docker-compose.yml -f docker-compose.gpu-windows.yml up -d --build`.
+
 > Linux와 Windows는 GPU를 컨테이너에 넣는 방식이 달라서 override 파일이 갈립니다. Linux는 CDI(`devices: nvidia.com/gpu=all`), Windows(Docker Desktop)는 Compose의 `deploy.resources.reservations.devices`(`driver: nvidia`)를 씁니다. 호스트 사전 준비는 아래 "GPU 가속" 절 참고.
 
 `docker compose up` 한 번이면 자동으로:
diff --git a/docker-compose.gpu-windows.yml b/docker-compose.gpu-windows.yml
index 039165f..021b387 100644
--- a/docker-compose.gpu-windows.yml
+++ b/docker-compose.gpu-windows.yml
@@ -5,8 +5,9 @@
 #
 #   docker compose -f docker-compose.yml -f docker-compose.gpu-windows.yml up -d
 #
-# Or set COMPOSE_FILE in .env (recommended):
-#   COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-windows.yml
+# Or set COMPOSE_FILE in .env (note the ";" separator on Windows — ":" collides
+# with the C: drive letter and breaks file resolution):
+#   COMPOSE_FILE=docker-compose.yml;docker-compose.gpu-windows.yml
 services:
   ollama:
     deploy:
diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md
index f425590..a9b9c43 100644
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -3,6 +3,12 @@
 One image, three roles (`JARVIS_ROLE`), selected in `.env`. GPU is added per OS
 via a compose override picked with `COMPOSE_FILE`.
 
+> `COMPOSE_FILE`'s file separator is OS-specific: Linux/macOS use `:`, Windows
+> uses `;` (a colon collides with the `C:` drive letter). Using `:` on Windows
+> yields `... The system cannot find the file specified`. If in doubt, leave
+> `COMPOSE_FILE` unset and pass the files explicitly:
+> `docker compose -f docker-compose.yml -f docker-compose.gpu-windows.yml up -d`.
+
 ## A. All-in-one (single machine)
 
 Everything (desktop + Chrome + bridge + bot + TTS) in one container.
@@ -10,8 +16,8 @@ Everything (desktop + Chrome + bridge + bot + TTS) in one container.
 ```
 # .env
 JARVIS_ROLE=full
-COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-linux.yml      # Ubuntu
-# COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-windows.yml  # Windows 11
+COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-linux.yml      # Ubuntu/macOS (":" )
+# COMPOSE_FILE=docker-compose.yml;docker-compose.gpu-windows.yml  # Windows 11 (";" )
 DISCORD_SELFBOT_TOKEN=...
 DISCORD_GUILD_ID=...
 
@@ -45,8 +51,8 @@ Watch it on this machine’s VNC (`localhost:5901`) / noVNC (`localhost:6080`).
 # .env
 JARVIS_ROLE=bot
 BROWSER_CONTROL_URL=http://192.168.10.9:8777      # the browser host's LAN IP
-COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-linux.yml      # Ubuntu
-# COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-windows.yml  # Windows 11
+COMPOSE_FILE=docker-compose.yml:docker-compose.gpu-linux.yml      # Ubuntu/macOS (":" )
+# COMPOSE_FILE=docker-compose.yml;docker-compose.gpu-windows.yml  # Windows 11 (";" )
 DISCORD_SELFBOT_TOKEN=...
 DISCORD_GUILD_ID=...