# Conectar um agente ao OverOne

Endpoint: **https://www.dtfchat.com.br/api/mcp**. Transporte: MCP Streamable HTTP, respostas JSON, sem sessão persistente de transporte. Autenticação: OAuth Authorization Code + PKCE S256, registro dinâmico e refresh token. A organização autorizada usa Nuvem por padrão; não depende de aba aberta.

## Acompanhar o Canvas na prévia do cliente

Ao conectar e no início de cada pedido, confira se o Canvas do projeto está aberto na **prévia/navegador integrado visível** do aplicativo de IA. Abra ou reutilize a aba antes de uma operação paga, **inclusive quando o saldo não permitir gerar**, quando o cliente oferecer navegação para sites externos e as preferências do usuário permitirem. O MCP fornece `interface_projeto` com o link e a orientação; a abertura depende das ferramentas do cliente. `conexao.navegador` indica o executor canvas e não comprova que a prévia está aberta.

1. Consulte a conexão e selecione ou crie o projeto desta conversa. Na lista, use `projetos[].url_canvas` do projeto escolhido; na criação, use `interface_projeto.url_canvas`, que aponta para o projeto novo. O link é `/c/ID?view=canvas` sem credenciais. Nas próximas respostas, confira se `interface_projeto.projeto_id` corresponde ao projeto desta conversa antes de abrir. Uma consulta sem `projeto_id` pode trazer o padrão de outra conversa. Em respostas antigas, use `contexto_atual.projeto.url_canvas` ou `projeto.url` e selecione Canvas pela interface. Confira nome e organização, sem trocar o projeto padrão da conexão para abrir a prévia.
2. Reutilize a aba desse projeto e mantenha-a disponível ao usuário. Não abra outra aba a cada chamada, não recarregue sem necessidade e não altere zoom/seleção enquanto o usuário interage. Respeite uma preferência por trabalhar sem prévia.
3. Se aparecer login, deixe a página aberta para o usuário entrar. OAuth do MCP e sessão do site são acessos distintos; o navegador integrado pode não compartilhar a sessão do navegador padrão. Não copie cookies ou tokens nem peça senha no chat. **Login com Google costuma não funcionar em navegador integrado** (ex.: prévia do Claude): oriente entrar com **e-mail e senha**. Quem criou a conta pelo Google cria a senha no site em Perfil → “Criar senha para entrar com E-mail” (ou em “esqueci” na tela de login). Após entrar, volte ao link do projeto se necessário. Se a organização ativa for outra, selecione a autorizada na interface.
4. Mantenha **headless** para executar na nuvem enquanto o Canvas mostra os arquivos salvos. Abrir a prévia não requer `overone_modo({modo:"canvas"})`: esse comando muda o executor para a aba, e deve ser reservado a tarefas que precisem desse modo.
5. Confira o estado e o #N quando possível. Ao concluir, incorpore a imagem na conversa também; a prévia não substitui a entrega. Só diga que houve atualização ao vivo se a observou. Antes de atualizar uma página parada, confirme a tarefa e preserve as edições em andamento.
6. Se a tela exigir uma ação do usuário, mantenha-a visível e aguarde. A disponibilidade e as opções de continuidade são apresentadas pelo próprio OverOne. Não efetue compras nem clique em assinatura ou recarga pelo usuário. Após uma mudança de saldo, consulte `overone_saldo` antes de retomar; não repita uma operação já aceita.

Se não houver navegador integrado compatível, apresente **Abrir Canvas do projeto** como link clicável e continue headless quando possível. Uma prévia limitada a apps locais ou um iframe bloqueado não serve como navegador autenticado. Codex, Claude e outros clientes têm ferramentas e políticas próprias: confira os recursos disponíveis, sem prometer que o servidor MCP abrirá uma janela em todos eles.

O link do Canvas **não autentica nem concede acesso**: o OverOne continua exigindo login e as permissões do projeto. As instruções completas ficam em `overone_guia.previa_ao_vivo`, anunciadas no resumo de inicialização do MCP.

## Apresentar o link de conexão ao usuário

1. Inicie a conexão no cliente MCP e obtenha uma URL de autorização real.
2. Mostre um link clicável: **Conectar minha conta OverOne**.
3. Oriente: “Abra no navegador em que sua conta está logada, escolha a organização e autorize as permissões. Depois volte a esta conversa.”
4. Espere o callback e confirme por uma chamada MCP antes de anunciar sucesso.

O link contém client_id, callback e desafio PKCE daquele cliente. Não existe um link universal que conecte qualquer chat. A página `/mcp` é um guia/painel; abri-la sozinha não conecta um agente. Não reutilize links de outra sessão e não peça senha, código ou token no chat.

## Clientes com MCP OAuth integrado

