Solución de problemas
Soluciones partiendo del síntoma para los problemas que realmente vemos: un widget bloqueado, una primera petición lenta, fallos de detección, fallos de enriquecimiento y problemas de inicio de sesión.
Parte de tu síntoma. Cada solución de esta página es el remedio real que se entrega hoy — y cuando algo necesita a una persona, la última sección dice exactamente a dónde escribir.
El widget no aparece
La causa más común es una Content-Security-Policy estricta en tu página. El widget inyecta sus estilos en su Shadow DOM con un elemento style, así que una style-src que prohíba estilos en línea lo bloquea — permite 'unsafe-inline' en style-src (los estilos nunca salen del shadow root del widget). La consola del navegador muestra la violación de CSP cuando esta es la causa.
Confirma también que script-src permite cdn.syncanix.com (donde se sirve widget.js) y connect-src permite api.syncanix.com (con quien habla).
Las páginas que aplican Trusted Types (require-trusted-types-for 'script') son compatibles: el widget arranca y conversa sin alimentar ningún sumidero de cadenas. Solo si tu política TAMBIÉN restringe los nombres de políticas con una directiva trusted-types, permite syncanix-widget (desafío antibots), syncanix-widget-sw (service worker sin conexión) y dompurify (saneador de respuestas); de lo contrario, esas funciones opcionales se degradan con elegancia mientras el chat sigue funcionando.
La primera petición es lenta, o falla una vez y luego funciona
En espacios de trabajo tranquilos, la primera petición tras un largo periodo inactivo puede tardar unos segundos mientras la capacidad serverless despierta y, en casos raros, falla una vez. El widget reintenta automáticamente la carga de su configuración. Si llamas a la API directamente, trata como reintentable una única primera petición fallida tras la inactividad.
El descubrimiento no encontró nada, o eligió el framework equivocado
Ejecuta primero syncanix doctor: comprueba tu versión de Node, el framework detectado, la validez de la configuración y la clave de API de una pasada. Si la detección se equivocó (los repos mixtos pueden confundirla), nombra el framework explícitamente: syncanix init --framework <nombre>.
Si el descubrimiento escaneó carpetas que no debía (código vendorizado, archivos generados), añádelas a .syncanixignore y vuelve a ejecutarlo.
El enriquecimiento falló, o necesitas trabajar sin conexión
Pasa --offline para escribir el catálogo localmente sin subirlo; sin claves de modelo configuradas, syncanix init --offline --yes completa el descubrimiento sin enriquecimiento. El archivo del catálogo es determinista, así que volver a ejecutarlo más tarde no revuelve tu revisión.
Problemas de inicio de sesión
syncanix login guarda un token generado en el panel en ~/.syncanix/credentials (legible solo por ti); syncanix logout lo elimina. Si las subidas fallan con un error de autenticación, ejecuta syncanix doctor — te dice si la clave guardada resuelve — y vuelve a iniciar sesión.
Cambiar una decisión de consentimiento guardada
Tu decisión de consentimiento de enriquecimiento se guarda en .syncanix/consent.json. Para cambiarla, borra el archivo y vuelve a ejecutar syncanix init: el aviso de consentimiento se muestra de nuevo.