Communitygithub.com

AntTheLimey/gm-apprentice

Publique um cofre de campanha do gm-apprentice como um site estático no GitHub Pages ou Cloudflare Pages e execute o loop de solicitação de alteração na mesa que permite que os jogadores solicitem edições nas fichas durante o jogo.

O que é gm-apprentice?

Esta skill transforma o conteúdo de um cofre do gm-apprentice em um site estático compartilhável para GMs de TTRPG, hospedado no Cloudflare Pages (recomendado) ou GitHub Pages. Ela gerencia todo o ciclo de vida do site: desde a configuração inicial, passando por atualizações de rotina e solução de problemas, até a execução de um loop de solicitação de alteração durante as sessões de jogo, permitindo que os jogadores solicitem edições em suas fichas de personagem. A skill utiliza internamente a ferramenta `gm-apprentice-publish` e se integra perfeitamente ao ecossistema do gm-apprentice, incluindo o plugin campaign-organizer e o skill campaign-qa. Ela é ideal para mestres que desejam compartilhar informações da campanha com seus jogadores de forma controlada e interativa.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Publicar Site

Você transforma o conteúdo do cofre do gm-apprentice em sites estáticos compartilháveis para GMs de TTRPG, hospedados no Cloudflare Pages (recomendado para novas configurações) ou GitHub Pages (totalmente suportado). O site criado é idêntico em ambos os casos; host em vault.config.json (cloudflare-pages ou github-pages; ausente significa github-pages) decide como ele faz o deploy.

Oriente os GMs durante a configuração, atualizações de rotina e solução de problemas em linguagem simples. A maioria não é técnica — explique o que npm, git ou um comando de terminal faz, em vez de presumir que eles sabem.

Verificação de versão: na primeira invocação execute python3 "${CLAUDE_PLUGIN_ROOT}/skills/shared/scripts/vault_check.py" <cofre> version. OK/SETUP → prossiga. MISMATCH → anuncie a linha, execute o references/migration-procedure.md do campaign-organizer e depois retome. AHEAD → anuncie a linha, diga ao GM para atualizar o plugin, pare. ERROR → relate a linha (instalação do plugin quebrada), pare. Nenhuma linha de veredito mais um erro not a directory → pergunte ao GM pelo caminho correto do cofre.

A ferramenta de build

Toda a lógica de build está na ferramenta gm-apprentice-publish, que é enviada dentro deste plugin (nunca a instale a partir do registro npm, e nunca replique sua lógica):

<caminho-cache-plugin>/gm-apprentice/<versao-plugin>/tools/publish

<versao-plugin> vem de .claude-plugin/plugin.json (ou do próprio caminho de cache desta skill). Comandos avulsos são executados a partir do cache:

FERRAMENTA="<caminho-cache-plugin>/gm-apprentice/<versao-plugin>/tools/publish/bin/gm-publish.js"
node "$FERRAMENTA" init <dir-destino>   # criar um novo site (se fixa automaticamente nesta versão)
node "$FERRAMENTA" update-pin --site <dir>                       # redirecionar + npm install em um site desatualizado (fora do plugin: adicione --tag publish-vX.Y.Z para fixar um tarball de release)
node "$FERRAMENTA" manifest diff --config <dir>/vault.config.json    # classificar arquivos do cofre vs o manifesto
node "$FERRAMENTA" manifest apply --config <dir>/vault.config.json ...  # editar o manifesto
node "$FERRAMENTA" manifest publish-played --config <dir>/vault.config.json  # registrar sessões jogadas
node "$FERRAMENTA" deploy --verify --config <dir>/vault.config.json  # build, deploy, sondar a URL
node "$FERRAMENTA" doctor --site --config <dir>/vault.config.json    # auditar o cofre em busca de defeitos de publicação
node "$FERRAMENTA" explain "<caminho relativo ao cofre>" --config <dir>/vault.config.json  # cadeia de publicação de um arquivo
node "$FERRAMENTA" --version
node "$FERRAMENTA" --help

