Reemplazo de ReDoc por Scalar en el portal de Referencia de API

Status: ✅ Implementado Fecha: 2026-07-28

Contexto

El portal de Referencia de API (doc/site/public/docs.html) usaba ReDoc (bundle vendoreado en assets/redoc.standalone.js) para renderizar openapi.yaml. Como paso previo a este cambio ya se le había aplicado un tema claro propio (mismos tokens que el resto del sitio — ver doc/plans/2026-07-25-seccion-documentacion.md), reemplazando el navy que traía por defecto. El cliente pidió reemplazar ReDoc directamente por Scalar (@scalar/api-reference).

Decisión

• Bundle vendoreado, mismo criterio que ReDoc: assets/scalar.standalone.js, copiado de @scalar/api-reference@1.63.0 (dist/browser/standalone.js, 3.7MB) — sin dependencia de CDN, igual que el bundle de ReDoc que reemplaza. assets/redoc.standalone.js queda sin uso en el repo (no se pudo borrar, ver limitaciones de la sesión que hizo el cambio).
• Scalar.createApiReference('#api-reference-container', {...}) en docs.html, con:
  • layout: 'modern'.
  • hideTestRequestButton: true — decisión de seguridad, no cosmética: sin esto, Scalar habilita por defecto un botón de "Test Request" que manda requests HTTP reales desde el navegador contra los endpoints documentados. Estas son las 4 APIs transaccionales REALES de Soterex (tokenC2P, SendRequest, Cancel, Notifications) — el portal tiene que seguir siendo de solo lectura, mismo criterio que ya cumplía ReDoc (que ni siquiera tiene esa capacidad). Este flag además oculta el panel de autenticación automáticamente (comportamiento documentado de Scalar).
  • forceDarkModeState: 'light' + hideDarkModeToggle: true — un solo tema fijo, sin toggle, mismo criterio que tenía ReDoc (sin modo oscuro).
  • Tema claro con los mismos tokens de marca que el resto del sitio (--scalar-color-*, --scalar-background-*, --scalar-sidebar-*), scopeados bajo .light-mode/.light-mode .sidebar (ver el <style> al principio de docs.html).
• ADR-004 (SSO) actualizado para reflejar que el portal ahora es Scalar, no ReDoc — la garantía de "solo lectura" que justifica el diseño de SSO sigue siendo válida, ahora vía hideTestRequestButton en vez de "ReDoc no tiene consola Try it".

Verificación

• curl confirma 200 para docs.html, assets/scalar.standalone.js y openapi.yaml.
• Chequeo de sintaxis (llaves/paréntesis/comillas balanceadas) sobre el docs.html reescrito.
• Confirmado en el HTML servido: sin menciones de "redoc"/"Redoc", con "Scalar"/"scalar.standalone" presentes.
• Sin herramienta de browser esta sesión — no se verificó visualmente el render final ni la interacción con el sidebar/búsqueda de Scalar en un navegador real. Verificado por partes (HTTP real + sintaxis) — la confirmación visual queda para revisar en el browser.

Pendiente / fuera de alcance

• El bloqueante ya conocido de doc/site/public/index.html/docs.html con Firebase hardcodeado a "REEMPLAZAR" para Staging/Producción (ver doc/environments/staging.md) es independiente de este cambio — no se resuelve acá.
• assets/redoc.standalone.js queda huérfano en el repo (no se pudo borrar esta sesión).