sapiens-mcp 1.0.0

package/dist/tools/pipeline.js

@@ -0,0 +1,294 @@
+import { z } from "zod";
+import { convexAction, convexMutation, convexQuery, getSessionToken, } from "../convexClient.js";
+const FORMATS = [
+    "tirinha",
+    "carrossel_ig",
+    "post_social",
+    "musica",
+    "mega_grafico",
+    "post_linkedin",
+    "post_twitter",
+    "post_threads",
+    "shorts_yt",
+    "cena_visual",
+    "video_yt",
+];
+const STATUSES = ["draft", "ready", "finalized"];
+export const pipelineSchema = z.object({
+    action: z.enum([
+        "list_sources",
+        "list_articles",
+        "get_source",
+        "get_production",
+        "list_versions",
+        "add_article_as_source",
+        "create_draft_article_and_source",
+        "create_production",
+        "update_production",
+        "finalize_production",
+        "remove_production",
+        "remove_source",
+        "set_source_done",
+        "update_source_notes",
+        "restore_version",
+        "set_publishable_title",
+        "backfill_via",
+        "propose_mega_grafico_plan",
+        "run_mega_grafico_full",
+    ]),
+    // propose_mega_grafico_plan / run_mega_grafico_full
+    withHelen: z
+        .boolean()
+        .optional()
+        .describe("Se TRUE, plano reserva 1 painel pra Helen Ailith interagindo com o tema (cartoon editorial). Se FALSE, poster 100% diagramático sem figura humana. Pergunte ao user antes de definir."),
+    // run_mega_grafico_full
+    skipFinalize: z
+        .boolean()
+        .optional()
+        .describe("Se TRUE, gera plano + imagem + branding + salva payload mas NÃO cria publishable (deixa production em 'ready' pro admin revisar). Default false."),
+    skipBranding: z
+        .boolean()
+        .optional()
+        .describe("Se TRUE, pula o composite do selo Sapiens + tEXt chunks. Use só quando o Convex storage está fora ou pra debug. Default false."),
+    templateSlug: z
+        .string()
+        .optional()
+        .describe("Slug do template de receita (admin edita em /dashboard/admin/image-templates). Se omitido, usa o template marcado isDefault=true pro formato. Ex: 'mega-grafico-blueprint-v1'."),
+    specOverride: z
+        .object({
+        model: z.string().optional(),
+        aspectRatio: z.string().optional(),
+        size: z.string().optional(),
+    })
+        .optional()
+        .describe("Override de model/aspectRatio/size sobre os defaults do template. Cada um valida contra o allowedX do template; se sair do whitelist, action throws."),
+    // list_articles
+    includeDrafts: z.boolean().optional(),
+    includeArchived: z.boolean().optional(),
+    onlyAvailable: z
+        .boolean()
+        .optional()
+        .describe("Se true, só artigos que ainda NÃO foram virados em source"),
+    // por id
+    sourceId: z.string().optional(),
+    productionId: z.string().optional(),
+    publishableId: z.string().optional(),
+    articleId: z.string().optional(),
+    // create / add
+    format: z.enum(FORMATS).optional(),
+    payload: z.any().optional().describe("Payload livre por formato"),
+    status: z.enum(STATUSES).optional(),
+    notes: z.string().optional(),
+    // create_draft_article_and_source
+    title: z.string().optional(),
+    slug: z.string().optional(),
+    excerpt: z.string().optional(),
+    tldr: z.string().optional(),
+    content: z.string().optional(),
+    category: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    thumbnailUrl: z.string().optional(),
+    // finalize_production
+    assets: z
+        .array(z.object({
+        kind: z.string(),
+        url: z.string().optional(),
+        text: z.string().optional(),
+        meta: z.any().optional(),
+    }))
+        .optional(),
+    caption: z.string().optional(),
+    hashtags: z.array(z.string()).optional(),
+    // set_source_done
+    isDone: z.boolean().optional(),
+    // backfill_via
+    sinceCreatedAt: z.number().optional(),
+    beforeCreatedAt: z.number().optional(),
+    via: z
+        .string()
+        .optional()
+        .describe("Ex: 'claude-mcp', 'modo-antigo', 'manual'"),
+    dryRun: z.boolean().optional(),
+});
+function need(value, name) {
+    if (value === undefined || value === null) {
+        throw new Error(`Faltando arg "${name}" pra essa action.`);
+    }
+    return value;
+}
+export async function pipeline(args) {
+    const sessionToken = getSessionToken();
+    switch (args.action) {
+        case "list_sources":
+            return await convexQuery("pipelineMcp:mcpListSources", { sessionToken });
+        case "list_articles":
+            return await convexQuery("pipelineMcp:mcpListArticles", {
+                sessionToken,
+                includeDrafts: args.includeDrafts,
+                includeArchived: args.includeArchived,
+                onlyAvailable: args.onlyAvailable,
+            });
+        case "get_source":
+            return await convexQuery("pipelineMcp:mcpGetSource", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+            });
+        case "get_production":
+            return await convexQuery("pipelineMcp:mcpGetProduction", {
+                sessionToken,
+                productionId: need(args.productionId, "productionId"),
+            });
+        case "list_versions":
+            return await convexQuery("pipelineMcp:mcpListPublishableVersions", {
+                sessionToken,
+                productionId: need(args.productionId, "productionId"),
+            });
+        case "add_article_as_source": {
+            const id = await convexMutation("pipelineMcp:mcpAddArticleAsSource", {
+                sessionToken,
+                articleId: need(args.articleId, "articleId"),
+                notes: args.notes,
+            });
+            return { sourceId: id };
+        }
+        case "create_draft_article_and_source": {
+            const result = await convexMutation("pipelineMcp:mcpCreateDraftArticleAndSource", {
+                sessionToken,
+                title: need(args.title, "title"),
+                slug: need(args.slug, "slug"),
+                excerpt: args.excerpt,
+                tldr: args.tldr,
+                content: need(args.content, "content"),
+                category: args.category,
+                tags: args.tags,
+                thumbnailUrl: args.thumbnailUrl,
+            });
+            return result;
+        }
+        case "create_production": {
+            const id = await convexMutation("pipelineMcp:mcpCreateProductionDraft", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+                format: need(args.format, "format"),
+                payload: args.payload,
+            });
+            return { productionId: id };
+        }
+        case "update_production":
+            await convexMutation("pipelineMcp:mcpUpdateProductionPayload", {
+                sessionToken,
+                productionId: need(args.productionId, "productionId"),
+                payload: need(args.payload, "payload"),
+                status: args.status,
+            });
+            return { ok: true };
+        case "finalize_production": {
+            const id = await convexMutation("pipelineMcp:mcpFinalizeProduction", {
+                sessionToken,
+                productionId: need(args.productionId, "productionId"),
+                assets: need(args.assets, "assets"),
+                caption: args.caption,
+                hashtags: args.hashtags,
+                title: args.title,
+            });
+            return { publishableId: id };
+        }
+        case "set_publishable_title":
+            await convexMutation("pipelineMcp:mcpSetPublishableTitle", {
+                sessionToken,
+                publishableId: need(args.publishableId, "publishableId"),
+                title: need(args.title, "title"),
+            });
+            return { ok: true };
+        case "backfill_via":
+            return await convexMutation("pipelineMcp:mcpBackfillVia", {
+                sessionToken,
+                sinceCreatedAt: args.sinceCreatedAt,
+                beforeCreatedAt: args.beforeCreatedAt,
+                via: need(args.via, "via"),
+                dryRun: args.dryRun,
+            });
+        case "remove_production":
+            await convexMutation("pipelineMcp:mcpRemoveProduction", {
+                sessionToken,
+                productionId: need(args.productionId, "productionId"),
+            });
+            return { ok: true };
+        case "remove_source":
+            await convexMutation("pipelineMcp:mcpRemoveSource", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+            });
+            return { ok: true };
+        case "set_source_done":
+            await convexMutation("pipelineMcp:mcpSetSourceDone", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+                isDone: need(args.isDone, "isDone"),
+            });
+            return { ok: true };
+        case "update_source_notes":
+            await convexMutation("pipelineMcp:mcpUpdateSourceNotes", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+                notes: need(args.notes, "notes"),
+            });
+            return { ok: true };
+        case "restore_version": {
+            const productionId = await convexMutation("pipelineMcp:mcpRestoreVersion", {
+                sessionToken,
+                publishableId: need(args.publishableId, "publishableId"),
+            });
+            return { productionId };
+        }
+        case "propose_mega_grafico_plan": {
+            // Gemini propõe um plano denso de mega gráfico a partir do source
+            // (artigo ou brief). Devolve fullPrompt + spec recomendada (vem do
+            // template) e referenceImageUrls se withHelen=true. templateSlug e
+            // specOverride respeitam o que o admin configurou em
+            // /dashboard/admin/image-templates.
+            // Use APENAS quando quiser controle granular (revisar plano antes de
+            // gerar imagem). Pra fluxo end-to-end, prefira run_mega_grafico_full
+            // que faz tudo numa chamada só.
+            const result = await convexAction("megaGraficoActions:mcpProposeMegaGraficoPlan", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+                withHelen: args.withHelen ?? false,
+                templateSlug: args.templateSlug,
+                specOverride: args.specOverride,
+            });
+            return result;
+        }
+        case "run_mega_grafico_full": {
+            // One-shot do fluxo mega gráfico inteiro: cria production (ou reusa
+            // se productionId passado), propõe plano com guard de qualidade (1
+            // retry se fraco), gera imagem via gpt-image-2-high, aplica selo
+            // Sapiens (logo + PNG tEXt chunks), salva payload, e finaliza como
+            // publishable (skipFinalize=true pula essa etapa).
+            //
+            // Custo: ~900 sinapses da geração de imagem + 0-100 sinapses Gemini
+            // text. Total ~900-1000.
+            //
+            // ANTES de chamar: pergunte ao user se withHelen=true (Helen
+            // interage com tema, ~15-25% do poster) ou false (poster 100%
+            // diagramático, sem humanos).
+            //
+            // Receita usada: o templateSlug do payload (admin edita em
+            // /dashboard/admin/image-templates). Sem templateSlug, usa o default.
+            // specOverride permite trocar model/aspect/size dentro do whitelist
+            // do template (ex: aspectRatio="1:1" pra IG, "16:9" pra og:image).
+            const result = await convexAction("megaGraficoRunner:mcpRunMegaGraficoFull", {
+                sessionToken,
+                sourceId: need(args.sourceId, "sourceId"),
+                withHelen: args.withHelen ?? false,
+                productionId: args.productionId,
+                skipFinalize: args.skipFinalize,
+                skipBranding: args.skipBranding,
+                caption: args.caption,
+                templateSlug: args.templateSlug,
+                specOverride: args.specOverride,
+            });
+            return result;
+        }
+    }
+}

