docs: Update copilot instructions to reflect Phase 4 completion and Phase 5 planning

.github/copilot-instructions.md

@@ -2,39 +2,57 @@
 
 ## Project Context
 
-WebDrop Bridge is a professional Qt-based desktop application that converts web-based drag-and-drop text paths into native file operations. It's designed for production deployment on Windows and macOS with professional-grade testing, documentation, and CI/CD.
+WebDrop Bridge is a professional Qt-based desktop application (v0.5.0) that converts web-based drag-and-drop text paths into native file operations. It's designed for production deployment on Windows and macOS with professional-grade testing, documentation, and CI/CD.
+
+**Current Status**: Phase 4 Complete - Phase 5 (Release Candidates) Planned as of Feb 18, 2026
 
 ## Architecture Overview
 
 - **Framework**: PySide6 (Qt bindings for Python)
+- **Python**: 3.9+ (tested on 3.10, 3.11, 3.12, 3.13, 3.14)
 - **Structure**: Modular (core/, ui/, utils/)
-- **Testing**: pytest with unit, integration, and fixture-based tests
+- **Testing**: pytest with unit and integration tests
 - **Distribution**: PyInstaller → MSI (Windows), DMG (macOS)
+- **Web Integration**: QWebEngineView with security-hardened JavaScript bridge
 
 ## Key Files & Their Purpose
 
 | File | Purpose |
 |------|---------|
-| `src/webdrop_bridge/main.py` | Application entry point |
-| `src/webdrop_bridge/config.py` | Configuration management |
-| `src/webdrop_bridge/core/validator.py` | Path validation and security |
-| `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop handling |
-| `src/webdrop_bridge/core/updater.py` | Update check and release management |
-| `src/webdrop_bridge/ui/main_window.py` | Main Qt window |
-| `tests/` | Pytest-based test suite |
-| `pyproject.toml` | Modern Python packaging |
-| `tox.ini` | Test automation config |
+| `src/webdrop_bridge/__init__.py` | Package info, version (0.5.0) |
+| `src/webdrop_bridge/main.py` | Application entry point, config loading |
+| `src/webdrop_bridge/config.py` | Configuration management (file/env), URL mappings, validation |
+| `src/webdrop_bridge/core/validator.py` | Path validation against whitelist, security checks |
+| `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop event handling |
+| `src/webdrop_bridge/core/config_manager.py` | File-based config loading and caching |
+| `src/webdrop_bridge/core/url_converter.py` | Azure blob URL → local path conversion |
+| `src/webdrop_bridge/core/updater.py` | Update checking via Forgejo API, release management |
+| `src/webdrop_bridge/ui/main_window.py` | Main Qt window, config injection, menu bar |
+| `src/webdrop_bridge/ui/restricted_web_view.py` | Hardened QWebEngineView with security policies |
+| `src/webdrop_bridge/ui/settings_dialog.py` | Settings UI, URL mapping configuration |
+| `src/webdrop_bridge/ui/update_manager_ui.py` | Update check UI and dialogs |
+| `src/webdrop_bridge/utils/logging.py` | Logging configuration (console + file) |
+| `tests/` | pytest-based test suite (unit/ and integration/) |
+| `pyproject.toml` | Modern Python packaging and tool config |
+| `tox.ini` | Test automation (pytest, lint, type, format) |
 
 ## Code Standards
 
 ### Python Style
