feat: refactor 30+ skills to Anthropic progressive disclosure pattern

- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-12 15:05:03 +00:00
parent 9404af7ac9
commit 6b3a6f2698
397 changed files with 67154 additions and 17257 deletions
--- a/infraestrutura/skills/easypanel-api/SKILL.md
+++ b/infraestrutura/skills/easypanel-api/SKILL.md
@@ -1,51 +1,41 @@
 ---
 name: easypanel-api
-description: EasyPanel official tRPC API reference. All endpoints for projects, services, deploy, settings. Use when user mentions "easypanel api", "criar serviço easypanel", "deploy easypanel", "easypanel config".
-author: Descomplicar® Crescimento Digital
-version: 1.0.0
-quality_score: 70
-user_invocable: true
-desk_task: 1502
+description: Referência completa da API tRPC oficial do EasyPanel — todos os endpoints para projectos, serviços, deploy e configurações.
 ---

 # /easypanel-api - API Oficial EasyPanel

-Referência completa da API tRPC do EasyPanel. **Baseado em engenharia reversa do SDK oficial.**
+Referência da API tRPC do EasyPanel. Baseado em engenharia reversa do SDK oficial.

 ---

 ## Autenticação

 ```bash
-# Token guardado em /etc/easypanel/.api-token (chmod 600)
 TOKEN=$(cat /etc/easypanel/.api-token)
-
-# Header obrigatório
+# Header obrigatório em todos os pedidos:
 -H "Authorization: Bearer $TOKEN"
 ```

---
+**Base URL:** `http://localhost:3000/api/trpc/`

-## Base URL
-
-```
-http://localhost:3000/api/trpc/
-```
-
-**Nota:** Usar localhost via SSH, não expor externamente.
+Usar sempre via SSH localhost. Nunca expor externamente.

 ---

-## Formato de Requests
+## Formato de Pedidos
+
+| Método | Quando usar | Formato |
+|--------|-------------|---------|
+| GET | Leitura (list, inspect, get) | `?input=URL_ENCODED_JSON` |
+| POST | Escrita (create, update, deploy, destroy) | `-d '{"json":{...}}'` com `Content-Type: application/json` |

-### GET (leitura)
 ```bash
+# GET
 curl -s "http://localhost:3000/api/trpc/ENDPOINT?input=URL_ENCODED_JSON" \
  -H "Authorization: Bearer $TOKEN"
-```

-### POST (escrita)
-```bash
+# POST
 curl -s -X POST "http://localhost:3000/api/trpc/ENDPOINT" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
@@ -56,344 +46,82 @@ curl -s -X POST "http://localhost:3000/api/trpc/ENDPOINT" \

 ## Projects API

-### Listar Projectos
+| Endpoint | Tipo | Descrição |
+|----------|------|-----------|
+| `projects.listProjects` | GET | Listar todos os projectos |
+| `projects.listProjectsAndServices` | GET | Projectos + todos os serviços |
+| `projects.createProject` | POST | Criar projecto (`name`) |
+| `projects.destroyProject` | POST | Destruir projecto (`projectName`) |
+| `projects.inspectProject` | GET | Inspecionar projecto (`projectName`) |

 ```bash
+# Listar projectos (teste rápido de autenticação)
 curl -s "http://localhost:3000/api/trpc/projects.listProjects" \
  -H "Authorization: Bearer $TOKEN"
-```

-**Response:**
-```json
-{
-  "result": {
-    "data": {
-      "json": [
-        {"name": "descomplicar", "createdAt": "2024-12-30T01:32:45.738Z"},
-        {"name": "clientes", "createdAt": "2024-12-30T16:18:38.840Z"}
-      ]
-    }
-  }
-}
-```
-
-### Listar Projectos com Serviços
-
-```bash
-curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-**Response:** Lista completa de projectos e todos os serviços com configurações.
-
-### Criar Projecto
-
-```bash
+# Criar projecto
 curl -s -X POST "http://localhost:3000/api/trpc/projects.createProject" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"json":{"name":"novo-projecto"}}'
 ```

-### Destruir Projecto
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/projects.destroyProject" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"nome-projecto"}}'
-```
-
-### Inspeccionar Projecto
-
-```bash
-curl -s "http://localhost:3000/api/trpc/projects.inspectProject?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%7D%7D" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
 ---

 ## Services API

