@intelli-ia/easyedit 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.2.0
+- Suporte a Windows (e Linux): `doctor` funciona com `npx.cmd`, mostra o sistema e como instalar cada dependência por sistema.
+- Verificador de zonas seguras: sem detecção automática (Windows/Linux), gera folhas de revisão visual com as zonas em vermelho e exige a conferência; `--manual 1` força o modo; `EASYEDIT_DETECTOR` aceita um detector externo.
+- `TOOLS.md` agora é neutro quanto a sistema e caminhos.
+- CI no GitHub Actions em ubuntu, macOS e Windows (Node 22 e 24).
+
+## 0.1.0
+- Primeira versão: `install`, `update`, `doctor`, `novo`, `progress`.
+- 13 skills `easyedit-*`, contrato `.easyedit/Spec.md` e template de spec.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# EasyEdit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Especificação, entrevista e acompanhamento de edição de vídeo (HyperFrames) em forma de skills para agentes de código.
+
+## Instalar a CLI
+    npm install --global @intelli-ia/easyedit
+    # desenvolvimento: npm link nesta pasta
+
+## Usar num projeto
+    cd meu-projeto-de-video
+    easyedit install      # skills em .claude/skills, contrato em .easyedit/, seção no CLAUDE.md
+    easyedit doctor       # confere Node, FFmpeg, HyperFrames, whisper
+    easyedit update       # atualiza; preserva specs e .easyedit/TOOLS.md
+
+Depois abra uma sessão nova do agente e use `/easyedit-novo` → `/easyedit-interviewer` → `/easyedit-build`.
+
+## Requisitos
+Node 22+, FFmpeg no `PATH` e HyperFrames no projeto (`npm i -D hyperframes`). Whisper.cpp (ou Parakeet) para transcrição. `easyedit doctor` diz o que falta e como instalar no seu sistema.
+
+| | macOS | Windows |
+| --- | --- | --- |
+| CLI e skills | ✔ | ✔ |
+| FFmpeg | `brew install ffmpeg` | `winget install Gyan.FFmpeg` |
+| Detecção automática de rosto nas zonas seguras | ✔ (Vision) | revisão visual de folhas de contato (obrigatória no gate); `EASYEDIT_DETECTOR` aceita um detector próprio |
+| Render | mais rápido (Apple Silicon) | ✔ |
+O EasyEdit espera a estrutura `clientes/<cliente>/{raw,assets,projects,output}`.

