@intelli-ia/easyedit 0.0.0-stage → 0.1.0

package/payload/skills/easyedit-vertical-trafego/references/playbook.md

@@ -0,0 +1,37 @@
+# Playbook · Criativo para tráfego pago na Meta
+
+Valores marcados com (padrão) são sugestões iniciais do EasyEdit a calibrar com resultado real; não são regra da Meta.
+
+## Estrutura do criativo
+- **Gancho (0–3 s):** a dor, a promessa ou a pergunta já na primeira frase e no primeiro quadro. Nada de logo animada ou apresentação.
+- **Desenvolvimento:** problema → solução → prova, em frases curtas.
+- **CTA:** dito e escrito, com uma ação única (matricule, clique, agende). Quadro final de 1–2 s (padrão) com CTA e marca, dentro da área útil.
+- **Duração: livre.** Não há mínimo, máximo nem meta de tempo: o criativo pode ter 30 s, 90 s, 120 s ou vários minutos. O que se exige é **concisão da ideia**, do gancho ao CTA: cada trecho cumpre uma função no argumento (gancho, problema, solução, prova, CTA). Corte digressão, repetição e trecho que não faz a ideia avançar; mantenha o que sustenta a oferta, por mais longo que fique.
+
+## Ritmo
+- Pausa máxima (padrão): 0,3 s (`$easyedit-ritmo`).
+- Um destaque visual a cada 2–4 s (padrão) (`$easyedit-destaques`).
+- Troca de b-roll a cada 2–4 s. Sem trecho de fala "limpa" por mais de ~5 s.
+
+## Som e legenda
+- Legenda sempre ligada (`$easyedit-legendas`): muita gente assiste sem som.
+- Música baixa (padrão: -18 a -22 dB sob a voz) com ducking (`/hyperframes-audio`); voz sempre inteligível.
+- Música e SFX com licença de uso comercial; sem trilha de tendência do Instagram, que não pode ser licenciada no render.
+
+## Zonas e formatos
+- Zonas cinzentas rigorosas (`$easyedit-zonas-seguras`).
+- Entregue 9:16 (Stories/Reels) e, quando a campanha usar feed, uma variante 4:5 recomposta para a área útil do 4:5.
+
+## Variantes para teste
+- Gere variantes de **gancho** (primeiros 3 s) mantendo o resto igual. Use `--variables` do `render` e nomes `<slug>-hookA-v1.mp4`, `<slug>-hookB-v1.mp4`.
+- Registre cada variante na seção 14 do spec e a diferença em `$easyedit-log`.
+
+## Checklist de conformidade (alerta, não parecer jurídico)
+Confira com o cliente e com as políticas de anúncios vigentes da Meta antes de publicar:
+- promessa de resultado garantido, ganho financeiro ou "cura";
+- antes/depois, saúde, corpo e estética;
+- afirmações sobre atributos pessoais do espectador ("você que sofre de…");
+- depoimentos e provas reais, com autorização de imagem;
+- uso de marcas, pessoas e músicas de terceiros;
+- setor regulado (educação, saúde, finanças): exigências específicas.
+Qualquer item suspeito vira pendência na seção 8 do spec, e a decisão é da pessoa responsável.

