From f1855641c5c5a214a1e183efb7e9d8f451d7b1da Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Sat, 28 Mar 2026 09:29:31 +0100
Subject: [PATCH] docs: add granular pack options to tools reference

---
 scripts/generate_site.py | 21 +++++++++++++++++++++
 wiki/tools.md            | 21 +++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/scripts/generate_site.py b/scripts/generate_site.py
index 63df236f..2b6d6290 100644
--- a/scripts/generate_site.py
+++ b/scripts/generate_site.py
@@ -1604,10 +1604,22 @@ def generate_wiki_tools() -> str:
         "Build platform-specific BIOS ZIP packs.",
         "",
         "```bash",
+        "# Full platform packs",
         "python scripts/generate_pack.py --all --output-dir dist/",
         "python scripts/generate_pack.py --platform batocera",
         "python scripts/generate_pack.py --emulator dolphin",
         "python scripts/generate_pack.py --system atari-lynx",
+        "",
+        "# Granular options",
+        "python scripts/generate_pack.py --platform retroarch --system sony-playstation",
+        "python scripts/generate_pack.py --platform batocera --required-only",
+        "python scripts/generate_pack.py --platform retroarch --split",
+        "python scripts/generate_pack.py --platform retroarch --split --group-by manufacturer",
+        "",
+        "# Hash-based lookup and custom packs",
+        "python scripts/generate_pack.py --from-md5 d8f1206299c48946e6ec5ef96d014eaa",
+        "python scripts/generate_pack.py --platform batocera --from-md5-file missing.txt",
+        "python scripts/generate_pack.py --platform retroarch --list-systems",
         "```",
         "",
         "Packs include platform baseline files plus files required by the platform's cores.",
@@ -1615,6 +1627,15 @@ def generate_wiki_tools() -> str:
         "the tool searches for a variant that satisfies both.",
         "If none exists, the platform version is kept and the discrepancy is reported.",
         "",
+        "**Granular options:**",
+        "",
+        "- `--system` with `--platform`: filter to specific systems within a platform pack",
+        "- `--required-only`: exclude optional files, keep only required",
+        "- `--split`: generate one ZIP per system instead of one big pack",
+        "- `--split --group-by manufacturer`: group split packs by manufacturer (Sony, Nintendo, Sega...)",
+        "- `--from-md5`: look up a hash in the database, or build a custom pack with `--platform`/`--emulator`",
+        "- `--from-md5-file`: same, reading hashes from a file (one per line, comments with #)",
+        "",
         "### cross_reference.py",
         "",
         "Compare emulator profiles against platform configs.",
diff --git a/wiki/tools.md b/wiki/tools.md
index 20278622..2f0f3180 100644
--- a/wiki/tools.md
+++ b/wiki/tools.md
@@ -51,10 +51,22 @@ Verification modes per platform:
 Build platform-specific BIOS ZIP packs.
 
 ```bash
+# Full platform packs
 python scripts/generate_pack.py --all --output-dir dist/
 python scripts/generate_pack.py --platform batocera
 python scripts/generate_pack.py --emulator dolphin
 python scripts/generate_pack.py --system atari-lynx
+
+# Granular options
+python scripts/generate_pack.py --platform retroarch --system sony-playstation
+python scripts/generate_pack.py --platform batocera --required-only
+python scripts/generate_pack.py --platform retroarch --split
+python scripts/generate_pack.py --platform retroarch --split --group-by manufacturer
+
+# Hash-based lookup and custom packs
+python scripts/generate_pack.py --from-md5 d8f1206299c48946e6ec5ef96d014eaa
+python scripts/generate_pack.py --platform batocera --from-md5-file missing.txt
+python scripts/generate_pack.py --platform retroarch --list-systems
 ```
 
 Packs include platform baseline files plus files required by the platform's cores.
@@ -62,6 +74,15 @@ When a file passes platform verification but fails emulator validation,
 the tool searches for a variant that satisfies both.
 If none exists, the platform version is kept and the discrepancy is reported.
 
+**Granular options:**
+
+- `--system` with `--platform`: filter to specific systems within a platform pack
+- `--required-only`: exclude optional files, keep only required
+- `--split`: generate one ZIP per system instead of one big pack
+- `--split --group-by manufacturer`: group split packs by manufacturer (Sony, Nintendo, Sega...)
+- `--from-md5`: look up a hash in the database, or build a custom pack with `--platform`/`--emulator`
+- `--from-md5-file`: same, reading hashes from a file (one per line, comments with #)
+
 ### cross_reference.py
 
 Compare emulator profiles against platform configs.