Fix Linux installation and launcher environment

.env.example

@@ -8,7 +8,7 @@ UI_BUTTON_WIDTH=14
 UI_BUTTON_FG="lime green"
 UI_BUTTON_FG_CANCEL=red2
 UI_BUTTON_FG_ACCENT2=yellow
-UI_FONT_SIZE=16
+UI_FONT_SIZE=13
 UI_FONT_FAMILY=Bahnschrift
 UI_PADDING=8
 

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Set the default base UI font size to 13 and made Linux setup, run, and desktop
+  launchers use the project virtual environment without requiring shell activation.
+- Added an XDG-aware Linux application-menu launcher and an optional Desktop
+  launcher when the user's Desktop directory exists.
 - Synchronized maintained user, developer, API, and in-app reference documentation with the published 1.0.0 implementation.
 
 ## [1.0.0] - 2026-09-22

README.md

@@ -140,11 +140,18 @@ bin\run.bat
 Linux/macOS:
 
 ```bash
-chmod +x bin/setup.sh bin/run.sh
 ./bin/setup.sh
 ./bin/run.sh
 ```
 
+The setup and run scripts use the project-local `.venv` directly, so you do not
+need to activate it first. Manual activation remains useful for development
+commands you run yourself. Running `./bin/run.sh` or `.venv/bin/differential-lab`
+keeps imports tied to the installed project environment and avoids mismatches
+from accidentally using the system Python. On Linux, `install.sh` adds an
+application-menu launcher and a Desktop launcher when the XDG Desktop directory
+exists.
+
 For development dependencies:
 
 ```bat
@@ -157,7 +164,8 @@ or on Linux/macOS:
 ./bin/setup.sh --dev
 ```
 