Antes de qualquer build ou deploy executado por esta skill, execute node "$FERRAMENTA" manifest publish-played --config <dir>/vault.config.json você mesmo, para que um site nunca seja enviado sem uma sessão jogada (#277). Ele marca um índice de sessão revisado apenas junto com um Wrap-Up vinculado que será publicado, então o site retém o corpo do hub. Ele pula entradas Excluídas e não faz nada sem um manifesto no modo jogador. Relate os caminhos que marcou. Cada outra sessão jogada é listada como "incerta" com seu motivo (nenhum Wrap-Up, Wrap-Up ainda não revisado, uma que é Excluída ou não será publicada, ou um pin de site desatualizado). Pergunte ao GM uma vez, em uma pergunta listando-as com seus motivos. Para uma sem Wrap-Up que será publicado, diga que o corpo do seu índice será publicado como está e sugira colocar quaisquer notas do Guardião entre cercas primeiro. Registre cada uma aprovada com manifest publish-played --config <dir>/vault.config.json --session "<indice>" mais --include-unreviewed quando tiver um Wrap-Up (não revisado, ou um pin desatualizado: ele dispensa apenas a verificação de revisão, então retransmita qualquer motivo que ainda der) ou --publish-body quando não tiver nenhum. Nunca marque um índice de sessão com manifest apply. Não os marque silenciosamente; se o GM disser "ainda não", deixe-os e não pergunte novamente nesta execução. Quando um motivo disser que o site está fixado em uma ferramenta mais antiga, ofereça update-pin --site <dir> primeiro. O build em si permanece somente leitura no cofre, então isso vive na skill, não em build/deploy.

Dentro de um site criado, faça o build com npm (ele resolve a ferramenta a partir do pin file: da estrutura criada — sem registro, sem rede):

npm install      # vincula a ferramenta de build fixada (as dependências são enviadas vendidas)
npm run build    # gerar docs/ a partir do cofre
# imprimir a ficha de um PJ — precisa de vault.config.json, então execute aqui
npx gm-apprentice-publish sheet show --pc <nome> [--player-safe] [--json]

Node 22+ é necessário; em um erro de versão, envie o GM para https://nodejs.org (LTS).

Diretório do site: as capacidades 2 e 4 leem publish.site_dir de _meta/vault-config.md; um valor relativo é relativo ao cofre. Se não estiver definido, peça o caminho absoluto para o repositório do site e ofereça para salvá-lo lá. Sem nenhum site, não há nada para registrar, então pule publish-played.

Nove Capacidades

1. Configuração inicial

("publicar minha campanha", "configurar um site", "quero que os jogadores vejam minha campanha")

Siga references/setup-wizard.md passo a passo — é autoritário (doctor de pré-voo primeiro, Cloudflare padrão, retoma de publish.setup_progress). Não improvise nem pule etapas.

2. Atualizações de rotina

("atualizar meu site", "reconstruir", "atualizei o cofre")

  1. Localize o diretório do site (acima).
  2. node "$FERRAMENTA" update-pin --site <dir> — relate sua única linha.
  3. node "$FERRAMENTA" manifest diff --config <dir>/vault.config.json. Se listar arquivos Novos/Removidos, apresente-os; após a confirmação do GM, node "$FERRAMENTA" manifest apply --config <dir>/vault.config.json --publish <caminho>... --exclude "<caminho>=<motivo>"... --prune. Deixe os índices de sessão jogados de fora de --publish: publish-played (acima) os registra.
  4. node "$FERRAMENTA" deploy --verify --config <dir>/vault.config.json — retransmita sua linha final literalmente. Em uma saída diferente de zero, vá para a capacidade 3. Credenciais ausentes do Cloudflare são explicadas inline por deploy; para defini-las diretamente, execute node "$FERRAMENTA" doctor --set-cloudflare-creds.

3. Solução de problemas

(mensagens de erro, "build quebrou", "retratos não aparecendo", "página está faltando", "links estão quebrados")

Execute node "$FERRAMENTA" doctor --site --config <dir>/vault.config.json primeiro; para uma página faltando, node "$FERRAMENTA" explain "<caminho relativo ao cofre>". Em seguida, use references/troubleshooting.md: nomeie o modo de falha, explique a causa claramente, guie a correção passo a passo e offereça-se para aplicá-la.

4. Migrações de esquema

("adicionei um novo tipo de entidade", "campaign-organizer foi atualizado", "nova pasta no cofre", "páginas faltando após uma atualização")

  1. Localize o diretório do site e leia seu vault.config.json.
  2. Compare folderMap com as pastas do cofre; proponha adições folderMap / excludeDirs.
  3. Aplique após confirmação, então npm run build para confirmar.
  4. Diga brevemente como o novo tipo é renderizado (template dedicado ou fallback smart wiki — references/schema-reference.md).

5. Gerenciamento de múltiplos sites

("tenho duas campanhas", "atualizar todos os meus sites")

Rastreie cada caminho do repositório do site e seu caminho do cofre na conversa, ofereça-se para executar atualizações de rotina em todos eles e confirme cada site antes de enviar.

6. Filtragem de conteúdo

("publicar apenas conteúdo do jogador", "ocultar notas do GM", "o que os jogadores verão", "publicar sem spoilers")

Leia references/content-filtering.md § Modelo de Visibilidade de Conteúdo e § Formato do Manifesto. Em mode: player, um arquivo é publicado apenas como uma entrada marcada em ## Publishing — marcá-la em ## Excluded ou ## Needs Decision não a publica; mode: full ignora o manifesto.

  1. Leia _meta/vault-config.md. Sem uma seção publish:, primeiro siga o Fluxo de Perguntas de Configuração de content-filtering.md (tema, imagem, 404) e escreva a configuração inicial. Confirme que mode é player — se for full, pare e peça ao GM para alterá-lo antes de construir o manifesto.
  2. Categorize cada arquivo do cofre de acordo com o modelo de visibilidade e escreva _meta/publish-manifest.md.
  3. Resuma, então guie o GM através dos itens ambíguos, registrando cada decisão no manifesto (marcado em ## Publishing, ou movido para ## Excluded com um motivo).

Publicações posteriores captam arquivos novos e removidos através da capacidade 2, diff do manifesto.

7. Loop de solicitação de alteração (na mesa)

("iniciar seu loop de verificação", "pegar as solicitações de alteração", "abrir a caixa de entrada", "observar alterações na ficha")

Siga references/change-request-loop.md — um loop autônomo e auto-gerenciado que aplica edições limpas nas fichas dos jogadores (GURPS 4e e CoC 7e) e sinaliza casos extremos.

8. Configuração da barra de status ao vivo (Tier 2a) / 9. Configuração da caixa de entrada na mesa (Tier 2b)

("ativar a barra de status", "deixar os jogadores atualizarem PV/PE ao vivo" / "configurar a caixa de entrada", "deixar os jogadores enviarem alterações")

Apenas Cloudflare Pages. A partir do diretório do site execute node "$FERRAMENTA" setup-status-bar ou node "$FERRAMENTA" setup-inbox (--config <caminho> se não for ./vault.config.json). Ambos têm pré-verificação, são idempotentes e lidam com o KV eles mesmos — veja references/cloudflare-pages.md § O caminho rápido. setup-inbox é apenas infraestrutura; a sessão na mesa é a capacidade 7.

Referências

  • references/configuration.md — todas as configurações. _meta/vault-config.md (filtragem, tema) prevalece sobre vault.config.json (caminhos, URLs, exibição) quando ambos definem algo.
  • references/schema-reference.md — quais campos cada tipo de entidade renderiza.
  • references/cloudflare-pages.md — token Cloudflare, credenciais (doctor --set-cloudflare-creds), primeiro deploy, domínios personalizados.
  • references/github-pages.md — habilitação manual de GitHub Pages. Ambos os hosts podem ser executados em paralelo a partir do mesmo docs/.

Skills Companheiras

campaign-organizer cria a estrutura do cofre que esta skill lê — páginas faltando ou incompatibilidades de esquema geralmente são causadas por ele. Para novo conteúdo, envie o GM para ttrpg-expert, depois reconstrua. Uma passagem de campaign-qa antes de publicar mantém links quebrados fora do site ao vivo.

Direitos Autorais

Sites publicados são públicos. Antes de publicar, lembre o GM de que o conteúdo licenciado de TTRPG no cofre deve permanecer dentro de sua licença (veja ATTRIBUTION.md no repositório gm-apprentice). Nunca coloque texto de regras licenciado em páginas geradas; se uma nota do cofre contiver texto de regras literal, sinalize-a para o GM parafrasear.

Habilidades Relacionadas