hraness/transmute

Criar diagramas claros

Use o CLI transmute instalado como o adaptador determinístico. Mantenha o arquivo .diagram.json fonte; trate .light.svg, .dark.svg, .light.png, .dark.png e .tldr como exportações substituíveis.

Siga o prompt literalmente

Trate o prompt do usuário como a especificação completa do conteúdo.

• Preserve rótulos, valores, relacionamentos, tamanhos relativos e omissões fornecidos.
• Adicione apenas mecânicas neutras necessárias para desenhar esses fatos.
• Não invente título, subtítulo, legenda, anotação, exemplo, implicação, categoria, métrica, marca, conector ou alegação decorativa.
• Não expanda um rótulo curto em uma frase. Prefira o rótulo de uma a três palavras do próprio usuário.
• Ao atualizar, remova o conteúdo rejeitado sem substituí-lo por uma nova elaboração.

Encontre a fonte

1. Leia as instruções do repositório local e procure por transmute.config.*.
2. Procure por um .diagram.json existente sobre o mesmo assunto antes de criar um.
3. Atualize essa fonte em vez de editar imagens geradas ou criar uma duplicata.
4. Em uma base de conhecimento com info/, use info/diagrams/<slug>.diagram.json e emparelhe com info/notes/<slug>.md. Em um repositório que ainda usa kb/, use os mesmos caminhos relativos lá. Incorpore ou vincule a imagem renderizada clara/escura de acordo com a convenção do host, e vincule o conhecimento através da nota, e não através de uma tela binária.
5. Fora de uma base de conhecimento, use o padrão diagrams/<slug>.diagram.json.

Componha o visual

Leia visual-communication.md antes de criar ou redesenhar materialmente um diagrama.

Aplique estes padrões profundamente:

• Use retângulos arredondados para conceitos comuns. Funções iguais recebem tamanhos, raios, espessuras de traço, tamanhos de ícone e tratamento de rótulo iguais.
• Deixe pelo menos 96px — e de preferência 120–200px — entre formas conectadas para que as setas sejam lidas como relacionamentos, e não como emendas.
• Coloque os ícones diretamente dentro de sua forma semântica. Não coloque um bloco de ícone com borda dentro de outro cartão com borda.
• Use de três a sete elementos primários quando o prompt permitir abstração.
• Estabeleça uma ordem de leitura clara e alinhe pares a uma grade compartilhada.
• Use espaço em branco antes de bordas, cores ou prosa para separar grupos.
• Use cor para no máximo uma distinção semântica. Nunca faça alterações arbitrárias de tamanho ou estilo que impliquem uma diferença que o prompt não forneceu.
• Mantenha os ícones como suporte: um rótulo ainda deve carregar o significado.
• Prefira um limite visível por objeto e um traço visível por eixo ou conector.

Não "melhore" dados literais para satisfazer essas preferências. O prompt vence.

Deixe o layout determinístico gerenciar coordenadas comuns

Use um layout stack livre de coordenadas para uma sequência horizontal ou vertical:

{
  "layout": {
    "type": "stack",
    "direction": "horizontal",
    "gap": 160,
    "align": "center"
  }
}

• A ordem do array controla apenas o posicionamento. Desenhe uma aresta somente quando o prompt forneceu esse relacionamento.
• Mantenha as formas da pilha como retângulos ou elipses e omita x e y.
• Use o espaçamento padrão de 160px, a menos que o prompt ou o quadro de publicação exija uma distância diferente.
• Mude para o modo posicionado para ramificações, arestas não adjacentes, gráficos, texto livre, linhas ou posicionamento deliberadamente desigual. Não force esses significados em uma pilha unidimensional.
• Se uma pilha não couber, aumente a tela ou reduza as dimensões autoradas explicitamente. Não reduza silenciosamente formas ou espaçamentos.

Autore e renderize

Use a URL do esquema público ou execute transmute diagram init para um modelo inicial:

transmute diagram check diagrams/<slug>.diagram.json --strict
transmute diagram render diagrams/<slug>.diagram.json

O comando de renderização sobrescreve as exportações consistentes de mesmo nome. Inspecione a saída clara e escura quando o layout ou o contraste estiver incerto. Resolva todas as descobertas de lint úteis; altere a fonte e depois re-renderize.

