sapiens-mcp 1.50.0 → 1.51.0

package/dist/convexClient.js

@@ -284,7 +284,11 @@ function withTimeout(p, label) {
     let timer;
     const timeout = new Promise((_, reject) => {
         timer = setTimeout(() => {
-            reject(new Error(`Timeout: o backend Sapiens não respondeu em ${Math.round(CONVEX_TIMEOUT_MS / 1000)}s (${label}). Tente de novo em instantes.`));
+            reject(new Error(`Timeout: o backend Sapiens não respondeu em ${Math.round(CONVEX_TIMEOUT_MS / 1000)}s (${label}). Isto é o CLIENTE desistindo de esperar, não a ` +
+                `operação morrendo: ela segue rodando no servidor e, se cobra ` +
+                `Sinapses, JÁ cobrou. NÃO repita a chamada — repetir gera e cobra ` +
+                `de novo. Espere alguns minutos e leia o estado real por uma ` +
+                `leitura (o \`get\`/\`list\`/\`status\` do mesmo tool) antes de decidir.`));
         }, CONVEX_TIMEOUT_MS);
     });
     return Promise.race([

package/dist/registry.js

@@ -14,7 +14,10 @@ import { instagram, instagramSchema } from "./tools/instagram.js";
 import { persona, personaSchema } from "./tools/persona.js";
 import { helen, helenSchema } from "./tools/helen.js";
 import { musicator, musicatorSchema } from "./tools/musicator.js";
-import { shorts, shortsSchema } from "./tools/shorts.js";
+// A tool sapiens_shorts saiu em ago/2026: os quatro estilos dela viraram
+// receitas de `sapiens_video` (templateSlug), que qualquer membro alcança e que
+// não está preso ao Veo. O BACKEND dela (mcpExtrasActions:mcpShortsRender)
+// continua no ar por retrocompat, porque pacote publicado ainda chama.
 import { video, videoSchema } from "./tools/video.js";
 import { write, writeSchema } from "./tools/write.js";
 import { stockAudio, stockAudioSchema } from "./tools/stockAudio.js";
@@ -80,7 +83,7 @@ export const TOOLS = {
         handler: community,
     },
     sapiens_article: {
-        description: "NÃO CRIA ARTIGO: este tool só mexe em artigo que JÁ existe. Pra criar draft novo do blog use sapiens_pipeline action=create_draft_article_and_source (devolve articleId + sourceId), ou sapiens_quote_pop pra quote e pop-article. Não confunda com sapiens_write, que é o espaço pessoal do membro em /u/<username> (tabela user_articles), e nunca salve o texto num .md solto no repo: draft de blog mora na tabela articles. CRUD do resto: get (by slug, retorna doc completo pra edit local), update (patch em title/excerpt/tldr/content/tags/etc + VISUAIS: thumbnailUrl capa webp, ogImageUrl JPEG do preview social, bodyImages array das ilustrações inline, conceptMap mapa visual, pra recapear um artigo num novo estilo; NÃO toca status/column/format), publish (status='published', set publishedAt), unpublish (volta pra draft), delete (irreversível), ensure_visuals (gera banner/ilustrações inline/conceptMap que faltam no artigo; idempotente, pula o que existe; ~1700 Sinapses num artigo pelado, forceBanner/forceInline/forceConceptMap regeram).",
+        description: "NÃO CRIA ARTIGO: este tool só mexe em artigo que JÁ existe. Pra criar draft novo do blog use sapiens_pipeline action=create_draft_article_and_source (devolve articleId + sourceId), ou sapiens_quote_pop pra quote e pop-article. Não confunda com sapiens_write, que é o espaço pessoal do membro em /u/<username> (tabela user_articles), e nunca salve o texto num .md solto no repo: draft de blog mora na tabela articles. CRUD do resto: get (by slug, retorna doc completo pra edit local), update (patch em title/excerpt/tldr/content/tags/etc + VISUAIS: thumbnailUrl capa webp, ogImageUrl JPEG do preview social, bodyImages array das ilustrações inline, conceptMap mapa visual, pra recapear um artigo num novo estilo; NÃO toca status/column/format), publish (status='published', set publishedAt), unpublish (volta pra draft), delete (irreversível), ensure_visuals (gera banner/ilustrações inline/conceptMap que faltam no artigo; idempotente, pula o que existe; ~1700 Sinapses num artigo pelado, forceBanner/forceInline/forceConceptMap regeram). ensure_visuals é ASSÍNCRONA: volta NA HORA com {status:'running', plan} e a leva corre no servidor, como o vídeo. NÃO repita a chamada pra ver se andou (cada leva gera e COBRA de novo, e as ilustrações somam) — acompanhe com visuals_status (custo 0) até jobStatus='done' ou 'error'. Quando não há nada faltando, ela responde na hora com status:'idle' e o retrato dos visuais, de graça: é a sonda pra saber o que o artigo já tem. Leva já em andamento devolve alreadyRunning:true em vez de abrir outra. visuals_status (custo 0) traz jobStatus (none/running/done/error/stale), o plano da leva, custo, erro e o estado real (hasBanner, inlineCount, hasConceptMap); 'stale' é leva que passou do teto de 10min do servidor sem fechar, ou seja, ninguém está mais gerando.",
         schema: articleSchema,
         handler: article,
     },
@@ -119,13 +122,8 @@ export const TOOLS = {
         schema: musicatorSchema,
         handler: musicator,
     },
-    sapiens_shorts: {
-        description: "Sapiens Shorts — render vertical 9:16 via VEO com brief structured (admin-only). Sub-action: render. Args: imageId (persona pré-existente em generatedImages, descubra via sapiens_gallery), styleId ('ugc'/'unboxing'/'app-demo'/'reflexao'), brief (product+hook+shots+vibe), references opcionais. render é ASSÍNCRONO: volta na hora com {imageId, status:'rendering', url:null}, e você acompanha com sapiens_video action=status imageId=<id> até status='completed' (traz a url VEO, expiração curta, baixe logo) ou 'error'. Pré-requisito: o imageId precisa ter row em generatedImages do user da sessão e cost definido. Pra criar a row sem passar pela UI: sapiens_image action=request_generation (modelos sapiens-video-*).",
-        schema: shortsSchema,
-        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-seedance-25' (Seedance 2.5, a geração SEGUINTE e não um quarto tier da 2.0: take de 4 a 30s num fôlego, edita e estende vídeo, mesmo repertório de referência mais ÁUDIO como referência; teto 720p e ~1,5x o preço por segundo do 2.0. Duração é o que pesa aqui: 30s em 720p passa de 40 mil Sinapses, então confirme a duração com a pessoa antes de disparar. Quem precisa de 1080p fica no 'sapiens-video-seedance'), 'sapiens-video-seedance-15' (Seedance 1.5 Pro: o degrau entre o 1.0 e a linha 2.x; t2v/i2v, 4-12s, 480/720/1080p, som sempre incluso sem toggle; imagem de referência e frame final ficam de fora por ora), '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-h3' (MiniMax H3: 2K com áudio nativo incluso sem toggle, 5 a 10s, t2v/i2v e frame final; não aceita imagem de referência), '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.",
+        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-seedance-25' (Seedance 2.5, a geração SEGUINTE e não um quarto tier da 2.0: take de 4 a 30s num fôlego, edita e estende vídeo, mesmo repertório de referência mais ÁUDIO como referência; teto 720p e ~1,5x o preço por segundo do 2.0. Duração é o que pesa aqui: 30s em 720p passa de 40 mil Sinapses, então confirme a duração com a pessoa antes de disparar. Quem precisa de 1080p fica no 'sapiens-video-seedance'), 'sapiens-video-seedance-15' (Seedance 1.5 Pro: o degrau entre o 1.0 e a linha 2.x; t2v/i2v, 4-12s, 480/720/1080p, som sempre incluso sem toggle; imagem de referência e frame final ficam de fora por ora), '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-h3' (MiniMax H3: 2K com áudio nativo incluso sem toggle, 5 a 10s, t2v/i2v e frame final; não aceita imagem de referência), '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. RECEITA DE TAKE (templateSlug + brief), o irmão do templateSlug da imagem: em vez de escrever o prompt inteiro, passe templateSlug e a receita travada da casa embrulha a cena com estilo, cenário, arco, áudio e look, e ainda escolhe o motor (por isso model fica opcional). O `prompt` vira só a CENA e o `brief` preenche os campos do formato (subject, persona, hook, shots com voiceLine e propVisible, uvps, language, energy); campo vazio some do prompt em vez de virar buraco. Receitas de hoje: 'ugc-vertical-v1' (selfie que fala, o formato nativo de Reels/TikTok/Shorts), 'unboxing-vertical-v1' (mãos e reveal, som real do papel e do lacre), 'app-demo-vertical-v1' (a tela do app legível na mão da pessoa) e 'reflexao-vertical-v1' (talking-head lento pra ideia ou ensaio). Override de model/aspectRatio/durationSec/resolution vale dentro do que a receita aceita, e o erro lista as opções. Sub-action 'templates' (sem custo, sem login) traz o catálogo vivo com spec default, whitelist e os briefFields de cada uma. Isto substitui a tool sapiens_shorts, que era admin-only e só falava Veo 3.1 Fast; o mesmo UGC de 8s sai a 720p no Seedance 2.0 Mini por bem menos. 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,
     },
@@ -227,7 +225,7 @@ O passo a passo travado de cada fluxo mora na tool sapiens_skill, servida por es
 - 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 personagem ou prompt de Midjourney (personagem), 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), montar currículo (curriculo). Perdido no começo: primeiros-passos.
+Puxe a skill ANTES de: gerar música ou efeito sonoro (musica), escolher modelo de vídeo (video), gerar imagem (imagem), criar personagem ou prompt de Midjourney (personagem), 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), montar currículo (curriculo), guardar obra ou ferramenta no acervo (repertorio). 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:
@@ -277,7 +275,6 @@ const TOOL_TITLES = {
     sapiens_persona: "Persona (MBTI)",
     sapiens_helen: "Voz Helen (TTS)",
     sapiens_musicator: "Musicator",
-    sapiens_shorts: "Sapiens Shorts",
     sapiens_video: "Sapiens Video",
     sapiens_stock_audio: "Banco de Áudio",
     sapiens_stock_video: "Banco de Vídeo",
@@ -306,7 +303,6 @@ const ADMIN_ONLY_TOOLS = new Set([
     "sapiens_pipeline",
     "sapiens_article",
     "sapiens_quote_pop",
-    "sapiens_shorts",
     "sapiens_instagram",
     "sapiens_aula",
     "sapiens_share",
@@ -331,6 +327,23 @@ export function buildToolList(tier) {
         },
     }));
 }
