Arquitetura e Fluxos — Hermes, Foundry e Ecossistema RPG

Regra de governança inviolável

Endpoints Tailscale, diretórios Syncthing, caminhos absolutos/relativos, método de acesso e política de escrita descritos aqui são restrições operacionais. Hermes não pode alterar, contornar ou substituir qualquer um deles sem: (1) apresentar o motivo técnico; (2) delimitar impacto e rollback; e (3) obter aprovação explícita e prévia de Yan.

Segredos

Este documento registra nomes de variáveis e arquivos de credenciais, mas não contém senhas, API keys, tokens, salts nem IDs privados completos de dispositivos. Credenciais continuam nos arquivos apropriados (.env, ~/.foundry-api.sh, configuração do Syncthing).

0. Escopo, método e estado da auditoria

Auditoria executada em 2026-07-30 18:22 BRT/ESAST (UTC-3), combinando:

1. testes HTTP/Tailscale e MCP sem escrita;
2. inspeção do estado vivo da b450m e da VM Oracle;
3. leitura de options.json, manifests de worlds/systems/modules e configurações Syncthing;
4. consulta da documentação oficial viva de foundryrestapi.com/docs;
5. leitura do código local de foundryvtt-mcp e 5e-statblock-importer;
6. revisão de sessões históricas, erros, correções e validações feitas por Yan;
7. consolidação das skills locais de Foundry, Obsidian, D&D 5e, WoD5e e TOR2e.

Estado observado, em uma linha

• b450m Foundry: offline em 100.72.191.109:30000 e 127.0.0.1:30000 no momento da auditoria.
• VM Foundry: online em 100.108.186.76:30000, Foundry 13.351, world vivo pathfinder2e-kingmaker, sistema PF2e 7.12.2.
• Foundry REST relay: chave válida, seis clients cadastrados, todos isOnline: false; portanto CRUD/execute-js não pôde ser validado end-to-end sem abrir uma sessão de browser do módulo.
• MCP Windows: fvtt-b450m-to-b450m e fvtt-b450m-to-oracle iniciaram o transporte stdio, mas terminaram em Connection closed; os dois MCPs Linux falharam no Windows como esperado (/usr/bin/node inexistente).
• Syncthing: VM íntegra e em sync para Foundry; b450m com 234 arquivos pendentes/erros no folder Foundry, principalmente colisões de caixa de nomes, além de aproximadamente 2,7 mil arquivos sync-conflict históricos, incluindo 279 no escopo de LevelDB de worlds.

---

1. Diagnóstico de logs e testes de conexão

1.1 Resultados dos testes ativos

Teste	Resultado	Latência/estado	Interpretação
http://100.72.191.109:30000/api/status	falhou	~2,04 s, conexão recusada	Foundry local b450m não estava ouvindo em :30000
http://127.0.0.1:30000/api/status na b450m	falhou	~2,05 s, conexão recusada	confirma ausência de listener local
http://100.108.186.76:30000/api/status	HTTP 200	~0,043 s total	Tailscale e Foundry VM operacionais
VM → 127.0.0.1:30000/api/status	HTTP 200	~0,0034 s	processo Foundry local à VM saudável
SSH alias foundry	sucesso	batch auth	acesso administrativo à VM operacional
PM2 VM	foundry:online	processo ativo	não foi reiniciado nem interrompido
Syncthing VM	ativo	processo PID presente	sincronização em execução
REST relay /clients	HTTP/autenticação válidos	6 clients, todos offline	relay acessível, mas nenhum world conectado por browser
MCP b450m→b450m	falhou	Connection closed em ~9,9 s	esperado enquanto Foundry local está offline
MCP b450m→Oracle	falhou	Connection closed em ~8,6 s	HTTP chega à VM, mas handshake/auth MCP não concluiu; provável incompatibilidade de usuário/world ativo ou erro no fluxo Socket.IO

Próxima verificação segura para o MCP Oracle

Antes de qualquer write:

1. confirmar que o usuário hermes-mcp existe no world atualmente ativo (pathfinder2e-kingmaker);
2. testar o fluxo de autenticação Socket.IO de quatro etapas contra o world vivo;
3. capturar stderr/debug do MCP sem imprimir senha;
4. executar hermes mcp test fvtt-b450m-to-oracle novamente;
5. só após Connected + descoberta de tools, executar uma leitura (get_world_summary);
6. não usar FOUNDRY_WRITE_ENABLED=true como permissão implícita para mutar dados.

1.2 O que funcionou historicamente

Foundry REST API

• GET /clients com x-api-key carregado de ~/.foundry-api.sh.
• PUT /update quando clientId e uuid são passados em query parameters.
• POST /execute-js usando payload JSON gerado em arquivo/pipe, evitando escaping frágil.
• criação de páginas via JournalEntry.createEmbeddedDocuments("JournalEntryPage", ...) e atualização posterior do conteúdo.
• HTML renderizado com text.format: 1 no Foundry v13.
• operações complexas via execute-js, seguidas de releitura por /get, /structure ou JavaScript vivo.
• assets em WebP copiados para a raiz correta e referenciados por caminho relativo images/....

MCP/Socket.IO e D&D 5e

• parser local import_dnd5e_statblock registrado e compilado no MCP;
• criação de Actor por modifyDocument('Actor', 'create') com persistência confirmada por conexão Socket.IO fresca;
• correção de cache adicionando o Actor recém-criado a worldData.actors;
• create_actor_item como rota validada para items que exigem Active Effects;
• IDs de activities/Active Effects com exatos 16 caracteres alfanuméricos;
• vinculação activity.effects[]._id === item.effects[]._id;
• saves com dc.calculation ligado ao atributo ou spellcasting, em vez de fórmula fixa quando o DC deriva do Actor;
• recharge 5–6 representado por formula: "5", period: "recharge", type: "recoverAll";
• verificação por Socket.IO fresco/UI em vez de confiar no cache MCP.

5e Statblock Importer

Módulo instalado: 5e-statblock-importer 2.3.15.

API confirmada no README e código do módulo:

const api = game.modules.get("5e-statblock-importer").api;
const parsed = api.parse(statblockText);
const { actor5e, importIssues } = await parsed.actor.createActor5e(folderId);
// ou
const { actor5e, importIssues } = await api.import(statblockText, folderId);

O parser exige layout WotC padrão. O resultado de parse() contém actor, statBlocks, lines e unknownLines. Spells na Spellbook dependem do compendium de spells instalado. A execução dentro do client Foundry preserva hooks e validação do sistema melhor do que criar payloads parciais externamente.

1.3 Falhas históricas, causas e correções

Falha	Causa comprovada/provável	Solução operacional validada
Agent preso navegando UI sem criar ficha	escolha do caminho indireto	parser → schema → criação direta → releitura → UI apenas para QA
Actor criado, mas MCP não encontra	cache worldData stale	sincronizar cache no createActor ou verificar via Socket.IO fresco
refreshWorldData() timeout	world aguardando atualização de packs/cache	não usar como única verificação; abrir nova conexão
t is not a function após create	consequência do fluxo do world, não prova de não persistência	conferir LevelDB/Socket.IO vivo antes de diagnosticar perda
Items sem features/actions	activity IDs curtos/inválidos e schemas incompletos	IDs de 16 chars e template completo de activity
Effects existentes, mas não aplicados	referência da activity aponta para ID antigo	reconciliar IDs após clone/create
Active Effects ignorados em items embedded	rota Socket.IO de create não materializou effects	recriar item via create_actor_item com source.type: "inline"
Spell criada manualmente incorreta	school/range/duration/properties/target incompletos	copiar do compendium e usar spellcasting
Journal criado vazio	conteúdo enviado ao campo flat content ou não relido	JournalEntryPage + format: 1; verificar página e conteúdo
Campaign Codex vazio	texto colocado em pages, mas sheet lê flags	usar flags.campaign-codex.data.description/notes
REST Invalid client ID	relay/browser desconectado ou flutuação	esperar client online, retry curto, nunca reiniciar Foundry como “fix”
REST Entity not found no update	uuid/clientId no body	mover ambos para query string
folder ignorado no create	limitação/quirk do endpoint	criar e mover via execute-js, depois verificar pasta
LevelDB inconsistente	o mesmo world aberto nos dois hosts ou sync incompleto de runtime	sincronização total por pasta de world; nunca abrir o mesmo world simultaneamente nas duas pontas; ignorar só travas/temporários cirúrgicos
caminhos VM escritos no Windows	options.json sincronizado entre SOs	CLI --dataPath correto por host; não confiar no arquivo sincronizado

---

2. Matriz de infraestrutura e rede

2.1 b450m versus VM

