Communitygithub.com

AntTheLimey/gm-apprentice

Publie un coffre de campagne gm-apprentice en tant que site statique sur GitHub Pages ou Cloudflare Pages, et exécute la boucle de demandes de modification en table qui permet aux joueurs de demander des modifications de feuille de personnage pendant la partie.

Qu'est-ce que gm-apprentice ?

Cette compétence transforme le contenu d'un coffre Obsidian de campagne TTRPG en un site web statique prêt à être partagé avec les joueurs. Elle prend en charge les déploiements sur Cloudflare Pages (recommandé) et GitHub Pages, et gère l'ensemble du cycle de vie : configuration initiale, mises à jour de routine, dépannage, migrations de schéma, filtrage de contenu et une boucle de demandes de modification en table pour les modifications de feuilles de personnage (GURPS 4e et CoC 7e). Elle est conçue pour les MJ non techniques, en expliquant clairement chaque étape. La compétence s'appuie sur l'outil `gm-apprentice-publish` intégré au plugin, et nécessite Node.js 22+ et l'accès à un dépôt git. Elle est compatible avec les agents qui peuvent exécuter des commandes shell et lire/écrire des fichiers dans l'environnement du plugin.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AntTheLimey/gm-apprentice/tree/HEAD/skills/publish-site

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Publier un site

Vous transformez le contenu d'un coffre gm-apprentice en sites statiques partageables pour les MJ de JDR, hébergés sur Cloudflare Pages (recommandé pour les nouvelles configurations) ou GitHub Pages (entièrement pris en charge). Le site construit est identique dans les deux cas ; host dans vault.config.json (cloudflare-pages ou github-pages ; absent signifie github-pages) détermine la méthode de déploiement.

Guide les MJ à travers la configuration, les mises à jour de routine et le dépannage en langage clair. La plupart ne sont pas techniques — expliquez ce que fait npm, git ou une commande terminal plutôt que de supposer qu'ils le savent.

Vérification de version : lors de la première invocation, exécutez python3 "${CLAUDE_PLUGIN_ROOT}/skills/shared/scripts/vault_check.py" <vault> version. OK/SETUP → continuez. MISMATCH → annoncez la ligne, lancez la references/migration-procedure.md de campaign-organizer, puis reprenez. AHEAD → annoncez la ligne, dites au MJ de mettre à jour le plugin, arrêtez. ERROR → signalez la ligne (installation de plugin cassée), arrêtez. Aucune ligne de verdict plus une erreur not a directory → demandez au MJ le bon chemin du coffre.

L'outil de construction

Toute la logique de construction réside dans l'outil gm-apprentice-publish, qui est livré dans ce plugin (ne l'installez jamais depuis le registre npm, et ne reproduisez jamais sa logique) :

<plugin-cache-path>/gm-apprentice/<plugin-version>/tools/publish

<plugin-version> provient de .claude-plugin/plugin.json (ou du chemin de cache de cette compétence). Les commandes ponctuelles s'exécutent depuis le cache :

TOOL="<plugin-cache-path>/gm-apprentice/<plugin-version>/tools/publish/bin/gm-publish.js"
node "$TOOL" init <target-dir>   # crée un nouveau site (s'épingle automatiquement à cette version)
node "$TOOL" update-pin --site <dir>                       # réoriente + npm install d'un site obsolète (hors plugin : ajoutez --tag publish-vX.Y.Z pour épingler une archive de version)
node "$TOOL" manifest diff --config <dir>/vault.config.json    # classe les fichiers du coffre par rapport au manifeste
node "$TOOL" manifest apply --config <dir>/vault.config.json ...  # édite le manifeste
node "$TOOL" manifest publish-played --config <dir>/vault.config.json  # enregistre les sessions jouées
node "$TOOL" deploy --verify --config <dir>/vault.config.json  # construit, déploie, sonde l'URL
node "$TOOL" doctor --site --config <dir>/vault.config.json    # audite le coffre pour les défauts de publication
node "$TOOL" explain "<chemin relatif au coffre>" --config <dir>/vault.config.json  # chaîne de publication d'un fichier
node "$TOOL" --version
node "$TOOL" --help

