docs: document per-system save folders

wiki/adding-a-platform.md

@@ -226,6 +226,16 @@ platform hands it no folder. `platform_layouts` builds one view per directory,
 so the builder, the manifest, verify and slots read the same placement, and the
 resolver still looks the collection up by the core's own path.
 
+A launcher that hands each libretro core a save directory per system needs to
+know which systems run each core. The scraper writes `libretro_systems`, each
+libretro core name with the systems the platform's own list offers it for, under
+the name the launcher puts in the path: Batocera and KNULLI from `es_systems.yml`
+(`libretro:` entries), RetroBat from `es_systems.cfg`, Recalbox from each
+`system.ini`, RetroDECK from the ROM folders of the ES-DE commands that load the
+core. With `save_directory.by_system`, a file a core reads below its save
+directory goes once below each of those folders, and a core no system runs is
+listed as omitted (`no_save_system`).
+
 ### Guide text
 
 `platforms/_guides.yml` holds each platform's guide: what it is, where its
@@ -287,9 +297,14 @@ that text belongs in a guide field.
     save_directory:                  # the save directory the frontend hands libretro cores,
       folder: saves                  # where it is one place: the pack folder holding the
       by_core: true                  # files cores read there (load_from: save_dir), its
-                                     # default place beside the BIOS folder, and whether
+                                     # default place beside the BIOS folder (a relative
+                                     # path, saves/retroarch/saves on EmuDeck), and whether
                                      # the frontend appends the core's library_name.
-                                     # null when it is one folder per game or system
+      by_system: true                # the launcher hands <folder>/<system> at each launch
+                                     # (Batocera, RetroBat): one copy per system in the
+                                     # platform file's libretro_systems
+      by_core_for: [dolphin]         # cores the launcher alone sorts by core (RetroBat)
+                                     # null when saves sit beside each game
     zip_digest: composite            # the frontend hashes a .zip by its members only
     firmware_folder_flat: true       # the frontend lists each system folder without
                                      # descending into it

wiki/installer.md

@@ -102,8 +102,17 @@ the save directory beside it (`saves`, `/storage/savefiles` on Lakka).
 applies, or when `savefiles_in_content_dir` or
 `sort_savefiles_by_content_enable` keeps saves beside each game, those files
 are left out and the run says why, like the other entries the list cannot
-install. Batocera, RetroBat and RetroPie hand each system or game a save folder
-of its own: their lists record these files as omitted.
+install.
+
+Batocera, KNULLI, Recalbox, RetroBat and RetroDECK write the save directory at
+each launch, one folder per system (`by_system` in the file list). Their lists
+already name each system's folder (`gamecube/User/GBA/gba_bios.bin`), and the
+run writes below the `saves` folder beside the BIOS folder (`/userdata/saves`,
+`/recalbox/share/saves`, `~/retrodeck/saves`), never reading a
+`retroarch.cfg` that only holds the last launch. EmuDeck's RetroArch config
+names `~/Emulation/saves/retroarch/saves`. RetroPie, ROCKNIX, AmberELEC and
+EmuELEC keep saves beside each game, and RomM keeps them in the browser: their
+lists record these files as omitted.
 
 A RetroArch run into an empty folder printed this on 2026-10-21:
 

wiki/profiling.md

@@ -562,10 +562,20 @@ The save directory itself is the platform's: `save_directory` in
 `platforms/_registry.yml` names it where the frontend keeps it in one place.
 RetroArch keeps `saves/` beside `system/` and sorts by core, so Azahar's keys
 land in `saves/Azahar/Azahar/sysdata/keys.txt`. Lakka keeps
-`/storage/savefiles`. Batocera, RetroBat and RetroPie hand each game or system
-a folder of its own: those entries are listed as omitted
-(`no_save_directory`), never placed in the BIOS tree where the core does not
-look.
+`/storage/savefiles`, and EmuDeck one unsorted `~/Emulation/saves/retroarch/saves`
+for every core.
+
+Batocera, KNULLI, Recalbox, RetroBat and RetroDECK hand a core the save folder
+of the system it was launched for (`by_system`): Batocera's configgen writes
+`/userdata/saves/<system>` at each launch. The file then goes once below each
+system that runs the core there, so libretro Dolphin's `User/GBA/gba_bios.bin`
+lands in both `saves/gamecube/User/GBA/` and `saves/wii/User/GBA/` on Batocera.
+RetroBat sorts Dolphin's saves by core too, which adds `dolphin-emu/`.
+
+RetroPie, ROCKNIX, AmberELEC and EmuELEC keep saves beside each game, and RomM
+runs cores in the browser: no single place exists, so those entries are listed
+as omitted (`no_save_directory`), never placed in the BIOS tree where the core
+does not look.
 
 ### File entry fields