oLuqueJs · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,36 @@
+---
+name: Relato de bug
+about: Relate um problema para ajudar a corrigi-lo.
+title: ""
+---
+
+## Descrição
+
+<!-- Descreva o problema de forma clara. -->
+
+## Como reproduzir
+
+1. Primeiro passo
+2. Segundo passo
+3. Terceiro passo
+
+## Resultado esperado
+
+<!-- O que deveria acontecer? -->
+
+## Resultado observado
+
+<!-- O que aconteceu? Inclua mensagens de erro, se houver. -->
+
+## Ambiente
+
+- Versão do RetroX:
+- Versão do macOS:
+- Arquitetura: Apple Silicon ou Intel
+- Emulador e versão, se aplicável:
+
+## Informações adicionais
+
+<!-- Inclua logs ou capturas de tela, se ajudarem. Remova dados pessoais e credenciais. -->
+
+<!-- Para vulnerabilidades de segurança, não abra uma issue pública. Consulte CONTRIBUTING.md. -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,23 @@
+---
+name: Sugestão de melhoria
+about: Proponha uma funcionalidade ou melhoria para o RetroX.
+title: ""
+---
+
+## Problema ou necessidade
+
+<!-- Descreva a situação e quem é afetado. -->
+
+## Solução proposta
+
+<!-- Descreva o comportamento desejado e como ele ajudaria. -->
+
+## Critérios de aceitação
+
+<!-- Liste resultados verificáveis que indiquem que a necessidade foi atendida. -->
+
+- [ ] Resultado esperado
+
+## Alternativas e contexto
+
+<!-- Se aplicável, descreva alternativas consideradas, exemplos ou referências. -->
diff --git a/.github/PULL_REQUEST_TEMPLATE/beta_release.md b/.github/PULL_REQUEST_TEMPLATE/beta_release.md
@@ -0,0 +1,23 @@
+## Beta release
+
+<!-- PR de ci/beta para main. -->
+
+## O que está incluído
+
+<!-- Resuma as mudanças mais relevantes para esta release. -->
+
+## Validação
+
+<!-- Informe os testes executados, seus resultados e a versão testada. -->
+
+## Riscos e pendências
+
+<!-- Descreva riscos, problemas conhecidos ou escreva "Nenhum". -->
+
+## Checklist
+
+- [ ] A branch de origem é `ci/beta` e o destino é `main`.
+- [ ] As alterações foram testadas e os resultados estão registrados acima.
+- [ ] O workflow **Testes** está verde.
+- [ ] A mensagem do commit de squash segue Conventional Commits e reflete o tipo de release desejado.
+- [ ] A mudança foi aprovada por um revisor.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,3 +1,5 @@
+> O alvo deste PR deve ser a branch `beta`.
+
 ## O que muda e por quê
 
 <!-- Descreva a mudança e o motivo. Ligue a issue: Closes #123 -->

diff --git a/.github/workflows/ci-release.yml b/.github/workflows/ci-release.yml
@@ -2,7 +2,7 @@ name: Publicar release
 
 on:
   push:
-    branches: [main]
+    branches: [main, beta]
 
 permissions:
   contents: read

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -3,7 +3,7 @@ name: Testes
 on:
   pull_request:
   push:
-    branches-ignore: [main]
+    branches-ignore: [main, beta]
   workflow_dispatch:
   workflow_call:
 

