Sincronización de documentación Markdown con el CMS

Este documento es un manual operativo para flujos de trabajo de IA/operador de confianza que sincronizan los archivos de documentación Markdown modificados de la carpeta docs/ del repositorio con páginas de documentación de WebBlocks CMS vinculadas a su fuente. Es orientación de producto exclusivamente documental. No añade ningún motor de sincronización en tiempo de ejecución, endpoint, migración, comando de Artisan, script, job, cola, tabla de base de datos, proceso de publicación ni conexión con ningún destino en producción.

Los archivos Markdown bajo docs/ siguen siendo la fuente de verdad de la documentación técnica de WebBlocks CMS. Las páginas de documentación del CMS son derivados generados, en borrador o publicados, de esos archivos Markdown. El flujo de trabajo existe para que los cambios de documentación realizados durante el desarrollo normal del producto puedan reflejarse en un sitio de documentación del CMS sin tratar la página del CMS como la copia autorizada.

Se trata de un flujo de trabajo de IA/operador, no de una sincronización automática en tiempo de ejecución. El CMS no debe vigilar el repositorio, ni descargar archivos Markdown, ni modificar contenido por su cuenta. Un operador o herramienta de IA de confianza planifica, valida y, opcionalmente, aplica actualizaciones seguras en borrador a través de la Internal Content API.

El modelo debe funcionar con cualquier instalación del CMS o sitio de documentación de destino. La documentación y los informes deben mantenerse genéricos y no deben incluir el nombre real de un sitio de destino, un dominio real, un token de API real, una ruta absoluta local, un registro en bruto ni un valor de entorno.

Los futuros operadores deberían poder usar prompts concisos como:

A partir de estos comandos breves, la IA/el operador debe deducir el flujo de trabajo estándar:

• usar los archivos Markdown bajo docs/ como conjunto de fuentes candidatas
• preferir los archivos modificados en lugar de un escaneo completo del árbol docs
• leer el front matter cms_sync y los metadatos de origen
• descubrir la API del CMS de destino desde GET /webadmin/api
• usar únicamente contratos de contenido y handles de bloque descubiertos
• emparejar las páginas del CMS vinculadas a su fuente por identidad de origen antes que por ruta
• elaborar un plan y un informe de validación por archivo
• aplicar solo cuando el comando autorice explícitamente una aplicación segura en borrador o el usuario apruebe el plan exacto
• no publicar nunca salvo que el usuario lo pida explícitamente y el token disponga de content.publish

Update por sí solo significa planificar, validar y aplicar cambios seguros en borrador únicamente cuando la instrucción del usuario autorice claramente la aplicación. No implica publicar, editar la navegación, sobrescribir páginas en producción, importar medios ni automatizar el navegador.

Use este orden para decidir qué archivos Markdown son candidatos:

1. Si el usuario proporciona una lista explícita de archivos, use esa lista.
2. En caso contrario, use los archivos Markdown modificados en el repositorio bajo docs/.
3. Incluya los archivos .md añadidos, modificados y renombrados.
4. Excluya los archivos de changelog de versiones archivados bajo docs/releases/ salvo que se soliciten explícitamente.
5. Excluya los documentos internos de IA, worklog, auditoría o planificación privada cuando queden fuera de la documentación pública o estén marcados como internos.
6. Excluya los archivos sin metadatos cms_sync salvo que el flujo de trabajo esté explícitamente en modo de planificación o de adopción.
7. Ejecute un reescaneo completo de docs/ solo cuando el usuario lo pida explícitamente.

La detección de archivos modificados es únicamente un paso de selección de fuentes. No debe alterar el estado de Git, ni preparar archivos en el índice, ni crear artefactos de versión, ni deducir una instalación del CMS de destino a partir de los remotos del repositorio.

Los archivos Markdown se adhieren mediante front matter:

cms_site, arriba, es un handle de sitio de destino de ejemplo, no un dominio ni un nombre de instalación reales. cms_source_id es la identidad de origen estable. Si un archivo se mueve, la identidad de origen puede permanecer sin cambios, de modo que la página de destino todavía pueda emparejarse con seguridad.

Reglas de los metadatos:

• cms_source_id es la identidad de origen estable.
• cms_path es la ruta canónica de Page Translation, como /docs/internal-content-api; no anteponga /p a las páginas de documentación nuevas.
• cms_layout toma por defecto el valor docs cuando falta.
• cms_locale toma por defecto el valor en cuando falta.
• cms_title toma por defecto el primer H1 o un título derivado del nombre del archivo cuando falta.
• el hash de origen es un hash SHA-256 del contenido Markdown de origen usado para detectar cambios.
• la ausencia de metadatos cms_sync significa que el archivo se omite en el modo de actualización normal y puede notificarse para la planificación de la adopción.