Se o repositório usar sua própria fonte ou pacote de ícones, leia customization.md. Não adicione MonoLisa ou outra fonte licenciada ao repositório. A renderização padrão usa a pilha sans-serif do sistema.

Autentique antes da geração de imagem hospedada

Use o fluxo do navegador OAuth quando a geração hospedada relatar AUTH_REQUIRED:

transmute auth login
transmute auth status

O callback é fixo em http://127.0.0.1:49671/oauth/callback. Os tokens pertencem apenas ao armazenamento de credenciais do sistema operacional através de Bun.secrets. Nunca peça ao usuário para colar um token, copiá-lo para um arquivo, imprimi-lo na saída da tarefa ou contornar a descoberta. Em hosts macOS e Linux suportados, transmute auth logout revoga a credencial remota quando possível e remove a credencial local. Login, atualização e logout usam coordenação de escopo de processo; compartilhar seu diretório de concessão entre namespaces de PID do Linux falha fechado sem excluir o marcador de outro escopo. Mutações de credencial falham fechado no Windows até que o Transmute tenha uma primitiva de coordenação privada nativa equivalente.

Gere um WebP hospedado literalmente

Quando o usuário solicitar explicitamente a geração de raster hospedado, preserve seu prompt em vez de enriquecê-lo:

transmute image generate '<literal prompt>' --output path/to/image.webp

O modelo padrão é recraft/recraft-v4.1-utility. Use --model openai/gpt-image-1.5 apenas quando o usuário solicitar ou seu comportamento for relevante para o resultado solicitado. Esses são os únicos IDs suportados.

A geração hospedada é uma prévia gratuita autenticada e limitada. Seu limite diário de conta UTC é 10 e seu limite global de segurança diário é 100. O pagamento ainda não é aplicado. A vetorização é governada separadamente e permanece local, gratuita e sem autenticação.

• Mantenha o caminho de saída .webp obrigatório dentro do espaço de trabalho solicitado pelo usuário.
• Deixe o CLI criar um UUID de idempotência. Forneça --idempotency-key apenas quando um chamador já possuir uma chave estável de 16 a 128 caracteres. O serviço armazena a chave de forma durável dentro do escopo da conta do conjunto.
• Nunca tente novamente uma chamada de geração com falha: um erro pode ser ambíguo mesmo com idempotência durável no escopo da conta.
• Não decodifique, escreva ou confie na imagem você mesmo. O CLI limita o base64 canônico, valida a magia de mídia RIFF/WebP e a publica atomicamente.

Use workflows 3D e de materiais orientados por referência deliberadamente

Leia reference-led-3d.md quando o usuário solicitar transformar uma imagem gerada ou fornecida em uma cena Three.js, um objeto low-poly, um loop 3D transparente ou um render de produto de logotipo metálico.

Estas são capacidades completas do modo Code local, atualmente distribuídas com o Desktop. O executor Bun público headless pode gerar uma imagem e executar suas quatro operações portáteis fixas, mas não executa sobreposições HTML, Three.js ou o renderizador de projeto privado. O shell Desktop fornece captura nativa, permissões e UI, em vez de outro modelo de workflow. Nunca implique o contrário. No modo Code local:

• Etapa o trabalho de imagem para Three como geração de referência, criação de fonte, revisão, pré-visualização e, em seguida, render final. Nunca envie JavaScript produzido por modelo diretamente para uma operação semântica.
• Vincule o artefato de referência exato à cena revisada com createThreeReferenceScaffoldInput, mesmo quando não estiver visivelmente composto.
• Use createMetallicLogoImageRequest para o tratamento de produto quadrado orientado por referência. Mantenha a seleção do modelo explícita e inspecione a fidelidade da identidade antes de aceitar o resultado.
• Renderize pré-visualizações completas em 1x primeiro. Aumente a resolução ou a escala do dispositivo somente após selecionar a fonte e o tratamento.

Vetorize um raster sem alterar seu significado

Quando o usuário solicitar converter arte raster de propriedade do chamador para SVG, mantenha o raster como fonte e trate o SVG como um derivado substituível:

transmute image vectorize path/to/input.png --output path/to/input.svg --json

