fix: deploy-pages v5 does not exist, revert to v4

This reverts commit d4e5af2c74.

.github/workflows/build.yml

@@ -18,13 +18,11 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  regenerate:
+  release:
+    if: false  # disabled until pack generation is validated in production
     runs-on: ubuntu-latest
     permissions:
       contents: write
-      pages: write
-    outputs:
-      changed: ${{ steps.commit.outputs.changed }}
     steps:
       - uses: actions/checkout@v6
 
@@ -34,57 +32,9 @@ jobs:
 
       - run: pip install pyyaml
 
-      - name: Restore large files from release
-        run: |
-          mkdir -p .cache/large
-          gh release download large-files -D .cache/large/ 2>/dev/null || true
-          # Copy large files to their bios/ paths so generate_db sees them
-          for f in .cache/large/*; do
-            [ -f "$f" ] || continue
-            name=$(basename "$f")
-            # Match against .gitignore entries to find target path
-            target=$(grep "$name" .gitignore | head -1)
-            if [ -n "$target" ] && [ ! -f "$target" ]; then
-              mkdir -p "$(dirname "$target")"
-              cp "$f" "$target"
-              echo "Restored: $target"
-            fi
-          done
-        env:
-          GH_TOKEN: ${{ github.token }}
-
-      - name: Regenerate database, readme, and site
-        run: |
-          pip install mkdocs-material
-          python scripts/generate_db.py --force --bios-dir bios --output database.json
-          python scripts/generate_readme.py --db database.json --platforms-dir platforms
-          python scripts/generate_site.py
-
       - name: Run tests
         run: python -m unittest tests.test_e2e -v
 
-      - name: Deploy site to GitHub Pages
-        if: github.ref == 'refs/heads/main'
-        run: mkdocs gh-deploy --force --clean
-
-      - name: Commit if changed
-        id: commit
-        run: |
-          git diff --quiet database.json README.md CONTRIBUTING.md && echo "changed=false" >> "$GITHUB_OUTPUT" && exit 0
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add database.json README.md CONTRIBUTING.md
-          git commit -m "regenerate database and docs"
-          git push
-          echo "changed=true" >> "$GITHUB_OUTPUT"
-
-  release:
-    needs: regenerate
-    if: (needs.regenerate.outputs.changed == 'true' || github.event.inputs.force_release == 'true')
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
       - name: Rate limit
         if: github.event.inputs.force_release != 'true'
         id: rate
@@ -103,19 +53,23 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/checkout@v6
+      - name: Restore large files from release
         if: steps.rate.outputs.skip != 'true'
-        with:
+        run: |
-          ref: main
+          mkdir -p .cache/large
-
+          gh release download large-files -D .cache/large/ 2>/dev/null || true
-      - uses: actions/setup-python@v6
+          for f in .cache/large/*; do
-        if: steps.rate.outputs.skip != 'true'
+            [ -f "$f" ] || continue
-        with:
+            name=$(basename "$f")
-          python-version: "3.12"
+            target=$(grep "$name" .gitignore | head -1)
-
+            if [ -n "$target" ] && [ ! -f "$target" ]; then
-      - name: Install dependencies
+              mkdir -p "$(dirname "$target")"
-        if: steps.rate.outputs.skip != 'true'
+              cp "$f" "$target"
-        run: pip install pyyaml
+              echo "Restored: $target"
+            fi
+          done
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Refresh data directories
         if: steps.rate.outputs.skip != 'true'
@@ -124,9 +78,7 @@ jobs:
 
       - name: Build packs
         if: steps.rate.outputs.skip != 'true'
-        run: |
+        run: python scripts/generate_pack.py --all --output-dir dist/
-          python scripts/generate_db.py --bios-dir bios --output database.json
-          python scripts/generate_pack.py --all --output-dir dist/
 
       - name: Release
         if: steps.rate.outputs.skip != 'true'
@@ -150,14 +102,16 @@ jobs:
           ${PACKS}
 
           ### Install
-          Download, extract to your emulator's BIOS directory.
+          Download the pack matching your frontend, extract to the BIOS directory.
 
-          | Platform | Path |
+          | Platform | Pack | Path |
-          |----------|------|
+          |----------|------|------|
-          | RetroArch / Lakka | system/ |
+          | RetroArch / Lakka | RetroArch_Lakka_BIOS_Pack.zip | system/ |
-          | Batocera | /userdata/bios/ |
+          | Batocera | Batocera_BIOS_Pack.zip | /userdata/bios/ |
-          | Recalbox | /recalbox/share/bios/ |
+          | Recalbox | Recalbox_BIOS_Pack.zip | /recalbox/share/bios/ |
-          | RetroBat | bios/ |
+          | RetroBat | RetroBat_BIOS_Pack.zip | bios/ |
+          | RetroDECK | RetroDECK_BIOS_Pack.zip | ~/retrodeck/bios/ |
+          | EmuDeck | EmuDeck_BIOS_Pack.zip | Emulation/bios/ |
 
           ### Changes
           ${CHANGES}

.github/workflows/deploy-site.yml

@@ -0,0 +1,59 @@
+name: Deploy Site
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "platforms/**"
+      - "emulators/**"
+      - "wiki/**"
+      - "scripts/generate_site.py"
+      - "scripts/generate_readme.py"
+      - "scripts/verify.py"
+      - "scripts/common.py"
+      - "database.json"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: deploy-site
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - run: pip install pyyaml mkdocs-material pymdown-extensions
+
+      - name: Generate site
+        run: |
+          python scripts/generate_site.py
+          python scripts/generate_readme.py --db database.json --platforms-dir platforms
+          mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -11,13 +11,8 @@ site/
 *.log
 node_modules/
 
-# Generated site pages (built in CI)
+# Generated site pages (built by generate_site.py, deployed in CI)
-docs/index.md
+docs/
-docs/platforms/
-docs/systems/
-docs/emulators/
-docs/contributing.md
-docs/gaps.md
 
 # Large files stored as GitHub Release assets (> 50MB)
 bios/Arcade/Arcade/Firmware.19.0.0.zip

README.md

@@ -1,8 +1,24 @@
-# Retrogaming BIOS & Firmware Collection
+# RetroBIOS
 
-Complete, verified collection of BIOS, firmware, and system files for retrogaming emulators.
+Source-verified BIOS and firmware packs for retrogaming platforms.
 
-> **6724** files | **5013.3 MB** | **8** platforms | **275** emulator profiles
+Documentation and metadata can drift from what emulators actually load at runtime.
+To keep packs accurate, each file here is checked against the emulator's source code:
+what the code opens, what hashes it expects, what happens when a file is missing.
+306 emulators profiled, 8 platforms cross-referenced,
+6,733 files verified.
+
+### How it works
+
+1. **Read emulator source code** - identify every file the code loads, its expected hash and size
+2. **Cross-reference with platforms** - match against what RetroArch, Batocera, Recalbox and others declare
+3. **Build packs** - for each platform, include its baseline files plus what its cores need
+4. **Verify** - run each platform's native checks (MD5, existence) and emulator-level validation (CRC32, size)
+
+When a platform and an emulator disagree on a file, the discrepancy is reported.
+When a variant in the repo satisfies both, it is preferred automatically.
+
+> **6,733** files | **5043.6 MB** | **8** platforms | **306** emulator profiles
 
 ## Download
 
@@ -23,12 +39,12 @@ Complete, verified collection of BIOS, firmware, and system files for retrogamin
 |----------|----------|----------|----------|---------|
 | Batocera | 359/359 (100.0%) | 358 | 1 | 0 |
 | EmuDeck | 161/161 (100.0%) | 161 | 0 | 0 |
-| Lakka | 448/448 (100.0%) | 448 | 0 | 0 |
+| Lakka | 448/448 (100.0%) | 440 | 8 | 0 |
-| Recalbox | 346/346 (100.0%) | 346 | 0 | 0 |
+| Recalbox | 346/346 (100.0%) | 341 | 5 | 0 |
-| RetroArch | 448/448 (100.0%) | 448 | 0 | 0 |
+| RetroArch | 448/448 (100.0%) | 440 | 8 | 0 |
-| RetroBat | 331/331 (100.0%) | 331 | 0 | 0 |
+| RetroBat | 331/331 (100.0%) | 330 | 1 | 0 |
-| RetroDECK | 2007/2007 (100.0%) | 1698 | 309 | 0 |
+| RetroDECK | 2007/2007 (100.0%) | 2001 | 6 | 0 |
-| RetroPie | 448/448 (100.0%) | 448 | 0 | 0 |
+| RetroPie | 448/448 (100.0%) | 440 | 8 | 0 |
 
 ## Documentation
 
@@ -47,4 +63,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 This repository provides BIOS files for personal backup and archival purposes.
 
-*Auto-generated on 2026-03-20T19:10:25Z*
+*Auto-generated on 2026-03-25T15:42:07Z*

database.json

@@ -1,5 +1,5 @@
 {
-  "generated_at": "2026-03-25T05:56:02Z",
+  "generated_at": "2026-03-25T15:41:49Z",
   "total_files": 6733,
   "total_size": 5288644732,
   "files": {
@@ -1163,16 +1163,6 @@
       "crc32": "b28f7112",
       "adler32": "591b377c"
     },
-    "ac4b78d53c7a97da2451ca35498395d8dd1e3024": {
-      "path": "bios/Arcade/Arcade/Firmware.19.0.0.zip",
-      "name": "Firmware.19.0.0.zip",
-      "size": 338076508,
-      "sha1": "ac4b78d53c7a97da2451ca35498395d8dd1e3024",
-      "md5": "72d6c73306c7f0b76723f989e7e1bdd1",
-      "sha256": "2f3791655e6c1b56f07a309b69ce8ea35d8412695599bbb6d4b0e29d1b044b66",
-      "crc32": "77228c84",
-      "adler32": "471a3291"
-    },
     "5426d52e17e0ff9195fabbb42f704342e556d08e": {
       "path": "bios/Arcade/Arcade/acpsx.zip",
       "name": "acpsx.zip",
@@ -1843,16 +1833,6 @@
       "crc32": "065d69d0",
       "adler32": "3e9b6373"
     },
-    "add40c002084e8e25768671877b2aa603aaf5cb1": {
-      "path": "bios/Arcade/Arcade/maclc3.zip",
-      "name": "maclc3.zip",
-      "size": 189428461,
-      "sha1": "add40c002084e8e25768671877b2aa603aaf5cb1",
-      "md5": "aff722788800df5b22d5a07cf8e558ee",
-      "sha256": "e663e456e88f475b3cacc06e75f50605e700789aa327b6648c627a560762a5d6",
-      "crc32": "81f21918",
-      "adler32": "dbd42440"
-    },
     "4e0202f8430cb4842184df7b5418e32620156c7b": {
       "path": "bios/Arcade/Arcade/macsbios.zip",
       "name": "macsbios.zip",
@@ -33253,16 +33233,6 @@
       "crc32": "df558b58",
       "adler32": "4f2d77b8"
     },
-    "b48f44194fe918aaaec5298861479512b581d661": {
-      "path": "bios/Nintendo/Nintendo DS/dsi_nand.bin",
-      "name": "dsi_nand.bin",
-      "size": 251658304,
-      "sha1": "b48f44194fe918aaaec5298861479512b581d661",
-      "md5": "dfafb1908da8f527df7a372e649b50be",
-      "sha256": "f57d9bf00529bec35d58404faff029a193fd2ccda0a83403ec4e6cc32626721b",
-      "crc32": "416bf51a",
-      "adler32": "3b3e7d56"
-    },
     "3b71f43ff30f4b15b5cd85dd9e95ebc7e84eb5a3": {
       "path": "bios/Nintendo/Nintendo DS/dsi_sd_card.bin",
       "name": "dsi_sd_card.bin",
@@ -65473,16 +65443,6 @@
       "crc32": "2c3bcd32",
       "adler32": "26412551"
     },
-    "093f8698b54b78dcb701de2043f82639de51d63b": {
-      "path": "bios/Sony/PlayStation 3/PS3UPDAT.PUP",
-      "name": "PS3UPDAT.PUP",
-      "size": 206126236,
-      "sha1": "093f8698b54b78dcb701de2043f82639de51d63b",
-      "md5": "05fe32f5dc8c78acbcd84d36ee7fdc5b",
-      "sha256": "69070a95780f59fc9e0d82bcf53eb9b28fd4ed4a7d54d0a40045f80422fd98d6",
-      "crc32": "24bdb2db",
-      "adler32": "1ec0b1c3"
-    },
     "6bf1ae9fb01915966b715836253592cbf588b406": {
       "path": "bios/Sony/PlayStation Portable/Roboto-Condensed.ttf",
       "name": "Roboto-Condensed.ttf",
@@ -66473,26 +66433,6 @@
       "crc32": "c0c3a1fe",
       "adler32": "ea4fd486"
     },
-    "ed3a4cb264fff283209f10ae58c96c6090fed187": {
-      "path": "bios/Sony/PlayStation Vita/PSP2UPDAT.PUP",
-      "name": "PSP2UPDAT.PUP",
-      "size": 56778752,
-      "sha1": "ed3a4cb264fff283209f10ae58c96c6090fed187",
-      "md5": "59dcf059d3328fb67be7e51f8aa33418",
-      "sha256": "c3c03fc7363dd573d90e5157629bf11551f434b283cc898d9ffc71dd716b791c",
-      "crc32": "082ecf86",
-      "adler32": "620a2ff1"
-    },
-    "cc72dfcc964577cc29112ef368c28f55277c237c": {
-      "path": "bios/Sony/PlayStation Vita/PSVUPDAT.PUP",
-      "name": "PSVUPDAT.PUP",
-      "size": 133834240,
-      "sha1": "cc72dfcc964577cc29112ef368c28f55277c237c",
-      "md5": "f2c7b12fe85496ec88a0391b514d6e3b",
-      "sha256": "6ef6dc8da6db026f28647713e473486d770087a605c52a8d751bfca7478386cf",
-      "crc32": "39075d41",
-      "adler32": "75d71010"
-    },
     "b184f1c1febf66c8168fcae0b8aa37a5754f79db": {
       "path": "bios/Synertek/SYM-1/SYM.ROM",
       "name": "SYM.ROM",
@@ -67332,6 +67272,66 @@
       "sha256": "2a86458696e83eb924fc6c6fda3ca5d320ca90885bd6c2f32d121757ade389bb",
       "crc32": "74b76447",
       "adler32": "701e6531"
+    },
+    "ac4b78d53c7a97da2451ca35498395d8dd1e3024": {
+      "path": ".cache/large/Firmware.19.0.0.zip",
+      "name": "Firmware.19.0.0.zip",
+      "size": 338076508,
+      "sha1": "ac4b78d53c7a97da2451ca35498395d8dd1e3024",
+      "md5": "72d6c73306c7f0b76723f989e7e1bdd1",
+      "sha256": "2f3791655e6c1b56f07a309b69ce8ea35d8412695599bbb6d4b0e29d1b044b66",
+      "crc32": "77228c84",
+      "adler32": "471a3291"
+    },
+    "add40c002084e8e25768671877b2aa603aaf5cb1": {
+      "path": ".cache/large/maclc3.zip",
+      "name": "maclc3.zip",
+      "size": 189428461,
+      "sha1": "add40c002084e8e25768671877b2aa603aaf5cb1",
+      "md5": "aff722788800df5b22d5a07cf8e558ee",
+      "sha256": "e663e456e88f475b3cacc06e75f50605e700789aa327b6648c627a560762a5d6",
+      "crc32": "81f21918",
+      "adler32": "dbd42440"
+    },
+    "b48f44194fe918aaaec5298861479512b581d661": {
+      "path": ".cache/large/dsi_nand.bin",
+      "name": "dsi_nand.bin",
+      "size": 251658304,
+      "sha1": "b48f44194fe918aaaec5298861479512b581d661",
+      "md5": "dfafb1908da8f527df7a372e649b50be",
+      "sha256": "f57d9bf00529bec35d58404faff029a193fd2ccda0a83403ec4e6cc32626721b",
+      "crc32": "416bf51a",
+      "adler32": "3b3e7d56"
+    },
+    "093f8698b54b78dcb701de2043f82639de51d63b": {
+      "path": ".cache/large/PS3UPDAT.PUP",
+      "name": "PS3UPDAT.PUP",
+      "size": 206126236,
+      "sha1": "093f8698b54b78dcb701de2043f82639de51d63b",
+      "md5": "05fe32f5dc8c78acbcd84d36ee7fdc5b",
+      "sha256": "69070a95780f59fc9e0d82bcf53eb9b28fd4ed4a7d54d0a40045f80422fd98d6",
+      "crc32": "24bdb2db",
+      "adler32": "1ec0b1c3"
+    },
+    "ed3a4cb264fff283209f10ae58c96c6090fed187": {
+      "path": ".cache/large/PSP2UPDAT.PUP",
+      "name": "PSP2UPDAT.PUP",
+      "size": 56778752,
+      "sha1": "ed3a4cb264fff283209f10ae58c96c6090fed187",
+      "md5": "59dcf059d3328fb67be7e51f8aa33418",
+      "sha256": "c3c03fc7363dd573d90e5157629bf11551f434b283cc898d9ffc71dd716b791c",
+      "crc32": "082ecf86",
+      "adler32": "620a2ff1"
+    },
+    "cc72dfcc964577cc29112ef368c28f55277c237c": {
+      "path": ".cache/large/PSVUPDAT.PUP",
+      "name": "PSVUPDAT.PUP",
+      "size": 133834240,
+      "sha1": "cc72dfcc964577cc29112ef368c28f55277c237c",
+      "md5": "f2c7b12fe85496ec88a0391b514d6e3b",
+      "sha256": "6ef6dc8da6db026f28647713e473486d770087a605c52a8d751bfca7478386cf",
+      "crc32": "39075d41",
+      "adler32": "75d71010"
     }
   },
   "indexes": {
@@ -67452,7 +67452,6 @@
       "fcb298d97792b9e9bdd3296cc6be10b6": "eb2a867578a05bbf8741e9fe7204301062df0cb8",
       "ddb8aacffffffa608ddbb4a6d6dda5ec": "0b6519209766ed883e3fca4c61bf866804c89004",
       "6c6c0c726cbf15e81785eb7592fdb51c": "de463b0577dfd1027bf7de523ff67a0fff861cdb",
-      "72d6c73306c7f0b76723f989e7e1bdd1": "ac4b78d53c7a97da2451ca35498395d8dd1e3024",
       "fcb631bf18a56f2d5b077fa846bab4a6": "5426d52e17e0ff9195fabbb42f704342e556d08e",
       "3f348c88af99a40fbd11fa435f28c69d": "e18c5e9ca21654dfd724aa54e625b386e6ffb2c5",
       "c266fc58905af1e246dffadc84301042": "beaf97c4a0e0792b8db65648f9dabb6a54ae0549",
@@ -67520,7 +67519,6 @@
       "7b51d463324b6bf26e86c4afb7316a3a": "8cf0aa7f9dca4d77485e605fb0e2173a734633bf",
       "7a14456d6e8afaf540f2368fead25f26": "78c8e1c3c033b65758b7e53a9346b44d037fea7f",
       "d048a9ff941041de45c26474a0da40aa": "65a2f2cee74c316d5f40b68deda66787609df353",
-      "aff722788800df5b22d5a07cf8e558ee": "add40c002084e8e25768671877b2aa603aaf5cb1",
       "34530e248d96e7171af19155af315378": "4e0202f8430cb4842184df7b5418e32620156c7b",
       "b48fb4fb35dc348f4904a318dbf9a712": "697551fcf9557ae33e31096b118a0c6769700a2e",
       "6bb005f55ba39bc5f6b330b663da1a58": "c9ee16e26e03496195a7bff151efbdd89da01204",
@@ -70661,7 +70659,6 @@
       "bfd8292fbf0a251647a23c5cb310a97a": "f1ad917e0affaeb8d2114c7ecd02b9f938c3cbd9",
       "94bc5094607c5e6598d50472c52f27f2": "1cf9e67c2c703bb9961bbcdd39cd2c7e319a803b",
       "8daa89fd280b3e5ec79fbab73ad6684e": "d2a5af338f09c5cbdd5d7628db5b9c075c69b616",
-      "dfafb1908da8f527df7a372e649b50be": "b48f44194fe918aaaec5298861479512b581d661",
       "b6d81b360a5672d80c27430f39153e2c": "3b71f43ff30f4b15b5cd85dd9e95ebc7e84eb5a3",
       "74f23348012d7b3e1cc216c47192ffeb": "3773f52559d5ac4fc6d8aefe35bce58730ae8181",
       "e45033d9b0fa6b0de071292bba7c9d13": "cfe072921ee3fb93f688743f8beef89043c3e9ad",
@@ -73883,7 +73880,6 @@
       "5dea62f70439682a6cee16ba3823d11e": "6eddec30056cde7c664a0cf508dcad29353a12bb",
       "de6da198a7359d1200c3eeb6df9c7eda": "40ecf6138c99a0aba775ef93240b295025a45500",
       "44552702b05697a14ccbe2ca22ee7139": "47d2ec4b342649e4c391043ab915d4435f9d180d",
-      "05fe32f5dc8c78acbcd84d36ee7fdc5b": "093f8698b54b78dcb701de2043f82639de51d63b",
       "55caa30ec34ef081ded15615db54eafe": "6bf1ae9fb01915966b715836253592cbf588b406",
       "a062688b08c70a42ff2a0acff6c46d93": "08325554623568bb9babadc10213bfc0b1151766",
       "ad0542e2956a8dddf52357f28a8a7d9c": "9d6c9874c1d6a0c57a1345f211154fe1e494b55a",
@@ -73983,8 +73979,6 @@
       "331d6806a56d7370515d94a66616eca6": "78632d0fe9dd77bf9a2264f192fae6f0af03a71c",
       "c96bb62586bf81dd6237c417f8cf3bb8": "18985a2079c7570c13cf39e0d001eef87538cd15",
       "8b5f60b56c3da8365b973dba570c53a5": "3ae832c9800fcaa007eccfc48f24242967c111f8",
-      "59dcf059d3328fb67be7e51f8aa33418": "ed3a4cb264fff283209f10ae58c96c6090fed187",
-      "f2c7b12fe85496ec88a0391b514d6e3b": "cc72dfcc964577cc29112ef368c28f55277c237c",
       "e59fdf56762c480ba4dfe1b3ec5fb86d": "b184f1c1febf66c8168fcae0b8aa37a5754f79db",
       "1d33d70f35b33873fc75941d95ad1ffa": "567c5b5054552a2771eafa7966844a146f0dde96",
       "b81dc552536796d234c08587bac7be43": "f2fa8d8e940f1d91a1b1624013df5dca0bb1ee44",
@@ -74068,7 +74062,13 @@
       "6f68e4baf89c8ee4623c19617319184b": "cee76080884af97c20059da0eb1ca956a835f3d0",
       "2010e5b85f9e1d60685ccb3d84a17115": "c7cc306fb921754ba00794153292d533cf0765ef",
       "39e5bc84ce9aac3a2d297d8aeb2a0d05": "22bcfeb5b6c6481569b90db96aa3f4b5f06c8848",
-      "a471e64e9f69afbe59c10cc94ed1b184": "ecfc092fe6371dbf38e238a8ba5f90785b5db52d"
+      "a471e64e9f69afbe59c10cc94ed1b184": "ecfc092fe6371dbf38e238a8ba5f90785b5db52d",
+      "72d6c73306c7f0b76723f989e7e1bdd1": "ac4b78d53c7a97da2451ca35498395d8dd1e3024",
+      "aff722788800df5b22d5a07cf8e558ee": "add40c002084e8e25768671877b2aa603aaf5cb1",
+      "dfafb1908da8f527df7a372e649b50be": "b48f44194fe918aaaec5298861479512b581d661",
+      "05fe32f5dc8c78acbcd84d36ee7fdc5b": "093f8698b54b78dcb701de2043f82639de51d63b",
+      "59dcf059d3328fb67be7e51f8aa33418": "ed3a4cb264fff283209f10ae58c96c6090fed187",
+      "f2c7b12fe85496ec88a0391b514d6e3b": "cc72dfcc964577cc29112ef368c28f55277c237c"
     },
     "by_name": {
       "3do_arcade_saot.bin": [
@@ -74428,9 +74428,6 @@
         "de463b0577dfd1027bf7de523ff67a0fff861cdb",
         "12516c82f52a8abb252fba754f95b7952c295e6f"
       ],
-      "Firmware.19.0.0.zip": [
-        "ac4b78d53c7a97da2451ca35498395d8dd1e3024"
-      ],
       "acpsx.zip": [
         "5426d52e17e0ff9195fabbb42f704342e556d08e"
       ],
@@ -83271,9 +83268,6 @@
       "dsi_firmware.bin": [
         "d2a5af338f09c5cbdd5d7628db5b9c075c69b616"
       ],
-      "dsi_nand.bin": [
-        "b48f44194fe918aaaec5298861479512b581d661"
-      ],
       "dsi_sd_card.bin": [
         "3b71f43ff30f4b15b5cd85dd9e95ebc7e84eb5a3"
       ],
@@ -92088,9 +92082,6 @@
       "rom1.bin": [
         "47d2ec4b342649e4c391043ab915d4435f9d180d"
       ],
-      "PS3UPDAT.PUP": [
-        "093f8698b54b78dcb701de2043f82639de51d63b"
-      ],
       "Roboto-Condensed.ttf": [
         "6bf1ae9fb01915966b715836253592cbf588b406"
       ],
@@ -92386,9 +92377,6 @@
         "3ae832c9800fcaa007eccfc48f24242967c111f8",
         "ed3a4cb264fff283209f10ae58c96c6090fed187"
       ],
-      "PSVUPDAT.PUP": [
-        "cc72dfcc964577cc29112ef368c28f55277c237c"
-      ],
       "coco.zip": [
         "567c5b5054552a2771eafa7966844a146f0dde96",
         "e31fbbb831f32886e57410183bc4e85d36c2dc7a"
@@ -92623,6 +92611,18 @@
       "data.zip": [
         "ecfc092fe6371dbf38e238a8ba5f90785b5db52d"
       ],
+      "Firmware.19.0.0.zip": [
+        "ac4b78d53c7a97da2451ca35498395d8dd1e3024"
+      ],
+      "dsi_nand.bin": [
+        "b48f44194fe918aaaec5298861479512b581d661"
+      ],
+      "PS3UPDAT.PUP": [
+        "093f8698b54b78dcb701de2043f82639de51d63b"
+      ],
+      "PSVUPDAT.PUP": [
+        "cc72dfcc964577cc29112ef368c28f55277c237c"
+      ],
       "disk2-16boot.rom": [
         "d4181c9f046aafc3fb326b381baac809d9e38d16"
       ],
@@ -93636,7 +93636,8 @@
         "2b8cb4f87580683eb4d760e4ed210813d667f0a2"
       ],
       "saturn_bios.bin": [
-        "2b8cb4f87580683eb4d760e4ed210813d667f0a2"
+        "2b8cb4f87580683eb4d760e4ed210813d667f0a2",
+        "df94c5b4d47eb3cc404d88b33a8fda237eaf4720"
       ],
       "sega-saturn:85ec9ca47d8f6807718151cbcca8b964": [
         "df94c5b4d47eb3cc404d88b33a8fda237eaf4720"
@@ -95473,7 +95474,6 @@
       "ad37f2de": "eb2a867578a05bbf8741e9fe7204301062df0cb8",
       "b0e03aa6": "0b6519209766ed883e3fca4c61bf866804c89004",
       "b28f7112": "de463b0577dfd1027bf7de523ff67a0fff861cdb",
-      "77228c84": "ac4b78d53c7a97da2451ca35498395d8dd1e3024",
       "9c9601ca": "5426d52e17e0ff9195fabbb42f704342e556d08e",
       "2c87c283": "e18c5e9ca21654dfd724aa54e625b386e6ffb2c5",
       "da9beacc": "beaf97c4a0e0792b8db65648f9dabb6a54ae0549",
@@ -95541,7 +95541,6 @@
       "ce2a2c77": "8cf0aa7f9dca4d77485e605fb0e2173a734633bf",
       "7325a518": "78c8e1c3c033b65758b7e53a9346b44d037fea7f",
       "065d69d0": "65a2f2cee74c316d5f40b68deda66787609df353",
-      "81f21918": "add40c002084e8e25768671877b2aa603aaf5cb1",
       "946c6bb8": "4e0202f8430cb4842184df7b5418e32620156c7b",
       "bfce92a3": "697551fcf9557ae33e31096b118a0c6769700a2e",
       "7c57bff1": "c9ee16e26e03496195a7bff151efbdd89da01204",
@@ -98682,7 +98681,6 @@
       "7389b815": "f1ad917e0affaeb8d2114c7ecd02b9f938c3cbd9",
       "62efc03d": "1cf9e67c2c703bb9961bbcdd39cd2c7e319a803b",
       "df558b58": "d2a5af338f09c5cbdd5d7628db5b9c075c69b616",
-      "416bf51a": "b48f44194fe918aaaec5298861479512b581d661",
       "a738ea1c": "3b71f43ff30f4b15b5cd85dd9e95ebc7e84eb5a3",
       "6f6d289b": "3773f52559d5ac4fc6d8aefe35bce58730ae8181",
       "945f9dc9": "cfe072921ee3fb93f688743f8beef89043c3e9ad",
@@ -101904,7 +101902,6 @@
       "0b805686": "6eddec30056cde7c664a0cf508dcad29353a12bb",
       "a3e573a0": "40ecf6138c99a0aba775ef93240b295025a45500",
       "2c3bcd32": "47d2ec4b342649e4c391043ab915d4435f9d180d",
-      "24bdb2db": "093f8698b54b78dcb701de2043f82639de51d63b",
       "72d2fd97": "6bf1ae9fb01915966b715836253592cbf588b406",
       "c48bf84b": "08325554623568bb9babadc10213bfc0b1151766",
       "2b629346": "9d6c9874c1d6a0c57a1345f211154fe1e494b55a",
@@ -102004,8 +102001,6 @@
       "616f5e40": "78632d0fe9dd77bf9a2264f192fae6f0af03a71c",
       "92ddefae": "18985a2079c7570c13cf39e0d001eef87538cd15",
       "c0c3a1fe": "3ae832c9800fcaa007eccfc48f24242967c111f8",
-      "082ecf86": "ed3a4cb264fff283209f10ae58c96c6090fed187",
-      "39075d41": "cc72dfcc964577cc29112ef368c28f55277c237c",
       "44295096": "b184f1c1febf66c8168fcae0b8aa37a5754f79db",
       "31c53421": "567c5b5054552a2771eafa7966844a146f0dde96",
       "d13aefe2": "f2fa8d8e940f1d91a1b1624013df5dca0bb1ee44",
@@ -102089,7 +102084,13 @@
       "8419990c": "cee76080884af97c20059da0eb1ca956a835f3d0",
       "3cacb086": "c7cc306fb921754ba00794153292d533cf0765ef",
       "0a4e2e07": "22bcfeb5b6c6481569b90db96aa3f4b5f06c8848",
-      "74b76447": "ecfc092fe6371dbf38e238a8ba5f90785b5db52d"
+      "74b76447": "ecfc092fe6371dbf38e238a8ba5f90785b5db52d",
+      "77228c84": "ac4b78d53c7a97da2451ca35498395d8dd1e3024",
+      "81f21918": "add40c002084e8e25768671877b2aa603aaf5cb1",
+      "416bf51a": "b48f44194fe918aaaec5298861479512b581d661",
+      "24bdb2db": "093f8698b54b78dcb701de2043f82639de51d63b",
+      "082ecf86": "ed3a4cb264fff283209f10ae58c96c6090fed187",
+      "39075d41": "cc72dfcc964577cc29112ef368c28f55277c237c"
     },
     "by_path_suffix": {
       ".variants/aa310.zip": [

emulators/amiberry.yml

@@ -1,9 +1,10 @@
 emulator: Amiberry
 type: standalone + libretro
+core_classification: official_port
 source: "https://github.com/BlitterStudio/amiberry"
 upstream: "https://github.com/tonioni/WinUAE"
-profiled_date: "2026-03-18"
+profiled_date: "2026-03-25"
-core_version: "v6.3.4"
+core_version: "v8.1.1"
 display_name: "Commodore - Amiga (Amiberry)"
 cores: [amiberry]
 systems:
@@ -12,111 +13,179 @@ systems:
   - commodore-cdtv
 
 notes: |
-  Amiberry is an Amiga emulator based on WinUAE, available as both
+  Amiberry is an Amiga emulator based on WinUAE, available as both standalone
-  standalone and libretro core. No built-in kickstart fallback — a real
+  and libretro core. No built-in kickstart — requires a real Kickstart ROM or
-  Kickstart ROM is required.
+  external AROS replacement files (aros-ext.bin + aros-rom.bin).
 
-  Core option "amiberry_kickstart" selects the ROM file:
+  Core option "amiberry_kickstart" overrides ROM selection: auto, kick.rom,
-  auto, kick.rom, kick13.rom, kick20.rom, kick31.rom, kick205.rom,
+  kick13.rom, kick20.rom, kick31.rom, kick205.rom, kick40068.A1200,
-  kick40068.A1200, kick40068.A4000, cd32.rom, cdtv.rom.
+  kick40068.A4000, cd32.rom, cdtv.rom. "auto" selects per model.
-  "auto" selects based on the model option.
+  ref: libretro/libretro.cpp:558,621-640
-  ref: BlitterStudio/amiberry/libretro/libretro.cpp:558,621-634
 
-  Standalone mode ships with data/ directory (UI icons, virtual keyboards,
+  Default model is A500 (KS 1.3). ROM search directories:
-  floppy sounds, AmigaTopaz.ttf font, gamecontrollerdb.txt). These are
+  save_dir/Kickstarts, system_dir/Kickstarts, system_dir/save-data/Kickstarts,
-  compiled into the standalone binary but the libretro core may look for
+  then system_dir as fallback.
-  them in the system directory.
+  ref: libretro/libretro.cpp:2740-2756
+
+  ROM identification uses SHA1 against WinUAE database (340+ entries) but does
+  not reject unknown ROMs. Cloanto encrypted ROMs supported with rom.key.
+
+  Munt MT-32/CM-32L emulation compiled in (WITH_MIDIEMU). ROMs loaded from
+  mt32-roms/ subdirectory of the ROM path.
+  ref: src/midiemu.cpp:120-157
+
+  WHDLoad autoboot requires whdboot/ directory in system_dir with boot-data.zip,
+  WHDLoad, AmiQuit, JST, whdload_db.xml. These ship with the standalone build
+  but must be obtained separately for the libretro core.
+  ref: libretro/libretro.cpp:1151-1184
 
 files:
-  # --- Required Kickstart ROMs (from .info) ---
+  # --- Kickstart ROMs (searched by find_kickstart_in_system_dir) ---
-  # ref: BlitterStudio/amiberry/libretro/libretro.cpp:558
+  # ref: libretro/libretro.cpp:1502-1565
-  # ref: WinUAE rommgr.cpp for ROM identification
 
-  - name: kick34005.A500
+  - name: kick13.rom
     system: commodore-amiga
     required: true
     size: 262144
-    crc32: c4f0f55f
+    note: "A500 Kickstart v1.3 rev 34.005, default for A500 model"
-    note: "A500 Kickstart v1.3 rev 34.5"
+    source_ref: "libretro/libretro.cpp:1516 candidates_a500"
-    source_ref: "libretro-super/dist/info/amiberry_libretro.info firmware0"
 
-  - name: kick37350.A600
+  - name: kick12.rom
-    system: commodore-amiga
-    required: true
-    size: 524288
-    crc32: 43b0df7b
-    note: "A600 Kickstart v2.05 rev 37.350"
-    source_ref: "amiberry_libretro.info firmware1"
-
-  - name: kick40068.A1200
-    system: commodore-amiga
-    required: true
-    size: 524288
-    crc32: 1483a091
-    note: "A1200 Kickstart v3.1 rev 40.68"
-    source_ref: "amiberry_libretro.info firmware2"
-
-  # --- Optional Kickstart ROMs ---
-
-  - name: kick33180.A500
     system: commodore-amiga
     required: false
     size: 262144
-    crc32: a6ce1636
+    note: "A500 Kickstart v1.2 rev 33.180, for A500OG model"
-    note: "A500 Kickstart v1.2 rev 33.180"
+    source_ref: "libretro/libretro.cpp:1515 candidates_a500og"
-    source_ref: "amiberry_libretro.info firmware3"
+
+  - name: kick20.rom
+    system: commodore-amiga
+    required: false
+    size: 524288
+    aliases: [kick204.rom]
+    note: "A500+ Kickstart v2.04 rev 37.175"
+    source_ref: "libretro/libretro.cpp:1517 candidates_a500p"
+
+  - name: kick205.rom
+    system: commodore-amiga
+    required: false
+    size: 524288
+    note: "A600 Kickstart v2.05 rev 37.350, also used for WHDLoad"
+    source_ref: "libretro/libretro.cpp:1518 candidates_a600, 1479 pick_whdload_kickstart"
+
+  - name: kick31.rom
+    system: commodore-amiga
+    required: false
+    size: 524288
+    note: "Kickstart v3.1 (generic), first candidate for A1200 and A4000"
+    source_ref: "libretro/libretro.cpp:1519-1520 candidates_a1200/a4000"
+
+  - name: kick40068.A1200
+    system: commodore-amiga
+    required: false
+    size: 524288
+    note: "A1200 Kickstart v3.1 rev 40.68, fallback after kick31.rom"
+    source_ref: "libretro/libretro.cpp:1519 candidates_a1200"
 
   - name: kick40068.A4000
     system: commodore-amiga
     required: false
     size: 524288
-    crc32: d6bae334
+    note: "A4000 Kickstart v3.1 rev 40.68, fallback after kick31.rom"
-    note: "A4000 Kickstart v3.1 rev 40.68"
+    source_ref: "libretro/libretro.cpp:1520 candidates_a4000"
-    source_ref: "amiberry_libretro.info firmware4"
 
-  - name: kick40060.CD32
+  - name: kick.rom
-    system: commodore-cd32
-    required: false
-    size: 524288
-    crc32: 1e62d4a5
-    note: "CD32 Kickstart v3.1 rev 40.60"
-    source_ref: "amiberry_libretro.info firmware5"
-
-  - name: kick40060.CD32.ext
-    system: commodore-cd32
-    required: false
-    size: 524288
-    crc32: 87746be2
-    note: "CD32 Extended ROM rev 40.60"
-    source_ref: "amiberry_libretro.info firmware6"
-
-  # --- Alternative names accepted by core option ---
-  # these are common user-facing names, same ROMs as above
-
-  - name: kick13.rom
     system: commodore-amiga
     required: false
-    note: "alias for kick34005.A500 (v1.3)"
+    note: "Generic name, any Kickstart ROM. Last resort fallback for all models."
-    source_ref: "libretro.cpp:630"
+    source_ref: "libretro/libretro.cpp:1510-1521 last in all candidate lists"
 
-  - name: kick34005.CDTV
+  # --- CD32 ROMs ---
+
+  - name: cd32.rom
+    system: commodore-cd32
+    required: false
+    size: 524288
+    aliases: [amiga-os-310-cd32.rom, kick40060.CD32]
+    note: "CD32 Kickstart v3.1 rev 40.60"
+    source_ref: "libretro/libretro.cpp:1521 candidates_cd32"
+
+  - name: cd32ext.rom
+    system: commodore-cd32
+    required: false
+    size: 524288
+    aliases: [amiga-ext-310-cd32.rom, "CD32 Extended.ROM"]
+    note: "CD32 extended ROM rev 40.60. Not needed if using a combined 1MB ROM."
+    source_ref: "libretro/libretro.cpp:1579 candidates_cd32 (find_ext_rom_in_system_dir)"
+
+  # --- CDTV ROMs ---
+
+  - name: cdtv.rom
     system: commodore-cdtv
     required: false
-    note: "CDTV extended ROM"
+    aliases: [kick34005.CDTV]
-    source_ref: "libretro.cpp:558 cdtv.rom option"
+    note: "CDTV extended ROM v1.00, used as kickstart candidate"
+    source_ref: "libretro/libretro.cpp:1522 candidates_cdtv"
 
-  # --- Standalone data files ---
+  - name: cdtvext.rom
+    system: commodore-cdtv
+    required: false
+    aliases: ["CDTV Extended.ROM"]
+    note: "CDTV extended ROM file"
+    source_ref: "libretro/libretro.cpp:1581 candidates_cdtv (find_ext_rom_in_system_dir)"
 
-  - name: AmigaTopaz.ttf
+  # --- AROS replacement ROMs ---
+  # ref: src/memory.cpp:1871-1930 load_kickstart_replacement
+
+  - name: aros-ext.bin
     system: commodore-amiga
     required: false
-    mode: standalone
+    hle_fallback: true
-    note: "Amiga Topaz font for UI rendering"
+    note: "AROS extended ROM replacement. Used when no Kickstart ROM is found."
-    source_ref: "BlitterStudio/amiberry/data/AmigaTopaz.ttf"
+    source_ref: "src/memory.cpp:1877 load_kickstart_replacement"
 
-  - name: gamecontrollerdb.txt
+  - name: aros-rom.bin
     system: commodore-amiga
     required: false
-    mode: standalone
+    hle_fallback: true
-    note: "SDL gamepad mapping database"
+    note: "AROS main ROM replacement. Used with aros-ext.bin as Kickstart fallback."
-    source_ref: "BlitterStudio/amiberry/controllers/gamecontrollerdb.txt"
+    source_ref: "src/memory.cpp:1910 load_kickstart_replacement"
+
+  # --- Cloanto key ---
+
+  - name: rom.key
+    system: commodore-amiga
+    required: false
+    note: "Decryption key for Cloanto Amiga Forever encrypted ROMs"
+    source_ref: "src/rommgr.cpp:1738 AMIROMTYPE1 decryption"
+
+  # --- Munt MT-32/CM-32L MIDI ROMs ---
+  # Located in mt32-roms/ subdirectory of the ROM path
+  # ref: src/midiemu.cpp:120-157 midi_emu_add_roms
+
+  - name: mt32-roms/mt32_control.rom
+    system: commodore-amiga
+    required: false
+    aliases: [mt32-roms/ctrl_mt32.rom, mt32-roms/MT32_CONTROL.rom]
+    note: "Roland MT-32 control ROM for Munt MIDI emulation"
+    source_ref: "src/midiemu.cpp:38-61 mt32ctl candidates, 151-156 load loop"
+
+  - name: mt32-roms/pcm_mt32.rom
+    system: commodore-amiga
+    required: false
+    aliases: [mt32-roms/mt32_pcm.rom, mt32-roms/MT32_PCM.rom, mt32-roms/PCM_MT32.rom]
+    note: "Roland MT-32 PCM ROM for Munt MIDI emulation"
+    source_ref: "src/midiemu.cpp:133-140 MT-32 PCM loading"
+
+  - name: mt32-roms/cm32l_control.rom
+    system: commodore-amiga
+    required: false
+    aliases: [mt32-roms/ctrl_cm32l.rom, mt32-roms/CM32L_CONTROL.rom]
+    note: "Roland CM-32L control ROM for Munt MIDI emulation"
+    source_ref: "src/midiemu.cpp:25-37 cm32lctl candidates, 151-156 load loop"
+
+  - name: mt32-roms/pcm_cm32l.rom
+    system: commodore-amiga
+    required: false
+    aliases: [mt32-roms/cm32l_pcm.rom, mt32-roms/PCM_CM32L.rom, mt32-roms/CM32L_PCM.rom]
+    note: "Roland CM-32L PCM ROM for Munt MIDI emulation"
+    source_ref: "src/midiemu.cpp:142-149 CM-32L PCM loading"

emulators/bsnes2014.yml

@@ -3,7 +3,7 @@ type: libretro
 core_classification: frozen_snapshot
 source: "https://github.com/libretro/bsnes2014"
 upstream: "https://github.com/bsnes-emu/bsnes"
-profiled_date: "2026-03-23"
+profiled_date: "2026-03-25"
 core_version: "v094"
 display_name: "Nintendo - SNES / SFC (bsnes 2014)"
 cores: [bsnes2014_accuracy, bsnes2014_balanced, bsnes2014_performance]
@@ -15,30 +15,23 @@ systems:
 
 notes: |
   Frozen at bsnes v094. Three build profiles: accuracy (dot-based PPU),
-  balanced, performance (scanline PPU). All 3 share the same 18 firmware
+  balanced, performance (scanline PPU). All 3 share the same 16 firmware
   files. Profiles only differ in PPU (sfc/profile-*.hpp), not coprocessors.
-  Performance .info is wrong (firmware_count=17, missing cx4.data.rom).
   SPC700 IPL ROM (64 bytes) embedded in target-libretro/libretro.cpp:31.
   No HLE fallback for any coprocessor in v094.
   Firmware loaded from system_dir via file::exists() + mmapstream.
-  DSP1 (non-b) names used via embedded database for specific SHA256-matched
+  No hash or size validation on any firmware file.
-  games; DSP1B names used via heuristic fallback for all DSP1/DSP1B games.
+  Libretro build uses heuristics only (ananke/heuristics/), not the SHA256
+  database (ananke/database/). All DSP1 games use DSP1B filenames via
+  heuristic fallback. The database dsp1.program.rom / dsp1.data.rom names
+  are only in the standalone build (target-ethos via ananke).
+  .info accuracy/balanced: firmware_count=18 (overcounts by 2, includes
+  phantom dsp1.* from unused database). Performance .info: firmware_count=17
+  (also missing cx4.data.rom).
   Upstream v094 source is contained within the libretro repo (sfc/, ananke/).
   bsnes-emu/bsnes is the modern rewrite (v115+).
 
 files:
-  - name: dsp1.program.rom
-    system: nintendo-snes
-    required: false
-    size: 6144
-    source_ref: "ananke/database/super-famicom.hpp:5658"
-
-  - name: dsp1.data.rom
-    system: nintendo-snes
-    required: false
-    size: 2048
-    source_ref: "ananke/database/super-famicom.hpp:5659"
-
   - name: dsp1b.program.rom
     system: nintendo-snes
     required: false

emulators/bsnes_mercury.yml

@@ -3,7 +3,7 @@ type: libretro
 core_classification: enhanced_fork
 source: "https://github.com/libretro/bsnes-mercury"
 upstream: "https://byuu.org/higan"
-profiled_date: "2026-03-23"
+profiled_date: "2026-03-25"
 core_version: "v094 (Mercury)"
 display_name: "Nintendo - SNES / SFC (bsnes-mercury)"
 cores: [bsnes_mercury_accuracy, bsnes_mercury_balanced, bsnes_mercury_performance]
@@ -22,7 +22,7 @@ notes: |
 
   Firmware loaded from system_dir via file::exists + mmapstream.
   No hash or size validation on any firmware file.
-  ref: target-libretro/libretro.cpp:241-263
+  ref: target-libretro/libretro.cpp:242-264
 
   firmware_appended: firmware can be appended to end of ROM file.
   ref: ananke/heuristics/super-famicom.hpp:83

emulators/gw.yml

@@ -2,7 +2,8 @@ emulator: "Game & Watch"
 type: libretro
 core_classification: pure_libretro
 source: "https://github.com/libretro/gw-libretro"
-profiled_date: "2026-03-21"
+upstream: "http://www.madrigaldesign.it/sim/"
+profiled_date: "2026-03-25"
 core_version: "Git"
 display_name: "Handheld Electronic (GW)"
 cores:

emulators/lowresnx.yml

@@ -3,7 +3,7 @@ type: libretro
 core_classification: official_port
 source: "https://github.com/timoinutilis/lowres-nx"
 upstream: "https://github.com/timoinutilis/lowres-nx"
-profiled_date: "2026-03-22"
+profiled_date: "2026-03-25"
 core_version: "v1.2"
 display_name: "LowRes NX"
 cores:
@@ -18,9 +18,10 @@ notes: |
   the same repository.
 
   retro_load_game() copies the .nx source code into memory
-  (libretro_main.c:490) and compiles it with the built-in interpreter.
+  (libretro_main.c:490-493) and compiles it with the built-in interpreter.
-  The boot intro is a string constant embedded in boot_intro.c. The core
+  The boot intro is a string constant embedded in boot_intro.c:26. Default
-  never accesses the system directory. No BIOS, firmware, or external
+  characters and charsets are compiled-in C arrays. The core never calls
+  RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY. No BIOS, firmware, or external
   files required.
 
 files: []

emulators/lrps2.yml

@@ -7,7 +7,7 @@ type: libretro
 core_classification: community_fork
 source: "https://github.com/libretro/ps2"
 upstream: "https://github.com/PCSX2/pcsx2"
-profiled_date: "2026-03-24"
+profiled_date: "2026-03-25"
 core_version: "Git"
 display_name: "Sony - PlayStation 2 (LRPS2)"
 cores: [lrps2]
@@ -17,12 +17,14 @@ bios_directory: "pcsx2/bios/"
 resources_directory: "pcsx2/resources/"
 
 notes: |
-  Hard fork of PCSX2 ported to libretro. BIOS detection is filename-agnostic: the core
+  Hard fork of PCSX2 (pre-Qt, 1.7-dev era) ported to libretro. x86_64 only.
-  scans pcsx2/bios/ for any file between 4-8 MB with a valid romdir structure containing
+  BIOS detection is filename-agnostic: scans pcsx2/bios/ for any file between 4-8 MB
-  RESET and ROMVER entries. The ROMVER entry determines region and version.
+  with a valid romdir structure (RESET + ROMVER entries). No hash validation.
-  Companion files (.rom1, .rom2, .nvm, .mec) derive their paths from the selected BIOS.
+  Companion files (.rom1, .rom2, .nvm, .mec) derive paths from the selected BIOS.
-  DEV9 (network adapter) and USB are stubbed in the libretro port.
+  DEV9 (network/HDD) and USB are stubbed in the libretro port.
-  GameIndex.yaml in pcsx2/resources/ provides per-game patches for compatibility.
+  Widescreen patches are largely compiled into the core (libretro/patches.cpp).
+  .info firmware_count=2 counts the bios folder and GameIndex.yaml.
+  .info description mentions EROM.BIN but no EROM loading path exists in the code.
 
 files:
   - name: "<bios>.bin"
@@ -32,7 +34,7 @@ files:
     min_size: 4194304
     max_size: 8388608
     validation: [size]
-    source_ref: "pcsx2/ps2/BiosTools.cpp:230-254,266-322"
+    source_ref: "pcsx2/ps2/BiosTools.cpp:231-254,267-322"
     note: >
       Scans pcsx2/bios/ for any file between 4 MB and 8 MB. Validates via romdir
       structure parsing (RESET + ROMVER entries). User selects BIOS via core option
@@ -43,7 +45,7 @@ files:
     required: false
     max_size: 4194304
     description: "DVD player ROM"
-    source_ref: "pcsx2/ps2/BiosTools.cpp:189-210,313"
+    source_ref: "pcsx2/ps2/BiosTools.cpp:190-211,314"
     note: >
       DVD player ROM. Tries <biospath>.rom1 (appended) then <biosbase>.rom1
       (extension replaced). Silently skipped if not found.
@@ -51,9 +53,9 @@ files:
   - name: "<bios>.rom2"
     path: "pcsx2/bios/"
     required: false
-    max_size: 4194304
+    max_size: 524288
     description: "Chinese ROM extension"
-    source_ref: "pcsx2/ps2/BiosTools.cpp:189-210,314"
+    source_ref: "pcsx2/ps2/BiosTools.cpp:190-211,315"
     note: >
       Chinese region ROM extension. Same naming convention as rom1.
       Only present on Chinese region consoles.

emulators/pcsx_rearmed.yml

@@ -3,7 +3,7 @@ type: libretro
 core_classification: embedded_hle
 source: "https://github.com/libretro/pcsx_rearmed"
 upstream: "https://github.com/notaz/pcsx_rearmed"
-profiled_date: "2026-03-24"
+profiled_date: "2026-03-25"
 core_version: "r25"
 display_name: "Sony - PlayStation (PCSX ReARMed)"
 cores: [pcsx_rearmed, pcsx_rearmed_neon, pcsx_rearmed_interpreter]

emulators/trident.yml

@@ -0,0 +1,39 @@
+emulator: trident
+display_name: "Nintendo - 3DS (Trident)"
+type: libretro
+core_classification: community_fork
+source: https://github.com/DanAlexMorton/3dsTrident
+upstream: https://github.com/wheremyfoodat/Panda3DS
+profiled_date: 2026-03-25
+core_version: git
+
+cores:
+  - trident
+
+systems:
+  - 3ds
+
+notes: >-
+  Libretro core wrapping Panda3DS, an HLE Nintendo 3DS emulator.
+  Shared font, Mii data, country list and bad word list are embedded in
+  the binary via CMRC and compiled-in headers. DSP firmware is loaded from
+  the game ROM at runtime, not from an external file.
+  DSP modes: HLE (default), LLE (Teakra), Null.
+  Files are resolved from the RetroArch save directory
+  (<save_dir>/Emulator Files/sysdata/), not the system directory.
+
+files:
+  - name: aes_keys.txt
+    description: AES encryption keys for decrypting encrypted 3DS ROMs
+    required: false
+    source_ref: >-
+      src/emulator.cpp:234,242-244 (path construction and existence check);
+      src/core/crypto/aes_engine.cpp:13-92 (loadKeys, parses key=value text);
+      src/core/loader/ncch.cpp:151-164 (panic if encrypted ROM loaded without keys)
+
+  - name: seeddb.bin
+    description: seed database for seed-encrypted 3DS games
+    required: false
+    source_ref: >-
+      src/emulator.cpp:235,246-248 (path construction and existence check);
+      src/core/crypto/aes_engine.cpp:94-153 (setSeedPath, loadSeeds, getSeedFromDB)

emulators/tyrquake.yml

@@ -1,27 +1,25 @@
 emulator: TyrQuake
 type: libretro
+core_classification: game_engine
 source: "https://github.com/libretro/tyrquake"
-profiled_date: "2026-03-18"
+upstream: "http://disenchant.net/tyrquake/"
+profiled_date: "2026-03-25"
 core_version: "v0.62"
 display_name: "Quake (TyrQuake)"
 cores: [tyrquake]
 systems: [quake]
-verification: existence
 notes: >
-  Quake engine source port. Plays Quake (id1), mission packs Scourge of Armagon
+  Quake engine source port by Kevin Shanahan (Tyrann). Plays Quake (id1), mission
-  (hipnotic) and Dissolution of Eternity (rogue), Quoth mod, and custom mods via
+  packs Scourge of Armagon (hipnotic) and Dissolution of Eternity (rogue), Quoth
-  -game parameter. The core accepts .pak extensions (retro_get_system_info sets
+  mod, and custom mods via -game parameter. Content is loaded directly from the
-  valid_extensions = "pak"). Content is loaded directly from the PAK file path -
+  PAK file path — the directory containing the PAK becomes basedir
-  the directory containing the PAK becomes basedir (libretro.c:988,1050).
+  (libretro.c:988,1050). The engine auto-detects game variant by checking the
-  The engine auto-detects game variant by checking the content path for id1,
+  content path for id1, hipnotic, rogue, or quoth substrings
-  hipnotic, rogue, or quoth substrings (libretro.c:1030-1070) and passes the
+  (libretro.c:1030-1070). All engine assets (gfx/palette.lmp, gfx/colormap.lmp,
-  corresponding command-line flag. For non-standard paths it uses -game with the
+  gfx.wad, textures, models, sounds) are loaded from within PAK files via
-  directory basename. PAK files are game data (maps, textures, models, sounds)
+  COM_AddGameDirectory (common.c:1709), which tries pak0.pak through pak9.pak in
-  shipped with the original retail game, not engine firmware. The engine checks
+  both lowercase and uppercase. The core never calls
-  for gfx/pop.lmp inside pak0.pak to distinguish registered vs shareware
+  RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY. BGM as OGG tracks in music/ subfolder
-  (common.c:974-991). COM_AddGameDirectory (common.c:1709) loads pak0.pak through
+  of each game directory.
-  pak9.pak sequentially from the game directory, trying both lowercase and
-  uppercase filenames. No engine data files are required in the RetroArch system
-  directory. The core needs no BIOS or firmware.
 
 files: []

emulators/uae4arm.yml

@@ -1,8 +1,64 @@
-emulator: "uae4arm"
+emulator: uae4arm
-type: alias
+type: libretro
-alias_of: "puae"
+core_classification: community_fork
-profiled_date: "2026-03-18"
+cores: [uae4arm]
+source: "https://github.com/libretro/uae4arm-libretro"
+upstream: "https://github.com/PandTomB/uae4arm"
+profiled_date: "2026-03-25"
 core_version: "v0.5"
 display_name: "Commodore - Amiga (UAE4ARM)"
-note: "This core uses the same BIOS/firmware as puae. See emulators/puae.yml for details."
+systems:
-files: []
+  - commodore-amiga
+
+notes: |
+  ARM-optimized Amiga emulator by TomB, ported to libretro by Chips-fr.
+  Based on an older uae4arm version, intended for low-powered ARM hardware
+  where PUAE cannot maintain full speed.
+
+  Core options expose three models: A500, A600, A1200. Each selects its
+  Kickstart ROM automatically. Extended ROMs (CDTV/CD32) can be set via
+  .uae config files but CD32/CDTV hardware emulation is absent from
+  this port (no akiko chip, CD support listed as missing).
+
+  Built-in AROS Kickstart replacement used as fallback when no ROM is found.
+
+  Cloanto-encrypted ROMs require rom.key in the system directory.
+
+files:
+  - name: "kick34005.A500"
+    description: "Amiga 500 Kickstart v1.3 rev 34.005"
+    required: false
+    hle_fallback: true
+    source_ref: "libretro/core/libretro-core.cpp:73,420 src/memory.cpp:2080-2180"
+
+  - name: "kick40063.A600"
+    description: "Amiga 600 Kickstart v3.1 rev 40.063"
+    required: false
+    hle_fallback: true
+    source_ref: "libretro/core/libretro-core.cpp:74,391 src/memory.cpp:2080-2180"
+
+  - name: "kick40068.A1200"
+    description: "Amiga 1200 Kickstart v3.1 rev 40.068"
+    required: false
+    hle_fallback: true
+    source_ref: "libretro/core/libretro-core.cpp:75,405 src/memory.cpp:2080-2180"
+
+  - name: "kick34005.CDTV"
+    description: "CDTV extended ROM v1.00 rev 34.005"
+    required: false
+    source_ref: "src/memory.cpp:1931-1971 (EXTENDED_ROM_CDTV via romextfile)"
+
+  - name: "kick40060.CD32"
+    description: "CD32 Kickstart v3.1 rev 40.060"
+    required: false
+    source_ref: "src/memory.cpp:2080-2180 (loaded via romfile from .uae config)"
+
+  - name: "kick40060.CD32.ext"
+    description: "CD32 extended ROM rev 40.060"
+    required: false
+    source_ref: "src/memory.cpp:1931-1971 (EXTENDED_ROM_CD32 via romextfile)"
+
+  - name: "rom.key"
+    description: "Cloanto Amiga Forever decryption key"
+    required: false
+    source_ref: "src/memory.cpp:598-613,625-700 (addkeydir, load_keyring)"

emulators/ume2015.yml

@@ -1,8 +1,477 @@
-emulator: "ume2015"
+emulator: UME 2015
-type: alias
+type: libretro
-alias_of: "mame2016"
+core_classification: frozen_snapshot
-profiled_date: "2026-03-18"
+source: "https://github.com/libretro/mame2015-libretro"
-core_version: "0.160"
+upstream: "https://github.com/mamedev/mame/tree/mame0159"
+logo: "https://raw.githubusercontent.com/mamedev/mame/master/docs/source/images/MAMElogo.svg"
+profiled_date: "2026-03-25"
+core_version: "0.159"
 display_name: "Multi (UME 2015)"
-note: "This core uses the same BIOS/firmware as mame2016. See emulators/mame2016.yml for details."
+mame_version: "0.159"
-files: []
+
+cores:
+  - ume2015
+systems:
+  - snk-neogeo-mvs
+  - snk-neogeo-aes
+  - igs-pgm
+  - sega-naomi
+  - sega-naomi2
+  - sega-naomigd
+  - sammy-atomiswave
+  - sega-stv
+  - sega-lindbergh
+  - sega-hikaru
+  - sega-chihiro
+  - sega-triforce
+  - deco-cassette
+  - nintendo-playch10
+  - sega-megaplay
+  - sega-megatech
+  - nintendo-sfcbox
+  - nintendo-nss
+  - philips-cdi
+  - commodore-cubo
+  - namco-system246
+  - namco-system256
+  - namco-system573
+  - konami-viper
+  - taito-gnet
+  - super-kaneko-nova
+  - capcom-zn1
+  - capcom-zn2
+  - konami-gv
+  - panasonic-3do
+  - hyper-neogeo64
+  - konami-twinkle
+
+notes: |
+  Universal Machine Emulator — combined MAME + MESS before the official
+  merge at MAME 0.162. Same repo as mame2015 (mame2015-libretro), built
+  with -DWANT_UME including both mame.mak and mess.mak. 69 arcade BIOS
+  root sets (identical to mame2015), plus 619 MESS computer/console
+  drivers. Source version.c says 0.159, .info claims 0.160.
+
+  Paths under system_dir/ume2015/ (samples, artwork, cheat, hash, ini).
+  Software list hash XMLs in system_dir/ume2015/hash/ (375 files from
+  repo hash/ directory, required for MESS software list support).
+  Per-game XML cheats in system_dir/ume2015/cheat/.
+  hiscore.dat loaded via f.open("hiscore", ".dat") without explicit
+  search path (libretro-specific path code disabled via #if 0).
+
+  ROM naming follows MAME 0.159 conventions.
+
+files:
+  # Data files (system_dir/ume2015/)
+  - name: hiscore.dat
+    required: false
+    category: game_data
+    source_ref: "src/emu/hiscore.c:335-337"
+    note: "high score definitions, external file, not embedded"
+
+  # SNK Neo Geo MVS/AES
+  - name: neogeo.zip
+    required: true
+    category: bios_zip
+    system: snk-neogeo-mvs
+    source_ref: "src/mame/drivers/neogeo.c:1529"
+
+  # IGS PGM
+  - name: pgm.zip
+    required: true
+    category: bios_zip
+    system: igs-pgm
+    source_ref: "src/mame/drivers/pgm.c:4147"
+
+  # Sega Naomi / Naomi 2 / Naomi GD-ROM / Atomiswave
+  - name: naomi.zip
+    required: true
+    category: bios_zip
+    system: sega-naomi
+    source_ref: "src/mame/drivers/naomi.c:8960"
+
+  - name: naomi2.zip
+    required: true
+    category: bios_zip
+    system: sega-naomi2
+    source_ref: "src/mame/drivers/naomi.c:8965"
+
+  - name: naomigd.zip
+    required: true
+    category: bios_zip
+    system: sega-naomigd
+    source_ref: "src/mame/drivers/naomi.c:8966"
+
+  - name: awbios.zip
+    required: true
+    category: bios_zip
+    system: sammy-atomiswave
+    source_ref: "src/mame/drivers/naomi.c:9275"
+
+  - name: hod2bios.zip
+    required: false
+    category: bios_zip
+    source_ref: "src/mame/drivers/naomi.c:8961"
+    note: "game-specific BIOS for House of the Dead 2"
+
+  - name: f355dlx.zip
+    required: false
+    category: bios_zip
+    source_ref: "src/mame/drivers/naomi.c:8962"
+    note: "game-specific BIOS for Ferrari F355 Challenge deluxe"
+
+  - name: f355bios.zip
+    required: false
+    category: bios_zip
+    source_ref: "src/mame/drivers/naomi.c:8963"
+    note: "game-specific BIOS for Ferrari F355 Challenge twin"
+
+  - name: airlbios.zip
+    required: false
+    category: bios_zip
+    source_ref: "src/mame/drivers/naomi.c:8964"
+    note: "game-specific BIOS for Airline Pilots deluxe"
+
+  # Sega ST-V
+  - name: stvbios.zip
+    required: true
+    category: bios_zip
+    system: sega-stv
+    source_ref: "src/mame/drivers/stv.c:3042"
+
+  # Sega Hikaru / Chihiro / Triforce / Lindbergh
+  - name: hikaru.zip
+    required: true
+    category: bios_zip
+    system: sega-hikaru
+    source_ref: "src/mame/drivers/hikaru.c:744"
+
+  - name: chihiro.zip
+    required: true
+    category: bios_zip
+    system: sega-chihiro
+    source_ref: "src/mame/drivers/chihiro.c:2192"
+
+  - name: triforce.zip
+    required: true
+    category: bios_zip
+    system: sega-triforce
+    source_ref: "src/mame/drivers/triforce.c:1021"
+
+  - name: lindbios.zip
+    required: true
+    category: bios_zip
+    system: sega-lindbergh
+    source_ref: "src/mame/drivers/lindbergh.c:569"
+
+  # DECO Cassette
+  - name: decocass.zip
+    required: true
+    category: bios_zip
+    system: deco-cassette
+    source_ref: "src/mame/drivers/decocass.c:1647"
+
+  # Nintendo arcade
+  - name: playch10.zip
+    required: true
+    category: bios_zip
+    system: nintendo-playch10
+    source_ref: "src/mame/drivers/playch10.c:1639"
+
+  - name: nss.zip
+    required: true
+    category: bios_zip
+    system: nintendo-nss
+    source_ref: "src/mame/drivers/nss.c:1058"
+
+  - name: sfcbox.zip
+    required: true
+    category: bios_zip
+    system: nintendo-sfcbox
+    source_ref: "src/mame/drivers/sfcbox.c:572"
+
+  # Sega Mega Drive arcade
+  - name: megaplay.zip
+    required: true
+    category: bios_zip
+    system: sega-megaplay
+    source_ref: "src/mame/drivers/megaplay.c:942"
+
+  - name: megatech.zip
+    required: true
+    category: bios_zip
+    system: sega-megatech
+    source_ref: "src/mame/drivers/megatech.c:1393"
+
+  # Philips CD-i
+  - name: cdibios.zip
+    required: true
+    category: bios_zip
+    system: philips-cdi
+    source_ref: "src/mame/drivers/cdi.c:611"
+
+  # Commodore Cubo (CD32-based)
+  - name: cubo.zip
+    required: true
+    category: bios_zip
+    system: commodore-cubo
+    source_ref: "src/mame/drivers/cubo.c:1362"
+
+  # Namco boards
+  - name: sys246.zip
+    required: true
+    category: bios_zip
+    system: namco-system246
+    source_ref: "src/mame/drivers/namcops2.c:672"
+
+  - name: sys256.zip
+    required: true
+    category: bios_zip
+    system: namco-system256
+    source_ref: "src/mame/drivers/namcops2.c:705"
+
+  - name: sys573.zip
+    required: true
+    category: bios_zip
+    system: namco-system573
+    source_ref: "src/mame/drivers/ksys573.c:4678"
+
+  # Konami
+  - name: kviper.zip
+    required: true
+    category: bios_zip
+    system: konami-viper
+    source_ref: "src/mame/drivers/viper.c:2609"
+
+  - name: konamigv.zip
+    required: true
+    category: bios_zip
+    system: konami-gv
+    source_ref: "src/mame/drivers/konamigv.c:822"
+
+  - name: konamigx.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/konamigx.c:3775"
+
+  - name: gq863.zip
+    required: true
+    category: bios_zip
+    system: konami-twinkle
+    source_ref: "src/mame/drivers/twinkle.c:1330"
+
+  # Taito
+  - name: taitogn.zip
+    required: true
+    category: bios_zip
+    system: taito-gnet
+    source_ref: "src/mame/drivers/taitogn.c:1081"
+
+  - name: taitotz.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/taitotz.c:2951"
+
+  - name: taitofx1.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/zn.c:4906"
+
+  # PSX-based arcade boards (ZN)
+  - name: cpzn1.zip
+    required: true
+    category: bios_zip
+    system: capcom-zn1
+    source_ref: "src/mame/drivers/zn.c:4800"
+
+  - name: cpzn2.zip
+    required: true
+    category: bios_zip
+    system: capcom-zn2
+    source_ref: "src/mame/drivers/zn.c:4823"
+
+  - name: atpsx.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/zn.c:4853"
+
+  - name: acpsx.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/zn.c:4862"
+
+  - name: tps.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/zn.c:4873"
+
+  - name: vspsx.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/zn.c:4896"
+
+  - name: psarc95.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/zn.c:4935"
+
+  - name: atluspsx.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/zn.c:4961"
+
+  # Super Kaneko Nova System
+  - name: skns.zip
+    required: true
+    category: bios_zip
+    system: super-kaneko-nova
+    source_ref: "src/mame/drivers/suprnova.c:1734"
+
+  - name: mac2bios.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/macs.c:747"
+
+  - name: macsbios.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/macs.c:746"
+
+  # Panasonic 3DO
+  - name: 3dobios.zip
+    required: true
+    category: bios_zip
+    system: panasonic-3do
+    source_ref: "src/mame/drivers/3do.c:253"
+
+  # Hyper Neo-Geo 64
+  - name: hng64.zip
+    required: true
+    category: bios_zip
+    system: hyper-neogeo64
+    source_ref: "src/mame/drivers/hng64.c:1991"
+
+  # Arcadia Systems
+  - name: ar_bios.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/arcadia.c:963"
+
+  # American Laser Games
+  - name: alg_bios.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/alg.c:772"
+
+  # Aleck64 (N64-based)
+  - name: aleck64.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/aleck64.c:1161"
+
+  # Atari System 1
+  - name: atarisy1.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/atarisy1.c:2368"
+
+  # Exidy Max-A-Flex
+  - name: maxaflex.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/maxaflex.c:536"
+
+  # Crystal System
+  - name: crysbios.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/crystal.c:1134"
+
+  # Galaxy Games
+  - name: galgbios.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/tmaster.c:1850"
+
+  # Aristocrat MK5/MK6
+  - name: aristmk5.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/aristmk5.c:739"
+
+  - name: aristmk6.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/aristmk6.c:224"
+
+  - name: mk6nsw11.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/aristmk6.c:225"
+
+  # Pinball
+  - name: allied.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/allied.c:711"
+
+  - name: gp_110.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/gp_1.c:531"
+
+  - name: gts1.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/gts1.c:978"
+
+  - name: gts1s.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/gts1.c:981"
+
+  # Other BIOS root sets
+  - name: bubsys.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/nemesis.c:2707"
+
+  - name: isgsm.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/segas16b.c:7501"
+
+  - name: iteagle.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/iteagle.c:315"
+
+  - name: pyson.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/pyson.c:251"
+
+  - name: sammymdl.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/sigmab98.c:2277"
+
+  - name: shtzone.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/shtzone.c:121"
+
+  - name: su2000.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/su2000.c:296"
+
+  - name: tourvis.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/tourvis.c:612"
+
+  - name: v4bios.zip
+    required: true
+    category: bios_zip
+    source_ref: "src/mame/drivers/mpu4vid.c:3655"

emulators/uw8.yml

@@ -1,13 +1,16 @@
 emulator: MicroW8
-profiled_date: "2026-03-18"
+profiled_date: "2026-03-25"
 core_version: "0.2.2"
 display_name: "MicroW8"
 type: game
+core_classification: pure_libretro
+source: https://github.com/libretro/uw8-libretro
+upstream: https://github.com/exoticorn/microw8
 cores: [uw8]
 systems: []
 files: []
 notes: >
-  MicroW8 is a WebAssembly-based fantasy console with a 320x240 screen,
+  WebAssembly-based fantasy console. 320x240 screen, 32-color palette,
-  32-color palette, and a 256KB memory limit. Programs are compiled to
+  256KB memory. The WASM runtime (platform + loader modules) is compiled
-  compact WASM modules (.uw8 format). The runtime is fully self-contained
+  to C via wasm2c and embedded in the binary. No external files required.
-  with no external dependencies. No BIOS or system directory files required.
+  firmware_count=0 in .info is correct.

emulators/uxn.yml

@@ -1,15 +1,19 @@
 emulator: UXN
-type: game
+type: libretro
-source: "https://github.com/libretro/uxn"
+core_classification: community_fork
-profiled_date: "2026-03-18"
+source: "https://codeberg.org/iyzsong/uxn-libretro"
-core_version: "0.0.0"
+upstream: "https://github.com/chmod222/zuxn"
+profiled_date: "2026-03-25"
+core_version: "0.0.1"
 display_name: "Uxn / Varvara (zuxn)"
 cores: [uxn]
 systems: []
 files: []
+exclusion_note: >
+  Uxn/Varvara is a software-defined stack machine with 64KB of memory.
+  The VM has no firmware or BIOS. ROMs compiled from Uxntal assembly are
+  loaded directly via libretro game_info. The .info declares no firmware.
 notes: >
-  Libretro port of the Varvara/UXN stack machine designed by Hundred Rabbits.
+  Libretro wrapper around the zuxn library (Zig implementation of the
-  UXN is a portable 8-bit virtual computer with 64KB of memory and a
+  Uxn/Varvara spec by Hundred Rabbits). The file device in Varvara handles
-  minimal instruction set. Loads .rom files compiled from Uxntal assembly.
+  ROM-initiated I/O but does not load system files from the system directory.
-  The VM is entirely software-defined with no firmware or BIOS dependencies.
-  No system directory files required.

emulators/uzem.yml

@@ -1,46 +1,38 @@
 emulator: uzem
 type: libretro
+core_classification: pure_libretro
 source: "https://github.com/libretro/libretro-uzem"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/Uzebox/uzebox"
-core_version: "3.1"
+profiled_date: "2026-03-25"
-display_name: "Uzem (Uzebox)"
+core_version: "v2.0"
 display_name: "Uzebox (Uzem)"
 cores:
   - uzem
 systems:
   - uzebox
 
-# Uzem emulates the Uzebox, an open-source 8-bit game console based on an
+# No BIOS or firmware files required. The Uzebox is an open-source 8-bit game
-# ATmega644 AVR microcontroller. The console was designed by Alec Bourque (Uze)
+# console (ATmega644 AVR MCU) with no proprietary firmware. Games are
-# and all hardware/software is open-source.
+# self-contained .uze files loaded directly into progmem
+# (uzem_libretro.cpp:254-286, "UZEBOX" magic header + RomHeader + program data).
 #
-# No BIOS or firmware files are required. The core loads .uze ROM files directly
+# The libretro core does not call RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY.
-# into progmem (uzem_libretro.cpp:254-286). The .uze format includes a "UZEBOX"
+# SD card emulation uses GET_CORE_ASSETS_DIRECTORY (uzem_libretro.cpp:186-192)
-# magic header followed by a RomHeader struct (uzerom.h) and raw program data.
+# for optional game data via virtual FAT16 filesystem (SDEmulator.cpp).
+# EEPROM is handled via RETRO_MEMORY_SAVE_RAM (uzem_libretro.cpp:407-408).
 #
-# The standalone uzem (oldsrcs/uzem.cpp:90) has a --boot flag that sets PC to
+# The standalone uzem supports --boot (PC=0xF000) for bootloader mode
-# 0xF000 for bootloader mode, but this is NOT exposed in the libretro port.
+# (uzem.cpp:206) and .hex format loading, neither exposed in the libretro port.
-# The libretro core has no retro_environment calls for RETRO_ENVIRONMENT_SET_SYSTEM_DIR
-# or any firmware loading paths.
 #
-# SD card emulation uses RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY
+# The .info file declares no firmware entries (firmware_count absent).
-# (uzem_libretro.cpp:186-192) for virtual FAT16 filesystem access via SDEmulator.cpp,
-# but this is optional game data, not system firmware.
-#
-# The .info file declares no firmware entries.
 
 files: []
 
 notes:
   open_source_console: >
-    The Uzebox is fully open-source hardware and software. There is no proprietary
+    Fully open-source hardware and software designed by Alec Bourque.
-    BIOS or bootloader required. Games are self-contained .uze files that include
+    No proprietary BIOS or bootloader. Games are self-contained .uze files.
-    all code needed to run on the ATmega644 MCU emulation.
   sd_card: >
     Some games use SD card access for loading assets. The core reads from the
-    libretro core assets directory to emulate a FAT16 SD card, but this is game
+    libretro core assets directory to emulate a FAT16 SD card (game data, not
-    data, not system firmware.
+    system firmware).
-  standalone_bootloader: >
-    The original standalone uzem supports a --boot flag for bootloader mode
-    (PC starts at 0xF000 instead of 0x0000). This feature is not available in
-    the libretro port.

emulators/vaporspec.yml

@@ -1,14 +1,17 @@
 emulator: VaporSpec
-type: game
+type: libretro
-source: "https://github.com/libretro/libretro-vaporspec"
+core_classification: official_port
-profiled_date: "2026-03-18"
+source: "https://github.com/minkcv/vm"
+upstream: "https://github.com/minkcv/vm"
+profiled_date: "2026-03-25"
 core_version: "GIT"
 display_name: "VaporSpec"
 cores: [vaporspec]
-systems: []
+systems: [vaporspec]
 files: []
 notes: >
-  Fantasy console for libretro inspired by retro hardware aesthetics.
+  Fantasy console with fixed specs (256x192 display, 4-channel audio,
-  Provides a virtual machine with fixed specs (256x192 display, 4-channel
+  256-color palette). Runs .vaporbin cartridge bundles containing code
-  audio) for running homebrew .vaporbin cartridge files.
+  and optional ROM data. All content is self-contained in the bundle
-  No BIOS, firmware, or system directory files required.
+  passed by the frontend; no system directory files loaded.
+  firmware_count=0 confirmed by code analysis.

emulators/vba_next.yml

@@ -1,7 +1,9 @@
 emulator: VBA-Next
 type: libretro
+core_classification: frozen_snapshot
 source: "https://github.com/libretro/vba-next"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/visualboyadvance-m/visualboyadvance-m"
+profiled_date: "2026-03-25"
 core_version: "SVN"
 display_name: "Nintendo - Game Boy Advance (VBA Next)"
 cores:
@@ -10,64 +12,34 @@ systems:
   - nintendo-gba
 
 notes: |
-  VBA-Next is a Game Boy Advance emulator forked from VBA-M, optimized for
+  Frozen snapshot of VBA-M circa 2011, optimized for libretro by Squarepusher.
-  libretro. It includes a built-in HLE BIOS (myROM array in src/gba.cpp:8423)
-  that handles all standard SWI calls, so no external BIOS file is needed for
-  most games.
 
-  BIOS loading is gated behind HAVE_HLE_BIOS (defined in build/Makefile.common)
+  Built-in HLE BIOS (myROM array, src/gba.cpp:8423) handles all standard SWI
-  and controlled by core option vbanext_bios (default: enabled). When enabled,
+  calls. No external BIOS file needed for most games.
-  the libretro port looks for gba_bios.bin in RetroArch's system directory
-  (libretro/libretro.cpp:198-203). CPUInit() loads the file via utilLoad(),
-  validates it is exactly 0x4000 bytes (16 KB), and sets useBios = true
-  (src/gba.cpp:12413-12443). If loading fails or the option is off, the HLE
-  BIOS (myROM) is memcpy'd into the bios buffer instead.
 
-  CPUIsGBABios() accepts extensions: .gba, .agb, .bin, .bios, .rom
+  BIOS loading gated by HAVE_HLE_BIOS (build/Makefile.common:3) and core option
+  vbanext_bios (default: enabled). When enabled, retro_init resolves gba_bios.bin
+  in system_dir (libretro/libretro.cpp:198-202). CPUInit loads via utilLoad(),
+  validates size == 0x4000, sets useBios = true (src/gba.cpp:12430-12438). On
+  failure, myROM is memcpy'd as HLE fallback (src/gba.cpp:12443).
+
+  With real BIOS, execution starts at 0x00000000 (BIOS entry point). Without,
+  jumps to 0x08000000 (ROM entry), skipping boot animation
+  (src/gba.cpp:12657-12675).
+
+  CPUIsGBABios accepts extensions: .gba, .agb, .bin, .bios, .rom
   (src/gba.cpp:8851-8873).
 
-  When useBios is true and skipBios is false, execution starts at 0x00000000
+  Upstream VBA-M CPUInit (src/core/gba/gba.cpp:3674-3702) is functionally
-  (real BIOS entry). Otherwise it jumps straight to 0x08000000 (ROM entry),
+  identical. No divergences in BIOS handling.
-  skipping the boot animation (src/gba.cpp:12657-12675).
-
-  The HLE BIOS covers: SoftReset, RegisterRamReset, Halt, VBlankIntrWait,
-  Div, Sqrt, ArcTan, ArcTan2, CpuSet, CpuFastSet, GetBiosChecksum,
-  BgAffineSet, ObjAffineSet, BitUnPack, LZ77UnComp (WRAM/VRAM),
-  HuffUnComp, RLUnComp (WRAM/VRAM), Diff8bitUnFilter (WRAM/VRAM),
-  Diff16bitUnFilter, MidiKey2Freq, SndDriverJmpTableCopy
-  (src/gba.cpp:2369-2578).
-
-  Some per-game overrides in gbaover[] (libretro/libretro.cpp:235) have a
-  useBios field, but all entries currently set it to 0 (no game forces BIOS).
 
 files:
-  # -------------------------------------------------------
-  # Game Boy Advance - BIOS (optional, HLE fallback)
-  # -------------------------------------------------------
   - name: gba_bios.bin
     system: nintendo-gba
     required: false
     hle_fallback: true
-    size: 16384  # 16 KB (0x4000)
+    size: 16384
-    note: "GBA BIOS. Optional -- HLE replacement (myROM) handles all standard SWI calls. Real BIOS adds startup logo and may improve edge-case accuracy."
+    validation: [size]
-    source_ref: "libretro/libretro.cpp:198-203, src/gba.cpp:12413-12443"
+    description: "GBA BIOS"
-
+    note: "Optional. HLE replacement handles all standard SWI calls. Real BIOS adds startup logo and may improve edge-case accuracy."
-platform_details:
+    source_ref: "libretro/libretro.cpp:198-202, src/gba.cpp:12430-12438"
-  gba:
-    bios_size: 16384  # 0x4000
-    hle_bios: true
-    source_ref: "src/gba.cpp:8423 (myROM), src/gba.cpp:2369-2578 (SWI handlers)"
-    notes: |
-      BIOS buffer is always allocated at 0x4000 bytes (src/gba.cpp:8963).
-      If the real BIOS loads successfully (exactly 0x4000 bytes), useBios is
-      set to true and CPUReset starts at address 0x00000000 with IRQ disabled.
-      Otherwise myROM (built-in HLE stub) is copied in and execution starts
-      at 0x08000000 with standard register init.
-
-      The core option vbanext_bios defaults to "enabled", so if gba_bios.bin
-      is present in the system directory it will be loaded automatically.
-
-      BIOS reads at runtime go through the memory map (src/gba.cpp:792-1076).
-      Address range 0x0000-0x3FFF maps to the bios buffer. A biosProtected[4]
-      array at 0x00f029e1 is returned when reading outside the current PC
-      region, matching real GBA BIOS protection behavior.

emulators/vbam.yml

@@ -1,8 +1,49 @@
-emulator: "vbam"
+emulator: VBA-M
-type: alias
+type: "standalone + libretro"
-alias_of: "vba_next"
+core_classification: official_port
-profiled_date: "2026-03-18"
+source: "https://github.com/libretro/vbam-libretro"
+upstream: "https://github.com/visualboyadvance-m/visualboyadvance-m"
+profiled_date: "2026-03-25"
 core_version: "2.1.4"
 display_name: "Nintendo - Game Boy Advance (VBA-M)"
-note: "This core uses the same BIOS/firmware as vba_next. See emulators/vba_next.yml for details."
+cores:
-files: []
+  - vbam
+systems:
+  - nintendo-gba
+  - nintendo-gb
+  - nintendo-gbc
+
+notes: |
+  Supports GB, GBC, GBA, and SGB (borders/palette only).
+  BIOS usage controlled by vbam_usebios core option (default: disabled).
+  Built-in HLE BIOS (myROM array) handles GBA SWI calls without external file.
+  GB/GBC boot sequence skipped when BIOS absent.
+  Upstream repo includes the libretro port in src/libretro/.
+
+files:
+  - name: gba_bios.bin
+    system: nintendo-gba
+    required: false
+    hle_fallback: true
+    size: 16384
+    validation: [size]
+    description: "GBA BIOS"
+    source_ref: "src/gba/GBA.cpp:3262-3272 (CPUInit size check), src/libretro/libretro.cpp:846-851 (gba_init)"
+
+  - name: gb_bios.bin
+    system: nintendo-gb
+    required: false
+    hle_fallback: true
+    size: 256
+    validation: [size]
+    description: "Game Boy boot ROM"
+    source_ref: "src/gb/GB.cpp:2172-2192 (gbCPUInit size check), src/libretro/libretro.cpp:861-879 (gb_init)"
+
+  - name: gbc_bios.bin
+    system: nintendo-gbc
+    required: false
+    hle_fallback: true
+    size: 2304
+    validation: [size]
+    description: "Game Boy Color boot ROM"
+    source_ref: "src/gb/GB.cpp:2172-2192 (gbCPUInit size check), src/libretro/libretro.cpp:861-879 (gb_init)"

emulators/vecx.yml

@@ -1,7 +1,9 @@
 emulator: vecx
 type: libretro
+core_classification: community_fork
 source: "https://github.com/libretro/libretro-vecx"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/jhawthorn/vecx"
+profiled_date: "2026-03-25"
 core_version: "SVN"
 display_name: "GCE - Vectrex (vecx)"
 cores:

emulators/vemulator.yml

@@ -1,7 +1,9 @@
 emulator: VeMUlator
 type: libretro
+core_classification: official_port
 source: "https://github.com/libretro/vemulator-libretro"
-profiled_date: "2026-03-18"
+upstream: "closed-source Android app (removed from Google Play ~2020)"
+profiled_date: "2026-03-25"
 core_version: "0.1"
 display_name: "VeMUlator"
 cores:
@@ -10,32 +12,18 @@ systems:
   - sega-vmu
 
 notes: |
-  VeMUlator is a Sega Dreamcast Visual Memory Unit (VMU/VMS) emulator ported
+  Sega Dreamcast VMU/VMS emulator. Same author (Mahmoud Jaoune) ported
-  from Android (Java) to C++ for libretro. It emulates the Sanyo LC8670
+  the original Android Java app to C++ for libretro. Emulates the Sanyo
-  "Potato" CPU, 128 KB flash memory, 48x32 monochrome LCD, piezo buzzer,
+  LC8670 CPU, 128 KB flash, 48x32 LCD, piezo buzzer, and timers.
-  and basic timer subsystems.
 
-  No BIOS files are required. The core uses High Level Emulation (HLE) to
+  No BIOS files required. The core uses HLE exclusively: startCPU()
-  bypass the VMU firmware entirely:
+  checks BIOSExists (always false), then initializeHLE() sets SFR
+  registers and system RAM directly (vmu.cpp:193-222).
 
-  - At startup, startCPU() checks the BIOSExists flag (vmu.cpp:195). When
+  A loadBIOS() function exists (vmu.cpp:82-137) handling encrypted and
-    false (always, in the libretro port), it calls initializeHLE() which
+  unencrypted BIOS images, but is never called from the libretro
-    sets up SFR registers (SP=0x7F, PSW=0x02, IE=0x80, MCR=0x08, P7=0x02,
+  interface. retro_load_game() only loads game flash data, with no
-    OCR=0xA3, BTCR=0x41) and system RAM variables directly (vmu.cpp:206-222).
+  system directory query. README lists BIOS support as planned.
-
-  - A loadBIOS() function exists in the VMU class (vmu.cpp:82-137) and can
-    handle both encrypted (XOR 0x37, 4-byte header stripped) and unencrypted
-    BIOS images (first byte must be 0x2A = JMPF opcode). Maximum accepted
-    size is 0xF004 (61444) bytes, loaded into 0xF000 (61440) bytes of ROM.
-    However, this function is never called by the libretro frontend code.
-    retro_load_game() in main.cpp only loads game flash data, with no BIOS
-    path resolution or RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY call.
-
-  - The README lists "BIOS support" as a planned future feature.
-
-  The .info file declares no firmware entries (firmware_count absent).
-  Supported ROM formats: VMS (.vms), DCI (.dci), raw flash dump (.bin).
-  The core option "enable_flash_write" allows persistent saves for .bin files.
 
 files: []
 

emulators/vice_x128.yml

@@ -0,0 +1,52 @@
+emulator: "VICE x128"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - C128 (VICE x128)"
+cores: [vice_x128]
+systems: [commodore-c128]
+notes: >
+  System ROMs embedded in binary: C128 kernal (318020-05), chargen (390059-01),
+  BASIC lo (318018-04), BASIC hi (318019-04), C64 kernal (901227-03), C64 BASIC (901226-01),
+  plus all drive ROMs (1540, 1541, 1541-II, 1551, 1570, 1571, 1571CR, 1581, 1001, 2031,
+  2040, 3040, 4040, 9000). Embedded ROM check in sysfile_load takes priority over filesystem.
+  Localized kernal/chargen variants (DE, FI, FR, IT, NO, SE, CH) are in the embedded list
+  with NULL data pointers; selecting a non-international model produces uninitialized ROM data.
+  JiffyDOS requires True Drive Emulation enabled and a 1541/1571/1581 drive type.
+  C64 BASIC/kernal use shared names (basic-901226-01.bin, kernal-901227-03.bin) instead of
+  upstream c128-specific names (basic64-901226-01.bin, kernal64-901227-03.bin) to share
+  files with the C64 core in RetroArch's shared system directory.
+
+files:
+  - name: "JiffyDOS_C128.bin"
+    description: "JiffyDOS C128 kernal replacement"
+    required: false
+    source_ref: "retrodep/ui.c:309-310"
+    notes: "Loaded into KernalIntName when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_C64.bin"
+    description: "JiffyDOS C64 kernal replacement (GO64 mode)"
+    required: false
+    source_ref: "retrodep/ui.c:307-308"
+    notes: "Loaded into Kernal64Name when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_1541-II.bin"
+    description: "JiffyDOS 1541-II drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:283-284"
+    notes: "Loaded into DosName1541ii when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_1571_repl310654.bin"
+    description: "JiffyDOS 1571 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:285-286"
+    notes: "Loaded into DosName1571 when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_1581.bin"
+    description: "JiffyDOS 1581 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:287-288"
+    notes: "Loaded into DosName1581 when vice_jiffydos option is enabled."

emulators/vice_x64.yml

@@ -0,0 +1,68 @@
+emulator: "VICE x64"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - C64 (VICE x64, fast)"
+cores: [vice_x64]
+systems: [commodore-c64]
+notes: >
+  System ROMs embedded in binary: C64 BASIC (901226-01), chargen (901225-01),
+  chargen Japanese (906143-02), kernal Rev 3 (901227-03), kernal GS (390852-01),
+  kernal SX-64 (251104-04), kernal 4064 (901246-01), kernal Japanese (906145-02),
+  plus all drive ROMs (1540, 1541, 1541-II, 1551, 1570, 1571, 1571CR, 1581, 1001,
+  2031, 2040, 3040, 4040, 9000) and VIC-II palettes. Embedded ROM check in
+  sysfile_load takes priority over filesystem. Kernal Rev 1 (901227-01) and
+  Rev 2 (901227-02) are NOT embedded; selecting C64 OLD NTSC or C64 OLD PAL model
+  requires them on the filesystem in system/vice/C64/. JiffyDOS requires True Drive
+  Emulation enabled and a 1541/1571/1581 drive type. SX-64 models use a separate
+  JiffyDOS kernal (JiffyDOS_SX-64.bin) not declared in the .info.
+
+files:
+  - name: "JiffyDOS_C64.bin"
+    description: "JiffyDOS C64 kernal replacement"
+    required: false
+    source_ref: "retrodep/ui.c:302-303"
+    notes: "Loaded into KernalName when vice_jiffydos option is enabled (non-SX64 models)."
+
+  - name: "JiffyDOS_SX-64.bin"
+    description: "JiffyDOS SX-64 kernal replacement"
+    required: false
+    source_ref: "retrodep/ui.c:295-296"
+    notes: "Loaded into KernalName when vice_jiffydos option is enabled and SX-64 model selected."
+
+  - name: "JiffyDOS_1541-II.bin"
+    description: "JiffyDOS 1541-II drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:283-284"
+    notes: "Loaded into DosName1541ii when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_1571_repl310654.bin"
+    description: "JiffyDOS 1571 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:285-286"
+    notes: "Loaded into DosName1571 when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_1581.bin"
+    description: "JiffyDOS 1581 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:287-288"
+    notes: "Loaded into DosName1581 when vice_jiffydos option is enabled."
+
+  - name: "kernal-901227-01.bin"
+    description: "C64 Kernal Rev 1"
+    required: false
+    size: 8192
+    validation: [size]
+    source_ref: "vice/src/c64/c64-resources.c:253, vice/src/c64/c64model.c:131"
+    notes: "Not embedded. Loaded via sysfile from system/vice/C64/ when C64 OLD NTSC model selected."
+
+  - name: "kernal-901227-02.bin"
+    description: "C64 Kernal Rev 2"
+    required: false
+    size: 8192
+    validation: [size]
+    source_ref: "vice/src/c64/c64-resources.c:254, vice/src/c64/c64model.c:117"
+    notes: "Not embedded. Loaded via sysfile from system/vice/C64/ when C64 OLD PAL model selected."

emulators/vice_x64dtv.yml

@@ -0,0 +1,34 @@
+emulator: "VICE x64dtv"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - C64DTV (VICE x64dtv)"
+cores: [vice_x64dtv]
+systems: [commodore-c64dtv]
+notes: >
+  System ROMs embedded in binary: C64 BASIC (901226-01), kernal Rev 3
+  (901227-03), chargen (901225-01), plus all drive ROMs (1540, 1541, 1541-II,
+  1551, 1570, 1571, 1571CR, 1581, 1001, 2031, 2040, 3040, 4040, 9000).
+  Embedded ROM check in sysfile_load takes priority over filesystem.
+  DTV has its own color system (viciidtv-color.c); external palette loading
+  is disabled. JiffyDOS is not supported (excluded from build conditionals).
+  The .info declares 4 JiffyDOS firmware (firmware_count=4) but the code
+  never loads them for this core. The .info also omits dtvrom.bin.
+
+files:
+  - name: "dtvrom.bin"
+    description: "C64 DTV 2MB flash ROM image"
+    required: false
+    hle_fallback: true
+    size: 2097152
+    source_ref: "vice/src/c64dtv/c64dtvflash.c:59-64,470-471,488-505"
+    notes: >
+      Loaded via sysfile_load from system/vice/C64DTV/. All model variants
+      (V2 PAL/NTSC, V3 PAL/NTSC, Hummer) default to this filename. If not
+      found, the core copies embedded BASIC, kernal and chargen ROMs into
+      flash memory. Without it, the DTV operates as a basic C64 without the
+      built-in DTV games and firmware. The original DTV ROM has distorted
+      colors; a patched ROM is recommended.

emulators/vice_x64sc.yml

@@ -0,0 +1,69 @@
+emulator: "VICE x64sc"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - C64 (VICE x64sc, accurate)"
+cores: [vice_x64sc]
+systems: [commodore-c64]
+notes: >
+  Cycle-accurate C64 emulator using the viciisc VIC-II implementation.
+  System ROMs embedded in binary: C64 BASIC (901226-01), chargen (901225-01),
+  chargen Japanese (906143-02), kernal Rev 3 (901227-03), kernal GS (390852-01),
+  kernal SX-64 (251104-04), kernal 4064 (901246-01), kernal Japanese (906145-02),
+  plus all drive ROMs (1540, 1541, 1541-II, 1551, 1570, 1571, 1571CR, 1581, 1001,
+  2031, 2040, 3040, 4040, 9000) and VIC-II palettes. Embedded ROM check in
+  sysfile_load takes priority over filesystem. Kernal Rev 1 (901227-01) and
+  Rev 2 (901227-02) are NOT embedded; selecting C64 OLD NTSC or C64 OLD PAL model
+  requires them on the filesystem in system/vice/C64/. JiffyDOS requires True Drive
+  Emulation enabled and a 1541/1571/1581 drive type. SX-64 models use a separate
+  JiffyDOS kernal (JiffyDOS_SX-64.bin) not declared in the .info.
+
+files:
+  - name: "JiffyDOS_C64.bin"
+    description: "JiffyDOS C64 kernal replacement"
+    required: false
+    source_ref: "retrodep/ui.c:302-303"
+    notes: "Loaded into KernalName when vice_jiffydos option is enabled (non-SX64 models)."
+
+  - name: "JiffyDOS_SX-64.bin"
+    description: "JiffyDOS SX-64 kernal replacement"
+    required: false
+    source_ref: "retrodep/ui.c:295-296"
+    notes: "Loaded into KernalName when vice_jiffydos option is enabled and SX-64 model selected."
+
+  - name: "JiffyDOS_1541-II.bin"
+    description: "JiffyDOS 1541-II drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:283-284"
+    notes: "Loaded into DosName1541ii when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_1571_repl310654.bin"
+    description: "JiffyDOS 1571 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:285-286"
+    notes: "Loaded into DosName1571 when vice_jiffydos option is enabled."
+
+  - name: "JiffyDOS_1581.bin"
+    description: "JiffyDOS 1581 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:287-288"
+    notes: "Loaded into DosName1581 when vice_jiffydos option is enabled."
+
+  - name: "kernal-901227-01.bin"
+    description: "C64 Kernal Rev 1"
+    required: false
+    size: 8192
+    validation: [size]
+    source_ref: "vice/src/c64/c64-resources.c:253, vice/src/c64/c64scmodel.c:141"
+    notes: "Not embedded. Loaded via sysfile from system/vice/C64/ when C64 OLD NTSC model selected."
+
+  - name: "kernal-901227-02.bin"
+    description: "C64 Kernal Rev 2"
+    required: false
+    size: 8192
+    validation: [size]
+    source_ref: "vice/src/c64/c64-resources.c:254, vice/src/c64/c64scmodel.c:123"
+    notes: "Not embedded. Loaded via sysfile from system/vice/C64/ when C64 OLD PAL model selected."

emulators/vice_xcbm2.yml

@@ -0,0 +1,22 @@
+emulator: "VICE xcbm2"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - CBM-II 6x0/7x0 (VICE xcbm2)"
+cores: [vice_xcbm2]
+systems: [commodore-cbm-ii]
+notes: >
+  System ROMs embedded in binary: chargen 600 (901237-01), chargen 700 (901232-01),
+  kernal (901244-04a), BASIC 128K (901242+3-04a), BASIC 256K (901240+1-03), plus
+  all drive ROMs (1001, 2031, 2040, 3040, 4040, 9000) and CRTC palettes (amber,
+  green, white). Embedded ROM check in sysfile_load takes priority over filesystem.
+  Models: 610 PAL/NTSC, 620 PAL/NTSC, 620+ PAL/NTSC, 710 NTSC, 720 NTSC,
+  720+ NTSC. 600 series uses CRTC with 8 scanlines/char, 700 series uses 14
+  scanlines/char (different chargen ROM). CBM-II uses IEEE-488 bus (not IEC serial),
+  so no JiffyDOS support. Cartridge slots (Cart1-Cart6) are user content, not system
+  files.
+
+files: []

emulators/vice_xcbm5x0.yml

@@ -0,0 +1,19 @@
+emulator: "VICE xcbm5x0"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - CBM-II 5x0 (VICE xcbm5x0)"
+cores: [vice_xcbm5x0]
+systems: [commodore-cbm-ii]
+notes: >
+  System ROMs embedded in binary: chargen 500 (901225-01), kernal 500
+  (901234-02), BASIC 500 (901235+6-02), plus all drive ROMs (1001, 2031, 2040,
+  3040, 4040, 9000) and VIC-II palettes. Embedded ROM check in sysfile_load
+  takes priority over filesystem. Models: 510 PAL/NTSC. CBM-5x0 (P500/C510)
+  uses VIC-II chip instead of CRTC. IEEE-488 bus (not IEC serial), no JiffyDOS
+  support. Cartridge slots (Cart1-Cart6) are user content, not system files.
+
+files: []

emulators/vice_xpet.yml

@@ -0,0 +1,24 @@
+emulator: "VICE xpet"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - PET (VICE xpet)"
+cores: [vice_xpet]
+systems: [commodore-pet]
+notes: >
+  System ROMs embedded in binary: kernal 1 (901439-04-07), kernal 2 (901465-03),
+  kernal 4 (901465-22), BASIC 1 (901439-09-05-02-06), BASIC 2 (901465-01-02),
+  BASIC 4 (901465-23-20-21), chargen 1 (901447-08), chargen 2 (901447-10),
+  SuperPET chargen (901640-01), 6 editor ROMs (1g40, 2b40, 2g40, 4b40, 4b80, 4g40),
+  6 SuperPET Waterloo 6809 ROMs (a000-f000), plus all drive ROMs (1540, 1541, 1541-II,
+  1551, 1570, 1571, 1571CR, 1581, 1001, 2031, 2040, 3040, 4040, 9000) and CRTC
+  palettes (amber, green, white). Embedded ROM check in sysfile_load takes priority
+  over filesystem. Models: 2001, 3008, 3016, 3032, 3032B, 4016, 4032, 4032B, 8032,
+  8096, 8296, SuperPET. PET uses IEEE-488 bus (not IEC serial), so no JiffyDOS support.
+  No cartridge support. Extension ROM slots ($9000/$A000/$B000) and German chargen
+  (chargen.de) are standalone-only features not exposed via libretro core options.
+
+files: []

emulators/vice_xplus4.yml

@@ -0,0 +1,23 @@
+emulator: "VICE xplus4"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - PLUS/4 (VICE xplus4)"
+cores: [vice_xplus4]
+systems: [commodore-plus4]
+notes: >
+  All system ROMs embedded in binary: BASIC (318006-01), kernal PAL (318004-05),
+  kernal NTSC (318005-05), kernal V232 (318004-01), kernal V364 (364),
+  3+1 function low (317053-01), 3+1 function high (317054-01), V364 speech ROM
+  (c2lo-364). All drive ROMs embedded (1540, 1541, 1541-II, 1551, 1570, 1571,
+  1571CR, 1581, 1001, 2031, 2040, 3040, 4040, 9000). TED palettes embedded
+  (colodore_ted, BT601, BT709, BT2020, yape-pal, yape-ntsc). Embedded check in
+  sysfile_load takes priority over filesystem. Models: C16 PAL/NTSC, Plus/4
+  PAL/NTSC, V364 NTSC, 232 NTSC — all use embedded kernal variants. No JiffyDOS
+  support (C64/C128/SCPU64 only). 3+1 function ROMs loaded for Plus/4 and V364
+  models, cleared to 0xFF for C16 and 232 models. c2lo loaded only for V364 model.
+
+files: []

emulators/vice_xscpu64.yml

@@ -0,0 +1,59 @@
+emulator: "VICE xscpu64"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - C64 SuperCPU (VICE xscpu64)"
+cores: [vice_xscpu64]
+systems: [commodore-c64-supercpu]
+notes: >
+  Embedded SCPU64 ROM V0.07 (free replacement by Soci/Singular, 64 KB), chargen
+  (901225-01, 906143-02), C64 BASIC (901226-01), all C64 kernals (Rev 3, GS,
+  SX-64, 4064, Japanese), all drive ROMs (1540 through 9000), and VIC-II palettes.
+  Embedded ROM check in sysfile_load takes priority over filesystem. External
+  scpu-dos-*.bin provide the original CMD SuperCPU DOS kernals, loaded from
+  system/vice/SCPU64/ when SuperCPU Kernal core option is changed from Internal.
+  JiffyDOS requires True Drive Emulation enabled and a non-internal SuperCPU
+  kernal (the internal ROM is not JiffyDOS-compatible). The .info incorrectly
+  declares JiffyDOS_C64.bin (firmware_count=4); the C64 kernal replacement is
+  only loaded for x64/x64sc/x128, never for xscpu64. Correct firmware_count=5
+  (2 SCPU64 kernals + 3 JiffyDOS drive DOSes).
+
+files:
+  - name: "scpu-dos-2.04.bin"
+    description: "CMD SuperCPU Kernal v2.04"
+    required: false
+    min_size: 65536
+    max_size: 524288
+    validation: [size]
+    source_ref: "retrodep/ui.c:262-263, vice/src/scpu64/scpu64rom.c:75-89"
+    notes: "Loaded as SCPU64Name when SuperCPU Kernal option set to 2.04. Size must be power of 2 between 64 KB and 512 KB. Stored in system/vice/SCPU64/."
+
+  - name: "scpu-dos-1.4.bin"
+    description: "CMD SuperCPU Kernal v1.4"
+    required: false
+    min_size: 65536
+    max_size: 524288
+    validation: [size]
+    source_ref: "retrodep/ui.c:265-266, vice/src/scpu64/scpu64rom.c:75-89"
+    notes: "Loaded as SCPU64Name when SuperCPU Kernal option set to 1.40. Size must be power of 2 between 64 KB and 512 KB. Stored in system/vice/SCPU64/."
+
+  - name: "JiffyDOS_1541-II.bin"
+    description: "JiffyDOS 1541-II drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:282-283"
+    notes: "Loaded as DosName1541ii when JiffyDOS option enabled."
+
+  - name: "JiffyDOS_1571_repl310654.bin"
+    description: "JiffyDOS 1571 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:285-286"
+    notes: "Loaded as DosName1571 when JiffyDOS option enabled."
+
+  - name: "JiffyDOS_1581.bin"
+    description: "JiffyDOS 1581 drive DOS replacement"
+    required: false
+    source_ref: "retrodep/ui.c:287-288"
+    notes: "Loaded as DosName1581 when JiffyDOS option enabled."

emulators/vice_xvic.yml

@@ -0,0 +1,36 @@
+emulator: "VICE xvic"
+type: libretro
+core_classification: community_fork
+source: "https://github.com/libretro/vice-libretro"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.10"
+display_name: "Commodore - VIC-20 (VICE xvic)"
+cores: [vice_xvic]
+systems: [commodore-vic20]
+notes: >
+  System ROMs embedded in binary: BASIC (901486-01), chargen (901460-03),
+  kernal PAL Rev 7 (901486-07), kernal NTSC Rev 6 (901486-06), plus all
+  drive ROMs (1540, 1541, 1541-II, 1551, 1570, 1571, 1571CR, 1581, 1001,
+  2031, 2040, 3040, 4040, 9000) and VIC palettes. Embedded ROM check in
+  sysfile_load takes priority over filesystem. Japanese VIC-1001 model
+  requires kernal Rev 2 (901486-02) and chargen (901460-02) on the
+  filesystem in system/vice/VIC20/; this model is not exposed via core
+  options (only via vicerc). No JiffyDOS support for VIC-20.
+
+files:
+  - name: "kernal.901486-02.bin"
+    description: "VIC-1001 Kernal Rev 2 (Japanese NTSC)"
+    required: false
+    size: 8192
+    validation: [size]
+    source_ref: "vice/src/vic20/vic20rom.h:49, vice/src/vic20/vic20model.c:60, vice/src/vic20/vic20rom.c:112-120"
+    notes: "Not embedded. Loaded via sysfile from system/vice/VIC20/ when VIC-1001 Japanese model selected via vicerc."
+
+  - name: "chargen-901460-02.bin"
+    description: "VIC-1001 Character ROM (Japanese)"
+    required: false
+    size: 4096
+    validation: [size]
+    source_ref: "vice/src/vic20/vic20rom.h:53, vice/src/vic20/vic20model.c:60, vice/src/vic20/vic20rom.c:173-179"
+    notes: "Not embedded. Loaded via sysfile from system/vice/VIC20/ when VIC-1001 Japanese model selected via vicerc."

emulators/vidtest.yml

@@ -1,7 +1,8 @@
 emulator: vidtest
 type: test
-source: "https://github.com/libretro/RetroArch"
+core_classification: pure_libretro
-profiled_date: "2026-03-18"
+source: "https://github.com/schellingb/vidtest_libretro"
+profiled_date: "2026-03-25"
 core_version: "0.1"
 display_name: "VidTest"
 cores:
@@ -9,11 +10,9 @@ cores:
 systems: []
 
 notes: |
-  Video test core built into RetroArch (not from libretro-samples). Tests
+  Video mode and input test core for libretro frontends. Provides interactive
-  video driver capabilities: pixel format negotiation, resolution switching,
+  GUI (Nuklear) to adjust resolution, aspect ratio, timing, and inspect full
-  aspect ratio handling, and frame pacing. Renders test patterns for visual
+  input state across all device types. Renders directly to a software surface.
-  validation of the video output chain.
+  No system files required.
-
-  No system files, BIOS, or firmware required. Not an emulator.
 
 files: []

emulators/vircon32.yml

@@ -1,8 +1,10 @@
 emulator: Vircon32
 type: libretro
+core_classification: official_port
 source: "https://github.com/vircon32/vircon32-libretro"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/vircon32/ComputerSoftware"
-core_version: "2024.08.28"
+profiled_date: "2026-03-25"
+core_version: "2026.2.18"
 display_name: "Vircon32"
 cores:
   - vircon32
@@ -18,7 +20,7 @@ notes: |
   C header (embedded/StandardBios.h), generated from Assets/StandardBios.v32
   at build time. The core never strictly requires an external BIOS file.
 
-  BIOS loading logic (libretro.cpp:416-429):
+  BIOS loading logic (libretro.cpp:415-429):
   1. Check if system_dir/Vircon32Bios.v32 exists on disk
   2. If found, load it via Console.LoadBiosFile() (external override)
   3. If not found, load the embedded BIOS via LoadEmbeddedBios()
@@ -44,7 +46,7 @@ files:
     size: 1073060
     md5: "73f04397cbb2dafcf2047b19a856153a"
     sha1: "67ddbcd018f03ed74b6e013074d92cc5f1f51c80"
-    source_ref: "libretro.cpp:423-426"
+    source_ref: "libretro.cpp:422-425"
     notes: |
       Optional external BIOS placed in the system directory root.
       If present, overrides the embedded Standard BIOS v1.2.

emulators/virtualjaguar.yml

@@ -1,7 +1,9 @@
 emulator: Virtual Jaguar
 type: libretro
+core_classification: community_fork
 source: "https://github.com/libretro/virtualjaguar-libretro"
-profiled_date: "2026-03-18"
+upstream: "http://shamusworld.gotdns.org/git/virtualjaguar"
+profiled_date: "2025-03-25"
 core_version: "v2.1.0"
 display_name: "Atari - Jaguar (Virtual Jaguar)"
 cores:

emulators/virtualxt.yml

@@ -1,55 +1,32 @@
 emulator: VirtualXT
 type: libretro
-source: "https://github.com/libretro/virtualxt"
+core_classification: pure_libretro
-profiled_date: "2026-03-18"
+source: "https://codeberg.org/virtualxt/virtualxt"
-core_version: "0.9.0"
+upstream: "https://codeberg.org/virtualxt/virtualxt"
+profiled_date: "2026-03-25"
+core_version: "2.1.0"
 display_name: "VirtualXT"
+cores: [virtualxt]
 systems: [ibm-pc]
 
-# VirtualXT is a Turbo PC/XT emulator (Intel 8088/186). Written in Odin.
+# All BIOS ROMs are embedded at compile time via Odin's #load() directive.
-# All BIOS ROMs are embedded at compile time via #load() directives in
+# No external files are loaded from system_dir in standard operation.
-# src/frontend/core.odin. No external BIOS files are required at runtime.
-
-# The default machine setup (setup_default_machine) loads these embedded ROMs:
-#   - BIOS: GLaBIOS 0.2.6 or Turbo XT BIOS 3.1 (user selects via core option)
-#   - VGA BIOS: vgabios.bin (loaded when VGA video mode is selected)
-#   - Disk Extension: vxtx.bin (always loaded)
-#   - RTC BIOS: GLaTICK 0.8.4 (loaded when RTC is enabled)
-
-# Core option "virtualxt_bios" selects between GLaBIOS and TurboXT at startup.
-# Core option "virtualxt_video" selects CGA or VGA (VGA loads vgabios.bin).
-# Core option "virtualxt_rtc" selects GLaTICK or none (loads GLaTICK_0.8.4_AT.ROM).
-
-# INI config files (.ini extension) can reference external ROM paths, but the
-# standard usage path does not require any files in the system directory.
-
-# Embedded BIOS files (shipped inside the compiled core binary):
 #
-#   GLABIOS.ROM           8192 bytes   md5:bbeb6f7e2175732eebc3f0b49976347a  sha1:701bb8ab0f9797581f795394a5c09eb147ff93d2
+# Embedded ROMs (core.odin:323-394, edge branch):
-#   pcxtbios.bin          8192 bytes   md5:336bf8888a22075caa09e2e8e4d96a3b  sha1:f7b73e441fd7b582a493837658fa17407e851d7c
+#   GLABIOS.ROM, pcxtbios.bin, vgabios.bin, vxtx.bin, GLaTICK_0.8.4_AT.ROM
-#   vgabios.bin          32768 bytes   md5:9c80b0a0784dcf80f84c35b1cc8db81b  sha1:251d85a90d3df3d116c30568167587ee3819f623
+#
-#   vxtx.bin              2048 bytes   md5:c6c7eef021e5e40503cb5ae860f02fde  sha1:ccd27f24e5d7bd7d14b336be5b79b7ef8ba6e6be
+# INI config files can reference external ROM paths via load_from_file
-#   GLaTICK_0.8.4_AT.ROM  2048 bytes   md5:06ead46b977ffb4a056844e2965653eb  sha1:025c5d6d9391698488cebad11623ee239ce070a2
+# (rom.odin:42-68), but this is not the standard usage path.
-
+#
-# Source references:
+# source_ref: src/frontend/core.odin:323-394 (setup_default_machine, #load)
-#   src/frontend/core.odin:295-370  - BIOS embedding via #load("bios:...", []byte)
+# source_ref: src/modules/rom/rom.odin:42-68 (load_from_file, INI only)
-#   src/frontend/options.odin:55    - core option "virtualxt_bios" (GLaBIOS|TurboXT)
+# source_ref: src/frontend/options.odin:55 (core option virtualxt_bios)
-#   src/modules/rom/rom.odin:42-67  - load_from_file (INI path only)
-#   bios/                           - open-source BIOS files (GLaBIOS, TurboXT, vgabios)
 
 files: []
 
 notes:
   bios_approach: >
-    VirtualXT embeds all BIOS ROMs into the core binary at compile time using
+    All BIOS ROMs embedded at compile time via Odin #load() directive.
-    Odin's #load() directive. The bios/ directory in the source tree contains
+    Open-source replacements: GLaBIOS (GPL), Turbo XT BIOS 3.1, vgabios.
-    open-source replacements: GLaBIOS (GPL), Turbo XT BIOS 3.1, and vgabios.
+    No proprietary IBM PC/XT BIOS needed.
-    No proprietary IBM PC/XT BIOS is needed.
-  ini_config: >
-    When loading an .ini file, the core can instantiate ROM modules with external
-    file paths (rom.odin handles string values for "mem" via load_from_file).
-    This is an advanced usage path; standard operation needs no external files.
   supported_extensions: "img, ini, exe, com"
-  supported_features: >
-    Intel 8088/186 CPU, CGA/VGA graphics, EMS memory, ethernet adapter,
-    host file sharing (RIFS2), GDB server, floppy and hard disk images.

emulators/vitaquake2.yml

@@ -1,7 +1,9 @@
 emulator: vitaQuakeII
 type: libretro
+core_classification: official_port
 source: "https://github.com/libretro/vitaquake2"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/Rinnegatamante/vitaQuakeII"
+profiled_date: "2026-03-25"
 core_version: "git"
 display_name: "Quake II (vitaQuake 2)"
 cores: [vitaquake2, vitaquake2-rogue, vitaquake2-xatrix, vitaquake2-zaero]

emulators/vitaquake3.yml

@@ -1,22 +1,21 @@
 emulator: vitaQuakeIII
 type: game
+core_classification: community_fork
 source: "https://github.com/libretro/vitaquake3"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/ioquake/ioq3"
+profiled_date: "2026-03-25"
 core_version: "git"
 display_name: "Quake III: Arena (vitaQuake 3)"
-cores: [vitaquake3, vitavoyager]
+cores: [vitaquake3]
 systems: [quake3]
 
 notes: >
-  Quake III Arena and Star Trek Voyager Elite Force source ports. Built from
+  Quake III Arena source port built from ioquake3 with the libretro backend.
-  ioquake3 with the libretro backend. vitaquake3 plays Quake III Arena and
+  Also supports Team Arena (missionpack), OpenArena (baseoa), Quake3Rally
-  Team Arena, vitavoyager plays Star Trek Voyager Elite Force (Holomatch
+  (baseq3r), and Urban Terror (q3ut4) via path detection. Content is loaded
-  multiplayer). Both cores accept .pk3 extensions. Content is loaded from the
+  from the .pk3 file path - the engine resolves the parent directory structure
-  .pk3 file path - the engine resolves the parent directory structure to find
+  to find baseq3/ and loads pak0.pk3 through pak8.pk3 sequentially. Game data
-  baseq3/ (or baseEF/ for vitavoyager) and loads pak0.pk3 through pak8.pk3
+  files (.pk3 archives) come from the retail game. No files are required in
-  sequentially. Game data files (.pk3 archives containing maps, textures,
+  the RetroArch system directory.
-  models, shaders, sounds) come from the retail game, not engine firmware.
-  No files are required in the RetroArch system directory. The cores need
-  no BIOS or firmware.
 
 files: []

emulators/vitavoyager.yml

@@ -1,8 +1,20 @@
-emulator: "vitavoyager"
+emulator: vitavoyager
-type: alias
+type: game
-alias_of: "vitaquake3"
+core_classification: community_fork
-profiled_date: "2026-03-18"
+source: "https://github.com/libretro/vitavoyager"
+upstream: "https://github.com/zturtleman/lilium-voyager"
+profiled_date: "2026-03-25"
 core_version: "git"
 display_name: "Star Trek: Voyager - Elite Force (vitaVoyager)"
-note: "This core uses the same BIOS/firmware as vitaquake3. See emulators/vitaquake3.yml for details."
+cores: [vitavoyager]
+systems: [quake3]
+
+notes: >
+  Star Trek Voyager Elite Force Holomatch (multiplayer) source port built from
+  Lilium Voyager (itself an ioquake3 fork) with the libretro backend. Content
+  is loaded from the .pk3 file path - the engine resolves the parent directory
+  structure to find baseEF/ and loads pak0.pk3 through pak3.pk3 sequentially.
+  Game data files (.pk3 archives) come from the retail game. No files are
+  required in the RetroArch system directory.
+
 files: []

emulators/wasm4.yml

@@ -1,15 +1,15 @@
 emulator: WASM-4
 type: game
+core_classification: game_engine
 source: "https://github.com/aduros/wasm4"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/aduros/wasm4"
+profiled_date: "2026-03-25"
 core_version: "2.1.0"
 display_name: "WASM-4"
 cores: [wasm4]
 systems: []
 files: []
 notes: >
-  WASM-4 is a low-level fantasy game console for building small games with
+  Fantasy game console for WebAssembly. 160x160 display, 4-color palette,
-  WebAssembly. It provides a fixed 160x160 display, 4-color palette, gamepad
+  1024 bytes persistent storage. Self-contained runtime, no external file
-  input, and 1024 bytes of persistent storage. Games are standalone .wasm
+  dependencies. Libretro backend is in the upstream repo (no separate fork).
-  cartridges. The runtime is fully self-contained with no external file
-  dependencies. No BIOS or system directory files required.

emulators/x1.yml

@@ -1,83 +1,92 @@
 emulator: "X Millennium"
 type: libretro
+core_classification: community_fork
 source: "https://github.com/libretro/xmil-libretro"
-profiled_date: "2026-03-18"
+upstream: "http://amethyst.yui.ne.jp/svn/x1/xmil/trunk/"
-core_version: "0.60"
+profiled_date: "2026-03-25"
+core_version: "0.60a"
 display_name: "Sharp X1 (X Millennium)"
 cores:
   - x1
 systems:
   - sharp-x1
 
-# X Millennium (XMIL) is a Sharp X1 series emulator by yui. The libretro port
+# X Millennium (XMIL) is a Sharp X1 series emulator by yui, ported to libretro
-# supports X1, X1 Turbo, and X1 TurboZ models via the "X1_ROMTYPE" core option
+# by r-type. Supports X1, X1 Turbo, and X1 TurboZ models via the "X1_ROMTYPE"
-# (values: X1, TURBO, TURBOZ; default: X1 = ROM_TYPE 1).
+# core option (X1 = ROM_TYPE 1, TURBO = 2, TURBOZ = 3).
+#
+# SUPPORT_TURBOZ is not compiled in the libretro build (compiler.h), so TurboZ
+# extended color modes are unavailable. ROM_TYPE 3 still selects IPLROM.X1T.
 #
 # All system files go under: <system_dir>/xmil/
-# (libretro.c:597 builds the path as "<system_dir>/xmil")
+# retro_init() builds: retro_system_conf = "<system_dir>/xmil" (libretro.c:597)
 #
-# IPL ROM loading (memio.c:88-116):
+# IPL ROM loading (memio.c:87-121):
-#   ROM_TYPE 0: uses built-in default IPL (575 bytes, basic boot stub from defipl.res)
+#   biosmem is initialized with defaultiplrom (575-byte boot stub from defipl.res).
-#   ROM_TYPE 1 (X1): loads xmil/IPLROM.X1 (32 KB)
+#   ROM_TYPE >= 1: loads external IPL ROM into biosmem, overwriting the stub.
-#   ROM_TYPE 2 (Turbo): loads xmil/IPLROM.X1T (32 KB)
+#   ROM_TYPE 1 (X1): xmil/IPLROM.X1
-#   ROM_TYPE 3 (TurboZ): loads xmil/IPLROM.X1T (32 KB, same file as Turbo)
+#   ROM_TYPE >= 2 (Turbo/TurboZ): xmil/IPLROM.X1T
-#   If the file is missing, the core falls back to the built-in default IPL.
+#   Path built explicitly: sprintf(rtmp, "%s%c%s", retro_system_conf, slash, iplfile)
+#   If file missing, the 575-byte stub remains (limited boot capability).
 #
-# Font loading (font.c:90-127, fontx1.c:70-123):
+# Font loading (fontx1.c:69-122, font.c:89-127):
-#   font_load() calls x1fontread() which looks for font files using fontopen().
+#   font_load(NULL, TRUE) called from pccore_initialize() (pccore.c:67).
-#   fontopen() resolves paths relative to the working directory (file_getcd()),
+#   Built-in defaults (defrom_ank, defrom_txt from fontdata.c) provide basic ASCII.
-#   which in libretro context is the xmil subdirectory.
+#   x1fontread() tries to load external font files via fontopen().
-#   Built-in defaults (defrom_ank, defrom_txt) are used for basic ASCII rendering.
+#   Font path resolution uses file_getcd() which defaults to "./" in the libretro
-#   External font ROMs add full Japanese character support.
+#   port (file_setcd() is never called). Upstream win9x/sdl2 calls file_setcd()
+#   to set the working dir. Fonts may not be found from xmil/ in practice.
 #
-# The .info file only lists IPLROM.X1 and IPLROM.X1T as required BIOS files.
+# .info declares firmware_count=2 (IPL ROMs only). Font files are not declared.
-# Font ROMs are optional -- the core renders basic text without them but Japanese
+# .info firmware1_desc incorrectly says "8x8 Font ROM" (actually Turbo IPL ROM).
-# kanji display requires the external font files.
 
 notes: |
   Place all files in: <system_dir>/xmil/
   The core selects between IPLROM.X1 and IPLROM.X1T based on the "X1_ROMTYPE"
-  core option. A built-in fallback IPL exists but lacks full boot functionality.
+  core option. A 575-byte built-in IPL stub provides limited boot without the
-  Font files are optional; without them, kanji/JIS characters won't render.
+  real ROMs. Font files add Japanese character support; the libretro port has a
+  path resolution quirk where fonts are searched in "./" instead of "xmil/"
+  (missing file_setcd call).
 
 files:
-  # -- IPL ROMs --
-
   - name: IPLROM.X1
     path: xmil/IPLROM.X1
     size: 32768
-    md5: eeeea1cd29c6e0e8b094790ae969bfa7
+    required: false
-    required: true
+    hle_fallback: true
-    note: "X1 IPL ROM (32 KB). Loaded when ROM_TYPE=1 (X1 model). Listed in .info."
+    description: "X1 IPL ROM. Loaded when ROM_TYPE=1 (X1 model)."
-    source_ref: "io/memio.c:82,96-103"
+    source_ref: "io/memio.c:82,96-108"
 
   - name: IPLROM.X1T
     path: xmil/IPLROM.X1T
     size: 32768
-    md5: 851e4a5936f17d13f8c39a980cf00d77
+    required: false
-    required: true
+    hle_fallback: true
-    note: "X1 Turbo/TurboZ IPL ROM (32 KB). Loaded when ROM_TYPE=2 or 3. Listed in .info."
+    description: "X1 Turbo/TurboZ IPL ROM. Loaded when ROM_TYPE=2 or 3."
-    source_ref: "io/memio.c:83,97-99"
+    source_ref: "io/memio.c:83,97-108"
-
-  # -- Font ROMs (optional, for Japanese text rendering) --
 
   - name: FNT0808.X1
     path: xmil/FNT0808.X1
     size: 2048
+    validation: [size]
     required: false
-    note: "8x8 ANK font ROM (2 KB). Provides half-width ASCII/kana characters."
+    hle_fallback: true
+    description: "8x8 ANK font ROM. Built-in defrom_ank fallback provides basic ASCII."
     source_ref: "font/fontdata.c:6, font/fontx1.c:79-87"
 
   - name: FNT0816.X1
     path: xmil/FNT0816.X1
     size: 4096
+    validation: [size]
     required: false
-    note: "8x16 ANK font ROM (4 KB). Provides taller half-width characters for text mode."
+    hle_fallback: true
+    description: "8x16 ANK font ROM. Built-in fallback derived from defrom_ank/defrom_txt."
     source_ref: "font/fontdata.c:7, font/fontx1.c:89-103"
 
   - name: FNT1616.X1
     path: xmil/FNT1616.X1
     size: 306176
+    validation: [size]
     required: false
-    note: "16x16 Kanji font ROM (~299 KB). Full JIS kanji character set for Japanese text."
+    description: "16x16 Kanji font ROM. No built-in kanji data (zeroed). Required for Japanese text."
     source_ref: "font/fontdata.c:8, font/fontx1.c:105-120"

emulators/x64sdl.yml

@@ -1,20 +1,181 @@
 emulator: x64sdl
 type: libretro
-source: "https://github.com/libretro/vice-libretro"
+core_classification: community_fork
-profiled_date: "2026-03-18"
+source: "https://github.com/r-type/sdlvice-libretro"
-core_version: "v3.1"
+upstream: "https://sourceforge.net/projects/vice-emu/"
+profiled_date: "2026-03-25"
+core_version: "3.1"
 display_name: "Commodore - C64 (VICE SDL)"
-cores:
+cores: [x64sdl]
-  - vice_x64
+systems: [commodore-c64]
-systems:
+notes: >
-  - commodore-c64
+  Old port of VICE 3.1 using an SDL-to-libretro shim (r-type/sdlvice-libretro).
+  Separate codebase from the newer vice-libretro port. Marked experimental and
+  superseded. Unlike the newer port, this core does NOT embed system ROMs; all ROMs
+  must be on disk in <system_dir>/data/C64/ and <system_dir>/data/DRIVES/.
+  The .info declares firmware_count=0 which is incorrect. No JiffyDOS support.
+  No save states, no netplay, no cheats.
 
-notes: |
+files:
-  Alias for the VICE x64 core. x64sdl is an alternate build name
+  # C64 system ROMs (required, path: data/C64/)
-  referencing the SDL-based VICE x64 Commodore 64 emulator. In the
+  - name: "kernal"
-  libretro ecosystem this maps to the same vice_x64 core binary.
+    description: "C64 Kernal ROM"
+    required: true
+    size: 8192
+    path: "data/C64/kernal"
+    source_ref: "src/c64/c64rom.c:133, src/c64/c64-resources.c:255"
 
-  See vice.yml for full ROM and BIOS details. All standard ROMs are
+  - name: "basic"
-  embedded in the core binary.
+    description: "C64 BASIC ROM"
+    required: true
+    size: 8192
+    path: "data/C64/basic"
+    source_ref: "src/c64/c64rom.c:192, src/c64/c64-resources.c:258"
 
-files: []
+  - name: "chargen"
+    description: "C64 character generator ROM"
+    required: true
+    size: 4096
+    path: "data/C64/chargen"
+    source_ref: "src/c64/c64rom.c:207, src/c64/c64-resources.c:252"
+
+  # C64 variant kernals (optional, for alternate models via c64model.c)
+  - name: "sxkernal"
+    description: "SX-64 Kernal ROM"
+    required: false
+    size: 8192
+    path: "data/C64/sxkernal"
+    source_ref: "src/c64/c64model.c:142,147"
+    notes: "Loaded when SX64 PAL or SX64 NTSC model selected."
+
+  - name: "jpkernal"
+    description: "Japanese C64 Kernal ROM"
+    required: false
+    size: 8192
+    path: "data/C64/jpkernal"
+    source_ref: "src/c64/c64model.c:152"
+    notes: "Loaded when C64 JAP NTSC model selected."
+
+  - name: "jpchrgen"
+    description: "Japanese C64 character generator ROM"
+    required: false
+    size: 4096
+    path: "data/C64/jpchrgen"
+    source_ref: "src/c64/c64model.c:152"
+    notes: "Loaded when C64 JAP NTSC model selected."
+
+  - name: "gskernal"
+    description: "C64 Games System Kernal ROM"
+    required: false
+    size: 8192
+    path: "data/C64/gskernal"
+    source_ref: "src/c64/c64model.c:157"
+    notes: "Loaded when C64 GS PAL model selected."
+
+  - name: "edkernal"
+    description: "PET64/Educator64 Kernal ROM"
+    required: false
+    size: 8192
+    path: "data/C64/edkernal"
+    source_ref: "src/c64/c64model.c:162,167"
+    notes: "Loaded when PET64 PAL or PET64 NTSC model selected."
+
+  # IEC drive ROMs (optional, path: data/DRIVES/)
+  - name: "dos1540"
+    description: "1540 floppy drive ROM"
+    required: false
+    path: "data/DRIVES/dos1540"
+    source_ref: "src/drive/iec/iecrom.c:99, src/drive/iec/iec-resources.c:182"
+    notes: "Hardware-level 1540 drive emulation. Absence disables this drive type."
+
+  - name: "dos1541"
+    description: "1541 floppy drive ROM"
+    required: false
+    path: "data/DRIVES/dos1541"
+    source_ref: "src/drive/iec/iecrom.c:106, src/drive/iec/iec-resources.c:185"
+    notes: "Hardware-level 1541 drive emulation. Most common C64 drive."
+
+  - name: "d1541II"
+    description: "1541-II floppy drive ROM"
+    required: false
+    path: "data/DRIVES/d1541II"
+    source_ref: "src/drive/iec/iecrom.c:113, src/drive/iec/iec-resources.c:187"
+
+  - name: "dos1570"
+    description: "1570 floppy drive ROM"
+    required: false
+    path: "data/DRIVES/dos1570"
+    source_ref: "src/drive/iec/iecrom.c:121, src/drive/iec/iec-resources.c:189"
+
+  - name: "dos1571"
+    description: "1571 floppy drive ROM"
+    required: false
+    path: "data/DRIVES/dos1571"
+    source_ref: "src/drive/iec/iecrom.c:127, src/drive/iec/iec-resources.c:191"
+
+  - name: "dos1581"
+    description: "1581 floppy drive ROM"
+    required: false
+    path: "data/DRIVES/dos1581"
+    source_ref: "src/drive/iec/iecrom.c:133, src/drive/iec/iec-resources.c:193"
+
+  - name: "dos2000"
+    description: "CMD FD-2000 drive ROM"
+    required: false
+    path: "data/DRIVES/dos2000"
+    source_ref: "src/drive/iec/iecrom.c:139, src/drive/iec/iec-resources.c:195"
+    notes: "Not shipped with VICE 3.1 data files."
+
+  - name: "dos4000"
+    description: "CMD FD-4000 drive ROM"
+    required: false
+    path: "data/DRIVES/dos4000"
+    source_ref: "src/drive/iec/iecrom.c:145, src/drive/iec/iec-resources.c:197"
+    notes: "Not shipped with VICE 3.1 data files."
+
+  # IEEE drive ROMs (optional, path: data/DRIVES/)
+  - name: "dos2031"
+    description: "2031 IEEE drive ROM"
+    required: false
+    path: "data/DRIVES/dos2031"
+    source_ref: "src/drive/ieee/ieee.c:115, src/drive/ieee/ieee-resources.c:93"
+    notes: "IEEE488 interface drive. Requires parallel IEEE488 extension."
+
+  - name: "dos2040"
+    description: "2040 IEEE drive ROM"
+    required: false
+    path: "data/DRIVES/dos2040"
+    source_ref: "src/drive/ieee/ieee.c:116, src/drive/ieee/ieee-resources.c:96"
+
+  - name: "dos3040"
+    description: "3040 IEEE drive ROM"
+    required: false
+    path: "data/DRIVES/dos3040"
+    source_ref: "src/drive/ieee/ieee.c:117, src/drive/ieee/ieee-resources.c:98"
+
+  - name: "dos4040"
+    description: "4040 IEEE drive ROM"
+    required: false
+    path: "data/DRIVES/dos4040"
+    source_ref: "src/drive/ieee/ieee.c:118, src/drive/ieee/ieee-resources.c:100"
+
+  - name: "dos1001"
+    description: "1001/8050/8250 IEEE drive ROM"
+    required: false
+    path: "data/DRIVES/dos1001"
+    source_ref: "src/drive/ieee/ieee.c:119, src/drive/ieee/ieee-resources.c:102"
+
+  # Printer ROMs (optional, path: data/PRINTER/)
+  - name: "mps803"
+    description: "MPS-803 printer character ROM"
+    required: false
+    path: "data/PRINTER/mps803"
+    source_ref: "src/printerdrv/drv-mps803.c:420"
+    notes: "Loaded on demand when MPS-803 printer opened."
+
+  - name: "nl10-cbm"
+    description: "NL10 printer ROM"
+    required: false
+    path: "data/PRINTER/nl10-cbm"
+    source_ref: "src/printerdrv/drv-nl10.c:2210"
+    notes: "Loaded on demand when NL10 printer opened."

emulators/xrick.yml

@@ -1,7 +1,9 @@
 emulator: XRick
 type: libretro
+core_classification: game_engine
 source: "https://github.com/libretro/xrick-libretro"
-profiled_date: "2026-03-18"
+upstream: "https://github.com/fabiensanglard/xrick"
+profiled_date: "2026-03-25"
 core_version: "1.0.0.6"
 display_name: "Rick Dangerous (XRick)"
 cores:

emulators/yabasanshiro.yml

@@ -1,8 +1,55 @@
-emulator: "yabasanshiro"
+emulator: yabasanshiro
-type: alias
+type: libretro
-alias_of: "kronos"
+core_classification: official_port
-profiled_date: "2026-03-18"
+source: "https://github.com/libretro/yabause/tree/yabasanshiro"
+upstream: "https://github.com/devmiyax/yabause"
+profiled_date: "2026-03-25"
 core_version: "v2.6.8"
 display_name: "Sega - Saturn (YabaSanshiro)"
-note: "This core uses the same BIOS/firmware as kronos. See emulators/kronos.yml for details."
+cores:
-files: []
+  - yabasanshiro
+systems:
+  - sega-saturn
+
+notes: |
+  YabaSanshiro is a Sega Saturn emulator by devmiyax, forked from Yabause.
+  Requires OpenGL 3.3 or OpenGL ES 3.0.
+
+  Saturn BIOS search order:
+    1. {system}/saturn_bios.bin
+    2. {system}/sega_101.bin
+    3. {system}/mpr-17933.bin
+  First file found wins. Real BIOS required for normal operation.
+  HLE available via yabasanshiro_force_hle_bios core option (deprecated,
+  debug only).
+
+  Addon cartridges: 1M/4M RAM expansion via core option (no files needed).
+  ROM cartridge and MPEG card ROM loading disabled in libretro port
+  (cartpath = empty, mpegpath = NULL).
+
+  BIOS loading: libretro.c retro_load_game() lines 1048-1069.
+  Core load: memory.c LoadBios() line 1353, T123Load() memory.h lines 219-280.
+
+files:
+  - name: "saturn_bios.bin"
+    system: sega-saturn
+    required: true
+    hle_fallback: true
+    note: "Primary Saturn BIOS. Any region accepted."
+    source_ref: "libretro.c:1048"
+
+  - name: "sega_101.bin"
+    system: sega-saturn
+    region: [japan]
+    required: false
+    hle_fallback: true
+    note: "Saturn BIOS v1.01 (Japan). Fallback if saturn_bios.bin missing."
+    source_ref: "libretro.c:1052"
+
+  - name: "mpr-17933.bin"
+    system: sega-saturn
+    region: [north-america, europe]
+    required: false
+    hle_fallback: true
+    note: "Saturn BIOS v1.003 (NA/EU). Last fallback."
+    source_ref: "libretro.c:1056"

emulators/yabause.yml

@@ -1,8 +1,61 @@
-emulator: "yabause"
+emulator: yabause
-type: alias
+type: libretro
-alias_of: "kronos"
+core_classification: community_fork
-profiled_date: "2026-03-18"
+source: "https://github.com/libretro/yabause"
+upstream: "https://github.com/Yabause/yabause"
+profiled_date: "2026-03-25"
 core_version: "v0.9.15"
 display_name: "Sega - Saturn (Yabause)"
-note: "This core uses the same BIOS/firmware as kronos. See emulators/kronos.yml for details."
+cores:
-files: []
+  - yabause
+systems:
+  - sega-saturn
+
+notes: |
+  Yabause is a software-rendered Sega Saturn emulator. Upstream project is
+  dead; libretro port maintained by the community on the master branch of
+  libretro/yabause.
+
+  Saturn BIOS search order:
+    1. {system}/saturn_bios.bin
+    2. {system}/sega_101.bin
+    3. {system}/mpr-17933.bin
+  First file found wins. HLE BIOS available via yabause_force_hle_bios core
+  option (reduced compatibility). Multi-disc (m3u) requires real BIOS.
+
+  Addon cartridges: 1M/4M RAM expansion via core option (no files needed).
+  ROM cartridge loading, SH1 ROM (CD Block LLE), and MPEG card ROM are
+  standalone-only features disabled in the libretro port.
+
+  BIOS loading: libretro.c retro_load_game() lines 1035-1049.
+  Core load: memory.c LoadBios() line 1260, T123Load() memory.h lines 196-264.
+
+files:
+  - name: "saturn_bios.bin"
+    system: sega-saturn
+    required: true
+    hle_fallback: true
+    max_size: 524288
+    validation: [max_size]
+    note: "Primary Saturn BIOS. Any region accepted."
+    source_ref: "libretro.c:1035"
+
+  - name: "sega_101.bin"
+    system: sega-saturn
+    region: [japan]
+    required: false
+    hle_fallback: true
+    max_size: 524288
+    validation: [max_size]
+    note: "Saturn BIOS v1.01 (Japan). Fallback if saturn_bios.bin missing."
+    source_ref: "libretro.c:1039"
+
+  - name: "mpr-17933.bin"
+    system: sega-saturn
+    region: [north-america, europe]
+    required: false
+    hle_fallback: true
+    max_size: 524288
+    validation: [max_size]
+    note: "Saturn BIOS (NA/EU). Last fallback."
+    source_ref: "libretro.c:1043"

emulators/ymir.yml

@@ -0,0 +1,72 @@
+emulator: ymir
+type: standalone + libretro
+core_classification: community_fork
+source: "https://github.com/warmenhoven/Ymir/tree/libretro"
+upstream: "https://github.com/StrikerX3/Ymir"
+profiled_date: "2026-03-25"
+core_version: "PR#746"
+display_name: "Sega - Saturn (Ymir)"
+cores:
+  - ymir
+systems:
+  - sega-saturn
+
+notes: |
+  Ymir is a Sega Saturn emulator by StrikerX3. The libretro port by
+  warmenhoven wraps the shared ymir-core library (PR #746, not yet merged).
+  No .info file exists in libretro-core-info.
+
+  Saturn BIOS search order:
+    1. {system}/sega_101.bin
+    2. {system}/mpr-17933.bin
+    3. {system}/saturn_bios.bin
+  First file found with exact 512 KiB size wins. No HLE fallback for IPL.
+
+  CD Block LLE: optional low-level CD drive emulation. Scans {system}/cdb/
+  for any 64 KiB file. Falls back to HLE when disabled or no ROM found.
+  Known versions in upstream db: 1.04, 1.05, 1.06.
+
+  ROM cartridges: KoF95 and Ultraman shipped with physical ROM carts. The
+  core auto-detects required cartridge from its game database.
+
+  Addon cartridges: 1M/4M DRAM expansion handled via core option (no files).
+
+  Upstream uses XXH128 hashes for ROM identification only, not validation.
+  All file loading validates size only.
+
+files:
+  - name: "sega_101.bin"
+    system: sega-saturn
+    required: true
+    size: 524288
+    validation: [size]
+    aliases: [mpr-17933.bin, saturn_bios.bin]
+    description: "Saturn IPL ROM (BIOS). Any region accepted."
+    source_ref: "libretro.cpp:260-263,534-558"
+
+  - name: "cdb/cdb_rom.bin"
+    system: sega-saturn
+    required: false
+    hle_fallback: true
+    size: 65536
+    validation: [size]
+    description: "SH1 CD Block ROM for low-level CD drive emulation. Core scans cdb/ subdirectory for any matching file."
+    source_ref: "libretro.cpp:567-591"
+
+  - name: "mpr-18811-mx.ic1"
+    system: sega-saturn
+    required: false
+    category: game_data
+    size: 2097152
+    validation: [size]
+    description: "ROM cartridge for The King of Fighters '95."
+    source_ref: "libretro.cpp:619-620,597-616"
+
+  - name: "mpr-19367-mx.ic1"
+    system: sega-saturn
+    required: false
+    category: game_data
+    size: 2097152
+    validation: [size]
+    description: "ROM cartridge for Ultraman: Hikari no Kyojin Densetsu."
+    source_ref: "libretro.cpp:619,621,597-616"

mkdocs.yml

@@ -24,6 +24,7 @@ theme:
   - navigation.tabs
   - navigation.sections
   - navigation.top
+  - navigation.indexes
   - search.suggest
   - search.highlight
   - content.tabs.link
@@ -32,8 +33,13 @@ markdown_extensions:
 - tables
 - admonition
 - attr_list
+- md_in_html
 - toc:
     permalink: true
+- pymdownx.details
+- pymdownx.superfences
+- pymdownx.tabbed:
+    alternate_style: true
 plugins:
 - search
 nav:
@@ -46,6 +52,7 @@ nav:
   - Recalbox: platforms/recalbox.md
   - RetroArch: platforms/retroarch.md
   - RetroBat: platforms/retrobat.md
+  - RetroDECK: platforms/retrodeck.md
   - RetroPie: platforms/retropie.md
 - Systems:
   - Overview: systems/index.md
@@ -56,6 +63,7 @@ nav:
   - Apple: systems/apple.md
   - Arcade: systems/arcade.md
   - Atari: systems/atari.md
+  - BBK: systems/bbk.md
   - Bally: systems/bally.md
   - Bandai: systems/bandai.md
   - Bit Corporation: systems/bit-corporation.md
@@ -79,20 +87,27 @@ nav:
   - GamePark: systems/gamepark.md
   - Grundy: systems/grundy.md
   - Hartung: systems/hartung.md
+  - IBM: systems/ibm.md
   - Id Software: systems/id-software.md
   - Infocom: systems/infocom.md
   - Java: systems/java.md
+  - Jupiter: systems/jupiter.md
+  - Lambda: systems/lambda.md
+  - Lexaloffle: systems/lexaloffle.md
   - Magnavox: systems/magnavox.md
   - Mattel: systems/mattel.md
+  - Microdigital: systems/microdigital.md
   - Microsoft: systems/microsoft.md
   - NEC: systems/nec.md
   - Nintendo: systems/nintendo.md
   - Nokia: systems/nokia.md
   - Oric: systems/oric.md
+  - Other: systems/other.md
   - Palm: systems/palm.md
   - Philips: systems/philips.md
   - Pioneer: systems/pioneer.md
   - RPG Maker: systems/rpg-maker.md
+  - Ringo: systems/ringo.md
   - SNK: systems/snk.md
   - ScummVM: systems/scummvm.md
   - Sega: systems/sega.md
@@ -103,6 +118,7 @@ nav:
   - Tandy: systems/tandy.md
   - Texas Instruments: systems/texas-instruments.md
   - Tiger: systems/tiger.md
+  - Timex: systems/timex.md
   - Tomy: systems/tomy.md
   - VTech: systems/vtech.md
   - Videoton: systems/videoton.md
@@ -111,192 +127,294 @@ nav:
   - xrick: systems/xrick.md
 - Emulators:
   - Overview: emulators/index.md
-  - '2048': emulators/2048.md
+  - Official ports (60):
-  - 3DEngine: emulators/3dengine.md
+    - amiarcadia: emulators/amiarcadia.md
+    - Amiberry: emulators/amiberry.md
+    - Ardens: emulators/ardens.md
+    - Atari800: emulators/atari800.md
+    - BlastEm: emulators/blastem.md
+    - Boytacean: emulators/boytacean.md
+    - bsnes: emulators/bsnes.md
+    - ClownMDEmu: emulators/clownmdemu.md
+    - CrocoDS: emulators/crocods.md
+    - DirkSimple: emulators/dirksimple.md
+    - DuckStation: emulators/duckstation.md
+    - emux (CHIP-8): emulators/emux_chip8.md
+    - emux (Game Boy): emulators/emux_gb.md
+    - emux (NES): emulators/emux_nes.md
+    - emux (SMS): emulators/emux_sms.md
+    - FinalBurn Neo: emulators/fbneo.md
+    - FinalBurn Neo (CPS-1/CPS-2): emulators/fbneo_cps12.md
+    - FinalBurn Neo (Neo Geo): emulators/fbneo_neogeo.md
+    - fixGB: emulators/fixgb.md
+    - fixNES: emulators/fixnes.md
+    - Flycast: emulators/flycast.md
+    - FreeJ2ME: emulators/freej2me.md
+    - galaksija: emulators/galaksija.md
+    - Gearboy: emulators/gearboy.md
+    - Gearcoleco: emulators/gearcoleco.md
+    - Geargrafx: emulators/geargrafx.md
+    - Gearlynx: emulators/gearlynx.md
+    - Gearsystem: emulators/gearsystem.md
+    - Geolith: emulators/geolith.md
+    - Holani: emulators/holani.md
+    - JAXE: emulators/jaxe.md
+    - JollyCV: emulators/jollycv.md
+    - Kronos: emulators/kronos.md
+    - LowRes NX: emulators/lowresnx.md
+    - M2000: emulators/m2000.md
+    - MAME: emulators/mame.md
+    - MAME Arcade: emulators/mamearcade.md
+    - MAME MESS: emulators/mamemess.md
+    - Mesen: emulators/mesen.md
+    - mesen-s: emulators/mesen-s.md
+    - mGBA: emulators/mgba.md
+    - Mr.Boom: emulators/mrboom.md
+    - Panda3DS: emulators/panda3ds.md
+    - PicoDrive: emulators/picodrive.md
+    - play: emulators/play.md
+    - PPSSPP: emulators/ppsspp.md
+    - Rustation: emulators/rustation.md
+    - RVVM: emulators/rvvm.md
+    - SameBoy: emulators/sameboy.md
+    - sameduck: emulators/sameduck.md
+    - SDLPAL: emulators/sdlpal.md
+    - skyemu: emulators/skyemu.md
+    - snes9x: emulators/snes9x.md
+    - SquirrelJME: emulators/squirreljme.md
+    - VaporSpec: emulators/vaporspec.md
+    - VBA-M: emulators/vbam.md
+    - VeMUlator: emulators/vemulator.md
+    - Vircon32: emulators/vircon32.md
+    - vitaQuakeII: emulators/vitaquake2.md
+    - yabasanshiro: emulators/yabasanshiro.md
+  - Community forks (104):
     - EightyOne: emulators/81.md
     - a5200: emulators/a5200.md
-  - amiarcadia: emulators/amiarcadia.md
     - Anarch: emulators/anarch.md
     - AppleWin: emulators/applewin.md
-  - Ardens: emulators/ardens.md
+    - Azahar: emulators/azahar.md
-  - Arduous: emulators/arduous.md
-  - Atari800: emulators/atari800.md
     - b2: emulators/b2.md
     - Beetle Lynx (Mednafen Lynx): emulators/beetle_lynx.md
     - Beetle NGP (Mednafen Neo Geo Pocket): emulators/beetle_ngp.md
     - Beetle PCE (Mednafen PCE): emulators/beetle_pce.md
     - Beetle PC-FX (Mednafen): emulators/beetle_pcfx.md
     - Beetle PSX (Mednafen PSX): emulators/beetle_psx.md
-  - Beetle Saturn (Mednafen): emulators/beetle_saturn.md
+    - beetle_saturn: emulators/beetle_saturn.md
     - Beetle VB (Mednafen Virtual Boy): emulators/beetle_vb.md
-  - Beetle WonderSwan (Mednafen WonderSwan): emulators/beetle_wswan.md
     - BennuGD: emulators/bennugd.md
     - bk-emulator: emulators/bk.md
-  - BlastEm: emulators/blastem.md
     - blueMSX: emulators/bluemsx.md
-  - bnes: emulators/bnes.md
+    - bsnes-jg: emulators/bsnes-jg.md
-  - boom3: emulators/boom3.md
-  - Boytacean: emulators/boytacean.md
-  - bsnes: emulators/bsnes.md
-  - Cannonball: emulators/cannonball.md
     - Caprice32: emulators/cap32.md
-  - Cemu: emulators/cemu.md
+    - ChimeraSNES: emulators/chimerasnes.md
-  - ChaiLove: emulators/chailove.md
+    - Citra: emulators/citra.md
-  - Citra / Lime3DS / Azahar: emulators/citra.md
+    - Citra Canary: emulators/citra_canary.md
-  - ClownMDEmu: emulators/clownmdemu.md
-  - Craft: emulators/craft.md
-  - CrocoDS: emulators/crocods.md
-  - Cruzes: emulators/cruzes.md
     - Daphne: emulators/daphne.md
     - DeSmuME: emulators/desmume.md
     - DICE: emulators/dice.md
-  - Dinothawr: emulators/dinothawr.md
-  - DirectXBox: emulators/directxbox.md
     - Dolphin: emulators/dolphin.md
-  - Dolphin Launcher: emulators/dolphin_launcher.md
+    - DOSBox: emulators/dosbox.md
     - DOSBox-core: emulators/dosbox_core.md
-  - DOSBox Pure: emulators/dosbox_pure.md
+    - DOSBox-SVN: emulators/dosbox_svn.md
-  - DoubleCherryGB: emulators/doublecherrygb.md
+    - DOSBox-SVN CE: emulators/dosbox_svn_ce.md
-  - doukutsu-rs: emulators/doukutsu_rs.md
-  - DuckStation: emulators/duckstation.md
-  - EasyRPG Player: emulators/easyrpg.md
-  - ECWolf: emulators/ecwolf.md
     - EmuSCV: emulators/emuscv.md
-  - emux (CHIP-8): emulators/emux_chip8.md
+    - ep128emu_core: emulators/ep128emu_core.md
-  - ep128emu-core: emulators/ep128emu.md
-  - FAKE-08: emulators/fake08.md
-  - FinalBurn Neo: emulators/fbneo.md
     - FCEUmm: emulators/fceumm.md
-  - FFmpeg: emulators/ffmpeg.md
-  - fixGB: emulators/fixgb.md
-  - Flycast: emulators/flycast.md
     - fMSX: emulators/fmsx.md
-  - FreeChaF: emulators/freechaf.md
-  - FreeIntv: emulators/freeintv.md
-  - FreeIntv (Touchscreen Overlay): emulators/freeintv_ts_overlay.md
-  - FreeJ2ME: emulators/freej2me.md
     - Frodo: emulators/frodo.md
+    - FS-UAE: emulators/fsuae.md
     - Fuse: emulators/fuse.md
-  - galaksija: emulators/galaksija.md
-  - GAM4980: emulators/gam4980.md
     - Gambatte: emulators/gambatte.md
-  - Gearcoleco: emulators/gearcoleco.md
-  - Geargrafx: emulators/geargrafx.md
-  - Gearlynx: emulators/gearlynx.md
-  - Gearsystem: emulators/gearsystem.md
     - Genesis Plus GX: emulators/genesis_plus_gx.md
-  - Geolith: emulators/geolith.md
-  - Game Music Emu: emulators/gme.md
-  - Gong: emulators/gong.md
     - gpSP: emulators/gpsp.md
-  - Game & Watch: emulators/gw.md
     - Handy: emulators/handy.md
-  - Hatari: emulators/hatari.md
+    - higan (SFC Accuracy): emulators/higan_sfc.md
-  - HBMAME (Homebrew MAME): emulators/hbmame.md
+    - LRPS2: emulators/lrps2.md
-  - Holani: emulators/holani.md
+    - mednafen_pce: emulators/mednafen_pce.md
-  - Image Viewer: emulators/imageviewer.md
+    - mednafen_pce_fast: emulators/mednafen_pce_fast.md
-  - Ishiiruka: emulators/ishiiruka.md
+    - mednafen_supafaust: emulators/mednafen_supafaust.md
-  - JAXE: emulators/jaxe.md
+    - mednafen_supergrafx: emulators/mednafen_supergrafx.md
-  - JollyCV: emulators/jollycv.md
+    - melonDS: emulators/melonds.md
-  - Jump 'n Bump: emulators/jumpnbump.md
+    - melonDS DS: emulators/melonds_ds.md
-  - Kronos: emulators/kronos.md
-  - LowRes NX: emulators/lowresnx.md
-  - Lutro: emulators/lutro.md
-  - M2000: emulators/m2000.md
-  - MAME 2003-Plus: emulators/mame2003_plus.md
-  - MAME 2010: emulators/mame2010.md
-  - MAME 2016: emulators/mame2016.md
-  - MCSoftserve: emulators/mcsoftserve.md
-  - MelonDS: emulators/melonds.md
-  - Mesen: emulators/mesen.md
     - Meteor GBA: emulators/meteor.md
-  - mGBA: emulators/mgba.md
     - Mini vMac: emulators/minivmac.md
-  - mkxp-z: emulators/mkxp_z.md
-  - MojoZork: emulators/mojozork.md
     - Moonlight: emulators/moonlight.md
     - mpv: emulators/mpv.md
-  - Mr.Boom: emulators/mrboom.md
+    - nekop2: emulators/nekop2.md
-  - Mu: emulators/mu.md
+    - nes: emulators/nes.md
-  - Mupen64Plus-Next: emulators/mupen64plus.md
-  - NeoCD: emulators/neocd.md
     - Nestopia UE: emulators/nestopia.md
     - NooDS: emulators/noods.md
-  - NP2kai: emulators/np2kai.md
     - Numero: emulators/numero.md
-  - NXEngine: emulators/nxengine.md
     - O2EM: emulators/o2em.md
     - Oberon: emulators/oberon.md
     - ONScripter: emulators/onscripter.md
-  - ONScripter Yuri: emulators/onsyuri.md
-  - OpenLara: emulators/openlara.md
-  - OpenTyrian: emulators/opentyrian.md
     - Opera (4DO): emulators/opera.md
-  - Panda3DS: emulators/panda3ds.md
+    - ParaLLEl N64: emulators/parallel_n64.md
-  - Pascal Pong: emulators/pascal_pong.md
     - PCem: emulators/pcem.md
-  - PCSX2: emulators/pcsx2.md
+    - PCSX1: emulators/pcsx1.md
-  - PCSX-ReARMed: emulators/pcsx_rearmed.md
     - PD777: emulators/pd777.md
-  - PicoDrive: emulators/picodrive.md
-  - Play!: emulators/play.md
-  - PocketCDG: emulators/pocketcdg.md
     - PokeMini: emulators/pokemini.md
-  - PPSSPP: emulators/ppsspp.md
+    - Potator: emulators/potator.md
-  - PrBoom: emulators/prboom.md
     - ProSystem: emulators/prosystem.md
     - PUAE (P-UAE): emulators/puae.md
-  - PuzzleScript: emulators/puzzlescript.md
     - px68k: emulators/px68k.md
     - QEMU: emulators/qemu.md
     - QUASI88: emulators/quasi88.md
+    - QuickNES: emulators/quicknes.md
     - RACE (Neo Geo Pocket): emulators/race.md
-  - Redbook: emulators/redbook.md
     - REminiscence: emulators/reminiscence.md
-  - RemoteJoy: emulators/remotejoy.md
-  - Retro8: emulators/retro8.md
     - RetroDream: emulators/retrodream.md
-  - ROM Cleaner: emulators/romcleaner.md
-  - RPCS3: emulators/rpcs3.md
-  - Rustation: emulators/rustation.md
-  - RVVM: emulators/rvvm.md
     - SAME CDi: emulators/same_cdi.md
-  - SameBoy: emulators/sameboy.md
-  - ScummVM: emulators/scummvm.md
-  - SDLPAL: emulators/sdlpal.md
     - SimCoupe: emulators/simcp.md
-  - SMS Plus GX: emulators/smsplus.md
+    - swanstation: emulators/swanstation.md
-  - snes9x: emulators/snes9x.md
-  - SquirrelJME: emulators/squirreljme.md
-  - Stella: emulators/stella.md
-  - Stone Soup: emulators/stonesoup.md
-  - Super Bros War: emulators/superbroswar.md
     - Syobon Action: emulators/syobonaction.md
     - TamaLIBretro: emulators/tamalibretro.md
     - TempGBA: emulators/tempgba.md
     - TGB Dual: emulators/tgbdual.md
-  - Theodore: emulators/theodore.md
+    - trident: emulators/trident.md
-  - The Powder Toy: emulators/thepowdertoy.md
+    - uae4arm: emulators/uae4arm.md
-  - TIC-80: emulators/tic80.md
-  - TyrQuake: emulators/tyrquake.md
-  - MicroW8: emulators/uw8.md
     - UXN: emulators/uxn.md
-  - uzem: emulators/uzem.md
-  - VaporSpec: emulators/vaporspec.md
-  - VBA-Next: emulators/vba_next.md
     - vecx: emulators/vecx.md
-  - VeMUlator: emulators/vemulator.md
+    - VICE x128: emulators/vice_x128.md
-  - VICE: emulators/vice.md
+    - VICE x64: emulators/vice_x64.md
-  - Vircon32: emulators/vircon32.md
+    - VICE x64dtv: emulators/vice_x64dtv.md
+    - VICE x64sc: emulators/vice_x64sc.md
+    - VICE xcbm2: emulators/vice_xcbm2.md
+    - VICE xcbm5x0: emulators/vice_xcbm5x0.md
+    - VICE xpet: emulators/vice_xpet.md
+    - VICE xplus4: emulators/vice_xplus4.md
+    - VICE xscpu64: emulators/vice_xscpu64.md
+    - VICE xvic: emulators/vice_xvic.md
     - Virtual Jaguar: emulators/virtualjaguar.md
-  - VirtualXT: emulators/virtualxt.md
-  - Vita3K: emulators/vita3k.md
-  - vitaQuakeII: emulators/vitaquake2.md
     - vitaQuakeIII: emulators/vitaquake3.md
-  - WASM-4: emulators/wasm4.md
+    - vitavoyager: emulators/vitavoyager.md
     - X Millennium: emulators/x1.md
     - x64sdl: emulators/x64sdl.md
-  - Xemu: emulators/xemu.md
+    - yabause: emulators/yabause.md
+    - ymir: emulators/ymir.md
+  - Pure libretro (29):
+    - '2048': emulators/2048.md
+    - 3DEngine: emulators/3dengine.md
+    - Arduous: emulators/arduous.md
+    - Beetle WonderSwan (Mednafen WonderSwan): emulators/beetle_wswan.md
+    - Craft: emulators/craft.md
+    - Cruzes: emulators/cruzes.md
+    - DirectXBox: emulators/directxbox.md
+    - FFmpeg: emulators/ffmpeg.md
+    - FreeChaF: emulators/freechaf.md
+    - FreeIntv: emulators/freeintv.md
+    - GAM4980: emulators/gam4980.md
+    - Game Music Emu: emulators/gme.md
+    - Gong: emulators/gong.md
+    - Game & Watch: emulators/gw.md
+    - Image Viewer: emulators/imageviewer.md
+    - MCSoftserve: emulators/mcsoftserve.md
+    - MojoZork: emulators/mojozork.md
+    - Mu: emulators/mu.md
+    - NeoCD: emulators/neocd.md
+    - Pascal Pong: emulators/pascal_pong.md
+    - PocketCDG: emulators/pocketcdg.md
+    - Redbook: emulators/redbook.md
+    - RemoteJoy: emulators/remotejoy.md
+    - ROM Cleaner: emulators/romcleaner.md
+    - Theodore: emulators/theodore.md
+    - The Powder Toy: emulators/thepowdertoy.md
+    - MicroW8: emulators/uw8.md
+    - uzem: emulators/uzem.md
+    - VirtualXT: emulators/virtualxt.md
+  - Game engines (24):
+    - boom3: emulators/boom3.md
+    - Cannonball: emulators/cannonball.md
+    - ChaiLove: emulators/chailove.md
+    - Dinothawr: emulators/dinothawr.md
+    - doukutsu-rs: emulators/doukutsu_rs.md
+    - EasyRPG Player: emulators/easyrpg.md
+    - ECWolf: emulators/ecwolf.md
+    - FAKE-08: emulators/fake08.md
+    - Jump 'n Bump: emulators/jumpnbump.md
+    - Lutro: emulators/lutro.md
+    - mkxp-z: emulators/mkxp_z.md
+    - NXEngine: emulators/nxengine.md
+    - ONScripter Yuri: emulators/onsyuri.md
+    - OpenLara: emulators/openlara.md
+    - OpenTyrian: emulators/opentyrian.md
+    - PrBoom: emulators/prboom.md
+    - PuzzleScript: emulators/puzzlescript.md
+    - Retro8: emulators/retro8.md
+    - ScummVM: emulators/scummvm.md
+    - Super Bros War: emulators/superbroswar.md
+    - TIC-80: emulators/tic80.md
+    - TyrQuake: emulators/tyrquake.md
+    - WASM-4: emulators/wasm4.md
     - XRick: emulators/xrick.md
+  - Enhanced forks (12):
+    - bsnes-hd beta: emulators/bsnes_hd_beta.md
+    - bsnes-mercury: emulators/bsnes_mercury.md
+    - DOSBox Pure: emulators/dosbox_pure.md
+    - DoubleCherryGB: emulators/doublecherrygb.md
+    - Genesis Plus GX Wide: emulators/genesis_plus_gx_wide.md
+    - HBMAME (Homebrew MAME): emulators/hbmame.md
+    - nSide (SFC Balanced): emulators/higan_sfc_balanced.md
+    - Ishiiruka: emulators/ishiiruka.md
+    - MAME 2003-Plus: emulators/mame2003_plus.md
+    - Mupen64Plus-Next: emulators/mupen64plus_next.md
+    - NP2kai: emulators/np2kai.md
+    - SMS Plus GX: emulators/smsplus.md
+  - Frozen snapshots (32):
+    - bnes: emulators/bnes.md
+    - bsnes 2014: emulators/bsnes2014.md
+    - bsnes C++98: emulators/bsnes_cplusplus98.md
+    - CDi 2015: emulators/cdi2015.md
+    - Citra 2018: emulators/citra2018.md
+    - DeSmuME 2015: emulators/desmume2015.md
+    - FB Alpha 2012: emulators/fbalpha2012.md
+    - FB Alpha 2012 CPS-1: emulators/fbalpha2012_cps1.md
+    - FB Alpha 2012 CPS-2: emulators/fbalpha2012_cps2.md
+    - FB Alpha 2012 CPS-3: emulators/fbalpha2012_cps3.md
+    - FB Alpha 2012 Neo Geo: emulators/fbalpha2012_neogeo.md
+    - Hatari: emulators/hatari.md
+    - MAME 2000: emulators/mame2000.md
+    - MAME 2003: emulators/mame2003.md
+    - MAME 2003 Midway: emulators/mame2003_midway.md
+    - MAME 2009: emulators/mame2009.md
+    - MAME 2010: emulators/mame2010.md
+    - MAME 2015: emulators/mame2015.md
+    - MAME 2016: emulators/mame2016.md
+    - mednafen_gba: emulators/mednafen_gba.md
+    - mednafen_snes: emulators/mednafen_snes.md
+    - MESS 2015: emulators/mess2015.md
+    - PUAE 2021: emulators/puae2021.md
+    - Snes9x 2002: emulators/snes9x2002.md
+    - Snes9x 2005: emulators/snes9x2005.md
+    - Snes9x 2005 Plus: emulators/snes9x2005_plus.md
+    - Snes9x 2010: emulators/snes9x2010.md
+    - Stella 2014: emulators/stella2014.md
+    - Stella 2023: emulators/stella2023.md
+    - Stone Soup: emulators/stonesoup.md
+    - UME 2015: emulators/ume2015.md
+    - VBA-Next: emulators/vba_next.md
+  - Embedded HLE (1):
+    - PCSX-ReARMed: emulators/pcsx_rearmed.md
+  - Launchers (1):
+    - Dolphin Launcher: emulators/dolphin_launcher.md
+  - Other (10):
+    - Beetle GBA (Mednafen): emulators/beetle_gba.md
+    - Cemu: emulators/cemu.md
+    - ep128emu-core: emulators/ep128emu.md
+    - PCSX2: emulators/pcsx2.md
+    - Redream: emulators/redream.md
+    - RPCS3: emulators/rpcs3.md
+    - VBA-M: emulators/vba_m.md
+    - VICE: emulators/vice.md
+    - Vita3K: emulators/vita3k.md
+    - Xemu: emulators/xemu.md
+- Cross-reference: cross-reference.md
 - Gap Analysis: gaps.md
+- Wiki:
+  - Overview: wiki/index.md
+  - Architecture: wiki/architecture.md
+  - Tools: wiki/tools.md
+  - Profiling guide: wiki/profiling.md
+  - Data model: wiki/data-model.md
 - Contributing: contributing.md

scripts/common.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import urllib.error
+import urllib.request
 import zipfile
 import zlib
 from pathlib import Path
@@ -416,16 +418,23 @@ def group_identical_platforms(
     """Group platforms that produce identical packs (same files + base_destination).
 
     Returns [(group_of_platform_names, representative), ...].
+    The representative is the root platform (one that does not inherit).
     """
     fingerprints: dict[str, list[str]] = {}
     representatives: dict[str, str] = {}
+    inherits: dict[str, bool] = {}
 
     for platform in platforms:
         try:
+            raw_path = os.path.join(platforms_dir, f"{platform}.yml")
+            with open(raw_path) as f:
+                raw = yaml.safe_load(f) or {}
+            inherits[platform] = "inherits" in raw
             config = load_platform_config(platform, platforms_dir)
         except FileNotFoundError:
             fingerprints.setdefault(platform, []).append(platform)
             representatives.setdefault(platform, platform)
+            inherits[platform] = False
             continue
 
         base_dest = config.get("base_destination", "")
@@ -440,9 +449,16 @@ def group_identical_platforms(
 
         fp = hashlib.sha1("|".join(sorted(entries)).encode()).hexdigest()
         fingerprints.setdefault(fp, []).append(platform)
-        representatives.setdefault(fp, platform)
+        # Prefer the root platform (no inherits) as representative
+        if fp not in representatives or (not inherits[platform] and inherits.get(representatives[fp], False)):
+            representatives[fp] = platform
 
-    return [(group, representatives[fp]) for fp, group in fingerprints.items()]
+    result = []
+    for fp, group in fingerprints.items():
+        rep = representatives[fp]
+        ordered = [rep] + [p for p in group if p != rep]
+        result.append((ordered, rep))
+    return result
 
 
 def resolve_platform_cores(
@@ -537,8 +553,10 @@ def _build_validation_index(profiles: dict) -> dict[str, dict]:
                     "min_size": None, "max_size": None,
                     "crc32": set(), "md5": set(), "sha1": set(), "sha256": set(),
                     "adler32": set(), "crypto_only": set(),
+                    "emulators": set(),
                 }
                 sources[fname] = {}
+            index[fname]["emulators"].add(emu_name)
             index[fname]["checks"].update(checks)
             # Track non-reproducible crypto checks
             index[fname]["crypto_only"].update(
@@ -584,6 +602,7 @@ def _build_validation_index(profiles: dict) -> dict[str, dict]:
     for v in index.values():
         v["checks"] = sorted(v["checks"])
         v["crypto_only"] = sorted(v["crypto_only"])
+        v["emulators"] = sorted(v["emulators"])
         # Keep hash sets as frozensets for O(1) lookup in check_file_validation
     return index
 
@@ -677,6 +696,59 @@ def filter_files_by_mode(files: list[dict], standalone: bool) -> list[dict]:
     return result
 
 
+LARGE_FILES_RELEASE = "large-files"
+LARGE_FILES_REPO = "Abdess/retrobios"
+LARGE_FILES_CACHE = ".cache/large"
+
+
+def fetch_large_file(name: str, dest_dir: str = LARGE_FILES_CACHE,
+                     expected_sha1: str = "", expected_md5: str = "") -> str | None:
+    """Download a large file from the 'large-files' GitHub release if not cached."""
+    cached = os.path.join(dest_dir, name)
+    if os.path.exists(cached):
+        if expected_sha1 or expected_md5:
+            hashes = compute_hashes(cached)
+            if expected_sha1 and hashes["sha1"].lower() != expected_sha1.lower():
+                os.unlink(cached)
+            elif expected_md5:
+                md5_list = [m.strip().lower() for m in expected_md5.split(",") if m.strip()]
+                if hashes["md5"].lower() not in md5_list:
+                    os.unlink(cached)
+                else:
+                    return cached
+            else:
+                return cached
+        else:
+            return cached
+
+    encoded_name = urllib.request.quote(name)
+    url = f"https://github.com/{LARGE_FILES_REPO}/releases/download/{LARGE_FILES_RELEASE}/{encoded_name}"
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "retrobios/1.0"})
+        with urllib.request.urlopen(req, timeout=300) as resp:
+            os.makedirs(dest_dir, exist_ok=True)
+            with open(cached, "wb") as f:
+                while True:
+                    chunk = resp.read(65536)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+    except (urllib.error.URLError, urllib.error.HTTPError):
+        return None
+
+    if expected_sha1 or expected_md5:
+        hashes = compute_hashes(cached)
+        if expected_sha1 and hashes["sha1"].lower() != expected_sha1.lower():
+            os.unlink(cached)
+            return None
+        if expected_md5:
+            md5_list = [m.strip().lower() for m in expected_md5.split(",") if m.strip()]
+            if hashes["md5"].lower() not in md5_list:
+                os.unlink(cached)
+                return None
+    return cached
+
+
 def safe_extract_zip(zip_path: str, dest_dir: str) -> None:
     """Extract a ZIP file safely, preventing zip-slip path traversal."""
     dest = os.path.realpath(dest_dir)

scripts/generate_db.py

@@ -216,6 +216,62 @@ def save_cache(cache_path: str, cache: dict):
         json.dump(cache, f)
 
 
+def _load_gitignored_large_files() -> dict[str, str]:
+    """Read .gitignore and return {filename: bios_path} for large files."""
+    gitignore = Path(".gitignore")
+    if not gitignore.exists():
+        return {}
+    entries = {}
+    for line in gitignore.read_text().splitlines():
+        line = line.strip()
+        if line.startswith("bios/") and not line.startswith("#"):
+            name = Path(line).name
+            entries[name] = line
+    return entries
+
+
+def _preserve_large_file_entries(files: dict, db_path: str) -> int:
+    """Preserve database entries for large files not on disk.
+
+    Large files (>50 MB) are stored as GitHub release assets and listed
+    in .gitignore. When generate_db runs locally without them, their
+    entries would be lost. This reads the existing database, downloads
+    missing files from the release, and re-adds entries with paths
+    pointing to the local cache.
+    """
+    from common import fetch_large_file
+
+    large_files = _load_gitignored_large_files()
+    if not large_files:
+        return 0
+
+    try:
+        with open(db_path) as f:
+            existing_db = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return 0
+
+    count = 0
+    for sha1, entry in existing_db.get("files", {}).items():
+        if sha1 in files:
+            continue
+        name = entry.get("name", "")
+        path = entry.get("path", "")
+        # Match by gitignored bios/ path OR by filename of a known large file
+        if path not in large_files.values() and name not in large_files:
+            continue
+        cached = fetch_large_file(
+            name,
+            expected_sha1=entry.get("sha1", ""),
+            expected_md5=entry.get("md5", ""),
+        )
+        if cached:
+            entry = {**entry, "path": cached}
+        files[sha1] = entry
+        count += 1
+    return count
+
+
 def main():
     parser = argparse.ArgumentParser(description="Generate multi-indexed BIOS database")
     parser.add_argument("--force", action="store_true", help="Force rehash all files")
@@ -236,6 +292,11 @@ def main():
     if not files:
         print("Warning: No BIOS files found", file=sys.stderr)
 
+    # Preserve entries for large files stored as release assets (.gitignore)
+    preserved = _preserve_large_file_entries(files, args.output)
+    if preserved:
+        print(f"  Preserved {preserved} large file entries from existing database")
+
     platform_aliases = _collect_all_aliases(files)
     for sha1, name_list in platform_aliases.items():
         for alias_entry in name_list:

scripts/generate_pack.py

@@ -26,7 +26,7 @@ from pathlib import Path
 sys.path.insert(0, os.path.dirname(__file__))
 from common import (
     _build_validation_index, build_zip_contents_index, check_file_validation,
-    check_inside_zip, compute_hashes, filter_files_by_mode,
+    check_inside_zip, compute_hashes, fetch_large_file, filter_files_by_mode,
     group_identical_platforms, list_emulator_profiles, list_system_ids,
     load_database, load_data_dir_registry, load_emulator_profiles,
     load_platform_config, md5_composite, resolve_local_file,
@@ -43,55 +43,48 @@ DEFAULT_PLATFORMS_DIR = "platforms"
 DEFAULT_DB_FILE = "database.json"
 DEFAULT_OUTPUT_DIR = "dist"
 DEFAULT_BIOS_DIR = "bios"
-LARGE_FILES_RELEASE = "large-files"
-LARGE_FILES_REPO = "Abdess/retrobios"
-
 MAX_ENTRY_SIZE = 512 * 1024 * 1024  # 512MB
 
 
-def _verify_file_hash(path: str, expected_sha1: str = "",
+def _find_candidate_satisfying_both(
-                      expected_md5: str = "") -> bool:
+    file_entry: dict,
-    if not expected_sha1 and not expected_md5:
+    db: dict,
-        return True
+    local_path: str,
-    hashes = compute_hashes(path)
+    validation_index: dict,
-    if expected_sha1:
+    bios_dir: str,
-        return hashes["sha1"].lower() == expected_sha1.lower()
+) -> str | None:
-    md5_list = [m.strip().lower() for m in expected_md5.split(",") if m.strip()]
+    """Search for a repo file that satisfies both platform MD5 and emulator validation.
-    return hashes["md5"].lower() in md5_list
 
-
+    When the current file passes platform verification but fails emulator checks,
-def fetch_large_file(name: str, dest_dir: str = ".cache/large",
+    search all candidates with the same name for one that passes both.
-                     expected_sha1: str = "", expected_md5: str = "") -> str | None:
+    Returns a better path, or None if no upgrade found.
-    """Download a large file from the 'large-files' GitHub release if not cached."""
+    """
-    cached = os.path.join(dest_dir, name)
+    fname = file_entry.get("name", "")
-    if os.path.exists(cached):
+    if not fname:
-        if expected_sha1 or expected_md5:
+        return None
-            if _verify_file_hash(cached, expected_sha1, expected_md5):
+    entry = validation_index.get(fname)
-                return cached
+    if not entry:
-            os.unlink(cached)
-        else:
-            return cached
-
-    encoded_name = urllib.request.quote(name)
-    url = f"https://github.com/{LARGE_FILES_REPO}/releases/download/{LARGE_FILES_RELEASE}/{encoded_name}"
-    try:
-        req = urllib.request.Request(url, headers={"User-Agent": "retrobios-pack/1.0"})
-        with urllib.request.urlopen(req, timeout=300) as resp:
-            os.makedirs(dest_dir, exist_ok=True)
-            with open(cached, "wb") as f:
-                while True:
-                    chunk = resp.read(65536)
-                    if not chunk:
-                        break
-                    f.write(chunk)
-    except (urllib.error.URLError, urllib.error.HTTPError):
         return None
 
-    if expected_sha1 or expected_md5:
+    md5_expected = file_entry.get("md5", "")
-        if not _verify_file_hash(cached, expected_sha1, expected_md5):
+    md5_set = {m.strip().lower() for m in md5_expected.split(",") if m.strip()} if md5_expected else set()
-            os.unlink(cached)
+
+    by_name = db.get("indexes", {}).get("by_name", {})
+    files_db = db.get("files", {})
+
+    for sha1 in by_name.get(fname, []):
+        candidate = files_db.get(sha1, {})
+        path = candidate.get("path", "")
+        if not path or not os.path.exists(path) or os.path.realpath(path) == os.path.realpath(local_path):
+            continue
+        # Must still satisfy platform MD5
+        if md5_set and candidate.get("md5", "").lower() not in md5_set:
+            continue
+        # Check emulator validation
+        reason = check_file_validation(path, fname, validation_index, bios_dir)
+        if reason is None:
+            return path
     return None
-    return cached
 
 
 def _sanitize_path(raw: str) -> str:
@@ -118,10 +111,11 @@ def resolve_file(file_entry: dict, db: dict, bios_dir: str,
 
     path, status = resolve_local_file(file_entry, db, zip_contents,
                                       dest_hint=dest_hint)
-    if path:
+    if path and status != "hash_mismatch":
         return path, status
 
-    # Last resort: large files from GitHub release assets
+    # Large files from GitHub release assets — tried when local file is
+    # missing OR has a hash mismatch (wrong variant on disk)
     name = file_entry.get("name", "")
     sha1 = file_entry.get("sha1")
     md5_raw = file_entry.get("md5", "")
@@ -131,6 +125,10 @@ def resolve_file(file_entry: dict, db: dict, bios_dir: str,
     if cached:
         return cached, "release_asset"
 
+    # Fall back to hash_mismatch local file if release asset unavailable
+    if path:
+        return path, status
+
     return None, "not_found"
 
 
@@ -362,20 +360,28 @@ def generate_pack(
                 else:
                     file_status.setdefault(dedup_key, "ok")
 
-                # Emulator-level validation (matches verify.py behavior)
+                # Emulator-level validation: informational only for platform packs.
-                # In existence mode: validation is informational (warning, not downgrade)
+                # Platform verification (existence/md5) is the authority for pack status.
-                # In md5 mode: validation downgrades OK to UNTESTED
+                # Emulator checks are supplementary — logged but don't downgrade.
+                # When a discrepancy is found, try to find a file satisfying both.
                 if (file_status.get(dedup_key) == "ok"
                         and local_path and validation_index):
                     fname = file_entry.get("name", "")
-                    reason = check_file_validation(local_path, fname, validation_index)
+                    reason = check_file_validation(local_path, fname, validation_index,
+                                                   bios_dir)
                     if reason:
-                        if verification_mode == "existence":
+                        better = _find_candidate_satisfying_both(
-                            # Existence mode: file present = OK, validation is extra info
+                            file_entry, db, local_path, validation_index, bios_dir,
-                            file_reasons.setdefault(dedup_key, reason)
+                        )
+                        if better:
+                            local_path = better
                         else:
-                            file_status[dedup_key] = "untested"
+                            ventry = validation_index.get(fname, {})
-                            file_reasons[dedup_key] = reason
+                            emus = ", ".join(ventry.get("emulators", []))
+                            file_reasons.setdefault(
+                                dedup_key,
+                                f"{platform_display} says OK but {emus} says {reason}",
+                            )
 
                 if already_packed:
                     continue
@@ -475,7 +481,7 @@ def generate_pack(
 
     for key, reason in sorted(file_reasons.items()):
         status = file_status.get(key, "")
-        label = "UNTESTED"
+        label = "UNTESTED" if status == "untested" else "DISCREPANCY"
         print(f"  {label}: {key} — {reason}")
     for name in missing_files:
         print(f"  MISSING: {name}")
@@ -915,10 +921,11 @@ def main():
     groups = group_identical_platforms(platforms, args.platforms_dir)
 
     for group_platforms, representative in groups:
-        if len(group_platforms) > 1:
+        variants = [p for p in group_platforms if p != representative]
-            names = [load_platform_config(p, args.platforms_dir).get("platform", p) for p in group_platforms]
+        if variants:
-            combined_name = " + ".join(names)
+            all_names = [load_platform_config(p, args.platforms_dir).get("platform", p) for p in group_platforms]
-            print(f"\nGenerating shared pack for {combined_name}...")
+            label = " / ".join(all_names)
+            print(f"\nGenerating pack for {label}...")
         else:
             print(f"\nGenerating pack for {representative}...")
 
@@ -929,10 +936,10 @@ def main():
                 zip_contents=zip_contents, data_registry=data_registry,
                 emu_profiles=emu_profiles,
             )
-            if zip_path and len(group_platforms) > 1:
+            if zip_path and variants:
-                names = [load_platform_config(p, args.platforms_dir).get("platform", p) for p in group_platforms]
+                all_names = [load_platform_config(p, args.platforms_dir).get("platform", p) for p in group_platforms]
-                combined_filename = "_".join(n.replace(" ", "") for n in names) + "_BIOS_Pack.zip"
+                combined = "_".join(n.replace(" ", "") for n in all_names) + "_BIOS_Pack.zip"
-                new_path = os.path.join(os.path.dirname(zip_path), combined_filename)
+                new_path = os.path.join(os.path.dirname(zip_path), combined)
                 if new_path != zip_path:
                     os.rename(zip_path, new_path)
                     print(f"  Renamed -> {os.path.basename(new_path)}")

scripts/generate_readme.py

@@ -97,11 +97,27 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
     ) if Path("emulators").exists() else 0
 
     lines = [
-        "# Retrogaming BIOS & Firmware Collection",
+        "# RetroBIOS",
         "",
-        "Complete, verified collection of BIOS, firmware, and system files for retrogaming emulators.",
+        "Source-verified BIOS and firmware packs for retrogaming platforms.",
         "",
-        f"> **{total_files}** files | **{size_mb:.1f} MB** | **{len(coverages)}** platforms | **{emulator_count}** emulator profiles",
+        "Documentation and metadata can drift from what emulators actually load at runtime.",
+        "To keep packs accurate, each file here is checked against the emulator's source code:",
+        "what the code opens, what hashes it expects, what happens when a file is missing.",
+        f"{emulator_count} emulators profiled, {len(coverages)} platforms cross-referenced,",
+        f"{total_files:,} files verified.",
+        "",
+        "### How it works",
+        "",
+        "1. **Read emulator source code** - identify every file the code loads, its expected hash and size",
+        "2. **Cross-reference with platforms** - match against what RetroArch, Batocera, Recalbox and others declare",
+        "3. **Build packs** - for each platform, include its baseline files plus what its cores need",
+        "4. **Verify** - run each platform's native checks (MD5, existence) and emulator-level validation (CRC32, size)",
+        "",
+        "When a platform and an emulator disagree on a file, the discrepancy is reported.",
+        "When a variant in the repo satisfies both, it is preferred automatically.",
+        "",
+        f"> **{total_files:,}** files | **{size_mb:.1f} MB** | **{len(coverages)}** platforms | **{emulator_count}** emulator profiles",
         "",
         "## Download",
         "",

scripts/pipeline.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Run the full retrobios pipeline: generate DB, verify, generate packs.
+"""Run the full retrobios pipeline.
 
 Steps:
   1. generate_db.py --force     (rebuild database.json from bios/)
@@ -7,11 +7,14 @@ Steps:
   3. verify.py --all            (check all platforms)
   4. generate_pack.py --all     (build ZIP packs)
   5. consistency check          (verify counts == pack counts)
+  6. generate_readme.py         (rebuild README.md + CONTRIBUTING.md)
+  7. generate_site.py           (rebuild MkDocs pages)
 
 Usage:
     python scripts/pipeline.py                    # active platforms
     python scripts/pipeline.py --include-archived # all platforms
     python scripts/pipeline.py --skip-packs       # steps 1-3 only
+    python scripts/pipeline.py --skip-docs        # skip steps 6-7
     python scripts/pipeline.py --offline          # skip step 2
 """
 from __future__ import annotations
@@ -94,7 +97,7 @@ def check_consistency(verify_output: str, pack_output: str) -> bool:
     v = parse_verify_counts(verify_output)
     p = parse_pack_counts(pack_output)
 
-    print("\n--- 5/5 consistency check ---")
+    print("\n--- 5/7 consistency check ---")
     all_ok = True
 
     for v_label, (v_ok, v_total) in sorted(v.items()):
@@ -128,6 +131,8 @@ def main():
                         help="Include archived platforms")
     parser.add_argument("--skip-packs", action="store_true",
                         help="Only regenerate DB and verify, skip pack generation")
+    parser.add_argument("--skip-docs", action="store_true",
+                        help="Skip README and site generation")
     parser.add_argument("--offline", action="store_true",
                         help="Skip data directory refresh")
     parser.add_argument("--output-dir", default="dist",
@@ -145,7 +150,7 @@ def main():
     ok, out = run(
         [sys.executable, "scripts/generate_db.py", "--force",
          "--bios-dir", "bios", "--output", "database.json"],
-        "1/5 generate database",
+        "1/7 generate database",
     )
     results["generate_db"] = ok
     if not ok:
@@ -156,18 +161,18 @@ def main():
     if not args.offline:
         ok, out = run(
             [sys.executable, "scripts/refresh_data_dirs.py"],
-            "2/5 refresh data directories",
+            "2/7 refresh data directories",
         )
         results["refresh_data"] = ok
     else:
-        print("\n--- 2/5 refresh data directories: SKIPPED (--offline) ---")
+        print("\n--- 2/7 refresh data directories: SKIPPED (--offline) ---")
         results["refresh_data"] = True
 
     # Step 3: Verify
     verify_cmd = [sys.executable, "scripts/verify.py", "--all"]
     if args.include_archived:
         verify_cmd.append("--include-archived")
-    ok, verify_output = run(verify_cmd, "3/5 verify all platforms")
+    ok, verify_output = run(verify_cmd, "3/7 verify all platforms")
     results["verify"] = ok
     all_ok = all_ok and ok
 
@@ -184,11 +189,11 @@ def main():
             pack_cmd.append("--offline")
         if args.include_extras:
             pack_cmd.append("--include-extras")
-        ok, pack_output = run(pack_cmd, "4/5 generate packs")
+        ok, pack_output = run(pack_cmd, "4/7 generate packs")
         results["generate_packs"] = ok
         all_ok = all_ok and ok
     else:
-        print("\n--- 4/5 generate packs: SKIPPED (--skip-packs) ---")
+        print("\n--- 4/7 generate packs: SKIPPED (--skip-packs) ---")
         results["generate_packs"] = True
 
     # Step 5: Consistency check
@@ -197,9 +202,34 @@ def main():
         results["consistency"] = ok
         all_ok = all_ok and ok
     else:
-        print("\n--- 5/5 consistency check: SKIPPED ---")
+        print("\n--- 5/7 consistency check: SKIPPED ---")
         results["consistency"] = True
 
+    # Step 6: Generate README
+    if not args.skip_docs:
+        ok, _ = run(
+            [sys.executable, "scripts/generate_readme.py",
+             "--db", "database.json", "--platforms-dir", "platforms"],
+            "6/7 generate readme",
+        )
+        results["generate_readme"] = ok
+        all_ok = all_ok and ok
+    else:
+        print("\n--- 6/7 generate readme: SKIPPED (--skip-docs) ---")
+        results["generate_readme"] = True
+
+    # Step 7: Generate site pages
+    if not args.skip_docs:
+        ok, _ = run(
+            [sys.executable, "scripts/generate_site.py"],
+            "7/7 generate site",
+        )
+        results["generate_site"] = ok
+        all_ok = all_ok and ok
+    else:
+        print("\n--- 7/7 generate site: SKIPPED (--skip-docs) ---")
+        results["generate_site"] = True
+
     # Summary
     total_elapsed = time.monotonic() - total_start
     print(f"\n{'=' * 60}")

wiki/architecture.md

@@ -0,0 +1,144 @@
+# Architecture - RetroBIOS
+
+## Directory structure
+
+```
+bios/                    BIOS and firmware files, organized by Manufacturer/Console/
+  Manufacturer/Console/  canonical files (one per unique content)
+  .variants/             alternate versions (different hash, same purpose)
+emulators/               one YAML profile per core (285 profiles)
+platforms/               one YAML config per platform (scraped from upstream)
+  _shared.yml            shared file groups across platforms
+  _registry.yml          platform metadata (logos, scrapers, status)
+  _data_dirs.yml         data directory definitions (Dolphin Sys, PPSSPP...)
+scripts/                 all tooling (Python, pyyaml only dependency)
+  scraper/               upstream scrapers (libretro, batocera, recalbox...)
+data/                    cached data directories (not BIOS, fetched at build)
+schemas/                 JSON schemas for validation
+tests/                   E2E test suite with synthetic fixtures
+dist/                    generated packs (gitignored)
+.cache/                  hash cache and large file downloads (gitignored)
+```
+
+## Data flow
+
+```
+Upstream sources          Scrapers parse       generate_db.py scans
+  System.dat (libretro)   + fetch versions     bios/ on disk
+  batocera-systems                             builds database.json
+  es_bios.xml (recalbox)                       (SHA1 primary key,
+  core-info .info files                         indexes: by_md5, by_name,
+                                                by_crc32, by_path_suffix)
+
+emulators/*.yml          verify.py checks      generate_pack.py resolves
+  source-verified         platform-native       files by hash, builds ZIP
+  from code               verification          packs per platform
+```
+
+## Three layers of data
+
+| Layer | Source | Role |
+|-------|--------|------|
+| Platform YAML | Scraped from upstream | What the platform declares it needs |
+| `_shared.yml` | Curated | Shared files across platforms, reflects actual behavior |
+| Emulator profiles | Source-verified | What the code actually loads. Used for cross-reference and gap detection |
+
+The pack combines platform baseline (layer 1) with core requirements (layer 3).
+Neither too much (no files from unused cores) nor too few (no missing files for active cores).
+
+## Pack grouping
+
+Platforms that produce identical packs are grouped automatically.
+RetroArch and Lakka share the same files and `base_destination` (`system/`),
+so they produce one combined pack (`RetroArch_Lakka_BIOS_Pack.zip`).
+RetroPie uses `BIOS/` as base path, so it gets a separate pack.
+
+## Storage tiers
+
+| Tier | Meaning |
+|------|---------|
+| `embedded` (default) | file is in the `bios/` directory, included in packs |
+| `external` | file has a `source_url`, downloaded at pack build time |
+| `user_provided` | user must provide the file (instructions included in pack) |
+
+## Verification severity
+
+How missing or mismatched files are reported:
+
+| Mode | required + missing | optional + missing | hash mismatch |
+|------|-------------------|-------------------|--------------|
+| existence | WARNING | INFO | N/A |
+| md5 | CRITICAL | WARNING | UNTESTED |
+
+Files with `hle_fallback: true` are downgraded to INFO when missing
+(the emulator has a software fallback).
+
+## Discrepancy detection
+
+When a file passes platform verification (MD5 match) but fails
+emulator-level validation (wrong CRC32, wrong size), a DISCREPANCY is reported.
+The pack generator searches the repo for a variant that satisfies both.
+If none exists, the platform version is kept.
+
+## Security
+
+- `safe_extract_zip()` prevents zip-slip path traversal attacks
+- `deterministic_zip` rebuilds MAME ZIPs so same ROMs always produce the same hash
+- `crypto_verify.py` and `sect233r1.py` verify 3DS RSA-2048 signatures and AES-128-CBC integrity
+- ZIP inner ROM verification via `checkInsideZip()` replicates Batocera's behavior
+- `md5_composite()` replicates Recalbox's composite ZIP hash
+
+## Edge cases
+
+| Case | Handling |
+|------|---------|
+| Batocera truncated MD5 (29 chars) | prefix match in resolution |
+| `zippedFile` entries | MD5 is of the ROM inside the ZIP, not the ZIP itself |
+| Regional variants (same filename) | `by_path_suffix` index disambiguates |
+| MAME BIOS ZIPs | `contents` field documents inner structure |
+| RPG Maker/ScummVM | excluded from dedup (NODEDUP) to preserve directory structure |
+| `strip_components` in data dirs | flattens cache prefix to match expected path |
+| case-insensitive dedup | prevents `font.rom` + `FONT.ROM` conflicts on Windows/macOS |
+
+## Platform inheritance
+
+Platform configs support `inherits:` to share definitions.
+Lakka inherits from RetroArch, RetroPie inherits from RetroArch with `base_destination: BIOS`.
+`overrides:` allows child platforms to modify specific systems from the parent.
+
+Core resolution (`resolve_platform_cores`) uses three strategies:
+
+- `cores: all_libretro` - include all profiles with `libretro` in their type
+- `cores: [list]` - include only named profiles
+- `cores:` absent - fallback to system ID intersection between platform and profiles
+
+## MAME clone map
+
+`_mame_clones.json` at repo root maps MAME clone ROM names to their canonical parent.
+When a clone ZIP was deduplicated, `resolve_local_file` uses this map to find the canonical file.
+
+## Tests
+
+`tests/test_e2e.py` contains 75 end-to-end tests with synthetic fixtures.
+Covers: file resolution, verification, severity, cross-reference, aliases,
+inheritance, shared groups, data dirs, storage tiers, HLE, launchers,
+platform grouping, core resolution (3 strategies + alias exclusion).
+
+```bash
+python -m unittest tests.test_e2e -v
+```
+
+## CI workflows
+
+| Workflow | File | Trigger | Role |
+|----------|------|---------|------|
+| Build & Release | `build.yml` | `workflow_dispatch` (manual) | restore large files, build packs, deploy site, create GitHub release |
+| PR Validation | `validate.yml` | pull request on `bios/`/`platforms/` | validate BIOS hashes, schema check, run tests, auto-label PR |
+| Weekly Sync | `watch.yml` | cron (Monday 6 AM UTC) + manual | scrape upstream sources, detect changes, create update PR |
+
+Build workflow has a 7-day rate limit between releases and keeps the 3 most recent.
+
+## License
+
+See `LICENSE` at repo root. Files are provided for personal backup and archival.
+

wiki/index.md

@@ -0,0 +1,19 @@
+# Wiki - RetroBIOS
+
+Technical documentation for the RetroBIOS toolchain.
+
+## Pages
+
+- **[Architecture](architecture.md)** - directory structure, data flow, platform inheritance, pack grouping, security, edge cases, CI workflows
+- **[Tools](tools.md)** - CLI reference for every script, pipeline usage, scrapers
+- **[Profiling guide](profiling.md)** - how to create an emulator profile from source code, step by step, with YAML field reference
+- **[Data model](data-model.md)** - database.json structure, indexes, file resolution order, YAML formats
+
+## For users
+
+If you just want to download BIOS packs, see the [home page](../index.md).
+
+## For contributors
+
+Start with the [profiling guide](profiling.md) to understand how emulator profiles are built,
+then see [contributing](../contributing.md) for submission guidelines.

wiki/profiling.md

@@ -0,0 +1,132 @@
+# Profiling guide - RetroBIOS
+
+How to create an emulator profile from source code.
+
+## Approach
+
+A profile documents what an emulator loads at runtime.
+The source code is the reference because it reflects actual behavior.
+Documentation, .info files, and wikis are useful starting points
+but are verified against the code.
+
+## Steps
+
+### 1. Find the source code
+
+Check these locations in order:
+
+1. Upstream original (the emulator's own repository)
+2. Libretro fork (may have adapted paths or added files)
+3. If not on GitHub: GitLab, Codeberg, SourceForge, archive.org
+
+Always clone both upstream and libretro port to compare.
+
+### 2. Trace file loading
+
+Read the code flow. Don't grep keywords by assumption.
+Each emulator has its own way of loading files.
+
+Look for:
+
+- `fopen`, `open`, `read_file`, `load_rom`, `load_bios` calls
+- `retro_system_directory` / `system_dir` in libretro cores
+- File existence checks (`path_is_valid`, `file_exists`)
+- Hash validation (MD5, CRC32, SHA1 comparisons in code)
+- Size validation (`fseek`/`ftell`, `stat`, fixed buffer sizes)
+
+### 3. Determine required vs optional
+
+This is decided by code behavior, not by judgment:
+
+- **required**: the core does not start or function without the file
+- **optional**: the core works with degraded functionality without it
+- **hle_fallback: true**: the core has a high-level emulation path when the file is missing
+
+### 4. Document divergences
+
+When the libretro port differs from the upstream:
+
+- `mode: libretro` - file only used by the libretro core
+- `mode: standalone` - file only used in standalone mode
+- `mode: both` - used by both (default, can be omitted)
+
+Path differences (current dir vs system_dir) are normal adaptation,
+not a divergence. Name changes (e.g. `naomi2_` to `n2_`) may be intentional
+to avoid conflicts in the shared system directory.
+
+### 5. Write the YAML profile
+
+```yaml
+emulator: Dolphin
+type: standalone + libretro
+core_classification: community_fork
+source: https://github.com/libretro/dolphin
+upstream: https://github.com/dolphin-emu/dolphin
+profiled_date: 2026-03-25
+core_version: 5.0-21264
+systems:
+  - nintendo-gamecube
+  - nintendo-wii
+
+files:
+  - name: GC/USA/IPL.bin
+    system: nintendo-gamecube
+    required: false
+    hle_fallback: true
+    size: 2097152
+    validation: [size, adler32]
+    known_hash_adler32: 0x4f1f6f5c
+    region: north-america
+    source_ref: Source/Core/Core/Boot/Boot_BS2Emu.cpp:42
+```
+
+### 6. Validate
+
+```bash
+python scripts/cross_reference.py --emulator dolphin --json
+python scripts/verify.py --emulator dolphin
+```
+
+## YAML field reference
+
+### Profile fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `emulator` | yes | display name |
+| `type` | yes | `libretro`, `standalone`, `standalone + libretro`, `alias`, `launcher` |
+| `core_classification` | no | `pure_libretro`, `official_port`, `community_fork`, `frozen_snapshot`, `enhanced_fork`, `game_engine`, `embedded_hle`, `alias`, `launcher` |
+| `source` | yes | libretro core repository URL |
+| `upstream` | no | original emulator repository URL |
+| `profiled_date` | yes | date of source analysis |
+| `core_version` | yes | version analyzed |
+| `systems` | yes | list of system IDs this core handles |
+| `cores` | no | list of core names (default: profile filename) |
+| `files` | yes | list of file entries |
+| `notes` | no | free-form technical notes |
+| `exclusion_note` | no | why the profile has no files |
+| `data_directories` | no | references to data dirs in `_data_dirs.yml` |
+
+### File entry fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | filename as the core expects it |
+| `required` | true if the core needs this file to function |
+| `system` | system ID this file belongs to |
+| `size` | expected size in bytes |
+| `md5`, `sha1`, `crc32`, `sha256` | expected hashes from source code |
+| `validation` | list of checks the code performs: `size`, `crc32`, `md5`, `sha1` |
+| `aliases` | alternate filenames for the same file |
+| `mode` | `libretro`, `standalone`, or `both` |
+| `hle_fallback` | true if a high-level emulation path exists |
+| `category` | `bios` (default), `game_data`, `bios_zip` |
+| `region` | geographic region (e.g. `north-america`, `japan`) |
+| `source_ref` | source file and line number |
+| `path` | path relative to system directory |
+| `description` | what this file is |
+| `note` | additional context |
+| `archive` | parent ZIP if this file is inside an archive |
+| `contents` | structure of files inside a BIOS ZIP |
+| `storage` | `embedded` (default), `external`, `user_provided` |
+

wiki/tools.md

@@ -0,0 +1,128 @@
+# Tools - RetroBIOS
+
+All tools are Python scripts in `scripts/`. Single dependency: `pyyaml`.
+
+## Pipeline
+
+Run everything in sequence:
+
+```bash
+python scripts/pipeline.py --offline          # DB + verify + packs + readme + site
+python scripts/pipeline.py --offline --skip-packs  # DB + verify only
+python scripts/pipeline.py --skip-docs        # skip readme + site generation
+```
+
+## Individual tools
+
+### generate_db.py
+
+Scan `bios/` and build `database.json` with multi-indexed lookups.
+Large files in `.gitignore` are preserved from the existing database
+and downloaded from GitHub release assets if not cached locally.
+
+```bash
+python scripts/generate_db.py --force --bios-dir bios --output database.json
+```
+
+### verify.py
+
+Check BIOS coverage for each platform using its native verification mode.
+
+```bash
+python scripts/verify.py --all                # all platforms
+python scripts/verify.py --platform batocera  # single platform
+python scripts/verify.py --emulator dolphin   # single emulator
+python scripts/verify.py --system atari-lynx  # single system
+```
+
+Verification modes per platform:
+
+| Platform | Mode | Logic |
+|----------|------|-------|
+| RetroArch, Lakka, RetroPie | existence | file present = OK |
+| Batocera, RetroBat | md5 | MD5 hash match |
+| Recalbox | md5 | MD5 multi-hash, 3 severity levels |
+| EmuDeck | md5 | MD5 whitelist per system |
+
+### generate_pack.py
+
+Build platform-specific BIOS ZIP packs.
+
+```bash
+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
+```
+
+Packs include platform baseline files plus files required by the platform's cores.
+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.
+
+### cross_reference.py
+
+Compare emulator profiles against platform configs.
+Reports files that cores need but platforms don't declare.
+
+```bash
+python scripts/cross_reference.py                    # all
+python scripts/cross_reference.py --emulator dolphin # single
+```
+
+### refresh_data_dirs.py
+
+Fetch data directories (Dolphin Sys, PPSSPP assets, blueMSX databases)
+from upstream repositories into `data/`.
+
+```bash
+python scripts/refresh_data_dirs.py
+python scripts/refresh_data_dirs.py --key dolphin-sys --force
+```
+
+### Other tools
+
+| Script | Purpose |
+|--------|---------|
+| `dedup.py` | Deduplicate `bios/`, move duplicates to `.variants/`. RPG Maker and ScummVM excluded (NODEDUP) |
+| `validate_pr.py` | Validate BIOS files in pull requests |
+| `auto_fetch.py` | Fetch missing BIOS files from known sources |
+| `list_platforms.py` | List active platforms (used by CI) |
+| `download.py` | Download packs from GitHub releases |
+| `common.py` | Shared library: hash computation, file resolution, platform config loading, emulator profiles |
+| `generate_readme.py` | Generate README.md and CONTRIBUTING.md from database |
+| `generate_site.py` | Generate all MkDocs site pages (this documentation) |
+| `deterministic_zip.py` | Rebuild MAME BIOS ZIPs deterministically (same ROMs = same hash) |
+| `crypto_verify.py` | 3DS RSA signature and AES crypto verification |
+| `sect233r1.py` | Pure Python ECDSA verification on sect233r1 curve (3DS OTP cert) |
+| `batch_profile.py` | Batch profiling automation for libretro cores |
+| `migrate.py` | Migrate flat bios structure to Manufacturer/Console/ hierarchy |
+
+## Large files
+
+Files over 50 MB are stored as assets on the `large-files` GitHub release.
+They are listed in `.gitignore` so they don't bloat the git repository.
+`generate_db.py` downloads them from the release when rebuilding the database,
+using `fetch_large_file()` from `common.py`. The same function is used by
+`generate_pack.py` when a file has a hash mismatch with the local variant.
+
+## Scrapers
+
+Located in `scripts/scraper/`. Each inherits `BaseScraper` and implements `fetch_requirements()`.
+
+| Scraper | Source | Format |
+|---------|--------|--------|
+| `libretro_scraper` | System.dat + core-info .info files | clrmamepro DAT |
+| `batocera_scraper` | batocera-systems script | Python dict |
+| `recalbox_scraper` | es_bios.xml | XML |
+| `retrobat_scraper` | batocera-systems.json | JSON |
+| `emudeck_scraper` | checkBIOS.sh | Bash + CSV |
+| `retrodeck_scraper` | component manifests | JSON per component |
+| `coreinfo_scraper` | .info files from libretro-core-info | INI-like |
+
+Internal modules: `base_scraper.py` (abstract base with `_fetch_raw()` caching
+and shared CLI), `dat_parser.py` (clrmamepro DAT format parser).
+
+Adding a scraper: inherit `BaseScraper`, implement `fetch_requirements()`,
+call `scraper_cli(YourScraper)` in `__main__`.
+