From 8ac64d6143ee39b3e122bb8248e92df8fb2248c2 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Thu, 26 Mar 2026 07:15:01 +0100
Subject: [PATCH] docs: add build guide and documentation site section to
 readme

Quick start commands for generating packs by platform, emulator, or
system. Documentation site section explains what users can find there.
---
 README.md                  | 41 +++++++++++++++++++++++++++++++++-----
 database.json              |  2 +-
 scripts/generate_readme.py | 39 ++++++++++++++++++++++++++++++++----
 3 files changed, 72 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 15d9b85d..339da0ac 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,41 @@ Full list with per-file details: **[https://abdess.github.io/retrobios/](https:/
 | RetroPie | 448/448 (100.0%) | 448 | 0 | 0 |
 | RomM | 374/374 (100.0%) | 359 | 15 | 0 |
 
+## Build your own pack
+
+Clone the repo and generate packs for any platform, emulator, or system:
+
+```bash
+# Full platform pack
+python scripts/generate_pack.py --platform retroarch --output-dir dist/
+python scripts/generate_pack.py --platform batocera --output-dir dist/
+
+# Single emulator or system
+python scripts/generate_pack.py --emulator dolphin
+python scripts/generate_pack.py --system sony-playstation-2
+
+# List available emulators and systems
+python scripts/generate_pack.py --list-emulators
+python scripts/generate_pack.py --list-systems
+
+# Verify your BIOS collection
+python scripts/verify.py --all
+python scripts/verify.py --platform batocera
+python scripts/verify.py --emulator flycast
+```
+
+Only dependency: Python 3 + `pyyaml`.
+
+## Documentation site
+
+The [documentation site](https://abdess.github.io/retrobios/) provides:
+
+- **Per-platform pages** with file-by-file verification status and hashes
+- **Per-emulator profiles** with source code references for every file
+- **Per-system pages** showing which emulators and platforms cover each console
+- **Gap analysis** identifying missing files and undeclared core requirements
+- **Cross-reference** mapping files across 9 platforms and 319 emulators
+
 ## How it works
 
 Documentation and metadata can drift from what emulators actually load.
@@ -61,10 +96,6 @@ To keep packs accurate, each file is checked against the emulator's source code.
 3. **Build packs** - include baseline files plus what each platform's cores need
 4. **Verify** - run platform-native checks and emulator-level validation
 
-## Documentation
-
-Per-file hashes, emulator profiles, gap analysis, cross-reference: **[https://abdess.github.io/retrobios/](https://abdess.github.io/retrobios/)**
-
 ## Contributors
 
 <a href="https://github.com/PixNyb"><img src="https://avatars.githubusercontent.com/u/40770831?v=4" width="50" title="PixNyb"></a>
@@ -79,4 +110,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 This repository provides BIOS files for personal backup and archival purposes.
 
-*Auto-generated on 2026-03-26T02:33:34Z*
+*Auto-generated on 2026-03-26T06:14:11Z*
diff --git a/database.json b/database.json
index 8a6b6d16..a4d1ed5a 100644
--- a/database.json
+++ b/database.json
@@ -1,5 +1,5 @@
 {
-  "generated_at": "2026-03-26T02:33:17Z",
+  "generated_at": "2026-03-26T06:09:06Z",
   "total_files": 6748,
   "total_size": 5505760050,
   "files": {
diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py
index 0b88c228..191d25af 100644
--- a/scripts/generate_readme.py
+++ b/scripts/generate_readme.py
@@ -191,6 +191,41 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         )
 
     lines.extend([
+        "",
+        "## Build your own pack",
+        "",
+        "Clone the repo and generate packs for any platform, emulator, or system:",
+        "",
+        "```bash",
+        "# Full platform pack",
+        "python scripts/generate_pack.py --platform retroarch --output-dir dist/",
+        "python scripts/generate_pack.py --platform batocera --output-dir dist/",
+        "",
+        "# Single emulator or system",
+        "python scripts/generate_pack.py --emulator dolphin",
+        "python scripts/generate_pack.py --system sony-playstation-2",
+        "",
+        "# List available emulators and systems",
+        "python scripts/generate_pack.py --list-emulators",
+        "python scripts/generate_pack.py --list-systems",
+        "",
+        "# Verify your BIOS collection",
+        "python scripts/verify.py --all",
+        "python scripts/verify.py --platform batocera",
+        "python scripts/verify.py --emulator flycast",
+        "```",
+        "",
+        f"Only dependency: Python 3 + `pyyaml`.",
+        "",
+        "## Documentation site",
+        "",
+        f"The [documentation site]({SITE_URL}) provides:",
+        "",
+        f"- **Per-platform pages** with file-by-file verification status and hashes",
+        f"- **Per-emulator profiles** with source code references for every file",
+        f"- **Per-system pages** showing which emulators and platforms cover each console",
+        f"- **Gap analysis** identifying missing files and undeclared core requirements",
+        f"- **Cross-reference** mapping files across {len(coverages)} platforms and {emulator_count} emulators",
         "",
         "## How it works",
         "",
@@ -202,10 +237,6 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "3. **Build packs** - include baseline files plus what each platform's cores need",
         "4. **Verify** - run platform-native checks and emulator-level validation",
         "",
-        "## Documentation",
-        "",
-        f"Per-file hashes, emulator profiles, gap analysis, cross-reference: **[{SITE_URL}]({SITE_URL})**",
-        "",
     ])
 
     contributors = fetch_contributors()