From 0ffde1bc8f4d189f4629157135cf01b94a17edc4 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Wed, 21 Oct 2026 10:09:20 +0200
Subject: [PATCH] docs: first install shows the run as printed

The Batocera example is dated and carries the Not installable line and the closing list of files the collection does not hold, which every Batocera run prints. Disk sizes are no longer hand-kept: the run prints its size. The no-platform case describes the menu install.sh makes possible by handing over the terminal.
---
 tests/test_doc_pages.py | 58 +++++++++++++++++++++++++++++++++++
 wiki/first-install.md   | 67 ++++++++++++++++++++++++++++++-----------
 2 files changed, 108 insertions(+), 17 deletions(-)

diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py
index ff40b6cb..69f51f85 100644
--- a/tests/test_doc_pages.py
+++ b/tests/test_doc_pages.py
@@ -668,5 +668,63 @@ class PublishedNumbersShareOneFormat(unittest.TestCase):
         self.assertEqual(re.findall(r"\*\*\d{4,}\b[^*]*\*\*", readme), [])
 
 
+class FirstInstallWalkthrough(unittest.TestCase):
+    """First install showed a Batocera run of 12893 files with no omission
+    line and said any other ending meant work left undone, while every
+    Batocera run printed 399 files not installed. Its disk sizes (Batocera
+    4.0 GB) contradicted its own example (8.6 GB), and its no-platform case
+    said a piped command cannot ask, where install.sh hands it the terminal
+    and the installer shows a menu."""
+
+    def setUp(self):
+        self.text = _page("first-install.md")
+
+    def test_no_hand_kept_size_before_the_run(self):
+        import install
+
+        section = _section(self.text, "Before starting")
+        # The confirmation threshold is a constant of the installer, not a pack size.
+        self.assertEqual(install.CONFIRM_FROM_BYTES, 1024 ** 3)
+        self.assertIn("reaches 1 GB", section)
+        self.assertNotRegex(section.replace("reaches 1 GB", ""), r"\d+(\.\d+)? ?[KMG]B\b")
+
+    def test_the_run_is_dated_and_consistent_with_the_manifest(self):
+        import install
+
+        self.assertRegex(self.text, r"published on \d{4}-\d{2}-\d{2}")
+        step3 = _section(self.text, "Step 3. Let it work")
+        step4 = _section(self.text, "Step 4. Read the end of the run")
+        step5 = _section(self.text, "Step 5. Confirm it later")
+        count, size = re.search(r"\n  (\d+) files \(([\d.]+ [KMG]B)\)", step3).groups()
+        self.assertIn(f"0/{count} present", step3)
+        self.assertIn(f"Downloading {count} files ({size})", step3)
+        self.assertIn(f"Done. {count} files installed", step4)
+        self.assertIn(f"{count}/{count} present ({count} verified", step5)
+        manifest = json.loads((ROOT / "install" / "batocera.json").read_text(encoding="utf-8"))
+        omitted = re.search(r"Not installable: (\d+) files \((\d+) required", step3)
+        if manifest.get("omitted_files"):
+            self.assertIsNotNone(omitted, "the manifest omits files and the run shows no line for it")
+        if omitted:
+            total, required = map(int, omitted.groups())
+            first, needed = install._omission_lines(
+                total, [{"required": True, "dest": str(i)} for i in range(required)]
+            )[:2]
+            self.assertIn(first, step4)
+            self.assertIn(needed.split(":")[0], step4)
+            self.assertIn(f"all {required} belong", step4)
+            self.assertIn(f"other {total - required} are optional", step4)
+
+    def test_no_platform_detected_reads_like_the_installer(self):
+        source = (ROOT / "install.py").read_text(encoding="utf-8")
+        branch = source.split('print("  No supported platform detected.")', 1)[1][:400]
+        self.assertIn("if not interactive or listing:", branch)
+        self.assertIn("_prompt_manual_platform(os_type)", branch)
+        self.assertIn('"$INSTALLER" "$@" </dev/tty', (ROOT / "install.sh").read_text(encoding="utf-8"))
+        section = _section(self.text, "No supported platform detected.")
+        self.assertIn("a menu follows", section)
+        self.assertIn("--no-input", section)
+        self.assertNotIn("cannot stop and ask", section)
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/wiki/first-install.md b/wiki/first-install.md
index 71f39e5a..43905e6a 100644
--- a/wiki/first-install.md
+++ b/wiki/first-install.md
@@ -15,9 +15,10 @@ Three things, and a few minutes:
   computer.
 - `curl` or `wget`, and Python 3.8 or newer. The command below checks for both
   and stops with a message if either is absent.
-- Room on the drive. A full RetroArch set is 5.5 GB, Batocera 4.0 GB, MiSTer
-  FPGA 24 MB. The installer measures the free space and refuses before writing
-  anything if there is not enough.
+- Room on the drive. The size depends on the platform and changes with each
+  release: the run prints it before downloading (Step 3), and asks first when it
+  reaches 1 GB. The installer also measures the free space and refuses before
+  writing anything if there is not enough.
 
 Nothing is written outside the BIOS folder, and games and saves are never
 touched.
