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)

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