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:
value: |
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
**Delete game** templates are usually faster.
For things that aren't bugs: a missing game or a wrong genre goes in
[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
id: surface
@@ -17,7 +19,10 @@ body:
description: Helps me figure out which layer to look at first.
options:
- "Web app — https://free-steam-games.win/"
- "Desktop app (Windows / macOS / Linux)"
- "Android app"
- "Top online — games/top-online.md"
- "Top offline — games/top-offline.md"
- "Raw data — data/data_*.jsonl"
- "API / direct fetch"
- "Other (describe below)"
@@ -36,8 +41,6 @@ body:
- label: Reviews / players not updating
- label: Wrong game count / total
- 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: Dropdown / form validation issue
- label: Mobile-specific
@@ -49,8 +52,8 @@ body:
label: Describe the bug
description: |
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.
`#/games/730` or `#/charts/anti-cheat`).
If it's a web-app bug, include the page address (e.g.
`https://free-steam-games.win/games/730` or `/charts/anti-cheat`).
validations:
required: true
@@ -60,10 +63,10 @@ body:
label: Steps to reproduce
description: How can I see the bug? Numbered list works great.
placeholder: |
1. Open #/games
1. Open /games
2. Filter genre = FPS
3. Click row "Counter-Strike 2"
4. Edit drawer fails to open
3. Click the row "Counter-Strike 2"
4. The game page shows no player count
- type: textarea
id: screenshots
@@ -71,8 +74,8 @@ body:
label: Screenshots / links
description: |
Paste image URLs (drag-drop into this field works) or links to the
affected commit / row / chart. The web app supports per-game
permalinks — `https://poli0981.github.io/free-steam-games-list/#/games/{appid}`.
affected commit / row / chart. The web app has a page per game —
`https://free-steam-games.win/games/{appid}`.
- type: input
id: env-browser
@@ -84,9 +87,9 @@ body:
- type: input
id: env-version
attributes:
label: Web app version (for web app bugs)
description: Hover the F2P Tracker title in the sidebar — it shows the version.
placeholder: v0.1
label: App version (web, desktop or Android)
description: Shown as "Steam · v…" under the F2P Tracker title in the sidebar (in the menu on small screens).
placeholder: v2.5.0
- type: textarea
id: console
+2 -2
View File
@@ -6,7 +6,7 @@ body:
- type: markdown
attributes:
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
id: type
@@ -56,7 +56,7 @@ body:
id: code
attributes:
label: Code snippet/mockup (optional – no malware pls, I'll check though lazy :D)
render: python
render: text
- type: checkboxes
id: terms
+1 -1
View File
@@ -1,5 +1,5 @@
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] "
labels: ["off-topic"]
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/> |
`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.
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
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) |
| 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`) |
| 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) |
| 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
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)
About **~70 %** of the code in this repository was generated with help from large-language-model assistants:
- **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.
+41
View File
@@ -4,6 +4,47 @@ All notable changes to this awesome noob repo will be documented here.
## [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)
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
- **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 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.
- **Disagreements?** Keep it calm in Issues/PRs. If it gets heated, I'll just close it and go play a game.
### 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
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)
- 🐛 **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**
- 📢 **Feedback / rant**
- ❓ **Off-topic**
@@ -58,7 +59,7 @@ For code changes, or to queue games yourself:
{"link": "730"}
{"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.
@@ -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.
- **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.
- **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
+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)
[![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/)
[![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)
@@ -9,7 +9,7 @@
![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)
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:
@@ -28,20 +28,21 @@ A **curated list** of free-to-play games on Steam — now ~3,600 of them — no
| Surface | URL |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 🌐 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)) |
| 🏆 Top online (md) | [games/top-online.md](games/top-online.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) |
| 👤 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>
<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.
- **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.
- **⌘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>
@@ -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):
- 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.
- 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.
@@ -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_001.jsonl # ≤ 800 records
│ ├── data_002.jsonl … 005 # the rest
│ └── index.json # last_updated, totals, shard manifest
│ ├── data_001.jsonl … # 800 records per shard, as many shards as it takes
│ ├── index.json # last_updated, totals, shard manifest (SHA-256 each)
│ ├── 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
│ ├── 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)
│ └── 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
├── LICENSE # MIT — code
└── 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 |
| 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
@@ -210,9 +221,11 @@ is archived and no longer a way in.
**Issues** are for reports, not submissions:
[Bug report](.github/ISSUE_TEMPLATE/bug_report.yml),
[Accessibility barrier](.github/ISSUE_TEMPLATE/accessibility.yml),
[Feature request](.github/ISSUE_TEMPLATE/feature_request.yml),
[Delete game](.github/ISSUE_TEMPLATE/delete_game.yml) and
[Feedback](.github/ISSUE_TEMPLATE/feedback.yml). All reviewed by hand.
[Delete game](.github/ISSUE_TEMPLATE/delete_game.yml),
[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:
@@ -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.
- [CODE OF CONDUCT](CODE_OF_CONDUCT.md) — be chill.
- [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 ✨
+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
wrong on every count, so here is the real picture:
- a **Cloudflare Worker** serving the site, holding a D1 binding and — for the
admin path — a credential that can write to this repository
- a **React single-page app** with a few dozen npm dependencies
- a **Cloudflare Worker** serving the site. It holds a D1 binding, an R2
bucket for the game art (public at `media.free-steam-games.win`), a
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
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
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.
## 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,
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 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
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
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
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
@@ -72,6 +80,8 @@ functionality without an Access session.
already read. A way to make `/api/human-check` accept a token Cloudflare
rejected is in scope.
- Social engineering of the maintainer.
- Accessibility barriers. They are real bugs, but not security ones: see
[`ACCESSIBILITY.md`](ACCESSIBILITY.md).
## 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
- **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.
- **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.
@@ -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.
**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.
- [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`.
@@ -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.
**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**
- [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)
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:**
- **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
- [`../web/src-tauri/TAURI.md`](../web/src-tauri/TAURI.md) — Tauri 2 desktop build prerequisites
- [`../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
- [`../../../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)
- [`../../../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` is the single source of truth for every other channel (chat, socials,
video, donations). Handles are maintained there, not here, so a moved or
retired account cannot leave a dead link in this repository.
video). Handles are maintained there, not here, so a moved or retired account
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
- **SvelteKit 2 + Svelte 5** (runes), prerendered to static HTML by
- **SvelteKit 3 + Svelte 5** (runes), prerendered to static HTML by
`@sveltejs/adapter-static`
- **Vite 8** (Rolldown) + **TypeScript**
- **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
- **Apache ECharts 6** (`echarts/core` + an explicit `use()` list) and
`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)
- **unified / remark / rehype** — build time only, for `/legal/*`
- 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,
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
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
@@ -55,8 +58,9 @@ node node_modules/wrangler/bin/wrangler.js dev --config wrangler.jsonc
## Where the data comes from
The browser never talks to GitHub. Everything is same-origin through the
Worker:
The browser never talks to GitHub or to Valve. Everything below is
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`,
`last_updated`, `files`)