-### Service Types
+Endpoints completos com exemplos curl: ver [references/services-api.md](references/services-api.md)

-| Type | Descrição |
-|------|-----------|
-| `app` | Aplicação (Node.js, Python, Go, etc.) |
-| `mysql` | MySQL database |
-| `mariadb` | MariaDB database |
-| `postgres` | PostgreSQL database |
-| `mongo` | MongoDB database |
-| `redis` | Redis cache |
+| Endpoint | Tipo | Descrição |
+|----------|------|-----------|
+| `services.app.createService` | POST | Criar serviço app |
+| `services.postgres.createService` | POST | Criar PostgreSQL |
+| `services.mysql.createService` | POST | Criar MySQL |
+| `services.redis.createService` | POST | Criar Redis |
+| `services.app.inspectService` | GET | Inspecionar serviço |
+| `services.app.deployService` | POST | Fazer deploy |
+| `services.app.enableService` | POST | Activar serviço |
+| `services.app.disableService` | POST | Desactivar serviço |
+| `services.app.destroyService` | POST | Destruir serviço |

-### Criar Serviço App
+**Parâmetros obrigatórios:** `projectName` + `serviceName` em todos os endpoints de serviços.

-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.createService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
-```
-
-### Criar Serviço Database
-
-```bash
-# PostgreSQL
-curl -s -X POST "http://localhost:3000/api/trpc/services.postgres.createService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-db"}}'
-
-# MySQL
-curl -s -X POST "http://localhost:3000/api/trpc/services.mysql.createService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"mysql-db"}}'
-
-# Redis
-curl -s -X POST "http://localhost:3000/api/trpc/services.redis.createService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"cache"}}'
-```
-
-### Inspeccionar Serviço
-
-```bash
-# URL encode: {"json":{"projectName":"descomplicar","serviceName":"dashboard_descomplicar"}}
-curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%2C%22serviceName%22%3A%22dashboard_descomplicar%22%7D%7D" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-**Response:**
-```json
-{
-  "projectName": "descomplicar",
-  "name": "dashboard_descomplicar",
-  "type": "app",
-  "enabled": true,
-  "token": "deploy-webhook-token",
-  "source": {"type": "git", "repo": "https://...", "ref": "main"},
-  "build": {"type": "nixpacks", "buildCommand": "npm run build"},
-  "env": "VAR=value",
-  "mounts": [],
-  "ports": []
-}
-```
-
-### Deploy Serviço
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.deployService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
-```
-
-### Enable/Disable Serviço
-
-```bash
-# Disable
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.disableService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
-
-# Enable
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.enableService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
-```
-
-### Destruir Serviço
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.destroyService" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}'
-```
+**Regra Descomplicar:** `projectName:"descomplicar"` para serviços próprios.

 ---

 ## Service Configuration API

-### Actualizar Source (GitHub)
+Endpoints completos com exemplos curl: ver [references/service-config-api.md](references/service-config-api.md)

