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`.