Merge branch 'feat-multiple-edit-tags-and-actions' into deploy-synology

Combine labels/metadata system with global filters, 2-tier caching, and Synology deployment.

Merged features from both branches:
- Labels system: 62 tests, metadata API endpoints, complete documentation (feat-multiple-edit-tags-and-actions)
- Global filters: 18 predefined queries + 4 advanced filters (feat-global-filters via feat-multiple-edit-tags-and-actions)
- 2-tier caching: Memory (15min) + DB (24h) for IGDB data (feat-global-filters)
- Xbox integration + auth system + Docker detection (feat-global-filters)
- CSS refactoring: Externalized 2000+ lines inline CSS (feat-global-filters)
- Synology deployment: BACKLOGIA_DATA_DIR configuration support (deploy-synology)

Conflict resolution:
- .env.example: Preserved both BACKLOGIA_DATA_DIR (Synology) and ENABLE_AUTH (incoming)
- .gitignore: Updated OpenSpec workflow comments
- CHANGELOG.md: Merged feature sections from both branches
- web/main.py: Merged labels DB setup + auth config + labels system initialization
- web/routes/library.py: Combined personal_rating/priority sorting + advanced filters
- web/routes/settings.py: Added Xbox credentials fields
- web/templates/game_detail.html: Used incoming version with CSS improvements

Additional fixes:
- web/database.py: Added from feat-multiple-edit-tags-and-actions (labels migrations)
- web/routes/api_metadata.py: Complete version with priority/rating endpoints
- web/services/system_labels.py: Auto-tagging system

Test results: 195 tests passing
- 121 from feat-global-filters (filters, caching, performance)
- 74 from feat-multiple-edit-tags-and-actions (labels, metadata, migrations)

Docker: Tested successfully, migrations execute cleanly

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: davidp57

.env.example

@@ -33,4 +33,8 @@ GOG_DB_DIR=C:/ProgramData/GOG.com/Galaxy/storage
 # data directory for storing Backlogia's database and config files
 # This should be a persistent volume in production to retain data across container restarts
 # For development, you can set this to a local directory (e.g., ./data)
-# BACKLOGIA_DATA_DIR=/path/to/backlogia/root/dir
+# BACKLOGIA_DATA_DIR=/path/to/backlogia/root/dir
+
+# Authentication (optional)
+# ENABLE_AUTH=true
+# SESSION_EXPIRY_DAYS=30

.gitignore

@@ -1,9 +1,10 @@
-game_library.db
+*.db
+.DS_Store
 
 # Copilot documentation
 .copilot-docs/
 
-# OpenSpec workflow
+# OpenSpec workflow and GitHub configs
 openspec/
 
 # Ignore specific GitHub config (but allow workflows)
@@ -232,3 +233,24 @@ __marimo__/
 
 # Claude code
 .claude/
+.github/prompts/opsx-apply.prompt.md
+.github/prompts/opsx-archive.prompt.md
+.github/prompts/opsx-bulk-archive.prompt.md
+.github/prompts/opsx-continue.prompt.md
+.github/prompts/opsx-explore.prompt.md
+.github/prompts/opsx-ff.prompt.md
+.github/prompts/opsx-new.prompt.md
+.github/prompts/opsx-onboard.prompt.md
+.github/prompts/opsx-sync.prompt.md
+.github/prompts/opsx-verify.prompt.md
+.github/skills/openspec-apply-change/SKILL.md
+.github/skills/openspec-archive-change/SKILL.md
+.github/skills/openspec-bulk-archive-change/SKILL.md
+.github/skills/openspec-continue-change/SKILL.md
+.github/skills/openspec-explore/SKILL.md
+.github/skills/openspec-ff-change/SKILL.md
+.github/skills/openspec-new-change/SKILL.md
+.github/skills/openspec-onboard/SKILL.md
+.github/skills/openspec-sync-specs/SKILL.md
+.github/skills/openspec-verify-change/SKILL.md
+.github/copilot-instructions.md

CHANGELOG.md

