primocode 10.17.1 → 10.19.0

package/lib/kits.js

@@ -0,0 +1,1045 @@
+/**
+ * kits.js — os kits de estilo de motion: cada um é uma skill que a IA carrega.
+ *
+ *   "No primeiro pedido de motion, o PrimoCode abre a tela de escolha de estilo
+ *    que já existe, e as escolhas voltam pro PrimoCode. Se a pessoa mandar uma
+ *    referência, abre a tela de referência. O PrimoCode manda o roteiro, o nome
+ *    do vídeo e o estilo escolhido, e só começa depois que a pessoa confirma.
+ *    Se o estilo pedido não existe, ele cria." (Joel, 26/10)
+ *
+ * Um kit (kits/<slug>/, formato no kits/KITS.md) não é template: tem a skill
+ * (SKILL.md), as regras em números, os elementos Remotion com props, os sons, a
+ * receita de batidas e um exemplo de plano. A IA monta o plano de cenas batida
+ * por batida (nunca troca os textos da demo) e escreve o roteiro; a `Montagem` do kit só executa.
+ *
+ * ── QUEM DECIDE ──────────────────────────────────────────────────────────
+ * A IA. O menu (uma linha por kit: slug, nome, quando) vai na frente do pedido
+ * e ela escolhe; o regex de "parece motion" só decide se o menu vai inteiro ou
+ * numa linha só (economia de token), nunca qual kit.
+ *
+ * ── O CAMINHO ────────────────────────────────────────────────────────────
+ *   primocode kit menu         no primeiro motion abre a tela de estilos (lib/estudio/kits-tela.js: os kits no
+ *                              carrossel da tela de gosto) e devolve o menu com o kit que a pessoa escolheu lá
+ *   primocode kit ver <slug>   a skill inteira: SKILL.md, regras, receita, props dos elementos, plano de exemplo
+ *   primocode kit referencia   abre a tela de referências (a do /taste referencias) e devolve o que ela mediu
+ *   primocode kit montar …     o esqueleto pela receita do kit (lib/kits-plano.js): batidas, tempos, sons; sem conteúdo
+ *   primocode kit batida <n>   a IA monta UMA batida com os elementos do kit e o conteúdo da pessoa; ele confere e conserta
+ *   primocode kit plano …      confere o plano montado e devolve o cartão: roteiro + nome do vídeo + estilo. A IA mostra e PARA.
+ *   primocode kit fazer        só num pedido seguinte (a pessoa respondeu): voz (VoiceStudio primeiro) + render
+ *   primocode kit criar …      estilo que não existe: um kit novo em ~/.primocode/kits/<slug>, no formato do KITS.md
+ *   primocode kit preview <s>  o preview.mp4 do kit, renderizado aqui na primeira vez (o pacote só leva a capa)
+ *   primocode kit galeria      a tela de estilos (capa + preview + nome); a escolha volta e vira o padrão
+ *
+ * O run_shell roda `primocode kit …` aqui dentro (lib/tools.js), não num filho:
+ * a tela de estilos no app sai pela linha de protocolo do stderr DESTE processo.
+ *
+ * ── A CONFIRMAÇÃO ────────────────────────────────────────────────────────
+ * O `plano` grava o turno (PRIMOCODE_TURNO, um por pedido da pessoa, lib/act.js).
+ * O `fazer` recusa no mesmo turno: só passa depois que a pessoa respondeu.
+ * Teste: PRIMOCODE_KIT_CONFIRMAR=1 aceita sozinho.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn, spawnSync } = require('child_process');
+
+const RAIZ = path.join(__dirname, '..', 'kits');
+const ESTUDIO = path.join(RAIZ, 'estudio');
+const FAMILIAS = ['SaaS e tecnologia', 'Tipografia em movimento', 'Retrô', 'Feito à mão', '3D e abstrato', 'Redes sociais', 'Marca e evento'];
+const REGRAS = ['tipografia.md', 'cor.md', 'movimento.md', 'som.md', 'ritmo.md', 'area-segura.md'];
+const MIDIA = /\.(png|jpe?g|webp|gif|svg|mp4|webm|mov|mp3|wav|m4a)$/i;
+const FPS = 30;
+
+const casa = (home = os.homedir()) => path.join(home, '.primocode', 'kits');
+const baseEstudio = (home = os.homedir()) => path.join(home, '.primocode', 'kits-estudio');
+const semAcento = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+const slugar = (s) => semAcento(s).replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+
+// ── o turno: um por pedido da pessoa ─────────────────────────────────────
+
+let turnoLocal = `${process.pid}-${Date.now().toString(36)}`;
+/** Chamado no começo de cada pedido da pessoa (lib/act.js). Vai no env: o `primocode kit` num filho herda. */
+function novoTurno() {
+    turnoLocal = crypto.randomBytes(6).toString('hex');
+    process.env.PRIMOCODE_TURNO = turnoLocal;
+    return turnoLocal;
+}
+const turnoAtual = () => process.env.PRIMOCODE_TURNO || turnoLocal;
+const autoConfirma = (env = process.env) => env.PRIMOCODE_KIT_CONFIRMAR === '1';
+
+// ── ler os kits ──────────────────────────────────────────────────────────
+
+/** frontmatter simples: `chave: valor` e listas com `- item` (o mesmo leitor do repo dos kits). */
+function lerFrontmatter(texto) {
+    const m = String(texto || '').replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return null;
+    const out = {}; let lista = null;
+    for (const linha of m[1].split('\n')) {
+        const item = linha.match(/^\s+-\s+(.*)$/);
+        if (item && lista) { out[lista].push(item[1].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '')); continue; }
+        const kv = linha.match(/^([a-z_]+):\s*(.*)$/);
+        if (!kv) continue;
+        const v = kv[2].replace(/\s+#.*$/, '');
+        if (v === '') { out[kv[1]] = []; lista = kv[1]; } else { out[kv[1]] = v.replace(/^["']|["']$/g, ''); lista = null; }
+    }
+    return out;
+}
+
+function lerKit(pasta, origem, extra = {}) {
+    let fm = null;
+    try { fm = lerFrontmatter(fs.readFileSync(path.join(pasta, 'SKILL.md'), 'utf8')); } catch { return null; }
+    if (!fm) return null;
+    const slug = fm.slug || path.basename(pasta);
+    const capa = path.join(pasta, 'capa.jpg');
+    return {
+        slug, nome: extra.nome || fm.nome || slug, familia: fm.familia || extra.familia || '',
+        descricao: fm.descricao || extra.descricao || '',
+        quando: Array.isArray(fm.quando) ? fm.quando : [], nao_serve: Array.isArray(fm.nao_serve) ? fm.nao_serve : [],
+        versao: Number(fm.versao) || 1, pasta, origem, capa: fs.existsSync(capa) ? capa : null,
+        ...(fm.base ? { base: fm.base } : {}),
+    };
+}
+
+/** Os kits do pacote (kits/manifest.json) e os que a pessoa criou (~/.primocode/kits/<slug>). */
+function listar({ home, raiz = RAIZ } = {}) {
+    const out = [];
+    let manifesto = [];
+    try { manifesto = JSON.parse(fs.readFileSync(path.join(raiz, 'manifest.json'), 'utf8')); } catch { /* pacote sem kits */ }
+    for (const m of manifesto) {
+        if (!m || !m.slug || m.status === 'rascunho') continue;
+        const k = lerKit(path.join(raiz, m.slug), 'pacote', m);
+        if (k) out.push(k);
+    }
+    const dela = casa(home);
+    let pastas = [];
+    try { pastas = fs.readdirSync(dela, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'previews'); } catch { /* nenhum criado */ }
+    for (const d of pastas) {
+        const k = lerKit(path.join(dela, d.name), 'seu');
+        if (k && !out.some((x) => x.slug === k.slug)) out.push(k);
+    }
+    return out;
+}
+
+/** O kit pelo slug (ou começo do slug, ou nome sem acento). */
+function achar(nome, op = {}) {
+    const alvo = slugar(nome);
+    if (!alvo) return null;
+    const todos = op.todos || listar(op);
+    return todos.find((k) => k.slug === alvo) || todos.find((k) => slugar(k.nome) === alvo)
+        || todos.find((k) => k.slug.startsWith(alvo)) || null;
+}
+
+// ── o menu pra IA ────────────────────────────────────────────────────────
+
+const linhaDoMenu = (k) => `- ${k.slug} · ${k.nome.split(' · ')[0]}${k.origem === 'seu' ? ' (seu)' : ''}: ${(k.quando.length ? k.quando.slice(0, 2) : [k.descricao]).join('; ').replace(/\s+/g, ' ').replace(/"/g, '')}`.slice(0, 92);
+
+/** "estilo apple", "estilo papel recortado": a palavra depois de "estilo" que é o slug ou o nome de um kit. Só sugere. */
+function kitCitado(texto, todos) {
+    const m = semAcento(texto).match(/estilos?\s+(?:de\s+|do\s+|da\s+)?([a-z0-9-]+(?:\s+[a-z0-9-]+)?)/);
+    if (!m) return null;
+    for (const cand of [m[1], m[1].split(/\s+/)[0]]) {
+        const s = slugar(cand);
+        const k = todos.find((x) => x.slug === s) || todos.find((x) => slugar(x.nome.split(' · ')[0]) === s) || todos.find((x) => x.slug.startsWith(s + '-'));
+        if (k) return { k, palavra: cand };
+    }
+    return null;
+}
+
+/** O menu compacto: uma linha por kit. É a IA que escolhe por ele. */
+function menuParaIA(op = {}) {
+    const todos = op.todos || listar(op);
+    if (!todos.length) return '';
+    return todos.map(linhaDoMenu).join('\n');
+}
+
+/* Só SUGERE que o pedido é de motion, pra mandar o menu inteiro em vez de uma linha. Não escolhe kit nem caminho. */
+const PARECE_MOTION = /(^|[^a-z])(motion|motions|animad[oa]s?|animacao|animacoes|vinheta|reels?|teaser|intro|explainer|lancamento|video|videos|estilo apple)([^a-z]|$)/;
+const pareceMotion = (texto) => PARECE_MOTION.test(semAcento(texto));
+
+const CAMINHO = [
+    '1) run_shell "primocode kit menu": no primeiro motion abre a tela de estilos e devolve o kit que a pessoa escolheu lá.',
+    '2) Escolha o kit que casa com o pedido e o gosto (você decide; o pedido explícito da pessoa ganha).',
+    '3) "primocode kit montar --kit <slug> --produto \\"<o que é: app de celular, curso, garrafa…>\\" [--marca \\"<nome>\\"] [--segundos 15] [--arquivos logo.png,foto.jpg] [--cores \\"#hex,#hex\\"]": o esqueleto do vídeo pela receita do kit (batidas, tempos, sons) e o formulário da batida 1.',
+    '4) Uma batida por vez: "primocode kit batida <n> --camadas \'[{\\"elemento\\":\\"…\\",\\"props\\":{…}}]\'". Você MONTA cada batida com os elementos do kit e o conteúdo DA PESSOA (texto, produto, logo, fotos, cores); ele confere, conserta e devolve a próxima. Texto, produto ou arquivo da demo do kit é barrado.',
+    '5) Escreva o roteiro.md (o que o vídeo diz, cena a cena) e rode "primocode kit plano --kit <slug> --nome \\"<nome do vídeo>\\" --roteiro roteiro.md [--fala \\"o texto da narração\\"]". Devolve o cartão (roteiro + nome + estilo): mostre à pessoa e TERMINE a resposta perguntando se pode começar.',
+    '6) Com o sim dela (no pedido seguinte): "primocode kit fazer". Confira os quadros que ele devolve.',
+    'Ela mandou ou citou um vídeo de referência? "primocode kit referencia" abre a tela de referências.',
+    'O estilo pedido não existe? "primocode kit criar --nome \\"<nome>\\" --descricao \\"<como é>\\" --base <slug mais parecido> [--ref <vídeo>]" e use o kit novo.',
+    'Nenhum kit serve e ela não quer estilo novo: o estudio_motion continua valendo.',
+].join('\n');
+
+/**
+ * O que vai na frente do pedido (lib/act.js). Pedido com cara de motion: o caminho + o menu inteiro;
+ * o resto: uma linha que lembra que os kits existem. Nos dois casos quem decide é a IA.
+ */
+function cabecaDoPedido(texto, op = {}) {
+    const todos = op.todos || listar(op);
+    if (!todos.length) return '';
+    // um vídeo esperando o sim nesta pasta: é fato, não palpite — a IA lê a resposta da pessoa e decide
+    const pend = op.projectDir ? lerPendente(op.projectDir) : null;
+    if (pend && pend.kit) {
+        return `[VÍDEO ESPERANDO O SIM DA PESSOA] No pedido anterior você mostrou o cartão de "${pend.nome}" (kit ${pend.kit}, ${Math.round((pend.plano && pend.plano.duracao || 0) / FPS)} s) e perguntou se podia começar. O pedido abaixo é a resposta dela.\n`
+            + '- Se ela confirmou: rode run_shell "primocode kit fazer" (o plano, o roteiro e o estilo já estão guardados; NÃO use estudio_plano, estudio_render nem estudio_motion pra este vídeo). Depois confira os quadros que ele devolve.\n'
+            + '- Se ela pediu mudança: ajuste e rode "primocode kit plano" de novo, mostrando o cartão novo.\n'
+            + '- Se é outro assunto: siga o pedido.';
+    }
+    // um vídeo montado pela metade nesta pasta (o pedido anterior parou no meio): segue da batida que falta
+    const mont = op.projectDir ? lerMontagem(op.projectDir) : null;
+    if (mont && mont.kit) {
+        let pl = null;
+        try { pl = JSON.parse(fs.readFileSync(path.join(op.projectDir, 'motion', 'plano.json'), 'utf8')); } catch { /* sem plano */ }
+        const falta = pl && Array.isArray(pl.cenas) ? pl.cenas.map((c, i) => (c.falta ? i + 1 : 0)).filter(Boolean) : [];
+        if (falta.length && pl.kit === mont.kit) {
+            let form = '';
+            try { const k = achar(mont.kit, op); const P = require('./kits-plano.js'); if (k) form = P.formulario(P.contexto(k, op.projectDir, mont.pessoa || {}), pl, falta[0]); } catch { /* sem formulário */ }
+            return `[VÍDEO SENDO MONTADO NESTA PASTA] Kit ${mont.kit}, produto "${(mont.pessoa && mont.pessoa.produto) || '?'}": ${pl.cenas.length - falta.length} de ${pl.cenas.length} batidas prontas em motion/plano.json; faltam ${falta.join(', ')}.\n`
+                + `- Se o pedido abaixo continua esse vídeo (ou confirma): MANDE já as camadas da batida ${falta[0]} (o formulário está aqui embaixo) com "primocode kit batida ${falta[0]} --camadas '[…]'" e siga batida por batida; depois roteiro.md + "primocode kit plano". NÃO use estudio_motion pra ele.\n`
+                + '- Se pediu outro vídeo: "primocode kit montar …" de novo começa do zero. Se é outro assunto: siga o pedido.'
+                + (form ? `\n\n${form}` : '');
+        }
+    }
+    if (!pareceMotion(texto)) {
+        return `[estilos de motion] ${todos.length} kits de estilo prontos (${todos.slice(0, 6).map((k) => k.nome.split(' · ')[0]).join(', ')}…). Se o pedido for um vídeo de motion, rode "primocode kit menu"; você decide.`;
+    }
+    const citado = kitCitado(texto, todos);
+    const dica = citado ? `\nO pedido cita o estilo "${citado.palavra}": é o kit ${citado.k.slug} (${citado.k.nome}). Pedido de motion com kit vai pelo caminho abaixo (montar + batidas), não pelo estudio_motion.` : '';
+    return `[estilos de motion: você decide] Há ${todos.length} kits de estilo (cada um é uma skill: regras em números, elementos Remotion, sons). Para um motion:\n${CAMINHO}${dica}\n\nOs kits:\n${menuParaIA({ todos })}`;
+}
+
+// ── a skill de um kit ────────────────────────────────────────────────────
+
+/** Os blocos `export type X = …` de um .tsx, com as chaves equilibradas. */
+function tiposDe(codigo) {
+    const out = [];
+    const re = /export (?:type|interface) \w+[^=\n{]*=?\s*/g;
+    let m;
+    while ((m = re.exec(codigo))) {
+        let i = m.index + m[0].length, nivel = 0, fim = -1;
+        for (; i < codigo.length; i++) {
+            const ch = codigo[i];
+            if (ch === '{' || ch === '(' || ch === '[') nivel++;
+            else if (ch === '}' || ch === ')' || ch === ']') nivel--;
+            else if ((ch === ';' || ch === '\n') && nivel <= 0) { fim = i; break; }
+        }
+        out.push(codigo.slice(m.index, fim < 0 ? codigo.length : fim + (codigo[fim] === ';' ? 1 : 0)).trim());
+        re.lastIndex = fim < 0 ? codigo.length : fim;
+    }
+    return out;
+}
+
+function lerSe(arq) { try { return fs.readFileSync(arq, 'utf8'); } catch { return ''; } }
+
+/* O resultado de uma ferramenta chega ao modelo cortado em ~6 mil caracteres (summarizeForModel, lib/act.js):
+   a skill de um kit (20 mil) vai em partes, cada uma cabendo inteira. */
+const TETO_PARTE = 4700;
+function cortar(texto, teto = TETO_PARTE, onde = '') {
+    return texto.length <= teto ? texto : texto.slice(0, teto) + `\n…(cortado${onde ? `: o resto em ${onde}` : ''})`;
+}
+const PARTES = ['elementos', 'exemplo', 'skill', 'regras'];
+
+/** Uma parte da skill do kit, pra IA carregar: elementos (padrão) · exemplo · skill · regras [nome]. */
+function ver(k, parte = 'elementos', qual) {
+    const P = (f) => path.join(k.pasta, f);
+    const outras = `Outras partes: ${PARTES.filter((x) => x !== parte).map((x) => `primocode kit ver ${k.slug} ${x}`).join(' · ')}`;
+    if (parte === 'exemplo') {
+        let plano = null;
+        try { plano = JSON.parse(lerSe(P('exemplos/plano.json'))); } catch { /* sem exemplo */ }
+        if (!plano) return 'Este kit não tem exemplos/plano.json.';
+        const { cenas = [], ...cabeca } = plano;
+        const aviso = `É a DEMO do kit: serve pra ver o ritmo e o formato. Texto, produto e arquivos dela são barrados no seu plano. Monte o seu: primocode kit montar --kit ${k.slug} --produto "…"`;
+        const linhas = [`# ${k.nome}: o plano da demo`, aviso, '', JSON.stringify(cabeca), ...cenas.map((c) => JSON.stringify(c))];
+        return cortar(linhas.join('\n'), TETO_PARTE, P('exemplos/plano.json')) + '\n' + outras;
+    }
+    if (parte === 'skill') return cortar(lerSe(P('SKILL.md')).trim(), TETO_PARTE, P('SKILL.md')) + '\n' + outras;
+    if (parte === 'regras') {
+        const lista = qual ? REGRAS.filter((r) => r.startsWith(qual)) : REGRAS;
+        const txt = lista.map((r) => lerSe(P(path.join('regras', r))).trim()).filter(Boolean).join('\n\n');
+        return cortar(txt, TETO_PARTE, `primocode kit ver ${k.slug} regras <${REGRAS.map((r) => r.replace(/\.md$/, '')).join('|')}>`) + '\n' + outras;
+    }
+    const partes = [`# Kit ${k.nome} (${k.slug}): ${k.descricao}`, `Monte o vídeo: primocode kit montar --kit ${k.slug} --produto "…" (o esqueleto pela receita) e primocode kit batida <n> --camadas '[…]' (uma batida por vez).`, '', '## Batidas (receita.json: duração em quadros → elementos)'];
+    try {
+        const r = JSON.parse(lerSe(P('receita.json')));
+        for (const b of r.batidas || []) partes.push(`- ${b.nome}${b.obrigatoria ? '*' : ''}: ${(b.duracao || []).join('–')} q → ${(b.elementos || []).join(', ')}${b.sons && b.sons.length ? ` · sons ${b.sons.join(', ')}` : ''}`);
+        if ((r.transicoes || []).length) partes.push(`Transições: ${r.transicoes.map((t) => t.nome).join(', ')}`);
+    } catch { /* sem receita */ }
+    partes.push('', '## Elementos (props)');
+    let els = [];
+    try { els = fs.readdirSync(P('elementos')).filter((f) => f.endsWith('.tsx')).sort(); } catch { /* sem elementos */ }
+    for (const f of els) {
+        const cod = lerSe(P(path.join('elementos', f)));
+        const tipos = tiposDe(cod).map((t) => t.replace(/\/\*\*[\s\S]*?\*\//g, '').replace(/\n\s*\n/g, '\n').replace(/[ \t]+/g, ' ')).join('\n');
+        if (tipos) partes.push(`${f.replace(/\.tsx$/, '')}: ${tipos}`);
+    }
+    partes.push('', 'Plano: {"kit","duracao" (quadros = o "ate" da última cena),"trilha":{"volume"},"cenas":[{"batida","de","ate","entrada","camadas":[{"elemento","props"}],"sons":[{"som","em"}]}]}. 1080×1920, 30 fps; "de"/"ate" absolutos, o resto relativo à cena.',
+        'Foto/logo da pessoa: o caminho na prop, relativo ao projeto ("logo.png"); o PrimoCode copia. Com --fala, as cenas esticam se a voz for mais longa.');
+    return cortar(partes.join('\n'), TETO_PARTE) + '\n' + outras;
+}
+
+// ── conferir um plano e um kit ───────────────────────────────────────────
+
+function elementosDo(k) {
+    try { return fs.readdirSync(path.join(k.pasta, 'elementos')).filter((f) => f.endsWith('.tsx')).map((f) => f.replace(/\.tsx$/, '')); } catch { return []; }
+}
+
+/** Os erros do plano que virariam quadro vazio ou crash no meio do render. */
+function validarPlano(plano, k) {
+    const erros = [];
+    if (!plano || typeof plano !== 'object') return ['o plano não é um objeto JSON'];
+    if (!Array.isArray(plano.cenas) || !plano.cenas.length) return ['o plano não tem "cenas"'];
+    const els = new Set(elementosDo(k));
+    let fim = 0;
+    plano.cenas.forEach((c, i) => {
+        const n = i + 1;
+        if (!c || typeof c !== 'object') { erros.push(`cena ${n}: não é objeto`); return; }
+        if (!(Number(c.ate) > Number(c.de)) || Number(c.de) < 0) erros.push(`cena ${n}: "de" (${c.de}) e "ate" (${c.ate}) em quadros, com ate > de`);
+        if (!Array.isArray(c.camadas)) erros.push(`cena ${n}: falta "camadas"`);
+        for (const cam of c.camadas || []) if (!cam || !els.has(cam.elemento)) erros.push(`cena ${n}: o elemento "${cam && cam.elemento}" não existe no kit ${k.slug} (tem: ${[...els].filter((e) => !/^(Montagem|Cena|Camera|Fundo|Som)$/.test(e)).join(', ')})`);
+        fim = Math.max(fim, Number(c.ate) || 0);
+    });
+    if (!(Number(plano.duracao) > 0)) erros.push('falta "duracao" (em quadros: o "ate" da última cena)');
+    else if (Number(plano.duracao) < fim) erros.push(`"duracao" (${plano.duracao}) é menor que o fim da última cena (${fim})`);
+    if (Number(plano.duracao) > 120 * FPS) erros.push('mais de 2 minutos: corte em partes');
+    return erros;
+}
+
+/** O formato do KITS.md (o checar-kit.mjs do repo dos kits, sem o preview). */
+function checar(pasta) {
+    const erros = [];
+    const tem = (f) => fs.existsSync(path.join(pasta, f));
+    const fm = lerFrontmatter(lerSe(path.join(pasta, 'SKILL.md')));
+    if (!fm) erros.push('falta SKILL.md com frontmatter');
+    else {
+        for (const c of ['nome', 'descricao', 'familia', 'versao']) if (!fm[c]) erros.push(`SKILL.md: falta "${c}"`);
+        if (!Array.isArray(fm.quando) || fm.quando.length < 3) erros.push('SKILL.md: "quando" precisa de 3+ pedidos');
+        if (fm.familia && !FAMILIAS.includes(fm.familia)) erros.push(`SKILL.md: família "${fm.familia}" fora da lista`);
+        if (fm.slug && fm.slug !== path.basename(pasta)) erros.push(`SKILL.md: slug "${fm.slug}" difere da pasta`);
+    }
+    for (const r of REGRAS) if (!tem(`regras/${r}`)) erros.push(`falta regras/${r}`);
+    const els = tem('elementos') ? fs.readdirSync(path.join(pasta, 'elementos')).filter((f) => f.endsWith('.tsx')) : [];
+    if (els.length < 5) erros.push(`elementos/: ${els.length} componentes (mínimo 5)`);
+    if (!tem('elementos/index.ts')) erros.push('falta elementos/index.ts');
+    if (!tem('elementos/Montagem.tsx')) erros.push('falta elementos/Montagem.tsx');
+    try {
+        const r = JSON.parse(lerSe(path.join(pasta, 'receita.json')));
+        for (const b of r.batidas || []) for (const e of b.elementos || []) if (!els.includes(`${e}.tsx`)) erros.push(`receita.json: elemento "${e}" não existe`);
+    } catch { erros.push('receita.json ausente ou inválido'); }
+    if (!tem('exemplos/plano.json')) erros.push('falta exemplos/plano.json');
+    return erros;
+}
+
+// ── o pedido guardado (entre o cartão e o sim) ───────────────────────────
+
+const arqPendente = (pasta) => path.join(pasta, 'motion', '.pendente.json');
+function lerPendente(pasta) { try { return JSON.parse(fs.readFileSync(arqPendente(pasta), 'utf8')); } catch { return null; } }
+
+function lerTextoOuArquivo(v, pasta) {
+    if (!v) return '';
+    const s = String(v);
+    const arq = path.resolve(pasta, s);
+    if (s.length < 400 && !/\n/.test(s) && fs.existsSync(arq) && fs.statSync(arq).isFile()) return fs.readFileSync(arq, 'utf8');
+    return s;
+}
+
+// ── o estúdio (Remotion dos kits), instalado uma vez ─────────────────────
+
+function depsDoEstudio() { try { return JSON.stringify(JSON.parse(fs.readFileSync(path.join(ESTUDIO, 'package.json'), 'utf8')).dependencies); } catch { return ''; } }
+
+/** O node_modules com o Remotion dos kits. PRIMOCODE_KITS_MODULOS aponta um pronto (dev/teste). */
+function garantirEstudio({ home, aoFalar = () => {}, env = process.env } = {}) {
+    if (env.PRIMOCODE_KITS_MODULOS && fs.existsSync(path.join(env.PRIMOCODE_KITS_MODULOS, 'remotion'))) return { ok: true, modulos: env.PRIMOCODE_KITS_MODULOS };
+    const base = baseEstudio(home);
+    const modulos = path.join(base, 'node_modules');
+    const deps = depsDoEstudio();
+    if (fs.existsSync(path.join(modulos, '@remotion', 'renderer')) && lerSe(path.join(base, 'deps.json')) === deps) return { ok: true, modulos };
+    fs.mkdirSync(base, { recursive: true });
+    fs.copyFileSync(path.join(ESTUDIO, 'package.json'), path.join(base, 'package.json'));
+    aoFalar('instalando o estúdio dos kits (uma vez só, alguns minutos)');
+    let r = null;
+    for (let t = 0; t < 2; t++) {
+        r = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--loglevel=error'], { cwd: base, encoding: 'utf8', shell: process.platform === 'win32', timeout: 15 * 60000 });
+        if (r.status === 0) break;
+    }
+    if (!r || r.status !== 0) return { ok: false, error: `não consegui instalar o Remotion dos kits: ${String((r && (r.stderr || r.error)) || '').slice(-300)}` };
+    fs.writeFileSync(path.join(base, 'deps.json'), deps);
+    return { ok: true, modulos };
+}
+
+// ── montar a pasta do vídeo e renderizar ─────────────────────────────────
+
+function copiarKit(k, destino) {
+    fs.rmSync(destino, { recursive: true, force: true });
+    fs.cpSync(k.pasta, destino, { recursive: true, filter: (src) => !/(^|[\\/])(preview\.mp4|capa\.jpg|\.DS_Store|referencia)$/.test(src) });
+}
+
+/** As strings das props que são arquivo da pessoa (foto, logo): copia pra arquivos/ e devolve o mapa de imports. */
+function arquivosDoPlano(plano, pastaProjeto, pastaArquivos, pastaKit) {
+    const mapa = new Map();
+    const andar = (v) => {
+        if (typeof v === 'string') {
+            if (!MIDIA.test(v) || mapa.has(v)) return;
+            // o da pessoa (na pasta do projeto) primeiro; senão um asset do próprio kit (assets/…). Arquivo da demo (exemplos/) nunca.
+            const candidatos = path.isAbsolute(v) ? [v] : [path.resolve(pastaProjeto, v), ...(pastaKit ? [path.join(pastaKit, v)] : [])];
+            const arq = candidatos.find((x) => fs.existsSync(x) && fs.statSync(x).isFile());
+            if (!arq) return;
+            fs.mkdirSync(pastaArquivos, { recursive: true });
+            const nome = `${mapa.size}-${path.basename(arq).replace(/[^\w.-]/g, '_')}`;
+            fs.copyFileSync(arq, path.join(pastaArquivos, nome));
+            mapa.set(v, `./arquivos/${nome}`);
+        } else if (Array.isArray(v)) v.forEach(andar);
+        else if (v && typeof v === 'object') Object.values(v).forEach(andar);
+    };
+    for (const c of plano.cenas || []) for (const cam of c.camadas || []) andar(cam.props);
+    return mapa;
+}
+
+function entradaDoPlano({ mapa, narracao }) {
+    const imports = [...mapa.values()].map((rel, i) => `import a${i} from ${JSON.stringify(rel)};`);
+    const chaves = [...mapa.keys()].map((k, i) => `  ${JSON.stringify(k)}: a${i},`);
+    return `// gerado por lib/kits.js — o vídeo é o plano.json rodando na Montagem do kit
+import React from 'react';
+import {AbsoluteFill, Audio, Composition, registerRoot} from 'remotion';
+import {Montagem} from './kit/elementos';
+import plano from './plano.json';
+${imports.join('\n')}
+${narracao ? "import narracao from './arquivos/narracao.mp3';" : ''}
+const arquivos: Record<string, string> = {
+${chaves.join('\n')}
+};
+const Video: React.FC = () => <AbsoluteFill>
+  {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
+  <Montagem plano={plano as any} arquivos={arquivos} />
+  ${narracao ? '<Audio src={narracao} />' : ''}
+</AbsoluteFill>;
+const Raiz: React.FC = () => <Composition id="Video" component={Video} durationInFrames={(plano as {duracao: number}).duracao} fps={${FPS}} width={1080} height={1920} />;
+registerRoot(Raiz);
+`;
+}
+
+function entradaDoPreview() {
+    return `// gerado por lib/kits.js — o preview do kit
+import React from 'react';
+import {Composition, registerRoot} from 'remotion';
+import {preview} from './kit/preview';
+const Raiz: React.FC = () => <Composition id="Video" component={preview.Componente as React.FC} durationInFrames={preview.duracaoEmQuadros} fps={${FPS}} width={1080} height={1920} />;
+registerRoot(Raiz);
+`;
+}
+
+function ligarModulos(dir, modulos) {
+    const alvo = path.join(dir, 'node_modules');
+    try { fs.rmSync(alvo, { recursive: true, force: true }); } catch { /* não havia */ }
+    fs.symlinkSync(modulos, alvo, 'dir');
+}
+
+function rodarRender(dir, saida, { escala = 1, quadros, aoFalar = () => {}, minutos = 30 } = {}) {
+    return new Promise((resolve) => {
+        fs.copyFileSync(path.join(ESTUDIO, 'render.mjs'), path.join(dir, 'render.mjs'));
+        const args = [path.join(dir, 'render.mjs'), path.join(dir, 'entrada.tsx'), saida, '--escala', String(escala)];
+        if (quadros && quadros.length) args.push('--quadros', quadros.join(','));
+        const p = spawn(process.execPath, args, { cwd: dir });
+        let fim = null, erro = '', resto = '';
+        const rel = setTimeout(() => { try { p.kill(); } catch { /* já foi */ } }, minutos * 60000);
+        p.stdout.on('data', (d) => {
+            resto += d.toString();
+            const linhas = resto.split('\n'); resto = linhas.pop();
+            for (const l of linhas) {
+                let o; try { o = JSON.parse(l); } catch { continue; }
+                if (o.passo) aoFalar(o.passo);
+                else if (o.progresso != null) aoFalar(`renderizando ${o.progresso}%`);
+                else if ('ok' in o) fim = o;
+            }
+        });
+        p.stderr.on('data', (d) => { erro = (erro + d.toString()).slice(-3000); });
+        p.on('close', () => {
+            clearTimeout(rel);
+            if (resto.trim()) { try { const o = JSON.parse(resto); if ('ok' in o) fim = o; } catch { /* resto não é JSON */ } }
+            resolve(fim || { ok: false, error: `o render parou sem dizer por quê: ${erro.split('\n').filter(Boolean).slice(-4).join(' | ')}` });
+        });
+        p.on('error', (e) => { clearTimeout(rel); resolve({ ok: false, error: e.message }); });
+    });
+}
+
+function duracaoDoAudio(arq) {
+    const r = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', arq], { encoding: 'utf8' });
+    const d = parseFloat(String(r.stdout || '').trim());
+    return Number.isFinite(d) ? d : null;
+}
+
+/** Narração mais longa que o plano: estica as cenas na mesma proporção (o tempo dentro de cada cena é relativo, segue valendo). */
+function esticar(plano, segundosVoz) {
+    const precisa = Math.ceil((segundosVoz + 0.6) * FPS);
+    if (!(precisa > plano.duracao)) return { plano, fator: 1 };
+    const f = precisa / plano.duracao;
+    const cenas = plano.cenas.map((c) => ({ ...c, de: Math.round(c.de * f), ate: Math.round(c.ate * f) }));
+    return { plano: { ...plano, duracao: Math.max(precisa, cenas[cenas.length - 1].ate), cenas }, fator: +f.toFixed(2) };
+}
+
+// ── os comandos ──────────────────────────────────────────────────────────
+
+const PADRAO_ABRIR = (alvo) => { try { require('./tools.js').openInBrowser(alvo); } catch { /* sem navegador */ } };
+
+async function cmdMenu(op) {
+    const { home } = op;
+    const T = require('./estudio/kits-tela.js');
+    // no primeiro motion abre a tela de estilos (os kits no carrossel da tela de gosto); a escolha volta aqui
+    let tela = null;
+    try { tela = await (op.abrirKits || ((o) => T.primeiroMotion(o, { env: op.env || process.env })))({ home }); } catch { /* sem tela, segue */ }
+    const G = require('./estudio/gosto.js');
+    const g = G.ler(home);
+    const todos = listar({ home });
+    const linhas = [];
+    const escolha = T.lerEscolha(home);
+    const kEsc = escolha && escolha.slug ? achar(escolha.slug, { home, todos }) : null;
+    if (tela && tela.ok && kEsc) linhas.push(`A pessoa acabou de escolher na tela de estilos: ${kEsc.nome} (${kEsc.slug}). Use este kit (só troque se o pedido dela disser outro estilo com todas as letras).`);
+    else if (kEsc) linhas.push(`O estilo que a pessoa escolheu na tela de estilos: ${kEsc.nome} (${kEsc.slug}). É o padrão dela; o pedido explícito ganha.`);
+    else if (tela && tela.motivo === 'pulou') linhas.push('Na tela de estilos a pessoa deixou você escolher.');
+    else if (tela && tela.motivo && !/nao_abre|ja_escolheu/.test(tela.motivo)) linhas.push(`A tela de estilos fechou sem escolha (${tela.motivo}).`);
+    const resumo = g && !g.pulou ? G.resumo(g) : '';
+    if (resumo) linhas.push(`O gosto de motion dela: ${resumo}`);
+    linhas.push('', `Os ${todos.length} kits de estilo (escolha um; o pedido explícito ganha):`, menuParaIA({ todos }), '',
+        'Depois: primocode kit ver <slug>. Nenhum serve? primocode kit criar --nome … --descricao … --base <slug>.');
+    return { ok: true, texto: linhas.join('\n'), escolha: kEsc ? kEsc.slug : null };
+}
+
+function cmdVer(slug, parte, qual, op) {
+    const k = achar(slug, op);
+    if (!k) return naoExiste(slug, op);
+    return { ok: true, texto: ver(k, PARTES.includes(parte) ? parte : 'elementos', qual) };
+}
+
+function naoExiste(slug, op) {
+    const todos = listar(op);
+    const s = semAcento(slug).split(/[^a-z0-9]+/).filter((x) => x.length > 2);
+    const parecidos = todos.filter((k) => s.some((p) => semAcento(`${k.slug} ${k.nome} ${k.descricao}`).includes(p))).slice(0, 5).map((k) => k.slug);
+    return { ok: false, texto: `Não existe o estilo "${slug}".${parecidos.length ? ` Parecidos: ${parecidos.join(', ')}.` : ''} `
+        + `Se nenhum serve, crie: primocode kit criar --nome "${slug}" --descricao "<como é o estilo>" --base <slug mais parecido> [--ref <vídeo>]` };
+}
+
+async function cmdPlano(a, op) {
+    const pasta = op.projectDir || process.cwd();
+    if (!a.kit) return { ok: false, texto: 'Falta --kit <slug>. Veja: primocode kit menu' };
+    const k = achar(a.kit, op);
+    if (!k) return naoExiste(a.kit, op);
+    const nome = String(a.nome || '').trim();
+    if (!nome) return { ok: false, texto: 'Falta --nome "<nome do vídeo>": vai no cartão que a pessoa confirma e no arquivo.' };
+    const roteiro = lerTextoOuArquivo(a.roteiro, pasta).trim();
+    if (!roteiro) return { ok: false, texto: 'Falta --roteiro (arquivo .md ou o texto): é o que a pessoa lê antes de confirmar.' };
+    if (a.textos) return { ok: false, texto: `Trocar os textos da demo saiu: o vídeo é montado com as peças do kit e o conteúdo da pessoa. Rode: primocode kit montar --kit ${k.slug} --produto "<o que é>" e preencha as batidas.` };
+    let plano;
+    const arqPlano = a.plano ? path.resolve(pasta, String(a.plano)) : path.join(pasta, 'motion', 'plano.json');
+    try { plano = JSON.parse(fs.readFileSync(arqPlano, 'utf8')); } catch (e) {
+        return { ok: false, texto: fs.existsSync(arqPlano) ? `O ${path.relative(pasta, arqPlano)} não é um JSON válido (${e.message}).` : `Não há plano montado. Rode: primocode kit montar --kit ${k.slug} --produto "<o que é>" e preencha as batidas (primocode kit batida <n>).` };
+    }
+    if (plano.kit && plano.kit !== k.slug) return { ok: false, texto: `O plano montado é do kit ${plano.kit}, não ${k.slug}. Use --kit ${plano.kit} ou monte de novo.` };
+    const P = require('./kits-plano.js');
+    const mont = lerMontagem(pasta);
+    const faltas = P.conferirPlano(P.contexto(k, pasta, (mont && mont.kit === k.slug && mont.pessoa) || {}), plano);
+    if (faltas.length) return { ok: false, texto: `O plano ainda não está pronto (${faltas.length}):\n- ${faltas.slice(0, 12).join('\n- ')}` };
+    plano = limparPlano(plano);
+    plano.kit = k.slug;
+    const erros = validarPlano(plano, k);
+    if (erros.length) return { ok: false, texto: `O plano tem ${erros.length} problema(s):\n- ${erros.slice(0, 12).join('\n- ')}` };
+    // primeiro motion (a IA pulou o menu): a tela de estilos abre com este kit marcado; outro kit escolhido lá = refazer o plano
+    try {
+        const T = require('./estudio/kits-tela.js');
+        const t = await (op.abrirKits || ((o) => T.primeiroMotion(o, { env: op.env || process.env })))({ home: op.home, inicial: k.slug });
+        if (t && t.ok && t.slug && t.slug !== k.slug) return { ok: false, texto: `Na tela de estilos a pessoa escolheu ${t.kit ? t.kit.nome : t.slug} (${t.slug}), não ${k.slug}. Refaça o plano com --kit ${t.slug}: primocode kit ver ${t.slug}` };
+    } catch { /* segue */ }
+    const fala = lerTextoOuArquivo(a.fala, pasta).trim();
+    const pend = { kit: k.slug, nome, roteiro, plano, fala, voz: a.voz || null, turno: turnoAtual(), quando: new Date().toISOString() };
+    fs.mkdirSync(path.dirname(arqPendente(pasta)), { recursive: true });
+    fs.writeFileSync(arqPendente(pasta), JSON.stringify(pend, null, 1));
+    const seg = (plano.duracao / FPS).toFixed(1).replace(/\.0$/, '');
+    const auto = autoConfirma(op.env);
+    const cartao = [
+        'O VÍDEO, ANTES DE COMEÇAR',
+        `Nome: ${nome}`,
+        `Estilo: ${k.nome} (${k.slug}) — ${k.descricao}`,
+        `Duração: ${seg} s · ${plano.cenas.length} cenas · ${fala ? 'com narração (VoiceStudio se estiver aberto; senão a voz de sempre)' : 'sem narração'}`,
+        '', 'Roteiro:', roteiro.slice(0, 2000), '',
+        auto ? '(confirmação automática ligada: PRIMOCODE_KIT_CONFIRMAR=1) Pode rodar: primocode kit fazer'
+            : '→ Mostre este cartão à pessoa como está e pergunte se pode começar. TERMINE a resposta aqui. Só depois do sim dela rode: primocode kit fazer (pediu mudança? ajuste e rode primocode kit plano de novo).',
+    ];
+    return { ok: true, texto: cartao.join('\n'), pendente: arqPendente(pasta) };
+}
+
+// ── montar: o esqueleto pela receita e uma batida por vez (lib/kits-plano.js) ──
+
+const arqMontagem = (pasta) => path.join(pasta, 'motion', '.montagem.json');
+function lerMontagem(pasta) { try { return JSON.parse(fs.readFileSync(arqMontagem(pasta), 'utf8')); } catch { return null; } }
+const lista = (v) => String(v || '').split(/\s*,\s*/).map((x) => x.trim()).filter(Boolean);
+/** Tira as marcas de trabalho (cenario, falta) antes do render. */
+function limparPlano(plano) {
+    return { ...plano, cenas: (plano.cenas || []).map(({ falta, ...c }) => ({ ...c, camadas: (c.camadas || []).map(({ elemento, props }) => ({ elemento, props })) })) };
+}
+
+function cmdMontar(a, op) {
+    const pasta = op.projectDir || process.cwd();
+    if (!a.kit) return { ok: false, texto: 'Falta --kit <slug>. Veja: primocode kit menu' };
+    const k = achar(a.kit, op);
+    if (!k) return naoExiste(a.kit, op);
+    const produto = String(a.produto || '').trim();
+    if (!produto) return { ok: false, texto: 'Falta --produto "<o que o vídeo mostra: app de celular, curso online, garrafa térmica…>": é o que você vai montar em cena (nunca o produto da demo do kit).' };
+    const arquivos = [...lista(a.arquivos), ...lista(a.logo), ...lista(a.fotos)];
+    const sumidos = arquivos.filter((f) => !fs.existsSync(path.resolve(pasta, f)));
+    if (sumidos.length) return { ok: false, texto: `Não achei na pasta do projeto: ${sumidos.join(', ')}` };
+    const pessoa = { produto, marca: String(a.marca || '').trim() || undefined, arquivos, cores: lista(a.cores) };
+    const P = require('./kits-plano.js');
+    const ctx = P.contexto(k, pasta, pessoa);
+    const r = P.esqueleto(ctx, { segundos: a.segundos, batidas: lista(a.batidas) });
+    if (r.erro) return { ok: false, texto: r.erro };
+    // montar de novo o MESMO vídeo (mesmo kit, mesmas batidas) não joga fora as batidas já prontas: o modelo
+    // rodava o montar outra vez depois de um erro numa batida e recomeçava do zero (E2E do Lume, 27/10)
+    let mantidas = 0;
+    try {
+        const velho = JSON.parse(fs.readFileSync(path.join(pasta, 'motion', 'plano.json'), 'utf8'));
+        const mesmo = velho.kit === k.slug && Array.isArray(velho.cenas) && velho.cenas.map((c) => c.batida).join() === r.plano.cenas.map((c) => c.batida).join();
+        if (mesmo) velho.cenas.forEach((c, i) => { if (!c.falta) { r.plano.cenas[i] = { ...r.plano.cenas[i], camadas: c.camadas }; delete r.plano.cenas[i].falta; mantidas++; } });
+    } catch { /* não havia plano */ }
+    fs.mkdirSync(path.join(pasta, 'motion'), { recursive: true });
+    fs.writeFileSync(path.join(pasta, 'motion', 'plano.json'), JSON.stringify(r.plano, null, 1));
+    fs.writeFileSync(arqMontagem(pasta), JSON.stringify({ kit: k.slug, pessoa }, null, 1));
+    const linhas = [`Esqueleto do vídeo no ${k.nome} (motion/plano.json): ${(r.plano.duracao / FPS).toFixed(1)} s, ${r.plano.cenas.length} batidas pela receita do kit:`,
+        r.plano.cenas.map((c, i) => `${i + 1}. ${c.batida} ${((c.ate - c.de) / FPS).toFixed(1)} s`).join(' · ')];
+    const geral = P.conferirPlano(ctx, { ...r.plano, cenas: [] });
+    if (geral.length) linhas.push(`Vale pro vídeo todo: ${geral.join('; ')}`);
+    const prox = r.plano.cenas.findIndex((c) => c.falta);
+    if (mantidas) linhas.push(`(${mantidas} batida(s) que já estavam prontas foram mantidas; siga da ${prox + 1}.)`);
+    if (prox >= 0) linhas.push('', P.formulario(ctx, r.plano, prox + 1));
+    else linhas.push('', `Todas as batidas já estão montadas. Agora: primocode kit plano --kit ${k.slug} --nome "…" --roteiro roteiro.md`);
+    return { ok: true, texto: linhas.join('\n') };
+}
+
+function cmdBatida(a, op) {
+    const pasta = op.projectDir || process.cwd();
+    const mont = lerMontagem(pasta);
+    let plano = null;
+    try { plano = JSON.parse(fs.readFileSync(path.join(pasta, 'motion', 'plano.json'), 'utf8')); } catch { /* sem plano */ }
+    if (!mont || !plano) return { ok: false, texto: 'Não há vídeo sendo montado nesta pasta. Rode: primocode kit montar --kit <slug> --produto "…"' };
+    const k = achar(mont.kit, op);
+    if (!k) return naoExiste(mont.kit, op);
+    const P = require('./kits-plano.js');
+    const ctx = P.contexto(k, pasta, mont.pessoa || {});
+    const qual = String(a._[0] || '');
+    const corpo = a.camadas || a.props || (a.arquivo ? lerTextoOuArquivo(String(a.arquivo), pasta) : null);
+    let dado = null;
+    if (corpo != null && corpo !== true) {
+        try { dado = JSON.parse(String(corpo)); } catch (e) { return { ok: false, texto: `O JSON não abriu (${e.message}). Mande entre aspas simples: --camadas '[{"elemento":"…","props":{…}}]' (ou --arquivo batida.json).` }; }
+    }
+    if (qual === 'geral') {
+        if (!dado) return { ok: true, texto: `Vale pro vídeo todo (* = obrigatório): ${P.mostrar(ctx.sch.geral)}\nMande: primocode kit batida geral --props '{…}'` };
+        const c2 = { notas: [], erros: [], demo: ctx.demo, permitidos: ctx.permitidos, arquivoOk: ctx.arquivoOk };
+        const sch = { k: 'obj', campos: Object.fromEntries(Object.entries(ctx.sch.geral.campos).map(([c, v]) => [c, { ...v, opc: true }])) };
+        const v = P.consertar(dado, sch, c2, ['geral']);
+        if (c2.erros.length) return { ok: false, texto: `Não entrou:\n- ${c2.erros.join('\n- ')}` };
+        // mescla raso: o que veio substitui o campo inteiro, menos objetos (mescla por dentro)
+        for (const [c, x] of Object.entries(v || {})) plano[c] = x && typeof x === 'object' && !Array.isArray(x) && plano[c] && typeof plano[c] === 'object' ? { ...plano[c], ...x } : x;
+        fs.writeFileSync(path.join(pasta, 'motion', 'plano.json'), JSON.stringify(plano, null, 1));
+        return { ok: true, texto: `Geral ok.${c2.notas.length ? ` Consertei: ${c2.notas.join('; ')}` : ''}` };
+    }
+    const n = Number(qual);
+    if (!(n >= 1 && n <= plano.cenas.length)) return { ok: false, texto: `Qual batida? 1 a ${plano.cenas.length} (ou "geral").` };
+    if (!dado) return { ok: true, texto: P.formulario(ctx, plano, n) + `\nVocê já tem tudo pra batida ${n}: o próximo passo é MANDAR as camadas (--camadas '[…]'), não pedir o formulário de novo.` };
+    const cena = plano.cenas[n - 1];
+    const b = (ctx.receita.batidas || []).find((x) => x.nome === cena.batida) || { nome: cena.batida, elementos: [] };
+    const r = P.conferirBatida(ctx, b, dado, n);
+    if (r.erros.length) return { ok: false, texto: `A batida ${n} não entrou:\n- ${r.erros.join('\n- ')}${r.notas.length ? `\n(também consertaria: ${r.notas.join('; ')})` : ''}\nArrume e mande de novo.` };
+    const mandouCenario = r.camadas.some((c) => P.ehCenario(ctx.sch, c.elemento));
+    cena.camadas = [...(mandouCenario ? [] : (cena.camadas || []).filter((c) => c.cenario)), ...r.camadas];
+    delete cena.falta;
+    fs.writeFileSync(path.join(pasta, 'motion', 'plano.json'), JSON.stringify(plano, null, 1));
+    const linhas = [`Batida ${n} (${cena.batida}) ok: ${r.camadas.map((c) => c.elemento).join(' + ')}.${r.notas.length ? ` Consertei: ${r.notas.join('; ')}.` : ''}`];
+    const prox = plano.cenas.findIndex((c, i) => c.falta && i !== n - 1);
+    if (prox >= 0) linhas.push('', P.formulario(ctx, plano, prox + 1));
+    else {
+        const faltas = P.conferirPlano(ctx, plano);
+        if (faltas.length) linhas.push('', `Falta: ${faltas.join('; ')}`);
+        else linhas.push('', `Todas as ${plano.cenas.length} batidas montadas. Agora escreva o roteiro.md e rode: primocode kit plano --kit ${k.slug} --nome "<nome do vídeo>" --roteiro roteiro.md`);
+    }
+    return { ok: true, texto: linhas.join('\n') };
+}
+
+async function cmdFazer(a, op) {
+    const pasta = op.projectDir || process.cwd();
+    const pend = lerPendente(pasta);
+    if (!pend) return { ok: false, texto: 'Não há vídeo esperando confirmação nesta pasta. Rode primocode kit plano antes.' };
+    if (pend.turno === turnoAtual() && !autoConfirma(op.env)) {
+        return { ok: false, texto: 'A pessoa ainda não confirmou: o cartão foi mostrado neste mesmo pedido. Termine a resposta perguntando se pode começar; rode primocode kit fazer quando ela disser sim.' };
+    }
+    const k = achar(pend.kit, op);
+    if (!k) return naoExiste(pend.kit, op);
+    const falar = op.aoFalar || (() => {});
+    const est = garantirEstudio({ home: op.home, aoFalar: falar, env: op.env || process.env });
+    if (!est.ok) return { ok: false, texto: est.error };
+    const dir = path.join(pasta, 'motion', slugar(pend.nome) || 'video');
+    fs.mkdirSync(dir, { recursive: true });
+    copiarKit(k, path.join(dir, 'kit'));
+    const pastaArq = path.join(dir, 'arquivos');
+    fs.rmSync(pastaArq, { recursive: true, force: true });
+    let plano = pend.plano, voz = null;
+    if (pend.fala) {
+        falar('gravando a narração');
+        fs.mkdirSync(pastaArq, { recursive: true });
+        const mp3 = path.join(pastaArq, 'narracao.mp3');
+        const narrar = op.narrar || ((t, m, v) => require('./estudio/maquina-voz.js').cadeiaLocal(t, m, v));
+        const r = await narrar(pend.fala, mp3, pend.voz || undefined);
+        if (r && r.ok && fs.existsSync(mp3)) {
+            const d = duracaoDoAudio(mp3);
+            const e = d ? esticar(plano, d) : { plano, fator: 1 };
+            plano = e.plano;
+            voz = { motor: r.motor, segundos: d, esticou: e.fator };
+            if (plano.trilha !== false) plano = { ...plano, trilha: { ...(plano.trilha || {}), volume: +(((plano.trilha && plano.trilha.volume) ?? 0.5) * 0.45).toFixed(2) } };
+        } else voz = { erro: (r && r.error) || 'sem voz', motor: null };
+    }
+    const mapa = arquivosDoPlano(plano, pasta, pastaArq, k.pasta);
+    fs.writeFileSync(path.join(dir, 'plano.json'), JSON.stringify(plano, null, 1));
+    fs.writeFileSync(path.join(dir, 'roteiro.md'), `# ${pend.nome}\n\nEstilo: ${k.nome} (${k.slug})\n\n${pend.roteiro}\n`);
+    fs.writeFileSync(path.join(dir, 'entrada.tsx'), entradaDoPlano({ mapa, narracao: !!(voz && voz.motor) }));
+    ligarModulos(dir, est.modulos);
+    const saida = path.join(dir, `${slugar(pend.nome) || 'video'}.mp4`);
+    fs.rmSync(path.join(dir, 'quadros'), { recursive: true, force: true });
+    // um quadro por cena, a 70% dela (depois da entrada): é o que a conferência lê
+    const meios = plano.cenas.map((c) => Math.round(c.de + (c.ate - c.de) * 0.7));
+    const r = await rodarRender(dir, saida, { escala: Number(a.escala) || 1, aoFalar: falar, quadros: meios });
+    if (!r.ok) return { ok: false, texto: `O render falhou: ${r.error}\nA pasta do vídeo ficou em ${dir} (plano.json + kit/) pra conferir.` };
+    const problemas = conferirQuadros(k, plano, r.quadros || [], pasta, op.visao);
+    try { fs.renameSync(arqPendente(pasta), path.join(dir, 'pedido.json')); } catch { /* segue */ }
+    try { fs.renameSync(arqMontagem(pasta), path.join(dir, 'montagem.json')); } catch { /* não foi montado aqui */ }
+    if (op.abrirVideo) op.abrirVideo(r.video);
+    const linhas = [`Pronto: ${r.video} (${r.segundos} s, estilo ${k.nome}).`];
+    if (voz && voz.motor) linhas.push(`Narração: ${voz.motor}${voz.esticou > 1 ? ` (as cenas esticaram ${voz.esticou}× pra caber a voz)` : ''}.`);
+    else if (voz) linhas.push(`Sem narração: ${voz.erro}.`);
+    linhas.push(`Quadros pra conferir (um por cena): ${(r.quadros || []).join(', ')}`);
+    if (problemas.length) linhas.push(`Conferi os quadros e achei ${problemas.length} problema(s):`, ...problemas.map((p) => `- cena ${p.cena}: ${p.texto}`),
+        'Conserte a batida (primocode kit batida <n> --camadas …), depois primocode kit plano + fazer de novo. Não diga pronto com isso aberto.');
+    else linhas.push('Abra os quadros antes de dizer pronto. Algo torto? Refaça a batida (primocode kit batida <n>) e rode primocode kit plano + fazer de novo.');
+    return { ok: true, texto: linhas.join('\n'), video: r.video, quadros: r.quadros, voz, problemas };
+}
+
+/**
+ * O olho depois do render (lib/estudio/conferencia-visual.js, o Vision do macOS): no quadro do meio de cada cena,
+ * texto colado na borda, encavalado, e — o que os E2E mostraram — a cena que tem texto no plano e nenhum texto
+ * no quadro (entrou tarde demais, cor igual ao fundo, fora da tela). Sem Vision: nada (os quadros vão pra IA olhar).
+ */
+/** O desvio dos tons de cinza de um quadro (0–255), pelo ffmpeg em 16×28. null sem ffmpeg. */
+function variacao(arq) {
+    const r = spawnSync('ffmpeg', ['-v', 'error', '-i', arq, '-vf', 'scale=16:28', '-f', 'rawvideo', '-pix_fmt', 'gray', '-'], { maxBuffer: 1 << 16 });
+    if (r.status !== 0 || !r.stdout || !r.stdout.length) return null;
+    const v = [...r.stdout];
+    const m = v.reduce((a, b) => a + b, 0) / v.length;
+    return Math.sqrt(v.reduce((a, b) => a + (b - m) * (b - m), 0) / v.length);
+}
+
+function conferirQuadros(k, plano, quadros, pasta, visao) {
+    const out = [];
+    // o quadro do meio da cena quase de uma cor só: o produto não aparece (câmera dentro dele, fora do quadro) ou o texto some no fundo
+    quadros.forEach((q, i) => {
+        const d = variacao(q);
+        if (d != null && d < 5) out.push({ cena: i + 1, tipo: 'vazio', texto: `o quadro do meio da cena é quase todo de uma cor só (variação ${d.toFixed(1)}): o produto não aparece (câmera dentro dele ou fora do quadro?) ou o texto some no fundo` });
+    });
+    let V = visao;
+    if (V === undefined) { try { V = require('./estudio/visao.js'); } catch { V = null; } }
+    if (!V || !V.disponivel() || !quadros.length) return out;
+    const r = V.ler(quadros);
+    if (!r || !r.ok) return out;
+    const CV = require('./estudio/conferencia-visual.js');
+    const P = require('./kits-plano.js');
+    const sch = P.esquema(k);
+    (r.quadros || []).forEach((q) => {
+        const i = quadros.indexOf(q.arquivo);
+        if (i < 0) return;
+        out.push(...CV.julgarLeitura(q, i + 1));
+        const doPlano = P.textosDaCena(sch, plano.cenas[i]).filter((t) => /[a-zà-ú0-9]{2}/i.test(t));
+        const lidos = (q.textos || []).filter((t) => t.conf >= 0.3).map((t) => String(t.texto));
+        if (doPlano.length && !lidos.length && !out.some((x) => x.cena === i + 1 && x.tipo === 'vazio')) out.push({ cena: i + 1, tipo: 'sumiu', texto: `o texto da cena ("${doPlano[0].slice(0, 40)}") não aparece no quadro do meio: entra tarde, sai cedo, some no fundo ou está fora da tela` });
+    });
+    return out;
+}
+
+async function cmdReferencia(a, op) {
+    const G = require('./estudio/gosto.js');
+    const desde = Date.now() - 1000;
+    const r = await (op.abrirReferencias || ((o) => G.abrirOndeDer(o)))({ inicio: 'referencias', home: op.home });
+    if (!r || !r.ok) return { ok: false, texto: `A tela de referências fechou sem salvar (${(r && r.motivo) || 'sem tela'}). Siga com o pedido ou peça o vídeo de novo.` };
+    const pastaRef = path.join(op.home || os.homedir(), '.primocode', 'gosto-referencias');
+    let videos = [];
+    try { videos = fs.readdirSync(pastaRef).map((f) => path.join(pastaRef, f)).filter((f) => !path.basename(f).startsWith('.') && fs.statSync(f).mtimeMs >= desde); } catch { /* nenhum */ }
+    const refs = (r.gosto && r.gosto.referencias) || [];
+    const linhas = ['As referências que a pessoa trouxe (medidas na tela):'];
+    for (const x of refs.slice(-5)) linhas.push(`- ${x.nome}: ${G.fraseDeUmaReferencia(x.medida)}${x.descricao && x.descricao.frases ? ' · ' + x.descricao.frases.join('; ') : ''}`);
+    if (videos.length) linhas.push('', `Os vídeos: ${videos.join(', ')}`);
+    // os kits mais perto do vídeo (paleta da capa + ritmo da receita): sugestão, quem escolhe é a IA
+    const ultima = refs.length ? refs[refs.length - 1].medida : null;
+    let perto = [];
+    try { perto = require('./kits-parecidos.js').parecidos(ultima, listar(op), { home: op.home }); } catch { /* sem ffmpeg */ }
+    if (perto.length) linhas.push('', 'Os kits mais parecidos com o vídeo (sugestão; você decide):', ...perto.map((p, i) => `${i + 1}. ${p.k.slug} · ${p.k.nome.split(' · ')[0]}: ${p.porque}`));
+    linhas.push('', 'Escolha o kit mais próximo (primocode kit menu) ou, se nenhum chega perto, crie um a partir do vídeo: primocode kit criar --nome "<nome>" --descricao "<como é>" --base <slug> --ref <vídeo>');
+    return { ok: true, texto: linhas.join('\n'), videos };
+}
+
+function cmdCriar(a, op) {
+    const nome = String(a.nome || '').trim();
+    if (!nome) return { ok: false, texto: 'Falta --nome "<nome do estilo>".' };
+    const slug = slugar(a.slug || nome);
+    const todos = listar(op);
+    if (todos.some((k) => k.slug === slug)) return { ok: false, texto: `O estilo ${slug} já existe: primocode kit ver ${slug}` };
+    const base = achar(a.base || 'minimal', { todos }) || todos[0];
+    if (!base) return { ok: false, texto: 'Não há kit nenhum pra servir de base neste pacote.' };
+    const descricao = String(a.descricao || '').replace(/\s+/g, ' ').trim() || `estilo ${nome}`;
+    const destino = path.join(casa(op.home), slug);
+    copiarKit(base, destino);
+    const corpoBase = lerSe(path.join(base.pasta, 'SKILL.md')).replace(/^---\n[\s\S]*?\n---\n?/, '');
+    const quando = String(a.quando || '').split(/\s*;\s*/).filter(Boolean);
+    while (quando.length < 3) quando.push([`vídeo no estilo ${nome}`, descricao, `motion ${nome.toLowerCase()}`][quando.length]);
+    const familia = FAMILIAS.includes(a.familia) ? a.familia : base.familia;
+    const fm = ['---', `slug: ${slug}`, `nome: ${nome}`, `descricao: ${descricao}`, `familia: ${familia}`, 'versao: 1', `base: ${base.slug}`, 'quando:', ...quando.map((q) => `  - "${q.replace(/"/g, "'")}"`), '---', ''].join('\n');
+    const nota = `> Kit criado pelo PrimoCode em ${new Date().toISOString().slice(0, 10)} a partir de **${base.nome}** (${base.slug}), pro pedido: "${descricao}".\n> Os elementos e a receita vêm da base; as regras e os tokens (elementos/base.ts) são o que muda.\n\n`;
+    fs.writeFileSync(path.join(destino, 'SKILL.md'), fm + nota + corpoBase.trim() + '\n');
+    const linhas = [`Criei o kit ${nome} (${slug}) em ${destino}, a partir de ${base.nome} (${base.slug}).`];
+    if (a.ref) {
+        const mc = require('./motioncraft.js').CLI;
+        const dirRef = path.join(destino, 'referencia');
+        const rodar = (...args) => spawnSync(process.execPath, [mc, 'ref', ...args, '--dir', dirRef], { encoding: 'utf8', timeout: 5 * 60000 });
+        const g = rodar('get', path.resolve(op.projectDir || process.cwd(), String(a.ref)));
+        const rep = g.status === 0 ? rodar('report') : g;
+        if (rep.status === 0) {
+            linhas.push(`Analisei a referência (MotionCraft ref): ${path.join(dirRef, 'ref_report.md')} — cortes, BPM, movimento por segundo, paleta (palette.png) e folhas de contato (sheet_*.jpg).`);
+            fs.writeFileSync(path.join(destino, 'regras', 'referencia.md'), `# Referência\n\nVídeo: ${a.ref}\n\n${lerSe(path.join(dirRef, 'ref_report.md'))}\n`);
+        } else linhas.push(`Não consegui analisar a referência: ${String(rep.stderr || rep.stdout || rep.error || '').split('\n').filter(Boolean).slice(-2).join(' ')}`);
+    }
+    const erros = checar(destino);
+    if (erros.length) linhas.push(`Formato: ${erros.length} pendência(s): ${erros.join('; ')}`);
+    linhas.push('', 'Agora faça o estilo virar o pedido (você edita os arquivos do kit):',
+        `1) regras/cor.md e regras/tipografia.md: troque pelos números do estilo pedido${a.ref ? ' (abra palette.png e as folhas de contato em referencia/)' : ''}.`,
+        `2) elementos/base.ts: as cores, a fonte e as curvas (os tokens) do estilo novo. Fonte nova só OFL/Apache, em assets/fontes, listada no assets/ASSETS.md.`,
+        '3) SKILL.md: reescreva "o que é o estilo" e o "proibido" do jeito do pedido.',
+        `Depois use como os outros: primocode kit ver ${slug}. A capa e o preview: primocode kit preview ${slug}.`);
+    return { ok: true, texto: linhas.join('\n'), slug, pasta: destino };
+}
+
+async function cmdPreview(slug, op) {
+    const k = achar(slug, op);
+    if (!k) return naoExiste(slug, op);
+    const pronto = previewPronto(k, op);
+    if (pronto) return { ok: true, texto: `Preview: ${pronto}`, video: pronto };
+    const est = garantirEstudio({ home: op.home, aoFalar: op.aoFalar, env: op.env || process.env });
+    if (!est.ok) return { ok: false, texto: est.error };
+    const dir = path.join(casa(op.home), '.render', k.slug);
+    fs.mkdirSync(dir, { recursive: true });
+    copiarKit(k, path.join(dir, 'kit'));
+    fs.writeFileSync(path.join(dir, 'entrada.tsx'), entradaDoPreview());
+    ligarModulos(dir, est.modulos);
+    const saida = path.join(casa(op.home), 'previews', `${k.slug}.mp4`);
+    const r = await rodarRender(dir, saida, { escala: 0.5, quadros: [Math.round(FPS * 3)], aoFalar: op.aoFalar || (() => {}) });
+    if (!r.ok) return { ok: false, texto: `O preview falhou: ${r.error}` };
+    if (k.origem === 'seu' && r.quadros && r.quadros[0]) { try { fs.copyFileSync(r.quadros[0], path.join(k.pasta, 'capa.jpg')); } catch { /* sem capa */ } }
+    return { ok: true, texto: `Preview: ${saida}`, video: saida };
+}
+
+/** O preview.mp4 do kit: o da pasta do kit (repo de dev), o renderizado aqui, ou nada. */
+function previewPronto(k, op = {}) {
+    for (const f of [path.join(k.pasta, 'preview.mp4'), path.join(casa(op.home), 'previews', `${k.slug}.mp4`)]) if (fs.existsSync(f)) return f;
+    return null;
+}
+
+// ── a galeria (/styles) ──────────────────────────────────────────────────
+
+const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const urlDe = (arq) => 'file://' + encodeURI(arq.split(path.sep).join('/'));
+
+/** A galeria em HTML: capa, preview (o local, ou PRIMOCODE_KITS_PREVIEW_URL/<slug>/preview.mp4) e nome de cada kit. */
+function galeriaHtml(op = {}) {
+    const env = op.env || process.env;
+    const remoto = String(env.PRIMOCODE_KITS_PREVIEW_URL || '').replace(/\/+$/, '');
+    const todos = listar(op);
+    const grupos = [...new Set([...FAMILIAS, ...todos.map((k) => k.familia)])].filter((f) => todos.some((k) => k.familia === f));
+    const cartao = (k) => {
+        const local = previewPronto(k, op);
+        const video = local ? urlDe(local) : (remoto && k.origem === 'pacote' ? `${remoto}/${k.slug}/preview.mp4` : '');
+        return `<figure class="kit" data-slug="${esc(k.slug)}">
+  <div class="tela">${k.capa ? `<img src="${esc(urlDe(k.capa))}" alt="" loading="lazy">` : '<div class="sem"></div>'}${video ? `<video muted loop playsinline preload="none" data-src="${esc(video)}"></video>` : ''}</div>
+  <figcaption><b>${esc(k.nome)}</b><span>${esc(k.descricao)}</span><code>/styles ${esc(k.slug)}</code></figcaption>
+</figure>`;
+    };
+    return `<!doctype html><html lang="pt-BR"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Estilos de motion</title>
+<style>
+:root{--bg:#0c0b0f;--surface:#16141b;--line:#2e2a37;--fg:#efeaf3;--muted:#9a93a6;--accent:#ff4d7d;color-scheme:dark}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 "Instrument Sans","Helvetica Neue",system-ui,sans-serif}
+.wrap{max-width:1480px;margin:0 auto;padding:28px 16px 64px}
+h1{font:800 clamp(30px,5vw,54px)/1 "Bricolage Grotesque","Avenir Next",system-ui,sans-serif;letter-spacing:-.03em;margin:0 0 6px}
+.sub{color:var(--muted);margin:0 0 28px}.sub b{color:var(--accent)}
+h2{font:700 13px/1 ui-monospace,"SF Mono",Menlo,monospace;text-transform:uppercase;letter-spacing:.12em;color:var(--muted);margin:36px 0 14px}
+.grade{display:grid;grid-template-columns:repeat(auto-fill,minmax(170px,1fr));gap:16px}
+.kit{margin:0;background:var(--surface);border:1px solid var(--line);border-radius:14px;overflow:hidden;transition:transform .25s cubic-bezier(.2,.8,.2,1),border-color .25s}
+.kit:hover{transform:translateY(-4px) rotate(-.4deg);border-color:var(--accent)}
+.tela{position:relative;aspect-ratio:9/16;background:#000}.tela img,.tela video{position:absolute;inset:0;width:100%;height:100%;object-fit:cover}
+.tela video{opacity:0;transition:opacity .2s}.kit.toca video{opacity:1}.sem{position:absolute;inset:0;background:repeating-linear-gradient(45deg,#1b1922 0 10px,#15131a 10px 20px)}
+figcaption{padding:10px 12px 12px;display:grid;gap:4px}figcaption b{font-weight:600}figcaption span{color:var(--muted);font-size:12.5px;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
+code{font:12px ui-monospace,"SF Mono",Menlo,monospace;color:var(--accent)}
+</style></head><body><div class="wrap">
+<h1>Estilos de motion</h1><p class="sub"><b>${todos.length}</b> kits. Passe o mouse pra ver mexendo. No pedido, é só dizer o estilo ("estilo apple") ou deixar o PrimoCode escolher.</p>
+${grupos.map((f) => `<h2>${esc(f || 'Outros')}</h2><div class="grade">${todos.filter((k) => k.familia === f).map(cartao).join('\n')}</div>`).join('\n')}
+</div><script>
+document.querySelectorAll('.kit').forEach(function (k) {
+  var v = k.querySelector('video'); if (!v) return;
+  k.addEventListener('mouseenter', function () { if (!v.src) v.src = v.dataset.src; k.classList.add('toca'); v.play().catch(function () {}); });
+  k.addEventListener('mouseleave', function () { k.classList.remove('toca'); v.pause(); });
+});
+</script></body></html>`;
+}
+
+/** A tela de estilos (lib/estudio/kits-tela.js): capa, preview com o mouse em cima, nome; a escolha volta. */
+async function cmdGaleria(op) {
+    const T = require('./estudio/kits-tela.js');
+    const r = await (op.abrirKits || ((o) => T.abrirOndeDer(o, { env: op.env || process.env })))({ home: op.home, inicial: op.inicial });
+    if (r && r.ok) return { ok: true, texto: `Estilo escolhido: ${r.kit ? r.kit.nome : r.slug} (${r.slug}). O próximo motion sai nele.`, slug: r.slug };
+    const motivo = { pulou: 'você deixou o PrimoCode escolher pelo pedido', fechou: 'a tela fechou sem escolha', tempo: 'acabou o tempo (10 min)', sem_tela: 'não consegui abrir a tela' }[r && r.motivo] || (r && r.motivo) || 'sem escolha';
+    return { ok: r && r.motivo === 'pulou', texto: `Tela de estilos: ${motivo}.` };
+}
+
+/** O texto do /styles: os kits por família. */
+function listaParaPessoa(op = {}) {
+    const todos = listar(op);
+    if (!todos.length) return ['Este PrimoCode não tem kits de estilo.'];
+    const linhas = [];
+    for (const f of [...new Set(todos.map((k) => k.familia))]) {
+        linhas.push(f || 'Outros');
+        for (const k of todos.filter((x) => x.familia === f)) linhas.push(`  ${k.slug.padEnd(20)} ${k.nome}${k.origem === 'seu' ? '  (seu)' : ''}`);
+    }
+    return linhas;
+}
+
+// ── a linha de comando ───────────────────────────────────────────────────
+
+/** Separa a linha como o shell faria: aspas simples e duplas, contrabarra. null se tiver operador de shell fora de aspas. */
+function palavras(linha) {
+    const out = []; let atual = null, aspas = null;
+    const s = String(linha || '');
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (aspas) {
+            if (ch === aspas) { aspas = null; continue; }
+            if (ch === '\\' && aspas === '"' && i + 1 < s.length && /["\\$`]/.test(s[i + 1])) { atual += s[++i]; continue; }
+            atual += ch; continue;
+        }
+        if (ch === '"' || ch === "'") { aspas = ch; if (atual == null) atual = ''; continue; }
+        if (ch === '\\' && i + 1 < s.length) { atual = (atual || '') + s[++i]; continue; }
+        if (/\s/.test(ch)) { if (atual != null) { out.push(atual); atual = null; } continue; }
+        if (/[;&|<>`$()]/.test(ch)) return null;
+        atual = (atual || '') + ch;
+    }
+    if (aspas) return null;
+    if (atual != null) out.push(atual);
+    return out;
+}
+
+function opcoes(args) {
+    const a = { _: [] };
+    for (let i = 0; i < args.length; i++) {
+        const m = String(args[i]).match(/^--([a-z-]+)(?:=(.*))?$/);
+        if (!m) { a._.push(args[i]); continue; }
+        if (m[2] != null) a[m[1]] = m[2];
+        else if (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) a[m[1]] = args[++i];
+        else a[m[1]] = true;
+    }
+    return a;
+}
+
+const AJUDA = `primocode kit — os kits de estilo de motion
+  menu                      o menu dos kits (no primeiro motion abre a tela de estilos)
+  ver <slug> [parte]        a skill do kit em partes: elementos (padrão) · exemplo · skill · regras [nome]
+  referencia                abre a tela de referências e devolve o que mediu
+  montar --kit <slug> --produto "<o que é>" [--marca "<nome>"] [--segundos 15] [--batidas a,b,c] [--arquivos logo.png,foto.jpg] [--cores "#hex,#hex"]
+                            o esqueleto do vídeo pela receita do kit (motion/plano.json) e o formulário da batida 1
+  batida <n|geral> [--camadas '<json>' | --arquivo <json>]
+                            sem JSON: o formulário da batida; com: confere, conserta e grava (devolve a próxima)
+  plano --kit <slug> --nome "<nome>" --roteiro <md> [--plano <json>] [--fala "<texto>"] [--voz <voz>]
+                            o cartão pra pessoa confirmar (roteiro + nome + estilo), com o plano montado
+  fazer [--escala 0.5]      depois do sim: narração + render
+  criar --nome "<nome>" --descricao "<como é>" [--base <slug>] [--ref <vídeo>] [--quando "a; b; c"] [--familia "<família>"]
+  preview <slug>            o preview.mp4 do kit (renderiza aqui na primeira vez)
+  galeria                   abre a tela de estilos (capa + preview + nome) e devolve a escolha
+  lista                     os kits por família`;
+
+/** Roda um comando. Resolve {ok, texto}. `op`: {projectDir, home, env, aoFalar, abrir, abrirVideo, gostoOp, narrar, abrirReferencias}. */
+async function main(argv, op = {}) {
+    const [cmd, ...resto] = argv;
+    const a = opcoes(resto);
+    try {
+        switch (cmd) {
+            case 'menu': return await cmdMenu(op);
+            case 'ver': case 'skill': return a._[0] ? cmdVer(a._[0], a._[1], a._[2], op) : { ok: false, texto: 'Uso: primocode kit ver <slug>' };
+            case 'referencia': case 'referencias': return await cmdReferencia(a, op);
+            case 'montar': return cmdMontar(a, op);
+            case 'batida': return cmdBatida(a, op);
+            case 'plano': return await cmdPlano(a, op);
+            case 'fazer': case 'confirmar': return await cmdFazer(a, op);
+            case 'criar': return cmdCriar(a, op);
+            case 'preview': return a._[0] ? await cmdPreview(a._[0], op) : { ok: false, texto: 'Uso: primocode kit preview <slug>' };
+            case 'galeria': case 'escolher': return await cmdGaleria(op);
+            case 'lista': case 'list': case undefined: return { ok: true, texto: listaParaPessoa(op).join('\n') };
+            case 'checar': { const k = achar(a._[0] || '', op); if (!k) return naoExiste(a._[0] || '', op); const e = checar(k.pasta); return { ok: !e.length, texto: e.length ? e.join('\n') : `ok ${k.slug}` }; }
+            default: return { ok: cmd === 'help' || cmd === 'ajuda', texto: AJUDA };
+        }
+    } catch (e) { return { ok: false, texto: `primocode kit ${cmd}: ${e.message}` }; }
+}
+
+/**
+ * O run_shell chama isto antes de abrir um shell (lib/tools.js): `primocode kit …` roda AQUI, no processo do
+ * PrimoCode, pra tela de estilos e a de referências abrirem do jeito certo (no app, pela linha de protocolo).
+ * null quando o comando não é de kit (ou tem operador de shell): aí segue o shell de sempre.
+ */
+async function doShell(comando, op = {}) {
+    const linha = String(comando || '').trim();
+    let w = palavras(linha), resto = '';
+    // "primocode kit batida 2 --help || true", "… 2>&1 | head -50": o modelo cola operador de shell. Sem isto a linha ia
+    // pro shell de verdade, que rodava OUTRO primocode (o instalado no sistema) e abria uma sessão aninhada até o prazo.
+    if (!w) {
+        const pre = antesDoOperador(linha).replace(/\s+\d$/, '');
+        w = palavras(pre);
+        resto = linha.slice(pre.length).trim();
+    }
+    if (!w || w.length < 2 || !/^(primocode|primo)$/.test(path.basename(w[0])) || !/^(kit|kits)$/.test(w[1])) return null;
+    const r = await main(w.slice(2), op);
+    const nota = resto ? `\n(rodei só "${w.join(' ')}" aqui dentro; "${resto.slice(0, 60)}" não roda: o primocode kit responde inteiro, sem pipe)` : '';
+    return { ok: r.ok, code: r.ok ? 0 : 1, stdout: r.texto + nota + '\n', stderr: '', ...(r.ok ? {} : { error: r.texto }) };
+}
+
+/** O começo da linha até o primeiro operador de shell fora de aspas (; & | < > ` $ ( )). */
+function antesDoOperador(linha) {
+    let aspas = null;
+    for (let i = 0; i < linha.length; i++) {
+        const ch = linha[i];
+        if (aspas) { if (ch === aspas) aspas = null; else if (ch === '\\' && aspas === '"') i++; continue; }
+        if (ch === '"' || ch === "'") { aspas = ch; continue; }
+        if (ch === '\\') { i++; continue; }
+        if (/[;&|<>`$()]/.test(ch)) return linha.slice(0, i).trimEnd();
+    }
+    return linha;
+}
+
+/** As batidas que faltam do vídeo sendo montado nesta pasta ([] = pronto ou nenhum). */
+function batidasFaltando(pasta) {
+    const mont = pasta ? lerMontagem(pasta) : null;
+    if (!mont) return [];
+    try {
+        const pl = JSON.parse(fs.readFileSync(path.join(pasta, 'motion', 'plano.json'), 'utf8'));
+        if (pl.kit !== mont.kit) return [];
+        return (pl.cenas || []).map((c, i) => (c.falta ? i + 1 : 0)).filter(Boolean);
+    } catch { return []; }
+}
+/** O pedido da pessoa continua o vídeo? (motion, ou um "sim/continua/pode/segue"): só então a montagem empurra. */
+const CONTINUA = /^\s*(sim|s|ok|okay|pode|continua|continue|segue|siga|bora|vai|manda|faz|isso|beleza|claro|yes|go)\b/i;
+const continuaVideo = (texto) => pareceMotion(texto) || CONTINUA.test(semAcento(texto));
+
+module.exports = {
+    batidasFaltando, continuaVideo,
+    RAIZ, FAMILIAS, casa, listar, achar, lerFrontmatter, menuParaIA, cabecaDoPedido, pareceMotion, ver, tiposDe,
+    validarPlano, checar, esticar, limparPlano, palavras, opcoes, entradaDoPlano, galeriaHtml, listaParaPessoa, previewPronto,
+    novoTurno, turnoAtual, main, doShell, garantirEstudio, conferirQuadros,
+};