@@ -76,46 +77,73 @@ keeps its BIOS files, stop with Ctrl+C and see the last section.
 
 ## Step 3. Let it work
 
+The examples on this page follow the Batocera list as published on 2026-10-21.
+The figures change with each release.
+
 Two phases follow. The first reads what is already in the folder, which takes a
 few minutes on a memory card because every file is hashed:
 
 ```
 Fetching file index for batocera...
-  12893 files (8.6 GB)
+  14481 files (9.1 GB)
+  Not installable: 399 files (79 required, not found: 399).
 
 Checking existing files...
-  0/12893 present (0 verified, 0 wrong hash)
+  0/14481 present (0 verified, 0 wrong hash)
 ```
 
+`Not installable` counts the files of the list that the collection does not
+hold. They are named at the end of the run (Step 4).
+
 On a first install the present count is zero, which is expected, not a fault.
 On a later run it counts what is already there, and only the rest is
 downloaded. A download of 1 GB or more is confirmed first
-(`Download 8.6 GB to /userdata/bios? [Y/n]`).
+(`Download 9.1 GB to /userdata/bios? [Y/n]`).
 
 The second phase downloads what is missing, one line per file:
 
 ```
-Downloading 12893 files (8.6 GB)...
+Downloading 14481 files (9.1 GB)...
   Press Ctrl+C to stop. Running the same command again carries on from here.
-  [1/12893] 3do_arcade_saot.bin ok
-  [2/12893] 3dobios.zip ok
+  [1/14481] 3do_arcade_saot.bin ok
+  [2/14481] 3dobios.zip ok
 ```
 
 Ctrl+C is safe at any point. Files already installed stay, and running the
 command again picks up where it stopped.
 
-## Step 4. Read the last three lines
+## Step 4. Read the end of the run
 
 This is what a finished run looks like:
 
 ```
-Done. 12893 files installed, 0 files already up to date.
+Done. 14481 files installed, 0 files already up to date.
 Location: /userdata/bios
+399 files were not installed: the collection does not hold them, or its copy fails their check.
+  Needed to start an emulator (79 files):
+    dark-forces (theforceengine): DARK.GOB, SOUNDS.GOB, SPRITES.GOB, TEXTURES.GOB
+    dark-forces-ii (openjkdf2): openjkdf2/episode/JK1.gob, openjkdf2/episode/JK1CTF.gob, openjkdf2/episode/JK1MP.gob, openjkdf2/resource/Res1hi.gob, openjkdf2/resource/Res2.gob
+    diablo (devilutionx): devilutionx/diabdat.mpq
+    doom3 (dhewm3): base/pak000.pk4, base/pak002.pk4, base/pak003.pk4, base/pak004.pk4
+    droidworks (openjkdf2): dwCD.GOB, dwHD.GOB, dwMin.GOB, dwStream.GOB
+    fallout (fallout1-ce): fallout1-ce/critter.dat, fallout1-ce/master.dat
+    fallout2 (fallout2-ce): fallout2-ce/critter.dat, fallout2-ce/master.dat
+    fury (fury): fury.grp
+    ... and 9 more systems (--check --verbose lists them all)
+  Each emulator's page says what these files are: https://abdess.github.io/retrobios/emulators/
 To check this later, run the same command with --check.
 ```
 
-The word `Done` and a location are the confirmation. Any other ending means
-something was left undone, and the run says which case it was.
+The word `Done` and a location are the confirmation. Any other ending (`Stopped`,
+`Finished with errors`, `Nothing was installed`) means something was left undone,
+and the run says which case it was.
+
+The lines between `Location:` and the `--check` hint name the files of the list
+that the collection does not hold. `Needed to start an emulator` gives, for each
+system, the emulators that read it and the files they cannot start without. On
+the run above, all 79 belong to games (Dark Forces, Diablo, Doom 3, Tomb Raider
+and the others): the engine reads them from a copy of the game itself. The
+other 320 are optional, and the emulators reading them start without them.
 
 ## Step 5. Confirm it later
 
@@ -127,12 +155,13 @@ curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh |
 
 ```
 Checking existing files...
-  72/72 present (72 verified, 0 wrong hash)
+  14481/14481 present (14481 verified, 0 wrong hash)
 
   All files up to date.
 ```
 
-`0 wrong hash` is the line that matters. A number there means a file is present
+The files the collection does not hold are listed after it again, as long as
+they are absent from the folder. `0 wrong hash` is the line that matters. A number there means a file is present
 whose contents the platform will reject, and running the install again replaces
 it.
 
@@ -140,8 +169,12 @@ it.
 
 ### No supported platform detected.
 
-The command was piped from the internet, so it cannot stop and ask a question.
-Name the platform and the folder instead:
+At a terminal, a menu follows that line. The platform is picked by its number,
+then the run asks for the BIOS folder, offering the platform's usual folder on
+this system as the default when it has one.
+
+Without a terminal, or with `--no-input`, the run stops there and prints the
+command to use instead, with the platform and the folder named:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh \