getshareout/shareout-skill

Skill ShareOut

ShareOut transforme des fichiers en artefacts web partageables avec données persistantes, collaboration en temps réel, stockage de fichiers, intégrations et automatisation. Il prend en charge les applications HTML ainsi que les visualiseurs CSV, Markdown, JSON et TXT.

Ceci est le skill canonique. Chargez-le en premier pour toute tâche ShareOut.

Vérification de version — étape obligatoire

Avant toute autre chose, confirmez que vous disposez de la dernière version du skill. La version dans l'en-tête de ce fichier est la version que vous détenez actuellement (actuellement 2.21.0).

1. GET https://shareout.site/v1/skill/version → { "version": "...", "updated_at": "..." }.
2. Si la version renvoyée est plus récente que celle de ce fichier, vous êtes obsolète : téléchargez GET https://shareout.site/v1/skill (un zip du dossier complet du skill), extrayez-le, jetez votre ancienne copie et continuez à partir des fichiers extraits.
3. Si elles correspondent, poursuivez.

Ne sautez pas cette vérification. Utiliser un skill obsolète produit des endpoints et comportements erronés.

Modèle de plan

ShareOut propose deux plans :

Plan	Utilisez ce comportement du skill
Personnel	Utilisez uniquement ce skill de base. Créez, publiez, mettez à jour, automatisez et gérez les artefacts de l'utilisateur.
Équipes	Utilisez d'abord ce skill de base, puis chargez la surcouche Équipes pour l'administration de l'espace de travail ou les capacités réservées à Équipes.

Équipes est additif. N'utilisez jamais la surcouche Équipes à la place de ce skill de base.

Protocole de chargement de l'agent

1. Commencez par ce fichier.
2. Si l'utilisateur mentionne une équipe, un espace de travail, des membres, un partage interne d'espace de travail, un sous-domaine, un style interne, des plannings d'espace de travail ou des contrôles administrateur, demandez s'il est sur le plan Équipes si ce n'est pas déjà clair.
3. Si l'utilisateur n'est pas sur Équipes, restez en mode Personnel et ne chargez ni n'appliquez les instructions réservées à Équipes.
4. Si l'utilisateur est sur Équipes, chargez team/SKILL.md. Si un slug/id d'espace de travail et un jeton sont disponibles, récupérez GET /v1/skill?workspace={slugOrId} — le zip inclut un fichier workspace-context.md supplémentaire avec les règles internes.
5. Utilisez INDEX.md pour charger des fichiers détaillés à la demande.

Premières questions

Avant de recommander une implémentation, identifiez :

1. Que construisent-ils ? Tableau de bord, formulaire, rapport, outil, document, grille de données, présentation ou automatisation.
2. Qui l'utilise ? Uniquement le propriétaire, des personnes invitées, un espace de travail Équipes ou le public.
3. De quelles données a-t-il besoin ? Aucune, état simple, enregistrements structurés, fichiers, données externes en direct, ou collaboration en temps réel.
4. Que doit-il se passer après la publication ? Partager un lien, collecter des données, envoyer des notifications, planifier une livraison, alerter sur des métriques, recevoir et agir sur les e-mails entrants, ou permettre aux visiteurs de discuter avec l'IA.

Routeur de mode

Intention de l'utilisateur	Charger d'abord	Puis si nécessaire
Publier HTML/CSV/Markdown/JSON/TXT	api/artifact-types.md	api/artifacts.md, core/source-editor.md, auth.md
Construire une application/page/tableau de bord/formulaire HTML	core/html-spec/overview.md	modules/ui/overview.md, patterns/overview.md
Améliorer l'apparence / bon goût / éviter un look IA générique	modules/ui/taste.md	modules/ui/overview.md
Sauvegarder un état simple	sdk/json.md	core/html-spec/manifest.md
Stocker des enregistrements/soumissions	sdk/table.md	patterns/forms.md, patterns/tables.md
Grille de feuille de calcul modifiable	sdk/grid.md	sdk/table.md, integrations/google-sheets.md
Télécharger des fichiers/images	sdk/blobs.md	patterns/uploads.md
Utiliser des données externes en direct	sdk/live-data.md	sdk/connections.md, integrations/overview.md
Construire une collaboration en temps réel	sdk/realtime.md	modules/_shared/permissions.md
Ajouter des commentaires	sdk/comments.md	modules/_shared/permissions.md
Ajouter une discussion IA dans l'artefact	agents/overview.md	agents/context.md
Discuter avec des pages via Telegram	agents/telegram.md	api/jobs.md
Discuter avec des pages via Slack (bot DM)	agents/slack.md	integrations/slack.md, agents/telegram.md
Exécuter Python dans le navigateur	sdk/python.md	sdk/overview.md
Envoyer un e-mail ou des modèles	sdk/email.md	api/templates.md
Recevoir un e-mail / transférer du courrier vers un artefact / déclencher sur e-mail entrant	integrations/inbound-email.md	api/jobs.md
Actualisation planifiée d'entrepôt/json snapshot (déterministe)	api/jobs.md	agents/crew.md, sdk/connections.md
Équipe d'artefact (requête → résumer → livrer)	agents/crew.md	api/jobs.md, integrations/slack.md
Demander l'accès à une page privée	modules/_shared/permissions.md	core/access-policy.md
Planifier une livraison ou des webhooks	api/jobs.md	api/destinations.md
Alerter lorsqu'une métrique franchit un seuil	api/metric-alerts.md	patterns/dashboards.md
Espace de travail Équipes/administrateur/sous-domaine/contexte	team/SKILL.md	team/INDEX.md
Gouvernance de publication Équipes (approbation membre pour public)	team/publish-governance.md	team/SKILL.md, modules/_shared/publishing.md
Marketplace de skills Équipes (playbooks réutilisables)	team/skill-marketplace.md	team/workspace-context.md, agents/overview.md