Adicione o endpoint como servidor MCP remoto nas configurações do cliente e use conectar/autenticar. O aplicativo administra callback, PKCE e tokens. Se abrir outro navegador, apresente a mesma URL de autorização para o usuário abrir no navegador de preferência.

A LLM precisa de um aplicativo ou ambiente com suporte a MCP/HTTP e OAuth. Ler este documento num chat sem essas capacidades não instala um conector: explique essa limitação e oriente a adicionar o servidor nas configurações do aplicativo.

## Agentes locais com Node e HTTP

Cliente de exemplo: https://www.dtfchat.com.br/mcp-oauth-client.mjs — Node 22+, sem dependências externas. Baixe e inspecione antes de executar. Ele mantém PKCE/tokens em memória e recebe o callback em 127.0.0.1. Execute em processo persistente **no computador em que o usuário abrirá o navegador**. Agentes em nuvem precisam de seu próprio callback HTTPS; o loopback remoto não aponta para o computador do usuário.

```js
import {startOAuthLink} from './mcp-oauth-client.mjs';
const login = await startOAuthLink({
  clientName: 'Meu agente · OverOne', scopes: ['read', 'create']
});
console.log(login.authorizationUrl); // apresente como link clicável imediatamente
// Mantenha o processo vivo enquanto o usuário autoriza.
while (login.status() === 'waiting') await new Promise(r => setTimeout(r, 1000));
if (login.status() !== 'connected') throw Error('Autorização não concluída');
await login.initialize();
const connection = await login.call('overone_conexao');
const balance = await login.call('overone_saldo');
const projects = await login.call('overone_listar_projetos');
// Continue usando a mesma instância login. Não imprima credenciais.
```

O callback espera até 20 minutos. Encerrar o processo antes da autorização torna o retorno indisponível; gere outro link. `login.close()` encerra o cliente local, sem revogar o acesso no servidor. O usuário revoga em `/mcp` → Suas conexões. A autorização dura até sete dias; refresh mantém o token de acesso válido dentro desse período. Não renova assinatura nem créditos.

## Implementar em outro cliente

- Protected resource metadata: `https://www.dtfchat.com.br/.well-known/oauth-protected-resource/api/mcp`.
- Authorization server metadata: `https://www.dtfchat.com.br/.well-known/oauth-authorization-server/oauth`.
- Issuer: `https://www.dtfchat.com.br/oauth`.
- Registre no `registration_endpoint`, com `client_name`, `redirect_uris`, `token_endpoint_auth_method: none`; use o `client_id` recebido.
- Guarde um `code_verifier` aleatório, crie o desafio S256 e um `state` aleatório por solicitação.
- Monte o `authorization_endpoint` com `response_type=code`, `client_id`, `redirect_uri`, `resource=https://www.dtfchat.com.br/api/mcp`, `scope`, `state`, `code_challenge_method=S256`, `code_challenge`.
- Apresente essa URL ao usuário. Confira `state` e `iss` no callback registrado antes de trocar o código.
- Troque no `token_endpoint`, enviando `grant_type=authorization_code`, `client_id`, `redirect_uri`, `resource`, `code`, `code_verifier`. Envie o access token apenas em `Authorization: Bearer ...` no MCP.
- Token endpoint aceita JSON e formulário URL encoded. Renove com `grant_type=refresh_token`, `client_id`, `resource`, `refresh_token`; guarde o novo refresh token recebido na rotação.

Escopos: `read` para consultas; `create` para projetos e criação/transformação; `store_write` para alterar loja. Solicite somente o necessário. O usuário escolhe permissões na autorização.

## Depois de conectar

Consulte **overone_guia** na primeira interação. O servidor entrega orientações também em `initialize.instructions`, e as respostas incluem `guia_versao`, `projeto` (onde o pedido agiu) e `contexto_atual` com nome e link do projeto do pedido. Diga “Projeto atual: [nome](url)” nas mensagens de trabalho e ao trocar de projeto. Releia o guia quando sua versão mudar. Ao entregar uma tarefa antiga, use o projeto retornado naquela tarefa, que pode ser diferente do atual.

O guia é mantido no servidor: os aprendizados aprovados entram nele e passam a estar disponíveis para todos os clientes. Não é necessário copiar manualmente esta conversa. A seção `direcao_arte` ensina pesquisa, construção do pedido, uso de referências, iluminação e avaliação. É uma receita consultável pelo agente, não treinamento de pesos como um LoRA nem garantia de qualidade. Preferências e imagens privadas de um cliente não são publicadas como instruções globais. Alguns aplicativos mantêm ferramentas em cache ou não expõem as instruções à LLM; nesses casos atualize o catálogo ou reconecte.

## Imagem gerada na própria IA → OverOne

