diff --git a/cpp/PATTERNS.md b/cpp/PATTERNS.md
index ba3fdab8..14d870ce 100644
--- a/cpp/PATTERNS.md
+++ b/cpp/PATTERNS.md
@@ -110,3 +110,48 @@ Solo si la app es:
 
 En cualquier otro caso, usar `fn::run_app`. Si `AppConfig` no expone algo que
 necesitas, **abrir un issue para extender el shell**, no duplicar boilerplate.
+
+## Tests visuales y CI gate (issue 0048)
+
+`primitives_gallery` soporta un modo `--capture <output_dir>` que renderiza
+cada demo en una ventana GLFW invisible y guarda un PNG por demo. Se usa
+para tests visuales tipo golden-image:
+
+```bash
+# Regenerar goldens (cuando tu cambio es intencional):
+cpp/scripts/update_goldens.sh
+
+# Equivalente manual:
+LIBGL_ALWAYS_SOFTWARE=1 \
+    cpp/build/apps/primitives_gallery/primitives_gallery \
+    --capture cpp/tests/golden
+```
+
+`cpp/tests/test_visual.cpp` corre la captura sobre un tmpdir y compara contra
+`cpp/tests/golden/<demo>.png` con tolerancia 1% de pixels distintos
+(threshold 5/255 por canal). Skipea si:
+
+- `cpp/tests/golden/` esta vacio (no hay goldens todavia).
+- El binario `primitives_gallery` no se construyo.
+- El entorno no puede crear contexto GL (WSL minimo, container sin Mesa) —
+  el test reporta SKIP en lugar de FAIL.
+
+Para diagnosticar un diff: revisar el PNG actual en
+`cpp/build/tests/visual_actual/<demo>.png` vs el golden en
+`cpp/tests/golden/<demo>.png`.
+
+### CI gate `check_tested.sh`
+
+`cpp/scripts/check_tested.sh [days]` (default `30`) consulta `registry.db` y
+falla con codigo != 0 si alguna funcion C++ creada en los ultimos N dias no
+tiene `tested: true` en su frontmatter. Esta hookeado al final de
+`cpp/scripts/run_tests.sh`, por lo que el flujo CI (`./scripts/run_tests.sh`)
+falla si se anade una funcion C++ nueva sin test asociado.
+
+Para satisfacer el gate:
+1. Crear `cpp/tests/test_<name>.cpp` (puede ser placeholder Catch2 si la
+   logica visual se cubre via `primitives_gallery`).
+2. Anadirlo a `cpp/tests/CMakeLists.txt` con `add_fn_test(test_<name> ...)`.
+3. Marcar `tested: true` + `test_file_path: cpp/tests/test_<name>.cpp` en el
+   frontmatter del `.md` de la funcion.
+4. Correr `fn index` para refrescar `registry.db`.