-Direct run from an activated environment:
+Manual run from an activated environment (activation is optional when using
+the project scripts above):
 
 ```bash
 python src/main_program.py

bin/linux_desktop.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Create Linux application-menu and optional Desktop launchers.
+
+create_linux_launchers() {
+    local project_dir="$1"
+    local data_home="${XDG_DATA_HOME:-$HOME/.local/share}"
+    local applications_dir="$data_home/applications"
+    local app_launcher="$applications_dir/DifferentialLab.desktop"
+    local desktop_dir=""
+    local entry_point="$project_dir/.venv/bin/differential-lab"
+    local icon_path="$project_dir/images/DifferentialLab_icon.png"
+
+    mkdir -p "$applications_dir"
+    cat > "$app_launcher" << EOF
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=DifferentialLab
+Comment=Launch DifferentialLab
+Exec="$entry_point"
+Path=$project_dir
+Icon=$icon_path
+Terminal=false
+EOF
+    chmod +x "$app_launcher"
+    echo "Application-menu launcher created: $app_launcher"
+
+    if [ -n "${XDG_DESKTOP_DIR:-}" ] && [ -d "$XDG_DESKTOP_DIR" ]; then
+        desktop_dir="$XDG_DESKTOP_DIR"
+    elif command -v xdg-user-dir >/dev/null 2>&1; then
+        desktop_dir="$(xdg-user-dir DESKTOP 2>/dev/null || true)"
+        [ -d "$desktop_dir" ] || desktop_dir=""
+    fi
+    if [ -z "$desktop_dir" ] && [ -d "$HOME/Desktop" ]; then
+        desktop_dir="$HOME/Desktop"
+    fi
+
+    if [ -n "$desktop_dir" ]; then
+        cp "$app_launcher" "$desktop_dir/DifferentialLab.desktop"
+        chmod +x "$desktop_dir/DifferentialLab.desktop"
+        echo "Desktop launcher created: $desktop_dir/DifferentialLab.desktop"
+    else
+        echo "No usable Desktop directory found; application-menu launcher is available."
+    fi
+}

bin/run.sh

@@ -13,17 +13,22 @@ if [ ! -d ".venv" ]; then
     exit 1
 fi
 
+ENTRY_POINT=".venv/bin/differential-lab"
+if [ ! -x "$ENTRY_POINT" ]; then
+    echo "ERROR: DifferentialLab entry point not found or not executable: $ENTRY_POINT"
+    echo "Please run bin/setup.sh first"
+    exit 1
+fi
+
 MODE="${1:---prod}"
 
 case "$MODE" in
     --dev|-d)
-        source .venv/bin/activate
-        python src/main_program.py
+        "$ENTRY_POINT"
         ;;
     --background|-b|--prod|-p)
-        source .venv/bin/activate
         mkdir -p logs
-        nohup python src/main_program.py >> logs/run.log 2>&1 &
+        nohup "$ENTRY_POINT" >> logs/run.log 2>&1 &
         PID="$!"
         echo "DifferentialLab started in background (PID: $PID)"
         echo "Logs: logs/run.log"

bin/setup.sh

@@ -130,17 +130,19 @@ else
     echo "       Virtual environment created"
 fi
 
-echo ""
-echo "[4/7] Activating virtual environment..."
-source .venv/bin/activate
+VENV_PYTHON=".venv/bin/python"
+if [ ! -x "$VENV_PYTHON" ]; then
+    echo "ERROR: Virtual environment Python not found or not executable: $VENV_PYTHON"
+    exit 1
+fi
 
 echo ""
-echo "[5/7] Upgrading pip..."
-python -m pip install --upgrade pip
+echo "[4/7] Upgrading pip..."
+"$VENV_PYTHON" -m pip install --upgrade pip
 
 echo ""
 echo "[6/7] Installing dependencies..."
-python -m pip install -e "$INSTALL_TARGET"
+"$VENV_PYTHON" -m pip install -e "$INSTALL_TARGET"
 
 echo ""
 echo "[7/7] Setting up environment file..."

docs/configuration.md

@@ -37,7 +37,7 @@ and are logged.
 | `UI_BUTTON_FG` | `str` | `lime green` | Primary button text color. |
 | `UI_BUTTON_FG_CANCEL` | `str` | `red2` | Cancel/destructive button text color. |
 | `UI_BUTTON_FG_ACCENT2` | `str` | `yellow` | Secondary accent button text color. |
-| `UI_FONT_SIZE` | `int` | `16` | Base UI font size in points. |
+| `UI_FONT_SIZE` | `int` | `13` | Base UI font size in points. |
 | `UI_FONT_FAMILY` | `str` | `Bahnschrift` | UI font family. |
 | `UI_PADDING` | `int` | `8` | General spacing between UI elements. |
 

docs/getting-started.md

@@ -15,7 +15,8 @@ create the environment yourself before installing the package.
 ### First-time clone and setup
 
 These scripts are intended for users who do not already have the repository.
-They clone the project, run setup, and create a desktop shortcut where possible.
+They clone the project and run setup. On Linux, they also add an application-menu
+launcher and a Desktop launcher when the XDG Desktop directory exists.
 
 Windows:
 
@@ -26,7 +27,6 @@ install.bat
 Linux/macOS:
 
 ```bash
-chmod +x install.sh
 ./install.sh
 ```
 
@@ -41,10 +41,14 @@ bin\setup.bat
 Linux/macOS:
 
 ```bash
-chmod +x bin/setup.sh
 ./bin/setup.sh
 ```
 
+The setup and run scripts use `.venv` directly, so manual activation is not
+required. You can still activate it for manual development commands. Using
+`./bin/run.sh` or `.venv/bin/differential-lab` also avoids import and dependency
+mismatches caused by running with the system Python.
+
 For development work, install the development extras:
 
 ```bat
@@ -110,7 +114,7 @@ bin\run.bat --background  :: Windows background mode, writes logs/run.log
 ./bin/run.sh --background  # Linux/macOS background mode
 ```
 
-Direct run from an activated environment:
+Manual run from an activated environment (activation is optional for the scripts):
 
 ```bash
 python src/main_program.py

install.sh

@@ -76,32 +76,18 @@ if [ -d "$REPO_NAME" ]; then
     else
         echo "       Using existing directory..."
         cd "$REPO_NAME"
-        chmod +x bin/setup.sh
+        chmod +x bin/setup.sh bin/run.sh
         ./bin/setup.sh
         PROJECT_DIR="$(pwd)"
