From 9c9b6028e7b5737857c0da16bba34cf155aa84d2 Mon Sep 17 00:00:00 2001
From: Sergio Valor <jaildesigner@gmail.com>
Date: Wed, 22 Apr 2026 10:35:19 +0200
Subject: [PATCH] docs: convencions de commit i debug.yaml
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documenta dues peces que no estaven enlloc:

- Missatges de commit: valencià, frases curtes, sense firma automàtica
  (cap Co-Authored-By ni signatura de Claude Code).
- debug.yaml: ruta dins la carpeta de sistema, format, valors vàlids,
  i la diferència de comportament entre build release (sempre LOGO,
  ignora el fitxer) i build debug (llig el fitxer i el crea amb GAME
  si no existeix).

Entrada nova a l'índex de docs/README.md.
---
 docs/README.md      |  1 +
 docs/convencions.md | 61 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 docs/convencions.md

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.