nolan

¿Qué hace nolan?

Un director no aprieta "grabar" y espera que salga bien. Primero crea un storyboard, encuadra cada plano y rueda tomas completas. nolan hace lo mismo con las demos de software: convierte una funcionalidad en un storyboard, controla tu aplicación real en pantalla, narra cada paso como un product manager que le muestra el producto a un usuario y captura un video limpio por escena.

El resultado es una demo, no una prueba de humo — el tipo de clip que pondrías en una landing page o enviarías a un cliente, donde un espectador que ve el producto por primera vez entiende tanto qué está pasando como por qué es importante.

Cuándo usar esta habilidad

Úsala siempre que la tarea real sea "producir un video visible de este producto haciendo algo, para una persona que nunca lo ha visto". Esto incluye clips de lanzamiento, demostraciones de funcionalidades, videos principales de landing pages, tutoriales de onboarding y GIFs para notas de versión.

No la uses para probar un flujo — eso es una prueba end-to-end, y debe ser concisa y sin interfaz gráfica. nolan optimiza para lo opuesto: legibilidad, ritmo y narración para una audiencia humana.

El flujo de trabajo — tres etapas

Etapa	Preguntas…	nolan produce	Referencia
🎬 Storyboard	"planifica una demo de la función X"	Un storyboard escena por escena (JSON): tarjetas de título, leyendas, los clics/escritura exactos y qué esperar	reference/storyboard.md
🎥 Grabar	"grábalo"	Un .webm por escena, ejecutado en vivo contra la aplicación en ejecución con tarjetas de título superpuestas + leyendas de subtítulos	reference/recording.md
✨ Pulir	"haz que sea visible"	Una toma revisada y regrabada: ritmo corregido, acciones completas, leyendas legibles, encuadre corregido	reference/polish.md

Las etapas se encadenan: storyboard → grabar → verlo → pulir → regrabar. El storyboard es la fuente de verdad; la grabación es determinista a partir de él.

Las cuatro disciplinas (no negociables, en cada video)

Esto es lo que diferencia una demo de una captura de pantalla. No son opcionales.

1. Voz de product manager, no de prueba de humo. Narra el valor para el usuario — qué le permite hacer y por qué es bueno — nunca los mecanismos de prueba. Cada leyenda se lee como un PM guiando a un cliente por el producto. Consulta reference/pm-voice.md.

2. Contenido cotidiano y comprensible en pantalla. Solo se introducen en la UI entradas que un público general ya entiende: preguntas normales, ejemplos del mundo real ("compra leche de avena", "una nota de agradecimiento a un compañero"). Nunca jerga técnica, nombres en clave internos o conceptos "alienígenas" que el espectador tenga que descifrar. La accesibilidad es lo primero.

3. Mostrar, luego decir. Cada escena comienza con una tarjeta de título a pantalla completa (producto + nombre de la escena) y lleva leyendas de subtítulos incrustadas (un banner superior) que narran cada paso a medida que ocurre, para que ningún espectador se pierda nunca. Consulta reference/captions.md.

4. Tomas completas sobre la aplicación real. Controla el producto real en vivo: escritura visible a ritmo humano y clics reales, y espera a que cada acción termine por completo antes de pasar a la siguiente, luego mantén la pausa para que sea legible. Nunca cortes una respuesta ni hagas transiciones a medio camino. La duración está al servicio de la integridad.

Procedimiento estándar

1. Delimitar la demo. ¿Qué producto, qué funcionalidad(es), en qué URL se sirve y quién es la audiencia? Confirma que la aplicación se está ejecutando y es accesible (nolan graba una aplicación en vivo; no simula una).
2. Storyboard. Redacta storyboard.json — una escena por idea, cada una con una tarjeta de título, pasos ordenados (escribir / hacer clic / seleccionar / esperar) y leyendas en voz de PM. Usa assets/storyboard-template.json como plantilla. Mantén los mensajes genéricos (§2).
3. Prueba en seco de los selectores. Confirma que los marcadores / roles / texto a los que apunta el storyboard realmente existen en el DOM antes de una grabación completa (un selector incorrecto desperdicia toda una toma). reference/recording.md cubre la selección robusta.
4. Grabar. Ejecuta scripts/record.py storyboard.json [escena ...]. Inyecta la superposición de leyenda/tarjeta de título, controla cada escena, espera a que termine y guarda un .webm por escena en el out_dir del storyboard.
5. Verlo y pulir. Revisa cada disciplina con reference/polish.md — ¿hay algo cortado?, ¿alguna leyenda es jerga?, ¿la escritura se lee como humana?, ¿cada acción está completa? Corrige el storyboard y vuelve a grabar solo las escenas afectadas.
6. Entregar. Informa dónde están los archivos, sus tamaños/duraciones y una descripción de una línea por escena. Ofrece un fotograma de póster o un GIF si es útil.

Configuración que espera nolan

• Python + Playwright (pip install playwright && playwright install chromium). scripts/record.py usa la API síncrona y record_video_dir para capturar .webm.
• Una aplicación en ejecución en una URL a la que la máquina pueda acceder (servidor de desarrollo local o un entorno desplegado donde tengas permiso para grabar).
• Datos de demostración realistas y no sensibles cargados en la aplicación — consulta la disciplina §2 y la nota sobre datos en SECURITY.md. Nunca grabes datos reales de clientes ni secretos.
• Opcional — narración hablada. Por defecto, la demo es silenciosa (las leyendas la transmiten). Para agregar una voz en off con sonido humano, añade un bloque voice al storyboard y líneas vo a los pasos; esto necesita ffmpeg (brew install ffmpeg) además de un proveedor de TTS: ElevenLabs / OpenAI / Deepgram (clave de API, la más humana), Piper (fuera de línea, código abierto), say de macOS (gratuito, robótico) o cualquier herramienta mediante una plantilla command. Consulta reference/narration.md.

Consulta reference/recording.md para los detalles del arnés de grabación, la técnica de superposición y la referencia de pasos del storyboard.

Añadir narración (opcional)

La narración está desactivada a menos que el storyboard tenga un bloque voice. Cuando alguien pida audio / una voz en off / que "suene humano":

1. Pregunta qué proveedor. Para audio verdaderamente humano, usa un proveedor en la nube y confirma que el usuario tiene (o añadirá) la clave de API: ELEVENLABS_API_KEY, OPENAI_API_KEY o DEEPGRAM_API_KEY. También pueden apuntar command a su propia herramienta de TTS.
2. Si no tiene clave, ofrece las alternativas gratuitas/fuera de línea (Piper para buena calidad, say de macOS para configuración cero pero robótico) — o "provider": "auto" para usar el mejor disponible.
3. Si no quiere ninguna, deja fuera voice (o "provider": "none") — el video se graba en silencio, exactamente como antes.

Luego escribe líneas vo con la misma voz de PM que las leyendas y graba como de costumbre; record.py sintetiza y multiplexa el audio por escena. Detalles: reference/narration.md.

Principios de salida

• Un video por escena, con el nombre NN-slug.webm, para que las escenas se puedan regrabar de forma independiente.
• Encabeza tu entrega con el resultado visible (qué muestra cada clip), luego los aspectos técnicos (rutas, tamaños, cómo regrabar).
• Prefiere varias escenas cortas y completas a un único clip largo — es más fácil regrabarlas y reutilizarlas.
• Si una toma tuvo que interrumpirse o una leyenda es un marcador de posición, dilo — es mejor un "la escena 3 aún necesita una regrabación" honesto que enviar una demo cortada.