(CODUX-119) Document desktop system bar behavior

docs-web/user/installation.md

@@ -64,8 +64,7 @@ Download the latest installer for your platform from
 > releases page.
 
 The desktop app launches the runtime and opens the dashboard automatically. The title bar shows the
-running version and a compact **Update** action that opens the official GitHub release download page
-in your default browser; the app does not navigate away from the dashboard.
+running version so you can confirm which build is active.
 
 ### Speech input on desktop
 
@@ -230,9 +229,12 @@ pnpm install
 pnpm run build
 
 # desktop app
-# use the title-bar Update action, or download and run the latest installer from GitHub Releases
+# download and run the latest installer from GitHub Releases
 ```
 
+In the desktop app, the title-bar **Update** action opens the latest GitHub Releases page in your
+default browser. It is a download shortcut, not an automatic background or in-app update flow.
+
 ## Uninstall
 
 ```bash

docs/dashboard/design-system-shell-navigation.md

@@ -19,6 +19,16 @@ Header dropdowns, searches, and related shell controls are standardized to a sin
 - **Header Container Container:** The primary nav container uses `min-h-[60px]` instead of fixed `h-[60px]` to allow clustering elements to wrap on constrained viewports if needed.
 - **Global Search Trigger:** The top-nav search trigger belongs in the left header cluster beside the brand. It should use the same compact visual rhythm as project, sprint, and worker selectors, collapse toward an icon-led affordance on tight widths, and avoid forcing sibling controls to overflow.
 
+### 2a. Desktop System Bar
+The Electron system bar is compact application chrome, not a content header.
+
+- **Chrome Height:** Keep the Electron-only bar at `h-9` so it remains visually subordinate to the dashboard header and leaves route content stable.
+- **Brand And Version:** Preserve the compact Code UX mark and visible version label; do not hide the version behind hover, menus, or responsive-only states.
+- **Drag Regions:** The surrounding bar owns the draggable region, while every button, link, input, and custom control must be marked no-drag with the existing `titlebar-no-drag` contract.
+- **Interaction Safety:** Interactive controls must stop double-click propagation so only empty chrome toggles maximize/restore.
+- **Accessible Controls:** System buttons need stable accessible labels that describe the current action, including platform window controls whose label changes between maximize and restore.
+- **Platform Stability:** macOS keeps space for native traffic lights, while Windows and Linux render custom window controls; shared controls such as the update action must keep consistent placement and behavior across both layouts.
+
 ### 3. Unified Focus Rings
 All interactive components inside the shell layer must follow exactly the same focus rules.
 

docs/deployment/electron-desktop.md

@@ -14,7 +14,14 @@ Code UX can run as an installable Electron desktop app while preserving the exis
 - Windows packaged builds keep the active WebGL context cap at 16 so the persistent shell canvas, avatar canvases, and route-scoped chart canvases have enough headroom during long navigation sessions while old Chromium contexts are waiting for garbage collection.
 - External links are opened through the host operating system. In-app dashboard and sprint-preview URLs remain inside the Electron app.
 - The desktop shell renders only the resolved dashboard origin and same-port sprint preview origins that match `preview-<session>.localhost:<dashboardPort>` internally. Other `http`, `https`, and `mailto` navigations are denied in the renderer and opened through the host operating system after scheme validation; all other schemes are blocked.
-- The compact title bar renders only when the preload bridge exposes the desktop window API. It always shows the Code UX logo, the running `v{version}` label, and a no-drag "Update" button that calls `window.codeUxDesktop.openUpdates()`. That fixed IPC action opens `https://github.com/codeux-ai/codeux/releases/latest` without giving the renderer a generic external URL opener. Double-clicking non-interactive title-bar chrome toggles maximize/restore through `window.codeUxDesktop.window.toggleMaximize()`.
+
+## Desktop System Bar
+
+The desktop dashboard uses a frameless renderer-owned system bar instead of native window chrome. It renders only when the preload bridge exposes `window.codeUxDesktop.window`, and it keeps the Code UX logo, the update action, and a visible `v{version}` label compiled from `package.json` through Vite's `__APP_VERSION__` define.
+
+The update button is a no-drag control that calls the fixed `window.codeUxDesktop.openUpdates()` preload IPC method. That method opens `https://github.com/codeux-ai/codeux/releases/latest` in the host browser and deliberately does not expose a generic URL opener or perform an automatic in-app update.
+
+Double-clicking non-interactive system-bar chrome toggles maximize/restore through `window.codeUxDesktop.window.toggleMaximize()`. Interactive controls stop double-click propagation and stay inside `titlebar-no-drag` regions so buttons do not accidentally trigger window dragging or maximize behavior.
 
 ## Native Desktop Integration