chore: merge origin/main

scripts/common.py

@@ -112,7 +112,7 @@ def load_database(db_path: str) -> dict:
         )
         if close:
             raise DatabaseUnreadable(
-                f"{db_path} not found. Did you mean {typed.with_name(close[0])}?"
+                f"{db_path} not found. Close match: {typed.with_name(close[0])}"
             ) from None
         raise DatabaseUnreadable(
             f"{db_path} not found. Build it with: python scripts/generate_db.py "
@@ -665,7 +665,7 @@ def suggest_names(
     close = sorted({m for name in typed
                     for m in difflib.get_close_matches(name, available, n=3, cutoff=0.6)})
     if close:
-        return f"Did you mean: {', '.join(close)}? {listing_flag} lists all {total}."
+        return f"Close matches: {', '.join(close)}. {listing_flag} lists all {total}."
     if len(available) <= SHORT_LIST:
         return f"Known: {', '.join(available)}."
     return f"{listing_flag} lists all {total}."
@@ -733,7 +733,7 @@ def require_platform(name: str, platforms_dir: str = "platforms") -> None:
 
     known = list_registered_platforms(platforms_dir)
     close = difflib.get_close_matches(name, known, n=1)
-    hint = f" Did you mean '{close[0]}'?" if close else ""
+    hint = f" Close match: '{close[0]}'." if close else ""
     raise SystemExit(
         f"ERROR: unknown platform '{name}'.{hint}\nKnown platforms: {', '.join(known)}"
     )
@@ -3661,7 +3661,7 @@ def _unknown_target_message(target: str, platforms: list[str], platforms_dir: st
     close = difflib.get_close_matches(target, sorted(owners), n=3, cutoff=0.6)
     if close:
         named = ", ".join(f"{n} ({', '.join(sorted(owners[n]))})" for n in close)
-        return f"{message} Did you mean: {named}?"
+        return f"{message} Close matches: {named}."
     return (f"{message} python scripts/verify.py --platform <name> --list-targets "
             "lists the targets of one platform.")
 

scripts/generate_site.py

@@ -518,8 +518,8 @@ def generate_home(
         "## Three steps",
         "",
         *markup.steps([
-            "**Pick the device.** Its page shows the BIOS folder.",
-            "**Run one command.** Some setups have a ZIP.",
+            "**Pick the device.** Its page gives one line to copy.",
+            "**Paste it, press Enter.** Some setups have a ZIP.",
             "**Start a game.**",
         ]),
         *install_demo(),
@@ -4520,6 +4520,8 @@ def _platform_guide(name: str, display: str, cov: dict, registry: dict, no_list:
     guide = GUIDES[name]
     entry = registry.get(name, {})
     extract_to = entry.get("extract_to")
+    # An app's page opens on the command: one line to paste is the shortest
+    # way to a working setup, and the folder table is what a manual copy needs.
     lines = ["## Where the files go", ""]
     if guide.lead:
         lines += [guide.lead, ""]
@@ -4543,6 +4545,7 @@ def _platform_guide(name: str, display: str, cov: dict, registry: dict, no_list:
     if guide.on_card:
         lines += ["<!-- image: minui-card -->", ""]
     if _computer_first(name, guide):
+        # The ZIP copied over the network needs the folder table above it.
         lines += [
             *_guide_download(name, display, guide, extract_to,
                              "## From a computer { #download }"),
@@ -4550,10 +4553,12 @@ def _platform_guide(name: str, display: str, cov: dict, registry: dict, no_list:
             *_guide_install(name, guide, "## On the device { #install }"),
         ]
     else:
-        lines += [
+        where = lines
+        lines = [
             *_setup_routes(name, display, page_link=True),
             *_guide_download(name, display, guide, extract_to, "## Download"),
             *_offline_line(name),
+            *where,
         ]
     check_args = {key: f"{args} --check" for key, args in platform_args(name, guide).items()}
     lines += [

scripts/region.py

@@ -129,7 +129,7 @@ def unknown_region_message(raw: str, aliases: dict[str, str], regions: frozenset
 
     spelled = raw.strip()
     close = difflib.get_close_matches(spelled.lower(), [*aliases, *regions], n=3, cutoff=0.5)
-    hint = f" Did you mean: {', '.join(close)}?" if close else ""
+    hint = f" Close matches: {', '.join(close)}." if close else ""
     return (
         f"unknown region: {spelled}.{hint} Short forms: {', '.join(aliases)}; "
         f"regions: {', '.join(sorted(regions))}"