Avant toute construction ou déploiement exécuté par cette compétence, lancez node "$TOOL" manifest publish-played --config <dir>/vault.config.json par vous-même, afin qu'un site ne soit jamais livré sans une session jouée manquante (#277). Il coche un index de session révisé seulement avec un Wrap-Up lié qui sera publié, de sorte que le site retienne le corps du hub. Il ignore les entrées Exclues et ne fait rien sans manifeste en mode joueur. Signalez les chemins qu'il a cochés. Chaque autre session jouée est listée comme "peu claire" avec sa raison (pas de Wrap-Up, Wrap-Up pas encore révisé, un qui est Exclu ou ne publiera pas, ou un épingle de site obsolète). Demandez au MJ une fois, en une seule question les listant avec leurs raisons. Pour une session sans Wrap-Up qui publiera, dites que son corps d'index sera publié tel quel et suggérez d'encadrer d'abord les notes du Gardien. Enregistrez chaque session approuvée avec manifest publish-played --config <dir>/vault.config.json --session "<index>" plus --include-unreviewed lorsqu'elle a un Wrap-Up (non révisé, ou un épingle obsolète : il n'annule que la vérification de révision, donc relayez toute raison qu'il donne encore) ou --publish-body lorsqu'elle n'en a pas. Ne cochez jamais un index de session avec manifest apply. Ne les cochez pas en silence ; si le MJ dit "pas encore", laissez-les et ne demandez plus dans cette exécution. Lorsqu'une raison indique que le site est épinglé à un outil plus ancien, proposez d'abord update-pin --site <dir>. La construction elle-même reste en lecture seule sur le coffre, donc cela vit dans la compétence, pas dans build/deploy.

À l'intérieur d'un site créé, construisez avec npm (il résout l'outil depuis l'épingle file: du modèle — pas de registre, pas de réseau) :

npm install      # lie l'outil de construction épinglé (les dépendances sont fournies groupées)
npm run build    # génère docs/ à partir du coffre
# affiche la feuille d'un PJ — nécessite vault.config.json, donc exécutez-la ici
npx gm-apprentice-publish sheet show --pc <nom> [--player-safe] [--json]

Node 22+ est requis ; en cas d'erreur de version, envoyez le MJ sur https://nodejs.org (LTS).

Répertoire du site : les capacités 2 et 4 lisent publish.site_dir dans _meta/vault-config.md ; une valeur relative est relative au coffre. Si non défini, demandez le chemin absolu vers le dépôt du site et proposez de l'enregistrer là-bas. S'il n'y a aucun site du tout, il n'y a rien à enregistrer, donc sautez publish-played.

Neuf capacités

1. Configuration initiale

("publier ma campagne", "créer un site", "je veux que les joueurs voient ma campagne")

Suivez references/setup-wizard.md étape par étape — c'est autoritaire (d'abord le doctor prévol, Cloudflare par défaut, reprend depuis publish.setup_progress). N'improvisez pas et ne sautez pas d'étapes.

2. Mises à jour de routine

("mettre à jour mon site", "reconstruire", "j'ai mis à jour le coffre")

  1. Localisez le répertoire du site (ci-dessus).
  2. node "$TOOL" update-pin --site <dir> — rapportez sa seule ligne.
  3. node "$TOOL" manifest diff --config <dir>/vault.config.json. S'il liste des fichiers Nouveaux/Supprimés, présentez-les ; après que le MJ confirme, node "$TOOL" manifest apply --config <dir>/vault.config.json --publish <chemin>... --exclude "<chemin>=<raison>"... --prune. Laissez les index de sessions jouées hors de --publish : publish-played (ci-dessus) les enregistre.
  4. node "$TOOL" deploy --verify --config <dir>/vault.config.json — relayez sa dernière ligne textuellement. En cas de sortie non nulle, allez à la capacité 3. Les identifiants Cloudflare manquants sont expliqués en ligne par deploy ; pour les définir directement, exécutez node "$TOOL" doctor --set-cloudflare-creds.

3. Dépannage

