[CLAUDE] Docs: gotcha #25 — Install-WindowsFeature Web-WebSockets locks webSocket section in applicationHost

docs/gotchas.md

@@ -182,6 +182,23 @@ Mỗi migration tạo: `{name}.cs` + `{name}.Designer.cs` + `ApplicationDbContex
 
 **Fix:** Luôn dùng `MenuKeys.Contracts` const (BE) + `MenuKeys.Contracts` (FE `menuKeys.ts`). Không hardcode string.
 
+## IIS / Windows Server
+
+### 25. `Install-WindowsFeature Web-WebSockets` khóa section `<webSocket>` ở applicationHost
+
+**Triệu chứng:** Sau khi install WebSocket feature → TẤT CẢ IIS site có `<webSocket enabled="true" />` trong web.config trả về HTTP 500.19 với error code `0x80070021` "configuration section cannot be used at this path" — kể cả site khác project không liên quan.
+
+**Nguyên nhân:** Feature install thêm `<webSocket>` section vào `applicationHost.config` với `overrideModeDefault="Deny"`. Site web.config override section đó → fail.
+
+**Fix:** Unlock section ở server level:
+```powershell
+& "$env:SystemRoot\system32\inetsrv\appcmd.exe" unlock config -section:system.webServer/webSocket
+```
+
+Tương tự khi dùng URL Rewrite `<serverVariables>` cần unlock `system.webServer/rewrite/allowedServerVariables`.
+
+**Cảnh báo co-existence:** Trên VPS shared với project khác, enable feature mới qua `Install-WindowsFeature` có thể làm sập site project khác. Luôn test all site sau mỗi enable.
+
 ## Checklist debug bug mới
 
 1. Build pass không? → fail → check using + package version compat