feat: Implement centralized version management and sync process

CONTRIBUTING.md

@@ -314,31 +314,159 @@ Integration tests should cover workflows across multiple components. See [tests/
 
 ## Release Process
 
-### Version Numbering
+### Versioning & Release Process
 
-We follow [Semantic Versioning](https://semver.org/):
+### Version Management
 
-- **MAJOR**: Breaking changes
-- **MINOR**: New features (backward compatible)
-- **PATCH**: Bug fixes
+WebDrop Bridge uses **semantic versioning** (MAJOR.MINOR.PATCH). The version is centralized in one location:
 
-Example: `1.2.3` (Major.Minor.Patch)
+**Single Source of Truth**: `src/webdrop_bridge/__init__.py`
 
-### Creating a Release
+```python
+__version__ = "1.0.0"
+```
 
-1. Update version in:
-   - `pyproject.toml`
-   - `src/webdrop_bridge/__init__.py`
+**Shared Version Utility**: `build/scripts/version_utils.py`
 
-2. Update CHANGELOG.md
+All build scripts and version management tools use a shared utility to read the version from `__init__.py`, ensuring consistency across:
+- `pyproject.toml` - Reads dynamically at build time
+- `config.py` - Reads dynamically at startup
+- `.env.example` - Updated by sync script (optional)
+- `CHANGELOG.md` - Updated by sync script
 
-3. Create git tag:
-   ```bash
-   git tag -a v1.2.3 -m "Release version 1.2.3"
-   git push origin v1.2.3
-   ```
+### Releasing a New Version
 
-4. GitHub Actions will automatically build installers
+#### Step 1: Update the Version (Only Place to Edit)
+
+Edit `src/webdrop_bridge/__init__.py` and change `__version__`:
+
+```python
+__version__ = "1.2.0"  # Change this to your new version
+```
+
+#### Step 2: Sync Version to Changelog
+
+Run the sync script to update the changelog:
+
+```bash
+python scripts/sync_version.py
+```
+
+Or let the build script do it automatically:
+
+```bash
+# Windows
+python build/scripts/build_windows.py
+
+# macOS
+bash build/scripts/build_macos.sh
+```
+
+Both the build script and sync script use the shared `build/scripts/version_utils.py` utility.
+
+#### Step 3: Update CHANGELOG.md Manually (Content Only)
+
+The sync script adds the version header with the date. Now add your changes under each section:
+
+```markdown
+## [1.2.0] - 2026-01-15
+
+### Added
+- New feature description
+
+### Changed
+- Breaking change description
+
+### Fixed
+- Bug fix description
+```
+
+#### Step 4: Commit and Tag
+
+```bash
+git add -A
+git commit -m "chore: release v1.2.0
+
+- Feature 1 details
+- Feature 2 details"
+
+git tag -a v1.2.0 -m "Release version 1.2.0"
+git push origin main --tags
+```
+
+### Manual Version Sync (If Needed)
+
+If you need to sync versions without building:
+
+```bash
+python scripts/sync_version.py
+```
+
+To set a specific version:
+
+```bash
+python scripts/sync_version.py --version 1.2.0
+```
+
+### Querying Version in Code
+
+Always import from the package:
+
+```python
+from webdrop_bridge import __version__
+
+print(__version__)  # "1.2.0"
+```
+
+### Environment Override (Development Only)
+
+If needed for testing, you can override with `.env`:
+
+```bash
+# .env (development only)
+APP_VERSION=1.2.0-dev
+```
+
+Config loads it via lazy import (to avoid circular dependencies):
+```python
+if not os.getenv("APP_VERSION"):
+    from webdrop_bridge import __version__
+    app_version = __version__
+else:
+    app_version = os.getenv("APP_VERSION")
+```
+
+### Shared Version Utility
+
+Both build scripts and the sync script use `build/scripts/version_utils.py` to read the version:
+
+```python
+from version_utils import get_current_version, get_project_root
+
+version = get_current_version()  # Reads from __init__.py
+root = get_project_root()        # Gets project root
+```
+
+This ensures:
+- **No duplication** - Single implementation used everywhere
+- **Consistency** - All tools read from the same source
+- **Maintainability** - Update once, affects all tools
+
+If you create new build scripts or tools, import from this utility instead of implementing version reading again.
+
+---
+
+## Summary of Version Management
+
+| Task | How | Location |
+|------|-----|----------|
+| Define version | Edit `__version__` | `src/webdrop_bridge/__init__.py` |
+| Read version in app | Lazy import `__init__.py` | `src/webdrop_bridge/config.py` |
+| Read version in builds | Use shared utility | `build/scripts/version_utils.py` |
+| Update changelog | Run sync script | `scripts/sync_version.py` |
+| Release new version | Edit `__init__.py`, run sync, commit/tag | See "Releasing a New Version" above |
+
+**Golden Rule**: Only edit `src/webdrop_bridge/__init__.py`. Everything else is automated or handled by scripts.
 
 ## Getting Help