diff --git a/bootstrap.sh b/bootstrap.sh
index 18d0876..9c4b38a 100755
--- a/bootstrap.sh
+++ b/bootstrap.sh
@@ -118,11 +118,55 @@ have() { command -v "$1" >/dev/null 2>&1; }
 OS="$(uname -s)"
 
 # --- 1. OS detection -----------------------------------------------------
+# Detect WSL2 (uname -s = Linux but kernel reports Microsoft) — full path works.
+# Detect Git Bash / Cygwin / MSYS on bare Windows — substrate cannot run there;
+# guide user to WSL2 instead of dying silently.
+IS_WSL=0
+if [ "$OS" = "Linux" ] && [ -r /proc/version ] && grep -qiE "microsoft|wsl" /proc/version 2>/dev/null; then
+    IS_WSL=1
+fi
+
 case "$OS" in
-    Darwin|Linux) ;;
-    *) err "unsupported OS: $OS (only Darwin / Linux for now)"; exit 1 ;;
+    Darwin|Linux)
+        if [ "$IS_WSL" = "1" ]; then
+            log "OS: WSL2 (Linux inside Windows) — full substrate path available"
+        else
+            log "OS: $OS"
+        fi
+        ;;
+    MINGW*|MSYS*|CYGWIN*)
+        err ""
+        err "Detected: bare Windows ($OS) via Git Bash / Cygwin / MSYS."
+        err ""
+        err "KeiSeiKit's substrate is Bash-only and needs apt/brew + full POSIX —"
+        err "it will not run reliably outside WSL2. Native PowerShell port is NOT"
+        err "on the roadmap (would double maintenance; WSL gives 100% coverage)."
+        err ""
+        err "Path forward (one-time setup, ~5 min + reboot):"
+        err ""
+        err "  1. Open PowerShell as Administrator."
+        err "  2. Run:        wsl --install -d Ubuntu"
+        err "  3. Reboot when prompted; Ubuntu auto-starts on next login."
+        err "  4. Inside Ubuntu, re-run this same bootstrap:"
+        err "       curl -fsSL https://raw.githubusercontent.com/KeiSeiLab/KeiSeiKit-1.0/main/bootstrap.sh | bash"
+        err ""
+        err "Alternative — MCP-only (no substrate, no skills, no hooks):"
+        err "  Grab kei-mcp-server-windows-x64.exe from a release and wire it"
+        err "  into Claude Desktop / VS Code MCP config. Gets you spawn_agent +"
+        err "  kei_bash/kei_edit/kei_write only. See README → Platforms section."
+        err ""
+        # Best-effort: copy the wsl --install command to clipboard if possible.
+        if command -v clip.exe >/dev/null 2>&1; then
+            printf 'wsl --install -d Ubuntu' | clip.exe 2>/dev/null && \
+                err "(I've copied 'wsl --install -d Ubuntu' to your Windows clipboard.)"
+        fi
+        exit 1
+        ;;
+    *)
+        err "unsupported OS: $OS (supported: Darwin / Linux / WSL2)"
+        exit 1
+        ;;
 esac
-log "OS: $OS"
 
 # --- 2. install jq -------------------------------------------------------
 install_jq() {
diff --git a/install.sh b/install.sh
index 3c9ded1..20df7c8 100755
--- a/install.sh
+++ b/install.sh
@@ -20,6 +20,28 @@
 
 set -euo pipefail
 
+# --- OS guard (v0.47): friendly message on bare Windows ------------------
+_uname_s="$(uname -s 2>/dev/null || echo unknown)"
+case "$_uname_s" in
+    Darwin|Linux) ;;  # ok
+    MINGW*|MSYS*|CYGWIN*)
+        echo "[install.sh] ERROR: bare Windows ($_uname_s) detected." >&2
+        echo "" >&2
+        echo "KeiSeiKit's substrate is Bash-only. Use WSL2 instead:" >&2
+        echo "  1. PowerShell (admin):  wsl --install -d Ubuntu" >&2
+        echo "  2. Reboot when prompted; launch Ubuntu." >&2
+        echo "  3. Inside Ubuntu, re-run this installer." >&2
+        echo "" >&2
+        echo "See README → 'Platforms' for the full path + MCP-only fallback." >&2
+        exit 1
+        ;;
+    *)
+        echo "[install.sh] ERROR: unsupported OS: $_uname_s (supported: Darwin / Linux / WSL2)" >&2
+        exit 1
+        ;;
+esac
+unset _uname_s
+
 # --- paths ----------------------------------------------------------------
 KIT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 HOME_DIR="${HOME:?HOME not set}"