# 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

```bash
# 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:

```bash
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`):

```nginx
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;
    }
}
```

```bash
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
```