sapiens-mcp 1.35.0 → 1.37.0

package/dist/convexClient.js

@@ -167,6 +167,18 @@ const requestTokenContext = new AsyncLocalStorage();
 export function runWithSessionToken(token, fn) {
     return requestTokenContext.run(token, fn);
 }
+/**
+ * True quando a chamada corre dentro do transporte REMOTO (streamable HTTP):
+ * cada request remota roda embrulhada em runWithSessionToken, então o
+ * AsyncLocalStorage tem valor. No stdio (processo local, na máquina do dono do
+ * token) o contexto NUNCA é setado. É o sinal confiável pra recusar operações
+ * que tocam o disco do HOST (ex: ler um arquivo local pra usar como frame de
+ * vídeo): no servidor multi-tenant da Vercel, um caminho arbitrário seria
+ * leitura de arquivo do próprio servidor, nunca do PC do usuário.
+ */
+export function isRemoteContext() {
+    return requestTokenContext.getStore() !== undefined;
+}
 export function getSessionToken() {
     // Prioridade -1: token da REQUEST (transporte remoto, ver acima). Vence tudo:
     // identidade no remoto é sempre do bearer, nunca do estado do host.

package/dist/index.js

@@ -6,6 +6,33 @@ import { MCP_VERSION } from "./version.js";
 import { buildToolList, callTool, SAPIENS_INSTRUCTIONS, TOOLS, } from "./registry.js";
 import { getCachedTier, onTierVisibilityChange, probeTierInBackground, } from "./tier.js";
 import { getPrompt, listPrompts } from "./prompts.js";
+import { convexMutation, getSessionToken } from "./convexClient.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
+// mcpUsage, que só via o remoto. Loga o MESMO shape que o remote.ts, com
+// transport:"stdio". Identidade do login local (getSessionToken), nunca args
+// (só tool/action/ok/ms). Opt-out por SAPIENS_MCP_NO_TELEMETRY=1.
+function logStdioUsage(fields) {
+    try {
+        if (process.env.SAPIENS_MCP_NO_TELEMETRY === "1")
+            return;
+        const token = getSessionToken();
+        if (!token)
+            return; // sem login não há identidade pra vincular
+        convexMutation("mcpUsage:logCall", {
+            sessionToken: token,
+            tool: fields.tool,
+            action: fields.action ?? undefined,
+            ok: fields.ok,
+            ms: Math.round(fields.ms),
+            transport: "stdio",
+        }).catch(() => { });
+    }
+    catch {
+        // telemetria nunca vira erro pro cliente
+    }
+}
 // Transporte STDIO (o pacote npm/npx que os clients locais rodam). O catálogo,
 // as instructions e o dispatch vivem no registry.ts, compartilhados com o
 // transporte remoto (remote.ts). Aqui fica só o que é do stdio: o tier vem do
@@ -24,7 +51,19 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => ({
 server.setRequestHandler(GetPromptRequestSchema, async (req) => {
     return getPrompt(req.params.name, (req.params.arguments ?? {}));
 });
-server.setRequestHandler(CallToolRequestSchema, async (req) => callTool(req.params.name, req.params.arguments));
+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);
+    logStdioUsage({
+        tool: name,
+        action: typeof args.action === "string" ? args.action : null,
+        ok: !result.isError,
+        ms: Date.now() - t0,
+    });
+    return result;
+});
 // Tier mudou de um jeito que altera a lista visível (login/logout/probe):
 // avisa o client pra re-listar. Best-effort: client que não suporta ignora.
 onTierVisibilityChange(() => {

package/dist/registry.js

@@ -38,7 +38,7 @@ import { describeConvexError } from "./convexClient.js";
  */
 export const TOOLS = {
     sapiens_pipeline: {
-        description: "CRUD do content pipeline Sapiens (sources/productions/publishables). Sub-actions: list_sources, list_articles (use includeDrafts pra incluir drafts; onlyAvailable pra esconder os já virados em source), get_source, get_production, list_versions, add_article_as_source, create_draft_article_and_source (seed), create_production (sourceId+format → productionId draft), update_production (substitui payload, opcionalmente muda status), finalize_production (cria publishable v1, v2... com snapshot), remove_production, remove_source, set_source_done, update_source_notes, restore_version (volta payload duma versão antiga), set_publishable_title (renomeia um publishable), backfill_via (rotula em lote o campo 'via' das productions antigas; dryRun=true só lista), propose_mega_grafico_plan (granular: só gera plano via Gemini, devolve fullPrompt+spec), run_mega_grafico_full (ONE-SHOT, recomendado: cria production+propõe plano+gera imagem+aplica selo Sapiens+finaliza publishable numa chamada só), generate_carousel (gera um carrossel editorial standalone a partir de brief OU articleId — 7-9 slides na voz Sapiens + imagens do banco; devolve id + url do editor pro humano abrir, ajustar e exportar; admin-only, cobra Sinapses, reembolsa se falhar). CARROSSEL FINO (edição sem tela, admin-only): list_carousels (seus carrosséis standalone), get_carousel (payload completo + catálogo de templates com slots/limites + paletas — tudo pra VOCÊ escrever os slides), update_carousel (payload inteiro de volta, sanitizado no servidor; preserve os campos image dos slides que não mexeu), carousel_auto_images (IA escolhe imagens do banco pros slides de foto, 60 Sinapses; makeVisual=true converte slides de texto pra layouts de foto antes — ritmo visual; generateMissing=true gera imagem nova pros que o banco não cobrir, ~450 Sinapses cada, até 4, avise o custo antes), carousel_generate_image (imagem nova pra UM slide, ~450 Sinapses, customPrompt opcional). Fluxo confortável: generate_carousel → get_carousel → update_carousel (afia os textos) → carousel_auto_images → humano abre a url pra exportar. Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente (menos drift). Idempotente só na production (passa productionId pra reusar a MESMA row), mas cada run RE-GERA a imagem e cobra de novo (~900 Sinapses): não é grátis re-rodar. OBRIGATÓRIO perguntar ao user antes se withHelen=true (cartoon Helen interage com tema, ~15-25% do poster) ou false (poster 100% diagramático). Custo ~900-1000 sinapses por geração. run_mega_grafico_full, generate_carousel, carousel_auto_images (com generateMissing) e carousel_generate_image são SÍNCRONAS e pesadas: vale a REGRA DO TIMEOUT (podem cobrar mesmo voltando 'Timeout'; cheque get_carousel/dashboard antes de repetir). Use skipFinalize=true se quiser deixar production em 'ready' pro admin revisar antes de publishable. Payload livre por formato — chame sapiens_meta action=formats pra ver schemas sugeridos.",
+        description: "CRUD do content pipeline Sapiens (sources/productions/publishables). Sub-actions: list_sources, list_articles (use includeDrafts pra incluir drafts; onlyAvailable pra esconder os já virados em source), get_source, get_production, list_versions, add_article_as_source, create_draft_article_and_source (seed), create_production (sourceId+format → productionId draft), update_production (substitui payload, opcionalmente muda status), finalize_production (cria publishable v1, v2... com snapshot), remove_production, remove_source, set_source_done, update_source_notes, restore_version (volta payload duma versão antiga), set_publishable_title (renomeia um publishable), backfill_via (rotula em lote o campo 'via' das productions antigas; dryRun=true só lista), propose_mega_grafico_plan (granular: só gera plano via Gemini, devolve fullPrompt+spec), run_mega_grafico_full (ONE-SHOT, recomendado: cria production+propõe plano+gera imagem+aplica selo Sapiens+finaliza publishable numa chamada só), generate_carousel (gera um carrossel editorial standalone a partir de brief OU articleId — 7-9 slides na voz Sapiens + imagens do banco; devolve id + url do editor pro humano abrir, ajustar e exportar; admin-only, cobra Sinapses, reembolsa se falhar). generate_carousel_production (o IRMÃO PIPELINE do generate_carousel: recebe um sourceId de artigo, CRIA a production carrossel_ig e a preenche pelo MESMO motor da casa, já no shape editorial (templateId+slots) que o editor de pipeline renderiza — prefira ESTE a create_production+payload cru pro carrossel, que abre VAZIO no editor; devolve productionId + url do editor de pipeline; admin-only, cobra Sinapses, reembolsa se falhar). CARROSSEL FINO (edição sem tela, admin-only): list_carousels (seus carrosséis standalone), get_carousel (payload completo + catálogo de templates com slots/limites + paletas — tudo pra VOCÊ escrever os slides), update_carousel (payload inteiro de volta, sanitizado no servidor; preserve os campos image dos slides que não mexeu), carousel_auto_images (IA escolhe imagens do banco pros slides de foto, 60 Sinapses; makeVisual=true converte slides de texto pra layouts de foto antes — ritmo visual; generateMissing=true gera imagem nova pros que o banco não cobrir, ~450 Sinapses cada, até 4, avise o custo antes), carousel_generate_image (imagem nova pra UM slide, ~450 Sinapses, customPrompt opcional). Fluxo confortável (standalone): generate_carousel → get_carousel → update_carousel (afia os textos) → carousel_auto_images → humano abre a url pra exportar. Fluxo pipeline (carrossel atrelado a um artigo/source): generate_carousel_production (sourceId) → humano abre a url do editor de pipeline pra revisar e finalizar (finalize_production). Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente (menos drift). Idempotente só na production (passa productionId pra reusar a MESMA row), mas cada run RE-GERA a imagem e cobra de novo (~900 Sinapses): não é grátis re-rodar. OBRIGATÓRIO perguntar ao user antes se withHelen=true (cartoon Helen interage com tema, ~15-25% do poster) ou false (poster 100% diagramático). Custo ~900-1000 sinapses por geração. run_mega_grafico_full, generate_carousel, generate_carousel_production, carousel_auto_images (com generateMissing) e carousel_generate_image são SÍNCRONAS e pesadas: vale a REGRA DO TIMEOUT (podem cobrar mesmo voltando 'Timeout'; cheque get_carousel/dashboard antes de repetir). Use skipFinalize=true se quiser deixar production em 'ready' pro admin revisar antes de publishable. Payload livre por formato — chame sapiens_meta action=formats pra ver schemas sugeridos.",
         schema: pipelineSchema,
         handler: pipeline,
     },
@@ -53,7 +53,7 @@ export const TOOLS = {
         handler: meta,
     },
     sapiens_repertorio: {
-        description: "Acervo pessoal de filme/série/anime/jogo/livro/música (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), lists (listas curadas), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT travada na lista de providers: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), (1) infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped) e rating se citado; (2) chame action=resolve {mediaType, query}, escolha o candidato certo e faça add_item passando SÓ o source + externalId DELE + os campos pessoais (status/rating/tags/note). O servidor re-resolve no provider e grava título/capa/ano canônicos — você NÃO manda título/capa nem inventa externalId. (3) Se o resolve não achar (lista vazia/providerKeyMissing), NÃO dá pra adicionar: diga ao user que não encontrou nos providers (não fabrique entry manual). Upsert/dedup por (userId, source, externalId). Só pergunte se ambíguo entre candidatos. FERRAMENTAS DE IA (Repertório de Ferramentas): fluxo separado (vêm do catálogo aitag, não dos providers de mídia). action=search_tools {query} acha a ferramenta no catálogo e devolve o toolId; action=add_tool {toolId, favorite?, rating?, note?} grava como mediaType 'tool' (estar no acervo já é 'usei'; favorite=true liga a estrela). Use quando o user fala 'adiciona o Midjourney/Cursor no meu repertório de ferramentas' ou 'uso tal ferramenta de IA'. Cada ferramenta aponta pra página dela no aitag.",
+        description: "Acervo pessoal de filme/série/anime/jogo/livro/música (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT travada na lista de providers: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), (1) infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped) e rating se citado; (2) chame action=resolve {mediaType, query}, escolha o candidato certo e faça add_item passando SÓ o source + externalId DELE + os campos pessoais (status/rating/tags/note). O servidor re-resolve no provider e grava título/capa/ano canônicos — você NÃO manda título/capa nem inventa externalId. (3) Se o resolve não achar (lista vazia/providerKeyMissing), NÃO dá pra adicionar: diga ao user que não encontrou nos providers (não fabrique entry manual). Upsert/dedup por (userId, source, externalId). Só pergunte se ambíguo entre candidatos. FERRAMENTAS DE IA (Repertório de Ferramentas): fluxo separado (vêm do catálogo aitag, não dos providers de mídia). action=search_tools {query} acha a ferramenta no catálogo e devolve o toolId; action=add_tool {toolId, favorite?, rating?, note?} grava como mediaType 'tool' (estar no acervo já é 'usei'; favorite=true liga a estrela). Use quando o user fala 'adiciona o Midjourney/Cursor no meu repertório de ferramentas' ou 'uso tal ferramenta de IA'. Cada ferramenta aponta pra página dela no aitag.",
         schema: repertorioSchema,
         handler: repertorio,
     },
@@ -113,7 +113,7 @@ export const TOOLS = {
         handler: shorts,
     },
     sapiens_video: {
-        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. 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): a mesa 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 a sombra/depth-map de um vídeo pro Acervo como driving reutilizável; 'shadows-list' lista as sombras prontas. Sub-action 'models' (sem custo, sem login): lista os modelos de vídeo ativos + preço-piso + config (durações/resoluções) + disponibilidade (Omni depende de env).",
+        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. FRAME POR ARQUIVO LOCAL (só no MCP instalado/stdio, não no remoto): startImagePath/endImagePath = caminho absoluto de uma imagem no seu PC (PNG/JPEG/WebP até 8MB); o processo lê o arquivo e sobe como frame inicial/final, igual a subir no gerador do site — 1 imagem inicial + 1 final por vídeo, então pra vários vídeos rode create uma vez por imagem. No remoto use id/url. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}. VITRINE (sem custo): sub-action 'demos' lista os SEUS demo films (kind=demo do Estúdio de Vídeo) com slug + estado de vitrine; sub-action 'showcase' põe/tira um demo (por slug) do mini-cinema da /conectar-claude, com showcaseTag (chip de capacidade) e showcaseOrder (ordem asc). Fluxo: 'demos' pra achar o slug, depois 'showcase' com showcase=true. Só entra na vitrine pública se for a conta da casa. VÍDEOS PROGRAMÁTICOS (ADMIN, sem custo): a mesa 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 a sombra/depth-map de um vídeo pro Acervo como driving reutilizável; 'shadows-list' lista as sombras prontas. 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).",
         schema: videoSchema,
         handler: video,
     },
