From 8a9b17c83cff7789d687b826fb148f11efc2a133 Mon Sep 17 00:00:00 2001
From: reugenio <yo@reugenio.com>
Date: Mon, 8 Dec 2025 23:14:00 +0100
Subject: [PATCH] docs: update CLAUDE.md with complete project context
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add audit/ module to architecture
- Include TEAM_STANDARDS normas esenciales
- Add Zig 0.15 compatibility notes
- Reference REFERENCE.md and docs/
- Include workflow and communication guidelines

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

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

diff --git a/CLAUDE.md b/CLAUDE.md
index 9d40c9c..701667c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,13 +4,21 @@
 
 ## Estado
 
-**v1.0 - Completo** | 7,563 líneas | 15 módulos | 63 tests
+**v1.1** | ~12,000 líneas | 16 módulos | 80 tests
+
+## Quick Start
+
+```bash
+zig build              # Compilar
+zig build test         # Tests (80/80)
+./zig-out/bin/basic    # Ejemplo
+```
 
 ## Arquitectura
 
 ```
 src/
-├── root.zig        # Exports públicos y tests
+├── root.zig        # Exports públicos
 ├── database.zig    # Conexión, transacciones, pragmas, snapshots
 ├── statement.zig   # Prepared statements, binding, row mapping
 ├── session.zig     # Change tracking (Session extension)
@@ -24,42 +32,107 @@ src/
 ├── vtable.zig      # Virtual tables API
 ├── types.zig       # Tipos comunes
 ├── errors.zig      # Mapeo de errores
-└── c.zig           # C bindings
+├── c.zig           # C bindings
+└── audit/          # Sistema de auditoría
+    ├── mod.zig     # Exports
+    ├── log.zig     # AuditLog principal
+    ├── entry.zig   # Entry + JSON
+    ├── context.zig # User/app context
+    ├── index.zig   # File index
+    ├── writer.zig  # File rotation
+    └── verify.zig  # Hash chain verification
 ```
 
-## Comandos
+## Documentación
 
-```bash
-# Build
-zig build
-
-# Tests
-zig build test
-
-# Ejemplo
-zig build basic && ./zig-out/bin/basic
-```
+| Archivo | Contenido |
+|---------|-----------|
+| `REFERENCE.md` | **Manual técnico completo** - API, ejemplos, tipos |
+| `docs/AUDIT_LOG_DESIGN.md` | Diseño del sistema de auditoría |
+| `README.md` | Introducción y ejemplos básicos |
 
 ## SQLite Flags
 
 ```
--DSQLITE_THREADSAFE=0          # Single-threaded
--DSQLITE_ENABLE_FTS5           # Full-text search
--DSQLITE_ENABLE_JSON1          # JSON functions
--DSQLITE_ENABLE_RTREE          # R-Tree
--DSQLITE_ENABLE_SESSION        # Change tracking
--DSQLITE_ENABLE_SNAPSHOT       # Snapshots
+-DSQLITE_THREADSAFE=0           # Single-threaded
+-DSQLITE_ENABLE_FTS5            # Full-text search
+-DSQLITE_ENABLE_JSON1           # JSON functions
+-DSQLITE_ENABLE_RTREE           # R-Tree spatial
+-DSQLITE_ENABLE_SESSION         # Change tracking
+-DSQLITE_ENABLE_SNAPSHOT        # Snapshots
 -DSQLITE_ENABLE_COLUMN_METADATA
--DSQLITE_ENABLE_PREUPDATE_HOOK
+-DSQLITE_ENABLE_PREUPDATE_HOOK  # Pre-update hooks (audit)
 ```
 
-## Notas Técnicas
+## Notas Zig 0.15
 
-- Zig 0.15: usar `std.ArrayListUnmanaged` (no `ArrayList.init`)
-- Strings: `std.fmt.allocPrint` + null terminator manual
-- Callbacks C: requieren `callconv(.c)`
-- SQLITE_TRANSIENT: necesario para strings que Zig puede mover
-- Named params: incluir prefijo (`:name`, no `name`)
+| Cambio | Solución |
+|--------|----------|
+| `ArrayList.init` no existe | Usar `ArrayListUnmanaged` + `.empty` |
+| `callconv(.C)` | Cambiar a `callconv(.c)` (minúscula) |
+| `bufferedReader()` | Usar `readFileAlloc` |
+| Strings para SQLite | `allocPrint` + null terminator |
+| Named params | Incluir prefijo (`:name`) |
+
+## Audit Log
+
+```zig
+var audit = try AuditLog.init(allocator, &db, .{
+    .log_dir = "/var/log/audit",
+    .app_name = "my_app",
+});
+defer audit.deinit();
+audit.start();  // IMPORTANTE: después de que struct esté en memoria final
+```
+
+**Verificar integridad:**
+```zig
+var result = try verifyAuditChain(allocator, "/var/log/audit");
+defer result.deinit(allocator);
+if (!result.valid) { /* ALERTA */ }
+```
+
+---
+
+## TEAM STANDARDS
+
+**Ubicación:** `/mnt/cello2/arno/re/recode/TEAM_STANDARDS/`
+
+### Normas Esenciales
+
+**NUNCA:**
+- Ejecutar binarios en background (`&`) - shells zombies
+- Commit sin testing
+- Silenciar warnings
+- Duplicar código (verificar common/ primero)
+- Archivos >600 líneas
+- Modificar scope sin consultar
+
+**SIEMPRE:**
+- DRY - Una función por tarea
+- Testing progresivo (compilar + verificar)
+- Security commits antes de refactorizaciones
+- Actualizar CLAUDE.md cada sesión
+- Fragmentar: <400 líneas (core), <200 (utils)
+
+### Comunicación
+- Directo al grano, sin preámbulos
+- Honestidad técnica total
+- Si algo está mal, decirlo y explicar
+
+### Workflow
+1. Leer `TEAM_STANDARDS/LAST_UPDATE.md`
+2. Leer CLAUDE.md del proyecto
+3. Implementar con testing progresivo
+4. Actualizar documentación
+5. Commit tras confirmación usuario
+
+### Documentos Clave
+- `QUICK_REFERENCE.md` - Cheat sheet (<1 min)
+- `NORMAS_TRABAJO_CONSENSUADAS.md` - Metodología completa
+- `NORMAS_PATRONES_DESARROLLO.md` - Patrones específicos
+
+---
 
 ## Git
 
@@ -67,3 +140,9 @@ zig build basic && ./zig-out/bin/basic
 origin: git@git.reugenio.com:reugenio/zsqlite.git
 branch: main
 ```
+
+## Zig Path
+
+```bash
+ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
+```