hraness/transmute

Créer des diagrammes clairs

Utilisez le CLI transmute installé comme adaptateur déterministe. Conservez le fichier source .diagram.json créé ; traitez .light.svg, .dark.svg, .light.png, .dark.png et .tldr comme des exportations remplaçables.

Suivez l'invite à la lettre

Traitez l'invite de l'utilisateur comme la spécification complète du contenu.

• Conservez les étiquettes, valeurs, relations, tailles relatives et omissions fournies.
• Ajoutez uniquement les mécanismes neutres nécessaires pour dessiner ces faits.
• N'inventez pas de titre, sous-titre, légende, annotation, exemple, implication, catégorie, métrique, graduation, connecteur ou affirmation décorative.
• Ne développez pas une étiquette courte en une phrase. Préférez l'étiquette propre de l'utilisateur en un à trois mots.
• Lors de la mise à jour, supprimez le contenu rejeté sans le remplacer par une nouvelle élaboration.

Trouver la source

1. Lisez les instructions du dépôt local et cherchez transmute.config.*.
2. Recherchez un fichier .diagram.json existant sur le même sujet avant d'en créer un.
3. Mettez à jour cette source plutôt que de modifier les images générées ou de créer un doublon.
4. Dans une base de connaissances avec info/, utilisez info/diagrams/<slug>.diagram.json et associez-le à info/notes/<slug>.md. Dans un dépôt qui utilise encore kb/, utilisez les mêmes chemins relatifs. Intégrez ou liez l'image claire/obscure rendue selon la convention de l'hôte, et liez les connaissances via la note plutôt que via un canevas binaire.
5. En dehors d'une base de connaissances, utilisez par défaut diagrams/<slug>.diagram.json.

Composer le visuel

Lisez visual-communication.md avant de créer ou de modifier substantiellement un diagramme.

Appliquez ces valeurs par défaut en profondeur :

• Utilisez des rectangles arrondis pour les concepts ordinaires. Des rôles égaux obtiennent des tailles, des rayons, des épaisseurs de trait, des tailles d'icônes et un traitement d'étiquette égaux.
• Laissez au moins 96px, et de préférence 120-200px, entre les formes connectées afin que les flèches soient lues comme des relations plutôt que des coutures.
• Placez les icônes directement à l'intérieur de leur forme sémantique. Ne placez pas une tuile d'icône bordée à l'intérieur d'une autre carte bordée.
• Utilisez trois à sept éléments principaux lorsque l'invite le permet.
• Établissez un ordre de lecture clair et alignez les éléments de même niveau sur une grille partagée.
• Utilisez les espaces blancs avant les bordures, les couleurs ou le texte pour séparer les groupes.
• Utilisez la couleur pour au plus une distinction sémantique. Ne faites jamais de changements arbitraires de taille ou de style qui impliquent une différence que l'invite n'a pas fournie.
• Gardez les icônes comme support : une étiquette doit toujours porter le sens.
• Préférez une limite visible par objet et un trait visible par axe ou connecteur.

N'"améliorez" pas les données littérales pour satisfaire ces préférences. L'invite l'emporte.

Laissez la mise en page déterministe posséder les coordonnées ordinaires

Utilisez une mise en page stack sans coordonnées pour une séquence horizontale ou verticale :

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

• L'ordre du tableau contrôle uniquement le placement. Dessinez un bord uniquement lorsque l'invite a fourni cette relation.
• Gardez les formes de la pile sous forme de rectangles ou d'ellipses et omettez x et y.
• Utilisez l'écart par défaut de 160 px, sauf si l'invite ou le cadre de publication nécessite une distance différente.
• Passez en mode positionné pour les branches, les bords non adjacents, les graphiques, le texte libre, les lignes ou le placement délibérément inégal. Ne forcez pas ces significations dans une pile unidimensionnelle.
• Si une pile ne tient pas, agrandissez le canevas ou réduisez explicitement les dimensions créées. Ne réduisez pas silencieusement les formes ou les écarts.

Créer et rendre

Utilisez l'URL du schéma public ou exécutez transmute diagram init pour un modèle de départ :

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

La commande de rendu écrase les exportations cohérentes de la même tige. Inspectez les sorties claire et obscure lorsque la mise en page ou le contraste est incertain. Traitez tous les résultats utiles de lint ; modifiez la source, puis refaites le rendu.

Si le dépôt utilise sa propre police ou son propre pack d'icônes, lisez customization.md. N'ajoutez pas MonoLisa ou une autre police sous licence au dépôt. Le rendu par défaut utilise la pile sans empattement du système.

