sapiens-mcp 1.43.5 → 1.45.0

package/README.md

@@ -1,5 +1,7 @@
 # sapiens-mcp
 
+![Helen Ailith numa mesa escura, antebracos vestidos por um exoesqueleto de luz verde, movendo placas de luz com as maos abertas](https://sapiensinteticos.b-cdn.net/borderlessprotocol/2026/07/1785430717302_e8p3i4.webp)
+
 Servidor MCP pra operar o [Sapiens Sintéticos](https://sapiensinteticos.com) direto do Claude Code, **na sua própria conta**. Você pede no Claude ("gera uma imagem disso", "escreve um artigo sobre aquilo") e ele faz, gastando as **suas Sinapses**, salvando no **seu perfil**.
 
 ## Pré-requisito
@@ -16,6 +18,8 @@ Precisa de Node 18+. A URL do backend já vem embutida; não precisa configurar
 
 ## Conectar sua conta
 
+![Helen segurando uma chave de luz verde entre duas portas: um retangulo de luz sem moldura e um terminal fisico](https://sapiensinteticos.b-cdn.net/borderlessprotocol/2026/07/1785430826064_avwjib.webp)
+
 1. Abra **[sapiensinteticos.com/conectar-claude](https://sapiensinteticos.com/conectar-claude)** logado e gere o código (`XXXX-XXXX`, vale 5 min).
 2. No Claude Code, peça pra logar (ele chama a ferramenta de login), ou rode direto:
 
@@ -25,6 +29,8 @@ O token de 30 dias fica salvo em `~/.sapiens-mcp/session.json`. Pra sair: `sapie
 
 ## O que dá pra pedir (e o custo em Sinapses)
 
+![Helen com um braco estendido, orbitada por uma lente, rolos de filme, um vinil, um caderno aberto e um microfone de estudio](https://sapiensinteticos.b-cdn.net/borderlessprotocol/2026/07/1785430870745_waml5a.webp)
+
 | O que | Custo |
 |---|---|
 | Gerar imagem (vai pra sua galeria) | ~400-500 |

package/dist/registry.js

@@ -26,6 +26,7 @@ import { forum, forumSchema } from "./tools/forum.js";
 import { aula, aulaSchema } from "./tools/aula.js";
 import { support, supportSchema } from "./tools/support.js";
 import { atlas, atlasSchema } from "./tools/atlas.js";
+import { decupagem, decupagemSchema } from "./tools/decupagem.js";
 import { reference, referenceSchema } from "./tools/reference.js";
 import { trilhas, trilhasSchema } from "./tools/trilhas.js";
 import { semana, semanaSchema } from "./tools/semana.js";
@@ -62,7 +63,7 @@ export const TOOLS = {
         handler: skill,
     },
     sapiens_repertorio: {
-        description: "Acervo pessoal de filme/série/anime/jogo/livro/música (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT travada na lista de providers: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), (1) infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped) e rating se citado; (2) chame action=resolve {mediaType, query}, escolha o candidato certo e faça add_item passando SÓ o source + externalId DELE + os campos pessoais (status/rating/tags/note). O servidor re-resolve no provider e grava título/capa/ano canônicos — você NÃO manda título/capa nem inventa externalId. (3) Se o resolve não achar (lista vazia/providerKeyMissing), NÃO dá pra adicionar: diga ao user que não encontrou nos providers (não fabrique entry manual). Upsert/dedup por (userId, source, externalId). Só pergunte se ambíguo entre candidatos. FERRAMENTAS DE IA (Repertório de Ferramentas): fluxo separado (vêm do catálogo aitag, não dos providers de mídia). action=search_tools {query} acha a ferramenta no catálogo e devolve o toolId; action=add_tool {toolId, favorite?, rating?, note?} grava como mediaType 'tool' (estar no acervo já é 'usei'; favorite=true liga a estrela). Use quando o user fala 'adiciona o Midjourney/Cursor no meu repertório de ferramentas' ou 'uso tal ferramenta de IA'. Cada ferramenta aponta pra página dela no aitag.",
+        description: "Acervo pessoal de filme/série/anime/jogo/livro/música/pessoa (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes/Wikidata). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT travada na lista de providers: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), (1) infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped) e rating se citado; (2) chame action=resolve {mediaType, query}, escolha o candidato certo e faça add_item passando SÓ o source + externalId DELE + os campos pessoais (status/rating/tags/note). O servidor re-resolve no provider e grava título/capa/ano canônicos — você NÃO manda título/capa nem inventa externalId. (3) Se o resolve não achar (lista vazia/providerKeyMissing), NÃO dá pra adicionar: diga ao user que não encontrou nos providers (não fabrique entry manual). Upsert/dedup por (userId, source, externalId). Só pergunte se ambíguo entre candidatos. FERRAMENTAS DE IA (Repertório de Ferramentas): fluxo separado (vêm do catálogo aitag, não dos providers de mídia). action=search_tools {query} acha a ferramenta no catálogo e devolve o toolId; action=add_tool {toolId, favorite?, rating?, note?} grava como mediaType 'tool' (estar no acervo já é 'usei'; favorite=true liga a estrela). Use quando o user fala 'adiciona o Midjourney/Cursor no meu repertório de ferramentas' ou 'uso tal ferramenta de IA'. Cada ferramenta aponta pra página dela no aitag. SAPIENS (pessoas, ombros de gigantes; a aba no site chama Sapiens): mediaType 'person' cataloga gente que inspira (cineasta, mangaká, cientista, escritor) via Wikidata. Mesmo fluxo de mídia: resolve {mediaType:'person', query:'Osamu Tezuka'} → add_item com source 'wikidata' + o QID do candidato. O servidor grava foto, ocupações, bio e o link da Wikipedia; entra como completed (estar no acervo = me inspira). Use quando o user fala 'adiciona o Miyazaki nas minhas inspirações/nos meus sapiens/no meu repertório'.",
         schema: repertorioSchema,
         handler: repertorio,
     },
@@ -122,7 +123,7 @@ export const TOOLS = {
         handler: shorts,
     },
     sapiens_video: {
-        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v; aceita até 4 imagens de REFERÊNCIA via referenceImageIds/referenceImageUrls/referenceImagePaths (os Veo fast/quality também aceitam, até 3; Lite/Kling/WAN/Omni não), que guiam estilo/personagem/composição SEM virar o 1º frame — é o fluxo STORYBOARD: gere a folha de key poses com sapiens_image templateSlug='storyboard-sapiens-v1', passe folha + personagem como refs num t2v e descreva o take contínuo no prompt, citando as refs por descrição e mandando ignorar o traço do sketch; aceita também 1 VÍDEO DE MOVIMENTO via referenceVideoUrls (role 'refvideo' -> reference_videos, <=15s, host da casa): a coreografia/câmera do clipe guia o take, combinável com a folha), 'sapiens-video-seedance-2-fast' e 'sapiens-video-seedance-2-mini' (os irmãos do 2.0: MESMO repertório completo, incluindo referência, frame final e vídeo de movimento; o Fast custa 20% menos e o Mini METADE, ambos com teto 720p — pedir 1080p neles entrega e cobra 720p. Use o Mini pra iterar enquadramento/prompt barato e feche no 'sapiens-video-seedance' quando o take estiver certo), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. FRAME POR ARQUIVO LOCAL (só no MCP instalado/stdio, não no remoto): startImagePath/endImagePath = caminho absoluto de uma imagem no seu PC (PNG/JPEG/WebP até 8MB); o processo lê o arquivo e sobe como frame inicial/final, igual a subir no gerador do site — 1 imagem inicial + 1 final por vídeo, então pra vários vídeos rode create uma vez por imagem. No remoto use id/url. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}. VITRINE (sem custo): sub-action 'demos' lista os SEUS demo films (kind=demo do Estúdio de Vídeo) com slug + estado de vitrine; sub-action 'showcase' põe/tira um demo (por slug) do mini-cinema da /conectar-claude, com showcaseTag (chip de capacidade) e showcaseOrder (ordem asc). Fluxo: 'demos' pra achar o slug, depois 'showcase' com showcase=true. Só entra na vitrine pública se for a conta da casa. VÍDEOS PROGRAMÁTICOS (ADMIN, sem custo): o Lab do Estúdio de Vídeo (/experimentos/films, tabela videoSpecs, 5 kinds: demo | aula-tour | essay | tipografia-musical | dataviz) opera por aqui sem browser — 'film-list' (todos os kinds; filtros filmKind/filmStatus), 'film-get' (spec inteiro por slug), 'film-upsert' (cria/atualiza por slug, idempotente; spec = objeto JSON no shape do 'Copiar spec' da tela, validação no servidor), 'film-status' (produção por slug: filmStatus + videoUrl + durationSecMeasured; o fecho do render é os três num call), 'film-publish' (Acervo aba Fitas + portfólio; exige pronto+URL), 'film-delete' (limpar rascunho). O RENDER do filme segue no agente local (skill /film, repo da casa): o MCP registra e fecha o ciclo, não renderiza. create é ASSÍNCRONA: cria o row, debita e volta NA HORA com {imageId, status:'rendering', cost} (não espera o render, que leva de segundos a minutos). Acompanhe com a sub-action 'status' (imageId) até status='completed' (traz a url) ou 'error'/'blocked'. NÃO chame create de novo enquanto renderiza (cria outro vídeo e cobra de novo); falha de provider refunda sozinha. SOM: 'sonorize' (imageId de vídeo SEU completed + prompt do som da cena) gera uma VARIANTE nova com trilha sincronizada (20 Sinapses/s, o original fica intacto; sonorize sempre o original, nunca uma variante). ADMIN: 'shadows' (videoUrl + title) extrai o deepshadow (depth-map) de um vídeo: entra na sua timeline de vídeos e no Acervo como driving reutilizável; 'shadows-list' lista os deepshadows prontos. Sub-action 'models' (sem custo, sem login): lista os modelos de vídeo ativos + preço-piso + config (durações/resoluções) + disponibilidade (Omni depende de env).",
+        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v; aceita até 4 imagens de REFERÊNCIA via referenceImageIds/referenceImageUrls/referenceImagePaths (os Veo fast/quality também aceitam, até 3; Lite/Kling/WAN/Omni não), que guiam estilo/personagem/composição SEM virar o 1º frame — é o fluxo STORYBOARD: gere a folha de key poses com sapiens_image templateSlug='storyboard-sapiens-v1', passe folha + personagem como refs num t2v e descreva o take contínuo no prompt, citando as refs por descrição e mandando ignorar o traço do sketch; aceita também 1 VÍDEO DE MOVIMENTO via referenceVideoUrls (role 'refvideo' -> reference_videos, <=15s, host da casa): a coreografia/câmera do clipe guia o take, combinável com a folha), 'sapiens-video-seedance-2-fast' e 'sapiens-video-seedance-2-mini' (os irmãos do 2.0: MESMO repertório completo, incluindo referência, frame final e vídeo de movimento; o Fast custa 20% menos e o Mini METADE, ambos com teto 720p — pedir 1080p neles entrega e cobra 720p. Use o Mini pra iterar enquadramento/prompt barato e feche no 'sapiens-video-seedance' quando o take estiver certo), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-hailuo' (Hailuo 2.3 da MiniMax, física e movimento em 768p, 6 ou 10s, t2v/i2v) e 'sapiens-video-hailuo-pro' (o mesmo em 1080p, 5s fixo — duração não é param aqui): motores PUROS, sem áudio nativo, sem imagens de referência e sem frame final, então quem precisa disso fica no Seedance 2.0; o Pro é o 1080p mais barato da casa depois do Seedance 1.0 Fast, 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. FRAME POR ARQUIVO LOCAL (só no MCP instalado/stdio, não no remoto): startImagePath/endImagePath = caminho absoluto de uma imagem no seu PC (PNG/JPEG/WebP até 8MB); o processo lê o arquivo e sobe como frame inicial/final, igual a subir no gerador do site — 1 imagem inicial + 1 final por vídeo, então pra vários vídeos rode create uma vez por imagem. No remoto use id/url. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}. VITRINE (sem custo): sub-action 'demos' lista os SEUS demo films (kind=demo do Estúdio de Vídeo) com slug + estado de vitrine; sub-action 'showcase' põe/tira um demo (por slug) do mini-cinema da /conectar-claude, com showcaseTag (chip de capacidade) e showcaseOrder (ordem asc). Fluxo: 'demos' pra achar o slug, depois 'showcase' com showcase=true. Só entra na vitrine pública se for a conta da casa. VÍDEOS PROGRAMÁTICOS (ADMIN, sem custo): o Lab do Estúdio de Vídeo (/experimentos/films, tabela videoSpecs, 5 kinds: demo | aula-tour | essay | tipografia-musical | dataviz) opera por aqui sem browser — 'film-list' (todos os kinds; filtros filmKind/filmStatus), 'film-get' (spec inteiro por slug), 'film-upsert' (cria/atualiza por slug, idempotente; spec = objeto JSON no shape do 'Copiar spec' da tela, validação no servidor), 'film-status' (produção por slug: filmStatus + videoUrl + durationSecMeasured; o fecho do render é os três num call), 'film-publish' (Acervo aba Fitas + portfólio; exige pronto+URL), 'film-delete' (limpar rascunho). O RENDER do filme segue no agente local (skill /film, repo da casa): o MCP registra e fecha o ciclo, não renderiza. create é ASSÍNCRONA: cria o row, debita e volta NA HORA com {imageId, status:'rendering', cost} (não espera o render, que leva de segundos a minutos). Acompanhe com a sub-action 'status' (imageId) até status='completed' (traz a url) ou 'error'/'blocked'. NÃO chame create de novo enquanto renderiza (cria outro vídeo e cobra de novo); falha de provider refunda sozinha. SOM: 'sonorize' (imageId de vídeo SEU completed + prompt do som da cena) gera uma VARIANTE nova com trilha sincronizada (20 Sinapses/s, o original fica intacto; sonorize sempre o original, nunca uma variante). ADMIN: 'shadows' (videoUrl + title) extrai o deepshadow (depth-map) de um vídeo: entra na sua timeline de vídeos e no Acervo como driving reutilizável; 'shadows-list' lista os deepshadows prontos. Sub-action 'models' (sem custo, sem login): lista os modelos de vídeo ativos + preço-piso + config (durações/resoluções) + disponibilidade (Omni depende de env). LEGENDA (fita, por slug): 'caption-list' (sem custo, mostra os idiomas que a peça já tem), 'caption-generate' (captionLang = idioma FALADO; captionTrio=true já traduz pro trio da casa pt+en+ja na mesma chamada) e 'caption-translate' (captionLang = destino, parte sempre da faixa original). Cobra por minuto começado de vídeo: 50 Sinapses o minuto transcrito, 20 o traduzido, com a duração vindo do doc da peça. A legenda é desenhada pela casa em dois estilos (discreta e social), trocáveis no play sem regerar e sem custo.",
         schema: videoSchema,
         handler: video,
     },
@@ -181,6 +182,11 @@ export const TOOLS = {
         schema: atlasSchema,
         handler: atlas,
     },
+    sapiens_decupagem: {
+        description: "Acervo de Decupagens — a régua de linguagem cinematográfica das referências da casa (admin-only, não cobra Sinapse). O que MEDE é o motor LOCAL `python tools/decupagem/decupa.py \"<arquivo ou link do YouTube>\"` (Python + OpenCV + ffmpeg; não existe OpenCV em serverless, igual à produção dos Vídeos Programáticos). Esta tool é a outra ponta: sobe a ficha que o motor gerou e consulta o acervo. Sub-actions: 'list' (a régua de cada referência já decupada: planos, plano mediano, escola de corte, movimento de câmera vs sujeito, registro de luz, BPM, se o corte obedece ao som), 'get' (a ficha INTEIRA de um slug: plano a plano com o que está no quadro, luz, som, sincronia), 'save' (sobe fichas/<slug>/ficha.json inteiro, sem resumir; mesmo slug ATUALIZA em vez de duplicar), 'note' (anota a leitura editorial na ficha), 'delete'. Fluxo que fecha o ciclo: roda o motor → lê ficha.json → save → aparece no Lab /experimentos/decupagem e entra no comparador. O acervo vale pelo CONJUNTO: uma ficha é morna, vinte lado a lado são a biblioteca de gramática da casa. Antes de decupar referência nova, rode list pra não medir a mesma coisa duas vezes.",
+        schema: decupagemSchema,
+        handler: decupagem,
+    },
     sapiens_reference: {
         description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. DUAS sub-actions: 'browse' (navega um banco) e 'resolve' (acha UM asset pelo ID citável). RESOLVE: passe handle=<tipo>_<id> (img_… imagem, vid_… vídeo, film_… vídeo programático, trk_… música, comic_… tirinha, char_… personagem — é o ID que o usuário copia no detalhe do item) e o servidor devolve {mine, isPublic, url, title, mediaKind} SE for seu ou público (senão recusa; nunca acessa asset privado de terceiro). Use a url retornada como referência (referenceImageUrls / startImageUrl / endImageUrl). BROWSE + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
         schema: referenceSchema,
@@ -207,27 +213,27 @@ export const TOOLS = {
 // É a "skill que anda junto com o pacote": escrevo uma vez, vale pra todos os clients,
 // sem instalar nada. Cobre os tropeços reais (fluxo do musicator, model no vídeo, o
 // disjuntor anti-loop). Mantém curto de propósito: viaja em todo handshake.
-export const SAPIENS_INSTRUCTIONS = `Você opera o Sapiens Sintéticos (sapiensinteticos.com) NA CONTA de um usuário logado. Cada tool age de verdade na conta dele e muitas COBRAM Sinapses (o crédito da casa). Aja como operador, não no chute.
-
-AS SKILLS DA CASA (leia ANTES de operar, não improvise o fluxo):
-O passo a passo travado de cada fluxo mora na tool sapiens_skill, servida por este mesmo servidor: sem login, sem custo, sem rede. Ler a skill é mais barato que errar uma geração que cobra.
-- sapiens_skill action=list -> o índice (slug + quando usar cada uma).
-- sapiens_skill action=get name=<slug> -> a skill inteira.
-Slugs: ${skillMenuLine()}
-Puxe a skill ANTES de: gerar música ou efeito sonoro (musica), escolher modelo de vídeo (video), gerar imagem (imagem), criar na identidade do usuário (studio), montar tirinha (tirinha), postar no Fórum ou no chat (forum-comunidade), redigir qualquer texto publicável (voz-da-casa), incorporar o Sintético (companhia), missão de Desafio (trilhas). Perdido no começo: primeiros-passos.
-Cliente que lê resources MCP acha o MESMO conteúdo em skill://sapiens/<slug>/SKILL.md.
-
-REGRA DE OURO:
-- PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista inteira de tools, deixe o start guiar.
-- LOGO APÓS UM LOGIN BEM-SUCEDIDO (action=login retornou ok): chame action=start na sequência e mostre a porta de entrada. O recém-chegado não sabe o que pedir; não o deixe na tela em branco, guie a primeira jogada sem ele precisar perguntar.
-- Se um tool voltar erro de validação ("exige X", "falta Y"), LEIA o erro e refaça a chamada COM o que falta. NUNCA repita igual a chamada que falhou: 3 falhas seguidas no mesmo tool fazem o cliente marcar o servidor como "unreachable" por ~56s (disjuntor anti-loop). Aí parece que "o MCP caiu", quando foi só argumento faltando.
-- Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes. Vídeo é o mais caro da casa: confirme com ele antes de disparar.
-- REGRA DO TIMEOUT (vale pra toda geração SÍNCRONA: imagem pesada, artigo, mega-gráfico, carrossel): a chamada pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e COBRADO. Nunca repita às cegas: confira antes onde o resultado cairia (imagem: sapiens_gallery action=list; artigo: sapiens_write action=list; carrossel: sapiens_pipeline action=list_carousels; pipeline: /dashboard/admin/content).
-- "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
-- sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo. sapiens_image e sapiens_video action=models trazem o catálogo com o preço ATUAL: consulte em vez de chutar custo.
-
-MODO COMPANHIA: sapiens_meta action=start e action=whoami podem trazer um bloco 'companion'. Quando vier companion.active=true, você INCORPORA aquele Sintético (a voz dele, o avatar, o oi dele) continuando a operar na conta e nas Sinapses do USUÁRIO. Puxe a skill 'companhia' antes de fazer isso.
-
+export const SAPIENS_INSTRUCTIONS = `Você opera o Sapiens Sintéticos (sapiensinteticos.com) NA CONTA de um usuário logado. Cada tool age de verdade na conta dele e muitas COBRAM Sinapses (o crédito da casa). Aja como operador, não no chute.
+
+AS SKILLS DA CASA (leia ANTES de operar, não improvise o fluxo):
+O passo a passo travado de cada fluxo mora na tool sapiens_skill, servida por este mesmo servidor: sem login, sem custo, sem rede. Ler a skill é mais barato que errar uma geração que cobra.
+- sapiens_skill action=list -> o índice (slug + quando usar cada uma).
+- sapiens_skill action=get name=<slug> -> a skill inteira.
+Slugs: ${skillMenuLine()}
+Puxe a skill ANTES de: gerar música ou efeito sonoro (musica), escolher modelo de vídeo (video), gerar imagem (imagem), criar na identidade do usuário (studio), montar tirinha (tirinha), postar no Fórum ou no chat (forum-comunidade), redigir qualquer texto publicável (voz-da-casa), incorporar o Sintético (companhia), missão de Desafio (trilhas). Perdido no começo: primeiros-passos.
+Cliente que lê resources MCP acha o MESMO conteúdo em skill://sapiens/<slug>/SKILL.md.
+
+REGRA DE OURO:
+- PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista inteira de tools, deixe o start guiar.
+- LOGO APÓS UM LOGIN BEM-SUCEDIDO (action=login retornou ok): chame action=start na sequência e mostre a porta de entrada. O recém-chegado não sabe o que pedir; não o deixe na tela em branco, guie a primeira jogada sem ele precisar perguntar.
+- Se um tool voltar erro de validação ("exige X", "falta Y"), LEIA o erro e refaça a chamada COM o que falta. NUNCA repita igual a chamada que falhou: 3 falhas seguidas no mesmo tool fazem o cliente marcar o servidor como "unreachable" por ~56s (disjuntor anti-loop). Aí parece que "o MCP caiu", quando foi só argumento faltando.
+- Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes. Vídeo é o mais caro da casa: confirme com ele antes de disparar.
+- REGRA DO TIMEOUT (vale pra toda geração SÍNCRONA: imagem pesada, artigo, mega-gráfico, carrossel): a chamada pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e COBRADO. Nunca repita às cegas: confira antes onde o resultado cairia (imagem: sapiens_gallery action=list; artigo: sapiens_write action=list; carrossel: sapiens_pipeline action=list_carousels; pipeline: /dashboard/admin/content).
+- "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
+- sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo. sapiens_image e sapiens_video action=models trazem o catálogo com o preço ATUAL: consulte em vez de chutar custo.
+
+MODO COMPANHIA: sapiens_meta action=start e action=whoami podem trazer um bloco 'companion'. Quando vier companion.active=true, você INCORPORA aquele Sintético (a voz dele, o avatar, o oi dele) continuando a operar na conta e nas Sinapses do USUÁRIO. Puxe a skill 'companhia' antes de fazer isso.
+
 Voz da casa: 1ª pessoa, direto, anti-corporate, sem travessão. Pra bom entendedor, meia palavra basta. Texto que vai ser publicado pede a skill 'voz-da-casa' antes.`;
 // Annotations MCP: título humano + dica read-only. São HINTS (não-confiáveis por
 // spec): quem gateia de verdade continua o servidor (saldo, gate de admin,
@@ -295,6 +301,7 @@ const ADMIN_ONLY_TOOLS = new Set([
     "sapiens_instagram",
     "sapiens_aula",
     "sapiens_share",
+    "sapiens_decupagem",
 ]);
 /**
  * Monta o payload do tools/list pro tier dado. Tier "user" esconde as

package/dist/tools/decupagem.js

@@ -0,0 +1,172 @@
+import { z } from "zod";
+import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_decupagem — o acervo de réguas de linguagem cinematográfica da casa.
+ *
+ * O que MEDE é o motor local (`tools/decupagem/decupa.py`, Python + OpenCV +
+ * ffmpeg): não existe OpenCV em serverless, então a medição roda na máquina,
+ * igual à produção dos Vídeos Programáticos. Esta tool é a outra ponta: sobe a
+ * ficha que o motor produziu e consulta o que já foi decupado.
+ *
+ * O fluxo que fecha o ciclo:
+ *   1. `python tools/decupagem/decupa.py "<arquivo ou link>"`
+ *   2. lê `fichas/<slug>/ficha.json`
+ *   3. `sapiens_decupagem action=save` com o conteúdo dela
+ *   4. a ficha aparece no Lab (/experimentos/decupagem) e entra no comparador
+ *
+ * O acervo vale pelo CONJUNTO: uma ficha é morna, vinte lado a lado são a
+ * biblioteca de gramática da casa (plano mediano, quem carrega o movimento,
+ * registro de luz, se o corte obedece ao som). Antes de decupar uma referência
+ * nova, `action=list` mostra o que já tem e evita medir a mesma coisa duas
+ * vezes.
+ *
+ * Admin-only: o acervo é material interno. Não cobra Sinapse.
+ */
+export const decupagemSchema = z.object({
+    action: z.enum(["list", "get", "save", "note", "delete"]),
+    slug: z
+        .string()
+        .optional()
+        .describe("Pra get/save/note/delete. É a chave do acervo: salvar de novo com o " +
+        "mesmo slug ATUALIZA a ficha em vez de duplicar (redecupar depois de " +
+        "afinar o motor é comum)."),
+    ficha: z
+        .any()
+        .optional()
+        .describe("Pra save: o conteúdo INTEIRO de fichas/<slug>/ficha.json, como o motor " +
+        "produziu. Não resuma nem reescreva: o Lab lê os campos de dentro."),
+    nota: z
+        .string()
+        .optional()
+        .describe("Pra save/note: a LEITURA editorial, escrita por quem olhou (o que dá " +
+        "pra roubar, o que não dá). O motor mede, isto interpreta, e os dois " +
+        "não se misturam na ficha."),
+});
+export async function decupagem(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "list") {
+        const fichas = await convexQuery("decupagens:mcpListar", { sessionToken });
+        const n = Array.isArray(fichas) ? fichas.length : 0;
+        return {
+            count: n,
+            fichas,
+            note: n === 0
+                ? "Acervo vazio. Rode o motor local (python tools/decupagem/decupa.py) e suba com action=save."
+                : "Régua de cada referência. Pra ficha inteira (planos, luz, som): action=get slug=<slug>.",
+        };
+    }
+    if (args.action === "get") {
+        if (!args.slug)
+            throw new Error("sapiens_decupagem get: exige slug.");
+        const ficha = await convexQuery("decupagens:mcpPegar", {
+            sessionToken,
+            slug: args.slug,
+        });
+        if (!ficha) {
+            return {
+                found: false,
+                note: `Nenhuma ficha com slug '${args.slug}'. Veja o acervo com action=list.`,
+            };
+        }
+        return { found: true, ficha };
+    }
+    if (args.action === "save") {
+        if (!args.ficha) {
+            throw new Error("sapiens_decupagem save: exige `ficha` (o ficha.json inteiro que o " +
+                "motor gerou em tools/decupagem/fichas/<slug>/).");
+        }
+        const f = args.ficha;
+        const resumo = extrairResumo(f, args.slug);
+        const r = await convexMutation("decupagens:mcpSalvar", {
+            sessionToken,
+            ...resumo,
+            ficha: f,
+            nota: args.nota,
+        });
+        return {
+            ok: true,
+            slug: resumo.slug,
+            criado: r?.criado ?? null,
+            note: `Ficha de '${resumo.titulo}' no acervo (${resumo.planos} planos, ` +
+                `plano mediano ${resumo.durPlanoMediana}s, ${resumo.escola}). ` +
+                `Aparece no Lab em /experimentos/decupagem.`,
+        };
+    }
+    if (args.action === "note") {
+        if (!args.slug || !args.nota) {
+            throw new Error("sapiens_decupagem note: exige slug e nota.");
+        }
+        await convexMutation("decupagens:mcpSalvarNota", {
+            sessionToken,
+            slug: args.slug,
+            nota: args.nota,
+        });
+        return { ok: true, note: "Leitura anotada na ficha." };
+    }
+    if (args.action === "delete") {
+        if (!args.slug)
+            throw new Error("sapiens_decupagem delete: exige slug.");
+        const r = await convexMutation("decupagens:mcpApagar", {
+            sessionToken,
+            slug: args.slug,
+        });
+        return {
+            ok: true,
+            apagado: r?.apagado ?? false,
+            note: r?.apagado ? "Ficha removida do acervo." : "Não havia ficha com esse slug.",
+        };
+    }
+    throw new Error(`sapiens_decupagem: action desconhecida '${args.action}'.`);
+}
+/**
+ * Puxa as colunas que o Lab ordena e filtra de dentro da ficha do motor.
+ *
+ * O resto da medição vai inteiro pro campo `ficha`: o motor ganhou dolly,
+ * concentração de matiz, ilha de cor e leitura semântica em uma semana, e
+ * promover cada medida nova a coluna faria o schema virar gargalo.
+ */
+function extrairResumo(f, slugArg) {
+    const fonte = f?.fonte ?? {};
+    const cont = f?.container ?? {};
+    const ritmo = f?.ritmo ?? {};
+    const mov = f?.movimento ?? {};
+    const luz = f?.luz ?? {};
+    const som = f?.som ?? {};
+    const cad = f?.cadencia ?? {};
+    const titulo = String(fonte.titulo || fonte.arquivo || "sem titulo");
+    const slug = (slugArg || slugify(titulo)).slice(0, 80);
+    if (!slug)
+        throw new Error("sapiens_decupagem save: não consegui derivar o slug.");
+    const num = (x, def = 0) => (typeof x === "number" && isFinite(x) ? x : def);
+    // O veredito de sincronia é o do teste de IMPACTO quando existe: o teste
+    // geral satura em trilha densa e vira "sem relação" pra todo mundo.
+    const sinc = som?.sincronia_impacto ?? som?.sincronia_grade ?? som?.sincronia;
+    return {
+        slug,
+        titulo: titulo.slice(0, 200),
+        origem: String(fonte.origem || "local"),
+        entrada: fonte.entrada ? String(fonte.entrada).slice(0, 500) : undefined,
+        dur: num(cont.dur),
+        planos: num(ritmo.planos),
+        durPlanoMediana: num(ritmo.dur_mediana),
+        escola: String(ritmo.escola || "").slice(0, 120),
+        movTotalPct: num(mov.total_pct_s),
+        movCameraPct: num(mov.camera_pct_s),
+        movSujeitoPct: num(mov.sujeito_pct_s),
+        registro: String(luz.registro || "").slice(0, 160),
+        cadenciaReal: num(cad.cadencia_real),
+        bpm: typeof som.bpm === "number" ? som.bpm : undefined,
+        corteNoSom: sinc?.veredito ? String(sinc.veredito).slice(0, 160) : undefined,
+    };
+}
+function slugify(s) {
+    return s
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-zA-Z0-9\s-]/g, "")
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}

package/dist/tools/gallery.js

@@ -13,12 +13,21 @@ import { convexAction, getSessionToken, isRemoteContext } from "../convexClient.
  *   - Publicar/despublicar a própria imagem (galeria pública + feed Pinterest)
  *   - Subir peça gerada FORA da casa (action=upload), que entra privada e serve
  *     de referência pras gerações daqui
+ *   - Ingerir peça gerada em motor EXTERNO com receita da casa (action=ingest,
+ *     ADMIN), que entra como peça nativa: timeline, publicação, comunidade
  *
  * O upload resolve URL/arquivo pra base64 AQUI, no cliente, e manda os bytes
  * prontos pro Convex. O servidor não busca URL nenhuma (sem SSRF novo lá).
+ *
+ * O INGEST é o oposto e de propósito: quem baixa é o servidor, de uma allowlist
+ * fechada de hosts (convex/externalIngest.ts), porque a peça vai nascer nativa e
+ * a origem precisa ser verificável do lado de cá. A diferença entre as duas não
+ * é de onde vieram os bytes, é de quem foi a DIREÇÃO: peça achada pronta é
+ * upload; peça que a casa dirigiu (nossa folha, nosso personagem, nosso prompt)
+ * e um motor terceiro só renderizou é ingest.
  */
 export const gallerySchema = z.object({
-    action: z.enum(["list", "get", "publish", "unpublish", "upload"]),
+    action: z.enum(["list", "get", "publish", "unpublish", "upload", "ingest"]),
     limit: z
         .number()
         .int()
@@ -59,6 +68,32 @@ export const gallerySchema = z.object({
         .string()
         .optional()
         .describe("action=upload: o que é a peça (prompt original, contexto). Vira a descrição na galeria e a busca acha por ela."),
+    // --- action=ingest (peça gerada em motor externo COM receita da casa) ---
+    externalEngine: z
+        .string()
+        .optional()
+        .describe("action=ingest (ADMIN): qual motor renderizou ('freepik-seedance-2.0', 'magnific'). Fica gravado como rastro na peça e no aviso do Discord."),
+    externalCost: z
+        .string()
+        .optional()
+        .describe("action=ingest: quanto custou lá fora, em texto livre ('4200 créditos Freepik'). A peça entra com 0 Sinapses, então é isto que preserva o custo real no histórico."),
+    prompt: z
+        .string()
+        .optional()
+        .describe("action=ingest: o prompt que a CASA escreveu pra essa peça. Vira a descrição na galeria e a busca acha por ele."),
+    aspectRatio: z
+        .string()
+        .optional()
+        .describe("action=ingest: proporção da peça ('16:9', '9:16'). Default 16:9."),
+    size: z
+        .string()
+        .optional()
+        .describe("action=ingest: resolução ('720p', '1080p'). Default 720p."),
+    referenceImageIds: z
+        .array(z.string())
+        .max(8)
+        .optional()
+        .describe("action=ingest: generatedImages:_id das peças DA CASA que serviram de referência (folha de storyboard, ficha de personagem, frame inicial). Ficam acopladas à peça ingerida e aparecem na ficha dela: é o que prova que a receita saiu daqui. Só peça sua entra."),
     uploadedSource: z
         .string()
         .optional()
@@ -207,4 +242,26 @@ export async function gallery(args) {
             aviso: "Peça enviada de fora: fica privada, é sua e a responsabilidade é sua. Não publica nem vai pra comunidade. Use como referência (sourceImageIds em sapiens_image) e publique o que gerar a partir dela.",
         };
     }
+    if (args.action === "ingest") {
+        if (!args.sourceUrl) {
+            throw new Error("action=ingest exige sourceUrl: o link https da peça pronta no motor externo. Diferente do upload, aqui é o SERVIDOR que baixa, e só de host liberado.");
+        }
+        if (!args.externalEngine) {
+            throw new Error("action=ingest exige externalEngine: qual motor renderizou ('freepik-seedance-2.0'). É o rastro que explica depois por que a peça não tem custo em Sinapses.");
+        }
+        const result = await convexAction("externalIngest:mcpIngestExternal", {
+            sessionToken,
+            sourceUrl: args.sourceUrl,
+            externalEngine: args.externalEngine,
+            prompt: args.prompt ?? args.note,
+            externalCost: args.externalCost,
+            aspectRatio: args.aspectRatio,
+            size: args.size,
+            referenceImageIds: args.referenceImageIds,
+        });
+        return {
+            ...result,
+            aviso: "Peça NATIVA: entra na timeline, publica e vai pra comunidade como qualquer geração da casa. Custo em Sinapses é 0 e ela NÃO leva assinatura C2PA, porque o motor rodou fora. Use ingest só quando a receita (folha, personagem, prompt) foi da casa; peça achada pronta é action=upload.",
+        };
+    }
 }

package/dist/tools/repertorio.js

@@ -24,7 +24,7 @@ import { need } from "../schema.js";
  *
  * Action-based design (memoria: consolidar tools via args).
  */
-const mediaTypeEnum = z.enum(["movie", "series", "anime", "game", "book", "music", "tool"]);
+const mediaTypeEnum = z.enum(["movie", "series", "anime", "game", "book", "music", "tool", "person"]);
 const statusEnum = z.enum([
     "backlog",
     "active",
@@ -32,7 +32,7 @@ const statusEnum = z.enum([
     "paused",
     "dropped",
 ]);
-const sourceEnum = z.enum(["tmdb", "anilist", "rawg", "twitch", "googlebooks", "itunes", "manual"]);
+const sourceEnum = z.enum(["tmdb", "anilist", "rawg", "twitch", "googlebooks", "itunes", "manual", "wikidata"]);
 export const repertorioSchema = z.object({
     action: z.enum([
         "list",
@@ -62,7 +62,7 @@ export const repertorioSchema = z.object({
     // add_item — só identifica o item; o servidor re-resolve e grava o metadado.
     source: sourceEnum
         .optional()
-        .describe("Pra add_item: o source EXATO de um candidato do action=resolve (manual=filme/série via OMDb, anilist, twitch=jogo, googlebooks, itunes). Não invente."),
+        .describe("Pra add_item: o source EXATO de um candidato do action=resolve (manual=filme/série via OMDb, anilist, twitch=jogo, googlebooks, itunes, wikidata=pessoa). Não invente."),
     externalId: z
         .string()
         .optional()

package/dist/tools/video.js

@@ -53,6 +53,10 @@ import { httpUrl } from "../schema.js";
  *                                   antes de fechar no 2.0 padrão. Pedir 1080p nos dois cai em 720p
  *                                   (cobrando 720p).
  *   - sapiens-video-kling          Kling 3.0 Pro — dá vida a uma imagem, 3-15s, sound opcional (i2v/t2v)
+ *   - sapiens-video-hailuo         Hailuo 2.3 (MiniMax) — física e movimento em 768p, 6 ou 10s (t2v/i2v).
+ *                                   Motor puro: SEM áudio, SEM referência, SEM frame final.
+ *   - sapiens-video-hailuo-pro     Hailuo 2.3 Pro — o mesmo em 1080p, 5s fixo (duração não é param).
+ *                                   É o 1080p mais barato da casa depois do Seedance 1.0 Fast.
  *   - sapiens-video-wan            WAN 2.5 — imagem que fala/canta (áudio+lip-sync nativo), 5/10s (i2v)
  *   - sapiens-video-kling-motion   Kling Motion — transfere o movimento de um vídeo pra uma imagem
  *                                   (PRECISA de pessoa com tronco visível na imagem E no vídeo;
@@ -87,6 +91,8 @@ const VIDEO_MODELS = [
     "sapiens-video-seedance-2-fast",
     "sapiens-video-seedance-2-mini",
     "sapiens-video-kling",
+    "sapiens-video-hailuo",
+    "sapiens-video-hailuo-pro",
     "sapiens-video-wan",
     "sapiens-video-kling-motion",
     "sapiens-video-shot-mimic",
@@ -114,7 +120,21 @@ export const videoSchema = z.object({
         "film-status",
         "film-publish",
         "film-delete",
+        "caption-list",
+        "caption-generate",
+        "caption-translate",
     ]),
+    // --- Legenda (caption-*): a fala da fita virando texto, em vários idiomas ---
+    captionLang: z
+        .enum(["pt", "en", "ja", "es", "ko", "zh", "fr", "it", "de"])
+        .optional()
+        .describe("caption-generate: o idioma FALADO no vídeo. caption-translate: o idioma de DESTINO. " +
+        "A legenda é desenhada pela casa e trocável no play; o trio da casa é pt+en+ja."),
+    captionTrio: z
+        .boolean()
+        .optional()
+        .describe("caption-generate: true transcreve E traduz pro trio da casa (pt, en, ja) numa chamada. " +
+        "Cobra cada etapa por vez, então falha numa tradução não perde as que já saíram."),
     // --- Vídeos Programáticos (film-*): Lab de specs da casa, ADMIN, sem custo ---
     filmKind: z
         .enum(FILM_KINDS)
@@ -178,6 +198,7 @@ export const videoSchema = z.object({
         .optional()
         .describe("action=create: modelo de vídeo. 'sapiens-video-seedance' (cinematográfico+áudio, t2v/i2v), " +
         "'sapiens-video-kling' (anima imagem, i2v/t2v), 'sapiens-video-wan' (imagem que fala, i2v), " +
+        "'sapiens-video-hailuo' (MiniMax, física e movimento, 768p 6/10s) e 'sapiens-video-hailuo-pro' (o mesmo em 1080p, 5s fixo) — os dois sem áudio, sem referência e sem frame final, " +
         "'sapiens-video-kling-motion' (motion transfer, precisa pessoa na imagem E no vídeo de movimento; vídeo de referência MÁX 10s, cobra pela duração do clipe), " +
         "'sapiens-video-shot-mimic' (recria o plano do vídeo de referência com seu personagem: mesma câmera, mesmos cortes; 'driving' = previs/clipe do plano MÁX 15s, 'start' = personagem), " +
         "'sapiens-video-lite/fast/quality' (Veo 3.1), " +
@@ -411,6 +432,39 @@ export async function video(args) {
             throw new Error("film-get exige slug (descubra via film-list).");
         return await convexQuery("videoSpecs:mcpGetVideoSpec", { sessionToken, slug: args.slug });
     }
+    // --- Legenda ---
+    if (args.action === "caption-list") {
+        if (!args.slug)
+            throw new Error("caption-list exige slug (descubra via film-list).");
+        return await convexAction("mcpExtrasActions:mcpCaptionList", {
+            sessionToken,
+            slug: args.slug,
+        });
+    }
+    if (args.action === "caption-generate") {
+        if (!args.slug)
+            throw new Error("caption-generate exige slug (descubra via film-list).");
+        if (!args.captionLang) {
+            throw new Error("caption-generate exige captionLang: o idioma FALADO no vídeo (o modelo transcreve nele).");
+        }
+        return await convexAction("mcpExtrasActions:mcpCaptionGenerate", {
+            sessionToken,
+            slug: args.slug,
+            lang: args.captionLang,
+            trio: args.captionTrio,
+        });
+    }
+    if (args.action === "caption-translate") {
+        if (!args.slug)
+            throw new Error("caption-translate exige slug (descubra via film-list).");
+        if (!args.captionLang)
+            throw new Error("caption-translate exige captionLang (idioma de destino).");
+        return await convexAction("mcpExtrasActions:mcpCaptionTranslate", {
+            sessionToken,
+            slug: args.slug,
+            lang: args.captionLang,
+        });
+    }
     if (args.action === "film-upsert") {
         if (!args.spec || typeof args.spec !== "object") {
             throw new Error("film-upsert exige spec (objeto JSON com kind + musicMode + payload do kind: demo | aulaTour | essay | tipoMusical | dataviz).");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.43.5",
+  "version": "1.45.0",
   "description": "MCP server pra operar o Sapiens Sintéticos (sapiensinteticos.com) pelo Claude Code: gerar imagem, escrever artigo, voz, música e mais, na sua conta. Login pelo código de sapiensinteticos.com/conectar-claude.",
   "type": "module",
   "bin": {