docs: soften tone, explain methodology without dismissing other sources

README.md

@@ -2,19 +2,21 @@
 
 Source-verified BIOS and firmware packs for retrogaming platforms.
 
-Every file in this collection is traced to its ground truth: the emulator's source code.
+Documentation and metadata can drift from what emulators actually load at runtime.
-Not .info files, not documentation, not community wikis - the actual code that loads the file.
+To keep packs accurate, each file here is checked against the emulator's source code:
-305 emulators profiled from source, 8 platforms cross-referenced,
+what the code opens, what hashes it expects, what happens when a file is missing.
+305 emulators profiled, 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
+1. **Read emulator source code** - identify every file the code loads, its expected hash and size
-2. **Cross-reference with platforms** - each platform (RetroArch, Batocera, Recalbox...) declares what it needs
+2. **Cross-reference with platforms** - match against what RetroArch, Batocera, Recalbox and others declare
-3. **Build packs** - for each platform, include the baseline files + what its cores actually require
+3. **Build packs** - for each platform, include its baseline files plus what its cores need
-4. **Verify everything** - platform-native verification (MD5, existence) + emulator-level validation (CRC32, SHA256, size)
+4. **Verify** - run each platform's native checks (MD5, existence) and emulator-level validation (CRC32, 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.
+When a platform and an emulator disagree on a file, the discrepancy is reported.
+When a variant in the repo satisfies both, it is preferred automatically.
 
 > **6,733** files | **5043.6 MB** | **8** platforms | **305** emulator profiles
 
@@ -61,4 +63,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 This repository provides BIOS files for personal backup and archival purposes.
 
-*Auto-generated on 2026-03-25T13:49:31Z*
+*Auto-generated on 2026-03-25T13:51:15Z*

scripts/generate_readme.py

@@ -101,19 +101,21 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "",
         "Source-verified BIOS and firmware packs for retrogaming platforms.",
         "",
-        "Every file in this collection is traced to its ground truth: the emulator's source code.",
+        "Documentation and metadata can drift from what emulators actually load at runtime.",
-        "Not .info files, not documentation, not community wikis - the actual code that loads the file.",
+        "To keep packs accurate, each file here is checked against the emulator's source code:",
-        f"{emulator_count} emulators profiled from source, {len(coverages)} platforms cross-referenced,",
+        "what the code opens, what hashes it expects, what happens when a file is missing.",
+        f"{emulator_count} emulators profiled, {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",
+        "1. **Read emulator source code** - identify every file the code loads, its expected hash and size",
-        "2. **Cross-reference with platforms** - each platform (RetroArch, Batocera, Recalbox...) declares what it needs",
+        "2. **Cross-reference with platforms** - match against what RetroArch, Batocera, Recalbox and others declare",
-        "3. **Build packs** - for each platform, include the baseline files + what its cores actually require",
+        "3. **Build packs** - for each platform, include its baseline files plus what its cores need",
-        "4. **Verify everything** - platform-native verification (MD5, existence) + emulator-level validation (CRC32, SHA256, size)",
+        "4. **Verify** - run each platform's native checks (MD5, existence) and emulator-level validation (CRC32, 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.",
+        "When a platform and an emulator disagree on a file, the discrepancy is reported.",
+        "When a variant in the repo satisfies both, it is preferred automatically.",
         "",
         f"> **{total_files:,}** files | **{size_mb:.1f} MB** | **{len(coverages)}** platforms | **{emulator_count}** emulator profiles",
         "",

scripts/generate_site.py

@@ -221,17 +221,19 @@ def generate_home(db: dict, coverages: dict, profiles: dict,
         "",
         "## Methodology",
         "",
-        "Every file in this collection is traced to its **ground truth**: the emulator's source code.",
+        "Documentation and metadata can drift from what emulators actually load at runtime.",
+        "To keep packs accurate, each file here is checked against the emulator's source code.",
         "",
-        "Three levels of truth, in order of authority:",
+        "The source code is the primary reference because it reflects actual behavior.",
+        "Other sources remain useful but are verified against it:",
         "",
-        "1. **Upstream emulator source** - the original project (Dolphin, PCSX2, Mednafen...)",
+        "1. **Upstream emulator source** - what the original project loads (Dolphin, PCSX2, Mednafen...)",
-        "2. **Libretro core source** - the RetroArch port, which may diverge (different paths, added/removed files)",
+        "2. **Libretro core source** - the RetroArch port, which may adapt paths or add files",
-        "3. **`.info` declarations** - metadata files that can be wrong or outdated",
+        "3. **`.info` declarations** - metadata that platforms rely on, checked for accuracy",
         "",
-        f"**{emulator_count}** emulators profiled from source code. "
+        f"**{emulator_count}** emulators profiled. "
         f"Each profile documents what the code loads, what it validates, "
-        f"and where the upstream diverges from the port.",
+        f"and where the port differs from the original.",
         "",
         f"**{total_files:,}** files | **{len(coverages)}** platforms | "
         f"**{emulator_count}** emulator profiles | **{_fmt_size(total_size)}** total",