primocode 10.15.2 → 10.17.0

package/editor/references/referencia-aplicar.md

@@ -0,0 +1,203 @@
+# Aplicar referência
+
+Você usa a leitura de um vídeo de referência para editar o vídeo do usuário com a mesma linguagem: quem ocupa a
+tela e quando, o que faz cada virada, o ritmo, o jeito da legenda e do texto, as cores e o som na mesma medida. A
+pessoa não é técnica. Ela quer que o vídeo dela "fique com a cara" daquele que ela gostou.
+
+O conteúdo continua sendo dela: a fala, a oferta, o rosto, a marca, o jeito de falar. A referência orienta a forma.
+Ela não entrega oferta, prova, imagem nem direito de uso.
+
+## Antes de começar
+
+**O vídeo do usuário.** O corte aprovado. O estilo entra no plano em blocos e nas peças do projeto HyperFrames.
+
+**A referência.** Três situações:
+
+1. **Já existe a pasta da medida** (`references/referencia-medir.md`): leia o `guia-de-estilo.md` (inclusive a
+   seção 8), o `regras-da-referencia.json`, o `trechos.csv` e o `leitura.md`. Pasta medida antes da troca de nome
+   tem `receita.json` no lugar do primeiro e `mapa.csv` no lugar do `trechos-medidos.csv` (o conteúdo é o mesmo),
+   e o `trechos.csv` dela pode ter colunas com outros nomes: leia pelo sentido. Se o arquivo da referência estiver
+   à mão, confira se é o mesmo (`shasum -a 256` contra o `sha256` do `regras-da-referencia.json`). Confira a
+   cobertura, os tempos e os limites das regras que interessam. Reabra só o que ficou `nao_visto`, o que está em
+   conflito, o que mudou ou a prova que falta para uma decisão. Refazer tudo sem motivo é desperdício.
+2. **Não dá para abrir a referência de novo:** diga que está trabalhando só em cima da leitura anterior. Não finja
+   que assistiu. O que era ESTIMADO continua estimado.
+3. **Não existe medida:** se a pessoa quer a extração completa antes, meça (`references/referencia-medir.md`).
+   Senão, assista o suficiente para entender a abertura, o desenvolvimento, as trocas de foco e o fechamento
+   (folha de quadros e tiras dos momentos que importam) e anote os intervalos que sustentam cada decisão.
+
+Só imagens: dá para trazer composição, cor e tipografia aparente. Movimento, duração e transição não. Link
+fechado: diga o que não deu para ver; pode trabalhar com a descrição da pessoa, marcada como descrição dela.
+
+Não leia a transcrição que fica em `medidas/`: ela é da fala da referência e não serve para o vídeo do usuário.
+
+## Como falar com a pessoa
+
+- Português simples, frases curtas, uma decisão por vez.
+- Comece dizendo em 3 ou 4 linhas o que vai trazer e o que não vai. Exemplo:
+  > "Vou trazer o jeito de montar: você em tela cheia quando opina, a tela do app grande quando mostra, e você
+  > voltando num quadrinho. Também o ritmo (a imagem muda a cada 3 segundos) e a legenda de 2 palavras. Não vou
+  > usar a música nem as frases dela, e a cor de destaque vai ser a da sua marca. Primeiro faço um pedacinho de
+  > uns 10 segundos."
+- Não cole JSON, comandos ou caminhos longos. Tempo no formato 00:12.
+- Antes de gastar dinheiro (imagem, trilha ou efeito gerado por IA), peça autorização.
+- Autorização em camadas: se a pessoa pediu para aprovar a amostra, espere; se já autorizou o vídeo todo, a
+  amostra é teste interno e você segue.
+
+## Três colunas na sua cabeça
+
+Para cada decisão, separe:
+
+| visto ou ouvido | palpite sobre como foi feito | proposta para este vídeo |
+|---|---|---|
+| "a palavra some atrás do ombro dela em 00:07" | "recorte da pessoa com o texto numa camada de trás" | "texto atrás da pessoa na frase principal, depois do teste de recorte" |
+
+Palpite não vira fato. Aparência não prova técnica: uma maquete pode ser vídeo pronto, render ou geometria; um
+fundo trocado pode ser chroma, máscara ou recorte. Escolha uma técnica que existe aqui e cumpre a função, e diga a
+diferença.
+
+## Transfira a gramática, não só os números
+
+O que mais dá identidade a uma referência quase nunca é o número de cortes. Procure e traga:
+
+- **Quem ocupa a tela inteira** e em que momentos a pessoa divide o espaço com outra coisa.
+- **Quanto tempo cada situação fica sem mudar**, em relação à velocidade da fala, e o que dispara cada mudança
+  (uma palavra, uma pausa, a entrada de um exemplo).
+- **Proporção e hierarquia dos textos**: o que é grande, o que é apoio, onde fica cada um.
+- **O papel da cor, da luz, do vazio e do contraste**: o que é aceso, o que fica escuro, quanto respiro tem.
+- **Continuidade**: como um objeto segue de uma cena para a outra e que ação faz a passagem.
+
+Cada regra do `leitura.md` vira decisão pelo campo **quando**: o que a fala do usuário está fazendo, nunca o
+segundo da referência. Regra com firmeza `pede teste` passa por teste antes de virar padrão; `uma vez` entra
+onde a fala dele tiver o mesmo motivo, e não se espalha pelo vídeo.
+
+## Adjetivo vira decisão que dá para conferir
+
+A pessoa diz um adjetivo; você devolve decisões que dá para ver. Alguns jeitos de ler (escolha o que o material
+dela sustenta):
+
+- **"moderno":** poucas cores, muito espaço livre, texto em caixa baixa, cortes secos, nada de brilho.
+- **"divertido":** cores saturadas, texto que entra com um pulinho, efeito sonoro curto em cada entrada, zoom
+  rápido na piada.
+- **"cara de caro":** fundo escuro, uma cor de destaque só, animações lentas e poucas, trilha bem baixa.
+
+Conte a leitura que escolheu em uma linha.
+
+## Várias referências
+
+- Dê um papel a cada uma: uma manda na composição, outra no lettering, outra no som. No fim tem que parecer um
+  vídeo só, com a cara da marca dela.
+- Duas referências mandando na mesma coisa (duas legendas diferentes, dois ritmos): fica o que ela pediu mais
+  recentemente, se ela escolheu. Sem preferência dela e com diferença que muda o vídeo: mostre o conflito com um exemplo de cada e proponha
+  uma saída. Diferença pequena: decida você e conte.
+
+## Adaptação
+
+- Duração, voz e sentido são os da gravação dela. Não acelere a fala nem corte uma condição para imitar o ritmo.
+  Trecho de explicação pode ficar mais longo que na referência.
+- Quando a pessoa tem cor e fonte obrigatórias, elas passam na frente das da referência.
+- Regras do André continuam valendo: zona segura do Reels (texto em y 230 a 1530 e x 140 a 940), legenda de até 3
+  palavras por vez, rosto livre, som casado com cada animação e trilha 22 a 24 dB abaixo da voz.
+
+## Tabela de tradução: medida, decisão e o que adaptar
+
+| Na referência (medido ou estimado) | Decisão no vídeo do usuário | O que adaptar |
+|---|---|---|
+| Cortes por minuto e plano médio (`ritmo`) | Meta de "algo muda na tela" a cada tantos segundos: corte, punch-in, prova, moldura ou animação | Os cortes do usuário nascem da fala dele. Nunca corte no meio da palavra para bater número. Com menos cortes, complete com punch-in, prova e animação |
+| Cortes nos 3 primeiros segundos | Abertura com o mesmo número de mudanças no gancho | Se a referência abre com 2 cortes e o usuário tem uma frase só, use punch-in ou gancho escrito entrando |
+| Maior trecho sem corte | Limite de tempo parado | Passou disso no vídeo do usuário, ponha uma mudança |
+| Quem ocupa a tela e quando (`trechos.csv`) | Os `blocos` do plano: tela cheia, prova, moldura, tela verde, planos | Pelo papel de cada trecho da fala dele, não pelos tempos da referência |
+| Zoom nos cortes e nível | Punch-in e zoom da tela cheia | Acima de 1,2 a imagem perde nitidez; pare em 1,2 |
+| Tamanho do rosto e altura dos olhos | Deixe o enquadramento pelo rosto medido do usuário | Não recorte além de 1,2 para imitar close |
+| Planos sem rosto (imagem de apoio) | Quantidade de provas e inserções por minuto parecida | Material do usuário, prints dele, imagens com licença ou geradas com o ok dele. Nunca imagens da referência. Ilustração nunca como prova |
+| Posição da legenda (`legenda.centro_y`) | A legenda do projeto fica pelo rosto (no peito) | Só mude de lugar se o vídeo dele tiver o mesmo motivo. Fique na zona segura |
+| Palavras por linha | `legenda.max_palavras` (até 3) e `legenda.max_letras` do projeto | Frases longas do usuário quebram em mais trocas; tudo bem |
+| Caixa alta, contorno, fundo atrás | Estilo da legenda e das peças | Fundo claro no vídeo do usuário pede contorno ou fundo, mesmo que a referência não tenha |
+| Lettering e hierarquia | `references/lettering.md` com a hierarquia vista | O texto é escrito para a fala dele. Nunca a frase da referência |
+| Cor do texto e cor de destaque | Cor de destaque do projeto | Com cor de marca, use a da marca com brilho parecido. Confira contraste |
+| Forma da letra | Fonte livre parecida (tabela "Fontes") | Veja abaixo |
+| Texto de gancho nos 3 s (`gancho_escrito`) | Gancho escrito na mesma zona, maior que a legenda | Nunca a frase da referência |
+| Textos fixos (rótulos, títulos) | Só a forma: "rótulo pequeno no topo por 5 s" | Nunca o texto, nunca @, logo ou marca d'água |
+| Cores da imagem (`cores.dominantes`) | Paleta dos cartões, diagramas e peças | Não pinte o vídeo do usuário para parecer o da referência |
+| Loudness | -14 LUFS, pico -1 | Mesmo que a referência esteja mais alta |
+| Trilha: diferença para a voz | 22 a 24 dB abaixo da voz (o padrão do André) | Mais alta só se a pessoa pedir. Nunca a música da referência (`references/som-e-trilha.md`) |
+| Efeitos por minuto | Um som por animação que importa, no quadro em que ela bate | Confiança baixa: pergunte se ela ouve efeitos. Sons livres desta skill |
+| Família dos efeitos (grave, cheio, agudo) | Grave: impacto. Cheio: whoosh. Agudo: pop, clique | O timbre exato não foi ouvido; escolha pelo movimento |
+| Palavras por minuto e pausas | Nada muda na voz | O ritmo da fala vem do corte. Nunca acelere a voz |
+| Transições e continuidade (`leitura.md`) | Transições em cadeia do plano (`references/direcao-por-blocos.md`) | Com a técnica disponível aqui. O que não dá, deixe de fora e diga |
+
+Status importa: **MEDIDO** pode virar meta direta. **ESTIMADO** é ponto de partida e passa pela amostra. **NÃO DÁ
+PRA SABER** não vira decisão. Campo `null` no `regras-da-referencia.json`: decida com a pessoa ou use o padrão desta skill. O
+bloco `editor_video` dele traz os mesmos números com os nomes do `edit_data.json` do motor antigo desta skill; no
+projeto HyperFrames, use a tabela acima.
+
+## O que nunca copiar
+
+- **Fala e roteiro**: frases, ganchos, promessas, chamadas. Nem trocando uma palavra.
+- **Promessa e números de resultado da referência**: faturamento, prints de venda, depoimentos. São de outra
+  pessoa e não valem para o vídeo do usuário.
+- **Marca**: nome, logo, @, marca d'água, produto, interface ou vinheta da referência.
+- **Música e sons com direito**: a trilha da referência e qualquer som tirado dela.
+- **Pessoa**: rosto, voz, jeito característico de apresentação de quem aparece na referência.
+- **Imagens e gráficos prontos** da referência (prints, ilustrações, cartões com texto).
+- **Fonte paga**: se a fonte da referência não for livre, use uma parecida (abaixo).
+
+Se a pessoa pedir para copiar algo dessa lista, explique em uma frase por que não dá e ofereça a versão própria
+(outra música do mesmo clima, gancho escrito para a oferta dela).
+
+## Fontes
+
+A medida dá a forma da letra, não o nome. Escolha pela forma, sempre entre fontes livres:
+
+| Forma medida | Google Fonts (livres) |
+|---|---|
+| Estreita (condensada) | Anton, Bebas Neue, Oswald |
+| Média | Inter, Figtree, Manrope |
+| Larga (geométrica) | Montserrat, Poppins, Archivo |
+| Escrita à mão | Caveat, Permanent Marker |
+
+- Se a pessoa souber o nome da fonte da referência e ela for paga, use a parecida da tabela. Se ela tiver a licença
+  e mandar o arquivo, pode usar o arquivo dela.
+- Peso: legenda de reel quase sempre é pesada (800 ou 900).
+- No projeto, a fonte vai em arquivo com `@font-face` e passa pela checagem de caracteres do português
+  (`references/lettering.md`). Registre a troca na entrega.
+
+## A amostra
+
+- 8 a 15 s do vídeo do usuário. Não escolha pelo começo: escolha o trecho com o que mais marca a referência e com
+  o ponto em que você teve de adaptar.
+- Monte no estúdio (`references/estudio.md`), sem render.
+- Compare gramática, não pixels. Se a amostra só lembra a paleta e não repete os movimentos que dão identidade à
+  referência, está incompleta.
+- Pediu para aprovar: mostre e espere. Já autorizou tudo: confira pelos critérios e siga.
+
+Está bom quando: quem fala e o que se diz continuam sendo dela; cada decisão aponta para um momento da referência;
+tudo se lê no celular; e nada entrou por palpite.
+
+## Passo a passo
+
+1. Leia a medida (ou assista, se não houver) e confira se a referência combina com o vídeo do usuário. Uma
+   referência cheia de 3D não vira isso num vídeo simples de celular. Diga o que dá para trazer.
+2. Conte o plano em 3 ou 4 linhas (o que traz, o que não traz).
+3. Escreva a tabela de transferência em `transferencia.md` na pasta do projeto, uma linha por decisão, com quatro
+   colunas: prova vista (id ou tempo na referência), regra, adaptação, como conferir.
+4. Monte as decisões no plano em blocos e no `projeto.json` (tabela de tradução).
+5. Amostra no estúdio (seção acima).
+6. Vídeo inteiro no estúdio, render só no fim, conferência do arquivo exportado.
+7. Confira o resultado contra a referência com números: rode o `helpers/medir_referencia.py` no vídeo final numa
+   pasta nova e compare cortes por minuto, posição da legenda, efeitos por minuto e trilha. Diferença grande que
+   ninguém escolheu vira ajuste.
+8. Nota de entrega curta: as regras que vieram da referência, as adaptações feitas de propósito, as técnicas
+   trocadas e os limites. Separe o que foi visto na referência do que foi proposta sua.
+
+## Quando não combina
+
+- **Referência com legenda em outro idioma**: mantenha a forma, a legenda do usuário sai na língua dele.
+- **Referência horizontal e vídeo vertical** (ou o contrário): converta as posições pela fração da altura
+  (`centro_y`), não pelos pixels.
+- **Referência com dois vídeos empilhados ou tela dividida**: escolha com a pessoa qual metade é o estilo que ela
+  quer; use as medidas daquela posição.
+- **Referência muito mais rápida que a fala do usuário**: não force. Chegue perto com punch-in, provas e animação e
+  diga à pessoa que o ritmo final depende da fala dela.
+- **Medida com confiança baixa** (áudio mono, fala sem pausa, legenda não achada): decida junto com a pessoa,
+  ouvindo ou olhando a referência, e diga que foi decisão de ouvido.