-- **Formatter**: Black (100 character line length)
-- **Linter**: Ruff
-- **Type Hints**: Required for all public APIs
-- **Docstrings**: Google-style format
+- **Formatter**: Black (88 character line length)
+- **Import Sorter**: isort (black-compatible profile)
+- **Linter**: Ruff (checks style, security, complexity)
+- **Type Checker**: mypy (strict mode for core modules)
+- **Type Hints**: Required for all public APIs and core modules
+- **Docstrings**: Google-style format (module, class, function level)
 
 ### Example
 ```python
+"""Module for path validation."""
+
+from pathlib import Path
+from typing import List
+
 def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
     """Validate path against allowed roots.
 
@@ -50,26 +68,35 @@ def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
 
 ## Before Making Changes
 
-1. **Check the development plan**: See `DEVELOPMENT_PLAN.md` for current phase and priorities
-2. **Understand the architecture**: Read `docs/ARCHITECTURE.md`
-3. **Follow the structure**: Keep code organized in appropriate modules (core/, ui/, utils/)
-4. **Write tests first**: Use TDD approach - write tests before implementing
+1. **Check the development plan**: See [DEVELOPMENT_PLAN.md](../../DEVELOPMENT_PLAN.md) - currently Phase 4 Complete, Phase 5 in planning
+2. **Understand the architecture**: Read [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
+3. **Review actual implementation**: Look at existing modules in core/, ui/, utils/
+4. **Follow the structure**: Keep code organized in appropriate modules
+5. **Write tests**: Use pytest - write tests for new functionality
 
 ## Making Changes
 
-1. **Run existing tests first**: `pytest tests -v`
-2. **Create test file**: `tests/unit/test_*.py`
-3. **Write failing test**: Verify it fails before implementing
-4. **Implement feature**: Follow code standards above
-5. **Run tests**: `pytest tests -v --cov`
-6. **Run quality checks**: `tox -e lint,type`
-7. **Update docs**: Add docstrings and update README if needed
+1. **Run existing tests first**: `pytest tests -v` (should pass)
+2. **Create test file**: `tests/unit/test_*.py` or `tests/integration/test_*.py`
+3. **Write test**: Verify test executes (may fail if feature incomplete)
+4. **Implement feature**: Follow code standards (black, ruff, isort, mypy)
+5. **Format code**: `tox -e format` (auto-formats with black/isort)
+6. **Run all checks**: `tox -e lint,type` (ruff, mypy validation)
+7. **Run tests with coverage**: `pytest tests --cov=src/webdrop_bridge`
+8. **Update docs**: Add/update docstrings, README if needed
 
 ## Development Environment
 
 **Virtual Environment**: `.venv` (already created)
 - Activate: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (macOS/Linux)
 - All Python commands automatically use this environment through VS Code integration
+- **Note**: Only activate if running commands outside VS Code terminal
+
+**Required**: 
+- Python 3.9+ (tested on 3.10, 3.11, 3.12, 3.13, 3.14)
+- PySide6 (for Qt GUI)
+- pytest (for testing)
+- tox (for automated testing and quality checks)
 
 ## Common Commands
 
@@ -77,19 +104,25 @@ def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
 # Setup (one-time)
 pip install -r requirements-dev.txt
 
-# Testing (uses .venv automatically)
-pytest tests -v
-pytest tests --cov=src/webdrop_bridge --cov-report=html
+# Testing
+pytest tests -v                                              # Run all tests
+pytest tests --cov=src/webdrop_bridge                       # With coverage
+pytest tests::test_module -v                                # Specific test
+pytest -k test_validator                                    # By name pattern
 
-# Quality checks
-tox -e lint      # Ruff + Black checks
-tox -e type      # mypy type checking
-tox -e format    # Auto-format code
-tox              # All checks
+# Quality checks (these use tox environments)
+tox -e lint                                                 # Ruff + Black check + isort check
+tox -e format                                               # Auto-format (Black + isort)
+tox -e type                                                 # mypy type checking
+tox -e coverage                                            # Tests with coverage report
+tox                                                        # Run everything
 
-# Building
-python build/scripts/build_windows.py  # Windows
-bash build/scripts/build_macos.sh      # macOS
+# Building distributions
+python build/scripts/build_windows.py                       # Windows (requires pyinstaller, wix)
+bash build/scripts/build_macos.sh                          # macOS (requires pyinstaller, notarization key)
+
+# Running application
+python -m webdrop_bridge.main                              # Start application
 ```
 
 ## Important Decisions
@@ -120,10 +153,17 @@ bash build/scripts/build_macos.sh      # macOS
 # Unit tests: Isolated component testing
 tests/unit/test_validator.py
 tests/unit/test_drag_interceptor.py
+tests/unit/test_url_converter.py
+tests/unit/test_config.py
+tests/unit/test_config_manager.py
+tests/unit/test_logging.py
+tests/unit/test_updater.py
+tests/unit/test_main_window.py
+tests/unit/test_restricted_web_view.py
+tests/unit/test_settings_dialog.py
+tests/unit/test_update_manager_ui.py
 
 # Integration tests: Component interaction and update flow
-tests/integration/test_drag_workflow.py
-tests/integration/test_end_to_end.py
 tests/integration/test_update_flow.py
 
 # Fixtures: Reusable test data