La adopción inicial puede realizarse como un paso de siembra de metadatos exclusivamente documental, antes de cualquier descubrimiento del CMS en producción o intento de aplicación. Ese paso debería añadir front matter genérico y seguro a los archivos Markdown de documentación pública seleccionados, para que los planes posteriores puedan identificar ids de origen, rutas, idiomas (locales), layouts y títulos sin conjeturas. Una pasada de adopción completa de docs/ debería seguir excluyendo los changelogs de versiones archivados bajo docs/releases/ salvo que un operador de confianza apruebe explícitamente esas páginas de archivo.

Una página del CMS vinculada a su fuente debería conservar los metadatos de origen en los ajustes de la página. Los ajustes de página bastan para el flujo de trabajo documentado; una tabla de mapeo de fuentes aparte solo puede plantearse más adelante si los informes, el mapeo entre idiomas, la auditoría o las operaciones a gran escala lo exigen.

Forma recomendada de los ajustes de página:

La ruta de origen es descriptiva. La identidad estable es source_id y el detector de cambios es source_sha256. La Internal Content API acepta este objeto únicamente a través del ajuste de página permitido source_sync, lo conserva tras el apply y devuelve los mismos campos seguros en las respuestas de listado y detalle de páginas para el emparejamiento. No almacene tokens, valores de entorno, rutas absolutas locales, rutas de servidor ni otros secretos.

El orden de emparejamiento debe ser determinista:

1. Busque una página del CMS cuyo source_sync.source_id coincida, o con metadatos cms_source_id equivalentes.
2. Si la encuentra, compare source_sha256.
3. Si no hay coincidencia por id de origen, busque una página en la ruta canónica cms_path.
4. Si la ruta existe sin metadatos de origen coincidentes, notifíquelo como caso de adopción o de revisión de conflicto.
5. Si la ruta pertenece a otro source_id, notifique un conflicto y deténgase para ese archivo.
6. Si no existe ninguna página en la ruta, planifique create_draft_page con page.path fijado a la ruta canónica cms_path.

No use la comparación de contenido como mecanismo principal de emparejamiento. Empareje primero por identidad de origen estable y solo después por ruta, para la adopción o la revisión de conflictos.

Para la documentación Markdown modificada, use estos valores por defecto:

• Si el hash de origen no ha cambiado en los metadatos del CMS, omita el archivo.
• Si no existe ninguna página del CMS coincidente, planifique create_draft_page.
• Si existe una página en borrador coincidente, planifique replace_existing_draft_page para los slots gestionados propiedad de la página.
• Si solo existe una página publicada coincidente, no la sustituya directamente salvo que el flujo de trabajo disponga de una vía documentada segura de borrador o de staging y el usuario apruebe explícitamente esa vía.
• El slot gestionado por defecto es main.
• Conserve la cabecera, el pie, los slots desactivados y las asignaciones de Shared Slot.
• No sustituya un slot respaldado por un Shared Slot.
• Planifique la navegación por separado y no aplique cambios de navegación por defecto.
• La publicación nunca forma parte de content apply por defecto.

El flujo de trabajo debería regenerar los slots gestionados propiedad de la página a partir de la fuente Markdown, en lugar de intentar conservar ediciones manuales del CMS dentro de esos slots. Las páginas de documentación vinculadas a su fuente son derivados reproducibles; el Markdown sigue siendo la autoridad.

Construya contenido estructurado usando únicamente handles descubiertos en la instalación de destino. No adivine nunca handles de bloque ni grafías parecidas.

Reglas prácticas de correspondencia:

• H1 se corresponde con el título de la página y/o con un bloque content_header cuando ese handle está disponible.
• H2 y H3 se corresponden con bloques header, con anclas donde estén soportadas.
• Los párrafos se corresponden con rich-text.
• El texto corto y sin formato puede usar plain_text solo cuando resulte más apropiado que el texto enriquecido.
• Las listas se corresponden con un bloque de lista cuando el contrato de contenido actual admita alguno; en caso contrario, manténgalas en rich-text.
• Las tablas se corresponden con un bloque table siempre que sea posible.
• Los bloques de código delimitados se corresponden con un bloque code.
• Las citas en bloque se corresponden con bloques quote o de tipo alert/aviso, según su significado y los contratos descubiertos.
• Los enlaces normales de Markdown siguen siendo enlaces de rich-text.
• Los enlaces de tipo CTA pueden convertirse en button_link solo cuando sean intencionadamente de acción.
• Debe evitarse el HTML en bruto; html es un recurso de reserva revisado, solo para cuando los bloques estructurados no puedan representar el contenido.
• Las imágenes y los medios no deben descargarse ni importarse. Avise, salvo que el flujo de trabajo de destino admita explícitamente referencias a medios existentes.

