Tu kit
Qué contiene el kit de un protocolo, dónde está en DevLab, qué es cada fichero y cada variable, dónde está la URL de Engine y cómo ejecutar un starter.
Tu kit es el conjunto de ficheros que DevLab prepara para un protocolo de tu organización: la configuración del cliente, el entorno de tu backend y dos guías. Ya trae todo lo que DevLab sabe (la URL de Engine de tu entorno, el protocolo, las decisiones que Neurologyca fijó para tu organización), así que solo añades lo que es tuyo: la key y, en el starter de grabación, una dirección pública.
Dónde encontrarlo
Sección titulada «Dónde encontrarlo»- Entra y abre Tu integración en la cabecera. Se abre en Protocolos.
- Elige un protocolo de la lista.
- Arriba del protocolo, junto a Protocolo, elige Kit.
La ruta es Tu integración › Protocolos › un protocolo › Kit. Cada vista tiene su propia dirección, así que puedes guardarla en favoritos.
Cuándo no hay Kit:
- Sin key activa. Si la key de tu equipo está revocada o no existe, los protocolos se ven en solo lectura («Protocolos de tu organización, solo lectura») y no tienen kit hasta que tu equipo vuelva a tener key. Consulta Tu cuenta de DevLab.
- Baseline. No tiene kit («Baseline no tiene kit: va antes de cualquier protocolo»).
- Un protocolo cuyo contexto DevLab no puede resolver («Sin kit: su contexto no está resuelto»). Pídeselo a Neurologyca si lo necesitas.
El mapa de todas las pantallas está en Dónde está cada cosa.
Los ficheros del kit
Sección titulada «Los ficheros del kit»La pestaña Kit muestra una pestaña por fichero, cada una con Copiar y un botón para descargarlo. El kit no lleva nunca tu key. Los navegadores quitan el punto inicial del nombre al guardar un fichero, así que el botón guarda .env.example como env.example y .npmrc como npmrc, y dice a qué renombrar cada uno (.env y .npmrc, en tu proyecto).
| Fichero | Dónde aparece | Qué es |
|---|---|---|
neuro.config.json | Siempre. | La configuración del cliente de tu protocolo: pásala a defineTenantConfig(json). |
.env.example | El kit de tu consola. | El entorno de tu backend, sin tu key: cópialo a .env y rellénalo. No subas nunca .env a git. |
.env | El zip del starter (en vivo o grabación). | El entorno de tu backend. La key va vacía salvo que descargaras el starter con «Incluir mi key». No lo subas nunca a git. |
.npmrc | Siempre. | Apunta @neurologyca a GitHub Packages y lee NODE_AUTH_TOKEN de tu entorno; no lleva ningún secreto. Sin él, npm install responde 404 para @neurologyca/*. |
KIT.md | Siempre. | El kit en prosa: las versiones del SDK para las que está hecho (con el comando para comprobar las tuyas y el changelog), el enlace a los indicadores que te da tu contexto (Tu integración › Protocolos), orden de arranque, el aviso que das a las personas que mides (con el texto modelo del Anexo biométrico y, en el starter de grabación, el consentimiento previo y por escrito que pide una grabación en diferido donde la ley lo exija), lo pendiente, audiencias, opciones de preguntas y enlaces a la doc. |
AGENTS.md | Siempre. | Las reglas y el índice de la doc para tu agente de código; pégalo en tu AGENTS.md o CLAUDE.md. Va en inglés a propósito. |
Junto a los ficheros, la pestaña Kit lista lo pendiente (una decisión que Neurologyca aún no ha fijado para tu organización: «Pídeselo a Neurologyca») y lo opcional (puedes capturar sin ello; por ejemplo, sin subcontexto Engine aplica el de la mecánica, constellationSubcontextId, o si no el por defecto del contexto). KIT.md lleva la misma información en prosa, con el orden de arranque, lo que no debes hacer nunca (poner la key en código de navegador, subir una credencial a git, confundir la key de Engine con el token del registro), el aviso que das a cada persona que mides antes de cualquier captura (con el enlace al texto modelo de aviso y consentimiento, sección 14 del Anexo biométrico), las audiencias de interpretación del contexto del protocolo y las opciones de pregunta de cada step. Enlaza también los indicadores que te da tu contexto, sin lista: la lista al día es Indicadores que recibes en este contexto, en el protocolo, en Tu integración › Protocolos (qué enseña).
Las versiones del SDK
Sección titulada «Las versiones del SDK»Bajo Vías, la pestaña Kit tiene Versiones: las versiones de @neurologyca/capture y @neurologyca/capture-server para las que está hecho el kit, las que DevLab instala y verifica y las que instalan los starters. DevLab no ve tu proyecto, así que no sabe qué versión tienes: compara con la fecha de publicación del changelog y te da el comando para comprobar la tuya, npm ls @neurologyca/capture @neurologyca/capture-server, con Copiar. Durante 30 días desde que se publica una versión, su fila lleva un chip, uno por paquete:
- Nueva · fecha: una versión compatible. Si tu proyecto usa una anterior, actualiza con el comando
npm ique enseña el bloque; no hace falta cambiar nada más. El enlace dice qué cambia en esa versión. - Incompatible · fecha: una versión publicada en esos 30 días, hasta la del kit, es incompatible (también si después salió una compatible; la fecha es la de la incompatible). Con una anterior, tu proyecto puede dejar de funcionar: sigue la guía de migración antes de actualizar.
KIT.md, en el kit y en los starters, dice lo mismo bajo su línea DevLab:: las versiones para las que está hecho y su fecha, el mismo comando y el enlace al changelog. El script doctor de la skill lee el mismo changelog publicado y sí mira tu node_modules (Integrar con tu agente de código).
Las variables del .env
Sección titulada «Las variables del .env».env.example del kit y el .env de un zip de starter llevan las mismas variables: copia .env.example a .env y rellena lo que es tuyo. Las variables de grabación aparecen solo donde dice la tabla.
| Variable | Dónde aparece | Qué es | Quién la rellena |
|---|---|---|---|
ENGINE_BASE | Siempre. | La URL del Engine de tu entorno, ya rellena desde tu kit. La usa tu backend; el navegador nunca. | Ya la rellena tu kit. |
ENGINE_API_KEY | Siempre. | La key de tu equipo, solo para tu backend. Va vacía en el kit: descarga el starter con «Incluir mi key» o revélala en Tu cuenta. Nunca en código de navegador ni en git. | Secreto. Vacía en el kit. Un starter descargado con Incluir mi key la rellena (los valores del procesador piden Incluir mi key y las credenciales del procesador). |
PROTOCOL_ID | Siempre. | El id del protocolo al que pertenece este kit. | Ya la rellena tu kit. |
ROLE | Protocolos de contexto (no Measurement). | Rol opcional que se fija en cada persona que crea tu backend. El kit lo rellena solo si Neurologyca fijó uno para ti, así que suele ir vacío y vale; si lo pones, ha de ser uno que Engine conozca. Hoy no tiene efecto. | El kit la rellena solo si Neurologyca fijó un valor para ti. |
NARRATIVE_LANGUAGE | Protocolos de contexto (no Measurement). | El idioma de la interpretación (en o es), que se fija en cada persona que crea tu backend. Sin él, Engine escribe en inglés. | Ya la rellena tu kit. |
PORT | Siempre. | El puerto en el que escucha tu backend (3000 por defecto). | — |
PROCESSOR_URL | El starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado. | La URL del servicio de procesado de Neurologyca para las capturas en diferido. Vacía si tu organización no lo tiene dado de alta. | Ya la rellena tu kit. |
PROCESSOR_API_KEY | El starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado. | La key del servicio de procesado, una sola pareja para toda tu organización. Se rellena solo al descargar el starter de grabación con «Incluir mi key y las credenciales del procesador». Queda vacía si el servicio de procesado está apagado o aún sin alta para tu organización. | Secreto. Vacía en el kit. Un starter descargado con Incluir mi key la rellena (los valores del procesador piden Incluir mi key y las credenciales del procesador). |
PROCESSOR_SECRET | El starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado. | El secreto con el que el servicio de procesado firma sus webhooks; verificar la firma es obligatorio. Se rellena junto con PROCESSOR_API_KEY y queda vacío en los mismos casos (servicio apagado o sin alta). | Secreto. Vacía en el kit. Un starter descargado con Incluir mi key la rellena (los valores del procesador piden Incluir mi key y las credenciales del procesador). |
PUBLIC_BASE_URL | El starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado. | El origen HTTPS público de tu backend. El servicio de procesado llama ahí a tres rutas (vídeo, token y webhook); nunca llama a localhost, así que para probar en local usa un túnel HTTPS público. | La pones tú. |
UPLOAD_URL_SECRET | El starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado. | Solo tuyo: firma las URL de tus vídeos y es distinto de PROCESSOR_SECRET. Cada descarga del starter de grabación lleva un valor aleatorio nuevo (una descarga nueva lo cambia e invalida las URL ya firmadas). En el kit de la consola (.env.example) va vacío: genera tú una cadena hex aleatoria de 32 bytes. | Secreto. Un valor aleatorio nuevo en cada descarga del starter de grabación. |
neuro.config.json
Sección titulada «neuro.config.json»La configuración del cliente de tu protocolo: pásala a defineTenantConfig(json). La lee el código de tu navegador; no lleva ningún secreto.
| Clave | Dónde aparece | Qué es |
|---|---|---|
engineBaseUrl | Siempre. | La ruta de tu propio proxy hacia Engine ('/engine'), no el host de Engine. El navegador llama a tu proxy y tu backend añade la key. |
taxonomy.contextId | Siempre. | El contexto en el que se mide la captura. Con Measurement es siempre "measurement". |
taxonomy.hciId | Protocolos de contexto que fijan un HCI objetivo. | El HCI objetivo del contexto, cuando el protocolo fija uno. |
taxonomy.subcontextByMechanic | Protocolos de contexto con el subcontexto de cada mecánica fijado. | El subcontexto elegido para cada mecánica, por nombre de mecánica. Sin él, Engine aplica el de la mecánica o el de por defecto del contexto. |
triggerAnalysis | Solo Measurement. | Una clave de tu aplicación, no del SDK: tu código la pasa a la captura (client.capture() o captureProtocol). false porque Measurement no interpreta. |
transcribe | Measurement (siempre, como false); protocolos de contexto con la transcripción encendida, que es lo habitual. | La transcripción: false, o { "language": "en" | "es" } sin región. Abre también el micrófono. El idioma es el que habla la persona: se fuerza, nunca se detecta. |
media | Protocolos de contexto donde algún step ofrece varias preguntas. | La pregunta de cada step: { "<mecánica>": { "<orden del step>": "<mediaPid>" } }. Por defecto, la primera que no usa un step anterior. |
processing.language | Solo el starter de grabación. | El idioma que tu backend manda con cada trabajo diferido (en o es); el servicio de procesado lo exige. |
processing.transcribeSteps | Solo el starter de grabación. | Los tipos de step que transcribe el servicio de procesado. Ponla a [] para apagar la transcripción en este starter (ignora "transcribe"). |
Dónde está la URL de Engine
Sección titulada «Dónde está la URL de Engine»La URL de Engine de tu entorno está en Tu integración › Protocolos › un protocolo › Kit › .env.example, en la línea ENGINE_BASE. Es también la línea ENGINE_BASE del .env que va dentro del zip de un starter.
La documentación nunca imprime el valor, porque es el de tu entorno (pruebas o producción): los ejemplos la llaman $ENGINE, y ENGINE_BASE es el mismo valor en el entorno de tu backend. Solo la usa tu backend. El navegador llama a tu proxy, y por eso engineBaseUrl de neuro.config.json es la ruta de tu proxy (/engine) y no la dirección de Engine.
Si tu equipo no tiene key activa no hay kit, y por tanto tampoco .env.example: mira dónde encontrarlo.
Dónde está mi key
Sección titulada «Dónde está mi key»El kit no la lleva: ENGINE_API_KEY va vacía en .env.example. Tienes dos formas de conseguirla:
- Revelarla en Tu cuenta, en Keys de Engine, con tu contraseña (Revela la key de tu equipo).
- Descargar un starter con Incluir mi key: el servidor escribe la key en el
.envdel zip. Mira abajo.
Los starters
Sección titulada «Los starters»Un starter es un proyecto pequeño y completo, listo para ejecutar, con tu kit ya dentro. Abajo en la pestaña Kit, Starters ofrece dos:
- Starter en el dispositivo (tiempo real): la página captura en el navegador y tu backend hace de proxy hacia Engine. Elígelo para ver la integración funcionando de extremo a extremo y como base de una captura en vivo.
- Starter de grabación (diferido, en servidor) (Preview): la página graba y sube, y tu backend recibe el aviso del servicio de procesado. Elígelo solo si vas a procesar grabaciones en un servidor (Diferido). Si tu organización aún no tiene el servicio de procesado, su tarjeta lo dice y el starter no arranca (
npm startse para con el mismo mensaje): pídeselo al admin de tu organización o a Neurologyca.
Elige Descargar .zip. Si la descarga no empieza, púlsalo de nuevo (la página lo dice pasados unos segundos). El playground tiene la misma descarga en Playground › SDK y API, sin tu key.
Qué trae el zip
Sección titulada «Qué trae el zip»En su raíz:
| Fichero | Qué es |
|---|---|
neuro.config.json | La configuración del cliente de tu protocolo, el mismo fichero que en tu kit. |
.env | El entorno de tu backend. La key va vacía salvo que elijas Incluir mi key. |
.npmrc | Apunta los paquetes @neurologyca al registro privado y lee el token de NODE_AUTH_TOKEN; nunca contiene el token. |
.gitignore | Deja .env, node_modules y los ficheros locales fuera de git. |
KIT.md | El kit en prosa, el mismo fichero que en tu kit. |
AGENTS.md | Las reglas y el índice de la doc para tu agente de código, el mismo fichero que en tu kit. |
README.md | La guía propia del starter: requisitos, los tres comandos y qué hace cada fichero del código. |
Además, el código propio del starter: un servidor pequeño, la página y los módulos que ejecuta el playground. El zip del starter de grabación trae también los scripts para simular el aviso.
Ejecútalo
Sección titulada «Ejecútalo»Necesitas Node.js 20.6 o posterior (los starters usan node --env-file) y el token del registro que Neurologyca te da con la invitación en NODE_AUTH_TOKEN (no es tu key de Engine; consulta Instalación). Sin Incluir mi key, pon antes tu key en .env (ENGINE_API_KEY; dónde).
export NODE_AUTH_TOKEN=... # PowerShell: $env:NODE_AUTH_TOKEN="..."npm install && npm startDespués abre http://127.0.0.1:3000 (la variable PORT lo cambia). Si npm start se para con bad option: --env-file, tu Node es anterior a 20.6. Si se para con Missing in .env: …, nombra cada variable que falta y de dónde sale. Dos starters pueden correr a la vez con PORT distintos.
npm test comprueba el arranque en Chrome con un vídeo sintético como cámara (sin cara, así que en el starter en el dispositivo pasa cuando el arranque llega a la comprobación de la cara; su README dice cómo comprobar hasta la captura con un vídeo tuyo) y borra la persona de prueba en Engine. Sin tu key en .env (o, en el starter en diferido, sin el servicio de procesado) esa comprobación se salta y dice por qué; el resto de npm test corre igual.
Incluir mi key
Sección titulada «Incluir mi key»La key nunca va en la página. Para tenerla en el zip, marca Incluir mi key y pulsa Descargar .zip: DevLab te pide la contraseña en un diálogo y el servidor escribe la key en el .env del zip. Si cancelas o cierras el diálogo, no se envía nada.
- Cuenta como un revelado: 5 por hora y cuenta, compartidos con Revelar en Tu cuenta y con las credenciales del procesador; una contraseña incorrecta también cuenta, y cada descarga queda registrada.
- En el starter de grabación la opción es Incluir mi key y las credenciales del procesador: escribe también
PROCESSOR_API_KEYyPROCESSOR_SECRET, la pareja de toda tu organización (la vigente, nunca una pendiente). Si el servicio de procesado está apagado o tu organización aún no tiene alta, esas dos líneas salen vacías con el motivo. Consulta Credenciales del procesado en diferido. - Mientras tu organización no acepte los Términos de DevLab, Incluir mi key está deshabilitada y dice por qué (el mismo aviso de Tu cuenta): el starter sin la key se sigue descargando.
- Cada zip de grabación lleva un
UPLOAD_URL_SECRETaleatorio nuevo: descargar otra vez lo cambia e invalida las URL de vídeo firmadas con el anterior. PUBLIC_BASE_URLlo pones tú: la dirección HTTPS pública de tu backend. El servicio de procesado nunca llama alocalhost, así que para probarlo en tu máquina usa un túnel HTTPS público (Servicio de procesado).
Si algo no funciona
Sección titulada «Si algo no funciona»| Ves | Qué significa | Qué hacer |
|---|---|---|
| La descarga no empieza, o «Si la descarga no empieza, inténtalo de nuevo» | El navegador no recibió el zip | Pulsa Descargar .zip de nuevo |
| «Contraseña incorrecta: no se ha descargado nada» | La contraseña de Incluir mi key no es la de tu cuenta de DevLab | Tecléala de nuevo; el intento cuenta para los 5 por hora |
| «Has llegado al límite de 5 por hora (compartido con Revelar)» | Has gastado tus 5 revelados de esta hora | Espera a que pase la hora |
«El starter no está disponible en este entorno» (tenant.starter_unavailable) |
Este DevLab no ofrece starters | Copia los ficheros de la pestaña Kit |
«Tu equipo no tiene key activa» (tenant.team_unavailable) |
La key se rotó o se revocó con la página abierta | Recarga; si el equipo sigue sin key, pídeselo a Neurologyca |
«Tu organización aún no ha aceptado los Términos de DevLab, así que el starter no puede llevar tu key» (legal.org_terms_required) |
La persona admin de tu organización no ha aceptado los términos | Descárgalo sin la key o pide a la persona admin de tu organización que los acepte |
npm install no descarga @neurologyca/... |
Falta NODE_AUTH_TOKEN o es incorrecto |
Ponlo en tu shell (Instalación) |
npm start se para con bad option: --env-file |
Node anterior a 20.6 | Actualiza Node |