package/bin/easyedit.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+main(process.argv.slice(2)).catch((e) => {
+  console.error(`easyedit: ${e.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@intelli-ia/easyedit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Especificação, entrevista e acompanhamento de edição de vídeo com HyperFrames, em forma de skills para agentes.",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/intelli-ia/easyedit.git" },
+  "homepage": "https://github.com/intelli-ia/easyedit#readme",
+  "bugs": { "url": "https://github.com/intelli-ia/easyedit/issues" },
+  "type": "module",
+  "bin": { "easyedit": "bin/easyedit.mjs" },
+  "files": ["LICENSE", "bin", "src", "payload", "CHANGELOG.md", "README.md"],
+  "engines": { "node": ">=22" },
+  "scripts": { "test": "node --test test/*.test.mjs" }
+}

package/payload/.easyedit/Spec.md

@@ -0,0 +1,82 @@
+# EasyEdit · Contrato da especificação de vídeo
+
+Regras comuns a todas as skills `easyedit-*`. Cada vídeo é um projeto isolado e tem **um único** `spec.md`, em `clientes/<cliente>/projects/<AAAA-MM-slug>/spec.md`. Ele é a fonte normativa do que foi especificado, implementado e alterado. Não crie `plan.md`, `tasks.md` nem outros relatórios paralelos.
+
+O template está em `.easyedit/templates/Spec.md`. As ferramentas disponíveis estão em `.easyedit/TOOLS.md`.
+
+## Vertical
+
+O campo `Vertical` do cabeçalho define o playbook: `trafego-meta` (criativo para anúncio na Meta, skill `easyedit-vertical-trafego`), `reels` (ainda sem playbook próprio) ou `a definir`.
+
+## Gravações do vídeo
+
+Todas as gravações de um criativo ficam em `clientes/<cliente>/raw/<AAAA-MM-slug>/`. `easyedit-takes` ordena (nome numerado, depois data de criação), transcreve, resolve refações e entrega a sequência ao restante do fluxo.
+
+## Estados
+
+O estado fica no campo `Status` do cabeçalho do `spec.md`. Não há pastas de estado, porque o projeto já é a unidade.
+
+| Status | Significa | Quem avança |
+| --- | --- | --- |
+| `Draft` | Entrevista em andamento. | `easyedit-novo`, `easyedit-interviewer` |
+| `Defined` | Ato I completo e aprovado pela pessoa (`Definition Gate: Passed`). | `easyedit-interviewer` |
+| `In Progress` | Ato II em execução. | `easyedit-build` |
+| `Review` | Render gerado e aguardando validação do cliente (`Delivery Gate: Pending`). | `easyedit-build` |
+| `Completed` | Entregue e aprovado (`Delivery Gate: Passed`). | `easyedit-build` |
+
+Mudança pedida depois de `Defined` é uma entrada no Registro de mudanças (Ato III). Quando altera o escopo, o Ato I também é editado e o `Definition Gate` volta a `Pending`.
+
+## Três atos
+
+1. **Ato I · Especificação:** o que o vídeo deve ser.
+2. **Ato II · Implementação:** como e com o quê foi feito, tarefas e evidências.
+3. **Ato III · Registro:** mudanças (adicionado, ajustado, alterado, removido), feedbacks e entrega.
+
+## IDs
+
+Nunca reutilize nem renumere. `RV-001` requisito de vídeo · `AC-001` critério de aceite · `T-001` tarefa · `CH-001` mudança · `FB-001` feedback.
+
+Cada `RV` precisa de pelo menos um `AC` que declare `Cobre: RV-xxx`. Cada tarefa aponta os `RV` que entrega.
+
+## Contrato de perguntas (uma por vez)
+
+Usado por toda skill com `Modo de interação: perguntas`. As perguntas são feitas **uma por vez**: faça a pergunta, espere a resposta, grave, reavalie e só então faça a próxima. Nunca envie uma lista de perguntas.
+
+**Formato fixo de cada pergunta**
+
+```
+Pergunta N · <tema curto>
+<a pergunta, em uma ou duas frases, com o contexto que a pessoa precisa para decidir>
+
+1. <opção técnica> (sugestão)
+2. <opção técnica>
+3. <opção técnica>
+4. Gerar outras opções
+5. Avançar sem responder
+```
+
+- **1 a 3:** respostas técnicas reais e distintas, com os efeitos relevantes (custo, risco, resultado) em poucas palavras. Marque com `(sugestão)` a que você recomenda, em regra a primeira.
+- **4 · Gerar outras opções:** descarte as três e proponha três novas, diferentes das anteriores, no mesmo formato. Pode ser pedido mais de uma vez.
+- **5 · Avançar sem responder:** a pessoa adia a decisão. Se houver sugestão, aplique-a e registre em `Suposições` do spec como default aceito. Se não houver default seguro (oferta, CTA, destino), registre o item como pendência na seção 8 e siga adiante; **o spec não passa para `Defined` com pendência aberta**.
+- **Resposta livre:** a pessoa pode responder com um texto no lugar de um número. Trate-o como uma opção nova e confirme o entendimento em uma linha.
+- **Sem pergunta aberta:** quando não houver opções técnicas plausíveis (por exemplo, o nome da oferta), faça a pergunta com opções de exemplo ou formatos de resposta, mantendo 4 e 5.
+
+**Regras**
+
+- Pergunte só o que muda o resultado: formato, mensagem, estilo, entrega (a duração do vídeo é livre e não é perguntada). Não repita o que já está no `CLAUDE.md` do cliente nem no `spec.md`, e não repita pergunta respondida.
+- Ordene as perguntas pelo impacto: primeiro as que bloqueiam o trabalho seguinte (ordem dos takes, autorização de modelo), depois objetivo, oferta, público e CTA, depois estilo.
+- Registre apenas respostas confirmadas. Nunca invente.
+- Reavalie o spec depois de cada resposta; feche a entrevista quando as seções 1 a 7 estiverem preenchidas.
+- Aprovações (de plano, de spec, de descarte) usam o mesmo formato: `1. Aprovar (sugestão)`, `2. Ajustar` e `3. Refazer`, mais 4 e 5.
+- **Nunca peça permissão para iniciar uma etapa.** A skill começa assim que é acionada ou chamada por outra. Perguntas servem para decisões e para ações sensíveis, não para "posso começar?".
+
+## Handoff entre skills
+
+Anuncie `Transição automática: $origem → $destino — motivo — resultado esperado` e carregue a skill de destino sem pedir confirmação, inclusive para iniciar a entrevista. Ações sensíveis (apagar arquivos, sobrescrever render aprovado, publicar) exigem autorização específica.
+
+## Regras de projeto
+
+- Nunca edite `raw/`. Insumos novos entram em `assets/` do cliente.
+- Renders finais vão para `clientes/<cliente>/output/` com o nome `<slug>-vN.mp4`. Não sobrescreva uma versão enviada ao cliente: gere `vN+1`.
+- Toda mudança de arquivo de composição durante `In Progress` é registrada com `easyedit-log` (script `registrar.mjs`).
+- Pergunte antes de baixar modelos grandes, instalar pacotes ou iniciar Docker.

package/payload/.easyedit/TOOLS.md

@@ -0,0 +1,113 @@
+# EasyEdit · Ferramentas de edição de vídeo
+
+Referência das ferramentas usadas neste repositório. É o equivalente do `STACK.md` do Specsfy: as skills do EasyEdit leem este arquivo para saber **o que existe, para que serve e como invocar**.
+
+Levantado com `npx hyperframes doctor` e `--help` de cada comando. Este arquivo é criado uma vez pelo `easyedit install` e não é sobrescrito no `update`: ajuste-o à sua máquina. Para ver o que está instalado agora, rode `easyedit doctor`.
+
+**Sistemas:** macOS e Windows são suportados. No macOS o verificador de zonas seguras detecta rostos automaticamente (Vision); no Windows (e Linux) ele gera folhas de revisão visual e a camada declarada (`elementos.json`) continua exata.
+
+## 1. Motor principal: HyperFrames
+
+| Item | Valor |
+| --- | --- |
+| O que é | Framework open-source (Apache-2.0) da HeyGen que transforma HTML + CSS + animações em vídeo determinístico. Inspirado no Remotion, mas com HTML puro em vez de React. |
+| Versão instalada | `hyperframes@0.8.141` (devDependency do repositório; chamar com `npx hyperframes …`) |
+| Fontes | https://github.com/heygen-com/hyperframes · https://hyperframes.heygen.com (Quick start, Catalog) |
+| Princípio | A composição é um `index.html`. O tempo é declarado com `data-*`; a animação precisa ser *seekable* (pausada e controlada por timeline). O renderizador posiciona cada frame no Chrome headless e o FFmpeg codifica. Mesma entrada produz os mesmos frames. |
+| Atributos-chave | `data-composition-id`, `data-start`, `data-duration`, `data-track-index`, `class="clip"`. Timelines GSAP registradas em `window.__timelines`. |
+| Pacotes internos | `core` (parser, linter, runtime, adapters) · `engine` (captura Puppeteer + FFmpeg) · `producer` (captura, encode, mix de áudio) · `studio` · `player` · `shader-transitions` · `aws-lambda` |
+| Extras | Catálogo de blocos e componentes (~400: transições, overlays, legendas, gráficos, mapas) · `frame.md` (camada de design system para vídeo) · Studio (editor no navegador e app desktop) |
+
+### Comandos da CLI (agrupados pelo uso no fluxo)
+
+| Etapa | Comando | Função |
+| --- | --- | --- |
+| Criar | `init <nome>` | Cria o projeto. |
+| Criar | `add <bloco>` · `catalog` | Instala ou busca blocos e componentes do registro. |
+| Criar | `capture <url>` | Captura um site como material de vídeo. |
+| Insumos | `transcribe <arquivo>` | Transcrição com timestamp por palavra. Também importa `.json`, `.srt` e `.vtt`, e exporta com `--to srt\|vtt`. |
+| Insumos | `beats` | Detecta batidas da música e grava `beats/<áudio>.json`. |
+| Insumos | `tts` | Gera fala local (Kokoro-82M). |
+| Insumos | `remove-background` | Remove o fundo de vídeo ou imagem (saída transparente). |
+| Insumos | `models install parakeet` | Baixa modelos on-device. |
+| Insumos | `normalize-audio` | Iguala o loudness (LUFS) entre dois clipes. |
+| Insumos | `media-treatment` | Aplica tratamentos determinísticos a um elemento de mídia. |
+| Validar | `lint` | Erros comuns de composição. |
+| Validar | `check` | Gate único: lint + validação de runtime + inspeção de layout. `validate`, `inspect` e `layout` são aliases antigos. |
+| Validar | `snapshot` | PNGs de frames-chave. |
+| Validar | `keyframes` | Diagnóstico de keyframes (onion-shot). |
+| Validar | `compare` | Folha comparativa de variantes. |
+| Validar | `grade-compare` | Compara color grades num frame. |
+| Inspecionar | `info` · `compositions` · `timeline [--json]` | Metadados, lista de composições, trilhas e clipes. |
+| Histórico | `history` | Lista, desfaz e restaura mudanças registradas. |
+| Rever | `preview` | Studio com live reload. |
+| Rever | `present` | Modo apresentação (decks). |
+| Entregar | `render` | Veja a tabela abaixo. |
+| Entregar | `publish` | Sobe para uma URL estável (privada por padrão). |
+| Entregar | `cloud` · `lambda` · `cloudrun` | Render remoto: HeyGen Cloud, AWS Lambda e Google Cloud Run. |
+| Ambiente | `doctor` · `browser` · `upgrade` · `skills` · `clean` · `benchmark` | Diagnóstico, gestão do Chrome, atualizações e limpeza. |
+
+### `render`: opções que importam
+
+| Opção | Efeito |
+| --- | --- |
+| `-o`, `--output` | Caminho de saída (padrão `renders/<nome>.mp4`). **No EasyEdit, o destino é `clientes/<cliente>/output/`.** |
+| `-f`, `--fps` | 24, 25, 30, 50, 60 (e racionais como `30000/1001`). Padrão: o `data-fps` da raiz, senão 30. |
+| `-q`, `--quality` | `draft` · `looks` (padrão, CRF 16) · `delivery` (alta). |
+| `--format` | `mp4` (padrão) · `webm` e `mov` (com transparência) · `gif` · `png-sequence` · `hls`. |
+| `-w`, `--workers` | Chromes paralelos. Cada um usa cerca de 256 MB de RAM. |
+| `--docker` | Render determinístico em container. |
+| `--strict`, `--strict-all` | Falha em erros de lint (ou também em avisos). |
+| `--variables`, `--variables-file` | Injeta variáveis na composição (ótimo para lotes por cliente). |
+| `-c`, `--composition` | Renderiza uma composição específica. |
+| `--video-frame-format png` | Use em gravações de tela ou de UI sensíveis a cor. |
+| `--crf`, `--video-bitrate`, `--gpu`, `--hdr`/`--sdr` | Ajuste fino de codificação. |
+
+## 2. Skills HyperFrames instaladas (`~/.claude/skills`)
+
+Instaladas globalmente. Atualizar com `npx hyperframes skills update`.
+
+| Skill | Quando usar |
+| --- | --- |
+| `hyperframes` | **Porta de entrada obrigatória.** Roteia o pedido para o workflow certo e retoma o estado do projeto. |
+| `hyperframes-core` | Contrato da composição: estrutura, `data-*`, trilhas, sub-composições, variáveis, regras de determinismo. Ler antes de escrever HTML. |
+| `hyperframes-cli` | Loop de desenvolvimento e diagnóstico de falhas de build ou render. |
+| `hyperframes-animation` | Regras de movimento, blueprints de cena, transições e os 7 adapters (GSAP padrão, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU). |
+| `hyperframes-keyframes` | Punch-in, zoom, reframe, Ken Burns e câmera. |
+| `hyperframes-creative` | Direção criativa: paletas, tipografia, narração, beats, `frame.md` e `design.md`. |
+| `hyperframes-audio` | Mix de áudio: fade, ganho, ducking, EQ, compressor e reverb. |
+| `hyperframes-registry` | Buscar e instalar blocos do catálogo **antes** de construir um efeito do zero. |
+| `hyperframes-studio` | Trabalho no Studio: se o pedido exige mudança, plano e storyboard, layout da timeline e zonas seguras de legenda. |
+| `media-use` | Resolve BGM, SFX, imagem, ícone, logo, voz e LUT para arquivo local com registro. Também faz TTS, transcrição, legendas e remoção de fundo. |
+| `talking-head-recut` | Overlays gráficos (títulos, lower-thirds, citações, PiP) sobre talking-head, entrevista ou podcast. O vídeo-base não é alterado. |
+
+Workflows que o roteador instala sob demanda, ainda não presentes na máquina: `/embedded-captions`, `/general-video`, `/motion-graphics`, `/faceless-explainer`, `/product-launch-video`, `/pr-to-video`, `/music-to-video`, `/slideshow`, `/remotion-to-hyperframes`.
+
+## 3. Ferramentas de sistema
+
+| Ferramenta | Versão / caminho | Papel no pipeline |
+| --- | --- | --- |
+| Node.js | ≥ 22 | Roda a CLI e os scripts. |
+| FFmpeg / FFprobe | no `PATH` (macOS: `brew install ffmpeg` · Windows: `winget install Gyan.FFmpeg` ou `choco install ffmpeg`) | Codifica o vídeo, faz mux e mix de áudio, corte, conversão e extração de frames. O FFprobe lê metadados (duração, fps, codec, resolução) dos arquivos brutos. |
+| Chrome headless-shell | baixado e gerenciado por `hyperframes browser` (cache do usuário) | Renderiza cada frame da composição. Gerenciado por `hyperframes browser`. |
+| whisper.cpp (`whisper-cli`) | no `PATH` (macOS: `brew install whisper-cpp` · Windows: binário do release do whisper.cpp, ou use o Parakeet) | Transcrição local. Modelos: `tiny.en`, `base.en`, `small.en` (padrão), `medium.en`, `large-v3`. Os `.en` são só inglês; **para português use `-l pt` com `large-v3`** ou o Parakeet. |
+| Parakeet (opcional) | `hyperframes models install parakeet` | Alternativa de ASR, mais rápida e precisa. Com `--engine auto` ela é preferida quando instalada e cobre o idioma. |
+| GSAP | embutido via adapter | Biblioteca de animação em JavaScript: movimento, easing e timelines. Fica pausada e é controlada por seek. |
+| Docker | opcional; só para `--docker` | Render determinístico opcional (`--docker`). |
+| Kokoro TTS | **não instalado** (opcional) | Voz local. `pip install kokoro-onnx soundfile`. |
+| MusicGen | **não instalado** (opcional) | Música local. `pip install transformers torch soundfile numpy`. |
+| yt-dlp | não instalado | Não faz parte do fluxo atual. |
+
+## 4. Convenções do repositório que o EasyEdit herda
+
+- Clientes ficam em `clientes/<cliente>/` (kebab-case). Projetos de vídeo: `projects/AAAA-MM-<slug>/`.
+- `raw/` é somente leitura. Renders finais vão para `output/`. Assets reutilizáveis ficam em `assets/`.
+- Ciclo: `init` → insumos (`transcribe`, `beats` etc.) → `lint`/`check` → `snapshot`/`preview` → `render`.
+
+## 5. Fontes consultadas
+
+- https://github.com/heygen-com/hyperframes (README)
+- https://hyperframes.heygen.com (landing)
+- Saída local de `hyperframes --help`, `render --help`, `transcribe --help` e `doctor`
+- Notícias de lançamento: https://www.noqta.tn/en/blog/heygen-hyperframes-html-to-mp4-ai-agent-video-2026 · https://themenonlab.blog/blog/heygen-hyperframes-video-as-code
+- whisper.cpp: https://huggingface.co/datasets/echodict/whisper.cpp/blob/main/examples/cli/README.md

package/payload/.easyedit/templates/Spec.md

@@ -0,0 +1,125 @@
+# {{TITULO}}
+
+| Campo | Valor |
+| --- | --- |
+| ID | VID-{{SLUG}} |
+| Slug | {{SLUG}} |
+| Cliente | {{CLIENTE}} |
+| Vertical | {{VERTICAL}} |
+| Status | Draft |
+| Definition Gate | Pending |
+| Delivery Gate | Pending |
+| Criado em | {{DATA}} |
+| Atualizado em | {{DATA}} |
+
+---
+
+# Ato I · Especificação
+
+## 1. Objetivo
+
+- **Mensagem central:** <!-- o que o espectador deve entender ou sentir -->
+- **Ator (público):** <!-- quem assiste -->
+- **Resultado esperado:** <!-- ação ou percepção desejada -->
+- **Tipo de vídeo:** <!-- legenda em vídeo existente · overlays em talking-head · motion graphic · explicativo · outro -->
+
+## 2. Plataforma e formato
+
+- **Plataformas:** <!-- Reels/TikTok/Shorts · YouTube · site -->
+- **Resolução e proporção:** <!-- 1080x1920 (9:16) · 1920x1080 (16:9) · 1080x1080 -->
+- **FPS:** <!-- 30 · 60 -->
+- **Duração:** livre (sem meta ou limite); registre aqui a duração final depois do render.
+
+## 3. Insumos
+
+| Insumo | Caminho | Observação |
+| --- | --- | --- |
+| Gravações (takes) | `../../raw/{{SLUG}}/` | Várias gravações do mesmo criativo; ordem definida por `easyedit-takes`. |
+| Imagens e b-roll | `../../assets/…` | |
+| Música | `../../assets/music/…` | |
+| Fontes e marca | `../../assets/fonts/`, `../../assets/brand/` | |
+
+Takes (preenchido por `easyedit-takes`):
+
+| Ordem | Arquivo | Duração | Uso |
+| --- | --- | --- | --- |
+
+## 4. Estrutura e roteiro
+
+| Cena | Tempo | Conteúdo (fala/texto) | Visual |
+| --- | --- | --- | --- |
+| 1 | 0:00–0:03 | | |
+
+## 5. Estilo
+
+- **Marca:** <!-- cores, logo, tom (ver CLAUDE.md do cliente) -->
+- **Legendas:** <!-- estilo, posição, destaque de palavras, idioma -->
+- **Motion:** <!-- ritmo, transições, intensidade -->
+- **Áudio:** <!-- música, volume, ducking sobre a voz, SFX -->
+
+## 6. Requisitos de vídeo
+
+| ID | Requisito (verificável) | Prioridade |
+| --- | --- | --- |
+| RV-001 | | Must |
+
+## 7. Critérios de aceite
+
+| ID | Cobre | Critério (Given/When/Then ou checagem observável) |
+| --- | --- | --- |
+| AC-001 | RV-001 | |
+
+## 8. Fora de escopo e suposições
+
+- **Fora de escopo:**
+- **Suposições** (defaults reversíveis aceitos na entrevista):
+
+---
+
+# Ato II · Implementação
+
+## 9. Plano técnico
+
+- **Workflow HyperFrames:** <!-- /embedded-captions · /talking-head-recut · /general-video · /motion-graphics … -->
+- **Skills e ferramentas:** <!-- ver .easyedit/TOOLS.md -->
+- **Pasta do projeto:** `.`
+- **Comando de render:** <!-- npx hyperframes render -o ../../output/{{SLUG}}-v1.mp4 -f 30 -q delivery -->
+
+## 10. Tarefas
+
+| ID | Tarefa | Entrega | Status |
+| --- | --- | --- | --- |
+| T-001 | | RV-001 | Pending |
+
+Status das tarefas: `Pending` · `Doing` · `Done` · `Dropped`.
+
+## 11. Evidências
+
+| Etapa | Comando | Resultado | Data |
+| --- | --- | --- | --- |
+| lint/check | `npx hyperframes check` | | |
+| snapshot | `npx hyperframes snapshot` | | |
+| render | `npx hyperframes render …` | | |
+
+---
+
+# Ato III · Registro
+
+## 12. Registro de mudanças
+
+Tipos: `adicionado` · `ajustado` · `alterado` · `removido`. Origem: `interno` · `cliente`.
+
+<!-- easyedit:changes -->
+| ID | Data | Tipo | O que mudou | Motivo | Origem | Afeta |
+| --- | --- | --- | --- | --- | --- | --- |
+<!-- /easyedit:changes -->
+
+## 13. Feedbacks
+
+| ID | Data | Quem | Feedback | Resolvido em |
+| --- | --- | --- | --- | --- |
+
+## 14. Entrega
+
+| Versão | Arquivo | Data | Enviado a | Status |
+| --- | --- | --- | --- | --- |

package/payload/claude-section.md

@@ -0,0 +1,5 @@
+## EasyEdit (especificação e acompanhamento por vídeo)
+Cada vídeo tem um `projects/<AAAA-MM-slug>/spec.md` (fonte única: especificado → implementado → alterado). Contrato em `.easyedit/Spec.md`, ferramentas em `.easyedit/TOOLS.md`, skills em `.claude/skills/easyedit-*`.
+Gravações do vídeo: `clientes/<cliente>/raw/<AAAA-MM-slug>/` (vários arquivos; `/easyedit-takes` ordena e junta). Verticais: `trafego-meta` (`/easyedit-vertical-trafego`); `reels` pendente. Apoio: `/easyedit-ritmo`, `/easyedit-destaques`, `/easyedit-split-broll`, `/easyedit-legendas`, `/easyedit-zonas-seguras`.
+Fluxo: `/easyedit-novo` → `/easyedit-interviewer` (Draft→Defined) → `/easyedit-build` (In Progress→Review→Completed). Mudanças: `/easyedit-log`. Panorama: `/easyedit-progress`.
+

package/payload/skills/easyedit-build/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: easyedit-build
+description: "Use quando o spec.md do vídeo está Defined (ou In Progress) e o usuário pede para montar, editar, ajustar, corrigir ou renderizar o vídeo. Planeja o Ato II, executa com as skills e a CLI do HyperFrames, valida, renderiza para output/ e mantém tarefas, evidências e registro de mudanças. Sem spec Defined, use easyedit-interviewer."
+---
+
+# Montar e renderizar o vídeo
+
+## Preparação obrigatória
+
+Antes de executar esta skill, carregue `$easyedit-setup`. Confirme que o `spec.md` está em `Defined`, `In Progress` ou `Review` (ajuste pedido pelo cliente). Se estiver em `Draft`, anuncie `Transição automática: $easyedit-build → $easyedit-interviewer` e retome depois.
+
+## Modo de interação
+
+Modo de interação: `sem perguntas`. Dúvida que muda o resultado volta para `$easyedit-interviewer`. Perguntas só para ações sensíveis (instalar pacote, baixar modelo, iniciar Docker, sobrescrever render).
+
+## Planejar (Ato II)
+
+1. Escolha o workflow HyperFrames pela seção 1 do spec: legendas em vídeo existente → `/embedded-captions`; overlays em talking-head → `/talking-head-recut`; motion curto → `/motion-graphics`; demais → `/general-video`. Em caso de dúvida, comece por `/hyperframes`, que roteia. Registre a escolha na seção 9.
+2. Quebre o trabalho em tarefas `T-001…` na seção 10, cada uma apontando os `RV` que entrega.
+3. Marque `Status: In Progress`:
+
+```bash
+node .claude/skills/easyedit-log/scripts/campo.mjs <spec.md> Status "In Progress"
+```
+
+## Executar
+
+Se `Vertical` for `trafego-meta`, siga a ordem de trabalho de `$easyedit-vertical-trafego` (takes → ritmo → destaques → tela dividida e legendas → áudio → zonas seguras → render por variante). Com mais de um arquivo em `raw/<slug>/`, comece sempre por `$easyedit-takes`, depois `$easyedit-ritmo`, antes de qualquer legenda ou destaque, porque eles dependem da linha do tempo final.
+
+Carregue as skills conforme a necessidade; os papéis estão em `.easyedit/TOOLS.md`:
+
+| Necessidade | Skill ou comando |
+| --- | --- |
+| Estrutura da composição, `data-*`, trilhas | `/hyperframes-core` |
+| Transcrição, legendas, TTS, BGM, SFX, logo | `/media-use`, `npx hyperframes transcribe` |
+| Movimento, transições | `/hyperframes-animation`, `/hyperframes-keyframes` |
+| Efeito nomeado (glitch, grain, gráfico) | `/hyperframes-registry` **antes** de construir à mão |
+| Paleta, tipografia, `frame.md` | `/hyperframes-creative` |
+| Mix de áudio | `/hyperframes-audio` |
+| Loop de CLI e falhas | `/hyperframes-cli` |
+| Várias gravações de um mesmo vídeo | `$easyedit-takes` |
+| Pausas e respiros | `$easyedit-ritmo` |
+| Palavras-chave e inserções | `$easyedit-destaques` |
+| Tela dividida com b-roll | `$easyedit-split-broll` |
+| Legendas de vertical | `$easyedit-legendas` |
+| Zonas cinzentas da Meta | `$easyedit-zonas-seguras` |
+
+Durante o trabalho:
+- Leia a marca em `clientes/<cliente>/CLAUDE.md` e aplique-a. Faça referência a `assets/` por caminho relativo.
+- Marque cada tarefa `Doing` → `Done` na seção 10 ao concluir.
+- Cada mudança de escopo ou de execução (adicionar cena, trocar música, remover trecho, ajustar timing) gera um registro com `$easyedit-log`.
+
+## Validar e renderizar
+
+1. `npx hyperframes check` (lint, runtime e layout). Corrija até passar.
+2. Em vídeo 9:16 de vertical (tráfego/Reels), rode as três verificações de `$easyedit-zonas-seguras` (inclui `verificar_zonas.mjs` num render `-q draft`) e corrija até **0 erros**. Sem detecção automática (Windows/Linux), o gate inclui a **revisão visual das folhas** que o verificador gera, com o resultado registrado em Evidências.
+3. `npx hyperframes snapshot` e confira os frames-chave contra os `AC`. Veja os PNGs antes de declarar pronto.
+4. Renderize para a saída do cliente, sem sobrescrever versões anteriores:
+
+```bash
+npx hyperframes render -o ../../output/<slug>-vN.mp4 -f <fps> -q delivery
+```
+
+5. Confira o arquivo com `ffprobe` (resolução e fps) contra a seção 2 e registre a duração final; a duração não tem limite nem meta.
+6. Rode `verificar_zonas.mjs` também sobre o render final (`delivery`) quando for vertical, e confirme 0 erros (e a revisão visual das folhas, em Windows/Linux).
+7. Registre as evidências na seção 11 (comando, resultado, data) e a versão na seção 14.
+8. Marque `Status: Review` e `Delivery Gate: Pending`. Informe o caminho do render e quais `AC` foram verificados, e quais não puderam ser.
+
+## Feedback e fechamento
+
+- Feedback do cliente: registre em 13 (`FB-xxx`), crie as mudanças correspondentes com `$easyedit-log` e gere `vN+1`. Volte `Status` para `In Progress` e depois para `Review`.
+- Aprovação do cliente: `Delivery Gate: Passed`, `Status: Completed`. Acrescente o aprendizado reutilizável ao `CLAUDE.md` do cliente (regras, preferências, histórico).
+
+## Limites
+
+- Nunca edite `raw/`. Nunca apague um render já enviado.
+- Não declare `Completed` sem aprovação do cliente informada pelo usuário.
+- Não diga que um `AC` passou sem ter visto a evidência.

package/payload/skills/easyedit-destaques/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: easyedit-destaques
+description: "Use para analisar a transcrição e o tema do vídeo e decidir em quais palavras ou frases marcantes inserir um reforço visual: imagem, vídeo curto em tela cheia, legenda especial, ícone, zoom ou SFX. Produz um plano de destaques para aprovação antes de montar. Não monta a composição; execução fica com easyedit-build."
+---
+
+# Planejar destaques sobre a fala
+
+## Preparação obrigatória
+
+Antes de executar esta skill, carregue `$easyedit-setup`. Use a transcrição já remapeada pelo `$easyedit-ritmo` (`transcript.cut.json`) quando houver corte; senão `transcript.json`.
+
+## Modo de interação
+
+Modo de interação: `perguntas`, uma única pergunta de aprovação do plano, no formato do `Contrato de perguntas (uma por vez)` de `.easyedit/Spec.md`: 1. Aprovar (sugestão), 2. Ajustar itens, 3. Refazer o plano, 4. Gerar outras abordagens, 5. Avançar sem aprovar (aplica o plano como rascunho).
+
+## Passos
+
+1. Leia a transcrição inteira, o tema (seção 1 do spec), a marca do cliente e o inventário de `assets/broll/`, `assets/images/`.
+2. Identifique as **palavras-âncora**: aquelas que carregam o argumento ou o gancho. Procure:
+   - números, preços, prazos e porcentagens;
+   - benefício principal, dor, objeção e prova ("garantia", "sem mensalidade", "aprovados");
+   - nome do produto, do cliente ou do lugar;
+   - verbos de ação e CTA ("matricule", "clique", "garanta");
+   - palavras de contraste ou virada ("mas", "só que", "na verdade").
+3. Para cada âncora escolha **uma** ação e justifique em poucas palavras:
+
+| Ação | Quando |
+| --- | --- |
+| Imagem (pop-in) | Substantivo concreto: lugar, objeto, pessoa. |
+| Vídeo curto em tela cheia (0,8–2 s) | Cena ou prova que ilustra a frase inteira. |
+| Legenda especial | Número, preço, palavra de impacto: maior, cor da marca, animação própria. |
+| Ícone | Conceito abstrato ou lista (check, cifrão, relógio, escudo). |
+| Zoom / punch-in | Ênfase na fala sem ilustração disponível (`/hyperframes-keyframes`). |
+| SFX | Acompanha a ação de maior impacto, nunca todas. |
+
+4. Respeite o **teto de densidade** da vertical (tráfego: um destaque a cada 2–4 s; Reels: a cada 3–5 s) e evite ações iguais seguidas. A primeira ação deve cair nos primeiros 3 s (gancho).
+5. Procure o material em `assets/` primeiro; se faltar, liste o que precisa ser pedido ao cliente ou gerado com `/media-use`. Não use logo ou imagem de terceiros sem origem.
+6. Apresente o plano em tabela, com tempos da linha do tempo final:
+
+| # | Tempo | Palavra/frase | Ação | Material | Motivo |
+| --- | --- | --- | --- | --- | --- |
+
+   Grave o plano no spec (seção 4, coluna Visual, e tarefas na seção 10) e em `destaques.json` na pasta do projeto. Peça aprovação ou ajustes; cada ajuste vira entrada do `$easyedit-log`.
+
+## Limites
+
+- Todo elemento visual (imagem, ícone, legenda especial, rosto em vídeo curto) obedece às zonas de `$easyedit-zonas-seguras` e entra em `elementos.json`.
+- Não invente afirmações: o destaque reforça o que foi dito, nunca acrescenta promessa.
+- Imagem ou vídeo ainda inexistente não entra no plano como "pronto".

package/payload/skills/easyedit-interviewer/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: easyedit-interviewer
+description: "Use quando um vídeo precisa de entrevista para definir como deve ser: objetivo, público, formato, insumos, roteiro, estilo, requisitos e critérios de aceite; ou quando o cliente pedir uma mudança no escopo depois da definição. Preenche o Ato I do spec.md com respostas confirmadas e promove Draft para Defined. Não executa edição de vídeo nem renderiza; para isso use easyedit-build."
+---
+
+# Entrevistar para especificar o vídeo
+
+## Preparação obrigatória
+
+Antes de executar esta skill, carregue `$easyedit-setup`. Não prossiga se o vídeo não tiver `spec.md`; nesse caso use `$easyedit-novo`.
+
+## Modo de interação
+
+Modo de interação: `perguntas`. Aplique o `Contrato de perguntas (uma por vez)` de `.easyedit/Spec.md`: uma pergunta por vez, em múltipla escolha de 1 a 5 (1–3 opções técnicas, 4 gerar outras opções, 5 avançar sem responder).
+
+**Inicie a entrevista imediatamente** ao ser acionada, sem perguntar se pode começar.
+
+## Conduzir a entrevista
+
+1. Leia o spec e o `CLAUDE.md` do cliente. Tudo que já estiver respondido ali deve ser reaproveitado, nunca perguntado de novo.
+2. Se o campo `Vertical` for `trafego-meta`, anuncie `Transição automática: $easyedit-interviewer → $easyedit-vertical-trafego` para aplicar as perguntas e os padrões da vertical, e retome aqui. Se houver gravações em `raw/<slug>/` e ainda não existir `takes.json`, carregue `$easyedit-takes` para inventariar e entender a sequência, e use isso na seção 4.
+3. Siga as seções do Ato I, escolhendo a **única** lacuna que mais muda o resultado e fazendo uma pergunta por vez. Temas por seção:
+
+| Seção | Perguntas típicas |
+| --- | --- |
+| 1 Objetivo | Qual a mensagem? Quem assiste? O que a pessoa deve fazer depois? É legenda em vídeo existente, overlays, motion ou vídeo novo? |
+| 2 Formato | Plataforma, proporção e fps. Não pergunte meta de duração: ela é livre; só registre a duração final. |
+| 3 Insumos | Qual vídeo bruto em `raw/`? Há b-roll, música, logo e fontes em `assets/`? O que falta pedir ao cliente? |
+| 4 Roteiro | Cenas e tempos; o que é fala e o que é texto na tela. |
+| 5 Estilo | Legenda (estilo, posição, destaque), ritmo do motion, música e volume. |
+| 6–7 | Derive `RV` verificáveis e `AC` a partir das respostas; confirme com a pessoa. |
+
+4. Depois de cada resposta, grave **só o que foi confirmado** na seção correspondente. Registre defaults aceitos em `Suposições`.
+5. Verifique ferramentas: se algo pedido exigir uma capacidade ausente (por exemplo voz TTS, música gerada ou Docker), diga isso consultando `.easyedit/TOOLS.md` e ofereça alternativa.
+6. Quando as seções 1 a 8 estiverem preenchidas, sem placeholders, e cada `RV` tiver pelo menos um `AC`, mostre um resumo e peça a aprovação explícita.
+7. Com a aprovação:
+
+```bash
+node .claude/skills/easyedit-log/scripts/campo.mjs <spec.md> "Definition Gate" Passed
+node .claude/skills/easyedit-log/scripts/campo.mjs <spec.md> Status Defined
+```
+
+   Anuncie `Transição automática: $easyedit-interviewer → $easyedit-build — motivo: spec Defined — resultado esperado: Ato II planejado e executado`.
+
+## Mudança de escopo depois de `Defined`
+
+Edite o Ato I, volte `Definition Gate` para `Pending`, registre a mudança com `$easyedit-log` (origem `cliente` ou `interno`) e repita o fechamento. Mudança que só afeta a execução (ajuste fino de timing, por exemplo) não reabre o gate: use apenas `$easyedit-log`.
+
+## Limites
+
+- Não invente respostas, métricas de marca ou textos do cliente.
+- Não edite o Ato II nem render aqui.
+- Não pergunte duas vezes a mesma coisa e não envie mais de uma pergunta por mensagem.
+- Não peça permissão para começar nem para chamar outra skill.

package/payload/skills/easyedit-legendas/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: easyedit-legendas
+description: "Use para criar legendas palavra a palavra com destaque em vídeo vertical para Reels ou anúncio da Meta, com estilo definido pela vertical e posição dentro da área útil. Parte da transcrição com timestamps. Para legenda simples sem estilo de vertical, o workflow /embedded-captions do HyperFrames também serve; para ícones/imagens sobre palavras use easyedit-destaques."
+---
+
+# Legendas para vertical
+
+## Preparação obrigatória
+
+Antes de executar esta skill, carregue `$easyedit-setup` e `$easyedit-zonas-seguras`.
+
+## Modo de interação
+
+Modo de interação: `sem perguntas`. O estilo vem da seção 5 do spec e do `CLAUDE.md` do cliente.
+
+## Passos
+
+1. Use `transcript.cut.json` (após `$easyedit-ritmo`) ou `transcript.json`. Corrija erros de transcrição óbvios (nomes próprios, marca) com a pessoa, nunca por suposição.
+2. Agrupe em blocos de 2–4 palavras, quebrando em pausas e fim de frase. Idioma e acentuação como na fala.
+3. Posicione o bloco na **área útil**, no terço inferior dela (y ≈ 900–1200 px), centralizado, com largura máxima menor que a área útil em x. Nada pode entrar no rodapé de 35%.
+4. Estilo base: fonte da marca em `assets/fonts/` (ex.: Poppins 700), caixa alta opcional, contorno ou fundo com contraste de pelo menos 4,5:1, palavra atual em cor de destaque da marca.
+5. A **legenda especial** das âncoras de `$easyedit-destaques` (números, preço, palavra de impacto) usa tamanho maior, cor própria e entrada animada; é exceção, não regra.
+6. Valide com `$easyedit-zonas-seguras` (registre a faixa da legenda em `elementos.json`) e `npx hyperframes check`; registre com `$easyedit-log`.
+
+## Limites
+
+- Legenda nunca cobre rosto, produto ou o CTA.
+- Não use mais de duas linhas por bloco.