package/payload/skills/easyedit-zonas-seguras/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: easyedit-zonas-seguras
+description: "Use ao posicionar legendas, textos, ícones, logo, produto, rostos ou CTA num vídeo 9:16 para Reels ou anúncio da Meta, e antes de entregar, para garantir que nada importante fique nas zonas cinzentas (topo, rodapé e laterais cobertos pela interface do Instagram/Facebook). Verifica texto (HyperFrames check), elementos declarados e rostos/objetos detectados automaticamente no render, com quadros anotados. Não escolhe estilo de legenda; para isso use easyedit-legendas."
+---
+
+# Respeitar as zonas cinzentas
+
+## Preparação obrigatória
+
+Antes de executar esta skill, carregue `$easyedit-setup`.
+
+## Modo de interação
+
+Modo de interação: `sem perguntas`.
+
+## Zonas
+
+Topo 14%, rodapé 35% e laterais 6% do canvas 1080x1920. Detalhes e ressalvas em [references/zonas.md](references/zonas.md). Área útil: x 65–1015, y 269–1248.
+
+## Ao construir
+
+1. Posicione legenda, texto, ícone, logo, rosto, produto e CTA **dentro da área útil**. Fundos e b-roll podem sangrar para fora.
+2. Registre cada logo, produto, CTA e texto posicionado em `elementos.json` (ver abaixo).
+3. Declare a área útil como variáveis CSS na composição (`--util-x0: 65px; --util-y0: 269px; --util-x1: 1015px; --util-y1: 1248px`) e ancore os elementos a elas, em vez de repetir números soltos.
+
+## Ao validar
+
+São **três verificações**, todas automáticas, mais a conferência visual dos quadros que elas apontam.
+
+1. **Texto (DOM)**: os quatro `check --caption-zone`, na pasta do projeto. Cada um usa `severity=error` e amostra cinco instantes. Qualquer `caption_zone_collision` é defeito: reposicione.
+
+```bash
+node ../../../../.claude/skills/easyedit-zonas-seguras/scripts/zonas.mjs comandos
+```
+
+2. **Elementos declarados (geometria exata)**: ao construir a composição, escreva `elementos.json` na pasta do projeto com **cada logo, produto, CTA, rosto/enquadramento e texto** que você posicionou, na tela, com a caixa em pixels do canvas 1080x1920. Fundos e b-roll que podem sangrar usam `"sangra": true`.
+
+```json
+[
+  {"id": "logo-final", "role": "logo",    "inicio": 27, "fim": 30, "x": 390, "y": 300, "w": 300, "h": 120},
+  {"id": "cta-final",  "role": "cta",     "inicio": 27, "fim": 30, "x": 140, "y": 900, "w": 800, "h": 200},
+  {"id": "produto-1",  "role": "produto", "inicio": 8,  "fim": 11, "x": 300, "y": 500, "w": 480, "h": 480},
+  {"id": "bg-broll",   "role": "fundo",   "inicio": 0,  "fim": 30, "x": 0,   "y": 0,   "w": 1080, "h": 1920, "sangra": true}
+]
+```
+
+   Mantenha o arquivo em dia a cada mudança de posição.
+
+3. **Pixels do render (detecção automática)**: renderize uma versão `-q draft` e rode o verificador. Ele extrai quadros (2 por segundo), detecta **rostos**, **texto** e **objetos salientes** (candidatos a produto ou logo) com o framework Vision do macOS (local, sem rede) e compara tudo com a área útil. Também confere o `elementos.json`.
+
+```bash
+node .claude/skills/easyedit-zonas-seguras/scripts/verificar_zonas.mjs \
+  --video <render.mp4> --elementos <projects/slug>/elementos.json --out <projects/slug>/verificacao-zonas
+```
+
+   Saída: `relatorio.json`, quadros anotados em `anotados/` (zonas em vermelho, detecções em amarelo/ciano) e código de saída 2 se houver erro.
+
+| Detecção | Gravidade | Como corrigir |
+| --- | --- | --- |
+| Rosto (pixels) fora da área útil | **erro** | Reenquadrar com `object-fit`/foco, reposicionar a faixa ou trocar o b-roll. |
+| Elemento declarado (logo, produto, CTA, texto) fora | **erro** | Mover para dentro da área útil e atualizar o `elementos.json`. |
+| Texto lido em pixels fora (legenda queimada, texto numa imagem) | aviso | Conferir no quadro anotado; texto do próprio filme (placa, bordado no uniforme) pode ser aceitável, texto nosso não. |
+| Objeto saliente fora (possível produto/logo) | aviso | Conferir no quadro anotado; se for produto/logo/assunto principal, mover. |
+
+   Corrija os **erros** e reexecute até zerar. Avalie cada **aviso** nos quadros anotados e registre a decisão (corrigido ou aceito, e por quê) na seção 11 do spec. Rostos muito pequenos ao fundo (< 4% da largura) são ignorados.
+
+4. Registre os resultados na seção 11 (comando, nº de erros e avisos, data) e as correções com `$easyedit-log`.
+
+## Limites
+
+- A detecção é aproximada: o Vision acha rostos de frente e de perfil, mas pode errar em rostos muito pequenos, cobertos ou desenhados. Produto e logo em pixels são só **candidatos** (objeto saliente), por isso o `elementos.json` é a verificação exata. Mantenha-o completo.
+- Requer macOS com `swiftc` (Xcode Command Line Tools) e `ffmpeg`. Na primeira execução, o detector é compilado em `~/.cache/easyedit/detectar`.
+- Não altere os valores de `ZONAS` sem registrar a mudança e a fonte.

