diff --git a/docs/README.md b/docs/README.md
index 49a9b59..730cc98 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,5 +5,6 @@
 | [audit-core-audio.md](audit-core-audio.md) | Auditoria de `source/core/audio/` | Arxivada (tancada amb `refactor/audio-engine-class`) |
 | [audit-core-rendering.md](audit-core-rendering.md) | Auditoria de `source/core/rendering/` | Arxivada (tots els ítems DONE/WONTFIX/DEFERRED documentats) |
 | [audit-game.md](audit-game.md) | Auditoria de `source/game/` | Arxivada (tancada amb `refactor/options-class`) |
+| [convencions.md](convencions.md) | Convencions del repo (commits, `debug.yaml`) | Viu |
 | [entities-system.md](entities-system.md) | Disseny del sistema d'entitats (factory, bus, EntityManager, hazards) | Viu |
 | [player-animations.md](player-animations.md) | Notes d'animacions direccionals i `stand` automàtic del Player | Viu |
diff --git a/docs/convencions.md b/docs/convencions.md
new file mode 100644
index 0000000..700bdd8
--- /dev/null
+++ b/docs/convencions.md
@@ -0,0 +1,61 @@
+# Convencions del repo
+
+## Missatges de commit
+
+- En **valencià**, frases curtes i compactes.
+- **Sense firma**: res de `Co-Authored-By:`, `Generated with Claude Code`, ni cap altra firma automàtica.
+- Un commit per unitat lògica. Si el canvi afecta àrees separades (feature + docs + test), separar en commits diferents.
+- Prefix opcional estil convencional (`feat:`, `fix:`, `refactor:`, `docs:`, `test:`) quan ajude a la llegibilitat.
+
+Exemple correcte:
+
+```
+feat(scenes): afegir placeholders LogoScene/TitleScene/IntroScene
+
+Tres escenes de 5 s cadascuna que precedeixen GameScene. Cada classe
+té el seu fitxer perquè divergiran quan es desenvolupe el contingut
+real (logo animat, menú de títol, cutscene).
+```
+
+## `debug.yaml` (ajust de dev, no versionat)
+
+Fitxer personal de desenvolupament, **fora del repo**. Viu a la mateixa carpeta
+de sistema que `config.yaml`:
+
+- Linux (XDG): `$XDG_CONFIG_HOME/jailgames/aee_2026/debug.yaml`
+  - Per defecte: `~/.config/jailgames/aee_2026/debug.yaml`
+
+### Comportament segons build
+
+- **Release** (`make release`): `debug.yaml` s'ignora completament. El joc
+  arranca sempre a `LOGO` i recorre el flux sencer `LOGO → TITLE → INTRO → GAME`,
+  tal com ho veurà el jugador final.
+- **Debug** (`make build`): es llig `debug.yaml`. Si no existeix, es crea
+  automàticament amb `start_scene: GAME` perquè el dia a dia de gameplay no
+  arrossegui els 15 s de placeholders. Editant-lo a mà, es pot triar el punt
+  d'entrada.
+
+### Format
+
+```yaml
+start_scene: GAME   # valors vàlids: LOGO, TITLE, INTRO, GAME
+```
+
+- `start_scene: LOGO` → arranca a `LogoScene` i recorre `LOGO → TITLE → INTRO → GAME`.
+- `start_scene: TITLE` → arranca a `TitleScene` i recorre `TITLE → INTRO → GAME`.
+- `start_scene: INTRO` → arranca a `IntroScene` i recorre `INTRO → GAME`.
+- `start_scene: GAME` → arranca directament a `GameScene` (valor que s'escriu
+  per defecte en la creació automàtica).
+
+### Comportament davant d'errors (build debug)
+
+- Fitxer buit, valor desconegut o YAML invàlid → `GAME` amb warning a stderr.
+  El fitxer no es reescriu automàticament: es respecta l'edició manual per si
+  l'usuari ha teclejat alguna cosa intencionadament.
+
+### Durada dels placeholders
+
+Cada escena placeholder (LOGO, TITLE, INTRO) mostra el seu nom i un compte
+regressiu de 5 segons al centre de la pantalla. Es pot saltar amb qualsevol
+tecla excepte les registrades a `data/input/keys.yaml` (F1–F12 i Escape),
+que mantenen el seu comportament de hotkey global.