S'authentifier avant la génération d'images hébergée

Utilisez le flux navigateur OAuth lorsque la génération hébergée signale AUTH_REQUIRED :

transmute auth login
transmute auth status

Le callback est fixé à http://127.0.0.1:49671/oauth/callback. Les jetons appartiennent uniquement au magasin d'informations d'identification du système d'exploitation via Bun.secrets. Ne demandez jamais à l'utilisateur de coller un jeton, de le copier dans un fichier, de l'imprimer dans une sortie de tâche ou de contourner la découverte. Sur les hôtes macOS et Linux pris en charge, transmute auth logout révoque l'information d'identification distante lorsque possible et supprime l'information d'identification locale. La connexion, l'actualisation et la déconnexion utilisent une coordination liée à la portée du processus ; le partage de son répertoire de location entre les espaces de noms PID Linux échoue en closed without deleting another scope's marker. Les mutations d'identifiants échouent en closed sur Windows jusqu'à ce que Transmute ait une primitive de coordination native privée équivalente.

Générer un WebP hébergé littéralement

Lorsque l'utilisateur demande explicitement une génération raster hébergée, conservez son invite plutôt que de l'enrichir :

transmute image generate '<littéral prompt>' --output chemin/vers/image.webp

Le modèle par défaut est recraft/recraft-v4.1-utility. Utilisez --model openai/gpt-image-1.5 uniquement lorsque l'utilisateur le demande ou que son comportement est important pour le résultat demandé. Ce sont les seuls ID pris en charge.

La génération hébergée est un aperçu gratuit authentifié et limité. Sa limite de compte par jour UTC est de 10 et sa limite de sécurité quotidienne globale est de 100. Le paiement n'est pas encore appliqué. La vectorisation est régie séparément et reste locale, gratuite et sans authentification.

• Conservez le chemin de sortie .webp requis dans l'espace de travail demandé par l'utilisateur.
• Laissez le CLI créer un UUID d'idempotence. Fournissez --idempotency-key uniquement lorsque un appelant possède déjà une clé stable de 16 à 128 caractères. Le service stocke la clé de manière durable dans le périmètre du compte de la suite.
• Ne réessayez jamais un appel de génération ayant échoué : une erreur peut être ambiguë même avec une idempotence durable au niveau du compte.
• Ne décodez pas, n'écrivez pas et ne faites pas confiance à l'image vous-même. Le CLI délimite le base64 canonique, valide la magie multimédia RIFF/WebP et la publie de manière atomique.

Utilisez les workflows 3D et matériels guidés par référence délibérément

Lisez reference-led-3d.md lorsque l'utilisateur demande de transformer une image générée ou fournie en scène Three.js, en objet low-poly, en boucle 3D transparente ou en rendu de produit métallique.

Ce sont des capacités complètes du mode Code local de l'hôte, actuellement distribuées avec Desktop. Le runner Bun public sans tête peut générer une image et exécuter ses quatre opérations portables fixes, mais il n'exécute pas les superpositions HTML, Three.js ou le rendu de projet privé. Le shell Desktop fournit la capture native, les autorisations et l'interface utilisateur plutôt qu'un autre modèle de workflow. Ne laissez jamais entendre le contraire. En mode Code local :

• Organisez le travail image-vers-Three comme une génération de référence, une création de source, une révision, un aperçu, puis un rendu final. N'envoyez jamais de JavaScript produit par le modèle directement à une opération sémantique.
• Liez l'artefact de référence exact à la scène révisée avec createThreeReferenceScaffoldInput, même lorsqu'il n'est pas visiblement composé.
• Utilisez createMetallicLogoImageRequest pour le traitement de produit carré guidé par référence. Gardez la sélection du modèle explicite et inspectez la fidélité de l'identité avant d'accepter le résultat.
• Rendez les aperçus pleine longueur à 1x d'abord. Augmentez la résolution ou l'échelle du périphérique uniquement après avoir sélectionné la source et le traitement.

Vectoriser un raster sans changer son sens

Lorsque l'utilisateur demande de convertir un raster appartenant à l'appelant en SVG, conservez le raster comme source et traitez le SVG comme un dérivé remplaçable :

transmute image vectorize chemin/vers/input.png --output chemin/vers/input.svg --json

