trivasa-context — docs + proyectos curados de BI

Repo separado de la infraestructura de datos en sí: reúne código, queries, estado y contexto de negocio de los proyectos de BI de Trivasa en un solo lugar, servido como sitio de documentación estático en trivasa.ehas.uk. Cada proyecto lleva index.md (narrativa, decisiones — se edita con cuidado) y PROGRESS.md (estado vivo, sobreescribible libremente incluso por un agente autónomo sin supervisión) por separado, nunca fusionados.

Motor: ProperDocs, no mkdocs

Sirve con ProperDocs (properdocs build, config en properdocs.yml), no mkdocs. El cambio de motor viene de que MkDocs entró en crisis de mantenimiento en 2026 — el autor original retuvo el control de PyPI para publicar un “MkDocs 2.0” incompatible con plugins y temas existentes, y un ex-mantenedor forkeó la rama 1.x como ProperDocs, un reemplazo drop-in que redirige de forma transparente los imports mkdocs.*. El theme sigue siendo mkdocs-material y los plugins de siempre (mkdocs-gen-files, mkdocs-literate-nav) — solo cambió el motor de build.

mkdocs-material en sí no migró a ProperDocs: sigue dependiendo del mkdocs real y entra en mantenimiento final el 5 de noviembre de 2026, con Zensical anunciado como sucesor por el mismo equipo. Si Material deja de funcionar sobre ProperDocs en algún punto, la migración de theme a Zensical es una decisión aparte, independiente del cambio de motor de build ya hecho.

Hosting: Cloudflare Pages

host: none porque no vive en ninguna máquina de la flota — el build corre en la infraestructura de Cloudflare, no en ctunlinux ni ninguna VM. Cloudflare Pages está conectado directo al repo de GitHub (ehalso/trivasa-context, rama main, proyecto trivasa-context-wiki); cada git push a main dispara automáticamente pip install -r requirements-docs.txt --break-system-packages && properdocs build y publica site/ en ~15-20 segundos, sin depender de wrangler ni de ninguna sesión en particular. Deploy manual (fallback, si el auto-build falla o para probar un cambio sin pushear) sigue disponible desde una máquina con wrangler autenticado: properdocs build && npx wrangler pages deploy site --project-name=trivasa-context-wiki.

Se evaluó self-hosted (nginx + Cloudflare Tunnel, mismo patrón que Lightdash/Metabase/Perses) y se descartó a favor de Cloudflare Pages por simplicidad de despliegue, aceptando que el contenido queda en infraestructura de Cloudflare en vez de exclusivamente en ctunlinux. Ese plan self-hosted nunca se llegó a ejecutar.

Gotchas conocidos

• Primer auto-deploy vacío al conectar Git: al conectar el proyecto de Cloudflare Pages al repo, quedó sin build_command/destination_dir configurados. El primer push activó un deploy automático que no corrió ningún build y publicó un deployment vacío marcado como el más reciente, rompiendo la resolución de assets/ (el HTML raíz se servía desde caché de un deploy manual previo, pero CSS/JS devolvían 404 — mismatch entre el deployment “latest” real y lo cacheado). Se corrigió configurando build_config.build_command y build_config.destination_dir=site en el proyecto vía API. Si el sitio se ve sin estilos tras un push, revisar primero que el build_command siga configurado y que el stage build haya corrido con éxito (no saltado).
• Falso positivo de bloqueo en el dominio custom: https://trivasa.ehas.uk puede devolver un 403 “Web Filter Violation — Nuevos dominios registrados” con certificado no confiable (TLS interceptado), típico de un filtro de contenido/DNS de red (NextDNS, Cisco Umbrella, firewall corporativo) bloqueando por categoría “dominio recién registrado” (ehas.uk se registró el 2026-08-09). No es un problema de Cloudflare ni del deploy — https://trivasa-context-wiki.pages.dev sirve el mismo contenido sin problema; si el dominio custom no carga desde el navegador normal, revisar el resolver DNS/filtro de red usado antes de tocar la config de Cloudflare.

Conexiones a BD

Las credenciales de conexión se copian manualmente desde trivasa-bi-core/connections/ cuando un proyecto de este repo las necesita — no hay symlink ni dependencia automática entre los dos repos. Regla dura desde un incidente del 2026-08-29: una copia nunca trae el password embebido en el create_engine(...); se verifica con git grep -n "mssql+pymssql://.*:.*@" sobre el archivo antes de comitear. Si el repo destino no puede importar shared/db_credentials.py, la copia lee usuario/password de variable de entorno.

Véase también

• Infraestructura de datos Trivasa — el ERP fuente y el warehouse que documentan los proyectos curados en este repo.
• ctunlinux — servidor Docker de Trivasa BI — donde corre el resto del stack de BI; este sitio de docs es la excepción que vive en Cloudflare Pages, no ahí.