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

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.example                   # Template
+├── .env
 ├── 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
-
-# Initech
-python build/scripts/build_windows.py --msi --env-file customer_configs/initech.env
+bash build/scripts/build_macos.sh --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:
-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
+After installation, the application normally saves user-controlled settings to the JSON config file in the app data directory.
 
-Users **do not** need to create their own `.env` files.
+## Recommended Runtime Workflow
 
-## After Installation
-
-When users run the installed application:
-1. The embedded `.env` is automatically available
-2. Settings are loaded and applied
-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
+1. Package the app with the correct `.env` bootstrap defaults.
+2. Launch the app once.
+3. Configure URLs, mappings, language, and branding in the Settings dialog.
+4. Let the app save `config.json` in the brand-specific config directory.
+5. Reuse exported profiles or branding templates for future setups.
 
 ## 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
-2. ✅ All required environment variables are present
-3. ✅ Values are valid (LOG_LEVEL is valid, paths exist for ALLOWED_ROOTS, etc.)
+1. the specified `.env` file exists,
+2. packaging metadata can be resolved, and
+3. the resulting installer assets are created successfully.
 
-If validation fails, the build stops with a clear error message.
-
-## 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.
+If you need the full runtime JSON schema, see `CONFIG_README.md`.

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:
-- `WebDropBridge-1.0.0-Setup.msi` (ACME - says "ACME Corp Edition")
-- `WebDropBridge-1.0.0-Setup.msi` (Globex - say "Globex Edition")
+**Result:** Four separate MSI files, for example:
+- `WebDropBridge-<version>-win-x64.msi` (default brand)
+- `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:
-choco install webdrop-bridge.0.8.0.nupkg -s C:\path\to\package\folder
+# User downloads webdrop-bridge.<version>.nupkg and runs:
+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 push upstream v0.8.0
+git tag -a vX.Y.Z -m "Release X.Y.Z"
+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