diff --git a/gitea-python-ci-cd.md b/gitea-python-ci-cd.md
index 5b92077..5d676ed 100644
--- a/gitea-python-ci-cd.md
+++ b/gitea-python-ci-cd.md
@@ -559,6 +559,32 @@ All NSIS shortcuts use: `"wscript.exe" '"$INSTDIR\scripts\start-hidden.vbs"'`
 doesn't have Python on PATH, so `python` alone won't work. The dev environment uses
 system Python, so the fallback handles both cases.
 
+#### VBS launcher gotchas
+
+Three separate things have to be right or the launcher fails silently (often with a misleading error):
+
+1. **Pure ASCII only.** No em-dashes, smart quotes, or any non-ASCII character — not even in comments. `wscript.exe` parses the file as ANSI. If it hits UTF-8 bytes it aborts with:
+
+    > Execution of the Windows Script Host failed. (Not enough memory resources are available to complete this operation.)
+
+    That dialog has nothing to do with memory; it's an encoding parse failure. If you write the VBS with a tool that defaults to UTF-8, strip any non-ASCII before shipping.
+
+2. **CRLF line endings.** LF-only files parse inconsistently across WSH versions. Run `unix2dos` (or `sed -i 's/$/\r/'`) on the VBS after writing it. Your build script should do this unconditionally — don't rely on whatever produced the file.
+
+3. **Use `python.exe` with `WindowStyle=0`, not `pythonw.exe`.** `pythonw.exe` has null stdout/stderr handles. Any library that touches those at startup (uvicorn, structlog, warnings) can silently crash the process before it writes a single log line. `python.exe` with `WshShell.Run cmd, 0, False` gives you a real console attached to a hidden window — same visual result, real stream handles, reliable startup.
+
+**Debugging tip:** if the shortcut "does nothing", run `file path\to\start-hidden.vbs` from Git Bash. It must report `ASCII text, with CRLF line terminators`. Any other encoding is a red flag. Also run the VBS through `cscript //nologo` from a terminal to see actual error output — wscript swallows errors by design.
+
+**Build-script enforcement:**
+
+```bash
+# In build-dist-windows.sh, right after copying scripts/ into the dist:
+cp server/scripts/start-hidden.vbs "$DIST_DIR/scripts/"
+# Paranoid: strip any accidental non-ASCII and normalize line endings
+LC_ALL=C sed -i 's/[^\x00-\x7F]//g' "$DIST_DIR/scripts/start-hidden.vbs"
+unix2dos "$DIST_DIR/scripts/start-hidden.vbs" 2>/dev/null
+```
+
 **CI dependencies:** `sudo apt-get install -y nsis msitools zip`
 
 Build: `makensis -DVERSION="${VERSION}" installer.nsi`