chore: sync CI/CD with upstream guide and update context docs

release.yml: add fallback for existing releases on tag re-push.
installer.nsi: add .onInit file lock check, use LaunchApp function
instead of RUN_PARAMETERS to fix NSIS quoting bug.
build-dist.ps1: copy start-hidden.vbs to dist scripts/.
start-hidden.vbs: embedded Python fallback for installed/dev envs.

Update ci-cd.md with version detection, NSIS best practices, local
build testing, Gitea vs GitHub differences, troubleshooting.
Update frontend.md with full entity type checklist and common pitfalls.

installer.nsi

@@ -10,6 +10,7 @@
 ; ── Metadata ────────────────────────────────────────────────
 
 !define APPNAME "LedGrab"
+!define VBSNAME "start-hidden.vbs"
 !define DESCRIPTION "Ambient lighting system — captures screen content and drives LED strips in real time"
 !define VERSIONMAJOR 0
 !define VERSIONMINOR 1
@@ -33,6 +34,12 @@ SetCompressor /SOLID lzma
 
 ; ── Pages ───────────────────────────────────────────────────
 
+; Use MUI_FINISHPAGE_RUN_FUNCTION instead of MUI_FINISHPAGE_RUN_PARAMETERS —
+; NSIS Exec command chokes on the quoting with RUN_PARAMETERS.
+!define MUI_FINISHPAGE_RUN ""
+!define MUI_FINISHPAGE_RUN_TEXT "Launch ${APPNAME}"
+!define MUI_FINISHPAGE_RUN_FUNCTION LaunchApp
+
 !insertmacro MUI_PAGE_WELCOME
 !insertmacro MUI_PAGE_DIRECTORY
 !insertmacro MUI_PAGE_COMPONENTS
@@ -44,6 +51,33 @@ SetCompressor /SOLID lzma
 
 !insertmacro MUI_LANGUAGE "English"
 
+; ── Functions ─────────────────────────────────────────────
+
+Function LaunchApp
+  ExecShell "open" "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"'
+  Sleep 2000
+  ExecShell "open" "http://localhost:8080/"
+FunctionEnd
+
+; Detect running instance before install (file lock check on python.exe)
+Function .onInit
+  IfFileExists "$INSTDIR\python\python.exe" 0 done
+  ClearErrors
+  FileOpen $0 "$INSTDIR\python\python.exe" a
+  IfErrors locked
+  FileClose $0
+  Goto done
+  locked:
+    MessageBox MB_YESNOCANCEL|MB_ICONEXCLAMATION \
+      "${APPNAME} is currently running.$\n$\nYes = Stop and continue$\nNo = Continue anyway (may cause errors)$\nCancel = Abort" \
+      IDYES kill IDNO done
+    Abort
+    kill:
+      nsExec::ExecToLog 'wmic process where "ExecutablePath like $\'%${APPNAME}%python%$\'" call terminate'
+      Sleep 2000
+  done:
+FunctionEnd
+
 ; ── Installer Sections ──────────────────────────────────────
 
 Section "!${APPNAME} (required)" SecCore
@@ -54,6 +88,7 @@ Section "!${APPNAME} (required)" SecCore
   ; Copy the entire portable build
   File /r "build\LedGrab\python"
   File /r "build\LedGrab\app"
+  File /r "build\LedGrab\scripts"
   File "build\LedGrab\LedGrab.bat"
 
   ; Create data and logs directories
@@ -65,8 +100,9 @@ Section "!${APPNAME} (required)" SecCore
 
   ; Start Menu shortcuts
   CreateDirectory "$SMPROGRAMS\${APPNAME}"
-  CreateShortcut "$SMPROGRAMS\${APPNAME}\${APPNAME}.lnk" "$INSTDIR\LedGrab.bat" \
-    "" "" "" SW_SHOWMINIMIZED "" "${DESCRIPTION}"
+  CreateShortcut "$SMPROGRAMS\${APPNAME}\${APPNAME}.lnk" \
+    "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
+    "$INSTDIR\python\pythonw.exe" 0
   CreateShortcut "$SMPROGRAMS\${APPNAME}\Uninstall.lnk" "$INSTDIR\uninstall.exe"
 
   ; Registry: install location + Add/Remove Programs entry
@@ -98,13 +134,15 @@ Section "!${APPNAME} (required)" SecCore
 SectionEnd
 
 Section "Desktop shortcut" SecDesktop
-  CreateShortcut "$DESKTOP\${APPNAME}.lnk" "$INSTDIR\LedGrab.bat" \
-    "" "" "" SW_SHOWMINIMIZED "" "${DESCRIPTION}"
+  CreateShortcut "$DESKTOP\${APPNAME}.lnk" \
+    "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
+    "$INSTDIR\python\pythonw.exe" 0
 SectionEnd
 
 Section "Start with Windows" SecAutostart
-  CreateShortcut "$SMSTARTUP\${APPNAME}.lnk" "$INSTDIR\LedGrab.bat" \
-    "" "" "" SW_SHOWMINIMIZED "" "${DESCRIPTION}"
+  CreateShortcut "$SMSTARTUP\${APPNAME}.lnk" \
+    "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
+    "$INSTDIR\python\pythonw.exe" 0
 SectionEnd
 
 ; ── Section Descriptions ────────────────────────────────────
@@ -131,6 +169,7 @@ Section "Uninstall"
   ; Remove application files (but NOT data/ — preserve user config)
   RMDir /r "$INSTDIR\python"
   RMDir /r "$INSTDIR\app"
+  RMDir /r "$INSTDIR\scripts"
   Delete "$INSTDIR\LedGrab.bat"
   Delete "$INSTDIR\uninstall.exe"