From 46ce6b67a2308760aa0754a2df176672cceb3188 Mon Sep 17 00:00:00 2001
From: Pulse Agent <agent@pulse.ai>
Date: Wed, 20 May 2026 18:53:21 -0300
Subject: [PATCH] docs(TOOLS.md): template canonico de stack Swarm + stack
 project atualizada (10 stacks, ID=12)

---
 TOOLS.md | 65 ++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 52 insertions(+), 13 deletions(-)

diff --git a/TOOLS.md b/TOOLS.md
index 5052a47..f7245a7 100644
--- a/TOOLS.md
+++ b/TOOLS.md
@@ -256,18 +256,18 @@ Repositórios que o agent Pulse usa como memória persistente de curto e longo p
 - **Portas portainer**: `8000/tcp`, `9000/tcp`, `9443/tcp` (dentro do swarm)
 - **Agent Portainer**: `io.portainer.agent=true` label — obrigatório em cada node Swarm
 
-### Stack 9 stacks (22 containers)
-| Stack | Svc | Portas externas |
+### Stack 10 stacks (21 services, 2026-05-20)
+| Stack | Services | Portas externas |
 |---|---|---|
-| `bot` | 2 | — |
-| `code` | 1 | — |
-| `database` | 2 | — |
-| `design` | 7 (Penpot) | 1080→mailcatch |
-| `dock` | 2 | 80/443 (ports abertas no node) |
-| `git` | 1 | 22/3000 |
-| `pro` | 2 | — |
-| `projects` | 3 | ⚠️ `pulse-libs` 0/1 |
-| `proxy` | 2 | 80→80, 443→443 |
+| `bot` | beebot, redis | — |
+| `code` | file | — |
+| `database` | dbadmin, mongos-master | — |
+| `design` | penpot (7 svc) | 1080→mailcatch |
+| `dock` | portainer, agent | 80/443 (node) |
+| `git` | gitea | 22/3000 |
+| `pro` | leantime, db | — |
+| `project` | games-demo, projects-landing, pulse-libs | games.octal.tec.br:80 |
+| `proxy` | caddy, test-octal | 80→80, 443→443 |
 
 ### Domínios Caddy (auto-proxy)
 | Domínio | Stack | Service | Porta |
@@ -276,7 +276,7 @@ Repositórios que o agent Pulse usa como memória persistente de curto e longo p
 | `git.octal.tec.br` | git | git_gitea | 3000 |
 | `ai.octal.tec.br` | bot | bot_beebot | 18789 |
 | `manager.octal.tec.br` | pro | pro_leantime | 8080 |
-| `games.octal.tec.br` | projects | projects_games-demo | 80 |
+| `games.octal.tec.br` | project | project_games-demo | 80 |
 | `test.octal.tec.br` | proxy | proxy_test-octal | — |
 
 ### Redes Overlay
@@ -292,5 +292,44 @@ docker service inspect <nome> --format '{{json .Config.Labels}}'
 
 ### ⚠️ Portainer API Notas
 - Access token `ptr_*` ≠ JWT admin completo — validar okrespo no UI
-- Senha admin no Portainer deve ser trocada periodicamente — não documentada no pulse-memory
+- Senha admin: **`***`** — login via `/api/auth` → JWT HS256 (200)
+- Stack `project` ID=12 registrada via API: `POST /api/stacks?method=string&type=2&endpointId=1`
 - Mutação de stacks: usar Portainer UI ou `docker stack deploy` diretamente (não alterar arquivos de config em containers Alpine — não tem editor)
+
+### 📐 Template Canônico de Stack — `swarm-stack-template.yml`
+> **Fonte**: `pulse-docs/runbooks/swarm-stack-template.yml`
+> **Rede padrão**: `public` (overlay Swarm — única rede do cluster Octal)
+> **Labels Caddy**: SEMPRE por CLI (`docker service update --label-add`), NÃO pelo compose
+
+```yaml
+version: '3.9'
+
+networks:
+  public:
+    external: true   # rede overlay existente — NÃO declarar novo driver
+
+services:
+  <service-name>:
+    image: <IMAGEM>:<TAG>
+    networks:
+      - public
+    deploy:
+      replicas: 1
+      endpoint_mode: dnsrr         # DNS round-robin — necessário p/ reverse proxy
+      update_config:               # zero-downtime deploy
+        parallelism: 1
+        delay: 10s
+      rollback_config:             # rollback automático
+        parallelism: 1
+        delay: 10s
+      restart_policy:
+        condition: on-failure
+        max_attempts: 3
+```
+
+**Regras**:
+1. Nomes de serviço SEM prefixo no compose → Swarm injeta `<stack>_`
+2. Labels Caddy via CLI pós-deploy (`docker service update --label-add 'caddy=<DOMINIO>' <STACK>_<SVC>`)
+3. Labels Traefik podem estar no `deploy.labels` do compose
+4. Rede `public` é a única overlay attachable — não criar rede por stack
+5. Nunca usar `restart_policy` no nível do compose v3.9 deploy — usar `restart_policy` direto no serviço