docs: publish divergence table and license scope

README.md

@@ -81,6 +81,9 @@ Full list with per-file details: **[https://abdess.github.io/retrobios/](https:/
 | RetroPie | 530/530 (100.0%) | 530 | 0 | 0 |
 | RomM | 374/374 (100.0%) | 374 | 0 | 0 |
 
+Coverage is measured against the file list each platform declares, using that platform's own verification mode.
+Where platform lists and emulator source code disagree, the differences are tracked in the [gap analysis](https://abdess.github.io/retrobios/gaps/).
+
 ## Build your own pack
 
 Clone the repo and generate packs for any platform, emulator, or system:
@@ -146,6 +149,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-This repository provides BIOS files for personal backup and archival purposes.
+The scripts and tooling are released under the [MIT License](LICENSE).
+The BIOS and firmware files are not covered by that license: they are third-party system software, preserved and provided for personal backup, archival, and interoperability with emulation software.
+The legal reasoning is laid out in the [FAQ](https://abdess.github.io/retrobios/wiki/faq/#is-this-legal).
 
-*Auto-generated on 2026-08-07T12:31:35Z*
+*Auto-generated on 2026-08-07T13:24:31Z*

scripts/generate_readme.py

@@ -275,6 +275,11 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
 
     lines.extend(
         [
+            "",
+            "Coverage is measured against the file list each platform declares,"
+            " using that platform's own verification mode.",
+            "Where platform lists and emulator source code disagree, the"
+            f" differences are tracked in the [gap analysis]({SITE_URL}gaps/).",
             "",
             "## Build your own pack",
             "",
@@ -358,7 +363,11 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
             "",
             "## License",
             "",
-            "This repository provides BIOS files for personal backup and archival purposes.",
+            "The scripts and tooling are released under the [MIT License](LICENSE).",
+            "The BIOS and firmware files are not covered by that license: they are"
+            " third-party system software, preserved and provided for personal"
+            " backup, archival, and interoperability with emulation software.",
+            f"The legal reasoning is laid out in the [FAQ]({SITE_URL}wiki/faq/#is-this-legal).",
             "",
             f"*Auto-generated on {ts}*",
         ]

scripts/generate_site.py

@@ -1435,6 +1435,7 @@ def generate_gap_analysis(
     coverages: dict,
     db: dict,
     data_names: set[str] | None = None,
+    registry: dict | None = None,
 ) -> str:
     """Generate a unified gap analysis page.
 
@@ -1545,7 +1546,55 @@ def generate_gap_analysis(
             f"| {missing_str} "
             f"| {cov['mode']} |"
         )
-    lines.append("")
+    lines.extend([
+        "",
+        "Verification follows each platform's own runtime check "
+        "([how each mode works](wiki/verification-modes.md)): the counts "
+        "measure the repository against the file list each platform declares.",
+        "",
+    ])
+
+    # ---- Section 1b: platform lists vs emulator source ----
+
+    from truth import diff_platform_truth, generate_platform_truth
+
+    div_rows = []
+    for pname, cov in sorted(coverages.items(), key=lambda x: x[1]["platform"]):
+        truth_data = generate_platform_truth(
+            pname, cov["config"], (registry or {}).get(pname, {}), profiles, db
+        )
+        s = diff_platform_truth(truth_data, cov["config"])["summary"]
+        div_rows.append(
+            f"| [{cov['platform']}](platforms/{pname}.md) "
+            f"| {s['total_missing']} "
+            f"| {s['total_extra_phantom'] + s['total_extra_unprofiled']} "
+            f"| {s['total_hash_mismatch']} "
+            f"| {s['total_required_mismatch']} |"
+        )
+
+    lines.extend([
+        "## Platform Lists vs Emulator Source",
+        "",
+        "Platform file lists are scraped as-is from each upstream project. "
+        "Emulator profiles are read from source code. The two do not always "
+        "agree, and this table counts the differences. Packs follow the "
+        "platform contract; these numbers show where that contract diverges "
+        "from what the code loads.",
+        "",
+        "| Platform | Missing from list | Phantom | Hash conflict | Required status |",
+        "|----------|------------------:|--------:|--------------:|----------------:|",
+        *div_rows,
+        "",
+        "- **Missing from list**: a profiled emulator loads the file, the platform list does not mention it",
+        "- **Phantom**: on the platform list, loaded by no profiled emulator",
+        "- **Hash conflict**: the platform list and the emulator source expect different hashes",
+        "- **Required status**: required/optional differs between list and code",
+        "",
+        "The same comparison drives `scripts/exporter/`: each platform's "
+        "corrected list can be regenerated in its native format "
+        "(System.dat, es_bios.xml, batocera-systems.json, ...).",
+        "",
+    ])
 
     # ---- Section 2: Problem files ----
 
@@ -2538,7 +2587,7 @@ def main():
     print("Generating gap analysis page...")
     write_if_changed(
         str(docs / "gaps.md"),
-        generate_gap_analysis(profiles, coverages, db, suppl_names),
+        generate_gap_analysis(profiles, coverages, db, suppl_names, registry),
     )
 
     # Wiki pages: copy manually maintained sources + generate dynamic ones