diff --git a/README.md b/README.md
index 409398f..f95d486 100644
--- a/README.md
+++ b/README.md
@@ -466,6 +466,8 @@ Defaults you get out of the box:
 - ~/.inputrc:/home/developer/.inputrc:ro
 ```
 
+> **Docker Desktop caveat (macOS/Windows):** Single-file bind-mounts can silently stop propagating host edits — Docker Desktop materializes the file onto the VM's disk on first mount, and later host changes never reach the container. Verify with `docker compose exec devbox mount | grep bash_aliases` — a live share shows a `grpcfuse`/`virtiofs` source; a broken one shows `/dev/vda1`. Workaround: use a directory mount instead (`~/.config/devbox-shell:/home/developer/.config/devbox-shell:ro`) and source files from there. Linux hosts are unaffected.
+
 **Option B — customize inside the container.** Just edit `~/.bash_aliases` or `~/.inputrc` as normal. Pair this with a bind-mount or named volume on the home dir if you want the edits to survive container recreation.
 
 ### Restoring or diffing defaults
diff --git a/docker-compose.yml b/docker-compose.yml
index f30286c..9040af4 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -64,6 +64,11 @@ services:
       # Optional: override baked shell defaults with your host's rc files.
       # The image ships sensible defaults (history tuning, prefix-search on
       # Up/Down arrows, fzf/zoxide integration). Uncomment to use your own:
+      #
+      # NOTE: On Docker Desktop (macOS/Windows), single-file bind-mounts can
+      # silently stop propagating host edits — the file gets materialized onto
+      # the VM disk. If host changes don't appear in the container, see the
+      # "Shell defaults" section in README.md. Linux hosts are unaffected.
       # - ~/.bash_aliases:/home/developer/.bash_aliases:ro
       # - ~/.inputrc:/home/developer/.inputrc:ro