flc1125/mote

Mote — Markdown entra, URL sai

Mote publica Markdown como uma página online imutável, não enumerável e legível por navegador, retornando uma URL. Este Skill apenas orienta quando e como usar o Mote; o protocolo de publicação é implementado pela CLI / MCP, não implemente a lógica de upload por conta própria.

Quando usar

Use o Mote quando uma das seguintes intenções estiver presente:

• "Compartilhe este Markdown / relatório / documento" "Transforme em página / link"
• Solicitação explícita para transformar documento de design, material de pesquisa, ata de reunião ou README em um link online
• Solicitação para publicar o relatório/resultado da análise que você acabou de gerar como uma página web

Apenas leitura, edição de Markdown ou visualização no navegador local não requer publicação no Mote.

Não use:

• Conteúdo contendo senhas, chaves de API, chaves privadas ou outros segredos, ou segredos corporativos — a URL do Mote é a credencial de acesso; quem sabe o link pode ler o conteúdo; atualmente não há entrada de exclusão do lado do usuário
• Necessidade de modificar conteúdo já publicado — os documentos do Mote são imutáveis; para alterar o conteúdo, é necessário republicar e obter uma nova URL

Como publicar

Primeiro verifique se há imagens locais referenciadas, depois escolha o caminho de acordo com a ferramenta configurada. Respeite a instância especificada pelo usuário; se já houver configuração auto-hospedada, não force a mudança para a instância pública https://mote.pub.

Caminho A: Ferramenta MCP (se o servidor MCP mote estiver conectado)

• Conteúdo na conversa e sem imagens locais → chame publish_markdown, passando markdown (opcionalmente name, como report.md). Esta ferramenta, tanto local quanto remota, não coleta imagens locais, apenas preserva URLs de imagens remotas.
• Arquivo Markdown local → apenas o stdio local fornece publish_markdown_file, passe path (imagens locais são enviadas automaticamente, deduplicadas por conteúdo); remoto apenas tem publish_markdown, então para arquivos/imagens locais use a CLI configurada, não passe o caminho para a ferramenta remota.

Caminho B: CLI (disponível se instalada e autenticada)

1. Se o arquivo já existir, publique o arquivo original. Se o conteúdo da conversa não tiver imagens locais, pode-se escrever em um arquivo temporário; se houver imagens locais, coloque o Markdown e as imagens necessárias em um diretório temporário mantendo as relações de caminho relativas, depois publique via CLI ou publish_markdown_file local. As imagens são resolvidas em relação ao diretório do arquivo Markdown, não ao diretório de trabalho do terminal; não mova apenas o Markdown para /tmp.
2. Execute:

mote <arquivo.md> --json

3. Analise o JSON do stdout: { "id": "...", "url": "..." }

A CLI lida automaticamente com referências a imagens locais em Markdown e HTML suportado, validação de caminhos, upload e deduplicação de conteúdo; imagens remotas mantêm a URL original, não são baixadas ou empacotadas. Apenas imagens são enviadas junto com o documento; links para outros arquivos Markdown locais não publicam automaticamente o arquivo de destino.

Compatibilidade de conteúdo

• Suporta Markdown comum, tabelas, listas de tarefas, notas de rodapé, Alertas estilo GitHub e destaque de sintaxe para linguagens específicas.
• Fórmulas matemáticas suportam um subconjunto de TeX; blocos de código mermaid suportam um subconjunto de seis tipos de gráficos estáticos, com no máximo quatro gráficos tentados por artigo. Conteúdo inválido, não suportado ou que exceda o orçamento pode ser exibido como código fonte; o sucesso da publicação não garante que toda a sintaxe estendida tenha sido renderizada.
• HTML permite apenas um subconjunto seguro, sem execução de scripts, MDX ou incorporações interativas. Não é suportado upload ou incorporação direta de SVG bruto; SVGs de gráficos gerados pelo Mote são limpos independentemente e podem ser exibidos.
• Ao publicar fórmulas ou gráficos complexos, verifique as fórmulas, linhas, rótulos e imagens na página real; sem verificação, não afirme que os resultados da renderização foram validados.

Para sintaxe detalhada ou limitações, consulte a documentação de compatibilidade e os exemplos online. O escopo de suporte de uma instância auto-hospedada depende da versão implantada.

Como lidar com a URL retornada

• Retorne a URL exatamente como recebida para o usuário, sem truncar ou modificar;
• Uma breve frase é suficiente, por exemplo, "Publicado: ";
• A página possui instruções para evitar indexação por mecanismos de busca, mas isso não é uma garantia de controle de acesso ou de que nunca será indexada; a acessibilidade depende da instância e do armazenamento contínuos;
• Se o usuário posteriormente solicitar "atualizar esta página": explique que o Markdown armazenado e os ativos enviados são imutáveis; republicar resultará em uma nova URL; atualizações do Viewer podem alterar a aparência, e imagens remotas dependem do site de origem.

Limitações (verificação antes de publicar)

• Markdown ≤ 2 MiB; imagem única ≤ 10 MiB; ativos enviados ≤ 50; pacote total ≤ 20 MiB. 1 MiB = 1.048.576 bytes; a CLI conta após deduplicação por conteúdo; imagens remotas não são contadas
• Formatos de imagem: png / jpeg / webp / gif / avif (SVG não suportado)
• Se os limites forem excedidos, informe honestamente ao usuário qual item excedeu o limite, não remova conteúdo por conta própria

Erros comuns

• Falha de login: oriente o usuário a concluir o login interativo na mesma instância; se o usuário solicitar explicitamente ajuda para login, continue dentro do escopo autorizado. Não inicie login no navegador devido a falha de publicação, não leia credenciais de outros clientes, não retorne ao token antigo. Consulte a documentação de autenticação para etapas específicas;
• no publish token configured: confirme o modo de autenticação da instância. Modo estático requer que o administrador da instância forneça um token; instâncias Access exigem login OAuth ou modo de máquina explícito; não use o token de API de gerenciamento do Cloudflare como chave de publicação; não gere credenciais por conta própria;
• Modo de máquina: requer MOTE_AUTH_MODE=service explícito e MOTE_SERVICE_API_URL, MOTE_SERVICE_CLIENT_ID, MOTE_SERVICE_CLIENT_SECRET correspondentes. Se ausente ou inválido, pare; não substitua pelo estado de login do usuário;
• Timeout, 5xx ou resultado desconhecido: não tente republicar automaticamente; um documento imutável pode já ter sido gerado; primeiro verifique o resultado, depois deixe o usuário decidir se deseja republicar;
• asset not found: <caminho>: uma imagem local referenciada no Markdown não existe; lembre o usuário de verificar o caminho relativo;
• unsupported image type: referência a formato não suportado, como SVG; sugira ao usuário converter para png/webp e tentar novamente.