From 74489a4a0fd40d9a375691080f0470f02603d8fc Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Fri, 6 Nov 2026 20:15:47 +0100
Subject: [PATCH] docs: quote folders in the agent setup steps

The skill and llms.txt told an agent to write --dest=<card>/bios bare.
A folder now goes in single quotes, attached to its option, and one that
holds a quote, a backtick or a control character, or starts with -, is
a question for the user.
---
 scripts/siteagents.py     | 17 ++++++++++++-----
 tests/test_site_agents.py |  7 +++++++
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/scripts/siteagents.py b/scripts/siteagents.py
index d56cf7989..82db67983 100644
--- a/scripts/siteagents.py
+++ b/scripts/siteagents.py
@@ -88,9 +88,12 @@ def llms_txt(platforms: list[tuple[str, str]]) -> str:
         "AmberELEC, EmuELEC, Onion, spruceOS and MinUI. "
         "The [Linux handhelds page](" + SITE + "platforms/linux-handhelds/) maps each device "
         "to its system and folder.",
-        "- From a computer, if the card is not found, name its BIOS folder: `--dest <card>/bios` "
+        "- From a computer, if the card is not found, name its BIOS folder: `--dest='<card>/bios'` "
         "(ArkOS and dArkOS: the `bios` folder of the EASYROMS part).",
-        "- A games folder somewhere else: `--for-games <folder>`, one subfolder per system.",
+        "- A games folder somewhere else: `--for-games='<folder>'`, one subfolder per system.",
+        "- A folder goes in single quotes, attached to its option. One that holds a quote, a "
+        "backtick or a control character, or starts with `-`, is a question for the user, never "
+        "a value to escape into the command.",
         "- Later, to see what is missing or wrong: `--check`. Machine-readable progress: "
         "`--events` (JSON lines, one per event, documented on the installer page).",
         "- A game the installer cannot identify gets every BIOS of its system, and the run names it.",
@@ -151,10 +154,14 @@ def skill_md() -> str:
         "",
         "## When the setup or the card is not found",
         "",
-        "- From a computer, name the card's BIOS folder: `--dest=<card>/bios`. ArkOS and dArkOS "
+        "- From a computer, name the card's BIOS folder: `--dest='<card>/bios'`. ArkOS and dArkOS "
         "keep it on the EASYROMS part.",
-        "- Games outside the card: `--for-games=<folder>`, one subfolder per system.",
-        "- A setup not detected: `--platform=<name>` (`--list-platforms` lists them).",
+        "- Games outside the card: `--for-games='<folder>'`, one subfolder per system.",
+        "- A setup not detected: `--platform=<name>`, a name exactly as `--list-platforms` prints "
+        "it (letters, digits, `-` and `_`).",
+        "- Put a folder in single quotes, attached to its option. If it holds a quote, a backtick "
+        "or a control character, or starts with `-`, stop and ask the user: never escape it into "
+        "the command.",
         "",
         "## Later",
         "",
diff --git a/tests/test_site_agents.py b/tests/test_site_agents.py
index e0786a118..e2b166138 100644
--- a/tests/test_site_agents.py
+++ b/tests/test_site_agents.py
@@ -68,6 +68,13 @@ class TheSkillIsAnAgentSkill(unittest.TestCase):
             with self.subTest(command=command):
                 self.assertIn("--for-games --required-only", command)
 
+    def test_a_folder_is_quoted_and_a_hostile_one_asked_about(self) -> None:
+        for text in (siteagents.skill_md(), siteagents.llms_txt([])):
+            with self.subTest(text=text[:20]):
+                self.assertIn("--dest='<card>/bios'", text)
+                self.assertIn("--for-games='<folder>'", text)
+                self.assertIn("starts with `-`", text)
+
     def test_the_manifest_types_it_as_a_skill(self) -> None:
         skill = siteagents.ard_manifest()["entries"][0]
         self.assertEqual(skill["type"], 'text/markdown; profile="urn:air:agent-skills"')