package/editor/references/referencia-medir.md

@@ -0,0 +1,375 @@
+# Referência medida
+
+Você mede como um vídeo de referência foi editado e transforma isso em regras que a edição do usuário pode
+seguir. Quem conversa com você não é técnico. A pessoa manda o vídeo de outra pessoa e diz "quero assim". Seu
+trabalho aqui é descobrir, com medida e com prova, o que é esse "assim" e explicar em palavras simples.
+
+Este passo só mede. Fazer a medida não autoriza editar nada. Só siga para a edição se o pedido já incluía isso.
+Quem usa a medida no vídeo do usuário é `references/referencia-aplicar.md`.
+
+## Como falar com a pessoa
+
+- Português simples, frases curtas. Diga "a imagem muda a cada 2 segundos", e não "30 cortes por minuto".
+- Não cole JSON, comandos, caminhos longos nem log na conversa.
+- Antes de rodar, avise o tempo: perto de 1 a 2 minutos para um reel de 1 minuto; uns 25 minutos para um vídeo
+  de 30 minutos. A transcrição e a leitura de texto são as partes mais lentas. A leitura com prova (trechos,
+  regras e pedido) leva mais uns minutos.
+- No fim, conte o que achou em 4 a 6 frases e pergunte se era isso que ela gostou no vídeo.
+- Se ela disser "decide você", decida, conte a decisão em uma linha e siga.
+
+## Regras fixas
+
+1. A medida serve para estilo. Fala, promessa, marca, logo, música, a pessoa da referência e números de
+   resultado nunca vão para o vídeo do usuário.
+2. Nunca grave nada na pasta do vídeo de referência e nunca altere o arquivo dele. A saída vai numa pasta
+   própria, por exemplo `<pasta do projeto do usuário>/referencias/<nome-curto>/`. Uma referência por pasta; não
+   sobrescreva a pasta de outra.
+3. Todo achado tem um grau, e você nunca apresenta um grau como outro:
+   - **MEDIDO** (constatado): tem prova que se localiza, vista, ouvida ou medida por uma ferramenta que você
+     sabe dizer qual é, num tempo que dá para achar.
+   - **ESTIMADO** (hipótese): diga o que sustenta e o que ele não prova.
+   - **NÃO DÁ PRA SABER**: diga o que impede.
+4. Não invente o que está no "não dá pra saber": tempo, quadro, nome da fonte, plugin, programa, arquivo
+   escondido, canal de transparência, geometria 3D, retenção. Ver as letras sumindo atrás do corpo é observação;
+   dizer qual programa recortou é invenção.
+5. Olhe as imagens antes de falar dos números. O script erra em vídeo com muita animação, e a folha de quadros
+   mostra o erro.
+6. Três pessoas, três vídeos: meça cada um na sua pasta e compare depois.
+7. Nada pago, nada instalado, nenhum modelo grande baixado e nenhum envio da mídia para fora sem autorização que
+   cubra isso. Sem ela, use o que há e diga o que perdeu.
+
+## Do que precisa
+
+- Esta skill instalada. O helper roda com o Python dela (numpy, opencv, pillow) e usa o detector de rosto, a
+  leitura de texto e a transcrição dela.
+- `ffmpeg` e `ffprobe` no sistema.
+- No Mac, a leitura de texto usa a Vision da Apple e lê as palavras. Em outro sistema ela só acha manchas de
+  texto: posição sai, mas palavras por linha e caixa alta ficam sem medida.
+
+`<SKILL>` abaixo é a pasta desta skill (a do SKILL.md).
+
+## O que a pessoa pode mandar
+
+- **Arquivo** (mp4, mov, m4v, webm): o caminho normal.
+- **Só um link:** peça o arquivo (salvar o vídeo ou gravar a tela do celular). Se não der, trabalhe com o que ela
+  descrever, marcado como descrição dela, e crie a pasta com um `leitura.md` que diz o impedimento. Nada de
+  análise inventada.
+- **Só imagens** (prints, quadros): dá para falar de composição, cor e tipografia aparente. Movimento, duração,
+  transição e som ficam NÃO DÁ PRA SABER. Áudio é desconhecido, nunca "era mudo".
+- **Vídeo sem som de verdade** (sem faixa de áudio): a análise é só visual. Não reconstrua a fala pelo texto da
+  tela.
+
+Use só vídeo que ela pode assistir; a medida é estudo de estilo.
+
+## Passo a passo
+
+1. **Pegue o arquivo** (seção acima).
+2. **Escolha a pasta de saída**, fora da pasta da referência.
+3. **Rode** (caminhos sempre entre aspas simples; nome de reel costuma ter emoji, `#` e espaço):
+
+   ```bash
+   uv run --directory "<SKILL>" python helpers/medir_referencia.py '<VIDEO>' --saida '<SAIDA>'
+   ```
+
+   Opções:
+   - `--limiar 0.20`: nota de cena para contar corte seco. Baixe para `0.12` se a folha mostrar cortes que o
+     script não pegou (corte entre planos muito parecidos). Suba para `0.30` se ele marcar animação como corte.
+   - `--sem-fala`: pula a transcrição (vídeo sem fala, ou pressa). Perde ritmo de fala e a checagem "a legenda
+     escreve a fala".
+   - `--transcricao arquivo.json`: usa uma transcrição já pronta (formato do `transcribe.py` desta skill).
+   - `--sem-texto`: pula a leitura de texto.
+   - `--fps-texto 2`: leituras de texto por segundo. Suba para 4 se a legenda trocar muito rápido.
+   - `--editor-video PASTA`: usa os helpers de outra instalação da skill (o padrão é esta).
+
+   Rodar de novo na mesma pasta sobrescreve o que o script escreve (não os arquivos que você escreveu à mão).
+
+4. **Confira (obrigatório).**
+   - Abra `folha-de-quadros/folha_01.jpg` (e as seguintes). Cada quadro é 1 segundo. Borda vermelha = corte;
+     borda laranja = corte provável; etiqueta SOM = efeito sonoro provável naquele segundo.
+   - Abra `cortes-para-conferir.jpg`. Cada par mostra o último quadro antes e o primeiro depois. Corte de verdade
+     muda o enquadramento, o zoom ou a cena. Imagem entrando por cima do vídeo, painel animado ou texto grande
+     aparecendo também marcam nota alta: anote como "inserção" ou "animação", não como corte.
+   - Abra 2 ou 3 arquivos de `recortes/` para confirmar cor, contorno e forma da legenda.
+   - Nos momentos que importam (entrada de texto, transição, pessoa que muda de tamanho), gere uma tira densa
+     (seção "Ver um trecho de perto").
+   - Número que não bate com a imagem: confie na imagem e corrija a linha no guia com "(corrigido olhando a folha)".
+5. **Complete a seção 8 do guia** ("Leitura da IA"): tipo de vídeo, elementos gráficos, transições, imagens de
+   apoio, como abre e como fecha. Descreva a forma. Não copie frases da referência.
+6. **Escreva a leitura com prova**: `trechos.csv` e `leitura.md` (seções abaixo).
+7. **Escreva o pedido reutilizável**: `pedido.md` (seção abaixo).
+8. **Faça a autoconferência** do pacote (seção abaixo).
+9. **Conte para a pessoa.** Exemplo de tom:
+   > "Medi o vídeo. A imagem muda a cada 3 segundos, mais ou menos. A legenda fica um pouco abaixo do queixo,
+   > com 2 palavras por vez, letra branca grossa e a palavra falada em lilás. Quando ela fala de um passo, a
+   > tela vira a demonstração e ela volta num quadrinho. Tem música bem baixinha e uns 8 efeitos de som, quase
+   > sempre quando entra um elemento novo. Era esse jeito que você gostou?"
+10. **Próximo passo.** Se ela quiser usar no vídeo dela (e o pedido cobre isso), siga
+    `references/referencia-aplicar.md` com esta pasta.
+
+## O que sai na pasta
+
+| Arquivo | Quem escreve | Para que serve |
+|---|---|---|
+| `guia-de-estilo.md` | script + você (seção 8) | Tudo que foi medido, em português, separado em MEDIDO, ESTIMADO e NÃO DÁ PRA SABER. |
+| `regras-da-referencia.json` | script | Os mesmos números para máquina: ficha resumida e o sha256 da referência, ritmo, legenda, cores, áudio, e um bloco `hyperframes` com cores e tipografia de partida. |
+| `trechos-medidos.csv` | script | Um segundo por linha: plano, corte, o que aparece, o que está escrito na tela (`escrito_na_tela`), som. Coluna `observacao` para você. |
+| `trechos.csv` | você | Uma linha por plano, virada sem corte, trecho não visto ou quadro solto, agrupadas por ideia. |
+| `leitura.md` | você | Cobertura, provas, achados por eixo e as regras reaproveitáveis. |
+| `pedido.md` | você | O pedido para usar esta referência depois, com três lacunas. |
+| `folha-de-quadros/` | script | 1 quadro por segundo em grade, com tempo, cortes e efeitos marcados. |
+| `cortes-para-conferir*.jpg` | script | Par antes e depois de cada corte achado. |
+| `recortes/` | script | Legenda e textos fixos em tamanho de trabalho. |
+| `tiras/` | você | Tiras densas dos trechos que você olhou de perto. |
+| `medidas/` | script | Dados brutos. A ficha técnica completa fica em `medidas/ficha.json` (sha256, fps, se a taxa é variável, codecs, canais e taxa do áudio). A transcrição da referência fica aqui e não entra em nenhum texto do usuário. |
+
+Pasta medida antes da troca de nome tem `receita.json` no lugar do `regras-da-referencia.json` e `mapa.csv` no
+lugar do `trechos-medidos.csv` (lá a coluna `escrito_na_tela` se chamava `texto_na_tela`). O conteúdo é o
+mesmo: leia o nome antigo quando o novo não existir. Rodar de novo nessa pasta escreve os nomes novos e avisa
+que os antigos sobraram.
+
+Tudo em UTF-8, com caminhos relativos à pasta. Tempo sempre em segundos, contados do zero do arquivo que você
+tem, com as casas que o método sustenta (a 30 qps, 0,033 s). Em taxa variável, use o tempo de cada quadro, não
+número do quadro vezes a média.
+
+## Cobertura: o que foi visto de verdade
+
+No começo do `leitura.md`, uma linha para cada meio: imagem, som e transcrição. Para cada um: o estado, os
+intervalos examinados, o método e os buracos com o motivo.
+
+| estado | quando |
+|---|---|
+| total | você examinou o meio inteiro, sem buraco |
+| parcial | examinou só uma parte, ou com um método que não cobre tudo |
+| sem acesso | o meio existe mas não deu para examinar (ferramenta faltando, link fechado) |
+| não se aplica | o meio não existe (vídeo sem faixa de áudio) |
+
+- Folha de 1 quadro por segundo e pares de corte orientam, mas não são passagem contínua: com eles, a imagem é
+  **parcial**. Imagem **total** só se você viu tiras densas (10 qps ou mais) do vídeo inteiro.
+- Ler a duração nos metadados não é ter assistido.
+- Ferramenta faltando é "sem acesso", não "não se aplica".
+- Se algum meio ficou parcial ou sem acesso, o pacote não se diz completo, e isso aparece no `pedido.md`.
+
+## Trechos por emenda e por ideia (trechos.csv)
+
+O `trechos-medidos.csv` conta o vídeo segundo a segundo; o `trechos.csv` conta a montagem. Você escreve este a
+partir da folha, dos pares de corte e das tiras, sempre pelo módulo `csv` do Python (ele cuida de vírgula, aspas e
+quebra de linha dentro do texto).
+
+Como dividir:
+
+- Toda emenda confirmada abre uma linha `plano`. Dentro de um plano, abra uma linha `virada` sempre que a tela muda
+  sem corte: a demonstração dá mais um passo, o arranjo troca, o olho é puxado para outro canto.
+- Linhas que contam a mesma ideia levam o mesmo código em `ideia` (`I01`, `I02`...). Três cortes seguidos podem ser
+  uma ideia só.
+- O segundo de `de_s` pertence ao trecho; o de `ate_s` já é do seguinte (de `12.40` a `15.10`, o quadro de 15,10 s
+  é do próximo). Uma transição fica numa linha só, nunca nas duas. Borda incerta: `exatidao` diz `aproximada` e
+  como você chegou nela.
+- Pedaço do vídeo que você não examinou também vira linha, `nao_visto`. Um quadro olhado isolado vira
+  `quadro_solto`, sem `ate_s`, e não tapa o buraco de um trecho não visto.
+- Uma linha `plano` ou `virada` tem que bastar para alguém refazer a cena: de onde parte, o que se vê acontecer,
+  onde termina, para onde o olho vai e que palavras da fala estão por baixo (poucas, só para achar o ponto).
+- Célula vazia é ambígua. Escreva `nao_olhei` quando não examinou aquilo naquele trecho e `nao_tem` quando olhou e
+  não havia.
+
+Colunas, nesta ordem: primeiro o tempo e a fala (é por eles que quem edita acha o trecho), depois a imagem, o som
+e as provas.
+
+| coluna | o que vai |
+|---|---|
+| `trecho` | código único da linha (`T01`, `T02`...) |
+| `de_s`, `ate_s` | começo e fim, em segundos |
+| `exatidao` | `exata` ou `aproximada`, com o método |
+| `ideia` | o código da ideia que a linha ajuda a contar |
+| `natureza` | `plano`, `virada`, `nao_visto` ou `quadro_solto` |
+| `fala_para_achar` | poucas palavras da fala, só para localizar |
+| `palavra_que_dispara` | a palavra ou a ideia que faz a tela mudar, e com quanto atraso |
+| `pessoa_no_quadro` | tamanho e lugar de quem fala, e quando divide a tela |
+| `o_olho_segue` | o que puxa o olhar naquele trecho |
+| `escrito_na_tela` | título, rótulo ou chamada fora da legenda: lugar, tamanho, forma |
+| `legenda` | posição, palavras por vez, destaque |
+| `entra_por_cima` | imagem, print ou peça que cobre o vídeo |
+| `frente_e_fundo` | o que fica atrás e o que fica na frente da pessoa |
+| `cores` | paleta, contraste, luz |
+| `passagem` | como este trecho vira o próximo |
+| `o_que_se_ouve` | voz, trilha e efeitos, e qual deles manda |
+| `andamento` | quanto tempo fica parado, onde respira |
+| `provas_ligadas` | ids das provas do `leitura.md` que apontam para esta linha |
+| `nota` | o que não coube nas outras |
+
+## Os doze eixos (leitura.md)
+
+Para cada eixo, pelo menos um achado: algo que existe, uma ausência que você viu, ou um limite que impediu de ver.
+Nenhum eixo fica em silêncio. Cada achado tem grau e aponta para provas.
+
+| eixo | o que olhar | o que a imagem sozinha não prova |
+|---|---|---|
+| legenda | posição, palavras por vez, quebras, destaque, sincronia | sem som, a sincronia |
+| tipografia e hierarquia | forma, peso, caixa, largura, lugar, o que manda | o nome da fonte |
+| pessoa no quadro | onde está, com que folga, quando divide a tela | rosto no centro não prova rastreamento |
+| recorte, zoom e acompanhamento | quando aproxima, quando reenquadra | câmera, recorte e escala podem parecer iguais |
+| camadas e oclusão | o que fica atrás e na frente, paralaxe | vídeo achatado não mostra a pilha do projeto |
+| recorte do fundo e volume | pessoa recortada, profundidade | o método (fica inferido) |
+| o que entra por cima | tipo, tamanho, para que serve, quando entra, quanto fica, como sai | que o arquivo de origem exista |
+| transições e continuidade | o que liga um estado ao outro | nome de plugin por semelhança |
+| cor e luz | paleta aparente, contraste, vazio | a cor tirada de vídeo comprimido é aproximada |
+| som | o que é voz, música e efeito, quando cada um entra e sai, qual fica por cima | nome da música, licença, loudness exato sem medida |
+| fala e movimento | que verbo ou ideia dispara cada ação, e com que atraso | |
+| ritmo | quanto dura cada ideia, quanto tempo fica parado, onde respira | retenção, venda ou tempo de produção |
+
+Provas: `P01`, `P02`... Cada uma com os trechos do `trechos.csv` ligados, o tempo, a exatidão, o método (folha,
+tira a 30 qps, medida do script, ouvido) e uma descrição curta; se tiver, o arquivo auxiliar (a tira em `tiras/`).
+Prova só aponta para linha que você viu (nunca para `nao_visto`), e com tempo compatível.
+
+## Regras reaproveitáveis (leitura.md)
+
+Das provas saem as regras (`R01`, `R02`...). Escreva cada uma como uma ficha que outra pessoa consiga seguir no
+vídeo dela, com estes campos, nesta ordem (primeiro o quanto dá para confiar, depois o que fazer, por último como
+checar):
+
+1. **firmeza:** `se repete` (visto em mais de um ponto), `uma vez` (escolha isolada que vale levar) ou `pede teste`
+   (depende de palpite ou de técnica que ninguém testou aqui; teste antes de virar padrão).
+2. **apoiada em:** os ids das provas. Limite que pesa sobre uma delas aparece escrito aqui também.
+3. **quando:** o que a fala do vídeo alvo precisa estar fazendo para a regra entrar ("quando a pessoa cita uma
+   etapa"). Segundo da referência nunca é resposta para "quando".
+4. **o que acontece:** na tela ou no som.
+5. **até quando:** critério de leitura, não cronômetro ("até terminar de dizer a etapa"). A duração vista na
+   referência vai junto como número observado, não como ordem.
+6. **como sai:** de que jeito e em que momento vai embora.
+7. **não pode perder:** o que continua intacto enquanto a regra age (rosto livre, legenda legível).
+8. **estraga se:** o erro que desmonta a regra.
+9. **precisa de:** o que a pessoa manda e o que teria de ser feito ou conseguido (com autorização).
+10. **se mudar o formato:** o que muda com outra proporção, outro tamanho, menos recurso ou outra marca.
+11. **como conferir:** o teste no vídeo do usuário.
+
+No fim do `leitura.md`, três listas curtas: o que dá para transferir, o que exige material da própria pessoa e o
+que precisa de teste. Sem slogan, roteiro, depoimento ou identidade da referência nessas listas. E uma linha de
+encaminhamento: que partes desta skill ajudam depois (lettering, animação, enquadramento, variações) e por quê.
+
+## O pedido reutilizável (pedido.md)
+
+Um texto pronto para a pessoa (ou você, numa conversa futura) usar esta referência em outro vídeo. Específico
+desta referência. Tem exatamente três lacunas entre colchetes: `[VÍDEO ALVO]`, `[FORMATO DE SAÍDA]` e
+`[IDENTIDADE VISUAL]`. Nenhuma instrução de preenchimento sobra no arquivo.
+
+Escreva como pedido, em primeira pessoa da pessoa, cobrindo:
+
+1. Ler o `guia-de-estilo.md`, o `regras-da-referencia.json`, o `trechos.csv` e o `leitura.md` desta mesma pasta,
+   e avisar se só o texto do pedido estiver disponível.
+2. As instruções e autorizações atuais da pessoa vencem o que esta medida sugere.
+3. Não copiar fala, voz, marca, oferta, prova, música nem imagem da referência.
+4. As regras, cada uma com id, firmeza, quando, o que acontece, estraga se e como conferir, separando o que foi
+   visto na referência do que é sugestão de adaptação.
+5. Os limites desta medida (cobertura parcial, graus ESTIMADO).
+6. Recalcular a sequência pela fala e pela duração do vídeo alvo; nunca copiar tempos.
+7. Mostrar primeiro uma amostra com a passagem de cena e o arranjo visual que mais marcam a referência, e só
+   depois espalhar o padrão pelo vídeo (se tudo já estiver autorizado, a amostra é teste interno).
+8. Camada inclinada é 2,5D, não 3D; máscara não é recorte; movimento calculado por quadro; nada pago sem
+   autorização.
+9. Sem identidade visual: propor uma direção própria, nunca a da referência.
+
+## Autoconferência do pacote
+
+Antes de dizer que terminou:
+
+- Os arquivos existem. `regras-da-referencia.json` abre como JSON e `trechos.csv` abre como CSV.
+- Ids únicos; toda prova e toda regra apontam para ids que existem.
+- Prova nenhuma aponta para linha `nao_visto`.
+- Nenhum início depois do fim, nada além da duração, nenhuma sobreposição entre planos.
+- O estado da cobertura bate com o método (medir a duração ou transcrever não é cobertura de imagem).
+- Todo limite que pesa sobre um achado aparece na regra que depende dele e no `pedido.md`.
+- As três lacunas estão no `pedido.md`.
+- Nada foi renderizado, postado ou mandado para serviço por causa da medida.
+
+Parte disso se confere com um script curto (grave na pasta de saída e rode com o Python da skill):
+
+```python
+# conferir_pacote.py  uso: uv run --directory "<SKILL>" python '<SAIDA>/conferir_pacote.py' '<SAIDA>'
+import csv, json, re, sys
+from pathlib import Path
+pasta = Path(sys.argv[1])
+regras = next(a for a in (pasta / "regras-da-referencia.json", pasta / "receita.json") if a.exists())  # nome antigo: receita.json
+dur = json.loads(regras.read_text(encoding="utf-8"))["ficha"]["duracao_s"]
+linhas = list(csv.DictReader(open(pasta / "trechos.csv", encoding="utf-8")))
+ids = [l["trecho"] for l in linhas]
+erros = [f"trecho repetido: {i}" for i in sorted({i for i in ids if ids.count(i) > 1})]
+planos = []
+for l in linhas:
+    if l["natureza"] == "quadro_solto":
+        continue
+    a, b = float(l["de_s"]), float(l["ate_s"])
+    if a > b or b > dur + 0.05:
+        erros.append(f"{l['trecho']}: tempo fora ({a} a {b}, duração {dur})")
+    if l["natureza"] == "plano":
+        planos.append((a, b, l["trecho"]))
+planos.sort()
+erros += [f"sobreposição: {x[2]} e {y[2]}" for x, y in zip(planos, planos[1:]) if y[0] < x[1] - 0.01]
+leitura = (pasta / "leitura.md").read_text(encoding="utf-8")
+for l in linhas:
+    for p in filter(None, re.split(r"[;\s]+", l["provas_ligadas"])):
+        if p not in leitura:
+            erros.append(f"{l['trecho']}: prova {p} não está no leitura.md")
+        if l["natureza"] == "nao_visto":
+            erros.append(f"{l['trecho']}: trecho não visto com prova {p}")
+pedido = (pasta / "pedido.md").read_text(encoding="utf-8")
+erros += [f"pedido.md sem {x}" for x in ("[VÍDEO ALVO]", "[FORMATO DE SAÍDA]", "[IDENTIDADE VISUAL]") if x not in pedido]
+print("\n".join(erros) or "ok")
+```
+
+Validar a estrutura não substitui olhar. Confira no próprio vídeo as fronteiras de corte, a duração dos estados,
+a sincronia e os trechos `nao_visto` que você declarou.
+
+Na conversa, diga onde estão as peças, a cobertura atingida e o que limita o reuso.
+
+## Como cada número é medido
+
+| No guia | Em palavras simples | Como | Confiança |
+|---|---|---|---|
+| Cortes, cortes por minuto, plano médio | De quanto em quanto tempo a imagem muda | Nota de mudança de cena do ffmpeg (`select` com `scene`) em todos os quadros. Corte = nota 0,20 ou mais. Provável = pico fraco 8 vezes maior que a vizinhança | Medido. Prováveis precisam de conferência |
+| Rosto, altura do rosto, olhos | Quão perto a câmera está | Detector de rosto YuNet em 1 quadro por segundo e no meio de cada plano | Estimado |
+| Zoom nos cortes | Se o rosto muda de tamanho de um plano para o outro | Tamanho do rosto antes e depois de cada corte | Estimado |
+| Posição, altura da linha, palavras por linha, linhas, caixa alta | Onde e como a legenda fica | Leitura de texto 2 vezes por segundo (helper `texto_na_tela.py` desta skill). A legenda é o texto que troca e bate com a fala da transcrição. Outra posição só conta se durar 2,5 s seguidos com a mesma altura de letra | Medido |
+| Tamanho da fonte, forma da letra, cores do texto | Parecença da letra | Altura da linha lida, largura por letra, cores do miolo das letras | Estimado |
+| Loudness, pico | Volume percebido | Filtro loudnorm do ffmpeg (padrão EBU R128) | Medido |
+| Trilha, quanto abaixo da voz | Se tem música e quão baixa | Nível nas pausas da fala, picos de nota musical e o canal lateral (esquerdo menos direito, onde a voz centralizada some) | Estimado |
+| Efeitos sonoros | Quantos sons de edição e onde | Canal lateral subindo 6 dB acima dos 4 s em volta, sons nas pausas, graves que a voz não explica | Estimado. Confiança baixa em áudio mono |
+| Palavras por minuto, pausas | Velocidade da fala | Transcrição local (Whisper desta skill) | Medido |
+
+Os limiares foram ajustados em dois reels que já tinham sido medidos à mão. Nesse teste, os 6 cortes secos
+bateram no quadro, a posição da legenda ficou a 6 px da medida manual, as cores da legenda ficaram a poucos pontos
+de hex, e o detector de efeitos achou 9 de 14 e 23 de 30 efeitos marcados. Use esses números como ordem de
+grandeza da precisão, não como garantia.
+
+## Quando o resultado sai estranho
+
+- **Animação marcada como corte** (painel entrando, tela girando): a folha mostra. Anote no guia como transição
+  animada e, no `trechos.csv`, como `virada` dentro do plano. Se forem muitas, rode de novo com `--limiar 0.30`.
+- **Corte que o script não pegou** (dois planos quase iguais): rode com `--limiar 0.12` e confira os pares.
+- **Transição de vários quadros** (chicote, zoom rápido): aparece com "(vários quadros)" na lista.
+- **Legenda não achada**, mas ela existe na folha: a letra pode ser muito enfeitada para a leitura. Meça à mão
+  pela folha e pelos recortes e marque como "medido olhando".
+- **Texto fixo que não é legenda** (título, @, marca d'água, chamada): fica em "Textos que ficam parados". O que
+  parecer marca ou perfil vem marcado "não copiar".
+- **Dois vídeos empilhados ou tela dividida**: as posições valem para o quadro inteiro. Diga isso no guia.
+- **Áudio mono** (celular sem estéreo): efeitos sonoros ficam com confiança baixa. Não use o número como meta;
+  pergunte à pessoa se ela ouve efeitos no vídeo.
+- **Fala sem pausa**: o som de fundo fica "incerto". Não afirme que tem ou não tem trilha.
+- **Taxa de quadros variável** (`fps_variavel` em `medidas/ficha.json`): os tempos dos cortes são os carimbos de cada quadro.
+  Não converta número de quadro em tempo pela média.
+- **Vídeo longo** (VSL de 10 minutos ou mais): demora (uns 25 minutos para 30 minutos de vídeo) e a conferência
+  de cortes vira uma amostra de até 120 pares. Os primeiros minutos não valem como padrão do resto. Meça em
+  pedaços em sequência, cada um encavalando uns 2 s no anterior, confira as emendas entre os pedaços e o
+  encerramento. Com pressa, meça três trechos (começo, meio e fim) e declare a cobertura como parcial:
+  `ffmpeg -ss 300 -i '<VIDEO>' -t 120 -c copy '<SAIDA>/trecho_05min.mp4'`.
+
+## Ver um trecho de perto
+
+A folha tem 1 quadro por segundo. Para ver como uma palavra entra, quanto dura um zoom ou em que quadro um título
+some, gere uma tira de quadros do trecho:
+
+```bash
+uv run --directory "<SKILL>" python helpers/tira_de_quadros.py '<VIDEO>' 17.4 17.9 --fps 30 --faixa 0.66:0.78 --saida '<SAIDA>/tiras/legenda_17s.jpg'
+```
+
+`--fps 30` mostra quadro a quadro; `--faixa` corta só uma parte da altura (a faixa da legenda, por exemplo).
+Conte os quadros para escrever a duração no guia (a 30 qps, 3 quadros = 0,1 s). Cada tira que sustenta um achado
+vira arquivo auxiliar de uma prova.