New user-editable tags

.gitignore

@@ -3,6 +3,10 @@ game_library.db
 # Copilot documentation
 .copilot-docs/
 
+# OpenSpec workflow and GitHub configs
+.github/
+openspec/
+
 # Docker
 data/
 .empty/
@@ -222,4 +226,7 @@ marimo/_lsp/
 __marimo__/
 
 # Streamlit
-.streamlit/secrets.toml
+.streamlit/secrets.toml
+
+# Claude code
+.claude/

CHANGELOG.md

@@ -8,14 +8,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **Editable local games paths in Settings UI**: Users can now configure local game folder paths directly from the Settings page without needing to edit environment variables or .env files
+- **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)
+- **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
+- **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
+- **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
 
 ### Changed
-- `LOCAL_GAMES_PATHS` setting is now editable through the web interface and stored in the database
-- Settings template updated to show an input field for local games paths instead of read-only display
-- Docker users can still use `LOCAL_GAMES_DIR_1`, `LOCAL_GAMES_DIR_2`, etc. environment variables (these take precedence)
+- **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
+
+### 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`)
 
 ### Technical Details
-- Modified `web/routes/settings.py` to handle saving and loading `LOCAL_GAMES_PATHS` from database
-- Updated `web/templates/settings.html` to provide an editable text input for local games paths
-- Added `.copilot-docs/` to `.gitignore` for development documentation
+- **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/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/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
+  - `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)
+  - `.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 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
+- **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`

README.md

@@ -42,6 +42,38 @@ All your games from every store, displayed in one place. Smart deduplication ens
 - **Flexible sorting** — Sort by name, rating, playtime, or release date
 - **Store indicators** — See at a glance which platforms you own each game on
 
+### Smart Filters
+
+Quickly find games that match your mood with predefined filters organized into categories:
+
+- **Gameplay Filters** — Unplayed, Just Tried, Played, Well-Played, Heavily-Played
+- **Rating Filters** — Highly-Rated (90+), Well-Rated (75+), Below-Average (<75), Unrated, Hidden Gems, Critic Favorites, Community Favorites
+- **Date Filters** — Recently Added (30 days), Older Library (180+ days), Recent Releases (90 days), Recently Updated, Classics (pre-2000)
+- **Content Filters** — NSFW, Safe
+
+**Features:**
+- **Result count badges** — See how many games match each filter before applying it
+- **Global Filters Mode** — Enable "Apply filters globally" to keep your selected filters active across all pages (Library, Discover, Collections, Random)
+- **Keyboard navigation** — Use arrow keys to navigate filters, Esc to close dropdowns, Enter/Space to toggle filters
+- **Accessibility** — Full ARIA label support and screen reader compatibility
+
+### Automatic Gameplay Tagging (Steam)
+
+Steam games are automatically tagged with gameplay labels based on your playtime. Every time you sync your Steam library, Backlogia evaluates each game's playtime and assigns the appropriate label:
+
+| Label | Playtime |
+|-------|----------|
+| **Never Launched** | 0 hours |
+| **Just Tried** | < 2 hours |
+| **Played** | 2 - 10 hours |
+| **Well Played** | 10 - 50 hours |
+| **Heavily Played** | 50+ hours |
+
+- Labels update automatically on each Steam sync — no manual action required
+- Labels are visible on game detail pages and power the Gameplay filters above
+- Steam-only: other stores don't provide reliable playtime data, but you can assign labels manually
+- See [System Labels documentation](docs/system-labels-auto-tagging.md) for technical details
+
 ### Rich Game Details
 
 Every game is enriched with metadata from IGDB (Internet Game Database), giving you consistent information across all stores.
@@ -65,7 +97,7 @@ Find your next game to play with curated discovery sections based on your actual
 - **Highly rated** — Games scoring 90+ ratings
 - **Hidden gems** — Quality games that deserve more attention
 - **Most played** — Your games ranked by playtime
-- **Random pick** — Can't decide? Let Backlogia choose for you
+- **Random pick** — Can't decide? Let Backlogia surprise you with one game. Works with global filters to respect your preferences
 
 ### Custom Collections