Merge branch 'docs/adr-0013-iniciativas-clientes-2026-09-21'

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

workloads/docs-portal/docs/decisiones/0012-practica-multicloud-gcp-azure.md

@@ -1,9 +1,13 @@
 # ADR 0012 — Práctica multi-cloud: GCP y Azure DevOps en paralelo al lab ZimaOS
 
-**Estado:** aceptada — Fase 1 (Google Workspace) en ejecución en esta
+**Estado:** aceptada — Fase 1 (Google Workspace) completa y verificada
-misma sesión; Fases 2-4 quedan documentadas como roadmap, explícitamente
+en vivo, con un giro real: el MCP self-hosted planeado
-no implementadas hasta que se pidan en una sesión futura.
+(`taylorwilsdon/google_workspace_mcp`) quedó abandonado por un límite
-**Fecha:** 2026-09-20
+real de esa librería (ver §Fase 1), reemplazado por los Connectors
+nativos de claude.ai. Fases 2-4 quedan documentadas como roadmap,
+explícitamente no implementadas hasta que se pidan en una sesión
+futura.
+**Fecha:** 2026-09-20 (Fase 1 cerrada 2026-09-21)
 
 ## Contexto
 
@@ -36,7 +40,7 @@ empujan a abrir una segunda línea de práctica en paralelo:
   arquitectónica real, diagramas Mermaid, cifras verificadas en vivo o
   contra fuente primaria (no contra un blog de terceros sin
   corroborar — ver el caso del supuesto MCP "oficial" de Google
-  Workspace en la [Fase 1](#fase-1-ejecutar-en-esta-sesion-google-workspace)).
+  Workspace en la [Fase 1](#fase-1-ejecutada-google-workspace-con-un-giro-real-en-la-implementacion)).
 
 ## Diagrama del lab actual (ZimaOS)
 
@@ -194,20 +198,60 @@ Todas documentadas acá; **solo la Fase 1 se ejecuta en esta sesión.**
 Las Fases 2-4 no se implementan sin pedido explícito en una sesión
 futura — quedan como roadmap, no como trabajo en curso.
 
-### Fase 1 (ejecutar en esta sesión) — Google Workspace
+### Fase 1 (ejecutada) — Google Workspace, con un giro real en la implementación
 
-MCP de Google Workspace vía cuenta personal, para las iniciativas ya
+**Objetivo cumplido — acceso real a Google Calendar desde Claude,
-en curso. Detalle de la investigación previa a implementar (qué MCP
+verificado en vivo — pero por un camino distinto al planeado
-usar, oficial vs comunitario) en la Parte 3 de esta conversación —
+originalmente.** Detalle de la investigación previa (qué MCP usar,
-resumen: **no existe un MCP oficial de Google Workspace** publicado
+oficial vs comunitario) — resumen: **no existe un MCP oficial de
-por Google (se verificó explícitamente buscando en los GitHub
+Google Workspace** publicado por Google (se verificó explícitamente
-`google`/`googleworkspace` oficiales — no aparece ninguno; un solo
+buscando en los GitHub `google`/`googleworkspace` oficiales — no
-blog de terceros afirma que "ya existe uno oficial" sin que ninguna
+aparece ninguno; un solo blog de terceros afirma que "ya existe uno
-otra fuente lo corrobore, así que se descarta esa afirmación por no
+oficial" sin que ninguna otra fuente lo corrobore, así que se descarta
-verificable). `taylorwilsdon/google_workspace_mcp` es la opción
+esa afirmación por no verificable). Se optó por
-comunitaria más completa y activamente mantenida (120+ herramientas,
+`taylorwilsdon/google_workspace_mcp` (comunitario, el más completo y
-OAuth 2.1, +2500 estrellas) — es la que se usa, etiquetada como
+activamente mantenido: 120+ herramientas, OAuth 2.1, +2500 estrellas)
-comunitaria, no oficial.
+como primer intento, self-hosted dentro de `tmux-host`.
+
+**Ese self-hosted quedó abandonado — límite real encontrado en la
+librería, no un error de configuración.** El servidor usa FastMCP's
+`GoogleProvider`/`OAuthProxy`, que construye el `redirect_uri`
+enviado a Google directamente desde su propio `base_url` — **no**
+desde la variable `GOOGLE_OAUTH_REDIRECT_URI` que el proyecto expone
+(esa variable solo valida entradas, no arma la salida real; hallazgo
+confirmado leyendo el código fuente instalado, no la documentación
+pública). Y `base_url` es la misma variable de la que depende por
+default `issuer_url`, que el SDK de MCP exige sea HTTPS salvo que sea
+literalmente `localhost`/`127.0.0.1` (chequeo hardcodeado en
+`mcp/server/auth/routes.py:validate_issuer_url`, sin variable de
+entorno que lo salte). Resultado: **no hay combinación de variables
+de entorno que satisfaga a la vez** "el navegador del usuario debe
+poder llegar al callback" (necesita un dominio real, no `localhost`)
+y "el issuer debe ser HTTPS o `localhost`" — `workspace-mcp` no
+expone `issuer_url` por separado de `base_url` en su capa de
+configuración (confirmado en `core/server.py`: solo pasa `base_url` a
+`GoogleProvider(...)`).
+
+**Decisión del usuario ante ese límite:** en vez de armar un proxy
+HTTPS con certificado autofirmado (infraestructura extra, fricción de
+certificado no confiable en cada uso) o parchear el paquete instalado
+a mano (frágil, se pierde en cualquier reinstalación), se usaron los
+**Connectors nativos de claude.ai** (Google Calendar, vía el
+directorio de conectores de la cuenta, fuera de Claude Code por
+completo) — mismo resultado práctico (Claude con acceso real al
+calendario personal), infraestructura cero de nuestro lado, sin
+tocar código de terceros. Contrapartida real: es una integración de
+cuenta de claude.ai, no un MCP configurado dentro del proyecto
+`platform-multicloud` — no aparece como herramienta en sesiones de
+Claude Code (`lab`/`cloud-practice`), solo en el chat normal de
+claude.ai.
+
+**Verificado en vivo:** pregunta real en claude.ai normal ("¿qué
+tengo en el calendario esta semana?") devolvió una respuesta correcta
+revisando 3 calendarios reales de la cuenta (principal, Familia,
+festivos de Colombia) vía la herramienta `Google Calendar: Lists
+calendar events`, con razonamiento correcto sobre qué cuenta como
+"esta semana" dado el día/hora real de la consulta.
 
 ### Fase 2 (documentar, no ejecutar) — Terraform aislado
 

workloads/docs-portal/docs/decisiones/0013-iniciativas-clientes.md

@@ -0,0 +1,122 @@
+# ADR 0013 — Iniciativas de clientes: Google Apps Script y AppSheet
+
+**Estado:** aceptada — **fase prioritaria**, precede la reanudación de
+las Fases 2-4 del [ADR 0012](0012-practica-multicloud-gcp-azure.md).
+Scaffold del repo en curso; primeras iniciativas reales se agregan
+sesión a sesión, a medida que se comparten.
+**Fecha:** 2026-09-21
+
+## Contexto
+
+Iniciativas propias de la empresa (no del lab), trabajadas con **cuenta
+personal de Google** — dos herramientas concretas: **Google Apps
+Script** (código, automatizaciones) y **Google AppSheet** (apps
+no-code sobre Sheets). Se abre como fase separada del ADR 0012 y con
+prioridad sobre él por decisión explícita: retomar las Fases 2-4 del
+lab (Terraform, Azure DevOps, GKE) espera a que esto avance primero.
+
+**Restricción dura, no negociable:** ningún repo ni documento de esta
+iniciativa contiene credenciales, datos ni información real de
+cliente. Apps Script versiona código (lógica), nunca datos. AppSheet
+no tiene export de código — solo se documenta desde afuera (tablas,
+columnas, expresiones, capturas), nunca se copian datos reales de
+ninguna hoja de cálculo al repo.
+
+## Opciones consideradas
+
+### Apps Script: MCP vs. `clasp`
+
+| Opción | A favor | En contra |
+|---|---|---|
+| MCP para Apps Script | Interacción conversacional directa | **No existe un MCP oficial de Google.** Se verificó explícitamente buscando — solo hay servidores comunitarios (`mohalmah/google-appscript-mcp-server`, `whichguy/gas_mcp`, entre otros), ninguno publicado por Google. Se descartan sin evaluar más a fondo: no hay necesidad de agregar una dependencia comunitaria no verificada cuando existe una CLI oficial que cubre el caso de uso completo. |
+| **`clasp`** (elegido) | CLI oficial de Google (`@google/clasp`), mantenida por el equipo de Apps Script, cubre push/pull/login/versiones/despliegues | Requiere login interactivo (OAuth) — mitigado: el login lo corre el dueño de la cuenta, nunca se comparte el código de autorización |
+
+### AppSheet: qué se puede versionar
+
+Se verificó contra la documentación oficial vigente (no se asumió):
+**AppSheet no expone ningún mecanismo de export de la definición de la
+app** (tablas virtuales, vistas, expresiones, automatizaciones) hacia
+un formato versionable con git. La única superficie exportable es la
+app en sí vía la consola de AppSheet, no un artefacto de código. Existe
+un addon de terceros ("App Script Saver") pero es específico de Apps
+Script, no de AppSheet, y no se evaluó como parte de esta decisión
+(mismo criterio que con los MCP: no se instala nada de terceros sin
+pasar primero por la verificación de publicador/permisos ya establecida
+en el lab).
+
+**Decisión sobre AppSheet:** no se intenta versionar la app —se
+documenta desde afuera. La documentación (markdown + capturas) es la
+única fuente versionada; la app real en la consola de AppSheet sigue
+siendo la fuente de verdad operativa, con el riesgo explícito de que
+la documentación quede desactualizada (ver Consecuencias).
+
+## Decisión
+
+Repo privado nuevo `client-initiatives` en Gitea (separado de
+`apps-registry`/`platform-infra`/`scripts`/`platform-multicloud` — ni
+lab GitOps ni práctica multi-cloud, es su propia categoría). Estructura:
+una carpeta por iniciativa bajo `apps-script/` (proyecto `clasp`
+completo, con su propio `.clasp.json`) o `appsheet/` (documentación +
+plantilla de estructura vacía). Mismo criterio de versionado semántico
+y modularidad que ya usa `docs-portal`.
+
+**Flujo Apps Script:** rama `fix/*` → diff mostrado → `merge --no-ff`
+a `main`. `clasp push` (subir el código a Google) es una confirmación
+explícita **aparte**, nunca agrupada con el merge a git — son dos
+sistemas de versionado distintos (git para el repo, Apps Script para
+las versiones desplegadas) y no deben confundirse.
+
+**Gitleaks:** se agrega al pipeline del repo nuevo. Nota real
+encontrada al planificar esto: Gitleaks hoy solo corre en
+`apps-registry` (3 workflows) — `platform-infra` y `scripts` no tienen
+Gitea Actions configurado en absoluto, no hay "los otros tres repos con
+Gitleaks" como se asumió al principio. Se replica el step exacto que
+ya usa `apps-registry` (Gitleaks v8.21.2, `--no-git --redact`, reporte
+JSON) por ser el único precedente real en el lab.
+
+## Fases
+
+### Fase A — Google Apps Script
+
+1. Scaffold del repo `client-initiatives` (estructura, Gitleaks,
+   convenciones documentadas).
+2. Login de `clasp` (`clasp login --no-localhost`) corrido por el
+   dueño de la cuenta — verificación posterior de que
+   `~/.clasprc.json` queda fuera de cualquier repo y con `chmod 600`.
+3. Primeras iniciativas: pendientes de compartir, se agregan una por
+   una bajo `apps-script/<slug>/` a medida que llegan.
+
+### Fase B — Google AppSheet
+
+1. Por cada app existente: documentar tablas, columnas y expresiones
+   en markdown, más capturas del estado actual, bajo
+   `appsheet/<slug>/`.
+2. Plantilla de estructura de datos vacía si aplica (schema, nunca
+   filas reales).
+3. Limitación dejada explícita en cada README de iniciativa: sin diff
+   automático posible entre esta doc y la app real.
+
+## En pausa mientras esta fase esté activa
+
+Por decisión explícita del usuario, prioridad sobre lo ya documentado
+en el ADR 0012 y el resto del lab:
+
+- **Swap de `tmux-host`** — no se corre en esta fase.
+- **[Fase 4 del ADR 0012](0012-practica-multicloud-gcp-azure.md#fase-4-documentar-no-ejecutar-gke-real-con-spot-auto-apagado)**
+  (GKE real con Spot + auto-apagado) — sigue solo documentada.
+- **Prueba del skill `frontend-design`** (pendiente desde la
+  instalación de plugins del 2026-09-20) — no se ejecuta.
+
+Tampoco se toca NPM, `cloudflared`, ni `lab-agent` durante esta fase.
+
+## Consecuencias
+
+- Se gana un espacio versionado y auditado (Gitleaks) para
+  automatizaciones reales de la empresa, sin mezclar nada con el lab
+  GitOps ni con la práctica multi-cloud.
+- Se acepta como deuda consciente que la documentación de AppSheet
+  puede desincronizarse de la app real — no hay forma técnica de
+  evitarlo, solo disciplina de actualizarla.
+- Revertir esta decisión implicaría: eliminar el repo
+  `client-initiatives` (las iniciativas seguirían existiendo en Google,
+  solo se perdería el historial versionado y la documentación externa).

workloads/docs-portal/mkdocs.yml

@@ -101,6 +101,7 @@ nav:
       - "0010 · Pago y envío reales": decisiones/0010-pago-envio-reales-y-storefront.md
       - "0011 · Ambiente de Staging": decisiones/0011-ambiente-staging.md
       - "0012 · Práctica multi-cloud GCP/Azure": decisiones/0012-practica-multicloud-gcp-azure.md
+      - "0013 · Iniciativas de clientes": decisiones/0013-iniciativas-clientes.md
       - Plantilla ADR: decisiones/plantilla-adr.md
   - Playbooks:
       - Crashloop Medusa: playbooks/incidente-crashloop-medusa.md

workloads/docs-portal/patches/deployment.yaml

@@ -25,7 +25,7 @@ spec:
         runAsNonRoot: false
       containers:
         - name: app
-          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.276
+          image: gitea.cruzcloud.net/devops/docs-portal:v1.0.279
           # El base saca TODAS las capabilities. Probado en vivo y
           # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE
           # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al