HomenShum/NodeKit

NodeKit Present

Transforme artefatos de desenvolvimento verificados em uma apresentação viva. Trate o deck como uma projeção do registro de mudanças, nunca como uma fonte independente de afirmações.

Leia o contrato de história de mudança antes de criar ou atualizar artefatos de apresentação.

Fluxo de Trabalho

1. Classifique o nível da mudança. Pule decks para trabalho trivial; use um cartão de mudança para uma correção estreita, um mini-deck de 3 a 5 slides para um recurso importante e um deck completo com apêndice para releases ou hackathons.
2. Crie ou atualize changes/<change-id>/change.yaml. Registre público, problema, estado anterior, decisão, alternativas, sistemas afetados, fluxo de trabalho do usuário, requisitos de prova, limitações e nível de apresentação.
3. Capture evidências enquanto o trabalho acontece: screenshots de base e posteriores, commits exatos, identidade de implantação, testes, benchmarks, rastreamentos, artefatos, exportações e falhas conhecidas. Preserve recibos brutos.
4. Construa um índice de evidências. Dê a cada afirmação material um status e IDs de evidência. Rotule afirmações planejadas, inferidas, afirmadas pelo usuário e medidas de forma distinta.
5. Planeje cada slide antes de renderizar. Declare sua função, pergunta do público, conclusão, papel narrativo, visual dominante, IDs de evidência, orçamento de densidade e objetivo da nota do apresentador.
6. Use o transporte NodeSlide instalado nesta ordem: adaptador nativo do repositório, CLI do NodeSlide, MCP do NodeSlide ou API do pacote. Inspecione as capacidades primeiro e nunca presuma que gravações hospedadas, exportação ou aprovação estejam disponíveis.
7. Proponha alterações no deck contra a versão fixada do deck. Valide, compare e aplique através da política do host; não ignore a governança do NodeSlide por conveniência.
8. Verifique cada afirmação material contra o commit ou implantação atual. Atualize screenshots e métricas desatualizadas. Mantenha as limitações visíveis.
9. Exporte o formato editável solicitado e reabra-o. Verifique o deck renderizado, as notas do apresentador, as ligações de origem e qualquer ciclo de ida e volta PPTX.
10. Derive o script de demonstração, seção README, notas de release e texto de submissão da mesma História de Mudança e Índice de Evidências.

Um clipe de demonstração é um walkthrough renderizado, nunca uma gravação de tela

Esta seção existe por causa de uma falha medida. Uma implantação de produção foi verificada 11/11 com um clipe gravado, e o clipe era uma captura bruta do Playwright: sem enquadramento de foco, sem legendas, sem streaming visível ou chamadas de ferramenta, sem slides. As ferramentas para cada um desses itens já existiam e esta skill não nomeou nenhuma delas, então foi feita manualmente de forma ruim em vez de ser bem conduzida.

FeatureClipStudio (feature-walkthrough-gif/) é o pipeline de captura para renderização, e cobre as quatro coisas que uma captura bruta nunca tem:

o que uma captura bruta não tem	o que o pipeline faz
foco no que importa	câmera com zoom para foco, cursor animado deslizando para cada clique com uma ondulação
explicação	legendas por etapa por estado
o trabalho sendo visível	carregamento e streaming capturados AO VIVO — spinner girando, resultados chegando
os internos quando a afirmação depende deles	painéis de evidências JSON/estado brutos

npm run capture   # Playwright dirige o fluxo ao vivo e registra cada estado da UI
npm run studio    # storyboard dos estados capturados
npm run render    # Remotion renderiza o walkthrough
npm run judge     # Gemini assiste à RENDERIZAÇÃO e a avalia

judge-video.mjs é o portão, e é o que deve ser executado antes de considerar um clipe concluído. Ele assiste ao MP4 renderizado contra uma rubrica de anti-herói e retorna defeitos com timestamp em P0/P1/P2 — P0 bloqueia a publicação. Seu próprio cabeçalho declara o ponto: o corte final deixa de ser o único estágio que apenas olhos humanos verificam. Julgue o MP4 em vez do GIF; GIF não é um MIME de vídeo suportado.

Não entre em um loop de polimento de re-renderização sobre P2s que o juiz já aprovou.

Dois eixos, e o segundo é o que falha

judge-video.mjs avalia CRAFT (CRAFT — cursor truth, pacing, legibility, motion) e separadamente avalia COMPREENSÃO (COMPREHENSION), as dez coisas que um espectador deve realmente absorver:

