docs: link the start pages from the README

Quick install linked only the installer reference. It now names the first
install, troubleshooting and FAQ pages.

README.md

@@ -39,6 +39,8 @@ curl -fsSL https://abdess.github.io/retrobios/i | sh -s -- --platform retroarch
 The script opens a full-screen installer, driven with the arrow keys and Enter, or with a controller on a handheld. It finds your setup and its BIOS folder, downloads only the missing files and checks each one. It can also copy the BIOS files from your old SD card.
 Every option, and what the installer detects and writes, is on the [installer page](https://abdess.github.io/retrobios/wiki/installer/#passing-options).
 
+First time? Follow the [first install, step by step](https://abdess.github.io/retrobios/wiki/first-install/). A game does not start: [what to check](https://abdess.github.io/retrobios/wiki/troubleshooting/). Other questions: the [FAQ](https://abdess.github.io/retrobios/wiki/faq/).
+
 ## Download BIOS packs
 
 A pack holds everything its platform runs: its own BIOS list plus every file its emulator cores load. Pick your platform, download the ZIP, extract to the BIOS path. Each Download link is a page that keeps its address from one release to the next. The installer above does the same file by file: its screen installs everything, or fewer under **Choose systems**, and `--system`, `--core`, `--region` and `--target` make the same choice without questions. For a bare minimum, build your own pack below.
@@ -206,4 +208,4 @@ The scripts and tooling are released under the [MIT License](LICENSE).
 The BIOS and firmware files are not covered by that license: they are third-party system software, preserved and provided for personal backup, archival, and interoperability with emulation software. [NOTICE](NOTICE) sets out their status and how to ask for a file to be removed.
 The reasoning, and where it is weakest, is in [the project's legal position](https://abdess.github.io/retrobios/wiki/legal/).
 
-*Auto-generated on 2026-11-06T02:18:34Z*
+*Auto-generated on 2026-11-06T02:20:28Z*

scripts/generate_readme.py

@@ -593,6 +593,10 @@ def generate_readme(db: dict, platforms_dir: str, db_path: str = "database.json"
         " files and checks each one. It can also copy the BIOS files from your old SD card.",
         f"Every option, and what the installer detects and writes, is on the [installer page]({SITE_URL}wiki/installer/#passing-options).",
         "",
+        f"First time? Follow the [first install, step by step]({SITE_URL}wiki/first-install/)."
+        f" A game does not start: [what to check]({SITE_URL}wiki/troubleshooting/)."
+        f" Other questions: the [FAQ]({SITE_URL}wiki/faq/).",
+        "",
         "## Download BIOS packs",
         "",
         "A pack holds everything its platform runs: its own BIOS list plus every file its emulator cores load. Pick your platform, download the ZIP, extract to the BIOS path. Each Download link is a page that keeps its address from one release to the next. The installer above does the same file by file: its screen installs everything, or fewer under **" + _installer_words().TUI_SYSTEMS_ROW + "**, and `--system`, `--core`, `--region` and `--target` make the same choice without questions. For a bare minimum, build your own pack below.",

tests/test_doc_surfaces.py

@@ -248,6 +248,21 @@ class SlicesLeaveWithTheirRelease(unittest.TestCase):
         self.assertNotIn(".zip.001", _which_pack())
 
 
+class TheReadmeLeadsBeginnersToTheirPages(unittest.TestCase):
+    """The README linked the installer reference and the FAQ's no-ZIP anchor
+    only: a user stopped by an install error or a BIOS-not-found message had
+    no link to the first install or troubleshooting page."""
+
+    def test_quick_install_links_the_start_pages(self):
+        # The code block holds `#` comment lines, so the section runs to
+        # the next level-two heading.
+        section = _read("README.md").split("## Quick install", 1)[1].split("\n## ", 1)[0]
+        for page in ("first-install", "troubleshooting", "faq"):
+            with self.subTest(page=page):
+                self.assertIn(f"wiki/{page}/)", section)
+                self.assertTrue((REPO_ROOT / "wiki" / f"{page}.md").is_file())
+
+
 class EndUsersCheckTheirOwnFolder(unittest.TestCase):
     """verify.py reads database.json and bios/. Advice about a user's own
     files points at the installer's --check, which hashes their folder."""