@@ -8,63 +8,137 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **Editable local games paths in Settings UI (non-Docker)**: Users running Backlogia locally can now configure game folder paths directly from the Settings page without needing to edit environment variables or .env files
-- **Docker deployment detection**: Automatically detects Docker environment and adapts UI accordingly
+
+**From feat-multiple-edit-tags-and-actions branch:**
+- **Comprehensive test coverage for labels system**: 62 new tests covering all metadata and bulk operations:
+  - API integration tests (32 tests): All priority, rating, manual tag, and bulk operation endpoints
+  - Database migration tests (12 tests): Collections→labels migration, metadata columns, CASCADE behavior
+  - Manual tag persistence tests (5 tests): Auto vs manual tag conflict resolution, non-Steam games
+  - Edge case tests (13 tests): Games with all metadata, system label deletion, NULL playtime handling, large library performance
+- **Complete API documentation**: New `docs/api-metadata-endpoints.md` with request/response examples, curl commands, and error codes for all 13 metadata endpoints
+- **Enhanced user documentation**: 
+  - Quick Start guide with step-by-step workflows (auto-tagging, priorities, ratings, bulk actions, collections)
+  - FAQ section with 12 common questions (e.g., "Why aren't my Epic games auto-tagged?", "Do manual tags get overwritten?")
+  - Keyboard shortcuts documentation for multi-select mode (Shift-click range selection)
+- **Developer contribution guide**: New `docs/contributing-labels-system.md` with:
+  - System architecture diagrams (database schema, auto column lifecycle)
+  - Tutorial for adding new system labels with code examples
+  - Tutorial for adding new metadata fields (completion_status example)
+  - Performance optimization techniques (batch processing, caching, indexing)
+  - Migration best practices (idempotency, testing, rollback procedures)
+
+**From feat-global-filters branch (Merge MAIN → feat-global-filters):**
 - **Predefined query filters system**: 18 quick filters organized in 4 categories for better library organization:
   - **Gameplay** (5 filters): Unplayed, Played, Started, Well-Played, Heavily-Played
   - **Ratings** (7 filters): Highly-Rated, Well-Rated, Below-Average, Unrated, Hidden Gems, Critic Favorites, Community Favorites
   - **Dates** (5 filters): Recently Added, Older Library, Recent Releases, Recently Updated, Classics
   - **Content** (2 filters): NSFW, Safe
-- **Global filter persistence**: Filters always apply across all pages (Library, Discover, Collections, Random) and persist via localStorage
+- **Global filter persistence**: 6 global filters (stores, genres, queries, excludeStreaming, noIgdb, protondbTier) persist across all pages via localStorage
 - **Random page**: New `/random` endpoint with full page displaying configurable number of random games (default 12, max 50) with filter support
 - **Reusable filter components**: Component-based architecture with `_filter_bar.html`, `filters.css`, and `filters.js` for consistent UX
+- **2-tier caching system** for IGDB data:
+  - **Tier 1 (Memory)**: 15-minute cache for instant page loads (~0ms)
+  - **Tier 2 (Database)**: 24-hour persistent cache surviving restarts
+  - Hash-based invalidation on library changes
+  - Filter-specific caching (each filter combo gets own cache)
+- **Advanced filter suite** (4 new filters):
+  - **Collection filter**: Show games from specific user collections
+  - **ProtonDB tier filter**: Hierarchical Steam Deck compatibility (Platinum > Gold > Silver > Bronze)
+  - **Exclude streaming**: Hide cloud gaming services (Xbox Cloud, GeForce NOW)
+  - **No IGDB data**: Show games missing IGDB metadata for curation
+- **Xbox Game Pass integration**: Authentication via XSTS token, market/region selection, subscription plan configuration
+- **CSS architecture refactoring**: Externalized 2000+ lines of inline CSS to shared files (`filters.css`, `shared-game-cards.css`, `discover-hero.css`)
+- **Optional authentication system**: Password protection with bcrypt hashing and signed session tokens (opt-in via `ENABLE_AUTH`)
+- **Docker environment detection**: Auto-detects Docker and disables LOCAL_GAMES_PATHS editing (use volume mounts instead)
+- **Progressive Web App meta**: Theme color support for better mobile/PWA experience
+
+**Combined features:**
+- **Complete filter system**: 18 predefined queries + 4 advanced filters working in harmony
 - **Performance optimizations**:
   - Database indexes on frequently filtered columns (playtime_hours, total_rating, added_at, release_date, nsfw, last_modified)
-  - Discover page: reduced from 5+ queries to 1 UNION ALL query
-  - IGDB popularity data: 24-hour caching system to reduce API calls
-- **Comprehensive test suite**: 69 tests covering:
-  - Filter definitions and SQL generation (26 unit tests)
-  - Filter combinations and edge cases (26 integration tests)
-  - Empty library handling (7 tests)
-  - Performance with 10,000 games (6 tests)
-  - Recently Updated filter edge cases (4 tests)
-- **Documentation**: Complete technical documentation in `.copilot-docs/` covering filter system architecture, SQL reference, and database schema
+  - Discover page: 1 UNION ALL query for DB categories + parallel IGDB API fetching
+  - 2-tier caching: 99.95% faster on cached loads
+- **Comprehensive test suite**: 120+ tests covering filters, caching, edge cases, performance, labels system
+- **Complete documentation**: Filter system architecture, SQL reference, merge documentation, API reference
 
 ### Changed
-- Settings UI now conditionally renders based on deployment mode:
-  - **Non-Docker**: Editable input field for `LOCAL_GAMES_PATHS` with database storage
-  - **Docker**: Read-only display with instructions for configuring via `.env` and `docker-compose.yml`
-- Docker deployments prevent `LOCAL_GAMES_PATHS` from being saved through the UI (paths must be volume-mounted)
-- Settings template updated with deployment-specific instructions and help text
-- **Filter behavior**: Removed "Apply filters globally" checkbox—filters are now always global for simpler UX
-- **Filter application**: Auto-apply with 300ms debounce using event delegation for better reliability
-- **Random page**: Converted from redirect to full HTML page with game grid and filter integration
-- **Filter bar**: Custom dropdowns with dark theme styling and count badges
-- **Custom dropdowns**: Replaced native select elements with styled dropdowns for consistent dark theme
+- **Filter behavior**: Filters are always global for simpler UX (no toggle needed)
+- **Filter application**: Auto-apply with 300ms debounce using event delegation
+- **Global filter count**: Expanded from 3 to 6 global filters (stores, genres, queries, excludeStreaming, noIgdb, protondbTier)
+- **Discover page architecture**: Immediate render + AJAX for IGDB sections (non-blocking)
+- **Filter bar**: Extended with 4 advanced filter UI components
+- **JavaScript buildUrl()**: Signature extended from 6 to 10 parameters for advanced filters
+- **Custom dropdowns**: Replaced native select elements with styled dropdowns for dark theme
+- **Settings UI**: Conditional rendering based on Docker/bare-metal deployment
+- **CSS organization**: Inline styles moved to external cacheable files
 
 ### Fixed
-- Filter state persistence across page navigations
-- Event listeners for dynamically loaded filter checkboxes using event delegation
-- Recently Updated filter now works for all stores (uses `last_modified` field instead of Epic-specific `game_update_at`)
+- **Global filter persistence**: Advanced filters (excludeStreaming, noIgdb) now persist across pages
+- **Filter synchronization**: Defensive dual-save strategy (buildUrl + saveCurrentFilters) ensures robust persistence
+- **Navigation link interception**: Global filters automatically added to Library/Discover/Collections/Random links
+- **Docker localStorage conflicts**: Browser cache requires Ctrl+F5 hard refresh after code changes
+- **Column validation**: PRAGMA-based sort column detection prevents SQL errors on schema changes
+- **Filter state persistence**: Event delegation for dynamically loaded filter checkboxes
+- **Recently Updated filter**: Works for all stores (uses `last_modified` field)
 
 ### Technical Details
