AGENTS.md — Ecosistema Educativo Hermes IA para ARL SURA

Guía de contexto y operación para agentes que trabajen en este proyecto. Léela completa antes de modificar cualquier archivo.

1. Qué es este proyecto

Producción de la ruta de 7 cursos de SST en inglés para empresas afiliadas a ARL SURA con talento angloparlante, impartidos con el agente conversacional Tibot (Hermes IA) dentro del LMS Zalvadora (Colegio de Gestión del Riesgo).

2. Estructura del repositorio

sitio/                          Fuente del sitio de validación (Cloudflare Pages)
├── index.md                    Portada y navegación
├── contexto/
│   └── playbook-tibot-v2-1.md  Playbook maestro (FUENTE DE VERDAD metodológica)
├── cursos/
│   └── index.md                Índice y seguimiento de los 7 cursos (FUENTE DE VERDAD de estados)
├── entregables/
│   ├── entregable-a-plantilla-generica.md   Plantilla maestra (FUENTE DE VERDAD de estructura)
│   └── entregable-a-curso-01.md             Curso 1 instanciado (APROBADO — referencia de detalle)
└── assets/estilo.css           Estilos (se embeben en cada HTML)

.kimi-code/                     ECC instalado (skills, agentes, reglas — ver sección 5)
*.md (raíz)                     Documentos fuente del proyecto (ley, visitas, planes, playbook original)
Entregable_A_Modulo1_Plan_de_Contenido_V2.docx   Entregable A original aprobado (fuente)

Reglas de oro del contenido:

  1. Nunca se reduce ni se omite un elemento de la plantilla genérica al instanciar un curso. Las 10 secciones 0–6 con todas sus subsecciones son obligatorias.
  2. Los {{PLACEHOLDERS}} de la plantilla se reemplazan con contenido real; las notas [GUÍA] NO se entregan al cliente (se eliminan al instanciar).
  3. No usar el símbolo § en ningún documento — usar la palabra “sección”.
  4. Nunca usar la palabra “cápsula”. Jerarquía oficial: Ruta → Módulo → Elemento.
  5. Nivel de inglés B1 en todo el contenido de entrega; español Colombia en la versión ES maestra.
  6. Cero fórmulas técnicas GTC-45 (ND/NE/NP/NC/NR) dirigidas al trabajador.
  7. El docx original y la Ley 2466/2025 son insumos de lectura; nunca se editan.

3. Ciclo de vida de un curso (entrega, seguimiento y aprobación)

Cada curso pasa por estos estados, registrados en sitio/cursos/index.md:

POR INSTANCIAR → EN REDACCIÓN → EN REVISIÓN INTERNA → EN VALIDACIÓN SURA → APROBADO → PUBLICADO
Estado Significado Quién mueve el estado
Por instanciar Solo existe la ficha breve en el índice —
En redacción Se está creando entregable-a-curso-NN.md desde la plantilla Agente / Neo MKT
En revisión interna Checklist v2.1 aplicado y completo; listo para ojos de SURA Agente / Neo MKT
En validación SURA Enviado a Gestora Metodológica + experto técnico Humano (Mauro)
Aprobado SURA aprobó; el documento queda como referencia Humano (Mauro)
Publicado HTML regenerado y desplegado en Cloudflare Pages Agente

Regla de seguimiento: toda sesión que trabaje un curso debe terminar con el estado actualizado en sitio/cursos/index.md y el sitio republicado si hubo cambios en documentos aprobados o en revisión.

4. Comandos operativos

Regenerar el sitio (tras editar cualquier .md de sitio/)

