learnings: Portainer ptr-token-scope + compose-v3 swarm labels/gotchas + stack migration pattern

- LRN-20260520-006: ptr_ token scope (401 endpoints, /api/status OK)
- LRN-20260520-007: compose v3.9 restart_policy e deploy.labels nao funcionam no Swarm
- LRN-20260520-008: stack migration create-then-remove-pattern

.learnings/LEARNINGS.md

@@ -228,3 +228,76 @@ Workaround mínimo para testar onChange em inputs no jsdom puro, onde `.value`
 - Tags: jsdom, fireEvent, input, value
 - Pattern-Key: jsdom.fireEvent-change-writable
 - Recurrence-Count: 1
+
+---
+
+## [LRN-20260520-006] portainer-api-ptr-token-scope
+
+**Logged**: 2026-05-20T17:38:00-03:00
+**Priority**: high
+**Status**: reference
+**Area**: devops | infra | docker
+
+### Summary
+Token Portainer com prefixo `ptr_` é um access token — funciona em `/api/status` (200) mas retorna 401 em `/api/endpoints`, `/api/stacks`, `/api/auth` — escopo muito limitado.
+
+### Details
+Para operações de mutação (criar/gerenciar stacks) pela API Portainer é necessário JWT admin válido obtido via `POST /api/auth` com username+senha. Senha admin do Portainer não estava documentada — usamos `docker stack deploy` via CLI Docker Swarm diretamente como workaround.
+
+### Suggested Action
+Documentar senha admin do Portainer de forma segura (password manager), ou usar service token JWT com escopo `admin` completo.
+
+### Metadata
+- Source: error
+- Tags: portainer, api, token, docker-swarm, jwt
+- Pattern-Key: portainer.api-ptr-token-scope
+
+---
+
+## [LRN-20260520-007] docker-compose-v3-swarm-labels-and-restart-policy
+
+**Logged**: 2026-05-20T17:38:00-03:00
+**Priority**: high
+**Status**: reference
+**Area**: devops | docker
+
+### Summary
+docker stack deploy com compose v3.9 no Swarm mode — duas propriedades que não funcionam como esperado:
+
+1. **`restart_policy`** — não é propriedade válida no `deploy` spec; Docker Swarm gerencia restart nativamente (Always)
+2. **`deploy.labels`** — não se tornam container labels; labels só são aplicadas via `docker service create --label-add` ou `--label-add` em `docker service update`
+
+### Fix
+- Remover `restart_policy` do YAML
+- Aplicar labels necessárias (ex: caddy=) via CLI `docker service update --label-add` ou diretamente no `docker service create`
+
+### Metadata
+- Source: error
+- Tags: docker, swarm, compose, labels, restart-policy
+- Pattern-Key: docker.swarm-compose-v3-gotchas
+
+---
+
+## [LRN-20260520-008] stack-migration-docker-swarm-createmigrate
+
+**Logged**: 2026-05-20T17:38:00-03:00
+**Priority**: medium
+**Status**: reference
+**Area**: devops | docker
+
+### Summary
+Migração de stack Docker Swarm (trocar de nome/namespace):
+1. Criar novos serviços com o nome da stack destino + labels corretas (`docker service create --label-add ...`)
+2. Validar que os serviços estão saudáveis
+3. Remover a stack antiga (`docker stack rm <antiga>`)
+
+### Safety notes
+- Não usar `docker stack deploy --prune` em stack ativa em produção — apaga services não presentes no novo compose
+- Para imagens locais: usar `--with-registry-auth` ou tag com registry acessível
+- Sempre validar `docker service ps <nome>` antes de remover a stack antiga
+
+### Metadata
+- Source: best_practice
+- Tags: docker, swarm, migration, stack
+- Pattern-Key: docker.swarm-stack-migration
+