@@ -133,12 +133,12 @@ export const TOOLS = {
         handler: brand,
     },
     sapiens_character: {
-        description: "Personagens (character sheets) do Sapiens — a tabela `influencers`: personagem reutilizável com imagens (pra character-lock em geração) + alma (systemPrompt), tudo amarrado à conta do dono do token (sem admin). Sub-actions: list_public (catálogo global de personagens públicos do Explorar; cada um traz mainImageUrl/imageUrls usáveis direto como referenceImageUrls em sapiens_image; sem custo, sem login), get (detalhe de 1 por characterId — público+ativo qualquer um vê, draft/privado só o dono; systemPrompt só volta pro dono), list_mine (os personagens do próprio user, inclui drafts/privados), create (cria rascunho na conta: name + gender + opcional title/systemPrompt), add_image (adiciona imagem ao próprio personagem via imageUrl público OU sourceImageId da galeria; 1ª vira principal), set_card (edita alma/título/nome do próprio), activate (publica, sai de draft, exige ≥1 imagem), set_visibility (isPublic true=Explorar+slug / false=privado). Fluxo de criação: create → add_image (1+) → set_card (opcional) → activate → set_visibility isPublic=true. Pra usar um personagem público como referência numa geração, pegue mainImageUrl em list_public/get e passe em sapiens_image referenceImageUrls.",
+        description: "Personagens (character sheets) do Sapiens — a tabela `influencers`: personagem reutilizável com imagens (pra character-lock em geração) + alma (systemPrompt), tudo amarrado à conta do dono do token (sem admin). Sub-actions: list_public (catálogo global de personagens públicos do Explorar; cada um traz mainImageUrl/imageUrls usáveis direto como referenceImageUrls em sapiens_image; sem custo, sem login), get (detalhe de 1 por characterId — público+ativo qualquer um vê, draft/privado só o dono; systemPrompt só volta pro dono), list_mine (os personagens do próprio user, inclui drafts/privados), create (cria rascunho na conta: name + gender + opcional title/systemPrompt), add_image (adiciona imagem ao próprio personagem via imageUrl público OU sourceImageId da galeria; 1ª vira principal), set_card (edita alma/título/nome do próprio), activate (publica, sai de draft, exige ≥1 imagem), set_visibility (isPublic true=Explorar+slug / false=privado). GESTÃO de imagem (por url, pegue as urls atuais em action=get campo imageUrls): remove_image (tira uma), set_main_image (define a principal), reorder_images (nova ordem via orderedUrls, posição 0=principal), e delete (apaga o personagem, permanente). Fluxo de criação: create → add_image (1+) → set_card (opcional) → activate → set_visibility isPublic=true. Pra usar um personagem público como referência numa geração, pegue mainImageUrl em list_public/get e passe em sapiens_image referenceImageUrls.",
         schema: characterSchema,
         handler: character,
     },
     sapiens_profile: {
-        description: "O 'tudo junto' do perfil do user (/u/<username>), leitura user-tier. Agrega o que mora no perfil mas estava fora do MCP: identidade + nível/XP + saldo, badges (conquistas) e golden tools (favoritos do aitag). Sub-actions: get (card completo: identidade + nível + saldo + badges + golden tools), badges (só as conquistas, lista cheia), golden_tools (só os favoritos do aitag, lista cheia), notifications (suas notificações recentes do sino + contagem de não-lidas), mark_read (marca uma notificationId ou TODAS as não-lidas como lidas). As partes grandes do perfil NÃO são duplicadas aqui, têm tool própria: imagens geradas/publicadas=sapiens_gallery, repertório (filmes/séries/jogos/livros/música)=sapiens_repertorio, personagens=sapiens_character, persona/arquétipo MBTI=sapiens_persona action=my_profile, saldo detalhado por bucket=sapiens_meta action=subscription. Monta a partir de queries já em prod (sem custo).",
+        description: "O 'tudo junto' do perfil do user (/u/<username>), user-tier. Agrega o que mora no perfil mas estava fora do MCP: identidade + nível/XP + saldo, badges (conquistas) e golden tools (favoritos do aitag). Sub-actions de LEITURA: get (card completo: identidade + nível + saldo + badges + golden tools), badges (só as conquistas, lista cheia), golden_tools (só os favoritos do aitag, lista cheia), notifications (suas notificações recentes do sino + contagem de não-lidas), mark_read (marca uma notificationId ou TODAS as não-lidas como lidas). Sub-actions de ESCRITA (mexem na SUA conta; identidade sempre da sessão): follow/unfollow (seguir/deixar de seguir outro user por followingId=users:_id, descoberto via sapiens_community participants/search_users), update_bio (edita a sua bio), update_username (troca o seu @; inválido/tomado volta {success:false,error}). As partes grandes do perfil NÃO são duplicadas aqui, têm tool própria: imagens geradas/publicadas=sapiens_gallery, repertório (filmes/séries/jogos/livros/música)=sapiens_repertorio, personagens=sapiens_character, persona/arquétipo MBTI=sapiens_persona action=my_profile, saldo detalhado por bucket=sapiens_meta action=subscription. Monta a partir de queries já em prod (sem custo).",
         schema: profileSchema,
         handler: profile,
     },