Gere frente e costas como arquivos separados. Para camiseta preta, use **fundo preto sólido**; para camisetas claras/coloridas, use croma uniforme que não exista na arte e depois remova o fundo. **Nunca envie quadriculado desenhado como transparência.** O PNG final DTF pode ter alpha real.

No ChatGPT, use primeiro **overone_importar_imagem** com `projeto_id`, `pedido_id` e `arquivo` da conversa. A ferramenta declara `openai/fileParams`: o ChatGPT fornece `download_url` e `file_id`, e o servidor importa o PNG original sem exigir download/upload manual. Aguarde `ok=true` e `itens`, depois use o `seq` como `#N` em DTF/recorte/mockup. Não invente URLs. Se a referência expirar, obtenha uma nova para o mesmo arquivo e reutilize o pedido. Quando uma falha retornar `upload_id`, consulte `overone_concluir_upload` antes de repetir.

Para clientes com acesso aos bytes e HTTP, o fluxo abaixo continua disponível. O upload não gera outra imagem nem consome uma geração: usa o armazenamento da conta. PNG de até 32 MB, `projeto_id` explícito (o projeto desta conversa) e permissão `create`:

1. Calcule o SHA-256 hexadecimal e o tamanho do arquivo.
2. Chame `overone_preparar_upload` com `projeto_id`, `nome`, `pedido_id`, `tamanho_bytes` e `sha256`.
3. Envie os bytes por `PUT` para `upload.url` com os headers indicados. A URL já é assinada: **não envie OAuth junto e não a exponha ao usuário**.
4. Chame `overone_concluir_upload` com `upload_id` e `projeto_id`. Somente `ok=true` com `itens` confirma que a arte ficou salva. Use o `seq` retornado em DTF, recorte e mockup.

A URL de envio dura 5 minutos, o pedido dura 30 minutos. Repetir a preparação com os mesmos argumentos renova o link; repetir a conclusão retorna o mesmo item. A conclusão usa o projeto do upload (o do preparo): conclua com o mesmo `projeto_id`, mesmo que outra conversa trabalhe em outro projeto; o arquivo não será enviado silenciosamente a outro lugar.

No cliente Node de exemplo já autenticado:

```js
import {readFile} from 'node:fs/promises';
const result = await login.uploadPng(await readFile('/caminho/arte.png'), {
  projeto_id: 'ID retornado pelo OverOne',
  nome: 'Unohana — frente', pedido_id: 'unohana-frente-01'
});
// Confira result.ok e result.itens antes de chamar transformar_em_dtf.
```

O export `importPng(call, bytes, options)` funciona com outros clientes MCP autenticados. Esse fluxo por bytes precisa de leitura do arquivo e envio HTTP; no ChatGPT prefira a ferramenta direta acima; se ele não disponibiliza o arquivo gerado à integração, explique a limitação e peça o anexo no projeto. Nunca afirme que uma imagem local já está no OverOne sem confirmar.

## Referências e receitas de geração

Para encontrar uma imagem de identidade do personagem, siga esta ordem, salvo uma escolha explícita diferente do usuário:

1. Use o **anexo enviado pelo usuário** e inspecione seus traços. Não o substitua automaticamente por uma imagem buscada.
2. Se não houver anexo adequado, procure uma referência já disponível no projeto ou no acervo autorizado.
3. Se ainda faltar, use a **busca web do próprio aplicativo de IA**. Abra a imagem e sua página de origem, confira personagem e qualidade, e obtenha um arquivo realmente acessível. Não invente URLs nem trate uma miniatura da busca como original sem verificar. Na entrega, inclua a página de origem e o crédito do autor quando identificado; não invente autoria ou licença.

O MCP do OverOne não oferece busca web nem um importador de URLs arbitrárias. Se o cliente não tiver busca, use anexo/acervo; no ChatGPT tente a importação direta da referência de arquivo. Só se o cliente não oferecer referência nem leitura/envio dos bytes, explique a limitação e peça o arquivo no projeto. Não anuncie busca ou importação que não executou.

Antes de gerar, **importe cada referência externa no projeto desta conversa pelo fluxo de PNG acima**. JPEG/WebP pode ser convertido para PNG sem redesenhar a imagem. Aguarde `overone_importar_imagem` ou `overone_concluir_upload` retornar `ok=true` e `itens`; só então use o `seq` como referência `#N`. Uma referência já salva no mesmo projeto pode reutilizar seu número. Uma URL encontrada ou um caminho local, por si só, não significa que a imagem está no OverOne.

Separe **identidade**, **acabamento visual**, **composição** e **logo**. Inspecione cada imagem e declare no prompt o que extrair e o que não copiar dela. Em `refs:[9,1]`, a Imagem 1 do prompt é a arte #9 e a Imagem 2 é a #1. Os slots de uma receita do Clonador podem ter outra ordem: respeite a receita escolhida.