cd sitio
for f in index.md cursos/index.md entregables/*.md contexto/*.md; do
  pandoc "$f" -f markdown -t html5 -s --css "$PWD/assets/estilo.css" \
    --embed-resources --metadata lang=es -o "${f%.md}.html"
  sed -i '' -E 's/href="([^"#]+)\.md(#[^"]*)?"/href="\1.html\2"/g' "${f%.md}.html"
done

Desplegar a Cloudflare Pages

cd sitio
export CLOUDFLARE_ACCOUNT_ID=cf0b43be965e5a8cd3c901b4a40f622e   # cuenta hola@neomkt.co
npx wrangler pages deploy . --project-name=sura-curso-ingles --branch=main

Convertir un .docx nuevo a markdown

pandoc "<archivo>.docx" -t markdown -o <salida>.md --wrap=none

5. ECC (Everything Claude Code) — cómo se usa aquí

ECC 2.2.3 (MIT, https://github.com/affaan-m/ECC) está instalado en .kimi-code/ vía install.sh --profile minimal --target kimi. Provee agentes, skills y reglas generales de ingeniería.

Lo que SÍ aplica de ECC a este proyecto:

Lo que NO aplica literalmente: cobertura de tests 80% (este repositorio es contenido, no software); inmutabilidad de objetos; revisión de seguridad de código — salvo en los scripts de build/deploy.

Reinstalar/actualizar ECC: git clone --depth 1 https://github.com/affaan-m/ECC.git /tmp/ecc-repo && bash /tmp/ecc-repo/install.sh --profile minimal --target kimi desde la raíz del proyecto.

6. Skills propias del proyecto

Ubicadas en .kimi-code/skills/, siguen el formato ECC:

Skill Qué hace Cuándo usarla
curso-instanciar Crea el Entregable A de un curso nuevo desde la plantilla genérica, sin omitir secciones Al iniciar la redacción de cualquier curso 2–7
curso-validar Aplica el checklist de producción v2.1 completo a un curso y reporta hallazgos Antes de mover un curso a “En validación SURA”
sitio-publicar Regenera los HTML, despliega a Cloudflare Pages y verifica respuestas 200 Tras cualquier cambio en documentos de sitio/

7. App de gestión del proyecto (trazabilidad)

URL: https://sura-curso-ingles-2bj.pages.dev/gestion — es la puerta de entrada del sitio. Todos los documentos internos llevan un guard (sitio/assets/guard.html) que redirige a /gestion si no hay sesión.

Login (trazabilidad, NO seguridad): usuarios diana, marta, abigail, luis; la contraseña es el propio nombre de usuario. La sesión se guarda en localStorage (tibot-user) y se envía como header x-user en cada llamada a la API para registrar autoría. Todos los usuarios pueden hacer todo; los roles son informativos:

Usuario Rol
Diana Stakeholder cliente — aprueba cada elemento
Marta Líder del proyecto — valida cumplimiento y avances
Abigail Diseño — carga multimedias y entregables
Luis Desarrollador — descarga información y comparte embebidos

Jerarquía de la app: Definición (estática, sin datos de empresas piloto) → Entregables por curso (7 tarjetas con barra de progreso) → al entrar a un curso: Contenido base (URLs de materiales, elemento 0) + 10 elementos (los 10 momentos del playbook), cada uno con Multimedia y Embebido.

Modelo de datos (Cloudflare KV GESTION_KV, id 9c5b699c52c542d9861e4da1f8e1b075, clave única items):

API (Pages Functions en sitio/functions/api/):

Endpoint Método Acción
/api/items GET / POST Listar / añadir ítem
/api/items/{id} PATCH Cambiar aprobación (decision + evidencia + comentario opcional)
/api/items/{id}/comentarios GET / POST Listar / añadir comentario
/api/items/{id}/borrar DELETE Eliminar ítem

Todas requieren header x-user válido (401 si falta). El wrangler.toml de sitio/ declara el binding KV y compatibility_flags = ["nodejs_compat"] (obligatorio o el deploy de Functions falla).

Footer obligatorio en todas las páginas: “Neo Modular Key Tech | Proyecto Tibot Cursos Ingles en Colegio” (se inyecta con sitio/assets/footer.html en el build pandoc).

8. Decisiones vigentes (no re-decidir sin consultar)