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")
- Localize o diretório do site (acima).
node "$FERRAMENTA" update-pin --site <dir>— relate sua única linha.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.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 pordeploy; para defini-las diretamente, executenode "$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")
- Localize o diretório do site e leia seu
vault.config.json. - Compare
folderMapcom as pastas do cofre; proponha adiçõesfolderMap/excludeDirs. - Aplique após confirmação, então
npm run buildpara confirmar. - 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.
- Leia
_meta/vault-config.md. Sem uma seçãopublish:, primeiro siga o Fluxo de Perguntas de Configuração de content-filtering.md (tema, imagem, 404) e escreva a configuração inicial. Confirme quemodeéplayer— se forfull, pare e peça ao GM para alterá-lo antes de construir o manifesto. - Categorize cada arquivo do cofre de acordo com o modelo de visibilidade e escreva
_meta/publish-manifest.md. - Resuma, então guie o GM através dos itens ambíguos, registrando
cada decisão no manifesto (marcado em
## Publishing, ou movido para## Excludedcom 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 sobrevault.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 mesmodocs/.
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.