Update README.md

README.md

@@ -1,26 +1,144 @@
 # Steam Backlog Helper
 
-Steam Backlog Helper is a planned cross-platform desktop application that helps Steam users pick a game from a large backlog.
+Steam Backlog Helper is a desktop app for choosing what to play next from a large Steam library.
 
-The first version is picker-first: it asks a short set of questions, scores the user's Steam library, and presents a dynamic shortlist with a slot-machine style reveal. It is designed for personal use first, with an open-source release path.
+It is built around a simple workflow: connect a Steam profile, import the owned games list, set a few preferences, then spin the wheel for a recommendation. The app is intended for people with enough Steam games that picking one has become its own chore.
 
-## Naming
+## What It Does
 
-- Official app name: Steam Backlog Helper
-- Repository name: steam-backlog-helper
-- Package ID: `com.boris.backloghelper`
-- Internal slug: `backlog-helper`
+- Imports your Steam library using your Steam profile and Steam Web API key.
+- Shows a large recommendation wheel using Steam game artwork.
+- Picks from your imported library with either weighted recommendations or true random mode.
+- Lets you adjust hard eligibility filters, such as whether to include unplayed or already-played games.
+- Lets you set preference weights for reviews, single-player/multiplayer, genre or Steam tags, and playtime.
+- Builds a shortlist of top candidate games.
+- Opens a separate debug window so you can inspect why a game was picked.
 
-## Product Direction
+## Current State
 
-- Target users: Steam users with large libraries and many unplayed or lightly played games.
-- Desktop framework: Tauri.
-- Frontend: Svelte/SvelteKit with TypeScript.
-- Storage: local SQLite.
-- Platforms: Windows 10+, macOS 26+, and Linux AppImage.
-- Distribution: personal Gitea releases, with possible GitHub publication later.
+This is an early local-first version. The app can run as a Tauri desktop application and can build a macOS DMG locally.
 
-## Planning Documents
+Working now:
+
+- First-run setup wizard.
+- Local settings storage.
+- Steam owned-games import.
+- Recommendation wheel.
+- Shortlist view.
+- Settings modal.
+- Separate debug diagnostics window.
+- Background metadata enrichment for reviews, tags, genres, categories, and play mode where available.
+
+Still evolving:
+
+- Metadata caching in SQLite.
+- Faster and more reliable Steam Store enrichment for very large libraries.
+- Better exclusion of non-game Steam apps once metadata caching is in place.
+- Launching selected games directly through Steam.
+- Completion-time integration.
+- Release automation for all platforms.
+
+## Requirements
+
+You need:
+
+- A Steam account with public or API-accessible game details.
+- A Steam Web API key.
+- Node.js and npm for local development.
+- Rust/Cargo for the Tauri desktop app.
+
+The app does not ask for your Steam password.
+
+## Running Locally
+
+Install dependencies first:
+
+```bash
+npm install
+```
+
+Run validation:
+
+```bash
+npm run local:check
+```
+
+Start the desktop app:
+
+```bash
+npm run local:dev
+```
+
+Build a local desktop release:
+
+```bash
+npm run local:build
+```
+
+On macOS, the DMG is written under:
+
+```text
+src-tauri/target/release/bundle/dmg/
+```
+
+## Setup Flow
+
+On first run, the app asks for:
+
+- Steam profile, vanity URL, profile URL, or Steam ID.
+- Steam Web API key.
+- Optional time-to-beat provider placeholder.
+- Default session length.
+- Random mode preference.
+
+Settings can be changed later from the cog button in the top bar.
+
+## Recommendations
+
+The picker separates two kinds of filters:
+
+- Eligibility filters remove games from the candidate pool.
+- Preferred filters change weighting without removing games.
+
+Preferred filters currently include:
+
+- Review signal.
+- Single-player or multiplayer/co-op preference.
+- Genre and Steam tag preference.
+- Playtime preference.
+
+True random mode bypasses weighting and chooses from the eligible pool.
+
+## Debug Window
+
+The Settings screen includes an Open Debug Window button. This opens a second desktop window that shows:
+
+- Current pick.
+- Active restrictions.
+- Score contributions.
+- Review data.
+- Genres.
+- Steam tags.
+- Categories.
+- Play mode metadata.
+- Candidate scores.
+
+This is useful while tuning the recommendation logic.
+
+## Data And Privacy
+
+Steam Backlog Helper is local-first.
+
+- Settings are stored locally.
+- The Steam API key is currently stored locally in SQLite during early development.
+- The app contacts Steam APIs and public Steam Store pages to import and enrich library data.
+- Library data is not sent to an app-owned server.
+
+Before a public release, API key storage should move to OS-protected credential storage.
+
+## Documentation
+
+Project planning lives in:
 
 - [Product Brief](docs/product-brief.md)
 - [Implementation Plan](docs/implementation-plan.md)
@@ -28,8 +146,4 @@ The first version is picker-first: it asks a short set of questions, scores the
 - [Technical Plan](docs/technical-plan.md)
 - [Data and Integrations](docs/data-and-integrations.md)
 - [Architecture Decisions](docs/architecture-decisions.md)
-- [Open Questions](docs/open-questions.md)
-
-## Current Status
-
-This repository contains the initial Tauri + SvelteKit application shell. The frontend can be typechecked and built; Tauri desktop compilation requires a local Rust toolchain.
+- [Answered Product Questions](docs/open-questions.md)