Folio
Lisez la demande et tout artefact existant avant d'écrire du HTML. Chaque dépendance externe et URL de publication appartient au registre du manifeste. Les artefacts sont des documents statiques — ils n'appellent pas d'API.
Quand utiliser folio — et quand ne pas l'utiliser
Folio est destiné aux livrables web durables, ouvrables et partageables — des éléments que l'utilisateur conservera, rouvrira ou remettra à quelqu'un d'autre.
Utilisez folio lorsque :
- L'utilisateur demande un document, un tableau de bord, une feuille, un diaporama ou une page qu'il sauvegardera ou enverra
- Le résultat est un livrable, pas un aperçu rapide ("fais-moi un rapport", "construis un tableau de bord pour l'équipe", "mets cela en ligne", "je veux une page qui…")
- L'utilisateur invoque un verbe explicitement (
folio publish,folio audit,folio remix,folio describe)
N'utilisez pas folio lorsque :
- L'utilisateur veut un aperçu rapide, pas un livrable ("montre-moi", "à quoi ça ressemble", "vérifie juste", "peux-tu afficher")
- Le résultat ne sera pas rouvert après cette conversation — répondez en ligne ou écrivez un fichier temporaire, ne le tamponnez pas, ne le registrez pas, ne le bloquez pas
- La demande concerne un extrait de code, un fichier de configuration, une seule fonction — ce ne sont pas des artefacts de navigateur
Porte d'entrée. Avant d'entrer dans le flux d'artefacts, demandez : l'utilisateur rouvrira-t-il ce fichier après cette session ? Si non, folio n'est pas le bon outil — répondez simplement. Si oui, continuez.
Autonome est la valeur par défaut. Le chemin le plus léger de folio est un dossier unique avec un index.html — pas de racine de site, pas de site.json, pas de page d'index. Une racine de site apparaît seulement lorsqu'il y a un deuxième artefact ou que l'utilisateur demande à publier une collection. Ne créez pas de cérémonie de site pour un seul fichier.
Glossaire
Utilisez uniquement ces termes dans la sortie de Folio.
| Terme | Signification |
|---|---|
| artefact | Livrable web statique autonome : HTML avec CSS/JS, exécutable dans un navigateur |
| bundle | L'un de single-file (CSS/JS en ligne) ou multi-file (ressources liées dans un répertoire) |
| type d'artefact | L'un de doc, feuille, tableau de bord, explicatif, diapositives, outil, page d'atterrissage |
| profil d'hébergement | Où le site réside durablement : local, surge, gh-pages, cf-pages, cf-worker |
| partage (tunnel) | URL publique temporaire vers le serveur local en cours, via localhost.run (par défaut) ou ngrok. Éphémère, la machine reste l'hôte — ce n'est pas une publication |
| racine de site | Répertoire contenant un index.html et une arborescence artifacts/, publié comme un seul domaine. Les artefacts sont des chemins en dessous, pas des sous-domaines séparés. |
| manifeste de site | .folio/site.json — la source de vérité canonique. Porte le domaine + le registre par artefact (slug, type, bundle, registre, provenance, état de publication). Le tampon, l'index et l'audit en dérivent. |
| artefact autonome | Artefact sans racine de site. Le tampon HTML est son seul manifeste. Passe à une entrée de site lorsqu'un deuxième artefact apparaît. |
| provenance | Le champ source sur un artefact remixé : { slug, site, url }. Null pour les originaux. Lu par describe, audit et remix. |
| manifeste | HTML d'entrée, liste de fichiers, dépendances externes et métadonnées de publication optionnelles |
| registre | Le registre du manifeste — dépendances, fichiers de données, URLs et niveaux de preuve avant construction |
| porte | Vérification binaire qui doit passer avant la remise |
| niveau de preuve | L'un de observé, dérivé, déclaré, absent |
Comment utiliser cette compétence
- Par défaut : créer ou mettre à jour un artefact. Suivez le flux d'artefact. Un artefact unique est autonome par défaut — pas de racine de site requise.
folio audit <chemin|url>: audit en lecture seule. Ne modifiez pas. Lisezreferences/verbs/audit.md.folio describe <chemin|url|slug>: lire l'entrée du manifeste d'un artefact (type, registre, provenance, état de publication). Lisezreferences/verbs/describe.md.folio share <racine-de-site>: ouvrir un lien temporaire public vers le site en cours via un tunnel (par défaut localhost.run — pas d'installation, pas de compte ; alternative--ngrok). La machine reste l'hôte ; l'URL meurt avec le processus. Utilisez ceci pour "laissez quelqu'un voir maintenant", pas pour publier. Lisezreferences/verbs/share.md.folio publish <racine-de-site>: déployer une racine de site (tous les artefacts) vers le profil d'hébergement choisi pour un hébergement durable ailleurs. Régénérez d'abord l'index (scripts/gen-index.js), puis déployez. Lisezreferences/verbs/publish.md.folio remix <chemin|url>: forker un artefact et le modifier tout en préservant l'honnêteté du manifeste et en enregistrant la lignée source. Lisezreferences/verbs/remix.md.
Un exécution = un artefact, sauf si l'utilisateur en nomme plusieurs. Préférez le plus petit bundle qui satisfait la demande. Un artefact unique est autonome ; plusieurs artefacts vivent sous une seule racine de site et sont publiés comme un seul domaine. Lisez references/site-index.md pour le modèle de racine de site et la mise à niveau autonome-vers-site.
Disciplines non négociables
- Exécutable avant d'être beau. L'artefact s'ouvre dans un navigateur et les interactions de base fonctionnent avant le polissage ou la publication.
- Documents statiques uniquement. Pas de
fetch()vers des API externes, pas de connexions WebSocket, pas deXMLHttpRequestvers des points d'accès en direct. Les données sont intégrées en ligne, chargées à partir d'un fichier local viafetch('./data/…'), ou générées au moment de la construction. Les seules requêtes réseau que fait un artefact sont vers des scripts CDN, des styles et des polices enregistrés. - Honnêteté du manifeste. Les scripts CDN, polices, images et fichiers de données sont des lignes de registre, pas des surprises.
- Local d'abord, puis partage, puis publication. Le profil d'hébergement par défaut est
local. Exécutez-le de manière dynamique —node <folio-skill>/scripts/serve.js <racine-de-site>garantit le dossierartifacts/, régénère la page d'index/recherche à partir du registre, choisit un port ouvert et sert via HTTP (un simplefile://convient pour un fichier unique entièrement en ligne, mais cassefetchet les imports de modules). Voirreferences/local-server.md. Pour montrer à quelqu'un maintenant, ouvrez un tunnel temporaire —node <folio-skill>/scripts/share.js <racine-de-site>(par défaut localhost.run, pas d'installation/compte) ; le lien est éphémère et la machine reste l'hôte. L'hébergement durable ailleurs estpublish— seulement lorsque l'utilisateur le demande ou quefolio publishest invoqué. Ne faites jamais la promotion proactive des capacités de partage ou de publication. - Pas de secrets dans les fichiers statiques. Les clés API, jetons et URLs privées n'ont pas leur place dans le HTML/JS commité ou publié.
- Pas moche. Les artefacts suivent la ligne de base visuelle. Lisez
references/visual-baseline.mdavant la construction.
Trace de décision en or
Demande : Construire un histogramme de latence interactif à partir de ce CSV pour un collègue.
Inventaire :
· Cible : nouvel artefact `latency-hist`
· Existant : aucun
· Données : utilisateur a joint `runs.csv` (observé, 840 lignes)
· Contraintes : dossier local, pas de publication
Choix : type=explicatif · bundle=multi-fichier · hôte=local · audience=remise à un collègue
Registre :
dép | type | preuve | dans l'artefact sous
d3@7 (cdn.jsdelivr) | script | déclaré, utilisateur n'a pas épinglé | balise script index.html + note dans README
runs.csv | donnée | observé | ./data/runs.csv, chargé via fetch('./data/runs.csv')
Plan de fichiers :
Créer : artifacts/latency-hist/index.html, style.css, app.js, data/runs.csv, README.md
Pas de suppressions.
Vérification : npx serve artifacts/latency-hist ; le graphique s'affiche ; console propre
Portes : ouvre-localement=oui, console-propre=oui, registre-complet=oui, pas-de-secrets=oui, maquette-étiquetée=s.o., ligne-de-base-visuelle=oui
Remise : chemin, comment ouvrir, résumé du registre, reporté : aucun
Portée de la fourche
Résoudre la portée avant les grandes questions de conception.
| Forme de la demande | Bundle | Hôte | Ignorer |
|---|---|---|---|
| Démo rapide jetable | single-file | local | README, publication, multi-page |
| Document écrit ou rapport | single-file ou multi-file | local | Graphiques, JS lourd |
| Tableau de données ou feuille | single-file ou multi-file | local | Prose narrative, décoration |
| Tableau de bord de métriques | multi-file | local | CRUD complet, flux de données en direct |
| Explicateur de concept | multi-file | local | Décharges de données brutes denses |
| Diaporama | multi-file | local | Dispositions de défilement, widgets |
| Artefact partagé avec un collègue | multi-file | local | Étape de construction du framework |
| Montrer à quelqu'un maintenant | single-file ou multi-file | share (tunnel) | Cérémonie de déploiement, hôte durable |
| Lien public durable | multi-file | surge ou cf-pages | Authentification, logique serveur |
| Aperçu de transfert d'agent | single-file préféré | local | Partager/publier sauf si demandé |
Demande ambiguë : demandez une fois, de manière concise. Exemple : "Fichier unique autonome ou petit dossier avec CSS/JS séparés ?" Si sans réponse, choisissez le plus petit bundle qui fonctionne.
Flux d'artefacts
0. Inventaire
Lisez la demande et toute arborescence d'artefact existante. Lisez references/evidence.md et references/artifact-types.md.
Collectez :
- Sujet : ce que l'artefact doit montrer ou permettre à l'utilisateur de faire
- Entrées : fichiers, JSON, CSV, copie, contraintes de conception (avec niveaux de preuve)
- Artefact existant : chemin, HTML d'entrée, manifeste, dernière URL de publication si existante
- Profil d'hébergement : par défaut
local; lisezreferences/host-profiles.mdlorsque la publication est dans le périmètre - Source de convention :
folio.mdsi présent
Émettez un inventaire compact avec des citations avant de procéder.
1. Choix
Émettez avant de construire : Choix : type=<x> · bundle=<y> · hôte=<z> · audience=<a>.
Lisez references/artifact-types.md lorsque le type est flou. Lisez references/host-profiles.md lorsque l'hôte n'est pas local.
2. Registre du manifeste
Construisez le registre avant d'écrire du HTML. Lisez references/manifest-ledger.md.
Colonnes :
dép | type | preuve | dans l'artefact sous
Types : script, style, font, image, data, mock, publish-target.
Les fichiers de données et les données simulées doivent être explicites. Les appels API externes sont hors de portée — voir la discipline #2.
3. Plan de fichiers et construction
Indiquez le plan de fichiers avant d'éditer :
Créer : artifacts/<slug>/index.html, app.js, data/sample.json
Modifier : aucun
Pas de suppressions.
Partez d'un modèle. Chargez references/templates/<type>.html et adaptez-le — remplacez le contenu {{placeholder}} et les marqueurs <!-- Replace: ... --> par du vrai contenu. Les modèles sont des artefacts folio qui passent les portes ; ils portent le bloc de jetons, le bouton jour/nuit, le favicon et la structure spécifique au type. Lisez l'index de references/templates/ pour savoir ce que fournit chaque modèle.
Lisez references/visual-baseline.md avant d'écrire du CSS.
Construisez avec du HTML/CSS/JS simple sauf si l'utilisateur a nommé une stack spécifique. Préférez :
- HTML sémantique, un fichier d'entrée évident (
index.html) - Propriétés personnalisées CSS pour tous les jetons visuels (couleur, type, espacement, rayon, ombre)
- OKLCH pour la couleur ; pas de hex/rgb en ligne en dehors du bloc de jetons
:root - JS vanille ou une seule bibliothèque CDN nommée — enregistrée
multi-file: gardez tous les chemins de ressources relatifs ; pas de chemins machine absolus- Pas de titres en italique ; mesure lisible (
max-width: 60–70ch) ;overflow-x: clipsurhtmletbody
Lisez references/security.md lorsque l'artefact accepte une entrée utilisateur, intègre du contenu tiers ou est publié publiquement.
Tampons (commentaire HTML, en haut du fichier d'entrée) :
<!-- Folio · slug: latency-hist · type: explicatif · bundle: multi-fichier · hôte: local -->
<!-- dép: d3@7 · données: runs.csv · publication: aucun -->
Pour single-file, gardez le tampon minimal (une ligne).
4. Vérification
Lisez references/verification.md. Exécutez les vérifications qui correspondent au profil d'hébergement.
Matrice minimale :
vérification | commande/preuve | résultat | notes
Exemples : serveur statique + charger l'URL d'entrée, console DevTools propre, cliquer sur l'interaction primaire, scan de liens cassés, note file:// vs serveur pour fetch, vérification visuelle de la ligne de base.
5. Portes
Appliquez avant la remise. Tout non déclenche une boucle de correction.
| Porte | Vérification |
|---|---|
ouvre-localement | Le HTML d'entrée se charge via un serveur statique (ou la réserve honnête file:// documentée) ; pour la configuration du serveur, voir references/local-server.md (scripts/serve.js est le chemin en une commande) |
console-propre | Pas d'erreurs non interceptées sur le chemin principal |
registre-complet | Chaque dépendance externe et source de données apparaît dans le registre |
pas-de-secrets | Pas de clés, jetons ou URLs privées dans le code source |
maquette-étiquetée | Données simulées/échantillon étiquetées lorsque les données réelles sont absentes |
statique-uniquement | Pas de fetch() vers des API externes, pas de WebSocket, pas de XHR vers des points d'accès en direct |
ligne-de-base-visuelle | Bloc de jetons présent, pas de couleurs en ligne en dehors de :root, pas de titres en italique, contraste adéquat |
prêt-à-publier | Lors de la publication : les étapes du profil d'hébergement documentées et vérifiées ou explicitement reportées |
dérivation-manifeste | Consultatif. Le tampon HTML (slug, type, bundle) correspond à l'entrée site.json pour cet artefact. Signale les dérives ; voir references/verification.md#manifest-derivation-check. |
Lisez references/slop-test.md après la construction. Corrigez P0/P1 avant la remise.
6. Publication (optionnelle)
Uniquement lorsque l'utilisateur demande une publication ou invoque folio publish. Lisez references/verbs/publish.md et le fichier approfondi du profil d'hébergement.
Enregistrez l'URL de publication dans le manifeste et la remise. Ne revendiquez jamais une URL sans preuve de la sortie de la commande de publication.
7. Remise
Incluez :
- Chemin de l'artefact et fichier d'entrée
- Comment ouvrir localement (commande exacte)
- URL de publication (si publiée), avec preuve
- Résumé du registre du manifeste
- Commandes et résultats de vérification
- Éléments reportés (par exemple,
fetchnécessite un serveur, données simulées utilisées)
N'enterrez pas les faits du manifeste ou de la publication sous des bavardages d'implémentation.
Contraste MAUVAIS/BON
MAUVAIS : Câbler fetch('/api/users') parce que les tableaux de bord chargent généralement les utilisateurs depuis une API.
BON : Intégrer data/users.json avec une étiquette visible "Données échantillon". Pas d'appels API.
MAUVAIS : Coller Google Analytics, des polices et trois bibliothèques CDN sans les lister. BON : Chaque dépendance est une ligne de registre avec URL et objectif.
MAUVAIS : "Déployé à https://demo.example.com" sans avoir exécuté de commande de publication. BON : URL de publication copiée depuis la sortie de la commande, ou marquée comme reportée.
MAUVAIS : Valeurs oklch() en ligne dispersées dans le CSS, trois déclarations font-family différentes.
BON : Toutes les valeurs visuelles dans le bloc de jetons :root, référencées via var().```