Convenções swarm

Origem dessa nota: incidente 2026-05-31. Repo /home/swarm/ não existia (zero .git), 12+ scripts úteis vagando em /tmp/ (some no reboot), arquivos transit no Windows C:\Users\User\hermes\.tmp_*.py. User flagou — corrigido com git init + estrutura organizada + sanitização secrets.

Layout do repo /home/swarm/

/home/swarm/  (git main)
├── .secrets.env          ← gitignored, único lugar com credenciais (root 600)
├── .gitignore            ← cobre secrets, sessions, kits gerados, node_modules
├── DEPLOY.md             ← bootstrap guide
├── README.md
├── config/               ← mirror sanitized de coisas que vivem em /root/.openclaw
│   ├── agents/<nome>/AGENTS.md
│   ├── openclaw.template.json  (${ENV} placeholders)
│   ├── systemd/<*.service|*.timer>
│   └── crontab.swarm
├── openclaw/
│   ├── scripts/
│   │   ├── swarm-mcp.mjs        ← tools MCP (1700+ linhas)
│   │   ├── cakto/               ← seed_products.py, upload_covers.py, build_session_state.py
│   │   ├── migrations/          ← *.sql numbered
│   │   ├── maintenance/         ← one-shot ops scripts
│   │   ├── campaign_manager_cron.sh
│   │   ├── smoke_tests.sh
│   │   ├── phase1_finalize.sh
│   │   └── CHANGELOG.md
│   └── workspace/               ← runtime: AGENTS/SOUL/USER/MEMORY/HEARTBEAT .md (versionados); pdf/xlsx gerados (ignored)
├── dashboard/                   ← Astro SSR + React islands
├── scraper/                     ← Playwright reutilizável
├── infra/                       ← docker-compose.yml (swarm-db Postgres + dashboard)
└── db/schema.sql                ← schema canônico

Regra cardeal — nunca /tmp/, nunca hermes\.tmp_* local-only

• /tmp/ no VPS some no reboot. Scripts úteis lá = perdidos.
• C:\Users\User\hermes\.tmp_*.py no Windows = invisível ao repo. Só serve como transit para base64 → ssh → /home/swarm/.... Deletar imediatamente após transfer.
• Toda mudança operacional vai pro repo. Sem exceção.

Como adicionar tool MCP nova

1. Edita openclaw/scripts/swarm-mcp.mjs, insere bloco antes de const transport = new StdioServerTransport().
2. node --check valida sintaxe (não pula).
3. Se precisa env var: adiciona em .secrets.env E em /root/.openclaw/openclaw.json (mcp.servers.swarm.env).
4. systemctl --user restart openclaw-gateway recarrega.
5. Smoke: invoca via auditor pedindo pra listar a tool por nome.

Como adicionar agente specialist

1. mkdir -p /root/.openclaw/agents/<nome>/agent
2. Escreve AGENTS.md com role+regras (idioma pt-BR ok, código en).
3. Adiciona entrada em /root/.openclaw/openclaw.json → agents.list com id, name, workspace, agentDir, model.primary/fallbacks.
4. Mirror no repo: cp pra config/agents/<nome>/AGENTS.md, commit.
5. Restart gateway. openclaw agents list confirma.

Como adicionar migration

1. openclaw/scripts/migrations/NNN_<descricao>.sql (numerado sequencial)
2. Aplicar: docker cp ... && docker exec infra-swarm-db-1 psql -U swarm -d swarm -f /tmp/x.sql
3. Commit no repo.

Secrets sanitization

• Nunca hardcoded em .py/.mjs versionado. Sempre via process.env.X / os.environ["X"].
• .secrets.env é root 600, gitignored. Backup manual (não via git).
• openclaw.template.json no repo usa "DATABASE_URL": "${DATABASE_URL}" — envsubst no deploy substitui pelo valor real do .secrets.env.

Commits

• Feature-by-feature. Não bolos enormes.
• Mensagem: <categoria>(<componente>): <o que mudou> + body com por que.
• Categorias: mcp, agent, dashboard, config, migration, script, sanitize, docs.
• Exemplo bom: mcp(swarm): cakto_upload_image — SPA Bearer+cookies multipart endpoint

Sync entre /root/.openclaw/* e config/ no repo

Mudanças manuais em /root/.openclaw/ (agents, openclaw.json) devem ser refletidas no repo:

# bem manual por enquanto — TODO: cron de drift detection
cp /root/.openclaw/agents/agent-X/agent/AGENTS.md /home/swarm/config/agents/agent-X/AGENTS.md
git add -p && git commit