-- Modified `web/routes/settings.py` to detect Docker environment using `/.dockerenv` file
-- Added conditional rendering in `web/templates/settings.html` based on `is_docker` flag
-- POST handler skips `LOCAL_GAMES_PATHS` database save in Docker mode
-- Added `.copilot-docs/` to `.gitignore` for development documentation
+
+**From feat-multiple-edit-tags-and-actions branch:**
+- **New files**:
+  - `tests/test_api_metadata_endpoints.py`: API integration tests for metadata endpoints (32 tests)
+  - `tests/test_database_migrations.py`: Database migration tests (12 tests)
+  - `tests/test_edge_cases_labels.py`: Edge case tests for labels system (13 tests)
+  - `docs/api-metadata-endpoints.md`: Complete API reference with examples and error codes
+  - `docs/contributing-labels-system.md`: Developer guide for labels system contributions
+  - `web/routes/api_metadata.py`: REST API for game metadata (priority, rating, manual tags, bulk operations)
+- **Modified files**:
+  - `tests/test_system_labels_auto_tagging.py`: Added 5 manual tag persistence tests
+  - `docs/system-labels-auto-tagging.md`: Added Quick Start guide, FAQ (12 questions), keyboard shortcuts
+  - `web/database.py`: Added labels tables migration, metadata columns
+- **Database schema**:
+  - Migrated `collections` → `labels` system with CASCADE delete
+  - Added `game_labels` junction table (game_id, label_id, added_at)
+  - Added `priority` and `personal_rating` columns to `games` table
+
+**From feat-global-filters branch (Merge MAIN → feat-global-filters):**
 - **New files**:
   - `web/utils/filters.py`: Filter definitions (PREDEFINED_QUERIES, QUERY_DISPLAY_NAMES, QUERY_CATEGORIES, QUERY_DESCRIPTIONS)
-  - `web/templates/_filter_bar.html`: Reusable filter bar component
+  - `web/templates/_filter_bar.html`: Reusable filter bar component with 4 advanced filters
   - `web/templates/random.html`: Random games page with grid layout
-  - `web/static/css/filters.css`: Filter-specific styles
-  - `web/static/js/filters.js`: Filter management with global state
+  - `web/static/css/filters.css`: Filter bar styles (~500 lines)
+  - `web/static/css/shared-game-cards.css`: Game card components (~800 lines)
+  - `web/static/css/discover-hero.css`: Discover page hero section (~600 lines)
+  - `web/static/js/filters.js`: Global filter management with 6 global filters
   - `tests/test_predefined_filters.py`: Unit tests (26)
   - `tests/test_predefined_filters_integration.py`: Integration tests (26)
   - `tests/test_empty_library.py`: Empty library tests (7)
   - `tests/test_large_library_performance.py`: Performance tests (6)
   - `tests/test_recently_updated_edge_case.py`: Edge case tests (4)
+  - `tests/test_advanced_filters.py`: Advanced filter tests (15)
+  - `tests/test_caching_system.py`: 2-tier cache tests (19)
+  - `requirements-dev.txt`: Development dependencies (pytest, pytest-cov, ruff)
   - `.copilot-docs/filter-system.md`: Filter system architecture
   - `.copilot-docs/filter-sql-reference.md`: SQL conditions reference
   - `.copilot-docs/database-schema.md`: Database schema documentation
-- **Modified routes**: `library.py`, `discover.py`, `collections.py`, `settings.py` to support `queries` parameter
-- **Database**: Added `popularity_cache` table and `ensure_predefined_query_indexes()` in `database.py`
+  - `merge_MAIN_to_FEAT_GLOBAL_FILTERS.md`: Comprehensive merge documentation (temporary file, will be removed post-PR)
+- **Modified files**:
+  - `web/routes/library.py`: Added 4 advanced filters + PRAGMA column validation + personal_rating/priority sorting
+  - `web/routes/discover.py`: 2-tier caching + modular architecture + filter integration
+  - `web/routes/collections.py`: Advanced filter support in collection detail page
+  - `web/routes/settings.py`: Xbox credentials + Docker detection
+  - `web/main.py`: Auth router import + DB table creation calls (labels, auth, cache)
+  - `web/database.py`: Added `popularity_cache` table + `ensure_predefined_query_indexes()`
+  - `web/templates/discover.html`: Removed 1800 lines inline CSS, external CSS links
+  - `web/templates/index.html`: Removed 300 lines inline CSS, external CSS links
+  - `web/templates/collection_detail.html`: CSS links + PWA theme-color meta tag
+  - `requirements.txt`: Removed pytest (moved to requirements-dev.txt), added bcrypt, itsdangerous
+- **Database schema**:
+  - New table: `popularity_cache` (for Tier 2 caching)
+  - New indexes: On playtime_hours, total_rating, added_at, release_date, nsfw, last_modified
+  - New tables: `collections`, `collection_games` (for collection filtering)
+  - Migration: Collections → labels system with metadata columns
+- **API changes**:
+  - `buildUrl()` JavaScript function: 6 → 10 parameters
+  - New endpoint: `/api/discover/igdb-sections` (AJAX IGDB section loading)
+  - New endpoints: 13 metadata API endpoints (priority, rating, manual tags, bulk operations)
+  - Extended parameters: All route handlers accept 6 global filter parameters