**O fundo técnico aplica-se à imagem de saída.** A referência do personagem pode ter cenário, fundo colorido, fotografia ou transparência real; não precisa ser recortada ou colocada sobre preto para servir de identidade. Preserve o arquivo e explique no prompt que o fundo da referência não deve ser copiado quando a saída exigir preto sólido ou croma.

Descreva rosto/cabelo/roupa a preservar; traço, luz, brilho, sombra e textura desejados; pose, hierarquia e paleta; fundo técnico e erros a evitar. Resolva as variáveis antes de enviar o prompt. Confira se todas as referências estão acessíveis e depois compare o resultado com elas. Sucesso técnico não é aprovação estética. Um logo que precisa ser exato deve ser aplicado a partir do arquivo original; geração não garante cópia geométrica.

Quando o usuário indicar uma receita ou resultado que funcionou, identifique o template, as referências ordenadas, o modelo e os parâmetros disponíveis antes de comparar. Se esses dados não estiverem acessíveis, peça o que falta. Não apresente outra receita como reprodução da original.

Preencha cada variável **no contexto da frase completa** e confira a coerência do conjunto: identidade, enquadramento, pose, luz e efeitos. Não basta eliminar os colchetes; o texto final precisa fazer sentido. Preserve o que aparece na referência escolhida, sem acrescentar penteados, acessórios ou marcas apenas por associação ao nome do personagem.

Descreva o acabamento que deseja obter: grupos de mechas, planos de rosto e tecido, variação de linha, hachuras, direção de luz e sombras coloridas quando apropriadas. Uma linguagem gráfica pode conservar volume e iluminação rica. **Preto sólido nas regiões negativas não exige um fundo vazio:** inclua os efeitos temáticos solicitados, com hierarquia e áreas de respiro. Quando o pedido exigir figura isolada e borda limpa, siga esse requisito. Se o usuário mudar essa direção, atualize o prompt; não deixe a regra antiga de ausência de efeitos contradizer a nova composição.

Esses princípios são gerais. Receitas e imagens privadas continuam vinculadas à conta. `gerar` aceita prompt completo com referências; isso não equivale a executar automaticamente uma receita salva do Clonador.

## Pesquisar o tema e construir a direção de arte

Antes de gerar, identifique personagem, obra e versão ou transformação solicitada. Use a busca do **cliente de IA**, quando disponível, para consultar a obra e materiais oficiais do autor ou estúdio. Abra a fonte e inspecione as imagens: o nome de um poder não explica sua aparência. Não misture versões, trajes ou efeitos de personagens distintos. Sem acesso à pesquisa, use os anexos e fontes disponíveis e declare o que não verificou.

Registre a origem e a confiança dos elementos importantes: **observado na referência escolhida**, **confirmado por fonte primária** ou **interpretação criativa**. Uma referência escolhida pelo usuário pode ser uma releitura e continuar definindo a identidade desejada; isso não a transforma em prova de cânone. Inclua as páginas consultadas, sem inventar autoria, licença ou confirmação oficial.

Descreva efeitos por sua construção visual: forma, contorno, material, cor, direção, densidade e relação com a figura. Termos ambíguos podem introduzir objetos errados. Se o efeito for líquido, por exemplo, descreva fluxos sinuosos de tinta; a palavra “correntes” pode produzir elos de metal. Um efeito da imagem de acabamento só deve entrar na nova arte se corresponder ao tema e ao pedido.

Declare a interação entre as referências, além dos seus papéis: “aplique o acabamento da Imagem 2 à identidade da Imagem 1; use da Imagem 3 somente a construção do efeito descrito”. Preserve os números e a ordem realmente enviados. Não copie identidade, acessórios, símbolos ou efeitos da referência de acabamento sem que façam parte da direção escolhida.

Separe **cor própria** de **luz da cena**. Pele ou cabelo iluminados por vermelho não passam a ter vermelho como cor fixa. Preserve a identidade e descreva como suas superfícies recebem a iluminação planejada.

Para conseguir luz e volume, especifique decisões concretas: direção, cor e intensidade relativa da luz principal; áreas que ela revela no rosto e no tecido; forma e borda das sombras; fonte e posição de reflexos ou recorte quando apropriados. Defina contornos externos, linhas internas, espessuras e agrupamento de mechas. Hachuras acompanham o volume e se concentram onde são necessárias. Corrigir fidelidade não exige apagar contraste ou simplificar a iluminação; mais resolução também não corrige esses problemas por si só.

## Nova geração e edição são decisões diferentes

**Toda nova geração, tentativa ou variação começa nas referências originais** de identidade, acabamento e composição selecionadas para aquele pedido. Uma tentativa que falhou serve para diagnosticar o problema e ajustar o prompt; não vira automaticamente a referência da próxima. Usar repetidamente o último resultado acumula mudanças de rosto, luz e elementos do tema.