package/dist/tools/quotePop.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { convexMutation, getSessionToken } from "../convexClient.js";
+/**
+ * Publish curado pra Coluna Sapiens (quote) e Coluna Repertório (pop-article)
+ * via session token. Substitui:
+ *   - apps/sapiens/scripts/sapiens-quote-publish.js
+ *   - apps/sapiens/scripts/sapiens-pop-article-publish.js
+ *
+ * Antes esses scripts usavam setAdminAuth (CONVEX_ADMIN_KEY). Agora o MCP
+ * publica direto via `mcpExtras.mcpPublishQuote` / `mcpPublishPopArticle`,
+ * que valida o sessionToken e exige user admin. Mesma garantia de segurança,
+ * setup zero pro user (não precisa mais ter CONVEX_ADMIN_KEY no env).
+ *
+ * Sub-actions:
+ *   - publish_quote: cria entry na Coluna Sapiens. Default status="draft"
+ *     (admin revisa em /dashboard/admin/blog/sapiens-curation). publishNow=true
+ *     pula direto pra published.
+ *   - publish_pop: cria entry na Coluna Repertório (artigo longo com obra
+ *     do acervo como lente). column="repertorio", format="pop-article".
+ */
+const quoteImageRef = z.object({
+    url: z.string(),
+    alt: z.string(),
+    caption: z.string().optional(),
+    credit: z.string().optional(),
+    license: z.string().optional(),
+});
+const quotePayload = z.object({
+    text: z.string(),
+    author: z.string(),
+    authorWikidataId: z.string().optional(),
+    sourceWork: z.string().optional(),
+    sourceUrl: z.string().optional(),
+    year: z.number().optional(),
+    page: z.string().optional(),
+    originalLang: z.string().optional(),
+    translation: z.string().optional(),
+    translator: z.string().optional(),
+    license: z.string().optional(),
+    referenceImage: quoteImageRef.optional(),
+    flowImage: z
+        .object({
+        url: z.string(),
+        alt: z.string(),
+        caption: z.string().optional(),
+        prompt: z.string().optional(),
+        model: z.string().optional(),
+    })
+        .optional(),
+});
+const popReferencePayload = z.object({
+    featuredItemId: z.string(),
+    relatedItemIds: z.array(z.string()).optional(),
+    lensTheme: z.string().optional(),
+});
+const educativeReferencePayload = z.object({
+    sourceLessonId: z.string().describe("lessons:_id da aula fonte"),
+    sourceCourseSlug: z.string().optional(),
+    sourceModuleId: z.string().optional(),
+    angle: z.string().optional().describe("fundamento, case, objecao, exemplo…"),
+    partNumber: z.number().optional(),
+    totalParts: z.number().optional(),
+});
+export const quotePopSchema = z.object({
+    action: z.enum(["publish_quote", "publish_pop", "publish_educativo"]),
+    // Comuns
+    slug: z.string().describe("kebab-case único"),
+    title: z.string(),
+    excerpt: z.string().optional(),
+    content: z.string().describe("Markdown completo do artigo/comentário."),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("Tags. Pra publish_quote, 'sapiens-column' é adicionada automaticamente se faltar."),
+    thumbnailUrl: z.string().optional(),
+    generatedBy: z
+        .string()
+        .optional()
+        .describe("Marker do gerador (ex: 'claude-opus-4.7-max:sapiens-quote-skill'). Default genérico se omitido."),
+    publishNow: z
+        .boolean()
+        .optional()
+        .describe("Default false (cria como draft). True publica direto sem passar por curation."),
+    // Quote-specific
+    tldr: z.string().optional(),
+    category: z.string().optional().describe("Default 'filosofia-tech' pra quote, 'repertorio' pra pop"),
+    format: z
+        .string()
+        .optional()
+        .describe("Pra publish_quote: 'short' (200-600 palavras) ou 'essay' (>600). Default 'short'."),
+    readingTimeMinutes: z.number().optional(),
+    connectedSlugs: z.array(z.string()).optional(),
+    quote: quotePayload
+        .optional()
+        .describe("Obrigatório pra publish_quote."),
+    overwrite: z
+        .boolean()
+        .optional()
+        .describe("Pra publish_quote: se draft com mesmo slug existe (status='draft', column='sapiens'), apaga e recria. Não sobrescreve published."),
+    // Pop-specific
+    popReference: popReferencePayload
+        .optional()
+        .describe("Obrigatório pra publish_pop. featuredItemId vem de sapiens_repertorio."),
+    // Educativo-specific
+    educativeReference: educativeReferencePayload
+        .optional()
+        .describe("Obrigatório pra publish_educativo. sourceLessonId vem da query lms:listLessonsForBlogPicker."),
+});
+export async function quotePop(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "publish_quote") {
+        if (!args.quote) {
+            throw new Error("publish_quote exige campo 'quote' (objeto).");
+        }
+        const tags = args.tags ?? [];
+        const result = await convexMutation("mcpExtras:mcpPublishQuote", {
+            sessionToken,
+            slug: args.slug,
+            title: args.title,
+            excerpt: args.excerpt,
+            tldr: args.tldr,
+            content: args.content,
+            category: args.category ?? "filosofia-tech",
+            tags,
+            format: args.format ?? "short",
+            readingTimeMinutes: args.readingTimeMinutes,
+            connectedSlugs: args.connectedSlugs,
+            quote: args.quote,
+            thumbnailUrl: args.thumbnailUrl,
+            generatedBy: args.generatedBy ?? "mcp-sapiens:quote",
+            overwrite: args.overwrite,
+            publishNow: args.publishNow,
+        });
+        return result;
+    }
+    if (args.action === "publish_pop") {
+        if (!args.popReference) {
+            throw new Error("publish_pop exige popReference { featuredItemId, relatedItemIds?, lensTheme? }.");
+        }
+        const result = await convexMutation("mcpExtras:mcpPublishPopArticle", {
+            sessionToken,
+            slug: args.slug,
+            title: args.title,
+            excerpt: args.excerpt,
+            content: args.content,
+            tags: args.tags,
+            thumbnailUrl: args.thumbnailUrl,
+            popReference: args.popReference,
+            generatedBy: args.generatedBy ?? "mcp-sapiens:pop",
+            publishNow: args.publishNow,
+        });
+        return result;
+    }
+    if (args.action === "publish_educativo") {
+        if (!args.educativeReference) {
+            throw new Error("publish_educativo exige educativeReference { sourceLessonId, angle?, partNumber?, totalParts? }.");
+        }
+        const result = await convexMutation("mcpExtras:mcpPublishEducativo", {
+            sessionToken,
+            slug: args.slug,
+            title: args.title,
+            excerpt: args.excerpt,
+            tldr: args.tldr,
+            content: args.content,
+            category: args.category,
+            tags: args.tags,
+            thumbnailUrl: args.thumbnailUrl,
+            readingTimeMinutes: args.readingTimeMinutes,
+            educativeReference: args.educativeReference,
+            generatedBy: args.generatedBy ?? "mcp-sapiens:educativo",
+            publishNow: args.publishNow,
+        });
+        return result;
+    }
+}

