hbox-docs/CLAUDE.md

hbox-docs — the command centre (drogheda.helgen.online)

Mantra: «Si no está en el sitio, no pasó.» If it isn't on drogheda.helgen.online, it didn't happen. The rule and the closing loop live in the master index (../CLAUDE.md, section ★ Command centre). This file is the mechanics: where each piece of the site lives and how to change it.

This repo (submodule of Drogheda) is the internal site: MkDocs Material in Mexican Spanish + a Flask backend (backend/app.py, gunicorn actas-hbox on 127.0.0.1:8081, nginx basic auth in front). Leo, Adriana, Michelle, Jesús and the field technicians work from it; Claude closes every task on it too.

Read first (start of every task)

1. _estado/tablero.md — the board snapshot (pendientes by person, overdue, last 14 days of activity, lotes applied). Taken by ./scripts/tablero.sh foto and by every ./scripts/deploy.sh. If it is missing or older than a day, ask Leo for a fresh ./scripts/tablero.sh foto before writing a lote.
2. docs/datos/proyecto.json — Ruta a producción, per-version cards, hitos, fase.
3. docs/hardware/index.md — state of every board with its documents.
4. ../CLAUDE.md §0 — engineering status.

Where each thing lives

On the site	Source	Who edits	How
Pendientes (kanban, «Por persona», Ingeniería/Producción views)	server /srv/projects/drogheda/tareas	everyone in the UI (deleting: admins + TAREAS_BORRAN, by default Adriana and Gibran; soft delete to tareas/_borrados/); Claude only through lotes	backend/lotes/AAAA-MM-DD_tema.json → Leo runs ./scripts/tablero.sh revisar then aplicar. Format and rules: backend/lotes/README.md
Actividad (home, Bitácora)	automatic: task history + actas	—	nothing to write; lotes show up as «Claude terminó / creó / comentó en …»
Semáforo (home, 22-oct) and per-site color	docs/datos/proyecto.json → semaforo (color rojo/amarillo/verde, titulo, texto, causas with bold/links, destraba, actualizado) + estado/nota/meta on each sitios[] item and on oficina	Leo decides the color; Claude or Leo edit	update it in every crisis or junta hand-off; map pins and the site list link to /tableros/pendientes/?sitio=<id>
Sitio of each task (22-oct)	task field sitios = list of icave · timsa · eit · lzc · qro (no field = qro, Querétaro: fabricación e ingeniería)	everyone in the UI (site checkboxes); Claude through lotes ("sitios": ["eit"])	filter ?sitio=eit,timsa, view «Por sitio» (?vista=sitio); GET /api/tareas advertises the list; a lote with sitios needs the restarted backend
Juntas (standup + quick wins, 22-oct)	docs/tableros/juntas.md (process, agenda, cadence, register)	Claude or Leo	Leo records with Gemini → Claude turns the transcript into a lote → Leo applies; add a row to «Registro» each time; tags crisis, quick-win; track gestion
Enfoque de la semana (home)	server /api/hoy (enfoque.json)	Leo and Adriana only	Claude proposes the text in the hand-off; enfoque_inicial in proyecto.json shows only while nobody has written one
Ruta a producción, version cards, fase, pedido, próximas fechas, map pins	docs/datos/proyecto.json	Claude or Leo	edit by hand (keep the one-array-per-line format); step states hecho · ahora · bloqueado · falta, card tone hecho · ahora · aviso · bloqueado; bump actualizado
Instalaciones (per-site installation board, 22-oct)	docs/tableros/instalaciones.md + .js/.css; data: field actas via GET /api/instalaciones (backend/instalaciones.py, hooked at the end of app.py)	automatic	stages envío → recepción → instalación → prueba en sitio (acta prueba-sitio; only a passed test counts for the 1–2 per-site goal) → en operación (7 days after the test, no failure) + «con falla»; colour, nota and meta per site from proyecto.json; forms accept ?serie=&sitio=&<clave>= prefill (acta.js)
Últimas decisiones (Ingeniería)	docs/tableros/ingenieria.md	Claude or Leo	new <li><b>DD-mmm (hora)</b> — …</li> at the top, with the decision number (D-xx-n) and links
Bitácora → Documentos por fecha	docs/bitacora.md	Claude or Leo	newest first under the month: **DD oct** + : [Title](path.md#anchor): what it decides or changes
Documentos recientes (home)	automatic from date: front matter (hooks/documentos.py)	—	give every new page a date:; pages under «Historia» are left out
Engineering docs (audits, ECOs, passes, procedures)	../NN-…/AAAA-MM-DD_Drogheda_…md	Claude or Leo	write the source in the Drogheda folder, add it to the MAP in scripts/sync-docs.sh, run the sync. Never edit the copy in docs/
Navigation	mkdocs.yml	Claude or Leo	current audits/passes under Tarjetas y hardware → Auditorías y pasadas; superseded ones to Historia → Tarjetas superadas with a banner saying what replaces them
Section index pages	docs/index.md, docs/hardware/index.md, docs/produccion/, docs/taller/, docs/campo/	Claude or Leo	site-only (not in the MAP); hardware/index.md carries the per-board state and the 21-oct style warning box
Figures	docs/<section>/img/AAAA-MM-DD_Drogheda_…png	Claude	always on the site, embedded in the doc they explain
Card images (white copper)	docs/img/tarjetas/*.webp	Claude	scripts/tarjetas/ (see its README)
Engineer's rules	docs/guia-ingeniero.md	Leo / Claude	«El sitio es el centro de mando» is the team-facing version of the closing loop
Deploy notes	DESPLIEGUE.md	Claude	one dated section per change that needs server steps

Rules when editing the site

• Mexican Spanish for every word the team reads (pages, notes in lotes, task titles).
• mkdocs build --strict must pass (warnings fail). Build a copy first if another session may be editing.
• Another session may be editing hbox-docs at the same time. Check the file's mtime/hash right before writing; never overwrite a file that changed since you read it — merge instead.
• No secrets: the 4G/NTRIP parameter file (caster, APN) never goes on the site, only its template.
• Never run git in the mounted folder (stale .git/index.lock); give Leo the commands. The mount can't delete: move leftovers to _to_delete/ (gitignored).
• .css/.js links get ?v=<hash> automatically (hooks/versiones.py); no manual cache busting.
• If backend/app.py changes, the hand-off must say sudo systemctl restart actas-hbox.
• UI changes: check with the local proxy (site + real backend) in light, dark and phone width.

Hand-off block (end of every task that touched the site)

cd ~/Documents/Claude/Projects/Drogheda/hbox-docs
./scripts/sync-docs.sh                    # only if a synced doc changed
mkdocs build --strict
git add -A && git commit -m "…" && git push
cd .. && git add hbox-docs && git commit -m "hbox-docs: …" && git push    # bump the submodule
cd hbox-docs && ./scripts/deploy.sh       # site + backend; also refreshes _estado/
./scripts/tablero.sh revisar              # if there is a new lote: read what it will do
./scripts/tablero.sh aplicar
# ssh leo@git.helgen.online 'sudo systemctl restart actas-hbox'   ← only if app.py changed