chore: improve desktop development experience

README.md

@@ -59,10 +59,14 @@ usable as the lower-level agent package.
 
 ## Requirements
 
-- Python 3.11 or newer
+- Python 3.11.x
 - Node.js `^20.19.0` or `>=22.12.0`
 - npm
 
+Python 3.11.x is the currently validated version for both backend development
+and Desktop packaging. Using the same minor version keeps the local runtime and
+the PyInstaller build environment consistent.
+
 PostgreSQL, MySQL, Ollama, and local GGUF models are optional. They are needed
 only when you choose those connection or model types.
 
@@ -71,7 +75,7 @@ only when you choose those connection or model types.
 ### 1. Install the backend
 
 From the repository root, create the runtime environment expected by the start
-script:
+script. Confirm that `python3.11 --version` reports Python 3.11.x first:
 
 ```bash
 python3.11 -m venv backend/.venv-runtime
@@ -167,12 +171,17 @@ cd frontend
 npm run dev:desktop
 ```
 
+The development shell uses the AurigaSQL product name and icon. It still runs
+from Electron's development executable; distributable application metadata is
+applied by the packaging commands below.
+
 Set `VITE_BFF_BASE_URL` in `frontend/.env.local` only when the BFF is not running
 at `http://127.0.0.1:6003`.
 
 ## Desktop Packaging
 
-Install the packaging dependencies first:
+Desktop packaging uses the same Python 3.11.x virtual environment created in
+Quick Start. Activate it and install the packaging dependencies first:
 
 ```bash
 source backend/.venv-runtime/bin/activate

backend/packaging/README.md

@@ -27,9 +27,12 @@ platform-specific `llama.cpp` runtime files.
 
 ## Build the bundled backend and app
 
-Use Python 3.11 for PyInstaller builds.
+Use Python 3.11.x for PyInstaller builds. This is the currently validated
+packaging version and should match the environment at `backend/.venv-runtime`.
 
 ```bash
+python3.11 -m venv backend/.venv-runtime
+source backend/.venv-runtime/bin/activate
 python -m pip install -e .
 python -m pip install -r backend/requirements.txt
 python -m pip install -r backend/requirements-build.txt

backend/packaging/build-macos.sh

@@ -12,7 +12,7 @@ DIST_DIR="${AURIGASQL_BACKEND_DIST_DIR:-$REPO_ROOT/frontend/electron-backend}"
 
 PYTHON_VERSION="$("$PYTHON_BIN" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
 if [[ "$PYTHON_VERSION" != 3.11* ]]; then
-  echo "AurigaSQL desktop backend builds require Python 3.11; got $PYTHON_VERSION from $PYTHON_BIN" >&2
+  echo "AurigaSQL desktop backend builds require Python 3.11.x; got $PYTHON_VERSION from $PYTHON_BIN" >&2
   exit 1
 fi
 

backend/packaging/build-windows.ps1

@@ -10,7 +10,7 @@ $env:PYINSTALLER_CONFIG_DIR = Join-Path $RepoRoot "build/pyinstaller-cache"
 
 $PythonVersion = & $PythonBin -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"
 if (-not $PythonVersion.StartsWith("3.11")) {
-  throw "AurigaSQL desktop backend builds require Python 3.11; got $PythonVersion from $PythonBin"
+  throw "AurigaSQL desktop backend builds require Python 3.11.x; got $PythonVersion from $PythonBin"
 }
 
 New-Item -ItemType Directory -Force -Path $DistDir | Out-Null

frontend/electron/main.cjs

@@ -4,6 +4,8 @@ const http = require("node:http");
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 
+const APP_NAME = "AurigaSQL";
+const APP_ICON = path.join(__dirname, "assets", "icon.png");
 const DEV_SERVER_URL = process.env.ELECTRON_RENDERER_URL || "http://127.0.0.1:5173";
 const BACKEND_PORT = Number(process.env.AURIGASQL_BFF_PORT || "6013");
 const BACKEND_BASE_URL = `http://127.0.0.1:${BACKEND_PORT}`;
@@ -12,6 +14,10 @@ let backendRestartCount = 0;
 let backendStopRequested = false;
 let quitting = false;
 
+// `electron .` runs through Electron's generic development executable. Set the
+// product identity explicitly so the development shell matches packaged builds.
+app.setName(APP_NAME);
+
 ipcMain.handle("app:restart-backend", async () => {
   if (!app.isPackaged) return { ok: false, message: "Backend restart is only managed in packaged app mode." };
   await stopBackend();
@@ -55,7 +61,8 @@ function createWindow() {
     height: 960,
     minWidth: 1100,
     minHeight: 720,
-    title: "AurigaSQL",
+    title: APP_NAME,
+    icon: APP_ICON,
     backgroundColor: "#f7f4ee",
     webPreferences: {
       preload: path.join(__dirname, "preload.cjs"),
@@ -345,6 +352,10 @@ app.on("before-quit", () => {
 });
 
 app.whenReady().then(() => {
+  if (!app.isPackaged && process.platform === "darwin") {
+    app.dock.setIcon(APP_ICON);
+  }
+
   createWindow();
 
   app.on("activate", () => {