**A edição parte de um resultado quando o usuário disser que gostou/aprovar e pedir uma alteração nele.** Identifique o #N aprovado, o que muda e o que deve permanecer. Mantenha as originais disponíveis para conferir identidade e acabamento. A avaliação positiva do agente, sozinha, não promove uma tentativa à base de edição. Se a base pedida estiver ambígua, esclareça antes de gastar.

“Edição” descreve a intenção do pedido: em `gerar`, ela usa prompt e referências e produz um novo item. Isso não anuncia uma ferramenta dedicada de edição, não sobrescreve automaticamente o original nem garante preservação pixel a pixel fora da alteração. Confira o resultado antes de afirmar que apenas a região pedida mudou.

Mantenha uma ficha curta no contexto privado do trabalho ou em arquivo privado autorizado:

| Campo | Conteúdo |
| --- | --- |
| Projeto e objetivo | ID, nome, URL, uso da arte, modelo e parâmetros |
| Tema e fontes | Obra/versão, elementos observados, fatos confirmados, interpretações e confiança |
| Referências originais | #N, ordem, origem, papel, o que usar e o que não copiar |
| Identidade | Rosto, cabelo, proporções, roupa, marcas e cor própria, separados da luz observada |
| Direção | Pose, composição, paleta, plano de luz, acabamento, efeitos e fundo técnico |
| Regras | Escolhas ativas e instruções substituídas pelo usuário, com motivo |
| Tentativas | tarefa/pedido_id, #N, custo informado, avaliação, decisão do usuário e resultado aprovado, se houver |

Consulte e atualize essa ficha a cada tentativa. Remova instruções substituídas do prompt ativo; guarde o histórico para impedir que o erro reapareça. O MCP não salva essa ficha automaticamente e este guia não acrescenta uma ferramenta de memória. Dados e referências particulares permanecem privados.

## Comparar sem perder os acertos

Exiba o resultado e compare com as referências originais e a referência de qualidade. Avalie separadamente:

- **Identidade:** rosto, olhos, cabelo, proporções, roupa e marcas reconhecíveis.
- **Acabamento:** iluminação, contraste, volume, desenho, hachuras e densidade.
- **Anatomia e objetos:** mãos, corpo, armas e acessórios, incluindo pequenos fragmentos.
- **Composição e tema:** hierarquia, equilíbrio, efeitos pertinentes e ausência dos motivos rejeitados.
- **Arquivo:** fundo, bordas, dimensões e persistência no projeto.

Registre evidências concretas. Um rosto mais fiel com iluminação inferior ainda não atingiu a referência de qualidade; uma composição bonita com outra identidade também não. Confirme toda a imagem, não apenas a área que pretendia corrigir. Resultado técnico concluído não significa aprovação estética.

Se precisar de outra tentativa, ajuste as causas na ficha e no prompt e volte às originais, dentro da autorização de iteração. Consulte saldo e custo, registre as tentativas e confira falhas/estornos pelos dados disponíveis. Não repita uma operação paga para recuperar o arquivo nem continue indefinidamente sem progresso; explique a limitação e a próxima mudança fundamentada.

## Mostrar a cota

Nas mensagens ao usuário, apresente somente a **porcentagem restante da cota semanal**, usando `conta.cota_semanal.percentual_restante`. Exemplo de formato: “Cota semanal: 27,49% restante”. Não mostre quantidades de créditos, saldos absolutos, bônus ou custos em créditos. Os números técnicos retornados pelo MCP servem à conferência interna de disponibilidade e cobrança.

Esse percentual não inclui bônus nem saldo promocional. Não some esses saldos ao percentual nem invente uma porcentagem total. Se a cota semanal chegar a 0% e ainda houver saldo extra utilizável, diga “Cota semanal: 0%. Há saldo extra disponível”, sem quantidade. Percentual ausente significa indisponível, não 0%.

Antes de uma operação paga, consulte `overone_saldo` e confira a disponibilidade real. **0% semanal sozinho não significa bloqueio:** se houver bônus ou saldo promocional utilizável, explique que há saldo extra disponível. Se cota e saldo extra não cobrirem a operação, informe a insuficiência sem oferecer compra. Bônus bloqueado não é bônus esgotado. Informe renovação ou restrição de plano somente quando confirmadas nos dados.

A integração usa os direitos já disponíveis na conta. Não ofereça recarga, assinatura, upgrade, planos comerciais ou links que iniciem compras digitais. Use apenas `conta.url_informacoes`, uma página informativa sem checkout. Para bloqueio da conta, oriente suporte; falhas de permissão, conexão ou execução não significam falta de saldo. Não repita uma operação paga automaticamente. Se o usuário informar uma mudança na conta, consulte o saldo novamente antes de retomar.

