feat: add methodology and ground truth narrative to readme and site

README.md

@@ -1,8 +1,22 @@
-# Retrogaming BIOS & Firmware Collection
+# RetroBIOS
 
-Complete, verified collection of BIOS, firmware, and system files for retrogaming emulators.
+Source-verified BIOS and firmware packs for retrogaming platforms.
 
-> **6724** files | **5013.3 MB** | **8** platforms | **275** emulator profiles
+Every file in this collection is traced to its ground truth: the emulator's source code.
+Not .info files, not documentation, not community wikis - the actual code that loads the file.
+305 emulators profiled from source, 8 platforms cross-referenced,
+6,733 files verified.
+
+### How it works
+
+1. **Profile emulators from source code** - read the code, document every file loaded, its hash, size, and validation
+2. **Cross-reference with platforms** - each platform (RetroArch, Batocera, Recalbox...) declares what it needs
+3. **Build packs** - for each platform, include the baseline files + what its cores actually require
+4. **Verify everything** - platform-native verification (MD5, existence) + emulator-level validation (CRC32, SHA256, size)
+
+When a platform and an emulator disagree on a file, we detect it. When a better variant exists in the repo, we use it.
+
+> **6,733** files | **5043.6 MB** | **8** platforms | **305** emulator profiles
 
 ## Download
 
@@ -23,12 +37,12 @@ Complete, verified collection of BIOS, firmware, and system files for retrogamin
 |----------|----------|----------|----------|---------|
 | Batocera | 359/359 (100.0%) | 358 | 1 | 0 |
 | EmuDeck | 161/161 (100.0%) | 161 | 0 | 0 |
-| Lakka | 448/448 (100.0%) | 448 | 0 | 0 |
+| Lakka | 448/448 (100.0%) | 440 | 8 | 0 |
-| Recalbox | 346/346 (100.0%) | 346 | 0 | 0 |
+| Recalbox | 346/346 (100.0%) | 341 | 5 | 0 |
-| RetroArch | 448/448 (100.0%) | 448 | 0 | 0 |
+| RetroArch | 448/448 (100.0%) | 440 | 8 | 0 |
-| RetroBat | 331/331 (100.0%) | 331 | 0 | 0 |
+| RetroBat | 331/331 (100.0%) | 330 | 1 | 0 |
-| RetroDECK | 2007/2007 (100.0%) | 1698 | 309 | 0 |
+| RetroDECK | 2007/2007 (100.0%) | 2001 | 6 | 0 |
-| RetroPie | 448/448 (100.0%) | 448 | 0 | 0 |
+| RetroPie | 448/448 (100.0%) | 440 | 8 | 0 |
 
 ## Documentation
 
@@ -47,4 +61,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 This repository provides BIOS files for personal backup and archival purposes.
 
-*Auto-generated on 2026-03-20T19:10:25Z*
+*Auto-generated on 2026-03-25T13:49:31Z*

scripts/generate_readme.py