package/dist/tools/character.js

@@ -21,6 +21,10 @@ import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js
  *   - set_card:     edita a alma (systemPrompt), título e/ou nome do próprio.
  *   - activate:     publica (sai de draft). Exige ≥1 imagem.
  *   - set_visibility: público (entra no Explorar, ganha slug) ou privado.
+ *   - remove_image: tira UMA imagem do próprio personagem (por url).
+ *   - set_main_image: define a principal (por url, entre as que já existem).
+ *   - reorder_images: reordena as imagens (posição 0 = principal).
+ *   - delete:       apaga o próprio personagem (permanente).
  *
  * Fluxo típico de criação: create → add_image (1+) → set_card (opcional) →
  * activate → set_visibility isPublic=true.
@@ -35,6 +39,10 @@ export const characterSchema = z.object({
         "set_card",
         "activate",
         "set_visibility",
+        "remove_image",
+        "set_main_image",
+        "reorder_images",
+        "delete",
     ]),
     characterId: z
         .string()
@@ -63,7 +71,11 @@ export const characterSchema = z.object({
         .describe("Pra create/set_card: a 'alma' do personagem (personalidade, jeito de falar, contexto). Usado no chat e como guia de geração."),
     imageUrl: httpUrl()
         .optional()
-        .describe("Pra add_image: URL pública da imagem (Bunny CDN / Convex storage). Use a `url` que sapiens_image/sapiens_gallery devolvem."),
+        .describe("Pra add_image: URL pública da imagem (Bunny CDN / Convex storage). Use a `url` que sapiens_image/sapiens_gallery devolvem. Pra remove_image/set_main_image: a url da imagem JÁ no personagem (pegue via action=get, campo imageUrls)."),
+    orderedUrls: z
+        .array(z.string())
+        .optional()
+        .describe("Pra reorder_images: as urls das imagens do personagem na nova ordem (posição 0 = principal). url ausente vai pro fim, nenhuma se perde. Pegue as urls atuais via action=get."),
     sourceImageId: z
         .string()
         .optional()
@@ -188,4 +200,54 @@ export async function character(args) {
             isPublic: args.isPublic,
         });
     }
