sapiens-mcp 1.69.2 → 1.71.0

package/dist/clientIdentity.js

@@ -0,0 +1,41 @@
+// ============================================
+// QUEM É O CLIENT — o motor que a pessoa usa do outro lado do MCP.
+//
+// O backend quer saber por onde um personagem nasceu ou foi ativado ("MCP
+// (Claude)" em vez de "MCP (agente)" no alerta do dono). Dois transportes,
+// duas fontes:
+//   - stdio: o handshake `initialize` traz clientInfo {name, version} e o
+//     Server do SDK guarda em getClientVersion(). É a fonte boa: "claude-ai",
+//     "claude-code", "cursor", "gemini-cli"...
+//   - remoto (streamable HTTP, stateless na Vercel): cada request é um Server
+//     novo e o initialize não fica. Sobra o User-Agent do HTTP, que viaja com
+//     o prefixo "ua:" pro backend saber que é pista, não nome.
+// O valor cru vai pro backend, que rotula (convex/shared/characterOrigin.ts).
+// Nunca é identidade: a identidade é sempre o bearer/login.
+// ============================================
+import { AsyncLocalStorage } from "node:async_hooks";
+const MAX = 120;
+const requestClient = new AsyncLocalStorage();
+/** Limpa o que veio de fora: uma linha, sem caractere de controle, teto de 120. */
+export function sanitizeClientName(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const clean = raw
+        .replace(/[\u0000-\u001f\u007f]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!clean)
+        return undefined;
+    return clean.slice(0, MAX);
+}
+/** Embrulha a chamada com a pista do client (call do stdio ou request remota). */
+export function runWithClientHint(hint, fn) {
+    const clean = sanitizeClientName(hint);
+    if (!clean)
+        return fn();
+    return requestClient.run(clean, fn);
+}
+/** A pista do client da chamada em curso, se houver. */
+export function getClientName() {
+    return requestClient.getStore();
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { getCachedTier, onTierVisibilityChange, probeTierInBackground, } from ".
 import { getPrompt, listPrompts } from "./prompts.js";
 import { listSkillResources, readSkillResource } from "./skills.js";
 import { convexMutation, getSessionToken } from "./convexClient.js";
+import { runWithClientHint } from "./clientIdentity.js";
 // Telemetria stdio (fire-and-forget, NUNCA derruba a chamada). O stdio sempre
 // foi caixa-preta (cada cliente roda a própria cópia via npx), então o
 // transporte que mais roda — Helen/Cursor/Gemini CLI — era invisível na
@@ -77,7 +78,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const name = req.params.name;
     const args = (req.params.arguments ?? {});
     const t0 = Date.now();
-    const result = await callTool(name, args);
+    // O client do handshake (clientInfo.name) viaja com a chamada: é o que
+    // deixa o backend dizer "MCP (Claude)" em vez de "MCP (agente)".
+    const result = await runWithClientHint(server.getClientVersion()?.name, () => callTool(name, args));
     logStdioUsage({
         tool: name,
         action: typeof args.action === "string" ? args.action : null,

package/dist/registry.js

@@ -76,7 +76,7 @@ export const TOOLS = {
         handler: repertorio,
     },
     sapiens_gallery: {
-        description: "Browse, publicação e upload das imagens do user. Sub-actions: list (últimas N peças, com prompt/model/url + isPublic + acervoUrl; kind=image por default, kind=video traz os takes com posterUrl, a capa, e kind=all mistura. Depois de ingerir ou gerar vídeo, é o list kind=video que dá a capa pra mostrar miniatura + player em vez de link solto), get (1 imagem com metadados, opcionalmente base64), publish (torna a PRÓPRIA imagem pública: entra na galeria pública + feed Pinterest, e ganha página indexável /imagem/<id> se o modelo não for degen devolve publicPageUrl; publicado NÃO despublica, não existe unpublish), upload (traz pra galeria uma peça gerada FORA da casa, por sourceUrl https, filePath local ou base64; ADMIN por ora), ingest (peça que a CASA dirigiu e um motor externo só renderizou: entra NATIVA na timeline e nasce PRIVADA (isPublic false), publicável DEPOIS pelo dono como qualquer geração da casa, nunca sozinha, com custo 0 em Sinapses e o custo real guardado em externalCost; carrega o prompt inteiro, as referências da casa (referenceImageIds) e o personagem (characterId), e é idempotente por sourceUrl, então re-ingerir corrige a ficha em vez de duplicar; ADMIN), refs (acopla peças da casa como REFERÊNCIA numa peça que já existe, de upload ou de ingest; ADMIN, e só na própria peça), cast (QUEM ESTÁ EM CENA numa peça que já existe, quando é mais de uma criatura: characterIds em ordem, o protagonista primeiro, e a peça passa a contar na ficha de todos eles em vez de sumir da segunda; qualquer membro, na própria peça). Use list/get pra reusar imagem como referência (passe o imageId em sapiens_image mode=edit ou mode=variation) ou pra mostrar pro user o que ele já tem; publish quando o user quer divulgar a imagem dele. IMPORTANTE sobre upload: a peça entra PRIVADA e continua privada — o servidor recusa publicar e recusa compartilhar na comunidade, porque ela é do usuário e a responsabilidade é dele. O caminho pra ela virar coisa pública é usar como referência numa geração daqui e publicar o resultado. O refs escreve só proveniência (de que ficha/folha a peça nasceu): não promove nada, e um upload continua sem publicar depois de ganhar referência.",
+        description: "Browse, publicação e upload das imagens do user. Sub-actions: list (últimas N peças, com prompt/model/url + isPublic + acervoUrl; kind=image por default, kind=video traz os takes com posterUrl, a capa, e kind=all mistura. Depois de ingerir ou gerar vídeo, é o list kind=video que dá a capa pra mostrar miniatura + player em vez de link solto), get (1 imagem com metadados, opcionalmente base64), publish (torna a PRÓPRIA imagem pública: entra na galeria pública + feed Pinterest, e ganha página indexável /imagem/<id> se o modelo não for degen devolve publicPageUrl; publicado NÃO despublica, não existe unpublish), upload (traz pra galeria uma peça gerada FORA da casa, por sourceUrl https, filePath local ou base64; ADMIN por ora), ingest (A PONTE, qualquer conta logada: peça que a PESSOA dirigiu com a ficha do personagem daqui e um motor de fora renderizou, no crédito dela (Kie, fal, Magnific, Sogni, a própria placa): entra NATIVA na timeline e nasce PRIVADA (isPublic false), publicável DEPOIS por ela como qualquer geração da casa, nunca sozinha, com custo 0 em Sinapses e o custo real guardado em externalCost; carrega o prompt VERBATIM, as referências da casa (referenceImageIds), o personagem (characterId) e o motor (externalEngine 'provedor-motor'); a peça chega por filePath (local, só no MCP instalado), sourceUrl (o render, baixado pelo MCP na máquina da pessoa, nunca pelo servidor) ou base64; o carimbo +18 nasce na entrada pela CLASSE do provedor (peso aberto como Sogni, Replicate, HF, fal, WaveSpeed, Civitai e a própria placa entram carimbados, só a curadoria tira; serviço com moderação como Kie, Magnific, Freepik, Krea entra sem) ou por unfiltered=true dito pela pessoa (carimbo dela, ela tira depois); idempotente por sourceUrl ou pelo hash do arquivo, então re-ingerir corrige a ficha em vez de duplicar; tetos 12 MB imagem, 60 MB vídeo, 40 por dia. A chave do provedor NUNCA passa por aqui: quem gerou foi o harness da pessoa. Passo a passo na skill 'pontes'), refs (acopla peças da casa como REFERÊNCIA numa peça que já existe, de upload ou de ingest; ADMIN, e só na própria peça), cast (QUEM ESTÁ EM CENA numa peça que já existe, quando é mais de uma criatura: characterIds em ordem, o protagonista primeiro, e a peça passa a contar na ficha de todos eles em vez de sumir da segunda; qualquer membro, na própria peça). Use list/get pra reusar imagem como referência (passe o imageId em sapiens_image mode=edit ou mode=variation) ou pra mostrar pro user o que ele já tem; publish quando o user quer divulgar a imagem dele. IMPORTANTE sobre upload: a peça entra PRIVADA e continua privada: o servidor recusa publicar e recusa compartilhar na comunidade, porque ela é do usuário e a responsabilidade é dele. O caminho pra ela virar coisa pública é usar como referência numa geração daqui e publicar o resultado. O refs escreve só proveniência (de que ficha/folha a peça nasceu): não promove nada, e um upload continua sem publicar depois de ganhar referência. COMO A PEÇA FOI FEITA: list aceita skill=<slug> e devolve só o que saiu daquela skill (o mesmo slug que sapiens_image gravou em skills), com a busca varrendo as últimas 200 peças antes de cortar no limit; cada item volta com o campo skills, e null ali quer dizer que ninguém marcou, não que foi feita sem skill.",
         schema: gallerySchema,
         handler: gallery,
     },
@@ -236,26 +236,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 personagem ou prompt de Midjourney (personagem), criar na identidade do usuário (studio), 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:
-- 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.
-- 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: geração SÍNCRONA 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 (a tabela de onde conferir está na skill 'primeiros-passos').
-- "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. Se vier 'characterOffer', siga o que ele manda: são personagens que o usuário escreveu e que podem entrar em cena, e quem OFERECE é você, na hora em que a conversa encostar num deles. Só personagem de autoria dele; a alma de personagem alheio não sai por aqui.
-
+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 personagem ou prompt de Midjourney (personagem), criar na identidade do usuário (studio), 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), gerar em motor de fora com crédito próprio e trazer a peça pro acervo (pontes). 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.
+- 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.
+- SEM SALDO, ou motor que a casa não tem: a casa é ponte, não muro. Se a pessoa tem crédito na Kie, na fal, na Magnific, na Sogni ou na própria placa, ela gera LÁ com a ficha do personagem daqui (sapiens_character action=get) e a peça volta pro acervo por sapiens_gallery action=ingest. A chave dela NUNCA passa pelo Sapiens (nem em arg, nem no chat). sapiens_meta action=pontes diz o que ela já tem configurado; skill 'pontes' tem o passo a passo.
+- REGRA DO TIMEOUT: geração SÍNCRONA 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 (a tabela de onde conferir está na skill 'primeiros-passos').
+- "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. Se vier 'characterOffer', siga o que ele manda: são personagens que o usuário escreveu e que podem entrar em cena, e quem OFERECE é você, na hora em que a conversa encostar num deles. Só personagem de autoria dele; a alma de personagem alheio não sai por aqui.
+
 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,

package/dist/remote.js

@@ -1,4 +1,5 @@
 import { createMcpHandler, withMcpAuth } from "mcp-handler";
+import { runWithClientHint } from "./clientIdentity.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { buildToolList, callTool, SAPIENS_INSTRUCTIONS, } from "./registry.js";
 import { getPrompt, listPrompts } from "./prompts.js";
@@ -263,7 +264,10 @@ export function createSapiensRemoteHandler(opts) {
         if (!tokenLimiter.hit(token)) {
             return tooMany("Muitas requisições dessa sessão num minuto. Espere um pouco e tente de novo.");
         }
-        return runWithSessionToken(token, () => base(req));
+        // Stateless: o initialize não fica entre requests, então a pista do client
+        // aqui é o User-Agent (prefixo "ua:" avisa o backend que é pista, não nome).
+        const ua = req.headers.get("user-agent") ?? undefined;
+        return runWithSessionToken(token, () => runWithClientHint(ua ? `ua:${ua}` : undefined, () => base(req)));
     };
     const authed = withMcpAuth(inner, (_req, bearerToken) => {
         // Shape-check só (sem rede): a validação de VERDADE acontece por request

package/dist/skills.js

@@ -729,6 +729,76 @@ A foto NUNCA vai pra banco nenhum, nem da casa nem de terceiro:
 - Idiomas com \`pct\` honesto (nativo ~100, fluente ~85, intermédio ~55).
 - Visto/disponibilidade/mudança entram em \`highlight\` (o box perto do contato), não no resumo.`,
     },
+    {
+        name: "pontes",
+        title: "Pontes: gerar fora com crédito próprio e trazer pro acervo",
+        description: "A pessoa tem crédito na Kie, na fal, na Magnific, na Sogni ou na própria placa e quer usar o personagem dela lá, ou está sem Sinapse pra vídeo. Como levar a ficha, gerar no balcão dela (a chave nunca passa pelo Sapiens) e trazer a peça de volta por sapiens_gallery action=ingest, com a ficha inteira. Puxe quando ouvir 'tem Kie aí?', 'uso a fal', 'gastei minhas Sinapses', 'gero na Magnific', 'tenho ComfyUI'.",
+        body: `## O que é uma ponte
+
+O Sapiens é uma das pontes, não um muro. A pessoa monta o personagem aqui (ficha, passaporte, referências) e gera a peça ONDE TEM CRÉDITO: Kie, fal, Magnific, Sogni, Krea, Replicate, a própria placa. A peça volta pro acervo dela como NATIVA, com motor, prompt, custo real e personagem na ficha, custo 0 em Sinapses. O portfólio dela cresce aqui; o dinheiro dela sai de onde ela já pôs.
+
+**A regra da chave, sem exceção:** a chave do provedor NUNCA passa pelo Sapiens. Não vai em arg de tool, não vai em prompt, não vai colada no chat. Ela mora no ambiente da pessoa (variável \`FAL_KEY\`, \`KIE_API_KEY\`, um conector MCP do provedor ligado na conversa, o SDK dela) e quem chama o motor é o harness dela, na máquina dela. O Sapiens entra ANTES (a ficha) e DEPOIS (o ingest). Se a pessoa colar a chave no chat por engano, diga pra ela rotacionar a chave no provedor, e siga sem usar o valor.
+
+## Passo 1: descobrir onde a pessoa tem crédito
+
+\`sapiens_meta action=pontes\` (sem login, sem custo) devolve o catálogo de balcões e, no MCP instalado, o que já está configurado no ambiente dela, lido pelo NOME da variável (o valor nunca é lido nem devolvido). No remoto (claude.ai, ChatGPT) ele não olha nada: pergunte.
+
+Ordem de preferência quando há mais de uma opção, pelo que custa DE VERDADE pra pessoa:
+1. O que ela já paga fixo (assinatura Sogni, Magnific com crédito parado, a própria placa): custo marginal zero.
+2. O balcão onde ela tem crédito pré-pago (Kie, fal, WaveSpeed, Krea, Replicate): custo por peça, em dólar.
+3. \`sapiens_video\` / \`sapiens_image\` em Sinapse: o único que serve motor exclusivo da casa e o único com a régua de qualidade da casa por trás. Não é o último por ser pior: é o último por ser o mais caro por peça.
+
+Confirme com ela ANTES de disparar em qualquer balcão pago. Geração de fora também custa dinheiro real, só que dela.
+
+## Passo 2: a ficha portátil
+
+\`sapiens_character action=get characterId=<id>\` (ou \`list_mine\` pra achar o id). O que viaja:
+
+- \`passportPrompt\`: o bloco já montado pra colar no prompt do motor (descritor em inglês + negative travado + locks). Cole VERBATIM no começo do prompt; a cena vem depois.
+- \`imageUrls\` e \`mainImageUrl\`: as referências. São URLs públicas do CDN da casa, aceitas direto pelos motores que recebem referência por URL (Kie, fal, Krea). Motor que quer arquivo (ComfyUI, alguns SDKs): baixe a imagem antes.
+- \`passport.recipes\`: as receitas medidas por tipo de peça (\`kind\`, \`engine\`, \`prompt\`, \`note\`). Se existe receita pro motor que ela vai usar, é ELA que vai, verbatim.
+- \`passport.refs\` por papel (rosto, proporção, tatuagem): ref sem papel ninguém sabe usar. Use a de rosto como referência de identidade, a de proporção como frame inicial quando o motor é image-to-video.
+
+Regras que valem fora igual dentro: prompt SEM idade em número; personagem nunca menor (a casa trabalha com 23+ no foco e 18 é piso absoluto); motor citado pelo nome que ele tem no provedor. Prompt novo que funcionar lá fora: grave de volta com \`sapiens_character action=set_passport\` (campo \`recipes\`, prompt verbatim + note com o que provou). É isso que faz a próxima rodada não redescobrir.
+
+## Passo 3: gerar lá fora
+
+O que a casa MEDIU em cada balcão (o resto está na doc do provedor; não invente parâmetro):
+
+| Balcão | Onde a chave mora | O que roda bem | Armadilha medida |
+|---|---|---|---|
+| **Kie** | \`KIE_API_KEY\` | Kling 3.0, Kling Motion, MiniMax/Hailuo, WAN; imagem também | Um endpoint pra tudo: \`POST createTask\` com \`model\` + \`input\`, depois \`recordInfo\` até estado final. HTTP 200 NÃO é sucesso: o \`code\` vem no corpo (422 modelo inexistente, 500 campo faltando, 401 chave). O \`resultJson\` é STRING com JSON dentro (\`resultUrls\` está lá). A URL do resultado expira em 24h e a mídia some em 14 dias: ingira no mesmo turno. Rate limit de 20 criações por 10s por conta. |
+| **fal.ai** | \`FAL_KEY\` | Krea 2 (inclusive sem freio), Kling, WAN, Seedance, Flux | \`POST https://fal.run/<endpoint>\` síncrono com \`Authorization: Key <FAL_KEY>\`, ou a fila em \`queue.fal.run\` pra vídeo. O modelo vai no SLUG do endpoint, não no corpo. Entrega em \`fal.media\`. Slug \`fal-\` na casa entra como classe +18 (sai da vitrine anônima, fica no perfil). |
+| **WaveSpeed** | \`WAVESPEED_API_KEY\` | Flux.2 Klein, Krea 2 Livre, WAN 2.2, Kling, Shot Mimic | É o balcão que a casa mais usa por trás do \`sapiens_video\`; o que a casa serve em Sinapse a pessoa pode rodar direto com a chave dela. Slug \`wavespeed-\` é classe +18 na casa. |
+| **Sogni** | \`SOGNI_API_KEY\` (SDK \`@sogni-ai/sogni-client\`) | MiniMax H3 inteira, WAN 2.2 com animate, LTX 2.3 e 2.5, Krea 2 Turbo, Identity Edit | Assinatura Unlimited cobre o catálogo aberto (\`billingMode: "subscription"\`, custo marginal zero); Seedance e GPT Image saem em Spark comprado. UM socket por conta: um job por vez. Vídeo de 10s+ leva 20 min de parede; rode em background e espere. Matar o processo local NÃO cancela o job (cancele pela API). |
+| **Magnific / Freepik** | conector MCP na conversa (sem chave) | Seedance 2.0 e 2.5 (até 30s e 1080p, mais que a casa), MiniMax H3, upscale, relight | A URL assinada do render expira no mesmo dia: ingira na hora. \`multi_prompt\` junto com \`references\` quebra no Seedance 2.0: plano único com prompt longo. A frase "preserve their identity" é recusada pelo H3 de lá: escreva "keep the same face, body proportions, outfit". |
+| **Krea API** | \`KREA_API_KEY\` | Krea 2 Turbo/Medium/Large, MiniMax H3 Max Turbo, Seedream, Veo, Seedance | Preço fixo por geração, saldo pré-pago separado do app. Filtra NSFW e job que falha (inclusive por moderação) não cobra. Sem img2img no Krea 2 e sem LoRA de fora. |
+| **A própria máquina** | nada (ComfyUI, SD local, runner) | o que a placa aguenta: LTX, Klein, Krea 2 com LoRA, H3 destilado | Custo zero em dinheiro, pago em tempo. A peça entra por \`filePath\`, slug \`bancada-<motor>\` (ex: \`bancada-ltx-2.5\`). Guarde o \`.json\` da geração ao lado do arquivo: é de lá que sai o prompt verbatim e a seed pra ficha. |
+
+Não repita geração paga às cegas: se a chamada deu timeout, consulte o job no provedor antes de criar outro. Peça grande (master de 30s em 1080p) reencoda em peso de web ANTES de trazer: \`ffmpeg -i in.mp4 -c:v libx264 -crf 23 -preset slow -movflags +faststart out.mp4\`. Guarde o master local.
+
+## Passo 4: trazer pra casa
+
+\`sapiens_gallery action=ingest\`, no MESMO turno do render (URL de render expira):
+
+- A peça: \`filePath\` (arquivo local; só no MCP instalado, é a porta de quem gerou na máquina ou baixou antes), ou \`sourceUrl\` (o link do render; quem baixa é o MCP na máquina da pessoa, não o servidor), ou \`base64\` (imagem).
+- \`externalEngine\`: \`provedor-motor\`, sempre. \`kie-kling-3.0\`, \`fal-krea-2\`, \`sogni-minimax-h3\`, \`magnific-seedance-2.5\`, \`bancada-ltx-2.5\`. Marca sozinha é recusada: é este campo que a ficha mostra em "Motor".
+- \`prompt\`: o texto EXATO mandado ao motor. Não é resumo, não é título. É o que permite regerar.
+- \`externalCost\`: na moeda de lá ("420 créditos Kie", "US$ 0,35 na fal", "0, assinatura Sogni", "0, 17 min na RTX 5060 Ti").
+- \`characterId\` (ou \`characterIds\` em ordem de cena quando há mais de uma criatura) e \`referenceImageIds\` (as peças da casa que serviram de ref). Sem os dois a peça entra órfã: publica, mas não conta no personagem.
+- \`aspectRatio\` e \`size\` como saíram do motor.
+- O carimbo +18 nasce na entrada pela CLASSE do provedor, porque a peça já chega renderizada e nenhuma guarda de geração da casa alcança os bytes. Peso aberto (Sogni, Replicate, Hugging Face, fal, WaveSpeed, Civitai, a própria placa) ou provedor que a casa não conhece: a peça entra COM o carimbo, que só a curadoria tira (igual ao motor sem freio da casa). Serviço com moderação (Kie, Magnific, Freepik, faceless, Krea, Midjourney, Runway, Higgsfield): entra SEM carimbo. Nome de motor com \`-spicy\`, \`-nsfw\`, \`-uncensored\` carimba por classe também. \`unfiltered: true\` é a declaração da pessoa pra motor de nome neutro em modo livre num serviço que modera: carimba em nome dela, e ela tira depois na ficha. Carimbo é alcance, não existência: publica, fica no perfil e no link, sai da vitrine anônima. Avise a pessoa quando a peça entrar carimbada por classe: ela precisa saber que a vitrine anônima não vai mostrar.
+
+Tetos: 12 MB imagem, 60 MB vídeo por peça; 40 peças por dia e 300 no estoque por conta. Formatos: mp4, mov, png, jpg, webp.
+
+O que a peça vira: NATIVA, PRIVADA, publicável depois por \`action=publish\` (ato da pessoa, nunca seu), custo 0 em Sinapses, sem assinatura C2PA (o motor rodou fora). Idempotente: repetir a mesma \`sourceUrl\` (ou o mesmo arquivo) corrige a ficha em vez de duplicar. Depois de ingerir, \`action=list kind=video\` traz a capa e a ficha: mostre a peça, não o link solto. Não apague o arquivo local antes de ver a peça no acervo.
+
+## Quando a ponte NÃO é o caminho
+
+- Motor exclusivo da casa: Helen TTS, Musicator, os templates de take (\`templateSlug\`), Sombras, o carimbo assinado. Isso só existe em Sinapse.
+- A pessoa tem Sinapse e o take é curto: \`sapiens_video\` é um comando só, com a régua de qualidade da casa. Menos atrito vence quando o custo cabe.
+- Peça achada pronta na internet, sem direção dela: é \`action=upload\` (privada pra sempre), não ingest.`,
+    },
 ];
 export const SKILLS = Object.fromEntries(SKILL_LIST.map((s) => [s.name, s]));
 /** Monta o SKILL.md completo (frontmatter do formato aberto + corpo). */

package/dist/tools/character.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { httpUrl } from "../schema.js";
 import { convexQuery, convexMutation, convexAction, getSessionToken } from "../convexClient.js";
+import { getClientName } from "../clientIdentity.js";
 /**
  * sapiens_character — personagens (character sheets) do Sapiens.
  *
@@ -333,6 +334,7 @@ export async function character(args) {
         const sessionToken = getSessionToken();
         return await convexMutation("influencers:mcpCreateCharacter", {
             sessionToken,
+            client: getClientName(),
             name: args.name,
             fullName: args.fullName,
             gender: args.gender,
@@ -441,6 +443,7 @@ export async function character(args) {
         const sessionToken = getSessionToken();
         return await convexMutation("influencers:mcpActivateCharacter", {
             sessionToken,
+            client: getClientName(),
             characterId: args.characterId,
         });
     }

package/dist/tools/gallery.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
-import { convexAction, convexMutation, getSessionToken, isRemoteContext, } from "../convexClient.js";
+import { createHash } from "node:crypto";
+import { convexAction, convexMutation, describeConvexError, getSessionToken, isRemoteContext, } from "../convexClient.js";
 /**
  * Galeria do usuário: browse, publicação e UPLOAD de peça de fora.
  * Wrapper sobre `desktopMcp.galleryList` / `galleryGet` / `gallerySetPublic` e
@@ -13,18 +14,21 @@ import { convexAction, convexMutation, getSessionToken, isRemoteContext, } from
  *   - 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
+ *   - Ingerir peça gerada em motor EXTERNO com a receita da pessoa
+ *     (action=ingest, qualquer conta desde set/2026: a PONTE), 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.
+ * O INGEST tem duas portas no servidor com o mesmo contrato de peça: a do dono
+ * (o servidor baixa de allowlist fechada de hosts, convex/externalIngest.ts) e
+ * a ponte (os bytes são resolvidos AQUI, na máquina da pessoa, sobem pro
+ * storage do Convex e o servidor só move pro Bunny, convex/externalIngestNode.ts).
+ * A diferença entre upload e ingest não é de onde vieram os bytes, é de quem
+ * foi a DIREÇÃO: peça achada pronta é upload; peça que a pessoa dirigiu (a
+ * ficha do personagem dela, o prompt dela) e um motor terceiro só renderizou é
+ * ingest. A chave do provedor nunca passa por aqui nem pelo servidor.
  */
 export const gallerySchema = z.object({
     action: z.enum([
@@ -47,6 +51,10 @@ export const gallerySchema = z.object({
         .string()
         .optional()
         .describe("Filtro de model (action=list). Ex: 'nano-banana-max' pra ver só Pro."),
+    skill: z
+        .string()
+        .optional()
+        .describe("Filtro por SKILL que dirigiu a peça (action=list): devolve só o que saiu daquela skill, pelo slug exato que a geração gravou (ex: 'camarim', 'escala-gigantismo'). É o que responde 'me mostra tudo que saiu do camarim'. Com filtro, a busca varre as últimas 200 peças antes de cortar no limit, então acha coisa antiga. Peça sem marcação nenhuma volta com skills null e nunca casa com filtro."),
     kind: z
         .enum(["image", "video", "all"])
         .optional()
@@ -59,23 +67,23 @@ export const gallerySchema = z.object({
         .boolean()
         .optional()
         .describe("Default false. Quando true, action=get devolve os bytes em base64 (pesado, evite em listagens)."),
-    // --- action=upload (peça de fora) ---
+    // --- action=upload e action=ingest: de onde vêm os bytes ---
     sourceUrl: z
         .string()
         .optional()
-        .describe("action=upload: URL https direta da imagem gerada em outro lugar (ex: o link do render da Magnific). Alternativa a filePath/base64."),
+        .describe("action=upload/ingest: URL https direta da peça pronta no motor de fora (o link do render da Kie, da fal, da Magnific). No ingest ela também é o RASTRO e a chave de idempotência: repetir a mesma sourceUrl corrige a ficha em vez de duplicar. Quem baixa é o cliente MCP (na sua máquina, no stdio; no remoto, o servidor do site): URL de render expira (Kie em 24h, Magnific no mesmo dia), então ingira no mesmo turno do render. Alternativa a filePath/base64."),
     filePath: z
         .string()
         .optional()
-        .describe("action=upload: caminho ABSOLUTO de um arquivo de imagem local. SÓ no MCP instalado (stdio); no remoto use sourceUrl."),
+        .describe("action=upload/ingest: caminho ABSOLUTO de um arquivo local (png, jpg, webp, mp4, mov). SÓ no MCP instalado (stdio): é a porta de quem gerou na própria máquina ou baixou o render antes; no remoto use sourceUrl. No ingest, o sha256 do arquivo vira a chave de idempotência."),
     base64: z
         .string()
         .optional()
-        .describe("action=upload: os bytes já em base64, se você mesmo os tem em mãos."),
+        .describe("action=upload/ingest: os bytes já em base64, se você mesmo os tem em mãos (imagem; vídeo vai por filePath ou sourceUrl)."),
     mimeType: z
         .string()
         .optional()
-        .describe("action=upload: tipo do arquivo (image/png, image/webp...). Detectado sozinho a partir da URL/extensão/resposta HTTP quando omitido."),
+        .describe("action=upload/ingest: tipo do arquivo (image/png, video/mp4...). Detectado sozinho a partir da URL/extensão/resposta HTTP quando omitido."),
     note: z
         .string()
         .optional()
@@ -84,7 +92,7 @@ export const gallerySchema = z.object({
     externalEngine: z
         .string()
         .optional()
-        .describe("action=ingest (ADMIN): qual motor renderizou, sempre no formato provedor-motor ('freepik-seedance-2.0', 'magnific-minimax-h3', 'faceless-seedance-2.0'). É ESTE campo que a ficha da peça mostra em 'Motor', então a marca sozinha ('magnific') é recusada pelo servidor: provedor é a loja, não o motor."),
+        .describe("action=ingest: qual motor renderizou, sempre no formato provedor-motor ('kie-kling-3.0', 'fal-krea-2', 'magnific-minimax-h3', 'sogni-minimax-h3', 'bancada-ltx-2.5'). É ESTE campo que a ficha da peça mostra em 'Motor', então a marca sozinha ('kie', 'magnific') é recusada pelo servidor: provedor é a loja, não o motor. O provedor decide o carimbo +18 na entrada: peso aberto (sogni-, replicate-, hf-, fal-, wavespeed-, civitai-, bancada-, comfy-, local-) ou provedor que a casa não conhece entra com o carimbo por classe (publica e fica no perfil, só não vai pra vitrine anônima); serviço com moderação (kie-, magnific-, freepik-, faceless-, krea-, midjourney-, runway-, higgsfield-, modelark-) entra sem."),
     externalCost: z
         .string()
         .optional()
@@ -117,6 +125,10 @@ export const gallerySchema = z.object({
         .union([z.array(z.string()), z.string()])
         .optional()
         .describe("QUEM ESTÁ EM CENA, quando é mais de uma criatura (action=ingest e action=cast). Em ordem de cena: o PRIMEIRO é o protagonista (é ele que a ficha e o cartão do vídeo mostram) e o resto vira elenco, então a peça conta na ficha de TODOS eles em vez de sumir da segunda. Teto de 6. Use quando a fita foi dirigida com duas folhas de personagem: sem isto, ela aparece só na ficha de um. Aceita lista ou os ids separados por vírgula, personagem seu ou público. Pra peça de uma criatura só continue usando characterId."),
+    unfiltered: z
+        .boolean()
+        .optional()
+        .describe("action=ingest: true quando o motor rodou SEM filtro de conteúdo (modo livre, spicy, uncensored) num serviço que normalmente modera. A peça nasce com o carimbo +18 da casa DECLARADO por você (você pode tirar depois na ficha): publica, fica no seu perfil e no link direto, e sai da vitrine anônima e dos feeds. Não precisa dizer pra provedor de peso aberto (Sogni, Replicate, Hugging Face, fal, WaveSpeed, Civitai, a própria placa): esses já entram com o carimbo por CLASSE, que só a curadoria tira, igual ao motor sem freio da casa. Serviço com moderação (Kie, Magnific, Freepik, faceless, Krea, Midjourney, Runway, Higgsfield) entra sem carimbo, a menos que você diga isto ou o nome do motor tenha '-spicy', '-nsfw', '-uncensored'."),
     replace: z
         .boolean()
         .optional()
@@ -130,6 +142,13 @@ export const gallerySchema = z.object({
 // que falhar depois de trafegar o base64 inteiro.
 const MAX_UPLOAD_BYTES = 12 * 1024 * 1024;
 const FETCH_TIMEOUT_MS = 30_000;
+// Tetos da PONTE (action=ingest pela porta do membro), espelho de
+// convex/shared/ingestRules.ts. O servidor devolve os dele na uploadUrl e é o
+// que manda; estes só recusam antes de trafegar o arquivo.
+const MAX_INGEST_VIDEO_BYTES = 60 * 1024 * 1024;
+const MAX_INGEST_IMAGE_BYTES = 12 * 1024 * 1024;
+// Render de vídeo demora mais pra baixar que uma imagem.
+const INGEST_FETCH_TIMEOUT_MS = 120_000;
 const EXT_MIME = {
     png: "image/png",
     jpg: "image/jpeg",
@@ -137,6 +156,9 @@ const EXT_MIME = {
     webp: "image/webp",
     gif: "image/gif",
     avif: "image/avif",
+    // Vídeo entra pela ponte (action=ingest); o upload continua só imagem.
+    mp4: "video/mp4",
+    mov: "video/quicktime",
 };
 function mimeFromPath(p) {
     const ext = p.split("?")[0].split("#")[0].split(".").pop()?.toLowerCase();
@@ -217,6 +239,101 @@ async function resolveUploadBytes(args) {
     }
     throw new Error("action=upload exige a peça: sourceUrl (https), filePath (local, stdio) ou base64.");
 }
+const AVISO_INGEST = "Peça NATIVA: entra na timeline PRIVADA (isPublic false), igual a qualquer geração da casa. Ela NÃO publica sozinha e NÃO vai pra comunidade: publicar é ato separado do dono, por action=publish. Custo em Sinapses é 0 e ela NÃO leva assinatura C2PA, porque o motor rodou fora. Use ingest só quando a receita (ficha do personagem, prompt, folha) foi sua; peça achada pronta é action=upload. Mostre a peça com action=list kind=video (capa + player) em vez de devolver link solto.";
+/**
+ * Os bytes da PONTE, resolvidos aqui (na máquina da pessoa no stdio; no
+ * servidor do site no remoto, com o mesmo guard de host público do upload).
+ * Devolve também a chave de idempotência: a própria URL quando veio de URL, ou
+ * `sha256:<hash>` do conteúdo pra arquivo local e base64, pra o retry corrigir
+ * a ficha em vez de duplicar a peça.
+ */
+async function resolveIngestBytes(args) {
+    const tetoDe = (mime) => mime.startsWith("video/") ? MAX_INGEST_VIDEO_BYTES : MAX_INGEST_IMAGE_BYTES;
+    const confereTeto = (bytes, mime, oQue) => {
+        const teto = tetoDe(mime);
+        if (bytes.byteLength > teto) {
+            throw new Error(`${oQue} grande demais: ${(bytes.byteLength / 1024 / 1024).toFixed(1)} MB (teto ${Math.round(teto / 1024 / 1024)} MB). ` +
+                (mime.startsWith("video/")
+                    ? "Reencode em peso de web antes de trazer: ffmpeg -i in.mp4 -c:v libx264 -crf 23 -preset slow -movflags +faststart out.mp4 (um take de 15s em 1080p fica abaixo de 15 MB)."
+                    : "Exporte em webp ou jpg com qualidade 85."));
+        }
+    };
+    const hexDe = (bytes) => createHash("sha256").update(bytes).digest("hex");
+    if (args.base64?.trim()) {
+        const mimeType = args.mimeType ||
+            args.base64.match(/^data:([^;]+);base64,/)?.[1] ||
+            "image/png";
+        const bytes = Buffer.from(args.base64.trim().replace(/^data:[^;]+;base64,/, ""), "base64");
+        confereTeto(bytes, mimeType, "Peça");
+        const hex = hexDe(bytes);
+        return { bytes, mimeType, sourceKey: `sha256:${hex}`, sha256: hex };
+    }
+    if (args.filePath) {
+        if (isRemoteContext()) {
+            throw new Error("filePath só funciona no MCP instalado (stdio). No remoto, mande sourceUrl.");
+        }
+        const bytes = await readFile(args.filePath);
+        const mimeType = args.mimeType || mimeFromPath(args.filePath) || "image/png";
+        confereTeto(bytes, mimeType, "Arquivo");
+        const hex = hexDe(bytes);
+        return { bytes, mimeType, sourceKey: `sha256:${hex}`, sha256: hex };
+    }
+    if (args.sourceUrl) {
+        const u = assertPublicHttpsUrl(args.sourceUrl);
+        const res = await fetch(u, {
+            redirect: "follow",
+            signal: AbortSignal.timeout(INGEST_FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            throw new Error(`Baixar o render falhou: HTTP ${res.status} ${res.statusText}. URL de render expira (Kie em 24h, Magnific no mesmo dia): se passou do prazo, baixe de novo no provedor ou mande o arquivo por filePath.`);
+        }
+        // Revalida o destino final: um 3xx pra host privado seria o buraco que o
+        // assertPublicHttpsUrl da URL inicial não vê.
+        if (res.url)
+            assertPublicHttpsUrl(res.url);
+        const headerMime = res.headers.get("content-type")?.split(";")[0]?.trim();
+        const mimeType = args.mimeType || mimeFromPath(u.pathname) || headerMime || "image/png";
+        const bytes = Buffer.from(await res.arrayBuffer());
+        confereTeto(bytes, mimeType, "Render");
+        return { bytes, mimeType, sourceKey: args.sourceUrl, sha256: hexDe(bytes) };
+    }
+    throw new Error("action=ingest exige a peça: sourceUrl (https), filePath (local, stdio) ou base64.");
+}
+/**
+ * A ponte, de ponta a ponta: bytes -> URL assinada do storage -> action Node
+ * que move pro Bunny e grava a ficha. Três chamadas, e a chave de provedor não
+ * aparece em nenhuma delas, porque o motor já rodou antes, no harness da pessoa.
+ */
+async function ingestPelaPonte(sessionToken, args, ficha) {
+    const { bytes, mimeType, sourceKey, sha256 } = await resolveIngestBytes(args);
+    const porta = await convexMutation("externalIngest:mcpIngestUploadUrl", { sessionToken });
+    const teto = mimeType.startsWith("video/")
+        ? porta.maxVideoBytes
+        : porta.maxImageBytes;
+    if (bytes.byteLength > teto) {
+        throw new Error(`Peça grande demais pro servidor: ${(bytes.byteLength / 1024 / 1024).toFixed(1)} MB (teto ${Math.round(teto / 1024 / 1024)} MB). Reencode em peso de web e tente de novo.`);
+    }
+    const subida = await fetch(porta.uploadUrl, {
+        method: "POST",
+        headers: { "Content-Type": mimeType },
+        body: bytes,
+    });
+    if (!subida.ok) {
+        throw new Error(`Subir a peça pro storage falhou: HTTP ${subida.status}. Tente de novo; se repetir, peça outra uploadUrl (ela vale 1h).`);
+    }
+    const { storageId } = (await subida.json());
+    return await convexAction("externalIngestNode:mcpIngestFromStorage", {
+        sessionToken,
+        storageId,
+        mimeType,
+        sourceUrl: sourceKey,
+        // Prova de posse: o servidor confere contra o sha256 do storage antes de
+        // mover ou apagar qualquer byte.
+        contentSha256: sha256,
+        unfiltered: args.unfiltered,
+        ...ficha,
+    });
+}
 /**
  * Normaliza `referenceImageIds` pro formato que o Convex espera (lista).
  *
@@ -255,6 +372,7 @@ export async function gallery(args) {
             sessionToken,
             limit: args.limit ?? 20,
             model: args.model,
+            skill: args.skill,
             kind: args.kind,
         });
         return {
@@ -303,16 +421,32 @@ 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.",
         };
     }
+    // ingest: a peça que a pessoa DIRIGIU (ficha do personagem, prompt dela) e um
+    // motor de fora renderizou entra como NATIVA. Duas portas no servidor, o mesmo
+    // contrato de peça:
+    //
+    //   1. A do dono (`externalIngest:mcpIngestExternal`): o SERVIDOR baixa a URL,
+    //      só de host liberado, e fita grande que já mora no CDN da casa entra sem
+    //      trafegar byte. Continua como sempre foi.
+    //   2. A ponte (`externalIngestNode:mcpIngestFromStorage`): qualquer conta.
+    //      Os bytes são resolvidos AQUI, na máquina da pessoa (URL do render,
+    //      arquivo local ou base64), sobem pro storage do Convex pela URL assinada
+    //      e o servidor só move pro Bunny. Sem fetch de URL do membro no servidor,
+    //      sem chave de provedor em lugar nenhum: quem gerou lá fora foi o harness
+    //      da pessoa, com o crédito dela.
+    //
+    // Com só a URL em mãos, tenta a porta do dono primeiro (é a que aceita a fita
+    // grande do CDN); se o servidor recusar por cargo ou por host, cai pra ponte
+    // sem a pessoa precisar saber que existem duas.
     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, no formato provedor-motor ('freepik-seedance-2.0', 'magnific-minimax-h3', 'faceless-seedance-2.0'). É o que a ficha mostra em 'Motor' e o que explica depois por que a peça não tem custo em Sinapses. Marca sozinha ('magnific') não vale.");
+            throw new Error("action=ingest exige externalEngine: qual motor renderizou, no formato provedor-motor ('kie-kling-3.0', 'fal-krea-2', 'magnific-minimax-h3', 'sogni-minimax-h3'). É o que a ficha mostra em 'Motor' e o que explica depois por que a peça não tem custo em Sinapses. Marca sozinha ('kie', 'magnific') não vale.");
         }
-        const result = await convexAction("externalIngest:mcpIngestExternal", {
-            sessionToken,
-            sourceUrl: args.sourceUrl,
+        const temBytesLocais = Boolean(args.filePath || args.base64?.trim());
+        if (!args.sourceUrl && !temBytesLocais) {
+            throw new Error("action=ingest exige a peça: sourceUrl (o link https do render no motor de fora), filePath (arquivo local, só no MCP instalado) ou base64.");
+        }
+        const ficha = {
             externalEngine: args.externalEngine,
             prompt: args.prompt ?? args.note,
             externalCost: args.externalCost,
@@ -323,10 +457,33 @@ export async function gallery(args) {
             characterIds: normalizeCastIds(args.characterIds).length
                 ? normalizeCastIds(args.characterIds)
                 : undefined,
-        });
+        };
+        if (args.sourceUrl && !temBytesLocais) {
+            try {
+                const result = await convexAction("externalIngest:mcpIngestExternal", {
+                    sessionToken,
+                    sourceUrl: args.sourceUrl,
+                    ...ficha,
+                });
+                return { ...result, aviso: AVISO_INGEST };
+            }
+            catch (e) {
+                // Só as duas recusas que a ponte resolve caem pra ela. O resto (motor
+                // sem nome, personagem errado, tipo recusado) é erro de verdade e sobe.
+                const msg = describeConvexError(e);
+                if (!/restrita ao dono|Host não liberado/i.test(msg))
+                    throw e;
+            }
+        }
+        const result = await ingestPelaPonte(sessionToken, args, ficha);
         return {
             ...result,
-            aviso: "Peça NATIVA: entra na timeline PRIVADA (isPublic false), igual a qualquer geração da casa. Ela NÃO publica sozinha e NÃO vai pra comunidade: publicar é ato separado do dono, por action=publish. 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.",
+            aviso: AVISO_INGEST +
+                (result.adulta
+                    ? result.adultaPor === "declaracao"
+                        ? " Esta nasceu com o carimbo +18 que você declarou (unfiltered): publica e fica no seu perfil e no link, só não vai pra vitrine anônima. Você tira o carimbo na ficha se mudar de ideia."
+                        : " Esta nasceu com o carimbo +18 por CLASSE (provedor de peso aberto ou motor sem freio): publica e fica no seu perfil e no link, só não vai pra vitrine anônima. Esse carimbo só a curadoria tira, igual ao motor sem freio da casa."
+                    : ""),
         };
     }
     // cast: quem está EM CENA numa peça que já existe.

package/dist/tools/image.js

@@ -73,6 +73,39 @@ const MODELS = [
 // assim, listados em action=models e recusados no generate). Hoje vazio: todo
 // motor ativo de imagem entra.
 export const IMAGE_FORA_DE_PROPOSITO = {};
+/**
+ * Motores que NASCEM em 2K quando quem chama não diz o tamanho. Padrão do MCP
+ * desde 20/09/2026, decisão do dono depois do take de aferição.
+ *
+ * Por que só estes dois grupos: na família Krea 2 o 2K é nativo do endpoint
+ * (2720x1536 em 16:9, o dobro do lado do 1K) e a peça de teste segurou fio de
+ * cabelo, poro e trama de tricô sem virar cera. No Gemini o 2K não custa NADA a
+ * mais pro provider (mesma conta de tokens de saída do 1K; o salto de custo só
+ * aparece no 4K), então ali é detalhe de graça.
+ *
+ * Quem fica de fora e por quê, pra ninguém tentar de novo: no gpt-image-2 e nos
+ * 2.5 o size é vestigial, quem decide o tamanho é o aspect ratio
+ * (mapAspectRatioToImageSize no backend, teto de 1536x1024), então não existe 2K
+ * pra pedir ali. O Seedream já entrega 2K nativo sem escada. Grok e MAI aceitam,
+ * mas ficaram de fora por decisão: neles o 2K custa mais pro provider.
+ *
+ * É padrão do MCP, não da casa: o gerador web continua abrindo em 1K, porque lá
+ * quem escolhe vê o preço mudar na tela. O size explícito manda em tudo,
+ * inclusive pra baixo (size="1K" volta ao barato).
+ */
+const DEFAULT_2K_MODELS = new Set([
+    "wavespeed-krea2",
+    "wavespeed-krea2-realism",
+    "wavespeed-krea2-base",
+    "wavespeed-krea2-transparencia",
+    "wavespeed-krea2-broken-tears",
+    "nano-banana-max",
+    "nano-banana-2",
+]);
+/** Tamanho padrão do motor, quando quem chama não passou o size. */
+function defaultSizeFor(model) {
+    return model && DEFAULT_2K_MODELS.has(model) ? "2K" : undefined;
+}
 export const imageSchema = z.object({
     action: z.enum(["generate", "request_generation", "compose", "models"]),
     prompt: z
@@ -90,7 +123,7 @@ export const imageSchema = z.object({
     size: z
         .enum(["1K", "2K", "4K"])
         .optional()
-        .describe("Default '1K'. Resolução acima de 1K SOMA um adder ao preço do modelo, e só nos modelos com hasResolutionAdder (nano-banana-max e nano-banana-2 vão até 4K; grok-2-image e grok-2-image-quality param em 2K, e pedir 4K neles entrega 2K e cobra o adder de 2K). Nos demais modelos o size é ignorado (fica em 1K). O valor VIVO do adder por modelo sai em action=models (campo resolutionAdders, já clampado ao teto do motor): não escreva o número de cabeça, ele muda quando o provider reajusta."),
+        .describe("PADRÃO DO MCP: quem NÃO passa size nasce em 2K no Gemini (nano-banana-max, nano-banana-2) e na família Krea 2 da WaveSpeed, e em 1K no resto. Nesses dois grupos o 2K soma o adder ao preço (+100 hoje), e é decisão da casa pagar por ele: no Gemini o 2K não custa nada a mais pro provider, e na Krea 2 ele dobra o lado da peça (2720x1536 em 16:9) sem perder pele. Passe size='1K' explícito quando o barato importar mais que o detalhe. Resolução acima de 1K só existe nos modelos com hasResolutionAdder (o Gemini vai até 4K; grok-2-image, grok-2-image-quality e a família Krea 2 param em 2K, e pedir 4K neles entrega 2K e cobra o adder de 2K). Nos demais modelos o size é ignorado (fica em 1K): no gpt-image-2 e nos 2.5, por exemplo, quem decide o tamanho é o aspect ratio. O valor VIVO do adder por modelo sai em action=models (campo resolutionAdders, já clampado ao teto do motor): não escreva o número de cabeça, ele muda quando o provider reajusta."),
     styleId: z
         .string()
         .optional()
@@ -112,6 +145,10 @@ export const imageSchema = z.object({
         .enum(["persona", "logo", "none"])
         .optional()
         .describe("Marca na imagem do brand: 'persona' (personagem do brand via character sheets, ex: Helen), 'logo' (carimba a logo no canto), 'none' (só o estilo). Default 'none'. Só aplica se brandSlug setado e o brand oferecer a marca."),
+    skills: z
+        .array(z.string())
+        .optional()
+        .describe("COMO A PEÇA FOI FEITA: os slugs das skills que dirigiram esta geração (ex: ['camarim'], ['dop','escala-gigantismo']). Metadado puro: não muda preço, motor nem resultado, e serve pra ACHAR depois tudo que saiu de uma skill. Passe sempre que a geração estiver saindo de uma skill da casa, na ordem em que elas entraram (quem escreveu o prompt primeiro). Fica no registro da peça e volta em sapiens_gallery."),
     templateSlug: z
         .string()
         .optional()
@@ -259,16 +296,18 @@ export async function image(args) {
     // exigem imageId pré-existente). Pra modelos de imagem (nano-banana-*,
     // gpt-image-2-*), prefira action="generate" que já faz tudo num call.
     if (args.action === "request_generation") {
+        const reqModel = args.model ?? "nano-banana-2";
         return await import("../convexClient.js").then(({ convexMutation }) => convexMutation("mcpExtras:mcpRequestGeneration", {
             sessionToken,
-            model: args.model ?? "nano-banana-2",
+            model: reqModel,
             styleId: args.styleId,
             prompt: args.prompt,
             negativePrompt: args.negativePrompt,
             aspectRatio: args.aspectRatio ?? "16:9",
-            size: args.size ?? "1K",
+            size: args.size ?? defaultSizeFor(reqModel) ?? "1K",
             brandSlug: args.brandSlug,
             brandMark: args.brandMark,
+            skills: args.skills,
         }));
     }
     // Edit/variation usam desktopMcp.generateImageOnline (suporta sourceImageId
@@ -289,14 +328,19 @@ export async function image(args) {
     // (estilo + persona via refs server-side + logo) aplica dentro do
     // generateImageAction, igual ao gerador web. Substitui o antigo branch
     // referenceImageUrls→pipelineMcpImage (que era admin-only).
+    // Com templateSlug e sem model, fica undefined DE PROPÓSITO: quem manda no
+    // motor (e no tamanho) é o default do template.
+    const genModel = args.model ?? (args.templateSlug ? undefined : "nano-banana-2");
     const result = await convexAction("desktopMcp:generateImageOnline", {
         sessionToken,
         prompt: args.prompt,
         aspectRatio: args.aspectRatio,
-        size: args.size,
+        // Sem size explícito, o motor decide (ver DEFAULT_2K_MODELS). Quando nem ele
+        // manda, o campo vai undefined e o backend fica no 1K de sempre.
+        size: args.size ?? defaultSizeFor(genModel),
         // Com templateSlug, deixa o model em branco pro default do template valer
         // (sem template, mantém o default nano-banana-2 da tool).
-        model: args.model ?? (args.templateSlug ? undefined : "nano-banana-2"),
+        model: genModel,
         negativePrompt: args.negativePrompt,
         mode: args.mode ?? "create",
         sourceImageId: args.sourceImageId,
@@ -304,6 +348,7 @@ export async function image(args) {
         referenceImageUrls: args.referenceImageUrls,
         brandSlug: args.brandSlug,
         brandMark: args.brandMark,
+        skills: args.skills,
         templateSlug: args.templateSlug,
         registro: args.registro,
         influencerId: args.influencerId,

package/dist/tools/meta.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { convexQuery, convexMutation, convexAction, getSessionToken, saveSessionToken, clearSessionToken, describeConvexError, } from "../convexClient.js";
+import { convexQuery, convexMutation, convexAction, getSessionToken, saveSessionToken, clearSessionToken, describeConvexError, isRemoteContext, } from "../convexClient.js";
 import { getMcpVersion } from "../version.js";
 import { setTierFromIsAdmin } from "../tier.js";
 /**
@@ -50,6 +50,7 @@ export const metaSchema = z.object({
         "app_url",
         "subscription",
         "version",
+        "pontes",
     ]),
     code: z
         .string()
@@ -135,6 +136,77 @@ const FORMAT_GUIDE = {
 // porque o MCP é pacote separado e não importa o examples.ts do app Next).
 // NÃO menciona slash command (/sapiens:login etc.): isso só existe no Claude
 // Code; Helen/Gemini/Cursor falam só MCP em linguagem natural.
+/**
+ * AS PONTES: onde a pessoa pode gerar com crédito PRÓPRIO, com a ficha do
+ * personagem daqui, e trazer pro acervo por sapiens_gallery action=ingest.
+ *
+ * A chave do provedor NUNCA passa pelo Sapiens. O que este catálogo faz é dizer
+ * ao harness da pessoa o NOME da variável onde a chave costuma morar, pra ele
+ * descobrir sozinho o que ela já tem (`action=pontes` detecta por nome, no
+ * stdio, sem ler o valor) e o que cada balcão roda. O passo a passo vive na
+ * skill 'pontes'; aqui é só o índice.
+ *
+ * Só entra balcão que a casa mediu (motor que rodou de verdade por lá). Preço
+ * não entra: muda toda semana e a skill diz onde conferir.
+ */
+const PONTES = [
+    {
+        key: "kie",
+        nome: "Kie",
+        envVars: ["KIE_API_KEY"],
+        roda: "Kling 3.0, Kling Motion, MiniMax/Hailuo, WAN, Seedance; imagem também",
+        nota: "Um endpoint pra tudo (createTask + recordInfo). A URL do render expira em 24h: ingira no mesmo turno.",
+    },
+    {
+        key: "fal",
+        nome: "fal.ai",
+        envVars: ["FAL_KEY"],
+        roda: "Krea 2, Kling, WAN, Seedance, Flux; Krea 2 sem freio existe lá",
+        nota: "fal.run síncrono ou queue.fal.run. Slug 'fal-' na casa é classe +18 (sai da vitrine anônima, fica no perfil).",
+    },
+    {
+        key: "wavespeed",
+        nome: "WaveSpeed",
+        envVars: ["WAVESPEED_API_KEY"],
+        roda: "Flux.2 Klein, Krea 2 Livre, WAN 2.2, Kling, Shot Mimic",
+        nota: "É o balcão que a casa mais usa por trás do sapiens_video. Slug 'wavespeed-' é classe +18.",
+    },
+    {
+        key: "sogni",
+        nome: "Sogni",
+        envVars: ["SOGNI_API_KEY"],
+        roda: "MiniMax H3 inteira, WAN 2.2 (com animate), LTX 2.3 e 2.5, Krea 2 Turbo, Identity Edit",
+        nota: "Assinatura Unlimited cobre o catálogo aberto (custo marginal zero). Um socket por conta: um job por vez.",
+    },
+    {
+        key: "magnific",
+        nome: "Magnific / Freepik",
+        envVars: [],
+        roda: "Seedance 2.0 e 2.5 (até 30s e 1080p), MiniMax H3, upscale, relight",
+        nota: "Sem chave: é o conector MCP da Magnific na sessão da pessoa. A URL assinada do render expira no mesmo dia.",
+    },
+    {
+        key: "krea",
+        nome: "Krea API",
+        envVars: ["KREA_API_KEY"],
+        roda: "Krea 2 Turbo/Medium/Large, MiniMax H3 Max Turbo, Seedream, Veo, Seedance",
+        nota: "Filtra NSFW; job que falha não cobra. Saldo pré-pago separado do app.",
+    },
+    {
+        key: "replicate",
+        nome: "Replicate",
+        envVars: ["REPLICATE_API_TOKEN"],
+        roda: "catálogo aberto (Flux, WAN, LTX e o que a comunidade sobe)",
+        nota: "A casa não mediu motor por lá; o contrato de ingest é o mesmo.",
+    },
+    {
+        key: "bancada",
+        nome: "A própria máquina (ComfyUI, SD local)",
+        envVars: [],
+        roda: "o que a placa aguenta: LTX, Klein, Krea 2 com LoRA, H3 destilado",
+        nota: "Custo zero em dinheiro, pago em tempo. Entra por filePath, slug 'bancada-<motor>'.",
+    },
+];
 const FIRST_POWERS = [
     {
         icon: "📚",
@@ -319,7 +391,7 @@ export async function meta(args) {
             balance,
             ...(lowBalance
                 ? {
-                    balanceWarning: "Saldo abaixo de 500 Sinapses: o que é grátis roda tranquilo, mas pra imagem/música/vídeo talvez precise recarregar.",
+                    balanceWarning: "Saldo abaixo de 500 Sinapses: o que é grátis roda tranquilo, mas pra imagem/música/vídeo talvez precise recarregar. Outra saída é a ponte: se a pessoa tem crédito na Kie, na fal, na Magnific ou na Sogni, gera lá com a ficha do personagem daqui e traz a peça pro acervo por sapiens_gallery action=ingest (skill 'pontes'; sapiens_meta action=pontes diz o que ela já tem configurado).",
                 }
                 : {}),
             firstPowers: FIRST_POWERS,
@@ -471,6 +543,38 @@ export async function meta(args) {
                     : "Nenhuma sessão local encontrada.",
         };
     }
+    // pontes: o que a pessoa já tem de crédito FORA da casa, e como cada balcão
+    // entra. Não exige login e não fala com o backend: é leitura do catálogo
+    // acima mais uma olhada nos NOMES das variáveis do ambiente do MCP instalado
+    // (o valor nunca é lido nem devolvido; no remoto o processo é o servidor do
+    // site, então lá não se olha nada e a resposta manda perguntar).
+    if (args.action === "pontes") {
+        const remoto = isRemoteContext();
+        const detectadas = remoto
+            ? []
+            : PONTES.filter((p) => p.envVars.some((nome) => {
+                const valor = process.env[nome];
+                return typeof valor === "string" && valor.trim().length >= 8;
+            })).map((p) => p.key);
+        return {
+            regra: "A chave de provedor NUNCA passa pelo Sapiens: quem chama o motor é o seu harness, na sua máquina, com o seu crédito. A casa entra com a ficha do personagem (sapiens_character action=get: passportPrompt + imageUrls) e recebe a peça de volta por sapiens_gallery action=ingest, que grava motor, prompt verbatim, custo real e personagem. Passo a passo: sapiens_skill action=get name=pontes.",
+            detectadas,
+            detectadasNota: remoto
+                ? "No MCP remoto não dá pra olhar o ambiente da pessoa: pergunte a ela onde tem crédito (Kie, fal, Magnific, Sogni, Krea...) ou olhe os conectores que já estão nesta conversa."
+                : detectadas.length
+                    ? `Achei chave configurada (pelo NOME da variável, sem ler o valor) pra: ${detectadas.join(", ")}. Proponha gerar por aí antes de gastar Sinapse.`
+                    : "Nenhuma variável de provedor no ambiente deste MCP. Pergunte onde a pessoa tem crédito, ou olhe os conectores já ligados nesta conversa (Magnific, Krea, Sogni).",
+            pontes: PONTES.map((p) => ({
+                key: p.key,
+                nome: p.nome,
+                roda: p.roda,
+                envVars: p.envVars,
+                nota: p.nota,
+                ingestSlug: `${p.key}-<motor>`,
+            })),
+            voltaPraCasa: "sapiens_gallery action=ingest com externalEngine='<provedor>-<motor>', prompt VERBATIM, externalCost na moeda de lá, characterId e referenceImageIds. filePath (arquivo local, só no MCP instalado) ou sourceUrl (o render, que expira: ingira no mesmo turno). unfiltered=true quando o motor rodou sem filtro. Tetos: 12 MB imagem, 60 MB vídeo, 40 peças por dia.",
+        };
+    }
     const sessionToken = getSessionToken();
     if (args.action === "whoami") {
         // mcpGetMySubscription usa requireMcpUser (qualquer logado), então whoami

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.69.2",
+  "version": "1.71.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",

package/dist/tools/referencia.js

@@ -1,114 +0,0 @@
-import { z } from "zod";
-import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
-/**
- * sapiens_referencia — o acervo de publicidade da casa, pela porta do agente.
- *
- * Existe pra resolver um gargalo de curadoria, não pra expor mais um catálogo:
- * achar um comercial bom e precisar de terminal pra guardar significa que o
- * acervo só cresce quando o dono está na máquina. Aqui ele guarda de onde
- * estiver, com o link e uma frase.
- *
- * O acervo tem duas trilhas e as duas ensinam coisas opostas: `referencia` é
- * campanha premiada (o teto do ofício) e `replicavel` é anúncio veiculando
- * agora (o degrau). O membro vê tudo em /dashboard/acervo?tab=referencias.
- *
- * ADMIN-ONLY de ponta a ponta: o Convex recusa quem não é dono em toda action,
- * e a tool some do tools/list de membro. A curadoria é o valor deste acervo, e
- * acervo que qualquer agente alimenta vira lista.
- *
- * O que esta tool NÃO faz: guardar peça de biblioteca de anúncio (Meta,
- * TikTok). Aquelas servem por URL assinada que expira, então o vídeo precisa
- * ser espelhado no CDN da casa antes de virar ficha, e isso é trabalho do
- * script `apps/sapiens/scripts/ingest-ad-references.mjs`, com ffmpeg e
- * browser. Link do YouTube e do Vimeo, que têm embed oficial, entram aqui.
- */
-export const referenciaSchema = z.object({
-    action: z.enum(["list", "save", "note"]),
-    url: z
-        .string()
-        .optional()
-        .describe("Pra save: link do YouTube ou do Vimeo. Só essas duas, porque têm embed " +
-        "oficial que não expira. Peça de Meta Ad Library ou TikTok entra pelo " +
-        "script de ingestão da casa, não por aqui."),
-    titulo: z.string().optional().describe("Pra save: o nome da campanha."),
-    marca: z.string().optional().describe("Pra save: quem anuncia. Resolve o setor sozinho quando o setor não vem."),
-    trilha: z
-        .enum(["referencia", "replicavel"])
-        .optional()
-        .describe("Pra save: 'referencia' (campanha premiada, o teto do ofício) ou " +
-        "'replicavel' (anúncio veiculando agora). Default: referencia."),
-    setor: z
-        .string()
-        .optional()
-        .describe("Pra save/list: o setor do catálogo (Alimentação e bebida, IA e software, " +
-        "Moda e beleza...). Em save, sem isto o servidor deduz pela marca."),
-    ano: z.number().optional().describe("Pra save: ano da campanha."),
-    leitura: z
-        .string()
-        .optional()
-        .describe("Pra save/note: a leitura editorial. O que a peça faz que dá pra roubar, " +
-        "onde está o gancho, por que ela segura. É o que o acervo tem e uma " +
-        "busca no YouTube não tem."),
-    fonte: z
-        .enum(["youtube", "vimeo", "tiktok-library", "tiktok-creative-center", "meta-ad-library"])
-        .optional()
-        .describe("Pra note: a fonte da peça já guardada (vem do list)."),
-    externalId: z.string().optional().describe("Pra note: o id da peça na fonte (vem do list)."),
-    limite: z.number().optional().describe("Pra list: teto de fichas (default 60, máx 200)."),
-});
-export async function referencia(args) {
-    const sessionToken = getSessionToken();
-    if (args.action === "list") {
-        const fichas = await convexQuery("adReferences:mcpListar", {
-            sessionToken,
-            ...(args.trilha ? { trilha: args.trilha } : {}),
-            ...(args.setor ? { setor: args.setor } : {}),
-            ...(args.limite ? { limite: args.limite } : {}),
-        });
-        const n = Array.isArray(fichas) ? fichas.length : 0;
-        const semLeitura = Array.isArray(fichas) ? fichas.filter((f) => !f.temLeitura).length : 0;
-        return {
-            count: n,
-            fichas,
-            note: n === 0
-                ? "Nada nesse recorte ainda."
-                : `${semLeitura} sem leitura escrita. A leitura é o que o acervo tem e uma busca no YouTube não tem: action=note fonte=<f> externalId=<id> leitura="...".`,
-        };
-    }
-    if (args.action === "save") {
-        if (!args.url)
-            throw new Error("sapiens_referencia save: exige url.");
-        if (!args.titulo)
-            throw new Error("sapiens_referencia save: exige titulo.");
-        const r = await convexMutation("adReferences:mcpGuardar", {
-            sessionToken,
-            url: args.url,
-            titulo: args.titulo,
-            ...(args.marca ? { marca: args.marca } : {}),
-            ...(args.trilha ? { trilha: args.trilha } : {}),
-            ...(args.setor ? { setor: args.setor } : {}),
-            ...(args.ano ? { ano: args.ano } : {}),
-            ...(args.leitura ? { leitura: args.leitura } : {}),
-        });
-        return {
-            ...r,
-            note: r?.novo
-                ? "Guardada. Aparece pro membro em /dashboard/acervo?tab=referencias."
-                : "Já estava no acervo; a ficha foi atualizada em vez de duplicar.",
-        };
-    }
-    if (args.action === "note") {
-        if (!args.fonte || !args.externalId) {
-            throw new Error("sapiens_referencia note: exige fonte e externalId (vêm do list).");
-        }
-        if (!args.leitura)
-            throw new Error("sapiens_referencia note: exige leitura.");
-        return await convexMutation("adReferences:mcpAnotar", {
-            sessionToken,
-            fonte: args.fonte,
-            externalId: args.externalId,
-            leitura: args.leitura,
-        });
-    }
-    throw new Error(`sapiens_referencia: action desconhecida "${args.action}".`);
-}

package/dist/tools/shorts.js

@@ -1,81 +0,0 @@
-import { z } from "zod";
-import { convexAction, getSessionToken } from "../convexClient.js";
-/**
- * Sapiens Shorts — vídeo vertical 9:16 via VEO (v1.5).
- *
- * Sub-action:
- *   - render: dispara render com brief structured + imageId persona pré-existente.
- *
- * Pré-requisitos pro caller:
- *   1. Gerar imagem persona via sapiens_image (ou escolher do gallery via sapiens_gallery)
- *   2. Ter créditos suficientes (custo varia por modelo)
- *   3. Brief montado segundo schema (product/hook/shots/vibe)
- *
- * Estilos:
- *   - ugc: real-life talking-head (mais comum)
- *   - unboxing: close em produto físico
- *   - app-demo: persona + tela
- *   - reflexao: atmosfera mais lenta, contemplativa
- *
- * Retorna `{ success:true, imageId, status:'rendering', url:null }` (ASSÍNCRONO):
- * o render VEO roda fora da chamada. Acompanhe com sapiens_video action=status
- * imageId=<id> até status='completed' (traz a url VEO, expiração curta, baixe
- * logo) ou 'error'/'blocked'.
- */
-export const shortsSchema = z.object({
-    action: z.enum(["render"]),
-    imageId: z.string().describe("generatedImages:_id da persona base. Use sapiens_gallery action=list pra descobrir."),
-    styleId: z.enum(["ugc", "unboxing", "app-demo", "reflexao"]),
-    brief: z.object({
-        product: z.object({
-            name: z.string(),
-            type: z.enum(["app", "physical", "saas"]),
-            uvps: z.array(z.string()).describe("Unique Value Propositions, 2-4 bullets curtos"),
-            persona: z.string().describe("Descrição da persona-protagonista (idade/contexto/estilo)"),
-        }),
-        hook: z.object({
-            line: z.string().describe("Frase de abertura punchy, 5-10 palavras"),
-            emotion: z.string().describe("Emoção alvo (ex: 'curiosity', 'frustration', 'awe')"),
-        }),
-        shots: z
-            .array(z.object({
-            sec: z.number().describe("Duração em segundos (cap 8 por shot)"),
-            role: z.enum(["hook", "problem", "solution", "cta"]),
-            camera: z.enum(["close-up", "medium", "over-shoulder", "product-pov"]),
-            action: z.string().describe("Ação visual descrita em 1 frase"),
-            emotion: z.string(),
-            voiceLine: z.string().optional().describe("Linha falada na cena (PT-BR)"),
-            propVisible: z.string().optional(),
-        }))
-            .min(2)
-            .max(6)
-            .describe("2-6 shots. Total 15-60s. Geralmente: hook → problem → solution → cta."),
-        vibe: z.object({
-            energy: z.enum(["calm", "high"]).describe("Energia geral do edit"),
-            language: z.enum(["pt-BR", "en"]).optional().describe("Default 'pt-BR'"),
-        }),
-    }),
-    references: z
-        .array(z.object({
-        mimeType: z.string(),
-        data: z.string(),
-        role: z.string().optional(),
-    }))
-        .optional()
-        .describe("References opcionais (start/end frames) em base64. Se omitido, persona é o start frame default."),
-});
-export async function shorts(args) {
-    if (args.action === "render") {
-        const sessionToken = getSessionToken();
-        if (args.brief.shots.length === 0) {
-            throw new Error("brief.shots vazio — passe 2-6 shots descrevendo a sequência.");
-        }
-        return await convexAction("mcpExtrasActions:mcpShortsRender", {
-            sessionToken,
-            imageId: args.imageId,
-            styleId: args.styleId,
-            brief: args.brief,
-            references: args.references,
-        });
-    }
-}