package/payload/skills/easyedit-zonas-seguras/references/zonas.md

@@ -0,0 +1,18 @@
+# Zonas cinzentas (9:16, 1080x1920)
+
+Regiões onde a interface do Instagram/Facebook cobre o vídeo. Fonte única dos valores: `scripts/zonas.mjs` (`ZONAS`).
+
+| Região | Fração | Pixels | O que a plataforma mostra |
+| --- | --- | --- | --- |
+| Topo | 14% | ≈ 269 px | Perfil, nome da conta, rótulo "Patrocinado". |
+| Rodapé | 35% | ≈ 672 px | Botão de CTA, legenda do post, curtir/comentar/compartilhar, áudio. |
+| Laterais | 6% | ≈ 65 px | Margem de respiro e ícones laterais. |
+| **Área útil** | | x 65–1015 · y 269–1248 | Tudo que importa (legenda, texto, rosto, produto, logo, CTA) fica aqui. |
+
+**Origem e cautela:** valores consolidados de guias de terceiros (AdNabu, FirstPier, Adspirer e outros, consultados em 2026-10-14), não da documentação oficial da Meta. As fontes divergem no rodapé (20% em Stories, até 35% em Reels) e só uma cita as laterais. Adotamos o mais conservador para Reels e anúncios. Valide no preview do Gerenciador de Anúncios e ajuste `ZONAS` se a Meta divergir.
+
+**Regras de uso**
+- Fundo, b-roll e vídeo base **podem** ocupar o quadro inteiro. A regra vale para texto, **rostos**, produto, logo e CTA, inclusive os que aparecem *dentro* do b-roll ou do vídeo base.
+- A legenda fica dentro da área útil, preferencialmente no terço inferior dela (y ≈ 900–1200 px).
+- Em tela dividida, a linha de divisão e os dois rostos/assuntos principais ficam na área útil.
+- Para a variante 4:5 de feed, recalcule: o feed só corta o 9:16 em proporção, então use o centro 4:5 como área útil (1080x1350 no meio do quadro) e reposicione.

package/payload/skills/easyedit-zonas-seguras/scripts/detectar.swift

@@ -0,0 +1,37 @@
+// Detecta rostos, texto e objetos salientes em imagens com o framework Vision (macOS, local, sem rede).
+// uso: detectar <imagem1> [<imagem2> ...]   → JSON em stdout
+// Caixas normalizadas (0–1) com origem no canto superior esquerdo.
+import Foundation
+import Vision
+import ImageIO
+
+struct Det: Codable { let tipo: String; let x: Double; let y: Double; let w: Double; let h: Double; let conf: Double; let texto: String? }
+struct Res: Codable { let arquivo: String; let deteccoes: [Det] }
+
+func caixa(_ r: CGRect, _ tipo: String, _ conf: Float, _ texto: String? = nil) -> Det {
+    Det(tipo: tipo, x: Double(r.minX), y: Double(1 - r.maxY), w: Double(r.width), h: Double(r.height), conf: Double(conf), texto: texto)
+}
+
+var saida: [Res] = []
+for caminho in CommandLine.arguments.dropFirst() {
+    let url = URL(fileURLWithPath: caminho)
+    let handler = VNImageRequestHandler(url: url, options: [:])
+    let rostos = VNDetectFaceRectanglesRequest()
+    let texto = VNRecognizeTextRequest()
+    texto.recognitionLevel = .fast
+    texto.usesLanguageCorrection = false
+    let saliente = VNGenerateObjectnessBasedSaliencyImageRequest()
+    var dets: [Det] = []
+    do {
+        try handler.perform([rostos, texto, saliente])
+        for o in rostos.results ?? [] { dets.append(caixa(o.boundingBox, "rosto", o.confidence)) }
+        for o in texto.results ?? [] { dets.append(caixa(o.boundingBox, "texto", o.confidence, o.topCandidates(1).first?.string)) }
+        for o in saliente.results?.first?.salientObjects ?? [] { dets.append(caixa(o.boundingBox, "objeto", o.confidence)) }
+    } catch {
+        FileHandle.standardError.write(Data("falha em \(caminho): \(error)\n".utf8))
+    }
+    saida.append(Res(arquivo: caminho, deteccoes: dets))
+}
+let enc = JSONEncoder()
+enc.outputFormatting = [.sortedKeys]
+print(String(data: try! enc.encode(saida), encoding: .utf8)!)

