@intelli-ia/easyedit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +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/README.md

@@ -3,8 +3,7 @@
 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        # após publicar
-    npm install --global github:intelli-ia/easyedit    # direto do GitHub
+    npm install --global @intelli-ia/easyedit
     # desenvolvimento: npm link nesta pasta
 
 ## Usar num projeto
@@ -16,5 +15,12 @@ Especificação, entrevista e acompanhamento de edição de vídeo (HyperFrames)
 Depois abra uma sessão nova do agente e use `/easyedit-novo` → `/easyedit-interviewer` → `/easyedit-build`.
 
 ## Requisitos
-Node 22+, FFmpeg, HyperFrames no projeto (`npm i -D hyperframes`). Whisper.cpp para transcrição. O verificador de zonas seguras usa Swift/Vision e só roda em macOS.
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intelli-ia/easyedit",
-  "version": "0.1.0",
+  "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" },

package/payload/.easyedit/TOOLS.md

@@ -2,7 +2,9 @@
 
 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 em 2026-10-14 com `npx hyperframes doctor` e `--help` de cada comando. Atualize quando uma versão ou capacidade mudar.
+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
 
@@ -85,13 +87,13 @@ Workflows que o roteador instala sob demanda, ainda não presentes na máquina:
 
 | Ferramenta | Versão / caminho | Papel no pipeline |
 | --- | --- | --- |
-| Node.js | v24.20.0 (exigido ≥ 22) | Roda a CLI e os scripts. |
-| FFmpeg / FFprobe | 9.0.1 · `/opt/homebrew/bin` | 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 | 152.0.7977.30 · cache em `~/.cache/hyperframes/chrome` | Renderiza cada frame da composição. Gerenciado por `hyperframes browser`. |
-| whisper.cpp (`whisper-cli`) | `/opt/homebrew/bin/whisper-cli` | 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. |
+| 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 | 29.7.2 instalado, **não está rodando** | Render determinístico opcional (`--docker`). |
+| 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. |

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

@@ -53,7 +53,7 @@ Durante o trabalho:
 ## 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**.
+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:
 
@@ -62,7 +62,7 @@ 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.
+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.
 

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

@@ -46,7 +46,7 @@ node ../../../../.claude/skills/easyedit-zonas-seguras/scripts/zonas.mjs comando
 
    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`.
+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) e compara tudo com a área útil. Também confere o `elementos.json`. No **macOS** a detecção é automática (framework Vision, local, sem rede). Em **Windows/Linux** não há detecção automática de rosto: o verificador gera folhas de contato com as zonas em vermelho (`revisao-visual/folha01.png`…, 18 quadros por folha) e imprime `REVISÃO VISUAL OBRIGATÓRIA`. Nesse caso **abra cada folha com a ferramenta de leitura de imagens**, confira se algum rosto, texto, logo ou produto cai sobre o vermelho, e registre o resultado (e os instantes com problema) em Evidências. Use `--manual 1` para pedir esse modo também no macOS e `--manual-fps` para mudar a amostragem (padrão 1 quadro por segundo). Um detector próprio pode ser plugado com a variável `EASYEDIT_DETECTOR` (executável que recebe JPGs e devolve o mesmo JSON do `detectar.swift`).
 
 ```bash
 node .claude/skills/easyedit-zonas-seguras/scripts/verificar_zonas.mjs \
@@ -69,5 +69,5 @@ node .claude/skills/easyedit-zonas-seguras/scripts/verificar_zonas.mjs \
 ## 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`.
+- Requer `ffmpeg` em qualquer sistema. A detecção automática exige macOS com `swiftc` (Xcode Command Line Tools); na primeira execução o detector é compilado em `~/.cache/easyedit/detectar`. Sem ela (Windows/Linux), a revisão visual das folhas é parte obrigatória do gate, e o `elementos.json` continua sendo a verificação exata.
 - Não altere os valores de `ZONAS` sem registrar a mudança e a fonte.

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

@@ -2,20 +2,20 @@
 // 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
+//   1. Pixels (Vision no macOS; EASYEDIT_DETECTOR em qualquer sistema; sem detector, folhas de revisão visual): 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 { basename, 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]');
+if (!args.video && !args.elementos) fail('uso: --video <render.mp4> [--elementos <elementos.json>] [--fps 2] [--out <dir>] [--tol 0.05] [--manual 1]');
 
 const fps = Number(args.fps ?? 2);
 const tol = Number(args.tol ?? 0.05);
