# CruzCloud Lab — Plataforma GitOps

> **TODO (fase 2+):** reescribir esta portada con la narrativa final. Por
> ahora describe el propósito y la audiencia para que la navegación y el
> `nav:` de `mkdocs.yml` tengan un punto de entrada real.

Este sitio documenta un laboratorio personal de **Platform Engineering**:
un cluster Kubernetes (k3d) corriendo sobre un NAS (ZimaOS), gobernado
100% por GitOps (Gitea + Argo CD), sirviendo una tienda de e-commerce real
(Medusa + Next.js) como carga de trabajo de referencia.

No es un tutorial genérico ni una demo de juguete: cada decisión, cada
incidente y cada diagrama de este sitio corresponde a un sistema que
corre de verdad, con los commits, logs y causas raíz reales que lo
probaron.

## Para quién es este sitio

Este portal sirve a tres audiencias distintas, y está organizado para
que cada una pueda entrar por su propia puerta:

- **Reclutadores / pares de Platform Engineering** — ver
  [`decisiones/`](decisiones/0001-por-que-k3d.md) para el criterio
  arquitectónico detrás del stack, y [`playbooks/`](playbooks/incidente-crashloop-medusa.md)
  para diagnóstico real de incidentes (no solo "lo arreglé").
- **Alguien evaluando este patrón para un caso de negocio real**
  (tienda desplegable desde ZimaOS) — ver
  [`arquitectura/`](arquitectura/vision-general.md) para el flujo
  completo y su costo/complejidad real.
- **Estudiantes empezando con GitOps/Kubernetes** (incluye a mi hijo,
  7mo semestre de Ingeniería de Sistemas) — empezar por
  [`guia-estudiante/`](guia-estudiante/README.md), pensada para alguien
  que nunca ha visto estos conceptos.

## Mapa del sitio

| Sección | Qué encontrarás |
|---|---|
| [Arquitectura](arquitectura/vision-general.md) | Diagramas Mermaid del flujo completo, red/exposición, flujo GitOps, glosario |
| [Decisiones (ADRs)](decisiones/0001-por-que-k3d.md) | Por qué k3d, por qué Argo CD, por qué HTTP/2 sobre QUIC, etc. |
| [Playbooks](playbooks/incidente-crashloop-medusa.md) | Incidentes reales, diagnóstico paso a paso, causa raíz, fix |
| [Aprendizajes](aprendizajes/notas-sueltas.md) | Qué haría distinto, gotchas de Medusa v2 |
| [Guía del estudiante](guia-estudiante/README.md) | Ruta de aprendizaje desde cero |

## Estado de este sitio

Este portal se mantiene vivo junto con el lab — cada página muestra su
última fecha de modificación real (`git-revision-date-localized`). Si
una página dice "TODO", es contenido pendiente de una fase posterior,
no una promesa incumplida: la estructura completa se construyó primero
a propósito, para que el contenido se llene sección por sección con el
mismo criterio que el resto del lab.

Desde este commit, el sitio se construye y publica solo: cada push a
`main` que toca `docs/` o `mkdocs.yml` dispara
`.gitea/workflows/deploy-docs.yaml`, que hace `mkdocs build --strict`,
publica la imagen en el Registry de Gitea y Argo CD sincroniza el
Deployment en el cluster (namespace `docs-portal`). Este párrafo es la
prueba: si lo estás leyendo servido desde el pod real, el pipeline
funcionó de punta a punta.