CenaForge: primeira versão pública

Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz,
Clipador de lives e Publicador para YouTube, TikTok e Instagram.

Inclui a leitura das visualizações dos posts para o Dashboard e o botão
"Publicar no <rede>" nos cartões das publicações.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 16:35:09 -03:00
co-authored by Claude Opus 5.5
commit 84f30bbc2d
484 changed files with 74826 additions and 0 deletions
@@ -0,0 +1,510 @@
# Clipador (`clipper/`) — cortes automáticos de live
Fonte completa: **`clipper/README.md`**. Ele cobre a arquitetura, as regras da heurística, o juiz, a API,
o `.env` e os limites. Este arquivo só diz onde mexer e o que não pode quebrar. Não copie o README para cá.
## O que é
Serviço FastAPI local (Python 3.12, `clipper/.venv`) em `127.0.0.1:4520`. Ele grava uma live (Twitch, YouTube
ou Kick) ou um VOD, lê o chat, transcreve pelo serviço de voz e pede o veredito a uma IA pela CLI. Depois
renderiza cortes verticais (1080×1920, padrão) ou horizontais (1920×1080, YouTube). Toda rota, exceto `GET /health`, exige `X-Service-Key` (`CLIPPER_SERVICE_KEY` de
`clipper/.env`; nunca copie a chave).
| O quê | Onde |
|---|---|
| Banco do Clipador | `data/clipper/clipper.db` (`PRAGMA user_version` 10, `SCHEMA` em `clipper/app/db.py`: v1 tabelas, v2 `settings`, v3 jogo/varredura/emotes/configuração do corte — colunas novas em `sessions`, `channels.settings_json`, `chat.emotes`, `clips.learned`, tabelas `games` e `emotes`; v4 `edits` (`clip_id`, `project_json`, `rev`, `cover`, `exported_at`, `created_at`, `updated_at`); v5 `face_track`; v6 `games.notes_json`/`games.edited_at`; v7 `edits.origin` (`ai`/`user`) + `edits.ai_project_json`; v8 `clips.aspect` (`vertical`/`horizontal`, padrão `vertical`, gravado no render); v9 `sessions.capture_json` (o que a captura gravou de fato; sessões antigas `NULL`); v10 tabela `deleted_clips` (marca do corte apagado, `ON DELETE CASCADE` com a sessão)). Migra ao subir o serviço. **Nunca altere uma migração já aplicada** (o banco real estava em v4 quando a v7 nasceu): coluna nova = `ALTER` numa versão nova |
| Blocos gravados (`.ts` de 30 s + `segments.csv`) e frames | `data/clipper/sessions/<id>/` (frames em `frames/`) |
| Pesos do rastreio de reação (YuNet, MediaPipe, OpenSeeFace) | `data/clipper/models/`, fixados (URL imutável + sha256) em `clipper/models.lock.json` |
| Cortes prontos | `output/clipper/<sessão>/clip-<id>.mp4` + `clip-<id>.jpg` |
| Arquivos do editor (proxy, TTS) | `output/clipper/<sessão>/edit-<id>/` (narração em `tts-<hash12>.wav`) |
| Fontes empacotadas (ASS e prévia do painel) | `assets/fonts/` **plana** (Luckiest Guy Apache-2.0; Bangers, Anton, Bebas Neue, Poppins ExtraBold OFL-1.1; licença ao lado de cada `.ttf`), fixadas em `assets/fonts/fonts.lock.json` (URL presa a commit do google/fonts + sha256 + `family` = nome dentro do arquivo). Fonte nova: arquivo na pasta + entrada no lock (gotchas, item 105) |
| Vínculo canal → conta (painel) | tabela `account_channels` em `data/cenaforge.db` (migração **v3** do painel, `panel/src/lib/db.ts`; sem chave estrangeira para o canal) |
## Onde mexer
| Mudança | Arquivo(s) | Também atualizar |
|---|---|---|
| Captura (Streamlink → bomba Python → `ffmpeg -f segment`), linha do tempo, hora do chat, metadados (`title`/`category`) | `clipper/app/worker.py`, `sources.py` | `clipper/tests/` |
| Qualidade de gravação (`capture.quality`, argumentos do Streamlink, `OPTIONS` com GB/h, `record_run` → `sessions.capture_json`) | `clipper/app/capture.py`; validação `CAPTURE_QUALITIES` em `layout.py`; gravação do 1º bloco em `worker.py` | `clipper/tests/test_capture_quality.py` |
| Busca de quadro dentro de bloco `.ts` (`seek_args`, `grab_frame`) e emenda de resolução/codec (`uniform_segments`) | `clipper/app/media.py`; `clipper/app/editor_render.py`; `face.grab_bgr` e tamanho do quadro por bloco (`_frame_size`) em `face.py` | gotchas, itens 107–108 |
| Retomada de live (`Engine.live_check`, `keep_live`, `RESUME_DELAYS_S`, `resume_interrupted`), render que falha (`recover_orphan_renders`, `ORPHAN_RENDER_S` 300, `MAX_RENDER_ATTEMPTS` 3), cortes duplicados (`SAME_PEAK_S` 10, `SAME_MOMENT_OVERLAP` 0,6, `KEPT_STATUSES`/`VETO_STATUSES`, `discard_pending_duplicates`) | `clipper/app/worker.py` | `clipper/tests/test_resume.py`, `clipper/tests/test_render_and_duplicates.py` |
| Apagar cortes (`delete_clip`, `delete_many`, `select_ids`, `MAX_BATCH` 500, recusas `BUSY`/`PUBLISHED`/`CHANGED`, marca `marks`/`mark_spans`, arquivos só dentro das pastas do Clipador) | `clipper/app/clip_delete.py`; rotas em `main.py` (`ClipsDeleteIn`); marca lida em `worker.py` (veto depois do juiz) e na varredura (`intel.py`) | `clipper/tests/test_clip_delete.py`; `METHODS` em `panel/src/lib/clipper.ts`; seção "Apagar cortes" abaixo |
| Chat (IRC anônimo da Twitch com `CAP REQ :twitch.tv/tags` → emotes nativos e `room-id`; Pusher da Kick, emotes `[emote:id:NOME]`) | `clipper/app/chat.py` | — |
| Heurística: pesos, base de 3 min, mínimo proporcional (`_required_messages`), reações (`min_reactions`), chat fraco (`sparse_rate` 0,5 msg/s), momentos do chat/áudio/rosto (`_chat_moments`/`_audio_moments`/`_face_moments`; `face_*` em `Params`), `pick_peaks`, `fit_window` (duração de todo corte automático) | `Params` e funções em `clipper/app/scoring.py`; alvo `min_target` em `layout.py` | `clipper/tests/test_scoring.py` (regressões de falso positivo, chat fraco e rosto), `test_duration_banner_fonts.py` |
| Rastreio de reação — E/S: backends (MediaPipe; plano B OpenSeeFace), download sob demanda com sha256, recorte FFmpeg 6 qps, laço `face` | `clipper/app/face.py` (`for_scoring`, `must_wait`, `view`, `reset`); laço `_face_loop` e uso de `must_wait` na decisão do corte em `worker.py`; bancada `clipper/tools/face_bench.py` | `clipper/tests/test_face.py`, `clipper/models.lock.json`, `doc/FACE_BAKEOFF.md` |
| Rastreio de reação — lógica pura: sinal por segundo contra o neutro do streamer, rótulos, `reaction_moments`, `summarize` (linha do analista), `locate_cam` (câmera pelo rosto) | `ReactionParams` e funções em `clipper/app/reaction.py` | `clipper/tests/test_reaction.py` |
| Emotes: catálogo 7TV/BTTV/FFZ (canal + global, TTL 1 h, fonte que falha é ignorada), emojis, peso aprendido (`LEARN_UP`/`LEARN_DOWN` 0,3/0,15) | `clipper/app/emotes.py`; ingestão e aprendizado em `clipper/app/intel.py` (`ingest_chat`, `learn_from_clip`) | `clipper/tests/test_intel.py` |
| Contexto do jogo (categoria a cada `GAME_CHECK_S` 600, `screen_game`, perfil pela web; `clean_profile`, `save_profile`, `refine`, `delete_note`), varredura (`SCAN_*`), webcam (`detect_cam`: YuNet local primeiro, IA só se não achar ou `use_ai`; `CAM_RETRY_S` 300), opções `OPTION_DEFAULTS` (inclui `faceTrack`) | `clipper/app/intel.py` | README do Clipador |
| Juízes (analista + editor), prompts, glossário `CHAT_GLOSSARY`, linha "Rosto do streamer: …" do analista, schemas, chamada da CLI, pesquisa e refino do jogo (`PROFILE_SYSTEM`/`research_game`, `REFINE_SYSTEM`/`refine_game`), câmera | `clipper/app/judge.py`; montagem dos 6 frames do analista (8 se o trecho passa de 80 s) em `worker.py` | README do Clipador |
| Hashtags da legenda (`to_tag`, `fold`, `split_hashtags`, `compose`, `build_caption`; `MAX_TAGS` 8, `GAME_TAGS` 3, `MOMENT_TAGS` 4) | `clipper/app/hashtags.py`; uso em `judge_clip` de `worker.py`; campo `hashtags` em `judge.py` (`VERDICT_SCHEMA`, `PROFILE_SCHEMA`, `Verdict.hashtags`) e `PROFILE_LISTS`/`clean_profile`/`Intel.session_game` em `intel.py` — ver "Hashtags da legenda" abaixo | `clipper/tests/test_hashtags.py` |
| Configuração do corte: camadas padrão ← canal ← sessão ← projeto (`DEFAULTS`, `merge`, `validate`), `format.aspect` (`ASPECTS`, `FRAME_SIZES`, `CANVAS_SIZES`, `aspect()`), `MODES` (5 modos, inclui `cam_only`), `resolved_mode` (queda para `blur` sem câmera; `full` no horizontal), retângulos, legenda, crédito, `duration` (`min_target`), `hook` (`HOOK_STYLES`, `HOOK_ANIMS`, `HOOK_FONT`), `capture`; fontes empacotadas (`PACKAGED_FONTS`, `font_files`, `ass_filter` = `ass=` com `fontsdir` só se o ASS usar uma delas); cadeia de layout reutilizável `layout_chain(settings, src, dst, tail, suffix, mode)` (usada por `video_filter` e pelo editor) | `clipper/app/layout.py`; rotas de settings em `main.py` (devolvem `aspects`, `frames`, `fontFiles`, `hookStyles`, `hookAnims` e `captureQualities`) | `clipper/tests/test_format_and_captions.py` (o vertical precisa continuar batendo com `clipper/tests/data/vertical_golden_sha256.json`); modo novo também em `LayoutMode`/`MODE_LABEL` de `panel/src/components/clipper-client.ts` e `resolvedMode` de `clip-editor-model.ts`; grupo novo também em `CutSettings` (`Aspect`, `aspectOf`, `withFormat` para serviço antigo) |
| Projeto de edição: modelo, tempo sessão↔saída, `normalize_cuts`, `validate_project`, `auto_project` (projeto da IA), `pick_hook` (texto do gancho), `CAPTION_PRESETS`, `SUGGEST_SCHEMA`/`clean_suggestion` | `clipper/app/editor.py` | `clipper/tests/test_editor.py`, `clipper/tests/test_editor_layers.py`; tipos espelhados em `panel/src/components/clip-editor-model.ts` |
| Render do corte (ASS animado, gancho e tarja `banner`, textos, barra, chat na tela `chat_events`, filtergraph, trecho mudo, áudio, proxy, forma de onda, capa e capa no início) | `clipper/app/editor_render.py` (`render_project`, `build_filter`, `build_project_ass`); cores ASS via `layout.ass_color`/`ass_inline_color` | [gotchas.md](gotchas.md) itens 57, 71, 74–78, 104–105 |
| Reenquadramento do jogo (`reframe.keys`, `perspective_filter`) e camadas inseridas (`kind: "inset"`, decoração numpy/OpenCV), `EASES`, `MAX_KEYS` 60, `MAX_INSETS` 12 | `clipper/app/reframe.py`; validação em `editor.py`; grafo em `editor_render.py` | `clipper/tests/test_reframe_insets.py`; interpolação espelhada em `clip-editor-model.ts` (`easeAt`, `interpolate`, `reframeAt`) — as duas precisam dar o mesmo valor; gotchas, item 106 |
| Rotas do editor, `ensure_edit`, `render_clip_edit`, `chat_for` (mensagens da sessão para o chat na tela) | `clipper/app/editor_api.py`; chamado por `Engine.render_clip` em `worker.py` | `ALLOWED` e timeout em `panel/src/lib/clipper.ts` |
| Legenda (tempo saneado: `clean_words`, `group_words`, `caption_blocks`; `build_ass`) e crédito — usada pelo render do editor e pelo worker, nos dois formatos | `clipper/app/subtitles.py` (`MIN_WORD_S` 0,06, `MIN_STEP_S` 0,04). `media.render_vertical` ainda existe em `media.py`, mas **não** é mais usado pelo render de cortes | `clipper/tests/test_format_and_captions.py`; [gotchas.md](gotchas.md) itens 57–58, 70, 90 |
| Rotas HTTP | `clipper/app/main.py` (editor: `editor_api.py`) | `ALLOWED` em `panel/src/lib/clipper.ts` (o proxy recusa caminho fora da regex) e o timeout por rota no mesmo arquivo |
| Variáveis do `.env` | `clipper/app/config.py` + `clipper/.env.example` | tabela do README do Clipador |
| Página `/clipper` | `panel/src/app/clipper/page.tsx`, `panel/src/components/clipper-*.tsx` (`clipper-cut-settings.tsx` modal do corte em 5 abas, com Gancho e "Qualidade da gravação"; `clipper-games.tsx` aba Jogos e emotes (editar perfil, pedir à IA, pedidos guardados); `clipper-queue.tsx` cartão com a análise, reação do rosto (`FaceSignal`, `FACE_LABEL`), recuo do início `START_STEPS`, botão "Editar"/"Continuar edição", "Apagar" e seleção discreta (`SelectionPill`); `clipper-judge.tsx` interruptor "Rastrear a reação do streamer"; `clipper-sessions.tsx` cartão da sessão (`sessionHealth`, selo de quem achou a câmera, relógio `RecordingClock`, cadência `SummaryCadence`) e cabeçalho em `clipper-studio.tsx`), cliente `clipper-client.ts` | [panel.md](panel.md) |
| Página do editor `/clipper/edit/[clipId]` | `panel/src/app/clipper/edit/[clipId]/page.tsx` + `panel/src/components/clip-editor*.ts(x)` (papel de cada arquivo em [panel.md](panel.md#editor-de-cortes)); tokens `--color-nle-*` e bloco `.nle` em `panel/src/app/globals.css` | [panel.md](panel.md#editor-de-cortes) |
| Ponte e proxy do painel | `panel/src/lib/clipper.ts` + `panel/src/app/api/clipper/[...path]/route.ts` | — |
| Fontes (canais de live) nos canais de publicação | `linkChannel`/`endChannel`/`accountsForChannel` em `panel/src/lib/accounts.ts`; rotas `panel/src/app/api/accounts/[id]/channels/`; card "Fontes de corte" em `account-manager.tsx`. Na UI "Canais" virou **"Fontes"**; código e rotas seguem `channels` | [panel.md](panel.md) |
| Publicação dos cortes | despachante do painel lê `GET /v1/clips` com `channel=` (fontes, separadas por vírgula), `status=ready,approved` e `ids=`; aprova (`PATCH status=approved`) e marca `published` | [publishing.md](publishing.md) |
## Como os momentos nascem (resumo; regras completas no README)
- `source` do corte: `chat`, `audio`, `face` (rosto forte com apoio), `ai` (varredura) ou `manual`.
- **Chat:** mínimo nos 8 s do pico = 3× a mediana recente, entre 4 (`min_peak_floor`) e 12 (`min_peak_messages`), e
≥ 2 reações (texto ou emote) — ou o dobro do mínimo em mensagens. Emote soma bônus + peso aprendido do canal.
- **Áudio:** sempre sem chat; também com chat fraco (< `sparse_rate` 0,5 msg/s).
- **Varredura** (`scanEnabled`, `scanIntervalS` 180, 60–900): a IA vê até 7 frames + fala + chat + perfil do jogo e
propõe 0–2 momentos; proposta com nota < 4 (`SCAN_MIN_PROPOSAL`) não vai aos juízes. Cada janela grava em
`sessions.memory_json` `proposals` (quantas a IA propôs) e `created` (quantas viraram candidato) e loga
"varredura <sessão> lo–hi s: N proposta(s), M candidato(s)": é por aí que se sabe se ela não propôs ou se foi barrada.
- **Aprendizado dos emotes:** aprovar/rejeitar no painel = ±0,3/0,15 nos emotes de −10 s a +6 s do pico, uma vez por
corte (`clips.learned`); a decisão da IA conta com `factor=0.5`. Peso limitado a −1…3.
## Juízes (decisão do usuário: pela CLI, sem chave de API)
- Provedores `codex` (padrão `gpt-6-luna`; lista de `~/.codex/models_cache.json`), `claude` (`haiku`/`sonnet`/`opus`)
ou `off` (só a heurística).
- **ANALISTA** vê 6 frames (8 se o trecho passa de 80 s) + fala + chat + glossário e devolve `situation`, `what_happened`, `screen`, `speech`,
`chat_meaning`, `confidence` (0–1) e início/fim da ação. **EDITOR** vê só texto + a análise e escreve título,
legenda, nota e corte. Os dois podem recuar até `duration.backtrackS` (padrão 120 s) antes do candidato.
- `PUT /v1/judge`: provedor, `model` (editor), `analystModel` (vazio = o mesmo), `minScore`, `scanEnabled`,
`scanIntervalS`, `vision`, `camDetect`, `faceTrack`. Fica na tabela `settings`, sem reiniciar; o `.env` só dá o valor inicial.
- Codex: cada imagem com seu `-i`, todas antes do `-` final; `--search` é opção **global** (antes de `exec`).
- Custo fixo: cada chamada é um processo novo (2 por candidato). `codex_lean_overrides(search, config_file=None)` em
`judge.py` enxuga o Codex; o Claude leva `--setting-sources project,local`. Números e limites em
[token-economy.md](token-economy.md); teste: `test_codex_lean_overrides`. Vale após reiniciar o Clipador (gotcha 136).
- Não adicione chave de API ao juiz sem pedido do usuário. Corte manual é renderizado mesmo com nota baixa.
## Hashtags da legenda (`hashtags.py`)
Pedido do dono (17/11/2026): a IA põe as # certas, do jogo e da missão. A legenda do corte = texto + hashtags + crédito,
montada por `build_caption(text, tags, credit)` (partes separadas por linha em branco; o crédito é "🎥 Créditos: link").
- **Quem escolhe o quê:** o sistema fixa o **canal** (nome do streamer) e as do **jogo** (até 3 de `profile.hashtags`;
sem perfil ou sem a seção, o nome do jogo). A IA escolhe só as do **momento** (2–4 no campo `hashtags` do veredito:
missão, atividade, evento, modo, lugar, item ou personagem, de preferência com termos do perfil; sem genéricas e sem
repetir canal ou jogo). `JUDGE_SYSTEM` manda a `caption` sem hashtags; `split_hashtags` tira as que vierem no texto
e as junta às do momento.
- `compose(streamer, game, profile, moment)`: canal → jogo → até 4 do momento, sem repetidas (`fold`: sem #, acento e
maiúscula), até 8. `to_tag`: "ROB RUN" → `#ROBRUN`, "perseguição policial" → `#PerseguiçãoPolicial`; sem letra → `None`.
- `Verdict.hashtags` é tupla (padrão `()`); `_clean` aceita resposta sem `hashtags`. `_MOMENT` (varredura) **não** tem o
campo. Sem juiz ou com o juiz falhando, ainda saem as tags do canal e do jogo.
- Perfil do jogo: `PROFILE_SCHEMA` ganhou `hashtags` (3–6 que o público usa no TikTok, Shorts e Reels BR, a principal
primeiro); `PROFILE_SECTIONS` ganhou "Hashtags"; `clean_profile` normaliza com `to_tag`/`fold`. `game_context` também
passa as `mechanics` como termos para as tags do momento. `Intel.session_game(session)` devolve (nome, perfil) com o
mesmo critério do contexto.
- Painel: seção "Hashtags" (violeta, chips, editável, com chat) em `SECTIONS` e `ProfileView` de `clipper-games.tsx`;
`GameProfile.hashtags?` em `clipper-client.ts`. Armadilha de perfil sem a seção e de cortes antigos: gotchas, item 144.
- API: `GameRefineIn.section` aceita `"hashtags"` (chat da seção) e `GameProfileIn.hashtags` (lista, máx. 20) existe;
sem esse campo, salvar o perfil à mão apagaria as hashtags. Campo novo no perfil = acrescentar nos dois modelos de
`main.py`. Teste: `test_api_accepts_hashtags_in_profile_edit_and_section_chat`.
- Só vale depois de reiniciar o Clipador (gotchas, item 143). Limite: tags do momento dependem da CLI real; não testado
com IA real.
## Configuração do corte
- `GET/PUT /v1/channels/{id}/settings` (padrão do streamer) e `/v1/sessions/{id}/settings` (`settings_json`,
sobrescreve campo a campo). Modos `auto|blur|cam_top|game_only|cam_only`; `cam`/`game` = retângulos 0–1 do quadro
original. `cam_only` = câmera do streamer na tela inteira; `cam_top` e `cam_only` sem câmera marcada caem em `blur`.
- `format.aspect`: `vertical` (padrão, 1080×1920) ou `horizontal` (1920×1080, YouTube). No horizontal: quadro original
inteiro (ou `layout.game` recortado para preencher); `cam_only` continua valendo; `auto`/`blur`/`cam_top`/`game_only`
viram quadro inteiro (`resolved_mode` = `full`). ASS num quadro lógico 2560×1440 → tamanhos em px do JSON saem a
75 %; legenda automática a 85 % da altura; crédito no canto direito. Tabela de tamanhos no README do Clipador.
- `duration`: padrão `{minS: 60, maxS: 90, backtrackS: 120}`; limites `minS` 5–120, `maxS` 15–180, `backtrackS` 0–120 e
`minS` < `maxS` (senão `LayoutError`). Para Shorts de terceiros, baixe o canal para ≤ 60 s. **Todo corte automático
sai com ≥ `minS` + 1 s e ≤ `maxS`** (`layout.min_target` = `minS` + 1,1 s, por `scoring.fit_window`): heurística,
varredura, juízes, `auto_project` (depois de silêncios e aparos), remoção de silêncio e "IA sugere". Faltando
material, o corte cresce para trás (no começo da gravação, para a frente); gravação menor que o mínimo não inventa
vídeo. "Cortar agora" e a edição à mão continuam livres. Não reintroduza ajuste de início/fim fora de `fit_window`
(gotchas, item 103).
- `hook` (estilo do gancho que o projeto da IA põe na abertura): `{style: plain|banner, bg, color, font,
anim: pop|fade|none|slide, seconds 1–8}`; padrão `banner`, `#00FF00`, `#FFFFFF`, Luckiest Guy, `slide`, 3 s. Tudo em
ASS, sem filtro extra (entrada `slide` em duas camadas: gotchas, item 104).
- Fontes (`caption.font`, `hook.font`, `font` dos textos): as do Windows (Arial Black, Arial, Impact, Verdana, Segoe UI
Black, Trebuchet MS) e as empacotadas de `assets/fonts/` (sha256 conferido ao carregar). Nome = família de dentro do
arquivo ("Poppins ExtraBold").
- `capture.quality`: `best` (padrão) | `1440p` | `1080p` | `720p` | `480p` (teto), por canal e por sessão (não por
corte); vale na **próxima** gravação ou retomada. `CLIPPER_QUALITY` não é mais lida. Detalhes em "Qualidade de
gravação" abaixo.
- `GET …/settings` devolve `own`, `effective`, `defaults` (com `format`, `duration` e `hook`), `modes`, `fonts`,
`fontFiles` (`{família: "assets/fonts/…ttf"}`), `hookStyles`, `hookAnims`, `aspects`, `frames`
(`{vertical, horizontal: {width, height, canvasWidth, canvasHeight}}`) e `captureQualities`
(`[{id, label, maxHeight, gbPerHour, gbPerHourMax, hint}]`). O formato do arquivo renderizado fica em `clips.aspect` e
sai no JSON do corte (antes do 1º render, `vertical`).
- Webcam: `POST /v1/sessions/{id}/detect-cam` (YuNet local em 12 quadros, sem IA; a IA olha 3 frames só se o local
não achar rosto e `vision` estiver ligada, ou com `?ai=true`) ou automática nos 2 primeiros blocos, se `camDetect`.
`cam_json.source` = `yunet` | `ai` | `manual`. Prévia sem salvar (no formato efetivo): `POST …/preview`; quadro: `GET …/frame?t=`.
- Jogo da sessão: `PUT /v1/sessions/{id}/game` trava a troca automática. Emotes do canal:
`GET /v1/emotes?channel=twitch-<login>`.
- Timeouts do proxy do painel: 8 min para `games/*/(research|refine)`, 5 min para
`clips/*/(proxy|preview-render|retranscribe|tts|suggest|waveform)`, 3 min para `detect-cam|preview|check`, 30 s para
`sessions/*/face(/reset)`, 2 min o resto.
## Qualidade de gravação (`capture.py`)
Fonte completa (tabelas de nomes de stream e de custo): seção "Qualidade de gravação" de `clipper/README.md`.
- Streamlink: `best` (ignora `audio_only` e `*_portrait`); teto = `--stream-sorting-excludes >{teto}60` com
`best,worst-unfiltered` (sem nada abaixo do teto, pega a menor variante: nunca falha pela qualidade). Twitch com
`best`/`1440p`: `--twitch-supported-codecs h264,h265` (o 2K vem em HEVC). AV1 não é pedido (FFmpeg local sem
libdav1d). Sem opção de 30/60 qps (o topo é quase sempre 60 qps; o corte sai em 30 qps).
- Gravado de fato: `ffprobe` do 1º bloco de cada execução → `sessions.capture_json` → `capture` em
`GET /v1/sessions/{id}` (`quality`, `width`, `height`, `fps`, `codec`, `kbps`, `gbPerHour`, `fromIdx`, `runs`,
`mixed`); `null` = sessão antiga (≤ 720p). Painel: "gravando em L×A · fps" no cartão da sessão.
- Medido (17/11/2026, trecho real do skipnho): disco/hora 720p60 1,5 GB, 1080p60 3,6 GB; 1440p60 4,7–4,9 GB/h só com
blocos **gerados** do 1080p (nenhuma live 2K no ar). Render de 60 s com NVENC 6,2–6,7 s em qualquer resolução. A
câmera recortada no vertical sai mais nítida em 1080p que em 720p; 2K ampliado não ganha nada.
- O que existe nas plataformas (17/11/2026): Twitch quase sempre até `1080p60` (+ `*_portrait` em 9 de 143 canais);
Kick até `1080p60`; YouTube pelo Streamlink para em 1080p, até em live "4K".
- Retomada pode trocar de qualidade: o render e o proxy uniformizam o trecho que atravessa a emenda (gotchas, item 108).
## Retomada, render que falha e cortes duplicados (`worker.py`)
Regras completas em "Armadilhas já resolvidas" do README do Clipador.
- **Retomada:** `Engine.live_check` devolve `live` / `offline` ("No playable streams…") / `unknown` (timeout, erro,
JSON inválido). `keep_live` tenta de novo com esperas `RESUME_DELAYS_S` (0, 10, 20, 40, 60, 90, 120 s ≈ 5,7 min)
antes de processar; enquanto tenta, a sessão fica `interrupted`. Vale na subida e para a captura que cai no meio da
live. Só processa depois de esgotar as tentativas ou de ver `offline` 2 vezes seguidas; 3 retomadas seguidas sem
bloco novo desistem. `POST /v1/sessions/{id}/resume` vale para qualquer live que não esteja gravando.
- **Render:** qualquer exceção no render marca o corte `error` com a mensagem e a fila segue. `rendering` órfão há
mais de 5 min volta para `pending`; na 3ª vez vira `error`.
- **Duplicados:** o candidato guarda a janela original (`reasons.candidateStartS/EndS`) e não nasce se o pico estiver a
≤ 10 s de outro corte ou sobrepuser o trecho final ou a janela original de qualquer corte (inclusive `discarded`).
O corte apagado conta como existente (marca em `deleted_clips`, ver "Apagar cortes").
Depois do juiz, o trecho final é conferido contra `VETO_STATUSES` (= `KEPT_STATUSES` pendente/renderizando/pronto/
aprovado/publicado **+ `rejected`**) e contra os apagados que estavam num desses estados: "mesmo momento" (pico a
≤ 10 s ou ≥ 60 % do trecho mais curto coberto) vira `discarded` com "Duplicado do corte N (mesmo momento | que você
rejeitou | que você apagou)" (`judge.duplicateOf`). O descartado pela IA **não** veta o trecho final. "Cortar agora"
(manual) só ganha `judge.warning`. Antes de cada render, `discard_pending_duplicates` usa o **mesmo veto**: tira da
fila o pendente/renderizando igual a um corte pronto, aprovado, publicado ou rejeitado, a um apagado que estava num
desses estados ou a um pendente mais antigo, com o mesmo motivo "Duplicado do corte N (…)". Descartado pela IA não
veta; manual, exportado do editor e o que está renderizando agora nunca saem. Duplicados já prontos não são
mexidos: rejeite ou apague à mão.
## Apagar cortes (`clip_delete.py`)
Fonte completa: seção "Apagar cortes" e tabela "API" de `clipper/README.md`.
| Rota | Faz |
|---|---|
| `DELETE /v1/clips/{id}[?confirmPublished=true]` | 200 `{id, sessionId, status, removedFiles, left: [{file, reason}]}`; 404 `not_found`; 409 `{error, code}` com `busy_candidate`, `busy_rendering`, `published` ou `changed` |
| `POST /v1/clips/delete` `{ids: [≤ 500]}` **ou** `{statuses, sessionId?}`, `confirmPublished?` | 200 `{requested, remaining, deleted, failed: [{id, code, reason}]}`; 400 sem os dois, com os dois ou `sessionId` com `ids`; 422 acima de 500 ou estado inválido |
- Recusa `candidate`, `rendering` e o `pending` que o motor já pegou (`engine._rendering`, sob o mesmo `engine.lock`
do render). `published` só com `confirmPublished`. Cada corte do lote segue as mesmas regras; recusado vai em `failed`.
- Some: linha em `clips`, `edits`, `clip-<id>.*`/`clip-<id>-*` em `output/clipper/<sessão>/`, a pasta `edit-<id>/` e os
quadros do juiz `frames/clip<id>-*.jpg`. Os blocos `.ts` ficam (são da sessão). Só apaga dentro de
`CLIPPER_OUTPUT_DIR`/`CLIPPER_DATA_DIR`, com caminho resolvido; link ou junção some só o link; o que não pôde vai em
`left` com o motivo.
- **O momento apagado não volta:** a marca em `deleted_clips` (pico, trecho final, janela original, estado) entra no
anti-duplicado do candidato (`find_new_clips`), na varredura (`mark_spans`), no veto depois do juiz e na limpeza da
fila antes do render (`discard_pending_duplicates`), nos dois só se o estado era de `VETO_STATUSES`. Não apague a marca para "liberar" o momento sem pedido.
- Proxy do painel: `METHODS` em `panel/src/lib/clipper.ts` aceita só POST em `clips/delete` e só GET/PATCH/DELETE em
`clips/{id}` (outro método = 405). O painel manda os **ids que está mostrando**, nunca `statuses`: corte que chega
depois da confirmação não é apagado junto. UI em [panel.md](panel.md#página-clipper-clipador).
## Rastreio de reação (rosto do streamer)
Fonte completa: seção "Rastreio de reação" de `clipper/README.md`; plano e licenças em `doc/PLANO_RASTREIO_REACAO.md`;
medições em `doc/FACE_BAKEOFF.md`. Roda no PC, sem IA. Opção `faceTrack` (padrão ligada; `PUT /v1/judge`).
- **Stack (licenças livres para publicar):** YuNet `face_detection_yunet_2026may.onnx` (MIT, `cv2.FaceDetectorYN` do
OpenCV 5) acha a câmera; MediaPipe Face Landmarker (Apache-2.0, 478 pontos + 52 blendshapes) mede expressões;
OpenSeeFace `.onnx` (BSD-2) é o plano B (só posição, sem expressões). **Não use** SCRFD/InsightFace, YOLO-Face,
LibreFace, OpenFace 3.0 nem Py-Feat: licença incompatível com publicação.
- **Fluxo:** `face.py` (E/S) recorta a câmera +10 % pelo FFmpeg (~384 px, 6 qps, `rgb24` por pipe) → MediaPipe em
modo VIDEO, um landmarker por bloco → tabela `face_track` (status `done`/`no_cam`/`error`), `cx`/`cy`/`size` no
**quadro inteiro**. `reaction.py` (lógica pura, sem cv2/mediapipe) faz o resto. Câmera trocada → série refeita.
- **Câmera pelo rosto** (`locate_cam`): grupo de rostos estável em ≥ 50 % dos quadros **e** confiança média do grupo
≥ `ReactionParams.min_cam_score` (0,7). Webcam real dá 0,92–0,94; desenho de rosto em live sem câmera dá 0,61–0,66
(gotchas, item 92). Não baixe esse piso sem medir.
- **Sinal:** z robusto de cada canal contra o neutro dos últimos 180 s do próprio streamer; rótulos `risada`, `grito`,
`susto`, `choque`, `raiva`, `confuso`. Ajuste por `ReactionParams` (pisos por canal, pesos, limiares).
- **Cortes:** rosto **reforça, não manda.** `reasons.face` + bônus ≤ 0,6 em momentos do chat/áudio; fonte `face` só
com z ≥ 6 **e** apoio (áudio suavizado ≥ 1,5 ou ≥ 2 mensagens de reação). A decisão do corte espera o rosto do
trecho (no máximo 2 blocos atrás da transcrição). O analista recebe a linha "Rosto do streamer: …" — exceto
quando a série da sessão é do plano B OpenSeeFace (sem blendshapes): aí `FaceService.summary` não manda linha.
- **Modelos:** `setup.ps1` passo 6b baixa e confere o sha256; o serviço baixa sob demanda se faltar. Falha de modelo
não marca blocos: nova tentativa em 5 min. Modelo novo = entrada em `clipper/models.lock.json` com URL imutável +
sha256 + licença.
- **Dependências** (`clipper/requirements.txt`): `mediapipe`, `opencv-contrib-python`, `numpy`, `onnxruntime` —
versões em [tools.md](tools.md). Nunca instale `opencv-python-headless` junto (gotchas, item 80).
- **Rotas:** `GET /v1/sessions/{id}/face?from=&to=` (série, `signal`, picos, câmera, progresso) e
`POST …/face/reset`. Ambas na regex `ALLOWED` do painel.
- **Bancada** (lê o banco só para leitura, saída em `output/face-bench/`):
`clipper\.venv\Scripts\python.exe clipper\tools\face_bench.py --session 3`. Armadilhas: [gotchas.md](gotchas.md) itens 79–84 e 92–95.
- **Instância de teste isolada** (receita em "Variáveis" de `clipper/README.md`): `CLIPPER_PORT=4521`,
`CLIPPER_DATA_DIR=output/<teste>/data`, `CLIPPER_OUTPUT_DIR=output/<teste>/clips` no ambiente (padrões:
`data/clipper` e `output/clipper`; as duas precisam ficar **dentro** do repo, senão `ConfigError` em
`clipper/app/config.py`), juiz `off`, e o `sqlite_sequence` de `sessions` do banco novo em 90000 antes da 1ª sessão
(gotchas, item 93). Cuidados com cópia do banco real: item 77.
## Editor de cortes (`/clipper/edit/<id>`)
Fonte completa: seção "Editor de cortes" de `clipper/README.md` (campos do projeto, render, medições, limitações).
Pesquisa de referência (OpenCut, effectcraft, Descript, Submagic etc.; nenhum código copiado):
`doc/clip-editor-research.md`.
- **Um caminho só de render:** `Engine.render_clip` (`worker.py`) → `editor_api.ensure_edit` (gera o projeto da IA se
o corte não tem) → `editor_api.render_clip_edit` → `editor_render.render_project` (FFmpeg). Não reintroduza
render que contorne o projeto de edição.
- **Formato:** o projeto pode trocar o formato só daquele corte em `settings.format` (mesma validação de
`layout.validate`); projeto antigo sem `format` segue canal/sessão. Export, `preview-render` e capa saem no formato do
corte (1080×1920 ou 1920×1080). O Programa do painel segue o formato do corte (tamanhos de `frames`; em 16:9 no
horizontal).
- **Projeto da IA** (`editor.auto_project`): trecho `action_start_s − 0,8 s … reaction_end_s + 0,8 s`, encaixado em
palavras e depois em `fit_window` (≥ `minS` + 1 s, ≤ `maxS`; o início só adianta se o mínimo continuar); tira vãos
≥ 2 s sem fala, quietos (< −38 dBFS) e a mais de ±3 s do pico; legenda
Whisper preset `pop` (tempo saneado por `subtitles.py`); gancho por `pick_hook` (regra abaixo) no estilo do grupo
`hook`; zoom 1,25× no `peak_s` (no rosto em `cam_top`); capa no pico; `meta.origin = "ai"` com data, modelo e passos.
**A IA não propõe reenquadramento nem camadas inseridas** (o analista não devolve região da tela).
- **Gancho (`editor.pick_hook`):** o `hook` do analista só vale se tiver ≤ 8 palavras, ≤ 48 caracteres e nenhum tempo
da gravação (3+ dígitos seguidos de "s"); senão vale o título do editor. Em qualquer caso a menção ao tempo
("Aos 5085s, …") é removida, a 1ª letra vira maiúscula e o texto para em palavra inteira até 60 caracteres.
- **Origem:** `edits.ai_project_json` guarda o projeto da IA ("Projeto da IA" no editor volta a ele). PUT do editor
marca `origin = 'user'`. Rejudge (corte volta a `pending`) apaga **só** edit de origem `ai`; o do usuário fica.
- **Tempo:** `cuts`, palavras, textos, zoom, narração e capa em tempo da sessão; só o gancho em tempo de saída.
- **Validação forte** em `validate_project` (3–180 s, limites de quantidade, texto escapado no ASS, áudio só de
`assets/` ou dos TTS do editor, nada vira shell). Campo novo no projeto = validação com valor padrão (projeto
antigo continua abrindo) + teste em `clipper/tests/` + tipo em `clip-editor-model.ts`.
- `clip_view` devolve `edit: {updatedAt, exportedAt, cover, origin}` (o painel decide "Editar"/"Continuar edição").
Campos das camadas (tabela completa do projeto em "Tempo e modelo do projeto" do README):
| Campo | Regra |
|---|---|
| `cuts[].mode` | layout só daquele trecho: um de `MODES` ou `null` (= o do corte) |
| `cuts[].muted` | trecho sem o áudio da live (`volume=0` no trecho; narração e música continuam). `normalize_cuts` só junta trechos encostados com o mesmo `mode` **e** o mesmo `muted` |
| `overlays[].x` (gancho e texto) | posição horizontal 0,05–0,95; ausente = 0,5. `y` 0,04–0,96. No zoom, `x`/`y` (0–1) são o foco |
| `overlays[]` `hook`/`text`: `style`, `bg`, `color`, `font`, `anim` | opcionais. `style` `plain` (padrão) ou `banner` (tarja na largura toda, centrada em `y`, maiúsculas em até 2 linhas; a fonte diminui em vez de cortar palavra); `font` = uma de `fonts`; `anim` ganhou `slide`. Sem esses campos, renderiza idêntico ao de antes |
| `overlays[]` `kind: "inset"` | camada inserida: `start`/`end` (sessão), `src` `{x, y, w, h}` (recorte 0–1 do quadro original), `x`/`y` (centro na saída), `size` 0,1–1 da largura, `border` (`#RRGGBB`/null), `borderW` 0–40 (6), `radius` 0–200 (18), `shadow` (true), `anim` `pop`\|`fade`\|`slide`\|`none`, `keys` opcionais `[{t, x, y, size, ease}]`. Até 12. Ordem do array = empilhamento: acima do vídeo e do zoom, abaixo do ASS (legenda, gancho, textos, chat). **Não entra na capa** |
| `reframe` | `{keys: [{t, cx, cy, w, ease: smooth\|linear\|hold}]}`, até 60, `t` em tempo da sessão, `cx`/`cy`/`w` (0,05–1) absolutos no quadro original; a altura sai da área do jogo do layout do trecho (nunca distorce). Com keys, `layout.game` é ignorado; não vale em `cam_only`; no `blur`, `game_only` e horizontal ocupa a tela toda. A capa usa a janela parada do instante dela |
| `chat` | chat da live na tela: `enabled` (padrão `false`), `x` 0–0,9 (borda esquerda), `y` 0,1–0,98 (base do bloco), `width` 0,25–0,96, `lines` 1–10, `size` 18–64, `showUser`. `chat_events` redesenha o bloco a cada mensagem; ele some 9 s depois da última (`CHAT_HOLD_S`) |
| `cover.atStart` | a capa também cobre os 2 primeiros quadros do MP4 (0 s). Exige `cover.enabled`; `render_clip_edit` gera a capa antes do vídeo e a passa como `cover_file`. `preview-render` também põe a capa quando `fromS` = 0 |
**Editar com a mão** (arrastar e aparar palavra, deslizar e dividir trecho, mover texto/legenda/chat no monitor,
marcar a câmera só daquele corte): tabela "Mexer com a mão" do README; componentes e atalhos em
[panel.md](panel.md#editor-de-cortes).
Limites do editor (lista completa em "Limitações" do README):
- **Uma trilha de vídeo só, sem B-roll.** A timeline é o tempo da sessão: um pedaço não vai para outra camada nem
toca fora da ordem da gravação. Não prometa reordenar trechos.
- A prévia do Programa é um canvas; a exata é `preview-render` (no formato do corte). Legenda e recorte de câmera/jogo
já saem como no render: blocos por `cleanWords`/`groupWords`/`captionBlocks` (porte de `subtitles.py`, constantes em
`CAPTION_TIMING` de `clip-editor-model.ts`) e recorte por `ffmpegCropFill` (arredondamento par do FFmpeg, tamanho da
gravação de `session.capture`). **Mudou constante ou regra em `subtitles.py`, ou a cadeia `layout_chain`, mude o
porte junto.** Tarja a ~2 px do render (informado).
- Reenquadramento no 9:16 com câmera em cima: a área do jogo é 1080×1268 (proporção ~0,85), então um inventário 16:10
não cabe inteiro; a janela mostra no máximo 0,48 da largura. No 16:9 cabe.
- Custo medido (corte 61, 60 s, NVENC): sem nada 6,1–6,2 s; com reenquadramento 7,1–9,5 s; com reenquadramento +
2 camadas 15,8–20,5 s.
- Campo novo (`cam_only`, `muted`, `chat`, `cover.atStart`, texto com `x`, `style`/`font` do gancho, `reframe`, `inset`)
só vale no serviço reiniciado (gotchas, item 73).
Rotas (todas com `X-Service-Key`; todas na regex `ALLOWED`):
| Rota | Faz |
|---|---|
| `GET/PUT/DELETE /v1/clips/{id}/edit` | projeto; PUT manda `rev` e recebe 409 se outro salvou antes |
| `POST …/proxy` `{lo,hi}` · `GET …/waveform?lo=&hi=` | prévia 480p (`-g 15`) e forma de onda (50 picos/s) da janela |
| `POST …/preview-render` `{fromS, durationS ≤ 10, project?}` | prévia real de poucos segundos |
| `POST …/export` | volta para a fila de render → `ready` |
| `POST …/retranscribe` `{startS, endS}` (≤ 90 s) | Whisper de novo no trecho |
| `POST …/tts` `{text, voice, speed}` | narração pelo serviço de voz (4510) |
| `POST …/suggest` | IA (`Judge.ask`) sugere gancho, título, início/fim, trechos mortos e zooms |
Teste local do editor sem tocar no serviço do usuário: instância na faixa 4500–4599 (ex.: 4521) sobre **cópia** do
banco, com as regras do item 77 de [gotchas.md](gotchas.md). Teste de UI no painel do usuário sobre um corte real:
intercepte as escritas (item 86) e ache as camadas do canvas pelo cursor (item 85).
## Perfil do jogo (aba Jogos)
Toda rota abaixo devolve a lista inteira (mesma forma de `GET /v1/games`).
| Rota | Faz |
|---|---|
| `GET /v1/games` | perfis com `status`, `model`, `researchedAt`, `editedAt`, `notes` (`[{text, at, section?}]`) e `profile` |
| `POST /v1/games/{id}/research` | refaz o perfil do zero pela web (`RESEARCH_TIMEOUT_S` 420); os pedidos guardados entram no prompt |
| `PUT /v1/games/{id}` | grava o perfil editado à mão: `name`, `summary`, `genre`, `mechanics`, `clip_worthy`, `avoid`, `jargon`, `news`, `hashtags`, `sources` |
| `POST /v1/games/{id}/refine` | `{instruction, search, section, history}` → `{games, reply}`. `instruction` 3–1500 caracteres; `search` padrão `true` (`false` = sem web, `TIMEOUT_S` 240); `section` `""` \| `summary` \| `clip_worthy` \| `avoid` \| `mechanics` \| `news` \| `jargon` \| `hashtags` \| `sources` (`Literal` em `GameRefineIn` de `main.py`, inválido dá 422); `history` `[{role: "user"\|"ai", text ≤1500}]`, máx. 20. A IA devolve o perfil inteiro + `reply` (1–2 frases do que mudou); guarda o pedido (com `section`) e marca `edited_at` |
| `DELETE /v1/games/{id}/notes/{index}` | esquece um pedido guardado (o perfil atual fica como está) |
- `clean_profile` (`intel.py`) normaliza tudo que entra: apara, tira vazios e duplicados, no máximo 20 itens por lista.
São guardados os últimos 30 pedidos.
- **Pedido guardado sobrevive a "Pesquisar de novo"** (`research_game(name, title, notes)`; `PROFILE_SYSTEM` manda
priorizar os pedidos sobre a pesquisa). **Edição à mão não sobrevive.** Por isso o painel pede confirmação
quando há `editedAt`. Para algo durar, prefira o pedido à IA.
- Refino (`judge.py`): `refine_game(name, profile, instruction, search, section, history)` usa `REFINE_SCHEMA`
(= `PROFILE_SCHEMA` + `reply`) e `PROFILE_SECTIONS` (chave → título). A IA vê só os últimos 8 turnos do
`history`, 400 caracteres cada. `REFINE_SYSTEM` manda mexer só na seção em foco e transformar pedido genérico
em item concreto ("reação do streamer conta" → "Streamer grita, xinga ou ri alto logo depois de uma morte ou fuga").
`Intel.refine(...)` (`intel.py`) devolve `(profile, reply)`.
- Painel (`clipper-games.tsx`): o cabeçalho tem selo de iniciais e os botões "Conversar com a IA" (perfil inteiro),
"Editar" (uma linha por item) e "Pesquisar de novo". Cada seção é um cartão com "Pedir à IA", que abre o chat
daquela seção (`AiChat`: Enter envia, Shift+Enter quebra linha, chave "Confirmar na web" **desligada** por
padrão no painel, embora a API use `search=true` por padrão). Item recém-acrescentado aparece com selo "novo".
"Memória da IA" lista os pedidos guardados (com a seção) e tem X. A conversa só existe enquanto o chat está
aberto. O que fica salvo é o pedido. Tipo `Game` em `panel/src/components/clipper-client.ts`
(`editedAt?`, `notes?[].section?`). Detalhes visuais em [panel.md](panel.md).
## Regras
- **Aprovar publica** nas redes dos canais de publicação ligados à fonte (pelo despachante do painel; aprovar vale
para todas as redes). O painel marca o corte `published` quando todos os jobs dele saíram. Exportar no editor
volta o corte para `pending` e cancela os jobs ainda não enviados (voltam quando o corte fica pronto de novo).
Regras em [publishing.md](publishing.md). Corte aprovado **sem fonte ligada** (ou em outra rede) sai pelo botão
**"Publicar"** do cartão (`clip-publish.tsx`; em `published` vira "Publicar em outra rede"): ver publishing.md.
- **Direitos autorais.** Todo corte leva o crédito do canal. Marque `authorized` nos canais que autorizaram.
- Mudança de código em `clipper/app/` só entra no ar depois de reiniciar o serviço. O `scripts/dev.ts` sobe o
uvicorn sem `--reload` (gotchas, itens 53 e 73). O painel é do usuário, então peça a ele que reinicie — e só com a
suíte verde: reinício no meio de uma edição carrega código intermediário (gotchas, item 87). Agente que edita o
serviço trabalha numa cópia e aplica em `clipper/app/` por **edição pontual**, nunca sobrescrevendo o arquivo
inteiro: vários agentes e outras sessões mexem em `clipper/` ao mesmo tempo.
- Nada de rede (APIs de emotes, CLI) na thread do chat: use `EmoteCatalog.cached()` e baixe em thread à parte
(gotchas, item 72).
- Subprocesso sem shell. A CLI do Codex é chamada pelo `codex.js` (gotchas, item 28).
## Testes e evidência
Os testes não chamam a CLI de IA: `FakeJudge.ask` (`clipper/tests/test_sources_and_api.py`) sempre falha, e o serviço
segue pelo caminho de "IA fora". Juiz falso novo precisa cobrir `ask` também.
Hashtags da legenda (17/11/2026): `pnpm test:clipper` → **278 passed** (reexecutado nesta manutenção; bate com o
informado). Testes novos em `clipper/tests/test_hashtags.py`. O perfil do ROB RUN no banco ainda não tem `hashtags`
(informado; não conferido no banco).
Apagar cortes, veto do rejeitado, varredura contada e prévia igual ao render (17/11/2026):
- `pnpm test:clipper` → **270 passed** (medido na 1.29.1; o coordenador informou 269 — o disco já tinha outro teste
novo; na 1.29.0 eram 268). Testes novos: `test_clip_delete.py` (14); em `test_render_and_duplicates.py`, veto do
rejeitado, contagem da varredura e `test_queue_cleanup_uses_the_same_veto_as_the_judge` (limpeza da fila).
- `npx tsc --noEmit -p panel` → exit 0, sem erro (medido nesta manutenção; o lote informou erros de outra sessão em
`montage-editor.tsx`/`lib/montage*.ts`, já resolvidos quando rodei).
- Banco real `data/clipper/clipper.db` em `user_version` 10 (lido só para leitura nesta manutenção).
- Informado: diagnóstico "não sai corte" da sessão 3 (README, "Armadilhas já resolvidas"; gotchas, item 114);
legenda do painel em 22 conferências contra o Python; teste de ponta a ponta no corte 61 (projeto montado no editor,
capturado do PUT interceptado, render por `editor_render.render_project`) com enquadramento, inserção e legenda
iguais em 2/3,5/5/6,5/8 s; observador só leitura depois da retomada (01:30–01:46): corte 68 pronto e aprovado,
69 e 70 descartados, 71 pronto em 8 s.
Duração mínima, tarja do gancho, fontes, reenquadramento, camadas e qualidade de gravação (17/11/2026):
- `pnpm test:clipper` → **251 passed** (medido nesta manutenção; bate com o informado). Testes novos:
`test_duration_banner_fonts.py` (19), `test_reframe_insets.py` (10), `test_capture_quality.py` (17).
- `npx tsc --noEmit -p panel` → exit 0 (medido nesta manutenção; uma 1ª rodada deu erro em `confirm-dialog.tsx`,
de outro trabalho que ainda estava sendo escrito, e passou depois que ele terminou).
- Informado: medições de render, disco e nitidez acima e no README; prévia da tarja a ≤ ~2 px do render; interpolação
do painel × `reframe.py` em 41 conferências.
Formato horizontal, legenda com fala rápida, retomada, render que falha e duplicados (17/11/2026):
- `pnpm test:clipper` → **170 passed** e `npx tsc --noEmit -p panel` → exit 0, ambos medidos nesta manutenção (o lote
informou 169; o disco já tinha mudanças de outro lote em andamento). Testes novos: `test_format_and_captions.py`,
`test_resume.py`, `test_render_and_duplicates.py`; o vertical bate com o SHA de referência
(`tests/data/vertical_golden_sha256.json`).
- Informado: render horizontal real 1920×1080 conferido no ffprobe; legenda medida numa cópia do banco (3 projetos,
sessão 3 do skipnho): 63 de 286 eventos sobrepostos antes, 0 de 299 depois (README, "Tempo da legenda").
- Informado: capturas por CDP com as escritas interceptadas — modal "Configuração do corte" em 1920×1080 e 1366×768;
aba Sessões sem mudança de posição/altura entre atualizações automáticas.
Redesenho do editor e camadas novas (16/11/2026):
- `pnpm test:clipper` → 136 passed na época e `npx tsc --noEmit -p panel` → exit 0.
`clipper/tests/test_editor_layers.py` (6 testes): projeto antigo ganha os padrões, `cam_only` enche a tela,
`mode`/`muted` sobrevivem sem juntar, texto com `x` e bloco de chat no ASS, capa no início, e um render real pelo
FFmpeg com as camadas novas.
- Informado pelo coordenador, Chrome sem janela por CDP em `/clipper/edit/25` do painel, com as escritas
interceptadas (nada gravado): palavra aparada pela direita 34→21 px e pela esquerda 21→12 px com a outra borda
parada; mover −6 px com a largura igual; clique simples não move; Ctrl+Shift+clique divide (1→2 trechos) e Ctrl+Z
desfaz; marcar a câmera mudou a área de "21% × 24% em 2%, 43%" para "25% × 35% em 5%, 45%"; câmera inteira e chat
na tela aparecem na prévia.
Rastreio de reação (16–17/11/2026):
- `cd clipper; .venv\Scripts\python -m pytest` → 120 passed na época (2 execuções seguidas);
`npx tsc --noEmit -p panel` limpo (informado). Versões instaladas no `clipper/.venv` conferidas (ver tools.md);
os 4 pesos já estão em `data/clipper/models/`.
- `doc/FACE_BAKEOFF.md` (cópia do banco, sessão 3 do skipnho): MediaPipe achou rosto em 97,8–100 % dos quadros dos 6
trechos, 5–7 ms/quadro; bloco de 30 s em 1,47 s de média (p95 2,05 s); 144/144 blocos `done`, rosto em 85,1 % dos quadros;
após calibração 114 picos, 0 no trecho calmo, 0 cortes novos de fonte `face`, 14 dos 21 momentos do chat com
`reasons.face`. **O rosto não separou aprovados de descartados** nos cortes 10–13 — por isso é só reforço.
Rastreio de reação ao vivo (16–17/11/2026; seção "Testes de 17/11 — ao vivo" de `doc/FACE_BAKEOFF.md`):
- `cd clipper; .venv\Scripts\python -m pytest` → 170 passed e `npx tsc --noEmit -p panel` → exit 0 (conferidos
nesta manutenção).
- Download real dos 4 modelos para pasta vazia (0,28–0,91 s cada), sha256 conferido, nenhum `.part`; sha256 errado e
URL 404 → `FaceUnavailable` com `.part` apagado; arquivo corrompido → baixado de novo.
- Plano B OpenSeeFace com pesos reais × MediaPipe (sessão 3, blocos 54/66/80): rosto 96,7–100 % × 94,4–100 %;
12,3–13,9 × 9,8–13,2 ms/quadro (FFmpeg + modelo ÷ 180); `size` do OSF ~18 % menor; OSF dá sinal 0 (sem picos, sem erro).
- Serviço real, instância 4521, twitch.tv/skipnho (sessão 90001, 722 s, 25 blocos, juiz `off`): câmera `yunet` em
12/12 quadros, confiança 0,864; 25/25 `done`, atraso de 0–1 bloco; 1,71 s/bloco (p95 2,20 s) com gravação +
transcrição + chat juntos; fim do bloco → rosto gravado 1,4–9,4 s; CPU média 16,8 % de um núcleo, pico 90 % na
reconstrução após reset; rosto em 99,8 % dos segundos; `GET …/face` 200; `POST …/face/reset` 200 (ocioso) / 202
(bloco em andamento), refez 19 blocos em ~45 s; 2 cortes do chat, um com `reasons.face` grito z 12,7 (o outro,
decidido durante a reconstrução, sem rosto, como desenhado). Queda do `start.bat` no meio → sessão retomada sozinha.
- twitch.tv/lofigirl (sem câmera, sessão 90002): falso positivo achado e corrigido (gotchas, item 92); refeito →
`hasWebcam: false`, 8 blocos `no_cam`.
- Painel em 127.0.0.1:4500/clipper sem erro de console; selo, interruptor e chip de reação vistos só com respostas GET
alteradas no navegador (o serviço do usuário rodava o código antigo).
Editor de cortes, 1ª versão (16/11/2026):
- `pnpm test:clipper` → 120 passed na época.
- Informado pelo coordenador, instância de teste em 127.0.0.1:4521 sobre cópia do banco (sessão 3 do skipnho, já
derrubada e cópia apagada): tempos na tabela "Medido" do README; export do corte 9 editado (início −20 s, 2 trechos
removidos, legenda `pop` com palavra trocada e ênfase, gancho com caixa, zoom 1,5×, barra) = 55,6 s H.264
1080×1920 30 fps + AAC em ~9 s; corte 10 rejulgado pela IA real → projeto da IA → MP4 33,8 s em 24 s; quadros
inspecionados; editor em tela cheia no Chrome sem janela sem rolagem nem erro de console; `pnpm typecheck` e
`npx tsc --noEmit -p panel` limpos.
Chat por seção do perfil (16/11/2026, informado pelo coordenador, IA simulada em banco temporário): `refine`
com `section=clip_worthy` acrescentou o item, devolveu `reply`, recebeu 2 turnos de histórico e salvou a nota com
`section`; seção inválida recusada pelo pydantic; `tsc --noEmit` do painel limpo; `import app.main` ok; captura
de `localhost:4500/clipper?tab=jogos` com o chat aberto em "O que rende corte". **IA real não testada** (serviço
não reiniciado).
Perfil editável do jogo (informado pelo coordenador, banco temporário): migração até `user_version` 7,
`save_profile` deduplicou lista, `refine` guardou o pedido e marcou `edited_at`, a pesquisa recebeu as notas,
`delete_note` limpou; `tsc --noEmit` do painel limpo; `import app.main` ok. O serviço no ar precisa ser reiniciado
para migrar (o banco real estava em v4).
Fase 2 (17/11/2026):
- `pnpm test:clipper` → 46 passed (sem rede, juiz falso); `pnpm typecheck` e `npx tsc --noEmit -p panel` limpos.
Conferido nesta manutenção.
- Informado pelo coordenador, numa cópia do banco da live do skipnho (chat de ~0,15 msg/s):
- jogo ROB RUN pela categoria e perfil pesquisado (~15–35 s por jogo);
- webcam achada no canto inferior esquerdo (~5 s); render `cam_top` de 59 s inspecionado;
- varredura de 2 janelas sem falso positivo (~7 s por janela com `gpt-6-luna`);
- corte do lag: título "O lag jogou ele em três lugares ao mesmo tempo", `lag_ou_bug`, confiança 0,93, início
recuado 35 s, ~18 s nos dois juízes.
Fase 1 (16/11/2026, `twitch.tv/alanzoka`, sessão 2): 21 blocos (617,97 s), 490 mensagens, 4 cortes do chat aprovados
pelo `codex:gpt-6-luna` (notas 7,4–8,5) e 1 manual (nota 3,0) renderizado; `clip-4.mp4` H.264 1080×1920 + AAC.
Não verificado:
- hashtags: juiz e pesquisa de jogo com a CLI real (o campo `hashtags` do veredito e do perfil); UI da seção "Hashtags"
contra o serviço reiniciado;
- apagar: rota no serviço real do usuário; arquivo em uso no Windows (deve voltar em `left`); pedido do editor em
andamento gravando em `edit-<id>/` depois de apagar; relógio da sessão com movimento reduzido, aba escondida e
larguras de 1024/1280; a faixa do topo em `clipper-studio.tsx` ainda mostra o `durationS` real (sem o relógio);
- duração, gancho, reenquadramento, camadas e captura: live 2K real e HEVC real da Twitch pela captura; gravação longa
em 1080p ou 2K com o serviço real; juiz e varredura reais com as durações novas; render real de um projeto feito no
editor com reenquadramento e camadas comparado com a prévia (pendente, depois do reinício do serviço); camadas na
capa (não entram por desenho);
- formato e retomada: juízes, varredura e "IA sugere" com a CLI real depois da mudança de prompts; retomada automática
contra live real; horizontal com NVENC e com fonte que não é 16:9; corte horizontal de ponta a ponta numa live;
gravação real do `format` pelo modal (as escritas foram interceptadas);
- editor: música e efeitos com arquivo real (não há áudio em `assets/`; só o filtergraph em teste unitário);
arrastes com mouse humano (só por CDP, e nem todos: deslizar o corpo do clipe, arrastar texto/zoom/narração na
timeline, mover texto/gancho/legenda/chat no Programa, "Editar"/"Ocultar" da transcrição, "Salvar projeto" e
minimizar painéis não têm medição registrada); export real pelo serviço do usuário (4520) de um projeto com
`cam_only`, `muted`, `chat` ou `cover.atStart` — as escritas do teste de UI foram interceptadas, e o serviço
precisa ser reiniciado para o código novo e a migração v7 (gotchas, item 73);
- rastreio de reação: câmera em tela cheia, escura ou minúscula; GPU; live > 15 min (`LIVE_WINDOW_S` 900 s não foi
ultrapassada); a linha "Rosto do streamer" chegando ao juiz analista ao vivo (juiz `off` no teste); interação real
com o interruptor `faceTrack` contra o serviço novo (só com respostas simuladas no navegador); câmera que muda de
lugar no meio da live. O serviço do usuário só pega a correção do `min_cam_score` depois de reiniciar o `start.bat`;
- editar/refinar perfil pela UI contra o serviço reiniciado; `refine` com IA real (com e sem `search`);
- a UI nova (modal do corte, aba Jogos e emotes) contra o serviço novo no ar — o serviço do usuário ainda roda o
código antigo;
- juiz com a CLI do Claude (analista, editor, varredura, câmera e pesquisa);
- chat da Kick e lives do YouTube ponta a ponta; VOD; render com NVENC.
@@ -0,0 +1,701 @@
# Armadilhas conhecidas
Cada item: **sintoma → causa → correção → onde está tratado**. Observadas na implementação da
prova de conceito com Godot 4.7.2 / FFmpeg 7.1.1 / pnpm 11.22 (16/11/2026). Registro formal em
`doc/TEST_RESULT.md`: itens 1–5, 7, 13–15, 17 e 18; itens 30–33 estão em `voice/README.md`
("GPU e CPU"); itens 57–61 estão em `clipper/README.md` ("Armadilhas já resolvidas"); itens 74–76, 87–90 e 103–108 também estão lá e o 78 na seção "Limitações" do editor; itens 79, 81–84 e 92–95 estão em `doc/FACE_BAKEOFF.md` (o 93 também em "Variáveis" de `clipper/README.md`) (o 80, no comentário de `clipper/requirements.txt`); itens 118–128 (publicação) seguem `doc/publicacao/` e o código; itens 129–132 foram informados em 17/11/2026 e conferidos no código (`doc_main.gd`, `doc/godot/cenas.md`) e no banco (`agent_runs` 5, 7 e 8); itens 62–67, 77, 85–86, 91, 99–102, 109–112 e as ampliações do 52, do 44, 77, 86 e 87 foram informados em 16–17/11/2026 (não estão em `doc/TEST_RESULT.md`); os demais vieram de erros de compilação ou instalação durante a implementação.
Ao descobrir uma nova, registre aqui via `cenaforge-skill-updater`. Os números são estáveis
(outros textos os citam): item novo entra na seção do assunto com o próximo número livre.
## Render (Godot Movie Maker)
1. **Primeiro quadro diferente** (azulado, sombra diagonal errada).
Causa: sombras e radiância do céu ainda não prontas no 1º quadro.
Correção: 3 quadros de aquecimento em t = 0, descartados com `-start_number 3`.
Onde: `--warmup-frames` em `main.gd`; `render.ts` passa `-start_number`.
2. **`delta` não é 1/fps** mesmo com `--fixed-fps` (0,025; 0,0333; 0,0417…).
Correção: tempo da cena = contador de quadros / fps. Nunca use `delta` em render.
Onde: `_process_render` em `main.gd`.
3. **Resolução do filme travada na inicialização.** `--resolution` e `content_scale_size` em
runtime não mudam o arquivo; janela de 1080×1920 não cabe numa tela de 1080 px.
Correção: `godot/override.cfg` temporário com o viewport do perfil e janela menor
(stretch `viewport`, aspect `keep`). A cena aborta (código 3) se o viewport ≠ config.
Onde: `render.ts` escreve/remove o arquivo; checagem em `main.gd`.
Consequência: render manual sem o lançador só sai em 540×960.
4. **`--write-movie` relativo grava em `godot/`, e falha em silêncio.** Com a pasta
inexistente, nenhum PNG é gravado e a Godot sai com código 0 dizendo "Done recording".
Correção: caminho absoluto; o lançador confere os PNGs; `main.gd` aborta se a pasta não existe.
Lição: log de sucesso não prova nada — confira arquivos.
5. **Quantidade de quadros.** Chamar `quit()` no `_process` do último quadro ainda grava esse
quadro: total de PNGs = aquecimento + fps × duração, índices contínuos a partir de 0,
padrão `frame%08d.png`, mais `frame.wav` (silencioso, descartado).
6. **Modo `--headless` não renderiza 3D válido.** Use só para validação, testes e preparação
de assets. O render abre uma janela e precisa de backend gráfico.
7. **Custo do render é a codificação PNG** (~105 ms/quadro em 540×960, ~404 ms em 1080×1920),
não a GPU. Não prometa tempo sem medir.
110. **Cena do documentário (`doc2d`/`doc3d`) reprovada como "quadro preto" ou "moto não termina no ponto".** Causa: as
checagens do lançador eram da rua — o fundo escuro do documentário (#0d0d10) tem luma ≈ 13, abaixo do piso 20
(`MIN_AVERAGE_LUMA`), e não há moto. Correção: com `kind` `doc2d` ou `doc3d`, `render.ts` pula a checagem da moto e usa
`MIN_AVERAGE_LUMA_DOC2D` = 4. Fundo novo mais escuro que isso → ajuste o piso, não desligue a checagem.
129. **Render de cena `doc3d` não termina e enche a pasta de PNGs** (17/11/2026: 39 mil quadros, "apply em Nil" em laço).
Causa: `template.gd` com erro de compilação; o protocolo seguia sem a cena. Correção: `doc_main.gd` carrega o script
na validação e, se `can_instantiate()` falha, sai com `SCENE_SCRIPT_INVALID` (código 2, `EXIT_INVALID_CONFIG`); os
`Parse Error` com a linha ficam no `render.log` do run. No render, cena sem `setup`/`apply` também sai com
`SCENE_SCRIPT_INVALID`. Se um render antigo travar assim: encerre a Godot **e** o lançador e apague
`output/.render.lock`. Erros de GDScript mais comuns: itens 9 e 130.
## GDScript (Godot 4.7) e TypeScript do lançador
8. **`class_name` depende do cache do editor.** O projeto roda sem importação prévia; use
`const X := preload(...)`.
9. **`var x := dicionario.campo + 1.0`** não compila (tipo não inferível a partir de Variant). Idem
`var x := dict.get("k")`, `var p := nodes[i]` e retorno de método de kit chamado por variável tipada como `Node3D`.
Declare o tipo (`var x: float = ...`) ou use `=`.
10. **Comparar valor não-objeto com `null`**: prefira `typeof(v) == TYPE_NIL`.
11. **`quit()` é adiado para o fim do quadro**: depois de chamar, marque um sinalizador
(`_halted`) para o `_process` seguinte não rodar com estado incompleto.
12. **Dentro de comentário de bloco TypeScript, `*/`** (ex.: `godot-*/`) encerra o comentário.
130. **"shadows a native class"**: constante com nome de classe do Godot (`const Sky := preload(...)`, `Camera3D`,
`Environment`) não compila. Use outro nome (`SkyRig` em `godot/library/castaways/template.gd`). Guia: "Testar" em
`doc/godot/cenas.md`.
## Composição visual
13. Título longo quebra linha: o rótulo cresce para cima (alinhado embaixo) para não invadir as
opções. Reserve ~18% inferior livre para a interface da plataforma.
14. No fim do plano, câmera baixa (~1,1 m) com leve inclinação para baixo põe o entregador na
metade superior e mantém o horizonte; câmera alta deixa o texto cobrindo o personagem.
15. Borda do plano do morro vira linha reta no céu: a cumeeira de volumes irregulares resolve.
16. Câmera lateral perto dos postes (x = meia pista + 0,5 m): mantenha ≥ 1 m de folga no offset.
17. Rodas: a ~4 m/s giram ~26°/quadro; acima de 30°/quadro a simetria de 60° dos raios pode
causar efeito estroboscópico.
111. **Espuma do mar desenhada por elipse não acompanha a costa** (anel regular em volta de uma ilha irregular).
Causa: a elipse no shader do mar ignora o contorno real do terreno. Correção: removida; a cor turquesa perto da
costa já marca a transição. Espuma futura precisa seguir a altura do terreno, não uma forma fixa. Onde:
`_build_ocean` em `godot/library/island/template.gd`.
## Ferramentas
18. **`pnpm doctor`** é comando nativo do pnpm 11 → use `pnpm run doctor`.
19. **pnpm 11 bloqueia scripts de instalação** não aprovados (erro `ERR_PNPM_IGNORED_BUILDS`).
O `esbuild` está recusado em `pnpm-workspace.yaml` (`allowBuilds: esbuild: false`) e funciona assim.
20. **pnpm repassa o `--`** para o script; o parser do lançador ignora um `--` solto.
21. Executável principal da Godot (não o `_console.exe`) escreve stdout em pipe normalmente;
use-o para poder encerrar a árvore com `taskkill /T`.
44. **Heredoc ou `node -e "..."` no Bash do agente quebra com barra invertida e aspas** (`\\` vira `\`; escapes como
`\b` de regex se perdem; às vezes o script inteiro falha). Em 17/11/2026 um `node -e` com regex quebrou o build do
painel duas vezes. Texto com barra invertida (caminhos Windows, `package.json`, regex) ou
script com aspas aninhadas: edite com Edit/Write, ou grave o script num arquivo (scratchpad) com
Write e execute o arquivo, nunca inline.
## Painel
22. **Portas:** o CenaForge usa a faixa **4500–4599** (painel = 4500). A 3100 já é de outro
aplicativo nesta máquina. `EADDRINUSE` = porta ocupada: escolha outra da faixa, nunca
encerre o processo alheio.
23. **Node não executa `.cmd`/`.bat` sem shell** (ex.: `pnpm.cmd`). O painel chama o lançador
como `node node_modules/tsx/dist/cli.mjs scripts/cli.ts render …` e procura só `.exe`.
24. **Next.js 16.4** vem com `cacheComponents` ligado; o painel desliga (dados sempre dinâmicos)
e chama `connection()` antes de ler o SQLite. `params` de página/rota é `Promise`.
25. **Script `.ts` dentro de `panel/`** roda como CommonJS (sem `"type": "module"`): para
`await` no topo, use `.mts`.
26. **`claude -p` reclama de stdin** se a entrada não for fechada: o painel usa `stdio: ["ignore", …]`.
27. **Codex fora de repositório Git** recusa rodar sem `--skip-git-repo-check`. `codex exec resume`
não aceita `--sandbox` nem `-C`: use `-c sandbox_mode="workspace-write"` e o cwd do processo.
28. **Shims do npm no Windows** (`codex`, `codex.cmd`, `codex.ps1`): o sem extensão é script de
shell e o `.cmd` exige shell. O painel (`agents.ts`) e o juiz do Clipador (`clipper/app/judge.py`)
executam `node <pacote>/bin/codex.js`.
29. **Ruído das CLIs no stderr.** Codex: configuração pessoal do usuário (`~/.codex/config.toml`,
servidor MCP fora do ar) e "Codex is ignoring N unrecognized configuration setting"; Claude Code:
`[claude-code:unrecognized_model]` para id fora da lista interna dele (ex.: `claude-fable-5-2`), mas
o modelo roda normalmente. O painel filtra esses padrões (`STDERR_NOISE` em `panel/src/lib/agents.ts`);
os avisos de configuração do Codex chegam como item `error`, exibidos como nota.
42. **Ícone some no menu recolhido:** SVG dentro de flex encolhe a 0 px ao lado de texto
`nowrap`. Correção: `shrink-0` nos ícones (`panel/src/components/icons.tsx`).
43. **Grade na barra lateral cresce até a largura do texto.** Correção: `flex-col` + `min-w-0`
(`panel/src/components/sidebar-nav.tsx`).
48. **Nó do `@xyflow/react` 13 não responde a clique** sem `onNodeClick` no canvas.
Correção: o clique sobe até o nó e é tratado no `onNodeClick` (`components/story-flow.tsx`).
49. **Foco dentro do canvas rola o contêiner** e desalinha a árvore. Correção: `onScrollCapture`
desfaz a rolagem e `setCenter` traz o nó focado para a vista (`story-flow.tsx`).
50. **Grade sem `grid-cols-1` estoura no celular** (colunas implícitas crescem até o conteúdo).
Correção: declarar `grid-cols-1` na base e as colunas extras só nos breakpoints.
51. **Mudança de esquema não aparece no painel em dev** (ex.: v4 → criar história documental falha no
CHECK de `stories.kind`). Causa: a conexão do SQLite fica em `globalThis.__cenaforgeDb`
(`panel/src/lib/db.ts`) e a migração só rodava ao abrir o banco. Hoje a marca `checkedThisModule` faz a 1ª
chamada de `db()` depois da recarga do código migrar o banco aberto (item 138); se o `db.ts` não foi recarregado,
faça uma requisição ao painel ou peça ao usuário que reinicie o `pnpm panel` (é dele: não reinicie você). Conferir:
`PRAGMA user_version` do `data/cenaforge.db` = `MIGRATIONS.length`.
52. **`tsx` com `await` no topo** exige arquivo `.mts`, e o import de módulo local precisa de URL
`file:///` (caminho Windows cru com `C:\` ou `f:/` não é URL e falha no loader ESM). Node puro não resolve
import `.ts` sem extensão: rode pelo tsx da raiz, `node node_modules/tsx/dist/cli.mjs <script>.mts`, com
imports `file:///<raiz-do-repo>/panel/src/lib/<módulo>.ts`. Complementa o item 25.
62. **Classe de largura não pega em `Select`/`Input`** do `panel/src/components/ui.tsx`.
Causa: a classe base tem `w-full` fixo e `cx()` só concatena (não faz merge de Tailwind como o
`tailwind-merge`); `w-48` passado junto perde para o `w-full`. Correção: controlar a largura com
um `<div>` em volta (ex.: barra de filtros de `voice-cards.tsx`).
63. **Patch por string falha nos `.tsx` do painel**: os arquivos são CRLF. Correção: normalizar o
fim de linha antes de procurar o trecho (ou usar a ferramenta Edit) e gravar de volta em CRLF.
96. **Codex aplica as restrições de ficção a um pedido documental.** Causa: o Codex lia
`.claude/agents/cenaforge-story-writer.md` como instrução, mas é um subagente do Claude. Correção: as
regras saíram do subagente para `doc/roteiro/` (`comum.md` + `ficcao.md`/`documental.md`); o prompt
(`writingRules(provider, kind)` em `panel/src/lib/prompts.ts`) manda o Codex ler só o guia do formato e
escrever sozinho, e o `AGENTS.md` da raiz tem a mesma regra. Regra nova de texto vai para os .md, não
para o subagente nem para o código.
97. **Codex retomado depois de interrompido esquece o pedido original.** Medido com o Codex 0.169 (`exec` +
`taskkill /T /F` + `exec resume <thread>`): matando logo no `thread.started`, a sessão retomada não tinha o
pedido (respondeu "Nenhuma"); matando depois de um `agent_message`, lembrou (respondeu "BANANA"). O 1º
`item.completed` pode ser um item `error` de MCP pessoal, que não conta como progresso. Correção:
"Corrigir agora" (`sendFollowUp` em `panel/src/lib/agents.ts`) exige `session_id` e `progressed` (algum
evento que não seja `system`, `stderr` nem `error`); antes disso, recusa e sugere "Enviar ao terminar".
98. **Acentos quebrados no Codex** ("história" no console). Causa: o Windows PowerShell 5.1 lê arquivo UTF-8
sem BOM como ANSI. Correção: o prompt do Codex (`panel/src/lib/prompts.ts`) manda ler texto com
`Get-Content -Raw -Encoding UTF8`. Mesma raiz do item 36 (script `.ps1` precisa de BOM).
99. **Script de teste marca como `interrupted` o que o painel está rodando.** Causa: importar `lib/db.ts` (direto
ou por outro módulo do painel) abre o banco, e a abertura roda `UPDATE renders/agent_runs SET status =
'interrupted' WHERE status = 'running'`. Correção: script fora do painel não importa nada que toque o banco;
por isso o FFmpeg da montagem documental fica em `panel/src/lib/montage-ffmpeg.ts`, sem banco.
100. **Parâmetro extra some da URL de arquivo.** Causa: `fileUrl()` (`panel/src/components/ui.tsx`) já devolve
`/api/files?path=...`. Correção: anexar com `&v=...` (ex.: quebra de cache do áudio em `montage-editor.tsx`).
101. **Asterisco no vídeo documental** (`*Bothrops insularis*`). Causa: o "texto na tela" do roteiro vem com
markdown. Correção: `loadMontage` (`panel/src/lib/montage.ts`) tira `**`, `__`, `*`, `_`, crase e aspas externas.
102. **Trecho do MP4 mais longo que a tabela do roteiro** (trecho 1: roteiro 0–2 s, fala 4,08 s). Não é erro: a
montagem segue a duração real de cada fala (+ pausa), não a coluna "t (s)". Para encurtar, corte o texto falado.
112. **Primeira montagem logo depois de editar `panel/src/lib/` sai com o comportamento antigo** (17/11/2026: a 1ª saiu
sem o fundo desfocado da foto; a 2ª, certa). Causa provável (não isolada): o Next dev ainda executa o módulo antigo
logo após a edição. Correção: confira os quadros da primeira saída depois de mexer no servidor; se vier com o
comportamento antigo, gere de novo antes de concluir.
109. **Ctrl+Z do editor de cortes não desfaz slider, arraste nem setas** (só em dev). Causa: o React em modo estrito roda
o updater do `setState` duas vezes; a chave/hora de agrupamento ficava num ref alterado dentro do updater, e a 2ª
execução "agrupava consigo mesma". Correção: o updater é **puro** — chave e hora moram no próprio estado. Regra
para todo `setState((s) => …)` do painel: nada de ref, relógio ou efeito lá dentro (leia `Date.now()` antes). Onde:
`useHistory` em `panel/src/components/clip-editor-model.ts`.
131. **Agente do painel morre ao reiniciar o `pnpm panel`** (execução #5, cena do estádio, ficou `interrupted`). Causa: o
agente é processo filho do painel, e a abertura do banco marca `running` como `interrupted` (item 99). Correção: não
reinicie o painel com agente rodando; se precisar (ex.: migração, item 51), espere terminar. O painel é do usuário.
132. **Agente para no meio por limite de uso** (17/11/2026: Claude na #7, "You've hit your 5-hour limit", e Codex na #8,
"You've hit your usage limit"; as duas ficaram `error`). A mensagem aparece no console (`data/logs/agents/<id>.jsonl`);
na #7 a coluna `agent_runs.error` ficou só "success". Correção: abra nova execução no **outro provedor** com o
contexto de onde parou (arquivos já feitos, o que falta); a #8 (Codex) continuou a cena `castaways` da #7 (Claude).
133. **Claude do painel falha com "Failed to authenticate: OAuth session expired".** Causa: o painel lança o `claude` sem
`CLAUDE_CONFIG_DIR`, ou seja com `~/.claude`, e o OAuth dessa config estava expirado (17/11/2026), mesmo com outra
conta ativa no terminal. Correção: rode `claude` e `/login` nessa config, ou suba o `pnpm panel` com
`CLAUDE_CONFIG_DIR` da conta ativa (o painel é do usuário, item 131). Onde: `panel/src/lib/agents.ts`.
134. **Execução do agente custa milhões de tokens / dura dezenas de minutos.** Causas medidas: (a) Codex abrindo ~100
imagens em resolução cheia (#8: 6,83 milhões de tokens de entrada, 29 min); (b) página web inteira na pesquisa
(#6: 1,06 milhão); (c) custo fixo de plugins/MCP/skills do usuário carregados pela CLI (#7: ~49 mil por chamada);
(d) retomar conversa longa. Correção: `frame_check.py` + uma imagem por render, pesquisa curta, flags enxutas
do painel, nova execução em vez de resume. Detalhes em [token-economy.md](token-economy.md).
135. **`-c mcp_servers={}` não desliga os MCPs do Codex, e `collaboration` (`spawn_agent` etc., ~5,4 mil caracteres) não
sai por `-c features.*`.** Causa: o Codex mescla tabelas do `-c` com o `config.toml`. Correção: um
`-c mcp_servers.<nome>.enabled=false` por servidor (lidos do `config.toml`) e `plugins."<id>".enabled=false` para
computer-use. A `collaboration` fica; é parte do fixo. Onde: `codexLeanOverrides` em `panel/src/lib/agents.ts`.
## Serviço de voz (`voice/`)
Medidas em 16/11/2026, RTX 2060 SUPER 8 GB, Windows 11.
30. **Whisper na GPU só falha na 1ª inferência** com `RuntimeError: Library cublas64_12.dll is
not found`: o `ctranslate2` enxerga a GPU mesmo sem cuBLAS/cuDNN.
Correção: aquecimento real na subida (`FasterWhisperEngine.warmup()`, 1 s de tom **sem VAD** —
com VAD o silêncio não chega ao modelo e a falha passa) e queda para CPU `int8` com aviso no log.
Onde: `voice/app/stt.py` (`warmup`), `voice/app/main.py`; DLLs em `voice/requirements-cuda.txt`.
31. **GPU disputada por jogo** (98% de uso, 7,4/8 GB): 6,5 s de fala levaram 41–124 s na GPU
contra 2,7 s na CPU; noutra medição (99%, 7,2 GB) a legenda de 6,5 s ficou > 8 min presa na GPU.
Correção: `VOICE_DEVICE=auto` consulta o `nvidia-smi` na subida e usa CPU com < 2048 MiB livres
ou ≥ 85% de uso (log: `GPU ocupada por outro programa (99% de uso, 1593 MiB livres)`); depois
do reinício a mesma legenda pelo painel levou 2,5 s (14 palavras + `.srt`). Só vale na subida:
jogo aberto depois → reinicie o serviço ou use `VOICE_DEVICE=cpu`. Onde: `voice/app/device.py`.
32. **Edge TTS 403** (`WSServerHandshakeError` de `speech.platform.bing.com`) desde out/2026 com
`edge-tts` 7.2.8. Correção: `edge-tts==7.3.1` em `voice/requirements.txt`, sem patch.
33. **sha256 do Piper divergente:** o lock apontava para `resolve/main` e o arquivo mudou no
Hugging Face. Correção: URL fixada no commit `e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c` em
`voice/models.lock.json`. Regra: todo peso novo com URL imutável (commit no HF ou release
versionado no GitHub) e sha256.
34. **LRU do cache empatava no Windows** (`time.time_ns()` anda em passos de ~1 ms).
Correção: `Store._tick()` estritamente crescente em `voice/app/store.py`.
35. **Caminho Windows em script do `package.json`:** o `cmd` não aceita `voice/.venv/...` como
executável; use barra invertida, escrita `\\` no JSON (ver `test:voice`:
`cd voice && .venv\\Scripts\\python -m pytest`).
36. **`scripts/setup.ps1` precisa ser UTF-8 com BOM**: o PowerShell 5.1 lê sem BOM como ANSI e
estraga os acentos. Mantenha o BOM ao editar.
37. **GPU detectada como "sem GPU"** (RTX 2060 SUPER → torch `+cpu`).
Causa: `nvidia-smi ... | Select-Object -First 1` corta o pipeline, o PowerShell mata o
processo e `$LASTEXITCODE` ≠ 0.
Correção: capturar a saída inteira com `@(nvidia-smi ...)` e usar `[0]`. Onde: `scripts/setup.ps1`.
38. **`uv pip install torch==2.11.0` aceita a variante errada já instalada** (`2.11.0+cpu`
satisfaz). Correção: pedir `torch==2.11.0+cu128` (ou `+cpu`) explicitamente. Evidência: na
2ª rodada o uv trocou `- torch==2.11.0+cpu` por `+ torch==2.11.0+cu128`. Onde: `scripts/setup.ps1`.
39. **stderr do uv vira `NativeCommandError`** com `$ErrorActionPreference = "Stop"` no
PowerShell 5.1. Correção: `"Continue"` e conferir `$LASTEXITCODE` em `Run()`. Onde:
`scripts/setup.ps1`.
40. **Serviço órfão segurando a 4510** (`WinError 10048`) após reinício pelo `voice/.env`.
Causa: o `exit` do processo antigo chega depois de o novo subir; um sinalizador global
`restarting` fazia o lançador sair no `--voice-only` e largar o novo processo.
Correção: `WeakSet` dos processos substituídos + `process.on("exit", stopAll)`; checagem de
porta livre antes de subir. Onde: `scripts/dev.ts`.
41. **`.pth` que não é RVC** derruba o Applio com `KeyError: 'config'`.
Correção: vira `422 rvc_failed` com mensagem clara. Onde: `voice/app/rvc.py`, `voice/app/errors.py`.
45. **Edge TTS `NoAudioReceived` intermitente** (visto com `en-US-AndrewMultilingualNeural`, 1ª
tentativa). O serviço não repete: vira `502 engine_unavailable` (`EdgeEngine` em
`voice/app/engine.py`). Correção: repetir a requisição (a 2ª deu certo).
46. **Acentos estragados ao testar o Piper na linha de comando no Windows**
(`echo ... | python -m piper`: "até" vira lixo). Causa: stdin/stdout fora de UTF-8. Correção:
`PYTHONUTF8=1` ou `PYTHONIOENCODING=utf-8` no teste manual. O serviço não é afetado.
47. **`faster_whisper.decode_audio(caminho)` falha** com o PyAV do `voice/.venv`
(`open() got an unexpected keyword argument 'metadata_errors'`). Só em teste avulso: decodifique
com ffmpeg para PCM 16 kHz mono e passe o array numpy. O serviço não é afetado: decodifica os
bytes com o próprio `voice/app/decode.py` (`av.open` em memória).
53. **Mudança de código em `voice/app/` não entra no ar** com `pnpm dev`/`pnpm voice`.
Causa: `scripts/dev.ts` sobe o uvicorn sem `--reload`; só reinicia sozinho quando
`voice/.env` muda. Correção: reiniciar o serviço (o painel é do usuário: peça). Mudança de
catálogo (`catalog.json`, `models.lock.json`, `user-voices.json`) não precisa: é relida na
próxima consulta de vozes ou síntese.
Exceção: voz de **motor novo** (ex.: `kokoro`, `google`, `azure`, `clone` em 16/11/2026) com o serviço ainda no
código antigo → a recarga falha (`motor desconhecido`), as vozes atuais ficam e o log avisa;
só aparece depois de reiniciar (`start.bat` / `pnpm dev`). O worker de clonagem também só
reinicia sozinho quando `voice/.env` muda.
54. **`kokoro-v1.0.int8.onnx` não roda no onnxruntime 1.31.0** (`NOT_IMPLEMENTED` em
`ConvInteger(10)`). Correção: usar `kokoro/kokoro-v1.0.fp16.onnx` (é o que está no
`voice/models.lock.json`).
55. **Kokoro fp16 inunda o log com centenas de avisos "constant folding"** do onnxruntime ao criar
a sessão. Correção: `SessionOptions.log_severity_level = 3` (e threads limitadas) em
`KokoroEngine`, `voice/app/engine.py`. Não é erro; ignore se aparecer em teste avulso.
56. **Recarga do catálogo lenta com muitas vozes Kokoro** (todas apontam para o mesmo onnx de
~160 MB e o sha256 era recalculado por voz). Correção: cache de `sha256_file` por
(caminho, mtime, tamanho) em `voice/app/catalog.py` — 62 vozes: 0,3 s → 0,01 s (informado).
64. **Download dos pesos do Chatterbox trava** (~3,3 GB de `ResembleAI/chatterbox` para
`data/voice/models/clone-hf/`): o protocolo Xet do Hugging Face baixou 256 MB em 9 min.
Correção: `HF_HUB_DISABLE_XET=1` (com ele baixou tudo); o worker já define isso e
`HF_HUB_DISABLE_SYMLINKS_WARNING=1`. Onde: `voice/clone/worker.py`. Atenção: a revisão é `main`,
**não fixada em commit** nem conferida por sha256 (foge da regra do `models.lock.json`).
65. **Chatterbox não cabe no `voice/.venv`**: fixa `numpy<2`, torch 2.6 e transformers 5.2.0.
Correção: venv próprio `voice/.venv-clone` (Python 3.12, torch/torchaudio 2.6.0+cu124) e worker
HTTP separado na 4511, chamado pelo `CloneEngine`. Nunca instale `chatterbox-tts` no
`voice/.venv`. Onde: `scripts/setup.ps1` (`-Clone`), `voice/clone/requirements.txt`.
66. **Fala clonada longa estoura o tempo**: ~1,5 s de processamento por s de áudio na GPU (RTX 2060
SUPER) pode passar de `VOICE_SYNTH_TIMEOUT_S=90`. Correção: sintetizar textos longos em partes
(o worker já divide em trechos ≤ 280 caracteres, mas o tempo total da requisição conta). A 1ª
fala inclui o condicionamento da referência (6,0 s de áudio em 20,5 s; a 2ª, 7,1 s em 10,5 s).
67. **`speed` não muda a voz clonada** e todo áudio sai com marca d'água inaudível PerTh. Não é
defeito: o Chatterbox não tem controle de velocidade. Para outro ritmo, use outro motor.
## Clipador (`clipper/`)
Itens 57–61 observados em 16/11/2026 na live real (`twitch.tv/alanzoka`) e nos testes. Contexto em
[clipper.md](clipper.md).
57. **Legenda some ou sai deslocada no corte.** Causa: com `-ss` depois do `-i`, o filtro `ass` vê
o tempo do bloco, não o do corte. Correção: `-ss` **antes** do `-i`. Onde: `clipper/app/editor_render.py`
(render atual) e `clipper/app/media.py` (caminho antigo).
58. **Tag ASS inválida na legenda palavra a palavra.** Causa: `.upper()` na linha ASS inteira transformava a
tag `\c` em `\C`, que é inválida. Correção: maiúsculas só no texto da palavra. Onde:
`clipper/app/subtitles.py` (`build_ass`).
59. **Falsos positivos com o chat calmo.** Causa: o emote `clip5k1hmm` casava com `\bclip`, e 3
mensagens já davam razão 2,35. Além disso, o começo da gravação não tinha base de comparação.
Correção: "clip" só como palavra inteira, mínimo de mensagens nos 8 s do pico (hoje proporcional,
item 68) e 60 s de aquecimento. Onde: `clipper/app/scoring.py` (`Params`, `warmup_s`); há teste
de regressão em `clipper/tests/test_scoring.py`.
60. **Ao vivo, a explosão do chat era cortada cedo.** Causa: um pico menor do começo da explosão
fechava antes do pico maior, que ainda estava crescendo. Correção: o pico é escolhido olhando a
série inteira e só depois é filtrado pelo "assentado" (`limit_s`). Onde: `pick_peaks` em
`clipper/app/scoring.py`.
61. **Chat e vídeo desalinhados na Twitch.** Causa: o Streamlink pausa durante o anúncio filtrado.
Correção: o tempo da mensagem é convertido pela hora real em que cada bloco chegou (`wall_end`
da tabela `segments`), não pelo relógio desde o início. Onde: `clipper/app/worker.py`.
Observadas em 17/11/2026 (fase 2) numa cópia do banco da live do skipnho e nos testes:
68. **Live de chat pequeno nunca gerava corte.** Causa: com ~0,15 msg/s, o mínimo fixo de 12 mensagens
nos 8 s do pico era inalcançável. Correção: mínimo = 3× a mediana recente, entre 4 e 12, exigindo
≥ 2 reações (texto ou emote); com chat < 0,5 msg/s o áudio também propõe momentos; e a varredura da
IA cobre o resto. Onde: `_required_messages`, `_chat_moments`, `_audio_moments` em
`clipper/app/scoring.py`; varredura em `clipper/app/intel.py`.
69. **Título preso à frase solta da transcrição** ("Jogando três jogos ao mesmo tempo" num momento de
lag). Causa: um único juiz só com texto. Correção: ANALISTA com 6 frames (8 se o trecho passa de 80 s) + glossário de gírias do
chat (`CHAT_GLOSSARY`: "server chinês" = lag) e EDITOR que escreve a partir da análise. Onde:
`clipper/app/judge.py`; frames montados em `clipper/app/worker.py`.
70. **Crédito em cima do rosto no `cam_top`.** Causa: crédito no topo fica sobre a webcam. Correção:
no `cam_top` o crédito do topo desce para o pé do painel da câmera (`cam_panel_height`). Onde:
`clipper/app/subtitles.py`.
71. **Cor errada na legenda ASS.** Causa: formatos diferentes — a linha `Style` usa `&H00BBGGRR&` (com
alfa) e a tag `\c` inline usa `&HBBGGRR&` (sem alfa); ambos em BGR, não RGB. Correção: sempre
converter por `ass_color` (Style) ou `ass_inline_color` (tag). Onde: `clipper/app/layout.py`.
72. **Chat travando ao baixar emotes.** Causa: APIs de 7TV/BTTV/FFZ podem demorar (FFZ) ou dar 404
(7TV em canal sem 7TV). Correção: a thread do chat só lê `EmoteCatalog.cached()`; o download
(`names()`, cache de 1 h, fonte com falha ignorada) roda em thread à parte ao chegar o `room-id`.
Onde: `ingest_chat` em `clipper/app/intel.py`, `clipper/app/emotes.py`.
73. **Código novo do Clipador "não funciona" no painel.** Causa: o uvicorn sobe sem `--reload`; a UI
nova (o Next em dev recarrega sozinho) chama rotas ou manda campos que o serviço antigo não conhece — ex.: um
serviço anterior ao `cam_only` recusa o projeto do editor que usa esse modo (`validate_project` → 400).
Correção: reiniciar o Clipador (`start.bat` / `pnpm dev`, que é do usuário — peça a ele; ele pode estar
gravando). Mesmo padrão do item 53.
Observadas em 16/11/2026 no editor de cortes, numa cópia do banco (sessão 3 do skipnho) e nos testes:
74. **Projeto do editor recusado com 400.** Causa: o Whisper devolve palavra com duração zero (ex.: "queria"
1020,10–1020,10). Correção: palavra com fim ≤ início ganha 50 ms. Onde: `clipper/app/editor.py`
(leitura das palavras e `validate_project`).
75. **Capa sai vazia.** Causa: o mjpeg do FFmpeg 7.1 recusa yuv420p marcado como faixa "tv" (blocos do libx264).
Correção: o quadro intermediário da capa é PNG. Em teste, bloco sintético precisa de `-g` curto; senão o `-ss`
não acha quadro e o grab sai vazio. Onde: capa em `clipper/app/editor_render.py`; `clipper/tests/test_editor.py`.
76. **Gancho vira frase longa cortada ou mostra o tempo da gravação** ("Aos 5085s, ele solta que…", corte 25 do
skipnho). Causa: o `hook` do analista às vezes é uma frase descritiva. Correção: só vale com ≤ 8 palavras, ≤ 48
caracteres e sem tempo da gravação; senão usa o título do editor. A menção ao tempo é sempre removida e o texto
nunca para no meio de palavra (≤ 60 caracteres). Onde: `pick_hook` em `clipper/app/editor.py` (usado por
`auto_project` e `default_project`).
77. **Instância de teste do Clipador apaga a gravação real.** Causa: a cópia do banco aponta para os mesmos `.ts`;
o prune por `CLIPPER_KEEP_HOURS` e o monitor/varredura da cópia agiriam sobre os arquivos e canais reais.
Correção: na instância de teste, **sempre** `keep_hours = 0` (pula o prune), canais com `monitor = 0` na cópia e
sem monitor/varredura/contexto (subclasse de `Engine` que só sobe a fila de cortes); porta na faixa 4500–4599
(ex.: 4521). Derrube a instância e apague a cópia ao terminar. Onde: `prune` em `clipper/app/worker.py`.
A cópia também **herda as sessões**: um `Engine` completo retoma as `interrupted` na subida (`keep_live`), pode
gravar uma live de verdade e chamar a CLI de IA. Ao terminar, encerre a árvore de processos inteira (uvicorn,
streamlink, ffmpeg). Há várias sessões do Claude neste projeto ao mesmo tempo: uma instância na 4521 pode ser de
outra sessão — confira antes de derrubar ou usar.
78. **Emoji sai monocromático no vídeo.** Causa: o libass do FFmpeg não desenha emoji colorido. Sem correção por
enquanto (limitação registrada no README do Clipador); não prometa emoji colorido na legenda ou no gancho.
Observadas em 16–17/11/2026 no rastreio de reação (bancada e calibração numa cópia do banco, sessão 3 do skipnho;
registro em `doc/FACE_BAKEOFF.md`):
79. **`ImportError` ao carregar o MediaPipe.** Causa: `from mediapipe.tasks import python` não existe no
`mediapipe` 1.2.3. Correção: importar os submódulos (`from mediapipe.tasks.python import vision`,
`from mediapipe.tasks.python.core.base_options import BaseOptions`), e só dentro da função (o serviço e os
testes sobem sem cv2/mediapipe). Onde: backend `mediapipe` em `clipper/app/face.py`.
80. **`cv2` quebrado ou sem `FaceDetectorYN`.** Causa: `opencv-python-headless` instalado junto do
`opencv-contrib-python` (os dois brigam pelo mesmo módulo `cv2`). Correção: só `opencv-contrib-python`, o que
vem com o MediaPipe. Onde: comentário em `clipper/requirements.txt`.
81. **Risada não aparece no sinal.** Causa: em live, `jawOpen` quase nunca passa de 0,1 e `eyeWide*` fica em ~0,
mesmo com recorte apertado. Correção: risada sai do sorriso (`mouthSmile*`), com z relativo ao neutro do próprio
streamer; não exija boca aberta. Onde: `label` e `ReactionParams` em `clipper/app/reaction.py`.
82. **Streamer partido em dois na detecção da câmera.** Causa: agrupar os rostos comparando com o 1º membro do
grupo; quando ele se inclinou (0,8 largura de rosto) virou outro grupo. Correção: agrupar pelo **centro**
(média corrente) do grupo, tolerância `cluster_faces` 1,0. Onde: `locate_cam` em `clipper/app/reaction.py`.
83. **"Sustos" falsos.** Causa: o rastreio perde o rosto por instantes e o centro "pula", virando movimento grande.
Correção: movimento só rotula (não entra na intensidade) e só vale com rosto em ≥ 80 % do segundo
(`motion_min_present`). Onde: `clipper/app/reaction.py`.
84. **Streamer de neutro sorridente não gera pico** (corte 12 aprovado sem pico). Causa: o z é relativo ao normal
dele, que já é alto. Sem correção: limitação do sinal relativo (`smile_raw` só ajuda no rótulo). Por isso o rosto
só reforça o corte (bônus ≤ 0,6) e nunca decide sozinho; não o use como juiz.
Observadas em 17/11/2026 nos testes ao vivo do rastreio (instância isolada na 4521; seção "Testes de 17/11 — ao vivo"
de `doc/FACE_BAKEOFF.md`):
92. **Live sem câmera ganha "webcam"** (twitch.tv/lofigirl). Causa: o YuNet achou um rosto de 24×34 px colado na
borda (a tela de um notebook desenhado) em 8 de 12 quadros, score 0,61–0,66, e o `locate_cam` aceitou só pela
presença estável. Webcam real dá 0,92–0,94. Correção: confiança média do grupo ≥ `ReactionParams.min_cam_score`
(0,7). Onde: `locate_cam` em `clipper/app/reaction.py`; teste em `clipper/tests/test_reaction.py`.
93. **Instância de teste com banco novo pega a transcrição de outra sessão.** Causa: o serviço de voz (4510) é
compartilhado e guarda a transcrição pela chave `clipper-<sessão>-<bloco>`; num banco novo as sessões recomeçam
do 1 e colidem com as do banco real. Correção: antes da 1ª sessão, subir o `sqlite_sequence` de `sessions` do
banco de teste (ex.: 90000), além de `CLIPPER_DATA_DIR`/`CLIPPER_OUTPUT_DIR` dentro do repo. Onde: receita em
"Variáveis" de `clipper/README.md`; pastas em `clipper/app/config.py`.
94. **Analista lê "sem reação marcante no rosto" com o plano B.** Causa: o OpenSeeFace não tem blendshapes; os canais
saem 0 e o resumo dizia que não houve reação, o que é falso. Correção: com a série da sessão no backend
`openseeface`, `FaceService.summary` devolve "" (nenhuma linha de rosto vai ao analista). Onde: `clipper/app/face.py`.
95. **WARNING "pesquisa de jogo falhou: IA desligada" a cada 30 s** com o juiz `off`. Causa: `research_pending`
tentava pesquisar o jogo mesmo com a IA desligada. Correção: sai cedo se `judge.enabled` for falso (o jogo fica
`pending`). Onde: `Intel.research_pending` em `clipper/app/intel.py`.
Observadas em 16/11/2026 no teste de UI do editor de cortes redesenhado (Chrome sem janela por CDP):
85. **Teste automático não acha texto, legenda nem chat no monitor Programa.** Causa: a prévia é um `<canvas>`; as
camadas não são elementos do DOM. Correção: mover o ponteiro sobre o canvas e ler `style.cursor` — `"move"` =
há camada arrastável ali (`hitAt` em `panel/src/components/clip-editor-preview.tsx`). Trilhas e palavras da
timeline são DOM normal.
86. **Teste de UI grava no corte real do usuário.** Causa: o editor salva sozinho 1,2 s depois de cada mudança e o
painel (4500) fala com o Clipador real (4520). Correção: interceptar toda requisição não-GET de
`*/api/clipper/*` (domínio `Fetch` do CDP) e responder sem repassar; conferir depois que nada mudou. Para
simular dados (ex.: sessão em outro estado), altere só a **resposta** do GET (`requestStage: "Response"`). Para
testar gravação de verdade, use a instância sobre cópia do banco (item 77). Ligue o `Fetch` **antes** de navegar,
senão os GET da carga da página passam sem alteração. Atalho com Ctrl (Ctrl+Z) precisa ir como evento `keyDown`.
Observadas em 16–17/11/2026 no serviço do usuário (sessão 3 do skipnho) e no painel; 87–90 também em "Armadilhas já
resolvidas" de `clipper/README.md`:
87. **Cortes presos em `rendering` sem mensagem; a capa sai e o vídeo não** (10 cortes, ids 42–58). Causa: o serviço foi
reiniciado no meio de uma edição de código e subiu com uma versão intermediária da legenda (casava a ênfase por
`id()` da palavra → `KeyError` quando o saneamento mudava palavras); a exceção escapava do render e o corte ficava
em `rendering` para sempre. Correção: qualquer exceção no render vira `error` com a mensagem; `rendering` órfão há
> 5 min volta para `pending` (3ª vez = `error`). Regra: **só reinicie o serviço com a suíte verde**; agente que
edita `clipper/app/` trabalha numa cópia e aplica no fim **por edição pontual** (trecho a trecho), nunca
sobrescrevendo o arquivo inteiro: vários agentes e outras sessões mexem em `clipper/` ao mesmo tempo e a cópia
inteira apagaria o trabalho deles. Onde: `render_clip`, `recover_orphan_renders` em `clipper/app/worker.py`.
88. **Live no ar foi para `processing` depois de reiniciar o serviço.** Causa: a retomada da subida checava uma vez só,
e timeout/erro do `streamlink --json` pareciam "offline". Correção: `Engine.live_check` separa `live`/`offline`/
`unknown` e `keep_live` tenta de novo (`RESUME_DELAYS_S` 0…120 s); a sessão fica `interrupted` enquanto tenta; a
captura que cai no meio passa pelo mesmo caminho. Onde: `clipper/app/worker.py`; teste `clipper/tests/test_resume.py`.
89. **O mesmo momento vira vários cortes** (pico 1149 s → cortes 42, 47, 49, 51, 52 em cima do 9). Causa: o juiz recua o
trecho para antes do pico (ainda mais com `backtrackS` 120), e a checagem comparava o candidato só com o trecho
final dos cortes. Correção: comparar também o pico e a janela original (`reasons.candidateStartS/EndS`), em
qualquer estado, e conferir de novo depois do juiz (`judge.duplicateOf`). Onde: `clipper/app/worker.py`
(`SAME_PEAK_S`, `SAME_MOMENT_OVERLAP`, `discard_pending_duplicates`); teste `clipper/tests/test_render_and_duplicates.py`.
90. **Legenda uma em cima da outra com fala rápida.** Causa: o fim de cada bloco (fim da última palavra, no mínimo
+0,25 s) passava do início do seguinte e o libass empilha eventos ativos ao mesmo tempo; o Whisper também devolve
palavras de 0 s e palavras que começam juntas. Correção: `clean_words` (ordem, 60 ms mínimos, 40 ms entre inícios,
sem sobreposição) e `caption_blocks` (fim do bloco cortado no início do seguinte); ênfase casada nos tempos
originais. Onde: `clipper/app/subtitles.py`; teste `clipper/tests/test_format_and_captions.py`.
91. **Texto truncado longo alarga a página `/clipper`.** Causa: cartão dentro da grade das abas cresce com o conteúdo
intrínseco mesmo com `truncate`. Correção: `[contain:inline-size]` no cartão. Onde: cartão da sessão em
`panel/src/components/clipper-sessions.tsx`.
Observadas em 17/11/2026 (duração mínima, tarja do gancho, fontes, reenquadramento, camadas e qualidade de gravação;
103–108 também em "Armadilhas já resolvidas" de `clipper/README.md`):
103. **Cortes automáticos mais curtos que o mínimo** (mínimo 60: cortes 43 = 54,6 s, 55 = 46,8 s, 61 = 43,8 s). Causa:
`auto_project` adiantava o início para o `action_start_s` do analista sem reimpor o mínimo; juiz e varredura
limitavam o fim sem recuar o início. Correção: todo corte automático passa por `scoring.fit_window` com
`layout.min_target` (`minS` + 1 s + 0,1 s de folga, ≤ `maxS`); faltando material, cresce para trás. "Cortar agora"
e a edição à mão continuam livres. Teste: `clipper/tests/test_duration_banner_fonts.py`.
104. **Texto da tarja não desfoca na entrada `slide`.** Causa: com contorno (`\bord` > 0), o `\blur` do libass desfoca
só a borda e o preenchimento fica nítido. Correção: duas camadas ASS — preenchimento com `\bord0` e `\blur18`→0, e
o contorno por baixo. Assentado, sai idêntico ao de antes (0 px de diferença aos 1500 ms, informado). Onde:
gancho/texto `banner` em `clipper/app/editor_render.py`.
105. **Fonte empacotada ignorada pelo libass** (cai numa fonte padrão, sem erro). Causa: o `fontsdir` não lê subpastas,
e a família no ASS precisa ser o nome **dentro** do arquivo ("Poppins ExtraBold", não "Poppins"). Correção:
`assets/fonts/` plana; `family` em `assets/fonts/fonts.lock.json`; no Windows, caminho absoluto entre aspas com
`:` escapado (`layout.ass_filter`). O `fontsdir` só entra quando o ASS usa fonte empacotada, para o filtro de
projetos antigos (e o SHA de referência do vertical) não mudar.
106. **Zoom variável no tempo não sai com `crop`.** Causa: o `crop` do FFmpeg avalia `w`/`h` uma vez só (posição por
quadro, tamanho fixo); `scale` com `eval=frame` + `crop` fixo falhou no encoder e arredonda a posição a pixel
inteiro. Correção: `perspective` com `eval=frame` (4 cantos por quadro, subpixel) e depois `scale`. O contador
`in` do `perspective` começa em **1** (com `in/30` a janela ia 1 quadro adiantada). Grafo > 20 000 caracteres vai
por arquivo (`-/filter_complex`). Onde: `perspective_filter` em `clipper/app/reframe.py`; `editor_render.py`.
107. **Quadro errado ao buscar dentro de um bloco `.ts`.** Causa: o demuxer mpegts trata todo pacote como ponto de
busca; `-ss` antes do `-i` cai num quadro P → em H.264 sai o próximo quadro-chave (até 2 s depois), em **HEVC**
sai quadro **cinza** (frames do juiz, capa e YuNet; a câmera não era achada). Um 2º `-ss` depois do `-i` também
erra com áudio no bloco. Correção: `media.seek_args` busca 4 s antes, `-copyts -start_at_zero` e
`select='gte(t,alvo)'` (usado por `grab_frame` e `face.grab_bgr`). Render e proxy (concat demuxer) já buscavam certo.
108. **Vídeo para no meio do corte, sem erro** (corte de 35 s com 20 s de vídeo). Causa: o trecho atravessa a emenda de
uma retomada em outra resolução ou codec (H.264 → HEVC) e o concat + `filter_complex` corta o vídeo ali.
Correção: `uniform_segments` (`editor_render.py`) converte os blocos do trecho num intermediário uniforme só
nesse caso (render e proxy); o proxy faz `fps` antes do `scale`; `face.py` mede o tamanho do quadro por bloco.
Observadas em 17/11/2026 (diagnóstico da sessão 3, cartão da sessão, apagar cortes e prévia do editor; 114 também em
"Armadilhas já resolvidas" de `clipper/README.md`):
114. **"Não está gerando cortes".** Causa quase sempre: a **live esfriou**, não as regras. Sessão 3 (cópia do banco):
chat de 0,27–0,39 msg/s e 56–78 reações a cada 500 s caiu para 0,04–0,10 msg/s e 2–10 reações; nenhum pico da
heurística em 8872–10350 s, nem com as regras antigas; as antigas dariam 3 candidatos a mais (2 de rosto fraco com
nota 2,5 e 1 na cena do corte 61, rejeitado); zona proibida 34 % × 24 %. Correção: antes de mexer em regra, olhe
msg/s e reações (`GET /v1/sessions/{id}/timeline`) e `proposals`/`created` da varredura em `sessions.memory_json`
(e no log). Onde: `clipper/app/intel.py` (contagem), `worker.py` (`VETO_STATUSES`).
115. **"Agora na live" parece travado e o tempo gravado anda aos saltos.** Causa: o resumo só muda a cada janela da
varredura (`scanIntervalS`, 180 s) e `durationS` sobe por bloco (30 s). Correção: relógio local que corre entre as
consultas, com teto de 45 s ("aguardando o bloco"), e contagem "próximo em m:ss". Onde: `RecordingClock` e
`SummaryCadence` em `panel/src/components/clipper-sessions.tsx`.
116. **Barra de seleção presa no topo da fila reprovada pelo dono.** Causa: ação em massa ocupando espaço e cobrindo
o conteúdo. Correção: controles discretos no canto ("Selecionar", "⋯"), caixa do cartão só no hover/foco/modo de
seleção e pílula flutuante pequena; nada pode empurrar a lista. Vale para toda ação em massa nova. Onde:
`panel/src/components/clipper-queue.tsx`.
117. **Prévia do editor 1–3 px deslocada do render** (corte 61, câmera 18 % × 23 %) e blocos de legenda diferentes.
Causa: o FFmpeg recorta em pixel **par** no yuv420 e o `scale … increase` arredonda; a prévia dividia em subpixel;
a legenda do painel não saneava os tempos como `subtitles.py`. Correção: `ffmpegCropFill` com o tamanho de
`session.capture` e porte `cleanWords`/`groupWords`/`captionBlocks` (`CAPTION_TIMING`). Onde:
`panel/src/components/clip-editor-model.ts`; mudou `subtitles.py` ou `layout_chain`, mude o porte junto.
136. **Juiz do Clipador esgota a cota do ChatGPT / chamadas lentas e caras.** Causa: cada chamada do juiz é um processo
novo de CLI (2 por candidato) e o Codex carrega ~77 mil caracteres fixos (~19 mil tokens) antes do prompt; uma live de
3,7 h (75 candidatos, ~150 chamadas) gastou ~2,9 milhões de tokens só de fixo. Correção: `codex_lean_overrides`
(features/MCP/plugins off, `system` em `model_instructions_file`) e `--setting-sources project,local` no Claude.
**Só vale depois de reiniciar o Clipador (porta 4520)**: o código é lido na partida. Detalhes em
[token-economy.md](token-economy.md). Onde: `clipper/app/judge.py`.
## Publicação (Publicador + despachante do painel)
Regras de projeto informadas em 17/11/2026 (código em `panel/src/lib/publishing*.ts` e `publisher/app/`); nenhuma
observada num envio real ainda. Contexto em [publishing.md](publishing.md).
118. **Job em "Com problema" dizendo que o Publicador terminou sem confirmar o link.** Causa: o Publicador devolveu
`done` sem `remoteId`/`url` (comum no modo sessão quando a tela não mostra o link). Correção: por regra nunca vira
`published` sem ID/URL (ou rascunho) — `readPublisherJob` grava `failed`. **Confira na rede** antes de "Tentar de
novo", senão o vídeo sai duas vezes. Mesmo cuidado com `failed` "interrompido" (Publicador fechado no meio). Todo
`failed` que chegou ao Publicador tem `mayBeLive`: a UI pergunta "Confira na rede se o vídeo já saiu" e a API
responde 409 ao `retry` sem `{confirm: true}` (`retryJob` em `publishing.ts`).
119. **Job parado em "Esperando: …" sem falhar.** Causas, nesta ordem: painel fechado (o laço de 20 s roda dentro do
`pnpm panel`); publicação pausada em Configurações; Publicador fora (503 → "inicie com pnpm dev"); perfil não
`connected` no Publicador (409 → o job **fica na fila** e a rede é reconsultada); "Publicador indisponível ou mal
configurado" (401/403/404: `PUBLISHER_SERVICE_KEY` diferente ou Publicador antigo — reinicie o `pnpm dev`).
Timeout/conexão caída também deixa na fila: o reenvio usa o mesmo `clientRef` e não duplica. Onde: `sendDue`.
120. **Rede em `expired` ou `needs_login`.** Causa: autorização oficial vencida (ex.: YouTube em "Testing" vence em 7
dias) ou a rede pediu login/captcha no modo sessão. Correção: reconectar em Canais de publicação ("Entrar de
novo"/reabrir a janela); nunca automatizar login nem captcha.
121. **Jobs de um corte cancelados sozinhos.** Causa: exportar no editor (ou re-renderizar) volta o corte para
`pending`; jobs não enviados viram `canceled` com `cancel_reason = 'source_changed'`. Encerrar a fonte ou a
história no canal faz o mesmo com `unlinked` ("a fonte/história foi desligada deste canal"). Correção: nenhuma —
voltam sozinhos quando o corte fica pronto de novo ou a fonte é religada. Já enviado não é cancelado.
122. **Ligou a aprovação automática e os cortes antigos não saíram.** Não é erro: só cortes criados depois de ligar
(`accounts.auto_since`) e depois de ligar a fonte ao canal são aprovados sozinhos; religar uma fonte encerrada
zera `linked_at`, então os cortes do intervalo desligado também não. Antigos: aprovar à mão.
123. **"Na hora" virou agendado.** Causa: limite diário da rede (`daily_limit`) já atingido; vai para o próximo
horário bom livre. Correção: subir o limite ou esperar.
124. **TikTok oficial publica só como "Somente eu".** Causa: app sem auditoria só permite `SELF_ONLY` (conta privada)
e a auditoria para uso próprio provavelmente é negada (`doc/publicacao/PESQUISA.md`). Correção: modo Rascunho
(`tiktok_mode = 'draft'`, até 5 pendentes/24 h) ou sessão logada.
125. **API do painel responde 403 "Acesso recusado…" ou 415 a `curl`/script.** Causa: `panel/src/proxy.ts` só aceita
Host 127.0.0.1/localhost/[::1] e exige, em POST/PUT/PATCH/DELETE, `Origin` do mesmo host (ou `Sec-Fetch-Site:
same-origin`), senão "Acesso recusado: pedido sem origem do próprio painel"; `readJson` (`lib/http.ts`, usado em parte
das rotas; as outras leem `request.json()` direto) exige `Content-Type: application/json`. Correção:
`curl -X POST -H "Origin: http://127.0.0.1:4500" -H "Content-Type: application/json" -d '{}' http://127.0.0.1:4500/api/...`.
Não afrouxe a guarda (anti DNS rebinding e CSRF; teste em `panel/src/lib/proxy.test.ts`).
126. **Agendado saiu em outro horário depois de reabrir o painel.** Causa: horário automático (`schedule_source =
'auto'`) vencido há > 30 min (`STALE_AFTER_MS`) é reencaixado no próximo horário bom, sem rajada. Horário manual e
"Publicar agora"/"Tentar de novo" não são reencaixados. Onde: `needsReflow` (`publishing-rules.ts`), `promoteDue`.
127. **Conectar pela API oficial não conclui.** Causas: o Publicador reiniciou no meio (o `code_verifier` do PKCE fica
só em memória) ou o passo a passo parou de esperar (10 min, `WAIT_LIMIT_MS` em `connect-wizard.tsx`). Correção:
clicar **Conectar** de novo.
128. **Janela do navegador do modo sessão fecha sozinha.** Não é erro: fecha depois de cada envio e do "Já entrei"
(saída limpa; mata após 10 s) e quando ociosa (5 min; 15 min se aberta para login), para a porta CDP ficar aberta o
mínimo. Fica aberta se a rede pedir login/captcha. Onde: `publisher/app/platforms/session/browser.py`.
137. **Modo sessão: o Chrome abre, a conta está logada, a porta 4540 responde em `/json/version`, mas o painel diz "O
navegador abriu mas não respondeu".** Causa (17/11/2026): o **Chrome 157 (157.0.8103.79) não grava
`DevToolsActivePort` no perfil quando a porta é fixa** (`--remote-debugging-port=4540`), e `owns_port` dependia só
desse arquivo. Correção: `owns_port` usa o `DevToolsActivePort` quando existe; senão usa a marca
`CenaForgeWindow.json` (`{"pid","port"}`, gravada por `write_window_mark` logo depois do `Popen`) e exige que o PID
que escuta na porta (`listener_pid`, `GetExtendedTcpTable` via ctypes, sem psutil) seja exatamente o da marca e que o
executável (`process_exe_name`, `QueryFullProcessImageNameW`) seja `chrome.exe`/`msedge.exe`. `active_port` também lê
a marca; `open()` apaga marca e `DevToolsActivePort` velhos. Medido ao vivo: `listener_pid(4540)` = `chrome.exe`
lançado pelo Publicador (o PID do `Popen` é o próprio processo que escuta). **Só vale depois de reiniciar o
`pnpm dev`** (o Publicador roda sem `--reload`). Variante: se o processo sai logo, o Chrome entregou a URL a uma
janela já aberta com o mesmo perfil (sem a nossa porta); `_wait_cdp(port, user_dir, process)` detecta e mostra "Já
existe uma janela do navegador aberta com este perfil. Feche essa janela (a conta continua logada) e tente de
novo." — feche a janela, não mexa no código. Testes: `test_owns_port_without_devtools_file_uses_window_mark` e
`test_wait_cdp_explains_when_profile_window_is_already_open` em `publisher/tests/test_hardening.py`. Onde:
`publisher/app/platforms/session/browser.py`.
138. **"Publicar" no cartão do corte (ou desligar fonte) falha com "table publish_jobs has no column named origin".**
Causa (17/11/2026, `POST /api/publishing/clips/75`): a v7 do banco (`publish_jobs.origin`) não tinha sido aplicada
no banco já aberto; `INSERT ... origin` e `accounts.endChannel` (`AND origin = 'link'`) quebram. Hoje o `db()` migra
sozinho: a conexão fica em `globalThis.__cenaforgeDb`, e a marca de módulo `checkedThisModule` (some a cada recarga
do código pelo HMR) faz a 1ª chamada depois da recarga rodar `migrate()` no banco aberto, com backup em
`data/backups/` (`cenaforge-v<antiga>-<data>.db`). Medido: um `GET /api/publishing/summary` no painel em execução
levou o banco real a `user_version` 7, com a coluna `origin` e o backup `cenaforge-v6-2026-11-17T16-28-39-725Z.db`.
O sintoma ainda aparece se o próprio `db.ts` não foi recarregado (módulo antigo, sem a marca); na prática qualquer
edição em `db.ts` o recarrega. Correção: fazer qualquer requisição ao painel (ex.: `GET /api/publishing/summary`,
com `Origin` se não for GET, item 125) ou, se ainda falhar, pedir ao usuário que reinicie o `pnpm dev` (o painel é
dele; reiniciar mata agente em execução, item 131). Conferir: `PRAGMA user_version` de `data/cenaforge.db` =
`MIGRATIONS.length`. Onde: `db()` em `panel/src/lib/db.ts`, `publishClip` em `panel/src/lib/publishing.ts`.
139. **Modo sessão (TikTok): job falha com "Locator.set_input_files: Cannot transfer files larger than 50Mb to a browser
not co-located with the server", embora o login e a navegação tenham funcionado.** Sintoma (17/11/2026): a captura
`data/publisher/logs/20261117-133245-tiktok-*.png` mostra o TikTok Studio logado na tela "Selecione o vídeo a
enviar"; a falha foi só na entrega do arquivo. A mensagem ao usuário é a genérica "O navegador travou ou mudou de
página no meio do envio" (todo `PlaywrightError` cai nela, `_with_page`); o texto real vem depois de "Detalhe:". Causa:
com `connect_over_cdp` o Playwright trata o navegador como remoto e recusa `set_input_files` acima de 50 MB; os
cortes do Clipador têm 100–108 MB (`clip-52.mp4` com 107,9 MB). Correção: `is_local=True` no `connect_over_cdp`
(parâmetro existe no playwright 1.65.2 da `publisher/.venv`, conferido na assinatura), em `_with_page`
(`runner.py`, com comentário) e em `BrowserManager.close` (`browser.py`). Só `127.0.0.1` com porta conferida como
nossa (`owns_port`); não use para endereço remoto. **Só vale depois de reiniciar o `pnpm dev`** (o Publicador roda sem
`--reload`). Evidência: `pnpm test:publisher` → 73 passed (reexecutado na skill, 17/11/2026); **envio real ainda não
refeito**. Ao ver "travou ou mudou de página", leia o "Detalhe" antes de culpar o navegador. Onde:
`publisher/app/platforms/session/runner.py`, `publisher/app/platforms/session/browser.py`.
140. **TikTok em modo sessão publicou, mas o job falhou com "não confirmou o link".** Sintoma (17/11/2026, 1º envio real,
público às 13:35): o vídeo está no ar (`https://www.tiktok.com/@vortplay/video/7709179978520284437`) e o painel marcou
`failed`. Causa: depois de publicar, o Studio vai para `/tiktokstudio/content`, mas a linha nova só mostra o
`<a href="/@conta/video/<id>">` alguns segundos depois; o código antigo procurava `a[href*='/video/']` por só 5 s.
Correção (2ª versão, 17/11/2026): `find_video_url(page, caption, sleep, attempts=12, reads=5, progress)` espera 5 s e, a
cada tentativa, abre ou RECARREGA `CONTENT_URL` (a lista não se atualiza sozinha; o vídeo novo entra depois de
processar), lê 5 vezes a cada 3 s, até 12 cargas (~3 min), e só aceita o link da linha (até 10 ancestrais do `<a>`)
que contém `caption_key(caption)` (24 primeiros caracteres da legenda sem #hashtags/@menções): nunca pega o link de
outro vídeo. Sem link: step "…não apareceu na lista do Studio em ~3 min; link não encontrado"; o painel mostra "Saiu
na rede, mas o link do vídeo não apareceu a tempo… use 'Já saiu: informar o link'" (`readPublisherJob`). O seletor `video_link` saiu
de `SELECTORS`. Validado ao vivo, só leitura (informado): legenda certa → link; legenda de outro corte → `None`. Se
acontecer de novo: **confira na rede antes de "Tentar de novo"** (publicaria duas vezes) e use "Já saiu: informar o
link" (`mark-published`, `publishing.md`). Só vale depois de reiniciar o `pnpm dev` (item 137). Teste:
`test_tiktok_link_waits_for_the_list_and_matches_caption` (`publisher/tests/test_browser.py`). Onde:
`publisher/app/platforms/session/tiktok_studio.py`.
141. **Job manual novo cancelado como "unlinked" (regra antiga) ou despachante ignorando código novo.** Causa: o laço de
`panel/src/instrumentation.ts` (`startDispatcher`) guarda a função `tick` em `globalThis` e o HMR não a substitui;
o laço seguia com o `dispatcherTick` antigo (sem a regra de `origin = 'manual'`). Correção: no fim de
`panel/src/lib/publishing.ts`, ao carregar o módulo, `if (state.tick && state.tick !== dispatcherTick) state.tick =
dispatcherTick`. Regra: todo estado de laço guardado em `globalThis` precisa ser reapontado quando o módulo recarrega.
Se o sintoma voltar com outro módulo, aplique o mesmo padrão; reiniciar o `pnpm dev` é do usuário (item 131). Onde:
`panel/src/lib/publishing.ts` (bloco final), `panel/src/lib/dispatcher.ts`.
142. **Modo sessão (TikTok): falha com "Locator.click: Timeout 30000ms exceeded … waiting for locator("div[contenteditable='true'].public-DraftEditor-content")".**
Sintoma (17/11/2026): a captura `data/publisher/logs/20261117-134508-tiktok-*.png` mostra o vídeo já carregado e,
por cima da página escurecida, um aviso de novidade do Studio, "Veja a prévia do seu vídeo no seu celular", com o botão
**Entendi**. Causa: o aviso bloqueia o clique na legenda (o seletor está certo). O Studio também pré-preenche a legenda
com o nome do arquivo ("clip-75"), mas `fill_text` já faz Ctrl+A/Delete. Correção em `common.py`: `TIP_BUTTONS` aceita só
`^(Entendi|Entendido|Ok, entendi|Got it)$`; `dismiss_tips(page, sleep, rounds=3)` fecha esses avisos;
`click_through(locator, sleep, timeout_ms=8000)` clica e, no timeout, fecha os avisos e tenta de novo (sem aviso
para fechar, relança o erro original); `fill_text` usa `click_through`. Em `tiktok_studio.py`, `dismiss_tips` roda
antes da legenda e antes de "Publicar", e todos os cliques (privacidade, mostrar mais, IA, Publicar, Publicar agora)
passam por `click_through`. **Regra:** por esse caminho só se fecham avisos de "entendi"; nunca aceitar ou recusar
opções (verificação de conteúdo, música etc.). Outro aviso novo com outro texto de botão: acrescente-o a `TIP_BUTTONS`
só se fechá-lo não mudar o post. Mensagens: `browser_error_text(detail)` em `runner.py` troca o genérico "O navegador
travou…" por frases para clique com timeout ("aviso do site aberto por cima…"), timeout comum, arquivo > 50 MB e janela
fechada; o "Detalhe" técnico continua depois. Testes: `test_click_through_closes_tip_and_retries` e
`test_browser_error_text_explains_common_failures` (`publisher/tests/test_browser.py`); `pnpm test:publisher` → 76
passed (reexecutado na skill, 17/11/2026). **Só vale depois de reiniciar o `pnpm dev`** (item 137); o post desse envio
não chegou a ser feito e a correção **não foi testada num envio real**. O upload de 100+ MB funcionou nesse envio, o
que indica que o `is_local` (item 139) já valia. Onde: `publisher/app/platforms/session/common.py`,
`publisher/app/platforms/session/tiktok_studio.py`, `publisher/app/platforms/session/runner.py`.
143. **Corrigi o código, mas o envio/corte seguinte ainda se comportou como antes.** Sintoma (17/11/2026): o envio das
13:50 no TikTok durou 25 s, menos que a busca nova do link, e saiu sem link. Causa: o processo do Publicador (uvicorn
:4530) começou às 13:34:25; `tiktok_studio.py` (13:46), `common.py` e `runner.py` (13:46–13:47) foram gravados depois,
e o serviço roda sem `--reload`: rodou o código ANTIGO. Vale também para o Clipador (:4520) e a voz. Diagnóstico:
comparar o início do processo com a data dos arquivos, antes de culpar a correção:
`Get-CimInstance Win32_Process -Filter "Name='python.exe'" | Select ProcessId,CreationDate,CommandLine` (PowerShell) e
`Get-Item <arquivo> | Select LastWriteTime`. Arquivo mais novo que o processo = reiniciar o `pnpm dev` (do usuário,
item 131). Só dê "validado" a mudança em serviço depois de confirmar que o processo é posterior ao arquivo.
144. **Legenda do corte com `#RobRun` e `#ROBRUN` alternando ou tags genéricas (`#clã`, `#loot`).** Causa (antes de
17/11/2026): o juiz escrevia 3–5 hashtags livres na legenda. Hoje a legenda sai de `build_caption`
(`clipper/app/hashtags.py`): texto sem hashtags, tags de `compose` (canal, até 3 do jogo, até 4 do momento, sem
repetidas por `fold`, até 8) e crédito. Se o perfil do jogo **não tem `hashtags`** (caso do ROB RUN até a pesquisa ou
a edição), vale só o nome do jogo (`#ROBRUN`): use "Pesquisar de novo" ou edite a seção "Hashtags" na aba Jogos.
Legenda de corte antigo não muda; só corte novo ou "Mandar de novo para a IA". Só vale depois de reiniciar o
Clipador (item 143). Teste: `clipper/tests/test_hashtags.py`.
145. **Modo sessão (Instagram): "Já entrei" responde "não achei o botão Criar do Instagram" com a conta logada.**
Causa (17/11/2026, inspecionado ao vivo): no layout novo a barra lateral só tem ícones; o botão é `<a>` com
`<svg aria-label="Postar">` e abre direto o diálogo "Criar novo post" (sem submenu), com o `input[type=file]` dentro
do diálogo. O usuário também rodava código antigo (item 143). Correção: `SELECTORS["create"]` aceita "Postar"
(svg, link, botão); mensagem "botão Postar". Risco ligado: no feed cada post tem um botão de ícone "Compartilhar", e
`role=button ^Compartilhar$` podia clicá-lo; `next`, `share` e `reels_notice_ok` agora são CSS presos a `_DIALOG`
(`div[role='dialog']`). Teste: `test_buttons_of_the_flow_are_searched_inside_the_dialog`. Onde:
`publisher/app/platforms/session/instagram_web.py`. Fluxo e validação: [publishing.md](publishing.md).
146. **Instagram: rótulo de IA não liga, ou a legenda troca `#teste` por `#testemunho`.** Causa: com a legenda terminando
em `#tag`/`@menção`, o Instagram abre a lista de sugestões POR CIMA dos interruptores; um clique forçado
(`force=True`) no rótulo de IA caiu na lista (ensaio de 17/11/2026). O interruptor é `input role=switch` sem nome
acessível (achado pelo texto da linha, `find_ai_switch`). Correção: `close_suggestions` digita um espaço no fim
(Esc NÃO serve: fecha a caixa de criação); clique forçado removido; depois do clique `_is_on` confere e, se não ligou,
`PublishError` (não publica sem o rótulo). Teste: `test_instagram_links_and_hashtag_suggestions`. Regra geral: nunca
`force=True` em seletor de modo sessão (clica no que estiver por cima). Para validar seletor com conta real sem
publicar, rode só `prepare` e descarte o rascunho.
147. **Instagram: o reel saiu em 1:1 (quadrado), sem o topo do rosto do streamer; o TikTok saiu certo.** Sintoma
(17/11/2026, 1º reel real `/reel/Df2cezTNhY7/`, corte 68). Causa: a etapa "Cortar" do diálogo vem em 1:1 e o fluxo
clicava em "Avançar" direto. Correção: `keep_original_shape(page, sleep)` (`instagram_web.py`), chamada em `prepare`
antes dos "Avançar": clica em `svg[aria-label='Selecionar corte']` (ou 'Select crop') dentro do diálogo, escolhe
"Original" (opções: Original, 1:1, 9:16, 16:9) e fecha o menu. Sem o ícone ou sem a opção, `PublishError`: **não
publica cortado**. Sub-armadilha: o botão "Original" tem o texto mais o `<title>` do svg ("Ícone de contorno de
foto"), então `:text-is('Original')` não casa; usa-se `("role","button", r"^\s*Original\b")` e `:has-text` no
diálogo. Também `common.find` com `visible=True` agora olha até 6 ocorrências (`nth`) até achar uma visível (a
primeira pode ser cópia escondida); os falsos de teste ganharam `nth`. Validado (informado): ensaio sem publicar
mostrou a prévia "Novo reel" com o vídeo inteiro 9:16, rosto completo, legenda e rótulo de IA; rascunho descartado.
O usuário apagou o reel cortado à mão (a página mostra "Esta página não está disponível"). **Só vale depois de
reiniciar o `pnpm dev`** (item 143); nenhum envio real feito com o formato novo. Onde:
`publisher/app/platforms/session/instagram_web.py` (`SELECTORS["crop_toggle"]`, `["crop_original"]`), `common.py`.
148. **Corte publicado com rótulo de IA, ou "Perfil gerado por IA" sob o nome no Instagram.** Regra (pedido do dono,
17/11/2026): corte nunca leva rótulo de IA. Em `sendDue` (`publishing.ts`): `aiGenerated = job.source_kind === "clip"
? false : aiGeneratedFor(...)`, mesmo com o canal em "always". O texto "Perfil gerado por IA" visto no reel NÃO veio do
post: o job tinha `aiGenerated: False` e o canal estava em `ai_label=auto`. Provável rótulo do PERFIL (talvez foto de
perfil feita com IA e metadados); **não confirmado**. Episódio segue a regra de `aiGeneratedFor`.
149. **Vídeo publicado foi apagado na rede e o painel ainda o mostra como publicado (ou não deixa publicar de novo).**
Correção: ação "Apaguei na rede" (`removed`), só em job `published`. `markRemoved(id)` (`publishing.ts`) faz UPDATE
condicional para `canceled`/`user`, zera `url`, `remote_id`, `published_at`, grava o step "Apagado da rede por você…"
e apaga `publications WHERE job_id` (métricas saem em cascata). Depois, "Publicar" no corte reenvia com `attempts`+1
(novo `clientRef`). O painel NÃO apaga nada na rede: apague direto lá primeiro (a UI confirma). Rota
`POST /api/publishing/jobs/[id]/removed`; cliente `markJobRemoved`; botão em Publicadas (`publishing-board.tsx`).
Usada no job 3 (Instagram do corte 68). Teste em `publishing-db.test.ts`.
150. **Script Python de diagnóstico com `-I` imprime `?`/falha ao escrever acentos no Windows.** `python -I` ignora
`PYTHONIOENCODING` e `PYTHONUTF8`. Correção: no script, `sys.stdout.reconfigure(encoding="utf-8")`.
Relacionadas, já registradas acima:
- `codex.cmd` sem shell: item 28.
- Script de patch com regex (`\b`) passado por heredoc: item 44.
- Publicador roda sem `--reload`: mudança em `publisher/app/` só vale depois de reiniciar o `pnpm dev` (itens 137, 139, 140, 142, 143, 145 e 147; o Clipador também: 144).
- Migração do painel (v3 … v7) é aplicada na 1ª requisição depois da recarga do `db.ts`; reiniciar o `pnpm panel`/`pnpm dev` só se isso não bastar: itens 51 e 138 (reiniciar mata agente em execução: item 131).
@@ -0,0 +1,516 @@
# Painel: confirmação e aviso, formatos de história, leitor de roteiro, montagem documental (fotos do Commons, cenas 2D/3D e biblioteca, um clique), vertentes, votação, agentes (e mensagem durante a execução), exclusão, canais de publicação e dashboard
Fonte: código em `panel/src/lib/` e `panel/README.md`. O painel é do usuário: ele roda
`pnpm panel`; não inicie, não encerre, nada de `next build` com o dev ligado.
## Confirmação e aviso (`components/confirm-dialog.tsx`)
**Regra:** nada de `confirm()`/`alert()` nativos no painel (hoje não sobra nenhum em `panel/src/`). Use:
| Função | Uso |
|---|---|
| `askConfirm({ title, message?, confirmLabel?, cancelLabel?, tone? })` | `Promise<boolean>`; `false` em Cancelar, Esc ou clique no fundo. O handler que pergunta vira `async`: `if (!(await askConfirm({...}))) return;` |
| `showAlert({ title, message?, okLabel?, tone? })` | `Promise<void>`; um botão só (padrão "Entendi"), `role="alertdialog"` |
| `confirmSubmit(options, when?)` | `onSubmit` de `<form action={serverAction}>`: segura o envio, pergunta e, se confirmou, `form.requestSubmit(submitter)` com `data-confirmed="1"` (o 2º submit passa sem perguntar). `when()` decide se precisa perguntar. Usado em `delete-story-button.tsx` e `forms.tsx` |
- `tone: "danger"` → botão de confirmar vermelho e foco inicial em **Cancelar** (Enter não apaga por engano).
- `<ConfirmHost />` montado **uma vez** em `app/layout.tsx`; pedidos entram numa fila (um por vez; antes do host
montar, esperam num backlog). É `<dialog>` nativo com `showModal()`, então abre por cima de outros modais nativos
(ex.: `CutSettingsDialog` de `clipper-cut-settings.tsx`). Não monte um segundo host.
- `Button` (`components/ui.tsx`) tipa as props como `ComponentProps<"button">` e aceita `ref` (React 19).
## Banco (`data/cenaforge.db`, esquema v7)
- Migração em `panel/src/lib/db.ts` (lista `MIGRATIONS`). Banco com dados → cópia em `data/backups/`
antes de migrar (`cenaforge-v<atual>-<data>.db`). `foreign_keys = OFF` fora da transação e `PRAGMA
foreign_key_check` antes do `COMMIT` de cada versão.
- v3: `account_channels` (conta ↔ canal de live do Clipador; `status` `active`/`ended`). O canal
vive em `data/clipper/clipper.db`, então não há chave estrangeira para ele.
- v4: reconstrói `stories` (SQLite não altera CHECK) para `kind` aceitar `'documentary'`; mesmas
colunas e ids.
- v5: publicação real — `publish_jobs`, `app_settings`, `clip_auto_approvals`; `account_networks` e `publications`
reconstruídas (sem `mock`; `publications.clip_id`/`job_id`); colunas novas em `accounts` (`approval_mode`, `timing`,
`ai_label`, `auto_since`) e `episodes` (`approved_at`, `approved_render_id`, `publish_title`, `publish_caption`).
Detalhe em [publishing.md](publishing.md) e `doc/publicacao/PLANO.md` §4.
- v6: reconstrói `publish_jobs` (ids preservados) com `schedule_source` (`auto`/`manual`/`now`) e `cancel_reason`
`unlinked`. Banco real em v6 (`PRAGMA user_version`, conferido em 17/11/2026, antes da v7).
- v7: `publish_jobs.origin` (`link`/`manual`, padrão `link`): job criado pelo botão "Publicar" do corte. Ver publishing.md.
- API: toda rota `/api/**` passa por `panel/src/proxy.ts` (Host local; escrita exige `Origin` do painel) e corpo por
`readJson` (415 sem `Content-Type: application/json`) — gotchas, item 125.
- A conexão fica em `globalThis.__cenaforgeDb`; a marca de módulo `checkedThisModule` faz a 1ª chamada de `db()` depois
de recarregar o código rodar `migrate()` no banco aberto (backup em `data/backups/`) → esquema novo entra na 1ª
requisição, sem reiniciar. Só se o `db.ts` não foi recarregado é preciso reiniciar o `pnpm panel` (gotchas, itens 51 e 138).
- Testes do painel: `pnpm --filter cenaforge-panel test:panel` (`panel/src/lib/*.test.ts`, node:test via tsx). Teste que
importa algo que abre o banco precisa de `CENAFORGE_ROOT` numa pasta temporária (gotchas, item 99).
## Formatos de história (`kind`)
Lista em `STORY_FORMATS` (`components/story-formats.ts`, rótulo curto `storyFormatLabel`) + tipo
`StoryKind`/`STORY_KINDS` (`lib/types.ts`). Formato novo também exige migração do CHECK em `db.ts`.
| `kind` | O que é | Arquivos |
|---|---|---|
| `interactive` | episódios ~12 s terminando em votação A–D (2–4 vertentes) | `biblia.md`, `<file_key>.md`, `.choices.json` |
| `linear` | episódios de ficção em sequência, sem votação (`branch_count` = 1) | `biblia.md`, `epNN.md` |
| `documentary` | **vídeo único** vertical sobre tema real, nomes reais, fato com fonte, sem votação | `biblia.md` = ficha de pauta; `ep01.md` = roteiro (formatos em `doc/roteiro/documental.md`) |
- Regras de texto e formato dos arquivos: **`doc/roteiro/`**, fonte única para Claude e Codex.
`comum.md` (idioma, onde escrever, estrutura do vídeo curto, limites do overlay, produção, retorno;
tabela formato → guia) + `ficcao.md` (interativa/linear: sem cidade, marca ou pessoa real, A/B no fim,
formato de `biblia.md` e `ep<NN>.md`) ou `documental.md` (nomes reais, fato com fonte, mito × fato,
45–90 s, ficha de pauta e roteiro). 1ª linha da `biblia.md`: `Formato: interativa | linear | documental`.
- Aba Fluxo: tudo que não é `interactive` usa layout em linha (`story-flow.tsx`).
- Termos na interface: `unitTerms(kind)` (`story-formats.ts`) → `{one, One, many, Many, code(n)}`. Série =
"episódio"/`ep01`; documental = "vídeo" (`code(1)` = "vídeo", `code(n)` = "vídeo n"). Usado no console do
agente (campo "Episódio" vira "Vídeo"; `StoryOption` tem `kind`), no cartão da página inicial, na página da
história (aba, contagem, criar) e na do episódio (breadcrumb, eyebrow "Vídeo documental", metadata). Texto
novo que fale da unidade usa `unitTerms`, não "episódio" fixo. O **arquivo** continua `episodeCode` (`ep01.md`).
- `createStoryFromTextAction`: no documental o episódio nasce sem título ("Abertura" só em série).
## Leitor de roteiro (`lib/script-doc.ts` + `components/script-reader.tsx`)
- `parseScript(md)` (puro, sem servidor) → título, metadados, `facts` (pares `Chave: valor` separados por " · "),
seções com `role` deduzido do título (`hook`, `shots`, `sources`, `needs`, `cover`, `overlay`, `summary`, `ending`,
`consequences`, `other`), `shots`, `targetSeconds`, `narrationWords`. Trechos = a **primeira tabela cuja 1ª coluna
é "t (s)"/tempo**; as outras colunas são achadas pelo cabeçalho (imagem/b-roll, texto na tela, narração/diálogo).
Mudar o cabeçalho em `doc/roteiro/` (`documental.md`, `ficcao.md`) pode quebrar a leitura.
- Tempo falado = palavras / `WORDS_PER_SECOND` (2,5). Alertas: narração total > 1,1× a duração alvo; trecho com
narração > 1,15× a duração dele ("mais longa que o trecho").
- `ScriptReader` não usa HTML cru: markdown em linha próprio (negrito, itálico, código, links/URLs com
`target="_blank" rel="noopener noreferrer"`). Mostra resumo, "Copiar narração" (`components/copy-button.tsx`),
"Gerar áudio em Vozes" (só um link para `/voices`; não leva o texto), gancho, régua do vídeo com âncoras
`#trecho-N`, cartão por trecho, texto de capa com contagem de caracteres, fontes com domínio, necessidades de
produção e o .md original recolhido.
- Usado em `app/stories/[storyId]/episodes/[number]/page.tsx` e na página só de leitura `.../[number]/roteiro/page.tsx`.
Página da história: botão "Ler roteiro" → último episódio com roteiro.
- Documental na página do episódio: roteiro primeiro (`order-first`), título do roteiro, eyebrow "Vídeo documental";
sem "Montar cena" nem render da rua 3D — no lugar, o passo a passo "Como este vídeo é feito" e o card "Montagem do
vídeo" (seção abaixo).
## Montagem documental
Card "Montagem do vídeo" (`components/montage-editor.tsx`) na página do vídeo documental. Regras de texto em
`doc/roteiro/comum.md` e `documental.md` (seção "Como o vídeo é montado"). **Decisão do dono (17/11/2026): a geração
é automática, num clique; o admin só revisa e troca.**
- **Um trecho = uma linha da tabela "t (s)"** do roteiro (`parseScript`). Cada trecho tem:
- **áudio próprio**, um parágrafo por vez (decisão do dono: áudio longo deixa a voz estranha), gerado do **texto
falado**: editável, nasce de `toSpokenText(narração)` (`lib/speech-text.ts`: números até bilhões, decimais
"0,0055" → "zero vírgula zero zero cinquenta e cinco", milhar "1.500", km, m², ha, cm, kg, %, "por m²"). Texto na
tela que é pergunta e que a narração não repete entra antes da fala ("Uma cobra por metro quadrado? Não. ...");
- **visual** (`VISUAL_KINDS` em `lib/montage.ts`; rótulo da UI entre parênteses): `image` (Foto), `godot2d`
(Animação 2D), `godot3d` (Cena 3D da biblioteca), `video` (Clipe: envio ou render Godot já feito), `card`
(Cartela, sem arquivo). Pode misturar. `ShotVisual`: `scene` + `sceneKey` (Godot), `search {queries, pick}` (foto
da internet), `auto` (escolhido pelo automático; trocar à mão grava `auto: false`), `inset` (cartão de foto por
cima do visual; na UI, `InsetCard`: "Outra foto", "Tirar", "Pôr foto da internet").
- **Estilo do vídeo** (`style` no `.montage.json`, `PATCH {style}`; seletor "Estilo do vídeo" no topo): `"mixed"`
(padrão: foto, 2D e 3D) ou `"3d"` ("Tudo em 3D": todo trecho vira cena 3D da biblioteca, fotos só em cartão).
Regras de roteiro para isso: "Vídeo todo em 3D" em `doc/roteiro/documental.md` (coluna Imagem = tomada 3D,
`[foto: termos]`, cenas 3D que faltam em "Necessidades de produção").
- **Cartões de informação em sequência:** texto na tela `A; depois: B; depois: C` mostra as partes uma após a outra,
dividindo o tempo do trecho.
- Topo do card: **"Gerar vídeo automático"** (etapa do `job` + Cancelar), **"Refazer tudo do zero"** (`replan`) e
modo manual: voz pt-BR, velocidade 0,7–1,3 na UI (o servidor aceita 0,5–2), legenda, "Gerar N áudios", "Só montar".
- Por trecho: estilos em grade (3 colunas; 5 a partir de `sm`), **"Gerar de novo"** (ou "Buscar na internet" na foto
sem arquivo) e `SceneEditor`: 2D = modelo (`DOC2D_TEMPLATES`) + campos; 3D = seletor da biblioteca + formulário
gerado do manifesto + link "Peça uma nova ao agente" (`/agent?kind=godot&story=…&prompt=…`). "Prévia da cena" =
`renderShotScene` ← `POST .../montage/scene`.
- Envio de visual (multipart): **licença opcional** (padrão "não informada", decisão do dono), crédito e link
opcionais; vira asset da história (`AssetKind` `image`/`video`). Também dá para escolher da biblioteca/assets da
história ou dos renders Godot com `status = 'success'`.
- Estado: `stories/<id>/<file_key>.montage.json` (`voiceId`, `speed`, `captions`; por índice `spoken`, `visual`,
`audio{file, durationMs, key}`). Áudio: `stories/<id>/audio/<file_key>-NN.ogg`. Config de cada cena Godot:
`stories/<id>/godot/<file_key>-tNN.json`. `audioKey` = hash de voz + velocidade + texto falado; `sceneKey` = hash
de `kind` + modelo + params + duração (fala + pausa). Mudou → aparece desatualizado.
### Plano do trecho (`lib/montage-godot.ts`, sem banco, sem IA)
- `scriptEntities(md)`: nomes científicos (itálico binomial, `*Bothrops insularis*`) e lugares de `MAP_PLACES` citados.
- `planShot(shot, {species, places, library}, variant)`, nesta ordem:
1. `planScene` deu `map` ou `counter` → cena 2D;
2. 1ª oração da coluna Imagem cita animal ou objeto real (placa, pesquisador, navio, foto…) → foto; buscas = nome
científico, "Farol <ilha>" (se fala de farol), a ilha; nada achado → cena 2D de reserva;
3. `matchLibrary(coluna Imagem)` → cena 3D (`paramsFor` escolhe cada `select` pelas keywords das opções);
4. título 2D.
- `planShot3d(shot, ctx, index)` (estilo `"3d"`): cena `doc3d` por `matchLibrary` na coluna Imagem, depois na Imagem +
narração, senão a primeira da biblioteca; `params` por `paramsFor` + `variant = índice do trecho`. Cartão de foto
(`insetQueries`) só com `[foto: termos]` na coluna Imagem ou animal real (`ANIMAL`) na 1ª oração — aí busca os nomes
científicos do roteiro; barco, navio e personagem ficam na cena 3D, sem cartão. Biblioteca 3D vazia → erro pedindo
cena ao agente.
- `planScene(shot)`: ≥ 2 lugares conhecidos, ou 1 lugar + "mapa/litoral/km" → `map` com rota cidade → ilha e rótulo
"N km" (tirado do texto); número no texto na tela → `counter` (kicker = texto antes do número; rótulo completado
pela narração, ex.: "jararacas por hectare"); resto → `title`. "São Paulo" só vira marcador se o texto disser
cidade/capital ("litoral de São Paulo" é o estado).
- `MAP_PLACES` **tem de ficar igual** a `PRESETS["litoral-sp"].places` de `godot/scripts/doc/doc2d_canvas.gd` (a
Godot resolve lat/lon pelo nome).
- `renderGodotScene` grava o JSON (`kind` `doc2d`/`doc3d`, 1080×1920, 30 fps, duração da fala + pausa) e chama
`scripts/cli.ts render --config <json> --profile final` pelo `node_modules/tsx/dist/cli.mjs` (sem shell); o MP4 é
lido da linha `MP4: ...` da saída.
- Modelos 2D (`variant` muda o visual): `title` (3 layouts por `variant % 3` — centro, editorial à esquerda com
barra, embaixo com sublinhado; destaque brasa/ciano/violeta), `counter` (conta em pt-BR 1.500 / 0,0055 com anel que
fecha; `grid` opcional), `map` (voo: começa aberto, zoom 0,45 em `variant` par ou 0,62 em ímpar, desce até a rota em
1,6 s, a linha começa em 1,5 s e o destino pulsa; terra estendida 8° além dos limites; km pela haversine se faltar o
rótulo; "Mapa ilustrativo" no rodapé — a costa é aproximada).
### Fotos da internet (`lib/image-search.ts`)
- `searchCommons(q)`: API do Wikimedia Commons, sem chave, User-Agent genérico; `filetype:bitmap`, menor lado ≥ 900
px, descarta títulos com mapa/diagrama/logo/brasão/bandeira/gráfico; URL em 1600 px. `searchFirst(queries)` tenta
as buscas em ordem; `downloadImage` baixa.
- `applyInternetImage(ep, shot, queries, startPick, used, "main" | "inset")` (`lib/montage.ts`) pula imagem já usada
noutro trecho (`sourceUrl`; fotos principais e cartões juntos) e cria o asset `image` com crédito (autor), licença e
origem (página do Commons), que vão para a cartela de créditos. `"inset"` grava no cartão do trecho.
- Medido (17/11/2026, informado): "Bothrops insularis" → fotos reais da espécie (Butantan, Otavio Marques); "Ilha da
Queimada Grande" → farol e navio da Marinha; termo genérico ("aves migratórias") → lixo. Por isso as buscas usam
nomes do roteiro, nunca descrições genéricas.
### Biblioteca de cenas 3D (`godot/library/`)
- Cena = `godot/library/<id>/template.gd` (`extends Node3D`: `setup(cfg, viewport_size)`, `apply(t)`,
`state_signature()`) + `manifest.json` (`id`, `kind: "doc3d"`, `label`, `description`, `keywords`, `params` com
`type` `select`|`bool`|`number`|`text`, `default` e `options[{value, label, keywords}]`). Guia para agentes:
`doc/godot/cenas.md`.
- O painel lê sem banco (`lib/scene-library.ts`): `listLibrary()`, `matchLibrary(texto, lib)` (mais keywords
achadas), `paramsFor(cena, texto)`. Cena nova aparece sozinha no seletor, no formulário e na escolha automática.
- `island` ("Ilha costeira"): terreno FastNoiseLite com sementes fixas, 5.200 árvores em MultiMesh,
rochas, farol listrado com lanterna pulsando; mar por shader com `uniform scene_time` (determinístico), turquesa
perto da costa, plano de 16 km (horizonte sem emenda); ProceduralSky, ACES, névoa leve. Params `shot`
`orbit`|`approach`|`lighthouse`|`lowpass`, `time` `day`|`sunset`|`night` (céu escuro, lua azulada, farol forte),
`lighthouse` (bool); `variant` muda **só a câmera** (ângulo e sentido). Como cenário de outra cena: `embedded: true`
(sem câmera própria), `environment: false` (sem céu e luz), `sea_detail: true` (malha fina do mar perto da câmera);
métodos `height_at` (ruído) / `ground_at` (malha desenhada: apoio de pés e pedras) / `ground_normal`,
`sea_height(x, z, t)`, `set_sea_state(escala)`, `set_sea_focus(x, z)`, `rock_list()`, `lighthouse_position()`.
- `castaways` ("Náufragos no costão", caso real da Ilha das Cobras, 2019): `moment`
`arrival`|`sinking`|`swimming`|`waiting`|`rescue`|`boarding`|`departure` (keywords tiradas da coluna Imagem do
roteiro), `camera` `medium`|`close`|`wide`, `variant`. Peças na pasta: `shore.gd` (estende a ilha com laje de
costão), `actor.gd` (estende `person.gd`), `cast.gd` (elenco e barcos), `sky.gd` (céu por hora, mistura noite → dia),
`verify.gd` (determinismo e apoio: `Godot --headless --path godot --script res://library/castaways/verify.gd` →
`CASTAWAYS_OK 84 estados`). Feita pelo agente do painel: Claude (#7) e Codex (#8), cada um parou no limite de uso.
- **Kits** `godot/kits/` (não são cenas; o painel não lista): `person.gd` — pessoa low-poly com juntas `hips`, `spine`,
`chest`, `neck`, `head`, `shoulder|elbow|hip|knee_l/r`; `build({shirt, pants, skin, hair, shoes, vest, height,
sleeveless, shorts})`, `pose(action, t)` (`idle`, `walk`, `run`, `swim`, `sit`, `wave`, `kneel`, `lie`, `exhausted`),
`blend(a, b, t, k)`. `boat.gd` — lancha/pesqueiro ~8 m (casco SurfaceTool, cabine, mastro, luzes de navegação):
`build({hull, stripe, cabin, lights})`, `float_on(t, intensidade)`, `sink(0..1)`, `deck()` (convés). Uso, cena
dentro de outra e `.glb` por `GLTFDocument` em tempo de execução: `doc/godot/cenas.md`.
- Cena nova pelo painel: tarefa "Cena no Godot" do agente (seção "Agentes e modelos").
### Gerar o MP4 (`startMontageRender(id, { auto, replan })`)
- `auto: false` ("Só montar"): exige áudio atualizado e visual em todos os trechos (menos cartela); as cenas Godot
(2D e 3D) desatualizadas são renderizadas também neste modo.
- `auto: true` ("Gerar vídeo automático"): planeja com `planShot` os trechos sem visual (com `replan: true`, "Refazer
tudo do zero", também os `auto` e as cenas Godot antigas sem a marca; o que o admin escolheu fica); sem voz usa a
pt-BR padrão do serviço (`getStatus`); gera os áudios que faltam; renderiza as cenas Godot com `sceneKey` velha; monta.
- `regenerateShot(id, index, target)` (`POST .../montage/regenerate {index, target}`): `"visual"` (padrão) — cena Godot
→ `variant + 1` e re-render; foto da internet → próxima da busca (sem repetir as dos outros trechos); foto enviada →
busca; cartela e clipe → erro. `"inset"` → outra foto no cartão (busca do cartão, do `planShot3d` ou nomes
científicos; sem termos → pede `[foto: termos]`). `"remove-inset"` → tira o cartão.
- Uma montagem por vez. Progresso em memória: `montageJob(episodeId)` → `job: { renderId, progress }` no GET (não
sobrevive a reiniciar o painel). Grava em `renders` com `profile = 'documentary'`; saída
`output/documentary/<story>-<file_key>-<stamp>/<story>-<file_key>.mp4`, log `data/logs/renders/<id>.log`.
- FFmpeg em `lib/montage-ffmpeg.ts` (**sem banco**, testável sozinho: gotchas, item 99): `buildSegment`,
`buildCredits`, `concatSegments`. 1080×1920, 30 fps, H.264 CRF 20 + AAC 48 kHz estéreo.
- Foto horizontal (aspecto > 0,8): fundo = a própria foto desfocada (`boxblur=32`, brilho −0,12), foto a 118% da
largura (até 62% da altura), zoom de 8%, um pouco acima do meio. Foto vertical: cobre a tela com `zoompan`. Pares
aproximam, ímpares afastam. A entrada de áudio varia com o visual (`audioInput`). Vídeo: `-stream_loop -1` + crop.
- Texto na tela (y = 13%; na cartela, centro) e legenda (y = 74%) por `drawtext` com `textfile=` e
`expansion=none`; grafo em `-filter_complex_script`; cwd = pasta de saída (arquivos relativos). **`godot2d` não
recebe o texto na tela** (a cena já mostra); `godot3d` recebe; a legenda continua em todos. Texto na tela com
mais de 26 caracteres usa fonte 54 (senão 66); `; depois:` divide em partes sequenciais.
- Cartão de foto (`plan.inset`): foto a 62% da largura com borda branca de 12 px, topo a 21% da altura; entra em
0,3 s (fade de 0,35 s subindo 50 px) e sai 0,4 s antes do fim; crédito "Foto: autor" embaixo.
- Legenda = narração escrita em pedaços de até 30 caracteres, tempo proporcional; pedaço < 12 caracteres junta
ao anterior.
- Duração do trecho = fala real + `PAD_S` 0,35 s (último + `LAST_PAD_S` 0,9 s), não o tempo da tabela (gotchas,
item 102). Cartela final de 3,5 s (`CREDITS_S`) com créditos das imagens e domínios das fontes (só se houver).
Junção com `-c copy`.
- Rotas: `GET|PATCH /api/episodes/[id]/montage` (GET traz também `templates` e `job`), `POST .../montage/audio`
(`{index}`), `POST .../montage/scene` (`{index}`), `POST .../montage/regenerate` (`{index, target?}`),
`POST .../montage/upload` (multipart), `POST .../montage/render` (`{auto, replan}`) e
`DELETE .../montage/render?render=<id>`. `/api/files` serve também `.webm`, `.mov` e `.mkv`.
- **Provado de ponta a ponta (17/11/2026, "Tudo em 3D"):** agente `story` (Codex, #6) pesquisou e escreveu
`stories/naufragos-na-ilha-das-cobras/ep01.md` com fontes; agentes `godot` #7 (Claude) e #8 (Codex) fizeram
`castaways`; "Refazer tudo do zero" planejou 11 trechos (1–9 `castaways` nos momentos certos, 10–11 `island` orbit
com cartão da jararaca, fotos do Commons diferentes). MP4 em `output/documentary/naufragos-na-ilha-das-cobras-ep01-*/`:
101,7 s, 1080×1920, h264 + aac (ffprobe). Cenas finais 1080×1920 de 2,8–12,3 s em 9,8–89,7 s cada (`report.json`);
total ~9 min (informado). Quadros conferidos pelo agente que montou (não refeito aqui).
## Agentes e modelos (`lib/agents.ts`, `lib/prompts.ts`)
- `buildPrompt({ kind, provider, ... })` inclui `writingRules(provider, story.kind)` (guias em
`GUIDE_COMMON`/`GUIDE_BY_KIND`): no **Claude** manda delegar ao subagente `cenaforge-story-writer`
informando o formato (o subagente é uma casca que lê `doc/roteiro/`; sem WebSearch, fato sem fonte fica
"a confirmar"); no **Codex** manda ler os guias e escrever sozinho, sem usar `.claude/agents/` (mesma
regra no `AGENTS.md`).
- Lista de modelos = `models()` (não há mais constante fixa):
- Codex: lê `models_cache.json` de `$CODEX_HOME` (padrão `~/.codex`), que a CLI do Codex atualiza
sozinha; filtra `visibility === "list"`, ordena por `priority`. Primeira opção "Padrão da CLI (…)"
= `model = "..."` do `config.toml`. O id vai em `codex exec -m <slug>`. Em 17/11/2026: 8 modelos
(gpt-6.1-sol, gpt-6-astra, gpt-6.1-terra, gpt-6-sol, gpt-6-luna, gpt-5.6-sol/terra/luna).
- Claude: `claude-fable-5-2`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5` (via
`claude --model`); apelidos `opus`/`sonnet`/`haiku` ainda aceitos ao retomar execuções antigas.
- Padrão: `DEFAULT_MODEL` só vale no Claude (`scene` e `branches` = `claude-sonnet-5-5`; demais = padrão
da CLI); no Codex, sempre o do `config.toml`. Provedor preferido por tarefa: `PREFERRED_PROVIDER`
(story/script/branches = Codex; `godot` = Claude).
- Tarefa `godot` ("Cena no Godot", `AgentKind` em `lib/types.ts`): o prompt (`prompts.ts`) manda seguir
`doc/godot/cenas.md`, reaproveitar a biblioteca (`godot/library/island/` de referência), renderizar e olhar os
quadros, e não mexer em `godot/scripts/`, `scripts/` nem `panel/`. O console (`/agent`) aceita `?prompt=` como
pedido inicial (link "Peça uma nova ao agente" do `SceneEditor`).
- "Nova história com IA" (`components/story-composer.tsx`) tem seletor de modelo (campo `model`, lido
em `createStoryFromTextAction`, `app/actions.ts`). Por script: `POST /api/stories {text, title?, kind?, provider?,
model?}` (`app/api/stories/route.ts`; `kind` padrão `documentary`, texto 20–20.000 caracteres) cria a história + ep01
e dispara o agente `story` → `{storyId, episodeId, runId}` (cabeçalho `Origin`: gotchas, item 125).
- O agente roda dentro do processo do painel: reiniciar o `pnpm panel` o mata (gotchas, item 131). Limite de uso do
Claude/Codex para a tarefa no meio: continue no outro provedor com o contexto (item 132).
- Prompt do Codex manda ler texto no PowerShell com `Get-Content -Raw -Encoding UTF8` (gotchas, item 98).
### Mensagem com o agente rodando
- Console (`components/agent-console.tsx`): durante a execução a caixa de pedido fica liberada com dois botões —
**"Corrigir agora"** (também Ctrl+Enter: interrompe e retoma a mesma sessão com a correção) e **"Enviar ao
terminar"** (fila; envia quando o agente fechar). Uma mensagem por vez: a nova substitui a da fila.
- Rota `POST /api/agent/runs/[id]/messages` com `{text, mode: "now"|"queue"}` → `sendFollowUp(id, text, mode)`.
`ActiveRun` tem `emit`, `followUp` e `progressed` (vira `true` no 1º evento que não seja `system`, `stderr`
nem `error`). "now" exige `session_id` **e** `progressed` (senão recusa: gotchas, item 97); marca a execução
`cancelled` (error "interrompida para correção") e chama `killTree`.
- No `close`, havendo `followUp`, `startRun({..., resumeRunId: id})` roda **antes** de avisar os ouvintes, então o
"end" do SSE já leva `followUpRunId` (`followUpRunOf(id)`, `resume_of = id`) e o console troca para a
continuação, mostrando o texto do usuário como pedido. Falhou a continuação (executor ocupado, sem
`session_id`) → evento de erro pedindo para reenviar.
- A rota de events só manda `followUpRunId` no fim **ao vivo** (`finish(true)`): abrir uma execução antiga do
histórico não pula para a continuação.
## História interativa = árvore de vertentes
| Conceito | Onde |
|---|---|
| Vertentes por episódio | `stories.branch_count` (1–4; linear = 1; interativa ≥ 2, escolhido na criação, campo `branchCount` de `createStory` em `stories.ts`) |
| Arquivos do episódio | `file_key` (`ep01`, `ep02-b`) → `stories/<id>/<file_key>.md`, `stories/<id>/<file_key>.choices.json`, `config/<id>-<file_key>.json` |
| Estado do episódio | `status` `main` / `candidate` / `discarded`; `branch_label`; `branches_status` `none`/`queued`/`running`/`ready`/`error` |
| Votação A–D | `decisions.ts`: `parseVote(text, letras)`, `tally`, `leader()`, `closeDecision`; votos em `votes_json` |
| Gerar vertentes | `branches.ts`: `prepareBranches` cria as candidatas e **uma** execução de agente (tarefa `branches`; Codex preferido — modelo em "Agentes e modelos") que escreve roteiro, cena e `.choices.json` de cada vertente |
| Fila | um agente por vez; o próximo `queued` é puxado em `onAgentRunClosed` |
| Fechar votação | `closeDecision`: vencedora vira `main`, irmãs `discarded`, e o próximo nível é preparado sozinho (`prepareBranches(..., { auto: true })`) |
| Árvore na tela | `flow.ts` (`storyFlow`, layout em árvore próprio) + `components/story-flow.tsx` (`@xyflow/react` 13.0.1); aba Fluxo da história |
Regra: só o **próximo nível** é gerado — nunca a árvore inteira de uma vez.
Limitação: o overlay da Godot só tem `choiceA`/`choiceB` (`scene_config.gd`); C/D existem só no
`.choices.json` e no painel. Cores das opções: `CHOICE_STYLE` em `components/ui.tsx`, tokens
`--color-option-c`/`--color-option-d` em `app/globals.css`.
## Canais de publicação e dashboard
- Canal de publicação = tabela `accounts` (no código continua "account"; na UI, "Canal de publicação", rota
`/accounts`, `components/account-manager.tsx`): várias histórias ativas por canal, uma história em vários canais.
Redes conectadas de verdade (API oficial ou sessão logada) — tudo de publicação em [publishing.md](publishing.md).
- Dashboard (`metrics.ts`, `/dashboard`, primeiro item do menu; `metrics-view.tsx`,
`dashboard-controls.tsx`): totais, por rede/conta/história/episódio, melhores e piores.
Métricas continuam **simuladas** (`simulated = 1`; `simulateMetrics` / `clearSimulated`); publicação real grava
`publications` com `simulated = 0`. Não apresente números simulados como reais.
- Fontes do Clipador (no código `channels`): card "Fontes de corte" em `account-manager.tsx`, rotas
`POST /api/accounts/<id>/channels` (ligar) e `DELETE /api/accounts/<id>/channels/<channelId>` (encerrar). Cortes
das fontes ligadas entram na fila de publicação do canal. Veja [clipper.md](clipper.md).
- Página da história: abas Episódios | Fluxo | Contas.
## Excluir história
- `deleteStory(id)` (`lib/stories.ts`) ← `deleteStoryAction` (`app/actions.ts`, campo `storyId`, redireciona
para "/") ← `components/delete-story-button.tsx` (`confirmSubmit` com `tone: "danger"`; erro no modo `compact`
por `showAlert`). Aparece como ícone (`compact`) no canto
inferior direito do cartão em "Biblioteca · Em produção" (`app/page.tsx`, **fora** do `<Link>`: botão dentro de
`<a>` é inválido) e como "Excluir" no cabeçalho de `app/stories/[storyId]/page.tsx`.
- Recusa se houver `agent_runs` `running` da história ou `renders` `running` de algum episódio dela.
- **Arquivos primeiro, banco depois; nada é apagado de vez:** `stories/<id>/` (com `.choices.json` e
`assets/`) → `data/trash/<id>-<timestamp>/stories/`; `config/<id>-<file_key>.json` dos episódios do banco →
`.../config/`. Recuperar = mover de volta à mão (não há botão). MP4s em `output/` não são movidos.
- Depois, numa transação: apaga `assets` com `scope='story'` (sem isso ficariam órfãos, pois
`assets.story_id` é `SET NULL`) e a linha de `stories`. CASCADE leva episódios, comentários, decisões,
publicações/métricas e `account_stories`; `agent_runs.story_id` e `renders.episode_id` viram NULL (histórico fica).
- Ainda **não existe** exclusão de asset da biblioteca (`assets/library/`).
## Página `/clipper` (Clipador)
- `clipper-cut-settings.tsx`: modal "Configuração do corte" em cinco abas — Formato e duração (com a seção
"Qualidade da gravação" e o disco por hora de cada opção, de `captureQualities`) · Câmera e layout · Legenda (com
seletor de fonte) · Gancho (estilo, cores, fonte, animação de entrada, "Ver a entrada") · Crédito — com a prévia ao
lado mudando de proporção (`frames` da rota de settings). Durações mostradas como "1:30 · 90 s", com o padrão lido
de `defaults`. Desenhar o retângulo da câmera sobre o quadro (`…/frame`),
prévia (`…/preview`), achar webcam (`…/detect-cam`), salvar na sessão ou como padrão do canal.
- `clipper-client.ts`: tipo `Aspect`, `format` em `CutSettings`, `aspect?` em `Clip`, `aspectOf()` (ausente =
vertical) e `withFormat()` (completa a resposta de um serviço antigo sem `format`). Na fila (`clipper-queue.tsx`)
o corte horizontal aparece em 16:9.
- Aba Sessões (`clipper-sessions.tsx`; cabeçalho em `clipper-studio.tsx`): cartão com cabeçalho (tempo gravado,
"gravando em L×A · fps" de `capture` e ações), frase de saúde (`sessionHealth()`), painel "o que está acontecendo" (resumo da IA + jogo), quatro blocos
(Chat, Transcrição, IA assistiu, Cortes) e barra de ferramentas. **Altura fixa por desenho**: nada pode pular na
atualização automática. "Retomar gravação" aparece em toda live que não está gravando (botão principal só em
`interrupted`). Cartão na grade leva `[contain:inline-size]` (gotchas, item 91).
- **Relógio da gravação** (`RecordingClock`): o tempo gravado corre segundo a segundo entre as consultas
(`setInterval` de `CLOCK_TICK_MS` 250 ms por cartão, só gravando e com a aba visível); ressincroniza com o
`durationS` real sem voltar. Passou `CLOCK_MAX_AHEAD_S` (45 s) além do último `durationS`: para e mostra
"aguardando o bloco" com o selo em alerta (ao voltar à aba, espera 6 s antes de acusar).
- **Cadência do resumo** (`SummaryCadence`): ao lado de "Agora na live", "atualiza a cada 3 min · próximo em m:ss";
atrasou, "gerando o próximo resumo…". O intervalo vem de `/status` → `judge.options.scanIntervalS`
(`useScanInterval`; reserva 180 = `OPTION_DEFAULTS` de `intel.py`). Existe porque o dono achou que o resumo
travava (gotchas, item 115).
- `clipper-games.tsx`: aba Jogos e emotes. O card do jogo tem selo de iniciais (primeira + última palavra, cor
por `hueOf`) e os botões "Conversar com a IA", "Editar" e "Pesquisar de novo". Cada seção é um cartão com
barra colorida, contador e "Pedir à IA", que abre o chat inline `AiChat` (balões, atalhos de pedido por seção,
indicador de digitação, "+N itens novos / −N removidos"). Item novo fica verde com selo "novo". Gírias viram
chips, e Fontes e "Memória da IA" ficam recolhidas. A aba também mostra os emotes do canal com usos e peso.
Rotas e regras em [clipper.md](clipper.md#perfil-do-jogo-aba-jogos).
- `clipper-queue.tsx`: cartão do corte mostra a análise do juiz e recua/avança o início (`START_STEPS`
−30/−10/−5/−2/+2 s). `clipper-judge.tsx`: modelos do editor e do analista, varredura, visão, câmera.
- `clipper-queue.tsx` também tem o botão "Editar" (ou "Continuar edição" se `edit.origin === "user"`) que abre o
editor.
- **Apagar na fila** (`clipper-queue.tsx`; regras do serviço em [clipper.md](clipper.md#apagar-cortes-clip_deletepy)):
"Apagar" em cada cartão, com confirmação no próprio cartão. Seleção **discreta** (o dono reprovou uma barra presa
no topo e pediu "bem sutil, no cantinho"; gotchas, item 116): no canto da linha das abas, "Selecionar" e o menu
"⋯" ("Apagar todos desta aba (N)", modal com a contagem e aviso do filtro de sessão); a caixa de cada cartão só
aparece no hover, no foco ou no modo de seleção; com o modo ligado, a pílula flutuante `SelectionPill` no canto de
baixo ("N selecionados · Selecionar todos · Apagar · ✕", vermelho só no hover). Esc sai do modo. Nada disso ocupa
espaço na página. Manda os ids mostrados em lotes de `CLIP_DELETE_MAX` por `POST clips/delete`; resultado em
aviso fixo (`deleteSummary`). Estados que não se apagam: `UNDELETABLE_CLIP` em `clipper-client.ts`.
- Toda rota nova do serviço precisa entrar na regex `ALLOWED` de `panel/src/lib/clipper.ts` (e, se for lenta, no
timeout por rota do mesmo arquivo; se só alguns métodos valem, em `METHODS`). Detalhes em [clipper.md](clipper.md).
## Editor de cortes
Página `/clipper/edit/[clipId]` (`panel/src/app/clipper/edit/[clipId]/page.tsx`). Projeto, rotas e render em
[clipper.md](clipper.md#editor-de-cortes-clippereditid); fonte completa em `clipper/README.md`.
- **Tela cheia sem mexer no layout raiz:** o componente cobre o rail com `nle fixed inset-0 z-[70]` e trava a rolagem
do documento só nessa página. Tudo cabe em 100vh; cada painel rola sozinho.
- **Desenho de editor de vídeo (NLE):** cores só pelos tokens `--color-nle-*` (classes `bg-nle-panel`,
`text-nle-dim`…) e pelo bloco `.nle` de `panel/src/app/globals.css`; peças prontas em `clip-editor-ui.tsx`. Não use
os tokens do resto do painel dentro do editor.
- Disposição: cabeçalho (Fila, desfazer/refazer, "Projeto da IA", descartar, título e origem, estado do salvamento,
**Salvar projeto**, botões que minimizam Camadas, Transcrição/Chat e Propriedades, "IA sugere", atalhos, status,
Exportar) · Camadas |
Transcrição/Chat | monitor "Fonte · Programa" | Propriedades · timeline na largura toda + medidor de áudio. Em
tela estreita os painéis da esquerda viram abas de um painel só.
- Trilhas da timeline, uma por camada: C1 legenda, V3 textos, V2 zoom, INS inserções, ENQ enquadramento (keyframes
do reenquadramento), CAM câmera (layout de cada trecho), V1 vídeo (miniaturas), A1 áudio da live (forma de onda;
"MUDO" no trecho mudo), A2 narração, A3 música e efeitos, CH chat.
- **Programa no formato do corte:** tamanho vem de `frames` (`frameOf`, `FALLBACK_FRAMES`; sem `W`/`H` fixos), 16:9 no
horizontal; "Formato" do corte em Propriedades › Vídeo. Aviso quando a duração sai do mínimo/máximo (a edição é livre).
- **Fontes na prévia** (`clip-editor-fonts.tsx`): as empacotadas vêm por `fetch` + `FontFace` de `/api/files`
(`fontFiles` da rota de settings); a prévia só desenha depois de carregadas. Tamanho do texto pelas métricas do
arquivo, como o libass: px = tamanho ASS × unitsPerEm / (usWinAscent + usWinDescent), passo de linha = tamanho.
(Antes a prévia saía ~40 % maior que o render.) `FontPicker` = seletor com amostra.
- **ENQ e INS** (`clip-editor-keyframes.tsx`): keyframes ◆ suave / ◇ linear / ■ segurar; arrastar, duplo clique troca
a curva, Delete, Ctrl+C/V, `[` `]` pulam de key. Na Fonte, a janela do reenquadramento tem proporção travada e
auto-key no playhead; o recorte da inserção é desenhado na Fonte e posicionado no Programa, com keyframes de
posição/tamanho, aparência e subir/descer na ordem. Interpolação em `clip-editor-model.ts` (`easeAt`,
`interpolate`, `reframeAt`, `insetAt`), alinhada a `clipper/app/reframe.py`: mudou uma, mude a outra.
- **Câmera editável na Fonte** (`clip-editor-source.tsx`, geometria em `rect-geometry.ts`, compartilhada com o modal):
alças, mover, desenhar numa área vazia, setas (Shift = tamanho). Propriedades "Câmera e layout deste trecho" separa
"Layout · só este trecho" de "Posição da câmera · corte inteiro"; "Usar esta câmera nos próximos cortes da sessão"
grava na sessão (os cortes existentes não mudam). Mudança de layout do corte passa por `editLayout(p, fn)`.
- Fluxos secundários abrem em modal (`ModalKind` = `export` | `ai` | `narration` | `keys`), não em aba.
| Arquivo (`panel/src/components/`) | Papel |
|---|---|
| `clip-editor.tsx` | estado, atalhos, autosave, cabeçalho, disposição dos painéis, som da prévia e medidor (`AudioMeters`) |
| `clip-editor-model.ts` | tipos (`EditProject`, `EditCut`, `ChatOverlay`/`CHAT_DEFAULT`, `InsetOverlay`) e operações puras do projeto (`removeRange`, `keepRange`, `resolvedMode`, `editLayout`, `frameOf`, interpolação de keys, `bannerLayout`); `useHistory` (updater puro: gotchas, item 109) |
| `clip-editor-fonts.tsx` | fontes empacotadas no navegador (`loadPackagedFonts`, `usePackagedFonts`), métricas (`fontMetrics`, `canvasFont`) e `FontPicker` |
| `clip-editor-keyframes.tsx` | trilhas/propriedades ENQ e INS (`ReframeLayer`, `ReframeKeyProps`, `InsetsLayer`, `InsetProps`, `moveInsetOrder`, `KeyGlyph`) |
| `clip-editor-source.tsx` · `rect-geometry.ts` | monitor Fonte (`SourceMonitor`: câmera, jogo, janela do reenquadramento, recorte da inserção) · geometria de retângulo 0–1 (alças, mover, setas), também usada pelo modal do corte |
| `clip-editor-ui.tsx` | peças do desenho NLE: ícones, `IconBtn`, `Btn`, `Modal` (`<dialog>` nativo), `PropSection`/`PropRow`, `Scrub`, `Keycap` |
| `clip-editor-layers.tsx` | painel Camadas: selecionar, ligar/desligar e criar no playhead |
| `clip-editor-timeline.tsx` | régua, trilhas, lâmina, ímã e todos os arrastes (`DRAG_START_PX` = 4) |
| `clip-editor-preview.tsx` | monitor Programa (canvas no formato do corte sobre o proxy, camadas arrastáveis, tarja, inserções e reenquadramento) |
| `clip-editor-transcript.tsx` | transcrição e chat: Tirar, Manter, Editar (troca o texto e reparte o tempo), Ocultar/Mostrar (só da legenda), Ênfase |
| `clip-editor-inspector.tsx` | Propriedades da seleção e os modais (`ExportModal`, `AiModal`, `NarrationModal`, `ShortcutsModal` com a lista `KEYS`) |
- Gestos (tabela "Mexer com a mão" de `clipper/README.md`): arrastar o corpo move palavra/grupo, texto, zoom,
narração e trecho (o trecho desliza sobre a gravação); bordas aparam; no Programa, arrastar muda `x`/`y` de texto,
gancho e chat e a altura da legenda; no Fonte, o alternador Câmera / Área do jogo (`SourceTargetToggle`) escolhe o
retângulo, e mover/alças/desenhar grava `settings.layout.cam`/`game` só daquele corte. O arraste de mover só começa depois de 4 px.
- Autosave 1,2 s com `rev` (409 = outro salvou); "Salvar projeto"/Ctrl+S salva na hora. Desfazer por instantâneos.
- Atalhos (fonte: `KEYS`; atalho novo entra lá e no `onKey` de `clip-editor.tsx`): Espaço tocar/pausar, K pausar,
J/L ±2 s, ←/→ um quadro (Shift = 1 s), Home/End, V seleção, C lâmina, S ou Ctrl+K dividir no playhead,
Ctrl+Shift+clique dividir onde clicar, Q/W começar/terminar o trecho no playhead, Delete, N ímã, Ctrl+roda zoom da
timeline, Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y, Ctrl+S salvar, Ctrl+E exportar, `[`/`]` keyframe anterior/seguinte,
Ctrl+C/Ctrl+V copiar/colar keyframe no playhead, Esc, ? atalhos.
- A prévia do navegador segue o render na legenda (`captionBlocks`, porte de `subtitles.py`) e no recorte de câmera/jogo
(`ffmpegCropFill`, tamanho de `session.capture`); o resto é aproximado e a exata é "Prévia real" (`preview-render`,
FFmpeg). Porte e regra de manutenção em [clipper.md](clipper.md#editor-de-cortes-clippereditid); diferença de 1–3 px:
gotchas, item 117.
- Teste automático da UI: armadilhas 85 (camadas do canvas) e 86 (não gravar no corte real) em [gotchas.md](gotchas.md).
## Evidência e lacunas (16/11/2026)
Teste ponta a ponta numa cópia do banco real (`CENAFORGE_ROOT` temporário, PATH sem CLIs de
agente), informado pelo coordenador: 10 grupos de casos passando (migração preservou 1 história,
1 episódio, 5 comentários; votos `{A:1,B:0,C:2}` → C; fluxo com 7 nós; contas; 14 publicações e
42 fotografias simuladas); typecheck limpo; `/dashboard`, `/accounts`, `?tab=flow` e APIs → 200.
Não verificado: "Preparar vertentes" com agente real; árvore no navegador com dados reais (só
com dados injetados); opções C/D no vídeo (o overlay não as desenha).
Formato documental e modelos (17/11/2026, informado pelo coordenador): `tsc --noEmit` do painel OK;
v4 aplicada numa cópia do banco v3 (stories 2→2, episodes 2→2, agent_runs 3→3, `foreign_key_check`
vazio; CHECK rejeita `kind` inválido e aceita `documentary`); `codexModels()` contra o `~/.codex` real →
9 opções; `claude -p --model claude-fable-5-2` e `claude-haiku-5-5` → "ok". Conferido pela skill: o
`data/cenaforge.db` real ainda está em `user_version` 3 (painel não reiniciado). Não verificado: história
documental criada de ponta a ponta pelo painel (Claude ou Codex) e render de um vídeo documental.
Guias `doc/roteiro/` e exclusão de história (17/11/2026, informado pelo coordenador): `tsc --noEmit` do painel OK
(reconferido pela skill); numa cópia do banco v4, excluir uma história → stories 2→1, episodes 2→1, agent_runs 3→3
(`story_id` da execução virou NULL), `foreign_key_check` vazio. Não verificado: o clique na UI (painel não
reiniciado), o `renameSync` para `data/trash/` no Windows com arquivo aberto e um roteiro real escrito pelos
guias novos (Claude ou Codex). Pela leitura do código: se um `renameSync` falhar no meio, a exceção sobe antes da
transação — a história continua no banco, mas o que já foi movido está na lixeira (devolver à mão).
Mensagem durante a execução e termos episódio × vídeo (17/11/2026, informado pelo coordenador): `tsc --noEmit` do
painel OK (reconferido pela skill); retomada do Codex 0.169 testada à parte com `gpt-6-luna`, sandbox read-only
(gotchas, item 97). Não verificado: o clique na UI (painel não reiniciado) e a retomada do Claude depois de
interrompido (o `--resume` já existia).
Leitor de roteiro (17/11/2026): `parseScript` no `stories/a-ilha-da-queimada-grande-conhecida-como/ep01.md` real →
9 trechos, 176 palavras (≈ 70 s, alvo 72 s), papéis hook/shots/cover/sources/needs (reconferido pela skill via `tsx`);
`tsc --noEmit` do painel e capturas do Chrome headless das três páginas: informados pelo coordenador.
Montagem documental (17/11/2026): `tsc --noEmit` do painel sem erros (reconferido pela skill). Informado pelo
coordenador: `numberToWords` 16/16 casos; teste isolado do `montage-ffmpeg.ts` com 3 trechos reais e
`pt-br-antonio` (Edge) → falas 6,82 / 13,16 / 13,37 s, cada segmento montado em 0,8–1,3 s, `final.mp4` de 38,48 s
(= falas + pausas + créditos, pelo ffprobe), h264 1080×1920 30 fps + aac 48 kHz estéreo, quadros conferidos (zoom,
texto, legenda, cartela, créditos); no painel ao vivo, GET da montagem do episódio 3 → 9 trechos com texto falado por
extenso, áudio do trecho 1 gerado em 3 s. Conferido pela skill: `ep01.montage.json` da Ilha da Queimada Grande com
`pt-br-antonio`, `durationMs` 4080. Não verificado: "Montar vídeo" completo pelo painel (faltam imagens) e
cancelamento (`DELETE .../montage/render`).
Cenas 2D e vídeo automático (17/11/2026). Conferido pela skill: os 9 `report.json` das cenas do episódio da Ilha
(`output/runs/20261117-0422*-ep01-t0N-final`) com `status: success`, 7,4–21,5 s cada; prévias 540×960 de mapa,
contador e título em 2,7–4,3 s (`*-teste-*-preview`, configs em `data/tmp/`). Informado: `planScene` nos 9 trechos
reais → títulos, mapa (Itanhaém → ilha, 35 km) e 2 contadores. Não verificado: cancelamento no meio de uma cena;
`godot/tests/` não tem caso de `doc2d` nem de `doc3d`.
Biblioteca 3D, fotos do Commons e "Gerar de novo" (17/11/2026). Conferido pela skill: com os nomes atuais
(`doc.tscn`, `godot/scripts/doc/`), 13 prévias `teste-ilha-*` (4 tomadas × 3 iterações + 1) com `status: success`,
540×960 × 5 s em 9,4–14,3 s no total (Godot 9–13 s); cena da ilha em final 1080×1920 de 9,1 s em 42,9 s (Godot 39,1 s;
`...-ep01-t07-final` das 04:46); `teste-inexistente` (`campo-futebol`) falha no `godotValidate` com "não existe na
biblioteca (godot/library/). Disponíveis: ["island"]"; prévias de mapa, contador e título v1/v2 em 2,9–3,9 s;
dois MP4 de `ep01` (04:46 e 04:48) h264 1080×1920 + aac, 88,33 s (ffprobe); `pnpm test` → 38 passaram;
`npx tsc --noEmit -p panel` → exit 0; `ep01.montage.json` com fotos do Commons nos trechos 1, 3, 4, 8 e 9 (licenças
CC BY, BY-SA e CC0 registradas), mapa, 2 contadores e `island`, todos `auto: true`. Informado: no painel ao vivo, "Refazer tudo do zero" no episódio 3 → fotos do
Commons diferentes nos trechos 1, 3, 4 e 9 (jararaca) e 8 (ilha + navio), mapa, 2 contadores e o farol 3D ao
entardecer, MP4 em 1 min 44 s; quadros e captura da UI conferidos. Não verificado: cena 3D criada pelo agente do painel
(execução #5, campo de futebol, em andamento), "Gerar de novo" de foto enviada e licença das fotos do Commons uma a uma.
Modal de confirmação (17/11/2026): `tsc --noEmit` do painel sem erros e nenhum `confirm(`/`alert(` nativo em
`panel/src/` (reconferidos pela skill; `askConfirm`/`showAlert`/`confirmSubmit` em 15 componentes). Informado pelo
coordenador: no navegador (http://localhost:4500/) o modal abre com título e descrição acessíveis, Esc fecha sem
excluir e Confirmar reenvia o formulário com o mesmo submitter (2º submit com `data-confirmed="1"`). Não verificado:
cada uma das 25 chamadas trocadas, uma a uma, na UI.
Editor de cortes com tarja, fontes, Programa 16:9, ENQ/INS e câmera na Fonte (17/11/2026): `npx tsc --noEmit -p panel`
→ exit 0 (reconferido pela skill). Informado: prévia da tarja a ≤ ~2 px do render; interpolação do painel ×
`reframe.py` em 41 conferências; testes de UI por CDP com as escritas interceptadas (gotchas, item 86). Render real
de um projeto do editor com enquadramento e inserção comparado com a prévia: ver o lote abaixo.
Apagar na fila, relógio da sessão e prévia igual ao render (17/11/2026): `npx tsc --noEmit -p panel` → exit 0
(reconferido pela skill). Informado pelo coordenador: porte da legenda em 22 conferências contra o Python; corte 61
montado no editor e renderizado pelo serviço com enquadramento, inserção e legenda iguais à prévia em
2/3,5/5/6,5/8 s. Não verificado: apagar pela UI contra o serviço real; relógio com movimento reduzido, aba escondida
e larguras de 1024/1280; a faixa do topo de `clipper-studio.tsx` ainda usa o `durationS` real.
@@ -0,0 +1,212 @@
# Publicação em YouTube, TikTok e Instagram (Publicador + despachante do painel)
Fonte completa: `doc/publicacao/PLANO.md` (contrato HTTP do Publicador §3, banco §4, despachante §5, telas §6) e
`doc/publicacao/PESQUISA.md` (fatos das plataformas, datados de 17/11/2026, reverificar a cada 3 meses). Instalação,
apps das redes e regras do modo sessão: `publisher/README.md`. Aqui só o que um agente precisa para agir.
## Quem faz o quê
```
Painel (4500) = cérebro ──► Publicador (4530) = executor ──► YouTube / TikTok / Instagram
canais, regras, fila cofre DPAPI, OAuth, perfis de API oficial OU Chrome/Edge via CDP (4540–4549)
publish_jobs, laço 20 s navegador, jobs (um por vez)
└──► Clipador (4520): lê cortes ready/approved (GET /v1/clips?channel=&status=&ids=), aprova e marca published
```
- **Despachante**: `panel/src/instrumentation.ts` → `startDispatcher` (`lib/dispatcher.ts`, `TICK_INTERVAL_MS` 20 s,
guarda em `globalThis` contra laço duplo no HMR) → `dispatcherTick` (`lib/publishing.ts`, que ao carregar troca
`dispatcherState().tick` pela versão nova: sem isso o laço usa as regras antigas, gotchas 141). **Só publica com o
`pnpm panel` aberto** (o painel é do usuário: não inicie nem encerre).
- **Publicador** (`publisher/`, Python 3.12 FastAPI): não conhece canal, história nem corte; recebe arquivo +
metadados + `profileId` (`<accountId>--<platform>`). Toda rota exige `X-Service-Key` (`PUBLISHER_SERVICE_KEY` em
`publisher/.env`), exceto `GET /health` e `GET /oauth/callback/{platform}` (validada por `state`). Dados em
`data/publisher/` (`publisher.db`, `vault.bin` DPAPI, `browser/<profileId>/`, `logs/` com capturas das falhas).
- Subir: `pnpm dev` (sobe depois do Clipador; sem `publisher/.venv` ou chave, pula com aviso). Instalar: `setup.bat`
(passo 6b2 do `scripts/setup.ps1`). Testes: `pnpm test:publisher` (pytest, sem rede nem navegador) e
`pnpm --filter cenaforge-panel test:panel` (node:test via tsx em `panel/src/lib/*.test.ts`, banco temporário por
`CENAFORGE_ROOT`). Typecheck do painel: `pnpm --filter cenaforge-panel typecheck`.
## Onde mexer
| Mudança | Arquivo(s) |
|---|---|
| Contrato HTTP, fila, cofre, OAuth | `publisher/app/` (`main.py` rotas, `service.py` regras, `worker.py` fila, `vault.py`, `db.py` (v2: `jobs.client_ref` UNIQUE), `paths.py` (`file`/`cover` só de `output/`, `stories/`, `assets/`; `data/` recusado), `acl.py` (ACL de `data/publisher` só para o usuário), `config.py`) |
| API oficial de uma rede | `publisher/app/platforms/{youtube,tiktok,instagram}_api.py` |
| Modo sessão (navegador) | `publisher/app/platforms/session/` (`browser.py` abre Chrome/Edge normal com `--user-data-dir` e `--remote-debugging-port`, confere a porta pelo `DevToolsActivePort` do perfil ou, se o Chrome 157+ não o gravar (porta fixa), pela marca `CenaForgeWindow.json` + PID que escuta (`owns_port`, `listener_pid`; gotchas 137), fecha a janela (`IDLE_CLOSE_S`/`LOGIN_IDLE_CLOSE_S`); `runner.py` (`_with_page` conecta com `connect_over_cdp(..., is_local=True)`: sem isso arquivo > 50 MB é recusado, gotchas 139; `browser_error_text(detail)` traduz o `PlaywrightError` em frase específica (clique com timeout, timeout, arquivo > 50 MB, janela fechada) ou, no resto, "O navegador travou ou mudou de página"; o "Detalhe" técnico vem depois); `common.py`: `step_pause`, `fill_text`, `click_through`, `dismiss_tips`, `TIP_BUTTONS`, `screenshot`, `prune_screenshots`); seletores no dicionário `SELECTORS` de `youtube_studio.py`, `tiktok_studio.py`, `instagram_web.py` |
| Cliente do Publicador no painel | `panel/src/lib/publisher.ts` |
| Regras puras (horário bom, limite, ações do job, sincronização de cortes, leitura do resultado, reencaixe, idempotência) | `panel/src/lib/publishing-rules.ts` (`placeJob`, `nextFreeSlot`, `planClipSync`, `readPublisherJob`, `jobActions`, `aiGeneratedFor`, `tagsFromCaption`, `needsReflow`/`STALE_AFTER_MS`, `clientRefFor`, `mayBeLive`, `parseVideoUrl`) + `publishing-rules.test.ts` |
| Fila, aprovação, envio, episódio | `panel/src/lib/publishing.ts` (`approveJob`, `placeApproved`, `retryJob`, `sendDue`, `promoteDue`, `pollPublishing`, `finishFromPublisher`, `markPublished`) + `publishing-db.test.ts` |
| Pausar tudo, horários bons, fuso | `panel/src/lib/settings.ts` (tabela `app_settings`) |
| Banco | `panel/src/lib/db.ts`: **v5** (`account_networks` reconstruída sem `mock`, `publish_jobs`, `publications` com `clip_id`/`job_id`, `app_settings`, `clip_auto_approvals`, colunas novas em `accounts` e `episodes`), **v6** (`publish_jobs` reconstruída: `schedule_source` `auto`/`manual`/`now`, `cancel_reason` aceita `unlinked`) e **v7** (`publish_jobs.origin` `link`/`manual`, padrão `link`) |
| "Publicar" no cartão do corte (sem fonte ligada) | UI `panel/src/components/clip-publish.tsx` (`ClipPublishButton` + diálogo; usado em `clipper-queue.tsx`, em `approved` e, como "Publicar em outra rede", em `published`; `useClipPublishing().reload()`); cliente `publishClip` em `publishing-client.ts`; rota `POST /api/publishing/clips/[id]` (`app/api/publishing/clips/[id]/route.ts`); servidor `publishClip` em `publishing.ts` |
| Guarda da API do painel | `panel/src/proxy.ts` (Next 16: o middleware se chama `proxy`; `checkRequest` exportado) + `proxy.test.ts`; `readJson` em `panel/src/lib/http.ts` (415 sem JSON) |
| Rotas | `/api/settings` e `/api/settings/apps/[platform]`, `/api/publisher/status`, `/api/publishing/jobs[/[id][/[action]]]`, `/api/publishing/summary`, `/api/episodes/[id]/approve`, `/api/accounts/[id]/networks/[platform]/(connect|token|check|reopen|creator-info)` |
| Telas | `/accounts` "Canais de publicação" (`account-manager.tsx`, `account-networks.tsx`, `connect-wizard.tsx`), `/publishing` "Publicações" (`publishing-board.tsx`, `publishing-client.ts`), `/settings` "Configurações" (`settings-panel.tsx`) |
| Modal novo (qualquer tela) | `Dialog` + `Steps` de `panel/src/components/dialog.tsx` (`<dialog>` nativo, foco preso, Esc fecha). Confirmação simples continua em `askConfirm` (panel.md) |
| Avisos e chips de estado por rede | `NoticeBar` e `PublishChips` em `panel/src/components/publishing-ui.tsx` |
Botões de um job vêm de `actions[]` da API (`jobActions` no servidor); a UI não decide sozinha o que oferecer.
No texto visível do Clipador "Canais" virou **"Fontes"**; código, tabelas e rotas continuam `channels`.
## Regras que não podem quebrar
- **Nunca `published` sem ID/URL remota** (ou rascunho confirmado). `done` sem link ⇒ `failed` com aviso para
conferir na rede antes de "Tentar de novo" (evita publicar duas vezes). Publicador fechado no meio de um envio ⇒
`failed` "interrompido — tente de novo": também conferir na rede.
- **Aprovar vale para o vídeo inteiro** (todas as redes e canais daquela origem); tirar uma rede = cancelar o job dela.
- **Aprovação automática** (`accounts.approval_mode = 'auto'`) só pega cortes criados depois de ligá-la
(`accounts.auto_since`) **e** depois de a fonte ser ligada ao canal. Episódio **sempre** precisa do clique
"Aprovar para publicar" (exige render final).
- "Na hora" (`timing = 'now'`) respeita o limite diário (`account_networks.daily_limit`); passou do limite, agenda no
próximo horário bom.
- `publishAt` nativo do YouTube **não é usado** (o painel manda `null`); o agendamento é do despachante.
- **Modo sessão viola os termos das três redes**: a UI exige marcar "Entendi o risco". Proibido stealth/patchright/
stealth.js, resolver captcha ou digitar senha; login, captcha ou checkpoint ⇒ `needs_login` e o usuário resolve.
Não rode `playwright install` (só o driver; o navegador é o Chrome/Edge do usuário).
- Segredos nunca voltam ao navegador (só `configured: true/false`) e nunca vão para logs nem para esta skill.
- **Idempotência:** o painel manda `clientRef = "<publish_jobs.id>:<attempts>"`; o Publicador devolve **200** com o job
existente (201 = novo). `attempts` só sobe em "Tentar de novo"/reaprovação. Timeout, conexão caída, 5xx ou
401/403/404 ao criar ⇒ o job **fica na fila** e reenvia com o mesmo `clientRef`; outro 4xx ⇒ `failed`.
- **`mayBeLive`** (falhou depois de chegar ao Publicador): `POST /api/publishing/jobs/<id>/retry` sem `{confirm: true}` ⇒ 409; a UI pergunta
"Confira na rede se o vídeo já saiu". Agente não manda `confirm: true` sem o usuário ter conferido.
- Agendamento automático vencido há > 30 min (painel fechado) é reencaixado no próximo horário bom; horário manual,
"Publicar agora" e "Tentar de novo" saem como estão.
- Encerrar fonte/história cancela os jobs não enviados (`unlinked`); religar zera `linked_at` (a automática não pega
cortes do intervalo desligado). Cancelar no meio de um ciclo vale (UPDATEs condicionais; se o Publicador já criou o
envio, o painel cancela lá). Aprovação automática é registrada em `clip_auto_approvals` antes do PATCH no Clipador.
- **Botão "Publicar" do corte** (`POST /api/publishing/clips/<id>`, corpo `{accountId, platforms[], timing?: "now"|"best_slot"}`,
resposta `{jobs, skipped[{platform, reason}], placed}`; `publishClip`): serve para corte aprovado cuja fonte **não** está
ligada a canal (`account_channels`) ou para outra rede. O clique é a aprovação humana. `timing` omitido = o do canal.
`"now"` força `queued` com `schedule_source='now'` e ignora o limite do dia. Job existente cancelado, `failed` ou
`needs_login` é reaproveitado (`attempts`+1 via `placeApproved`, que ganhou `opts.timing`); rede não conectada,
pausada, já publicada, na fila, agendada, enviando ou "pode ter saído" (`mayBeLive`) entra em `skipped` com motivo.
O diálogo lista essas redes bloqueadas com o motivo. Título e legenda são os do cartão.
- **`publish_jobs.origin`**: `link` (criado pelo vínculo fonte↔canal) ou `manual` (botão "Publicar"). Job `manual` **não**
é cancelado por "fonte desligada" (`planClipSync` com `ExistingJob.origin`, `linkActive`, `accounts.endChannel` só
cancela `origin = 'link'`); corte editado, rejeitado ou apagado ainda cancela o job. Armadilha de migração: gotchas 138.
- Rótulo de IA: se não der para ler a voz do episódio, vai ligado por cautela. **Corte (`source_kind = 'clip'`) nunca leva
o rótulo**, nem com o canal em "always" (`sendDue`; gotchas 148).
- **"Apaguei na rede"** (`removed`): `POST /api/publishing/jobs/<id>/removed`; `markRemoved` (`publishing.ts`) aceita só
`published`, volta o job a `canceled`/`user`, zera url/remote_id/published_at e apaga a `publications` do job; `jobActions`
de `published` = `["removed"]`; cliente `markJobRemoved`; botão em Publicadas com confirmação. O painel não apaga nada na
rede (apague lá primeiro); depois "Publicar" no corte reenvia com `attempts`+1. Gotchas 149.
- Modo sessão: a janela fecha depois de cada envio e do "Já entrei" (pede saída limpa, mata após 10 s); fica aberta
se a rede pedir login/captcha; ociosa fecha em 5 min (15 min se aberta para login). Capturas só da área visível,
nunca em login/captcha, apagadas após 7 dias. Ritmo: "intervalo mínimo entre envios" (30 s, `publisher/README.md`).
- Segurança do Publicador: ACL de `publisher/.env` e `data/publisher/` restrita ao usuário (`setup.ps1` + `acl.py`);
`code_verifier` do PKCE só em memória; loggers `httpx`/`httpcore` silenciados (o token do Instagram vai na URL).
- **Link do vídeo no TikTok** (`find_video_url(page, caption, sleep, attempts=12, reads=5, progress)` em
`tiktok_studio.py`): a lista "Publicações" (`/tiktokstudio/content`) **não se atualiza sozinha** e o vídeo novo só entra
depois de processar. Espera 5 s; a cada tentativa abre ou **recarrega** `CONTENT_URL` e lê 5 vezes (a cada 3 s); até 12
cargas (~3 min), com progresso "Publicado. Esperando o vídeo aparecer na lista do Studio… (n de 12)". **Só aceita o link
cuja linha (até 10 ancestrais do `<a>`) contém `caption_key(caption)`** (primeiros 24 caracteres da legenda sem #hashtags
e @menções): nunca devolve o link de outro vídeo. Sem achar, `PublishResult` sem link e step "Publicado no TikTok
(Studio), mas o vídeo não apareceu na lista do Studio em ~3 min; link não encontrado" ⇒ job `failed` (regra "nunca
`published` sem URL"). No painel, `readPublisherJob` (`publishing-rules.ts`) reconhece `done` sem link com step
começando em "Publicado no " e diz "Saiu na rede, mas o link do vídeo não apareceu a tempo… use 'Já saiu: informar o
link' (não use 'Tentar de novo')". Não há seletor `video_link` (links relativos). Gotchas 140 e 143.
- **"Já saiu: informar o link"** (`mark-published`): `POST /api/publishing/jobs/<id>/mark-published` com `{url}`
(`markPublished` em `publishing.ts`; `MarkPublishedDialog` em `publishing-board.tsx`; cliente `markJobPublished`;
`PublishJobAction` ganhou `"mark-published"`). Aparece em job `failed` (sempre; botão principal se `mayBeLive`) e
`needs_login` (só se `mayBeLive`). `parseVideoUrl(platform, url)` (`publishing-rules.ts`) valida e devolve
`{url, remoteId}`: TikTok `/@conta/video/<id>`; YouTube shorts, `watch?v=` ou `youtu.be`, normalizado para `/shorts/<id>`;
Instagram `reel(s)` ou `p`; outro formato ou rede ⇒ erro. Faz UPDATE condicional para `published` com url e
remote_id, `recordPublication` (registro real) e `kickDispatcher` (marca o corte `published` no Clipador). Use só depois
de conferir na rede que o vídeo está lá; o agente não inventa o link.
- **Primeiro envio real (TikTok, modo sessão, 17/11/2026 13:35):** público, `https://www.tiktok.com/@vortplay/video/7709179978520284437`
(informado; login, upload, legenda, privacidade e "Publicar" funcionaram com conta real). O job terminou `failed` por falta
do link (gotchas 140) e foi marcado como publicado pela rota acima. Seletores do TikTok validados nesse envio; **YouTube e
Instagram em modo sessão: só o ensaio sem publicar (próxima regra); YouTube segue sem validação.**
- **Instagram em modo sessão** (`publisher/app/platforms/session/instagram_web.py`; layout novo de 17/11/2026, barra
lateral só de ícones). Fluxo: o botão é `<a>` com `<svg aria-label="Postar">` e abre DIRETO o diálogo "Criar novo
post" (sem submenu; `create_post` só para o layout antigo), com o `input[type=file]` dentro do diálogo.
- `SELECTORS["create"]` aceita "Postar" (svg, link, botão); erro: "o botão Postar".
- `next`, `share` e `reels_notice_ok` são CSS presos a `_DIALOG` (`div[role='dialog']`): no feed cada post tem um
botão de ícone "Compartilhar" e o seletor global podia clicá-lo (teste `test_buttons_of_the_flow_are_searched_inside_the_dialog`).
- Envio dividido: `prepare(page, spec, progress, sleep)` faz tudo até devolver o locator do Compartilhar **sem
clicar**; `upload` chama `prepare`, clica e espera "compartilhado". Todo clique passa por `click_through`.
- **Rótulo de IA**: `input type=checkbox role=switch` SEM nome acessível, direto no painel (não em "Configurações
avançadas", que só abre como plano B do layout antigo). `find_ai_switch` casa a linha (`AI_ROW_TEXT`, até 6
ancestrais por `innerText`); `_is_on` lê `aria-checked`/`is_checked`; confere de novo depois do clique e, se não
ligou, `PublishError` (não publica sem o rótulo). Sem clique forçado (gotchas 145).
- **Formato "Original"** (`keep_original_shape(page, sleep)`, chamada em `prepare` antes dos "Avançar"): a etapa "Cortar"
vem em 1:1 e cortaria o vídeo vertical (o 1º reel real saiu quadrado, gotchas 147). Clica em
`svg[aria-label='Selecionar corte']`/'Select crop' no diálogo e escolhe "Original" (`SELECTORS["crop_toggle"]`,
`["crop_original"]`; opções Original, 1:1, 9:16, 16:9) e fecha o menu. Sem o ícone ⇒ `PublishError`, nunca publica cortado.
- `close_suggestions(page, text)`: legenda terminando em `#tag`/`@menção` ganha um espaço no fim (Esc fecharia a caixa).
- **Link do reel**: o endereço não muda após compartilhar. `find_reel_url(page, caption, sleep, attempts=6,
per_load=3, progress)` acha o link do perfil (`_PROFILE_HREF_JS`: `/<conta>/` com `textContent` "Perfil" ou foto do
perfil no `alt`; a barra recolhida esconde o texto), abre `/<conta>/reels/`, abre os 3 mais novos ainda não
conferidos e aceita o primeiro cuja página contém `caption_key(caption)` (agora em `common.py`, também usada pelo
TikTok); recarrega até 6 vezes, 20 s entre elas (~3 min). `MEDIA` aceita `/<conta>/reel/<código>/`. Sem link ⇒
`PublishResult` sem URL ⇒ job `failed` ⇒ "Já saiu: informar o link".
- **Ensaio sem publicar** (jeito seguro de validar seletores com conta real): rodar `prepare` com o navegador do
perfil, conferir o resultado e descartar o rascunho ("Descartar"); nunca clicar em Compartilhar sem pedido do usuário.
- Validado ao vivo (informado, 17/11/2026, ensaio com `ai_generated=True`): Postar, arquivo `clip-29.mp4`, Avançar ×2,
legenda "…#teste" intacta, rótulo de IA LIGADO, Compartilhar achado e não clicado, rascunho descartado, 0 diálogos no
fim. `_PROFILE_HREF_JS` voltou `/vortplay27/`. **Não validados com conta real:** clique em Compartilhar, a
confirmação "compartilhado" e `find_reel_url` (a conta ainda não tinha reels). Só vale depois de reiniciar o `pnpm dev`.
- **Avisos de novidade do site (modo sessão):** o TikTok Studio abre avisos por cima da página ("Veja a prévia do seu vídeo
no seu celular" → **Entendi**) que bloqueiam cliques. Todo clique do `tiktok_studio.py` passa por `click_through`
(timeout 8 s; se falhar, `dismiss_tips` fecha os avisos e tenta de novo; sem aviso, relança o erro) e `dismiss_tips`
roda antes da legenda e antes de "Publicar". `TIP_BUTTONS` só aceita `^(Entendi|Entendido|Ok, entendi|Got it)$`:
**nunca aceitar ou recusar opções por esse caminho**, só fechar avisos. Gotchas 142.
## Fatos das plataformas (resumo; detalhe e fontes em `doc/publicacao/PESQUISA.md`)
- YouTube: projeto não verificado já publica público (desde 02/11/2026); `videos.insert` 100 envios/dia; app em
"Testing" perde a autorização em 7 dias (pôr "In production").
- TikTok: sem auditoria, Direct Post só `SELF_ONLY` (conta privada) ou rascunho (até 5 pendentes/24 h); auditoria
para uso próprio provavelmente negada.
- Instagram: conta Profissional; conta própria sem App Review; token colado (a Meta não aceita redirect localhost),
vale 60 dias, renovado quando faltam < 10; `rupload` com arquivo local via `graph.instagram.com` ainda **a testar**.
## Evidência (17/11/2026)
Depois das revisões de segurança e correção, reconferido pela skill: `pnpm test:publisher` → 71 passed (depois da correção do Chrome 157, informado: 73 passed; gotchas 137);
`pnpm --filter cenaforge-panel test:panel` → 59/59; typecheck do painel e da raiz sem erro (informados também:
`test:launcher` 17/17, `test:clipper` 270 passed). Bancos reais: `data/cenaforge.db` ainda em `user_version` 5 (a v6
entrava só com o painel reaberto; hoje a 1ª requisição depois da recarga do `db.ts` migra — gotchas, itens 51 e 138); `data/publisher/publisher.db` em 2. Não
verificado: conexão de qualquer rede pela UI (nos dois modos), envio real, renovação de token, seletores do modo
sessão, laço do despachante com o painel ao vivo, fechamento da janela do navegador num envio real.
Botão "Publicar" do corte (informado, 17/11/2026; não reexecutado aqui): typecheck do painel verde; `test:panel` 63/63,
com testes novos em `publishing-rules.test.ts` ("publicado à mão (origin manual)…") e em `publishing-db.test.ts`
(seção "Publicar" no cartão do corte: job manual com rede não conectada pulada, `endChannel` não cancela o manual,
recusas); teste de migração agora espera a v7. **Não testado com conta real.** Plano: `doc/publicacao/PLANO.md` §7c.
Envio de arquivo grande no modo sessão (informado e reconferido, 17/11/2026): a 1ª tentativa real no TikTok chegou ao
TikTok Studio logado e falhou em `set_input_files` (> 50 MB, gotchas 139). Correção `is_local=True` aplicada;
`pnpm test:publisher` → 73 passed (então). O envio real depois disso funcionou (ver "Primeiro envio real" acima).
Link do TikTok e "Já saiu" (informado, 17/11/2026): `pnpm test:publisher` → **74 passed** (reexecutado na skill; teste novo
`test_tiktok_link_waits_for_the_list_and_matches_caption` em `publisher/tests/test_browser.py`); `test:panel` 65/65 e
typecheck verdes (informados, não reexecutados); `parseVideoUrl` em `publishing-rules.test.ts`, `markPublished` em
`publishing-db.test.ts`. `find_video_url` validado ao vivo só de leitura na lista real (informado): a legenda certa
devolveu o link, a de outro corte `None`. **`find_video_url` e `is_local` só valem depois de reiniciar o `pnpm dev`.**
Espera do link com recarga da lista (informado, 17/11/2026): `find_video_url` com 12 cargas × 5 leituras; validado ao vivo,
só leitura, achou `https://www.tiktok.com/@vortplay/video/7709183805373877524` (2º post real, 13:50); o job 1 foi marcado
publicado por `mark-published`. `pnpm test:publisher` → **76 passed** (reexecutado; teste
`test_tiktok_link_waits_for_the_list_and_matches_caption` agora recarrega e confere "2 de 12"). `test:panel` 65/65 e typecheck
verdes (informados, não reexecutados; teste novo da mensagem "Saiu na rede…"). **O envio das 13:50 rodou código antigo** (gotchas
143): a espera nova ainda **não foi exercitada num envio real**.
Aviso por cima da legenda (informado e reconferido, 17/11/2026): o 2º envio real no TikTok (captura `20261117-134508`)
falhou no clique da legenda por causa do aviso "Entendi" (gotchas 142); o upload de 100+ MB passou (`is_local` valendo).
`pnpm test:publisher` → **76 passed** (reexecutado; testes novos `test_click_through_closes_tip_and_retries` e
`test_browser_error_text_explains_common_failures`). O post não chegou a ser feito; **correção não testada num envio
real e só vale depois de reiniciar o `pnpm dev`.**
Instagram em modo sessão (informado e reconferido, 17/11/2026): `pnpm test:publisher` → **78 passed** (reexecutado; testes
novos `test_instagram_links_and_hashtag_suggestions` e `test_buttons_of_the_flow_are_searched_inside_the_dialog` em
`publisher/tests/test_browser.py`). Ensaio ao vivo sem publicar: ver regra "Instagram em modo sessão". O "Já entrei" do
usuário falhou porque o Publicador rodava código antigo (gotchas 143): reiniciar o `pnpm dev`.
1º reel real e formato (informado, 17/11/2026): o reel `/reel/Df2cezTNhY7/` (corte 68) saiu 1:1; o usuário o apagou e a
página mostra "Esta página não está disponível" (conferido). Corrigido com `keep_original_shape` (gotchas 147); ensaio sem
publicar validou a prévia 9:16 inteira com legenda e rótulo de IA; rascunho descartado. `pnpm test:publisher` → **78 passed**
(reexecutado). `test:panel` 66/66 e typecheck verdes (informados, não reexecutados; teste novo de `markRemoved`).
**Formato "Original" só vale depois de reiniciar o `pnpm dev`; o painel (`removed`, corte sem rótulo) já vale.** Não validado:
publicação real com o formato novo.
@@ -0,0 +1,82 @@
# Economia de tokens no CenaForge
Mantido pelo agente `cenaforge-token-auditor`. Princípio: o modelo caro decide e revisa; texto
narrativo vai para modelo mais barato; trabalho mecânico vai para script.
## Quem faz o quê
| Tarefa | Quem | Por quê |
|---|---|---|
| Arquitetura, pipeline de render, depuração, revisão final de entrega | modelo principal | erro aqui custa mais que os tokens |
| Enredo, bíblia da história, episódios, diálogos, título e opções A/B | `cenaforge-story-writer` (sonnet) | texto criativo não precisa do modelo mais caro; já respeita os limites do JSON |
| Dezenas de variações de título/opção, resumo de log, classificação | subagente com `model: haiku` | tarefa curta e repetitiva |
| Interface do painel (design, logo, componentes) | `cenaforge-dashboard-designer` (opus) | decisão do usuário: qualidade visual pede o modelo mais capaz |
| Atualizar a skill | `cenaforge-skill-updater` | confere fatos sem poluir o contexto principal |
| Achar onde algo está no código | agente `Explore` | devolve a conclusão, não os arquivos |
| Achar desperdício e criar scripts | `cenaforge-token-auditor` (sonnet) | — |
## Scripts (rode em vez de improvisar comandos)
Todos em `.claude/skills/cenaforge/scripts/`, Python 3.10+ só com biblioteca padrão. Rode a
partir da raiz do repositório.
| Script | Substitui | Uso |
|---|---|---|
| `runs_summary.py` | ler `report.json`/`render.log` inteiros | `python .claude/skills/cenaforge/scripts/runs_summary.py --last 3 --details` |
| `inspect_strip.py` | extrair e ler vários quadros soltos | `python .claude/skills/cenaforge/scripts/inspect_strip.py output/runs/<execução>` → lê só `inspect/strip.png` |
| `new_scene.py` | ler e reescrever o JSON inteiro | `python .claude/skills/cenaforge/scripts/new_scene.py --id <id> --set overlay.title="..." --set rider.travelMeters=36` (cria e valida) |
| `check_skill.py` | conferir caminhos/comandos da skill à mão | `python .claude/skills/cenaforge/scripts/check_skill.py` |
| `clean_runs.py` | listar e apagar execuções à mão | `python .claude/skills/cenaforge/scripts/clean_runs.py` (simula) · `--apply` (apaga) |
| `frame_check.py` | abrir vários quadros/QA para ver se a cena ficou boa | `python .claude/skills/cenaforge/scripts/frame_check.py --last` · `<output/runs/execução>` · `--config data/tmp/<id>-teste.json [--profile preview]` (renderiza e confere). Resume `report.json` e mede cada `inspect/t*.png` (luminância ESCURO < 0,08 / ESTOURADO > 0,92, contraste CHAPADO < 0,04, movimento PARADO < 0,004, enquadramento FORA se o detalhe foge > 30% do centro) e diz qual UMA imagem abrir. Saída 0 ok · 2 atenção · 1 falha |
| `check_script.py` | reler o roteiro à mão | `python .claude/skills/cenaforge/scripts/check_script.py stories/<história>` (ou um `ep*.md`): mesmas regras do leitor do painel (`script-doc.ts`, 2,5 palavras/s, "Duração:", tabela com 1ª coluna t (s)); avisa narração fora de ±15% do alvo, trecho que não cabe no tempo, buracos, coluna Imagem vazia, `meta.json` (title ≤ 60, logline) e `*.choices.json` (≤ 60, distintas) |
## Regras de leitura barata
- **Render:** depois do `pnpm render`, leia só o resumo impresso ou `runs_summary.py`. Abra o
`render.log` apenas se houver falha, e com `grep` (ex.: `grep -E "ERROR|SCRIPT|frames at"`).
- **Imagens:** uma `contact-sheet.png` ou `strip.png` por verificação, não quadros individuais.
Recorte ampliado só para checar um detalhe específico.
- **Testes:** filtre a saída (`pnpm test 2>&1 | grep -E "✖|^ℹ (pass|fail)|passaram|FALHA"`).
- **Código:** `Grep` com o nome da função antes de ler arquivos inteiros; leia por intervalo de linhas.
- **Renders:** um render de prévia por iteração; o perfil final só no fim. Não renderize para
testar algo que os testes headless ou `--validate-only` já cobrem.
- **Comandos longos de saída** (pnpm install, import da Godot): sempre com `| tail -n 5`.
- **Imagens, regra dura:** no máximo UMA por render, escolhida pelo `frame_check.py`. Nada de abrir quadros em
lote nem gerar imagens de QA próprias (ex.: `output/castaways-qa/`): cada imagem fica no histórico e é reenviada
a cada turno. Medido na execução #8 (Codex, cena Godot): ~100 imagens em resolução cheia → 26 milhões de caracteres
de saída de ferramenta, 6,83 milhões de tokens de entrada, 54 chamadas, 29 min.
- **Pesquisa na web (documental):** busque o termo dentro da página e use 3–5 fontes; página aberta inteira custa
30–40 mil caracteres (execução #6: 1,06 milhão de tokens de entrada).
- **Retomada (resume)** nas duas CLIs reenvia todo o histórico (vem do cache, mas conta): conversa longa fica cara a
cada mensagem. Com contexto já grande, abra nova execução com o resumo do que falta.
## Custo fixo dos agentes do painel (medido em 17/11/2026)
Código: `panel/src/lib/agents.ts`. Detalhes e correções de sintoma em [gotchas.md](gotchas.md) (itens 133–135).
| Provedor | O que o painel passa | Efeito medido |
|---|---|---|
| Claude CLI | `CLAUDE_LEAN_FLAGS`: `--setting-sources project,local --strict-mcp-config --tools Read,Edit,Write,Glob,Grep,Bash,Agent,Skill,TodoWrite` | prompt trivial no Haiku: 1º turno 62,4 mil → 14,9 mil tokens de entrada só com as flags (18,6 mil com o conjunto completo do painel, que inclui Agent); partida 8,0 s → 4,3 s. Sem as flags carregava plugins/MCP/hooks/skills do usuário (61 ferramentas, 5 MCPs, 310 skills, 78 agentes, 442 comandos). Subagentes do projeto (`.claude/agents`) e a skill `cenaforge` continuam visíveis |
| Claude CLI | `--max-budget-usd` por tarefa (`CLAUDE_BUDGET_USD`: story 1,5 · script 1,5 · branches 2,5 · scene 1 · godot 3 · free 3) | `error_max_budget_usd` vira "continue a conversa". A CLI não tem `--max-turns` |
| Codex | `codexLeanOverrides`: `-c model_reasoning_effort` por tarefa (story/script/branches/godot = medium, scene = low, free = o do `config.toml`), `mcp_servers.<nome>.enabled=false` para cada servidor do `config.toml`, plugins `computer-use@openai-bundled` e `unified-computer-use@openai-bundled` desligados (tira `cua_repl`, ~6,5 mil caracteres por turno) | fixo do Codex ~18–19 mil tokens no 1º turno; `base_instructions` ~21 mil caracteres |
Referência de peso: na execução #7 (cena Godot, Opus, US$ 3,09, 26 chamadas) o fixo era ~49 mil tokens por chamada e
somou 2,8 milhões de tokens lidos do cache — por isso o corte do fixo vale mais que qualquer ajuste de prompt.
### Juiz do Clipador (`clipper/app/judge.py`, medido em 17/11/2026)
Cada chamada é um processo novo de CLI: 2 por candidato (analista com 6–8 quadros 768×432 + editor só texto). Live de
3,7 h = 75 candidatos = ~150 chamadas; padrão Codex `gpt-6-luna`, esforço low.
| Provedor | O que o juiz passa | Efeito medido |
|---|---|---|
| Codex | `codex_lean_overrides(search)`: sem `--search`, `features.{plugins,apps,shell_tool,unified_exec,code_mode_host,sleep_tool,skill_search,tool_suggest,in_app_browser,browser_use}=false` + `computer_use,image_generation,goals,hooks=false`, `mcp_servers.<nome>.enabled=false`, plugins computer-use off, e o `system` num instructions.md temporário via `-c model_instructions_file='<caminho>'` (stdin só com o prompt). Com `--search` saem só os extras e o `system` fica no stdin. `view_image` fica ligado | antes: ~77 mil caracteres fixos (~19 mil tokens: instruções 18 mil, ferramentas 46,5 mil, skills/apps ~12 mil) ≈ 2,9 mi tokens naquela live, a mesma cota que bloqueou o agente do painel. Depois: instruções 105 caracteres, ferramentas 29 mil (sobram `exec` e `collaboration`, que `-c` não remove), fixo ≈ 35 mil caracteres (~9 mil tokens, −55%, estimativa). Imagem chega como `input_image`. **Resposta do modelo não validada** (cota esgotada até 16h27 de 17/11) |
| Claude | `--setting-sources project,local` (além de `--system-prompt`, `--tools`, `--strict-mcp-config`, `--no-session-persistence`) | Haiku: fixo 3,7 → 2,6 mil tokens (−31%), 5,5 → 2,8 s por chamada |
Propostas não implementadas (mudam recall; exigem decisão do usuário): na sessão 3, o juiz descartou 33 de 75
candidatos (44%) e, na origem `face`, 15 de 21 (heurística média 3,07). Opções: pré-filtro por pontuação antes do LLM
ou juntar analista+editor numa chamada.
Os prompts do painel (`panel/src/lib/prompts.ts`) já mandam: godot usa `frame_check.py` e uma imagem por render;
story/script/branches terminam com `check_script.py`; nenhum agente aciona `cenaforge-skill-updater` nem
`cenaforge-token-auditor`. `CLAUDE_ALLOWED_TOOLS` libera `frame_check.py` e `check_script.py` via Bash.
@@ -0,0 +1,190 @@
# Ferramentas do CenaForge
Inventário do que o pipeline usa, do que está planejado e de como avaliar uma ferramenta nova.
Versões abaixo foram **verificadas** na data indicada; ao trocar de versão, rode o render de
prévia e registre aqui (via `cenaforge-skill-updater`).
## Em uso
| Ferramenta | Versão testada | Papel | Como é localizada | Verificada em |
|---|---|---|---|---|
| Godot (edição padrão, GDScript) | 4.7.2.stable.official (ed1daf0bf) | monta e anima a cena (rua 3D `main.tscn`; documentário em `doc.tscn`: 2D por `doc2d_canvas.gd`, `_draw` + SystemFont Segoe UI/Arial/DejaVu; 3D pela biblioteca `godot/library/`: `island` com FastNoiseLite, MultiMesh, shader de mar e ProceduralSky; `castaways` sobre os kits `godot/kits/` com malha por SurfaceTool); Movie Maker grava PNG | `GODOT_BIN` → `PATH` (`godot`, `godot4`) → `.tools/godot-<versão>/Godot_v*-stable_win64.exe` | 16/11/2026 (reconferida 17/11/2026; `doc2d` e `doc3d` `island`/`castaways` com render ok em 17/11/2026) |
| Renderizador Godot | Mobile (Vulkan) | sombras direcionais, MSAA 4x, névoa, tonemap | método `mobile`, `msaa_3d=2` (4x) e sombra 4096 em `project.godot`; névoa e tonemap Filmic em `street_builder.gd`; ACES + névoa na ilha (`godot/library/island/template.gd`) | 16/11/2026 (ilha: 17/11/2026) |
| FFmpeg | 7.1.1 essentials (gyan.dev) | PNG → MP4; áudio AAC; quadros de inspeção; montagem documental do painel (`zoompan`, `boxblur` + `overlay` na foto horizontal, `drawtext`, concat `-c copy`; `panel/src/lib/montage-ffmpeg.ts`, fonte Segoe UI Bold/Arial Bold) | `FFMPEG_BIN` → `PATH` | 16/11/2026 (montagem: 17/11/2026) |
| FFprobe | 7.1.1 | verificação do MP4 e duração do áudio | `FFPROBE_BIN` → `PATH` | 16/11/2026 |
| Encoder de vídeo | `libx264` (preset medium, CRF 18) | H.264 yuv420p | ordem: libx264 → h264_nvenc → libopenh264 (`tools.ts`) | 16/11/2026 |
| Node.js | 24.19.0 (mínimo ≥ 20.10) | lançador | — | 16/11/2026 |
| pnpm | 11.22.0 | scripts e lockfile | — | 16/11/2026 |
| tsx | 4.23.15 | executa o TypeScript do lançador | devDependency | 16/11/2026 |
| TypeScript | 7.0.2 (compilador nativo) | `pnpm typecheck` | devDependency | 16/11/2026 |
| @types/node | 24.19.2 | tipos | devDependency | 16/11/2026 |
| Next.js / React / Tailwind | 16.4.6 / 19.3.0 / 4.3.3 | painel (`panel/`) | dependências do workspace | 16/11/2026 |
| @xyflow/react | 13.0.1 | árvore de vertentes na aba Fluxo (`panel/src/components/story-flow.tsx`) | dependência do painel | 16/11/2026 |
| SQLite | `node:sqlite` (Node 24) | banco do painel, sem dependência nativa | embutido | 16/11/2026 |
| Codex CLI | 0.169.0 (`@openai/codex`) | agente no painel (`codex exec --json -m <slug>`, sandbox `workspace-write`); modelos lidos de `~/.codex/models_cache.json` (panel.md, "Agentes e modelos") | `CODEX_BIN` → `.exe` no PATH → `codex.js` ao lado do `codex.cmd` do npm | 17/11/2026 |
| API do Wikimedia Commons (`commons.wikimedia.org/w/api.php`) | sem versão (HTTP público, sem chave; User-Agent genérico) | fotos reais por trecho na montagem documental (`panel/src/lib/image-search.ts`), com autor, licença e página de origem nos créditos | chamada direta do painel | 17/11/2026 (`ep01.montage.json`: 5 fotos do Commons com licença CC registrada; MP4 de 88,3 s; licença não conferida na página de cada foto) |
| Claude Code CLI | 2.1.314 | agente chamado pelo painel (`-p`, `stream-json`, `--resume`, `--model claude-*-5-5`/`claude-fable-5-2`) | `CLAUDE_BIN` → `PATH` (`claude.exe`) | 17/11/2026 |
Hardware do teste de referência: i9-13900K, 64 GB, RTX 2060 SUPER. Tempos: prévia 540×960
42–44 s; final 1080×1920 ~160 s. A etapa de render da Godot ocupa 94–96% do total, dominada
pela codificação PNG (105 ms/quadro na prévia, 404 ms no final; ~90–91% do total); GPU
1,9/4,5 ms por quadro. Cena 2D (`doc2d`, 17/11/2026, `report.json`): prévia 540×960 de 5 s em 2,7–4,3 s; final
1080×1920 de 4,4–14,3 s em 7,4–21,5 s por cena (9 cenas). Cena 3D `island` (`doc3d`, 17/11/2026, `report.json`): prévia
540×960 de 5 s em 9,4–14,3 s (Godot 9–13 s, 13 execuções); final 1080×1920 de 9,1 s em 42,9 s (Godot 39,1 s). Cena 3D
`castaways` (17/11/2026, `report.json`): prévia 540×960 de 4–5 s em 5,8–15,6 s (65 execuções `teste-cast-*`); final
1080×1920 de 2,8–12,3 s em 9,8–89,7 s por cena (11 cenas da montagem dos náufragos).
## Serviço de voz (`voice/`) — instalado, ainda fora do render
Serviço FastAPI local em `127.0.0.1:4510`, cópia adaptada do `dropsz_voice` (o original não é
alterado). Instalado por `setup.bat` → `scripts/setup.ps1`; fixações em `voice/requirements*.txt`
e `voice/models.lock.json`. Consumido pela página Vozes do painel (`panel/src/lib/voice.ts`).
Evidência (16/11/2026): `pnpm test:voice` → 133 passed (conferido nesta manutenção; inclui Kokoro/Google/Azure simulado/clone e flag `offline` por motor); legenda pelo painel na CPU: 6,5 s de fala
em 2,5 s, 14 palavras e `.srt`; fumaça
`voice/scripts/smoke.py` gerou os WAV das três vozes e a transcrição em `output/voice-smoke/`;
setup completo rodou 2x com saída 0 (repetível); `torch 2.11.0+cu128`, `cuda True`;
`VoiceConverter` do Applio importa no `voice/.venv` com device `cuda:0`; pré-requisitos em
`voice/vendor/applio/rvc/models/` (`predictors/rmvpe.pt`, `predictors/fcpe.pt`,
`embedders/contentvec/pytorch_model.bin`).
Catálogo com 76 vozes (16/11/2026): 12 Edge, 3 Piper, 45 Kokoro, 2 Google, 14 Azure (contagem
conferida no `catalog.json`; as Azure só aparecem com `VOICE_AZURE_KEY`). Antes, com 15 (informado): `fetch_models.py --group v1` conferiu sha256 de
cadu/jeff; `load_catalog(verify=True)` carregou 15; amostras transcritas com Whisper `small` —
Edge todas `pt` (prob ≥ 0,99), cadu correto, jeff erra palavras longas. `edresson` (Piper low,
16 kHz) fora de propósito. Piper não tem feminina pt-BR; a feminina offline agora é `kokoro-pf-dora`.
Kokoro (informado, 16/11/2026): as 54 vozes leram frase pt-BR, transcrição com Whisper `small` →
45 com 100% das palavras e idioma `pt` entraram; excluídas `af_bella`, `af_nicole`, `bf_alice`,
`bf_emma`, `bf_isabella`, `bm_fable`, `em_santa`, `ff_siwis`, `jf_alpha`.
**Nenhum render usou o serviço ainda** — o WAV entra no vídeo só via `audio.file`.
| Ferramenta | Versão verificada | Papel |
|---|---|---|
| uv | 0.11.26 | cria `voice/.venv` (o Python do sistema não é tocado) |
| Python | 3.12.13 | `voice/.venv` |
| FastAPI / uvicorn | 0.159.1 / 0.54.0 | HTTP (`uvicorn app.main:build --factory`, chamado por `scripts/dev.ts`) |
| edge-tts | 7.3.1 | 12 vozes online do catálogo (`pt-br-*`, `pt-pt-*`, `multi-*`) |
| piper-tts / onnxruntime | 1.8.0 / 1.31.0 | vozes `pt-br-faber`, `pt-br-cadu`, `pt-br-jeff` (offline, CPU, medium 22050 Hz) |
| kokoro-onnx / phonemizer / espeakng-loader | 0.6.1 / 3.6.0 / 0.2.4 | 45 vozes `kokoro-*` (offline, CPU; Kokoro-82M **fp16**, Apache-2.0; um modelo + `voices-v1.0.bin` do release `model-files-v1.1` de thewh1teagle/kokoro-onnx) |
| gTTS | 2.5.4 | `google-pt-br`, `google-pt-pt` (online; API não oficial do Google Tradutor; só normal/lenta) |
| faster-whisper / ctranslate2 / av | 1.2.1 / 4.8.3 / 19.0.2 | transcrição com tempos; modelos `base`, `small`, `medium`, `large-v3-turbo` |
| nvidia-cublas-cu12 / nvidia-cudnn-cu12 | 12.9.2.10 / 9.26.0.51 | DLLs CUDA 12 para o Whisper na GPU (só com GPU NVIDIA) |
| Applio | 3.7.0 (`voice/vendor/applio`) | RVC: vozes de personagem |
| torch / torchaudio | 2.11.0+cu128 (com GPU) ou 2.11.0+cpu (sem) | motor do Applio; o setup pede a variante explícita |
### Clonagem de voz (`voice/.venv-clone`, opcional: `setup.bat -Clone`)
Venv separado porque o Chatterbox conflita com o `voice/.venv` (gotchas, item 65). Worker
`voice/clone/worker.py` (stdlib, 127.0.0.1:4511, mesma `X-Service-Key`) chamado pelo `CloneEngine`.
Detalhes e formato da voz clonada: `voice/README.md`, "Clonagem de voz".
| Ferramenta | Versão verificada (16/11/2026) | Papel |
|---|---|---|
| Python | 3.12.13 | `voice/.venv-clone` |
| chatterbox-tts | 0.1.7 (Chatterbox Multilingual, Resemble AI, MIT; pt suportado) | clonagem a partir de 10–30 s de gravação; WAV 24 kHz; marca d'água PerTh; sem velocidade |
| torch / torchaudio | 2.6.0+cu124 (`torch.cuda.is_available()` = True) | fixado pelo Chatterbox |
| numpy / transformers | 1.26.4 / 5.2.0 | fixados pelo Chatterbox |
| Pesos | `ResembleAI/chatterbox`, revisão `main` (~3,3 GB em `data/voice/models/clone-hf/`) | **não fixados em commit nem sha256** (gotchas, item 64) |
Evidência informada (16/11/2026, RTX 2060 SUPER 8 GB, worker real na GPU; não registrada em
`doc/TEST_RESULT.md`): modelo carregou em 10 s (pesos já baixados); referência sintética de 10,7 s
(Kokoro `pm_alex`); fala 1: 6,0 s de áudio em 20,5 s (inclui condicionamento); fala 2: 7,1 s em
10,5 s; Whisper `small` transcreveu as duas exatamente (idioma `pt`, prob. 1,0). Não testado: CPU,
referência de voz humana real, fluxo completo pelo painel (upload → síntese).
Medições informadas (16/11/2026, i9-13900K, RTX 2060 SUPER 8 GB; não registradas em
`doc/TEST_RESULT.md`): Edge ~2,5–3 s por fala de ~6 s; Piper ~0,02 s (modelo já carregado);
Whisper `small` na CPU 2,7 s para 6,5 s de fala com palavras. Kokoro (CPU): `kokoro-pf-dora` 3,2 s
de áudio em 2,4 s (1ª síntese, carrega o modelo); depois `pm-alex` 0,6 s, `am-michael` 0,7 s.
Google: `google-pt-br` 4,8 s de áudio em 0,8 s. GPU disputada: ver `gotchas.md`.
Não verificado: conversão RVC com modelo real (`VOICE_ENABLE_RVC=1`, mas nenhum `.pth`
instalado), Whisper `large-v3-turbo` (só `small` baixado em `data/voice/models/whisper/`) e o
download de modelo de Whisper disparado pelo painel.
## Clipador (`clipper/`) — cortes de live, fora do render da Godot
Serviço FastAPI em `127.0.0.1:4520`. Instalado no passo 6b do `scripts/setup.ps1`, com as versões
fixadas em `clipper/requirements*.txt`. Detalhes e evidência em [clipper.md](clipper.md).
Evidência: `pnpm test:clipper` → 270 passed (17/11/2026, com apagar cortes e veto do rejeitado no juiz e na fila; sem dependência
Python nova nem ferramenta nova). Fase 1 (16/11/2026): uma live real da Twitch gerou 5 cortes H.264 1080×1920 + AAC. Horizontal 1920×1080: só
render de teste conferido no ffprobe (informado); nenhum corte horizontal de live ainda.
| Ferramenta | Versão verificada (16/11/2026) | Papel |
|---|---|---|
| Python | 3.12.13 | `clipper/.venv` (criado pelo uv) |
| FastAPI / uvicorn / httpx / websockets | 0.159.1 / 0.54.0 / 0.28.1 / 17.4 | HTTP do serviço; chamadas à voz; chat da Kick (Pusher) |
| Streamlink | 8.6.3 (reconferido em 17/11/2026) | captura de live/VOD (`clipper/.venv/Scripts/streamlink.exe`); qualidade por `--stream-sorting-excludes` e, na Twitch, `--twitch-supported-codecs h264,h265` (`clipper/app/capture.py`). HEVC real da Twitch não testado (nenhuma live 2K no ar) |
| pytest | 9.1.1 (fixado em `requirements-dev.txt`) | `pnpm test:clipper` |
| FFmpeg | 7.1.1 essentials, com filtro `ass` (libass) — reconferido em 17/11/2026 | blocos `-f segment`, render vertical e horizontal, legenda queimada com `fontsdir`, reenquadramento (`perspective` `eval=frame`), camadas (`alphamerge`/`overlay`); decodifica HEVC; sem libdav1d (AV1 não é pedido na captura); NVENC quando houver (`CLIPPER_ENCODER=auto`; horizontal com NVENC não testado) |
| Fontes empacotadas (`assets/fonts/`) | google/fonts no commit `7af0d90b4d532ffa4b041937b560c6df4e7b1e95`, sha256 em `fonts.lock.json` | ASS do Clipador e prévia do editor no painel. Licenças: Luckiest Guy Apache-2.0; Bangers, Anton, Bebas Neue, Poppins ExtraBold OFL-1.1 (texto ao lado de cada `.ttf`) |
| Codex CLI / Claude Code CLI | 0.169.0 (reconferida em 17/11/2026) / 2.1.314 (as mesmas da tabela "Em uso") | juízes analista + editor, varredura, câmera e pesquisa do jogo (`codex --search exec … -i <img> … -`), sem chave de API; padrão Codex `gpt-6-luna`. Claude: não testado |
| APIs públicas de emotes 7TV / BTTV / FFZ | sem versão (HTTP público, sem chave) | catálogo de emotes do canal e globais (`clipper/app/emotes.py`, cache 1 h; 7TV dá 404 em canal sem 7TV). Coberto só por teste sem rede; chamada real não registrada |
Rastreio de reação (`clipper/app/face.py` + `reaction.py`; detalhes em [clipper.md](clipper.md)). Versões conferidas
no `clipper/.venv` em 16/11/2026 (`importlib.metadata`). Evidência (`doc/FACE_BAKEOFF.md`): bancada e rastreio de
144 blocos numa cópia do banco; em 17/11/2026, serviço real ao vivo (instância 4521, 25/25 blocos, 1,71 s/bloco, p95
2,20 s, CPU média 16,8 % de um núcleo) e download real dos 4 pesos com sha256 conferido. Só CPU; GPU não testada.
| Ferramenta / peso | Versão verificada | Licença | Papel |
|---|---|---|---|
| mediapipe (Face Landmarker `face_landmarker.task` float16/1) | 1.2.3 | Apache-2.0 | 478 pontos + 52 blendshapes; 5–7 ms/quadro na bancada; bloco de 30 s em 1,71 s ao vivo (com gravação + transcrição juntas) |
| opencv-contrib-python (`cv2.FaceDetectorYN`) + YuNet `face_detection_yunet_2026may.onnx` | 5.0.0.93 (`cv2` 5.0.0) | Apache-2.0 / MIT (peso) | acha a câmera pelo rosto no quadro inteiro (piso de confiança 0,7: gotchas, item 92). Sem `opencv-python-headless` junto (gotchas, item 80) |
| numpy | 2.5.5 | BSD | séries e recorte |
| onnxruntime + OpenSeeFace `osf_lm_model3_opt.onnx` / `osf_mnv3_detection_opt.onnx` | 1.32.0 | MIT / BSD-2-Clause (pesos) | plano B (só posição, sem expressões; sem linha de rosto ao analista). Pesos reais no `face.py` em 17/11/2026: rosto 96,7–100 %, 12,3–13,9 ms/quadro (MediaPipe no mesmo trecho: 94,4–100 %, 9,8–13,2) |
Pesos fixados em `clipper/models.lock.json` (commit/caminho versionado + sha256), baixados em `data/clipper/models/`.
Descartados por licença (não integrar): SCRFD/InsightFace (pesos não comerciais), YOLO-Face (GPL/AGPL), LibreFace
(não comercial), OpenFace 3.0 (só pesquisa), Py-Feat (licença indefinida) — `doc/PLANO_RASTREIO_REACAO.md`.
## Publicador (`publisher/`) — instalado, sem envio real registrado
Serviço FastAPI em `127.0.0.1:4530` (detalhes em [publishing.md](publishing.md) e `publisher/README.md`). Instalado no
passo 6b2 do `scripts/setup.ps1`; versões fixadas em `publisher/requirements*.txt`. Evidência (17/11/2026):
`pnpm test:publisher` → 71 passed (rede e navegador simulados; reconferido pela skill depois das revisões de
segurança).
| Ferramenta | Versão verificada (17/11/2026, `publisher/.venv`) | Papel |
|---|---|---|
| Python | 3.12.13 | `publisher/.venv` (criado pelo uv) |
| FastAPI / uvicorn / pydantic / httpx | 0.159.1 / 0.54.0 / 2.14.1 / 0.28.1 | HTTP do serviço e chamadas às APIs das redes |
| playwright (Python) | 1.65.2 | **só o driver** para `connect_over_cdp` no Chrome/Edge do usuário (não rodar `playwright install`) |
| pytest | 9.1.1 | `pnpm test:publisher` |
| Chrome ou Edge instalado | versão da máquina (não registrada) | modo sessão: aberto como processo normal, CDP em 4540–4549 |
| DPAPI do Windows (`CryptProtectData`) | do sistema | cofre `data/publisher/vault.bin` |
## Planejadas ou candidatas — NÃO integradas
| Ferramenta | Para quê | Situação |
|---|---|---|
| Meshy | gerar modelos GLB (personagens, objetos) e rig | citada na especificação; não testada |
| Mixamo | animações para personagens com rig | citada como não obrigatória; não testada |
| `.glb` carregado por `GLTFDocument` em tempo de execução (Godot) | modelos prontos dentro de cenas da biblioteca (`library/<id>/assets/`) | **só documentado** em `doc/godot/cenas.md`; nenhum `.glb` no repositório nem render com ele (17/11/2026). Personagens e barcos atuais são procedurais (`godot/kits/`) |
| Serviço de voz no render | narração por fala e legenda automática a partir de `X-Detail: words` | próxima etapa; `scripts/lib/audio.ts` ainda não chama o serviço |
| Applio pessoal + projetos de narração do usuário | modelos RVC já treinados | existe no PC do usuário; **não instalar nem modificar**; possível origem de `.pth`/`.index` para `data/voice/models/rvc/<id>/` — não testado |
| Modelo RVC neutro pt-BR | primeira voz de personagem e teste RVC ponta a ponta | nenhum com licença clara: voice-models.com não tem pt-BR neutro; Adam (ElevenLabs), Jorge (Loquendo) e E-Girl têm licença não informada; no Hugging Face (16/11/2026) só imitações de personagem/dublador sem licença → **não usar**; `user-voices.json` segue sem voz |
| Azure Speech (motor `azure`, REST sem SDK, WAV `riff-24khz-16bit-mono-pcm`) | 14 vozes neurais pt-BR `azure-*` (chave do usuário; plano F0 0,5 M caracteres/mês, informado) | **código pronto** (`AzureEngine` em `voice/app/engine.py`, card no painel), mas **sem chave real**: testado só com `urlopen` simulado → não validado; nenhuma dependência nova |
| Vozes SAPI do Windows (Microsoft Maria Desktop pt-BR; Daniel/Maria OneCore) | TTS local sem download | existem na máquina; não integradas (robóticas) |
| Vozes "do TikTok/CapCut" famosas (Galvão Bueno, Ludmilla, narrador do CapCut Pro) | — | proprietárias ou imitação de pessoa real → **não copiar**. Equivalentes genéricos já no catálogo: Edge (Antonio/Francisca/Thalita) e Google |
| APIs oficiais: YouTube Data API v3, TikTok Content Posting API, Instagram API with Instagram Login | envio pelo Publicador (`publisher/app/platforms/*_api.py`) | **código pronto, testado só com chamadas simuladas**; nenhuma conta conectada nem envio real. Fatos e limites em `doc/publicacao/PESQUISA.md` (rupload do Instagram a testar) |
| Modo sessão logada (YouTube Studio, TikTok Studio, instagram.com) | envio pelo site com a sessão do usuário | **código pronto, seletores não validados com conta real**; viola os termos das redes |
| Chat do YouTube no Clipador | sinal de chat em lives do YouTube | exige a API do YouTube; não integrado (hoje só áudio + transcrição) |
| Saída AVI/MJPEG do Movie Maker | reduzir o tempo gasto em PNG | ideia; não medida |
Não afirme que uma candidata "funciona" ou "está integrada" até haver evidência registrada aqui.
## Como avaliar e adotar uma ferramenta nova
Antes de integrar, registre nesta tabela a resposta a cada item:
1. **Origem e licença** — fonte oficial, licença de uso dos arquivos gerados, custo.
2. **Interface** — CLI, API ou só interface gráfica; precisa de rede/conta? Funciona offline?
3. **Saída** — formato (GLB, FBX, WAV…), escala, orientação dos eixos, materiais, esqueleto,
animações incluídas. Lembre: rig corporal não garante lip sync nem atuação facial.
4. **Encaixe no pipeline** — onde entra (preparação de assets, nunca dentro do render), qual nó
adaptador corrige escala/orientação, como fica determinística.
5. **Teste mínimo** — um asset/arquivo real passando pelo render de prévia, com inspeção visual.
6. **Versão fixada** — versão exata testada, data, e onde o lançador a encontra.
Depois de adotada: mover para "Em uso", atualizar `scripts/lib/tools.ts` se o lançador a chama,
README e a tabela "Onde mexer" do `SKILL.md`. Dependência Python do serviço de voz: fixe a versão
em `voice/requirements*.txt`, peso novo em `voice/models.lock.json` com URL imutável (commit no
Hugging Face — nunca `resolve/main` — ou asset de release versionado no GitHub) e sha256, e rode `pnpm test:voice` + a fumaça.