docs: document dashboard --serve browser mode

Add a 'Browser mode (--serve)' section to the dashboard reference (per-OS
invocation, the token-URL behavior, port/host options, and the security model),
and a troubleshooting entry for the Linux/WSL2 blank-window (EGL) case that
points users at --serve as the fix. Built clean on Astro 7; the cross-page anchor
resolves.

Co-authored-by: Alfonso [Magic Context] <288211368+alfonso-magic-context@users.noreply.github.com>

Author: ualtinok

packages/docs/src/content/docs/help/troubleshooting.md

@@ -96,6 +96,24 @@ If you need to downgrade intentionally, run `doctor --force` afterward — it wi
 
 ---
 
+## Desktop app: blank window on Linux / WSL2
+
+**Symptom:** The Magic Context Desktop app opens to a blank window (only the top menu, no content), often with `Could not create default EGL display: EGL_BAD_PARAMETER` in the terminal. Most common on non-Ubuntu Linux distributions and under WSL2.
+
+**Why it happens:** The app's embedded WebView (WebKitGTK) cannot create a graphics surface against your host's driver stack. The bundled WebKitGTK is built for one environment and does not always match another distribution's Mesa/driver versions. Environment-variable workarounds (`WEBKIT_DISABLE_DMABUF_RENDERER=1`, etc.) usually do not help for this class.
+
+**Fix:** Run the dashboard in **browser mode** instead of as a desktop window. The same binary, started with `--serve`, runs a local web server you open in your normal browser, so no embedded WebView is created:
+
+```sh
+magic-context-dashboard --serve
+```
+
+It prints a URL with a one-time token; open it in your browser (under WSL2, open it in your Windows browser via `localhost`). See [Browser mode (`--serve`)](/reference/dashboard/#browser-mode---serve) for per-OS invocations and options.
+
+A native package using your system's own WebKitGTK (the `.deb` or `.rpm` rather than the `.AppImage`) can also resolve it on some distributions.
+
+---
+
 ## Filing a bug report
 
 Run:

packages/docs/src/content/docs/reference/dashboard.md

@@ -17,6 +17,43 @@ Grab the file for your platform from the newest `dashboard-vX.Y.Z` release. The
 
 You can also build from source: see the dashboard `README` in the [magic-context](https://github.com/cortexkit/magic-context) repo (`packages/dashboard`).
 
+## Browser mode (`--serve`)
+
+The dashboard normally runs as a desktop window (an embedded WebView). On some Linux distributions and under WSL2 that embedded WebView fails to start (a blank window, often with `Could not create default EGL display` in the terminal) because the bundled WebKitGTK does not match the host's graphics stack. For those cases the same binary can run as a **local web server** instead, which you then open in your normal browser. No WebView is created, so the graphics issue is bypassed entirely.
+
+Run the installed binary with `--serve`:
+
+```sh
+# Linux (.deb / .rpm install puts it on PATH)
+magic-context-dashboard --serve
+
+# Linux AppImage
+./Magic_Context_Dashboard.AppImage --serve
+
+# macOS
+"/Applications/Magic Context Dashboard.app/Contents/MacOS/magic-context-dashboard" --serve
+
+# Windows
+"%LOCALAPPDATA%\Programs\Magic Context Dashboard\Magic Context Dashboard.exe" --serve
+```
+
+It prints a URL with a one-time access token in the fragment and opens it in your default browser automatically when a desktop display is present:
+
+```
+Magic Context Dashboard serve mode listening on 127.0.0.1:9077
+Open this URL: http://127.0.0.1:9077/#token=<token>
+```
+
+On a headless or WSL2 host (no display) it just prints the URL; open it in a browser yourself. Under WSL2, `localhost` is forwarded to the Windows host, so the URL works in your **Windows** browser.
+
+**Options:**
+
+- `--serve`: serve on `127.0.0.1:9077` (default).
+- `--serve <port>`: use a different port, e.g. `--serve 8080`.
+- `--host 0.0.0.0 --allow-remote`: bind all interfaces so another machine can reach it. This is **off by default and requires the explicit `--allow-remote` flag**, because the dashboard can read every session transcript, edit your config, and run model-discovery subprocesses, all over plain bearer-token HTTP. Prefer an SSH tunnel over binding to an open network.
+
+**Security:** access is gated by a per-process random token delivered in the URL fragment (never sent to the server or logged) and sent as an `Authorization: Bearer` header on each request. By default the server only binds loopback (`127.0.0.1`) and only accepts requests whose `Host` is loopback, which blocks DNS-rebinding. The token is required for every data request; the page shell itself carries no data.
+
 ## Updates
 
 Production builds use Tauri’s updater against the project release manifest (`latest.json` on the project GitHub Pages site). When an update is available, the app shows an **Update available** toast with **Install & Restart**. You can also use the tray **Check for Updates** action for an interactive download-and-install flow.