+    // -------- remove_image: tira UMA imagem (por url) --------
+    if (args.action === "remove_image") {
+        if (!args.characterId)
+            throw new Error("action=remove_image exige characterId.");
+        if (!args.imageUrl)
+            throw new Error("action=remove_image exige imageUrl (a url da imagem no personagem; veja em action=get).");
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpRemoveCharacterImage", {
+            sessionToken,
+            characterId: args.characterId,
+            imageUrl: args.imageUrl,
+        });
+    }
+    // -------- set_main_image: define a principal (por url) --------
+    if (args.action === "set_main_image") {
+        if (!args.characterId)
+            throw new Error("action=set_main_image exige characterId.");
+        if (!args.imageUrl)
+            throw new Error("action=set_main_image exige imageUrl (uma das imagens já no personagem; veja em action=get).");
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpSetCharacterMainImage", {
+            sessionToken,
+            characterId: args.characterId,
+            imageUrl: args.imageUrl,
+        });
+    }
+    // -------- reorder_images: nova ordem (posição 0 = principal) --------
+    if (args.action === "reorder_images") {
+        if (!args.characterId)
+            throw new Error("action=reorder_images exige characterId.");
+        if (!args.orderedUrls || args.orderedUrls.length === 0) {
+            throw new Error("action=reorder_images exige orderedUrls (as urls na nova ordem; veja em action=get).");
+        }
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpReorderCharacterImages", {
+            sessionToken,
+            characterId: args.characterId,
+            orderedUrls: args.orderedUrls,
+        });
+    }
+    // -------- delete: apaga o próprio personagem (permanente) --------
+    if (args.action === "delete") {
+        if (!args.characterId)
+            throw new Error("action=delete exige characterId.");
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpDeleteCharacter", {
+            sessionToken,
+            characterId: args.characterId,
+        });
+    }
 }

package/dist/tools/meta.js