persona · propósito · caso_de_uso · clareza_do_recurso · interação_completa
responsividade · fluxo · resultado · sentido_para_não_especialista · transferência

Eles são ortogonais, e um corte pode ser bem feito e incompreensível. Medido em uma renderização real: craft passou com um veredito de publish, e compreensão marcou 1 em todos os dez — nada ausente, nada explícito, tudo meramente implícito — com o juiz nomeando 0:06 como o segundo em que um não especialista se perdeu ("conceitos de arquitetura de camadas e saídas de log do terminal").

sentido_para_não_especialista é o teste da mãe e BLOQUEIA por conta própria, independentemente dos totais. Um portão que aprova um vídeo que seu próprio juiz diz que ninguém fora da área poderia acompanhar não é um portão. Pontuações uniformes em todos os dez são sinalizadas em vez de calculadas como média, porque "todos 1s" significa tudo implícito e nada declarado, o que é uma constatação e não uma aprovação mediana.

O LOOP É O PADRÃO, não uma verificação final: renderize, julgue, leia o que diz estar faltando, recorte, julgue novamente. Três cortes em um filme o moveram de 10/20 para 13/20 e, mais utilmente, disseram ao criador que a história havia sido construída em torno do momento errado — algo que nenhuma quantidade de auto-revisão havia revelado. Pare quando a compreensão estiver clara e os defeitos restantes forem P2.

NodeSlide para o deck, NodeVideo para evidências em nível de quadro — um quadro apresentado como o produto em execução deve estar vinculado à implantação de onde veio, e presentedAs é o que torna isso verificável.

De onde vêm os vídeos de referência

Mobbin funciona para UI porque é um corpus que você OBSERVA e CITA, nunca copia. O vídeo precisa da mesma disciplina e se divide em dois tipos, que não são intercambiáveis:

Referências de FLUXO — o que um produto real realmente faz, passo a passo. Page Flows é o análogo direto: jornadas de usuário gravadas em vez de screenshots, 20.000+ aplicativos, organizados por tarefa — cadastro, upgrade, cancelar — incluindo a caixa de diálogo de consentimento, a validação de campo, o estado vazio e a tela de sucesso. Seu próprio enquadramento é a regra do anti-herói declarada do outro lado: Mobbin mostra o destino, Page Flows mostra a viagem. ScreensDesign cobre onboarding e paywalls com sinais de receita anexados. Use estes para responder "que estados um fluxo real deste tipo contém, e quais estou pulando?"

Referências de CRAFT — como um filme de lançamento é construído. Comece pelo YouTube. O juiz lê uma URL do YouTube diretamente — verificado: Gemini assistiu a um e descreveu seus segundos de abertura e duração a partir da URL sozinha, sem download. Portanto, uma referência é CITADA, nunca copiada, o que dissolve completamente a questão de licenciamento e torna o localizador uma URL mais um timestamp:

O agente constrói seu próprio corpus em vez de esperar receber um. yt-dlp PESQUISA no YouTube e lê metadados; nada é baixado, e Gemini assiste à URL:

node find-references.mjs "Raycast product demo" "Linear product demo"   # pesquisar, triar, observar
node judge-video.mjs out/demo.mp4                                       # corpus usado automaticamente
node judge-video.mjs out/demo.mp4 --no-reference                        # optar por não usar

find-references.mjs faz a triagem ANTES de gastar tokens: qualquer coisa acima de 180s é rejeitada por padrão como a forma errada e o custo errado para um walkthrough curto, com o motivo impresso. Medido em uma execução real — uma demonstração interna de 39s custou 3.9k tokens de prompt, uma de 18 minutos custou 102k. Em seguida, escreve references/video/<id>.json: fatos atômicos com timestamp (0:07 motion — teclas ficam verdes ao pressionar), hookSeconds, statesShown, whatToSteal e whatNotToSteal, além de uma lista notRun para qualquer coisa que não pôde determinar. Fatos, nunca adjetivos — um fato pontua um candidato, um adjetivo não.

O veredito ganha um bloco reference — singleMoment, statePacing, motionPurpose, whatToSteal e whatNotToSteal — com um timestamp obrigatório para cada afirmação sobre a referência. Todo filme de lançamento de produto que vale a pena estudar já está no YouTube e é a fonte primária; as bibliotecas curadas abaixo são uma camada de descoberta sobre ele, útil para ENCONTRAR candidatos em vez de assisti-los.