• Não autentique para vetorização. A conversão é local e não entra em contato com descoberta, OAuth, geração ou qualquer outro endpoint de rede.
• Não redesenhe, reetiquete, corte, recolorir ou simplifique o assunto além da mecânica de rastreamento que o comando mede.
• Use --duotone '#primary,#secondary' apenas quando o usuário solicitar explicitamente essa adaptação de duas cores.
• Preserve o recibo emitido na saída da tarefa ou em um registro de proveniência adjacente quando a auditabilidade for importante.
• Não ignore portões de entrada, pixel decodificado, duração, caminho, byte ou fidelidade.
• Inspecione o SVG em seu tamanho pretendido. Um rastreamento bem-sucedido não é evidência de que um símbolo desconhecido comunica o conceito pretendido.

O VTracer baixa de seu lançamento oficial com soma de verificação fixa no primeiro uso. Use TRANSMUTE_VTRACER_PATH apenas para um binário 0.6.4 local compatível; o Transmute ainda registra seu hash. Nunca adicione um modelo de upscaling, fallback raster incorporado ou fonte comercial para fazer um rastreamento passar.

A vetorização limitada é atualmente suportada no macOS e Linux. No Windows, reporte a falha deliberada de tool_platform; não a ignore com um arquivo de saída temporário ilimitado.

Use um servidor de ferramentas conectado de forma restrita

Quando o Transmute MCP estiver conectado, preserve as ferramentas dedicadas check_diagram e render_diagram para chamadas simples de compatibilidade. Use search_transmute para descobrir o registro semântico fixo e execute_transmute com um código retornado exato e JSON tipado. Continue a editar a fonte do diagrama verificada diretamente; nenhuma ferramenta cria ou reescreve a fonte.

• Passe apenas caminhos .diagram.json relativos à raiz.
• Trate check_diagram como somente leitura.
• Trate render_diagram como aprovação para substituir os cinco artefatos gerados documentados, nunca a fonte.
• Use o CLI em vez do MCP para uma fonte acima de 64 formas ou 128 arestas. O MCP retorna no máximo 40 descobertas e relata quando essa lista é truncada.
• O modo MCP usa deliberadamente temas e ícones embutidos e nunca executa configuração do workspace. Use o CLI fora do MCP quando uma configuração local confiável for necessária.
• transmute.image.vectorize aceita caminhos de entrada/saída relativos à raiz, não requer login e mantém bytes raster locais.
• transmute.image.generate requer um caminho de saída .webp relativo à raiz, escreve atomicamente a imagem limitada e retorna apenas metadados de arquivo/solicitação redigidos. Use apenas os dois IDs de modelo do registro e não tente novamente.
• Nunca passe código fonte, texto de shell, texto de importação dinâmica, URLs remotas ou nomes de operação não registrados para execução semântica.

Sem MCP, a superfície CLI equivalente legível por máquina é:

transmute code search '<terms>' --limit 4
transmute code execute <exact-operation-code> --input '<strict JSON object>'

Use tldraw deliberadamente

O arquivo .tldr gerado é intercâmbio editável e não requer o SDK tldraw ou aplicativo desktop para criar. Abra-o no tldraw Offline quando uma pessoa quiser edição direta da tela:

transmute canvas open diagrams/<slug>.tldr

Se o aplicativo opcional estiver ausente, transmute canvas install resolve o lançamento oficial atual, verifica seu digest SHA-256 publicado e inicia o instalador da plataforma. O aplicativo importa .tldr como um documento não salvo; salve-o lá para criar seu pacote nativo .tldraw mais recente. Nunca reescreva um pacote .tldraw ZIP/SQLite nativo diretamente.

Verifique

1. Execute transmute diagram check <source> --strict.
2. Execute transmute diagram render <source>.
3. Confirme que todos os cinco artefatos existem ao lado da fonte ou no diretório de saída solicitado.
4. Inspecione a saída clara e escura no tamanho real.
5. Confirme que formas pares não implicam diferenças falsas.
6. Confirme que os conectores são longos, vinculados às formas pretendidas em .tldr e não cruzam rótulos.
7. Se uma nota complementar for necessária, confirme seu caminho e referência visual.