diff --git a/.releaserc.json b/.releaserc.json
@@ -1,5 +1,5 @@
 {
-  "branches": ["main"],
+  "branches": ["main", { "name": "beta", "prerelease": true }],
   "plugins": [
     ["@semantic-release/commit-analyzer", {
       "releaseRules": [

diff --git a/AGENTS.md b/AGENTS.md
@@ -32,25 +32,60 @@ application UI from reusable core functionality.
 
 ## Git Workflow
 
-The project uses GitHub Flow. `main` is always releasable and protected.
+Two long-lived, protected branches:
 
-1. Never commit or push directly to `main`.
-2. Branch from an up-to-date `main`. Name branches `<type>/<short-description>`
+- `beta`: where changes land first. Every merge publishes a pre-release
+  (`1.2.0-beta.1`, `1.2.0-beta.2`, ...).
+- `main`: stable. Only receives promotions from `beta` and urgent hotfixes.
+  Every merge may publish a stable release.
+
+Rules:
+
+1. Never commit or push directly to `main` or `beta`.
+2. Branch from an up-to-date `beta`. Name branches `<type>/<short-description>`
    with the same types as commits: `feat/`, `fix/`, `chore/`, `docs/`,
    `refactor/`, `test/`, `ci/`.
 3. Keep branches short-lived and focused on one change.
-4. Open a pull request to `main`. Required: CI (workflow "Testes") green.
-5. PRs are merged with **squash merge** only. The PR title becomes the commit
-   on `main`, so it must be a valid Conventional Commit, in Portuguese:
-   `feat(biblioteca): detecta capas do Azahar`.
+4. Open a pull request to `beta`. Required: CI (workflow "Testes") green.
+   Contributions from forks follow the same rule.
+5. All PRs, including `beta` -> `main`, are merged with **squash merge**. The
+   PR title becomes the commit, so it must be a valid Conventional Commit, in
+   Portuguese: `feat(biblioteca): detecta capas do Azahar`.
 6. Delete the branch after merge.
-7. Never merge without human approval, never force-push `main`, never skip
-   hooks or CI.
+7. Never merge without human approval, never force-push `main` or `beta`,
+   never skip hooks or CI.
+
+### Promoting to stable
+
+A stable release happens when a PR `beta` -> `main` is squash merged, after the
+pre-release was tested. Never open it without being asked.
+
+Because the squash commit is the only commit semantic-release reads on `main`:
+
+- The title is a Conventional Commit whose **type matches the highest-impact
+  change** being promoted: `feat` if any feature, otherwise `fix` (or `chore`).
+  Example: `feat: novo tema Rayo Paradise e capas do Azahar`.
+- If any promoted change has a `BREAKING CHANGE`, repeat it as a
+  `BREAKING CHANGE: <description>` footer in the PR description, which becomes
+  the commit body.
+- The squash commit message must use "pull request title and description".
+- Right after the merge, merge `main` back into `beta`. Without this, the
+  promoted commits are not ancestors of `main` and the next promotion PR
+  conflicts or lists them again.
+
+### Exceptions to go straight to `main`
+
+- Urgent hotfixes (`fix/`), branched from `main`.
+- Changes that do not publish a version and do not touch app behavior
+  (`docs`, `ci`).
+
+After any change merged straight into `main`, merge `main` back into `beta`
+to keep the branches in sync.
 
 ### Commits and versions
 
-semantic-release publishes a release on every merge to `main`, using the
-rules in `.releaserc.json`:
+semantic-release publishes a release on every merge to `beta` (pre-release)
+and `main` (stable), using the rules in `.releaserc.json`:
 
 | Commit type | Release |
 | --- | --- |

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -42,28 +42,36 @@ detalhes, e a resposta vem o quanto antes.
 
 ### Fluxo de branches
 
-O projeto usa **GitHub Flow**: a `main` está sempre pronta para release e é protegida. Todo trabalho
-entra por pull request, vindo de uma branch curta (ou de um fork) criada a partir da `main`.
+O projeto tem duas branches protegidas:
+
+- **`beta`**: onde toda mudança entra primeiro. Cada merge publica uma pré-release
+  (`1.2.0-beta.1`, `1.2.0-beta.2`…), marcada como *pre-release* no GitHub e fora do link "última versão".
+- **`main`**: a versão estável. Só recebe a promoção da `beta` e correções urgentes.
+
+**Todo pull request, inclusive de forks, vai para a `beta`.** Se você abrir contra a `main` por engano,
+o mantenedor muda o alvo.
 
 - Nome da branch: `<tipo>/<descrição-curta>`, com os mesmos tipos dos commits.
-- O PR exige o CI verde e é integrado com **squash merge**. O título do PR vira o commit na `main`,
+- O PR exige o CI verde e é integrado com **squash merge**. O título do PR vira o commit na `beta`,
   então ele precisa seguir o padrão de commits abaixo.
-- Cada merge pode publicar uma release (veja [Releases](#releases)); por isso, agrupe mudanças
-  relacionadas num PR só.
 - Depois do merge, a branch é apagada.
+- A versão estável sai quando o mantenedor integra a `beta` na `main`, também por **squash merge**. O
+  título desse PR é o commit que define a versão, então usa o tipo da mudança mais relevante
+  (`feat: novo tema e capas do Azahar`), e um `BREAKING CHANGE:` vai na descrição. Em seguida, a `main` é
+  integrada de volta na `beta`; o mesmo vale depois de qualquer mudança direto na `main`.
 
 ### Enviando código por fork e pull request
 
 1. Faça um **fork** do repositório e clone o seu fork.
-2. Crie uma branch a partir da `main`, com um nome que descreva a mudança:
+2. Crie uma branch a partir da `beta`, com um nome que descreva a mudança:
    `feat/dolphin-adapter`, `fix/scan-capas`, `docs/readme`.
 3. Faça a mudança (veja as regras abaixo) e rode as verificações.
-4. Envie a branch para o seu fork e abra um **pull request** para a `main` deste repositório.
+4. Envie a branch para o seu fork e abra um **pull request** para a `beta` deste repositório.
 5. Descreva o que mudou e por quê, e ligue a issue relacionada (`Closes #123`).
 6. Responda aos comentários da revisão. Se pedirem ajustes, adicione commits à mesma branch.
 
 Pull requests de primeira vez passam pelo CI (workflow **Testes**). Ele precisa estar verde para o
-merge. Ninguém faz push direto na `main`; todo merge passa por revisão.
+merge. Ninguém faz push direto na `main` nem na `beta`; todo merge passa por revisão.
 
 ## Ambiente de desenvolvimento
 
@@ -112,8 +120,8 @@ O `!` depois do tipo não é reconhecido.
 
 ## Releases
 
-O workflow **Testes** roda em pull requests, em pushes para branches fora de `main` e sob demanda.
-O workflow de release reutiliza esses testes no commit enviado a `main`; depois deles, o
+O workflow **Testes** roda em pull requests, em pushes para branches fora de `main` e `beta` e sob demanda.
+O workflow de release reutiliza esses testes no commit enviado a `main` ou `beta`; depois deles, o
 semantic-release lê os commits, cria a tag e publica uma GitHub Release com o ZIP do `RetroX.app`
 (Apple Silicon) e o SHA-256. As regras de versão estão em `.releaserc.json`:
 

diff --git a/docs/DECISOES.md b/docs/DECISOES.md
@@ -27,7 +27,8 @@ Decisões do usuário e suposições de trabalho que não cabem num ADR. Decisõ
 | D14 | Abertura animada ao iniciar e transições suaves entre telas, inspiradas na fluidez do iiSU, com identidade própria. |
 | D15 | Marca do RetroX: a personagem **Rayo** (tile do ícone) e o nome com o "X" na cor de destaque, alinhados pela altura das maiúsculas. Substitui o R geométrico (conceito C). Kit e regras em `docs/design/logo/README.md`, gerados por `scripts/brand-kit.swift`. |
 | D16 | Código sob GPL-3.0; a marca (Rayo, logo, ícone e os nomes RetroX e Rayo) fica fora da licença, com todos os direitos reservados (2026-10-28). Regras em `BRAND.md`; contribuições por fork e PR em `CONTRIBUTING.md`. |
-| D17 | Fluxo de branches: GitHub Flow. `main` protegida e sempre liberável; branches curtas `<tipo>/<descrição>`; PR com CI verde e squash merge, cujo título é um Conventional Commit. Cada merge pode publicar uma release (semantic-release, regras em `.releaserc.json`). Sem `develop` nem nightly por ora; canal `next` fica como opção. Regras para agentes em `AGENTS.md`. |
+| D17 | Fluxo de branches: duas branches protegidas, `beta` (entrada de todas as mudanças, pré-releases) e `main` (estável). Branches curtas `<tipo>/<descrição>`; PR com CI verde e squash merge, cujo título é um Conventional Commit. Sem `develop` nem nightly. Regras para agentes em `AGENTS.md`. |
+| D18 | Pré-releases na branch `beta` (semantic-release, `prerelease: true`), versões `X.Y.Z-beta.N`. Todo PR, inclusive de forks, vai para a `beta`; a `main` recebe só a promoção `beta` -> `main` (PR com squash, título com o tipo da mudança mais relevante; depois a `main` é integrada de volta na `beta`) e hotfixes. `docs` e `ci` podem ir direto à `main`, com a `main` integrada de volta na `beta`. Nome `beta` coincide com o sufixo da versão e a convenção do semantic-release. |
 
 ## Suposições de trabalho