/` because every
- asset and data path in the code is **relative** (never start a path with `/`
- when editing).
+## 🎬 Explore the pages
-## Project structure
+### 🏠 Home
+*The next match with a live countdown, plus the tournament at a glance.*
-```
-worldcup2026/
-├── index.html SPA shell (header, tabs, hero, panels, modal root)
-├── assets/
-│ ├── css/ style.css · bracket.css · animations.css
-│ ├── js/ app.js (entry) · schedule.js · groups.js · bracket.js
-│ │ modal.js · stadiums.js · storage.js · i18n.js · calendar.js
-│ └── images/ flags/*.svg · stadiums/*.svg (placeholders)
-└── data/ ← the only thing you edit to maintain the site
- ├── teams.json 48 teams: { id, name, flag }
- ├── groups.json { "A": [4 team ids], … } × 12
- ├── matches.json 104 matches (UTC times; knockout uses bracketRef)
- ├── results.json one entry per match: scores + status (+ penalties)
- ├── stadiums.json name, city, capacity, image, IANA timezone
- └── bracket-config.json Round-of-32 slots + best-third assignment
-```
+
-## Maintaining the data
+### 📅 Matches
+*All 104 games in one place — search by team, city or stadium, filter by date, group, phase, team or venue, and flag your favourites with “My matches”.*
-> The current files contain **mock data** (real country names, fictional results)
-> so every feature can be exercised. Replace them with real data as the
-> tournament unfolds — no code changes needed.
+
-### Updating a result
+### 📊 Groups
+*Live standings for all 12 groups, worked out automatically from the results — points, goal difference, goals scored — with clear markers for who qualifies (and who’s chasing a best-third-place spot).*
-Edit the match's entry in `data/results.json`:
+
-```json
-{ "matchId": 74, "homeScore": 1, "awayScore": 1,
- "penalties": { "home": 4, "away": 3 }, "status": "finished" }
-```
+### 🏆 Knockout bracket
+*The centrepiece. A gorgeous interactive bracket that fills itself in as teams advance. Hover a team to trace its whole path to the final, zoom and pan around, switch between three layouts — **and predict it yourself**: pick winners, watch the rounds re-draw, then see how your picks score against the real results. You can even share your bracket as a link.*
-- `status`: `scheduled` → `live` → `finished`. Standings and the bracket only
- count `finished` matches.
-- `penalties` is optional — only for knockout draws.
+
-### Adding / changing matches
+### 🏟️ Stadiums
+*All 16 host venues across the three countries, each with its capacity and a jump straight to the matches played there.*
-`data/matches.json`. **All times are UTC** (the UI converts to local or stadium
-time). Group matches carry `homeTeam`/`awayTeam`; knockout matches carry a
-`bracketRef` (`R32-1`…`R32-16`, `R16-1`…, `QF-…`, `SF-…`, `THIRD-PLACE`, `FINAL`)
-and their teams are resolved automatically.
+
-### After the group stage: fill the third-place slots
+### 📈 Stats
+*A tournament stats screen: goals by stage and by round, records, a full 1–48 ranking and a head-to-head team comparator. Once the final is played, a champion “verdict” takes over the top of the page.*
-`data/bracket-config.json` is **the only file to edit** once the 8 best
-third-placed teams are known. Map each slot to a group letter:
+
-```json
-"thirdPlaceAssignment": { "1": "C", "2": "A", "3": null, … }
-```
+---
-A slot's team becomes `standings[group][3rd]`. Slots left `null` show a
-"Best 3rd #N" placeholder. The 16 `round32` entries define the bracket order
-(array position = bracket position) — they normally never change.
+## ✨ Under the hood (for the curious)
-### Teams, stadiums, images
+You don't need to be a developer to appreciate a few things that make this special:
-- `teams.json` — `flag` is a path relative to `assets/images/` (e.g. `flags/bra.svg`).
-- `stadiums.json` — `timezone` must be a valid IANA name (e.g. `America/Mexico_City`);
- it drives the "stadium time" display and stays correct across DST.
-- Replace the placeholder SVGs in `assets/images/` with real artwork keeping the
- same file names (or update the JSON paths).
+- **⚡ Loads in a blink.** The whole site is about **74 KB** of JavaScript — smaller than a single
+ phone photo — with **no frameworks and no libraries**. It's just clean, hand-written code.
+- **🔮 Predict the bracket.** Choose winners and the bracket redraws all the way to the final; your
+ picks are saved in your browser and can be handed to a friend as a link to compare.
+- **🔄 Always current.** New scores appear on their own — no need to refresh the page.
+- **📱 Works everywhere.** Phone, tablet or desktop, the layout adapts to fit.
+- **⬇️ Installable.** Add it to your home screen and it opens like a real app (it's a PWA).
+- **🌍 Two languages.** Every label is available in English and Portuguese, switchable on the fly.
+- **♿ Built to be usable by everyone.** Full keyboard navigation, screen-reader labels, and it
+ respects the system “reduce motion” setting.
-### UI labels (EN/PT)
+Curious how it's put together, or want to run it yourself? See **[DEVELOPMENT.md](DEVELOPMENT.md)**.
-Every UI string goes through `t(key)` — add new labels to **both** dictionaries
-in `assets/js/i18n.js`. Data values (team/stadium names) are not translated.
+---
-## Local storage
+
-| Key | Content |
-|---|---|
-| `wc2026_simulation` | `{ "R32-6": { "winner": "FRA", "score": "2-1" }, … }` |
-| `wc2026_favorites` | `["BRA", "MEX"]` |
-| `wc2026_prefs` | `{ "lang": "en"\|"pt", "timeMode": "local"\|"stadium", "lastTab": "bracket" }` |
+Made by **[Lucas Kalil](https://lucaskalil.com)** · Vanilla HTML, CSS & JavaScript.
-Clearing site data resets picks, favorites, and preferences — the JSON content
-is never modified by the app.
+A fan-made project for the love of the game. Not affiliated with, endorsed by, or sponsored by
+FIFA. All team and venue names belong to their respective owners.
-## Acceptance criteria (spec §18)
-
-- [x] All matches are loaded via JSON
-- [x] All results are loaded via JSON
-- [x] The bracket is generated dynamically (config + standings + winner pairing)
-- [x] Works on GitHub Pages (all paths relative, no server-side code)
-- [x] Works on desktop and mobile (≤767 / 768–1439 / 1440+ breakpoints)
-- [x] Allows knockout-stage simulation (persisted, never mutates JSON)
-- [x] Smooth animations (entry, hover, bracket line-draw; reduced-motion safe)
-- [x] No backend dependency — fully static, works offline after first load
-
-**Performance:** total JS ≈ 74 KB across 9 ES modules (budget: < 300 KB), no
-external dependencies, no blocking third-party requests.
-
-## Roadmap (spec §19)
-
-PWA install, dark/light theme, real-time statistics, results API, FIFA ranking,
-World Cup history, team comparison, push notifications.
+
diff --git a/docs/screenshots/bracket.png b/docs/screenshots/bracket.png
new file mode 100644
index 0000000..209090f
Binary files /dev/null and b/docs/screenshots/bracket.png differ
diff --git a/docs/screenshots/groups.png b/docs/screenshots/groups.png
new file mode 100644
index 0000000..a231633
Binary files /dev/null and b/docs/screenshots/groups.png differ
diff --git a/docs/screenshots/home.png b/docs/screenshots/home.png
new file mode 100644
index 0000000..06eca7a
Binary files /dev/null and b/docs/screenshots/home.png differ
diff --git a/docs/screenshots/matches.png b/docs/screenshots/matches.png
new file mode 100644
index 0000000..8d3a5f2
Binary files /dev/null and b/docs/screenshots/matches.png differ
diff --git a/docs/screenshots/stadiums.png b/docs/screenshots/stadiums.png
new file mode 100644
index 0000000..b31a5db
Binary files /dev/null and b/docs/screenshots/stadiums.png differ
diff --git a/docs/screenshots/stats.png b/docs/screenshots/stats.png
new file mode 100644
index 0000000..1c59e7e
Binary files /dev/null and b/docs/screenshots/stats.png differ