From 236d8322b0201a029bbd6f6a5315dce526ff8c7e Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Tue, 6 Oct 2026 01:33:33 +0200
Subject: [PATCH] fix: point pack guides at the path each platform reads

---
 scripts/generate_pack.py  |  6 +++++
 scripts/packreadme.py     | 16 ++++++++++---
 tests/test_pack_readme.py | 50 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_pack_readme.py

diff --git a/scripts/generate_pack.py b/scripts/generate_pack.py
index 2ad95233..5c00c398 100644
--- a/scripts/generate_pack.py
+++ b/scripts/generate_pack.py
@@ -1110,6 +1110,12 @@ def generate_pack(
           undecidable_slots=slot_undecidable,
           narrowings=narrowings,
           system_filter=system_filter,
+          bios_paths=[
+              str(detect.get("bios_path", ""))
+              for detect in (
+                  _pack_registry.get(platform_name, {}).get("install", {}) or {}
+              ).get("detect", [])
+          ],
       )
       _write_generated_member(zf, "README.txt", readme_text)
 
diff --git a/scripts/packreadme.py b/scripts/packreadme.py
index f5ad8c08..012ea705 100644
--- a/scripts/packreadme.py
+++ b/scripts/packreadme.py
@@ -19,6 +19,7 @@ def _build_readme(
     undecidable_slots: list[str] | None = None,
     narrowings: list[tuple[str, str]] | None = None,
     system_filter: list[str] | None = None,
+    bios_paths: list[str] | None = None,
 ) -> str:
     """Build a personalized step-by-step README for each platform pack."""
     narrowings = narrowings or []
@@ -128,8 +129,9 @@ def _build_readme(
             "  ----------------\n"
             "  1. Open Dolphin file manager\n"
             "  2. Show hidden files (Ctrl+H)\n"
-            "  3. Navigate to ~/retrodeck/bios/\n"
-            "  4. Extract all files from this archive directly into ~/retrodeck/bios/\n\n"
+            "  3. Navigate to ~/retrodeck/\n"
+            "  4. Extract all files from this archive directly into ~/retrodeck/\n"
+            "     (the archive already holds the bios/ and roms/ folders)\n\n"
             "  NOTE: RetroDECK uses its own BIOS checker. After\n"
             "  copying, open RetroDECK > Tools > BIOS Checker to\n"
             "  verify everything is detected.\n\n"
@@ -186,11 +188,19 @@ def _build_readme(
     # Lakka uses same guide as RetroArch
     guides["lakka"] = guides["retroarch"]
 
+    # A platform without a written guide is told where its files go by the
+    # registry, which the installer reads too: "your BIOS directory" sent
+    # MiSTer users looking for a folder MiSTer does not have.
+    targets = [path for path in bios_paths or [] if path]
+    where = (
+        " or ".join(f"{path}/" for path in targets)
+        if targets else "your BIOS directory"
+    )
     guide = guides.get(
         platform_name,
         (
             f"INSTALLATION\n\n"
-            f"  1. Extract all files from this archive directly into your BIOS directory\n"
+            f"  1. Extract all files from this archive directly into {where}\n"
             f"  2. Overwrite if asked\n\n"
         ),
     )
diff --git a/tests/test_pack_readme.py b/tests/test_pack_readme.py
new file mode 100644
index 00000000..f8313b70
--- /dev/null
+++ b/tests/test_pack_readme.py
@@ -0,0 +1,50 @@
+"""The README inside a pack sends files where the platform reads them.
+
+RetroDECK's pack holds bios/ and roms/ at its root, and its guide said to
+extract into ~/retrodeck/bios/, giving ~/retrodeck/bios/bios/. MiSTer and
+ROCKNIX had no guide and were told "your BIOS directory", a folder MiSTer
+does not have, while the registry names the path.
+"""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from packreadme import _build_readme  # noqa: E402
+
+
+def _extract_lines(text: str) -> list[str]:
+    return [line for line in text.splitlines() if "Extract all files" in line]
+
+
+class GuidesPointAtTheReadPath(unittest.TestCase):
+    def test_retrodeck_is_extracted_at_its_root(self):
+        text = _build_readme("retrodeck", "RetroDECK", "", 1, 1)
+        for line in _extract_lines(text):
+            self.assertNotIn("retrodeck/bios", line)
+
+    def test_unguided_platforms_name_the_registry_path(self):
+        registry = yaml.safe_load((REPO_ROOT / "platforms" / "_registry.yml").read_text())
+        for name, data in registry["platforms"].items():
+            paths = [
+                str(d.get("bios_path", ""))
+                for d in (data.get("install", {}) or {}).get("detect", [])
+            ]
+            if not any(paths):
+                continue
+            text = _build_readme(name, name, "", 1, 1, bios_paths=paths)
+            with self.subTest(platform=name):
+                self.assertFalse(
+                    any("your BIOS directory" in line for line in _extract_lines(text))
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()