sapiens-mcp 1.44.0 → 1.45.0

package/dist/registry.js

@@ -26,6 +26,7 @@ import { forum, forumSchema } from "./tools/forum.js";
 import { aula, aulaSchema } from "./tools/aula.js";
 import { support, supportSchema } from "./tools/support.js";
 import { atlas, atlasSchema } from "./tools/atlas.js";
+import { decupagem, decupagemSchema } from "./tools/decupagem.js";
 import { reference, referenceSchema } from "./tools/reference.js";
 import { trilhas, trilhasSchema } from "./tools/trilhas.js";
 import { semana, semanaSchema } from "./tools/semana.js";
@@ -62,7 +63,7 @@ export const TOOLS = {
         handler: skill,
     },
     sapiens_repertorio: {
-        description: "Acervo pessoal de filme/série/anime/jogo/livro/música (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT travada na lista de providers: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), (1) infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped) e rating se citado; (2) chame action=resolve {mediaType, query}, escolha o candidato certo e faça add_item passando SÓ o source + externalId DELE + os campos pessoais (status/rating/tags/note). O servidor re-resolve no provider e grava título/capa/ano canônicos — você NÃO manda título/capa nem inventa externalId. (3) Se o resolve não achar (lista vazia/providerKeyMissing), NÃO dá pra adicionar: diga ao user que não encontrou nos providers (não fabrique entry manual). Upsert/dedup por (userId, source, externalId). Só pergunte se ambíguo entre candidatos. FERRAMENTAS DE IA (Repertório de Ferramentas): fluxo separado (vêm do catálogo aitag, não dos providers de mídia). action=search_tools {query} acha a ferramenta no catálogo e devolve o toolId; action=add_tool {toolId, favorite?, rating?, note?} grava como mediaType 'tool' (estar no acervo já é 'usei'; favorite=true liga a estrela). Use quando o user fala 'adiciona o Midjourney/Cursor no meu repertório de ferramentas' ou 'uso tal ferramenta de IA'. Cada ferramenta aponta pra página dela no aitag.",
+        description: "Acervo pessoal de filme/série/anime/jogo/livro/música/pessoa (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes/Wikidata). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT travada na lista de providers: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), (1) infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped) e rating se citado; (2) chame action=resolve {mediaType, query}, escolha o candidato certo e faça add_item passando SÓ o source + externalId DELE + os campos pessoais (status/rating/tags/note). O servidor re-resolve no provider e grava título/capa/ano canônicos — você NÃO manda título/capa nem inventa externalId. (3) Se o resolve não achar (lista vazia/providerKeyMissing), NÃO dá pra adicionar: diga ao user que não encontrou nos providers (não fabrique entry manual). Upsert/dedup por (userId, source, externalId). Só pergunte se ambíguo entre candidatos. FERRAMENTAS DE IA (Repertório de Ferramentas): fluxo separado (vêm do catálogo aitag, não dos providers de mídia). action=search_tools {query} acha a ferramenta no catálogo e devolve o toolId; action=add_tool {toolId, favorite?, rating?, note?} grava como mediaType 'tool' (estar no acervo já é 'usei'; favorite=true liga a estrela). Use quando o user fala 'adiciona o Midjourney/Cursor no meu repertório de ferramentas' ou 'uso tal ferramenta de IA'. Cada ferramenta aponta pra página dela no aitag. SAPIENS (pessoas, ombros de gigantes; a aba no site chama Sapiens): mediaType 'person' cataloga gente que inspira (cineasta, mangaká, cientista, escritor) via Wikidata. Mesmo fluxo de mídia: resolve {mediaType:'person', query:'Osamu Tezuka'} → add_item com source 'wikidata' + o QID do candidato. O servidor grava foto, ocupações, bio e o link da Wikipedia; entra como completed (estar no acervo = me inspira). Use quando o user fala 'adiciona o Miyazaki nas minhas inspirações/nos meus sapiens/no meu repertório'.",
         schema: repertorioSchema,
         handler: repertorio,
     },
@@ -181,6 +182,11 @@ export const TOOLS = {
         schema: atlasSchema,
         handler: atlas,
     },