## Mostrar os resultados

**Entregue cada imagem no corpo da mensagem do assistente assim que sua tarefa concluir**, sem esperar o lote inteiro e sem depender de o agente abrir a imagem para inspeção. Use uma imagem incorporada em Markdown com a URL real retornada (`![Resultado #N](URL_DA_IMAGEM)`) ou o caminho absoluto do arquivo local, quando o cliente permitir. Inclua #N, modelo/operação e nome e link do projeto. Uma chamada `view_image`, miniatura de ferramenta, aviso de sucesso ou link para o projeto **não substitui a imagem na mensagem**.

Exiba cada item de uma resposta com várias imagens; uma consulta repetida da mesma tarefa não deve duplicar a entrega. Se o cliente não permitir incorporar a imagem, use seu recurso de apresentação de mídia. Como último recurso, forneça um link utilizável e explique a limitação. Não invente caminhos ou URLs. Links assinados expiram: consulte a arte novamente quando necessário.

Mostre as imagens na conversa e inclua o link do projeto e os números #N. Identifique modelo, frente/costas, tamanho e se houve retícula. `tarefa.id` é um recibo de andamento, não uma imagem pronta. Confira o arquivo e a persistência antes de afirmar que terminou. A assinatura do gerador externo e os créditos do OverOne são cobranças diferentes.

Leia `tools/list`. Consulte `overone_conexao` e `overone_saldo`; use `overone_listar_projetos` (ou `overone_criar_projeto`) para achar o projeto desta conversa e mande `projeto_id` em todo pedido — e `loja` nas ferramentas de loja. `overone_abrir_projeto` só muda o projeto padrão de todas as conversas da conexão. Havendo homônimos, peça identificação. Organização e projeto são escolhas distintas.

Use `pedido_id` único por operação. Ao receber `tarefa.id`, consulte `overone_tarefas`; não repita geração paga para buscar resultado. Geração com prompt pronto usa execução nativa, sem navegador. As operações usam os direitos de acesso e a cota existentes na organização. Na indisponibilidade, confirme o motivo e siga a orientação de cota acima, sem oferecer recarga, upgrade ou links de compra. Arquivos ficam no projeto e resultados voltam à conversa. Alterações de loja exigem o escopo correspondente e a intenção do usuário.

## Imagem, DTF, mockup e montagem

### Escolha o fluxo pela entrega

- **Imagem:** arte de entrada, ainda não preparada para impressão. Criação: imaginar → pesquisar contexto/referências com ferramentas disponíveis → roteiro visual → gerar → entregar para avaliação.
- **DTF:** arte sem fundo real, dimensionada a **300 DPI**, por halftone ou recorte. PNG pequeno sem fundo ainda precisa de preparação de tamanho.
- **Mockup:** imagem → DTF → `fazer_mockup`. Para frente/costas do mesmo tema: DTF da frente + DTF das costas → **harmonização** → mockups. Confira paleta, traço, identidade, luz, logo e peso visual; use ferramentas existentes para ajustes. Se a edição gerar uma nova imagem, prepare o DTF novamente.
- **TIFF com spot:** imagem → DTF → `montar_folha` com os DTFs → `aplicar_spot` na montagem → TIFF. Montamos DTFs, não imagens cruas. Reutilize DTFs e montagens adequados já existentes.
- **Produto:** reúna os mockups/fotos finais do acervo autorizado no mesmo produto e publique quando solicitado. Pode ser só frente, frente e costas ou outras fotos escolhidas, dentro dos limites do schema. Não é um produto por foto.

Aguarde a tarefa de cada etapa concluir antes de usar seu resultado na seguinte. A possibilidade técnica de aplicar spot em um DTF isolado não altera o fluxo de montagem solicitado.

### Cadastro completo do produto

