From 329fcc0f6297df851e56d2ae6aae5f8bd8f3caa0 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Thu, 5 Nov 2026 11:52:23 +0100
Subject: [PATCH] docs: name the installer cache and its variable

---
 tests/test_doc_pages.py | 22 ++++++++++++++++++++++
 wiki/faq.md             |  3 ++-
 wiki/installer.md       |  6 +++++-
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py
index 1a36ca46b..0d4510e12 100644
--- a/tests/test_doc_pages.py
+++ b/tests/test_doc_pages.py
@@ -1678,5 +1678,27 @@ class InstallerPagesFollowTheCode(unittest.TestCase):
         self.assertEqual(len(unserved_one_liners("installer.md", old)), 2)
 
 
+class InstallerVariablesAreDocumented(unittest.TestCase):
+    """RETROBIOS_CACHE moved a cache that --for-games writes, even under
+    --dry-run, and no page named it or the folder it defaults to."""
+
+    # Set by the full-screen interface for the runs it starts, never by a user.
+    INTERNAL = {"RETROBIOS_TUI_LIST"}
+
+    def test_every_variable_install_py_reads_is_in_the_table(self):
+        source = (ROOT / "install.py").read_text(encoding="utf-8")
+        page = (WIKI / "installer.md").read_text(encoding="utf-8")
+        table = page[page.index("## Environment overrides"):]
+        table = table[:table.index("\n## ", 1)]
+        for name in sorted(set(re.findall(r'"(RETROBIOS_[A-Z_]+)"', source)) - self.INTERNAL):
+            with self.subTest(variable=name):
+                self.assertIn(f"`{name}`", table)
+
+    def test_the_faq_names_the_cache(self):
+        faq = (WIKI / "faq.md").read_text(encoding="utf-8")
+        section = faq[faq.index("## Is the command safe?"):]
+        self.assertIn("cache", section[:section.index("\n## ", 1)])
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/wiki/faq.md b/wiki/faq.md
index c199069a7..58646b11b 100644
--- a/wiki/faq.md
+++ b/wiki/faq.md
@@ -57,7 +57,8 @@ Game sets must match the emulator's version:
 
 - It stops if the installer does not match its expected fingerprint, and
   checks each file.
-- It writes in your BIOS folder, and some emulators' save folder.
+- It writes in your BIOS folder, some emulators' save folder, and a cache
+  of what it read about your games.
 - It never touches games or saves.
 - It keeps each file it replaces in `retrobios-backup`, for `--restore`.
 
diff --git a/wiki/installer.md b/wiki/installer.md
index b5c6b183e..fd2536c22 100644
--- a/wiki/installer.md
+++ b/wiki/installer.md
@@ -865,7 +865,9 @@ it. So does an arcade set the core does not know. **Only what starts**
 (`--required-only`) leaves out the files the cores mark optional.
 
 The games are read without hashing whole discs, and a cache keeps what was
-read, so a second run over the same card reads only new files. Offline, with
+read, so a second run over the same card reads only new files. It is a
+`retrobios` folder in the system's cache folder (`RETROBIOS_CACHE`, see
+[Environment overrides](#environment-overrides)), written by `--dry-run` too. Offline, with
 no games index on this machine, the run keeps every file and says so.
 
 ### Firmware without game data
@@ -1826,6 +1828,8 @@ RetroArch folder that holds only `scph5501.bin`, in the order written:
 | `RETROBIOS_PAD` | The buttons a handheld launcher's mapper sends to the full screen (`gptokeyb`, `gptokeyb_muxterm`, `muxterm`, `evmapy`, `miyoo`), so its hints name them. See [On a handheld](#on-a-handheld-the-retrobios-port) |
 | `RETROBIOS_IDLE_EXIT` | Seconds the full screen waits for a first button, counted while nothing runs. With none pressed, it closes with exit status 2, as a quit, or with the code of the error or result screen it closed on |
 | `RETROBIOS_NO_MOUSE` | Set to any value but `0` or an empty one: the full screen never asks the terminal for clicks, and the mouse selects text everywhere as it does outside the installer |
+| `RETROBIOS_CACHE` | The folder that keeps the games index and what a run read of the games, for the next run. Defaults to `retrobios` in `$XDG_CACHE_HOME` (else `~/.cache`), `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows. Deleting it loses nothing |
+| `RETROBIOS_DEBUG` | Set to anything: says why the games index could not be fetched or a cache file not written |
 | `HTTPS_PROXY`, `NO_PROXY` | Honoured for every download through the standard library's default proxy handling: one names the proxy, the other the hosts to reach directly |
 
 ## When something goes wrong