-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGithub" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "owner":"ealmeida",
-    "repo":"MeuRepo",
-    "ref":"main",
-    "path":"/"
-  }}'
-```
-
-### Actualizar Source (Git Custom)
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGit" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "repo":"https://git.descomplicar.pt/org/repo",
-    "ref":"main",
-    "path":"/"
-  }}'
-```
-
-### Actualizar Source (Docker Image)
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceImage" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "image":"node:22-alpine"
-  }}'
-```
-
-### Actualizar Environment Variables
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateEnv" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "env":"NODE_ENV=production\nPORT=3000\nDATABASE_URL=postgres://..."
-  }}'
-```
-
-### Actualizar Domains
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateDomains" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "domains":[
-      {"host":"api.descomplicar.pt","https":true,"port":3000}
-    ]
-  }}'
-```
-
-### Actualizar Mounts
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateMounts" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "mounts":[
-      {"type":"volume","name":"data","mountPath":"/app/data"}
-    ]
-  }}'
-```
-
-### Actualizar Ports (non-HTTP)
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updatePorts" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "ports":[
-      {"published":8080,"target":3000,"protocol":"tcp"}
-    ]
-  }}'
-```
-
-### Actualizar Resources
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateResources" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "resources":{
-      "memoryLimit":"512m",
-      "memoryReservation":"256m",
-      "cpuLimit":1,
-      "cpuReservation":0.5
-    }
-  }}'
-```
-
-### Actualizar Build Config
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateBuild" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "build":{
-      "type":"nixpacks",
-      "buildCommand":"npm run build",
-      "startCommand":"npm start"
-    }
-  }}'
-```
-
-### Actualizar Deploy (Replicas, Command)
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateAdvanced" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-api",
-    "deploy":{
-      "replicas":2,
-      "command":"node dist/index.js",
-      "zeroDowntime":true
-    }
-  }}'
-```
+| Endpoint | Descrição |
+|----------|-----------|
+| `services.app.updateSourceGithub` | Source GitHub (`owner`, `repo`, `ref`, `path`) |
+| `services.app.updateSourceGit` | Source Git custom (`repo`, `ref`, `path`) |
+| `services.app.updateSourceImage` | Source Docker image (`image`) |
+| `services.app.updateEnv` | Variáveis de ambiente (`env` como string multi-linha) |
+| `services.app.updateDomains` | Domínios (`domains[]` com `host`, `https`, `port`) |
+| `services.app.updateMounts` | Volumes (`mounts[]` com `type`, `name`, `mountPath`) |
+| `services.app.updatePorts` | Portas TCP/UDP (`ports[]` com `published`, `target`, `protocol`) |
+| `services.app.updateResources` | CPU/RAM (`memoryLimit`, `cpuLimit`, etc.) |
+| `services.app.updateBuild` | Build config (`type`, `buildCommand`, `startCommand`) |
+| `services.app.updateAdvanced` | Deploy avançado (`replicas`, `command`, `zeroDowntime`) |
+| `services.postgres.updateBackup` | Backup BD para S3 |

 ---

 ## Monitor API

-### System Stats
-
 ```bash
+# Stats do sistema
 curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \
  -H "Authorization: Bearer $TOKEN"
-```

-### Service Stats
-
-```bash
-curl -s "http://localhost:3000/api/trpc/monitor.getServiceStats?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%2C%22serviceName%22%3A%22minha-api%22%7D%7D" \
+# Stats de serviço (URL encode necessário)
+# input: {"json":{"projectName":"descomplicar","serviceName":"api"}}
+curl -s "http://localhost:3000/api/trpc/monitor.getServiceStats?input=..." \
  -H "Authorization: Bearer $TOKEN"
-```

-### Docker Task Stats
-
-```bash
+# Stats Docker tasks
 curl -s "http://localhost:3000/api/trpc/monitor.getDockerTaskStats" \
  -H "Authorization: Bearer $TOKEN"
 ```
@@ -402,10 +130,10 @@ curl -s "http://localhost:3000/api/trpc/monitor.getDockerTaskStats" \

 ## Logs API

-### Get Service Logs
-
 ```bash
-curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=%7B%22json%22%3A%7B%22projectName%22%3A%22descomplicar%22%2C%22serviceName%22%3A%22minha-api%22%2C%22tail%22%3A100%7D%7D" \
+# Logs de serviço (tail=100)
+# input: {"json":{"projectName":"descomplicar","serviceName":"api","tail":100}}
+curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=..." \
  -H "Authorization: Bearer $TOKEN"
 ```

@@ -413,108 +141,26 @@ curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=%7B%22json%22%

 ## Settings API