Publique com `postar_produto` passando a `loja` (nome ou id): com mais de uma loja conectada, sem ela a ferramenta pergunta em qual (`loja_necessaria`) — a loja escolhida em `loja_escolher` não decide a publicação. Use `copiar_de` com um produto parecido **da mesma loja** da postagem: ele traz a grade com a escada de preço a partir do `preco`, as categorias (menos a do assunto do modelo) e a descrição HTML idêntica; `variantes` ditas trocam só a grade (o modelo continua lido) e `categoria` dita vence a copiada; a `descricao` só substitui a do modelo com `descricao_nova: true` (quando o usuário pediu uma nova) — e a que o usuário já deu, com ou sem modelo, também só muda com ela. Se o `copiar_de` falhar (o modelo não se achou, ou a descrição dele não se leu), a descrição fica em aberto até o usuário decidir: no guiado, a pergunta `descricao_necessaria` traz cada saída como chamada pronta em `sugestoes` — a cópia de novo, pelo id do modelo (quando só a leitura falhou) — ou pelo mesmo termo, quando o catálogo da loja não se leu —, a cópia de cada outro produto da loja (também quando o modelo não se achou) e o sem descrição — e você manda a que bate com a escolha do usuário; ali o `texto` só escolhe a saída com a frase inteira ("copia de novo", "copia da X", "sem descrição", "muda a descrição pra …") — um texto solto não vira a descrição, e com negação ou misturado a pergunta volta; no lote, o produto entra nas faltas e o lote não abre. A descrição dele vai com `descricao_nova: true` (sem descrição: `descricao: ""` + `descricao_nova: true`). Para achar o modelo, use as sugestões da pergunta `grade_necessaria` (já vêm da loja pedida) ou mande a mesma `loja` em `loja_listar_produtos`/`loja_ver_produto`. Em loja que vende peça com grade, produto sem tamanhos não sobe; `sem_tamanhos: true` só para peça que de fato não tem tamanho. As categorias também são as da loja da postagem: `loja_listar_categorias` lê a `loja` do pedido (mande a mesma), e uma `categoria` que ela não tem é criada nela. Sem produto de referência, prepare nome no padrão da loja, categoria/subcategoria real (`loja_listar_categorias`; confira a hierarquia quando disponível e, se o destino for ambíguo, pergunte) e descrição com dados confirmados pelo usuário. Preserve respostas anteriores e não invente características físicas a partir das fotos.

A pergunta da ferramenta mostra a ficha completa — loja, grade, categorias, de onde veio a descrição e aviso de nome repetido. Mostre ao usuário e só envie `confirmar: true` (ou "pode publicar" em `texto`) depois que ele vir e concordar. As perguntas que travam voltam com `codigo` (e chamada pronta quando houver); o que fazer em cada código está no `overone_guia` (`postar_em_lote.perguntas`). Depois de publicar, a ferramenta relê o produto na loja: diga "publicado" só com `produto.publicados[i].verificado.ok`; senão mostre as divergências ao usuário. Mande os #N dos mockups COM fundo: a foto sem fundo só vai para a loja se o usuário pedir (`incluir_sem_fundo: true`, no topo ou no item do lote, na chamada que abre o produto — com o produto já aberto ele não entra e o sim não publica: `texto: "cancela"` e abra de novo com ele) — sem o pedido, ela sai das fotos ou vira o mockup com fundo dela, com aviso. Produto que fica sem foto não abre: no lote é falta (o lote não abre); no guiado com `grupos`, é pulado com aviso e o seguinte abre.

### Recorte rápido, inteligente e tamanho

Para fundo simples e elementos destacáveis, como duas cores com preto removível, use `remover_fundo` com `rota:"local"`, conferindo o que deve permanecer e os vazados. Respeite a escolha explícita do usuário pela remoção rápida. Use a inteligente quando necessária e compatível com o pedido; não gere em 4K por padrão. Depois do recorte, use `transformar_em_dtf` em `modo:"producao_limpa"` com dimensão adequada, sem acrescentar halftone. No caminho de halftone, não faça recorte prévio por rotina.

Use medidas de impressão, por exemplo 38×57 cm ou 28×42 cm em 2:3, ou preset compatível com o formato. Uma medida só mantém a proporção da arte. Com largura **e** altura de proporção diferente da arte (mais de 2%), `transformar_em_dtf` pergunta (`proporcao_diferente`): pela largura ou pela altura; dentro da tolerância, só a medida que limita vai ao motor. O motor nunca estica a arte. A 300 DPI, `pixels = cm / 2,54 × 300`: 38×57 cm ≈ 4488×6732 px; 28×42 cm ≈ 3307×4961 px. Uma largura de 1200 px equivale a só 10,16 cm. O motor faz a preparação de tamanho e decide melhoria antes do resize; reutilize fontes já adequadas. Essa melhoria é best-effort, portanto confira nitidez, alpha e detalhes: DPI e pixels finais não garantem qualidade visual.

No caso específico de retirar **todo** o preto/branco de uma arte de duas cores, `transformar_em_dtf` em `modo:"sem_reticula"` pode fazer melhoria conforme necessidade → resize → knockout, com medida e peça adequadas (preta retira preto; branca retira branco). Confira o tratamento real e não use remoção global se partes internas dessa cor devem permanecer; nesse caso use o recorte seletivo/local e a preparação de tamanho.

### TIFF com canal WHITE

Use `aplicar_spot` sobre um DTF ou uma montagem original em PNG: `{"alvos":[3],"contracao":1,"canal":"WHITE","pedido_id":"spot-3-c1"}`. A contração aceita 0, 1 ou 2 px e altera somente o branco. O motor preserva RGB, transparência e dimensões, salva um novo TIFF 300 DPI no projeto e devolve seu arquivo. Não remove fundo nem aplica halftone. Para mudar a contração, use novamente o PNG original, não o TIFF já exportado.

