docs: sync the community docs with the repository

A read-through against the code found about forty claims that had drifted.

README:
- Dynamic game-count and version badges. The count is index.json's total.
  The version is the newest v* release by semver, since an app release
  published last would otherwise count as "latest".
- SvelteKit 3, every desktop package, and the shard layout without a last
  shard number.
- The media host, which commits deploy, and the nine workflows the table
  left out.
- The accessibility statement and form in the link lists.

SECURITY.md:
- Fix the broken bullet list.
- Describe the real stack, and pushes with the built-in GITHUB_TOKEN.
- Add to scope: the media host, /api/ingest/*, /api/updates/desktop and the
  avatar origin.

AUTHORS.md and username.txt:
- Donations are in FUNDING.yml.
- The Add-games template is gone.
- Test devices come from pc_spec.

The issue forms lose the hash URLs, the GitHub Pages permalink, and the
editing and GPG options.

web/README.md, dev_env (EN + VI), the acknowledgements and the contact page
are updated to match. The last two are not consent documents, so nobody is
asked to accept the terms again.

CHANGELOG [Unreleased] lists all three commits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-11-09 08:43:39 +07:00
1 parent 1845834b98
commit 2b4b988cc7
15 files changed
+147 -67

No files matched your search

+17 -14
View File
@@ -7,8 +7,10 @@ body:
attributes: attributes:
value: | value: |
Thanks for reporting! This broke unemployed dev will check when caffeine kicks in :)) Thanks for reporting! This broke unemployed dev will check when caffeine kicks in :))
For things that aren't bugs (just a missing game / wrong genre), the **Add games** or For things that aren't bugs: a missing game or a wrong genre goes in
**Delete game** templates are usually faster. [Discussions › Ideas](https://github.com/poli0981/free-steam-games-list/discussions/categories/ideas),
a game that should go uses **Delete game**, and something you can't use with a keyboard,
a screen reader or zoom has its own **Accessibility barrier** form.
- type: dropdown - type: dropdown
id: surface id: surface
@@ -17,7 +19,10 @@ body:
description: Helps me figure out which layer to look at first. description: Helps me figure out which layer to look at first.
options: options:
- "Web app — https://free-steam-games.win/" - "Web app — https://free-steam-games.win/"
- "Desktop app (Windows / macOS / Linux)"
- "Android app"
- "Top online — games/top-online.md" - "Top online — games/top-online.md"
- "Top offline — games/top-offline.md"
- "Raw data — data/data_*.jsonl" - "Raw data — data/data_*.jsonl"
- "API / direct fetch" - "API / direct fetch"
- "Other (describe below)" - "Other (describe below)"
@@ -36,8 +41,6 @@ body:
- label: Reviews / players not updating - label: Reviews / players not updating
- label: Wrong game count / total - label: Wrong game count / total
- label: Table / chart layout broken - label: Table / chart layout broken
- label: Edit / Add / Delete failed (web app)
- label: GPG signature unverified (web app)
- label: Service worker / offline cache issue - label: Service worker / offline cache issue
- label: Dropdown / form validation issue - label: Dropdown / form validation issue
- label: Mobile-specific - label: Mobile-specific
@@ -49,8 +52,8 @@ body:
label: Describe the bug label: Describe the bug
description: | description: |
What happened? Which game(s) or page(s)? How many records affected? What happened? Which game(s) or page(s)? How many records affected?
If it's a web-app bug, include the URL after the hash (e.g. If it's a web-app bug, include the page address (e.g.
`#/games/730` or `#/charts/anti-cheat`). `https://free-steam-games.win/games/730` or `/charts/anti-cheat`).
validations: validations:
required: true required: true
@@ -60,10 +63,10 @@ body:
label: Steps to reproduce label: Steps to reproduce
description: How can I see the bug? Numbered list works great. description: How can I see the bug? Numbered list works great.
placeholder: | placeholder: |
1. Open #/games 1. Open /games
2. Filter genre = FPS 2. Filter genre = FPS
3. Click row "Counter-Strike 2" 3. Click the row "Counter-Strike 2"
4. Edit drawer fails to open 4. The game page shows no player count
- type: textarea - type: textarea
id: screenshots id: screenshots
@@ -71,8 +74,8 @@ body:
label: Screenshots / links label: Screenshots / links
description: | description: |
Paste image URLs (drag-drop into this field works) or links to the Paste image URLs (drag-drop into this field works) or links to the
affected commit / row / chart. The web app supports per-game affected commit / row / chart. The web app has a page per game —
permalinks — `https://poli0981.github.io/free-steam-games-list/#/games/{appid}`. `https://free-steam-games.win/games/{appid}`.
- type: input - type: input
id: env-browser id: env-browser
@@ -84,9 +87,9 @@ body:
- type: input - type: input
id: env-version id: env-version
attributes: attributes:
label: Web app version (for web app bugs) label: App version (web, desktop or Android)
description: Hover the F2P Tracker title in the sidebar — it shows the version. description: Shown as "Steam · v…" under the F2P Tracker title in the sidebar (in the menu on small screens).
placeholder: v0.1 placeholder: v2.5.0
- type: textarea - type: textarea
id: console id: console
+2 -2
View File
@@ -6,7 +6,7 @@ body:
- type: markdown - type: markdown
attributes: attributes:
value: | value: |
Thanks for the idea! This noob dev appreciates it (Grok buddy will help code :))) Thanks for the idea! This noob dev appreciates it (Claude buddy will help code :)))
- type: checkboxes - type: checkboxes
id: type id: type
@@ -56,7 +56,7 @@ body:
id: code id: code
attributes: attributes:
label: Code snippet/mockup (optional – no malware pls, I'll check though lazy :D) label: Code snippet/mockup (optional – no malware pls, I'll check though lazy :D)
render: python render: text
- type: checkboxes - type: checkboxes
id: terms id: terms
+1 -1
View File
@@ -1,5 +1,5 @@
name: ❓ Off-Topic / Other name: ❓ Off-Topic / Other
description: Anything not bug/feature/add-game description: Anything that isn't a bug, feature, removal, feedback or accessibility report
title: "[Other] " title: "[Other] "
labels: ["off-topic"] labels: ["off-topic"]
body: body:
+8 -5
View File
@@ -17,8 +17,11 @@ This file lives at the repo root so the author can be found without digging into
| Everything else | <https://poli0981.dev/links/> | | Everything else | <https://poli0981.dev/links/> |
`poli0981.dev/links/` is the single source of truth for every other channel `poli0981.dev/links/` is the single source of truth for every other channel
— chat, socials, video, donations. It is maintained there rather than in — chat, socials, video. It is maintained there rather than in
this repository so a moved or retired account cannot leave a dead link here. this repository so a moved or retired account cannot leave a dead link here.
Donation links are the exception: they live in
[`.github/FUNDING.yml`](.github/FUNDING.yml) and on the web app's
[Donate page](https://free-steam-games.win/donate).
Anything that should not be public belongs in email — `contact@` unless one of Anything that should not be public belongs in email — `contact@` unless one of
the role addresses fits better. Security reports go to GitHub's private the role addresses fits better. Security reports go to GitHub's private
@@ -32,23 +35,23 @@ For people forking the repo or trying to reproduce a build:
| --------------- | ------------------------------------------------------------ | | --------------- | ------------------------------------------------------------ |
| GitHub | [@poli0981](https://github.com/poli0981) | | GitHub | [@poli0981](https://github.com/poli0981) |
| IDE | JetBrains 2026.x — paid lineup (PyCharm, WebStorm, RustRover) | | IDE | JetBrains 2026.x — paid lineup (PyCharm, WebStorm, RustRover) |
| Toolchains | Python 3.15 · Node.js 26 · TypeScript 7 · Rust stable · Tauri 2 | | Toolchains | Python 3.15 · Node.js 26 · TypeScript 7 + 6 · Rust stable · Tauri 2 |
| Git | GPG signing on (`commit.gpgsign=true`) | | Git | GPG signing on (`commit.gpgsign=true`) |
| Hardware spec | [`docs/pc_spec.md`](docs/pc_spec.md) (EN) · [`docs/i18n/vi/pc_spec.md`](docs/i18n/vi/pc_spec.md) (VI) | | Hardware spec | [`docs/pc_spec.md`](docs/pc_spec.md) (EN) · [`docs/i18n/vi/pc_spec.md`](docs/i18n/vi/pc_spec.md) (VI) |
| Dev environment | [`docs/dev_env.md`](docs/dev_env.md) (EN) · [`docs/i18n/vi/dev_env.md`](docs/i18n/vi/dev_env.md) (VI) | | Dev environment | [`docs/dev_env.md`](docs/dev_env.md) (EN) · [`docs/i18n/vi/dev_env.md`](docs/i18n/vi/dev_env.md) (VI) |
| Desktop build | [`web/src-tauri/TAURI.md`](web/src-tauri/TAURI.md) | | Desktop build | [`web/src-tauri/TAURI.md`](web/src-tauri/TAURI.md) |
| Test devices | iPhone 14 Pro · iPhone 13 Pro Max · iOS 26.x (Chrome / Brave / Safari) | | Test devices | Windows 11 (Chrome / Edge / Firefox / Brave) · iPhone 14 Pro and 13 Pro Max, iOS 26.x (Safari / Chrome / Brave) · Android 11–16 emulator + vivo 1907 (Android 12) — full list in [`docs/pc_spec.md`](docs/pc_spec.md) |
## Contributors ## Contributors
Anyone who's filed an issue, opened a PR, or used the Add-Games template is implicitly thanked. The full list is whatever GitHub renders on the [contributors page](https://github.com/poli0981/free-steam-games-list/graphs/contributors). Anyone who's filed an issue, opened a PR, or suggested a game in Discussions is implicitly thanked. The full list is whatever GitHub renders on the [contributors page](https://github.com/poli0981/free-steam-games-list/graphs/contributors).
## AI assistants (full disclosure) ## AI assistants (full disclosure)
About **~70 %** of the code in this repository was generated with help from large-language-model assistants: About **~70 %** of the code in this repository was generated with help from large-language-model assistants:
- **Grok (xAI)** — initial v1 Python pipeline (~2025). - **Grok (xAI)** — initial v1 Python pipeline (~2025).
- **Claude (Anthropic)** — v2 refactor, full data layer, the React/Vite web app, the Tauri 2 desktop wrapper, the GPG-signing path, the legal docs, and most recent commits. - **Claude (Anthropic)** — v2 refactor, full data layer, the web app (React/Vite first, SvelteKit since v4), the Cloudflare Worker and `/admin`, the Tauri 2 desktop and Android apps, the legal docs, and most recent commits.
Generated code is reviewed and tested before each commit. No user data is sent to any LLM at runtime — LLM calls happen on the maintainer's dev machine, never from your browser. Generated code is reviewed and tested before each commit. No user data is sent to any LLM at runtime — LLM calls happen on the maintainer's dev machine, never from your browser.
+41
View File
@@ -4,6 +4,47 @@ All notable changes to this awesome noob repo will be documented here.
## [Unreleased] ## [Unreleased]
### ✨ Added
- **An accessibility statement.** `ACCESSIBILITY.md` says what works today
with a keyboard, a screen reader and zoom, and what does not work yet: the
games table, most charts, the first-run screens, zoom in the apps. It also
lists which browsers and apps are checked by hand, and how a report is
handled. GitHub shows it as the repository's Accessibility tab. Barriers get
their own issue form and an `accessibility` label, and the About page links
the statement and the form.
- A pull request template covering what and why, the checks to run, and a
short accessibility list for interface changes.
### 🐛 Fixed
- The About page's stack list said SvelteKit 2 and counted 3,600 rows. Its
footnote said everything the page loads comes from this site, which is not
true of Cloudflare's beacon and human check. It now says what is true: the
game data and art come from this site. The Vietnamese AI note gains the
sentence it was missing.
- Source archives (`git archive`, GitHub's "Source code" downloads) left out
three legal documents that the web build reads, so building from one
stopped. They are included now.
### 📚 Docs
- The community docs match the repository again:
- **README:** live game-count and version badges, SvelteKit 3, every desktop
package, the shard layout, the workflows its table left out, and which
commits deploy.
- **SECURITY.md:** the real stack, pushes with the built-in token, and the
media host and the ingest and update endpoints in scope.
- **AUTHORS.md, `username.txt`, CONTRIBUTING.md and the code of conduct.**
- **The issue forms:** the hash links, GitHub Pages permalinks and the
editing and GPG options are gone. The version is under the title, not
behind a hover.
- **`web/README.md`, `docs/dev_env.md` (EN + VI), the acknowledgements and
the contact page.** Neither of the last two is a document you accept, so
nobody is asked to accept the terms again.
- `CLAUDE.md`: `ACCESSIBILITY.md` is a claim about the code, kept true in the
same pull request.
## [v4.7.0] – 2026-11-03 (The "Lucky Dip" Edition) ## [v4.7.0] – 2026-11-03 (The "Lucky Dip" Edition)
Two small additions. A Random games page picks up to five games from the Two small additions. A Random games page picks up to five games from the
+2 -2
View File
@@ -8,12 +8,12 @@ Be nice. Or at least civil. We're all unemployed introverts at heart (or pretend
### Standards ### Standards
- **Be respectful:** No harassment, no toxicity, no personal attacks. This ain't Dota 2 chat. - **Be respectful:** No harassment, no toxicity, no personal attacks. This ain't Dota 2 chat.
- **Be helpful:** Suggestions, additions, fixes – yes. Trolling, spam, off-topic rants – no. - **Be helpful:** Suggestions, additions, fixes – yes. Trolling, spam, off-topic rants – no.
- **Be inclusive:** Everyone's welcome, regardless of skill level (especially noobs on Easy mode). - **Be inclusive:** Everyone's welcome, regardless of skill level (especially noobs on Easy mode), and however you use the site: mouse, keyboard, screen reader, zoom. If something keeps you out, see [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
- **No malware/fake links:** Instant ban from contributing. I have trust issues already. - **No malware/fake links:** Instant ban from contributing. I have trust issues already.
- **Disagreements?** Keep it calm in Issues/PRs. If it gets heated, I'll just close it and go play a game. - **Disagreements?** Keep it calm in Issues/PRs. If it gets heated, I'll just close it and go play a game.
### Enforcement ### Enforcement
I'm the only maintainer (with Grok as backup), so violations = close issue/PR, block if needed. No appeals – life's too short. I'm the only maintainer (with an AI assistant as backup), so violations = close issue/PR, block if needed. No appeals – life's too short.
**Reporting:** if something needs raising privately rather than in the Issue **Reporting:** if something needs raising privately rather than in the Issue
thread it happened in, email **contact@poli0981.dev**. One person reads it, so thread it happened in, email **contact@poli0981.dev**. One person reads it, so
+4 -2
View File
@@ -33,6 +33,7 @@ Go to the [Issues tab](https://github.com/poli0981/free-steam-games-list/issues/
- ➖ **Delete game** (max 10 per issue) - ➖ **Delete game** (max 10 per issue)
- 🐛 **Bug report** - 🐛 **Bug report**
- ♿ **Accessibility barrier** — something you can't use with a keyboard, a screen reader or zoom (see [`ACCESSIBILITY.md`](ACCESSIBILITY.md))
- 💡 **Feature request / improvement** - 💡 **Feature request / improvement**
- 📢 **Feedback / rant** - 📢 **Feedback / rant**
- ❓ **Off-topic** - ❓ **Off-topic**
@@ -58,7 +59,7 @@ For code changes, or to queue games yourself:
{"link": "730"} {"link": "730"}
{"link": "https://store.steampowered.com/app/570/"} {"link": "https://store.steampowered.com/app/570/"}
``` ```
3. Push → open PR. Reviewer (= me) will look when caffeine hits. 3. Push → open PR. The template has a short checklist: what and why, the tests you ran, and an accessibility pass for interface changes. Reviewer (= me) will look when caffeine hits.
A queued line is a link and nothing else: any other key is ignored, and the game is fetched from Steam and checked (free, a game, reachable) before it is published. A queued line is a link and nothing else: any other key is ignored, and the game is fetched from Steam and checked (free, a game, reachable) before it is published.
@@ -70,7 +71,8 @@ A queued line is a link and nothing else: any other key is ignored, and the game
- **Notes / safe** are worth mentioning in a suggestion ("safe to play", "Toxic max", "Grind phê Easy mode"); the maintainer records them as overrides. - **Notes / safe** are worth mentioning in a suggestion ("safe to play", "Toxic max", "Grind phê Easy mode"); the maintainer records them as overrides.
- **Spam / off-topic** issues get closed without comment. Don't be that person. - **Spam / off-topic** issues get closed without comment. Don't be that person.
- **Code style:** match the surrounding file. No hard rules. The Python pipeline is intentionally low-ceremony; the web side (SvelteKit, the Worker, `admin/`) is TS-strict. - **Code style:** match the surrounding file. No hard rules. The Python pipeline is intentionally low-ceremony; the web side (SvelteKit, the Worker, `admin/`) is TS-strict.
- **Tests:** for web changes, `npm run typecheck && npm test && npm run build` must pass (in `web/`). For pipeline changes, `python -m pytest scripts/tests`. - **Tests:** for web changes, `npm run typecheck && npm test && npm run build && node scripts/verify-dist.mjs --web` must pass (in `web/`). For pipeline changes, `python -m pytest scripts/tests`.
- **Accessibility:** interface changes get a keyboard pass and keep their names, focus and contrast. The short list is in [`ACCESSIBILITY.md`](ACCESSIBILITY.md#for-contributors) and in the PR template.
## Code of conduct ## Code of conduct
+33 -17
View File
@@ -1,7 +1,7 @@
[![Games Count](https://img.shields.io/badge/Games-3.6k%2B-green?style=flat&logo=steam)](data/) [![Games Count](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fpoli0981%2Ffree-steam-games-list%2Fmain%2Fdata%2Findex.json&query=%24.total&label=Games&color=green&style=flat&logo=steam)](data/)
[![Last Updated](https://img.shields.io/badge/Updated-Daily-blue?style=flat&logo=github-actions)](.github/workflows) [![Last Updated](https://img.shields.io/badge/Updated-Daily-blue?style=flat&logo=github-actions)](.github/workflows)
[![Top Online](https://img.shields.io/badge/Top%20Online-Live%20Leaderboard-red?style=flat&logo=steam)](games/top-online.md) [![Top Online](https://img.shields.io/badge/Top%20Online-Live%20Leaderboard-red?style=flat&logo=steam)](games/top-online.md)
[![Version](https://img.shields.io/badge/version-4.0.0-purple?style=flat&logo=github)](https://github.com/poli0981/free-steam-games-list) [![Version](https://img.shields.io/github/v/release/poli0981/free-steam-games-list?filter=v*&sort=semver&label=version&color=purple&style=flat&logo=github)](https://github.com/poli0981/free-steam-games-list/releases)
[![Web App](https://img.shields.io/badge/Web%20App-Live-2563eb?style=flat&logo=svelte)](https://free-steam-games.win/) [![Web App](https://img.shields.io/badge/Web%20App-Live-2563eb?style=flat&logo=svelte)](https://free-steam-games.win/)
[![Desktop](https://img.shields.io/badge/Desktop-Tauri%202-FFC131?style=flat&logo=tauri)](https://github.com/poli0981/free-steam-games-list/releases) [![Desktop](https://img.shields.io/badge/Desktop-Tauri%202-FFC131?style=flat&logo=tauri)](https://github.com/poli0981/free-steam-games-list/releases)
[![Android](https://img.shields.io/badge/Android-11%2B%20APK-3DDC84?style=flat&logo=android)](https://github.com/poli0981/free-steam-games-list/releases) [![Android](https://img.shields.io/badge/Android-11%2B%20APK-3DDC84?style=flat&logo=android)](https://github.com/poli0981/free-steam-games-list/releases)
@@ -9,7 +9,7 @@
![Visitors](https://visitor-badge.laobi.icu/badge?page_id=poli0981.free-steam-games-list) ![Visitors](https://visitor-badge.laobi.icu/badge?page_id=poli0981.free-steam-games-list)
[![Sponsor](https://img.shields.io/badge/Sponsor-Buy%20me%20a%20coffee-ff5f5f?style=flat&logo=buy-me-a-coffee)](.github/FUNDING.yml) [![Sponsor](https://img.shields.io/badge/Sponsor-Buy%20me%20a%20coffee-ff5f5f?style=flat&logo=buy-me-a-coffee)](.github/FUNDING.yml)
A **curated list** of free-to-play games on Steam — now ~3,600 of them — no quality guarantees, no endorsements, just pure listings by a broke, unemployed Vietnamese dev with too much free time and a Steam library full of sale games (80% under $10). A **curated list** of free-to-play games on Steam — the badge above has today's count — no quality guarantees, no endorsements, just pure listings by a broke, unemployed Vietnamese dev with too much free time and a Steam library full of sale games (80% under $10).
**v4.0.0** is the version that got rebuilt from the ground up. It is still a list. It is also: **v4.0.0** is the version that got rebuilt from the ground up. It is still a list. It is also:
@@ -28,20 +28,21 @@ A **curated list** of free-to-play games on Steam — now ~3,600 of them — no
| Surface | URL | | Surface | URL |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- | | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 🌐 Web app | <https://free-steam-games.win/> | | 🌐 Web app | <https://free-steam-games.win/> |
| 🖥️ Desktop releases | [GitHub Releases](https://github.com/poli0981/free-steam-games-list/releases) (Win `.msi`, Mac `.dmg`, Linux `.AppImage`) | | 🖥️ Desktop releases | [GitHub Releases](https://github.com/poli0981/free-steam-games-list/releases) (Win `.msi` / `.exe`, Mac `.dmg`, Linux `.AppImage` / `.deb` / `.rpm`) |
| 📱 Android APK | [GitHub Releases](https://github.com/poli0981/free-steam-games-list/releases) (sideload `.apk`, **Android 11+** — see [`docs/android-support.md`](docs/android-support.md)) | | 📱 Android APK | [GitHub Releases](https://github.com/poli0981/free-steam-games-list/releases) (sideload `.apk`, **Android 11+** — see [`docs/android-support.md`](docs/android-support.md)) |
| 🏆 Top online (md) | [games/top-online.md](games/top-online.md) | | 🏆 Top online (md) | [games/top-online.md](games/top-online.md) |
| 🎯 Top offline (md) | [games/top-offline.md](games/top-offline.md) | | 🎯 Top offline (md) | [games/top-offline.md](games/top-offline.md) |
| 📦 Raw data | [data/data_001.jsonl](data/data_001.jsonl) … `data_005.jsonl` (5 sharded JSONL files) | | 📦 Raw data | [data/](data/) — JSONL shards of 800 games each (`data_001.jsonl` …), listed with a SHA-256 each in [`data/index.json`](data/index.json) |
| 🛠️ About | <https://free-steam-games.win/about> (in-app) | | 🛠️ About | <https://free-steam-games.win/about> (in-app) |
| 👤 Authors | [`AUTHORS.md`](AUTHORS.md) — maintainer + contact channels + AI-assistant disclosure | | 👤 Authors | [`AUTHORS.md`](AUTHORS.md) — maintainer + contact channels + AI-assistant disclosure |
| ♿ Accessibility | [`ACCESSIBILITY.md`](ACCESSIBILITY.md) — what works with a keyboard, screen reader and zoom, what doesn't yet, how to report a barrier |
### What's new in v4.0.0 ### What's in v4
<details> <details>
<summary><b>Web app at <code>free-steam-games.win/</code></b></summary> <summary><b>Web app at <code>free-steam-games.win/</code></b></summary>
A SvelteKit 2 / Svelte 5 app, prerendered and served by a Cloudflare Worker that also proxies the dataset (`/api/data/*`) and Steam artwork (`/img/*`), so your browser talks to this site only — apart from Cloudflare's analytics beacon and its Turnstile human check, both loaded only after you accept the terms. Features: A SvelteKit 3 / Svelte 5 app, prerendered and served by a Cloudflare Worker that also proxies the dataset (`/api/data/*`) and Steam artwork (`/img/*`; on the website the art comes from the site's own media host, `media.free-steam-games.win`), so your browser talks to this site only — apart from Cloudflare's analytics beacon and its Turnstile human check, both loaded only after you accept the terms. Features:
- **Browse** — virtualised table (TanStack Virtual), filters for genre, type, platform, status, anti-cheat and safety, Fuse.js fuzzy search, sortable columns, 50/100/200/500/all pages. Filters live in the URL, so a filtered view can be shared. - **Browse** — virtualised table (TanStack Virtual), filters for genre, type, platform, status, anti-cheat and safety, Fuse.js fuzzy search, sortable columns, 50/100/200/500/all pages. Filters live in the URL, so a filtered view can be shared.
- **Charts** — Apache ECharts: dashboard KPIs, genres, platforms, languages, tags, anti-cheat (chart and a searchable index), reviews, player tiers, release years and catalogue growth, DRM/DLC, delisted games, plus a stats page (Metacritic, retention, games that went quiet). - **Charts** — Apache ECharts: dashboard KPIs, genres, platforms, languages, tags, anti-cheat (chart and a searchable index), reviews, player tiers, release years and catalogue growth, DRM/DLC, delisted games, plus a stats page (Metacritic, retention, games that went quiet).
@@ -52,7 +53,7 @@ A SvelteKit 2 / Svelte 5 app, prerendered and served by a Cloudflare Worker that
- **i18n** vi / en — auto-detected, switchable from the welcome page or Settings. - **i18n** vi / en — auto-detected, switchable from the welcome page or Settings.
- **⌘K command palette**, **first-run introduction**, and the legal documents rendered in the app. - **⌘K command palette**, **first-run introduction**, and the legal documents rendered in the app.
Pushing to `main` deploys (Cloudflare Workers Builds). Pipeline commits to `data/**` do not need a rebuild: the data is proxied, not bundled. See [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md). Cloudflare Workers Builds deploys from `main`; which commits trigger a build is in [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md). Pipeline commits to `data/**` do not need a rebuild: the data is proxied, not bundled.
</details> </details>
@@ -61,7 +62,7 @@ Pushing to `main` deploys (Cloudflare Workers Builds). Pipeline commits to `data
A native shell around the same web app, distributed via [GitHub Releases](https://github.com/poli0981/free-steam-games-list/releases): A native shell around the same web app, distributed via [GitHub Releases](https://github.com/poli0981/free-steam-games-list/releases):
- Windows `.msi`, macOS `.dmg` (universal Apple Silicon + Intel), Linux `.AppImage` and `.deb`, and an Android `.apk`. - Windows `.msi` and `-setup.exe`, macOS `.dmg` (universal Apple Silicon + Intel), Linux `.AppImage`, `.deb` and `.rpm`, and an Android `.apk`.
- Resizable window; `steam://` links open the Steam client. - Resizable window; `steam://` links open the Steam client.
- The desktop app checks for a signed update on start and installs it when you say so, keeping your settings. - The desktop app checks for a signed update on start and installs it when you say so, keeping your settings.
- Same data path as the web app (`/api/data/*` on free-steam-games.win), same offline cache. - Same data path as the web app (`/api/data/*` on free-steam-games.win), same offline cache.
@@ -101,9 +102,11 @@ The Python pipeline that powered v2 is untouched and runs daily as before:
``` ```
. .
├── data/ # Sharded data (the source of truth) ├── data/ # Sharded data (the source of truth)
│ ├── data_001.jsonl # ≤ 800 records │ ├── data_001.jsonl … # 800 records per shard, as many shards as it takes
│ ├── data_002.jsonl … 005 # the rest │ ├── index.json # last_updated, totals, shard manifest (SHA-256 each)
│ └── index.json # last_updated, totals, shard manifest │ ├── blocklist.jsonl # removed games, kept out of every write
│ ├── overrides/ # human corrections, re-applied on every write
│ └── snapshots/ # daily per-game players and reviews
│ │
├── games/ # The two generated leaderboards ├── games/ # The two generated leaderboards
│ ├── top-online.md # live leaderboard │ ├── top-online.md # live leaderboard
@@ -128,7 +131,7 @@ The Python pipeline that powered v2 is untouched and runs daily as before:
│ ├── src-tauri/ # Tauri 2 desktop + Android shell (Rust) │ ├── src-tauri/ # Tauri 2 desktop + Android shell (Rust)
│ └── static/ # icons, social image, robots.txt, _headers │ └── static/ # icons, social image, robots.txt, _headers
│ │
├── docs/ # Legal + acknowledgements + contact ├── docs/ # Legal, setup and ops docs, plans (plan/), Vietnamese copies (i18n/vi/)
├── .github/workflows/ # data pipeline, discovery, CI, desktop/Android release ├── .github/workflows/ # data pipeline, discovery, CI, desktop/Android release
├── LICENSE # MIT — code ├── LICENSE # MIT — code
└── LICENSE-DATA # CC BY 4.0 — dataset └── LICENSE-DATA # CC BY 4.0 — dataset
@@ -193,7 +196,15 @@ scripts/
| Release Desktop / Android | On `desktop-v*` / `android-v*` tag | Build the apps into a draft release | | Release Desktop / Android | On `desktop-v*` / `android-v*` tag | Build the apps into a draft release |
| Announce Discussion | On release `published` | Auto-create a GitHub Discussion in `Announcements` | | Announce Discussion | On release `published` | Auto-create a GitHub Discussion in `Announcements` |
The site itself is deployed by Cloudflare Workers Builds on every push to `main`, not by a workflow. Also in `.github/workflows/`:
- **CodeQL** and **SonarCloud**: code scanning on pushes and pull requests.
- **Check Overrides**: pull requests that touch the override or blocklist files.
- **Backfill Discovery**: temporary; a weekly re-sweep of older release windows into the same `/admin` queue.
- **Announce Release to Discord**: posts each published release.
- Three **Notify** workflows: CI failures, the Pages deploy, the release pipeline.
- **Deploy Web (GitHub Pages)**: it only serves a redirect to the new site now.
The site itself is deployed by Cloudflare Workers Builds, not by a workflow.
### Contribute ### Contribute
@@ -210,9 +221,11 @@ is archived and no longer a way in.
**Issues** are for reports, not submissions: **Issues** are for reports, not submissions:
[Bug report](.github/ISSUE_TEMPLATE/bug_report.yml), [Bug report](.github/ISSUE_TEMPLATE/bug_report.yml),
[Accessibility barrier](.github/ISSUE_TEMPLATE/accessibility.yml),
[Feature request](.github/ISSUE_TEMPLATE/feature_request.yml), [Feature request](.github/ISSUE_TEMPLATE/feature_request.yml),
[Delete game](.github/ISSUE_TEMPLATE/delete_game.yml) and [Delete game](.github/ISSUE_TEMPLATE/delete_game.yml),
[Feedback](.github/ISSUE_TEMPLATE/feedback.yml). All reviewed by hand. [Feedback](.github/ISSUE_TEMPLATE/feedback.yml) and
[Off-topic](.github/ISSUE_TEMPLATE/off_topic.yml). All reviewed by hand.
**The manual way.** Fork, append store links to `scripts/temp_info.jsonl`, and open a pull request: **The manual way.** Fork, append store links to `scripts/temp_info.jsonl`, and open a pull request:
@@ -257,7 +270,10 @@ Unemployed, introvert max level, dropped out uni year 3, mooching off family. Ne
- [Contact](docs/Contact.md) — where to find the maintainer. - [Contact](docs/Contact.md) — where to find the maintainer.
- [CODE OF CONDUCT](CODE_OF_CONDUCT.md) — be chill. - [CODE OF CONDUCT](CODE_OF_CONDUCT.md) — be chill.
- [SECURITY](SECURITY.md) — vulnerability reporting. - [SECURITY](SECURITY.md) — vulnerability reporting.
- [`web/README.md`](web/README.md) — stack details, per-phase changelog, build instructions. - [Security setup](docs/SECURITY_SETUP.md) — the operational side: headers, WAF, rate limits, Access, each with a check command.
- [ACCESSIBILITY](ACCESSIBILITY.md) — what works with a keyboard, screen reader and zoom, what doesn't yet, and how to report a barrier.
- [Android support](docs/android-support.md) ([VI](docs/i18n/vi/android-support.md)) — why Android 11+, and what the APK is tested on.
- [`web/README.md`](web/README.md) — web stack, data paths, CSP, PWA, i18n, build and checks.
Code is [MIT](LICENSE); the dataset is [CC BY 4.0](LICENSE-DATA) with carve-outs for fields the project does not own (`description`, `header_image`). Keep the right licence with you if you fork. Star if you find a hidden gem ✨ Code is [MIT](LICENSE); the dataset is [CC BY 4.0](LICENSE-DATA) with carve-outs for fields the project does not own (`description`, `header_image`). Keep the right licence with you if you fork. Star if you find a hidden gem ✨
+21 -11
View File
@@ -6,17 +6,21 @@ The previous version of this file said the repository was "just a Markdown
list… no executable code, no dependencies, no backend, no user data." That was list… no executable code, no dependencies, no backend, no user data." That was
wrong on every count, so here is the real picture: wrong on every count, so here is the real picture:
- a **Cloudflare Worker** serving the site, holding a D1 binding and — for the - a **Cloudflare Worker** serving the site. It holds a D1 binding, an R2
admin path — a credential that can write to this repository bucket for the game art (public at `media.free-steam-games.win`), a
- a **React single-page app** with a few dozen npm dependencies 15-minute cron (reconcile, auto-approve, and minting the art into that
bucket), and, for the admin path, a credential that can write to this
repository
- a **SvelteKit / Svelte 5 web app**, prerendered to static pages, with a few
dozen npm dependencies, plus the `/admin` app embedded in the Worker
- a **Tauri 2 desktop and Android app**, signed, with an auto-updater - a **Tauri 2 desktop and Android app**, signed, with an auto-updater
Operational hardening — headers, HSTS, rate limiting, WAF — is documented in - a **Python pipeline** run by GitHub Actions. The data jobs push to `main`
with the built-in `GITHUB_TOKEN`; the release jobs hold the app signing keys
Operational hardening (headers, HSTS, rate limiting, WAF) is documented in
[`docs/SECURITY_SETUP.md`](docs/SECURITY_SETUP.md), with a check command for [`docs/SECURITY_SETUP.md`](docs/SECURITY_SETUP.md), with a check command for
each item. each item.
- a **Python pipeline** run by 23 GitHub Actions workflows, several holding
secrets that can push to `main`
There is genuinely something to attack here. Hence a real policy. There is genuinely something to attack here. Hence a real policy.
## Reporting ## Reporting
@@ -46,17 +50,21 @@ reproduce. A proof-of-concept URL beats a paragraph of description.
- The Cloudflare Worker (`web/worker/**`) — the data proxy, the image proxy, - The Cloudflare Worker (`web/worker/**`) — the data proxy, the image proxy,
and anything reachable under `/api/*` and anything reachable under `/api/*`
- The `/admin` path and its Cloudflare Access gate - The `/admin` path and `/api/ingest/*`, and their Cloudflare Access gates
- The D1 database and anything that writes to it - The D1 database and anything that writes to it
- The media host, `media.free-steam-games.win` (the R2 bucket's public
domain), and whatever the cron writes to it
- The GitHub Actions workflows, especially any path where untrusted input - The GitHub Actions workflows, especially any path where untrusted input
reaches a step that can push to `main` reaches a step that can push to `main`
- The Tauri updater and its signing key - The Tauri updater, its signing key, and its feed at `/api/updates/desktop`
- Dependency vulnerabilities that are actually reachable from shipped code - Dependency vulnerabilities that are actually reachable from shipped code
Things worth probing specifically: making `/img/*` fetch an origin that is not Things worth probing specifically: making `/img/*` fetch an origin that is not
`shared.akamai.steamstatic.com` or `shared.fastly.steamstatic.com`; making `shared.akamai.steamstatic.com` or `shared.fastly.steamstatic.com` (or, for
the avatars under `/img/gh/*`, `avatars.githubusercontent.com`); making
`/api/data/*` return a path outside its allowlist; reaching admin `/api/data/*` return a path outside its allowlist; reaching admin
functionality without an Access session. functionality without an Access session; getting the update feed to offer a
file that is not this repository's release download.
## Out of scope ## Out of scope
@@ -72,6 +80,8 @@ functionality without an Access session.
already read. A way to make `/api/human-check` accept a token Cloudflare already read. A way to make `/api/human-check` accept a token Cloudflare
rejected is in scope. rejected is in scope.
- Social engineering of the maintainer. - Social engineering of the maintainer.
- Accessibility barriers. They are real bugs, but not security ones: see
[`ACCESSIBILITY.md`](ACCESSIBILITY.md).
## What to expect ## What to expect
+3 -3
View File
@@ -5,7 +5,7 @@ Big thanks to everyone and everything that made this chaotic repo possible.
### People & Platforms ### People & Platforms
- **Valve / Steam** — for existing and having a ton of free-to-play games that keep broke people like the maintainer entertained. The Steam logo, store, community, VAC, and all related marks are trademarks of Valve Corporation; this project is independent and not affiliated. - **Valve / Steam** — for existing and having a ton of free-to-play games that keep broke people like the maintainer entertained. The Steam logo, store, community, VAC, and all related marks are trademarks of Valve Corporation; this project is independent and not affiliated.
- **GitHub** — for free hosting (data, Pages, Actions, Releases), free CI for the Python pipeline + the web app deploy + the desktop release matrix builds, and for letting unemployed devs pretend they're productive. - **GitHub** — for free hosting (data, Pages, Actions, Releases), free CI for the Python pipeline + the web app's checks + the desktop and Android release builds, and for letting unemployed devs pretend they're productive.
- **Steam Charts** ([steamcharts.com](https://steamcharts.com/)) — for the all-time peak player counts. The pipeline reads each game's recorded peak from its public page, about once a month per game and a few seconds apart. Not affiliated with this project. - **Steam Charts** ([steamcharts.com](https://steamcharts.com/)) — for the all-time peak player counts. The pipeline reads each game's recorded peak from its public page, about once a month per game and a few seconds apart. Not affiliated with this project.
- **The Steam community & various review aggregators** — for reviews, tags, and metadata that the pipeline scrapes off public store pages. Where copy-paste happens it stays attributed. - **The Steam community & various review aggregators** — for reviews, tags, and metadata that the pipeline scrapes off public store pages. Where copy-paste happens it stays attributed.
- **Caffeine & instant noodles** — the real MVPs keeping the maintainer awake during update sessions. - **Caffeine & instant noodles** — the real MVPs keeping the maintainer awake during update sessions.
@@ -51,7 +51,7 @@ in-app **About → Stack & third-party** section shows the headline ones with
links and licences; this is the whole list, grouped by what it does. links and licences; this is the whole list, grouped by what it does.
**Framework & build** **Framework & build**
- [Svelte 5](https://svelte.dev/) + [SvelteKit 2](https://svelte.dev/docs/kit) — UI runtime and app framework, with `adapter-static` (all MIT). - [Svelte 5](https://svelte.dev/) + [SvelteKit 3](https://svelte.dev/docs/kit) — UI runtime and app framework, with `adapter-static` (all MIT).
- [TypeScript 7](https://www.typescriptlang.org/) — type system (Apache-2.0); the native compiler type-checks the code, and TypeScript 6 stays alongside it for the Svelte tooling, which needs its JavaScript API. - [TypeScript 7](https://www.typescriptlang.org/) — type system (Apache-2.0); the native compiler type-checks the code, and TypeScript 6 stays alongside it for the Svelte tooling, which needs its JavaScript API.
- [Vite 8](https://vitejs.dev/), powered by the [Rolldown](https://rolldown.rs/) bundler, and `@sveltejs/vite-plugin-svelte` (MIT). - [Vite 8](https://vitejs.dev/), powered by the [Rolldown](https://rolldown.rs/) bundler, and `@sveltejs/vite-plugin-svelte` (MIT).
- [Tailwind CSS 4](https://tailwindcss.com/) via `@tailwindcss/vite` (MIT). Tailwind 4 is a Vite plugin, so there is no PostCSS step and no `tailwind.config.ts`. - [Tailwind CSS 4](https://tailwindcss.com/) via `@tailwindcss/vite` (MIT). Tailwind 4 is a Vite plugin, so there is no PostCSS step and no `tailwind.config.ts`.
@@ -79,7 +79,7 @@ links and licences; this is the whole list, grouped by what it does.
- [unified](https://unifiedjs.com/) with remark-parse, remark-gfm, remark-rehype, rehype-sanitize, rehype-slug and rehype-stringify — markdown to HTML (all MIT). These run at BUILD time only, so no parser or sanitizer reaches the browser. - [unified](https://unifiedjs.com/) with remark-parse, remark-gfm, remark-rehype, rehype-sanitize, rehype-slug and rehype-stringify — markdown to HTML (all MIT). These run at BUILD time only, so no parser or sanitizer reaches the browser.
**Offline** **Offline**
- [Workbox](https://developer.chrome.com/docs/workbox) via [`@vite-pwa/sveltekit`](https://vite-pwa-org.netlify.app/) — service worker and precache (MIT). Web only: the packaged apps never register one. - [Workbox](https://developer.chrome.com/docs/workbox) via [`vite-plugin-pwa`](https://vite-pwa-org.netlify.app/) — service worker and precache (MIT). Web only: the packaged apps never register one.
**Typefaces** **Typefaces**
- [Bricolage Grotesque](https://github.com/ateliertriay/bricolage), [IBM Plex Sans](https://github.com/IBM/plex) and [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono), self-hosted through `@fontsource-variable` (all OFL-1.1). - [Bricolage Grotesque](https://github.com/ateliertriay/bricolage), [IBM Plex Sans](https://github.com/IBM/plex) and [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono), self-hosted through `@fontsource-variable` (all OFL-1.1).
+1 -1
View File
@@ -4,7 +4,7 @@ Oh, you made it here? :)) Wild – I figured no one would bother with a "contact
## Quick Bio (Spoiler: Nothing Impressive) ## Quick Bio (Spoiler: Nothing Impressive)
A 20-something (guess: 22–23?) Vietnamese dev scraping by in unremarkable youth – unemployed, mildly self-loathing, introvert on god-mode, dropped out of university year 3 (details? See FAQ – it's a mess :D), mooching off family, with AI (currently Grok) as my only non-judgmental buddy. Yeah, that's the vibe. A 20-something (guess: 22–23?) Vietnamese dev scraping by in unremarkable youth – unemployed, mildly self-loathing, introvert on god-mode, dropped out of university year 3 (details? See FAQ – it's a mess :D), mooching off family, with AI (currently Claude) as my only non-judgmental buddy. Yeah, that's the vibe.
**Skills? Mediocre at Best:** **Skills? Mediocre at Best:**
- **Gaming**: Normal/Easy mode only – life's hard enough. Want to see "legendary noob plays" that go straight to hell? The links below will get you there. You'll witness decision-making that buries itself in the earth's core :))) - **Gaming**: Normal/Easy mode only – life's hard enough. Want to see "legendary noob plays" that go straight to hell? The links below will get you there. You'll witness decision-making that buries itself in the earth's core :)))
+1 -1
View File
@@ -89,4 +89,4 @@ Larger features (multi-task batches like the v3.x release cycle) are landed in p
- [`pc_spec.md`](pc_spec.md) — hardware spec - [`pc_spec.md`](pc_spec.md) — hardware spec
- [`../web/src-tauri/TAURI.md`](../web/src-tauri/TAURI.md) — Tauri 2 desktop build prerequisites - [`../web/src-tauri/TAURI.md`](../web/src-tauri/TAURI.md) — Tauri 2 desktop build prerequisites
- [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — contribution paths (issue / discussion / fork) - [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — contribution paths (issue / discussion / fork)
- [`../web/README.md`](../web/README.md) — web stack details + per-phase changelog - [`../web/README.md`](../web/README.md) — web stack, data paths, CSP, PWA, i18n, build + checks
+1 -1
View File
@@ -89,4 +89,4 @@ Feature lớn (gộp nhiều task như v3.x) gom thành phase-PR để history d
- [`pc_spec.md`](pc_spec.md) — cấu hình máy - [`pc_spec.md`](pc_spec.md) — cấu hình máy
- [`../../../web/src-tauri/TAURI.md`](../../../web/src-tauri/TAURI.md) — yêu cầu build Tauri 2 desktop - [`../../../web/src-tauri/TAURI.md`](../../../web/src-tauri/TAURI.md) — yêu cầu build Tauri 2 desktop
- [`../../../CONTRIBUTING.md`](../../../CONTRIBUTING.md) — các đường đóng góp (issue / discussion / fork) - [`../../../CONTRIBUTING.md`](../../../CONTRIBUTING.md) — các đường đóng góp (issue / discussion / fork)
- [`../../../web/README.md`](../../../web/README.md) — chi tiết stack web + changelog từng phase - [`../../../web/README.md`](../../../web/README.md) — stack web, đường dữ liệu, CSP, PWA, i18n, build + kiểm tra
+3 -2
View File
@@ -8,5 +8,6 @@ copyright: copyright@poli0981.dev
links: https://poli0981.dev/links/ links: https://poli0981.dev/links/
`links` is the single source of truth for every other channel (chat, socials, `links` is the single source of truth for every other channel (chat, socials,
video, donations). Handles are maintained there, not here, so a moved or video). Handles are maintained there, not here, so a moved or retired account
retired account cannot leave a dead link in this repository. cannot leave a dead link in this repository. Donation links are the exception:
they live in .github/FUNDING.yml.
+9 -5
View File
@@ -10,7 +10,7 @@ served only behind Cloudflare Access. See [docs/ADMIN.md](../docs/ADMIN.md).
## Stack ## Stack
- **SvelteKit 2 + Svelte 5** (runes), prerendered to static HTML by - **SvelteKit 3 + Svelte 5** (runes), prerendered to static HTML by
`@sveltejs/adapter-static` `@sveltejs/adapter-static`
- **Vite 8** (Rolldown) + **TypeScript** - **Vite 8** (Rolldown) + **TypeScript**
- **Tailwind CSS 4** — as a Vite plugin; there is no `tailwind.config.ts` and - **Tailwind CSS 4** — as a Vite plugin; there is no `tailwind.config.ts` and
@@ -18,7 +18,7 @@ served only behind Cloudflare Access. See [docs/ADMIN.md](../docs/ADMIN.md).
- **Bits UI** primitives, **@lucide/svelte** icons, **svelte-sonner** toasts - **Bits UI** primitives, **@lucide/svelte** icons, **svelte-sonner** toasts
- **Apache ECharts 6** (`echarts/core` + an explicit `use()` list) and - **Apache ECharts 6** (`echarts/core` + an explicit `use()` list) and
`echarts-wordcloud` `echarts-wordcloud`
- **@tanstack/svelte-virtual** for the 3,600-row table - **@tanstack/svelte-virtual** for the games table
- **Fuse.js** (fuzzy search), **idb-keyval** (IndexedDB cache) - **Fuse.js** (fuzzy search), **idb-keyval** (IndexedDB cache)
- **unified / remark / rehype** — build time only, for `/legal/*` - **unified / remark / rehype** — build time only, for `/legal/*`
- Three self-hosted variable typefaces: Bricolage Grotesque, IBM Plex Sans, - Three self-hosted variable typefaces: Bricolage Grotesque, IBM Plex Sans,
@@ -31,7 +31,10 @@ The browser contacts two third parties, both only after the reader accepts the
terms and neither in the packaged apps: the Cloudflare Web Analytics beacon, terms and neither in the packaged apps: the Cloudflare Web Analytics beacon,
and Cloudflare Turnstile for the once-a-day human check (`src/lib/human-check.ts`, and Cloudflare Turnstile for the once-a-day human check (`src/lib/human-check.ts`,
[docs/SECURITY_SETUP.md](../docs/SECURITY_SETUP.md) section 12). Everything else [docs/SECURITY_SETUP.md](../docs/SECURITY_SETUP.md) section 12). Everything else
is same-origin, through the Worker. comes from this site: same-origin through the Worker, except the game art on
the website, which loads from the R2 bucket's own host,
`media.free-steam-games.win` (`src/lib/image.ts`), with `/img/*` as the
fallback.
## Quick start ## Quick start
@@ -55,8 +58,9 @@ node node_modules/wrangler/bin/wrangler.js dev --config wrangler.jsonc
## Where the data comes from ## Where the data comes from
The browser never talks to GitHub. Everything is same-origin through the The browser never talks to GitHub or to Valve. Everything below is
Worker: same-origin through the Worker; the website loads the AVIF art from
`media.free-steam-games.win` first and falls back to `/img/*`:
- `/api/data/data/index.json` — shard manifest (`max_per_file`, `total`, - `/api/data/data/index.json` — shard manifest (`max_per_file`, `total`,
`last_updated`, `files`) `last_updated`, `files`)