-### Get Server IP
-
-```bash
-curl -s "http://localhost:3000/api/trpc/settings.getServerIp" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-### Get Panel Domain
-
-```bash
-curl -s "http://localhost:3000/api/trpc/settings.getPanelDomain" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-### Set Panel Domain
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/settings.setPanelDomain" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"domain":"easy.descomplicar.pt"}}'
-```
-
-### Get/Set Let's Encrypt Email
-
-```bash
-# Get
-curl -s "http://localhost:3000/api/trpc/settings.getLetsEncryptEmail" \
-  -H "Authorization: Bearer $TOKEN"
-
-# Set
-curl -s -X POST "http://localhost:3000/api/trpc/settings.setLetsEncryptEmail" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{"email":"emanuel@descomplicar.pt"}}'
-```
-
-### Restart Traefik
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/settings.restartTraefik" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{}}'
-```
-
-### Restart EasyPanel
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/settings.restartEasypanel" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{}}'
-```
-
-### Prune Docker Images
-
-```bash
-curl -s -X POST "http://localhost:3000/api/trpc/settings.pruneDockerImages" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{}}'
-```
+| Endpoint | Tipo | Descrição |
+|----------|------|-----------|
+| `settings.getServerIp` | GET | IP do servidor |
+| `settings.getPanelDomain` | GET | Domínio do painel |
+| `settings.setPanelDomain` | POST | Definir domínio (`domain`) |
+| `settings.getLetsEncryptEmail` | GET | Email Let's Encrypt |
+| `settings.setLetsEncryptEmail` | POST | Definir email (`email`) |
+| `settings.restartTraefik` | POST | Reiniciar Traefik |
+| `settings.restartEasypanel` | POST | Reiniciar EasyPanel |
+| `settings.pruneDockerImages` | POST | Limpar imagens Docker |

 ---

-## Database Backup API
-
-### Update Backup Config
+## URL Encoding para GET

 ```bash
-curl -s -X POST "http://localhost:3000/api/trpc/services.postgres.updateBackup" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"json":{
-    "projectName":"descomplicar",
-    "serviceName":"minha-db",
-    "backup":{
-      "enabled":true,
-      "schedule":"0 3 * * *",
-      "destination":{
-        "type":"s3",
-        "bucket":"backups",
-        "region":"eu-west-1",
-        "accessKey":"...",
-        "secretKey":"..."
-      }
-    }
-  }}'
-```
-
---
-
-## Helper: URL Encode JSON
-
-Para GET requests, o input deve ser URL encoded:
-
-```bash
-# Usando Python
 INPUT='{"json":{"projectName":"descomplicar","serviceName":"api"}}'
 ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))")
-curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$ENCODED" -H "Authorization: Bearer $TOKEN"
+curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$ENCODED" \
+  -H "Authorization: Bearer $TOKEN"
 ```

 ---
@@ -525,17 +171,12 @@ Criar `/usr/local/bin/easypanel-api`:

 ```bash
 #!/bin/bash
-# EasyPanel API wrapper
-# Usage: easypanel-api <endpoint> [json-body]
-
 TOKEN=$(cat /etc/easypanel/.api-token)
 BASE="http://localhost:3000/api/trpc"

 if [ -z "$2" ]; then
-  # GET request
  curl -s "$BASE/$1" -H "Authorization: Bearer $TOKEN"
 else
-  # POST request
  curl -s -X POST "$BASE/$1" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