+/**
+ * Apelidos que agentes CHAMAM e que não são o nome da tool. Não é palpite:
+ * saiu do `mcpUsage`, onde numa noite de jul/2026 um cliente gastou dez
+ * chamadas procurando o Repertório, quatro delas no slug traduzido pro inglês.
+ * O slug da casa é português; aceitar o apelido é mais barato que o agente
+ * descobrir sozinho, e não abre nome novo (o catálogo continua o mesmo).
+ *
+ * Só entra apelido INEQUÍVOCO. Os outros nomes daquela noite (`sapiens_track`,
+ * `sapiens_collection`, `sapiens_library`) ficam de fora de propósito: soam a
+ * música e a galeria tanto quanto a repertório, e mapear no chute manda a peça
+ * pro lugar errado calado. Pra esses, o erro de tool desconhecida agora lista
+ * o catálogo, que é a resposta honesta.
+ */
+const TOOL_ALIASES = {
+    sapiens_repertoire: "sapiens_repertorio",
+    repertorio: "sapiens_repertorio",
+};
 /**
  * Dispatch de uma tool: valida args no Zod, roda o handler e embrulha o
  * resultado no shape MCP (content + structuredContent; erro vira isError com
@@ -339,10 +352,20 @@ export function buildToolList(tier) {
  * (via runWithSessionToken).
  */
 export async function callTool(name, rawArgs) {
-    const tool = TOOLS[name];
+    const tool = TOOLS[(TOOL_ALIASES[name] ?? name)];
     if (!tool) {
+        // Beco sem saída vira mapa: o agente que erra o nome erra de novo se a
+        // resposta só diz "não existe". Listar o catálogo custa ~400 chars e só
+        // aparece no erro, nunca no handshake.
         return {
-            content: [{ type: "text", text: `Tool desconhecida: ${name}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Tool desconhecida: ${name}. As tools da casa são: ` +
+                        `${Object.keys(TOOLS).sort().join(", ")}. ` +
+                        `Chame a certa em vez de tentar outro nome.`,
+                },
+            ],
             isError: true,
         };
     }
@@ -376,12 +399,35 @@ export async function callTool(name, rawArgs) {
     catch (e) {
         return {
             content: [
-                { type: "text", text: `Erro: ${describeConvexError(e)}${retryHint(e)}` },
+                {
+                    type: "text",
+                    text: `Erro: ${describeConvexError(e)}${actionHint(e, tool.schema)}${retryHint(e)}`,
+                },
             ],
             isError: true,
         };
     }
 }
+/**
+ * Chamada sem `action` (ou com uma que não existe) é o segundo erro mais comum
+ * do connector depois de arg faltando: 23 chamadas peladas no `mcpUsage`, 12
+ * delas em erro. O Zod diz "Required" e não diz o que serve, então o agente
+ * chuta de novo. Aqui a resposta já vem com as actions daquele tool.
+ *
+ * Lê o enum do próprio schema em vez de uma lista à parte, que envelheceria
+ * sozinha: action nova aparece aqui no mesmo commit em que nasce.
+ */
+function actionHint(e, schema) {
+    if (!(e instanceof ZodError))
+        return "";
+    const touchesAction = e.issues.some((i) => i.path[0] === "action");
+    if (!touchesAction)
+        return "";
+    const options = schema?.shape?.action?.options;
+    if (!Array.isArray(options) || options.length === 0)
+        return "";
+    return ` -> As actions deste tool são: ${options.join(", ")}.`;
+}
 /**
  * A regra do disjuntor viaja NO ERRO, não no handshake. Ela só passa a valer
  * depois que uma chamada falhou, então cobrar ~300 chars de TODA conversa pra

package/dist/skills.js

@@ -131,6 +131,43 @@ Quem tem design system (\`sapiens_brand action=list\`) já vê a capa sair na pa
 ## Estrutura padrão de peça didática
 
 Condensa a informação num framework com nome, ancora numa analogia concreta, e só então desce pro detalhe. Estrutura arrumada, alma inquieta, nunca fórmula.`,
+    },
+    {
+        name: "repertorio",
+        title: "Repertório: guardar obra e ferramenta no acervo",
+        description: "Guardar filme, série, anime, jogo, livro, música, pessoa ou ferramenta de IA no Repertório. Puxe ANTES de qualquer sapiens_repertorio: a gravação é travada num fluxo de dois passos e tentar guardar direto falha sempre.",
+        body: `## A regra que faz este fluxo falhar
+
+Você NÃO grava uma obra passando o título. O servidor não aceita metadado vindo de você (título, capa, ano) de propósito: é anti-fabricação. Você identifica a obra num provider, e o servidor re-resolve por id e grava o canônico.
+
+São sempre DOIS passos. Pular o primeiro falha sempre, e é o erro número um deste fluxo.
+
+## Guardar uma obra
+
+1. **\`action=resolve\`** com \`mediaType\` e \`query\` (o título como a pessoa falou). Custo 0. Volta até 8 candidatos, cada um com \`source\` e \`externalId\`.
+2. Escolha o candidato certo. Em dúvida entre dois, PERGUNTE em vez de chutar: obra errada no acervo é a pessoa quem vai ter que apagar.
+3. **\`action=add_item\`** com o \`source\` e o \`externalId\` **exatos** daquele candidato, mais o que é pessoal: \`status\`, \`rating\` (0-10), \`tags\`, \`note\`, \`containsSpoilers\`, \`isPublic\`.
+
+\`mediaType\`: movie, series, anime, game, book, music, tool, person.
+\`status\`: backlog (quer ver), active (vendo agora), completed (viu), paused, dropped.
+
+Nunca invente um \`externalId\` nem reaproveite um de outra busca: id que não resolve no provider é rejeitado. A dedup é por (você, source, externalId), então repetir o mesmo par não duplica.
+
+## Guardar uma ferramenta de IA
+
+Outro par, mesmo espírito: **\`action=search_tools\`** com \`query\` (catálogo aberto, custo 0, sem login) e depois **\`action=add_tool\`** com o \`toolId\` do candidato. Estar no acervo já quer dizer "usei"; \`favorite: true\` é o eixo separado de "curto e indico".
+
+## Ler o acervo
+
+\`action=list\` e \`action=search\` **exigem \`userId\`**. Descubra uma vez com \`sapiens_meta action=whoami\` e reuse na conversa inteira. \`action=get\` pede \`itemId\`, que vem do list/search.
+
+Acervo de outra pessoa você lê, mas só o que ela deixou público.
+
+## Depois de guardar
+
+\`action=update_item\` muda o que é seu (\`rating\`, \`status\`, \`tags\`, \`note\`; \`rating: null\` remove a nota). \`action=remove_item\` tira do acervo. Os dois pedem \`itemId\`, nunca o título.
+
+\`action=popArticles\` lista os artigos publicados que usam uma obra como lente. É leitura pública, não precisa de login.`,
     },
     {
         name: "musica",
@@ -196,6 +233,21 @@ Duração é o que pesa aqui, não o modelo: um take de 30s em 720p passa de 40
 - \`sapiens-video-omni\`: Gemini Omni, texto vira clipe de 10s 720p com áudio nativo. NÃO aceita mídia da pessoa e ignora references/durationSec/resolution. O truque: \`editOfImageId\` aponta um vídeo Omni seu e o prompt vira instrução de edição sobre a MESMA cena (troca item ou personagem, preserva câmera e ambiente). É o caminho pra variações com continuidade: gera a base uma vez, edita N vezes. Cada edição debita como geração nova.
 - \`sapiens-video-lite\` / \`-fast\` / \`-quality\`: Veo 3.1.
 
+## Receita de take (\`templateSlug\`), quando o formato já tem forma
+
+Formato conhecido não precisa de prompt escrito do zero. Passe \`templateSlug\` e a receita da casa embrulha a cena com estilo, cenário, arco, áudio e look, e ainda escolhe o motor (aí \`model\` fica opcional). O \`prompt\` vira só a CENA e o \`brief\` preenche o resto.
+
+| Slug | O take |
+|---|---|
+| \`ugc-vertical-v1\` | selfie que fala, o formato nativo de Reels, TikTok e Shorts |
+| \`unboxing-vertical-v1\` | mãos e reveal, som real de papel e lacre |
+| \`app-demo-vertical-v1\` | a tela do app legível na mão da pessoa |
+| \`reflexao-vertical-v1\` | talking-head lento pra ideia ou ensaio |
+
+O \`brief\` aceita \`subject\`, \`persona\`, \`hook\` (\`line\` e \`emotion\`), \`shots\` (cada um com \`sec\`, \`camera\`, \`action\`, \`emotion\`, \`voiceLine\`, \`propVisible\`), \`uvps\`, \`language\` e \`energy\`. Campo vazio SOME do prompt em vez de virar buraco, e o que você não passa cai no valor de reserva da receita.
+
+\`action=templates\` (sem custo, sem login) lista o catálogo vivo: spec default, o que dá pra sobrepor e os \`briefFields\` que cada receita realmente usa. Override fora da whitelist é recusado com as opções na mensagem.
+
 ## Fluxo storyboard (o que dá o melhor resultado)
 
 Até 4 imagens de REFERÊNCIA via \`referenceImageIds\` / \`referenceImageUrls\` / \`referenceImagePaths\` guiam estilo, personagem e composição SEM virar o primeiro frame.
@@ -267,7 +319,7 @@ Refs valem pros modelos robustos (nano-banana-2, gpt-image-2-*, grok-2-image*).
 ## Cuidados
 
 - \`generate\` é SÍNCRONA e cobra ao concluir. Modelo pesado (Pro, gpt-image-2-high, Grok quality, Seedream 5.0 Pro, 2K/4K) cai na regra do timeout: cheque \`sapiens_gallery action=list\` antes de repetir, senão cobra duas vezes. O \`seedream-5-0-pro\` foi medido em ~140s, ACIMA do teto de 120s do cliente, então o Timeout nele é o esperado e a imagem está lá.
-- \`request_generation\` NÃO gera imagem: só cria a row pendente e debita, pra modelos \`sapiens-video-*\` antes de chamar vídeo ou shorts.
+- \`request_generation\` NÃO gera imagem: só cria a row pendente e debita, pra modelos \`sapiens-video-*\` antes de renderizar. Caminho legado: pra vídeo novo, \`sapiens_video action=create\` faz tudo num call.
 - Uma imagem só vira pública (e ganha página indexável) com \`sapiens_gallery action=publish\`.
 
 ## Quando a pessoa quer "do jeito dela"

package/dist/tools/article.js

@@ -24,6 +24,7 @@ export const articleSchema = z.object({
         "unpublish",
         "delete",
         "ensure_visuals",
+        "visuals_status",
     ]),
     slug: z
         .string()
@@ -32,7 +33,7 @@ export const articleSchema = z.object({
     articleId: z
         .string()
         .optional()
-        .describe("Obrigatório pra update/publish/unpublish/delete/ensure_visuals. Pode descobrir via action=get (o retorno tem _id)."),
+        .describe("Obrigatório pra update/publish/unpublish/delete/ensure_visuals/visuals_status. Pode descobrir via action=get (o retorno tem _id)."),
     // Campos pra update (todos opcionais)
     title: z.string().optional(),
     excerpt: z.string().optional(),
@@ -178,6 +179,12 @@ export async function article(args) {
             // Gera banner / inline / conceptMap que estiverem faltando.
             // Idempotente: pula o que já existe. Custo: ~1700 sinapses pra
             // artigo novo (450+450+800), só do que regerar pros que existem.
+            //
+            // ASSÍNCRONO (ago/2026): volta na hora com o plano da leva, porque as
+            // quatro gerações em sequência estouravam o teto de 120s do cliente em
+            // 10 de cada 22 chamadas — e o timeout parecia morte quando a operação
+            // seguia rodando e já tinha cobrado. Quando não há nada a gerar, segue
+            // respondendo na hora com o retrato de sempre (é a sonda barata).
             const articleId = need(args.articleId, "articleId");
             return await convexAction("articleVisuals:ensureArticleVisualsBySession", {
                 sessionToken,
@@ -186,6 +193,17 @@ export async function article(args) {
                 forceInline: args.forceInline,
                 forceConceptMap: args.forceConceptMap,
                 inlineCount: args.inlineCount,
+                async: true,
+            });
+        }
+        case "visuals_status": {
+            // Leitura pura da leva + do estado real dos visuais. Custo 0, pode
+            // chamar à vontade: é o jeito de fechar o ciclo depois de um
+            // ensure_visuals, e o único que não corre risco de cobrar de novo.
+            const articleId = need(args.articleId, "articleId");
+            return await convexAction("articleVisuals:articleVisualsJobBySession", {
+                sessionToken,
+                articleId,
             });
         }
     }

package/dist/tools/reference.js

@@ -12,12 +12,13 @@ import { convexAction, convexQuery, getSessionToken } from "../convexClient.js";
  * importa aqui: banco novo no picker web nasce com bucket irmão neste arquivo,
  * senão o agente enxerga menos que o browser e a paridade quebra em silêncio.
  *
- * Buckets (as abas do popup, completas):
+ * Buckets (as abas do popup, completas). `term` (busca escrita) vale em TODOS,
+ * espelhando o campo único de busca do modal web:
  *   - history    imagens recentes do user (privadas + públicas)
  *   - favorites  imagens que o user curtiu (só as suas)
  *   - videos     vídeos do user (Meus Vídeos)
- *   - stock_video Banco de Vídeo da casa (clipes/B-roll); aceita `term`/`orientation`/`loopOnly`
- *   - acervo     stock + comunidade de IMAGEM (público); aceita `term` (busca) e `source`
+ *   - stock_video Banco de Vídeo da casa (clipes/B-roll); aceita `orientation`/`loopOnly`
+ *   - acervo     stock + comunidade de IMAGEM (público); aceita `source`
  *   - characters personagens; `mode` = 'mine' (default) ou 'public'
  *   - deepshadow guias de movimento; `shadowSource` = 'house' (banco curado, default) ou 'mine'
  *
@@ -62,7 +63,10 @@ export const referenceSchema = z.object({
     term: z
         .string()
         .optional()
-        .describe("Buckets 'acervo' e 'stock_video': busca por texto (prompt/título/tag/mood). Ex: 'chuva'."),
+        .describe("Busca escrita, vale em QUALQUER bucket. Casa por pedaço de palavra, sem acento: 'board' acha 'storyboard'. " +
+        "Olha prompt, título, folha, personagem e modelo nas suas imagens; prompt/título/modelo nos vídeos; " +
+        "nome nos personagens; prompt/tag/mood no acervo e no banco de vídeo. " +
+        "Pra achar UMA peça específica que você já sabe qual é, use action=resolve com o handle (img_…), é mais direto."),
     source: z
         .enum(["all", "stock", "community"])
         .optional()
@@ -144,6 +148,14 @@ export async function reference(args) {
             note =
                 "Pra usar como referência: em sapiens_image passe o imageId em sourceImageIds (ou a url em referenceImageUrls); em sapiens_video passe startImageId/endImageId (ou startImageUrl/endImageUrl).";
         }
+        // Vazio COM termo não quer dizer banco vazio: sem essa linha o agente
+        // conclui que a pessoa não tem nada e vai gerar de novo o que já existe.
+        if (args.term && !res?.items?.length) {
+            note =
+                `Nenhuma peça deste banco casou com "${args.term}". O banco pode ter outras: tente um termo mais curto ` +
+                    `(a busca casa por pedaço de palavra), outro bucket, ou browse sem \`term\`. Se o usuário te deu o ID da ` +
+                    `peça (img_…, vid_…), use action=resolve.`;
+        }
         return { ...res, note };
     }
 }

package/dist/tools/video.js

@@ -8,6 +8,12 @@ import { httpUrl } from "../schema.js";
  * Sub-actions:
  *   - create:   escolhe modelo + config e gera num call só (cria a row + renderiza).
  *               Habilita Seedance/Kling/WAN/Motion (WaveSpeed) e os Veo, sem o site.
+ *               Com `templateSlug`, a RECEITA da casa embrulha a cena (estilo, arco,
+ *               áudio, look) e escolhe o motor: `prompt` vira só a cena e `brief`
+ *               preenche os campos do formato.
+ *   - templates: catálogo das receitas de take (slug, spec default, whitelist de
+ *               override e os campos de brief que cada uma usa). Sem custo, sem login.
+ *               Comeu o antigo sapiens_shorts, que era admin-only e só falava Veo.
  *   - generate: renderiza um imageId de vídeo já criado no site (legado).
  *   - demos:    lista os SEUS demo films (kind=demo do Estúdio de Vídeo) + estado
  *               de vitrine. Sem custo. Base pra curar o mini-cinema da vitrine.
@@ -125,6 +131,7 @@ export const videoSchema = z.object({
         "generate",
         "status",
         "models",
+        "templates",
         "demos",
         "showcase",
         "shadows",
@@ -208,11 +215,51 @@ export const videoSchema = z.object({
         .number()
         .optional()
         .describe("action=showcase: ordem na trilha do mini-cinema (asc, 0..999; menor aparece primeiro)."),
+    // --- Receita de take (templateSlug + brief) ---
+    templateSlug: z
+        .string()
+        .optional()
+        .describe("action=create: slug de um TEMPLATE de vídeo (receita travada da casa, igual ao templateSlug da imagem). " +
+        "Com ele, `prompt` vira só a CENA e o template embrulha com estilo, enquadramento, arco, áudio e look, " +
+        "além de escolher o motor (por isso `model` fica opcional). O `brief` preenche os campos do formato. " +
+        "Descubra os slugs em action=templates (sem custo, sem login): hoje 'ugc-vertical-v1', 'unboxing-vertical-v1', " +
+        "'app-demo-vertical-v1' e 'reflexao-vertical-v1'. Override de model/aspectRatio/durationSec/resolution vale, " +
+        "mas só dentro do que a receita aceita (o erro lista as opções)."),
+    brief: z
+        .object({
+        subject: z.string().optional().describe("O que o take é: o produto, a ideia, o tópico."),
+        subjectType: z.string().optional().describe("app | physical | saas | ideia."),
+        persona: z.string().optional().describe("Quem aparece (ou as mãos que aparecem)."),
+        uvps: z.array(z.string()).optional().describe("2 a 4 pontos curtos a reforçar."),
+        hook: z
+            .object({
+            line: z.string().optional().describe("A frase de abertura, 5-10 palavras."),
+            emotion: z.string().optional().describe("Emoção alvo (curiosidade, frustração, espanto)."),
+        })
+            .optional(),
+        shots: z
+            .array(z.object({
+            sec: z.number().optional().describe("Em que segundo o momento acontece."),
+            role: z.string().optional().describe("hook | problem | solution | cta."),
+            camera: z.string().optional().describe("close-up | medium | over-shoulder | product-pov."),
+            action: z.string().optional().describe("A ação visual em uma frase."),
+            emotion: z.string().optional(),
+            voiceLine: z.string().optional().describe("A fala da cena, na língua do brief."),
+            propVisible: z.string().optional().describe("Objeto/tela que precisa aparecer legível."),
+        }))
+            .optional()
+            .describe("Os momentos do take, na ordem. Sem eles, o template usa o arco de reserva dele."),
+        language: z.string().optional().describe("'pt-BR' (default) ou 'en'."),
+        energy: z.string().optional().describe("calm | high."),
+    })
+        .optional()
+        .describe("action=create com templateSlug: o formulário do template. Cada receita usa os campos que precisa " +
+        "(veja `briefFields` em action=templates) e ignora o resto; campo vazio some do prompt em vez de virar buraco."),
     // --- action=create ---
     model: z
         .enum(VIDEO_MODELS)
         .optional()
-        .describe("action=create: modelo de vídeo. O catálogo POR MODELO (capacidades, referências, tetos, preço) mora na description desta tool e VIVO em action=models; a skill 'video' (sapiens_skill) guia a escolha. " +
+        .describe("action=create: modelo de vídeo (opcional quando você passa templateSlug: a receita traz o motor). O catálogo POR MODELO (capacidades, referências, tetos, preço) mora na description desta tool e VIVO em action=models; a skill 'video' (sapiens_skill) guia a escolha. " +
         "Atalho de famílias: seedance/seedance-2-*/seedance-25 = cena+áudio+referências (o 25 estica até 30s e o preço acompanha), seedance-15 = degrau 1.5, kling = anima imagem, wan = imagem que fala, " +
         "hailuo/hailuo-pro = movimento puro sem áudio, h3 = 2K com áudio, kling-motion/shot-mimic = transferência de movimento/plano, lite/fast/quality = Veo 3.1, omni = Gemini com áudio nativo."),
     durationSec: z
