coursmith-course

Créer et publier un cours Coursmith

Vous écrivez un cours sous la forme d'un dossier contenant course.json et un répertoire assets/, vous le vérifiez avec l'interface en ligne de commande coursmith, puis vous le soumettez. Un agent de révision sur le portail l'approuve ensuite, demande une révision ou le rejette. Votre travail se termine lorsque le cours est approuvé, ou lorsque vous avez expliqué le résultat de la révision à l'utilisateur.

Exécutez l'interface en ligne de commande avec npx --yes coursmith@latest <commande> --json. Le paquet npm public inclut l'interface en ligne de commande et cette compétence ; aucun accès GitHub ni installation globale n'est nécessaire. Si npx est manquant, demandez à l'utilisateur d'installer Node.js 20 ou plus récent et de suivre le guide à /install. Avec --json, chaque commande imprime un document JSON ; lisez-le au lieu de deviner.

Fichiers de référence dans ce dossier de compétence (lisez-les lorsque vous atteignez l'étape correspondante) :

Fichier	Utilisation
references/course.schema.json	La structure exacte de course.json. Les clés inconnues sont rejetées.
references/block-catalog.md	Chaque bloc de contenu et visuel, avec des exemples JSON valides et des règles.
references/animation-presets.md	Les 7 préréglages d'animation et quand les utiliser.
references/writing-guide.md	Comment rédiger des étapes, glossaires et quiz qui passent la révision.
references/content-policy.md	Ce qui n'est pas autorisé et comment traiter les sujets sensibles.
examples/sample-course/	Un cours complet qui passe la validation. Copiez sa structure.

1. Se connecter

1. Exécutez npx --yes coursmith@latest whoami --json. Si cela imprime un username, passez à l'étape 2.
2. Sinon, exécutez npx --yes coursmith@latest login --no-wait --json. Montrez à l'utilisateur le verificationUri et le userCode et demandez-lui d'ouvrir le lien, de vérifier le code et de cliquer sur Approuver.
3. Lorsque l'utilisateur confirme, exécutez npx --yes coursmith@latest login --resume --json et vérifiez qu'il imprime logged_in.

2. Se mettre d'accord sur le cours avec l'utilisateur

Demandez, en un seul message, tout ce que l'utilisateur n'a pas déjà fourni :

• Sujet et, si utile, l'angle ou le public cible.
• Langue du cours (n'importe quelle langue ; vous aurez besoin de son code BCP-47 tel que it, en, pt-BR).
• Difficulté : débutant, intermédiaire ou avancé.
• Optionnel : durée souhaitée (par défaut environ 30 minutes), prérequis, éléments à inclure ou à éviter.

Vérifiez le sujet par rapport à references/content-policy.md. S'il n'est pas autorisé, dites-le et arrêtez-vous. S'il s'agit d'un sujet sensible (santé, droit, finance, politique, religion…), planifiez un traitement neutre et une clause de non-responsabilité.

3. Proposer un plan et le faire approuver

Montrez à l'utilisateur :

• le titre, un sous-titre d'une ligne, 2 à 6 objectifs d'apprentissage ;
• 3 à 6 sections, chacune avec un résumé d'une ligne et 2 à 5 titres d'étapes ;
• pour chaque étape, le visuel que vous prévoyez (graphique, diagramme, préréglage d'animation, image ou rien) ;
• le nombre prévu de questions de quiz (au moins 10, couvrant chaque section).

Révisez jusqu'à ce que l'utilisateur soit d'accord. N'écrivez pas course.json avant cela.

4. Écrire le cours

Créez un nouveau dossier nommé d'après le cours (en kebab-case) avec course.json et assets/. Suivez exactement references/course.schema.json et copiez la structure de examples/sample-course/course.json.

Règles appliquées par le validateur (détails dans references/block-catalog.md) :

• schemaVersion est "1.0". N'écrivez pas courseId : l'interface en ligne de commande le gère.
• Tous les identifiants sont en lettres minuscules, chiffres et tirets, uniques dans tout le cours (sections, étapes, ressources, questions de quiz).
• Chaque étape a un title et au moins un bloc ; la plupart des étapes ont également un visual.
• Glossaire : chaque section a un glossary qui définit chaque concept qu'elle introduit et chaque terme technique ou domaine qu'elle utilise. Dans le texte, marquez chaque terme comme [[terme]], ou [[terme|texte affiché]] lorsque le libellé diffère (utilisez aliases pour les pluriels et les inflexions). Un terme marqué doit être défini dans la même section ou une section antérieure. Les définitions sont autonomes et rédigées dans la langue du cours.
• Visuels : les graphiques sont des spécifications Vega-Lite avec data.values en ligne (pas d'URL) ; les diagrammes sont en Mermaid sans click ni %%{init}%% ; les animations utilisent un des 7 préréglages ; les images font référence à une ressource par son identifiant.
• Markdown : pas de HTML brut, pas d'images Markdown (utilisez un bloc image), les liens doivent être https://.
• Quiz final : au moins 10 questions ; chaque section est testée par au moins une question (sectionRef) ; chaque question a une explanation. Types : single, multiple, true_false, ordering (les éléments de classement sont listés dans le bon ordre ; le portail les mélange).
• Des questions check optionnelles à la fin d'une étape donnent aux apprenants un retour rapide et ne sont pas notées.

Écrivez section par section et maintenez la cohérence de la langue, de la difficulté et de la terminologie tout au long du cours (voir references/writing-guide.md).

5. Créer les ressources

• Une image de couverture est requise (meta.coverImage), idéalement 1200×630.
• Si vous disposez d'un outil de génération d'images, produisez des fichiers PNG, JPEG ou WebP. Sinon, écrivez du SVG propre à la main : formes simples, palette claire, viewBox défini, pas de scripts, pas de liens ou polices externes, pas d'images intégrées.
• Pour une animation highlight-svg, donnez aux éléments à mettre en surbrillance un attribut id.
• Placez chaque fichier directement dans assets/ et déclarez-le dans assets[] avec kind (image ou svg), file (assets/<nom>) et un texte alt significatif. Remplissez generatedBy pour les images générées par IA.
• Chaque fichier doit faire moins de 3 Mo ; l'ensemble du bundle moins de 25 Mo.

6. Valider jusqu'à ce que ce soit propre

Exécutez npx --yes coursmith@latest validate <dossier> --json. Cela imprime { "ok": ..., "issues": [...] } ; chaque problème a severity, code, path (par exemple sections[1].steps[0].blocks[2]) et message.

Corrigez chaque error, puis exécutez à nouveau. Répétez jusqu'à ce que ok soit true. Corrigez également les avertissements lorsqu'ils sont peu coûteux (par exemple glossary.unreferenced : marquez le terme avec [[...]] là où il est utilisé).

7. Soumettre et suivre la révision

1. Exécutez npx --yes coursmith@latest submit <dossier> --json. Cela télécharge le cours et imprime status: "in_review" avec un submissionId. L'interface en ligne de commande écrit .coursmith.json dans le dossier ; conservez-le, car il lie les soumissions ultérieures au même cours.
2. Exécutez npx --yes coursmith@latest status --dir <dossier> --wait --json (il attend jusqu'à 10 minutes ; exécutez-le à nouveau si le statut est toujours in_review).
3. Agissez en fonction du status :
   • approved : donnez à l'utilisateur le courseUrl. Mentionnez toutes suggestions optionnelles dans review.issues.
   • needs_revision : pour chaque problème dans review.issues, ouvrez l'élément à path, appliquez la suggestion (ou corrigez ce que décrit message), puis validez et soumettez à nouveau. Dites à l'utilisateur ce que vous avez changé. Les problèmes avec severity: "warning" sont facultatifs.
   • rejected : expliquez review.summary à l'utilisateur. Ne soumettez pas à nouveau le même contenu.

Si submit signale review_in_progress, attendez la révision en cours avec status --wait d'abord.

Mettre à jour un cours publié

Modifiez le même dossier (conservez .coursmith.json) et soumettez à nouveau. La nouvelle version passe par la révision tandis que la version actuelle reste en ligne ; maintenez les identifiants des étapes stables pour que les apprenants conservent leur progression.

Dépannage

Sortie de l'interface en ligne de commande	Que faire
not_logged_in / code de sortie 3	Revenez à l'étape 1.
client_outdated	Réessayez avec npx --yes coursmith@latest pour que npm récupère la dernière version de l'interface en ligne de commande.
validation_failed de submit	Exécutez validate et corrigez les problèmes qu'il liste.
rate_limited	L'utilisateur a atteint la limite de soumission quotidienne ; réessayez demain.
assets.content_type / assets.invalid	Le contenu du fichier ne correspond pas à son extension, ou il est corrompu. Réexportez-le.
animation.unknown_element	Le SVG ne contient pas d'élément avec cet id (les identifiants sont conservés, les scripts et liens externes sont supprimés).