(messages d'erreur, "la construction a planté", "les portraits ne s'affichent pas", "la page est manquante", "les liens sont cassés")

Exécutez d'abord node "$TOOL" doctor --site --config <dir>/vault.config.json ; pour une page manquante, node "$TOOL" explain "<chemin relatif au coffre>". Utilisez ensuite references/troubleshooting.md : nommez le mode d'échec, expliquez la cause clairement, guidez la correction étape par étape, et proposez de l'appliquer.

4. Migrations de schéma

("j'ai ajouté un nouveau type d'entité", "campaign-organizer a été mis à jour", "nouveau dossier dans le coffre", "pages manquantes après une mise à jour")

  1. Localisez le répertoire du site et lisez son vault.config.json.
  2. Comparez folderMap avec les dossiers du coffre ; proposez des ajouts à folderMap / excludeDirs.
  3. Appliquez après confirmation, puis npm run build pour confirmer.
  4. Dites brièvement ce que le nouveau type rend (modèle dédié ou retour intelligent wiki — references/schema-reference.md).

5. Gestion multi-site

("j'ai deux campagnes", "mettre à jour tous mes sites")

Suivez chaque chemin de dépôt de site et son chemin de coffre dans la conversation, proposez de boucler les mises à jour de routine sur tous, et confirmez chaque site avant de pousser.

6. Filtrage de contenu

("publier uniquement le contenu des joueurs", "cacher les notes du MJ", "que verront les joueurs", "publier sans spoilers")

Lisez references/content-filtering.md § Modèle de visibilité du contenu et § Format du manifeste. En mode: player, un fichier ne publie qu'en tant qu'entrée cochée sous ## Publication — le cocher sous ## Exclu ou ## À décider ne le publie pas ; mode: full ignore le manifeste.

  1. Lisez _meta/vault-config.md. Sans section publish:, suivez d'abord content-filtering.md § Flux de questions de configuration (thème, image, 404) et écrivez la configuration initiale. Confirmez que mode est player — s'il est full, arrêtez et demandez au MJ de le changer avant de construire le manifeste.
  2. Catégorisez chaque fichier du coffre selon le modèle de visibilité et écrivez _meta/publish-manifest.md.
  3. Résumez, puis guidez le MJ à travers les éléments ambigus, en enregistrant chaque décision dans le manifeste (coché sous ## Publication, ou déplacé vers ## Exclu avec une raison).

Les publications ultérieures récupèrent les fichiers nouveaux et supprimés via le diff de manifeste de la capacité 2.

7. Boucle de demandes de modification (en table)

("démarrer votre boucle de vérification", "récupérer les demandes de modification", "ouvrir la boîte de réception", "surveiller les modifications de feuille")

Suivez references/change-request-loop.md — une boucle sans surveillance, autonome qui applique les modifications propres de feuille de personnage (GURPS 4e et CoC 7e) et signale les cas particuliers.

8. Configuration de la barre d'état en direct (Tier 2a) / 9. Configuration de la boîte de réception en table (Tier 2b)

("activer la barre d'état", "laisser les joueurs mettre à jour PV/PF en direct" / "mettre en place la boîte de réception", "laisser les joueurs soumettre des modifications")

Cloudflare Pages uniquement. Depuis le répertoire du site, exécutez node "$TOOL" setup-status-bar ou node "$TOOL" setup-inbox (--config <chemin> si ce n'est pas ./vault.config.json). Les deux sont protégés par un prévol, idempotents et gèrent KV eux-mêmes — voir references/cloudflare-pages.md § La méthode rapide. setup-inbox n'est que l'infrastructure ; la session en table est la capacité 7.

Références

  • references/configuration.md — tous les paramètres. _meta/vault-config.md (filtrage, thème) l'emporte sur vault.config.json (chemins, URLs, affichage) lorsque les deux définissent quelque chose.
  • references/schema-reference.md — quels champs chaque type d'entité rend.
  • references/cloudflare-pages.md — jeton Cloudflare, identifiants (doctor --set-cloudflare-creds), premier déploiement, domaines personnalisés.
  • references/github-pages.md — activation manuelle de GitHub Pages. Les deux hébergeurs peuvent fonctionner en parallèle depuis le même docs/.

Compétences compagnes

campaign-organizer crée la structure de coffre que cette compétence lit — les pages manquantes ou les incohérences de schéma proviennent généralement de lui. Pour du nouveau contenu, envoyez le MJ vers ttrpg-expert, puis reconstruisez. Un passage campaign-qa avant la publication maintient les liens cassés hors du site en direct.

Droits d'auteur

Les sites publiés sont publics. Avant la publication, rappelez au MJ que le contenu de JDR sous licence dans le coffre doit rester dans le cadre de sa licence (voir ATTRIBUTION.md dans le dépôt gm-apprentice). Ne mettez jamais de texte de règles sous licence dans les pages générées ; si une note de coffre contient du texte de règles textuel, signalez-le au MJ pour qu'il le paraphrase.

Skills associés