package/payload/skills/easyedit-zonas-seguras/scripts/verificar_zonas.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Verifica se rostos, texto, logo, produto e CTA ficam dentro da área útil (fora das zonas cinzentas).
+//   node verificar_zonas.mjs --video <render.mp4> [--elementos <elementos.json>] [--fps 2] [--out <dir>] [--tol 0.05]
+// Camadas:
+//   1. Pixels (Vision, macOS): rosto → erro; texto lido e objeto saliente (candidato a produto/logo) → aviso
+//      (texto nosso é medido com exatidão pelo `check --caption-zone`; OCR em pixel pega texto dentro de imagem/vídeo).
+//   2. Declarada (elementos.json): logo/produto/cta/rosto/texto com caixa em px → erro. Geometria exata.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { UTIL, ZONAS } from './zonas.mjs';
+
+const aqui = dirname(fileURLToPath(import.meta.url));
+const args = Object.fromEntries(process.argv.slice(2).reduce((a, x, i, all) => (x.startsWith('--') ? [...a, [x.slice(2), all[i + 1]]] : a), []));
+const fail = (m) => { console.error(`erro: ${m}`); process.exit(1); };
+if (!args.video && !args.elementos) fail('uso: --video <render.mp4> [--elementos <elementos.json>] [--fps 2] [--out <dir>] [--tol 0.05]');
+
+const fps = Number(args.fps ?? 2);
+const tol = Number(args.tol ?? 0.05);
+const out = resolve(args.out ?? 'verificacao-zonas');
+const W = 1080, H = 1920;
+const r3 = (n) => Math.round(n * 1000) / 1000;
+mkdirSync(out, { recursive: true });
+
+/** Fração da caixa (frações do canvas) que está fora da área útil. */
+const foraDaUtil = ({ x, y, w, h }) => {
+  const area = w * h;
+  if (area <= 0) return 0;
+  const iw = Math.max(0, Math.min(x + w, UTIL.x1) - Math.max(x, UTIL.x0));
+  const ih = Math.max(0, Math.min(y + h, UTIL.y1) - Math.max(y, UTIL.y0));
+  return 1 - (iw * ih) / area;
+};
+const regioes = ({ x, y, w, h }) => {
+  const r = [];
+  if (y < UTIL.y0) r.push('topo');
+  if (y + h > UTIL.y1) r.push('rodapé');
+  if (x < UTIL.x0) r.push('lateral esquerda');
+  if (x + w > UTIL.x1) r.push('lateral direita');
+  return r.join(' + ');
+};
+
+const achados = [];
+const info = [];
+
+// ---- camada 2: elementos declarados
+if (args.elementos) {
+  const els = JSON.parse(readFileSync(args.elementos, 'utf8'));
+  for (const e of els) {
+    if (e.sangra) continue; // fundo/b-roll que pode ocupar o quadro todo
+    const caixa = { x: e.x / W, y: e.y / H, w: e.w / W, h: e.h / H };
+    const f = foraDaUtil(caixa);
+    if (f > 0.001) achados.push({ camada: 'declarado', gravidade: 'erro', tipo: e.role, id: e.id ?? null, tempo: `${e.inicio ?? 0}–${e.fim ?? '?'} s`, fora: r3(f), regiao: regioes(caixa), caixa });
+  }
+  info.push(`${els.length} elementos declarados conferidos`);
+}
+
+// ---- camada 1: pixels
+if (args.video) {
+  if (process.platform !== 'darwin') fail('a detecção por pixels usa o framework Vision (macOS)');
+  const bin = join(homedir(), '.cache/easyedit/detectar');
+  const fonte = join(aqui, 'detectar.swift');
+  if (!existsSync(bin) || statSync(bin).mtimeMs < statSync(fonte).mtimeMs) {
+    mkdirSync(dirname(bin), { recursive: true });
+    console.error('compilando detector (uma vez)…');
+    // O SDK padrão pode ser mais novo que o compilador; tenta os SDKs instalados do mais novo ao mais antigo.
+    const sdks = ['/Library/Developer/CommandLineTools/SDKs', '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs']
+      .filter(existsSync).flatMap((d) => readdirSync(d).filter((s) => /^MacOSX\d+(\.\d+)?\.sdk$/.test(s)).map((s) => join(d, s)))
+      .sort((a, b) => b.localeCompare(a, 'en', { numeric: true }));
+    let ok = false;
+    for (const sdk of [null, ...sdks]) {
+      try { execFileSync('swiftc', ['-O', ...(sdk ? ['-sdk', sdk] : []), fonte, '-o', bin], { stdio: 'ignore' }); ok = true; break; } catch { /* próximo SDK */ }
+    }
+    if (!ok) fail('não foi possível compilar o detector (swiftc + SDK do macOS)');
+  }
+  const frames = join(out, 'frames');
+  rmSync(frames, { recursive: true, force: true });
+  mkdirSync(frames, { recursive: true });
+  execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', args.video, '-vf', `fps=${fps},scale=${W}:${H}`, '-q:v', '3', join(frames, 'f%04d.jpg')]);
+  const arquivos = readdirSync(frames).filter((f) => f.endsWith('.jpg')).sort().map((f) => join(frames, f));
+  const res = [];
+  for (let i = 0; i < arquivos.length; i += 40) {
+    res.push(...JSON.parse(execFileSync(bin, arquivos.slice(i, i + 40), { maxBuffer: 1 << 28 }).toString()));
+  }
+  res.forEach((fr, i) => {
+    const t = r3(i / fps);
+    for (const d of fr.deteccoes) {
+      const caixa = { x: d.x, y: d.y, w: d.w, h: d.h };
+      if (d.tipo === 'rosto' && d.w < 0.04) continue; // rosto minúsculo ao fundo
+      const f = foraDaUtil(caixa);
+      if (f <= tol) continue;
+      const grande = d.w * d.h > 0.6; // objeto saliente do quadro inteiro: ruído
+      if (d.tipo === 'objeto' && grande) continue;
+      achados.push({
+        camada: 'pixels', gravidade: d.tipo === 'objeto' || d.tipo === 'texto' ? 'aviso' : 'erro', conf: r3(d.conf),
+        tipo: d.tipo === 'objeto' ? 'objeto (possível produto/logo)' : d.tipo, tempo: `${t} s`,
+        fora: r3(f), regiao: regioes(caixa), caixa, texto: d.texto ?? undefined, frame: fr.arquivo,
+      });
+    }
+  });
+  info.push(`${arquivos.length} frames analisados a ${fps} fps`);
+}
+
+writeFileSync(join(out, 'relatorio.json'), JSON.stringify({ zonas: ZONAS, tolerancia: tol, info, achados }, null, 2));
+const erros = achados.filter((a) => a.gravidade === 'erro');
+
+// quadros anotados: zonas em vermelho, detecções em amarelo (erro) ou ciano (aviso)
+const porFrame = Map.groupBy(achados.filter((a) => a.frame), (a) => a.frame);
+if (porFrame.size) mkdirSync(join(out, 'anotados'), { recursive: true });
+for (const [frame, lista] of porFrame) {
+  const caixa = (x, y, w, h, cor, fill) => `drawbox=x=iw*${r3(x)}:y=ih*${r3(y)}:w=iw*${r3(w)}:h=ih*${r3(h)}:color=${cor}:t=${fill ? 'fill' : 6}`;
+  const zonasF = [caixa(0, 0, 1, UTIL.y0, 'red@0.3', 1), caixa(0, UTIL.y1, 1, 1 - UTIL.y1, 'red@0.3', 1), caixa(0, UTIL.y0, UTIL.x0, UTIL.y1 - UTIL.y0, 'red@0.3', 1), caixa(UTIL.x1, UTIL.y0, 1 - UTIL.x1, UTIL.y1 - UTIL.y0, 'red@0.3', 1)];
+  const dets = lista.map((a) => caixa(a.caixa.x, a.caixa.y, a.caixa.w, a.caixa.h, a.gravidade === 'erro' ? 'yellow' : 'cyan', 0));
+  try { execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', frame, '-vf', [...zonasF, ...dets].join(','), join(out, 'anotados', `${frame.split('/').pop().replace('.jpg', '.png')}`)]); } catch { /* anotação é opcional */ }
+}
+
+console.log(`${info.join(' · ')}`);
+console.log(`erros: ${erros.length} · avisos: ${achados.length - erros.length}`);
+const grupos = Map.groupBy(achados, (a) => `${a.gravidade}|${a.tipo}|${a.regiao}`);
+for (const [chave, lista] of grupos) {
+  const [grav, tipo, regiao] = chave.split('|');
+  const tempos = [...new Set(lista.map((a) => a.tempo))];
+  const textos = [...new Set(lista.map((a) => a.texto).filter(Boolean))].slice(0, 3);
+  console.log(`${grav.toUpperCase().padEnd(5)} ${tipo} → ${regiao} · ${lista.length}x · ${tempos.slice(0, 8).join(', ')}${tempos.length > 8 ? ', …' : ''}${textos.length ? ` · "${textos.join('", "')}"` : ''}`);
+}
+console.log(`relatório: ${join(out, 'relatorio.json')}${porFrame.size ? ` · quadros anotados: ${join(out, 'anotados')}` : ''}`);
+process.exit(erros.length ? 2 : 0);

package/payload/skills/easyedit-zonas-seguras/scripts/zonas.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Fonte única das zonas cinzentas (frações do canvas 9:16) e utilitários.
+//   node zonas.mjs comandos            → imprime os 4 comandos `hyperframes check --caption-zone`
+//   node zonas.mjs mascara <in.png> <out.png> → desenha as zonas sobre um snapshot (precisa de ffmpeg)
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+export const ZONAS = { topo: 0.14, rodape: 0.35, laterais: 0.06 };
+const principal = import.meta.url === pathToFileURL(process.argv[1]).href;
+const [cmd, a, b] = principal ? process.argv.slice(2) : [];
+const { topo, rodape, laterais } = ZONAS;
+
+/** Retângulo da área útil em frações do canvas. */
+export const UTIL = { x0: laterais, y0: topo, x1: 1 - laterais, y1: 1 - rodape };
+
+const bandas = {
+  topo: `x0=0;y0=0;x1=1;y1=${topo}`,
+  rodape: `x0=0;y0=${1 - rodape};x1=1;y1=1`,
+  esquerda: `x0=0;y0=${topo};x1=${laterais};y1=${1 - rodape}`,
+  direita: `x0=${1 - laterais};y0=${topo};x1=1;y1=${1 - rodape}`,
+};
+
+if (cmd === 'comandos') {
+  for (const [nome, g] of Object.entries(bandas)) console.log(`npx hyperframes check --caption-zone "${g};severity=error;seek=.1,.3,.5,.7,.9"   # ${nome}`);
+  console.log(`# área útil (9:16 1080x1920): x ${Math.round(1080 * laterais)}–${Math.round(1080 * (1 - laterais))}, y ${Math.round(1920 * topo)}–${Math.round(1920 * (1 - rodape))}`);
+} else if (cmd === 'mascara' && a && b) {
+  const caixa = (x, y, w, h) => `drawbox=x=iw*${x}:y=ih*${y}:w=iw*${w}:h=ih*${h}:color=red@0.35:t=fill`;
+  const f = [
+    caixa(0, 0, 1, topo), caixa(0, 1 - rodape, 1, rodape),
+    caixa(0, topo, laterais, 1 - topo - rodape), caixa(1 - laterais, topo, laterais, 1 - topo - rodape),
+  ].join(',');
+  execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', a, '-vf', f, b]);
+  console.log(b);
+} else if (principal) {
+  console.error('uso: zonas.mjs comandos | zonas.mjs mascara <in.png> <out.png>');
+  process.exit(1);
+}

package/src/cli.mjs

@@ -0,0 +1,45 @@
+import { install } from "./install.mjs";
+import { doctor } from "./doctor.mjs";
+import { delegar } from "./delegar.mjs";
+import { versaoPacote } from "./paths.mjs";
+
+const AJUDA = `easyedit ${versaoPacote()}
+
+Uso: easyedit <comando> [opções]
+
+  install [--project <dir>]   Instala skills, contrato e templates no projeto (padrão: pasta atual).
+  update  [--project <dir>]   Atualiza skills e contrato; preserva specs e o TOOLS.md local.
+  doctor  [--project <dir>]   Confere Node, FFmpeg, HyperFrames, whisper e a instalação.
+  novo    [args]              Atalho para o script de /easyedit-novo (--cliente, --title, --vertical).
+  progress [args]             Atalho para o script de /easyedit-progress.
+  --version                   Mostra a versão do pacote.
+
+Opções de install/update: --dry-run (só mostra o que faria), --agents (copia também para .agents/skills).`;
+
+export async function main(argv) {
+  const [cmd, ...resto] = argv;
+  const opts = lerOpcoes(resto);
+  switch (cmd) {
+    case "install": return install({ ...opts, modo: "install" });
+    case "update": return install({ ...opts, modo: "update" });
+    case "doctor": return doctor(opts);
+    case "novo": return delegar("easyedit-novo", "novo_video.mjs", resto);
+    case "progress": return delegar("easyedit-progress", "progress.mjs", resto);
+    case "--version": case "-v": console.log(versaoPacote()); return;
+    case undefined: case "help": case "--help": case "-h": console.log(AJUDA); return;
+    default:
+      console.error(`Comando desconhecido: ${cmd}\n`);
+      console.log(AJUDA);
+      process.exitCode = 1;
+  }
+}
+
+function lerOpcoes(args) {
+  const o = { project: process.cwd(), dryRun: false, agents: false };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project") o.project = args[++i];
+    else if (args[i] === "--dry-run") o.dryRun = true;
+    else if (args[i] === "--agents") o.agents = true;
+  }
+  return o;
+}

