# Genaro · Documentos Administrativos Genaro es el módulo de AnimalCharlie para crear plantillas y generar documentos administrativos destinados a revisión y firma: RGPD, contratos de servicios, autorizaciones, consentimientos y documentos equivalentes. Genaro no forma parte de Certificación. No usa informes BEA, expedientes A2A2 ni plantillas de certificación. En la navegación vive en `Documentos > Genaro`, junto a Archivo por compartir el ciclo documental, no su implementación: Genaro crea plantillas y documentos administrativos y Archivo conserva informes, plantillas, backups y auditoría. ## Carcasa Y Navegación La cabecera común describe la tarea como `Trabajo documental`, muestra la disponibilidad de Hermes y deja la documentación y el identificador técnico `hermes-module-genaro` dentro de `Más`. El usuario entra directamente en el flujo de plantillas o documentos; la información de infraestructura no compite con la tarea principal. Genaro usa `master-detail`: la biblioteca es la región `index` y la plantilla o documento activo ocupa `workbench`. Las pestañas `Crear plantillas` y `Generar documentos` siguen siendo la navegación funcional principal, y `Actividad Hermes` permanece plegada mientras no se necesite revisar trabajos persistentes. En iPad Air vertical, una actividad plegada conserva una sola fila compacta; solo crece cuando el usuario pulsa `Mostrar` y existen trabajos que revisar. La biblioteca ocupa después toda la altura restante: cabecera, búsqueda y filtros conservan su tamaño natural y `#genaroDocumentsList` recibe el espacio flexible con scroll propio. Abrir una plantilla o documento repliega la biblioteca y entrega el workbench completo al editor. La búsqueda de la biblioteca permanece visible y actualiza las listas al escribir. En `Crear plantillas` busca por nombre, categoría, carpeta, etiquetas y descripción; en `Generar documentos`, por nombre, cliente, explotación, plantilla o email del destinatario. `Filtros` abre el popover común: las plantillas permiten filtrar borradores o publicadas y por carpeta; los documentos permiten filtrar borradores, revisados, enviados o firmados, y ocultan el campo de carpeta porque no aplica. El contador solo incluye filtros disponibles, `Limpiar` los restablece sin borrar la búsqueda y abrir un registro repliega el popover. ## Acceso - Hash UI: `#genaro`. - Módulo interno: `genaro`. - Lectura: `genaro.read` o `genaro.write`. - Escritura: `genaro.write`. - Roles iniciales: administrador y técnico pueden crear o modificar; revisor puede consultar. - Subagente Hermes estable: `hermes-module-genaro`. - Modelo dedicado: `gpt-5.5` mediante LiteLLM (`GENARO_LITELLM_MODEL`), independiente del modelo general de Charlie. ## Parte 1 · Crear Plantillas La interfaz de escritorio organiza cada plantilla en cinco pasos: `Word y datos`, `Variables`, `Diseño`, `Probar` y `Publicar`. El usuario puede volver a cualquier paso sin perder el trabajo. En el primer paso sube un Word `.docx`, indica qué documento es y cuándo se utiliza, y pulsa `Analizar con Hermes`. `Word guardado` abre `AnimalCharlieAssetLibrary` filtrada exclusivamente a DOCX y coloca el recurso elegido en el mismo input, de modo que extracción, fidelidad y análisis siguen teniendo una sola implementación. También puede asignar carpeta y etiquetas para organizar la biblioteca. La subida y extracción inicial terminan antes de crear un trabajo persistente en `genaro_jobs`. Desde ese momento el navegador puede cerrarse: el servidor continúa el análisis con `gpt-5.5`, conserva estado, etapa, porcentaje y resultado, y reanuda trabajos que estuvieran ejecutándose si AnimalCharlie se reinicia. Al volver a `#genaro`, la banda `Actividad Hermes` recupera los trabajos del usuario conectado y aplica la propuesta terminada al editor. El backend limita tanto el fichero como el XML descomprimido y convierte el Word a una representación editable conservando colores, tipografías, tamaños, alineación, fondos, bordes, tablas, cabeceras, pies e imágenes incrustadas compatibles. También interpreta saltos manuales y renderizados de Word, tamaño y orientación de página, márgenes, espaciado exacto o automático, reglas de párrafo, filas no divisibles, anchos de tabla, márgenes de celda e imágenes DrawingML/VML. El Word original es la plantilla visual canónica: AnimalCharlie no permite que `gpt-5.5` reconstruya el HTML. El DOCX original queda guardado como binario privado del trabajo y se vincula a la plantilla cuando esta se guarda. No se devuelve en los listados JSON. Si está disponible, `Word original` permite descargar exactamente el fichero subido. Los análisis históricos, que se crearon antes de esta persistencia, conservan la vista HTML pero requieren una nueva subida para disponer también del binario. Para plantillas históricas que perdieron los saltos antes de existir el importador paginado, Genaro aplica una recuperación conservadora: si detecta la misma cabecera gráfica pesada repetida al inicio de varias partes, inserta los límites entre páginas sin modificar texto, tablas ni imágenes. El contrato real `Plantilla_Contrato_HERBA26_RGPD_SEPA 3.docx` pasa así de cinco páginas mezcladas a seis páginas lógicas: portada, alcance, condiciones, RGPD, autorización y SEPA. El subagente recibe texto y una vista estructural sin los bytes de las imágenes. Solo devuelve campos, preguntas y sustituciones literales; el backend inserta los marcadores sobre los nodos de texto del Word sin tocar etiquetas ni estilos. La revisión ortográfica usa el mismo principio y aplica correcciones literales sobre el documento existente. Así, Hermes no puede cambiar por accidente el diseño, las zonas de firma ni la composición del documento. Los análisis terminados con una versión anterior, que no incluyen la marca de fidelidad, no se restauran sobre el editor. Hay que volver a subir ese `.docx` una vez para reconstruirlo con el importador visual nuevo. AnimalCharlie llama al runtime Hermes Charlie mediante backend y presenta una propuesta editable con: - HTML de plantilla para el editor WYSIWYG. - Marcadores `{{clave}}` donde debe entrar un dato variable. - Definición de campos: clave, etiqueta, pregunta, tipo, obligatoriedad y origen. - Preguntas de aclaración cuando una decisión material no puede deducirse del Word. - Indicador de fidelidad que confirma que el diseño del Word se ha conservado. Genaro consolida los campos por su identidad real. Si varias apariciones corresponden, por ejemplo, a `client.name`, todas reutilizan una única clave aunque el Word use textos distintos como «cliente», «razón social» o «nombre del cliente». Las sustituciones literales conservan todas las apariciones, pero el formulario solo pregunta el dato una vez. La pantalla de variables usa un modo simple por defecto: muestra el nombre humano y el origen del dato. La clave, el tipo y la prioridad solo aparecen al activar `Modo avanzado`. Cada variable indica cuántas apariciones tiene y permite localizarla en el documento. Dentro del editor los marcadores se presentan como etiquetas verdes no destructivas. Al guardar o probar, la interfaz vuelve a convertirlas en marcadores `{{clave}}`, por lo que el motor de generación continúa trabajando con el contrato canónico. Si el análisis conserva `sourceHtml`, `Comparar con Word` muestra el original y la plantilla lado a lado y sincroniza proporcionalmente el desplazamiento. La banda de fidelidad informa de páginas, tablas, imágenes, recuperación de saltos y disponibilidad del DOCX original. `Vista PDF` abre el estudio global con las páginas detectadas antes de publicar. Las respuestas a esas preguntas se reenvían con `Responder y refinar`. Hermes no guarda la plantilla: el usuario revisa y pulsa `Guardar plantilla`. ### Orígenes De Campo Una plantilla puede pedir valores personalizados o leerlos de AnimalCharlie: - Cliente: nombre, NIF/CIF, contacto, representante legal, email, teléfono, dirección, localidad, provincia, código postal y forma de pago. - Explotación: nombre, REGA, dirección, región, especie, producción, censo, UGM, responsable y horario de acceso. - Tarifa: servicio o producto, categoría, precio, impuesto y tipo. - Documento: fecha y título. - Personalizado: texto, área de texto, número, fecha, email, teléfono o selector que se pregunta antes de generar. Los campos no son bloqueantes. `required` queda desactivado por defecto y, si se activa manualmente, funciona únicamente como aviso prioritario. Las líneas de firma y huecos hechos con guiones suelen repetirse muchas veces en un Word. Para evitar que un dato termine en una celda equivocada, Hermes devuelve anclajes literales `beforeText` y `afterText`; el motor solo sustituye el hueco cuando ese contexto identifica una única ubicación. Una coincidencia ambigua sin contexto se descarta y queda como sugerencia sin ubicar, separada de los campos activos. La banda de fidelidad informa de cuántas sugerencias se omitieron y Hermes añade una pregunta de refinado con sus nombres para que el usuario indique dónde aparecen o confirme que no se usan. `replaceAll` solo se admite cuando todas las apariciones exactas representan realmente el mismo campo. ### Prueba Y Publicación `Generar prueba` resuelve la plantilla con un cliente, explotación, tarifa y respuestas personalizadas sin insertar un documento. Permite comprobar diseño, fuentes automáticas y datos pendientes antes de publicar. `Comparar PDF` usa exactamente ese resultado temporal y muestra cada salto como una hoja independiente. Solo las plantillas `published` aparecen en el generador. Guardar como borrador mantiene la plantilla fuera de uso. Cada guardado o publicación crea una versión recuperable; restaurar una versión nunca sobrescribe el historial, sino que crea un nuevo borrador. Una plantilla también puede duplicarse para preparar una variante independiente. ## Parte 2 · Generar Documentos El usuario selecciona: 1. Plantilla. 2. Cliente. 3. Explotación opcional vinculada al cliente. 4. Tarifa opcional procedente del catálogo de Facturación. 5. Respuestas personalizadas definidas por la plantilla. El backend vuelve a consultar la base de datos y resuelve los marcadores. No confía en valores automáticos manipulados desde el navegador. El HTML se sanea con una lista de estructura documental permitida, sin scripts, formularios ni recursos remotos. El resultado se guarda en `genaro_documents` y se abre con el motor compartido mediante `AnimalCharlieDocumentEditor.mount(...)`. Si falta cualquier valor, el documento se genera igualmente. En lugar de borrar el marcador o devolver un error, Genaro inserta `ATENCIÓN · FALTA [campo]` en rojo dentro del contenido. El aviso forma parte del borrador, sobrevive al guardado y se puede seleccionar, sustituir o borrar como cualquier otro texto del editor. La respuesta de `POST /api/genaro/documents/generate` incluye además `missingFields` para que la interfaz muestre cuántos datos quedan pendientes. La interfaz agrupa los campos automáticos en resúmenes como `Cliente · 5 datos automáticos` y solo presenta inputs para respuestas personalizadas. El panel `Pendientes` agrupa los avisos por dato, indica sus apariciones y permite saltar al siguiente. Cuando el usuario sustituye el texto de un aviso en el editor, deja de tratarse como pendiente. En escritorio, los datos previos permanecen visibles mientras se prepara un documento nuevo. Al generar o abrir un borrador, el panel se repliega para dedicar el ancho disponible al editor A4; `Mostrar datos` permite recuperarlo en cualquier momento. La hoja se ajusta automáticamente al ancho real del visor sin superar el 100 %, las acciones se agrupan por edición, estado y exportación, y el historial queda plegado para que la barra de estado del editor permanezca dentro de la pantalla. `Generación por lote` admite hasta 50 clientes y crea un borrador independiente por cliente con un `batchId` común. No envía ni firma automáticamente. El mismo motor se usa al crear la plantilla y al editar el documento generado. Ambas instancias usan el perfil `word`, que mantiene todos los comandos compactos y conserva por defecto el formato pegado para proteger la fidelidad del Word; el usuario puede elegir pegado adaptado o solo texto desde `Formato`. Genaro no tiene toolbar, historial, IA contextual ni motor de formato propios: solo aporta importación Word, marcadores, fidelidad, persistencia y revisión. Por ello, una mejora general en `AnimalCharlieDocumentEditor` se aplica a las dos superficies de Genaro sin reimplementarla aquí. La arquitectura y el contrato para reutilizarlo desde otros módulos están en `DOCUMENT_EDITOR_ENGINE.md`. ### IA Contextual Del Editor Además de la revisión final obligatoria de Genaro, el usuario puede seleccionar un fragmento y pedir a `hermes-document-editor` que lo corrija, aclare, formalice, resuma, amplíe o siga una instrucción libre. Esta función usa `gpt-5.5` mediante LiteLLM y está disponible como capacidad nativa del motor para cualquier módulo de AnimalCharlie. Hermes devuelve una propuesta de texto, explicación y advertencias. El usuario puede editar la propuesta y después sustituir la selección, insertarla a continuación o descartarla. No se modifica nada automáticamente y una selección obsoleta no se puede aplicar. ## Revisión Hermes Obligatoria `Revisar ortografía con Hermes` llama a `hermes-module-genaro` con el HTML actual. El agente puede corregir ortografía, gramática, puntuación y erratas, pero tiene prohibido: - inventar o eliminar cláusulas; - cambiar nombres, cifras, fechas o importes; - alterar el alcance jurídico; - añadir asesoramiento legal; - aplicar cambios automáticamente. La respuesta se guarda como propuesta con cambios y dudas separadas. El documento no cambia hasta pulsar `Aceptar revisión`. Cualquier edición posterior vuelve a marcar la revisión como pendiente. La revisión también se ejecuta como trabajo persistente. Si el documento cambia mientras la revisión está en curso, el trabajo falla de forma segura y solicita una revisión nueva en vez de aplicar una propuesta sobre contenido antiguo. Los endpoints de PDF y DOCX devuelven `409 genaro_review_required` hasta que la revisión haya sido aceptada. La exportación deja el documento listo para remitir o firmar; el envío externo y la firma electrónica no se ejecutan automáticamente desde Genaro. Después de aceptar la revisión se puede registrar el documento como `sent` o `signed`. Estos estados guardan actor y fecha en la trazabilidad, pero siguen siendo registros internos: los botones dejan claro que no ejecutan servicios externos. El email del destinatario se propone desde el cliente y queda preparado para una integración futura. ## Persistencia ### `genaro_templates` Guarda nombre, categoría, carpeta, etiquetas, explicación, Word de origen como texto, HTML y DOCX privado, HTML editable, campos, preguntas, estado de publicación, revisión, propietario y fechas. ### `genaro_template_versions` Guarda hasta las 30 versiones más recientes de cada plantilla como snapshots recuperables, con revisión, motivo, autor y fecha. ### `genaro_documents` Guarda plantilla, cliente, explotación, tarifa, valores resueltos, HTML editable, propuesta de revisión, estado documental, destinatario, lote, fechas de envío/firma, propietario y trazabilidad. ### `genaro_jobs` Guarda el tipo de trabajo, entidad, petición ya extraída, etapa, progreso, resultado o error, propietario y fechas. Los trabajos `running` vuelven a `queued` al arrancar para continuar después de un reinicio. ## API - `GET /api/genaro/context`: clientes, explotaciones, tarifas, fuentes de campo y agente activo. - `GET /api/genaro/jobs`: listar trabajos persistentes y su progreso. - `GET /api/genaro/jobs/{id}`: consultar resultado o error de un trabajo. - `GET /api/genaro/templates`: listar resúmenes ligeros de plantillas. - `POST /api/genaro/templates`: crear o actualizar plantilla. - `POST /api/genaro/templates/assist`: extraer el Word y encolar su conversión persistente mediante Hermes. - `POST /api/genaro/templates/test`: probar contenido y variables sin crear documento. - `GET /api/genaro/templates/{id}`: cargar el contenido completo al abrir una plantilla. - `GET /api/genaro/templates/{id}/versions`: listar versiones. - `GET /api/genaro/templates/{id}/source-docx`: descargar el DOCX original conservado. - `POST /api/genaro/templates/{id}/restore`: restaurar una versión como nuevo borrador. - `POST /api/genaro/templates/{id}/duplicate`: duplicar una plantilla. - `DELETE /api/genaro/templates/{id}`: archivar plantilla. - `GET /api/genaro/documents`: listar resúmenes ligeros de documentos. - `POST /api/genaro/documents/generate`: resolver campos y generar borrador. - `POST /api/genaro/documents/generate-batch`: generar un lote para varios clientes. - `GET /api/genaro/documents/{id}`: cargar el contenido completo al abrir un documento. - `GET /api/genaro/documents/{id}/history`: consultar su trazabilidad. - `PUT /api/genaro/documents/{id}`: guardar editor o aceptar revisión. - `POST /api/genaro/documents/{id}/review`: encolar una revisión Hermes persistente. - `GET /api/genaro/documents/{id}/docx`: descargar DOCX revisado. - `GET /api/genaro/documents/{id}/pdf`: descargar PDF revisado. - `DELETE /api/genaro/documents/{id}`: archivar documento. - `POST /api/document-editor/assist`: preparar una propuesta IA sobre el texto seleccionado; requiere `charlie.execute` y usa `hermes-document-editor`. El editor de plantillas también puede abrir el estudio PDF global para comprobar la composición. El documento generado no muestra esa salida genérica: su PDF final continúa exclusivamente en `/api/genaro/documents/{id}/pdf` y conserva el bloqueo `genaro_review_required`. Todas las rutas requieren sesión y permisos de Genaro. Las llamadas a LiteLLM siguen ocultas detrás de AnimalCharlie y del runtime Hermes Charlie. Al actualizar desde una versión anterior a Genaro, el arranque añade el módulo a las listas persistidas de administradores, técnicos y revisores. Esto evita que una lista de módulos creada antes de existir Genaro rechace las rutas con `403`; los perfiles cliente y empleado no reciben acceso. ## Validación La regresión comprueba navegación, permisos, tablas, endpoints, flujo guiado, versiones, duplicado, prueba, lote, estados, historial, editor, consolidación semántica de campos, generación no bloqueante con avisos rojos, bloqueo de exportación, identidad `hermes-module-genaro`, manifiesto de agentes y documentación. Los cambios visuales deben probarse en `#genaro` con navegador real de escritorio.