package/dist/tools/repertorio.js

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import { convexMutation, convexQuery, getSessionToken, } from "../convexClient.js";
+/**
+ * Acesso ao Repertório do Sapiens (acervo pessoal de filme/série/anime/jogo).
+ *
+ * Reads (v1.0): list, search, get, lists, popArticles. Sem auth necessária —
+ * só vê items públicos (isPublic !== false).
+ *
+ * Mutations (v1.1+): add_item, update_item, remove_item. Usam sessionToken
+ * e exigem admin (consistente com `requireMcpAdmin`). Ownership: tudo vai
+ * pro userId da sessão (o user logado). Caller NÃO escolhe pra quem
+ * adicionar.
+ *
+ * Action-based design (memoria: consolidar tools via args).
+ */
+const mediaTypeEnum = z.enum(["movie", "series", "anime", "game"]);
+const statusEnum = z.enum([
+    "backlog",
+    "active",
+    "completed",
+    "paused",
+    "dropped",
+]);
+const sourceEnum = z.enum(["tmdb", "anilist", "rawg", "manual"]);
+export const repertorioSchema = z.object({
+    action: z.enum([
+        "list",
+        "search",
+        "get",
+        "lists",
+        "popArticles",
+        "add_item",
+        "update_item",
+        "remove_item",
+    ]),
+    // Reads
+    userId: z
+        .string()
+        .optional()
+        .describe("users:_id (obrigatório pra list/search/lists). Descobre via sapiens_meta action=whoami."),
+    itemId: z
+        .string()
+        .optional()
+        .describe("repertorioItems:_id (obrigatório pra get/update_item/remove_item)."),
+    query: z.string().optional().describe("Texto pra action=search."),
+    mediaType: mediaTypeEnum.optional(),
+    status: statusEnum.optional(),
+    limit: z.number().int().positive().max(500).optional().default(100),
+    // add_item — todos os campos do schema repertorioItems user-side
+    source: sourceEnum
+        .optional()
+        .describe("Pra add_item: 'tmdb'/'anilist'/'rawg' se vem de provider externo; 'manual' pra entry hand-rolled (gere externalId único via UUID)."),
+    externalId: z
+        .string()
+        .optional()
+        .describe("Pra add_item: ID externo (tmdb/anilist/rawg) ou UUID se source='manual'. Dedup por (userId, source, externalId)."),
+    title: z.string().optional(),
+    titleOriginal: z.string().optional(),
+    year: z.number().optional(),
+    posterUrl: z.string().optional(),
+    backdropUrl: z.string().optional(),
+    overview: z.string().optional(),
+    genres: z.array(z.string()).optional(),
+    runtimeMin: z.number().optional(),
+    platforms: z.array(z.string()).optional(),
+    studios: z.array(z.string()).optional(),
+    rating: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("0-10. Pra update_item: passe null pra remover rating."),
+    tags: z.array(z.string()).optional(),
+    note: z.string().optional().describe("Nota pessoal sobre a obra."),
+    containsSpoilers: z.boolean().optional(),
+    isPublic: z.boolean().optional(),
+    imdbId: z.string().optional(),
+    tmdbId: z.number().optional(),
+    traktId: z.number().optional(),
+    anilistId: z.number().optional(),
+});
+function need(value, name) {
+    if (value === undefined || value === null) {
+        throw new Error(`Faltando arg "${name}" pra essa action.`);
+    }
+    return value;
+}
+export async function repertorio(args) {
+    // popArticles: sem auth necessário (lê públicos)
+    if (args.action === "popArticles") {
+        const articles = await convexQuery("popArticles:listPublishedPopArticles", { limit: args.limit });
+        return {
+            count: Array.isArray(articles) ? articles.length : 0,
+            articles: (articles || []).map((a) => ({
+                slug: a.slug,
+                title: a.title,
+                excerpt: a.excerpt,
+                lensTheme: a.lensTheme,
+                publishedAt: a.publishedAt,
+                url: `/articles/${a.slug}`,
+            })),
+        };
+    }
+    // Mutations: sempre exigem sessionToken
+    if (args.action === "add_item" ||
+        args.action === "update_item" ||
+        args.action === "remove_item") {
+        const sessionToken = getSessionToken();
+        if (args.action === "add_item") {
+            return await convexMutation("mcpExtras:mcpAddRepertorioItem", {
+                sessionToken,
+                mediaType: need(args.mediaType, "mediaType"),
+                source: need(args.source, "source"),
+                externalId: need(args.externalId, "externalId"),
+                title: need(args.title, "title"),
+                titleOriginal: args.titleOriginal,
+                year: args.year,
+                posterUrl: args.posterUrl,
+                backdropUrl: args.backdropUrl,
+                overview: args.overview,
+                genres: args.genres,
+                runtimeMin: args.runtimeMin,
+                platforms: args.platforms,
+                studios: args.studios,
+                status: args.status,
+                rating: args.rating === null ? undefined : args.rating,
+                tags: args.tags,
+                note: args.note,
+                isPublic: args.isPublic,
+                imdbId: args.imdbId,
+                tmdbId: args.tmdbId,
+                traktId: args.traktId,
+                anilistId: args.anilistId,
+            });
+        }
+        if (args.action === "update_item") {
+            return await convexMutation("mcpExtras:mcpUpdateRepertorioItem", {
+                sessionToken,
+                itemId: need(args.itemId, "itemId"),
+                status: args.status,
+                rating: args.rating,
+                tags: args.tags,
+                note: args.note,
+                containsSpoilers: args.containsSpoilers,
+                isPublic: args.isPublic,
+            });
+        }
+        if (args.action === "remove_item") {
+            return await convexMutation("mcpExtras:mcpRemoveRepertorioItem", {
+                sessionToken,
+                itemId: need(args.itemId, "itemId"),
+            });
+        }
+    }
+    // Reads que exigem userId
+    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"),
+        });
+        if (!item)
+            return { error: "not found" };
+        return slimItem(item);
+    }
+    // list / search
+    const queryArgs = { userId: args.userId, limit: args.limit };
+    if (args.mediaType)
+        queryArgs.mediaType = args.mediaType;
+    if (args.status)
+        queryArgs.status = args.status;
+    const items = await convexQuery("repertorio:listByUser", queryArgs);
+    let filtered = items || [];
+    if (args.action === "search" && args.query?.trim()) {
+        const q = args.query.toLowerCase();
+        filtered = filtered.filter((it) => (it.title || "").toLowerCase().includes(q) ||
+            (it.titleOriginal || "").toLowerCase().includes(q) ||
+            (it.genres || []).some((g) => g.toLowerCase().includes(q)) ||
+            (it.tags || []).some((t) => t.toLowerCase().includes(q)));
+    }
+    return {
+        count: filtered.length,
+        items: filtered.map(slimItem),
+    };
+}
+function slimItem(it) {
+    return {
+        _id: it._id,
+        title: it.title,
+        titleOriginal: it.titleOriginal,
+        year: it.year,
+        mediaType: it.mediaType,
+        genres: it.genres || [],
+        tags: it.tags || [],
+        rating: it.rating,
+        note: it.note,
+        status: it.status,
+        posterUrl: it.posterUrl,
+        source: it.source,
+        externalId: it.externalId,
+    };
+}