• Ne vous authentifiez pas pour la vectorisation. La conversion est locale et ne contacte pas la découverte, OAuth, la génération ni aucun autre point de terminaison réseau.
• Ne redessinez pas, ne réétiquetez pas, ne recadrez pas, ne recolorisez pas et ne simplifiez pas le sujet au-delà des mécanismes de tracé que la commande mesure.
• Utilisez --duotone '#primaire,#secondaire' uniquement lorsque l'utilisateur demande explicitement cette adaptation bicolore.
• Conservez le reçu émis dans la sortie de la tâche ou un enregistrement de provenance adjacent lorsque l'audibilité est importante.
• Ne contournez pas les entrées, les pixels décodés, la durée, le chemin, les octets ou les portes de fidélité.
• Inspectez le SVG à sa taille prévue. Un tracé réussi n'est pas une preuve qu'un symbole inconnu communique le concept prévu.

VTracer se télécharge à partir de sa version officielle à somme de contrôle épinglée lors de la première utilisation. Utilisez TRANSMUTE_VTRACER_PATH uniquement pour un binaire local compatible 0.6.4 ; Transmute enregistre toujours son hachage. N'ajoutez jamais de modèle de suréchantillonnage, de repli raster intégré ou de police commerciale pour faire passer un tracé.

La vectorisation limitée est actuellement prise en charge sur macOS et Linux. Sur Windows, rapportez l'échec délibéré de tool_platform ; ne le contournez pas avec un fichier de sortie temporaire non limité.

Utilisez un serveur d'outils connecté de manière étroite

Lorsque Transmute MCP est connecté, conservez les outils dédiés check_diagram et render_diagram pour les appels de compatibilité simples. Utilisez search_transmute pour découvrir le registre sémantique fixe et execute_transmute avec un code exact retourné et du JSON typé. Continuez à modifier la source du diagramme vérifié directement ; aucun outil ne crée ou ne réécrit la source.

• Passez uniquement des chemins .diagram.json relatifs à la racine.
• Traitez check_diagram comme en lecture seule.
• Traitez render_diagram comme une approbation pour remplacer les cinq artefacts générés documentés, jamais la source.
• Utilisez le CLI plutôt que MCP pour une source de plus de 64 formes ou 128 arêtes. MCP renvoie au plus 40 résultats et signale lorsque cette liste est tronquée.
• Le mode MCP utilise délibérément des thèmes et des icônes intégrés et n'exécute jamais la configuration de l'espace de travail. Utilisez le CLI en dehors de MCP lorsqu'une configuration locale de confiance est requise.
• transmute.image.vectorize accepte les chemins d'entrée/sortie relatifs à la racine, ne nécessite aucune connexion et conserve les octets raster localement.
• transmute.image.generate nécessite un chemin de sortie .webp relatif à la racine, écrit atomiquement l'image limitée et renvoie uniquement les métadonnées de fichier/requête expurgées. Utilisez uniquement les deux ID de modèle de registre et ne réessayez pas.
• Ne passez jamais de code source, de texte shell, de texte d'importation dynamique, d'URL distantes ou de noms d'opération non enregistrés à l'exécution sémantique.

Sans MCP, la surface CLI équivalente lisible par machine est :

transmute code search '<termes>' --limit 4
transmute code execute <code-opération-exact> --input '<objet JSON strict>'

Utilisez tldraw délibérément

Le fichier .tldr généré est un format d'échange modifiable et ne nécessite pas le SDK tldraw ou l'application de bureau pour être créé. Ouvrez-le dans tldraw Offline lorsqu'une personne souhaite une édition directe du canevas :

transmute canvas open diagrams/<slug>.tldr

Si l'application facultative est absente, transmute canvas install résout la version officielle actuelle, vérifie son condensat SHA-256 publié et lance le programme d'installation de la plateforme. L'application importe .tldr en tant que document non enregistré ; enregistrez-le là pour créer son bundle .tldraw natif plus récent. Ne réécrivez jamais un bundle .tldraw ZIP/SQLite natif directement.

Vérifier

1. Exécutez transmute diagram check <source> --strict.
2. Exécutez transmute diagram render <source>.
3. Confirmez que les cinq artefacts existent à côté de la source ou dans le répertoire de sortie demandé.
4. Inspectez la sortie claire et obscure à la taille réelle.
5. Confirmez que les formes de même niveau n'impliquent pas de fausses différences.
6. Confirmez que les connecteurs sont longs, liés aux formes prévues dans .tldr, et ne croisent pas les étiquettes.
7. Si une note d'accompagnement est requise, confirmez son chemin et sa référence visuelle.