@@ -43,6 +43,7 @@ const regioes = ({ x, y, w, h }) => {
 
 const achados = [];
 const info = [];
+let manual = null;
 
 // ---- camada 2: elementos declarados
 if (args.elementos) {
@@ -57,52 +58,81 @@ if (args.elementos) {
 }
 
 // ---- camada 1: pixels
+// Detector: Vision (macOS), executável externo (EASYEDIT_DETECTOR) ou revisão visual manual (Windows/Linux).
+// Um detector externo recebe caminhos de JPG como argumentos e imprime em stdout o mesmo JSON do detectar.swift:
+//   [{ "arquivo": "<jpg>", "deteccoes": [{ "tipo": "rosto|texto|objeto", "x": 0-1, "y": 0-1, "w": 0-1, "h": 0-1, "conf": 0-1, "texto": "..." }] }]
+let modoPixels = 'sem-video';
 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 externo = process.env.EASYEDIT_DETECTOR;
+  modoPixels = args.manual === '1' ? 'manual' : externo ? 'externo' : process.platform === 'darwin' ? 'vision' : 'manual';
   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,
-      });
+
+  if (modoPixels === 'manual') {
+    // Sem detector automático: gera folhas de contato com as zonas em vermelho para o agente/pessoa olhar.
+    const mfps = Number(args['manual-fps'] ?? 1);
+    const tw = 270, th = 480;
+    const zonasMini = [
+      `drawbox=x=0:y=0:w=${tw}:h=${Math.round(th * UTIL.y0)}:color=red@0.6:t=fill`,
+      `drawbox=x=0:y=${Math.round(th * UTIL.y1)}:w=${tw}:h=${th - Math.round(th * UTIL.y1)}:color=red@0.6:t=fill`,
+      `drawbox=x=0:y=${Math.round(th * UTIL.y0)}:w=${Math.round(tw * UTIL.x0)}:h=${Math.round(th * (UTIL.y1 - UTIL.y0))}:color=red@0.6:t=fill`,
+      `drawbox=x=${Math.round(tw * UTIL.x1)}:y=${Math.round(th * UTIL.y0)}:w=${tw - Math.round(tw * UTIL.x1)}:h=${Math.round(th * (UTIL.y1 - UTIL.y0))}:color=red@0.6:t=fill`,
+      `drawbox=x=${Math.round(tw * UTIL.x0)}:y=${Math.round(th * UTIL.y0)}:w=${Math.round(tw * (UTIL.x1 - UTIL.x0))}:h=${Math.round(th * (UTIL.y1 - UTIL.y0))}:color=white:t=2`, // contorno da área útil
+    ];
+    const dir = join(out, 'revisao-visual');
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', args.video, '-vf', [`fps=${mfps}`, `scale=${tw}:${th}`, ...zonasMini, 'tile=6x3:padding=4:color=black'].join(','), '-fps_mode', 'passthrough', join(dir, 'folha%02d.png')]);
+    const folhas = readdirSync(dir).filter((f) => f.endsWith('.png')).sort();
+    info.push(`detecção automática de pixels indisponível neste sistema (${process.platform}); ${folhas.length} folha(s) de revisão visual a ${mfps} fps, 18 quadros por folha, da esquerda para a direita e de cima para baixo`);
+    manual = { dir, folhas, fps: mfps };
+  } else {
+    let bin;
+    if (modoPixels === 'vision') {
+      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)');
+      }
+    } else bin = externo;
+    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()));
     }