@@ -37,18 +37,22 @@ const FORMAT_GUIDE = {
         },
     },
     carrossel_ig: {
-        description: "Carrossel Instagram com múltiplos slides texto + imagem.",
+        description: "Carrossel Instagram editorial (7-9 slides). O editor da pipeline renderiza por TEMPLATE: cada slide é { templateId, slots } (não { title, body } cru — esse shape genérico abre VAZIO no editor). NÃO monte o payload na mão: use sapiens_pipeline action=generate_carousel_production (sourceId), que cria a production E preenche pelo motor da casa, no shape certo, seguindo o artigo. Depois afine com get_carousel/update_carousel (mesmo shape editorial). O create_production com payload cru é legado pra quem já tem o shape editorial pronto.",
         payloadHint: {
+            meta: {
+                caption: "string (legenda do post)",
+                hashtags: ["string"],
+                keyword: "string MAIÚSCULA (gatilho do comment-to-DM, ex: QUERO)",
+            },
+            theme: { palette: "editorial-ink | editorial-dark | editorial-cream | editorial-bone" },
             slides: [
                 {
-                    title: "string opcional",
-                    body: "string",
-                    imagePrompt: "string (pra gerador de imagem)",
-                    imageUrl: "string (preenche depois de gerar)",
+                    id: "slide-1",
+                    templateId: "capa-tipografica-b | corpo-texto-puro-a | corpo-citacao-a | corpo-lista-a | corpo-dado-a | corpo-versus-a | corpo-foto-metade-a | cta-artigo-a (catálogo completo + slots por template vem de get_carousel)",
+                    slots: { "...": "slots do template escolhido (ex: kicker, title, body)" },
+                    image: "null, ou objeto { url, stockImageId, focal, zoom } nos templates de foto",
                 },
             ],
-            caption: "string",
-            hashtags: ["string"],
         },
     },
     tirinha: {

package/dist/tools/persona.js

@@ -35,15 +35,17 @@ const MBTI_GROUPS = {
     ENFP: "NF", INFP: "NF", ENFJ: "NF", INFJ: "NF",
     ENTP: "NT", INTP: "NT", ENTJ: "NT", INTJ: "NT",
 };
+// Nomes autorais da casa (renome 2026-07-18, sync com o site:
+// apps/sapiens/src/app/experimentos/persona-sapiens/data/personas.ts).
 const MBTI_NAMES = {
-    INTJ: "O Estrategista", INTP: "O Lógico",
-    ENTJ: "O Comandante", ENTP: "O Inovador",
-    INFJ: "O Defensor", INFP: "O Mediador",
-    ENFJ: "O Protagonista", ENFP: "O Ativista",
-    ISTJ: "O Logístico", ISFJ: "O Defensor (concreto)",
-    ESTJ: "O Executivo", ESFJ: "O Cônsul",
-    ISTP: "O Virtuoso", ISFP: "O Aventureiro",
-    ESTP: "O Empreendedor", ESFP: "O Animador",
+    INTJ: "Cientista", INTP: "Cypherpunk",
+    ENTJ: "Fundador", ENTP: "Inventor",
+    INFJ: "Editor", INFP: "Poeta",
+    ENFJ: "Maestro", ENFP: "Faísca",
+    ISTJ: "Arquivista", ISFJ: "Guardião",
+    ESTJ: "Produtor", ESFJ: "Anfitrião",
+    ISTP: "Mecânico", ISFP: "Artesão",
+    ESTP: "Negociador", ESFP: "Streamer",
 };
 // Escala Likert 1..7 (mesma do quiz no site).
 const LIKERT_SCALE = {
@@ -126,6 +128,28 @@ const QUIZ_QUESTIONS = [
     { id: "jp-11", axis: "JP", text: "Programas de viagem detalhados me deixam tranquilo, não entediado." },
     { id: "jp-12", axis: "JP", text: "Eu tendo a deixar várias abas mentais abertas ao mesmo tempo." },
 ];
+// ============================================================
+// BLOCO DA CASA: par de jogo (8 perguntas de vínculo, OPCIONAIS).
+// Não mudam o tipo; medem COMO a pessoa quer ser acompanhada (2 eixos:
+// Sparring↔Acolhimento, Direção↔Execução) → 1 de 4 modos de parceiro
+// (Mestre de Jogo, Sparring, Farol, Copiloto), que calibra o Sintético dela.
+// SYNC: espelho de data/vinculoQuestions.ts (site) e VINCULO_CONFIG
+// (convex/personalityProfiles.ts, scoring server-side).
+// ============================================================
+const VINCULO_QUESTIONS = [
+    { id: "vn-sa-1", axis: "SA", text: "Rendo mais quando alguém discorda de mim com força." },
+    { id: "vn-sa-2", axis: "SA", text: "Quando travo, o que me destrava é escuta, não cobrança." },
+    { id: "vn-sa-3", axis: "SA", text: "Prefiro um 'isso tá fraco' na cara a um elogio morno." },
+    { id: "vn-sa-4", axis: "SA", text: "Ideia recém-nascida precisa de espaço seguro antes de aguentar pancada." },
+    { id: "vn-de-1", axis: "DE", text: "Quero alguém que aponte o caminho e me deixe caminhar sozinho." },
+    { id: "vn-de-2", axis: "DE", text: "Plano bom é plano que alguém constrói comigo, mão na massa." },
+    { id: "vn-de-3", axis: "DE", text: "Um bom mapa me serve mais que companhia na trilha." },
+    { id: "vn-de-4", axis: "DE", text: "Ideia boa minha morre por falta de alguém segurando a ponta prática." },
+];
+const VINCULO_AXES_INFO = {
+    SA: "Sparring vs Acolhimento — a pessoa quer que a confrontem ou que a sustentem.",
+    DE: "Direção vs Execução — quer quem aponta o caminho ou quem senta e faz junto.",
+};
 export const personaSchema = z.object({
     action: z.enum([
         "my_profile",
@@ -146,6 +170,13 @@ export const personaSchema = z.object({
     }))
         .optional()
         .describe("Pra action=submit_quiz: as 48 respostas { questionId, value 1..7 }. Pegue os IDs/perguntas com action=get_quiz e colete tudo antes."),
+    vinculoAnswers: z
+        .array(z.object({
+        questionId: z.string(),
+        value: z.number().int().min(1).max(7),
+    }))
+        .optional()
+        .describe("Pra action=submit_quiz: as 8 respostas do bloco da casa (par de jogo, ids vn-*). Opcional, mas recomendado: destrava o modo de parceiro e a calibração do Sintético."),
     nome: z
         .string()
         .optional()
@@ -155,15 +186,21 @@ export async function persona(args) {
     // -------- get_quiz: as 48 perguntas pra aplicar conversando (estático) --------
     if (args.action === "get_quiz") {
         return {
-            totalQuestions: QUIZ_QUESTIONS.length,
+            totalQuestions: QUIZ_QUESTIONS.length + VINCULO_QUESTIONS.length,
             scale: LIKERT_SCALE,
             axes: AXES_INFO,
             instructions: "Aplique conversando: apresente as perguntas (pode ir em blocos por eixo) e " +
                 "peça pra pessoa responder de 1 (Discordo totalmente) a 7 (Concordo totalmente). " +
-                "Junte TODAS as 48 respostas e chame action=submit_quiz com answers=[{questionId, value}]. " +
+                "Junte TODAS as 48 respostas de `questions` e chame action=submit_quiz com answers=[{questionId, value}]. " +
+                "Depois das 48, aplique também o BLOCO DA CASA (`vinculoQuestions`, 8 itens, mesma escala): " +
+                "ele descobre o par de jogo da pessoa (como ela quer ser acompanhada) e calibra o Sintético dela. " +
+                "Essas 8 vão SEPARADAS, no arg vinculoAnswers. " +
                 "Não calcule o resultado você mesmo: o scoring é server-side.",
             questions: QUIZ_QUESTIONS,
-            howToSubmit: "sapiens_persona action=submit_quiz answers=[{questionId:'ei-1', value:5}, ...] (48 itens, value 1..7).",
+            vinculoQuestions: VINCULO_QUESTIONS,
+            vinculoAxes: VINCULO_AXES_INFO,
+            howToSubmit: "sapiens_persona action=submit_quiz answers=[{questionId:'ei-1', value:5}, ...] (48 itens) " +
+                "vinculoAnswers=[{questionId:'vn-sa-1', value:6}, ...] (8 itens, opcional).",
         };
     }
     // -------- submit_quiz: salva o resultado no perfil do user (de graça) --------
@@ -177,6 +214,10 @@ export async function persona(args) {
         const res = await convexMutation("mcpExtras:mcpSubmitPersonaQuiz", {
             sessionToken,
             answers: answers.map((a) => ({ questionId: a.questionId, value: a.value })),
+            // Bloco da casa (par de jogo): opcional; só vai se coletado completo.
+            ...(args.vinculoAnswers?.length
+                ? { vinculoAnswers: args.vinculoAnswers.map((a) => ({ questionId: a.questionId, value: a.value })) }
+                : {}),
             nome: args.nome,
         });
         return {
@@ -205,10 +246,10 @@ export async function persona(args) {
                 group: MBTI_GROUPS[c],
             })),
             groups: {
-                NT: "Analistas — pensa em sistemas",
-                NF: "Diplomatas — pensa em pessoas",
-                SJ: "Sentinelas — pensa em ordem",
-                SP: "Exploradores — pensa em sensação",
+                NT: "Direção (traça o rumo, pensa em sistemas)",
+                NF: "Roteiro (escreve o sentido, pensa em pessoas)",
+                SJ: "Produção (faz rodar, pensa em ordem)",
+                SP: "Cena (joga em tempo real, pensa em sensação)",
             },
         };
     }

package/dist/tools/pipeline.js

@@ -43,6 +43,7 @@ export const pipelineSchema = z.object({
         "propose_mega_grafico_plan",
         "run_mega_grafico_full",
         "generate_carousel",
+        "generate_carousel_production",
         "list_carousels",
         "get_carousel",
         "update_carousel",
@@ -124,7 +125,7 @@ export const pipelineSchema = z.object({
     sourceId: z
         .string()
         .optional()
-        .describe("contentSources:_id — get_source/create_production/remove_source/set_source_done/update_source_notes. Vem de list_sources/add_article_as_source."),
+        .describe("contentSources:_id — get_source/create_production/generate_carousel_production/remove_source/set_source_done/update_source_notes. Vem de list_sources/add_article_as_source."),
     productionId: z
         .string()
         .optional()
@@ -383,6 +384,22 @@ export async function pipeline(args) {
                 useSintetico: args.useSintetico,
             });
         }
+        case "generate_carousel_production": {
+            // Gera um carrossel EDITORIAL como PRODUCTION da pipeline, a partir do
+            // artigo de um source (sourceId de list_sources/add_article_as_source):
+            // cria a production carrossel_ig e a preenche pelo MESMO motor do editor
+            // (shape templateId+slots), então o resultado JÁ abre pronto no editor de
+            // pipeline, ao contrário do create_production cru. ADMIN-ONLY, cobra
+            // Sinapses (reembolsa se falhar). Devolve productionId + url do editor.
+            // SÍNCRONA e pesada (Gemini + imagens): vale a REGRA DO TIMEOUT — se voltar
+            // Timeout, confira em get_production/list_sources antes de repetir.
+            return await convexAction("carouselAutofill:mcpFillCarouselFromArticle", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+                autoPickImages: args.autoPickImages,
+                useSintetico: args.useSintetico,
+            });
+        }
         case "list_carousels":
             // Carrosséis standalone do dono (id + título + url do editor).
             return await convexQuery("carouselMcp:mcpListCarousels", { sessionToken });

package/dist/tools/profile.js

@@ -22,6 +22,9 @@ import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js
  *   - golden_tools: só os favoritos do aitag (lista cheia).
  *   - notifications: suas notificações recentes (sino) + contagem de não-lidas.
  *   - mark_read:    marca uma (notificationId) ou TODAS as suas não-lidas como lidas.
+ *   - follow/unfollow: segue/deixa de seguir outro usuário (followingId).
+ *   - update_bio:   edita a SUA bio.
+ *   - update_username: troca o SEU @username.
  */
 export const profileSchema = z.object({
     action: z.enum([
@@ -30,6 +33,10 @@ export const profileSchema = z.object({
         "golden_tools",
         "notifications",
         "mark_read",
+        "follow",
+        "unfollow",
+        "update_bio",
+        "update_username",
     ]),
     limit: z
         .number()
@@ -39,6 +46,18 @@ export const profileSchema = z.object({
         .string()
         .optional()
         .describe("Pra mark_read: o id de UMA notificação (vem de action=notifications). Omita pra marcar TODAS as não-lidas."),
+    followingId: z
+        .string()
+        .optional()
+        .describe("Pra follow/unfollow: users:_id de QUEM seguir/deixar de seguir. Você (o seguidor) é sempre o dono da sessão. Descubra o id via sapiens_community participants/search_users ou sapiens_search."),
+    bio: z
+        .string()
+        .optional()
+        .describe("Pra update_bio: o novo texto da sua bio (perfil /u/<username>)."),
+    newUsername: z
+        .string()
+        .optional()
+        .describe("Pra update_username: o novo @ (3-20 chars, alfanumérico + underscore). Já em uso ou inválido volta {success:false,error}."),
 });
 const APP = "https://sapiensinteticos.com";
 async function resolveUser(sessionToken) {
@@ -92,6 +111,40 @@ export async function profile(args) {
                 : `Marquei ${res.updated} notificação(ões) como lida(s).`,
         };
     }
+    // Escritas do perfil (autenticam pelo sessionToken; identidade sempre do
+    // token, o cliente só escolhe alvo/valor). Despacham antes do resolveUser.
+    if (args.action === "follow" || args.action === "unfollow") {
+        if (!args.followingId?.trim()) {
+            throw new Error(`action=${args.action} exige followingId (users:_id de quem seguir). Descubra via sapiens_community participants/search_users.`);
+        }
+        const fn = args.action === "follow" ? "users:mcpFollowUser" : "users:mcpUnfollowUser";
+        const res = await convexMutation(fn, {
+            sessionToken,
+            followingId: args.followingId.trim(),
+        });
+        return { ...res, action: args.action };
+    }
+    if (args.action === "update_bio") {
+        if (typeof args.bio !== "string") {
+            throw new Error("action=update_bio exige bio (o novo texto do perfil).");
+        }
+        const res = await convexMutation("users:mcpUpdateBio", {
+            sessionToken,
+            bio: args.bio,
+        });
+        return { ...res, note: "Bio atualizada." };
+    }
+    if (args.action === "update_username") {
+        if (!args.newUsername?.trim()) {
+            throw new Error("action=update_username exige newUsername (3-20 chars).");
+        }
+        const res = await convexMutation("users:mcpUpdateUsername", {
+            sessionToken,
+            newUsername: args.newUsername.trim(),
+        });
+        // doUpdateUsername devolve {success:false,error} quando inválido/tomado.
+        return res;
+    }
     const user = await resolveUser(sessionToken);
     const userId = user._id;
     if (args.action === "badges") {

package/dist/tools/repertorio.js

@@ -4,8 +4,10 @@ import { need } from "../schema.js";
 /**
  * Acesso ao Repertório do Sapiens (acervo pessoal de filme/série/anime/jogo/livro/música).
  *
- * Reads (v1.0): list, search, get, lists, popArticles. Sem auth necessária —
- * só vê items públicos (isPublic !== false).
+ * Reads (v1.0): list, search, get, popArticles. Sem auth necessária —
+ * só vê items públicos (isPublic !== false). (A action `lists` saiu em jul/2026:
+ * as listas curadas foram removidas do produto em 2026-06-22, e a query
+ * repertorio:listLists não existe mais no backend.)
  *
  * Mutations (v1.1+): add_item, update_item, remove_item. Usam sessionToken
  * e valem pra QUALQUER conta logada (`requireMcpUser`) — cada um mexe no
@@ -36,7 +38,6 @@ export const repertorioSchema = z.object({
         "list",
         "search",
         "get",
-        "lists",
         "popArticles",
         "resolve",
         "add_item",
@@ -197,21 +198,6 @@ export async function repertorio(args) {
     if (!args.userId) {
         throw new Error(`action=${args.action} exige userId. Use sapiens_meta action=whoami pra descobrir o user atual.`);
     }
-    if (args.action === "lists") {
-        const lists = await convexQuery("repertorio:listLists", {
-            userId: args.userId,
-        });
-        return {
-            count: Array.isArray(lists) ? lists.length : 0,
-            lists: (lists || []).map((l) => ({
-                _id: l._id,
-                name: l.name,
-                slug: l.slug,
-                description: l.description,
-                isPublic: l.isPublic,
-            })),
-        };
-    }
     if (args.action === "get") {
         const item = await convexQuery("repertorio:getById", {
             itemId: need(args.itemId, "itemId"),

package/dist/tools/video.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { convexAction, convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
+import { convexAction, convexQuery, convexMutation, getSessionToken, isRemoteContext, } from "../convexClient.js";
 import { httpUrl } from "../schema.js";
 /**
  * Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as
@@ -41,9 +41,12 @@ import { httpUrl } from "../schema.js";
  *   - sapiens-video-kling          Kling 3.0 Pro — dá vida a uma imagem, 3-15s, sound opcional (i2v/t2v)
  *   - sapiens-video-wan            WAN 2.5 — imagem que fala/canta (áudio+lip-sync nativo), 5/10s (i2v)
  *   - sapiens-video-kling-motion   Kling Motion — transfere o movimento de um vídeo pra uma imagem
- *                                   (PRECISA de pessoa com tronco visível na imagem E no vídeo)
+ *                                   (PRECISA de pessoa com tronco visível na imagem E no vídeo;
+ *                                   vídeo de referência MÁX 10s — o provider recusa acima disso —
+ *                                   e cobra pela duração do clipe; corte antes de mandar)
  *   - sapiens-video-shot-mimic     Shot Mimic — recria o plano do vídeo de referência (câmera,
  *                                   cortes, blocking) como cena nova; personagem via role 'start'
+ *                                   (vídeo de referência MÁX 15s — acima o provider corta em 15s)
  *   - sapiens-video-lite/fast/quality   Veo 3.1 (2000/5000/25000 sinapses)
  *   - sapiens-video-omni           Gemini Omni — texto -> vídeo 10s 720p com áudio nativo embutido.
  *                                   t2v + EDIÇÃO conversacional: `editOfImageId` aponta um vídeo Omni
@@ -150,8 +153,8 @@ export const videoSchema = z.object({
         .optional()
         .describe("action=create: modelo de vídeo. 'sapiens-video-seedance' (cinematográfico+áudio, t2v/i2v), " +
         "'sapiens-video-kling' (anima imagem, i2v/t2v), 'sapiens-video-wan' (imagem que fala, i2v), " +
-        "'sapiens-video-kling-motion' (motion transfer, precisa pessoa na imagem E no vídeo de movimento), " +
-        "'sapiens-video-shot-mimic' (recria o plano do vídeo de referência com seu personagem: mesma câmera, mesmos cortes; 'driving' = previs/clipe do plano, 'start' = personagem), " +
+        "'sapiens-video-kling-motion' (motion transfer, precisa pessoa na imagem E no vídeo de movimento; vídeo de referência MÁX 10s, cobra pela duração do clipe), " +
+        "'sapiens-video-shot-mimic' (recria o plano do vídeo de referência com seu personagem: mesma câmera, mesmos cortes; 'driving' = previs/clipe do plano MÁX 15s, 'start' = personagem), " +
         "'sapiens-video-lite/fast/quality' (Veo 3.1), " +
         "'sapiens-video-omni' (Gemini Omni: texto -> vídeo 10s 720p com áudio nativo; t2v + EDIÇÃO conversacional via editOfImageId; não aceita imagem/vídeo do user, ignora duração/resolução)."),
     durationSec: z
@@ -202,7 +205,7 @@ export const videoSchema = z.object({
             .describe("'start' = imagem inicial (i2v), 'end' = frame final, 'driving' = vídeo de movimento (Motion)"),
     }))
         .optional()
-        .describe("References em base64 (escape hatch / Motion / Shot Mimic). i2v: role 'start' (imagem). Motion: 'start' (pessoa) + 'driving' (vídeo de movimento, <=5MB). Shot Mimic: 'start' (personagem) + 'driving' (previs ou clipe do plano a imitar, <=5MB). Pra frame inicial/final a partir do seu acervo, prefira start/endImage* abaixo (sem precisar de base64)."),
+        .describe("References em base64 (escape hatch / Motion / Shot Mimic). i2v: role 'start' (imagem). Motion: 'start' (pessoa) + 'driving' (vídeo de movimento, <=5MB, MÁX 10s — o Kling Motion recusa referência acima de 10s e cobra pela duração do clipe; corte o trecho antes). Shot Mimic: 'start' (personagem) + 'driving' (previs ou clipe do plano a imitar, <=5MB, MÁX 15s — acima o provider corta em 15s). Pra frame inicial/final a partir do seu acervo, prefira start/endImage* abaixo (sem precisar de base64)."),
     // Frame inicial/final por REFERÊNCIA (resolvido server-side, igual à imagem):
     // id da própria galeria OU url allowlist (galeria/Acervo/personagens). Mais
     // simples que mandar base64. Descubra via sapiens_reference / sapiens_gallery.
@@ -220,7 +223,91 @@ export const videoSchema = z.object({
     endImageUrl: httpUrl()
         .optional()
         .describe("Frame FINAL: url pública de galeria/Acervo/personagem. Vira reference role 'end' (suporte varia por modelo)."),
+    // Frame inicial/final por ARQUIVO LOCAL (paridade com o upload do gerador do
+    // site). Só no MCP instalado (stdio): o processo lê o arquivo do disco e sobe
+    // como reference role 'start'/'end', sem o base64 passar pelo contexto do
+    // modelo. No remoto é recusado (o path seria do servidor, não do usuário).
+    startImagePath: z
+        .string()
+        .optional()
+        .describe("Frame INICIAL (i2v) a partir de um ARQUIVO LOCAL do seu PC — só no MCP instalado (stdio), não na conexão remota. " +
+        "Passe o caminho absoluto (ex: 'C:\\\\Users\\\\voce\\\\HERO\\\\1.png'); o processo lê o arquivo e sobe como frame inicial, igual a subir a imagem no gerador do site. PNG/JPEG/WebP, até 8MB. " +
+        "É 1 imagem inicial por vídeo (o modelo do site): pra vários vídeos, rode create uma vez por imagem. Mutuamente exclusivo com startImageId/startImageUrl."),
+    endImagePath: z
+        .string()
+        .optional()
+        .describe("Frame FINAL a partir de um ARQUIVO LOCAL do seu PC — só no MCP instalado (stdio). Caminho absoluto; PNG/JPEG/WebP até 8MB. Vira reference role 'end' (suporte varia por modelo). 1 imagem por vídeo. Mutuamente exclusivo com endImageId/endImageUrl."),
 });
+// Teto do arquivo local que vira frame de vídeo. Frame inicial/final não precisa
+// ser pesado; 8MB cobre um PNG/JPEG grande com folga e evita estourar o payload
+// da action (base64 infla ~33%).
+const MAX_LOCAL_IMAGE_BYTES = 8 * 1024 * 1024;
+// Detecta o mime por MAGIC BYTES (não confia na extensão). Frame de vídeo aceita
+// só PNG/JPEG/WebP; qualquer outra coisa é recusada com erro claro.
+export function detectImageMime(buf) {
+    if (buf.length >= 8 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+        return "image/png";
+    }
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (buf.length >= 12 &&
+        buf.toString("ascii", 0, 4) === "RIFF" &&
+        buf.toString("ascii", 8, 12) === "WEBP") {
+        return "image/webp";
+    }
+    return null;
+}
+// Lê um arquivo de imagem do disco e devolve uma reference base64 pro role dado.
+// Guarda de segurança: só no stdio (o processo roda na máquina do dono do token).
+// No remoto recusa ANTES de tocar o disco — ler um path arbitrário lá seria
+// leitura de arquivo do servidor multi-tenant.
+async function readLocalImageAsReference(filePath, role) {
+    if (isRemoteContext()) {
+        throw new Error(`${role}ImagePath (arquivo local) só funciona no MCP instalado na sua máquina (stdio). ` +
+            `Na conexão remota, suba a imagem no site e passe ${role}ImageId (id da galeria) ou ${role}ImageUrl (host Sapiens).`);
+    }
+    const [{ default: fs }, { default: path }] = await Promise.all([
+        import("node:fs/promises"),
+        import("node:path"),
+    ]);
+    const abs = path.resolve(filePath);
+    let buf;
+    try {
+        buf = await fs.readFile(abs);
+    }
+    catch {
+        throw new Error(`Não achei/li o arquivo em ${role}ImagePath: "${filePath}". Use o caminho absoluto do arquivo (ex: C:\\Users\\voce\\HERO\\1.png).`);
+    }
+    if (buf.length > MAX_LOCAL_IMAGE_BYTES) {
+        const mb = (buf.length / (1024 * 1024)).toFixed(1);
+        throw new Error(`Imagem de ${role} muito grande (${mb}MB; teto ${Math.round(MAX_LOCAL_IMAGE_BYTES / (1024 * 1024))}MB). Exporte menor e tente de novo.`);
+    }
+    const mimeType = detectImageMime(buf);
+    if (!mimeType) {
+        throw new Error(`O arquivo de ${role} não parece PNG/JPEG/WebP ("${filePath}"). O frame inicial/final aceita só imagem nesses formatos.`);
+    }
+    return { mimeType, data: buf.toString("base64"), role };
+}
+// Monta as references de frame inicial/final a partir de arquivos locais,
+// barrando o conflito com id/url (o site usa UMA via por frame: ou o arquivo,
+// ou a imagem já hospedada). Devolve [] quando nenhum path foi passado.
+export async function localFrameReferences(args) {
+    const refs = [];
+    if (args.startImagePath) {
+        if (args.startImageId || args.startImageUrl) {
+            throw new Error("Frame inicial: escolha UMA via — startImagePath (arquivo local) OU startImageId/startImageUrl (galeria/Acervo), não as duas.");
+        }
+        refs.push(await readLocalImageAsReference(args.startImagePath, "start"));
+    }
+    if (args.endImagePath) {
+        if (args.endImageId || args.endImageUrl) {
+            throw new Error("Frame final: escolha UMA via — endImagePath (arquivo local) OU endImageId/endImageUrl (galeria/Acervo), não as duas.");
+        }
+        refs.push(await readLocalImageAsReference(args.endImagePath, "end"));
+    }
+    return refs;
+}
 export async function video(args) {
     // models: catálogo VIVO dos modelos de vídeo (ativos + preço-piso/config +
     // override admin + disponibilidade). Público, sem custo e sem login — antes de
@@ -357,6 +444,13 @@ export async function video(args) {
         if (!args.model) {
             throw new Error("action=create exige model (ex: sapiens-video-seedance, sapiens-video-kling, sapiens-video-wan, sapiens-video-kling-motion).");
         }
+        // Frame inicial/final por arquivo local (paridade com o upload do site):
+        // lê do disco e injeta em references role start/end. O backend
+        // (buildVideoReferences) já mescla references + start/end e valida o teto.
+        const localRefs = await localFrameReferences(args);
+        const references = localRefs.length
+            ? [...(args.references ?? []), ...localRefs]
+            : args.references;
         return await convexAction("mcpExtrasActions:mcpVideoCreateAndRender", {
             sessionToken,
             model: args.model,
@@ -365,7 +459,7 @@ export async function video(args) {
             durationSec: args.durationSec,
             resolution: args.resolution,
             audio: args.audio,
-            references: args.references,
+            references,
             startImageId: args.startImageId,
             startImageUrl: args.startImageUrl,
             endImageId: args.endImageId,
@@ -397,12 +491,16 @@ export async function video(args) {
         if (!args.imageId) {
             throw new Error("action=generate exige imageId (vídeo já criado no site).");
         }
+        const localRefs = await localFrameReferences(args);
+        const references = localRefs.length
+            ? [...(args.references ?? []), ...localRefs]
+            : args.references;
         return await convexAction("mcpExtrasActions:mcpVideoGenerate", {
             sessionToken,
             imageId: args.imageId,
             prompt: args.prompt,
             aspectRatio: args.aspectRatio,
-            references: args.references,
+            references,
             startImageId: args.startImageId,
             startImageUrl: args.startImageUrl,
             endImageId: args.endImageId,

package/package.json

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