V2

README.md

@@ -162,6 +162,14 @@ npm install
 cd ..
 ```
 
+### Install Overlay Dependencies
+
+```powershell
+cd overlay
+npm install
+cd ..
+```
+
 ## Running The App
 
 ### Production-Style Local Run
@@ -205,6 +213,28 @@ Then open the Vite URL, usually:
 
 `http://127.0.0.1:5173/`
 
+### Transparent Profile Overlay
+
+The optional Electron overlay listens to the backend WebSocket at `ws://127.0.0.1:8000/ws` and shows a click-through popup when the visible deck changes. It appears on startup, active profile changes, and active folder changes, then fades away after 7 seconds.
+
+Start the backend first, then run:
+
+```powershell
+cd overlay
+npm run dev
+```
+
+The overlay is frameless, transparent, always on top, and non-interactable so it can sit over other desktop apps without stealing clicks. It does not put a button in the taskbar; the app lives in the Windows notification area with a tray menu for showing the last overlay state or quitting it.
+
+To build the Windows installer locally:
+
+```powershell
+cd overlay
+npm run dist:win
+```
+
+The installer is written to `overlay/release/`.
+
 ## Operational Notes
 
 ### Device Detection
@@ -252,6 +282,12 @@ For a reliable day-to-day setup on a dedicated machine:
 
 This app is best thought of as a local control appliance: hardware input on one side, desktop automation and operator UI on the other.
 
+### Overlay Release Automation
+
+The Gitea workflow in `.gitea/workflows/overlay-release.yml` builds the Electron overlay on a Windows runner for pushes and pull requests that touch `overlay/`. Pushing a tag that matches `v*` or `overlay-v*` also creates or reuses a Gitea release and uploads the generated installer `.exe`.
+
+The workflow uses the built-in `GITEA_TOKEN` with `releases: write` permission, so the repository Actions settings must allow release writes for the job token.
+
 ## Legacy Utility
 
 For raw serial logging without the full app: