hbox-docs — sitio de documentación técnica del HBOX

Sitio MkDocs Material (español de México) + backend Flask: el centro de mando del proyecto Drogheda en https://drogheda.helgen.online. Pendientes (kanban), ruta a producción, actas por unidad, inventario, sitios, bitácora y los documentos que se publican (procedimientos, auditorías, ECOs, manuales). Vive como submódulo de Drogheda, igual que el repo de KiCad.

Regla: si no está en el sitio, no pasó. Cada tarea termina aquí: su pendiente, su documento y, si algo estorbó, una mejora. Para Claude: CLAUDE.md (dónde vive cada cosa y cómo se cambia).

Flujo de trabajo

# 1. actualizar el contenido desde Drogheda (la lista curada vive en el script)
./scripts/sync-docs.sh

# 2. ver el sitio en local
pip install mkdocs-material        # una sola vez
mkdocs serve                        # http://127.0.0.1:8000

# 3. commit + push de este repo (y bump del submódulo en Drogheda)

# 4. publicar al servidor
./scripts/deploy.sh                 # leo@git.helgen.online:/srv/projects/drogheda/hbox-docs/site (puerto 22)
                                    # también copia el backend y baja la foto del tablero a _estado/

# 5. lotes de Claude para el tablero (si hay uno nuevo en backend/lotes/)
./scripts/tablero.sh revisar        # qué cambiaría cada uno; no escribe nada
./scripts/tablero.sh aplicar        # los aplica y baja la foto nueva

Política de publicación: solo se publica lo que está en la lista de scripts/sync-docs.sh. Se publica lo que sirve al técnico o al estado de ingeniería (procedimientos, actas, manuales, ECOs, auditorías de diseño y layout, guías de layout); nada de finanzas, fundraising ni briefs comerciales. Para agregar un documento al sitio se agrega a esa lista (y con eso queda auditado en git). Lo superado no se borra: baja a «Referencia e histórico» con un banner que dice qué lo sustituye.

Configuración del servidor (una sola vez)

En el servidor (git.helgen.online u otro), como root:

mkdir -p /srv/projects/drogheda/hbox-docs/site
chown -R leo:leo /srv/projects/drogheda/hbox-docs           # el usuario con el que hace rsync deploy.sh

# usuarios para los técnicos (HTTP Basic)
apt install -y apache2-utils
htpasswd -c /etc/nginx/hbox-docs.htpasswd luz
htpasswd    /etc/nginx/hbox-docs.htpasswd leo

Bloque de nginx (por ejemplo /etc/nginx/sites-available/hbox-docs, con el certificado que ya tenga el servidor o uno nuevo de certbot para drogheda.helgen.online):

server {
    listen 443 ssl;
    server_name drogheda.helgen.online;

    # ssl_certificate     ... ;   # certbot --nginx -d drogheda.helgen.online
    # ssl_certificate_key ... ;

    root /srv/projects/drogheda/hbox-docs/site;
    index index.html;

    auth_basic           "Helgen HBOX docs";
    auth_basic_user_file /etc/nginx/hbox-docs.htpasswd;

    location / {
        try_files $uri $uri/ =404;
    }
}

ln -s /etc/nginx/sites-available/hbox-docs /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Los técnicos entran a https://drogheda.helgen.online con su usuario y contraseña. Alternativa sin subdominio: servirlo como location /hbox/ dentro del server block existente, con el mismo auth_basic.

Estructura

CLAUDE.md             reglas para Claude: dónde vive cada cosa del sitio y cómo se cambia
mkdocs.yml            configuración del sitio (nav, tema, español, hooks)
docs/                 contenido publicado (lo sincronizado por sync-docs.sh + páginas propias del sitio)
docs/datos/proyecto.json  ruta a producción, tarjeta por versión, fechas y sitios de la página de inicio
overrides/, hooks/    plantillas del tema Helgen y ganchos de MkDocs (documentos recientes, versión de CSS/JS)
backend/              app.py (actas, pendientes, inventario, sitios, equipo, enfoque, actividad) + servicio
backend/tablero.py    foto del tablero y lotes de Claude (lo llama scripts/tablero.sh)
backend/lotes/        lotes de cambios al tablero, uno por tarea terminada (formato en su README)
scripts/sync-docs.sh  lista curada Drogheda → docs/ (la política de publicación)
scripts/deploy.sh     mkdocs build --strict + rsync del sitio y del backend + foto del tablero
scripts/tablero.sh    foto / revisar / aplicar desde la Mac
_estado/              foto del tablero (tablero.json, tablero.md); fuera de git