Camada	b450m (Windows 10)	VM Oracle (Ubuntu)
Host Hermes	perfil default em C:\Users\Yanbd\AppData\Local\hermes	réplica em ~/.hermes via Syncthing
Foundry app	C:\Users\Yanbd\foundry-app\v13.351\	/home/ubuntu/foundry/
Foundry data root	C:\Users\Yanbd\foundry-data\v13\	/home/ubuntu/Data/
Conteúdo Foundry (Data)	C:\Users\Yanbd\foundry-data\v13\Data\	/home/ubuntu/Data/Data/
Imagens	...\Data\images\	/home/ubuntu/Data/Data/images/
Worlds	...\Data\worlds\	/home/ubuntu/Data/Data/worlds/
Config	...\Config\	/home/ubuntu/Data/Config/
Foundry interno	127.0.0.1:30000 quando ativo	127.0.0.1:30000
Tailscale	100.72.191.109:30000	100.108.186.76:30000
Processo	app Windows; offline na auditoria	PM2 → bash → node ... --dataPath=/home/ubuntu/Data --port=30000
Syncthing folder	foundry-data-v13 → raiz Windows	foundry-data-v13 → ~/Data
Policy de write MCP viva	.env: true	.env.vm usado pela b450m: true; requer governança manual

Divergência de policy

A documentação histórica dizia que Oracle era read-only, mas os .env vivos da b450m tinham FOUNDRY_WRITE_ENABLED=true tanto para local quanto para VM. O valor vivo é tecnicamente efetivo; a regra de governança deste documento é mais restritiva: nenhum write de produção sem intenção explícita da tarefa e verificação do world ativo.

2.2 URIs e regra de roteamento

Origem	Destino	URI correta	MCP pretendido
Hermes na b450m	Foundry b450m	http://100.72.191.109:30000	fvtt-b450m-to-b450m
Hermes na b450m	Foundry VM	http://100.108.186.76:30000	fvtt-b450m-to-oracle
Hermes na VM	Foundry VM	http://127.0.0.1:30000	fvtt-oracle-to-oracle
Hermes na VM	Foundry b450m	http://100.72.191.109:30000	fvtt-oracle-to-b450m
Automação REST em qualquer host	relay	https://foundryrestapi.com	HTTP + clientId do world

Regras:

1. nomenclatura MCP é origem-to-destino;
2. MCP Windows usa Node/path Windows; MCP Linux usa /usr/bin/node;
3. não trocar Tailscale por hostname público, tunnel, localhost remoto ou relay REST sem aprovação;
4. sempre chamar /api/status antes de assumir world/sistema ativo;
5. DOTENV_CONFIG_PATH deve estar em env:, nunca em args:;
6. não registrar segredos no YAML compartilhado se houver arquivo .env local apropriado.

2.3 Estado vivo dos worlds

• VM viva: pathfinder2e-kingmaker — título Pathfinder2e Season of Ghosts, PF2e 7.12.2.
• b450m Config/options.json: raiders-of-the-serpent-sea, mas o serviço local estava offline.
• VM Config/options.json sincronizado também contém path Windows e raiders-of-the-serpent-sea, mas o PM2 força --dataPath=/home/ubuntu/Data; o world vivo era outro.

Não confiar em options.json sincronizado

O estado vivo de /api/status e os argumentos do processo têm precedência. Nunca escrever em um world com base apenas no options.json.

---

3. Syncthing, conflitos e matriz de paths

3.1 Folders sincronizados

Folder ID	b450m	VM	Tipo
foundry-data-v13	C:\Users\Yanbd\foundry-data\v13	~/Data	send-receive
hermes-agent-yan	C:\Users\Yanbd\AppData\Local\hermes	~/.hermes	send-receive
obs-sync-yan	C:\Users\Yanbd\dev\Wiki-Yan	~/Wiki-Yan	send-receive
guias-dnd-5e	não confirmado nesta b450m config	~/DnD5e-Drive/Guias	send-receive na VM
obs-raquel	não faz parte do vault Yan	~/obsidian-syncthing-raquel	fora do escopo

3.2 Auditoria de integridade Syncthing

Arquitetura multi-world — regra de ouro

• worlds, systems e modules são sincronizados integralmente para redundância e trabalho paralelo.
• Cada campanha tem banco isolado em Data/worlds/<world-id>/.
• Mundos diferentes podem ficar abertos/ser editados em paralelo na b450m e na VM.
• O mesmo world nunca pode ficar aberto simultaneamente nos dois hosts. Antes de trocar um world de host, aguardar o Syncthing concluir e verificar needFiles=0/errors=0 para aquele conteúdo.
• .ldb, .log, CURRENT e MANIFEST-* ativos são dados reais e permanecem sincronizados.
• O .stignore cirúrgico, idêntico nos dois hosts, ignora apenas LOCK/lock, LOG.old, MANIFEST-*.tmp, .DS_Store e Thumbs.db.

