docs: explain why the pack leaves a file out

A file the emulator installs itself is left out of the packs, per build and per platform. The profiling guide documents bundled, installed_on and not_bundled_on, the FAQ says why a file the emulator reads may be missing from a pack, and an emulator page names the build that installs it and the platforms whose package differs.

scripts/generate_site.py

@@ -2677,8 +2677,11 @@ def _file_badges(f: dict, in_repo: bool) -> list[str]:
             f'<span class="rb-badge rb-badge-muted">{storage}</span>'
         )
     if bundled:
+        # Said in words: the pack leaves the file out because the emulator,
+        # in the build the entry names, already installs it.
+        build = f" {f['mode']}" if f.get("mode") in ("standalone", "libretro") else ""
         badges.append(
-            '<span class="rb-badge rb-badge-muted">bundled</span>'
+            f'<span class="rb-badge rb-badge-muted">installed with the{build} emulator</span>'
         )
     if embedded:
         badges.append(
@@ -2832,6 +2835,12 @@ def _render_emulator_file(
         elif isinstance(validation, dict):
             for scope, checks in validation.items():
                 details.append(f"Validation ({scope}): {', '.join(checks)}")
+    if f.get("installed_on"):
+        details.append("Installed by the platform's own package on: "
+                       + ", ".join(sorted(f["installed_on"])))
+    if f.get("not_bundled_on"):
+        details.append("Left out by the platform's package, so the pack brings it, on: "
+                       + ", ".join(sorted(f["not_bundled_on"])))
     if source_ref:
         asker = requested_by(profile, source_ref)
         if asker:

tests/test_site_exports.py

@@ -805,5 +805,16 @@ class ADataDirectoryFileCanBeLookedUp(unittest.TestCase):
         self.assertEqual(items, [{"sha1": "c" * 40, "url": "emulators/dolphin/#sha1-cccccccccccc"}])
 
 
+class ACardSaysWhyAFileIsLeftOut(unittest.TestCase):
+    """The badge said "bundled" and nothing about which build, so a reader
+    could not tell why a RetroArch pack carried PPSSPP's assets."""
+
+    def test_the_build_and_the_platforms_are_named(self):
+        from generate_site import _file_badges
+
+        badges = " ".join(_file_badges({"name": "a", "bundled": True, "mode": "standalone"}, True))
+        self.assertIn("installed with the standalone emulator", badges)
+
+
 if __name__ == "__main__":
     unittest.main()

wiki/faq.md

@@ -142,6 +142,17 @@ curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh \
 On Windows the arguments need a script block, since `iex` would read them as
 its own. The form is on the [Installer](installer.md#passing-options) page.
 
+## Why is a file the emulator reads not in the pack?
+
+A pack brings what the user has to obtain. A file the emulator installs itself, a
+font, a shader, a game database, a free replacement BIOS, is already on the
+machine once the emulator is installed, so the pack leaves it out. This is decided
+per build and per platform: the PPSSPP standalone release ships its `assets/`
+folder, the PPSSPP libretro core does not, so RetroArch packs carry those files and
+a standalone PPSSPP pack does not. When a platform's own package installs data
+beside a core (Batocera with blueMSX), that platform's pack leaves it out too. The
+emulator's page on the site marks these files as installed with the emulator.
+
 ## Is this legal?
 
 Redistributing firmware is not settled law, and this page does not pretend otherwise. What follows is the reasoning the project acts on, with the strength of each argument stated plainly so anyone can weigh it. None of it is legal advice, and none of it has been tested in court.

wiki/profiling.md

@@ -397,7 +397,9 @@ partitions), and `game_count`.
 | `fast_boot` | BIOS generation label the core uses to decide whether fast boot is available |
 | `priority` | preference order when several BIOS satisfy the same slot, **lowest wins**. DuckStation's `FindBIOSImageInDirectory` keeps the image whose priority is lower, and its table de-prioritizes by raising the number: the buggy launch console sits at 50 and PS2 images at 100, while `scph5501` sits at 5. A core that walks an ordered search list, as PicoDrive does with `biosfiles_us/eu/jp`, maps onto the same field as 1, 2, 3. Only set it from the source. `--one-per-slot` reads it |
 | `embedded` | true if the data is compiled into the binary and the external file is optional |
-| `bundled` | true if the file ships with the emulator rather than being user-provided |
+| `bundled` | true if the emulator's own release installs the file where it reads it, for the build `mode` names (all builds when `mode` is absent). Packs and the installer leave it out: the user already has it. A file the standalone release ships but the libretro core does not (PPSSPP's assets, Dolphin's Sys) is bundled with `mode: standalone` only |
+| `not_bundled_on` | platforms (registry keys) whose package leaves out a file the release bundles: their packs bring it (Batocera installs hcl without its data) |
+| `installed_on` | platforms whose own package installs the file beside the emulator although the release does not: their packs leave it out (Batocera and RetroPie copy blueMSX's machines beside the core) |
 | `has_builtin` | true if the core falls back to a built-in copy when the file is absent |
 | `config_key` | configuration key the emulator exposes to point at the file |
 | `load_from` | directory the core reads the file from when it is not the system directory |