feat: Update documentation for version 0.9.1, including changelog, configuration, and package manager support

CHANGELOG.md

@@ -12,4 +12,4 @@ All notable changes to this project will be documented in this file.
 ### Fixed
 - Removed the generic placeholder release description from published releases.
 - Added a reliable fallback message when no detailed notes are available.
-- instead of using "Profiles" and "Configurations" use setups for more clarity.
+- Instead of using "Profiles" and "Configurations" use "Setups" for more clarity.

CONFIG_README.md

@@ -36,7 +36,10 @@ Create a `config.json` file with the following structure:
   "log_file": "logs/webdrop_bridge.log",
   "window_width": 1024,
   "window_height": 768,
-  "enable_logging": true
+  "enable_logging": true,
+  "language": "auto",
+  "active_branding_id": "default",
+  "brand_id": "agravity"
 }
 ```
 
@@ -99,6 +102,19 @@ Z:\aN5PysnXIuRECzcRbvHkjL7g0\Hintergrund_Agravity.png
 - **`window_width`**, **`window_height`** (number): Initial window size in pixels
   - Default: `1024` x `768`
 
+### Language and Branding Settings
+
+- **`language`** (string): UI language code
+  - Use `"auto"` to follow the system locale automatically
+  - Bundled translations currently include `en`, `de`, `fr`, `it`, `ru`, and `zh`
+
+- **`active_branding_id`** (string): Runtime branding template selected in the Settings dialog
+  - Default: `"default"`
+  - Useful when switching between saved branding templates without rebuilding the app
+
+- **`brand_id`** (string): Stable packaging/update identifier for branded variants
+  - Usually injected during packaging and normally left unchanged by end users
+
 - **`log_level`** (string): Logging verbosity
   - Options: `"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`, `"CRITICAL"`
   - Default: `"INFO"`
@@ -149,6 +165,14 @@ You can configure multiple Azure storage accounts:
 }
 ```
 
+## Configuration Priority
+
+At startup, WebDrop Bridge first loads any bootstrap `.env` defaults and then prefers the persisted JSON config if it exists. This means:
+
+1. packaged or development defaults can still come from `.env`,
+2. the Settings dialog saves the active runtime configuration to JSON, and
+3. the JSON file becomes the main configuration source after first save.
+
 ## Environment Variable Fallback
 
 If no JSON config exists, WebDrop Bridge will load from `.env`:

CONTRIBUTING.md

@@ -9,7 +9,7 @@ Please be respectful and constructive in all interactions. We're building a welc
 ## Getting Started
 
 ### Prerequisites
-- Python 3.10+
+- Python 3.9+
 - Git
 - Familiarity with Qt/PySide6 or willingness to learn
 

DEVELOPMENT_PLAN.md

@@ -1051,7 +1051,7 @@ Help Menu
 
 **Core:**
 - PySide6 6.6.0+
-- Python 3.10+
+- Python 3.9+
 
 **Optional:**
 - PyInstaller (building)

QUICKSTART.md

@@ -143,19 +143,19 @@ brew upgrade webdrop-bridge
 brew uninstall webdrop-bridge
 ```
 
-For more package manager details and internal hosting options, see [docs/PACKAGE_MANAGER_SUPPORT.md](../docs/PACKAGE_MANAGER_SUPPORT.md)
+For more package manager details and internal hosting options, see [docs/PACKAGE_MANAGER_SUPPORT.md](docs/PACKAGE_MANAGER_SUPPORT.md)
 
 #### Simplest: Direct wget (if you know the version)
 
 ```bash
-# Replace VERSION with release tag (e.g., v0.8.0)
+# Replace X.Y.Z with a release version (e.g., 0.9.1)
-wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/VERSION/WebDropBridge_Setup.msi
+wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-win-x64.msi
 
-# Real example - download v0.8.0 MSI
+# Real example - download v0.9.1 MSI
-wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi
+wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-win-x64.msi
 
-# macOS - download v0.8.0 DMG
+# macOS - download v0.9.1 DMG
-wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg
+wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-macos-universal.dmg
 ```
 
 #### Windows (PowerShell) - Full Control Script
@@ -168,7 +168,7 @@ wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0
 .\build\scripts\download_release.ps1 -OutputDir "C:\Installers"
 
 # Download specific version