Choix des données

Choisissez le plus petit stockage adapté :

État simple : thème, filtres, dernier ouvert -> sdk.json
Enregistrements structurés : tâches, soumissions, commandes -> sdk.table()
Édition en temps réel : docs, tableaux blancs, interface multi-utilisateur -> sdk.realtime()
Fichiers : images, PDF, pièces jointes -> sdk.blobs
Systèmes externes en direct : REST, BigQuery, Mixpanel, entrepôts -> sdk.connection / live-data

Ne confondez pas le choix des données avec le plan de compte. sdk.json, sdk.table() et sdk.realtime() sont des stockages de données, pas des plans de facturation.

Chargement du SDK

<head>
  <link rel="stylesheet" href="https://shareout.site/sdk/shareout.css">
  <script src="https://shareout.site/sdk/shareout-ui.js" defer></script>
  <script src="https://shareout.site/sdk/shareout.js"></script>
</head>
<script>
(async () => {
  const sdk = await ShareOut.create();
})();
</script>

Règles :

• Chargez https://shareout.site/sdk/shareout.js avant d'appeler ShareOut.create().
• Préférez await ShareOut.create() à new ShareOut() pour que le jeton Bearer intégré soit prêt.
• Le HTML publié s'exécute dans un iframe en bac à sable sur {hex}.shareoutcdn.site ; utilisez les méthodes SDK, pas un fetch brut vers /v1/data/.... Voir sdk/live-data.md.
• Liez https://shareout.site/sdk/shareout.css et utilisez les classes .so- avant d'écrire du CSS personnalisé. Voir modules/ui/overview.md.
• N'utilisez pas d'URLs SDK ShareOut via cdn.jsdelivr.net.

Règles des artefacts HTML

Les artefacts HTML fonctionnent qu'ils portent ou non les marqueurs structurels de ShareOut — la publication n'est jamais bloquée. Mais plus l'artefact déclare, plus l'éditeur visuel peut en faire (navigation par plan, édition en ligne, ajout/suppression de lignes). Visez par défaut un état prêt pour l'éditeur ; sautez-le uniquement pour une page statique délibérément jetable.

Liste de contrôle pour l'état prêt éditeur (ce que l'éditeur recherche) :

• Une balise script type="shareout/manifest" dans le head du document, avec JSON valide.
• Chaque clé sdk.json et chaque nom sdk.table() utilisé sont déclarés dans les sources du manifeste.
• Le contenu dynamique porte data-shareout-binding, et chaque liaison référence une source déclarée.
• Les pages utilisent data-shareout-page (pilote le plan de l'éditeur) ; le contenu répété utilise data-shareout-template.
• Les cibles interactives résolvent : data-shareout-link / data-shareout-action pointent vers des pages/sections/modales/onglets réels ; les modales ont un déclencheur d'ouverture ; les formulaires ont une soumission.
• Déclarez des données default d'exemple sur les sources — json, tables et connections (connecteurs live comme BigQuery/Snowflake/Sheets : sources.connections.<name>.default est un tableau d'échantillons de lignes). L'éditeur visuel prévisualise les données sans aucune récupération ou requête en direct (il résout toutes les lectures SDK — y compris sdk.connection(...).query() — à partir de ces valeurs par défaut, ou vides), donc un artefact qui verrouille son interface derrière await sdk.table(...).exec() / une requête de connecteur s'affiche et reste modifiable. Une source sans default prévisualise vide.

Chaque publication d'un artefact HTML renvoie un profil d'avis editor_readiness (voir api/artifacts.md) qui évalue ces critères et nomme chaque écart désactive. Partagez un résumé d'une ligne avec l'utilisateur, mais traitez-le comme un guide, pas une contrainte — ils peuvent publier exactement ce qu'ils veulent.

Spécification complète : core/html-spec/overview.md.

Goût en design

