sapiens-mcp 1.33.0 → 1.36.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). 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 e generate_carousel são SÍNCRONAS e pesadas: vale a REGRA DO TIMEOUT (podem cobrar mesmo voltando 'Timeout'; cheque /dashboard/admin/content 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,
     },
@@ -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. 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,
     },
@@ -212,7 +212,7 @@ Efeito sonoro (sapiens_stock_audio): primeiro procure pronto (action=list kind=s
 
 Sonorizar clipe (sapiens_video action=sonorize): dá som a um vídeo SEU já gerado (status completed). Passe imageId + prompt descrevendo o som da cena (ambiente, materiais, impactos); sai uma VARIANTE nova com trilha sincronizada ao movimento (MMAudio, 20 Sinapses/s do clipe, mín 100), o original fica intacto. Acompanhe com action=status no imageId NOVO que o sonorize devolve. Não re-sonorize uma variante: sonorize sempre o original.
 
-Vídeo (sapiens_video) action=create EXIGE 'model': sapiens-video-seedance | kling | wan | kling-motion | lite | fast | quality | omni. Sem model, falha de cara. O 'omni' (Gemini Omni) gera clipe de 10s 720p com áudio nativo a partir de TEXTO (não aceita imagem/vídeo do user, ignora duração/resolução) e EDITA os próprios vídeos: passe editOfImageId com o imageId de um vídeo Omni já gerado e o prompt vira instrução de edição sobre a MESMA cena (troca item/personagem, preserva câmera e ambiente; cada edição debita como geração nova). É o caminho pra variações com continuidade: gera a base uma vez, edita N vezes. Vídeo é o mais caro: confirme com o usuário antes. action=shadows (ADMIN, 200 Sinapses/segundo, refund na falha): passa videoUrl (URL pública) + title (+ durationSec se souber, pra cobrar proporcional; sem ela, flat ~2000) e o servidor extrai a SOMBRA (mapa de profundidade) do vídeo e guarda no Acervo (Corpo) como deepshadow reutilizável (driving pro Shot Mimic/Kling Motion). FILMES DA CASA (Estúdio de Vídeo, tela /experimentos/films): são OUTRA coisa, três kinds na tabela videoSpecs: demo (UI clonada + câmera), aula-tour (telas reais + narração) e essay (fita-ensaio abstrata: partícula/tinta vira símbolo, com a logo explodindo no fim; narração da casa OPCIONAL, sai em 16:9 ou 9:16 vertical, e o filme final é limpo, sem rótulos de produção). Eles NÃO são gerados por este MCP: o user monta o spec na tela e um agente local (Claude Code, skill /film) produz o mp4 no repo da casa. Se o user pedir 'fita-ensaio' ou 'demo film' aqui, aponte pra tela e pro agente local.
+Vídeo (sapiens_video) action=create EXIGE 'model': sapiens-video-seedance | kling | wan | kling-motion | lite | fast | quality | omni. Sem model, falha de cara. O 'omni' (Gemini Omni) gera clipe de 10s 720p com áudio nativo a partir de TEXTO (não aceita imagem/vídeo do user, ignora duração/resolução) e EDITA os próprios vídeos: passe editOfImageId com o imageId de um vídeo Omni já gerado e o prompt vira instrução de edição sobre a MESMA cena (troca item/personagem, preserva câmera e ambiente; cada edição debita como geração nova). É o caminho pra variações com continuidade: gera a base uma vez, edita N vezes. Vídeo é o mais caro: confirme com o usuário antes. action=shadows (ADMIN, 200 Sinapses/segundo, refund na falha): passa videoUrl (URL pública) + title (+ durationSec se souber, pra cobrar proporcional; sem ela, flat ~2000) e o servidor extrai a SOMBRA (mapa de profundidade) do vídeo e guarda no Acervo (Corpo) como deepshadow reutilizável (driving pro Shot Mimic/Kling Motion). VÍDEOS PROGRAMÁTICOS (Estúdio de Vídeo, tela /experimentos/films): são OUTRA coisa, a mesa de filmes-de-código da casa, CINCO kinds na tabela videoSpecs: demo (UI clonada + câmera), aula-tour (telas reais + narração), essay (fita-ensaio abstrata: partícula/tinta vira símbolo; narração opcional, 16:9 ou 9:16), tipografia-musical (clipe tipográfico, a música dirige o corte) e dataviz (barras/números no tempo). O RENDER não sai deste MCP: um agente local (Claude Code, skill /film) produz o mp4 no repo da casa. Mas o CICLO na plataforma fecha por aqui (ADMIN, sem custo): film-list/film-get puxam os specs, film-upsert registra/atualiza, film-status cola a URL do render e marca pronto, film-publish põe no Acervo. User comum pedindo 'fita-ensaio'/'demo film': aponte pra tela e pro agente local.
 
 Imagem (sapiens_image) action=generate: prompt + model + aspectRatio. Referência via referenceImageUrls (galeria/Acervo/personagens) e/ou sourceImageIds. templateSlug aplica um super-prompt travado da casa. PROMPT na regra da casa: full-bleed, sujeito oversized (70%+ do frame), sem "tarot card"/"intimate scale"/moldura/margem. action=models (sem custo, sem login) lista os modelos ativos com o preço atual: consulte quando não tiver certeza do modelo ou do custo.
 

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,12 @@ export const pipelineSchema = z.object({
         "propose_mega_grafico_plan",
         "run_mega_grafico_full",
         "generate_carousel",
+        "generate_carousel_production",
+        "list_carousels",
+        "get_carousel",
+        "update_carousel",
+        "carousel_auto_images",
+        "carousel_generate_image",
     ]),
     // propose_mega_grafico_plan / run_mega_grafico_full
     withHelen: z
@@ -83,6 +89,31 @@ export const pipelineSchema = z.object({
         .boolean()
         .optional()
         .describe("generate_carousel: se TRUE, a voz do Sintético do dono dirige o copy (amplificar). Default false = estilo do dono."),
+    // carrossel standalone (get/update/imagens)
+    carouselId: z
+        .string()
+        .optional()
+        .describe("carousels_standalone:_id — get_carousel/update_carousel/carousel_auto_images/carousel_generate_image. Vem de generate_carousel ou list_carousels."),
+    slideId: z
+        .string()
+        .optional()
+        .describe("carousel_generate_image: id do slide (ex: 'slide-3'), do payload do get_carousel."),
+    force: z
+        .boolean()
+        .optional()
+        .describe("carousel_auto_images: TRUE substitui as imagens já aplicadas por escolhas novas. Default false = preenche só o que falta."),
+    makeVisual: z
+        .boolean()
+        .optional()
+        .describe("carousel_auto_images: TRUE converte slides de texto pra layouts de foto antes de escolher (ritmo visual pro carrossel texto-pesado). O texto fica, muda a moldura."),
+    generateMissing: z
+        .boolean()
+        .optional()
+        .describe("carousel_auto_images: TRUE gera imagem NOVA (nanoBanana, ~450 Sinapses cada, até 4) pros slides que o banco não cobriu. O fallback stock→gerador. Avise o usuário do custo antes."),
+    customPrompt: z
+        .string()
+        .optional()
+        .describe("carousel_generate_image: direção extra da cena (opcional; sem ela a IA usa o texto do slide)."),
     // list_articles
     includeDrafts: z.boolean().optional(),
     includeArchived: z.boolean().optional(),
@@ -94,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()
@@ -353,5 +384,62 @@ 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 });
+        case "get_carousel":
+            // Devolve payload completo + catálogo de templates (id/slots/limites) +
+            // paletas válidas: tudo que você precisa pra ESCREVER os slides direto.
+            return await convexQuery("carouselMcp:mcpGetCarousel", {
+                sessionToken,
+                carouselId: need(args.carouselId, "carouselId"),
+            });
+        case "update_carousel":
+            // Payload INTEIRO (mesmo shape do get_carousel). Sanitizado no servidor.
+            // Preserve os campos image dos slides que você não mexeu — mandar slide
+            // sem image derruba a foto dele.
+            return await convexMutation("carouselMcp:mcpUpdateCarousel", {
+                sessionToken,
+                carouselId: need(args.carouselId, "carouselId"),
+                payload: coercePayloadArg(need(args.payload, "payload")),
+                ...(args.title ? { title: args.title } : {}),
+            });
+        case "carousel_auto_images":
+            // IA escolhe imagens do banco pros slides de foto sem imagem (60 Sinapses).
+            // makeVisual dá ritmo a carrossel texto-pesado; generateMissing gera as que
+            // o banco não cobriu (custo por imagem). SÍNCRONA e pesada com
+            // generateMissing: vale a REGRA DO TIMEOUT.
+            return await convexAction("carouselAutofill:mcpCarouselAutoImages", {
+                sessionToken,
+                carouselId: need(args.carouselId, "carouselId"),
+                force: args.force,
+                makeVisual: args.makeVisual,
+                generateMissing: args.generateMissing,
+            });
+        case "carousel_generate_image":
+            // Gera imagem NOVA pra UM slide (nanoBanana, ~450 Sinapses) e salva no
+            // carrossel. SÍNCRONA (~20-60s): vale a REGRA DO TIMEOUT.
+            return await convexAction("carouselAutofill:mcpCarouselGenerateImage", {
+                sessionToken,
+                carouselId: need(args.carouselId, "carouselId"),
+                slideId: need(args.slideId, "slideId"),
+                ...(args.customPrompt ? { customPrompt: args.customPrompt } : {}),
+            });
     }
 }

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
@@ -25,14 +25,28 @@ import { httpUrl } from "../schema.js";
  *               som da cena -> VARIANTE nova com trilha sincronizada (o original
  *               fica intacto). Cobra por segundo do clipe; poll via action=status.
  *