@@ -132,20 +172,27 @@ tests/fixtures/
 ```
 
 Target: 80%+ code coverage
+- Use `pytest --cov=src/webdrop_bridge --cov-report=html` to generate coverage reports
+- Review htmlcov/index.html for detailed coverage breakdown
 
 ## Performance Considerations
 
 - Drag event handling: < 50ms total
 - Application startup: < 1 second
 - Memory baseline: < 200MB
+- Logging overhead: minimize file I/O in drag operations
 
 ## Documentation Requirements
 
-- **Public APIs**: Docstrings required
+- **Public APIs**: Docstrings required (Google-style format)
 - **Modules**: Add docstring at top of file
-- **Features**: Update README.md and docs/
-- **Integration tests**: Reference and document in README.md and docs/ARCHITECTURE.md
-- **Breaking changes**: Update DEVELOPMENT_PLAN.md
+- **Classes**: Document purpose, attributes, and usage in docstring
+- **Functions**: Document args, returns, raises, and examples
+- **Features**: Update [DEVELOPMENT_PLAN.md](../../DEVELOPMENT_PLAN.md) milestones
+- **Architecture changes**: Update [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
+- **Config changes**: Update [CONFIG_README.md](../../CONFIG_README.md)
+- **Breaking changes**: Update CHANGELOG.md and DEVELOPMENT_PLAN.md
+- **Code examples**: Preferred format is in docstrings with >>> syntax
 
 ## Git Workflow
 
@@ -165,38 +212,48 @@ git push origin feature/my-feature
 
 ## Review Checklist
 
-- [ ] Tests pass (100% on CI)
-- [ ] Code follows black/ruff standards
-- [ ] Type hints added for public APIs
-- [ ] Documentation updated
-- [ ] No security concerns
-- [ ] Cross-platform compatibility verified (if applicable)
+- [ ] Tests pass (100% on local runs, `pytest tests -v`)
+- [ ] Code formatted with black/isort (`tox -e format`)
+- [ ] All linting passes (`tox -e lint`)
+- [ ] Type hints complete (`tox -e type` passes)
+- [ ] Docstrings added for all public APIs
+- [ ] No security concerns (especially in path validation)
+- [ ] Cross-platform compatibility verified (Windows + macOS tests if applicable)
+- [ ] Configuration handling tested for edge cases
+- [ ] Git history clean (meaningful commits with proper messages)
 
 ## When You're Stuck
 
-1. **Check DEVELOPMENT_PLAN.md**: Current phase and architecture decisions
-2. **Look at tests**: Existing tests show expected behavior
-3. **Read docstrings**: Functions document their contracts
-4. **Check docs/ARCHITECTURE.md**: Design patterns and data flow
+1. **Check DEVELOPMENT_PLAN.md**: Current phase (Phase 4 Complete) and architecture decisions
+2. **Look at tests**: Existing tests in `tests/unit/` and `tests/integration/` show expected behavior
+3. **Read docstrings**: Functions document their contracts using Google-style format
+4. **Check docs/ARCHITECTURE.md**: Design patterns, data flow, and module organization
+5. **Review config examples**: See [CONFIG_README.md](../../CONFIG_README.md) and `config.example.json`
+6. **Check CI output**: Look at tox and pytest output for detailed error messages
 
 ## What NOT to Do
 
-❌ Change architecture without discussion
-❌ Add dependencies without updating pyproject.toml
-❌ Merge without tests passing
-❌ Remove type hints or docstrings
-❌ Commit without running `tox -e lint,type`
-❌ Add platform-specific code without tests
+❌ Change architecture without reviewing DEVELOPMENT_PLAN.md first
+❌ Add dependencies without updating requirements-dev.txt and pyproject.toml
+❌ Commit without running `tox -e format,lint,type`
+❌ Remove type hints or docstrings from public APIs
+❌ Add imports without running `tox -e format` (isort cleanup)
+❌ Add platform-specific code without tests marked with @pytest.mark.windows or @pytest.mark.macos
+❌ Modify path validation logic without security review
+❌ Force-push to main or release branches
 
 ## Notes for Modifications
 
 - This is a production-quality application, not a PoC
-- Code quality and testing are non-negotiable
-- Cross-platform support (Windows + macOS) is required
-- User security (path validation) is critical
-- Documentation must keep pace with code
+- Code quality, testing, and documentation are non-negotiable
+- Cross-platform support (Windows + macOS) is required and tested
+- User security (path validation) is critical - be extra careful with path operations
+- Configuration must support both .env files and JSON files
+- All error messages should be meaningful and logged appropriately
+- Documentation must keep pace with code changes
 
 ---
 
-**Current Status**: Pre-release development (Phase 1-2)
-**Last Updated**: January 2026
+**Current Status**: Phase 4 Complete (Jan 29, 2026) - Phase 5 (Release Candidates) Planned
+**Version**: 0.5.0
+**Last Updated**: February 18, 2026