nolan

O que nolan faz?

Um diretor não aperta o play e espera. Ele storyboarda os planos, enquadra cada um e grava tomadas completas. nolan faz isso por demos de software: transforma uma funcionalidade em um storyboard, dirige seu app real na tela, narra cada passo como um gerente de produto mostrando o produto a um usuário e captura um vídeo limpo por cena.

O resultado é uma demonstração, não um teste de fumaça — o tipo de clipe que você colocaria em uma landing page ou enviaria a um cliente, onde um espectador de primeira viagem entende tanto o que está acontecendo quanto por que é importante.

Quando usar esta skill

Use-a sempre que o trabalho real for "produzir um vídeo assistível deste produto fazendo algo, para uma pessoa que nunca o viu." Isso inclui clipes de lançamento, vitrines de funcionalidades, vídeos herói de landing page, walkthroughs de integração e GIFs de notas de versão.

Não a utilize para testar um fluxo — isso é um teste de ponta a ponta, e deve ser conciso e sem cabeçalho. nolan otimiza para o oposto: legibilidade, ritmo e narração para uma audiência humana.

O fluxo de trabalho — três estágios

Estágio	Você pergunta…	nolan produz	Referência
🎬 Storyboard	"planeje uma demo da funcionalidade X"	Um storyboard cena a cena (JSON): cartões de título, legendas, os cliques/digitações exatos e o que esperar	reference/storyboard.md
🎥 Gravar	"grave-a"	Um .webm por cena, conduzido ao vivo contra o app em execução com sobreposição de cartões de título + legendas do tipo legenda	reference/recording.md
✨ Polir	"deixe isso assistível"	Uma tomada revisada e regravada: ritmo corrigido, ações completas, legendas legíveis, enquadramento corrigido	reference/polish.md

Os estágios se encadeiam: storyboard → gravar → assistir → polir → regravar. O storyboard é a fonte da verdade; a gravação é determinística a partir dele.

As quatro disciplinas (innegociáveis, todos os vídeos)

Estas são o que separa uma demo de uma captura de tela. Elas não são opcionais.

1. Voz de gerente de produto, não um teste de fumaça. Narre o valor para o usuário — o que isso permite que ele faça e por que é bom — nunca a mecânica do teste. Cada legenda soa como um PM guiando um cliente pelo produto. Veja reference/pm-voice.md.

2. Conteúdo cotidiano e relacionável na tela. Apenas entradas que o público geral já entende vão para a interface — perguntas normais, exemplos do mundo real ("compre leite de aveia", "um bilhete de agradecimento para um colega"). Nunca jargões nichados, codinomes internos ou conceitos "alienígenas" que o espectador precisa decodificar. Acessibilidade em primeiro lugar.

3. Mostre, depois diga. Toda cena abre com um cartão de título em tela cheia (produto + nome da cena) e carrega legendas do tipo legenda incorporadas (um banner superior) que narram cada passo enquanto acontece, para que nenhum espectador se perca. Veja reference/captions.md.

4. Tomadas completas no app real. Dirija o produto real ao vivo — digitação visível e em ritmo humano e cliques reais — e espere cada ação terminar completamente antes de continuar, depois pause para que seja legível. Nunca corte uma resposta ou faça transição no meio do fluxo. A duração serve à completude.

Procedimento padrão

1. Escopo da demo. Qual produto, qual(is) funcionalidade(s), em qual URL ele é servido e quem é o público? Confirme que o app está em execução e acessível (nolan filma um app ao vivo; ele não simula um).
2. Storyboard. Elabore um storyboard.json — uma cena por ideia, cada uma com um cartão de título, passos ordenados (digitar / clicar / selecionar / esperar) e legendas em voz de PM. Use assets/storyboard-template.json como modelo. Mantenha os prompts genéricos (§2).
3. Teste seco dos seletores. Confirme que os placeholders / papéis / texto que o storyboard almeja realmente existem no DOM antes de uma filmagem completa (um seletor errado desperdiça uma tomada inteira). reference/recording.md cobre a seleção robusta.
4. Gravar. Execute scripts/record.py storyboard.json [scene ...]. Ele injeta a sobreposição de legendas/cartão de título, dirige cada cena, espera a conclusão e salva um .webm por cena no out_dir do storyboard.
5. Assista e polir. Verifique cada disciplina contra reference/polish.md — algo está cortado, alguma legenda usa jargão, a digitação parece humana, toda ação está completa? Corrija o storyboard e regrave apenas as cenas afetadas.
6. Entregar. Informe onde os arquivos foram parar, seus tamanhos/durações e uma descrição de uma linha por cena. Ofereça um frame de pôster ou GIF se for útil.

Configuração que nolan espera

• Python + Playwright (pip install playwright && playwright install chromium). scripts/record.py usa a API síncrona e record_video_dir para capturar .webm.
• Um app em execução em uma URL que a máquina possa acessar (servidor de desenvolvimento local ou um ambiente implantado que você tem permissão para filmar).
• Dados de demonstração realistas e não sensíveis carregados no app — veja a disciplina §2 e a nota sobre dados em SECURITY.md. Nunca filme dados reais de clientes ou segredos.
• Opcional — narração falada. Por padrão, a demo é silenciosa (as legendas carregam o peso). Para adicionar uma narração com som humano, adicione um bloco voice ao storyboard e linhas vo aos passos; isso requer ffmpeg (brew install ffmpeg) mais um provedor de TTS — ElevenLabs / OpenAI / Deepgram (chave de API, mais humano), Piper (offline, código aberto), macOS say (gratuito, robótico) ou qualquer ferramenta via um template command. Veja reference/narration.md.

Veja reference/recording.md para os detalhes do harness, a técnica de sobreposição e a referência dos passos do storyboard.

Adicionar narração (opcional)

A narração está desligada a menos que o storyboard tenha um bloco voice. Quando alguém pedir áudio / uma narração / que soe "humano":

1. Pergunte qual provedor. Para áudio verdadeiramente humano, use um provedor na nuvem e confirme que o usuário tem (ou adicionará) a chave de API: ELEVENLABS_API_KEY, OPENAI_API_KEY ou DEEPGRAM_API_KEY. Eles também podem apontar command para sua própria ferramenta de TTS.
2. Se não tiver chave, ofereça as alternativas gratuitas/offline (Piper para qualidade razoável, macOS say para zero-configuração-mas-robótico) — ou "provider": "auto" para usar o melhor disponível.
3. Se não quiser nenhum, deixe voice de fora (ou "provider": "none") — o vídeo grava silencioso, exatamente como antes.

Em seguida, escreva linhas vo na mesma voz de PM das legendas e grave normalmente; record.py sintetiza e multiplexa o áudio por cena. Detalhes: reference/narration.md.

Princípios de saída

• Um vídeo por cena, nomeado NN-slug.webm, para que as cenas possam ser regravadas de forma independente.
• Lidere sua entrega com o resultado assistível (o que cada clipe mostra), depois a mecânica (caminhos, tamanhos, como regravar).
• Prefira várias cenas curtas e completas a um clipe longo — mais fácil de regravar e de reutilizar.
• Se uma tomada teve que ser interrompida ou uma legenda é um placeholder, diga — um honesto "a cena 3 ainda precisa de uma regravação" é melhor do que enviar uma demo cortada.