# Steam Backlog Helper

Steam Backlog Helper is a desktop app for choosing what to play next from a large Steam library.

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.

## What It Does

- 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.

## Current State

This is an early local-first version. The app can run as a Tauri desktop application and can build a macOS DMG locally.

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)
- [Feature Roadmap](docs/feature-roadmap.md)
- [Technical Plan](docs/technical-plan.md)
- [Data and Integrations](docs/data-and-integrations.md)
- [Architecture Decisions](docs/architecture-decisions.md)
- [Answered Product Questions](docs/open-questions.md)