ozali 0.4.1 → 0.6.0

package/cli/lib/detect.mjs

@@ -1,7 +1,7 @@
 // detect.mjs — detección read-only del entorno del proyecto destino.
 import fs from "node:fs";
 import path from "node:path";
-import { exists, which, gitInfo, nodeMajor, HOME } from "./util.mjs";
+import { exists, which, gitInfo, nodeMajor, HOME, readJSON } from "./util.mjs";
 
 /** Variante de fuente de verdad: {found, doc, dir, variant} */
 export function detectSourceOfTruth(cwd) {
@@ -47,6 +47,13 @@ export function detectEngram() {
   return { available: !!bin, bin: bin || null };
 }
 
+/** Metadatos compartibles de Engram Cloud del proyecto (sin secretos). */
+export function detectCloud(cwd) {
+  const metaPath = path.join(cwd, ".ozali", "cloud.json");
+  const meta = readJSON(metaPath);
+  return { present: !!meta, path: metaPath, meta: meta || null };
+}
+
 /**
  * Capacidades de testing (heurística read-only). Devuelve runner(s), comando y
  * un conteo aproximado de archivos de prueba. NO resuelve strict_tdd (eso lo
@@ -98,6 +105,7 @@ export function detectAll(cwd) {
     agents: detectAgents(cwd),
     skill: detectInstalledSkill(cwd),
     engram: detectEngram(),
+    cloud: detectCloud(cwd),
     testing: detectTesting(cwd),
   };
 }

package/cli/lib/util.mjs

@@ -10,6 +10,7 @@ import { execFileSync } from "node:child_process";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PKG_ROOT = path.resolve(HERE, "..", "..");
 export const SKILL_SRC = path.join(PKG_ROOT, "skill");
+export const COMMIT_SKILL_SRC = path.join(PKG_ROOT, "skill-commit");
 export const TEMPLATES_SRC = path.join(PKG_ROOT, "templates");
 
 export function pkgVersion() {
@@ -21,6 +22,21 @@ export function pkgVersion() {
   }
 }
 
+/**
+ * Nombre del asset de release de Engram para un SO/arch/versión dados.
+ * Convención oficial: engram_<version>_<os>_<arch>.<ext> (.tar.gz en linux/darwin, .zip en windows).
+ * Devuelve null si el SO o la arquitectura no están soportados. Función pura (sin red).
+ */
+export function engramAssetName(platform, arch, version) {
+  const osMap = { darwin: "darwin", linux: "linux", win32: "windows" };
+  const archMap = { x64: "amd64", arm64: "arm64" };
+  const os = osMap[platform];
+  const a = archMap[arch];
+  if (!os || !a) return null;
+  const ext = platform === "win32" ? "zip" : "tar.gz";
+  return `engram_${version}_${os}_${a}.${ext}`;
+}
+
 // ---- colores (sin deps; respeta NO_COLOR y no-TTY) --------------------------
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
@@ -70,6 +86,14 @@ export function writeJSON(p, obj) {
   fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n");
 }
 
+/** Abre una URL en el navegador por defecto. Devuelve true si pudo lanzar el comando. */
+export function openURL(url) {
+  if (!url) return false;
+  if (process.platform === "darwin") return spawnCmd("open", [url]) === 0;
+  if (process.platform === "win32") return spawnCmd("cmd", ["/c", "start", "", url]) === 0;
+  return spawnCmd("xdg-open", [url]) === 0;
+}
+
 // ---- ejecución de comandos (read-only / git) --------------------------------
 /** Ejecuta un binario y devuelve stdout recortado, o null si falla. */
 export function tryExec(cmd, args = [], opts = {}) {

package/cli/test/smoke.test.mjs

@@ -6,6 +6,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { engramAssetName } from "../lib/util.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const BIN = path.resolve(HERE, "..", "bin", "ozali.mjs");
@@ -132,6 +133,80 @@ test("update agrega ozali-jarvis en un repo que no lo tenía", () => {
   }
 });
 
+function initRepo(dir) {
+  run(["init", "--yes", "--no-engram", "--no-trust", "--no-jarvis", "--agent", "claude-code", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
+}
+
+function writeCdkStub(dir, body) {
+  const f = path.join(dir, ".claude", "skills", "cdk", "SKILL.md");
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, body);
+  return f;
+}
+
+test("init instala la skill ozali-commit", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    assert.ok(fs.existsSync(path.join(dir, ".claude", "skills", "ozali-commit", "SKILL.md")), "ozali-commit SKILL.md instalada");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor marca cdk al día cuando la versión de contrato coincide", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    writeCdkStub(dir, "---\nname: cdk\ncdk_contract_version: 1\n---\n# cdk\n");
+    const { stdout } = run(["doctor"], dir, true);
+    assert.match(stdout, /Skill cdk/, "doctor reporta la fila Skill cdk");
+    assert.match(stdout, /contrato v1 \(al día\)/, "doctor marca cdk al día");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor marca cdk desactualizada si referencia copsis-commit", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    writeCdkStub(dir, "---\nname: cdk\ncdk_contract_version: 1\n---\n# cdk\ninvoca copsis-commit al cierre del hito\n");
+    const { stdout } = run(["doctor"], dir, true);
+    assert.match(stdout, /copsis-commit/, "doctor avisa de copsis-commit");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("update avisa y da pasos manuales si cdk está desactualizada (legado)", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    writeCdkStub(dir, "---\nname: cdk\n---\n# cdk legado que invoca copsis-commit\n");
+    const { stdout } = run(["update"], dir);
+    assert.match(stdout, /cdk desactualizada/, "update avisa de cdk desactualizada");
+    assert.match(stdout, /copsis-commit/, "update menciona la migración de copsis-commit");
+    assert.match(stdout, /skill ozali|pre-flight|migra/i, "update da pasos manuales");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("update también instala ozali-commit en repos previos", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    // Simula instalación previa sin ozali-commit.
+    fs.rmSync(path.join(dir, ".claude", "skills", "ozali-commit"), { recursive: true, force: true });
+    assert.ok(!fs.existsSync(path.join(dir, ".claude", "skills", "ozali-commit", "SKILL.md")), "precondición: sin ozali-commit");
+    run(["update"], dir);
+    assert.ok(fs.existsSync(path.join(dir, ".claude", "skills", "ozali-commit", "SKILL.md")), "update instala ozali-commit");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("init --dry-run no escribe nada", () => {
   const dir = tmpProject();
   try {
@@ -150,3 +225,52 @@ test("el paquete NO tiene dependencias ni lifecycle scripts (seguridad)", () =>
     assert.ok(!(pkg.scripts && pkg.scripts[s]), `sin script de ciclo de vida: ${s}`);
   }
 });
+
+test("--help menciona el comando cloud", () => {
+  const { stdout } = run(["--help"]);
+  assert.match(stdout, /cloud/, "help debe mencionar cloud");
+  assert.match(stdout, /--dashboard/, "help debe mencionar --dashboard");
+  assert.match(stdout, /--conflicts/, "help debe mencionar --conflicts");
+});
+
+test("cloud status imprime cabecera y no rompe", () => {
+  const dir = tmpProject();
+  try {
+    const { code, stdout } = run(["cloud", "status"], dir, true);
+    assert.match(stdout, /ozali cloud status/, "debe imprimir cabecera de cloud status");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("cloud con subcomando desconocido sale con código 1", () => {
+  const dir = tmpProject();
+  try {
+    const { code, stdout } = run(["cloud", "frobnicate"], dir, true);
+    assert.equal(code, 1, "debe salir con código 1");
+    assert.match(stdout, /Subcomando desconocido/, "debe indicar subcomando desconocido");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test(".gitignore del repo destino permite .ozali/cloud.json (commiteable)", () => {
+  const dir = tmpProject();
+  try {
+    run(["init", "--yes", "--no-engram", "--no-trust", "--no-jarvis", "--agent", "claude-code", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
+    const gi = fs.readFileSync(path.join(dir, ".gitignore"), "utf8");
+    assert.match(gi, /\.ozali\/\*/, "debe ignorar .ozali/*");
+    assert.match(gi, /!\.ozali\/cloud\.json/, "debe permitir .ozali/cloud.json");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("engramAssetName respeta la convención de release por SO/arch", () => {
+  assert.equal(engramAssetName("linux", "x64", "1.17.0"), "engram_1.17.0_linux_amd64.tar.gz");
+  assert.equal(engramAssetName("linux", "arm64", "1.17.0"), "engram_1.17.0_linux_arm64.tar.gz");
+  assert.equal(engramAssetName("darwin", "arm64", "1.17.0"), "engram_1.17.0_darwin_arm64.tar.gz");
+  assert.equal(engramAssetName("win32", "x64", "1.17.0"), "engram_1.17.0_windows_amd64.zip");
+  assert.equal(engramAssetName("linux", "ia32", "1.17.0"), null, "arch no soportada → null");
+  assert.equal(engramAssetName("freebsd", "x64", "1.17.0"), null, "SO no soportado → null");
+});

package/docs/deploy-cloud-gcloud.md

@@ -0,0 +1,149 @@
+# Desplegar Engram Cloud en Google Cloud
+
+← [README](../README.md)
+
+Dos opciones para desplegar el **servidor de Engram Cloud** en Google Cloud Platform, según el
+perfil de carga y mantenimiento que prefieras.
+
+## Opción A: Cloud Run + Cloud SQL (serverless, managed)
+
+La opción más **hands-off**: Postgres gestionado por Google, Engram en Cloud Run (serverless,
+escala a cero). Ideal si no quieres mantener VMs.
+
+### Componentes
+
+| Servicio | Qué hace | Coste aprox. |
+|---|---|---|
+| Cloud SQL (Postgres 16) | Base de datos gestionada | ~$15-30/mes (db-f1-micro) |
+| Cloud Run | Ejecuta el servidor Engram | $0 por inactivo + por uso |
+| Secret Manager | Guarda el token y DB URL | gratis hasta 6 secretos |
+| Artifact Registry | Imagen Docker de Engram | gratis hasta 0.5 GB |
+
+### Pasos
+
+1. **Crear instancia de Cloud SQL:**
+   ```bash
+   gcloud sql instances create engram-db \
+     --database-version=POSTGRES_16 \
+     --tier=db-f1-micro \
+     --region=us-central1 \
+     --root-password=$(openssl rand -hex 32)
+   ```
+
+2. **Crear base de datos y usuario:**
+   ```bash
+   gcloud sql databases create engram --instance=engram-db
+   gcloud sql users create engram --instance=engram-db --password=$(openssl rand -hex 16)
+   ```
+
+3. **Subir la imagen a Artifact Registry:**
+   ```bash
+   gcloud artifacts repositories create engram --repository-format=docker --location=us-central1
+   docker pull ghcr.io/gentleman-programming/engram:latest
+   docker tag ghcr.io/gentleman-programming/engram:latest \
+     us-central1-docker.pkg.dev/$PROJECT_ID/engram/cloud:latest
+   docker push us-central1-docker.pkg.dev/$PROJECT_ID/engram/cloud:latest
+   ```
+
+4. **Crear secretos en Secret Manager:**
+   ```bash
+   echo -n "postgres://engram:...@/engram?cloudsql=/cloudsql/$PROJECT_ID:us-central1:engram-db" \
+     | gcloud secrets create ENGRAM_CLOUD_DATABASE_URL --data-file=-
+   echo -n "$(openssl rand -hex 32)" \
+     | gcloud secrets create ENGRAM_CLOUD_TOKEN --data-file=-
+   ```
+
+5. **Desplegar en Cloud Run:**
+   ```bash
+   gcloud run deploy engram-cloud \
+     --image=us-central1-docker.pkg.dev/$PROJECT_ID/engram/cloud:latest \
+     --region=us-central1 \
+     --port=18080 \
+     --no-allow-unauthenticated \
+     --add-cloudsql-instances=$PROJECT_ID:us-central1:engram-db \
+     --set-secrets="ENGRAM_CLOUD_DATABASE_URL=ENGRAM_CLOUD_DATABASE_URL:latest" \
+     --set-secrets="ENGRAM_CLOUD_TOKEN=ENGRAM_CLOUD_TOKEN:latest" \
+     --set-env-vars="ENGRAM_CLOUD_DASHBOARD=true"
+   ```
+
+6. **IAM — quién puede acceder:**
+   - Los devs no acceden a Cloud Run directamente; lo hace el CLI de Engram.
+   - Si Cloud Run está `--no-allow-unauthenticated`, configura un endpoint público con
+     Cloud Armor (IP allowlist) o un Identity-Aware Proxy (IAP).
+
+7. **VPC connector para Cloud SQL:**
+   Si Cloud SQL tiene IP privada (recomendado), crea un Serverless VPC connector:
+   ```bash
+   gcloud compute networks vpc-access connectors create engram-conn \
+     --network=default --region=us-central1 --range=10.8.0.0/28
+   ```
+   Y en el deploy de Cloud Run añade `--vpc-connector=engram-conn`.
+
+### Verificar
+   ```bash
+   gcloud run services describe engram-cloud --region=us-central1 --format='value(status.url)'
+   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
+     https://engram-cloud-xxxx-uc.a.run.app/health
+   ```
+
+## Opción B: GCE VM + docker-compose (similar al VPS)
+
+Si prefieres control total (equivalente al [despliegue VPS](deploy-cloud-vps.md) pero en GCE):
+
+1. **Crear VM:**
+   ```bash
+   gcloud compute instances create engram-cloud \
+     --machine-type=e2-small \
+     --zone=us-central1-a \
+     --image-family=ubuntu-2204-lts \
+     --image-project=ubuntu-os-cloud \
+     --boot-disk-size=30GB \
+     --tags=engram-cloud
+   ```
+
+2. **Firewall (solo HTTP/HTTPS + SSH):**
+   ```bash
+   gcloud compute firewall-rules create engram-allow-http \
+     --allow=tcp:80,tcp:443 --target-tags=engram-cloud
+   ```
+
+3. **SSH e instalar Docker:**
+   ```bash
+   gcloud compute ssh engram-cloud --zone=us-central1-a
+   # dentro de la VM:
+   sudo apt update && sudo apt install -y docker.io docker-compose-v2 nginx certbot python3-certbot-nginx
+   sudo usermod -aG docker $USER
+   ```
+
+4. **Desplegar igual que el VPS:**
+   - Copia `docker-compose.yml` y `.env` (ver [deploy-cloud-vps.md](deploy-cloud-vps.md))
+   - Configura nginx + Let's Encrypt
+   - Configura systemd para auto-start
+
+### Ventajas de GCE vs VPS genérico
+- **Secret Manager:** los secretos viven en GCP, no en un `.env` en disco
+- **Snapshots programados** del disco para backups
+- **Cloud Logging** centralizado
+- **MIG (Managed Instance Group)** si necesitas HA
+
+## Comparación rápida
+
+| | Opción A (Cloud Run) | Opción B (GCE VM) |
+|---|---|---|
+| Mantenimiento | Mínimo (serverless) | Medio (gestionas la VM) |
+| Coste en reposo | ~$0 (Cloud Run escala a 0) | ~$13/mes (e2-small) |
+| Cold start | Sí (1-3s tras inactividad) | No |
+| Control | Limitado | Total |
+| Backups | Automáticos (Cloud SQL) | Manuales (snapshots) |
+| Recomendado para | Equipos pequeños/medianos | Equipos con carga constante o compliance estricto |
+
+## Conectar los devs
+
+Independiente de la opción elegida, cada dev conecta con:
+
+```bash
+ozali init
+# → "¿Habilitar Engram Cloud?" → sí
+# → URL: https://engram-cloud-xxxx.a.run.app  (A) o https://engram.mi-empresa.com (B)
+# → Token: <ENGRAM_CLOUD_TOKEN>
+```

package/docs/deploy-cloud-vps.md

@@ -0,0 +1,174 @@
+# Desplegar Engram Cloud en un VPS
+
+← [README](../README.md)
+
+Guía para desplegar el **servidor de Engram Cloud** en un VPS genérico (DigitalOcean, Hetzner,
+Linode, AWS EC2, etc.). El servidor centraliza la memoria de equipo: los devs replican a él
+con `ozali sync --cloud` (o automáticamente con autosync).
+
+## Requisitos
+
+- VPS con Linux (Ubuntu 22.04+ recomendado) y acceso SSH
+- Docker Engine + Docker Compose v2
+- Un dominio (o subdominio) apuntando al VPS
+- Puertos: 80/443 (nginx) abiertos al público; 18080 solo localhost
+
+## 1. docker-compose.yml
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    env_file: .env
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U engram"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  cloud:
+    image: ghcr.io/gentleman-programming/engram:latest
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    env_file: .env
+    ports:
+      - "127.0.0.1:18080:18080"  # solo localhost; nginx expone al exterior
+
+volumes:
+  pgdata:
+```
+
+> El `cloud` escucha en `127.0.0.1:18080` (no `0.0.0.0`): nginx hace de reverse proxy con TLS
+> y es el único expuesto al público.
+
+## 2. .env (secretos fuertes)
+
+```bash
+# Postgres
+POSTGRES_USER=engram
+POSTGRES_PASSWORD=<genera un secreto fuerte: openssl rand -hex 32>
+POSTGRES_DB=engram
+
+# Engram Cloud
+ENGRAM_CLOUD_DATABASE_URL=postgres://engram:<PASSWORD>@postgres:5432/engram?sslmode=disable
+ENGRAM_CLOUD_TOKEN=<genera otro secreto fuerte: openssl rand -hex 32>
+ENGRAM_CLOUD_DASHBOARD=true
+```
+
+> **El `ENGRAM_CLOUD_TOKEN` es lo que pide `ozali init` a cada dev.** Compártelo por canal
+> seguro (1Password, Bitwarden, Signal), nunca por email/chat del repo.
+
+## 3. Hardening
+
+### 3.1 Firewall (ufw)
+
+```bash
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+sudo ufw allow 22/tcp      # SSH (considera cambiar el puerto)
+sudo ufw allow 80/tcp      # HTTP (nginx → redirige a HTTPS)
+sudo ufw allow 443/tcp     # HTTPS (nginx)
+sudo ufw enable
+```
+
+### 3.2 nginx reverse proxy con SSL (Let's Encrypt)
+
+```nginx
+server {
+    listen 80;
+    server_name engram.mi-empresa.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name engram.mi-empresa.com;
+
+    ssl_certificate     /etc/letsencrypt/live/engram.mi-empresa.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/engram.mi-empresa.com/privkey.pem;
+    ssl_protocols       TLSv1.2 TLSv1.3;
+    ssl_ciphers         HIGH:!aNULL:!MD5;
+
+    location / {
+        proxy_pass         http://127.0.0.1:18080;
+        proxy_set_header   Host $host;
+        proxy_set_header   X-Real-IP $remote_addr;
+        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Certbot para el certificado:
+
+```bash
+sudo certbot --nginx -d engram.mi-empresa.com
+```
+
+### 3.3 systemd para auto-start
+
+```ini
+# /etc/systemd/system/engram-cloud.service
+[Unit]
+Description=Engram Cloud (Docker Compose)
+After=docker.service
+Requires=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+WorkingDirectory=/opt/engram-cloud
+ExecStart=/usr/bin/docker compose up -d
+ExecStop=/usr/bin/docker compose down
+TimeoutStartSec=0
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable --now engram-cloud
+```
+
+## 4. Verificar
+
+```bash
+# En el VPS:
+docker compose ps              # ambos servicios "healthy"
+curl http://127.0.0.1:18080/health  # debería responder OK
+
+# Desde fuera:
+curl https://engram.mi-empresa.com/health
+```
+
+## 5. Conectar los devs
+
+Cada dev en su repo:
+
+```bash
+ozali init
+# → "¿Habilitar Engram Cloud?" → sí
+# → URL: https://engram.mi-empresa.com
+# → Token: <el ENGRAM_CLOUD_TOKEN del .env>
+# → autosync activo
+```
+
+Si el servidor requiere upgrade de esquema:
+
+```bash
+ozali cloud upgrade   # doctor → repair → bootstrap
+```
+
+## Backups
+
+```bash
+# Dump de Postgres (cron diario):
+docker exec engram-cloud-postgres-1 pg_dump -U engram engram | gzip > /backups/engram-$(date +%F).sql.gz
+```
+
+Mantén los backups fuera del VPS (S3, GCS, almacenamiento externo).

package/docs/ideas/postgres-vs-mysql-engram-cloud.md

@@ -0,0 +1,137 @@
+# PostgreSQL 16 vs MySQL 8.x para Engram Cloud
+
+← [README](../README.md)
+
+Guía comparativa para adaptar el despliegue de Engram Cloud de PostgreSQL a MySQL 8.x.
+
+## Cambios necesarios en `docker-compose.yml`
+
+### PostgreSQL 16 (actual — ver [deploy-cloud-vps.md](deploy-cloud-vps.md))
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    env_file: .env
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U engram"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  cloud:
+    image: ghcr.io/gentleman-programming/engram:latest
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    env_file: .env
+    ports:
+      - "127.0.0.1:18080:18080"
+
+volumes:
+  pgdata:
+```
+
+### MySQL 8.x (propuesto)
+
+```yaml
+services:
+  mysql:
+    image: mysql:8.0
+    restart: unless-stopped
+    env_file: .env
+    volumes:
+      - mysqldata:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  cloud:
+    image: ghcr.io/gentleman-programming/engram:latest
+    restart: unless-stopped
+    depends_on:
+      mysql:
+        condition: service_healthy
+    env_file: .env
+    ports:
+      - "127.0.0.1:18080:18080"
+
+volumes:
+  mysqldata:
+```
+
+## Cambios en `.env`
+
+| Variable | PostgreSQL | MySQL 8.x |
+|---|---|---|
+| DB user/pass | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | `MYSQL_ROOT_PASSWORD`, `MYSQL_DATABASE`, `MYSQL_USER`, `MYSQL_PASSWORD` |
+| Connection string | `postgres://engram:pass@postgres:5432/engram?sslmode=disable` | `engram:pass@tcp(mysql:3306)/engram?charset=utf8mb4&parseTime=True&loc=Local` |
+
+### `.env` para MySQL 8.x
+
+```bash
+# MySQL
+MYSQL_ROOT_PASSWORD=<genera un secreto fuerte: openssl rand -hex 32>
+MYSQL_DATABASE=engram
+MYSQL_USER=engram
+MYSQL_PASSWORD=<genera otro secreto fuerte>
+
+# Engram Cloud
+ENGRAM_CLOUD_DATABASE_URL=engram:<PASSWORD>@tcp(mysql:3306)/engram?charset=utf8mb4&parseTime=True&loc=Local
+ENGRAM_CLOUD_TOKEN=<genera otro secreto fuerte: openssl rand -hex 32>
+ENGRAM_CLOUD_DASHBOARD=true
+```
+
+## Tabla comparativa
+
+| Aspecto | PostgreSQL 16 | MySQL 8.x |
+|---|---|---|
+| Imagen Docker | `postgres:16-alpine` (~80MB) | `mysql:8.0` (~450MB) |
+| Healthcheck | `pg_isready -U engram` | `mysqladmin ping -h localhost` |
+| Volúmenes | `/var/lib/postgresql/data` | `/var/lib/mysql` |
+| Driver Go | `lib/pq` o `pgx` | `go-sql-driver/mysql` |
+| Connection string | `postgres://` | `user:pass@tcp(host:port)/db?...` |
+| JSON nativo | `JSONB` (índices GIN) | `JSON` + funciones |
+| Arrays nativos | Sí (`text[]`, `int[]`) | No (usa tablas relacionales) |
+| Full-text search | `tsvector`/`tsquery` | `FULLTEXT` indexes |
+| Concurrency | MVCC sin locks de lectura | MVCC con read locks en algunos casos |
+| Backup | `pg_dump` | `mysqldump` |
+
+## Bloqueador: ¿Engram soporta MySQL?
+
+Depende del código fuente de [github.com/Gentleman-Programming/engram](https://github.com/Gentleman-Programming/engram):
+
+- **Si usa GORM**: con cambiar el driver (`postgres` → `mysql`) y el DSN, funcionaría.
+- **Si usa SQL nativo con funciones Postgres** (`JSONB`, `NOW()`, `ARRAY`, `ILIKE`, `RETURNING`): requiere tocar el código de Engram.
+
+### Para verificar rápido
+
+```bash
+# 1. Desplegar con MySQL (docker-compose arriba)
+docker compose up -d
+
+# 2. Ver logs del contenedor cloud:
+docker logs engram-cloud-cloud-1
+# Si falla con "unsupported driver" o "syntax error", no hay soporte MySQL.
+
+# 3. Si conecta, verificar health:
+curl http://127.0.0.1:18080/health
+```
+
+## Backup con MySQL
+
+```bash
+# Dump de MySQL (cron diario):
+docker exec engram-cloud-mysql-1 mysqldump -u engram -p<PASSWORD> engram | gzip > /backups/engram-$(date +%F).sql.gz
+```
+
+## Recomendación
+
+- **Mantener PostgreSQL** si no hay requisito específico de MySQL. Es lo que Engram espera.
+- **Migrar a MySQL** solo si el equipo ya tiene infra MySQL operativa (DBA, backups, monitoreo) y se confirma que Engram tiene driver MySQL compilado.