O custo é real: uma referência de 18 minutos mediu 102k tokens de prompt. Prefira um corte de 30 a 90 segundos e passe no máximo duas ou três referências.

FlowJam é uma coleção de vídeos de SaaS e lançamento de produtos curada manualmente; a biblioteca da Tella e as análises da Vidico publicam exemplos com a fundamentação anexada. Use estes para ritmo, o momento único e onde o movimento está fazendo trabalho versus decorando.

Não cole nenhum dos tipos na rubrica como prosa. Registre-os da mesma forma que uma observação do Mobbin é registrada: um fato atômico, com um locatorDescription que para vídeo é um TIMESTAMP, citado para a URL de origem. A afirmação é "aos 0:12 o estado de carregamento é mantido por 1,4s antes do resultado", não "o ritmo deles é bom". Uma regra derivada de uma observação com timestamp pode ser pontuada; um adjetivo não.

Licença: observe e atribua, nunca re-hospede. licenceMode no esquema de observação é um valor único enumerado de propósito — estendê-lo para uma nova classe de fonte é uma revisão de licença e uma edição de esquema deliberada, não uma string digitada.

Um filme de lançamento é dirigido, depois renderizado — o contrato de vídeo de lançamento

Tudo acima julga um corte que já existe. Um filme de LANÇAMENTO falha antes disso: é construído em torno do momento errado, ou entregue após o lançamento, e nenhum loop de juiz pode recuperar nenhum dos dois. Estudado ao vivo no Motion Studio (filmes de lançamento para startups de nível YC): o processo deles é Direção → Primeiro rascunho → Revisões → Entrega, e "um diretor humano faz todas as chamadas de gosto". Essa ordenação é o produto. nodekit launch-video carrega isso como um contrato recusável, para que um agente de codificação orientado percorra os estágios em vez de pular para npm run render:

nodekit launch-video declare --application <slug> --out launch-video.json
# 1 BRIEF      preencher produto, história (palavras do interessado), público, launchDate, canais
# 2 DIREÇÃO    singleMoment, beats ordenados, referências via find-references.mjs (fatos com timestamp,
#              nunca adjetivos), durationTargetSeconds ≤ 180 — então um HUMANO aprova
# 3 RASCUNHOS  captura → studio → render (FeatureClipStudio ou NodeVideo), judge-video.mjs no
#              MP4, registrar o ciclo: corte, pontuações do juiz, anotaçõesHumanas, disposição
# 4 ENTREGA    finalCut + comprovanteDoJuiz + aprovação humana, deliveredAt ANTES DE launchDate
nodekit launch-video check --contract launch-video.json   # recusa em cada saída de estágio

O que a verificação recusa, e por que cada recusa existe:

• rascunhos antes de uma direção aprovada — o primeiro corte alinha uma direção, não a descobre; uma renderização feita antes da direção voltar é a conta da revisão.
• uma afirmação de referência sem timestamp — "o ritmo deles é bom" não pode ser pontuado; "aos 0:12 o estado de carregamento segura por 1,4s" pode.
• um ciclo final falhando sentido_para_não_especialista — o teste da mãe bloqueia a entrega sozinho, mesma regra do loop do juiz acima; o contrato torna isso uma saída de estágio em vez de um conselho.
• deliveredAt depois de launchDate — um filme de lançamento entregue após o lançamento é uma retrospectiva.
• entrega sem uma aprovação humana — o juiz é consultivo; a chamada de gosto é uma pessoa.

O loop do juiz permanece o loop interno do estágio 3 exatamente como descrito acima. O contrato adiciona o que o loop sozinho nunca segurou: os estágios em ordem, o humano nos dois portões de gosto e a data.

Pista paralela

Para uma implementação grande, execute o trabalho de apresentação como uma pista de leitura principalmente ao lado da construção e do QA. Esboce o problema e a arquitetura cedo; substitua placeholders apenas por evidências verificadas de portões posteriores. Bloqueie o release apenas para afirmações não suportadas, prova necessária ausente, evidência desatualizada ou uma exportação quebrada.

Linguagem de conclusão

• Diga rascunhado quando os planos de slide existirem.
• Diga vinculado-a-evidências quando cada afirmação material resolver para evidências atuais.
• Diga exportação-verificada somente após a saída solicitada reabrir com sucesso.
• Diga pronto-para-release somente quando a prova do aplicativo e a prova da apresentação passarem.

Não transforme um teste unitário verde em uma afirmação de produção, um HTTP 200 em prova de navegador ou um julgamento de modelo consultivo em um veredito autoritativo.