-        DESKTOP="${XDG_DESKTOP_DIR:-$HOME/Desktop}"
-        SHORTCUT="$DESKTOP/DifferentialLab.desktop"
-        ICON_PATH="$PROJECT_DIR/images/DifferentialLab_icon.ico"
-        if [ -d "$DESKTOP" ]; then
-            if [ -f "$ICON_PATH" ]; then
-                ICON_LINE="Icon=$ICON_PATH"
+        chmod +x install.sh bin/setup.sh bin/run.sh
+        if [ "$(uname -s)" = "Linux" ]; then
+            DESKTOP_HELPER="$PROJECT_DIR/bin/linux_desktop.sh"
+            if [ -f "$DESKTOP_HELPER" ]; then
+                source "$DESKTOP_HELPER"
+                create_linux_launchers "$PROJECT_DIR"
             else
-                ICON_LINE="Icon=utilities-terminal"
+                echo "WARNING: Linux desktop helper not found, skipping launcher creation"
             fi
-            cat > "$SHORTCUT" << EOF
-[Desktop Entry]
-Version=1.0
-Type=Application
-Name=DifferentialLab
-Comment=Launch DifferentialLab
-Exec=$PROJECT_DIR/bin/run.sh
-Path=$PROJECT_DIR
-$ICON_LINE
-Terminal=false
-EOF
-            chmod +x "$SHORTCUT"
-            echo ""
-            echo "Desktop shortcut created: $SHORTCUT"
         fi
         exit 0
     fi
@@ -126,38 +112,19 @@ echo ""
 echo "[3/4] Running setup..."
 echo ""
 
-chmod +x bin/setup.sh
+chmod +x install.sh bin/setup.sh bin/run.sh
 ./bin/setup.sh
 
-echo ""
-echo "[4/4] Creating desktop shortcut..."
-
 PROJECT_DIR="$(pwd)"
-DESKTOP="${XDG_DESKTOP_DIR:-$HOME/Desktop}"
-SHORTCUT="$DESKTOP/DifferentialLab.desktop"
-ICON_PATH="$PROJECT_DIR/images/DifferentialLab_icon.ico"
-
-if [ -d "$DESKTOP" ]; then
-    if [ -f "$ICON_PATH" ]; then
-        ICON_LINE="Icon=$ICON_PATH"
+chmod +x install.sh bin/setup.sh bin/run.sh
+if [ "$(uname -s)" = "Linux" ]; then
+    DESKTOP_HELPER="$PROJECT_DIR/bin/linux_desktop.sh"
+    if [ -f "$DESKTOP_HELPER" ]; then
+        source "$DESKTOP_HELPER"
+        create_linux_launchers "$PROJECT_DIR"
     else
-        ICON_LINE="Icon=utilities-terminal"
+        echo "WARNING: Linux desktop helper not found, skipping launcher creation"
     fi
-    cat > "$SHORTCUT" << EOF
-[Desktop Entry]
-Version=1.0
-Type=Application
-Name=DifferentialLab
-Comment=Launch DifferentialLab
-Exec=$PROJECT_DIR/bin/run.sh
-Path=$PROJECT_DIR
-$ICON_LINE
-Terminal=false
-EOF
-    chmod +x "$SHORTCUT"
-    echo "       Desktop shortcut created: $SHORTCUT"
-else
-    echo "       WARNING: Desktop directory not found, skipping shortcut"
 fi
 
 echo ""
@@ -167,5 +134,5 @@ echo "===================================="
 echo ""
 echo "DifferentialLab has been cloned and set up."
 echo "You can now run the application from: $PROJECT_DIR"
-echo "Desktop shortcut: $SHORTCUT"
+echo "Application-menu launcher is available on Linux."
 echo ""

src/config/env.py

@@ -79,7 +79,7 @@
     # --- ui: text / inputs ---
     {
         "key": "UI_FONT_SIZE",
-        "default": 16,
+        "default": 13,
         "cast_type": int,
         "min": 1,
         "description": "Base font size in points used across the UI.",