initial commit

docs/implementation-plan.md

@@ -0,0 +1,127 @@
+# Implementation Plan
+
+## Milestone 0: Repository Foundation
+
+Goal: make the project ready for implementation.
+
+Deliverables:
+
+- Planning docs aligned with confirmed product decisions.
+- `AGENTS.md` for coding-agent and contributor workflow.
+- `SECURITY.md` for vulnerability handling and secret-management expectations.
+- `CONTRIBUTING.md` for local development and contribution standards.
+- `CODE_OF_CONDUCT.md` for open-source readiness.
+- `.gitignore` suited for Tauri, SvelteKit, Rust, Node, and build artifacts.
+
+Exit criteria:
+
+- The repository explains what is in scope for the MVP.
+- A new contributor can understand the intended stack and project rules.
+
+## Milestone 1: Application Skeleton
+
+Goal: create the first runnable desktop application.
+
+Deliverables:
+
+- Tauri app scaffold using `Steam Backlog Helper` as the display name and `com.boris.backloghelper` as the package ID.
+- Svelte/SvelteKit frontend with TypeScript.
+- Basic app shell with setup, picker, and settings routes or views.
+- Lint, format, typecheck, and test commands.
+- Initial SQLite migration system.
+
+Exit criteria:
+
+- The app runs locally in development mode.
+- The app can open a desktop window.
+- CI can run linting and typechecks.
+
+## Milestone 2: Steam Setup And Library Import
+
+Goal: import a user's Steam library through supported API access.
+
+Deliverables:
+
+- Steam profile input supporting Steam ID, vanity URL, or profile URL.
+- User-provided Steam Web API key setup.
+- Owned-games fetch.
+- Library cache in SQLite.
+- Clear failure states for invalid keys, private profiles, rate limits, and network failures.
+
+Exit criteria:
+
+- A public/API-accessible Steam library can be imported and refreshed.
+- Imported games persist after app restart.
+- No real API keys are logged or committed.
+
+## Milestone 3: Metadata Enrichment
+
+Goal: make recommendations useful beyond raw ownership and playtime.
+
+Deliverables:
+
+- Steam Store metadata lookup for images, genres, categories, and release data.
+- Public review-score signal where available.
+- HowLongToBeat-compatible completion-time integration after validation.
+- Metadata cache with freshness timestamps.
+- Default filtering for demos, tools, soundtracks, and DLC.
+
+Exit criteria:
+
+- Recommendation candidates include playtime, image, genre/category, review, and completion-time data where available.
+- Metadata lookup failures degrade gracefully.
+
+## Milestone 4: Recommendation Engine
+
+Goal: produce explainable, useful recommendations.
+
+Deliverables:
+
+- Short-question recommendation flow.
+- Weighted scoring using available time, optional genre, completion preference, review score, and playtime.
+- True-random toggle that bypasses weighted scoring.
+- Dynamic shortlist output.
+- Human-readable recommendation explanations.
+- Unit tests for scoring behavior.
+
+Exit criteria:
+
+- Recommendation behavior is deterministic under seeded test data.
+- True-random mode is separate from weighted recommendations.
+- Edge cases such as empty candidate sets have clear UI states.
+
+## Milestone 5: Picker Experience
+
+Goal: make the primary workflow feel focused and polished.
+
+Deliverables:
+
+- Recommendation-first home screen.
+- Slot-machine style reveal for the primary recommendation.
+- Keyboard-accessible controls.
+- Steam app ID launch links.
+- Responsive desktop layout for common window sizes.
+
+Exit criteria:
+
+- A keyboard-only user can complete setup and run a recommendation.
+- The chosen game can be opened in Steam.
+- The picker remains usable without a full library-management screen.
+
+## Milestone 6: Packaging And Releases
+
+Goal: produce installable desktop artifacts.
+
+Deliverables:
+
+- Windows 10+ build.
+- macOS 26+ build, with self-signing where practical.
+- Linux AppImage build.
+- Gitea runner workflows for x86 builds.
+- Local arm64 build instructions.
+- Release artifact checklist.
+
+Exit criteria:
+
+- Release artifacts can be generated from the repository.
+- The release process is documented for personal Gitea.