@@ -543,23 +184,78 @@ else
 fi
 ```

-**Uso:**
-```bash
-easypanel-api projects.listProjects
-easypanel-api services.app.deployService '{"json":{"projectName":"descomplicar","serviceName":"api"}}'
-```
+Uso: `easypanel-api projects.listProjects`

 ---

-## Checklist Uso API
+## Checklist de Uso

+- [ ] SSH para servidor `easy`
+- [ ] `TOKEN=$(cat /etc/easypanel/.api-token)`
+- [ ] Testar: `curl -s ".../projects.listProjects" -H "Authorization: Bearer $TOKEN"`
+- [ ] Usar endpoints conforme documentado
+- [ ] Validar resposta em `result.data.json`
+
+---
+
+## Limitações de Mounts
+
+O EasyPanel usa Docker Swarm internamente. Isto impõe limitações nos mounts que diferem do Docker standalone.
+
+### Tipos de mount suportados
+
+| Tipo | API `type` | Comportamento | Limitações |
+|------|-----------|---------------|------------|
+| **Volume mount** | `volume` | Volume gerido pelo Docker Swarm | Funciona bem. Dados persistem no nó. Sem acesso directo ao filesystem do host |
+| **Bind mount** | `bind` | Monta directório do host no container | **Limitado no Swarm** — só funciona se o serviço estiver fixo a um nó específico |
+| **File mount** | `file` | Monta ficheiro individual (config) | Funciona. Ideal para ficheiros de configuração |
+
+### Limitações críticas
+
+1. **Bind mounts no Swarm** — O Docker Swarm não garante que o container corra sempre no mesmo nó. Um bind mount (`type: "bind"`) aponta para um path no host, mas se o container migrar para outro nó, esse path pode não existir. O EasyPanel mitiga isto parcialmente por correr num único nó, mas a limitação arquitectural mantém-se.
+
+2. **Sem suporte nativo a NFS/CIFS** — A API `updateMounts` não suporta drivers de volume remotos (NFS, CIFS, etc.) directamente. Para volumes partilhados, é necessário criar o volume Docker manualmente com o driver adequado e depois referenciá-lo.
+
+3. **Permissões** — Volumes criados via API pertencem a `root:root` por defeito. Containers que correm com utilizador não-root podem ter problemas de permissões. Workaround: usar `command` no `updateAdvanced` para corrigir permissões no arranque.
+
+4. **Substituição total** — `updateMounts` substitui **todos** os mounts existentes. Para adicionar um mount, é preciso primeiro obter os mounts actuais via `inspectService` e enviar a lista completa com o novo mount incluído.
+
+### Workarounds conhecidos
+
+```bash
+# 1. Obter mounts actuais antes de adicionar novo
+INSPECT=$(curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=..." \
+  -H "Authorization: Bearer $TOKEN")
+# Extrair mounts existentes do JSON e adicionar o novo
+
+# 2. Volume com permissões corrigidas — usar initCommand
+curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateAdvanced" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{
+    "projectName":"descomplicar",
+    "serviceName":"minha-api",
+    "deploy":{
+      "command":"chown -R 1000:1000 /app/data && node dist/index.js"
+    }
+  }}'
+
+# 3. Volume Docker manual com driver NFS (fora da API)
+docker volume create --driver local \
+  --opt type=nfs \
+  --opt o=addr=192.168.1.10,rw \
+  --opt device=:/export/data \
+  vol-nfs-data
+# Depois referenciar na API:
+# {"type":"volume","name":"vol-nfs-data","mountPath":"/app/data"}
 ```
-1. [ ] SSH para servidor easy
-2. [ ] TOKEN=$(cat /etc/easypanel/.api-token)
-3. [ ] Testar: curl -s "http://localhost:3000/api/trpc/projects.listProjects" -H "Authorization: Bearer $TOKEN"
-4. [ ] Usar endpoints conforme documentado
-5. [ ] Validar resposta (result.data.json)
-```
+
+### Recomendações
+
+- **Preferir `volume`** sobre `bind` — mais portável e compatível com Swarm
+- **Usar `file`** para configs individuais (nginx.conf, .env, etc.)
+- **Inspeccionar antes de actualizar** — a API substitui a lista inteira de mounts
+- **Documentar volumes manuais** — volumes criados fora da API não aparecem no painel EasyPanel até serem referenciados por um serviço

 ---

@@ -567,12 +263,16 @@ easypanel-api services.app.deployService '{"json":{"projectName":"descomplicar",

 | Anti-Pattern | Risco | Alternativa |
 |--------------|-------|-------------|
-| Expor API externamente | Segurança | Usar apenas via SSH localhost |
-| Hardcode token | Leak | Usar /etc/easypanel/.api-token |
-| Não validar response | Erros silenciosos | Verificar result.data.json |
-| POST sem Content-Type | Request falha | Sempre incluir header |
+| Expor API externamente | Segurança crítica | Usar apenas via SSH localhost |
+| Hardcode token | Leak de credenciais | Usar `/etc/easypanel/.api-token` |
+| Não validar response | Erros silenciosos | Verificar `result.data.json` |
+| POST sem `Content-Type` | Request falha | Sempre incluir header |

 ---

-**Versão:** 1.0.0 | **Autor:** Descomplicar®
-**Fonte:** Engenharia reversa SDK github.com/Easypanel-Community/easypanel
+## Ficheiros de Referência
+
+| Ficheiro | Conteúdo |
+|----------|----------|
+| [references/services-api.md](references/services-api.md) | Endpoints de serviços com curl completo (create, inspect, deploy, enable/disable, destroy) |
+| [references/service-config-api.md](references/service-config-api.md) | Endpoints de configuração (source, env, domains, mounts, ports, resources, build, deploy, backup BD) |