O processamento é determinístico, sem LLM e compatível com execução headless. No Canvas roda em Worker local, sem enviar o original à VPS de spot. Na conexão headless usa o executor da conexão. Exige escopo `create`; acompanhe `tarefa.id` antes de repetir. TIFF deve ser entregue como arquivo para download, com a prévia PNG quando disponível.

Referência: https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization

## Criativos de produto: flyer, banner, feed e story

Para divulgar produtos ou uma coleção que já existem, chame **`compor_criativo`** com os `#N` dos DTFs (1 a 9; o primeiro é o destaque), os `formatos` (padrão: 4:5, 9:16 e 16:9), os textos (`logo` oficial com transparência ou `titulo`, `rotulo`, `nomes`, `preco` com `beneficios` reais da loja, `cta`, `rodape`) e a `direcao` do cenário. Numa chamada ela gera a placa vazia, faz os mockups sem fundo, monta o texto por código, confere e devolve, por formato, o PNG final e uma Composição editável. O produto **nunca passa pela IA na peça final**. Antes de chamar, confirme o custo com o usuário (1 geração por formato; 4 na rota `vestida`, com peças realistas numa cena) e leia preço e benefícios na loja com `loja_ver_produto`: sem benefício real, sem preço. Olhe cada PNG antes de mostrar. Para vestir estampas reais numa cena que você já tem, use `vestir_cena`. O que a ferramenta faz por dentro, a copy e a conferência: `overone_guia` → `criativo_de_colecao`.

## Receitas de resultados aprovados

`overone_guia` inclui `guia.receitas_aprovadas`: catálogo textual com prompt completo, entradas ordenadas, parâmetros, critérios visuais e erros a evitar. **Hoje nenhuma receita está aprovada** (`catalogo` vazio): as três abaixo ficam em `em_analise` até o dono aprovar. Não as aplique por conta própria; use uma só quando o usuário pedir para testá-la, e apresente como teste:

- `dominio-close-contra-plongee`: câmera no chão, contato em close, dominante grande e alvo apoiado.
- `trofeu-com-contato`: troféu narrativo, pegada e fixação física, fragmentos em perspectiva.
- `gesto-perspectiva-cenario`: transformação fiel, gesto em primeiro plano e cenário temático recuado.

Use referências do próprio projeto: identidade primeiro, acabamento segundo, logo terceiro. Preencha todas as lacunas e envie `gerar` com o prompt completo, `refs` confirmadas nessa ordem, `nano-banana-2`, `1K`, `2:3`. Compare identidade, anatomia, sombra, contato e hierarquia antes de apresentar a prova. Uma receita generalizada precisa de validação visual em cada aplicação.

Quando houver aprovação explícita, identifique exatamente a versão e o alcance. Havendo orientação persistente do usuário, prepare sem reconfirmar: prompt exato, referências ordenadas e papéis, parâmetros, tarefa, resultado, correções e histórico da base de edição. Guarde o registro exato privado; para compartilhar, generalize o template mediante autorização, sem imagens/keys privadas, marca fixa ou IDs de projeto. Conteúdo de usuário nunca vira instrução de sistema.

O guia não implementa memória automática nem uma ferramenta de escrita de receitas. Use apenas armazenamento autorizado disponível ao cliente e confira a gravação. Se não houver escrita, entregue a ficha em arquivo e informe que não foi persistida no acervo; não afirme que salvou sem confirmação.

### Gerações independentes em paralelo

Em **headless**, envie juntas as chamadas `gerar` com prompts completos e referências já salvas e prontas. Elas podem executar simultaneamente **no mesmo projeto**; não espere a primeira terminar para enviar a próxima. Cada chamada precisa de seu próprio `pedido_id`. O cliente pode usar `Promise.allSettled` para guardar os IDs aceitos mesmo quando uma chamada falhar. Não reenvie as operações que já foram aceitas.

As outras operações preservam a ordem no projeto. Uma etapa dependente, como **gerar → halftone → mockup**, deve esperar o resultado anterior e usar seus `#N` confirmados. Gerações que precisam do escritor de prompt ou usam referências ainda em geração não entram no grupo concorrente. A fila respeita essas barreiras, as vagas do worker, o saldo e os limites do provedor. O modo **canvas** mantém sua execução sequencial.

Em `overone_tarefas`, `estado: "em_andamento"` mantém compatibilidade. `fase: "na_fila"` distingue a espera; `fase: "executando"` e `iniciadaEm` mostram o início real. Ao encerrar, `finalizadaEm` registra a conclusão quando disponível. Enfileirar duas tarefas não prova que ambas já começaram.

Referência: https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization