docs: add VBS launcher gotchas section (ASCII, CRLF, python.exe)

Three separate things sink portable-Python-on-Windows VBS launchers,
all learned from a debugging session where a wled-screen-controller
shortcut silently did nothing:

1. wscript parses .vbs as ANSI — any UTF-8 byte (em-dash, smart quote,
   even in a comment) triggers a dialog that lies about the cause:
   "Not enough memory resources are available to complete this
   operation." It's actually an encoding parse failure.
2. LF line endings parse inconsistently across WSH versions. Always
   normalize to CRLF.
3. pythonw.exe has null stdout/stderr; libraries that touch those at
   startup (uvicorn, structlog) can crash silently before the first
   log line. python.exe with WshShell.Run cmd, 0, False gives real
   stream handles attached to a hidden window — same visual result,
   reliable startup.

Also added a build-script snippet that normalizes the VBS
automatically so nobody has to remember these rules.

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`