docs(docs-portal): documentar platform-templates y la migracion real

Nueva seccion 'Templates' con la pagina principal de platform-templates
(diagrama Mermaid del flujo codigo->produccion, los 3 arquetipos, el
hallazgo real de Gitea sobre uses: cross-repo). Nuevo playbook de la
migracion de docs-portal/frontend/medusa, con los 3 bugs reales
encontrados en produccion (runAsNonRoot sin imagen no-root, capabilities
rompiendo el chown de nginx, runAsNonRoot sin runAsUser numerico) y los
2 gotchas de Kustomize (rename via patch, anular un campo heredado).

Nota: el directorio se llama docs/plantillas/ y no docs/templates/ --
MkDocs excluye silenciosamente cualquier carpeta llamada 'templates'
del build (confirmado en vivo con mkdocs build --strict, sin ningun
error/warning que lo explique, solo un INFO 'excluded from built site').

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT

workloads/docs-portal/docs/plantillas/platform-templates.md

@@ -0,0 +1,74 @@
+# platform-templates: dar de alta una app nueva
+
+!!! info "Qué problema resuelve"
+    Antes de este repo, cada app nueva significaba escribir un
+    Dockerfile, un pipeline con los 5 pasos de DevSecOps (Gitleaks,
+    Trivy, Semgrep, Syft, Cosign), y los manifiestos de Kubernetes —
+    todo desde cero, copiando y adaptando a mano lo que ya existía en
+    otra app. `platform-templates` es el repo donde ese trabajo repetido
+    quedó hecho una sola vez: copiás una plantilla, completás unos
+    pocos valores (nombre, imagen, puerto), y tenés el mismo nivel de
+    seguridad y buenas prácticas que ya tienen `ecommerce-frontend`,
+    `commerce-backend` y `docs-portal` — sin tener que redescubrirlas.
+
+Repo: [`devops/platform-templates`](https://gitea.cruzcloud.net/devops/platform-templates)
+
+## De "tengo código" a "está corriendo en producción"
+
+```mermaid
+flowchart TD
+    A["Tengo código<br/>(una app nueva)"] --> B["Elegir arquetipo:<br/>Next.js / API Node / sitio estático"]
+    B --> C["Copiar Dockerfile de<br/>platform-templates/dockerfiles/"]
+    C --> D["Agregar .gitea/workflows/build.yaml<br/>que llama al reusable workflow del arquetipo"]
+    D --> E["Copiar k8s-manifests/overlays-ejemplo/<br/>y ajustar nombre/imagen/puerto"]
+    E --> F["Generar par de llaves Cosign<br/>(cosign.pub commiteado, privada como secret)"]
+    F --> G["git push"]
+    G --> H["Pipeline: Gitleaks → build →<br/>Trivy → Semgrep → Syft → Cosign"]
+    H -->|"CRITICAL o firma inválida"| I["❌ Pipeline se detiene<br/>(nada llega al registry)"]
+    H -->|"todo pasa"| J["Imagen firmada<br/>sube al registry"]
+    J --> K["Pipeline actualiza el<br/>manifiesto GitOps automáticamente"]
+    K --> L["Argo CD detecta el cambio<br/>y sincroniza"]
+    L --> M["✅ App corriendo,<br/>con probes + resource limits +<br/>securityContext ya puestos"]
+
+    style A fill:#e8f4fd,stroke:#4a90d9
+    style M fill:#e6f7e6,stroke:#4ba84b
+    style I fill:#fde8e8,stroke:#d94a4a
+```
+
+Los pasos A→F son manuales (una vez, al dar de alta la app). De G en
+adelante es automático — cada `git push` a `main` repite H→M solo.
+
+## Los 3 arquetipos
+
+| Arquetipo | Para qué | Basado en |
+|---|---|---|
+| `archetype-nextjs-frontend` | Frontend Next.js con SSR (`output: standalone`) | `ecommerce-frontend` |
+| `archetype-node-api` | API backend Node/Express, sin UI | `commerce-backend` (Medusa) |
+| `archetype-static-site` | Sitio estático servido por nginx (MkDocs, Hugo, Astro) | `docs-portal` |
+
+Cada uno ya trae integrado el pipeline completo de DevSecOps — no hay
+que agregar los 5 pasos por separado, vienen adentro del reusable
+workflow.
+
+## Un detalle real de Gitea que no es como GitHub
+
+Armar este repo requirió confirmar en vivo (no asumir) cómo Gitea
+Actions maneja las referencias cross-repo, porque **no es 1:1 igual a
+GitHub Actions** en dos puntos concretos:
+
+1. Los reusable workflows (`workflow_call`) tienen que vivir en
+   `.gitea/workflows/` — no en cualquier carpeta.
+2. Cualquier `uses:` que apunte a otro repo de esta misma instancia
+   necesita la URL completa (`https://gitea.cruzcloud.net/owner/repo/...`)
+   — la forma corta de GitHub (`owner/repo/...`) se resuelve contra
+   **github.com** acá, no contra Gitea local.
+
+El detalle completo, con el error real del servidor que confirmó cada
+punto, está en el README del repo
+([`pipelines/archetype-nextjs-frontend/README.md`](https://gitea.cruzcloud.net/devops/platform-templates/src/branch/main/pipelines/archetype-nextjs-frontend/README.md)).
+
+## Ver también
+
+- [Migración de docs-portal/frontend/medusa a platform-templates](../playbooks/migracion-platform-templates-2026-08.md)
+  — qué cambió en las 3 apps que ya existían, y los bugs reales que
+  aparecieron aplicándolo en producción.