+ * Vídeos Programáticos (Estúdio de Vídeo, /experimentos/films) — ADMIN, sem custo.
+ * A mesa de specs da casa (tabela videoSpecs, 5 kinds: demo | aula-tour | essay |
+ * tipografia-musical | dataviz). A PRODUÇÃO do mp4 segue no agente local (skill
+ * /film, repo films/); estas actions fecham o CICLO na plataforma sem browser:
+ *   - film-list:    lista os specs (todos os kinds; filtros filmKind/filmStatus).
+ *   - film-get:     um spec inteiro por slug (payload pronto pra produção).
+ *   - film-upsert:  cria/atualiza spec por slug (idempotente; validação server).
+ *   - film-status:  status/URL do render/duração por slug (fecho: pronto+URL).
+ *   - film-publish: publica/despublica no Acervo (aba Fitas) + portfólio.
+ *   - film-delete:  apaga um spec (limpar rascunho/duplicata).
+ *
  * Modelos (action=create):
  *   - sapiens-video-seedance       Seedance 2.0 — cena com áudio nativo, 4-15s, 480/720/1080p (t2v/i2v)
  *   - 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
@@ -56,12 +70,56 @@ const VIDEO_MODELS = [
     "sapiens-video-quality",
     "sapiens-video-omni",
 ];
