From d706b6f0043a22978b476cf352adbb2bb932cf6b Mon Sep 17 00:00:00 2001
From: tzzrgit <git@tzr.systems>
Date: Mon, 22 Dec 2025 09:42:12 +0100
Subject: [PATCH] Update README with system documentation

---
 README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6a3b186..fc9b0ea 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,61 @@
-# feldman
+# FELDMAN
 
-Registro consolidado - Sistema TZZR
\ No newline at end of file
+**Registro consolidado - Sistema TZZR**
+
+## Rol
+
+Contable del sistema. Valida y archiva registros en bloques inmutables.
+
+## Posición en el Flujo
+
+```
+MASON ─────────────────┬──► FELDMAN
+                       │       │
+ALFRED/JARED (OK) ─────┘       │
+                               ▼
+                    ┌─────────────────────┐
+                    │   COLA (24h)        │
+                    │   ○ ○ ○ ○ ○        │
+                    └─────────┬───────────┘
+                              │
+                         cada 24h
+                              │
+                              ▼
+                    ┌─────────────────────┐
+                    │  BLOQUE INMUTABLE   │
+                    │  #1 → #2 → #3 → ... │
+                    └─────────────────────┘
+```
+
+## Fases
+
+### 1. Cola (24h)
+- Registros esperando consolidación
+- Usuario puede devolver a MASON
+- Configurable
+
+### 2. Bloques
+- Registros inmutables
+- Hash encadenado
+- Preparado para blockchain
+
+## Estructura de Bloque
+
+```json
+{
+  "numero": 127,
+  "hash_anterior": "def456...",
+  "merkle_root": "789abc...",
+  "validado_at": "2025-12-22T00:00:00Z",
+  "registros": [...],
+  "cantidad": 45
+}
+```
+
+## Arquitectura
+
+Ver documentación completa en [contratos-comunes/architecture](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/04-feldman.md)
+
+---
+
+*Componente del sistema TZZR*