@@ -97,11 +97,25 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
     ) if Path("emulators").exists() else 0
 
     lines = [
-        "# Retrogaming BIOS & Firmware Collection",
+        "# RetroBIOS",
         "",
-        "Complete, verified collection of BIOS, firmware, and system files for retrogaming emulators.",
+        "Source-verified BIOS and firmware packs for retrogaming platforms.",
         "",
-        f"> **{total_files}** files | **{size_mb:.1f} MB** | **{len(coverages)}** platforms | **{emulator_count}** emulator profiles",
+        "Every file in this collection is traced to its ground truth: the emulator's source code.",
+        "Not .info files, not documentation, not community wikis - the actual code that loads the file.",
+        f"{emulator_count} emulators profiled from source, {len(coverages)} platforms cross-referenced,",
+        f"{total_files:,} files verified.",
+        "",
+        "### How it works",
+        "",
+        "1. **Profile emulators from source code** - read the code, document every file loaded, its hash, size, and validation",
+        "2. **Cross-reference with platforms** - each platform (RetroArch, Batocera, Recalbox...) declares what it needs",
+        "3. **Build packs** - for each platform, include the baseline files + what its cores actually require",
+        "4. **Verify everything** - platform-native verification (MD5, existence) + emulator-level validation (CRC32, SHA256, size)",
+        "",
+        "When a platform and an emulator disagree on a file, we detect it. When a better variant exists in the repo, we use it.",
+        "",
+        f"> **{total_files:,}** files | **{size_mb:.1f} MB** | **{len(coverages)}** platforms | **{emulator_count}** emulator profiles",
         "",
         "## Download",
         "",

scripts/generate_site.py

@@ -215,13 +215,29 @@ def generate_home(db: dict, coverages: dict, profiles: dict,
     lines = [
         f"# {SITE_NAME}",
         "",
-        "Complete BIOS and firmware collection for retrogaming emulators.",
+        "Source-verified BIOS and firmware packs for retrogaming platforms.",
         "",
         "---",
         "",
+        "## Methodology",
+        "",
+        "Every file in this collection is traced to its **ground truth**: the emulator's source code.",
+        "",
+        "Three levels of truth, in order of authority:",
+        "",
+        "1. **Upstream emulator source** - the original project (Dolphin, PCSX2, Mednafen...)",
+        "2. **Libretro core source** - the RetroArch port, which may diverge (different paths, added/removed files)",
+        "3. **`.info` declarations** - metadata files that can be wrong or outdated",
+        "",
+        f"**{emulator_count}** emulators profiled from source code. "
+        f"Each profile documents what the code loads, what it validates, "
+        f"and where the upstream diverges from the port.",
+        "",
         f"**{total_files:,}** files | **{len(coverages)}** platforms | "
         f"**{emulator_count}** emulator profiles | **{_fmt_size(total_size)}** total",
         "",
+        "---",
+        "",
     ]
 
     # Platform table
@@ -595,7 +611,7 @@ def generate_emulator_page(name: str, profile: dict, db: dict,
     based_on = profile.get("based_on", "")
     if based_on:
         lines.append(f"| Based on | {based_on} |")
-    # Additional metadata fields (scalar values only — complex ones go to collapsible sections)
+    # Additional metadata fields (scalar values only -complex ones go to collapsible sections)
     for field, label in [
         ("core", "Core ID"), ("core_name", "Core name"),
         ("bios_size", "BIOS size"), ("bios_directory", "BIOS directory"),
@@ -784,7 +800,7 @@ def generate_emulator_page(name: str, profile: dict, db: dict,
             if not in_repo:
                 badges.append("missing from repo")
 
-            lines.append(f"**`{fname}`** — {', '.join(badges)}")
+            lines.append(f"**`{fname}`** -{', '.join(badges)}")
             if desc:
                 lines.append(f": {desc}")
             lines.append("")
@@ -873,7 +889,7 @@ def generate_emulator_page(name: str, profile: dict, db: dict,
                             parts.append(cdesc)
                         if csize:
                             parts.append(_fmt_size(csize))
-                        lines.append(f"    - {' — '.join(parts)}")
+                        lines.append(f"    - {' -'.join(parts)}")
                     else:
                         lines.append(f"    - {c}")
                 if len(contents) > 10:
@@ -886,7 +902,7 @@ def generate_emulator_page(name: str, profile: dict, db: dict,
         for dd in data_dirs:
             ref = dd.get("ref", "")
             dest = dd.get("destination", "")
-            lines.append(f"- `{ref}` → `{dest}`")
+            lines.append(f"- `{ref}` >`{dest}`")
         lines.append("")
 
     lines.extend([f"*Generated on {_timestamp()}*"])
@@ -1027,7 +1043,7 @@ def generate_cross_reference(
     lines = [
         f"# Cross-reference - {SITE_NAME}",
         "",
-        "Platform → Core → Systems → Upstream emulator.",
+        "Platform >Core >Systems >Upstream emulator.",
         "",
         "The libretro core is a port of the upstream emulator. "
         "Files, features, and validation may differ between the two.",