# Marketing Decks — Master Implementation Guide (LLM-Ready) > Apresentações com IA e com a marca da conta: de uma frase, de um texto, de > um arquivo ou de um endereço a um deck em cards, editado num editor de cards, > apresentado pelo navegador e exportado para PDF, PNG e PowerPoint a partir > do **mesmo desenho**. A geração roda no servidor, e toda edição feita por IA > deixa uma versão para voltar. "O agente edita. Abrir o link e apagar são de > gente." > > Este arquivo é a documentação para agentes. **Leia a seção 9 antes de > prometer qualquer coisa**: ela diz o que o produto não faz. Worker (API, link público, MCP): https://decks.worker.mymarketing.click Painel: https://decks.dashboard.mymarketing.click Servidor MCP: https://decks.worker.mymarketing.click/mcp — ver a seção 7. O mapa da linha (todos os produtos, login): https://mymarketing.click/llms.txt ## 0. Estado e credenciais — leia antes de tudo - **No ar desde 14/10/2026; na linha Marketing desde o início.** `GET https://decks.worker.mymarketing.click/status` responde `{"service":"marketing-decks",…}` com as promessas do produto e o estado do banco, da fila, das mídias, dos modelos e do desenho dos arquivos. Confira o `/status` antes de prometer que algo funciona agora. - **Login:** o Auth da linha (`https://auth.worker.mymarketing.click`, aplicação Marketing), com código por e-mail. Mesmo login, autorização por produto. Passo humano obrigatório: a pessoa lê um código no e-mail e o informa. Não tente contornar. - **Chave da conta:** `dk_…`, mostrada uma vez, para sistemas (`Authorization: Bearer dk_…`). **É recusada no `/mcp`**, e as rotas de abrir o link público e de apagar um deck a recusam: são da sessão de uma pessoa. - **Preço:** não há preço público e nada é cobrado. Não cite valor, plano, franquia em minutos nem "grátis". Se perguntarem: "Ainda não há planos, e nada é cobrado." ## 1. Modelo mental - **Deck** — tem número (vai no endereço), título, formato, tema, cards e estado: `draft`, `outlining`, `generating`, `ready`, `failed`. Um deck da conta pode ser marcado como modelo e duplicado. - **Card** — um documento de blocos: título, parágrafo, listas, citação, destaque (5 tipos), código, imagem, botão, colunas (2 a 4), tabela, incorporação (YouTube, Vimeo, Loom, Figma ou endereço), gráfico e layout inteligente. Imagem de destaque à esquerda, à direita, em cima ou de fundo. Notas do apresentador. - **Layout inteligente** — 11 famílias: caixas, tópicos, ícones, imagens, linha do tempo, setas, números, degraus, pirâmide (e funil), ciclo (e quadrantes) e citações. Trocar o layout não mexe no texto dos itens. - **Gráfico** — 8 tipos: barras, colunas, colunas empilhadas, linha, área, pizza, rosca e funil, desenhados em SVG. - **Formatos** — `presentation` (16:9, padrão, ou 4:3, em slide fixo), `document` (largura fixa, altura livre, ou A4), `webpage` e `social` (4:5, 1:1 ou 9:16). - **Tema** — 12 padrão (`standard:`) e os da conta (`custom:`). Um tema da conta pode ser a marca: todo deck novo nasce com ele. ## 2. Gerar — do pedido ao deck - **De onde:** uma frase; um texto colado, em três modos (`generate` desenvolve a ideia, `condense` resume, `preserve` mantém o texto e o divide em cards); um arquivo (PDF, DOCX, PPTX, TXT, MD; até 20 MB; o tipo é lido dos bytes); ou o endereço de uma página. PDF escaneado não é lido: peça o texto colado. - **Esboço antes de gerar:** `POST /api/outline` responde em SSE, card por card, com título, de 1 a 5 itens e a ideia da imagem. A pessoa edita e só então gera. De 1 a 60 cards. - **Geração no servidor:** `POST /api/generate` cria o deck e um trabalho na fila (`job`). Fechar a aba não para nada; os cards são gravados um a um, e as imagens vêm depois do texto. Acompanhe por `GET /api/jobs/:id`. - Na apresentação, o que não cabe no slide é avisado, nunca cortado em silêncio. ## 3. Editar — a IA no card e o Agent - **IA num card:** `POST /api/decks/:ref/cards/:cardId/ai` com uma de 15 ações (`improve`, `grammar`, `shorter`, `longer`, `simplify`, `specific`, `bullets`, `sections`, `summary`, `translate`, `visualize`, `new_layout`, `custom`, `split`, `fit`). Pela API, a resposta é uma **proposta**: nada é aplicado até alguém salvar. Pelo MCP (`decks_edit_card`), a edição é aplicada e a versão anterior fica guardada. - **Agent:** uma conversa por deck (`POST /api/decks/:ref/agent`) que lê, reescreve, insere, apaga e move cards, troca o tema, gera imagem para um card, traduz o deck, lê um endereço dado e **pesquisa na web, com as fontes** (título e endereço). Todo pedido deixa uma versão para voltar. A conversa **não tem limite de tamanho**: passadas 16 mensagens, as antigas viram um resumo. Até 4.000 caracteres por mensagem. - **Versões:** uma a cada geração, a cada pedido ao Agent, a cada edição de IA pelo MCP e a cada restauração; versões manuais com nome; uma automática a cada 30 minutos de edição. Passando de 100 por deck, as mais antigas automáticas e de IA saem primeiro. - **Salvar é otimista:** o `PATCH` leva a versão lida (`expectedVersion`); uma edição por cima de outra responde conflito. Não há edição simultânea. ## 4. A marca - 12 temas padrão e os da conta: cores, fontes, cantos, sombra, borda, botões, densidade, escala da fonte e logo. - Fonte própria: WOFF2, WOFF, TTF ou OTF, até 2 MB (`POST /api/fonts`). - `POST /api/themes/import` com o endereço do site: devolve logo, cores e fontes encontradas, **sem salvar**. - **A cor da marca nunca é trocada sem a pessoa mandar.** O contraste é conferido (WCAG) e volta com uma sugestão; a cor salva é a escolhida. - Imagens: geradas por IA, buscadas no Openverse (licença comercial, com o crédito) ou enviadas (PNG, JPEG, WebP, GIF, SVG sem script; até 10 MB). ## 5. Exportar e mostrar - `POST /api/decks/:ref/exports` com `kind`: `pdf`, `png` (um arquivo por card, em zip) ou `pptx`. Os três saem do mesmo desenho, no servidor. O arquivo fica disponível por 7 dias; depois, `410`, e é gerar de novo. - **O PowerPoint:** um slide por card, do tamanho do card; cada bloco de texto é **uma caixa só**, com o texto inteiro e editável (sem palavra repetida na quebra de linha); fundos, bordas e formas viram formas; notas vão para as notas do apresentador. **Os gráficos entram como imagem**: o gráfico editável do PowerPoint está desligado. - **Link público:** `https://decks.worker.mymarketing.click/v/:publicId` para rolar e `?present=1` para apresentar, quando uma pessoa abre o deck para quem tem o link. Prévia do link em `/v/:publicId/og.png`. O dono escolhe se o PDF pode ser baixado e se a busca pode indexar. Fechado, apagado e inexistente respondem o mesmo `404`. - **Leitura do link:** segundos por card e alcance, por visitante do dia, nos últimos 30 dias (`GET /api/decks/:ref/analytics`). Sem cookie: o visitante é um hash com chave do dia, do IP e do navegador. ## 6. Rotas Base: `https://decks.worker.mymarketing.click`, sem versão no caminho, com a sessão do painel ou a `dk_`. Coleções respondem `{items, page}`; erros, `{error: {code, message}}`. `:ref` é o número do deck ou o id. ``` GET /status o serviço e as promessas dele GET /api/decks · POST /api/decks os decks; POST cria um deck em branco GET /api/decks/:ref · PATCH · DELETE um deck (DELETE só a sessão) POST /api/decks/:ref/duplicate duplica POST /api/decks/:ref/template { isTemplate } marca como modelo POST /api/outline o esboço, em SSE POST /api/generate cria o deck e começa a geração → {deck, job} GET /api/jobs/:id · POST …/cancel um trabalho POST /api/decks/:ref/cards/:cardId/ai { action } → a proposta POST /api/decks/:ref/agent · GET o Agent e a conversa GET /api/decks/:ref/snapshots · POST as versões POST /api/decks/:ref/snapshots/:id/restore volta a uma versão POST /api/decks/:ref/exports · GET os arquivos GET /api/exports/:id/download o arquivo GET /api/decks/:ref/share · PUT o link público (PUT só a sessão) GET /api/decks/:ref/analytics a leitura do link GET /api/themes · POST · GET|PUT|DELETE /api/themes/:id os temas POST /api/themes/:id/default o tema vira a marca da conta POST /api/themes/import a marca a partir de um site GET /api/fonts · POST · DELETE as fontes enviadas POST /api/media · POST /api/media/url as imagens POST /api/import um arquivo para virar deck POST /api/images/generate imagem por IA → job GET /api/images/search?q imagens do Openverse GET /api/keys · POST · DELETE a chave dk_ (só a sessão) GET /api/agents os agentes que usaram a conta GET /v/:publicId o deck aberto, para quem tem o link ``` ## 7. Servidor MCP - **Endereço:** `https://decks.worker.mymarketing.click/mcp` (Streamable HTTP), para a conta inteira — a conta vem do token, nunca de um argumento. - **OAuth 2.1:** metadados em `https://decks.worker.mymarketing.click/.well-known/oauth-protected-resource`. O token só vale para este servidor. A `dk_` é recusada. - São 8 ferramentas, todas **Livre**: criar e editar são livres porque toda edição de IA deixa uma versão para voltar, e nada do que o agente faz sai da conta. Não há ferramenta **Confirma**. | Tool | Regra | O que faz | |---|---|---| | `decks_list` | Livre | os decks da conta, com título, número de cards e estado | | `decks_get` | Livre | um deck: os cards em texto, o tema e o link público quando houver | | `decks_list_themes` | Livre | os temas padrão e os da conta, com o da marca marcado (`isDefault`) | | `decks_create` | Livre | gera um deck de uma frase ou de um texto (`mode`, `cards`, `format`, `themeId`) | | `decks_edit_card` | Livre | uma ação de IA num card, aplicada; a versão anterior fica | | `decks_ask_agent` | Livre | um pedido ao Agent do deck; a versão anterior fica | | `decks_export` | Livre | PDF, PowerPoint ou PNG; o resultado traz um endereço assinado que vale 24 h | | `decks_get_job` | Livre | acompanha uma geração, um pedido ao Agent ou uma exportação | | `decks_share` · `decks_delete` | Só humano | **não são registradas**: abrir o link público e apagar são de uma pessoa | O painel lista os agentes que usaram a conta, e "Desconectar" faz o servidor recusar as chamadas deles. ## 8. Eventos **O Decks não manda nem recebe eventos.** Não há webhooks nem `POST /events/:sourceId`. Para saber quando uma geração terminou, acompanhe o trabalho (`GET /api/jobs/:id` ou `decks_get_job`). ## 9. Escopo — o que este produto NÃO faz - **Gráfico editável no PowerPoint.** O gráfico entra como imagem. - **Exportar para o Google Slides.** - **Domínio próprio ou senha no link do deck.** Para uma página no domínio da conta, a linha tem o Pages. - **Comentários e edição ao mesmo tempo por várias pessoas.** - **Controle remoto do apresentador.** - **Publicar em rede social.** O formato social gera o card na medida. - **Galeria de modelos prontos.** Os modelos são os decks que a conta marcou. - **Ler PDF escaneado.** - **Cobrança.** Não há plano publicado, e nada é cobrado. ## 10. Checklist para agentes de IA 1. **Gere com `decks_create` e acompanhe com `decks_get_job`;** a geração continua no servidor. 2. **Use o tema da marca** (`decks_list_themes`, `isDefault`) quando a pessoa não disser outro. 3. **Não prometa gráfico editável no PowerPoint.** 4. **Não tente abrir o link nem apagar:** são de uma pessoa, no painel. 5. **Não invente rota nem tool.** A seção 6 lista as rotas; a 7, as tools.