-  });
-  info.push(`${arquivos.length} frames analisados a ${fps} fps`);
+    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 (${modoPixels})`);
+  }
 }
 
-writeFileSync(join(out, 'relatorio.json'), JSON.stringify({ zonas: ZONAS, tolerancia: tol, info, achados }, null, 2));
+writeFileSync(join(out, 'relatorio.json'), JSON.stringify({ zonas: ZONAS, tolerancia: tol, pixels: modoPixels, revisaoVisual: manual, 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)
@@ -112,7 +142,7 @@ 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 */ }
+  try { execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', frame, '-vf', [...zonasF, ...dets].join(','), join(out, 'anotados', `${basename(frame).replace('.jpg', '.png')}`)]); } catch { /* anotação é opcional */ }
 }
 
 console.log(`${info.join(' · ')}`);
@@ -124,5 +154,6 @@ for (const [chave, lista] of grupos) {
   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('", "')}"` : ''}`);
 }
+if (manual) console.log(`REVISÃO VISUAL OBRIGATÓRIA: abra ${manual.folhas.map((f) => join(manual.dir, f)).join(', ')} e confira se há rosto, texto, logo ou produto sobre as áreas vermelhas (zonas cinzentas). Registre o resultado no spec.`);
 console.log(`relatório: ${join(out, 'relatorio.json')}${porFrame.size ? ` · quadros anotados: ${join(out, 'anotados')}` : ''}`);
 process.exit(erros.length ? 2 : 0);

package/src/doctor.mjs

@@ -3,14 +3,25 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { versaoPacote } from "./paths.mjs";
 
+const SO = process.platform; // darwin | win32 | linux
+const NOME_SO = { darwin: "macOS", win32: "Windows", linux: "Linux" }[SO] ?? SO;
+
+// No Windows, npx e outros são scripts .cmd: precisam de shell. Os argumentos aqui são fixos.
 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];
+  const r = spawnSync(c, args, { encoding: "utf8", shell: SO === "win32" });
+  return r.error || r.status !== 0 ? null : (r.stdout || r.stderr).trim().split(/\r?\n/)[0];
 }
 
+const COMO_INSTALAR = {
+  ffmpeg: { darwin: "brew install ffmpeg", win32: "winget install Gyan.FFmpeg  (ou choco install ffmpeg)", linux: "sudo apt install ffmpeg" },
+  whisper: { darwin: "brew install whisper-cpp", win32: "baixe o whisper.cpp (releases do GitHub) e coloque whisper-cli.exe no PATH; ou use `npx hyperframes models install parakeet`", linux: "compile o whisper.cpp ou use `npx hyperframes models install parakeet`" },
+  hyperframes: { darwin: "npm i -D hyperframes", win32: "npm i -D hyperframes", linux: "npm i -D hyperframes" },
+};
+const como = (k) => `instale: ${COMO_INSTALAR[k][SO] ?? COMO_INSTALAR[k].linux}`;
+
 export function doctor({ project }) {
   const alvo = resolve(project);
-  const linhas = [];
+  const linhas = [`Sistema: ${NOME_SO} (${process.arch})`];
   let falhas = 0;
   const item = (ok, nome, detalhe, obrigatorio = true) => {
     if (!ok && obrigatorio) falhas++;
@@ -20,12 +31,17 @@ export function doctor({ project }) {
   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");
+  item(!!ff, "FFmpeg", ff ?? como("ffmpeg"));
+  item(!!cmd("ffprobe", ["-version"]), "FFprobe", "vem junto com o FFmpeg");
   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);
+  item(!!hf, "HyperFrames", hf ?? `${como("hyperframes")} (dentro do projeto)`);
+  const whisper = !!cmd("whisper-cli", ["--help"]) || (SO === "darwin" && existsSync("/opt/homebrew/bin/whisper-cli"));
+  item(whisper, "whisper-cli (transcrição)", whisper ? "" : como("whisper"), false);
+
+  // Verificador de zonas seguras: detecção automática de rosto só no macOS (Vision) ou com detector externo.
+  if (process.env.EASYEDIT_DETECTOR) item(existsSync(process.env.EASYEDIT_DETECTOR), "Detector externo de zonas (EASYEDIT_DETECTOR)", process.env.EASYEDIT_DETECTOR, false);
+  else if (SO === "darwin") { const sw = !!cmd("swiftc", ["--version"]); item(sw, "swiftc (detector de rosto/texto do verificador de zonas)", sw ? "" : "instale as Xcode Command Line Tools: xcode-select --install", false); }
+  else item(true, "Zonas seguras", `sem detecção automática de rosto no ${NOME_SO}: o verificador gera folhas de revisão visual (confira-as no preview) e a camada declarada (elementos.json) segue valendo`);
 
   const v = join(alvo, ".easyedit", "version");
   const inst = existsSync(v) ? readFileSync(v, "utf8").trim() : null;