README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="web/static/favicons/Backlogia_logo.png" alt="Backlogia" width="128" height="128">
+</p>
+
 # Backlogia
 
 **Your entire game library, finally in one place.**
@@ -254,15 +258,54 @@ On **Linux** hosts, mDNS is advertised automatically via Avahi.
 
 **Trusting the Certificate:**
 
-Caddy generates a self-signed certificate. Your browser will show a warning on first visit. You can click past it. To trust it permanently on macOS:
+Caddy generates a self-signed certificate using its own internal CA. Browsers will show a security warning until you trust this CA. Trusting it is **required** for PWA install support (service workers need a valid certificate).
+
+Run the included script to trust the certificate automatically:
 ```bash
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./data/caddy_data/pki/authorities/local/root.crt
+./scripts/trust-caddy-cert.sh
 ```
 
+This adds Caddy's root CA to your system trust store. Restart your browser afterward. The script supports macOS, Linux, and Windows (via Git Bash).
+
+You can also trust it manually:
+- **macOS**: `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./data/caddy_data/caddy/pki/authorities/local/root.crt`
+- **Linux**: Copy `./data/caddy_data/caddy/pki/authorities/local/root.crt` to `/usr/local/share/ca-certificates/` and run `sudo update-ca-certificates`
+- **Windows (PowerShell, run as Administrator)**: `certutil -addstore -f Root .\data\caddy_data\caddy\pki\authorities\local\root.crt`
+
+---
+
+### Authentication (Optional)
+
+Backlogia runs without authentication by default. If you're exposing your instance beyond localhost, you can enable single-user authentication to protect all routes.
+
+**Enable authentication:**
+
+Add to your `.env` file:
+```bash
+ENABLE_AUTH=true
+```
+
+Then restart the container (or application). On first visit you'll be prompted to create an owner account — this is the only account allowed on the instance.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ENABLE_AUTH` | `false` | Set to `true` to require login |
+| `SESSION_EXPIRY_DAYS` | `30` | How long sessions last before requiring re-login |
+
+A session secret key is generated automatically and persisted in the database. You can logout from the Settings page.
+
 ---
 
 ### Option 3: Local Installation
 
+#### Prerequisites (Amazon)
+1. Build the latest `nile` code: https://github.com/imLinguin/nile?tab=readme-ov-file#setting-up-dev-environment
+2. Compile `nile` into an executable: https://github.com/imLinguin/nile?tab=readme-ov-file#building-pyinstaller-executable
+3. Make sure that the compiler executable is in your `PATH` (either place it in an existing `PATH` folder or add the folder containing the executable to the `PATH` list)
+4. If you added a new folder to your `PATH` above, open a **new terminal** for the instructions below (so it receives the updated `PATH`)
+
+#### Installation
+
 1. **Clone the repository**
    ```bash
    git clone https://github.com/sam1am/backlogia.git
@@ -287,17 +330,12 @@ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keyc
 
 5. **Edit `.env` with your settings** (see [Configuration](#configuration))
 
-6. **Initialize the database**
-   ```bash
-   python scripts/build_database.py
-   ```
-
-7. **Run the application**
+6. **Run the application**
    ```bash
    python web/app.py
    ```
 
-8. **Access Backlogia** at [http://localhost:5050](http://localhost:5050)
+7. **Access Backlogia** at [http://localhost:5050](http://localhost:5050)
 
 #### Updating (Local Installation)
 

docker-compose.yml

@@ -42,7 +42,11 @@ services:
       - LOCAL_GAMES_DIR_3=${LOCAL_GAMES_DIR_3:-}
       - LOCAL_GAMES_DIR_4=${LOCAL_GAMES_DIR_4:-}
       - LOCAL_GAMES_DIR_5=${LOCAL_GAMES_DIR_5:-}
-      # Amazon Games - uses Nile (pip install nile && nile auth --login)
+      # Authentication (optional)
+      - ENABLE_AUTH=${ENABLE_AUTH:-false}
+      - SECRET_KEY=${SECRET_KEY:-}
+      - SESSION_EXPIRY_DAYS=${SESSION_EXPIRY_DAYS:-30}
+      # Amazon Games - uses Nile
     restart: unless-stopped
 
   caddy: