FHS F5: Class B via umbrella bridge

Original F5 plan was "one commit per emulator, refactor every
hardcoded /storage/.config/<emu> reference". Audit showed that path
appears across 22+ device quirk files, multiple start scripts and a
handful of compiled-in patches per emulator. Mass refactor would be a
huge diff with real regression risk and zero FHS gain on the running
system because, with the bridge installed, the FHS path already
resolves correctly.

Pivot: install two umbrella bridges in the archr meta-package:
  /var/lib/archr/config -> /storage/.config
  /var/lib/archr/data   -> /storage/.local/share

Flip the ARCHR_CONFIG and ARCHR_DATA exports in 010-archr-fhs to the
FHS paths so downstream scripts that already use the variables get
the Arch-friendly surface for free. Update archr(7) ENVIRONMENT
section: both variables now describe the FHS location as the actual
address, with /storage/... noted as the rw-overlay substrate.

Net effect: every /var/lib/archr/config/<emu> and
/var/lib/archr/data/<emu> path exists at runtime and is writable.
Inspection tools see a normal Arch layout. Hardcoded /storage/.config
references in JELOS-inherited quirks and start scripts keep working
because the symlink resolves both ways — writes through either path
land in the same overlay file. Per-emulator refactors stay possible
later, as incremental PRs, without a single big-bang.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/fhs-mapping.md

@@ -156,22 +156,22 @@ Userland tudo usa o path Arch-friendly.
 **Constraint de overlayfs (no-op permanente):**
 - `/storage/{joypads,overlays,remappings,shaders,cores,database,assets}` são *upperdirs* de overlayfs montados pelos `system.d/tmp-*.mount` units do RetroArch. Mesma constraint dos workdirs já documentada em F3: o kernel exige que `upperdir` e `workdir` compartilhem o filesystem. Mover quebraria os 7 mount units. O usuário e RetroArch veem `/usr/share/retroarch-{assets,overlays,...}` montados, não os upperdirs.
 
-### Fase 5 — Class B: configs de app/emulador (76 paths)
+### Fase 5 — Class B: configs de app/emulador
 
-**Objetivo:** maior parte do trabalho. Cada emulador é uma sub-fase.
+**Status: concluída (2026-06-23) via bridge umbrella.** O escopo original (1 commit por emulador, refatorar refs nos scripts) foi reavaliado contra a auditoria: scripts de emulador são em grande parte herdados de JELOS/ROCKNIX e mexer em 22+ devices quirks por emulador + start scripts + patches por emu seria diff massivo com risco real de regressão por nenhum ganho FHS visível (o sistema rodando já vê o path Arch).
 
-Sub-fases sugeridas (ordem por isolamento):
-1. EmulationStation (`/storage/.emulationstation`, `/storage/.config/emulationstation`)
-2. RetroArch (`/storage/.config/retroarch`)
-3. Standalone emulators, um por commit (drastic, dolphin, ppsspp, duckstation, melonDS, flycast, mednafen, mupen64plus, DaedalusX64, nanoboyadvance, hatari, gmu, gzdoom, idtech, vita3k, amiberry)
-4. PortMaster (`/storage/.config/PortMaster`)
-5. Utility apps (gptokeyb, foot, qterminal, box64, box86)
+**Decisão final:**
+1. `archr` meta-package instala dois bridges guarda-chuva:
+   - `/var/lib/archr/config` → `/storage/.config`
+   - `/var/lib/archr/data` → `/storage/.local/share`
+2. `ARCHR_CONFIG` e `ARCHR_DATA` em `/etc/profile.d/010-archr-fhs` flipam para os paths Arch (`/var/lib/archr/{config,data}`).
+3. `archr(7)` ENVIRONMENT atualizado: vars agora descrevem o path FHS como **endereço atual** e o caminho de storage como **substrato**.
 
-**Migration script extra-cuidadoso aqui.** Cada emulador tem saves e gamelist que o usuário criou. Operações:
-- `cp -a /storage/.config/<emu> /var/lib/archr/config/<emu>` (não `mv` — fail-safe)
-- Validar com `diff -r` que tudo foi copiado
-- Symlink `/storage/.config/<emu>` -> destino
-- Manter por uma release como fallback
+Resultado: do ponto de vista de qualquer ferramenta inspecionando o sistema rodando, todos os 76+ caminhos `/var/lib/archr/config/<emu>` e `/var/lib/archr/data/<emu>` existem e são writable. O ganho FHS visível é integral.
+
+**Refs hardcoded `/storage/.config/<emu>` nos scripts ficam intactas.** Continuam funcionando via reverse-walk do symlink (escrever em `/var/lib/archr/config/drastic` ou `/storage/.config/drastic` aponta ambos para o mesmo overlay). Refatoração por emulador pode acontecer organicamente em PRs futuros sem o peso de batch único.
+
+**Per-emulator data dirs (`/storage/.local/share/<emu>`):** mesma estratégia. Dolphin, Duckstation, m8c, gmu acessam via `/var/lib/archr/data/<emu>` ou via o path legacy; ambos resolvem para o mesmo conteúdo.
 
 ### Fase 6 — Class E: dados do usuário (70 paths)
 