-.\build\scripts\download_release.ps1 -Version "0.8.0"
+.\build\scripts\download_release.ps1 -Version "0.9.1"
 
 # Skip checksum verification
 .\build\scripts\download_release.ps1 -Verify $false
@@ -186,7 +186,7 @@ wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0
 ./build/scripts/download_release.sh latest ~/Downloads
 
 # Download specific version
-./build/scripts/download_release.sh 0.8.0
+./build/scripts/download_release.sh 0.9.1
 
 # Skip checksum verification
 ./build/scripts/download_release.sh latest --no-verify

README.md

@@ -2,7 +2,7 @@
 
 > Professional Qt-based desktop application for intelligent drag-and-drop file handling between web applications and desktop clients (InDesign, Word, Notepad++, etc.)
 
-![Status](https://img.shields.io/badge/Status-Phase%204%20Complete-green) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
+![Status](https://img.shields.io/badge/Status-Phase%205%20RC%20In%20Progress-green) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
 
 ## Overview
 
@@ -19,23 +19,25 @@ WebDrop Bridge embeds a web application in a Qt container with full filesystem a
 
 ## Features
 
-- ✅ **Qt-based Architecture** - Professional Windows support via PySide6 (macOS support planned)
+- ✅ **Qt-based Architecture** - Professional cross-platform desktop app via PySide6 for Windows and macOS
 - ✅ **Embedded Web App** - QtWebEngine provides Chromium without browser limitations
 - ✅ **Drag Interception** - Converts text paths to native file operations
 - ✅ **Path Whitelist** - Security-conscious file system access control
-- ✅ **Configuration Management** - Profile-based settings with validation
+- ✅ **Configuration Management** - JSON config, profile import/export, and validation
-- ✅ **Settings Dialog** - Professional UI for path, URL, logging, and window configuration
+- ✅ **Runtime Branding** - Switch branding templates and packaged variants without code changes
+- ✅ **Multilingual UI** - Built-in translations for English, German, French, Italian, Russian, and Chinese
+- ✅ **Settings Dialog** - Language, branding, web source, path, URL, logging, and window configuration
 - ✅ **Auto-Update System** - Automatic release detection via Forgejo API
 - ✅ **Professional Build Pipeline** - MSI for Windows, DMG for macOS
-- ✅ **Comprehensive Testing** - Unit, integration, and end-to-end tests (80%+ coverage)
+- ✅ **Comprehensive Testing** - Unit and integration coverage across core modules
-- ✅ **Continuous Testing** - GitHub Actions test automation
+- ✅ **Continuous Testing** - Automated CI validation
 - ✅ **Structured Logging** - File-based logging with configurable levels
 
 ## Quick Start
 
 ### Requirements
-- Python 3.10+
+- Python 3.9+
-- Windows 10/11
+- Windows 10/11 or macOS 12+
 - 200 MB disk space (includes Chromium from PyInstaller)
 
 ### Installation from Pre-Built Release (Recommended)
@@ -58,11 +60,11 @@ brew upgrade webdrop-bridge  # Update to latest version
 **Option 2: Direct wget (if you know the version)**
 
 ```bash
-# Replace VERSION with release tag (e.g., v0.8.0)
+# Replace X.Y.Z with a release version (e.g., 0.9.1)
-wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/VERSION/WebDropBridge_Setup.msi
+wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-win-x64.msi
 
-# Example for v0.8.0:
+# Example for v0.9.1:
-wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi
+wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-win-x64.msi
 ```
 
 **Option 3: Automated script (auto-detects platform)**
@@ -93,6 +95,7 @@ python -m venv venv
 
 # Install dependencies
 pip install -r requirements.txt
+pip install -e .
 
 # Run application
 python -m webdrop_bridge.main
@@ -103,6 +106,7 @@ python -m webdrop_bridge.main
 ```bash
 # Install development dependencies
 pip install -r requirements-dev.txt
+pip install -e .
 
 # Run tests
 pytest tests -v
@@ -178,42 +182,36 @@ webdrop-bridge/
 
 ## Configuration
 
-WebDrop Bridge supports two configuration methods:
+WebDrop Bridge supports persisted JSON configuration plus optional bootstrap environment defaults.
 
-### 1. Settings Dialog (Recommended)
+### 1. Settings Dialog / JSON Config (Recommended)
 Launch the application and access the Settings menu to configure:
-- **Paths Tab** - Add/remove allowed root directories
+- **General Tab** - Select the UI language or follow the system locale automatically
-- **URLs Tab** - Configure allowed web URLs (whitelist mode)
+- **Branding Tab** - Switch, import, export, and preview runtime branding templates
-- **Logging Tab** - Set log level and file location
+- **Web Source Tab** - Configure the embedded web application URL
-- **Window Tab** - Configure window dimensions
+- **Paths / URLs / Logging / Window Tabs** - Control filesystem access, allowed sites, log output, and initial window size
-- **Profiles Tab** - Save/load/export-import configuration profiles
+- **Profiles Tab** - Save, load, import, and export complete configuration profiles
 
-Profiles are saved in `~/.webdrop_bridge/profiles/`
+Saved settings are written to the brand-specific application config directory as `config.json`.
 
-### 2. Environment Variables
+### 2. Bootstrap Environment Variables (`.env`)
-Create a `.env` file in the project root. Available settings:
+A `.env` file is still supported for local development and branded packaged defaults. It is used when no JSON config exists yet.
 
 ```bash
-# Application
 APP_NAME=WebDrop Bridge
-APP_VERSION=1.0.0
+BRAND_ID=webdrop_bridge
-
+WEBAPP_URL=https://dev.agravity.io/
-# Paths (comma-separated)
 ALLOWED_ROOTS=Z:/,C:/Users/Public
-
-# Web URLs (empty = no restriction, items = kiosk mode)
 ALLOWED_URLS=
-
+LANGUAGE=auto
-# Interface
+LOG_LEVEL=INFO
-WEBAPP_URL=file:///./webapp/index.html
 WINDOW_WIDTH=1024
 WINDOW_HEIGHT=768
-
-# Logging
-LOG_LEVEL=INFO
 ENABLE_LOGGING=true
 ```
 
+For the full JSON structure and branding workflow, see [CONFIG_README.md](CONFIG_README.md) and [BRANDING_AND_RELEASES.md](docs/BRANDING_AND_RELEASES.md).
+
 ## Testing
 
 WebDrop Bridge includes comprehensive test coverage with unit, integration, and end-to-end tests.
@@ -272,11 +270,20 @@ python build/scripts/build_windows.py --msi --code-sign
 ```
 
 Output:
-- Portable executable: `build/dist/windows/WebDropBridge/WebDropBridge.exe` (~195 MB)
+- Portable executable: `build/dist/windows/webdrop_bridge/WebDropBridge/WebDropBridge.exe`
-- Professional MSI installer: `build/dist/windows/WebDropBridge-{version}-Setup.msi`
+- Professional MSI installer: `build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi`
-- SHA256 checksum: `build/dist/windows/WebDropBridge/WebDropBridge.exe.sha256`
+- SHA256 checksum: `build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi.sha256`
 
-**Note on macOS**: Build scripts exist for macOS (DMG generation), but have never been built or tested. macOS support is theoretical at this point. The Qt/PySide6 architecture should support macOS, but platform-specific testing and validation would be required.
+### macOS DMG Installer
+
+```bash
+bash build/scripts/build_macos.sh
+```
+
+Output:
+- Application bundle: `build/dist/macos/webdrop_bridge/WebDropBridge.app`
+- DMG installer: `build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg`
+- SHA256 checksum: `build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg.sha256`
 
 ### Creating Releases
 
@@ -314,8 +321,8 @@ powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1
 ## Troubleshooting
 
 ### Application won't start
-- Ensure Python 3.10+ is installed
+- Ensure Python 3.9+ is installed
-- Check `logs/webdrop_bridge.log` for errors
+- Check the application log in your platform-specific app data directory
 - Verify all dependencies: `pip list`
 
 ### Drag-and-drop not working
@@ -332,10 +339,10 @@ powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1
 
 | Platform | Version | Status | Notes |
 |----------|---------|--------|-------|
-| Windows | 10, 11 | ✅ Full | Tested on x64, MSI installer support |
+| Windows | 10, 11 | ✅ Full | Primary target with MSI packaging and update support |
-| macOS | 12+ | ⚠️ **Untested** | Possible via Qt/PySide6, but never built or tested. Theoretical support only. |
+| macOS | 12, 13, 14 | ✅ Supported | Universal DMG builds for Intel and Apple Silicon |
 
-**Note**: WebDrop Bridge is currently developed and tested exclusively on Windows. While the Qt/PySide6 framework supports macOS, we cannot guarantee functionality without actual macOS testing and validation. Contributions for macOS support validation are welcome.
+**Note**: Release candidates currently target both Windows and macOS. For branded production releases, validate signing assets and installer behavior on the target platform before shipping.
 
 ## Contributing
 
@@ -367,4 +374,4 @@ MIT License - see [LICENSE](LICENSE) file for details
 
 ---
 
-**Development Phase**: Phase 4 Complete | **Last Updated**: February 18, 2026 | **Current Version**: 1.0.0 | **Python**: 3.10+ | **Qt**: PySide6 (Qt 6)
+**Development Phase**: Phase 5 Release Candidates | **Last Updated**: April 16, 2026 | **Current Version**: 0.9.1 | **Python**: 3.9+ | **Qt**: PySide6 (Qt 6)

build/package-managers/README.md

@@ -27,7 +27,7 @@ build/
 
 2. **Get SHA256 checksum**:
    ```powershell
-   certutil -hashfile build/dist/windows/WebDropBridge_Setup.msi SHA256
+   certutil -hashfile build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi SHA256
    ```
 
 3. **Update package files**:
@@ -42,7 +42,7 @@ build/
 
 5. **Publish** (requires Chocolatey API key):
    ```powershell
-   choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY
+   choco push webdrop-bridge.<version>.nupkg --api-key YOUR_KEY
    ```
 
 ### Homebrew Formula (macOS)
@@ -54,7 +54,7 @@ build/
 
 2. **Get SHA256 checksum**:
    ```bash
-   shasum -a 256 build/dist/macos/WebDropBridge_Setup.dmg
+   shasum -a 256 build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg
    ```
 
 3. **Update formula**:

build/scripts/README.md

@@ -75,8 +75,8 @@ The `download_release.ps1` (Windows) and `download_release.sh` (macOS/Linux) scr
 
 ```bash
 # Download directly by version tag
-wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi
+wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-win-x64.msi
-wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg
+wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-macos-universal.dmg
 ```
 
 **If you need to auto-detect latest (with grep/cut, no jq needed)**
@@ -111,7 +111,7 @@ sha256sum -c installer.sha256
 .\download_release.ps1
 
 # Specific version to Downloads folder
-.\download_release.ps1 -Version "0.8.0" -OutputDir "$env:USERPROFILE\Downloads"
+.\download_release.ps1 -Version "0.9.1" -OutputDir "$env:USERPROFILE\Downloads"
 
 # Skip checksum verification
 .\download_release.ps1 -Verify $false
@@ -124,7 +124,7 @@ sha256sum -c installer.sha256
 ./build/scripts/download_release.sh
 
 # Specific version to Downloads
-./build/scripts/download_release.sh 0.8.0 ~/Downloads
+./build/scripts/download_release.sh 0.9.1 ~/Downloads
 
 # Skip checksum verification
 ./build/scripts/download_release.sh latest --no-verify
@@ -165,7 +165,7 @@ Automated release creation with versioning and asset uploads.
 Manages consistent versioning across the project.
 
 ```bash
-python build/scripts/sync_version.py --version 0.8.0
+python build/scripts/sync_version.py --version 0.9.1
 ```
 
 ## Integration Flow

docs/CONFIGURATION_BUILD.md

@@ -1,33 +1,60 @@
 # Configuration Management for Builds
 
-This document explains how configuration is handled when building executables and installers for WebDrop Bridge.
+This document explains how configuration and branding work for development builds, packaged installers, and installed applications.
 
-## Overview
+## Current Configuration Model
 
-WebDrop Bridge uses `.env` files for runtime configuration. When building distributable packages (exe, MSI, or DMG), the `.env` file is **bundled into the application** so that users receive pre-configured settings.
+WebDrop Bridge now uses a **JSON-first runtime configuration** with optional `.env` bootstrap defaults:
 
-## Configuration File
+1. **Bootstrap `.env`** (optional)
+   - Loaded very early during startup
+   - Useful for packaged defaults such as `APP_NAME`, `BRAND_ID`, update channel, and default web source
+   - Commonly used by branded Windows/MSI and macOS/DMG builds
 
-The configuration file must be named `.env` and contains settings like:
+2. **Persisted JSON config** (preferred)
+   - Windows: `%APPDATA%\<config_dir_name>\config.json`
+   - macOS/Linux: `~/.config/<config_dir_name>/config.json`
+   - Created and maintained by the Settings dialog
+   - Takes precedence for day-to-day user settings after first launch
+
+In practice, installers can ship with a curated `.env`, while user changes are saved into `config.json`.
+
+## What Belongs Where?
+
+### Use JSON config for:
+- `url_mappings`
+- `allowed_roots`
+- `allowed_urls`
+- window size and logging settings
+- `language`
+- `active_branding_id`
+
+### Use `.env` bootstrap defaults for:
+- `APP_NAME`
+- `BRAND_ID`
+- `APP_CONFIG_DIR_NAME`
+- update channel and repository defaults
+- packaged first-launch defaults for customer-specific builds
+
+## Example Bootstrap `.env`
 
 ```dotenv
 APP_NAME=WebDrop Bridge
-APP_VERSION=0.7.1
+BRAND_ID=webdrop_bridge
+APP_CONFIG_DIR_NAME=webdrop_bridge
 WEBAPP_URL=https://example.com
 ALLOWED_ROOTS=Z:/,C:/Users/Public
 ALLOWED_URLS=
+LANGUAGE=auto
 LOG_LEVEL=INFO
-LOG_FILE=logs/webdrop_bridge.log
 ENABLE_LOGGING=true
 WINDOW_WIDTH=1024
 WINDOW_HEIGHT=768
 ```
 
-See `.env.example` for a template with all available options.
-
 ## Building with Default Configuration
 
-If you want to use the project's `.env` file (in the project root), simply run:
+If you want to use the project's default `.env` file from the repository root:
 
 ### Windows
 ```bash
@@ -39,11 +66,11 @@ python build/scripts/build_windows.py --msi
 bash build/scripts/build_macos.sh
 ```
 
-**Important:** The build will **fail** if `.env` doesn't exist. This prevents accidentally shipping without configuration.
+> The build scripts currently expect a `.env` file to exist. This is intentional so packaged builds always have explicit bootstrap defaults.
 
-## Building with Custom Configuration
+## Building with Custom Customer Defaults
 
-For different customers or deployments, you can specify a custom `.env` file:
+For customer-specific or branded releases, provide a different `.env` file during packaging:
 
 ### Windows
 ```bash
@@ -55,86 +82,73 @@ python build/scripts/build_windows.py --msi --env-file path/to/customer1.env
 bash build/scripts/build_macos.sh --env-file path/to/customer1.env
 ```
 
-The custom `.env` file will be bundled into the executable and users will receive those pre-configured settings.
+This bundles those bootstrap defaults into the packaged app while still allowing the installed application to persist later changes in JSON.
 
 ## Example: Multi-Customer Setup
 
-If you have different customer configurations:
+```text
-
-```
 webdrop_bridge/
-├── .env                           # Default project configuration
+├── .env
-├── .env.example                   # Template
 ├── build/
 │   └── scripts/
 │       ├── build_windows.py
 │       └── build_macos.sh
-├── customer_configs/              # Create this for customer-specific settings
+├── customer_configs/
 │   ├── acme_corp.env
 │   ├── globex_corporation.env
 │   └── initech.env
-└── ...
+└── config.example.json
 ```
 
-Then build for each customer:
+Then build per customer or brand:
 
 ```bash
-# ACME Corp
 python build/scripts/build_windows.py --msi --env-file customer_configs/acme_corp.env
-
-# Globex Corporation
 python build/scripts/build_windows.py --msi --env-file customer_configs/globex_corporation.env
-
+bash build/scripts/build_macos.sh --env-file customer_configs/initech.env
-# Initech
-python build/scripts/build_windows.py --msi --env-file customer_configs/initech.env
 ```
 
-Each MSI will include that customer's specific configuration (URLs, allowed paths, etc.).
+## What Gets Bundled into Installers?
 
-## What Gets Bundled
+During packaging, the supplied `.env` file is bundled so the application can resolve:
+- app display name
+- brand/config directory name
+- update channel defaults
+- initial web source and logging defaults
 
-When building, the `.env` file is:
+After installation, the application normally saves user-controlled settings to the JSON config file in the app data directory.
-1. ✅ Copied into the PyInstaller bundle
-2. ✅ Extracted to the application's working directory when the app starts
-3. ✅ Automatically loaded by `Config.from_env()` at startup
 
-Users **do not** need to create their own `.env` files.
+## Recommended Runtime Workflow
 
-## After Installation
+1. Package the app with the correct `.env` bootstrap defaults.
-
+2. Launch the app once.
-When users run the installed application:
+3. Configure URLs, mappings, language, and branding in the Settings dialog.
-1. The embedded `.env` is automatically available
+4. Let the app save `config.json` in the brand-specific config directory.
-2. Settings are loaded and applied
+5. Reuse exported profiles or branding templates for future setups.
-3. Users can optionally create a custom `.env` in the installation directory to override settings
-
-This allows:
-- **Pre-configured deployments** for your customers
-- **Easy customization** by users (just edit the `.env` file)
-- **No manual setup** required after installation
 
 ## Build Command Reference
 
 ### Windows
 ```bash
-# Default (.env from project root)
+# Default build using the repository root .env
 python build/scripts/build_windows.py --msi
 
-# Custom .env file
+# Customer-specific defaults
 python build/scripts/build_windows.py --msi --env-file customer_configs/acme.env
 
-# Without MSI (just EXE)
+# Without MSI (just the packaged executable)
 python build/scripts/build_windows.py
 
-# Sign executable (requires CODE_SIGN_CERT env var)
+# Sign executable (requires signing setup)
 python build/scripts/build_windows.py --msi --code-sign
 ```
 
 ### macOS
 ```bash
-# Default (.env from project root)
+# Default build using the repository root .env
 bash build/scripts/build_macos.sh
 
-# Custom .env file
+# Customer-specific defaults
 bash build/scripts/build_macos.sh --env-file customer_configs/acme.env
 
 # Sign app (requires Apple developer certificate)
@@ -144,19 +158,11 @@ bash build/scripts/build_macos.sh --sign
 bash build/scripts/build_macos.sh --notarize
 ```
 
-## Configuration Validation
+## Validation Notes
 
 The build process validates that:
-1. ✅ The specified `.env` file exists
+1. the specified `.env` file exists,
-2. ✅ All required environment variables are present
+2. packaging metadata can be resolved, and
-3. ✅ Values are valid (LOG_LEVEL is valid, paths exist for ALLOWED_ROOTS, etc.)
+3. the resulting installer assets are created successfully.
 
-If validation fails, the build stops with a clear error message.
+If you need the full runtime JSON schema, see `CONFIG_README.md`.
-
-## Version Management
-
-The `APP_VERSION` is read from two places (in order):
-1. `.env` file (if specified)
-2. `src/webdrop_bridge/__init__.py` (as fallback)
-
-This allows you to override the version per customer if needed.

docs/CUSTOMER_BUILD_EXAMPLES.md

@@ -20,7 +20,7 @@ webdrop_bridge/
 python build/scripts/build_windows.py --msi
 ```
 
-**Result:** `WebDropBridge-x.x.x-Setup.msi` with your `.env` configuration bundled.
+**Result:** `WebDropBridge-<version>-win-x64.msi` with your packaged bootstrap defaults bundled.
 
 ---
 
@@ -47,7 +47,7 @@ webdrop_bridge/
 **Customer Config Example:** `deploy/customer_configs/acme_corp.env`
 ```dotenv
 APP_NAME=WebDrop Bridge - ACME Corp Edition
-APP_VERSION=1.0.0
+BRAND_ID=acme_corp
 WEBAPP_URL=https://acme-drop.example.com/drop
 ALLOWED_ROOTS=Z:/acme_files/,C:/Users/Public/ACME
 LOG_LEVEL=INFO
@@ -72,9 +72,9 @@ python build/scripts/build_windows.py --msi --env-file deploy/customer_configs/i
 python build/scripts/build_windows.py --msi --env-file deploy/customer_configs/wayne_enterprises.env
 ```
 
-**Result:** Four separate MSI files:
+**Result:** Four separate MSI files, for example:
-- `WebDropBridge-1.0.0-Setup.msi` (ACME - says "ACME Corp Edition")
+- `WebDropBridge-<version>-win-x64.msi` (default brand)
-- `WebDropBridge-1.0.0-Setup.msi` (Globex - say "Globex Edition")
+- `AcmeBridge-<version>-win-x64.msi` (if the customer build uses its own asset prefix)
 - etc.
 
 ---

docs/PACKAGE_MANAGER_SUPPORT.md

@@ -20,16 +20,16 @@ WebDropBridge supports installation via package managers, making it easier for u
 # 1. Build the Chocolatey package
 cd build/chocolatey
 python ../../build/scripts/build_windows.py --msi
-certutil -hashfile "../../build/dist/windows/WebDropBridge_Setup.msi" SHA256
+certutil -hashfile "../../build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi" SHA256
 # Update checksum in tools/chocolateyInstall.ps1
 choco pack webdrop-bridge.nuspec
 
-# 2. Share webdrop-bridge.0.8.0.nupkg
+# 2. Share webdrop-bridge.<version>.nupkg
 #    File share: \\server\packages\
 #    USB drive, email, Forgejo releases, etc.
 
 # 3. Users install it
-#    choco install webdrop-bridge.0.8.0.nupkg -s "\\server\packages"
+#    choco install webdrop-bridge.<version>.nupkg -s "\\server\packages"
 ```
 
 **Advantages:**
@@ -56,21 +56,21 @@ choco pack webdrop-bridge.nuspec
 python build/scripts/build_windows.py --msi
 
 # 2. Calculate SHA256 checksum of the MSI
-certutil -hashfile "build/dist/windows/WebDropBridge_Setup.msi" SHA256
+certutil -hashfile "build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi" SHA256
 
 # 3. Update the checksum in build/chocolatey/tools/chocolateyInstall.ps1
 #    Replace: $Checksum = ''
 #    With:    $Checksum = 'YOUR_SHA256_HASH'
 
 # 4. Update version in chocolatey/webdrop-bridge.nuspec
-#    <version>0.8.0</version>
+#    <version>X.Y.Z</version>
 
 # 5. Create the package
 cd build/chocolatey
 choco pack webdrop-bridge.nuspec
 ```
 
-This creates `webdrop-bridge.0.8.0.nupkg`
+This creates `webdrop-bridge.<version>.nupkg`
 
 ### Publishing to Chocolatey
 
@@ -83,7 +83,7 @@ Host on your own NuGet server (Azure Artifacts, Artifactory, ProGet, etc.):
 choco source add -n=internal-repo -s "https://your-artifactory.internal/nuget/chocolatey/"
 
 # Push package to internal repo
-nuget push webdrop-bridge.0.8.0.nupkg -Source https://your-artifactory.internal/nuget/chocolatey/ -ApiKey YOUR_API_KEY
+nuget push webdrop-bridge.<version>.nupkg -Source https://your-artifactory.internal/nuget/chocolatey/ -ApiKey YOUR_API_KEY
 
 # Users install from internal repo (already configured)
 choco install webdrop-bridge
@@ -95,7 +95,7 @@ If you want public distribution (requires community maintainer account):
 
 ```bash
 # Push to community repo
-choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_CHOCOLATEY_API_KEY
+choco push webdrop-bridge.<version>.nupkg --api-key YOUR_CHOCOLATEY_API_KEY
 ```
 
 **Option 3: No Repository (Direct Distribution)**
@@ -103,8 +103,8 @@ choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_CHOCOLATEY_API_KEY
 Share the `.nupkg` file directly, users install locally:
 
 ```powershell
-# User downloads webdrop-bridge.0.8.0.nupkg and runs:
+# User downloads webdrop-bridge.<version>.nupkg and runs:
-choco install webdrop-bridge.0.8.0.nupkg -s C:\path\to\package\folder
+choco install webdrop-bridge.<version>.nupkg -s C:\path\to\package\folder
 ```
 
 ### User Installation
@@ -119,7 +119,7 @@ choco install webdrop-bridge
 choco install webdrop-bridge
 
 # If distributing directly
-choco install webdrop-bridge.0.8.0.nupkg -s "\\network\share\packages"
+choco install webdrop-bridge.<version>.nupkg -s "\\network\share\packages"
 ```
 
 ## Homebrew (macOS)
@@ -183,11 +183,11 @@ Submit to `homebrew/casks` (requires more maintenance but no separate tap):
 bash build/scripts/build_macos.sh
 
 # 2. Calculate SHA256 checksum
-shasum -a 256 "build/dist/macos/WebDropBridge_Setup.dmg"
+shasum -a 256 "build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg"
 
 # 3. Update formula with checksum and URL
 #    build/homebrew/webdrop-bridge.rb
-#    - url: https://git.him-tools.de/...releases/download/vX.X.X/WebDropBridge_Setup.dmg
+#    - url: https://git.him-tools.de/...releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-macos-universal.dmg
 #    - sha256: YOUR_SHA256_HASH
 ```
 
@@ -210,7 +210,7 @@ webdrop-bridge --version  # If CLI exists, or check Applications folder
 ### Step 1: Build Release
 
 ```bash
-# Release v0.8.0
+# Release vX.Y.Z
 
 # Windows MSI
 python build/scripts/build_windows.py --msi
@@ -224,8 +224,8 @@ bash build/scripts/build_macos.sh
 Tag and upload installers to Forgejo:
 
 ```bash
-git tag -a v0.8.0 -m "Release 0.8.0"
+git tag -a vX.Y.Z -m "Release X.Y.Z"
-git push upstream v0.8.0
+git push upstream vX.Y.Z
 
 # Upload MSI and DMG to Forgejo release page
 ```
@@ -234,10 +234,10 @@ git push upstream v0.8.0
 
 ```bash
 # Windows
-certutil -hashfile WebDropBridge_Setup.msi SHA256
+certutil -hashfile WebDropBridge-<version>-win-x64.msi SHA256
 
 # macOS
-shasum -a 256 WebDropBridge_Setup.dmg
+shasum -a 256 WebDropBridge-<version>-macos-universal.dmg
 ```
 
 ### Step 4: Update Package Manager Files
@@ -258,7 +258,7 @@ sha256 "MACOS_SHA256_HASH"
 ```powershell
 cd build/chocolatey
 choco pack
-choco install webdrop-bridge.0.8.0.nupkg -s .
+choco install webdrop-bridge.<version>.nupkg -s .
 ```
 
 **Homebrew (with tap):**
@@ -270,7 +270,7 @@ brew install ./build/homebrew/webdrop-bridge.rb
 
 **Chocolatey:**
 ```powershell
-choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY
+choco push webdrop-bridge.<version>.nupkg --api-key YOUR_KEY
 ```
 
 **Homebrew:**
@@ -343,7 +343,7 @@ This works for:
 ### Chocolatey Issues
 
 **Package won't install:**
-- Verify checksum: `certutil -hashfile WebDropBridge_Setup.msi SHA256`
+- Verify checksum: `certutil -hashfile WebDropBridge-<version>-win-x64.msi SHA256`
 - Check MSI exists at URL: `wget URL`
 - Verify SHA256 matches in `chocolateyInstall.ps1`
 
@@ -356,7 +356,7 @@ This works for:
 **Formula won't install:**
 - Validate syntax: `brew audit --formula webdrop-bridge.rb`
 - Check URL is accessible: `curl -I URL`
-- Verify SHA256: `shasum -a 256 WebDropBridge_Setup.dmg`
+- Verify SHA256: `shasum -a 256 WebDropBridge-<version>-macos-universal.dmg`
 
 **Upgrade fails:**
 - Remove old version: `brew uninstall webdrop-bridge`
@@ -375,7 +375,7 @@ This works for:
 
 1. **Easiest: Direct Distribution** ✅
    - Share `.nupkg` file via file share or email
-   - Users: `choco install webdrop-bridge.0.8.0.nupkg -s "\\share\packages"`
+   - Users: `choco install webdrop-bridge.<version>.nupkg -s "\\share\packages"`
    - No infrastructure needed
    - No maintainer account required