From 9b1d85c8c3f747adc60f9ca4501d2cdc22642a21 Mon Sep 17 00:00:00 2001
From: reugenio <yo@reugenio.com>
Date: Thu, 18 Dec 2025 19:05:06 +0100
Subject: [PATCH] docs: CLAUDE.md v0.2.3 - initDeferred() y rangos negativos
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documentación añadida:
- initDeferred(): control manual sin auto-crear archivo
- Arquitectura 3 fuentes (File > BD > Defaults)
- Validación rangos negativos: "-100-100" soportado
- Historial con commits 0ef5efd y 957767d

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 88 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2f5e6d3..c714fcc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -26,9 +26,9 @@ PATH=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2:$PATH zig
 | Campo | Valor |
 |-------|-------|
 | **Nombre** | zcatconfig |
-| **Version** | v0.2.1 |
+| **Version** | v0.2.3 |
 | **Fecha inicio** | 2025-12-17 |
-| **Estado** | FUNCIONAL - Integrado en zsimifactu |
+| **Estado** | FUNCIONAL - Integrado en zsimifactu (arquitectura 3 fuentes) |
 | **Lenguaje** | Zig 0.15.2 |
 | **Dependencias** | Ninguna (Zig puro) |
 
@@ -208,10 +208,15 @@ const zcatconfig = @import("zcatconfig");
 // Crear ConfigManager tipado
 const MyConfigManager = zcatconfig.ConfigManager(&variables, MyConfig, "mi_app");
 
-// Inicializar (carga o crea archivo)
+// Opcion 1: init() - Carga o crea archivo automaticamente
 var manager = try MyConfigManager.init(allocator, "config.txt");
 defer manager.deinit();  // Auto-save si dirty
 
+// Opcion 2: initDeferred() - NO carga/crea archivo (control manual)
+var manager = MyConfigManager.initDeferred(allocator, "config.txt");
+// Luego cargar manualmente cuando sea necesario:
+try manager.load();  // o manager.save() para crear
+
 // Acceso
 const cfg = manager.getConfig();
 try manager.set("@mi_variable", "nuevo_valor");
@@ -220,6 +225,39 @@ try manager.set("@mi_variable", "nuevo_valor");
 manager.addObserver(myCallback, my_context);
 ```
 
+### initDeferred() - Control manual de archivo (v0.2.3)
+
+Cuando necesitas controlar **cuándo** se crea/carga el archivo (ej: arquitectura 3 fuentes):
+
+```zig
+// Caso de uso: File > BD > Defaults
+// 1. Crear manager SIN cargar archivo
+var manager = MyConfigManager.initDeferred(allocator, "config.txt");
+
+// 2. Verificar si existe archivo
+const archivo_existe = std.fs.cwd().access("config.txt", .{}) catch false;
+
+// 3. Verificar si BD tiene config
+const bd_tiene_config = checkDatabase();
+
+// 4. Aplicar prioridad
+if (archivo_existe) {
+    try manager.load();           // Cargar de archivo
+    syncToBd(&manager);           // Sync a BD
+} else if (bd_tiene_config) {
+    loadFromBd(&manager);         // Cargar de BD
+    try manager.save();           // Crear archivo
+} else {
+    try manager.save();           // Crear con defaults
+    syncToBd(&manager);           // Sync defaults a BD
+}
+```
+
+**Por qué initDeferred()?**
+- `init()` llama `loadOrCreate()` que crea el archivo con defaults
+- Si BD tiene valores, el archivo ya existe antes de poder verificar
+- `initDeferred()` permite verificar BD primero, luego decidir
+
 ### FileWatcher (hot-reload)
 
 ```zig
@@ -243,6 +281,46 @@ zcatconfig.loadFromString(&variables, Config, &config, defaults);
 
 ---
 
+## VALIDACION DE RANGOS (v0.2.3)
+
+### Rangos negativos soportados
+
+La validación de rangos ahora soporta valores mínimos negativos:
+
+```zig
+// Definición de variable con rango negativo
+.{ .name = "offset_x", .var_type = .integer, .range = "-100-100", ... }
+.{ .name = "offset_y", .var_type = .integer, .range = "-50-50", ... }
+.{ .name = "temperature", .var_type = .float, .range = "-40.0-85.0", ... }
+```
+
+### Bug corregido (commit `957767d`)
+
+**Problema:** `splitScalar('-')` dividía `"-100-100"` como `["", "100", "100"]`
+
+**Solución:** Buscar el separador '-' excluyendo el primer carácter si es negativo:
+
+```zig
+const separator_pos = blk: {
+    const start: usize = if (range.len > 0 and range[0] == '-') 1 else 0;
+    for (range[start..], start..) |c, i| {
+        if (c == '-') break :blk i;
+    }
+    return false;
+};
+```
+
+### Formatos de rango válidos
+
+| Rango | Mínimo | Máximo | Notas |
+|-------|--------|--------|-------|
+| `"0-100"` | 0 | 100 | Positivo simple |
+| `"-100-100"` | -100 | 100 | Negativo a positivo |
+| `"-50-50"` | -50 | 50 | Centrado en cero |
+| `"-100-0"` | -100 | 0 | Solo negativos |
+
+---
+
 ## EQUIPO
 
 - **Usuario (R.Eugenio)**: Desarrollador principal
@@ -252,8 +330,10 @@ zcatconfig.loadFromString(&variables, Config, &config, defaults);
 
 ## HISTORIAL
 
-| Fecha | Version | Cambios |
-|-------|---------|---------|
-| 2025-12-18 | v0.2.1 | FileWatcher, loadFromString, updateMtime |
-| 2025-12-17 | v0.2.0 | ConfigManager con observers, auto-save, isDirty |
-| 2025-12-17 | v0.1.0 | Proyecto creado, Engine + persistence |
+| Fecha | Version | Commit | Cambios |
+|-------|---------|--------|---------|
+| 2025-12-18 | v0.2.3 | `957767d` | validateIntRange/Float fix: rangos negativos `"-100-100"` |
+| 2025-12-18 | v0.2.2 | `0ef5efd` | initDeferred(): control manual sin auto-crear archivo |
+| 2025-12-18 | v0.2.1 | - | FileWatcher, loadFromString, updateMtime |
+| 2025-12-17 | v0.2.0 | - | ConfigManager con observers, auto-save, isDirty |
+| 2025-12-17 | v0.1.0 | - | Proyecto creado, Engine + persistence |