feature/generador-instaladores-linux-windows

INTEGRACION_PANEL.md

@@ -132,15 +132,69 @@ Usado por utilidades legacy; el flujo principal de jobs usa `resolve-route`.
 
 ### POST `/api/restore/instance-config`
 
-Reporte de carpeta de entrada (`instance_key` = nombre del servidor).
+Reporte de carpeta de entrada e identidad del agente (`instance_key` = nombre del servidor).
+Es *best-effort*: un fallo aquí nunca bloquea una restauración.
+
+```jsonc
+{
+  "input_folder": "D:\\Backups\\Entrada",
+  "processed_folder": "D:\\Backups\\Procesados",  // opcional; el panel la deriva si falta
+  "host_name": "WIN-RESTORE-01",
+  "app_version": "1.1.0",       // versión instalada → cloudrestore_status.app_version
+  "platform": "windows",        // "windows" | "linux"
+  "arch": "x86_64",             // "x86_64" | "arm64"
+  "instance_key": "Alfa"        // = restore_targets.name
+}
+```
+
+`platform` y `arch` le dicen al panel **qué artefacto le corresponde a este servidor** al
+instalar o actualizar: `a24c.cras_releases` se llavea por `version + platform + arch`. Un
+agente viejo que no las mande sigue funcionando; el panel cae al texto libre de
+`restore_targets.os` para la primera instalación.
+
+Respuesta: `200 { "ok": true, "trace_id": "…" }`.
+
+### POST `/api/restore/agent-sync`
+
+Dispara la sincronización del catálogo de versiones contra Gitea. Lo usa
+`publish-release.sh --notify-panel` para que una versión recién publicada aparezca de
+inmediato, sin esperar a que un admin abra `/versiones-cras`.
+
+Body vacío (`{}`). Respuesta: `200 { "ok": true, "discovered": N, "versions": N }`.
+
+---
+
+## Distribución de versiones (Gitea → PANEL → servidor)
+
+Los binarios se publican en el registro de paquetes genéricos de Gitea; el panel los
+descubre leyendo su API, los cachea verificando el `sha256` que Gitea calcula, e instala
+por SSH/SFTP en el servidor destino.
+
+```
+build local  →  Gitea (generic packages)  →  PANEL (caché + instalador SSH)  →  servidor
+```
+
+- **Publicar:** ver [BUILD.md](BUILD.md) §5 (`publish-release.sh`).
+- **Instalar/actualizar:** panel → **Versiones CRAS** (`/versiones-cras`) → *Sincronizar con
+  Gitea* → *Activar* → *Instalar* en el servidor.
+- El panel siembra `config/.env` con `api_url`, `api_token` e `instance_key` durante la
+  instalación, así que el servidor queda operativo sin configuración manual.
+- El servidor destino **no descarga nada de internet**: el binario es autocontenido y los
+  bytes llegan del panel por SFTP.
+
+Tablas involucradas: `a24c.cras_releases` (catálogo de versiones publicadas) y
+`a24c.cras_install_runs` (bitácora de instalaciones con progreso paso a paso).
 
 ---
 
 ## Agregar servidores adicionales
 
-1. Panel → **Servidores de Restauración → + Nuevo servidor**
+1. Panel → **Servidores de Restauración → + Nuevo servidor** (incluye credenciales SSH)
 2. **Gestión de Bases de Datos** → dropdown servidor por base
-3. Instalar CRA → Config → instancia → Guardar (card **Reportada**)
+3. Panel → **Versiones CRAS** → *Instalar* en ese servidor (siembra el `.env` solo)
+
+El camino manual sigue disponible: instalar el CRA a mano → Config → instancia → Guardar
+(card **Reportada**).
 
 ---