docs(docs-portal): Fase 2 - contenido narrativo real de arquitectura/decisiones/aprendizajes

Reemplaza los placeholders "TODO (fase 2+)" por narrativa completa,
grounded en el codigo/manifiestos/incidentes reales del lab (no
generico):

- ADR 0001 (por que k3d) y ADR 0002 (por que Argo CD): pasan de
  template vacio a Contexto/Opciones/Decision/Consecuencias reales,
  apoyados en known-issues.md (blackhole MTU) y en la config real de
  ecommerce-app.yaml.
- vision-general.md: el "por que" de cada frontera de confianza del
  diagrama.
- gitops-flujo.md: ejemplo real con hashes de commit (Fase 3b de
  ADR 0006, v1.0.171 -> hotfix -> v1.0.172), selfHeal explicado con el
  syncPolicy real del repo.
- red-y-exposicion.md: diagrama de terminacion TLS real, por que todo
  va "proxied", patron de diagnostico "interno sano, publico roto".
- glosario.md: 9 terminos nuevos, cada uno con ejemplo real y
  verificado del repo (Namespace, ResourceQuota, LimitRange,
  NetworkPolicy, Deployment, Service, Ingress, StatefulSet, Init
  container).
- notas-sueltas.md: MinIO/S3, limites reales del subscriber
  revalidate-storefront.ts, que se automatizaria desde cero.

Validado con `docker build --target build` (mkdocs build --strict,
mismo paso que el pipeline real) -- cero links rotos, cero warnings.

workloads/docs-portal/docs/arquitectura/gitops-flujo.md

@@ -1,9 +1,9 @@
 # Del commit al despliegue: flujo GitOps
 
-> **TODO (fase 2+):** narrar cada paso con ejemplos reales tomados de
-> `.gitea/workflows/build-medusa.yaml` y `build.yaml`. El diagrama de
-> secuencia de abajo refleja el pipeline real (build → push imagen →
-> promoción segura → commit del tag → sync de Argo CD).
+El diagrama de abajo refleja el pipeline real (build → push imagen →
+promoción segura → commit del tag → sync de Argo CD). Después del
+diagrama hay un ejemplo con hashes de commit reales, tomado de un
+cambio real hecho sobre este mismo repo.
 
 ## Secuencia: un commit hasta quedar corriendo en el cluster
 
@@ -42,9 +42,53 @@ sequenceDiagram
   evita que un pipeline viejo sobreescriba el tag con una versión
   anterior si hubo un push más reciente mientras corría.
 
-## TODO
+## Ejemplo real: un commit de principio a fin
 
-- Ejemplo real con hashes de commit (tomar del historial de
-  `apps-registry`).
-- Explicar `syncPolicy.automated.selfHeal` con un caso concreto (qué
-  pasa si alguien hace `kubectl edit` a mano).
+Fase 3b del ADR 0006 (facetas del sidebar del catálogo, ver
+`decisiones/0006-motor-busqueda-facetas.md`) recorrió el flujo
+completo dos veces seguidas el mismo día:
+
+| Paso | Commit / evento real |
+|---|---|
+| Feature | `83d448b` — `feat(ecommerce): facetas reales de Meilisearch en el sidebar del catalogo`, en `fix/adr0006-etapa2-fase3b-facetas-sidebar` |
+| Merge a `main` | `6b5450f` |
+| CI build+push | Gitea Actions task 258, imagen `gitea.cruzcloud.net/devops/ecommerce-frontend` |
+| Release commit (CD) | `951682a` — `chore: release v1.0.171 [skip ci]`, bump automático del tag en `frontend/patches/deployment.yaml` |
+| Sync de Argo CD | dos ciclos distintos: primero sincronizó contra `6b5450f` (el merge, todavía con el tag viejo), y en el ciclo siguiente detectó `951682a` y aplicó el tag nuevo |
+| Rollout | `frontend-deploy` con 2/2 réplicas en `v1.0.171` |
+
+El gate en vivo contra ese mismo cambio encontró un bug real
+(`estimatedTotalHits` en 0 con `limit=0` en Meilisearch) — el fix
+repitió el mismo ciclo completo: `884dbd1` → merge `ba3e6c7` → release
+`v1.0.172` → sync → rollout. Dos vueltas completas del diagrama de
+arriba en la misma sesión, cada una verificada contra el endpoint real
+antes de darla por cerrada.
+
+**Detalle no obvio:** Argo CD sincroniza el *merge commit* primero
+(todavía con la imagen vieja, porque el bump de tag es un commit
+*posterior* que hace el propio pipeline) y recién en un segundo ciclo
+de poll detecta el commit de release. Son dos sincronizaciones
+distintas, no una sola — hay que esperar ambas antes de asumir que el
+pod nuevo está corriendo.
+
+## `selfHeal`, con la configuración real
+
+Todas las Applications de este repo comparten el mismo `syncPolicy`
+(`apps/ecommerce-app.yaml`):
+
+```yaml
+syncPolicy:
+  automated:
+    prune: true
+    selfHeal: true
+```
+
+Con `selfHeal: true`, si alguien corre `kubectl scale deployment
+frontend-deploy --replicas=1` directo contra el cluster (saltándose
+Git por completo), Argo CD no se queda en mostrar `OutOfSync` — en el
+siguiente ciclo de reconciliación vuelve a aplicar el manifiesto tal
+como está en `main` y el Deployment queda otra vez en las réplicas
+declaradas ahí. El cambio manual no se pierde silenciosamente: queda
+un instante como drift visible en la UI de Argo CD, pero nunca se
+vuelve el estado final. La única forma de que ese cambio persista es
+que exista en Git — lo mismo que describe [ADR 0002](../decisiones/0002-por-que-argocd-vs-manual.md).