package/src/delegar.mjs

@@ -0,0 +1,10 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function delegar(skill, script, args) {
+  const p = join(process.cwd(), ".claude", "skills", skill, "scripts", script);
+  if (!existsSync(p)) throw new Error(`Skill ${skill} não encontrada em ${process.cwd()}. Rode \`easyedit install\` primeiro.`);
+  const r = spawnSync(process.execPath, [p, ...args], { stdio: "inherit" });
+  process.exitCode = r.status ?? 1;
+}

package/src/doctor.mjs

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { versaoPacote } from "./paths.mjs";
+
+function cmd(c, args) {
+  const r = spawnSync(c, args, { encoding: "utf8" });
+  return r.error || r.status !== 0 ? null : (r.stdout || r.stderr).trim().split("\n")[0];
+}
+
+export function doctor({ project }) {
+  const alvo = resolve(project);
+  const linhas = [];
+  let falhas = 0;
+  const item = (ok, nome, detalhe, obrigatorio = true) => {
+    if (!ok && obrigatorio) falhas++;
+    linhas.push(`${ok ? "✔" : obrigatorio ? "✘" : "–"} ${nome}${detalhe ? `: ${detalhe}` : ""}`);
+  };
+
+  const nodeMaior = Number(process.versions.node.split(".")[0]);
+  item(nodeMaior >= 22, "Node ≥ 22", process.versions.node);
+  const ff = cmd("ffmpeg", ["-version"]);
+  item(!!ff, "FFmpeg", ff ?? "instale (ex.: brew install ffmpeg)");
+  item(!!cmd("ffprobe", ["-version"]), "FFprobe");
+  const hf = cmd("npx", ["--no-install", "hyperframes", "--version"]);
+  item(!!hf, "HyperFrames", hf ?? "instale no projeto (npm i -D hyperframes)");
+  item(!!cmd("whisper-cli", ["--help"]) || existsSync("/opt/homebrew/bin/whisper-cli"), "whisper-cli (transcrição)", "", false);
+  item(process.platform === "darwin" && !!cmd("swiftc", ["--version"]), "swiftc (verificador de zonas seguras, só macOS)", "", false);
+
+  const v = join(alvo, ".easyedit", "version");
+  const inst = existsSync(v) ? readFileSync(v, "utf8").trim() : null;
+  item(!!inst, "EasyEdit instalado", inst ? `v${inst}${inst !== versaoPacote() ? ` (pacote é v${versaoPacote()}; rode update)` : ""}` : "rode `easyedit install`");
+  const sk = join(alvo, ".claude", "skills");
+  const n = existsSync(sk) ? readdirSync(sk).filter((s) => s.startsWith("easyedit-")).length : 0;
+  item(n > 0, "Skills easyedit-*", `${n} encontradas`);
+  item(existsSync(join(alvo, "clientes")), "Pasta clientes/", "", false);
+
+  console.log(linhas.join("\n"));
+  if (falhas) { console.log(`\n${falhas} item(ns) obrigatório(s) com problema.`); process.exitCode = 1; }
+}