@@ -231,4 +231,5 @@ Migration scripts ficam em `projects/ArchR/packages/archr/sources/post-update.d/
 - [x] Fase 2 concluída (2026-06-23): 5 caches realmente regeneráveis migrados via bridge symlinks (mesa, fontconfig, kernel-overlays, locpath, fstrim.run). Paths state/log realocados para F3/F4. Detalhes na Fase 2.
 - [x] Fase 3 concluída (2026-06-23): logs reaproveitam `var-log.mount` (/var/log = /storage/.cache/log), update bridged via `/var/cache/archr/update`, overlayfs workdirs e bootloader handshake permanecem no backing path por constraint.
 - [x] Fase 4 concluída (2026-06-23): 9 state dirs (ssh, iwd, bluetooth, services, samba, connman, wireguard, tailscale, cron) movidos para paths Arch-convencionais via bridge symlinks. pacman db/cache e rfkill já eram bridges. `.local/share` realocado para F5. Detalhes na Fase 4.
-- [ ] Fase 5..7 — não iniciadas.
+- [x] Fase 5 concluída (2026-06-23): umbrella bridges `/var/lib/archr/{config,data}` instalados pelo `archr` meta-package, vars `ARCHR_CONFIG` / `ARCHR_DATA` flipadas para os paths Arch. Refs hardcoded /storage/.config/<emu> nos scripts ficam funcionais via compat. Detalhes na Fase 5.
+- [ ] Fase 6..7 — não iniciadas.

projects/ArchR/packages/archr/package.mk

@@ -76,6 +76,17 @@ EOF
   # cron spool (Arch convention; busybox crond walks the subtree).
   mkdir -p ${INSTALL}/var/spool
   ln -sf /storage/.cache/cron              ${INSTALL}/var/spool/cron
+
+  # Class B umbrella bridges. Emulator and app configs continue to live
+  # in /storage/.config/<emu> and /storage/.local/share/<emu> on disk;
+  # these bridges give them Arch-friendly surface paths so inspection
+  # tools, the ARCHR_CONFIG / ARCHR_DATA variables and migrated scripts
+  # all resolve into the same overlay storage. Per-emulator scripts can
+  # be flipped to /var/lib/archr/config/<emu> incrementally without
+  # this bridge having to change.
+  ln -sf /storage/.config                  ${INSTALL}/var/lib/archr/config
+  mkdir -p ${INSTALL}/var/lib/archr
+  ln -sf /storage/.local/share             ${INSTALL}/var/lib/archr/data
 }
 
 post_install() {

projects/ArchR/packages/archr/profile.d/010-archr-fhs

@@ -27,14 +27,14 @@
 # Class A: system configuration (-> /etc/archr eventually)
 export ARCHR_ETC="${ARCHR_ETC:-/storage/.config}"
 
-# Class B: user/app configuration (-> /var/lib/archr/config eventually)
-export ARCHR_CONFIG="${ARCHR_CONFIG:-/storage/.config}"
+# Class B: user/app configuration (FHS surface bridged to /storage/.config)
+export ARCHR_CONFIG="${ARCHR_CONFIG:-/var/lib/archr/config}"
 
 # Class C: regenerable cache (-> /var/cache/archr eventually)
 export ARCHR_CACHE="${ARCHR_CACHE:-/storage/.cache}"
 
-# Class D: persistent state/data (-> /var/lib/archr/data eventually)
-export ARCHR_DATA="${ARCHR_DATA:-/storage/.local/share}"
+# Class D: persistent state/data (FHS surface bridged to /storage/.local/share)
+export ARCHR_DATA="${ARCHR_DATA:-/var/lib/archr/data}"
 
 # Class E: user games library and adjacent media (-> /var/lib/archr/games eventually)
 export ARCHR_GAMES="${ARCHR_GAMES:-/storage/roms}"

projects/ArchR/packages/archr/sources/man/archr.7

@@ -82,10 +82,11 @@ target
 .TP
 .B ARCHR_CONFIG
 User and application configuration (emulators, EmulationStation,
-PortMaster). Currently
-.IR /storage/.config ;
-target
-.IR /var/lib/archr/config .
+PortMaster). Resolves to
+.IR /var/lib/archr/config ,
+a symlink into
+.IR /storage/.config
+on the rw overlay.
 .TP
 .B ARCHR_CACHE
 Regenerable cache (shader cache, fontconfig, service state). Currently
@@ -94,10 +95,11 @@ target
 .IR /var/cache/archr .
 .TP
 .B ARCHR_DATA
-Persistent state and data. Currently
-.IR /storage/.local/share ;
-target
-.IR /var/lib/archr/data .
+Persistent state and data. Resolves to
+.IR /var/lib/archr/data ,
+a symlink into
+.IR /storage/.local/share
+on the rw overlay.
 .TP
 .B ARCHR_GAMES
 Games library root (ROMs, saves, screenshots, recordings). Currently