docs: track improvements.md and release-policy.md

.gitignore had docs/* blocking everything; the rest of the directory
remains user-local notes, so whitelist only the two files that belong
to the project: improvements.md (Arch-ification roadmap, with the
architectural decision that LibreELEC overlay is by design) and
release-policy.md (semver-RC until v2.0, YYYY.MM.PATCH after, three
release channels mapped to updates.branch).

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

.gitignore

@@ -173,4 +173,6 @@ packages/sysutils/open-vm-tools/
 
 #other
 docs/*
+!docs/improvements.md
+!docs/release-policy.md
 bench-results/config/mipi-generator/__pycache__/

docs/improvements.md

@@ -0,0 +1,144 @@
+# Melhorias e modernização
+
+Documento vivo. Lista componentes do ArchR que se beneficiam de modernização incremental: qualidade de código, integração com hardware atual (RK3326 / Mali-G31), manutenibilidade. Reescritas do zero ficam fora deste documento; quando o veredito for "vale reescrever", abrir doc próprio em `docs/rewrite-<componente>.md`.
+
+**Convenção de status:**
+- `[ ]` não iniciado
+- `[~]` em progresso
+- `[x]` concluído
+- `[?]` investigação aberta, decisão pendente
+
+**Convenção de esforço:** S (horas), M (dias), L (semanas), XL (mês ou mais).
+
+---
+
+## 1. EmulationStation (emulationstation-next)
+
+**Repo:** `/media/disco-local/ArchR/emulationstation-next`
+**Linguagem:** C++17, CMake 3.10+, SDL2.
+**Hardware alvo primário:** R36S e clones (RK3326, Mali-G31, 1 GB DDR3L).
+
+**Veredito de reescrita:** descartado em 2026-06-23 (sessão dga.teles + Claude). 15+ anos de trabalho cumulativo, ecossistema de temas, scraper, gamelist XML, integração PortMaster e RetroAchievements: o custo de paridade básica supera de longe o ganho. Modernização incremental é o caminho.
+
+### 1.1. Qualidade de código
+
+- [ ] **Auditoria de C++17 vs C++20** S. Já estamos em C++17 via CMake. Avaliar bump para C++20 (concepts, ranges, designated initializers, span) ou ficar no 17. Decisão depende do gcc do toolchain do ArchR.
+- [ ] **Substituir loops manuais por algoritmos da STL** M. Varredura em `es-core/src/utils/` e `es-app/src/views/`, onde `for` com índice ainda predomina.
+- [ ] **Smart pointers consistentes** M. Há mistura de `new`/`delete` cru com `unique_ptr`/`shared_ptr`. Padronizar e remover `delete` manual onde possível.
+- [ ] **`constexpr` e `noexcept` em utilitários puros** S. Funções de path, parsing, math em `es-core/utils/`.
+- [ ] **Análise estática regular** S. Rodar `clang-tidy` com perfil mínimo (`modernize-*`, `performance-*`, `readability-*`) e arquivar relatório em `docs/es-clang-tidy-<data>.txt`.
+- [ ] **Remoção de código morto** S. O commit `563e1057f` (PackGamelists/BuildMultiDiskContentCache) sugere que ainda há referências obsoletas; varredura completa.
+
+### 1.2. Compatibilidade RK3326 / Mali-G31
+
+- [ ] **Paths de renderização Panfrost vs libmali** M. Quando o seletor de GPU driver voltar (atualmente oculto, ver `project_panfrost_selector_disabled`), o ES precisa dar caminhos de fallback diferentes para texture upload e shader cache. Hoje assume libmali.
+- [ ] **BO labelling** S. Os patches `0007..0010` do kernel 6.12-LTS habilitam labels em BOs do panfrost. ES pode anotar suas texturas e ajudar `panfrost_gem_show` no debug. Baixa prioridade, mas é literalmente uma chamada IOCTL.
+- [ ] **CMA 96 MB awareness** M. Pré-alocação de texture pool consciente do limite (R36S tem 96 MB de CMA reservado). Logar quando se aproxima do limite e degradar graciosamente em vez de OOM.
+- [ ] **Shader cache persistente** M. Mesa 26.1.3 já tem `MESA_SHADER_CACHE_DIR`. Garantir que o ES aponte para `/storage/.cache/mesa` (não `/tmp`, que é tmpfs) e que a pasta sobreviva ao boot.
+- [ ] **CPU governor durante navegação de menu** S. Hoje subimos governor para `performance` antes de lançar emulador. Avaliar manter `schedutil` durante navegação para reduzir consumo passivo e calor.
+
+### 1.3. Performance percebida
+
+- [ ] **Profiling de boot time** M. Medir `ExecMainStart` até primeira tela interativa. Identificar onde os ~5 a 8 segundos de boot do ES vão (XML parse, texture load, scraper init). O commit `a2181ff44` já paralelizou parte; rever o gap restante.
+- [ ] **Async load de capas e screenshots** M. Verificar se o load atual já é não-bloqueante e se não, paralelizar via ThreadPool (já existe no repo, ver commit `268ebb394`).
+- [ ] **Decoding incremental de imagens grandes** S. Sistemas com gamelists pesadas (capas a 2K) pagam decoding síncrono na entrada. Stream + downscale on-the-fly.
+- [ ] **Transições de view** S. Frame pacing nas transições com Mali-G31 às vezes engasga; checar se há frame drop em transições de carousel.
+
+### 1.4. Funcionalidades
+
+- [ ] **GPU governor menu** S. Já implementado em `4c3cb8af3` e `b9cb6b821`. Validar UX e documentar opções.
+- [ ] **Integração com overlay generator** M. Botão dentro do ES que abre `arch-r.io/overlay-generator/` ou rode local. Reduz fricção para clones não catalogados.
+- [ ] **Integração com Flasher para atualizar painel** M. Quando o usuário troca o cartão de painel, oferecer dentro do ES "atualizar overlay" sem reflash da SD.
+- [ ] **Modo party / split-screen UI** L. Discutido informalmente; especificar antes.
+- [ ] **Indicador de modo de gravação MIPI/SPKO** S. Para boards Soysauce, mostrar qual variant de áudio está ativo (debug útil).
+
+### 1.5. Build e dependências
+
+- [ ] **CMake 3.10 → 3.20+** S. Bump do mínimo. Toolchain do ArchR já está bem além.
+- [ ] **Substituir FetchContent por submodules ou pkg-config** S. Predição: builds reproduzíveis e cache friendly.
+- [ ] **SDL2 → SDL3** XL. SDL3 estável em 2025/2026. Migração não é blocker, mas vale levantar custo. Investigação aberta.
+- [ ] **CI no GitHub Actions** M. Build matrix (debug + release, gcc + clang) por PR; hoje só roda local.
+- [ ] **clang-format obrigatório** S. Adicionar `.clang-format` no repo e rodar via pre-commit hook.
+
+### 1.6. i18n e theming
+
+- [ ] **Auditoria de strings hardcoded** S. Garantir que tudo passa por `_("...")` ou equivalente.
+- [ ] **Suporte a novo formato de tema** L. Avaliar adoção do tema engine do batocera-emulationstation ou ES-DE para herdar ecossistema maior. Investigação aberta.
+
+---
+
+## 2. Arch-ificação da distro
+
+**Objetivo estratégico:** mover ArchR progressivamente para a filosofia Arch Linux (rolling, pacman-centric, FHS rigoroso, KISS) e deixar de ser uma variação ROCKNIX/LibreELEC. Nenhuma mudança aqui pode quebrar a experiência atual; tudo é incremental, com fallback para o caminho LibreELEC enquanto a paridade não estiver garantida.
+
+**Decisão arquitetural registrada (2026-06-23):** o modelo de boot herdado de LibreELEC (rootfs squashfs read-only + overlay `/storage` read-write + image-based atomic updates) **é decisão por design, não dívida técnica**. Não substituir. Motivos:
+1. Sobrevive a power-loss arbitrário (criança puxando da tomada no meio do jogo), que é cenário diário em handheld.
+2. Update atômico via swap de imagem é matematicamente impossível de deixar o sistema half-broken; pacman incremental, por design, pode.
+3. `/storage` como overlay garante que upgrade de sistema nunca come saves nem configurações de emulador.
+4. **Precedente validado:** SteamOS adotou exatamente esse modelo (rootfs read-only via OSTree, overlay `/home`, updates atômicos) e ainda assim é Arch Linux oficial com pacman e PKGBUILD plenamente funcionais. A arquitetura não define identidade de SO; userland, ferramentas e filosofia definem.
+
+Identidade Arch vem dos 7 itens desta seção (pacman, PKGBUILD, FHS, rolling, KISS, ArchWiki, branding), não da forma como o boot acontece.
+
+**Estado atual auditado (2026-06-23):**
+- `pacman 7.0.0` já compilado em `projects/ArchR/packages/sysutils/pacman/` mas não está conectado ao fluxo de update do usuário final.
+- `archr-keyring` já criado, populado com chaves Arch Linux ARM.
+- `archr-update` ainda faz HTTP POST para `update.arch-r.io` e baixa imagem inteira (estilo LibreELEC overlay).
+- 189 referências hardcoded a paths `/storage/...` em scripts (modelo overlay LibreELEC). FHS-puro seria `/etc`, `/var/lib`, `/home`.
+- 809 arquivos com refs a `libreelec` (maioria headers de copyright; legítimo manter, ver 2.7).
+- 8 arquivos com refs a `rocknix` em projects/ArchR: maioria é URL upstream ou crédito (legítimo); só 1 ou 2 são cosméticos.
+
+### 2.1. Wirar pacman como mecanismo de update real
+
+- [ ] **Subir mirror `repo.arch-r.io`** L. Hospedar `archr-core` (sistema base) e `archr-extra` (emuladores, temas, scrapers) como repos pacman. Sync via CI quando build de release sai.
+- [ ] **Construir packages `.pkg.tar.zst` no pipeline de release** M. Hoje cuspimos `.img.gz`; passar a também produzir um pacote pacman por componente quando o build do package.mk concluir. Permite atualização granular.
+- [ ] **Substituir `archr-update` por wrapper de `pacman -Syu`** M. Apenas para upgrades incrementais. Reservar image-based para upgrades grandes (kernel, mudança de major version) com migração assistida.
+- [ ] **Suporte a `pacman -S <emulador>`** M. Quando 2.1.1 e 2.1.2 estiverem ativos, o usuário pode instalar emuladores opcionais sem reflash. Reduz tamanho da imagem base.
+- [ ] **Rollback via pacman cache** S. `/storage/.pacman/cache` já está reservado no package.mk; só falta UI no settings menu para "voltar para a release anterior".
+
+### 2.2. Aproximar do FHS
+
+- [ ] **Auditoria das 189 refs a `/storage/`** M. Categorizar: config de usuário, state runtime, save games, cache. Mapear cada categoria para o lugar FHS correto (`/home/<user>/.config`, `/var/lib`, `/var/cache`).
+- [ ] **Symlinks de compatibilidade** S. Para cada migração, manter symlink `/storage/.config/<x>` → caminho FHS por uma release, com warning no log, e remover depois.
+- [ ] **Documentar o "porquê /storage"** S. Antes de mover, escrever página explicando que era herança LibreELEC overlay e o caminho atual. Vai para `docs/arch-migration.md`.
+
+### 2.3. Aceitar PKGBUILD da comunidade
+
+- [ ] **Diretório `archr-aur/` num repo separado** L. Espelho do AUR do Arch, mas com PKGBUILDs validados em RK3326. Build local via `makepkg` + chroot.
+- [ ] **`makepkg.conf` próprio com flags do RK3326** S. Cortex-A35 não tem NEON 2.0 nem SVE; o flag set padrão do Arch ARM precisa de ajuste. Já temos `makepkg.conf` no package.mk do pacman; revisar conteúdo.
+- [ ] **CI que builda PRs de PKGBUILD** M. GitHub Actions roda `makepkg --check --noconfirm` em PR; só merge se passa.
+
+### 2.4. Rolling release oficial
+
+- [x] **Decidir e documentar política de release** S. Definido em `docs/release-policy.md`: semver-RC mantido até v2.0 final, snapshots mensais `YYYY.MM.PATCH` a partir de v2.0. Canais `stable`/`next`/`dev` mapeiam direto para a variável `updates.branch` que `archr-update` já entende.
+- [ ] **Servidor `update.arch-r.io` interpretando `BRANCH=stable|next|dev`** M. Cliente já manda; falta o backend retornar build correto por canal.
+- [ ] **Versionamento `YYYY.MM.PATCH` ativado pós-v2.0** S. Tag git `vYYYY.MM.PATCH`. Mexer só depois que a v2.0 final sair.
+- [ ] **GitHub Releases com tags `[Action Required]` / `[Action Recommended]` / `[News]`** S. Convenção documentada em `release-policy.md`. Tooling consumidor (Flasher, archr-update) pode parsear depois.
+
+### 2.5. KISS e remoção de inertia
+
+- [ ] **Auditoria de quirks de hardware mortas** M. `quirks.d/` herdou items de JELOS/ROCKNIX para devices que não suportamos. Marcar com `[ARCHIR-PRUNE-CANDIDATE]` e revisar em batch.
+- [ ] **Splash + UX padrão** S. Splash atual ainda chama `rocknix-splash` antes do rename. Já corrigido no `archr-splash/package.mk` linha 13-14; validar e remover sed quando o upstream `rocknix-splash` virar fork puro.
+- [ ] **Simplificar `runemu.sh`** L. 1500+ linhas com if/else de 30 emuladores. Refatorar em plugins (um arquivo por emulador). Item caro mas paga em manutenibilidade.
+
+### 2.6. Documentação no estilo ArchWiki
+
+- [ ] **Wiki em `wiki.arch-r.io`** L. Páginas no padrão ArchWiki: Installation guide, Troubleshooting, Beginner's guide. Markdown estático, sem PHP.
+- [ ] **`man archr` na imagem** S. Página `man(7)` curta explicando os comandos próprios (`archr-update`, `archr-flasher`, scripts em `/usr/bin/archr-*`).
+- [ ] **`/etc/archr-release`** S. Arquivo padrão Arch (`/etc/arch-release` na original) para que ferramentas de detecção de OS reconheçam ArchR como família Arch.
+
+### 2.7. Branding e copyright cleanup
+
+- [ ] **Copyright headers** S. Onde o arquivo é 100% nosso, header só "ArchR". Onde herdou de LibreELEC/JELOS/ROCKNIX, manter o credit upstream + "Modified for ArchR (2026-present)". Patch em batch.
+- [ ] **`os-release` `ID=archr` e `ID_LIKE=arch`** S. Para que terceiros detectem como Arch family. Hoje `ID=archr` está OK, falta `ID_LIKE`.
+- [ ] **Refs upstream legítimas** N/A. Manter como estão: URLs de fork (`rocknix/rockchip-wlroots`), copyright headers herdados, comentários explicativos. Não-issue.
+
+---
+
+## Slots reservados (a preencher)
+
+- `## 3. archr-joypad`
+- `## 4. archr-flasher`
+- `## 5. archr-website`
+- `## 6. Kernel + drivers (mali_kbase, mali-bifrost, mipi-generator)`
+
+Cada um ganha sua seção quando começarmos a auditoria.

docs/release-policy.md

@@ -0,0 +1,82 @@
+# Política de release do ArchR
+
+Decisão registrada em 2026-06-23. Substituir este documento por edição direta quando a política mudar; nunca duplicar.
+
+## Resumo
+
+| Fase | Versionamento | Cadência | Quando muda |
+|------|---------------|----------|-------------|
+| Atual: pré-v2.0 | `vMAJOR.MINOR-rcN` (semver-RC) | sob demanda | RC5 vira 2.0 final |
+| Pós-v2.0 | `YYYY.MM.patch` (Arch-style) | snapshot mensal | a partir de 2.0 |
+
+## Por que mudar só depois de 2.0
+
+A v2.0 é um marco de identidade: nova arquitetura (`new-arch` branch), Arch-ificação inicial (`ID_LIKE=arch`, archr-release, archr(7), Mesa 26.1.3, kernel 6.12.94), Flasher v1.3.2 estável, catálogo de 44 painéis. Mudar versionamento *durante* o ciclo RC quebraria a expectativa de quem está acompanhando a sequência RC1..RC5 e tornaria a release final indistinguível de um snapshot de manutenção.
+
+Após 2.0, a v2.0 vira sentinel histórico e o sistema passa a ser efetivamente rolling. Versionar por data (Arch usa o mesmo modelo desde 2015) reflete melhor a realidade: cada snapshot é "o ArchR de junho de 2026", não "ArchR 2.1.7".
+
+## Canais de release
+
+| Canal | Conteúdo | Quem usa |
+|-------|----------|----------|
+| `stable` | snapshots mensais validados no R36S físico | usuário final |
+| `next` | builds da branch `new-arch` (ou equivalente) após CI passar | testers, contribuidores |
+| `dev` | builds noturnos de qualquer feature branch | mantenedores |
+
+A variável `updates.branch` em `system.cfg` já existe (ver `archr-update`) e mapeia diretamente para esses canais. O endpoint `update.arch-r.io` deve passar a entender esses três valores e devolver imagem correspondente.
+
+## Esquema de versionamento pós-v2.0
+
+`YYYY.MM.PATCH` onde:
+
+- `YYYY.MM`: ano e mês do snapshot (zero-pad no mês, `2026.07` e não `2026.7`)
+- `PATCH`: contador de hotfix dentro do mesmo mês, começando em `01`. Snapshot regular é sempre `.01`. Hotfix urgente (CVE, regressão crítica) vira `.02`, `.03` etc.
+
+Exemplos:
+- `2026.07.01`: snapshot regular de julho.
+- `2026.07.02`: hotfix dentro de julho.
+- `2026.08.01`: próximo snapshot regular.
+
+Tag git `vYYYY.MM.PATCH` (com `v` prefixo, consistente com nossa convenção atual `v2.0-rc4`).
+
+## Cadência
+
+Snapshot regular **uma vez por mês**, alvo: primeiro fim de semana. Justificativa:
+
+- Mesa, kernel LTS e libretro cores liberam atualizações em ritmo mensal.
+- Permite acumular testes do canal `next` antes de promover ao `stable`.
+- Não sobrecarrega usuário com reflash semanal.
+- Janela suficiente pra contribuidor testar uma feature antes de estabilizar.
+
+Hotfix sai quando necessário, sem cadência fixa.
+
+## archr-announce
+
+Lista pública de anúncios obrigatórios. Mecanismo de entrega: **GitHub Releases body + RSS público + canal pinned no Discord da comunidade**. Sem mailing list SMTP (custo de manutenção alto, baixo retorno na escala atual).
+
+### Convenção de tag no título da release
+
+Cada release no GitHub tem tag obrigatória no início do body:
+
+- `[Action Required]` exige passos manuais do usuário pós-update (ex.: re-pareamento de Bluetooth, migração de saves).
+- `[Action Recommended]` é recomendação não-bloqueante (ex.: limpar cache antigo de shader).
+- `[News]` é só anúncio, nenhuma ação.
+
+Tooling consumidor (Flasher, archr-update) pode parsear essa tag e mostrar banner correspondente.
+
+## Fluxo aprovado para subir um snapshot ao `stable`
+
+1. Build noturno do `dev` passa em CI por 7 dias consecutivos sem regressão.
+2. Promove para `next`: anúncio na release com tag `[News]`, instala em pelo menos 3 devices físicos diferentes (R36S original + 1 clone + 1 Soysauce).
+3. Permanece em `next` por no mínimo 7 dias com feedback dos testers.
+4. Promove para `stable`: anúncio com tag apropriada (Action Required se houver migração).
+
+## Compatibilidade com `archr-update` existente
+
+`archr-update` atual já aceita `BRANCH` como variável de canal e faz POST para `update.arch-r.io`. Nenhuma mudança no cliente é necessária. O servidor precisa entender:
+
+- `BRANCH=stable` (default): retorna último `YYYY.MM.PATCH` validado.
+- `BRANCH=next`: retorna último build da branch principal.
+- `BRANCH=dev`: retorna último build noturno (com warning de instabilidade).
+
+Quando 2.1 (pacman como update real) estiver implementado, os canais migram naturalmente para repos pacman separados (`archr-core-stable`, `archr-core-next`, `archr-core-dev`).