Reparo autorizado de 2026-07-31

• Backup integral pré-limpeza: C:\Users\Yanbd\foundry-backups\worlds-pre-syncthing-cleanup-20260731-103117.tar.gz (609.816.958 bytes; SHA-256 71d9a7f19a15375aaabc483754bcaf313304b055c7797ebc7794d9664c995a8d; gzip PASS; 6.499 entradas).
• 2.738 arquivos *.sync-conflict-* removidos na b450m, sendo 282 sob Data/worlds/*/data/*.
• Pós-check: zero conflitos restantes; arquivos normais preservados 183.723 → 183.723; .ldb normais preservados 5.236 → 5.236.
• Manifesto da exclusão: C:\Users\Yanbd\foundry-backups\removed-sync-conflicts-20260731-104454.tsv.
• VM após rescan: idle, 150438/150438, needFiles=0, errors=0.
• b450m após rescan: idle, 150204/150438, 234 pull errors/pendências residuais de case collision em assets; não são novos .sync-conflict e exigem tratamento separado por renomeação coordenada.

3.3 Regra para novas imagens

1. Produzir/stagear em C:\Users\Yanbd\Downloads\<lote>\ para aprovação quando for arte gerada por IA.
2. Após aprovação, escolher um único writer canônico por lote.
3. Para conteúdo que será usado na VM, publicar em /home/ubuntu/Data/Data/images/<campanha>/<categoria>/ e aguardar Syncthing.
4. Para conteúdo exclusivamente local/offline, publicar em C:\Users\Yanbd\foundry-data\v13\Data\images\... somente se a b450m for o writer deliberado.
5. Nunca editar o mesmo filename nos dois hosts durante a mesma janela.
6. Sempre versionar: arquivo-v1.webp, arquivo-v2.webp; nunca sobrescrever.
7. Confirmar no destino: arquivo existe, decodifica, tamanho/alpha corretos e URL relativa responde.
8. Só então atualizar img, prototypeToken.texture.src ou HTML do journal.

3.4 Matriz de equivalência de caminhos

Foundry relativo	b450m absoluto	VM absoluto
images/<campanha>/<categoria>/arquivo-vN.webp	C:\Users\Yanbd\foundry-data\v13\Data\images\<campanha>\<categoria>\arquivo-vN.webp	/home/ubuntu/Data/Data/images/<campanha>/<categoria>/arquivo-vN.webp
images/rotss/creatures/<Nome>-vN.webp	...\Data\images\rotss\creatures\<Nome>-vN.webp	/home/ubuntu/Data/Data/images/rotss/creatures/<Nome>-vN.webp
images/rotss/unnoficial/tokens/td_<Nome>-vN.webp	...\Data\images\rotss\unnoficial\tokens\td_<Nome>-vN.webp	/home/ubuntu/Data/Data/images/rotss/unnoficial/tokens/td_<Nome>-vN.webp
images/rome-modern/characters/<Nome>-vN.webp	...\Data\images\rome-modern\characters\<Nome>-vN.webp	/home/ubuntu/Data/Data/images/rome-modern/characters/<Nome>-vN.webp
images/rome-modern/sessions/<Cena>-vN.webp	...\Data\images\rome-modern\sessions\<Cena>-vN.webp	/home/ubuntu/Data/Data/images/rome-modern/sessions/<Cena>-vN.webp
images/over-hill-under-hill/tokens/<Nome>-vN.webp	...\Data\images\over-hill-under-hill\tokens\<Nome>-vN.webp	/home/ubuntu/Data/Data/images/over-hill-under-hill/tokens/<Nome>-vN.webp
worlds/<world>/data/actors/*	...\Data\worlds\<world>\data\actors\*	/home/ubuntu/Data/Data/worlds/<world>/data/actors/*

Caminhos Foundry sempre usam /, sem / inicial e sem prefixo Data/.

---

4. Ecossistema MCP multi-sistema

4.1 Princípio central

O endereço base conecta ao Foundry ativo, não a um sistema fixo. O MCP carrega worldData do world vivo. A seleção de schema é determinada por world.system, manifests locais e payloads do sistema. Não há roteamento mágico “por nome de campanha”.

Fluxo obrigatório:

/api/status → confirmar world + system + version
→ escolher schema/tool compatível
→ leitura/parse
→ payload versionado/reversível
→ write somente se autorizado
→ releitura pelo Foundry vivo
→ verificação visual quando player-facing

4.2 Campanhas e sistemas

Campanha solicitada	World observado	Sistema	Estratégia
Raiders of the Serpent Sea	raiders-of-the-serpent-sea	dnd5e	parser 5e/MCP + schema dnd5e 5.2.5; biografias e assets RotSS
Heróis de Thylea / Odyssey	heroes-of-thylea, heroes-of-thylea-friday, herois-de-tylea-sunday	dnd5e	fonte: MD/PDF da campanha; compendium/5e.tools só para criatura genérica
Descendo ao Avernus	descendo-ao-avernus; continuação chains-of-asmodeus	dnd5e	dnd5e 5.2.5; Campaign Codex/journals conforme world
Rusthenge / Season of Ghosts	pathfinder2e-kingmaker (título vivo: Season of Ghosts)	pf2e	usar compendia PF2e e schemas do sistema; não usar importer dnd5e
Roma Aeterna	rome-chronicle-vampire	wod5e	actors completos wod5e, Campaign Codex, powers/clan/items
Sombras de Merritt	sombras-de-merritt	dnd5e no manifest auditado	pode usar adereços narrativos de VTM, mas MCP/API devem usar exclusivamente schema dnd5e
Over Hill and Under Hill	over-hill-and-under-hill	tor2e	journals/source-first, scenes sem grade para mapas de referência, tokens/portraits separados

IDs vencem nomes e estética

Não existe world separado chamado rusthenge no inventário auditado; pathfinder2e-kingmaker tem título “Season of Ghosts” e usa PF2e 7.12.2. sombras-de-merritt usa manifest dnd5e mesmo quando incorpora adereços narrativos de VTM. Sempre resolver schema por world ID + /api/status, nunca por título ou estética.

4.3 Guia por sistema

D&D 5e 5.2.5

• Preferir 5e-statblock-importer no client quando hooks/compendia são essenciais, ou import_dnd5e_statblock MCP para fluxo direto validado.
• Statblock WotC limpo, sem headings Markdown.
• Activities/Effects usam IDs de 16 chars.
• Passivas não recebem activity artificial.
• Saves usam atributo calculado; spells usam spellcasting.
• Items com Active Effects: create_actor_item + reconciliação de IDs.
• Não usar condições inventadas em D&D 2024; effects custom descrevem mechanics.
• Sempre criar versões Nome (vN) e nunca apagar versão anterior sem aprovação.

Pathfinder 2e 7.12.2

• Usar compendia e APIs PF2e do world vivo; PF2e já modela strikes, actions, rules elements e effects de forma própria.
• Não converter schema dnd5e para PF2e.
• Para NPC/creature, estudar um Actor equivalente do compendium e clonar/ajustar Rule Elements.
• Módulos instalados relevantes: Rusthenge, Season of Ghosts, PF2e Assistant, Automations, Workbench, NPC Architect, Token Packs.
• Validar level, traits, perception, saves, skills, strikes, spellcasting entries e Rule Elements.

World of Darkness 5e 5.3.15

• Actor types: vampire, mortal, ghoul, hunter, werewolf, spc, group.
• NPC vampiro completo: 9 attributes, 27 skills, disciplines, powers como items, clan, predator type, headers, bio, touchstones originais, backgrounds/merits/flaws, gear e token.
• discipline não é item; poderes são power items.
• armorvalue e weaponvalue são lowercase.
• Roma Aeterna: conteúdo narrativo e técnico em inglês; assets em images/rome-modern/.
• Campaign Codex usa flags e secrets em <section class="secret">.

The One Ring 2e 5.5.2

• Fonte primeiro: PDF/transcrição/handouts/mapas oficiais.
• Não aceitar defaults de Actor como fatos (idade e bio de character podem ser placeholders).
• Mapas numerados são referência/exploração, não battlemaps D&D.
• Scenes de mapa: padding: 0, grid desabilitado quando apropriado.
• Combate é abstrato por stances, engagement e ranges.
• Portrait e token separados; token estritamente top-down, facing south, alpha real.

---

5. MCP local: funções, parâmetros e limites

Fonte: C:\Users\Yanbd\dev\foundryvtt-mcp\src\tools\definitions.ts.

5.1 Tools declaradas na build auditada

Grupo	Tools	Parâmetros/limites principais
Dice	roll_dice	formula obrigatório; reason opcional
Actors	search_actors, get_actor_details, import_dnd5e_statblock	search default 10; importer: statblock, folderId, img, tokenImg, dryRun
Actor writes	update_actor_attributes, delete_actor	actorId; patch dot-path; write-enabled + Socket.IO
Items	search_items	filtros query, type, rarity, default 10
Compendium	search_compendium	query obrigatório; filters; default 20; cursor; comentário do código exige REST API key
Actor items	create_actor_item, update_actor_item, delete_actor_item	Actor/item IDs; inline source; JSON merge patch
Scene	get_scene_info	sceneId opcional
Combat	get_combat_state, next_turn, end_combat, set_initiative, start_combat	active combat; token IDs/scene; GM/owner
Token	move_token, apply_status_effect	coordenadas em pixels; status id; scene opcional
Chat/users	get_chat_messages, get_users	chat 1–100, default 20
Journals	search_journals, get_journal	query/default 10; journalId
World	search_world, get_world_summary, refresh_world_data	search default 5 por coleção
Generation	generate_npc, generate_loot, lookup_rule	NPC level 1–20; loot CR 0–30
Diagnostics	get_recent_logs, search_logs, get_system_health, diagnose_errors, get_health_status	logs 1–100; diagnose_errors é stub

Limites conhecidos:

• transport muda para REST quando FOUNDRY_API_KEY existe; é switch, não camada paralela;
• writes requerem FOUNDRY_WRITE_ENABLED=true e Socket.IO ativo;
• cache de world pode ficar stale;
• refresh_world_data já sofreu timeout;
• update_actor_attributes só altera actor.system, não img/prototypeToken;
• compendium source em create_actor_item ainda não é suportado sobre Socket.IO conforme descrição do código;
• a build auditada não declara create_journal ou update_journal, apesar de documentação histórica citar essas tools;
• tools MCP se vinculam ao world ativo, não a todos os worlds simultaneamente.

---

6. Foundry REST API: rotas, grupos e limites

Fonte de verdade: Foundry REST API Docs consultada durante a auditoria. Módulo instalado localmente: foundry-rest-api 3.2.3.

6.1 Autenticação e conexão

• header: x-api-key;
• world: clientId;
• module/browser precisa manter WebSocket conectado ao relay;
• scopes por endpoint, por exemplo entity:read, entity:write;
• clients offline tornam operações de world indisponíveis;
• para criação/atualização de journals, REST API é o protocolo padrão: consultar /clients e exigir o clientId alvo com isOnline: true antes de qualquer request; create_journal e update_journal não existem na build MCP auditada;
• chaves ficam em ~/.foundry-api.sh: FKR (key), FKC (client), FKB (base URL); valores não são documentados aqui.

6.2 Inventário de rotas oficiais

Auth

POST /auth/key-request; GET /auth/key-request/:code/status; POST /auth/key-request/exchange.

Canvas

GET|POST|PUT|DELETE /canvas/:documentType; GET /measure-distance; POST /move-token.

Chat

GET|POST /chat; DELETE /chat/:messageId; DELETE /chat; GET /chat/subscribe (SSE).

Clients

GET /clients.

D&D 5e

GET /dnd5e/get-actor-details; POST /dnd5e/modify-item-charges; short-rest; long-rest; skill-check; ability-save; ability-check; death-save; modify-experience; GET /dnd5e/concentration; POST /dnd5e/break-concentration; concentration-save; equip-item; attune-item; transfer-currency; modify-currency; prepare-spell; use-ability; use-feature; use-spell; use-item.

Effects

GET /effects; GET /effects/list; POST /effects; DELETE /effects.

Encounter

GET /encounters; POST /start-encounter; next-turn; next-round; last-turn; last-round; end-encounter; add-to-encounter; remove-from-encounter.

Entity

GET /get; POST /create; PUT /update; DELETE /delete; POST /give; remove; decrease; increase; kill.

Parâmetros críticos:

• /get: clientId, uuid ou selected, actor, userId;
• /create: entityType, data, clientId, folder, keepId, override, userId;
• /update: data, clientId, uuid ou selected, actor, userId;
• /delete: clientId, uuid ou selected, userId.

Events/SSE

GET /hooks/subscribe; /encounters/subscribe; /actor/subscribe; /scene/subscribe.

Macro

GET /macros; POST /macro/:uuid/execute.

Playlist

GET /playlists; POST /playlist/play; stop; next; volume; POST /stop-sound.

Roll

GET /rolls; GET /lastroll; POST /roll; GET /rolls/subscribe (SSE).

Scene

GET /scene; GET /scene/image/raw; POST|PUT|DELETE /scene; POST /switch-scene; GET /scene/image.

Search

GET /search.

Session

POST /session-handshake; POST /start-session; DELETE /end-session; GET /session.

Sheet

GET /sheet.

Structure

GET /structure; GET /get-folder; POST /create-folder; DELETE /delete-folder; GET /contents/:path.

User

GET /users; GET /user; POST|PUT|DELETE /user.

Utility

POST /select; GET /selected; GET /players; GET /world-info; POST /execute-js.

WebSocket/File System

A documentação oficial possui grupos próprios de WebSocket e File System. Consultar a página específica da versão viva antes de implementar upload/streaming, pois o inventário de links é mais atual do que skills locais.

6.3 Quirks e regras

• /update: uuid e clientId na query string.
• /macro/:uuid/execute: UUID completo Macro.<id>.
• create de Journal/Actor pode ignorar folder; mover via Foundry API/execute-js.
• Journal v13: conteúdo em pages, text.format: 1.
• Campaign Codex: conteúdo principal em flags, não pages.
• execute-js é poderoso e deve ser usado com scripts idempotentes e releitura.
• Python urllib já recebeu 403 no relay; curl é a rota validada.
• nenhum success: true sem releitura conta como conclusão.
• não usar /start-session ou headless session para contornar a exigência do módulo/browser sem aprovação explícita.

---

7. Manual criativo, visual e narrativo

7.1 Princípios narrativos

1. Fonte primeiro: livro/PDF/MD da campanha antes de web genérica.
2. Expansão sem apagar o cânone: separar citação/fato canônico de adaptação de mesa.
3. Preparação acionável: aproximação → âncoras sensoriais → NPC voice lines → escolhas → consequência → fallback.
4. Conteúdo player-facing versus GM-only: não misturar spoilers.
5. Mecânica na linguagem do sistema: narrativa em PT-BR para mesas PT; termos mecânicos em EN quando essa é a convenção. Roma Aeterna deve permanecer em inglês.
6. D&D 2024: apenas condições reais; efeitos custom por texto mecânico.
7. Criaturas RotSS: Player’s Reference EN → Visual Description/AI Prompt → seção PT; sem statblock na bio.
8. V5: horror pessoal, relações, ambição/desejo, fraquezas e segredos; fichas completas.
9. TOR2e: tom literário e de viagem, source-first, combate abstrato e mapas não convertidos artificialmente em grid D&D.

7.2 Padrões visuais

Marca DM Yan

• títulos: MedievalSharp;
• corpo: DM Sans;
• logo: DMYan-white;
• banners limpos, título amplo, sem sobreposição;
• alta legibilidade e contraste.

Retratos e imagens de cena

• WebP para Foundry;
• estilo por campanha, consistente dentro do lote;
• RotSS: dark Norse fantasy, luz dramática, materiais e silhuetas legíveis;
• Roma Aeterna: identidade gótica/contemporânea coerente e conteúdo em inglês;
• cenas: 16:9 quando usadas como establishing shots/handouts;
• sempre revisar pixels, não aprovar só pelo prompt.

Tokens

• câmera 90° bird’s-eye estrita;
• facing south/down;
• equipamento dentro da silhueta;
• fundo chroma #00FF00 na geração;
• remoção por chroma/segmentação;
• RGBA WebP com alpha real, extremos 0 e 255;
• sem base, frame, texto, grid, sombra ou fake checkerboard;
• stage em Downloads para aprovação antes de publicar.

7.3 Obsidian

• raiz canônica do vault: C:\Users\Yanbd\dev\Wiki-Yan\content;
• notas RPG: content\RPG\;
• documentação de sistema: content\Sistemas\Documentacao_Hermes\;
• usar frontmatter, headings semânticos, tabelas e callouts;
• wikilinks [[...]] para navegação;
• campanhas usam prefixos numéricos quando a pasta adota sequência;
• packs grandes: 00 - Index, overview, people, places, encounters, visual prompts;
• não criar monólito quando múltiplas notas melhoram uso na mesa.

Callouts recomendados:

> [!read-aloud] Narração
> 
> Texto pronto para mesa.
 
> [!warning] Regra/risco
> 
> Informação operacional importante.
 
> [!secret] GM only
> 
> Spoiler, motivação ou consequência oculta.

7.4 Foundry HTML/CSS

• HTML semântico: <h1>, <h2>, <p>, <ul>, <blockquote>, <strong>;
• evitar inline colors/backgrounds de baixo contraste;
• journals normais: JournalEntryPage, text.format: 1;
• Campaign Codex: flags.campaign-codex.data.description e notes;
• secrets: <section class="secret">...</section>;
• imagens: paths relativos images/...;
• sempre verificar page count, conteúdo não vazio, folder, ownership e renderização no dark theme.

---

8. Protocolo operacional estrito

8.1 Antes de qualquer ação Foundry

• GET /api/status e registrar world/system/version.
• Confirmar destino: b450m ou VM.
• Confirmar rota: MCP, REST ou Socket.IO.
• Confirmar intenção de leitura versus escrita.
• Conferir policy viva de write sem expor segredo.
• Conferir se há sessão ativa de jogadores.
• Nunca parar/reiniciar Foundry sem aprovação explícita.

8.2 Writes

• Criar versão vN; não sobrescrever/deletar.
• Operação idempotente ou com rollback.
• Um writer por asset/lote entre hosts.
• Nunca editar LevelDB com Foundry aberto.
• Nunca usar LevelDB direto como atalho silencioso.
• Releitura pela API/Socket.IO fresca.
• Verificação visual para fichas/assets/journals.

8.3 Syncthing

• Não alterar folder paths, types, ignore rules ou device routing sem aprovação.
• Não limpar sync-conflict automaticamente.
• Sincronizar integralmente worlds, systems e modules; não ignorar .ldb, .log, CURRENT ou MANIFEST ativos.
• Nunca abrir o mesmo world nos dois hosts; mundos diferentes podem operar em paralelo.
• Antes de migrar um world entre hosts: fechar o world de origem, aguardar Syncthing estabilizar, verificar o destino e só então abrir.
• Para correção futura: backup → janela controlada → equivalência de .stignore cirúrgico → rescan → relatório.
• Resolver colisões de caixa por renomeação versionada e coordenada entre Linux/Windows.

8.4 Proibição de contorno

Hermes não pode:

• substituir IP Tailscale por túnel/host público “porque funciona”;
• usar REST para escapar de policy MCP, ou MCP para escapar de scopes REST;
• ativar headless session para contornar client offline;
• alterar dataPath, PM2, Syncthing ou .env sem proposta e aprovação;
• parar Foundry para liberar LevelDB;
• declarar sucesso sem releitura e, quando aplicável, UI/asset verification.

---

9. Pendências e recomendações que exigem aprovação

1. Resolver os 234 erros de case collision em assets SRD por renomeação coordenada Linux/Windows; não alterar sem autorização específica.
2. Investigar MCP b450m→Oracle no world PF2e ativo: usuário/auth/handshake.
3. Corrigir divergência de options.json por host: o arquivo VM contém path Windows, embora PM2 faça override correto.
4. Mapear client IDs restantes do REST para nomes de world: requer cada world conectado ou leitura específica das settings.

Concluídos em 2026-07-31: .stignore cirúrgico nos dois hosts, backup integral, remoção validada dos 2.738 conflitos, regra multi-world e schema real de Sombras/Season of Ghosts documentados. FOUNDRY_WRITE_ENABLED=true permanece ativo em .env e .env.vm, condicionado à validação do world vivo por /api/status antes de qualquer write.

---

10. Referências técnicas

• Foundry REST API Docs
• 5e Statblock Importer
• C:\Users\Yanbd\dev\foundryvtt-mcp\src\tools\definitions.ts
• C:\Users\Yanbd\foundry-data\v13\Data\modules\5e-statblock-importer\README.md
• Skills locais: foundry-local-audit, foundry-vtt, foundry-rest-api, mcp-creature-creation, obsidian

Changelog

• 2026-07-30: auditoria inicial prática e histórica; testes de rede/MCP/REST/Syncthing; protocolo estrito consolidado.
• 2026-07-31: arquitetura corrigida para sincronização total multi-world; .stignore cirúrgico aplicado nos dois hosts; backup e limpeza de 2.738 conflitos validados; REST definido como padrão para journals com preflight isOnline: true.

---

11. Persistência e confirmação

• Obsidian: esta nota foi gravada em Sistemas/Documentacao_Hermes/Arquitetura_e_Fluxos.md dentro do vault C:\Users\Yanbd\dev\Wiki-Yan\content.
• Honcho: o peer card foi atualizado e relido com 28 fatos. Os fatos duráveis agora registram a sincronização total multi-world, a proibição de abrir o mesmo world nos dois hosts, o .stignore cirúrgico, o reparo dos 2.738 conflitos, os schemas reais de Sombras/Season of Ghosts, REST como padrão para journals e a policy de write condicionada a /api/status.
• Honcho conclusions: o endpoint específico de conclusions havia recusado a auditoria inicial; a persistência vigente foi confirmada pelo peer card, preservando os fatos anteriores e substituindo o fato obsoleto que dizia que a b450m não possuía .stignore.
• Segredos: nenhum valor de senha, API key, token ou device ID completo foi persistido na nota ou nos fatos adicionais.