L'état prêt éditeur concerne la structure, pas l'apparence. L'apparence est une décision distincte et délibérée — et la valeur par défaut pour les pages construites par IA est « basée sur modèle et générique ». Avant de construire quoi que ce soit de visuel, lisez modules/ui/taste.md : il distille comment livrer des artefacts qui semblent conçus professionnellement plutôt qu'auto-générés. La version courte :

• Utilisez le système de design (classes .so- + tokens) — il fournit des polices de marque, une palette lumineuse chaleureuse et des espacements/ombres harmonisés, vous héritez donc d'un bon goût gratuitement. Voir modules/ui/overview.md.
• Le goût est la retenue : une couleur d'accent, un système de police, une action principale par écran, généreux espaces blancs, mouvement uniquement quand motivé.
• Évitez les marqueurs de l'IA de basse qualité : lueurs violettes/néon, rangées de trois cartes égales, surcharge de « eyebrow », chiffres parfaits factices, clichés marketing, états vides/d'erreur manquants. La liste complète des interdits et une liste de contrôle avant publication se trouvent dans modules/ui/taste.md.

Types d'artefacts

ShareOut détecte automatiquement le type à partir du type MIME ou de l'extension de fichier :

Type	Extensions	Utilisation
html	.html, .htm	Applications SDK complètes, tableaux de bord, outils, présentations
csv	.csv	Grilles de données triables/filtrables
markdown	.md, .markdown	Documents avec HTML rendu et table des matières
json	.json	Visualiseur d'arbre pliable
txt	.txt	Visualiseur de texte brut/log

Détails : api/artifact-types.md.

Première exécution — Obtenir un jeton

Toute action authentifiée nécessite un jeton. Si ~/.shareout/credentials n'existe pas encore, l'utilisateur n'a pas de compte — créez-en un avant de publier ou tout autre appel authentifié :

1. POST https://shareout.site/v1/auth/create-account (le seul endpoint non authentifié, sans corps) → { "token": "so_…", "user_id": "usr_…" }.
2. Sauvegardez le token dans ~/.shareout/credentials en tant que { "token": "so_…" } (chmod 600).
3. Toutes les requêtes ultérieures utilisent Authorization: Bearer so_….

La création de compte est limitée en débit par IP (code: RATE_LIMIT_EXCEEDED, 429). Le compte est anonyme et sans tête — aucun e-mail n'est requis pour publier.

Demandez ensuite à l'utilisateur s'il souhaite connecter Gmail/Google. Le compte sans tête n'a pas d'e-mail, il ne peut donc être utilisé qu'avec le jeton stocké. Lier un e-mail leur permet de se connecter à l'interface web sur https://shareout.site (tableau de bord d'accueil, éditeur visuel, jetons API en libre service). Proposez les deux chemins :

• Google : ouvrez GET https://shareout.site/v1/auth/link-google (jeton Bearer) dans un navigateur pour lier leur compte Google.
• Code e-mail : POST /v1/auth/link-email/start { "email" } → POST /v1/auth/link-email/verify { "email", "code" } (code à 6 chiffres, expiration 10 min).

S'ils refusent, le flux jeton uniquement continue de fonctionner. Voir auth.md pour la référence complète d'intégration et de liaison.

Publication

ShareOut est protégé par Cloudflare. Python requests peut déclencher un blocage 1010. Construisez les charges utiles comme vous le souhaitez, puis redirigez vers curl :

TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.shareout/credentials')))['token'])")
python3 build_payload.py | curl -sS -X POST 'https://shareout.site/v1/publish' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @-

API complète : api/overview.md.

Périmètre Équipes

Les artefacts personnels peuvent toujours être privés, partagés avec des collaborateurs, publics ou non listés. Ne chargez les documents Équipes que pour les capacités d'espace de travail du plan Équipes :

• Membres et rôles d'espace de travail.
• Visibilité interne d'espace de travail (visibility: "workspace").
• Politique d'adhésion à l'espace de travail par e-mail/domaine.
• Sous-domaines d'espace de travail.
• Fichiers de contexte d'espace de travail pour style interne.
• Plannings, automatisations, indicateurs de fonctionnalités et vues administrateur au niveau de l'espace de travail.

Distinction importante des termes :

Terme	Signification
access_policy	Filtrage des données au niveau des lignes d'artefact : chaque visiteur voit uniquement les lignes autorisées. Voir core/access-policy.md.
Politique d'adhésion à l'espace de travail	Règles d'adhésion par e-mail/domaine pour Équipes : qui peut rejoindre un espace de travail. Voir team/SKILL.md.
Rôle collaborateur	owner, editor, viewer au niveau de l'artefact.
Rôle espace de travail	owner, admin, member pour Équipes.

Vérification de version

Exécutez la vérification de version obligatoire avant chaque tâche. Trois manières équivalentes de comparer votre version détenue avec la version en direct :

GET  https

…

[truncé pour traduction]