From 6bca75b23ec7bf5df245317762e84e5343312203 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Wed, 21 Oct 2026 09:59:22 +0200
Subject: [PATCH] docs: name the registry keys the tools read

---
 tests/test_doc_pages.py   | 24 ++++++++++++++++++++++++
 wiki/adding-a-platform.md | 29 +++++++++++++++++++++++++----
 2 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py
index e2414d26..57a285f1 100644
--- a/tests/test_doc_pages.py
+++ b/tests/test_doc_pages.py
@@ -535,5 +535,29 @@ class ShortMd5Handling(unittest.TestCase):
         self.assertIn("_resolve_truncated_md5", section)
 
 
+class RegistryKeysDocumented(unittest.TestCase):
+    """zip_digest, firmware_folder_flat and extract_to were read from the
+    registry by the resolver, the pack and the README, and the page that
+    adds a platform named none of them while saying runtime behaviour lives
+    in the platform YAML only."""
+
+    def test_every_registry_key_is_on_the_page(self):
+        import yaml
+
+        registry = yaml.safe_load((ROOT / "platforms" / "_registry.yml").read_text(encoding="utf-8"))
+        keys = {key for entry in registry["platforms"].values() for key in entry}
+        page = _page("adding-a-platform.md")
+        self.assertEqual(sorted(k for k in keys if not re.search(rf"\b{k}\b", page)), [])
+
+    def test_the_page_says_the_registry_reaches_the_config(self):
+        import common
+
+        source = inspect.getsource(common.load_platform_config)
+        self.assertIn("config[key] = val", source)
+        section = _section(_page("adding-a-platform.md"), "Step 2: Register the platform")
+        self.assertIn("copies every registry key", section)
+        self.assertNotIn("belongs to the platform\nYAML", section)
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/wiki/adding-a-platform.md b/wiki/adding-a-platform.md
index 2cf0cd9a..166bac8f 100644
--- a/wiki/adding-a-platform.md
+++ b/wiki/adding-a-platform.md
@@ -131,10 +131,13 @@ This fetches from upstream and prints a summary without writing anything.
 
 Add an entry to `platforms/_registry.yml` under the `platforms:` key.
 
-The registry describes *where the data comes from*. How the platform behaves
-at runtime (`verification_mode`, `base_destination`) belongs to the platform
-YAML, because that is what `verify.py` and `generate_pack.py` load. Keeping the
-two apart means a re-scrape can rewrite the YAML without touching the registry.
+The registry describes *where the data comes from*, and the platform YAML
+holds what the upstream file declares, `verification_mode` and
+`base_destination` included. A re-scrape rewrites the YAML without touching the
+registry. `load_platform_config` copies every registry key the YAML does not
+carry into the config that `verify.py` and `generate_pack.py` read, so a runtime
+rule that no upstream file states (`zip_digest`, `firmware_folder_flat`) is
+written in the registry, where the next scrape leaves it in place.
 
 ### Required fields
 
@@ -190,6 +193,11 @@ its libretro layout whatever the platform calls it.
     logo: https://...                # SVG or PNG for UI/docs
     inherits_from: retroarch         # inherit systems/cores from another platform
     case_insensitive_fs: true        # if the platform runs on case-insensitive filesystems
+    extract_to: /userdata/bios/      # folder the pack extracts into, shown in the README,
+                                     # the site and the release notes
+    zip_digest: composite            # the frontend hashes a .zip by its members only
+    firmware_folder_flat: true       # the frontend lists each system folder without
+                                     # descending into it
     source_wiki: https://...         # human-readable upstream reference
     target_scraper: myplatform_targets  # hardware target scraper name, null if static
     target_source: https://...       # target data source URL
@@ -205,6 +213,19 @@ its libretro layout whatever the platform calls it.
         parse_key: bios_directory
 ```
 
+`zip_digest: composite` is set where the frontend's own check takes
+`Zip::Md5Composite` for every `.zip` and never the container's MD5 (Recalbox,
+`Bios.cpp:64-68`). Each `.zip` entry is then checked against its composite alone,
+by the resolver and by the pack check, as
+[verification modes](verification-modes.md#md5_composite-recalbox-zip-verification)
+describes.
+
+`firmware_folder_flat: true` is set where the frontend reads a system's firmware
+folder without descending into it (RomM 5.4.0,
+`backend/handler/filesystem/base_handler.py:1002`, `recursive=False`). On such a platform, a core file whose destination has a
+subfolder is left out of the pack (`nested` in `scripts/packextras.py`), since no
+core would receive it.
+
 ### Platform YAML header
 
 The runtime behavior lives at the top of `platforms/myplatform.yml`: