From c8742a189e4b4a23be42f7400c65c197c1f6c168 Mon Sep 17 00:00:00 2001
From: tzzrgit <git@tzr.systems>
Date: Mon, 22 Dec 2025 11:54:34 +0100
Subject: [PATCH] Add enriquecimiento data structure to README

- Documents all enrichment fields available
- Shows interaction with extraccion.tags_sugeridos
- Explains mutability rules
- Links to contratos-comunes schema
---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/README.md b/README.md
index 53c77ab..576b0f1 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,53 @@ FELDMAN ─────────────────┘
 | Novato | Usa mucho este espacio |
 | Avanzado | Paso casi automático |
 
+## Estructura de Datos
+
+MASON trabaja con la seccion `enriquecimiento` del contenedor (ver [esquema completo](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/06-contenedor-schema.md)):
+
+```json
+{
+  "enriquecimiento": {
+    "notas": "Pendiente de pago",
+    "campos_personalizados": {
+      "proyecto": "Proyecto Alpha",
+      "responsable": "Juan Garcia"
+    },
+    "tags_confirmados": ["sha256-tag1", "sha256-tag2"],
+    "tags_rechazados": ["sha256-tag3"],
+    "correcciones": {
+      "texto": null,
+      "entidades": null
+    },
+    "editado_por": "usuario-id",
+    "editado_at": "2025-01-15T11:00:00Z"
+  }
+}
+```
+
+### Campos disponibles
+
+| Campo | Tipo | Descripcion |
+|-------|------|-------------|
+| `notas` | String | Texto libre del usuario |
+| `campos_personalizados` | Object | Campos key-value definidos por usuario |
+| `tags_confirmados` | Array | h_maestro de tags sugeridos aceptados |
+| `tags_rechazados` | Array | h_maestro de tags sugeridos descartados |
+| `correcciones.texto` | String | Texto corregido si OCR fallo |
+| `correcciones.entidades` | Object | Entidades corregidas |
+
+### Interaccion con extraccion
+
+MASON muestra los `tags_sugeridos` de la seccion `extraccion` para que el usuario:
+- Confirme (se mueven a `enriquecimiento.tags_confirmados`)
+- Rechace (se mueven a `enriquecimiento.tags_rechazados`)
+
+### Mutabilidad
+
+- `enriquecimiento` es **mutable** mientras el registro esta en MASON
+- Una vez enviado a FELDMAN, se congela
+- Si FELDMAN devuelve el registro, vuelve a ser editable
+
 ## Arquitectura
 
 Ver documentación completa en [contratos-comunes/architecture](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/03-mason.md)