Onboarding guiado de descarga del Local Agent (PR #182, #293)

Descripción

Feature que ofrece al usuario una descarga guiada y contextual del Local Agent cuando lo necesita, pero no está instalado en su equipo.

Cierra la brecha de UX en el flujo de auto-discovery de red: hasta ahora, si el Agent no estaba en ejecución, el usuario veía solo un error seco ("Please start CreaRackAgent.exe") sin opciones. Ahora:

Se detecta que el Agent NO está corriendo (probe a 127.0.0.1:5050/info).
Se muestra un banner instalación con dos botones: Download Local Agent y Not now.
Al pulsar Download: se descarga el instalador .exe (descarga del navegador, automatizada), se sondea cada 2.5s, y se cierra el banner automáticamente cuando el Agent conecta.
Se ofrece en contextos específicos (discovery de red, agent_probe) — modelo “just-in-time”, no al iniciar la app (pues hay usuarios que solo leen datos del Sentinel central, sin necesidad de Agent local).

Contexto de negocio

Tarea #182: Falta guía de instalación del Local Agent en primera instalación.
Modelo de despliegue: El navegador solo ve el Agent de SU máquina (127.0.0.1). El Sentinel 24/7 (Agent Primary) entrega monitorización central sin necesidad de Agent local en cada equipo. Por eso no hay aviso genérico al arrancar la app.
Deuda menor: Traducción ES de strings nuevos → ciclo i18n F4.

Componentes técnicos

Módulo principal: `agent_onboarding.js`

Ubicación: static/js/modules/agent_onboarding.js (114 LOC).
API pública: window.CreaRackAgentOnboarding:
- offer(context) — muestra el banner de instalación. context puede ser 'discovery', 'manual' u otro.
- downloadAgent() — descargar el .exe.
- agentRunning() — probe ligero (fetch a /info con timeout 1.5s).
Polling: Cada 2.5s comprueba si el Agent conectó. Al conectar, cierra el banner y muestra un toast de éxito.
Estilos: Banner usa clase lna-notice (reutilizado de agent_lna_notice.js). Botones horizontales: .agent-install-actions (flexbox, gap 10px).

Integración en flujos existentes

discovery.js (línea ~255): En el catch del probeIpViaAgent, ofrece el onboarding en vez de lanzar error seco.
agent_probe.js (línea ~27): Igual — context 'discovery'.

Estilos CSS

components.css (19 LOC): Nueva clase .agent-install-actions para layout horizontal de botones.

Carga en HTML

base.html: Script defer tras agent_lna_notice.js, antes de auth.js.

Flujo UX

Usuario intenta discovery de red
    → agent_probe.js / discovery.js sondean Agent
        → Falla el fetch a 127.0.0.1:5050/info
            → En catch: CreaRackAgentOnboarding.offer('discovery')
                → Banner: "Install the Local Agent"
                → Botones: Download | Not now
                    → Download: descarga .exe, sondea cada 2.5s
                    → Not now: cierra banner (marca sesión para no reofrecerlo)

No auto-disparo al cargar la app: El usuario que solo consulta datos centrales nunca verá el banner (model just-in-time).

Detalles de implementación

Detección del Agent

async function agentRunning() {
    try {
        const r = await fetch(`${AGENT_URL}/info`, { 
            signal: AbortController, 
            timeout: 1500ms 
        });
        return r.ok;
    } catch { return false; }
}

Intro dinámico según context (discovery vs. manual).
Botones: btn-action (Download, en azul/primario) y btn-neutral (Not now, en gris).
Al hacer click en Download: el texto cambia a “Downloading…” y el botón se deshabilita.
El banner se remueve con animación fade-out (0.25s, clase lnaOut).

Polling

Cada 2.5s: agentRunning().
Al detectar conexión: limpiar intervalo, mostrar toast “Local Agent connected” (verde), remover banner.

Diferencias con `agent_lna_notice.js`

Módulo	Qué detecta	Cuándo se muestra	Acción
`agent_lna_notice.js`	Agent YA instalado pero permiso Local Network Access pendiente	Primera vez / consentimiento pendiente	Explica el popup del navegador para aceptar permiso
`agent_onboarding.js` (nuevo)	Agent NO instalado	Cuando se necesita en un flujo (discovery, etc.)	Ofrece descargar el instalador

Ambos usan el estilo .lna-notice (banner flotante en la app).

Verificación (testeado en local)

✅ Banner en contexto discovery (probe falla).
✅ Banner en contexto manual (offer() directo).
✅ Download cambia estado y deshabilita botón.
✅ Not now cierra + marca sesión.
✅ Polling cierra al conectar Agent.
✅ Toast de éxito “Local Agent connected”.
✅ Sin errores de consola (Docker + navegador, admin).
⚠️ Instalación sigue siendo manual (navegador no ejecuta .exe); descarga sí es automatizada.

Véase también

[[feature—core—aviso-lna]]
[[entity—static—service—agent-onboarding]]
[[concept—terminal—local-agent]]
[[decision—20260610—terminal-auth-local-cross-origin]]
[[feature—network—auto-provision-refresh-agent-fix]]