+const FILM_KINDS = ["demo", "aula-tour", "essay", "tipografia-musical", "dataviz"];
+const FILM_STATUSES = ["rascunho", "na_fila", "renderizando", "pronto"];
 export const videoSchema = z.object({
-    action: z.enum(["create", "generate", "status", "models", "demos", "showcase", "shadows", "shadows-list", "sonorize"]),
+    action: z.enum([
+        "create",
+        "generate",
+        "status",
+        "models",
+        "demos",
+        "showcase",
+        "shadows",
+        "shadows-list",
+        "sonorize",
+        "film-list",
+        "film-get",
+        "film-upsert",
+        "film-status",
+        "film-publish",
+        "film-delete",
+    ]),
+    // --- Vídeos Programáticos (film-*): mesa de specs da casa, ADMIN, sem custo ---
+    filmKind: z
+        .enum(FILM_KINDS)
+        .optional()
+        .describe("film-list: filtra por kind (demo | aula-tour | essay | tipografia-musical | dataviz)."),
+    filmStatus: z
+        .enum(FILM_STATUSES)
+        .optional()
+        .describe("film-status: novo status de produção (rascunho | na_fila | renderizando | pronto). " +
+        "film-list: filtra por status. O fecho do render é film-status com filmStatus='pronto' + videoUrl + durationSec."),
+    spec: z
+        .record(z.any())
+        .optional()
+        .describe("film-upsert: o spec inteiro como objeto JSON (validação fica no servidor, fonte única). " +
+        "Shape: { kind, musicMode ('default'|'file'|'track'), musicRef?, aulaSlug? (só aula-tour), " +
+        "e o payload do kind: demo | aulaTour | essay | tipoMusical | dataviz }. " +
+        "Mesmo shape do 'Copiar spec' da tela /experimentos/films; descubra um exemplo real com film-get."),
+    published: z
+        .boolean()
+        .optional()
+        .describe("film-publish: true publica no Acervo (aba Fitas) + portfólio (exige pronto + videoUrl), false despublica."),
+    durationSecMeasured: z
+        .number()
+        .optional()
+        .describe("film-status: duração MEDIDA do render em segundos (ffprobe), vira a duração do card."),
     // --- action=shadows (deepshadows: extrai o mapa de profundidade de um vídeo) ---
     videoUrl: httpUrl()
         .optional()
-        .describe("action=shadows: URL pública (http/https) do vídeo-fonte. O servidor extrai a SOMBRA (depth) e guarda no Acervo (Corpo). ADMIN, 200 Sinapses/segundo (refund na falha)."),
+        .describe("action=shadows: URL pública (http/https) do vídeo-fonte. O servidor extrai a SOMBRA (depth) e guarda no Acervo (Corpo). ADMIN, 200 Sinapses/segundo (refund na falha). " +
+        "film-status: a URL https do render no CDN (Bunny), o que acende o player do card."),
     title: z
         .string()
         .optional()
@@ -74,7 +132,9 @@ export const videoSchema = z.object({
     slug: z
         .string()
         .optional()
-        .describe("action=showcase: slug do demo film a curar (descubra via action=demos)."),
+        .describe("action=showcase: slug do demo film a curar (descubra via action=demos). " +
+        "film-get/film-status/film-publish/film-delete: slug do spec (descubra via film-list). " +
+        "film-upsert: slug fixo do filme no repo films/ (idempotente: existe = atualiza, não existe = cria com esse slug); omita pra criar com slug gerado."),
     showcase: z
         .boolean()
         .optional()
@@ -93,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
@@ -145,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.
@@ -163,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
@@ -196,6 +340,69 @@ export async function video(args) {
     if (args.action === "demos") {
         return await convexQuery("videoSpecs:mcpListMyDemoFilms", { sessionToken });
     }
+    // --- Vídeos Programáticos (mesa de specs, ADMIN, sem custo) ---
+    if (args.action === "film-list") {
+        return await convexQuery("videoSpecs:mcpListMyVideoSpecs", {
+            sessionToken,
+            kind: args.filmKind,
+            status: args.filmStatus,
+        });
+    }
+    if (args.action === "film-get") {
+        if (!args.slug)
+            throw new Error("film-get exige slug (descubra via film-list).");
+        return await convexQuery("videoSpecs:mcpGetVideoSpec", { sessionToken, slug: args.slug });
+    }
+    if (args.action === "film-upsert") {
+        if (!args.spec || typeof args.spec !== "object") {
+            throw new Error("film-upsert exige spec (objeto JSON com kind + musicMode + payload do kind: demo | aulaTour | essay | tipoMusical | dataviz).");
+        }
+        const { kind, musicMode, musicRef, aulaSlug, demo, aulaTour, essay, tipoMusical, dataviz } = args.spec;
+        return await convexMutation("videoSpecs:mcpUpsertVideoSpec", {
+            sessionToken,
+            slug: args.slug,
+            kind,
+            musicMode: musicMode ?? "default",
+            musicRef,
+            aulaSlug,
+            demo,
+            aulaTour,
+            essay,
+            tipoMusical,
+            dataviz,
+        });
+    }
+    if (args.action === "film-status") {
+        if (!args.slug)
+            throw new Error("film-status exige slug (descubra via film-list).");
+        if (args.filmStatus === undefined && args.videoUrl === undefined && args.durationSecMeasured === undefined) {
+            throw new Error("film-status: passe filmStatus, videoUrl e/ou durationSecMeasured (o fecho do render é os três).");
+        }
+        return await convexMutation("videoSpecs:mcpSetVideoStatus", {
+            sessionToken,
+            slug: args.slug,
+            status: args.filmStatus,
+            videoUrl: args.videoUrl,
+            durationSec: args.durationSecMeasured,
+        });
+    }
+    if (args.action === "film-publish") {
+        if (!args.slug)
+            throw new Error("film-publish exige slug (descubra via film-list).");
+        if (typeof args.published !== "boolean") {
+            throw new Error("film-publish exige published (true publica no Acervo, false despublica).");
+        }
+        return await convexMutation("videoSpecs:mcpSetVideoPublished", {
+            sessionToken,
+            slug: args.slug,
+            published: args.published,
+        });
+    }
+    if (args.action === "film-delete") {
+        if (!args.slug)
+            throw new Error("film-delete exige slug (descubra via film-list).");
+        return await convexMutation("videoSpecs:mcpDeleteVideoSpec", { sessionToken, slug: args.slug });
+    }
     if (args.action === "showcase") {
         if (!args.slug) {
             throw new Error("action=showcase exige slug (descubra via action=demos).");
@@ -237,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,
@@ -245,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,
@@ -277,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.33.0",
+  "version": "1.36.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": {