flc1125/mote

Mote — Markdown en entrée, URL en sortie

Mote publie du Markdown sous forme de page web immuable, non énumérable et lisible par navigateur, et renvoie une URL. Cette compétence guide uniquement sur quand et comment utiliser Mote ; le protocole de publication est implémenté par CLI / MCP — n'implémentez pas votre propre logique de téléversement.

Quand l'utiliser

Utilisez Mote lorsque l'une des intentions suivantes est exprimée :

• « Partage ce Markdown / rapport / document » « Publie-le en page web / lien »
• Demande explicite de transformer un document de conception, une étude, un compte rendu de réunion ou un README en lien en ligne
• Demande de publier un rapport / résultat d'analyse que vous venez de générer en tant que page web

Lorsque l'utilisateur se contente de lire, modifier ou prévisualiser du Markdown localement dans le navigateur, ne publiez pas sur Mote.

N'utilisez pas :

• Si le contenu contient des mots de passe, clés API, clés privées ou autres secrets, ou des informations confidentielles d'entreprise — l'URL Mote est le jeton d'accès ; quiconque connaît le lien peut lire le contenu, et il n'existe actuellement aucun moyen de suppression côté utilisateur
• Si vous devez modifier un contenu déjà publié — les documents Mote sont immuables ; toute modification nécessite une nouvelle publication générant une nouvelle URL

Comment publier

Vérifiez d'abord s'il y a des images locales référencées, puis choisissez le chemin selon l'outil configuré. Respectez l'instance spécifiée par l'utilisateur ; s'il existe déjà une configuration auto-hébergée, ne forcez pas l'utilisation de l'instance publique https://mote.pub.

Chemin A : Outil MCP (si le serveur MCP mote est connecté)

• Contenu dans la conversation sans images locales → appelez publish_markdown, en passant markdown (optionnellement name, ex. report.md). Cet outil local et distant ne collecte pas d'images locales, ne conserve que les URL d'images distantes.
• Fichier Markdown local → seul le stdio local fournit publish_markdown_file, passez path (les images locales sont téléversées automatiquement, dédupliquées par contenu) ; le serveur distant ne propose que publish_markdown, donc pour un fichier local / images locales, utilisez la CLI configurée, ne passez pas le chemin à l'outil distant.

Chemin B : CLI (disponible si installée et authentifiée)

1. Si le fichier existe déjà, publiez-le directement. Si le contenu de la conversation n'a pas d'images locales, vous pouvez l'écrire dans un fichier temporaire ; s'il y a des images locales, placez le Markdown et les images nécessaires dans un répertoire temporaire en conservant leurs relations de chemins relatives, puis publiez via la CLI ou l'outil local publish_markdown_file. Les chemins des images sont résolus par rapport au répertoire du fichier Markdown, pas par rapport au répertoire de travail du terminal ; ne déplacez pas simplement le Markdown vers /tmp.
2. Exécutez :

mote <fichier.md> --json

3. Analysez le JSON sur stdout : { "id": "...", "url": "..." }

La CLI gère automatiquement les références aux images locales dans le Markdown et le HTML supporté, la validation des chemins, le téléversement et la déduplication du contenu ; les images distantes conservent leur URL d'origine, elles ne sont pas téléchargées ni empaquetées. Seules les images sont téléversées avec le document ; les liens vers d'autres fichiers Markdown locaux ne publient pas automatiquement les fichiers cibles.

Compatibilité du contenu

• Prend en charge le Markdown courant, les tableaux, les listes de tâches, les notes de bas de page, les alertes de style GitHub, et la coloration syntaxique par langage.
• Les formules mathématiques supportent un sous-ensemble de TeX ; les blocs de code mermaid prennent en charge un sous-ensemble de six types de diagrammes statiques, chaque document pouvant tenter de rendre jusqu'à quatre diagrammes. Les contenus invalides, non supportés ou hors budget peuvent s'afficher sous forme de code source ; une publication réussie ne garantit pas que toutes les syntaxes étendues ont été rendues.
• Le HTML autorisé est un sous-ensemble sécurisé ; les scripts, MDX ou intégrations interactives ne sont pas exécutés. Le téléversement ou l'intégration directe de SVG bruts n'est pas supporté ; les SVG de diagrammes générés par Mote sont nettoyés indépendamment et peuvent s'afficher.
• Après la publication de formules complexes ou de diagrammes, vérifiez les formules, les connexions, les étiquettes et les images de la page réelle ; sans vérification, ne prétendez pas que le rendu est validé.

Pour une syntaxe détaillée ou les limites, consultez les notes de compatibilité et les exemples en ligne. L'étendue du support pour les instances auto-hébergées dépend de la version déployée.

Comment traiter l'URL renvoyée

• Retournez l'URL telle quelle à l'utilisateur, sans la tronquer ni la modifier ;
• Une simple phrase suffit, par exemple « Publié : » ;
• La page est paramétrée pour interdire l'indexation par les moteurs de recherche, mais cela ne constitue pas un contrôle d'accès ni une garantie absolue de non-référencement ; l'accessibilité dépend du fonctionnement continu de l'instance et du stockage ;
• Si l'utilisateur demande ensuite de « mettre à jour cette page » : expliquez que le Markdown stocké et les actifs téléversés sont immuables, une nouvelle publication générera une nouvelle URL ; les mises à jour du Viewer peuvent modifier l'apparence, les images distantes dépendent du site source.

Limites (auto-vérification avant publication)

• Markdown ≤ 2 Mio ; image unique ≤ 10 Mio ; actifs téléversés ≤ 50 ; paquet total ≤ 20 Mio. 1 Mio = 1 048 576 octets, la CLI compte après déduplication du contenu, les images distantes ne sont pas comptées.
• Formats d'image : png / jpeg / webp / gif / avif (SVG non supporté)
• En cas de dépassement, informez honnêtement l'utilisateur de l'élément dépassé, sans supprimer de contenu par vous-même

Erreurs courantes

• Session expirée : guidez l'utilisateur pour qu'il effectue une connexion interactive sur la même instance ; si l'utilisateur a explicitement demandé de l'aide pour la connexion, continuez dans les limites de l'autorisation. N'initiez pas une connexion navigateur de votre propre chef en cas d'échec de publication, ne lisez pas les jetons d'autres clients, ne revenez pas à un ancien jeton. Consultez les instructions d'authentification pour les détails ;
• no publish token configured : vérifiez le mode d'authentification de l'instance. Le mode statique nécessite un jeton fourni par l'administrateur de l'instance ; l'instance Access nécessite une connexion OAuth ou un mode machine explicite, n'utilisez pas le jeton d'API Cloudflare Management comme clé de publication ; ne générez pas vos propres identifiants ;
• Mode machine : nécessite MOTE_AUTH_MODE=service explicite ainsi que MOTE_SERVICE_API_URL, MOTE_SERVICE_CLIENT_ID et MOTE_SERVICE_CLIENT_SECRET correspondants. En cas d'absence ou d'invalidité, arrêtez-vous, n'utilisez pas la session utilisateur à la place ;
• Timeout, 5xx ou résultat inconnu : ne réessayez pas automatiquement la publication, un document immuable a peut-être déjà été créé ; vérifiez d'abord le résultat, puis laissez l'utilisateur décider de republier ;
• asset not found: <path> : une image locale référencée dans le Markdown n'existe pas, rappelez à l'utilisateur de vérifier le chemin relatif ;
• unsupported image type : une image SVG ou autre format non supporté est référencée, suggérez à l'utilisateur de la convertir en png/webp avant de réessayer.