package/src/install.mjs

@@ -0,0 +1,62 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { PAYLOAD, versaoPacote } from "./paths.mjs";
+
+const INI = "<!-- easyedit:begin -->";
+const FIM = "<!-- easyedit:end -->";
+
+export function install({ project, modo, dryRun, agents }) {
+  const alvo = resolve(project);
+  if (!existsSync(alvo) || !statSync(alvo).isDirectory()) throw new Error(`Pasta não encontrada: ${alvo}`);
+  const fx = join(alvo, ".easyedit");
+  const versaoAntiga = existsSync(join(fx, "version")) ? readFileSync(join(fx, "version"), "utf8").trim() : null;
+  if (modo === "update" && !versaoAntiga) throw new Error("EasyEdit não está instalado aqui. Rode `easyedit install`.");
+
+  const acoes = [];
+  const fazer = (descricao, fn) => { acoes.push(descricao); if (!dryRun) fn(); };
+
+  // skills: substitui apenas easyedit-* (não toca em skills de outros)
+  const destinos = [join(alvo, ".claude", "skills")];
+  if (agents) destinos.push(join(alvo, ".agents", "skills"));
+  const skills = readdirSync(join(PAYLOAD, "skills")).filter((n) => n.startsWith("easyedit-"));
+  for (const d of destinos) {
+    for (const s of skills) {
+      fazer(`skill ${s} → ${d}`, () => {
+        rmSync(join(d, s), { recursive: true, force: true });
+        mkdirSync(d, { recursive: true });
+        cpSync(join(PAYLOAD, "skills", s), join(d, s), { recursive: true });
+      });
+    }
+  }
+
+  // contrato e template: sempre atualizados
+  fazer(".easyedit/Spec.md e templates/", () => {
+    mkdirSync(join(fx, "templates"), { recursive: true });
+    cpSync(join(PAYLOAD, ".easyedit", "Spec.md"), join(fx, "Spec.md"));
+    cpSync(join(PAYLOAD, ".easyedit", "templates"), join(fx, "templates"), { recursive: true });
+  });
+
+  // TOOLS.md descreve a máquina: só cria se não existir
+  if (!existsSync(join(fx, "TOOLS.md"))) {
+    fazer(".easyedit/TOOLS.md (novo)", () => cpSync(join(PAYLOAD, ".easyedit", "TOOLS.md"), join(fx, "TOOLS.md")));
+  } else acoes.push(".easyedit/TOOLS.md preservado");
+
+  fazer(".easyedit/version", () => writeFileSync(join(fx, "version"), versaoPacote() + "\n"));
+  fazer("CLAUDE.md (seção EasyEdit)", () => escreverSecao(join(alvo, "CLAUDE.md")));
+
+  console.log(`${dryRun ? "[dry-run] " : ""}easyedit ${modo}: ${versaoAntiga ?? "nova instalação"} → ${versaoPacote()}`);
+  for (const a of acoes) console.log(`  · ${a}`);
+  if (!dryRun) console.log("\nAbra uma sessão nova do agente nesta pasta para carregar as skills. Depois rode `easyedit doctor`.");
+}
+
+function escreverSecao(arquivo) {
+  const secao = `${INI}\n${readFileSync(join(PAYLOAD, "claude-section.md"), "utf8").trim()}\n${FIM}\n`;
+  if (!existsSync(arquivo)) return writeFileSync(arquivo, secao);
+  const atual = readFileSync(arquivo, "utf8");
+  const i = atual.indexOf(INI), f = atual.indexOf(FIM);
+  if (i !== -1 && f > i) return writeFileSync(arquivo, atual.slice(0, i) + secao + atual.slice(f + FIM.length).replace(/^\n/, ""));
+  // seção antiga sem marcadores (instalação manual): substitui o bloco "## EasyEdit"
+  const m = atual.match(/^## EasyEdit[\s\S]*?(?=^## |\s*$(?![\s\S]))/m);
+  if (m) return writeFileSync(arquivo, atual.replace(m[0], secao + "\n"));
+  writeFileSync(arquivo, atual.replace(/\s*$/, "\n\n") + secao);
+}

package/src/paths.mjs

@@ -0,0 +1,10 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+
+export const RAIZ_PACOTE = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const PAYLOAD = join(RAIZ_PACOTE, "payload");
+
+export function versaoPacote() {
+  return JSON.parse(readFileSync(join(RAIZ_PACOTE, "package.json"), "utf8")).version;
+}