@@ -427,6 +474,18 @@ export async function video(args) {
             note: "basePriceSinapses é o PISO (config mais barata, já com override admin); o preço real escala por duração x resolução [x áudio]. available=false = 'em breve' (depende de env, ex: Omni).",
         };
     }
+    // templates: catálogo VIVO das receitas de take (estilo + spec + os campos de
+    // brief que cada uma usa). Público, sem custo e sem login, igual ao models:
+    // escolher a receita certa é de graça, errar o take é que custa.
+    if (args.action === "templates") {
+        const rows = await convexQuery("videoTemplates:list", {});
+        return {
+            count: rows?.length ?? 0,
+            templates: rows ?? [],
+            note: "Passe o slug em action=create como templateSlug: o `prompt` vira só a CENA e o `brief` preenche o resto. " +
+                "briefFields diz o que vale a pena preencher em cada receita; allowedModels/allowedDurationsSec são o teto do override.",
+        };
+    }
     const sessionToken = getSessionToken();
     if (args.action === "demos") {
         return await convexQuery("videoSpecs:mcpListMyDemoFilms", { sessionToken });
@@ -565,8 +624,8 @@ export async function video(args) {
         });
     }
     if (args.action === "create") {
-        if (!args.model) {
-            throw new Error("action=create exige model (ex: sapiens-video-seedance, sapiens-video-kling, sapiens-video-wan, sapiens-video-kling-motion).");
+        if (!args.model && !args.templateSlug) {
+            throw new Error("action=create exige model (ex: sapiens-video-seedance, sapiens-video-kling, sapiens-video-wan, sapiens-video-kling-motion) ou templateSlug (a receita traz o motor; veja action=templates).");
         }
         // Frame inicial/final por arquivo local (paridade com o upload do site):
         // lê do disco e injeta em references role start/end. O backend
@@ -578,6 +637,8 @@ export async function video(args) {
         return await convexAction("mcpExtrasActions:mcpVideoCreateAndRender", {
             sessionToken,
             model: args.model,
+            templateSlug: args.templateSlug,
+            brief: args.brief,
             prompt: args.prompt,
             aspectRatio: args.aspectRatio,
             durationSec: args.durationSec,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "mcpName": "com.sapiensinteticos/sapiens",
   "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",