Prefiera una estructura de documentación legible antes que un único bloque rich-text de gran tamaño. Una página de documentación normal suele usar content_header o el contenido del título derivado del H1, seguido de encabezados, texto enriquecido, listas, tablas y bloques de código dentro del slot gestionado main.

El flujo de trabajo es API-first:

1. Empiece por GET /webadmin/api.
2. Use los enlaces devueltos para OpenAPI, la guía de IA, el contrato de contenido, los tipos de bloque, las páginas, la navegación y los Shared Slots.
3. Confirme que el token tiene las capacidades necesarias para el modo solicitado.
4. Lea las páginas existentes y sus metadatos de origen a través de la API.
5. Elabore los planes de página usando únicamente handles descubiertos.
6. Ejecute POST /webadmin/api/content/validate antes del apply.
7. Aplique solo tras una aprobación explícita o cuando la instrucción del usuario autorice explícitamente una aplicación segura en borrador.
8. No publique nunca salvo que el usuario lo pida explícitamente y el token disponga de content.publish.
9. No use nunca automatización de navegador cuando la API esté disponible.

Los errores de la API son retroalimentación del flujo de trabajo. Trate las respuestas JSON 401, 403 y 422 como señales de parada o de revisión, siga los enlaces de descubrimiento/documentación e informe de un estado resumido y seguro sin imprimir secretos.

Cuando hay varios documentos modificados candidatos:

• trate cada documento de origen como una actualización de página planificada independiente
• valide todos los planes de página candidatos antes de aplicar cualquier lote, salvo que el operador opte explícitamente por aplicar archivo a archivo
• deje que el conflicto de un archivo detenga ese archivo sin ocultar los planes correctos de los demás
• informe por separado de los archivos omitidos, planificados, validados, aplicados, fallidos y en conflicto
• no haga cambios de navegación solo porque hayan cambiado varios documentos
• mantenga la planificación de la navegación como un plan explícito aparte

La aplicación por lotes debe ser conservadora. Si el usuario ha solicitado una aplicación segura en borrador, aplique solo los elementos validados que sean seguros para borrador y deje sin aplicar los conflictos y los casos pendientes de revisión.

Deténgase antes del apply cuando:

• el token de API falta, no es válido o ha sido revocado
• el descubrimiento de la API falla
• no se pueden leer OpenAPI, el contrato de contenido o los tipos de bloque
• los handles de bloque necesarios no están disponibles
• cms_path entra en conflicto con otro cms_source_id
• la página de destino está publicada y no hay ninguna vía segura de sustitución en borrador
• el plan sustituiría un slot respaldado por un Shared Slot
• la validación falla
• el usuario no ha aprobado el apply y la instrucción era una simulación o solo de planificación

Deténgase también antes de publicar salvo que el usuario lo pida explícitamente, el plan ya se haya validado/aplicado con seguridad y el token disponga de content.publish.

Para los lotes, agrupe los mismos campos en secciones skipped, planned, validated, applied, failed, conflict y needs review.

Solo planificar:

Solo validar:

Validar y aplicar actualizaciones seguras en borrador:

Planificación con reescaneo completo:

Solo planificación de la navegación:

Las páginas de documentación vinculadas a su fuente deberían marcarse como gestionadas desde el origen en el CMS. Una futura pantalla de edición podría avisar a los editores: "Esta página se sincroniza desde una fuente Markdown. Edite el archivo de origen en su lugar."

Las ediciones manuales en el CMS de las páginas de documentación vinculadas a su fuente no se conservan en la siguiente regeneración de los slots gestionados a partir del origen. Las asignaciones de cabecera/pie y de Shared Slot sí se conservan, porque no son contenido Markdown gestionado propiedad de la página.

La documentación y los informes del operador no deben incluir tokens, secretos, rutas absolutas locales, registros en bruto, valores de entorno, nombres reales de sitios de destino ni dominios reales.