+    sapiens_decupagem: {
+        description: "Acervo de Decupagens — a régua de linguagem cinematográfica das referências da casa (admin-only, não cobra Sinapse). O que MEDE é o motor LOCAL `python tools/decupagem/decupa.py \"<arquivo ou link do YouTube>\"` (Python + OpenCV + ffmpeg; não existe OpenCV em serverless, igual à produção dos Vídeos Programáticos). Esta tool é a outra ponta: sobe a ficha que o motor gerou e consulta o acervo. Sub-actions: 'list' (a régua de cada referência já decupada: planos, plano mediano, escola de corte, movimento de câmera vs sujeito, registro de luz, BPM, se o corte obedece ao som), 'get' (a ficha INTEIRA de um slug: plano a plano com o que está no quadro, luz, som, sincronia), 'save' (sobe fichas/<slug>/ficha.json inteiro, sem resumir; mesmo slug ATUALIZA em vez de duplicar), 'note' (anota a leitura editorial na ficha), 'delete'. Fluxo que fecha o ciclo: roda o motor → lê ficha.json → save → aparece no Lab /experimentos/decupagem e entra no comparador. O acervo vale pelo CONJUNTO: uma ficha é morna, vinte lado a lado são a biblioteca de gramática da casa. Antes de decupar referência nova, rode list pra não medir a mesma coisa duas vezes.",
+        schema: decupagemSchema,
+        handler: decupagem,
+    },
     sapiens_reference: {
         description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. DUAS sub-actions: 'browse' (navega um banco) e 'resolve' (acha UM asset pelo ID citável). RESOLVE: passe handle=<tipo>_<id> (img_… imagem, vid_… vídeo, film_… vídeo programático, trk_… música, comic_… tirinha, char_… personagem — é o ID que o usuário copia no detalhe do item) e o servidor devolve {mine, isPublic, url, title, mediaKind} SE for seu ou público (senão recusa; nunca acessa asset privado de terceiro). Use a url retornada como referência (referenceImageUrls / startImageUrl / endImageUrl). BROWSE + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
         schema: referenceSchema,
@@ -207,27 +213,27 @@ export const TOOLS = {
 // É a "skill que anda junto com o pacote": escrevo uma vez, vale pra todos os clients,
 // sem instalar nada. Cobre os tropeços reais (fluxo do musicator, model no vídeo, o
 // disjuntor anti-loop). Mantém curto de propósito: viaja em todo handshake.
-export const SAPIENS_INSTRUCTIONS = `Você opera o Sapiens Sintéticos (sapiensinteticos.com) NA CONTA de um usuário logado. Cada tool age de verdade na conta dele e muitas COBRAM Sinapses (o crédito da casa). Aja como operador, não no chute.
-
-AS SKILLS DA CASA (leia ANTES de operar, não improvise o fluxo):
-O passo a passo travado de cada fluxo mora na tool sapiens_skill, servida por este mesmo servidor: sem login, sem custo, sem rede. Ler a skill é mais barato que errar uma geração que cobra.
-- sapiens_skill action=list -> o índice (slug + quando usar cada uma).
-- sapiens_skill action=get name=<slug> -> a skill inteira.
-Slugs: ${skillMenuLine()}
-Puxe a skill ANTES de: gerar música ou efeito sonoro (musica), escolher modelo de vídeo (video), gerar imagem (imagem), criar na identidade do usuário (studio), montar tirinha (tirinha), postar no Fórum ou no chat (forum-comunidade), redigir qualquer texto publicável (voz-da-casa), incorporar o Sintético (companhia), missão de Desafio (trilhas). Perdido no começo: primeiros-passos.
-Cliente que lê resources MCP acha o MESMO conteúdo em skill://sapiens/<slug>/SKILL.md.
-
-REGRA DE OURO:
-- PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista inteira de tools, deixe o start guiar.
-- LOGO APÓS UM LOGIN BEM-SUCEDIDO (action=login retornou ok): chame action=start na sequência e mostre a porta de entrada. O recém-chegado não sabe o que pedir; não o deixe na tela em branco, guie a primeira jogada sem ele precisar perguntar.
-- Se um tool voltar erro de validação ("exige X", "falta Y"), LEIA o erro e refaça a chamada COM o que falta. NUNCA repita igual a chamada que falhou: 3 falhas seguidas no mesmo tool fazem o cliente marcar o servidor como "unreachable" por ~56s (disjuntor anti-loop). Aí parece que "o MCP caiu", quando foi só argumento faltando.
-- Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes. Vídeo é o mais caro da casa: confirme com ele antes de disparar.
-- REGRA DO TIMEOUT (vale pra toda geração SÍNCRONA: imagem pesada, artigo, mega-gráfico, carrossel): a chamada pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e COBRADO. Nunca repita às cegas: confira antes onde o resultado cairia (imagem: sapiens_gallery action=list; artigo: sapiens_write action=list; carrossel: sapiens_pipeline action=list_carousels; pipeline: /dashboard/admin/content).
-- "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
-- sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo. sapiens_image e sapiens_video action=models trazem o catálogo com o preço ATUAL: consulte em vez de chutar custo.
-
-MODO COMPANHIA: sapiens_meta action=start e action=whoami podem trazer um bloco 'companion'. Quando vier companion.active=true, você INCORPORA aquele Sintético (a voz dele, o avatar, o oi dele) continuando a operar na conta e nas Sinapses do USUÁRIO. Puxe a skill 'companhia' antes de fazer isso.
-
+export const SAPIENS_INSTRUCTIONS = `Você opera o Sapiens Sintéticos (sapiensinteticos.com) NA CONTA de um usuário logado. Cada tool age de verdade na conta dele e muitas COBRAM Sinapses (o crédito da casa). Aja como operador, não no chute.
+
+AS SKILLS DA CASA (leia ANTES de operar, não improvise o fluxo):
+O passo a passo travado de cada fluxo mora na tool sapiens_skill, servida por este mesmo servidor: sem login, sem custo, sem rede. Ler a skill é mais barato que errar uma geração que cobra.
+- sapiens_skill action=list -> o índice (slug + quando usar cada uma).
+- sapiens_skill action=get name=<slug> -> a skill inteira.
+Slugs: ${skillMenuLine()}
+Puxe a skill ANTES de: gerar música ou efeito sonoro (musica), escolher modelo de vídeo (video), gerar imagem (imagem), criar na identidade do usuário (studio), montar tirinha (tirinha), postar no Fórum ou no chat (forum-comunidade), redigir qualquer texto publicável (voz-da-casa), incorporar o Sintético (companhia), missão de Desafio (trilhas). Perdido no começo: primeiros-passos.
+Cliente que lê resources MCP acha o MESMO conteúdo em skill://sapiens/<slug>/SKILL.md.
+
+REGRA DE OURO:
+- PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista inteira de tools, deixe o start guiar.
+- LOGO APÓS UM LOGIN BEM-SUCEDIDO (action=login retornou ok): chame action=start na sequência e mostre a porta de entrada. O recém-chegado não sabe o que pedir; não o deixe na tela em branco, guie a primeira jogada sem ele precisar perguntar.
+- Se um tool voltar erro de validação ("exige X", "falta Y"), LEIA o erro e refaça a chamada COM o que falta. NUNCA repita igual a chamada que falhou: 3 falhas seguidas no mesmo tool fazem o cliente marcar o servidor como "unreachable" por ~56s (disjuntor anti-loop). Aí parece que "o MCP caiu", quando foi só argumento faltando.
+- Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes. Vídeo é o mais caro da casa: confirme com ele antes de disparar.
+- REGRA DO TIMEOUT (vale pra toda geração SÍNCRONA: imagem pesada, artigo, mega-gráfico, carrossel): a chamada pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e COBRADO. Nunca repita às cegas: confira antes onde o resultado cairia (imagem: sapiens_gallery action=list; artigo: sapiens_write action=list; carrossel: sapiens_pipeline action=list_carousels; pipeline: /dashboard/admin/content).
+- "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
+- sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo. sapiens_image e sapiens_video action=models trazem o catálogo com o preço ATUAL: consulte em vez de chutar custo.
+
+MODO COMPANHIA: sapiens_meta action=start e action=whoami podem trazer um bloco 'companion'. Quando vier companion.active=true, você INCORPORA aquele Sintético (a voz dele, o avatar, o oi dele) continuando a operar na conta e nas Sinapses do USUÁRIO. Puxe a skill 'companhia' antes de fazer isso.
+
 Voz da casa: 1ª pessoa, direto, anti-corporate, sem travessão. Pra bom entendedor, meia palavra basta. Texto que vai ser publicado pede a skill 'voz-da-casa' antes.`;
 // Annotations MCP: título humano + dica read-only. São HINTS (não-confiáveis por
 // spec): quem gateia de verdade continua o servidor (saldo, gate de admin,
@@ -295,6 +301,7 @@ const ADMIN_ONLY_TOOLS = new Set([
     "sapiens_instagram",
     "sapiens_aula",
     "sapiens_share",
+    "sapiens_decupagem",
 ]);
 /**
  * Monta o payload do tools/list pro tier dado. Tier "user" esconde as

package/dist/tools/decupagem.js

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

package/dist/tools/gallery.js

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

package/dist/tools/repertorio.js

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

package/package.json

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