From c1a018f20ddf4a09531ac3ef69741c9f3c7e0c98 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Tue, 10 Nov 2026 03:30:55 +0100
Subject: [PATCH] docs: state core resolution as the code reads it

The rule's strategies moved from resolve_platform_cores to
_platform_profiles, and the test read the old function. It now reads
both. The page named ROCKNIX among the lists naming retroarch, which
it no longer does since its list names the libretro cores it
installs, and said nothing of installable_cores: a downloadable core
designates libretro builds and counts under --target only on the
boards whose downloader offers it.
---
 tests/test_doc_pages.py   | 14 +++++++++++---
 wiki/adding-a-platform.md | 15 +++++++++------
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py
index 0b58a1f26..ef9c65877 100644
--- a/tests/test_doc_pages.py
+++ b/tests/test_doc_pages.py
@@ -491,9 +491,13 @@ class CoreResolutionWrittenOnce(unittest.TestCase):
         import common
 
         self.assertNotIn("cores: [list]", _page("architecture.md"))
-        source = inspect.getsource(common.resolve_platform_cores)
+        # resolve_platform_cores narrows by target, _platform_profiles holds
+        # the strategies.
+        source = inspect.getsource(common._platform_profiles)
         self.assertIn('not p.get("built_by")', source)
         self.assertIn('"retroarch" in core_set', source)
+        self.assertIn('config.get("installable_cores")', source)
+        self.assertIn("downloadable_on", inspect.getsource(common.resolve_platform_cores))
         naming = set()
         for path in (ROOT / "platforms").glob("*.yml"):
             config = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
@@ -504,10 +508,14 @@ class CoreResolutionWrittenOnce(unittest.TestCase):
         bullet = next(p for p in section.split("\n- ") if p.startswith("**Explicit list**"))
         used_by = re.search(r"Used by ([^.]+)\.", bullet.replace("\n", " ")).group(1)
         names = [n.strip().lower() for n in used_by.split(",")]
-        self.assertIn("the last\n  four", bullet)
-        self.assertEqual(set(names[-4:]), naming)
+        words = {2: "two", 3: "three", 4: "four", 5: "five"}
+        counted = re.search(r"\(the last\s+(\w+)\)", bullet).group(1)
+        self.assertEqual(counted, words[len(naming)])
+        self.assertEqual(set(names[-len(naming):]), naming)
         libretro = next(p for p in section.split("\n- ") if p.startswith("**all_libretro**"))
         self.assertIn("built_by", libretro)
+        for name in ("installable_cores", "downloadable_on", "downloaded_cores"):
+            self.assertIn(f"`{name}`", bullet)
 
 
 class ExitStatusTable(unittest.TestCase):
diff --git a/wiki/adding-a-platform.md b/wiki/adding-a-platform.md
index 3ca46cac4..1154990e3 100644
--- a/wiki/adding-a-platform.md
+++ b/wiki/adding-a-platform.md
@@ -195,12 +195,15 @@ resolved. Three strategies exist:
 
 - **Explicit list**: `cores: [beetle_psx, dolphin, ...]` - match by profile key name
   or by any name in a profile's `cores:`. When a profile's `built_by` names this
-  platform, that profile answers for the name. Used by Batocera, Recalbox, RetroBat,
-  RomM, KNULLI, AmberELEC, EmuELEC, MinUI, NextUI, MyMinUI, RetroPie, EmuDeck,
-  RetroDECK, ROCKNIX. A list that names `retroarch` (the last
-  four) also takes every libretro profile, as `all_libretro` does, plus the
-  libretro builds whose `built_by` names this platform (ROCKNIX's
-  `yabadabadoo`). An empty list
+  platform, that profile answers for the name (ROCKNIX's `yabadabadoo`). Used by
+  Batocera, Recalbox, RetroBat, RomM, KNULLI, AmberELEC, EmuELEC, MinUI, NextUI,
+  MyMinUI, ROCKNIX, RetroPie, EmuDeck, RetroDECK. A list that names `retroarch`
+  (the last three) also takes every libretro profile, as `all_libretro` does,
+  plus the libretro builds whose `built_by` names this platform. A name in `installable_cores`, a buildbot core the
+  platform's RetroArch downloads, designates libretro builds only. Under
+  `--target` such a core counts only on the boards whose downloader offers one
+  of its names (`downloadable_on`), and the install list gives those boards in
+  `downloaded_cores`. An empty list
   (BizHawk, MiSTer FPGA) resolves no profile, and the pack holds the platform's own
   files.
 - **all_libretro**: `cores: all_libretro` - every profile whose `type` contains