diff --git a/acidaos/skills/devops/SKILL.md b/acidaos/skills/devops/SKILL.md index 1a37803..43fe5d7 100644 --- a/acidaos/skills/devops/SKILL.md +++ b/acidaos/skills/devops/SKILL.md @@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, mcp__gitea__list_repo_action_workflows, Skill para criar e gerir pipelines CI/CD do AcidaOS via **Gitea Actions**. -> **Atenção:** O AcidaOS usa **Gitea Actions**, não GitHub Actions. A sintaxe é compatível mas o runner é self-hosted em `mcp-hub.descomplicar.pt`. +> **Atenção:** O AcidaOS usa **Gitea Actions**, não GitHub Actions. A sintaxe é compatível mas o runner é self-hosted em `gateway.descomplicar.pt`. ## Contexto @@ -18,7 +18,7 @@ Repositórios Gitea: acidaos-dashboard → Next.js Dashboard Runners: - self-hosted @ mcp-hub.descomplicar.pt + self-hosted @ gateway.descomplicar.pt Labels: [self-hosted, linux, rust, node] Deploy target: @@ -314,3 +314,15 @@ mcp__gitea__get_repo_action_job_log_preview({ owner: "descomplicar", repo: "acid --- **Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/acidaos/skills/docs/SKILL.md b/acidaos/skills/docs/SKILL.md index 8cbea79..287d5f7 100644 --- a/acidaos/skills/docs/SKILL.md +++ b/acidaos/skills/docs/SKILL.md @@ -189,3 +189,15 @@ Antes de marcar tarefa como concluída: --- **Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/acidaos/skills/rust-dev/SKILL.md b/acidaos/skills/rust-dev/SKILL.md index df83d43..c98bee7 100644 --- a/acidaos/skills/rust-dev/SKILL.md +++ b/acidaos/skills/rust-dev/SKILL.md @@ -230,3 +230,15 @@ cargo fmt --check # formatação correcta --- **Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/acidaos/skills/spoke-dev/SKILL.md b/acidaos/skills/spoke-dev/SKILL.md index 8f087e7..e1ada04 100644 --- a/acidaos/skills/spoke-dev/SKILL.md +++ b/acidaos/skills/spoke-dev/SKILL.md @@ -237,3 +237,15 @@ pnpm lint # zero erros ESLint --- **Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/automacao/skills/moloni-api/SKILL.md b/automacao/skills/moloni-api/SKILL.md index 0836fb3..72f54af 100644 --- a/automacao/skills/moloni-api/SKILL.md +++ b/automacao/skills/moloni-api/SKILL.md @@ -104,3 +104,15 @@ A sandbox fornece um ambiente isolado com dados fictícios para desenvolvimento - **[references/endpoints.md](references/endpoints.md)** - Catálogo completo de endpoints - **Docs oficiais:** https://www.moloni.pt/dev/endpoints/ - **Sandbox:** https://www.moloni.pt/dev/sandbox/ + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/automacao/skills/n8n-chatbot/SKILL.md b/automacao/skills/n8n-chatbot/SKILL.md index 304ade8..63261bf 100644 --- a/automacao/skills/n8n-chatbot/SKILL.md +++ b/automacao/skills/n8n-chatbot/SKILL.md @@ -299,3 +299,15 @@ mcp__n8n__search_templates({ --- *Skill v1.0 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/automacao/skills/n8n-health/SKILL.md b/automacao/skills/n8n-health/SKILL.md index 7c41529..9720b95 100644 --- a/automacao/skills/n8n-health/SKILL.md +++ b/automacao/skills/n8n-health/SKILL.md @@ -112,3 +112,15 @@ curl -H "X-N8N-API-KEY: $KEY" https://automator.descomplicar.pt/api/v1/workflows --- *Skill v1.0 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/automacao/skills/n8n-notify/SKILL.md b/automacao/skills/n8n-notify/SKILL.md index 59cfd04..729429f 100644 --- a/automacao/skills/n8n-notify/SKILL.md +++ b/automacao/skills/n8n-notify/SKILL.md @@ -232,3 +232,15 @@ mcp__n8n__search_templates({ --- *Skill v1.0 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/automacao/skills/n8n-schedule/SKILL.md b/automacao/skills/n8n-schedule/SKILL.md index cbba972..c21b153 100644 --- a/automacao/skills/n8n-schedule/SKILL.md +++ b/automacao/skills/n8n-schedule/SKILL.md @@ -167,3 +167,15 @@ mcp__n8n__n8n_executions({ --- *Skill v1.0 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/automacao/skills/n8n-sync/SKILL.md b/automacao/skills/n8n-sync/SKILL.md index 787efcd..b8f28dc 100644 --- a/automacao/skills/n8n-sync/SKILL.md +++ b/automacao/skills/n8n-sync/SKILL.md @@ -166,3 +166,15 @@ Slack (alertar) --- *Skill v1.0 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/automacao/skills/n8n-webhook/SKILL.md b/automacao/skills/n8n-webhook/SKILL.md index f89db25..718e0e2 100644 --- a/automacao/skills/n8n-webhook/SKILL.md +++ b/automacao/skills/n8n-webhook/SKILL.md @@ -158,3 +158,15 @@ curl -X POST https://automator.descomplicar.pt/webhook/meu-webhook \ --- *Skill v1.0 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/_core/SKILL.md b/core-tools/skills/_core/SKILL.md index b45ddec..ebb962c 100644 --- a/core-tools/skills/_core/SKILL.md +++ b/core-tools/skills/_core/SKILL.md @@ -122,3 +122,15 @@ mcp__memory-supabase__save_memory { --- *Core Standards v1.1 | 2026-03-12* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/agent-context-injector/SKILL.md b/core-tools/skills/agent-context-injector/SKILL.md index 5d3c655..9b70650 100644 --- a/core-tools/skills/agent-context-injector/SKILL.md +++ b/core-tools/skills/agent-context-injector/SKILL.md @@ -1,149 +1,65 @@ --- name: agent-context-injector -description: Injecção dinâmica de contexto específico para cada agente — MCPs disponíveis, skills relevantes e datasets Dify. +description: Injeccao dinamica de contexto (MCPs e Skills) nos agentes via script Python + hook SessionStart com deteccao de staleness. user-invocable: false allowed-tools: Read, Glob, Grep, ToolSearch --- # Agent Context Injector -Injecção dinâmica de contexto específico para cada agente. +Regeneracao automatica das seccoes "Your Available MCPs" e "Your Available Skills" em todos os agentes. -## Triggers +## Como funciona -Esta skill é activada automaticamente via hook `SubagentStart` quando: -- Um subagente é iniciado via Task tool -- Contexto precisa ser enriquecido com recursos do agente +1. **Hook SessionStart** (`~/.claude/hooks/agent-context-refresh.sh`) calcula hash dos inputs +2. Se hash mudou → executa `~/.claude/scripts/regenerate-agent-context.py` +3. Script le frontmatter de cada agente, inventario MCPs, mapeamento domain e skills dos plugins +4. Gera seccoes entre marcadores `` / `` +5. Guarda novo hash em `~/.claude/.agent-context-hash` -## Capabilities +## Ficheiros -### 1. Context Building -- Consultar mapeamento agente → recursos na BD -- Gerar lista de MCPs disponíveis para o agente -- Gerar lista de skills relevantes -- Incluir datasets Dify para consulta automática +| Ficheiro | Funcao | +|----------|--------| +| `~/.claude/scripts/regenerate-agent-context.py` | Script principal de regeneracao | +| `~/.claude/hooks/agent-context-refresh.sh` | Hook SessionStart com staleness | +| `~/.claude/_resources/domain-mcp-map.json` | Mapeamento domain -> MCPs recomendados | +| `~/.claude/_resources/mcps.json` | Inventario de 34+ MCPs | +| `~/.claude/.agent-context-hash` | Hash MD5 dos inputs (staleness) | -### 2. Token Optimization -- Calcular tokens do contexto gerado -- Priorizar recursos por relevância -- Truncar se exceder limite (~800 tokens) -- Cache de contextos frequentes +## Dados de entrada -### 3. Dynamic Injection -- Adicionar contexto ao prompt do agente -- Incluir instruções de uso dos recursos -- Configurar auto-consult para datasets +- **Agentes:** `~/.claude/agents/*.md` — frontmatter com `domain`, `skills` +- **MCPs:** `~/.claude/_resources/mcps.json` — lista com `id`, `name`, `category` +- **Domain map:** `~/.claude/_resources/domain-mcp-map.json` — primary/recommended por domain +- **Skills:** `descomplicar-plugins/*/skills/*/SKILL.md` — frontmatter com `name`, `description` -## Template de Contexto +## Performance -```markdown -## Recursos Disponíveis +| Cenario | Tempo | +|---------|-------| +| Sem mudancas (hash match) | ~66ms | +| Com regeneracao (61 agentes) | ~2-3s | -### MCPs Activos -$MCP_LIST -- Usar proactivamente para operações relevantes +## Manutencao -### Skills Recomendadas -$SKILLS_LIST -- Invocar quando tarefa corresponder +- **Adicionar MCP:** actualizar `mcps.json` e `domain-mcp-map.json` → proximo SessionStart regenera +- **Adicionar skill:** criar SKILL.md no plugin → proximo SessionStart regenera +- **Adicionar agente:** criar .md com frontmatter `domain:` → proximo SessionStart gera contexto +- **Mudar domain map:** editar `domain-mcp-map.json` → proximo SessionStart regenera -### Knowledge Base (Dify) -$DATASETS_LIST -- AUTO-CONSULT: Consultar ANTES de responder -- Query template: "$QUERY_TEMPLATE" +## Tarefa Desk -### Plugins -$PLUGINS_LIST -- Comandos disponíveis: $PLUGIN_COMMANDS +#1996 — Sistema injeccao Skills e MCPs nos agentes + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} ``` -## Workflow - -``` -SUBAGENT START → QUERY BD → BUILD CONTEXT → INJECT → EXECUTE -``` - -1. **Hook SubagentStart** dispara -2. **Identificar agente** pelo `subagent_type` -3. **Query MySQL**: - ```sql - SELECT r.resource_type, r.resource_id, r.priority - FROM cr_agent_resources r - JOIN cr_agents a ON r.agent_id = a.id - WHERE a.slug = '{agent_slug}' - AND r.auto_inject = TRUE - ORDER BY r.priority ASC; - ``` -4. **Consultar agent-knowledge-config.json** para datasets -5. **Gerar contexto** com template -6. **Calcular tokens** e optimizar se necessário -7. **Injectar** no prompt do agente - -## Métricas Target - -| Métrica | Target | -|---------|--------| -| Tempo de injecção | < 2s | -| Tokens médios | ~772 | -| Cache hit rate | > 60% | -| Erro rate | < 1% | - -## Exemplo de Output - -Para `wordpress-plugin-developer`: - -```markdown -## Recursos Disponíveis - -### MCPs Activos -- `cwp` - Gestão servidor CentOS WebPanel -- `ssh-unified` - Acesso SSH a servidores -- `filesystem` - Operações de ficheiros - -### Skills Recomendadas -- `/wp-dev` - Desenvolvimento WordPress -- `/wp-performance` - Optimização performance -- `/elementor` - Desenvolvimento Elementor - -### Knowledge Base (Dify) -- `wordpress-development` - Docs WP, hooks, filters -- `woocommerce-api` - API WooCommerce -- AUTO-CONSULT: Consultar ANTES de implementar - -### Plugins -- `superpowers` - TDD obrigatório -- `code-review` - Review automático -``` - -## Configuração - -Ficheiro `agent-knowledge-config.json`: -```json -{ - "wordpress-plugin-developer": { - "datasets": ["wordpress-development", "woocommerce-api"], - "auto_consult": true, - "query_template": "WordPress {topic} best practices 2026", - "priority_datasets": ["wordpress-development"] - } -} -``` - -## Integração com Scripts Existentes - -Este skill complementa (não substitui) os scripts Python existentes: -- `inject-mcp-context.py` - Continua activo -- `inject-skills-context.py` - Continua activo - -A skill adiciona: -- Datasets Dify dinâmicos -- Plugins activos -- Contexto mais rico e actualizado - -## Limites - -- Máximo ~800 tokens de contexto injectado (para preservar espaço) -- Não modifica comportamento do agente, apenas enriquece contexto -- Depende de mapeamentos correctos em `cr_agent_resources` -- Cache de 5 minutos pode mostrar dados desactualizados -- Não funciona para agentes não registados na BD +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/component-generator/SKILL.md b/core-tools/skills/component-generator/SKILL.md index 6f778e0..0d2bf90 100644 --- a/core-tools/skills/component-generator/SKILL.md +++ b/core-tools/skills/component-generator/SKILL.md @@ -282,4 +282,15 @@ Component Generator: - Score inicial tipicamente 50-70 (Draft) - Não cria componentes duplicados (verifica slug existente) - Requer conexão MySQL para registo em cr_* -- Não modifica componentes existentes (usar Edit tool) \ No newline at end of file +- Não modifica componentes existentes (usar Edit tool) +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/db-maintenance-manager/SKILL.md b/core-tools/skills/db-maintenance-manager/SKILL.md index 9411ef8..933c416 100644 --- a/core-tools/skills/db-maintenance-manager/SKILL.md +++ b/core-tools/skills/db-maintenance-manager/SKILL.md @@ -260,3 +260,15 @@ Resultado: - Backup não inclui tabelas não-cr_* - Optimização pode demorar em tabelas grandes (>1M registos) - Não substitui backups gerais do Desk CRM + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/infrastructure-manager/SKILL.md b/core-tools/skills/infrastructure-manager/SKILL.md index b3a1659..8b7bdad 100644 --- a/core-tools/skills/infrastructure-manager/SKILL.md +++ b/core-tools/skills/infrastructure-manager/SKILL.md @@ -203,3 +203,15 @@ Infrastructure Manager: - Detecção de órfãos limitada a tabelas cr_* conhecidas - Não corrige problemas automaticamente (apenas reporta) - Telemetria depende de hooks activos e funcionais + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/metrics/SKILL.md b/core-tools/skills/metrics/SKILL.md index 4ea9ab6..6dff43e 100644 --- a/core-tools/skills/metrics/SKILL.md +++ b/core-tools/skills/metrics/SKILL.md @@ -175,3 +175,15 @@ Link Desk CRM: `https://desk.descomplicar.pt/admin/projects/view/65` --- **Desk CRM:** Projecto #65, Task #1637 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/plugin-manager/SKILL.md b/core-tools/skills/plugin-manager/SKILL.md index ea48e7a..ef6b0ea 100644 --- a/core-tools/skills/plugin-manager/SKILL.md +++ b/core-tools/skills/plugin-manager/SKILL.md @@ -141,3 +141,15 @@ Avalia todas as regras e sugere `/plugin-config apply` se detectar alteracoes ne --- *Skill v3.0.0 | 04-03-2026 | Descomplicar* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/quality-validator/SKILL.md b/core-tools/skills/quality-validator/SKILL.md index bc27c43..1f8e742 100644 --- a/core-tools/skills/quality-validator/SKILL.md +++ b/core-tools/skills/quality-validator/SKILL.md @@ -188,3 +188,15 @@ Quality Validator: - Não modifica componentes (apenas lê e reporta) - Não cria componentes (usar component-generator) - Não executa correções automáticas (usar /descomplicar:upgrade) + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/core-tools/skills/relationship-manager/SKILL.md b/core-tools/skills/relationship-manager/SKILL.md index e92f4fc..09cb5e7 100644 --- a/core-tools/skills/relationship-manager/SKILL.md +++ b/core-tools/skills/relationship-manager/SKILL.md @@ -223,3 +223,15 @@ Relationship Manager: - Análise de impacto limitada a relacionamentos directos - Não propaga alterações automaticamente (requer confirmação) - Depende de consistência das tabelas cr_* na BD + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/auto-expense/SKILL.md b/crm-ops/skills/auto-expense/SKILL.md index 365f028..250b6ef 100644 --- a/crm-ops/skills/auto-expense/SKILL.md +++ b/crm-ops/skills/auto-expense/SKILL.md @@ -1,10 +1,10 @@ --- name: auto-expense -description: Criação automática de despesas a partir de facturas detectadas no IMAP e tickets. Extrai dados, verifica duplicados e cria despesas no Desk CRM com PDF anexo. +description: Criação automática de despesas a partir de facturas detectadas no IMAP e tickets. Extrai dados, verifica duplicados por reference_no e cria despesas no Desk CRM com PDF anexo. disable-model-invocation: true --- -# /auto-expense v1.0 +# /auto-expense v1.1 Cria despesas automaticamente a partir de facturas detectadas pelo IMAP e tickets. @@ -49,28 +49,57 @@ Para cada factura na lista: 3. EXTRAIR DO HTML: - Valor (padroes: $XX.XX, XX,XX EUR, USD XX.XX, Total: XX.XX) - - Referencia/Invoice number + - Referencia/Invoice number (OBRIGATORIO — guardar para dedup) - Data da factura - -4. VERIFICAR DUPLICADO (2 camadas): - Camada 1 - Desk CRM: - Pesquisar: mesmo fornecedor + mesmo valor (±0.05) + mesma data (±3 dias) - Se match → NAO criar, registar como duplicado - -5. CRIAR DESPESA: - mcp__desk-crm-v3__create_expense({ - category: [cat_id da tabela], - amount: [valor], - date: [data factura YYYY-MM-DD], - expense_name: "[Fornecedor] - [Referencia]", - note: "Auto-criado via /auto-expense", - currency: [2=USD ou 3=EUR], - tax: [0 ou 1], - send_invoice_to_customer: 0 - }) ``` -### Passo 3: PDF (se existir anexo) +### Passo 3: Verificar duplicados (OBRIGATORIO — 3 camadas) + +> **CRITICO: Este passo NUNCA pode ser saltado. Se saltado, causa duplicacao massiva de despesas.** + +``` +Camada 0 — Referencia de factura (PRIMARIA, mais fiavel): + get_expenses(search: "") + Para cada resultado: comparar campo reference_no + Se alguma despesa tem reference_no IGUAL → DUPLICADO CONFIRMADO + → NAO criar, registar como duplicado com ID existente + +Camada 1 — Fornecedor + Valor + Data: + get_expenses(search: "") + Filtrar: mesmo valor (±0.05) + mesma data (±3 dias) + Se match → NAO criar, registar como duplicado + +Camada 2 — Expense name pattern: + get_expenses(search: " - ") + Se match exacto no expense_name → NAO criar, registar como duplicado + +REGRA: Se QUALQUER camada detecta duplicado → PARAR imediatamente. +Nunca criar despesa sem passar as 3 camadas com sucesso. +Registar cada duplicado detectado no output JSON (campo "duplicados"). +``` + +### Passo 4: Criar despesa + +``` +APENAS se Passo 3 passou sem detectar duplicado: + + mcp__desk-crm-v3__create_expense({ + category: [cat_id da tabela], + amount: [valor], + date: [data factura YYYY-MM-DD], + expense_name: "[Fornecedor] - [Referencia]", + reference_no: "[numero factura/referencia]", + note: "Auto-criado via /auto-expense", + currency: [2=USD ou 3=EUR], + tax: [0 ou 1], + send_invoice_to_customer: 0 + }) + + OBRIGATORIO: campo reference_no DEVE ser preenchido com o numero + de factura extraido. Este campo e a chave primaria de deduplicacao. +``` + +### Passo 5: PDF (se existir anexo) ``` a. GUARDAR LOCAL: @@ -100,14 +129,14 @@ c. REGISTAR no Desk BD: d. LIMPAR temporarios ``` -### Passo 4: Actualizar CSV +### Passo 6: Actualizar CSV ``` CSV Path: /media/ealmeida/Dados/GDrive/Cloud/ADM_Descomplicar/Financeiro/Contabilidade/YYYY/MAPA-DESPESAS-YYYY.csv Formato linha: id_desk;data;categoria;fornecedor;descricao;valor;SIM;ficheiro;email;Auto /auto-expense ``` -### Passo 5: Escrever output JSON +### Passo 7: Escrever output JSON ``` Escrever em ~/.claude-work/today-expenses-{date}.json: @@ -115,12 +144,15 @@ Escrever em ~/.claude-work/today-expenses-{date}.json: "despesas_criadas": [ {"id": 1180, "fornecedor": "MEO", "valor": 76.26, "moeda": "EUR", "referencia": "FT A/861215955"} ], - "duplicados": 0, + "duplicados": [ + {"fornecedor": "MEO", "referencia": "FT A/861215955", "existente_id": 1175, "camada": 0} + ], "flagged": [ {"fornecedor": "Desconhecido", "nota": "TOConline - emitente desconhecido: XPTO LDA"} ], "erros": [], - "total_processadas": 1 + "total_processadas": 1, + "total_duplicados": 0 } ``` @@ -152,7 +184,7 @@ tax = 0 → Fornecedores estrangeiros send_invoice_to_customer = 0 → OBRIGATORIO (sem default na BD) -reference_no → coluna correcta (NAO "reference") +reference_no → coluna correcta (NAO "reference") — CHAVE DE DEDUPLICACAO ``` --- @@ -167,7 +199,8 @@ reference_no → coluna correcta (NAO "reference") |--------|-----------|-------|-------|-----|-----| ### Duplicados Detectados (Y) -- [Fornecedor] [Valor] - ja existe como #ID +| Fornecedor | Ref | ID Existente | Camada | +|-----------|-----|-------------|--------| ### Pendentes Revisao (Z) - [Plataforma] - emitente desconhecido: [nome] @@ -179,11 +212,26 @@ reference_no → coluna correcta (NAO "reference") - NUNCA usar currency=1 (nao existe) - NUNCA converter USD para EUR (manter original com currency=2) -- NUNCA criar despesa sem verificar duplicado primeiro +- NUNCA criar despesa sem verificar duplicado primeiro (3 camadas obrigatorias) - NUNCA omitir send_invoice_to_customer=0 +- NUNCA omitir reference_no ao criar despesa (chave primaria de dedup) +- NUNCA saltar a Camada 0 (referencia de factura) — e a mais fiavel - SEMPRE ler o email/ticket HTML para extrair valor real (nunca assumir) - SEMPRE incluir reference_no quando disponivel +- SEMPRE logar duplicados detectados no output JSON com camada e ID existente --- -*Skill v1.0.0 | 04-03-2026 | Descomplicar®* +*Skill v1.1.0 | 30-03-2026 | Descomplicar | Fix: dedup por reference_no (DES-137)* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/billing-check/SKILL.md b/crm-ops/skills/billing-check/SKILL.md index c3a6ab6..a51704e 100644 --- a/crm-ops/skills/billing-check/SKILL.md +++ b/crm-ops/skills/billing-check/SKILL.md @@ -293,3 +293,15 @@ Skill: 3. Executar workflow integrado Output: [resultado completo com referências] ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/crm-admin/SKILL.md b/crm-ops/skills/crm-admin/SKILL.md index a827a59..3d41a68 100644 --- a/crm-ops/skills/crm-admin/SKILL.md +++ b/crm-ops/skills/crm-admin/SKILL.md @@ -223,3 +223,15 @@ Skill: 3. Executar workflow integrado Output: [resultado completo com referências] ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/crm-ops/SKILL.md b/crm-ops/skills/crm-ops/SKILL.md index e026d64..95f2d76 100644 --- a/crm-ops/skills/crm-ops/SKILL.md +++ b/crm-ops/skills/crm-ops/SKILL.md @@ -430,3 +430,15 @@ User: Criar orçamento para lead João Silva **Criado:** 2026-01-28 **Actualizado:** 2026-01-28 **Motivo:** Prevenção de erros CRM após incidente de duplicação + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/crm/SKILL.md b/crm-ops/skills/crm/SKILL.md index 5241da0..1d90544 100644 --- a/crm-ops/skills/crm/SKILL.md +++ b/crm-ops/skills/crm/SKILL.md @@ -306,6 +306,24 @@ Skills descontinuadas: - Distinção Lead vs Customer - Proposal vs Estimate + + +--- + +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/crm.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + --- *Skill v2.0.0 | 2026-02-05 | Descomplicar®* + + +## Healing Log + diff --git a/crm-ops/skills/desk/SKILL.md b/crm-ops/skills/desk/SKILL.md index 8374816..6010ef0 100644 --- a/crm-ops/skills/desk/SKILL.md +++ b/crm-ops/skills/desk/SKILL.md @@ -235,6 +235,24 @@ Ao entrar numa pasta: ### v1.0.0 - Versão inicial + + +--- + +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/desk.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + --- *Skill v3.0.0 | 2026-02-05 | Descomplicar®* + + +## Healing Log + diff --git a/crm-ops/skills/estrategia-marca/SKILL.md b/crm-ops/skills/estrategia-marca/SKILL.md new file mode 100644 index 0000000..9785038 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/SKILL.md @@ -0,0 +1,174 @@ +--- +name: estrategia-marca +description: Cria estratégias de marca completas seguindo a metodologia Descomplicar® (ACIDA + Framework 16Ps). Inclui fase de pesquisa de mercado com /deep-research antes do briefing. Guia a análise de público, posicionamento, Pitch Canvas, copywriting e documento final entregável. Usar quando o utilizador diz "estratégia de marca", "branding", "criar marca", "posicionamento", "16Ps", "/estrategia-marca", "análise de público", "narrativa de marca", "proposta de valor", "pitch canvas", "pain + gain", "copywriting estratégico", "identidade de marca", "pesquisa de mercado para marca", ou quando um cliente adquire o serviço EST-MRK-010. +--- + +# Skill: Estratégia de Marca + +Guia completo para criar estratégias de marca Descomplicar® — da pesquisa de mercado ao documento final entregável. + +--- + +## Fluxo de trabalho (8 fases) + +### Fase 0 — Pesquisa de mercado + +Antes do briefing com o cliente, fazer pesquisa independente. Verificar primeiro se já existem ficheiros de pesquisa (ex: pasta `Pesquisas/` no projecto). + +**Se a pesquisa já existe:** ler os ficheiros relevantes e extrair síntese. + +**Se não existe:** usar `/deep-research` (ou `mcp__tavily__tavily_research`) com os seguintes focos: + +1. **Mercado/sector** — dimensão, crescimento, tendências, regulação +2. **Concorrentes** — posicionamento, mensagens, pricing, pontos fracos +3. **Público** — linguagem online, canais activos, dores expressas em fóruns/reviews +4. **Oportunidades** — gaps de mercado, tendências emergentes não exploradas + +Guardar síntese em `Pesquisas/sintese-mercado.md` no projecto do cliente. + +**Resultado esperado:** chegar ao briefing já com hipóteses validadas sobre o mercado e o público — não para impor, mas para fazer perguntas mais certeiras e poupar tempo ao cliente. + +### Fase 1 — Activação e contexto + +Ao iniciar, perguntar: +- Qual o nome do cliente/marca? +- Já existe briefing ou material de partida? +- Qual o sector/indústria? +- Temos exemplos de concorrentes? + +Se existir projecto no Desk CRM, verificar com `get_project` antes de prosseguir. + +### Fase 2 — Briefing estruturado + +Conduzir entrevista com as perguntas de `references/perguntas-briefing.md`. + +Organizar por blocos: +1. Negócio (problema, serviços, mercado) +2. Público-alvo (segmentos identificados) +3. Posicionamento actual vs desejado +4. Tom de voz e personalidade +5. Concorrência e diferenciação + +### Fase 3 — Fundamentos estratégicos + +Desenvolver com o cliente: +- **Proposta de valor única** — o que nos torna únicos, diferenciais, benefícios por camada +- **Missão, Visão, Valores e Objectivos** — com exemplos de como se manifestam na prática +- **Apresentação sumária** — empresa + serviços com tabela clara +- **Posicionamento** — declaração de posicionamento testável + +Ver `references/framework-16ps.md` → Bloco A para questões orientadoras. + +### Fase 4 — Análise de público (20 pontos por segmento) + +**Obrigatório:** Antes dos segmentos psicográficos, identificar os nichos sectoriais relevantes para o produto. Usar `references/nichos.md` para seleccionar e analisar **pelo menos 5 nichos específicos** (ex: clínicas de saúde, imobiliárias, agências digitais — não "PMEs" como categoria vaga). Para cada nicho preencher os 8 pontos do guia de análise sectorial. Cruzar com os 20 pontos psicográficos abaixo para construir personas completas. + +Para cada segmento identificado, desenvolver os 20 pontos na seguinte ordem: + +1. Perfil Demográfico +2. Perfil Psicográfico +3. Dores +4. Anseios +5. Desejos +6. Frustrações +7. Preocupações +8. Medos +9. Inimigos +10. Linguagem +11. Como procuram ajuda/informação/dicas +12. Canais digitais activos +13. Estilo de Decisão +14. Mudanças (que sabem necessárias) +15. Resistência à mudança +16. Objecções típicas (+ como ultrapassar) +17. Forma de gerar emoção +18. Argumentos (a que são mais sensíveis) +19. Concorrentes (que alternativas avaliam) +20. Propostas Recusadas (e porquê) + +Ver `references/metodologia-acida.md` para contexto e profundidade em cada ponto. + +### Fase 5 — Pitch Canvas + +Estrutura de 5 elementos: +- **Para quem:** segmento + problema específico +- **O problema:** dor principal na linguagem do cliente +- **A solução:** mecanismo único de resolução +- **O resultado:** transformação concreta (antes/depois + métrica) +- **Por que nós:** razão para acreditar + +Criar também a **Declaração de mudança no mundo** — frase que resume o impacto maior da marca. + +### Fase 6 — Copywriting estratégico + +Sequência obrigatória: + +1. **Questionamento estratégico** — Qual é o objectivo da comunicação? Que transformação prometemos? +2. **Pain + Gain** — formulação problema/resultado na linguagem do cliente; depois refinar com especificidades do sector +3. **Narrativa por segmento** — fórmula: Problema (dor do público) → Solução (serviços) → Resultado (benefícios concretos) +4. **Mensagem central** — 1 frase que toda a equipa sabe de cor +5. **Headlines** — por segmento (principal + secundária) + +Ver `references/narrativas-copywriting.md` para templates e exemplos reais. + +### Fase 7 — Documento final + Investimentos + +Completar as secções finais: +- **Demonstração dos serviços** — como demonstrar, preparação, follow-up +- **Investimentos prioritários** — canais, orçamento, ROI esperado +- **KPIs** — baseline + metas a 3m, 6m, 12m +- **Inventário de activos** — o que existe, estado, prioridade + +Ver `references/template-documento.md` para a estrutura completa do documento. + +**Checklist de entrega:** +- [ ] Pesquisa de mercado feita (Fase 0) +- [ ] Proposta de valor única definida +- [ ] Missão, Visão, Valores escritos +- [ ] Apresentação sumária da empresa e serviços +- [ ] Mínimo 5 nichos sectoriais analisados (8 pontos cada) — ver `references/nichos.md` +- [ ] Mínimo 2 segmentos psicográficos com 20 pontos completos +- [ ] Pitch Canvas preenchido +- [ ] Declaração de mudança no mundo +- [ ] Pain + Gain (original + refinado) +- [ ] Narrativa por segmento (Problema → Solução → Resultado) +- [ ] Mensagem central definida +- [ ] Investimentos prioritários identificados +- [ ] KPIs definidos com metas + +--- + +## Referências (carregar conforme necessário) + +| Ficheiro | Quando carregar | +|----------|----------------| +| `references/metodologia-acida.md` | Fases 3-4: ACIDA, 20 pontos por segmento | +| `references/framework-16ps.md` | Fase 3: fundamentos estratégicos (Bloco A) | +| `references/perguntas-briefing.md` | Fase 2: conduzir entrevista cliente | +| `references/narrativas-copywriting.md` | Fase 6: copywriting, Pain+Gain, narrativas | +| `references/template-documento.md` | Fase 7: estrutura completa do documento | +| `references/nichos.md` | Fase 4: análise sectorial dos 10 nichos PT/EU (mínimo 5 obrigatórios) | + +--- + +## Contexto do serviço + +- **Código:** EST-MRK-010 +- **Preço:** 900 EUR +- **Prazo médio:** 30h de trabalho +- **Entregáveis:** Documento estratégico completo, dashboard personas, narrativa de marca, apresentação executiva editável, guia de implementação, sessão de alinhamento com equipa +- **Suporte pós-entrega:** WhatsApp 1 mês + +Complementar com Branding WOW (BRAND-ESS/DIG/COM: 1.800–4.500 EUR) se o cliente precisar de identidade visual. + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/estrategia-marca/references/framework-16ps.md b/crm-ops/skills/estrategia-marca/references/framework-16ps.md new file mode 100644 index 0000000..85d49db --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/framework-16ps.md @@ -0,0 +1,193 @@ +# Framework 16Ps — Referência Completa + +Estrutura os 16 elementos da estratégia de marca em 4 blocos. Para cada P, incluir as questões orientadoras ao preencher. + +--- + +## Bloco A — Fundamentos estratégicos + +### P1: Problema +> Qual o problema principal que a marca resolve? + +- Problema de negócio que a estratégia precisa resolver +- Impacto desse problema no cliente (custo, tempo, risco, reputação) +- Urgência da solução: por que resolver agora? +- Consequências de não resolver + +*Exemplo SFV:* "Facturas de electricidade crescentes que consomem margens das empresas e rendimento das famílias, sem solução acessível percebida." + +### P2: Propósito +> Por que existe esta marca além do lucro? + +- **Missão:** o que fazemos e para quem (hoje) +- **Visão:** onde queremos chegar (3-5 anos) +- **Valores:** 3-5 valores fundamentais com descrição de como se manifestam +- **Propósito:** impacto no mundo que justifica a existência da marca + +*Estrutura valores:* [Nome do Valor] — [Como se manifesta na prática] + +### P3: Proposta de Valor +> O que tornamos possível que os concorrentes não conseguem? + +- Valor único que só esta marca entrega +- Diferenciais competitivos (lista) +- Benefícios principais (funcionais + emocionais) +- Formula: Para [segmento], que [dor/desejo], a [marca] oferece [solução] que [resultado único], ao contrário de [alternativa], porque [razão para acreditar] + +### P4: Posicionamento +> Que lugar específico ocupa na mente do cliente? + +- Posição actual no mercado (percepção real) +- Posição desejada (percepção target) +- Declaração de posicionamento (1-2 frases) +- Território da marca: categoria, concorrência directa, diferenciação +- Atributos únicos que definem esse território + +*Declaração-tipo:* "Para [público], somos a única [categoria] que [benefício único] porque [prova]." + +### P5: Performance +> Como medimos o sucesso? + +- KPIs principais (5-7 métricas) +- Metas específicas a 3, 6 e 12 meses +- Indicadores de sucesso por área (brand awareness, conversão, satisfação) +- Frequência de monitorização e responsável + +--- + +## Bloco B — Público e pesquisa + +### P6: Público-alvo +> Quem são exactamente os nossos clientes? + +- Segmento principal + segmentos secundários +- Critérios de segmentação (demográficos, comportamentais, psicográficos) +- Volume estimado de cada segmento +- Comportamento de compra: frequência, ticket médio, canal preferido + +### P7: Pesquisa de mercado +> Que dados sustentam as nossas decisões? + +- Dados de mercado: dimensão, crescimento, tendências +- Insights de comportamento do consumidor +- Oportunidades identificadas (não aproveitadas pela concorrência) +- Ameaças e riscos do mercado + +### P8: Personas +> Quem é o nosso cliente ideal em detalhe? + +Para cada persona: +- **Foto + nome fictício + idade + profissão** +- **Biografia resumida** (um dia típico) +- **Dores principais** (3-5) +- **Objectivos** (profissionais + pessoais) +- **Canais preferidos** (onde está, o que consome) +- **Citação representativa** ("Eu quero/preciso/temo...") +- **Frase de posicionamento** para esta persona + +### P9: Perfil +> Quais as características quantificáveis de cada segmento? + +Análise de 20 pontos por segmento (ver template completo em `template-documento.md`): +- Demográfico: idade, género, localização, rendimento, educação, sector, cargo, empresa +- Comportamental: rotina, hábitos, processo de decisão, critérios de escolha +- Psicográfico: valores, aspirações, mentalidade, atitude à inovação +- Jornada: awareness, consideração, decisão + +### P10: Pain Points +> Quais as dores mais urgentes e dolorosas? + +- Dores principais (urgentes, que precisam resolver já) +- Frustrações (já tentaram outras soluções sem resultado) +- Necessidades não atendidas (o mercado não resolve bem) +- Medos relacionados com a compra ou com não comprar + +--- + +## Bloco C — Produto e serviço + +### P11: Portfolio +> O que vendemos exactamente? + +- Lista de produtos/serviços principais +- Características técnicas vs benefícios percebidos +- Arquitectura de oferta: entrada, core, premium +- Casos de uso reais (exemplos concretos de aplicação) + +### P12: Preço e valor +> Como justificamos o que cobramos? + +- Estratégia de preços (custo+margem, valor percebido, concorrência, freemium) +- Posicionamento de valor: acessível, médio-alto, premium, luxo +- Política comercial: descontos, bundles, condições de pagamento +- ROI estimado para o cliente (quanto ganha/poupa ao escolher-nos) + +### P13: Processos críticos +> Que processos garantem a experiência prometida? + +- Processo de entrega do serviço/produto (passo a passo) +- Pontos de controlo de qualidade +- Garantias e políticas de satisfação +- Gestão de reclamações + +### P14: Parcerias estratégicas +> Com quem nos aliamos para ampliar valor? + +- Parceiros principais (nome, tipo, contribuição) +- Tipos de parceria: distribuição, tecnologia, referência, co-marketing +- Benefícios mútuos de cada parceria +- Parcerias a desenvolver (gap de oportunidade) + +### P15: Plataforma +> Onde operamos digitalmente? + +- Canais digitais activos: website, redes sociais, marketplaces, apps +- Presença online actual vs ideal +- Infraestrutura tecnológica (CRM, email, analytics, automação) +- Prioridades de investimento digital + +--- + +## Bloco D — Promoção e comunicação + +### P16: Promoção +> Como chegamos ao público-alvo? + +- Canais principais com objectivos específicos por canal +- Tácticas específicas (conteúdo, SEO, email, WhatsApp, eventos) +- Calendário promocional (frequência, momentos-chave) +- Budget orientativo por canal + +### P17: Publicidade +> Como amplificamos com investimento pago? + +- Estratégia de anúncios: plataformas, formato, objectivo +- Budget mensal e distribuição +- KPIs de publicidade (CPL, ROAS, CPA) +- Frequência e ciclo de renovação de criativos + +### P18: PR e referências +> Como construímos credibilidade externa? + +- Estratégia de relações públicas +- Parcerias com influenciadores (relevância > alcance) +- Imprensa e media especializada +- Programa de referências/embaixadores + +### P19: Presença digital +> Qual a nossa estratégia de conteúdo? + +- Estratégia de conteúdo por canal +- Frequência de publicação +- Pilares de conteúdo (3-5 temas centrais) +- Gestão de comunidade: resposta, engagement, moderação + +### P20: Proximidade — narrativa e impacto +> Que história contamos que ressoa emocionalmente? + +- **Declaração de Impacto:** frase que resume a essência e impacto da marca +- **Narrativa principal:** história de origem ou transformação +- **Pain + Gain por segmento:** o que perdiam antes → o que ganham agora +- **Mensagem central:** 1 frase que todos os colaboradores sabem de cor + +*Nota: O "Bloco D" tem 5 Ps numerados de 16 a 20 — alguns documentos listam apenas 16 Ps no total (agrupando Promoção, Publicidade e PR num único P). Adaptar conforme o nível de detalhe necessário.* diff --git a/crm-ops/skills/estrategia-marca/references/metodologia-acida.md b/crm-ops/skills/estrategia-marca/references/metodologia-acida.md new file mode 100644 index 0000000..b0e60b4 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/metodologia-acida.md @@ -0,0 +1,127 @@ +# Metodologia ACIDA — Referência Completa + +## 1. As 5 fases ACIDA + +### A — Atrair atenção + +O público está sobrecarregado de informação. A forma correcta de chamar a atenção não é destacar produtos — é conectar com o que emocionalmente mais interessa ao público: **as suas próprias dores e desejos**. + +Acções práticas: +- Headlines que falam directamente da dor ou desejo do segmento +- Conteúdo que provoca reconhecimento imediato ("é exactamente o meu problema") +- Formatos visuais que param o scroll: vídeo curto, imagem disruptiva, estatística chocante + +### C — Construir confiança + +Após conquistar atenção, estabelecer relacionamentos autênticos através de: +- Transparência, honestidade e autenticidade na comunicação +- Demonstrar compreensão profunda das dores e desejos do cliente +- Partilhar conhecimento e experiência profissional abertamente +- Educar o público para decisões mais informadas +- Estabelecer autoridade que permite influenciar percepções + +Formatos: artigos de blog, estudos de caso, testemunhos, webinars, guias gratuitos. + +### I — Despertar interesse + +Com confiança estabelecida, a comunicação torna-se altamente personalizada. +> "Não vendemos produtos nem serviços; oferecemos soluções específicas para os seus desafios." + +Ferramentas: +- Rastreamento de interacções para identificar segmentos de clientes +- Conteúdo customizado baseado em comportamentos anteriores +- Resolução antecipada de objecções conhecidas +- Nutrição de relacionamentos via email, WhatsApp, SMS, redes sociais + +### D — Estimular a decisão + +A decisão será favorável se o **valor percebido > preço a pagar**. + +Obstáculos a superar: +- O "muro invisível" criado por dúvidas do consumidor +- Medo do arrependimento pós-compra +- Necessidade de prova social e garantias sólidas + +Ferramentas: comparações, garantias, testemunhos de clientes reais, demonstrações, ROI calculado. + +### A — Incentivar a acção + +Converter interesse em acção através de: +- Chamadas à acção (CTA) claras e convincentes +- Criação de sentido de urgência (real, não artificial) +- Cumprimento de promessas +- Superação de expectativas na experiência do cliente + +--- + +## 2. Análise do público-alvo — 8 dimensões + +Para cada segmento, investigar as 8 dimensões antes de escrever qualquer copy: + +### Dimensão 1: Perfil demográfico e psicográfico +- Características mensuráveis: idade, género, localização, rendimento, educação, cargo +- Traços de personalidade: valores, crenças, atitudes, estilo de vida +- *Pergunta-chave: "Quem é esta pessoa na vida real?"* + +### Dimensão 2: Dores, desejos e frustrações +- Dores activas: problemas que precisam resolver agora +- Desejos: o que querem alcançar/ter/ser +- Frustrações: o que já tentaram e não funcionou +- *Pergunta-chave: "O que os mantém acordados à noite? O que sonham?"* + +### Dimensão 3: Preocupações e geração de emoção +- O que os preocupa a médio/longo prazo +- Como a nossa marca pode responder emocionalmente (não apenas racionalmente) +- *Pergunta-chave: "Que emoção queremos que sintam quando nos encontram?"* + +### Dimensão 4: Medos, inimigos e mudanças +- Medos concretos (perder negócio, ser enganado, falhar) +- "Inimigos" percebidos (concorrentes, reguladores, tendências de mercado) +- Mudanças que temem ou resistem +- *Pergunta-chave: "O que os impede de agir?"* + +### Dimensão 5: Anseios, interesses e linguagem +- O que aspiram a ser/ter/fazer +- Interesses e hobbies (pistas para onde comunicar) +- Linguagem que usam (jargão do sector, palavras que ressoam vs que afastam) +- *Pergunta-chave: "Como falam entre si? Que palavras usam?"* + +### Dimensão 6: Pesquisa de informação e influenciadores +- Onde procuram informação (Google, YouTube, LinkedIn, feiras, colegas) +- A quem pedem conselho (influenciadores, peers, família) +- Fontes que consideram credíveis +- *Pergunta-chave: "Como encontraram a nossa categoria de produto/serviço?"* + +### Dimensão 7: Dúvidas e perguntas +- Objecções previsíveis antes da compra +- Perguntas que fazem nas reuniões de vendas +- Informação que precisam para decidir +- *Pergunta-chave: "Quais as 5 objecções mais frequentes?"* + +### Dimensão 8: Estilo de decisão e concorrentes +- Processo de decisão: individual vs colectivo, rápido vs lento +- Factores comparativos: preço, qualidade, confiança, referências +- Concorrentes directos que avaliam em paralelo +- *Pergunta-chave: "Com quem nos comparam? Por que nos escolhem ou não?"* + +--- + +## 3. Pilares estratégicos ACIDA + +- **Crença central:** o centro do marketing digital são os princípios fundamentais de marketing + website — não as redes sociais +- **Proposta de valor:** "Criamos Resultados" — problema → solução → resultados esperados +- **Website como hub central:** não repositório, mas centro operacional integrado com CRM +- **Ecossistema multi-canal:** email, SMS/WhatsApp, SEO, Google/Meta Ads, website, redes sociais (como parte, não como centro) +- **Melhoria contínua:** métricas objectivas → ciclo iterativo baseado em dados + +--- + +## 4. ACIDA 2.0 — Fases operacionais + +| Fase | Acções | +|------|--------| +| **1. Análise** | Segmentação público, posicionamento, estruturação oferta, montagem narrativa | +| **2. Criação** | Recursos, copywriting e design, website e plataformas, automação | +| **3. Implementação** | Conteúdos e canais, blog e email marketing, redes sociais, marketplaces | +| **4. Desenvolvimento** | Funil de vendas, tráfego e anúncios, conteúdos, newsletters | +| **5. Acompanhamento** | Gestão de resultados, métricas e KPIs, optimização contínua, suporte | diff --git a/crm-ops/skills/estrategia-marca/references/narrativas-copywriting.md b/crm-ops/skills/estrategia-marca/references/narrativas-copywriting.md new file mode 100644 index 0000000..2d0f3d2 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/narrativas-copywriting.md @@ -0,0 +1,154 @@ +# Narrativas e Copywriting Estratégico + +Templates e exemplos reais de narrativas Descomplicar®. Baseados nos projectos SFV, LJM, MCT e Espiral Senior. + +--- + +## 1. Fórmula central: Dor → Solução → Resultado + +Estrutura base para qualquer narrativa por segmento: + +``` +DOR: [Nome do segmento] enfrenta [problema específico e urgente]. + Sem solução, [consequência negativa concreta]. + +SOLUÇÃO: [Nome da marca] resolve isto através de [mecanismo único]. + [Diferencial que os concorrentes não têm]. + +RESULTADO: O resultado é [benefício tangível e mensurável]. + [Prova social ou garantia que aumenta credibilidade]. +``` + +**Exemplo SFV (segmento Empresas):** +> Dor: As PMEs enfrentam facturas de electricidade crescentes que consomem margens já apertadas. +> Solução: A SFV instala painéis solares personalizados com análise de consumo prévia — sem adiantamento para projectos qualificados. +> Resultado: Redução de 60-90% na factura eléctrica, com ROI em 4-7 anos e garantia de 25 anos nos painéis. + +**Exemplo MCT (segmento Oficinas):** +> Dor: Mecânicos perdem tempo e dinheiro com ferramentas que chegam erradas, incompletas ou que avariam em obra. +> Solução: A Carritools fornece equipamento profissional com assessoria técnica presencial e substituição imediata em caso de avaria. +> Resultado: Menos tempo parado, mais trabalhos concluídos, clientes mais satisfeitos. + +--- + +## 2. Declaração de Impacto + +Uma frase poderosa que abre o documento e resume a essência da marca. Deve: +- Ser memorável (10-15 palavras máximo) +- Combinar emoção + resultado +- Não ser genérica ("líderes de mercado", "qualidade e inovação") + +**Exemplos reais:** + +| Cliente | Declaração de Impacto | +|---------|----------------------| +| SFV Solar | "Energia (quase) Grátis para Famílias e Empresas" | +| Espiral Senior | "Envelhecer em Dignidade, no Lugar que Mais Ama" | +| Descomplicar® | "Criamos Resultados!" | + +**Fórmulas para gerar Declaração de Impacto:** +- `[Verbo de transformação] + [benefício desejado] + [para quem]` +- `[Adjectivo emocional] + [resultado concreto]` +- `[Benefício surpreendente] + [para quem] + [sem o custo habitual]` + +--- + +## 3. Mensagens-chave por tipo de segmento + +### Segmento decisor (CEO/Gerente) +Foco: ROI, risco reduzido, credibilidade, tempo poupado. + +Template: +> "Mais de [N] empresas como a sua já [resultado]. A nossa abordagem garante [benefício financeiro] em [prazo], com [garantia específica]." + +### Segmento utilizador final (técnico/operacional) +Foco: facilidade de uso, suporte, fiabilidade, não criar problemas. + +Template: +> "Simples de implementar, sem interrupções ao seu trabalho. Em caso de dúvida, temos suporte [detalhe] para que nunca fique bloqueado." + +### Segmento referenciador (parceiro/consultor) +Foco: credibilidade para recomendar, win-win, diferenciação para os seus clientes. + +Template: +> "Ao recomendar [marca], está a oferecer aos seus clientes [resultado], o que reforça a sua autoridade como [cargo/papel]." + +### Segmento influenciador (família/comunidade) +Foco: valores partilhados, impacto positivo, pertença. + +Template: +> "Não é só [produto/serviço]. É uma escolha que [impacto maior]: [dimensão ambiental/social/familiar]." + +--- + +## 4. Gestão de objecções — estrutura padrão + +Para cada objecção, responder sempre com: +1. **Validar** — reconhecer que é uma preocupação legítima +2. **Reframeamento** — mudar o ângulo de análise +3. **Prova** — exemplo, dado ou testemunho que confirma +4. **CTA suave** — próximo passo de baixo compromisso + +**Objecções universais e respostas tipo:** + +| Objecção | Resposta base | +|----------|--------------| +| "É caro" | "Entendo a preocupação. O nosso preço reflecte [diferencial]. Clientes como [X] recuperaram o investimento em [prazo]. Posso mostrar-lhe o cálculo?" | +| "Preciso de pensar" | "Faz todo o sentido. O que precisa de esclarecer para se sentir confiante? Posso enviar [recurso específico] que costuma ajudar nesta fase." | +| "Já tentei algo parecido e não funcionou" | "Compreendo — essa experiência é frustrante. O que tipicamente falha é [causa]. A nossa abordagem resolve isto de forma diferente: [diferencial]." | +| "Não tenho tempo agora" | "Respeitamos o seu tempo. É por isso que o nosso processo começa com apenas [X horas], e tratamos nós de [trabalho pesado]." | +| "Preciso de aprovação interna" | "Claro. Posso preparar um resumo executivo de 1 página para facilitar a aprovação? Tenho feito isto para outros clientes com muito bom resultado." | + +--- + +## 5. Tom de voz por personalidade de marca + +### Marca especialista/técnica (ex: SFV, Carritools) +- Linguagem precisa, dados concretos, terminologia do sector +- Evitar: exageros sem prova, linguagem emocional excessiva +- Usar: casos reais, números, especificações, garantias técnicas + +### Marca próxima/humana (ex: Espiral Senior, Loja da Maria) +- Linguagem calorosa, inclusiva, em 2ª pessoa +- Evitar: jargão técnico, distância corporativa +- Usar: histórias pessoais, empatia directa, linguagem do dia-a-dia + +### Marca inovadora/disruptiva (ex: Descomplicar, SaaS) +- Linguagem energética, directa, com algum desafio ao status quo +- Evitar: clichés do sector, promessas vazias +- Usar: contraste antes/depois, resultados surpreendentes, "E se..." + +--- + +## 6. Estrutura de testemunho ideal + +Baseado nos testemunhos reais recolhidos nos projectos: + +``` +[Nome próprio + cargo + empresa] — [cidade, se relevante] +"[Frase de impacto espontânea que resume o resultado]" + +Contexto: [Situação antes de contratar] +Resultado: [Mudança concreta e mensurável após] +Recomendação: [Indicação explícita para outros como ele] +``` + +**Exemplo real SFV:** +> "Ricardo Castelão, Director Financeiro, Empresa de Distribuição — Porto +> 'Reduzimos a nossa factura eléctrica em 73% no primeiro ano.' +> Contexto: Gastávamos 4.200 EUR/mês em electricidade, sem alternativa viável. +> Resultado: Passámos para 1.134 EUR/mês. O sistema pagou-se em 5,5 anos. +> Recomendação: Para qualquer empresa com consumo acima de 1.500 EUR/mês, é obrigatório analisar esta opção." + +--- + +## 7. Headlines de alto impacto — padrões + +Padrões que funcionam consistentemente nos projectos Descomplicar: + +- **Resultado específico:** "Reduza a sua factura eléctrica em 70% sem investimento inicial" +- **Pergunta dor:** "Ainda a pagar [problema] quando existe solução comprovada?" +- **Autoridade + resultado:** "Como [N] empresas [resultado] com [solução]" +- **Contrafactual:** "E se a sua maior despesa se transformasse no seu maior activo?" +- **Urgência real:** "A [mudança de mercado/regulação] está a mudar tudo — [posição da marca]" +- **Social proof:** "Mais de [N] clientes em [região] já [resultado]" diff --git a/crm-ops/skills/estrategia-marca/references/nichos.md b/crm-ops/skills/estrategia-marca/references/nichos.md new file mode 100644 index 0000000..fcfb35b --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/nichos.md @@ -0,0 +1,318 @@ +# Análise de Nichos — Guia de Segmentação Sectorial + +Para marcas com público PME, "PME" é demasiado vasto. Identificar os nichos sectoriais específicos permite mensagens certeiras, canais certos e ROI superior. Qualquer estratégia de marca deve analisar **pelo menos 5 nichos específicos** relevantes para o produto/serviço. + +--- + +## Como usar este guia + +1. Identificar os nichos onde o produto/serviço tem tracção real ou potencial +2. Para cada nicho seleccionado, preencher os 8 pontos de análise sectorial +3. Cruzar com os 20 pontos da análise de público (template-documento.md § 5) para o perfil completo +4. Priorizar os 3 nichos de maior potencial para messaging principal + +--- + +## Os 8 pontos de análise por nicho + +Para cada nicho, responder: + +1. **Dimensão e contexto** — quantas empresas em PT/EU, crescimento do sector, maturidade digital +2. **Dores operacionais específicas** — o que os cansa no dia-a-dia (não genérico: específico do sector) +3. **Funcionalidades mais relevantes** — o que do produto resolve melhor o problema deste nicho +4. **Linguagem de venda** — palavras que usam, palavras que evitam, jargão do sector +5. **Canal de aquisição principal** — onde estão, como chegam ao produto +6. **Objecção principal** — o bloqueio mais frequente e como ultrapassar +7. **Trigger de compra** — o momento/evento que precipita a decisão +8. **Pricing sweet spot** — o que pagam por ferramentas similares, sensibilidade ao preço + +--- + +## Os 10 nichos de PME mais relevantes (PT/EU) + +### Nicho 1 — Saúde Privada + +**Quem:** Clínicas dentárias, psicólogos, nutricionistas, fisioterapeutas, clínicas médicas privadas, terapeutas. + +**Dimensão PT:** +12.000 clínicas e consultórios privados. Sector em crescimento pós-pandemia. Alta concentração em Lisboa, Porto e litoral. + +**Dores operacionais:** +- Agenda manual ou em sistemas desactualizados (Doctoralia, papel) +- Falhas de consulta (no-shows) sem sistema de lembretes automatizado +- Secretaria sobrecarregada com marcações e confirmações por telefone +- Facturação em saúde com complexidade fiscal (isenção IVA, recibos verdes) +- RGPD em saúde: dados sensíveis com requisitos legais estritos + +**Funcionalidades mais relevantes:** lembretes automáticos de consulta por WhatsApp/SMS, confirmação/cancelamento por WhatsApp, reagendamento automático, facturação PT com isenção IVA, base de conhecimento para FAQ de pacientes. + +**Linguagem de venda:** "reduzir faltas à consulta", "libertar a secretária para o que importa", "pacientes confirmam pelo WhatsApp", "agenda sempre actualizada". Evitar: "automação", "IA", "bot". + +**Canal de aquisição:** associações profissionais (OMD, Ordem dos Psicólogos), LinkedIn de gestores de clínica, referência entre profissionais de saúde, Google Ads ("software gestão clínica", "agenda online clínica"). + +**Objecção principal:** "Os meus pacientes são mais velhos e não usam WhatsApp." → Resposta: "O sistema funciona igualmente por SMS. E os cuidadores/filhos que marcam as consultas estão todos no WhatsApp." + +**Trigger de compra:** crescimento de lista de espera que a secretária já não consegue gerir; terceira consulta cancelada sem aviso no mesmo mês. + +**Pricing sweet spot:** €50-150/mês (referência: Doctoralia €80-200/mês). + +--- + +### Nicho 2 — Imobiliárias e Mediação + +**Quem:** Agências imobiliárias independentes, mediadores certificados (AMI), promotores imobiliários, gestoras de condomínios. + +**Dimensão PT:** +5.000 agências com licença AMI activas. Mercado em alta, mas muito fragmentado. Alta dependência de WhatsApp para comunicação com compradores/vendedores. + +**Dores operacionais:** +- Leads entram por portais (Imovirtual, Idealista, OLX) e ficam sem resposta rápida +- Gestão de visitas manual: telefonemas para confirmar, reagendar, cancelar +- Follow-up de compradores perdido no WhatsApp pessoal do agente +- Quando o agente sai, leva os contactos consigo +- Proposta/minuta demoram dias + +**Funcionalidades mais relevantes:** resposta automática a leads de portais, qualificação de leads por WhatsApp, agendamento de visitas com confirmação automática, CRM com histórico centralizado (não no telemóvel do agente), geração de propostas. + +**Linguagem de venda:** "nunca perde um lead do Idealista", "as visitas confirmam-se sozinhas", "quando o agente sai, o cliente fica na empresa", "responde ao lead em 2 minutos, a qualquer hora". + +**Canal de aquisição:** associações (APEMIP, ASIP), LinkedIn de directores de agência, eventos do sector imobiliário, Google Ads ("CRM imobiliário Portugal", "software mediação imobiliária"). + +**Objecção principal:** "Já usamos o CRM do Idealista." → Resposta: "O CRM do portal gere os leads do portal. O AcidaOS centraliza todos os portais + WhatsApp + email num só sítio, com o histórico completo de cada cliente." + +**Trigger de compra:** perda de uma venda grande por demora na resposta ao lead; saída de um agente que levou a carteira de clientes. + +**Pricing sweet spot:** €80-200/mês (referência: Salesforce RE €150-300/mês, CRMs sectoriais €50-150/mês). + +--- + +### Nicho 3 — Construção e Remodelação + +**Quem:** Empreiteiros de construção civil, empresas de remodelação e acabamentos, serralheiros, carpinteiros, canalizadores com equipa, empresas de pintura. + +**Dimensão PT:** sector fortíssimo — construção representa ~7% do PIB PT. Altamente fragmentado, maioria micro-empresas 1-20 pessoas. Baixa digitalização. Alta dependência de telefonema e referência. + +**Dores operacionais:** +- Orçamentos demoram dias ou semanas a chegar ao cliente +- Clientes ligam 5 vezes para saber se o orçamento chegou +- Gestão de obras espalhada por papel, WhatsApp e memória do encarregado +- Facturação atrasada em relação ao trabalho realizado (meses de delay) +- Cobranças de pagamentos em atraso constrangem a relação com o cliente + +**Funcionalidades mais relevantes:** geração de orçamentos, follow-up automático ("o seu orçamento foi enviado — alguma dúvida?"), facturação automática por fase de obra, lembretes de pagamento, agenda de obras com alertas de prazo. + +**Linguagem de venda:** "orçamento pronto em horas, não dias", "o cliente sabe sempre o estado da obra", "recebe quando acaba, não quando se lembra". Evitar linguagem tech — falar em "tempo poupado" e "dinheiro recebido". + +**Canal de aquisição:** referência entre empresários do sector, associações (AICCOPN, AECOPS), Facebook Groups de empreiteiros e remodelações, feiras de construção. + +**Objecção principal:** "A minha secretária já faz isso." → Resposta: "E quando ela está de férias? O AcidaOS não vai de férias." + +**Trigger de compra:** perda de um contrato por orçamento que chegou tarde; mês com 3 facturas por emitir de obras já concluídas. + +**Pricing sweet spot:** €30-80/mês (sector muito sensível ao preço, mas disposto a pagar se ROI for claro e imediato). + +--- + +### Nicho 4 — Agências Digitais e Criativas + +**Quem:** Agências de marketing digital, design, comunicação, relações públicas, fotografia/vídeo, produção de conteúdo. + +**Dimensão PT:** +3.500 agências activas. Sector muito competitivo, margens a comprimir. Muitas em transição de "serviços de execução" para "serviços de estratégia + produto". + +**Dores operacionais:** +- Relatórios mensais para clientes consomem 2-3 dias de trabalho manual +- Gestão de aprovações de conteúdo por WhatsApp e email (versões perdidas) +- Timesheets manuais → facturação imprecisa → conflitos com clientes +- Escalabilidade travada: para crescer precisa de contratar +- Receita 100% baseada em horas → vulnerável a perdas de cliente + +**Funcionalidades mais relevantes:** geração automática de relatórios mensais, portal do cliente com aprovação de conteúdos, registo automático de horas, facturação por projecto, upsell/cross-sell automatizado (ex: "o teu plano inclui X — quer adicionar Y?"). + +**Linguagem de venda:** "relatórios que se fazem sozinhos", "o cliente aprova no portal, não por email", "receita recorrente sem aumentar a equipa", "white-label para revender aos teus clientes". + +**Canal de aquisição:** LinkedIn (muito activo neste nicho), eventos de marketing (RD Summit, Social Media Week), comunidades Slack de marketers, referência entre agências. + +**Objecção principal:** "Já usamos Monday/Asana/Notion." → Resposta: "O AcidaOS integra com essas ferramentas. Mas adiciona a camada de IA que automatiza o que ainda fazem manualmente: relatórios, aprovações, facturação." + +**Trigger de compra:** perda de 20% da margem num trimestre por horas não facturadas; cliente grande que pediu relatórios mais frequentes sem pagar mais. + +**Pricing sweet spot:** €100-300/mês; alto potencial para plano Partner/white-label (€500-1.000/mês). + +--- + +### Nicho 5 — Comércio B2B e Distribuição + +**Quem:** Distribuidores, grossistas, representantes comerciais, importadores, empresas de venda a retalhistas. + +**Dimensão PT:** sector fundamental da economia, muito diversificado. Ciclos de venda mais longos, pedidos recorrentes, relacionamento comercial crítico. + +**Dores operacionais:** +- Pedidos chegam por WhatsApp, email e telefone — sem registo centralizado +- Catálogo de produtos actualizado só existe em Excel ou PDF +- Comerciais perdem tempo a dar preços e a verificar stock pelo telefone +- Dívidas de clientes descobertas tarde (só quando o contabilista avisa) +- Fidelização: o cliente vai ao concorrente se não for contactado regularmente + +**Funcionalidades mais relevantes:** chatbot de catálogo e preços por WhatsApp, processamento de pedidos automático, alertas de pagamentos em atraso, follow-up automático de clientes inativos ("não nos pede há 30 dias — tudo bem?"), facturação automática por encomenda. + +**Linguagem de venda:** "o cliente pede pelo WhatsApp e a factura sai automática", "nunca perde uma encomenda por estar em reunião", "sabe quem não lhe compra há um mês antes de o perder". + +**Canal de aquisição:** associações sectoriais, feiras B2B, LinkedIn de directores comerciais, referência entre distribuidores. + +**Objecção principal:** "Os meus clientes são empresas — preferem email formal." → Resposta: "O sistema funciona por email também. E o WhatsApp para os urgentes — que são 80% dos pedidos reais." + +**Trigger de compra:** perda de cliente para concorrente por resposta mais rápida; mês com facturas em atraso acima de €10K. + +**Pricing sweet spot:** €100-250/mês (dispostos a pagar pelo ROI directo em cobranças e pedidos capturados). + +--- + +### Nicho 6 — Restauração e Hotelaria + +**Quem:** Restaurantes, cafés, bares, hotéis boutique, alojamentos locais, serviços de catering, espaços de eventos. + +**Dimensão PT:** +80.000 estabelecimentos de restauração. Sector de margens apertadas, alta rotatividade de staff, sazonalidade intensa. + +**Dores operacionais:** +- Reservas por telefone interrompem o serviço → perdidas quando está cheio +- Grupos e eventos corporativos: orçamentação manual e demorada +- Gestão de feedback online (Google, Tripadvisor) sem resposta sistemática +- Campanhas de WhatsApp para promoções especiais feitas manualmente +- Alojamento local: check-in remoto, comunicação com hóspedes em múltiplas línguas + +**Funcionalidades mais relevantes:** reservas e confirmações por WhatsApp, resposta automática a reviews Google, campanhas de promoções ("mesa disponível para amanhã?"), comunicação com hóspedes em PT/EN/ES automática, facturação de eventos. + +**Linguagem de venda:** "mesa reservada e confirmada sem tirar o empregado do serviço", "campanhas de promoção para a base de clientes em 2 minutos", "hóspedes atendidos em qualquer língua, a qualquer hora". + +**Canal de aquisição:** associações (AHRESP, ARESP), feiras do sector (Horexpo, BTL), Instagram/Facebook de restaurateurs, referência entre proprietários. + +**Objecção principal:** "O meu cliente quer falar com uma pessoa." → Resposta: "O sistema trata das confirmações de rotina. Quando o cliente quer falar com alguém, o sistema escala — e o teu staff tem mais tempo para isso." + +**Trigger de compra:** mesa dupla marcada no mesmo horário; alta temporada com reservas a escapar por não conseguir atender o telefone. + +**Pricing sweet spot:** €30-80/mês (margens apertadas — proposta tem de ser de ROI imediato e muito claro). + +--- + +### Nicho 7 — Contabilidade e Consultoria + +**Quem:** Gabinetes de contabilidade, TOCs (Técnicos Oficiais de Contas), escritórios de advogados, consultores de gestão, solicitadores. + +**Dimensão PT:** +8.000 gabinetes de contabilidade registados. Sector muito regulado, conservador, mas sob pressão de digitalização e de novas exigências da AT. + +**Dores operacionais:** +- Clientes entregam documentação de forma caótica (papel, foto de WhatsApp, email) +- Prazos fiscais críticos (IRS, IRC, IVA, SS) gerem-se manualmente com risco de multa +- Comunicação de alertas a clientes por email → baixa taxa de abertura +- Facturação de honorários por horas não registadas sistematicamente +- Novos clientes: onboarding burocrático e demorado + +**Funcionalidades mais relevantes:** portal de recolha de documentos do cliente, alertas de prazos fiscais automáticos por WhatsApp, registo automático de horas, facturação mensal, onboarding digital de clientes. + +**Linguagem de venda:** "o cliente entrega os documentos pelo WhatsApp e chegam organizados", "o cliente recebe o alerta de IVA no dia certo, não quando já passou", "sem ligar 5 vezes para pedir o recibo". Evitar: "IA", "automação" — usar "sistema", "organização", "processo". + +**Canal de aquisição:** Ordem dos Contabilistas Certificados, formações profissionais obrigatórias, referência entre TOCs, LinkedIn de gestores de gabinetes. + +**Objecção principal:** "Os nossos clientes são conservadores e resistem a mudanças." → Resposta: "O cliente não vê nenhuma mudança — continua a mandar fotos para o WhatsApp. Só que chegam organizadas ao sistema em vez de à caixa de entrada da Ana." + +**Trigger de compra:** multa de cliente por prazo fiscal falhado por comunicação deficiente; novo quadro legal que aumenta o volume de entregas obrigatórias. + +**Pricing sweet spot:** €50-150/mês (sector conservador no pricing mas com ROI muito mensurável em tempo poupado). + +--- + +### Nicho 8 — E-commerce e Retalho Online + +**Quem:** Lojas online, marcas DTC (direct-to-consumer), revendedores em marketplace (Amazon PT, FNAC, Worten), lojas omnicanal (físico + online). + +**Dimensão PT:** +25.000 lojas online activas. Crescimento acelerado mas altíssima competição e margens em queda. + +**Dores operacionais:** +- Volume de mensagens de suporte pós-venda (estado da encomenda, devoluções) insustentável +- Carrinhos abandonados sem follow-up automático → receita perdida +- Campanhas de reactivação de clientes inativos feitas manualmente +- Devoluções: processo manual, email interminável, cliente frustrado +- Avaliações negativas sem resposta → impacto na conversão + +**Funcionalidades mais relevantes:** suporte automático de "onde está a minha encomenda" por WhatsApp, follow-up de carrinho abandonado, campanha de reactivação de clientes inativos, gestão de devoluções automatizada, resposta a reviews. + +**Linguagem de venda:** "responde a 80% das perguntas de suporte sem intervenção humana", "recupera 15% dos carrinhos abandonados com um WhatsApp certo", "o cliente fica satisfeito sem precisar de esperar por email". + +**Canal de aquisição:** comunidades de e-commerce (Shopify PT Facebook Group, grupos LinkedIn de e-commerce), eventos (eCommerce Day, NOS Alive), agências de e-commerce como parceiros. + +**Objecção principal:** "Já usamos o suporte do Shopify." → Resposta: "O suporte do Shopify trata do que está dentro da plataforma. O AcidaOS trata do WhatsApp, do email e das mensagens do Instagram — que é de onde vêm 70% das perguntas reais." + +**Trigger de compra:** Black Friday com volume de suporte 5x superior ao habitual sem equipa para responder; mês com carrinho abandonado acima de 70% sem follow-up. + +**Pricing sweet spot:** €69-149/mês (familiarizados com SaaS, comparam com Gorgias €10-150/mês, Tidio €29-100/mês). + +--- + +### Nicho 9 — Educação e Formação + +**Quem:** Centros de formação profissional, explicadores e centros de explicações, escolas de línguas, escolas de música/artes, coaches e mentores, plataformas de formação online. + +**Dimensão PT:** sector em expansão acelerada. Formação profissional fortemente subsidiada (FSE/IEFP) com requisitos administrativos pesados. + +**Dores operacionais:** +- Matrículas e inscrições por telefone e email — processo manual e demorado +- Comunicação com pais (no caso de menores) caótica e dispersa +- Cobranças de mensalidades em atraso constrangem a relação com o aluno/família +- Certificados e documentação de formação gerados manualmente +- Formação subsidiada: relatórios e documentação obrigatória para financiamento + +**Funcionalidades mais relevantes:** inscrições online com confirmação automática, comunicação com pais por WhatsApp, cobranças automáticas com link de pagamento (MB Way), geração de certificados, relatórios de frequência. + +**Linguagem de venda:** "os pais recebem updates do filho pelo WhatsApp, sem ligar para a recepção", "as inscrições chegam organizadas, não por telefone", "as mensalidades cobram-se sozinhas no dia certo". + +**Canal de aquisição:** DGERT (entidade reguladora de formação), LinkedIn de directores pedagógicos, grupos Facebook de formadores, referência entre centros. + +**Objecção principal:** "Temos sistema de gestão escolar." → Resposta: "O AcidaOS complementa — trata da comunicação e cobranças que o sistema escolar não faz." + +**Trigger de compra:** período de matrículas com recepção sobrecarregada; mensalidade em atraso de mais de 3 meses por falta de follow-up. + +**Pricing sweet spot:** €50-120/mês (sensíveis ao preço mas com ROI claro em cobranças recuperadas). + +--- + +### Nicho 10 — Serviços Técnicos Especializados + +**Quem:** Empresas de IT/informática, AVAC, electricistas com empresa, empresas de segurança e alarmes, canalizadores, empresas de manutenção de equipamentos. + +**Dimensão PT:** dezenas de milhares de micro e pequenas empresas. Alta dependência de WhatsApp para comunicar com técnicos e clientes. Muito fragmentado. + +**Dores operacionais:** +- Chamadas de avaria chegam fora de horas sem registo +- Orçamentos de intervenções demoram dias (técnico tem de ver primeiro) +- Scheduling de técnicos manual — conflitos de agenda e deslocações ineficientes +- Contrato de manutenção: clientes que deviam contactar para revisão e não contactam +- Relatório de intervenção escrito à mão ou por memória do técnico + +**Funcionalidades mais relevantes:** triagem automática de avarias fora de horas (gravidade, urgência), agendamento de técnicos por disponibilidade, geração de relatório de intervenção por voz (técnico descreve verbalmente → relatório gerado), alertas de manutenção preventiva, facturação de serviço. + +**Linguagem de venda:** "o técnico descreve o trabalho pelo WhatsApp e o relatório fica pronto", "as chamadas de avaria fora de horas ficam registadas e triadas", "o cliente de manutenção recebe o alerta de revisão no mês certo". + +**Canal de aquisição:** associações sectoriais (ANEOP, ASIAM), LinkedIn de gestores de empresa técnica, grupos Facebook de técnicos, referência entre pares. + +**Objecção principal:** "Os meus técnicos não usam computador." → Resposta: "Exactamente por isso — o AcidaOS funciona pelo WhatsApp que eles já usam. O relatório faz-se com uma nota de voz." + +**Trigger de compra:** chamada de avaria urgente perdida fora de horas; técnico que sai e leva o registo das intervenções que fez. + +**Pricing sweet spot:** €40-100/mês (dispostos a pagar pelo valor em tempo poupado e em trabalho não perdido). + +--- + +## Tabela resumo — priorização por atractividade + +| Nicho | Volume PT | Urgência da dor | Disposição a pagar | Canal de entrada | Score | +|-------|-----------|----------------|-------------------|-----------------|-------| +| Saúde Privada | Alta | Muito alta | Alta | Associações + Google | ⭐⭐⭐⭐⭐ | +| Imobiliárias | Média | Alta | Alta | LinkedIn + portais | ⭐⭐⭐⭐⭐ | +| Agências Digitais | Média | Alta | Muito alta | LinkedIn + eventos | ⭐⭐⭐⭐⭐ | +| E-commerce | Alta | Alta | Alta | Comunidades + parceiros | ⭐⭐⭐⭐ | +| Contabilidade | Alta | Média-alta | Média | Ordem OCC + formação | ⭐⭐⭐⭐ | +| Construção | Muito alta | Alta | Média | Referência + associações | ⭐⭐⭐⭐ | +| Comércio B2B | Alta | Alta | Média-alta | Feiras + LinkedIn | ⭐⭐⭐⭐ | +| Serviços Técnicos | Muito alta | Média | Média | Referência + grupos | ⭐⭐⭐ | +| Educação | Média | Média | Baixa-média | DGERT + referência | ⭐⭐⭐ | +| Restauração | Muito alta | Média | Baixa | AHRESP + Instagram | ⭐⭐⭐ | + +**Top 3 para arranque:** Saúde Privada, Imobiliárias, Agências Digitais — dor alta, disposição a pagar alta, canais de entrada claros. diff --git a/crm-ops/skills/estrategia-marca/references/perguntas-briefing.md b/crm-ops/skills/estrategia-marca/references/perguntas-briefing.md new file mode 100644 index 0000000..4ef6388 --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/perguntas-briefing.md @@ -0,0 +1,113 @@ +# Perguntas de Briefing — Entrevista Estratégica + +Guia de entrevista estruturado para conduzir o briefing inicial com o cliente. +Adaptar ao sector e nível de maturidade da marca. + +--- + +## Bloco 1 — O negócio + +### Contexto actual +1. O que faz a sua empresa, em termos simples? +2. Há quantos anos está no mercado? Como surgiu? +3. Qual a dimensão actual: equipa, facturação, clientes? +4. Qual é o maior desafio que enfrenta hoje no negócio? +5. O que o distingue dos concorrentes? (resposta espontânea — não sugerir) + +### Serviços e produtos +6. Quais são os seus produtos/serviços principais? +7. Qual gera mais receita? Qual tem mais potencial? +8. Existe algum produto que quer destacar mais? Porquê? +9. Que resultados concretos entregam aos clientes? + +### Posicionamento actual +10. Se pedisse a um cliente para descrever a sua empresa em 3 palavras, o que diria? +11. Existe uma percepção de mercado que quer mudar? +12. Onde se posiciona em preço vs concorrência? (mais caro, igual, mais barato) Porquê? + +--- + +## Bloco 2 — O cliente ideal + +### Segmentação +13. Quem é o seu cliente ideal? Descreva-o em detalhe. +14. Tem mais do que um tipo de cliente? Como os diferencia? +15. Qual o cliente que mais valoriza o que fazem e paga melhor? +16. Existe algum cliente que não quer ter? Porquê? + +### Comportamento de compra +17. Como é que os clientes chegam até si? (canal principal de aquisição) +18. Quanto tempo demora tipicamente desde o primeiro contacto até fechar negócio? +19. Quem toma a decisão de compra? É uma pessoa ou um grupo? +20. Que objecções ouve mais frequentemente antes de fechar? + +### Relação com clientes +21. Qual foi o feedback mais positivo que recebeu de um cliente? (pedir citação exacta) +22. Qual foi a queixa mais comum? Como resolveram? +23. Tem clientes que recomendam espontaneamente? O que dizem? + +--- + +## Bloco 3 — Mercado e concorrência + +### Mercado +24. Em que mercado opera? Geográfico (local, nacional, internacional)? +25. O mercado está a crescer, estável ou a contrair? +26. Que tendência do mercado mais o preocupa? Qual mais o entusiasma? +27. Existe sazonalidade? Em que períodos? + +### Concorrência +28. Quem são os 3 principais concorrentes? +29. Em que é que são melhores? Em que é que são piores? +30. Por que é que um cliente nos escolhe a nós vs ao concorrente X? +31. Existe algum concorrente que admira (mesmo que de outra área)? + +--- + +## Bloco 4 — Visão e ambição + +### Onde quer chegar +32. Qual é o objectivo da empresa a 3 anos? +33. O que precisa de mudar para chegar lá? +34. Existe um modelo de empresa que admira ou quer imitar? Porquê? +35. Se tivesse recursos ilimitados, o que faria primeiro? + +### Marca e identidade +36. Que 3 adjectivos descrevem a personalidade ideal da marca? +37. Que marcas (de qualquer sector) admira pela comunicação? O que lhes agrada? +38. Existe uma história de origem da empresa que emociona? (fundador, momento de viragem) +39. Que valores são inegociáveis? O que nunca fariam por dinheiro? + +### Tom de voz +40. A marca é mais formal ou informal? Mais técnica ou acessível? +41. Usa humor na comunicação? Em que contextos? +42. Existe linguagem/palavras que NÃO deve usar? + +--- + +## Bloco 5 — Recursos e restrições + +### Capacidade +43. Qual o budget mensal disponível para marketing? +44. Existe equipa interna de marketing ou será tudo externalizado? +45. Quem aprova conteúdos? Qual o processo de revisão? + +### Prazo +46. Existe algum lançamento, evento ou data importante a curto prazo? +47. Quando precisa de ter a estratégia operacional? + +### Material existente +48. Existe alguma estratégia anterior? O que funcionou? O que não funcionou? +49. Que activos existem: website, redes sociais, base de emails, testemunhos, cases? +50. Existem fotos/vídeos profissionais? Em que estado está a identidade visual? + +--- + +## Notas de condução da entrevista + +- Fazer max 15-20 perguntas numa sessão (60-90 min) +- Priorizar: Blocos 1, 2 e 4 na primeira sessão +- Blocos 3 e 5 podem ser preenchidos com pesquisa independente +- Pedir sempre exemplos concretos e citações textuais de clientes +- Quando a resposta é vaga, fazer "pode dar-me um exemplo específico?" +- Gravar a sessão (com autorização) para não perder citações úteis diff --git a/crm-ops/skills/estrategia-marca/references/template-documento.md b/crm-ops/skills/estrategia-marca/references/template-documento.md new file mode 100644 index 0000000..4fad45d --- /dev/null +++ b/crm-ops/skills/estrategia-marca/references/template-documento.md @@ -0,0 +1,374 @@ +# Template: Documento de Estratégia de Marca + +Estrutura completa do documento entregável ao cliente. Baseado nos projectos SFV, LJM, MCT, Espiral Senior e Sintricare. +Adaptar secções ao sector e complexidade do cliente. + +--- + +## Cabeçalho do documento + +``` +--- +title: [Nome da Marca] — Estratégia de Marca +cliente: [Nome do cliente] +código: EST-MRK-010 +versão: 1.0 +data: [DD-MM-YYYY] +elaborado: Descomplicar® — Agência de Aceleração Digital +status: draft | aprovado +--- +``` + +--- + +## DECLARAÇÃO DE IMPACTO + +> **[Uma frase poderosa — 10-15 palavras máximo]** +> *A essência e o impacto da marca numa linha.* + +--- + +## ÍNDICE + +1. Apresentação e Fundamentos Estratégicos +2. Proposta de Valor Única +3. Missão, Visão, Valores e Objectivos +4. Apresentação Sumária da Empresa e Serviços +5. Segmentação e Análise Detalhada de Público +6. Pitch Canvas +7. Copywriting Estratégico +8. Estratégia de Comunicação e Canais +9. Investimentos Prioritários +10. Monitorização e KPIs +11. Inventário de Activos de Marketing + +--- + +## 1. Apresentação e Fundamentos Estratégicos + +### 1.1 Contexto actual +- **Mercado:** [Análise do mercado actual — dimensão, tendências, oportunidades] +- **Concorrência:** [Principais concorrentes e posições] +- **Desafios:** [Principais desafios enfrentados pela marca] +- **Oportunidades:** [Oportunidades identificadas] + +### 1.2 Problema a resolver +[Identificação clara do problema de negócio que esta estratégia precisa resolver — qual é o problema central que impede o crescimento ou o impacto da marca?] + +--- + +## 2. Proposta de Valor Única + +### 2.1 O que nos torna únicos +[O que tornamos possível que os concorrentes não conseguem. Ser específico — evitar "qualidade e experiência".] + +### 2.2 Diferenciais competitivos +1. [Diferencial 1 — explicar o mecanismo único que o cria] +2. [Diferencial 2] +3. [Diferencial 3] + +### 2.3 Benefícios por camada +| Tipo | Benefícios | +|------|-----------| +| **Funcionais** | [O que o produto/serviço faz concretamente] | +| **Emocionais** | [Como o cliente se sente ao usar/contratar] | +| **Identitários** | [O que diz sobre o cliente escolher esta marca] | + +--- + +## 3. Missão, Visão, Valores e Objectivos + +### 3.1 Missão +> [O que fazemos, para quem e como — acção no presente. Max 2 frases.] + +### 3.2 Visão +> [Onde queremos estar e que impacto queremos ter em 3-5 anos. Max 2 frases.] + +### 3.3 Valores +- **[Valor 1]** — [Como se manifesta na prática, no dia-a-dia da empresa] +- **[Valor 2]** — [Como se manifesta] +- **[Valor 3]** — [Como se manifesta] +- **[Valor 4]** — [Como se manifesta] *(opcional)* + +### 3.4 Objectivos estratégicos +- **Curto prazo (6m):** [2-3 objectivos mensuráveis] +- **Médio prazo (1 ano):** [2-3 objectivos] +- **Longo prazo (3 anos):** [Ambição de impacto] + +--- + +## 4. Apresentação Sumária da Empresa e Serviços + +### 4.1 Quem somos +[Parágrafo de apresentação — quem são, o que fazem, há quanto tempo, dimensão, missão em acção] + +### 4.2 Serviços/Produtos principais + +| Serviço/Produto | Descrição | Para quem | Resultado principal | +|----------------|-----------|-----------|-------------------| +| [Nome] | — | — | — | +| [Nome] | — | — | — | + +### 4.3 Posicionamento +[Declaração de posicionamento — o lugar único que a marca ocupa na mente do cliente] + +> "Para [público], somos a única [categoria] que [benefício único] porque [prova]." + +--- + +## 5. Segmentação e Análise Detalhada de Público + +*Repetir a estrutura completa dos 20 pontos para cada segmento identificado.* + +--- + +### 5.X — [Nome do Segmento] + +*[Breve descrição de quem é este segmento — 2 linhas]* + +#### 1. Perfil Demográfico +[Idade, género, localização, rendimento, nível de educação, profissão, cargo, tipo/dimensão de empresa, estado civil, composição familiar — tudo o que é mensurável e verificável] + +#### 2. Perfil Psicográfico +[Valores pessoais, crenças, atitude perante a vida, estilo de vida, motivações profundas, relação com a categoria de produto/serviço, identidade social — o que não se mede mas define quem são] + +#### 3. Dores +[Problemas activos e urgentes que precisam resolver. O que os está a prejudicar agora. Dores específicas do dia-a-dia relacionadas com o que a marca resolve.] + +#### 4. Anseios +[O que aspiram a ser, ter ou alcançar. Sonhos profissionais e pessoais. A versão ideal do futuro que imaginam.] + +#### 5. Desejos +[O que querem concretamente — mais imediato e específico que os anseios. Desejos práticos relacionados com a nossa oferta.] + +#### 6. Frustrações +[O que já tentaram fazer ou comprar sem resultado. Soluções que prometeram e não entregaram. O cansaço acumulado de não resolver o problema.] + +#### 7. Preocupações +[O que os inquieta a médio/longo prazo. Cenários negativos que imaginam. Preocupações sistémicas relacionadas com a sua vida ou negócio.] + +#### 8. Medos +[Medos concretos associados à compra ou à não-compra. Medo de errar, de ser enganado, de perder dinheiro, de ser julgado. O que os paralisa antes de decidir.] + +#### 9. Inimigos +[Os "vilões" da história deste segmento — concorrentes que os desiludiram, sistemas que os prejudicam, tendências que os ameaçam, pessoas ou entidades a quem culpam o problema] + +#### 10. Linguagem +[As palavras e expressões exactas que usam para descrever o problema, a solução e os resultados. Jargão do sector. O que dizem aos amigos. O que escrevem no Google. Evitar linguagem que usamos internamente mas eles não usam.] + +#### 11. Como procuram ajuda, informação ou dicas? +[Onde vão quando têm o problema: Google (que pesquisas fazem?), YouTube, grupos Facebook, LinkedIn, amigos, consultores, feiras, etc. Que tipo de conteúdo consomem para se informar?] + +#### 12. Canais digitais +[Em que plataformas estão activos: Facebook, Instagram, LinkedIn, TikTok, YouTube, email, WhatsApp, fóruns, etc. Com que frequência? Em que contexto (trabalho vs lazer)?] + +#### 13. Estilo de Decisão +[Como tomam decisões de compra: rápido vs deliberado, emocional vs racional, individual vs colectivo, impulsivo vs comparativo. Que factores pesam mais? Precisam de aprovação de terceiros?] + +#### 14. Mudanças +[Mudanças que sabem e sentem necessárias nas suas vidas ou negócio. Passos que sabem que precisam dar mas ainda não deram. A consciência que já têm do problema.] + +#### 15. Resistência à Mudança +[De que maneira resistem à mudança? Que desculpas usam para adiar? Como os podemos ajudar a ultrapassar essa resistência? Que argumentos reduzem o atrito?] + +#### 16. Objecções Típicas +[As objecções mais frequentes às ofertas comerciais desta categoria. Como as podemos antecipar e superar? Respostas específicas a cada objecção.] + +| Objecção | Como ultrapassar | +|----------|----------------| +| — | — | +| — | — | +| — | — | + +#### 17. Forma de Gerar Emoção +[Que tipo de conteúdo, história ou mensagem os move emocionalmente? O que os faz parar no scroll? O que os faz partilhar? Qual o gatilho emocional mais poderoso para este segmento?] + +#### 18. Argumentos +[A que argumentos são mais sensíveis? Como os podemos persuadir a agir? Que tipo de prova precisam: dados, testemunhos, demonstrações, garantias? Qual a sequência de persuasão ideal?] + +#### 19. Concorrentes +[Que outras entidades lhes oferecem o mesmo tipo de serviço ou solução alternativa? Como se comparam a nós em percepção de valor?] + +#### 20. Propostas Recusadas +[Que propostas é que este segmento tem recusado e porquê? O que dizem explicitamente e o que dizem implicitamente? O que não querem mais ouvir?] + +--- + +## 6. Pitch Canvas + +### 6.1 O que é o Pitch Canvas? +O Pitch Canvas é uma ferramenta de comunicação estratégica que resume, numa única estrutura visual, o essencial da proposta de valor da empresa. É útil porque: +- Força clareza e síntese (não há espaço para vagueza) +- Alinha toda a equipa na mesma mensagem +- Serve de base para qualquer peça de comunicação +- Torna a proposta de valor testável e iterável + +### 6.2 Utilidade específica para [Nome da Marca] +[Como o Pitch Canvas pode ajudar esta marca concretamente — que clareza traz, que conversas simplifica, onde pode ser usado] + +### 6.3 Os 5 elementos do Pitch Canvas + +**Para quem:** +> [Segmento principal — quem são e qual o problema específico] + +**O problema:** +> [Dor principal, urgente e real — formulada na linguagem do cliente] + +**A solução:** +> [O que oferecemos — mecanismo único de resolução] + +**O resultado:** +> [Transformação concreta — antes vs depois, com métrica se possível] + +**Por que nós:** +> [Razão para acreditar — o que nos torna credíveis e únicos] + +### 6.4 Declaração de mudança no mundo +> **"[Nome da Marca] está a mudar [o quê] para [quem], através de [como], tornando possível [impacto maior]."** + +--- + +## 7. Copywriting Estratégico + +### 7.1 Questionamento estratégico + +**Qual é o objectivo da comunicação?** +[Definir claramente o que queremos que o público faça, sinta ou pense após cada comunicação. Sem objectivo claro não há comunicação eficaz.] + +**Que transformação prometemos?** +[A transformação específica que a marca entrega — não o produto, mas a mudança de estado do cliente] + +### 7.2 Pain + Gain (Problema e Resultado) + +> **Pain:** [O problema central na perspectiva do cliente — formulado com a dor, não com o produto] +> **Gain:** [O resultado desejado — formulado com o benefício, não com a funcionalidade] + +*Revisão com questões específicas do sector:* +> **Pain refinado:** [Após aprofundar com o briefing — mais específico, com linguagem do cliente] +> **Gain refinado:** [Com métricas ou resultados concretos já entregues a outros clientes] + +### 7.3 Narrativa por segmento + +*Fórmula: Problema (dor do público) → Solução (serviços da empresa) → Resultado (benefícios concretos)* + +**[Segmento A]:** +> **Problema:** [Dor específica e urgente deste segmento, na sua linguagem] +> **Solução:** [Como a marca resolve de forma única — mecanismo específico] +> **Resultado:** [Benefício tangível e mensurável + prova social ou garantia] + +**[Segmento B]:** +> **Problema:** [...] +> **Solução:** [...] +> **Resultado:** [...] + +*(Repetir para cada segmento)* + +### 7.4 Mensagem central da marca +> **"[A frase que todos os colaboradores sabem de cor — resumo da proposta de valor em 10 palavras]"** + +### 7.5 Headlines por segmento + +| Segmento | Headline principal | Headline secundária | +|----------|------------------|-------------------| +| [Seg. A] | — | — | +| [Seg. B] | — | — | + +--- + +## 8. Demonstração dos Serviços + +### 8.1 Como demonstrar [serviço/produto principal] + +**Preparação personalizada:** +[O que preparar antes da demonstração para cada segmento] + +**Introdução interactiva:** +[Como começar — conectar com a dor antes de mostrar a solução] + +**Demonstração ao vivo:** +[O que mostrar, em que ordem, com que foco] + +**Casos de uso:** +[Exemplos reais de clientes similares — antes/depois] + +**Q&A:** +[Perguntas frequentes na demonstração e respostas modelo] + +**Follow-up:** +[Próximo passo após a demonstração — o que enviar, quando contactar] + +--- + +## 9. Investimentos Prioritários + +### 9.1 Prioridades imediatas (impacto/esforço) + +| Prioridade | Investimento | Impacto esperado | Prazo | Custo estimado | +|-----------|-------------|-----------------|-------|---------------| +| 1 | [Ex: Website + SEO] | — | 30-60d | — | +| 2 | [Ex: Google Ads] | — | 30d | — | +| 3 | [Ex: Email marketing] | — | 60d | — | + +### 9.2 Estratégia de canais + +| Canal | Objectivo | Frequência | KPI | Budget mensal | +|-------|-----------|-----------|-----|--------------| +| Website | — | — | — | — | +| Google Ads | — | — | — | — | +| Meta Ads | — | — | — | — | +| LinkedIn | — | — | — | — | +| Email | — | — | — | — | +| WhatsApp | — | — | — | — | + +### 9.3 Pilares de conteúdo +1. [Pilar 1 — tema + tipos de conteúdo + frequência] +2. [Pilar 2] +3. [Pilar 3] + +--- + +## 10. Monitorização e KPIs + +### 10.1 Dashboard de métricas + +| Área | KPI | Baseline | Meta 3m | Meta 6m | Meta 12m | +|------|-----|---------|---------|---------|----------| +| Brand | Notoriedade espontânea | — | — | — | — | +| Tráfego | Visitas/mês | — | — | — | — | +| Leads | Leads qualificados/mês | — | — | — | — | +| Conversão | Taxa de fecho | — | — | — | — | +| Retenção | NPS | — | — | — | — | + +### 10.2 Ciclo de optimização +- **Revisão mensal:** métricas de canal, ajuste de conteúdo +- **Revisão trimestral:** avaliação de ROI, ajuste de orçamento +- **Revisão anual:** actualização estratégica completa + +--- + +## 11. Inventário de Activos de Marketing + +| Activo | Localização | Estado actual | Prioridade | +|--------|------------|--------------|-----------| +| Website | [URL] | — | — | +| Blog/Artigos | — | — | — | +| Redes sociais | — | — | — | +| Base de emails | — | — | — | +| Testemunhos/Cases | — | — | — | +| Materiais impressos | — | — | — | +| Apresentações | — | — | — | +| Fotos/Vídeos profissionais | — | — | — | + +--- + +## Notas de implementação + +1. **Sessão de alinhamento:** Apresentar o documento à equipa antes de implementar +2. **Validação:** Partilhar narrativas com 2-3 clientes actuais antes de publicar +3. **Implementação faseada:** Começar pelos canais de maior impacto e menor esforço +4. **Suporte:** WhatsApp durante 1 mês para dúvidas de implementação (EST-MRK-010) + +--- + +*Elaborado por Descomplicar® — Agência de Aceleração Digital* +*emanuel@descomplicar.pt | descomplicar.pt* diff --git a/crm-ops/skills/expense/SKILL.md b/crm-ops/skills/expense/SKILL.md index 824dcbe..e1a5747 100644 --- a/crm-ops/skills/expense/SKILL.md +++ b/crm-ops/skills/expense/SKILL.md @@ -1,6 +1,6 @@ --- name: expense -description: Gestao de despesas Desk CRM com PDF obrigatorio. Registar, categorizar e analisar despesas com verificacao de duplicados, upload SFTP e arquivo mensal automatico. +description: Gestao de despesas Desk CRM com PDF obrigatorio. Registar, categorizar e analisar despesas com verificacao de duplicados por reference_no, upload SFTP e arquivo mensal automatico. --- # /expense - Gestao de Despesas @@ -55,18 +55,27 @@ Para mapeamento completo de fornecedores, emails e padroes PDF para categorias: - Bypass valido apenas para: AT, Salarios, transferencias bancarias 2. LER O PDF: Extrair dados reais do documento - NUNCA copiar valor de um PDF para outro + - EXTRAIR reference_no (numero factura) — OBRIGATORIO para dedup 3. OBRIGATORIO: get_expense_categories(with_stats=true) 4. Identificar categoria correcta na lista -5. VERIFICAR DUPLICADOS: +5. VERIFICAR DUPLICADOS (3 camadas — OBRIGATORIO): + Camada 0 — Referencia de factura (PRIMARIA): + - get_expenses(search: "") + - Se alguma despesa tem reference_no IGUAL → DUPLICADO → PARAR + Camada 1 — Fornecedor + Valor + Data: - get_expenses(search: "") - - Mesmo fornecedor + valor + data = duplicado - - Mesmo numero factura = duplicado + - Mesmo fornecedor + valor (±0.05) + data (±3 dias) = duplicado + Camada 2 — Expense name: + - get_expenses(search: " - ") + - Se match exacto → duplicado + Se QUALQUER camada detecta duplicado → NAO criar, informar utilizador 6. Recolher dados: - category_id, amount, currency (EUR=3, USD=2), date (YYYY-MM-DD) + - reference_no (numero factura — OBRIGATORIO) - note (incluir numero factura), send_invoice_to_customer = 0 - Opcionais: client_id, project_id, billable, tax 7. CONFIRMAR com utilizador (mostrar resumo) -8. create_expense +8. create_expense (INCLUIR reference_no no payload) 9. UPLOAD PDF ao Desk via SFTP: a. mkdir -p no servidor: /home/ealmeida/desk.descomplicar.pt/uploads/expenses/ b. mcp__ssh-unified__sftp_upload(server:"desk", local_path, remote_path) @@ -104,7 +113,7 @@ Para mapeamento completo de fornecedores, emails e padroes PDF para categorias: Para protocolo completo de processamento de tickets de contabilidade: ver `references/ticket-processing.md` -**Resumo:** Obter ticket -> verificar anexos -> verificar duplicados -> extrair dados -> confirmar -> criar despesa -> upload PDF -> arquivo mensal. +**Resumo:** Obter ticket -> verificar anexos -> verificar duplicados (3 camadas) -> extrair dados -> confirmar -> criar despesa -> upload PDF -> arquivo mensal. --- @@ -136,15 +145,16 @@ Para protocolo completo de processamento de tickets de contabilidade: ver `refer **Despesas:** 4. Criar despesa sem category_id 5. Nao validar data (formato YYYY-MM-DD) -6. Criar despesa sem verificar duplicados primeiro +6. Criar despesa sem verificar duplicados primeiro (3 camadas obrigatorias) +7. Criar despesa sem reference_no (chave primaria de dedup) **Valores de PDFs:** -7. Assumir que ficheiros com nomes semelhantes tem o mesmo valor -8. SEMPRE ler CADA PDF individualmente para extrair o valor real +8. Assumir que ficheiros com nomes semelhantes tem o mesmo valor +9. SEMPRE ler CADA PDF individualmente para extrair o valor real **Tickets:** -9. Processar ticket sem verificar anexos PDF -10. Assumir que ticket com recibo = despesa nao lancada +10. Processar ticket sem verificar anexos PDF +11. Assumir que ticket com recibo = despesa nao lancada --- @@ -152,8 +162,11 @@ Para protocolo completo de processamento de tickets de contabilidade: ver `refer - [ ] Listar categorias existentes - [ ] Validar categoria correcta +- [ ] Extrair reference_no do PDF/factura +- [ ] Verificar duplicados (3 camadas) - [ ] Confirmar dados com utilizador - [ ] Usar formato data YYYY-MM-DD +- [ ] Incluir reference_no no create_expense - [ ] Incluir nota descritiva --- @@ -164,6 +177,24 @@ Para protocolo completo de processamento de tickets de contabilidade: ver `refer - `references/ticket-processing.md` - Protocolo completo de processamento de tickets - `references/changelog.md` - Historico de alteracoes + + --- -**Criado:** 2026-02-05 | **Actualizado:** 2026-02-12 +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/expense.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + +--- + +**Criado:** 2026-02-05 | **Actualizado:** 2026-03-30 | Fix: dedup 3 camadas com reference_no (DES-137) + + +## Healing Log + diff --git a/crm-ops/skills/invoice/SKILL.md b/crm-ops/skills/invoice/SKILL.md index 2c2e59d..7e4e537 100644 --- a/crm-ops/skills/invoice/SKILL.md +++ b/crm-ops/skills/invoice/SKILL.md @@ -253,3 +253,15 @@ Acções: --- *Skill v1.0.0 | 2026-02-05 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/orcamento/SKILL-light.md b/crm-ops/skills/orcamento/SKILL-light.md new file mode 100644 index 0000000..2678c5f --- /dev/null +++ b/crm-ops/skills/orcamento/SKILL-light.md @@ -0,0 +1,150 @@ +--- +name: orcamento +description: Criação de orçamentos Descomplicar baseados nos itens oficiais do Desk CRM. Versão light para heartbeats. +disable-model-invocation: true +--- + +# Orçamento — Referência Rápida + +## Fonte de verdade: Desk CRM (`tblitems` + `tblitems_groups`) + +651 itens em 14 grupos. Consultar SEMPRE o CRM para preços actualizados. + +## Sintaxe + +``` +/orcamento [cliente] [tipo] [-MEN|-TRI] +``` + +| Código | Tipo | Grupo CRM | +|--------|------|-----------| +| `starter` | StarterWP | Websites | +| `corporate` | CorporateWP | Websites | +| `care` | CareWP | Websites | +| `ecom` | eCommerceWP | Websites | +| `mkt` | Marketing 360 | Marketing | +| `man` | Manutenção | Suporte | +| `deskcrm` | DeskCRM | DeskCRM | +| `chatbot` | Chatbot | Chatbots | +| `acceleratorx` | AcceleratorX | Tecnologia | + +## Variantes de facturação + +| Flag | Unit | Pesquisa CRM | +|------|------|-------------| +| (nenhum) | ano | Item base | +| `-MEN` | mensalidade | `WHERE description LIKE 'Mensalidade%...'` | +| `-TRI` | trimestral | `WHERE description LIKE 'Trimestral%...'` | + +Preços das variantes são definidos no CRM (podem incluir markup). Nunca calcular por divisão simples. + +## Protocolo + +### 1. Identificar cliente + +``` +mcp__desk-crm-v3__search_customers query="[nome]" fields="company,vat" +``` + +### 2. Consultar preços + +```bash +# Itens base (setup/pontuais) +mysql -u root ealmeida_desk24 -e " + SELECT description, rate, unit FROM tblitems + WHERE group_id = [GROUP_ID] + AND description LIKE '%[PACOTE]%' + AND unit NOT IN ('mensalidade','trimestral','anuidade') + ORDER BY description;" + +# Itens recorrentes (com variante) +mysql -u root ealmeida_desk24 -e " + SELECT description, rate, unit FROM tblitems + WHERE group_id = [GROUP_ID] + AND description LIKE '[Mensalidade|Trimestral]%[PACOTE]%' + ORDER BY description;" +``` + +Ou via MCP: +``` +mcp__desk-crm-v3__price_management action="get_pricing_insights" params={"group": "[GRUPO]"} +``` + +### 3. Criar estimate + +``` +mcp__desk-crm-v3__create_estimate + client_id=[id] + date=[hoje] + expiry_date=[hoje + 30 dias] + items=[{description, qty, rate, unit}] + terms="[termos]" +``` + +**Formato item:** `{"description": "...", "qty": 1, "rate": 700, "unit": "un"}` + +**Unidades:** `un` (pontual), `mensalidade` (-MEN), `trimestral` (-TRI), `anuidade` (defeito) + +### 4. Termos por variante + +- **Sem flag:** "50% na adjudicação + 50% na entrega" +- **-MEN:** "Setup: 50%+50% | Recorrência: facturação mensal antecipada" +- **-TRI:** "Setup: 50%+50% | Recorrência: facturação trimestral antecipada" + +## Preços de referência (consultar CRM para valores reais) + +### Websites + +| Produto | Setup | Anuidade | +|---------|-------|----------| +| StarterWP | 700 | 250 | +| CorporateWP | 900 | 299 | +| eCommerceWP | 1100 | 349 | +| CareWP | 1300 | 350 | + +### DeskCRM + +| Produto | Anuidade | +|---------|----------| +| Starter | 400 | +| Profissional | 800 | +| Avançado | 1500 | +| Enterprise | 3000 | + +### AcceleratorX + +| Produto | Setup | +|---------|-------| +| WP ProCMS | 650 | +| e-Commerce | 750 | +| Care | 750 | +| School Manager | 850 | + +### Chatbots + +| Produto | Setup | +|---------|-------| +| Básico | 350 | +| Avançado | 850 | + +## Checklist + +- [ ] Cliente identificado/criado no CRM +- [ ] Tipo seleccionado +- [ ] Preços consultados no CRM +- [ ] Valores calculados (subtotal + IVA 23%) +- [ ] Recorrência calculada +- [ ] Estimate criado (status: Draft) +- [ ] Resumo apresentado + +## MCPs + +``` +mcp__desk-crm-v3__search_customers +mcp__desk-crm-v3__create_customer +mcp__desk-crm-v3__create_estimate +mcp__desk-crm-v3__price_management +``` + +--- +**Versão**: 4.1.0-light | **Base**: 4.1.0 diff --git a/crm-ops/skills/orcamento/SKILL.md b/crm-ops/skills/orcamento/SKILL.md index 376b4b2..2eba4a2 100644 --- a/crm-ops/skills/orcamento/SKILL.md +++ b/crm-ops/skills/orcamento/SKILL.md @@ -512,3 +512,15 @@ INSERT INTO tblskill_agent_metrics ( --- **Versao**: 4.1.0 | **Data**: 2026-03-12 | **Fonte de Verdade**: Desk CRM (tblitems) + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/proposal-deck/SKILL.md b/crm-ops/skills/proposal-deck/SKILL.md index 410914b..9fe9853 100644 --- a/crm-ops/skills/proposal-deck/SKILL.md +++ b/crm-ops/skills/proposal-deck/SKILL.md @@ -365,3 +365,15 @@ mcp__mcp-time__current_time - Data/hora actual --- **Versao**: 1.0.0 | **Data**: 2026-03-06 | **Template**: descomplicar-proposal-template.pptx + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/proposta-visual/SKILL.md b/crm-ops/skills/proposta-visual/SKILL.md new file mode 100644 index 0000000..ff5c4f4 --- /dev/null +++ b/crm-ops/skills/proposta-visual/SKILL.md @@ -0,0 +1,386 @@ +--- +name: proposta-visual +description: Criação completa de propostas comerciais visuais — página web (propostas.descomplicar.pt) + PDF exportável + PPTX editável. Recolhe dados CRM, gera JSON, renderiza condicionalmente e faz deploy. +--- + +# Skill /proposta-visual — Propostas Comerciais Visuais + +Cria propostas comerciais profissionais com 3 outputs: página web interactiva, PDF exportável e PPTX editável. + +## Triggers + +- `/proposta-visual` +- "proposta visual", "proposta web", "criar proposta", "nova proposta", "proposta para [cliente]" + +## Quando usar + +- Criar proposta comercial completa para um cliente +- Gerar página web + PDF + PPTX de uma proposta +- Actualizar proposta existente com novos dados + +## Quando NÃO usar + +- Apenas orçamento sem visual (usar `/orcamento`) +- Apenas PPTX sem página web (usar `/proposal-deck`) +- Análise de lead sem proposta (usar `/lead-approach`) + +--- + +## Projecto base + +| Campo | Valor | +|-------|-------| +| **Código fonte** | `/media/ealmeida/Dados/Dev/Propostas/` | +| **Stack** | React 18 + Vite + Tailwind + @react-pdf/renderer + Recharts + Framer Motion + Lucide React | +| **Live** | `propostas.descomplicar.pt/{slug}` | +| **Deploy** | Docker Swarm EasyPanel, serviço `descomplicar_propostas`, ficheiros `/opt/propostas/` | +| **DNS** | `propostas.descomplicar.pt` → 5.9.90.70 (Cloudflare proxied) | +| **Template PPTX** | `/media/ealmeida/Dados/Hub/90-Templates/Comercial/descomplicar-proposal-template.pptx` | + +--- + +## REGRAS CRÍTICAS (ler antes de qualquer implementação) + +### 1. PT-PT obrigatório — acentos em TODO o texto + +Todos os textos no JSON, componentes web e componentes PDF DEVEM ter acentos PT-PT correctos: +- ✓ migração, tradução, integração, opções, condições, execução, acção +- ✗ migracao, traducao, integracao, opcoes, condicoes, execucao, accao + +**Verificar no PDF:** labels hardcoded em `PDFWorkDone.jsx` e `PDFDocument.jsx` — já corrigidos mas confirmar sempre. + +### 2. JSON data-driven — renderização condicional obrigatória + +O `ProposalView.jsx` e o `PDFDocument.jsx` renderizam secções **condicionalmente** com base nos dados. Se um campo é `null`, `[]` ou não existe, a secção NÃO aparece. + +**Regra:** NUNCA assumir que todos os campos existem. Cada proposta pode ter um subconjunto diferente de secções. + +| Campo JSON | Secção web | Secção PDF | Condição | +|-----------|-----------|-----------|----------| +| `context.brandStrategy` | BrandStrategy | PageBrandStrategy | `!= null` | +| `salesData` | SalesChart | PageSales | `.length > 0` | +| `context.diagnosis` | Context | — | `.length > 0` | +| `context.scores` | ScoreGrid | PDFScores | `.length > 0` | +| `service360` | Service360 | PageService360 | `!= null` | +| `plans` | PricingCards | PDFPricing | `.length > 0` | +| `licenses` | LicensePack | PageLicenses | `!= null` | +| `workDone` | WorkDone | PDFWorkDone | `.length > 0` | +| `roadmap` | Roadmap | PDFWorkDone | `.length > 0` | +| `conditions` | Conditions | PDFWorkDone (pág. separada) | `.length > 0` | + +### 3. Título dinâmico — campo `title` no JSON + +O título da proposta (Hero web + capa PDF) vem do campo `title` no JSON: +- Proposta 360°: `"title": "Descomplicar 360°"` +- Migração técnica: `"title": "Migração Bookeo"` +- Website: `"title": "Website Profissional"` +- Fallback: `"Proposta Comercial"` + +**NUNCA** hardcodar "Descomplicar 360°" — usar `data.title`. + +### 4. Preços flexíveis — não assumir mensalidades + +Os planos suportam dois formatos de preço: + +**Mensalidade (avença):** +```json +{ + "monthly": 459, + "hours": 8, + "originalPrice": 540, + "discount": 15 +} +``` +Mostra: "459 €/mês" + "8h/mês incluídas · contrato anual" + +**Preço único (investimento):** +```json +{ + "price": 750, + "priceLabel": "EUR + IVA", + "priceSubtitle": "Investimento único · prazo 1-2 semanas", + "monthly": null, + "hours": null +} +``` +Mostra: "750 EUR + IVA" + "Investimento único · prazo 1-2 semanas" + +**Campos usados:** `plan.price ?? plan.monthly` para o valor, `plan.priceLabel ?? "€/mês"` para a unidade, `plan.priceSubtitle` para a descrição abaixo. + +### 5. react-pdf — bugs conhecidos e PROIBIÇÕES + +| Proibição | Porquê | Alternativa | +|-----------|--------|-------------| +| `gap` + `flexWrap` juntos | Crasha silenciosamente | `marginRight` + `marginBottom` nos items | +| `borderColor` com `rgba()` | Renderiza verde | Cor sólida (ex: `#D4A020`, `#E8E8E8`) | +| Import de componentes SVG (``, ``) | Crasha web worker do PDFDownloadLink | Implementar gráficos inline com `` | +| `Font.register` com fontes locais/CDN em multi-página | Falha silenciosa | Usar Helvetica/Helvetica-Bold (built-in) | +| `href` vazio no PDFDownloadLink | PDF não gerou — verificar consola | Cache do browser — Ctrl+Shift+R | + +### 6. Página 360° (service360) — contextualizar + +A secção service360 no PDF usa o label "O QUE PROPOMOS" (genérico) e o título "As nossas soluções para o seu negócio". Os dados vêm do JSON `service360.areas[]`. + +Para propostas que NÃO são 360°, adaptar os `areas` ao contexto: +- Migração técnica: features da migração +- Website: áreas do serviço web +- SEO: pilares do trabalho SEO + +Se `service360` for `null`, a secção não aparece. + +### 7. Condições comerciais — página separada no PDF + +As condições estão numa página PDF separada (não na mesma que o roadmap) para evitar corte entre páginas. O componente `PDFWorkDone` retorna um Fragment com 2 Pages. + +--- + +## Protocolo + +### Sintaxe + +``` +/proposta-visual [cliente] [tipo-serviço] +``` + +### Fase 1: Análise do contexto + +**ANTES de criar o JSON, responder a estas perguntas:** + +1. **Que tipo de proposta é?** (360°, website, migração técnica, SEO, eCommerce, outro) +2. **O preço é mensal ou único?** → define `monthly` vs `price`/`priceLabel`/`priceSubtitle` +3. **Que secções se aplicam?** → define que campos preencher no JSON +4. **Há dados quantitativos?** (vendas, scores SEO, KPIs) → define `salesData`, `context.scores` +5. **Há trabalho já realizado?** → define `workDone` +6. **Quantas opções de preço?** → define `plans[]` + +**Mapa de secções por tipo de proposta:** + +| Secção | 360° | Website | Migração | SEO | eCommerce | +|--------|:----:|:-------:|:--------:|:---:|:---------:| +| `title` | Descomplicar 360° | Website Profissional | [contexto] | Optimização SEO | Loja Online | +| `brandStrategy` | ✓ | Opcional | — | — | Opcional | +| `salesData` | Se existir | — | — | — | Se existir | +| `scores` | ✓ (audit) | Opcional | — | ✓ (audit) | Opcional | +| `service360` | ✓ | ✓ | ✓ | ✓ | ✓ | +| `plans` | ✓ (3 opções) | ✓ | ✓ | ✓ | ✓ | +| `licenses` | Se aplicável | — | — | — | Se aplicável | +| `workDone` | Se existir | Se existir | ✓ | Se existir | Se existir | +| `roadmap` | ✓ | ✓ | ✓ | ✓ | ✓ | +| `conditions` | ✓ | ✓ | ✓ | ✓ | ✓ | + +### Fase 2: Recolha de dados do CRM + +``` +mcp__desk-crm-v3__search_customers query="[nome]" +mcp__desk-crm-v3__get_customer customer_id=[id] +mcp__desk-crm-v3__get_estimates client_id=[id] +``` + +### Fase 3: Criar ficheiro JSON + +**Localização:** `src/data/[slug].json` + +**Gerar slug:** iniciais do cliente + tipo + hash curto. Ex: `ccv-bookeo-a3f7c1d2` + +**Schema mínimo obrigatório:** + +```json +{ + "title": "Título da Proposta", + "client": { + "name": "Nome Legal Lda.", + "brand": "Nome Comercial", + "website": "exemplo.pt", + "contact": "Nome Contacto", + "email": "email@exemplo.pt", + "phone": "+351 900 000 000" + }, + "company": { + "name": "Descomplicar, Lda.", + "brand": "Descomplicar", + "nif": "514 785 691", + "email": "info@descomplicar.pt", + "phone": "911 510 005", + "website": "descomplicar.pt" + }, + "date": "2026-03-23", + "validDays": 30, + "context": { + "description": "Descrição da situação...", + "diagnosis": [], + "scores": [], + "brandStrategy": null + }, + "service360": null, + "plans": [], + "licenses": null, + "workDone": [], + "roadmap": [], + "conditions": [], + "salesData": [], + "salesProjection": [] +} +``` + +**Campos opcionais para planos com preço único:** +```json +{ + "price": 750, + "priceLabel": "EUR + IVA", + "priceSubtitle": "Investimento único · prazo 1-2 semanas", + "monthly": null, + "hours": null +} +``` + +**Checklist PT-PT antes de guardar o JSON:** +- [ ] Todos os textos têm acentos correctos (ã, ç, ã, é, ê, í, ó, õ, ú) +- [ ] Zero brasileirismos +- [ ] Caractere → (seta) em vez de -> nos textos visíveis +- [ ] Monetário: "EUR" ou "€" (não "R$" nem "$") + +### Fase 4: Registar no App.jsx + +```jsx +import novaData from "./data/[slug].json" + +const proposals = { + // existentes... + "[novo-slug]": novaData, +} +``` + +### Fase 5: Verificar antes do build + +**Checklist pré-build:** +- [ ] JSON válido (sem trailing commas, sem campos undefined) +- [ ] Campos null/[] para secções que não se aplicam (NÃO omitir) +- [ ] `title` definido (não depender do fallback) +- [ ] `plans[].price` OU `plans[].monthly` definido (não ambos null) +- [ ] `plans[].priceLabel` definido se preço único +- [ ] Slug registado em App.jsx +- [ ] Nenhum `flexWrap` + `gap` nos componentes PDF +- [ ] Nenhum `borderColor` com `rgba()` nos componentes PDF + +### Fase 6: Build e deploy + +```bash +cd /media/ealmeida/Dados/Dev/Propostas +npm run build + +# Limpar dist +cd dist +rm -rf assets/template-media assets/template-referencia.pptx assets/slide-referencia.svg +cd assets/brochura && ls *.{jpg,png} 2>/dev/null | grep -v image8.jpg | xargs rm -f 2>/dev/null + +# Empacotar +cd /media/ealmeida/Dados/Dev/Propostas/dist +tar czf /tmp/propostas-dist.tar.gz . + +# Upload + deploy +mcp__ssh-unified__sftp_upload server=easy localPath=/tmp/propostas-dist.tar.gz remotePath=/tmp/propostas-dist.tar.gz overwrite=true +mcp__ssh-unified__ssh_execute server=easy command="cd /opt/propostas && rm -rf assets/* index.html; tar xzf /tmp/propostas-dist.tar.gz && docker service update --force descomplicar_propostas && rm -f /tmp/propostas-dist.tar.gz" + +# Verificar +curl -sI https://propostas.descomplicar.pt/[slug] | head -3 +# Deve retornar HTTP/2 200 + +# Limpar +rm -f /tmp/propostas-dist.tar.gz +``` + +### Fase 7: Testar PDF + +**OBRIGATÓRIO antes de entregar:** +1. Abrir `https://propostas.descomplicar.pt/[slug]` com Ctrl+Shift+R +2. Clicar "Exportar PDF" +3. Verificar que `href` do link não está vazio (PDF gerou) +4. Abrir PDF e verificar: + - [ ] Título correcto (não "Descomplicar 360°" hardcoded) + - [ ] Preços correctos (não "€/mês" se é preço único) + - [ ] Sem borders verdes (rgba renderiza verde no react-pdf) + - [ ] Sem secções que não se aplicam (360°, vendas, licenças, scores) + - [ ] Acentos PT-PT em todo o texto + - [ ] Condições comerciais numa página inteira (sem corte) + - [ ] Todas as 3 opções de preço com layout uniforme + +**Se o PDF não gera (href vazio):** +1. Verificar consola do browser (F12) +2. Causa mais provável: import de componente SVG dos infographics +3. Verificar que PDFDocument não importa de `./infographics/` +4. Verificar que não há `gap` + `flexWrap` no PDF +5. Ctrl+Shift+R e tentar novamente (cache) + +### Fase 8: Entrega e registo + +1. Guardar em `Hub/03-Propostas/[Cliente]/` +2. Registar estimate no CRM (se não existe) +3. Comunicar URL ao utilizador +4. Comentar tarefa CRM + +--- + +## Design system ACIDA 2.0 + +| Token | Valor | +|-------|-------| +| Dourado | #C88900 | +| Dourado claro | #EED59F | +| Dourado border PDF | #D4A020 (usar em vez de rgba no PDF) | +| Dark | #262626 | +| Background | #F8F8F8 | +| Fonte web | Inter (Google Fonts) | +| Fonte PDF | Helvetica / Helvetica-Bold | +| Logo escuro | `/assets/logo-descomplicar.png` | +| Logo claro | `/assets/logo-descomplicar-white.png` | + +--- + +## Propostas existentes + +| Slug | Cliente | Tipo | Data | +|------|---------|------|------| +| `ljm-360-61a8aecc` | A Loja da Maria | 360° (mensal) | 2026-03-20 | +| `ccv-bookeo-a3f7c1d2` | Carvoeiro Caves | Migração técnica (único) | 2026-03-23 | + +--- + +## Skills relacionadas + +- `/proposal-deck` — PPTX standalone (16 layouts, XML editing) +- `/orcamento` — Estimate no CRM (sem visual) +- `/lead-approach` — Estratégia de abordagem de lead +- `/crm` — Operações CRM genéricas + +--- + +## Changelog + +### v2.0.0 (2026-03-23) +- Regras críticas documentadas (7 regras) +- Renderização condicional obrigatória (ProposalView + PDFDocument) +- Título dinâmico via campo `title` no JSON +- Preços flexíveis (mensal vs único) com `price`/`priceLabel`/`priceSubtitle` +- Bugs react-pdf documentados com proibições explícitas +- Mapa de secções por tipo de proposta +- Checklist pré-build e teste PDF obrigatório +- Condições comerciais em página PDF separada + +### v1.0.0 (2026-03-23) +- Versão inicial + +--- + +**Versão:** 2.0.0 | **Data:** 2026-03-23 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/ticket-triage/SKILL.md b/crm-ops/skills/ticket-triage/SKILL.md index 3cf55a5..bb21bb8 100644 --- a/crm-ops/skills/ticket-triage/SKILL.md +++ b/crm-ops/skills/ticket-triage/SKILL.md @@ -169,3 +169,15 @@ Subject contem: --- *Skill v1.0.0 | 04-03-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/crm-ops/skills/ticket/SKILL.md b/crm-ops/skills/ticket/SKILL.md index fb6d6b3..e2d5af8 100644 --- a/crm-ops/skills/ticket/SKILL.md +++ b/crm-ops/skills/ticket/SKILL.md @@ -284,3 +284,15 @@ No checkup diário, mostrar tickets: --- *Skill v1.0.0 | 2026-02-05 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/design-media/skills/brand-guidelines/SKILL.md b/design-media/skills/brand-guidelines/SKILL.md index 42d5940..1248999 100644 --- a/design-media/skills/brand-guidelines/SKILL.md +++ b/design-media/skills/brand-guidelines/SKILL.md @@ -316,3 +316,15 @@ Hashtags/links: #2b6cb0 **Versao**: 1.0.0 | **Data**: 2026-03-10 | **Autor**: Descomplicar® *Paletas detalhadas por contexto: `references/color-palettes.md`* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/design-media/skills/cinematic-site/SKILL.md b/design-media/skills/cinematic-site/SKILL.md new file mode 100644 index 0000000..3600a0b --- /dev/null +++ b/design-media/skills/cinematic-site/SKILL.md @@ -0,0 +1,104 @@ +--- +name: cinematic-site +category: design-media +description: "Constroi websites cinematograficos a partir de um site existente. Pipeline 4 passos: brand analysis, scene generation, build HTML/CSS, preview. Usar quando 'cinematic', 'website premium', 'site cinematografico', 'redesign site', 'nanobanana'." +version: "1.0.0" +created: 2026-04-07 +tools: [Bash, Read, Write, mcp__claude-in-chrome__read_page, mcp__claude-in-chrome__tabs_create_mcp, mcp__chrome-devtools__take_screenshot] +--- + +# Skill: /cinematic-site + +Constroi websites cinematograficos responsivos a partir de um site existente. Inspirado no Nanobanana 2 (#366 Jay E / RoboNuggets). + +--- + +## Pipeline de 4 passos + +### Passo 1 — Brand Analysis + +Receber URL do site existente do utilizador. + +1. Abrir URL via `mcp__claude-in-chrome__tabs_create_mcp` + `mcp__claude-in-chrome__read_page` +2. Extrair: + - Paleta de cores (hex codes das cores dominantes) + - Logo (URL ou descricao) + - Fontes usadas (font-family do CSS) + - Tom de voz (formal, casual, tecnico) + - Tipo de negocio e sector + - Conteudo principal (hero text, servicos, about) +3. Guardar analise em `/tmp/cinematic-site/brand-analysis.json`: + +```json +{ + "url": "https://...", + "business": "restaurante italiano", + "colors": {"primary": "#2C3E50", "secondary": "#E74C3C", "accent": "#F39C12"}, + "fonts": {"heading": "Playfair Display", "body": "Inter"}, + "tone": "acolhedor e premium", + "logo_description": "...", + "hero_text": "...", + "sections": ["sobre", "menu", "reservas", "contacto"] +} +``` + +### Passo 2 — Scene Generation + +Com base na analise, definir o design cinematografico: + +1. **Hero section:** escolher tipo de animacao: + - Parallax com imagem de fundo + - Scroll-reveal progressivo + - Video background concept (descricao, nao video real) + - Cursor-follow effect +2. **3-5 seccoes adicionais** com animacoes scroll-based: + - Referenciar `Hub/04-Stack/02.03-IA/biblioteca-animacoes-scroll.md` para patterns disponiveis +3. **Responsive breakpoints:** mobile-first, 3 breakpoints (mobile, tablet, desktop) +4. Guardar plano em `/tmp/cinematic-site/scene-plan.md` + +### Passo 3 — Build + +Gerar ficheiros HTML/CSS/JS: + +1. Criar `/tmp/cinematic-site/output/`: + - `index.html` — single-page com todas as seccoes + - `styles.css` — Tailwind ou CSS puro + - `animations.js` — scroll observers + animacoes +2. Regras de qualidade: + - Referenciar `design.json` Descomplicar para standards + - Mobile-first + - Core Web Vitals: LCP <2.5s, CLS <0.1 + - Sem dependencias externas pesadas (max framer-motion ou CSS puro) + - Acessibilidade basica (alt text, contraste, focus states) +3. Incluir comentarios no HTML com seccoes claras + +### Passo 4 — Preview + +1. Abrir `index.html` no browser local: `xdg-open /tmp/cinematic-site/output/index.html` +2. Tirar screenshot via `mcp__chrome-devtools__take_screenshot` +3. Mostrar comparacao ao utilizador: + - Site original (URL) + - Novo site (screenshot) +4. Pedir aprovacao antes de qualquer proximo passo +5. Se aprovado, sugerir opcoes: + - Copiar para pasta de projecto + - Ajustar cores/seccoes + - Exportar para Vercel/Netlify (manual) + +--- + +## Regras + +- **Nunca deploy automatico** — apenas preview local +- **Nunca inventar conteudo** — usar texto real do site original +- **Sempre referenciar design.json** para standards visuais +- **Output em /tmp/cinematic-site/** — nunca em pastas de projecto sem aprovacao +- **README.md incluido** com instrucoes de deploy manual + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/design-media/skills/design-b2b/SKILL.md b/design-media/skills/design-b2b/SKILL.md new file mode 100644 index 0000000..65bcfb7 --- /dev/null +++ b/design-media/skills/design-b2b/SKILL.md @@ -0,0 +1,66 @@ +--- +name: design-b2b +description: > + Design system para serviços B2B — agências, consultoria, SaaS, PMEs portuguesas. + Propostas visuais, landing pages, apresentações e materiais para decisores PT. + Usar quando: proposta comercial, landing page serviço B2B, apresentação cliente, + one-pager, ou qualquer material visual para audiência empresarial portuguesa. +--- + +# /design-b2b — Design System Serviços B2B + +## Paleta + +```css +--primary: #1e3a5f; /* Azul institucional — confiança, autoridade */ +--accent: #f97316; /* Laranja acção — CTAs, destaques */ +--neutral: #f8fafc; /* Fundo profissional */ +--text: #1e293b; /* Texto principal */ +--muted: #64748b; /* Texto secundário, legendas */ +--border: #e2e8f0; /* Divisores subtis */ +``` + +## Estrutura proposta comercial + +### One-pager (1 A4 ou landing page equivalente) +1. **Header:** Logo cliente + logo Descomplicar + título proposta +2. **Problema:** 2-3 bullets do problema actual do cliente +3. **Solução:** O que entregamos (concreto, não vago) +4. **Resultados:** Métricas esperadas (%, EUR, tempo) +5. **Investimento:** Preço claro, sem asteriscos escondidos +6. **Próximo passo:** CTA único — "Agendar Reunião" ou "Aceitar Proposta" + +### Landing page serviço B2B +1. Headline: benefício principal (não feature) +2. Sub-headline: para quem é + resultado esperado +3. Prova social: 3 logos de clientes ou 1 case study +4. Serviços: 3-5 cards com ícone + nome + 1 linha +5. Processo: 3-4 passos (simples e claro) +6. CTA: formulário simples (nome, email, empresa, mensagem) + +## Tom e linguagem B2B PT + +- **Usar:** "optimizar", "aumentar eficiência", "reduzir custos" +- **Evitar:** "disruptivo", "revolucionário", "próximo nível" +- **Tratamento:** "Você" (neutro) ou "A sua empresa" — nunca "tu" em contexto formal +- **Números:** sempre com fonte (ex: "30% redução de custos — caso Empresa X") + +## Anti-slop checklist B2B + +- [ ] Zero jargão sem explicação +- [ ] Preços ou "Solicitar orçamento" — nunca ambiguidade +- [ ] Casos reais, não hipotéticos +- [ ] Mobile: decisores usam telemóvel para primeiro contacto +- [ ] Social proof: logo real, não ilustração + +## Referências visuais + +Ver `~/.claude/design/referencias-visuais/servicos-b2b/` + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/design-media/skills/design-ecommerce/SKILL.md b/design-media/skills/design-ecommerce/SKILL.md new file mode 100644 index 0000000..f28d725 --- /dev/null +++ b/design-media/skills/design-ecommerce/SKILL.md @@ -0,0 +1,64 @@ +--- +name: design-ecommerce +description: > + Design system para e-commerce — lojas WooCommerce, páginas produto, checkout PT. + Optimização conversão, layouts loja, UX checkout e elementos de confiança. + Usar quando: criar ou optimizar loja WooCommerce, página produto, carrinho, + checkout, ou qualquer elemento visual de e-commerce para mercado português. +--- + +# /design-ecommerce — Design System E-commerce + +## Paleta base (adaptar à marca do cliente) + +```css +--cta: #dc2626; /* Vermelho urgência — "Comprar Agora" */ +--trust: #16a34a; /* Verde confiança — "Pagamento Seguro" */ +--price: #1e3a5f; /* Azul preço destacado */ +--sale: #f59e0b; /* Âmbar promoção */ +--neutral: #ffffff; +--text: #111827; +``` + +## Elementos conversão obrigatórios + +### Página produto +1. Imagens: mínimo 4 ângulos, zoom, vídeo se possível +2. Preço: destacado, desconto visível, preço original riscado +3. Stock: urgência ("Últimas 3 unidades") +4. CTA: "Adicionar ao Carrinho" (vermelho, proeminente) +5. Confiança: selos Visa/MB/MBWay + devolução 30 dias +6. Avaliações: estrelas + número (social proof) +7. "Também pode gostar" + "Compraram juntos" + +### Checkout PT +- Referência Multibanco visível +- MB Way como opção principal +- Campo NIF opcional (B2B) +- Morada: formato PT (Rua, nº, andar, código postal, localidade) + +### Elementos de confiança PT +- Selos: MBWay, Visa, Mastercard, PayPal +- "Envio para Portugal Continental em 24-48h" +- "Devolução gratuita em 30 dias" +- "Suporte em português" + +## Anti-slop checklist e-commerce + +- [ ] Preços em EUR (não USD) +- [ ] CTAs em PT-PT: "Comprar" não "Buy", "Carrinho" não "Cart" +- [ ] Mobile: checkout testado em 375px (maioria compra no telemóvel) +- [ ] Tempo de carregamento: imagens optimizadas <100KB +- [ ] Trust badges visíveis acima do fold + +## Referências visuais + +Ver `~/.claude/design/referencias-visuais/ecommerce/` + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/design-media/skills/design-saude/SKILL.md b/design-media/skills/design-saude/SKILL.md new file mode 100644 index 0000000..6a62b90 --- /dev/null +++ b/design-media/skills/design-saude/SKILL.md @@ -0,0 +1,62 @@ +--- +name: design-saude +description: > + Design system para sector saúde — clínicas, KiviCare, consultórios médicos. + Paleta, tipografia, CTAs e layouts optimizados para contexto clínico PT. + Usar quando: criar landing page de clínica, página de serviços médicos, + agendamento online, ou qualquer material visual para clientes saúde. +--- + +# /design-saude — Design System Saúde + +## Paleta + +```css +--primary: #0ea5e9; /* Azul confiança médica */ +--secondary: #10b981; /* Verde saúde/cura */ +--neutral: #f8fafc; /* Fundo limpo e asséptico */ +--text: #1e293b; /* Texto principal */ +--accent: #f59e0b; /* CTA urgência (marcar consulta) */ +--danger: #ef4444; /* Alertas, urgências */ +``` + +## Tipografia + +- **Títulos:** Inter SemiBold — transmite profissionalismo sem frieza +- **Corpo:** Inter Regular 16px, line-height 1.7 — legibilidade para público 40+ +- **Evitar:** fontes decorativas, cursivas, serifas antiquadas + +## Layouts obrigatórios + +### Landing page clínica +1. Hero: foto médico real + headline "Cuidamos de si" + CTA "Marcar Consulta" +2. Serviços: cards com ícone + nome + preço (se disponível) +3. Equipa: fotos reais + credenciais +4. Depoimentos: com nome e tratamento (anonimizado se necessário) +5. Localização + horários + contacto +6. CTA final: WhatsApp ou formulário + +### CTAs saúde +- Principal: "Marcar Consulta" (verde, proeminente) +- Secundário: "Saber Mais" ou "Ver Serviços" +- Urgência: "Consulta Hoje" (âmbar) + +## Anti-slop checklist saúde + +- [ ] Fotos de pessoas reais (não stock de médicos brancos genéricos) +- [ ] RGPD: sem dados de pacientes visíveis em mockups +- [ ] Cores acessíveis: contraste WCAG AA mínimo +- [ ] Mobile: formulário agendamento testado em 375px +- [ ] PT-PT: "consulta" não "appointment", "médico" não "doctor" + +## Referências visuais + +Ver `~/.claude/design/referencias-visuais/saude/` + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/design-media/skills/design-solar/SKILL.md b/design-media/skills/design-solar/SKILL.md new file mode 100644 index 0000000..f0da622 --- /dev/null +++ b/design-media/skills/design-solar/SKILL.md @@ -0,0 +1,60 @@ +--- +name: design-solar +description: > + Design system para sector solar/fotovoltaico — SolarFV, instaladores, B2B energia. + Paleta, calculadoras, propostas visuais e layouts para sector energias renováveis PT. + Usar quando: landing page solar, proposta instalação FV, calculadora poupança, + ou material visual para clientes energia solar. +--- + +# /design-solar — Design System Solar/FV + +## Paleta + +```css +--primary: #f59e0b; /* Amarelo solar — energia, optimismo */ +--secondary: #1e3a5f; /* Azul escuro — confiança, profissionalismo B2B */ +--green: #16a34a; /* Verde sustentabilidade */ +--neutral: #f9fafb; /* Fundo limpo */ +--text: #111827; /* Texto principal */ +``` + +## Elementos distintivos sector solar + +### Calculadora de poupança (elemento central) +- Input: consumo mensal kWh + factura actual +- Output: poupança anual estimada + payback em anos +- Visual: comparação antes/depois com gráfico simples + +### Proposta instalação +1. Sumário executivo (1 página): consumo actual → produção estimada → ROI +2. Especificações técnicas: painéis, inversor, capacidade +3. Financiamento: opções (compra, leasing, PPA) +4. Garantias e certificações +5. CTA: "Solicitar Visita Técnica" + +## Tipografia + +- **Títulos:** Poppins Bold — moderno, energético +- **Dados/métricas:** Inter Mono — leiturabilidade para números +- **Corpo:** Inter Regular + +## Anti-slop checklist solar + +- [ ] Números reais de produção (não inventar kWh) +- [ ] Certificações visíveis (DGEG, SCE) +- [ ] Mobile: calculadora funcional em 375px +- [ ] B2B: tom técnico e sóbrio (não "salve o planeta") +- [ ] PT: "fotovoltaico" não "fotovoltaica" (painel fotovoltaico) + +## Referências visuais + +Ver `~/.claude/design/referencias-visuais/solar/` + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/design-media/skills/design/SKILL.md b/design-media/skills/design/SKILL.md index 05a1e9a..d9ffc59 100644 --- a/design-media/skills/design/SKILL.md +++ b/design-media/skills/design/SKILL.md @@ -154,3 +154,15 @@ fidelidade, concisao visual, legibilidade, profissionalismo, brand compliance. --- **Versao**: 2.0.0 | **Data**: 2026-02-12 | **Autor**: Descomplicar + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/design-media/skills/penpot-pipeline/SKILL.md b/design-media/skills/penpot-pipeline/SKILL.md new file mode 100644 index 0000000..4da2e0c --- /dev/null +++ b/design-media/skills/penpot-pipeline/SKILL.md @@ -0,0 +1,168 @@ +--- +name: penpot-pipeline +description: > + Pipeline Penpot→código: extrai designs do Penpot via MCP, converte para HTML/CSS/React. + Usar quando: converter mockup Penpot para código, gerar componente a partir de design, + exportar assets Penpot, sincronizar design system com código. +--- + +# /penpot-pipeline — Pipeline Design→Código + +Workflow formalizado para converter designs Penpot em código funcional. +O MCP Penpot já existe (`mcp__penpot__*`) — esta skill formaliza o workflow. + +--- + +## Workflow Completo + +### Passo 1 — Encontrar o Design + +```javascript +// Listar projectos Penpot +mcp__penpot__list_projects({}) + +// Listar ficheiros no projecto +mcp__penpot__get_project_files({ project_id: "" }) + +// Buscar componente específico +mcp__penpot__search_object({ + file_id: "", + query: "" +}) +``` + +### Passo 2 — Analisar Estrutura + +```javascript +// Schema disponível (ler uma vez por sessão) +mcp__penpot__penpot_tree_schema({}) + +// Árvore do componente com screenshot +mcp__penpot__get_object_tree({ + file_id: "", + object_id: "", + depth: 3 +}) + +// Screenshot visual de alta resolução +mcp__penpot__get_rendered_component({ + file_id: "", + object_id: "" +}) +``` + +### Passo 3 — Gerar Código + +Com base na árvore + screenshot, gerar código na stack alvo: + +#### HTML + CSS (vanilla) +``` +- Usar variáveis CSS para cores/fonts do design system +- Mobile-first (375px → 768px → 1200px) +- Nomes de classes: BEM (block__element--modifier) +- Acessibilidade: aria-labels, roles semânticos +``` + +#### React + TailwindCSS +``` +- Componente funcional com TypeScript +- Props tipadas +- Variantes via className condicional +- Shadcn/ui para primitivos (Button, Card, Input) +- Tailwind classes da paleta Descomplicar ou do cliente +``` + +#### Next.js (Server Component por defeito) +``` +- Server Component se sem interactividade +- Client Component ('use client') apenas para eventos +- Image: next/image com alt e sizes +- Link: next/link +``` + +### Passo 4 — Exportar Assets + +```javascript +// Exportar imagem/icon do design +mcp__penpot__export_object({ + file_id: "", + object_id: "", + format: "svg" // svg | png | pdf +}) +``` + +### Passo 5 — Auditoria 10/10 + +Antes de entregar código (Regra #49): +- [ ] Segurança: sem XSS, sem dados expostos +- [ ] Performance: imagens optimizadas, lazy loading +- [ ] Acessibilidade: contraste, labels, keyboard nav +- [ ] Mobile: testado em 375px +- [ ] PT-PT: texto em português europeu + +--- + +## Design System Descomplicar → Código + +```css +/* design.json → variáveis CSS */ +--color-primary: #1e3a5f; +--color-accent: #f97316; +--color-neutral: #f8fafc; +--color-text: #1e293b; +--color-muted: #64748b; +--font-heading: 'Inter', sans-serif; +--font-body: 'Inter', sans-serif; +``` + +```tsx +// Tailwind config (tailwind.config.ts) +colors: { + primary: '#1e3a5f', + accent: '#f97316', + neutral: '#f8fafc', +} +``` + +--- + +## Casos de Uso + +### Landing page de serviço +``` +1. mcp__penpot__search_object — encontrar frames "Hero", "Features", "CTA" +2. get_object_tree para cada frame +3. get_rendered_component para referência visual +4. Gerar HTML/CSS seguindo /design-b2b ou /design-saude +5. Integrar em WP (Elementor) ou Next.js +``` + +### Componente React isolado +``` +1. search_object — encontrar componente +2. get_object_tree com depth=5 (para componentes complexos) +3. Gerar TSX com props +4. Exportar assets SVG +5. Publicar em /components da biblioteca +``` + +--- + +## Anti-Patterns + +- **Nunca** gerar código sem ver o screenshot (get_rendered_component) +- **Nunca** assumir cores sem verificar design.json ou paleta do cliente +- **Nunca** entregar sem testar mobile (375px) +- **Nunca** hardcodar texto — usar variáveis/props + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +--- + +*Skill /penpot-pipeline v1.0 | 06-04-2026 | Eixo 5.5 — Pipeline Penpot→Código* diff --git a/dev-tools/skills/benchmark/SKILL.md b/dev-tools/skills/benchmark/SKILL.md new file mode 100644 index 0000000..b13b8d8 --- /dev/null +++ b/dev-tools/skills/benchmark/SKILL.md @@ -0,0 +1,124 @@ +--- +name: benchmark +description: > + Mede Core Web Vitals e performance antes/depois de alterações. Detecta regressões. + Usar antes e depois de qualquer alteração a WP, WooCommerce, Next.js ou infra. + Baseado no gstack /benchmark. Eixo 2B. +--- + +# /benchmark — Performance Antes/Depois + +Medir o impacto real de alterações. Nunca fazer deploy sem benchmark. + +--- + +## Quando Usar + +- Antes de qualquer optimização de performance +- Antes de deploy de plugins/temas WordPress +- Antes de alterações ao servidor ou cache +- Antes de implementar nova feature em produção +- Como baseline mensal de cada site + +--- + +## Métricas Alvo (Core Web Vitals 2024) + +| Métrica | Bom | Precisa Melhorar | Mau | +|---------|-----|-----------------|-----| +| LCP (Largest Contentful Paint) | ≤2.5s | 2.5-4.0s | >4.0s | +| FID / INP (Interaction to Next Paint) | ≤200ms | 200-500ms | >500ms | +| CLS (Cumulative Layout Shift) | ≤0.1 | 0.1-0.25 | >0.25 | +| TTFB (Time to First Byte) | ≤800ms | 800-1800ms | >1800ms | +| FCP (First Contentful Paint) | ≤1.8s | 1.8-3.0s | >3.0s | + +--- + +## Protocolo + +### Passo 1 — Baseline (ANTES) + +```bash +# Via MCP Lighthouse (se disponível) +mcp__lighthouse__get_core_web_vitals({ url: "" }) +mcp__lighthouse__run_audit({ url: "", categories: ["performance"] }) + +# Ou via Lighthouse CLI no servidor +ssh server "lighthouse --output=json --output-path=/tmp/before.json --chrome-flags='--headless'" + +# Ou via PageSpeed Insights API +curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=&strategy=mobile" | jq '.lighthouseResult.categories.performance.score' +``` + +**Guardar baseline:** +```bash +BEFORE_LCP= +BEFORE_CLS= +BEFORE_FCP= +BEFORE_SCORE= +``` + +### Passo 2 — Executar Alteração + +Fazer a alteração (deploy, optimização, plugin, etc.) + +### Passo 3 — Depois + +```bash +# Repetir as mesmas medições +mcp__lighthouse__get_core_web_vitals({ url: "" }) + +AFTER_LCP= +AFTER_CLS= +AFTER_FCP= +AFTER_SCORE= +``` + +### Passo 4 — Comparação + +```markdown +## Benchmark — [Site] — [Data] + +| Métrica | Antes | Depois | Delta | Estado | +|---------|-------|--------|-------|--------| +| LCP | Xs | Ys | ±Zs | ✅/⚠️/❌ | +| CLS | X | Y | ±Z | ✅/⚠️/❌ | +| FCP | Xs | Ys | ±Zs | ✅/⚠️/❌ | +| Score | X% | Y% | ±Z% | ✅/⚠️/❌ | + +**Veredicto:** MELHOROU / NEUTRO / REGREDIU +**Acção:** Manter deploy / Reverter / Investigar +``` + +--- + +## Regras de Decisão + +``` +SE qualquer métrica piorou >10% → REVERTER imediatamente +SE Score global piorou >5 pontos → investigar antes de continuar +SE CLS aumentou >0.05 → bloquear — UX crítica +SE LCP piorou >500ms em mobile → reverter +``` + +--- + +## Sites Descomplicar a Monitorizar + +| Site | URL | Frequência | +|------|-----|-----------| +| Descomplicar main | descomplicar.pt | Mensal | +| Clip | clip.descomplicar.pt | Após cada deploy | +| Outros clientes | variável | Após alterações WP | + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +--- + +*Skill /benchmark v1.0 | 06-04-2026 | Eixo 2B — gstack pattern* diff --git a/dev-tools/skills/canary/SKILL.md b/dev-tools/skills/canary/SKILL.md new file mode 100644 index 0000000..30e03c9 --- /dev/null +++ b/dev-tools/skills/canary/SKILL.md @@ -0,0 +1,155 @@ +--- +name: canary +description: > + Monitorização pós-deploy — detecta regressões em produção. Verifica que o deploy + não quebrou nada crítico nos 15min seguintes. Baseado no gstack /canary. Eixo 2B. + Usar após qualquer deploy em produção. +--- + +# /canary — Monitorização Pós-Deploy + +Os primeiros 15 minutos após um deploy são os mais críticos. Esta skill verifica que tudo está OK. + +--- + +## Quando Usar (SEMPRE após deploy produção) + +- Após deploy de código em produção +- Após actualização de WordPress (core, plugins, temas) +- Após alterações de servidor (PHP, Nginx, MySQL) +- Após mudanças de DNS ou SSL +- Após activação de nova funcionalidade + +--- + +## Protocolo (15 minutos) + +### Minuto 0-2 — Status Checks + +```bash +# 1. Site responde? +curl -s -o /dev/null -w "%{http_code}" / +# Esperado: 200 + +# 2. Admin WP responde? +curl -s -o /dev/null -w "%{http_code}" /wp-admin/ +# Esperado: 200 ou 302 + +# 3. SSL válido? +curl -vI 2>&1 | grep "SSL certificate verify" +# Esperado: SSL certificate verify ok + +# 4. Tempo de resposta aceitável? +curl -s -o /dev/null -w "%{time_total}\n" / +# Esperado: < 3.0 segundos +``` + +### Minuto 2-5 — Funcionalidades Críticas + +**Para WordPress:** +```bash +# Página principal carrega sem erros +curl -s / | grep -c "wp-content" +# Esperado: > 0 + +# Sem erro crítico PHP +curl -s / | grep -i "fatal error\|parse error\|warning" +# Esperado: sem output + +# WP-CLI status +wp --path=/var/www/html core verify-checksums 2>&1 | tail -1 +# Esperado: "WordPress installation verifies against checksums." +``` + +**Para aplicações:** +```bash +# Health endpoint +curl -s /api/health | jq '.status' +# Esperado: "ok" + +# Database conecta? +curl -s /api/health | jq '.database' +# Esperado: "connected" +``` + +### Minuto 5-10 — Métricas de Performance + +```javascript +// Via Lighthouse MCP +mcp__lighthouse__get_performance_score({ url: "" }) +// Esperado: >= baseline (ver /benchmark) + +mcp__lighthouse__get_core_web_vitals({ url: "" }) +// Comparar com baseline guardado +``` + +### Minuto 10-15 — Logs e Erros + +```bash +# Erros PHP nas últimas 15 min +ssh server "tail -100 /var/log/php/error.log | grep '$(date -d '15 minutes ago' +%H:%M)'" + +# Erros Nginx/Apache +ssh server "tail -50 /var/log/nginx/error.log" + +# WooCommerce (se aplicável) +wp --path=/var/www/html wc log list 2>&1 | head -20 +``` + +--- + +## Output — Relatório Canary + +```markdown +## Canary Check — [Site] — [Data] [Hora] + +**Deploy:** [O que foi alterado] + +| Check | Estado | Detalhe | +|-------|--------|---------| +| HTTP 200 | ✅/❌ | | +| SSL | ✅/❌ | | +| Tempo resposta | ✅/❌ | Xs | +| Sem erros PHP | ✅/❌ | | +| Performance score | ✅/❌ | X% (base: Y%) | +| Logs limpos | ✅/❌ | | + +**Resultado:** ✅ DEPLOY ESTÁVEL | ⚠️ INVESTIGAR | ❌ REVERTER +``` + +--- + +## Critérios de Reversão Imediata + +``` +❌ HTTP response != 200 → REVERTER +❌ SSL falha → REVERTER +❌ "Fatal error" em qualquer página → REVERTER +❌ Tempo resposta > 10s → INVESTIGAR +❌ Performance score caiu >15 pontos → INVESTIGAR +❌ Logs com erros críticos → INVESTIGAR +``` + +--- + +## Escalada Automática + +Se algum check falha: +``` +1. NOTIFICAR: criar issue no Desk CRM com urgência P1 +2. REVERTER: se erro crítico, reverter imediatamente +3. DOCUMENTAR: o que falhou e quando +4. ANALISAR: root cause antes de re-deploy +``` + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +--- + +*Skill /canary v1.0 | 06-04-2026 | Eixo 2B — gstack pattern* diff --git a/dev-tools/skills/chrome/SKILL.md b/dev-tools/skills/chrome/SKILL.md index cf44496..57acc2d 100644 --- a/dev-tools/skills/chrome/SKILL.md +++ b/dev-tools/skills/chrome/SKILL.md @@ -301,3 +301,15 @@ Activar Chrome por defeito **aumenta consumo de context window** porque as ferra 1. Desactivar default: `/chrome` -> desactivar 2. Usar `claude --chrome` apenas quando necessario 3. Preferir WebFetch para leituras simples de paginas publicas + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/db-design/SKILL.md b/dev-tools/skills/db-design/SKILL.md index d3d89b8..4ea0f79 100644 --- a/dev-tools/skills/db-design/SKILL.md +++ b/dev-tools/skills/db-design/SKILL.md @@ -241,3 +241,15 @@ Output: [resultado esperado] Input: [caso complexo] Output: [resultado detalhado] ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/dep-audit/SKILL.md b/dev-tools/skills/dep-audit/SKILL.md index 6c5644d..c15f26d 100644 --- a/dev-tools/skills/dep-audit/SKILL.md +++ b/dev-tools/skills/dep-audit/SKILL.md @@ -461,3 +461,15 @@ git commit **Skill v1.1** | 12-03-2026 | Descomplicar® | Renomeado de /security-check para /dep-audit **Security First** - Zero vulnerabilities ou documentadas + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/diagrama/SKILL.md b/dev-tools/skills/diagrama/SKILL.md new file mode 100644 index 0000000..4618b8a --- /dev/null +++ b/dev-tools/skills/diagrama/SKILL.md @@ -0,0 +1,267 @@ +--- +name: diagrama +category: dev-tools +description: "Gera diagramas de arquitectura, fluxo, ER e sequência em três formatos: draw.io (.drawio), Excalidraw e Mermaid. Usar quando 'diagrama', 'arquitectura', 'draw.io', 'fluxo', 'ER', 'sequência', 'infra', 'componentes'." +version: "1.0.0" +created: 2026-04-04 +tools: [mcp__claude_ai_Excalidraw__export_to_excalidraw, mcp__mcp-mermaid__generate, Write, Bash] +--- + +# Skill: /diagrama + +Gera diagramas técnicos em três formatos consoante o caso de uso. Suporta arquitectura de sistemas, fluxogramas, diagramas ER, sequência, infra-estrutura e redes. + +--- + +## Quando usar cada formato + +| Formato | Quando usar | Output | +|---------|------------|--------| +| **draw.io** | Diagramas formais para documentação, propostas, clientes | `.drawio` (editável) | +| **Excalidraw** | Esboços rápidos, brainstorming visual, estilo whiteboard | `.excalidraw` / MCP | +| **Mermaid** | Diagramas como código, versionáveis em Git, embeds Markdown | `.svg` / `.png` | + +--- + +## Processo de execução + +### 1. Identificar pedido + +Quando o utilizador pede um diagrama, detectar: +- **Tipo:** arquitectura | fluxo | ER | sequência | rede | organograma | classe +- **Formato pretendido:** draw.io (default para doc. formal) | excalidraw | mermaid +- **Contexto:** sistemas envolvidos, entidades, actores + +Se não especificado, perguntar apenas: "draw.io (formal) ou Excalidraw (esboço)?" + +### 2. Gerar conteúdo + +--- + +## Geração draw.io (.drawio) + +O formato draw.io é mxGraph XML. Gerar o XML e guardar como `.drawio`. + +### Estrutura base + +```xml + + + + + + + + + + + +``` + +### Templates de elementos mxGraph + +**Rectângulo (componente/serviço):** +```xml + + + +``` + +**Seta/ligação:** +```xml + + + +``` + +**Cilindro (base de dados):** +```xml + + + +``` + +**Cloud (serviço externo):** +```xml + + + +``` + +**Actor (pessoa/utilizador):** +```xml + + + +``` + +**Swimlane (grupo/camada):** +```xml + + + +``` + +### Paleta de cores Descomplicar + +| Componente | fillColor | strokeColor | +|-----------|-----------|-------------| +| Serviço/App | `#dae8fc` | `#6c8ebf` | +| Base de dados | `#f8cecc` | `#b85450` | +| Fila/Queue | `#d5e8d4` | `#82b366` | +| Externo/Cloud | `#fff2cc` | `#d6b656` | +| Infra/Servidor | `#e1d5e7` | `#9673a6` | +| Claude/IA | `#f0f4ff` | `#4a6cf7` | + +### Guardar ficheiro + +Guardar em `/media/ealmeida/Dados/Hub/tmp/diagramas/` com nome descritivo: +``` +YYYY-MM-DD-nome-diagrama.drawio +``` + +Abrir com: +```bash +drawio "/media/ealmeida/Dados/Hub/tmp/diagramas/NOME.drawio" & +``` +(ou abrir manualmente com draw.io desktop / draw.io no browser) + +--- + +## Geração Excalidraw + +Usar o MCP `mcp__claude_ai_Excalidraw__export_to_excalidraw` para diagramas no estilo whiteboard. + +### Fluxo + +1. Chamar `mcp__claude_ai_Excalidraw__create_view` para iniciar sessão +2. Chamar `mcp__claude_ai_Excalidraw__export_to_excalidraw` com o conteúdo estruturado +3. Informar o utilizador do link/path gerado + +### Casos de uso preferidos + +- Brainstorming e exploração rápida +- Diagramas de fluxo com estilo manual +- Esboços para reuniões +- Arquitecturas de alto nível para comunicação interna + +--- + +## Geração Mermaid + +Usar o MCP `mcp__mcp-mermaid__generate` para diagramas como código. + +### Tipos suportados + +**Fluxograma:** +``` +flowchart TD + A[Início] --> B{Condição} + B -->|Sim| C[Acção] + B -->|Não| D[Fim] +``` + +**Sequência:** +``` +sequenceDiagram + participant U as Utilizador + participant A as Claude Code + participant N as n8n + U->>A: Pedido + A->>N: Trigger workflow + N-->>A: Resultado + A-->>U: Resposta +``` + +**ER:** +``` +erDiagram + CLIENTE ||--o{ PROJECTO : tem + PROJECTO ||--o{ TAREFA : contém + TAREFA { + int id + string nome + string estado + } +``` + +**Arquitectura de componentes (C4):** +``` +C4Context + title Stack Descomplicar + Person(eal, "Emanuel", "Utilizador principal") + System(cc, "Claude Code", "Interface interactiva") + System(clip, "Paperclip", "Agentes autónomos") + System(n8n, "n8n", "Automação determinística") + Rel(eal, cc, "usa directamente") + Rel(cc, clip, "delega tarefas complexas") + Rel(cc, n8n, "activa workflows") +``` + +### Guardar output + +Guardar o código Mermaid em `/media/ealmeida/Dados/Hub/tmp/diagramas/NOME.mmd` e renderizar para SVG/PNG via MCP. + +--- + +## Templates prontos por contexto + +### Arquitectura StackDescomplicar + +Gerar diagrama com as três camadas do stack: +- **Camada 1:** Claude Code (trabalho interactivo) +- **Camada 2:** n8n (automação determinística) +- **Camada 3:** Paperclip (raciocínio autónomo) + +### Proposta comercial + +Diagrama da solução para o cliente com: +- Infra-estrutura actual (antes) +- Solução proposta (depois) +- Componentes e integrações + +### Pipeline de dados + +Diagrama de fluxo com: +- Fonte → Processamento → Destino +- Triggers, transformações, outputs + +### Diagrama ER Desk CRM + +Entidades principais: Lead → Customer → Estimate → Invoice → Payment + +--- + +## Boas práticas + +- **Máx. 10-15 elementos** por diagrama (mais → dividir em sub-diagramas) +- **Labels curtos:** 2-4 palavras por elemento +- **Setas com label** quando o fluxo não é óbvio +- **Cor consistente** por tipo de componente (seguir paleta Descomplicar) +- **Nome descritivo** no ficheiro (não "diagrama1.drawio") +- **Guardar em Hub/tmp/diagramas/** para fácil acesso + +--- + +## Instalar draw.io MCP (opcional, para funcionalidades avançadas) + +O vídeo #210 do Stack_Pesquisa_Videos.md demonstra um MCP draw.io com geração automática a partir de análise de código. Para instalar: + +```bash +# Verificar se há MCP draw.io disponível no gateway +# Ver: Hub/04-Stack/claude-code-context-hygiene.md → secção MCPs +``` + +Alternativa: usar draw.io via browser em https://app.diagrams.net (gratuito, sem instalação) e importar o `.drawio` gerado. + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/docx/SKILL-light.md b/dev-tools/skills/docx/SKILL-light.md new file mode 100644 index 0000000..8a47a25 --- /dev/null +++ b/dev-tools/skills/docx/SKILL-light.md @@ -0,0 +1,159 @@ +--- +name: docx +description: "Criação, edição e análise de documentos Word (.docx). Versão light para heartbeats." +--- + +# DOCX — Referência Rápida + +## Referência rápida + +| Tarefa | Abordagem | +|--------|-----------| +| Ler conteúdo | `pandoc` ou descompactar XML | +| Criar novo | `docx-js` (npm install -g docx) | +| Editar existente | Descompactar → editar XML → recompactar | +| Converter .doc | `python scripts/office/soffice.py --headless --convert-to docx doc.doc` | + +## Criar novos documentos (docx-js) + +### Setup básico + +```javascript +const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun, + Header, Footer, AlignmentType, PageOrientation, LevelFormat, HeadingLevel, + BorderStyle, WidthType, ShadingType, PageNumber, PageBreak } = require('docx'); + +const doc = new Document({ sections: [{ children: [/* conteúdo */] }] }); +Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer)); +``` + +### Tamanho de página (A4) + +```javascript +sections: [{ + properties: { + page: { + size: { width: 11906, height: 16838 }, // A4 em DXA + margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } + } + }, + children: [/* conteúdo */] +}] +``` + +Largura de conteúdo A4 com margens 1": `11906 - 2880 = 9026 DXA` + +**Paisagem:** Passar dimensões retrato + `orientation: PageOrientation.LANDSCAPE` (docx-js troca internamente). + +### Listas + +```javascript +numbering: { config: [ + { reference: "bullets", levels: [{ level: 0, format: LevelFormat.BULLET, text: "\u2022", + alignment: AlignmentType.LEFT, style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] } +] } +// Usar: new Paragraph({ numbering: { reference: "bullets", level: 0 }, children: [...] }) +``` + +### Tabelas + +```javascript +// Largura tabela = soma columnWidths. Usar SEMPRE WidthType.DXA (nunca PERCENTAGE). +new Table({ + width: { size: 9026, type: WidthType.DXA }, + columnWidths: [4513, 4513], + rows: [new TableRow({ children: [ + new TableCell({ + borders: { top: b, bottom: b, left: b, right: b }, + width: { size: 4513, type: WidthType.DXA }, + shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR, nunca SOLID + margins: { top: 80, bottom: 80, left: 120, right: 120 }, + children: [new Paragraph({ children: [new TextRun("Célula")] })] + }) + ] })] +}) +``` + +### Imagens + +```javascript +new ImageRun({ + type: "png", // Obrigatório + data: fs.readFileSync("image.png"), + transformation: { width: 200, height: 150 }, + altText: { title: "T", description: "D", name: "N" } // Três obrigatórios +}) +``` + +### Cabeçalhos/rodapés + +```javascript +headers: { default: new Header({ children: [new Paragraph({ children: [new TextRun("Cabeçalho")] })] }) }, +footers: { default: new Footer({ children: [new Paragraph({ + children: [new TextRun("Página "), new TextRun({ children: [PageNumber.CURRENT] })] +})] }) } +``` + +### Regras críticas docx-js + +- Nunca usar `\n` — usar Paragraphs separados +- Nunca usar bullets unicode — usar `LevelFormat.BULLET` +- PageBreak dentro de Paragraph: `new Paragraph({ children: [new PageBreak()] })` +- ImageRun requer `type` +- Tabelas: `columnWidths` E `width` na célula, ambos devem corresponder +- Usar `ShadingType.CLEAR`, nunca SOLID +- TOC requer `HeadingLevel` apenas, sem estilos custom +- Override estilos: IDs exactos "Heading1", "Heading2" + `outlineLevel` + +## Editar documentos existentes + +### Passo 1: Descompactar + +```bash +python scripts/office/unpack.py document.docx unpacked/ +``` + +### Passo 2: Editar XML + +Editar ficheiros em `unpacked/word/`. Usar ferramenta Edit directamente (não scripts Python). + +**Tracked changes:** +```xml + + + texto inserido + + + + + texto eliminado + +``` + +**Comentários:** +```bash +python scripts/comment.py unpacked/ 0 "Texto do comentário" +python scripts/comment.py unpacked/ 1 "Resposta" --parent 0 +``` + +**Smart quotes:** `‘` `’` `“` `”` + +### Passo 3: Recompactar + +```bash +python scripts/office/pack.py unpacked/ output.docx --original document.docx +``` + +Validação: `python scripts/office/validate.py doc.docx` + +## Convenções Descomplicar + +- Data: DD-MM-YYYY +- Monetário: 1.234,56 EUR +- Fonte: Arial 12pt +- Página: A4 (11906 x 16838 DXA) +- Autor tracked changes: "Claude" +- Idioma: PT-PT + +--- +**Versão**: 1.0.0-light | **Base**: 1.0.0 diff --git a/dev-tools/skills/docx/SKILL.md b/dev-tools/skills/docx/SKILL.md index b000879..dbbcc01 100644 --- a/dev-tools/skills/docx/SKILL.md +++ b/dev-tools/skills/docx/SKILL.md @@ -510,3 +510,15 @@ Apos executar `comment.py` (ver Passo 2), adicionar marcadores ao document.xml. --- **Versao**: 1.0.0 | **Autor**: Descomplicar® + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/nextjs/SKILL.md b/dev-tools/skills/nextjs/SKILL.md index a754edb..0fe391c 100644 --- a/dev-tools/skills/nextjs/SKILL.md +++ b/dev-tools/skills/nextjs/SKILL.md @@ -218,3 +218,15 @@ CMD ["npm", "start"] --- *Versão 1.0.0 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/pdf/SKILL-light.md b/dev-tools/skills/pdf/SKILL-light.md new file mode 100644 index 0000000..fd81682 --- /dev/null +++ b/dev-tools/skills/pdf/SKILL-light.md @@ -0,0 +1,160 @@ +--- +name: pdf +description: Processamento de ficheiros PDF — leitura, extracção, merge, split, OCR, formulários. Versão light para heartbeats. +--- + +# PDF — Referência Rápida + +## Bibliotecas Python + +### pypdf — operações básicas + +```python +from pypdf import PdfReader, PdfWriter + +# Ler e extrair texto +reader = PdfReader("documento.pdf") +for page in reader.pages: + text = page.extract_text() + +# Merge +writer = PdfWriter() +for pdf in ["doc1.pdf", "doc2.pdf"]: + for page in PdfReader(pdf).pages: + writer.add_page(page) +with open("merged.pdf", "wb") as f: + writer.write(f) + +# Split (uma página por ficheiro) +for i, page in enumerate(reader.pages): + w = PdfWriter() + w.add_page(page) + with open(f"page_{i+1}.pdf", "wb") as f: + w.write(f) + +# Rotate +page = reader.pages[0] +page.rotate(90) + +# Password +writer.encrypt("userpass", "ownerpass") +``` + +### pdfplumber — tabelas e texto com layout + +```python +import pdfplumber + +with pdfplumber.open("doc.pdf") as pdf: + for page in pdf.pages: + text = page.extract_text() + tables = page.extract_tables() +``` + +### reportlab — criação de PDFs + +```python +from reportlab.platypus import SimpleDocTemplate, Paragraph, Table, TableStyle, PageBreak +from reportlab.lib.styles import getSampleStyleSheet +from reportlab.lib import colors + +doc = SimpleDocTemplate("report.pdf") +styles = getSampleStyleSheet() +elements = [Paragraph("Título", styles['Title'])] +doc.build(elements) +``` + +**Subscripts/superscripts:** Nunca usar caracteres Unicode. Usar tags XML: `2`, `2`. + +## CLI + +```bash +# Extrair texto (poppler-utils) +pdftotext input.pdf output.txt +pdftotext -layout input.pdf output.txt + +# Merge/split (qpdf) +qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf +qpdf input.pdf --pages . 1-5 -- pages1-5.pdf + +# Encriptar +qpdf --encrypt user_pass owner_pass 256 -- input.pdf encrypted.pdf + +# Reparar +qpdf --check input.pdf + +# Extrair imagens +pdfimages -j input.pdf output_prefix + +# Render para PNG +pdftoppm -png -r 300 document.pdf output_prefix +``` + +## OCR (PDFs digitalizados) + +```python +import pytesseract +from pdf2image import convert_from_path + +images = convert_from_path('scanned.pdf') +text = "" +for image in images: + text += pytesseract.image_to_string(image) +``` + +## Formulários + +### Verificar campos preenchíveis + +```bash +python scripts/check_fillable_fields.py +``` + +### Campos preenchíveis (nativos) + +1. `python scripts/extract_form_field_info.py ` +2. `python scripts/convert_pdf_to_images.py ` +3. Criar `field_values.json` com `field_id`, `page`, `value` +4. `python scripts/fill_fillable_fields.py ` + +### Campos não preenchíveis (anotações) + +1. `python scripts/extract_form_structure.py form_structure.json` +2. **Abordagem A (estrutura):** Analisar JSON, criar `fields.json` com `pdf_width`/`pdf_height` e bounding boxes +3. **Abordagem B (visual):** Converter para imagens, identificar campos, refinar com crop +4. `python scripts/check_bounding_boxes.py fields.json` +5. `python scripts/fill_pdf_form_with_annotations.py fields.json ` +6. `python scripts/create_validation_image.py ` + +## Referência rápida + +| Tarefa | Ferramenta | Comando | +|--------|-----------|---------| +| Merge | pypdf/qpdf | `writer.add_page()` / `qpdf --pages` | +| Split | pypdf/qpdf | Uma página por ficheiro | +| Texto | pdfplumber | `page.extract_text()` | +| Tabelas | pdfplumber | `page.extract_tables()` | +| Criar | reportlab | Canvas ou Platypus | +| OCR | pytesseract | Converter para imagem primeiro | +| Formulários | pypdf/scripts | Ver secção acima | + +## Caminhos Descomplicar + +| Local | Caminho | +|-------|---------| +| Documentos empresa | `/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/` | +| Propostas | `/media/ealmeida/Dados/Hub/03-Propostas/` | +| Arquivo clientes | `/media/ealmeida/Dados/GDrive/Arquivo_de_Clientes/` | +| Knowledge Base | `/media/ealmeida/Dados/Hub/06-Operacoes/Knowledge-Base/PDFs/` | +| Temporários | `~/.claude-work/` (limpar ao concluir) | + +## Workflow + +1. Localizar PDF (filesystem ou Google Drive) +2. Descarregar para `~/.claude-work/` se necessário +3. Processar +4. Guardar no destino final +5. Limpar temporários + +--- +**Versão**: 1.0.0-light | **Base**: 1.0.0 diff --git a/dev-tools/skills/pdf/SKILL.md b/dev-tools/skills/pdf/SKILL.md index d3c07d3..11ca557 100644 --- a/dev-tools/skills/pdf/SKILL.md +++ b/dev-tools/skills/pdf/SKILL.md @@ -794,3 +794,15 @@ def extract_text_with_ocr(pdf_path): --- **Versao**: 1.0.0 | **Autor**: Descomplicar® + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/php-dev/SKILL.md b/dev-tools/skills/php-dev/SKILL.md index b2fb1ba..7dcc277 100644 --- a/dev-tools/skills/php-dev/SKILL.md +++ b/dev-tools/skills/php-dev/SKILL.md @@ -392,3 +392,15 @@ mcp__dify-kb__dify_kb_retrieve_segments({ --- **Versão**: 1.0.0 | **Autor**: Descomplicar® + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/prompt-refine/SKILL.md b/dev-tools/skills/prompt-refine/SKILL.md index 0a50943..2fad73d 100644 --- a/dev-tools/skills/prompt-refine/SKILL.md +++ b/dev-tools/skills/prompt-refine/SKILL.md @@ -130,3 +130,15 @@ Tabela com: ID, Nome, Segmento, Volume Anual (EUR), Projectos Activos, Última I --- **Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: dev-tools + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/react-patterns/SKILL.md b/dev-tools/skills/react-patterns/SKILL.md index 202ea4b..159e5b0 100644 --- a/dev-tools/skills/react-patterns/SKILL.md +++ b/dev-tools/skills/react-patterns/SKILL.md @@ -189,3 +189,15 @@ hooks/ - `references/composition-patterns.md` - Compound components, providers, dependency injection (Vercel Engineering) - `references/custom-hooks.md` - useDebounce, useLocalStorage, useFetch com codigo completo + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/skill-creator/SKILL.md b/dev-tools/skills/skill-creator/SKILL.md index 1f86f32..737c6e8 100644 --- a/dev-tools/skills/skill-creator/SKILL.md +++ b/dev-tools/skills/skill-creator/SKILL.md @@ -186,3 +186,15 @@ description: > Ver `references/anthropic-patterns.md` para exemplos detalhados de progressive disclosure. Ver `references/descomplicar-standards.md` para exemplos de skills Descomplicar bem estruturadas. + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/webapp-testing/SKILL.md b/dev-tools/skills/webapp-testing/SKILL.md index 31699de..78d14e5 100644 --- a/dev-tools/skills/webapp-testing/SKILL.md +++ b/dev-tools/skills/webapp-testing/SKILL.md @@ -144,3 +144,15 @@ No servidor dev, Playwright ja esta disponivel em `/root/Dev`. --- **Versao**: 1.0.0 | **Autor**: Descomplicar® + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/xlsx/SKILL.md b/dev-tools/skills/xlsx/SKILL.md index 93b61ea..bf41f6d 100644 --- a/dev-tools/skills/xlsx/SKILL.md +++ b/dev-tools/skills/xlsx/SKILL.md @@ -372,3 +372,15 @@ O ficheiro de referencia de precos esta em: --- **Versao**: 1.0.0 | **Autor**: Descomplicar® + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/dev-tools/skills/youtube-extract/SKILL.md b/dev-tools/skills/youtube-extract/SKILL.md new file mode 100644 index 0000000..9fa5ee2 --- /dev/null +++ b/dev-tools/skills/youtube-extract/SKILL.md @@ -0,0 +1,154 @@ +--- +name: youtube-extract +category: dev-tools +description: "Extrai transcrições e metadados de vídeos, playlists e canais YouTube para o ficheiro de pesquisa Stack_Pesquisa_Videos.md. Usar quando 'youtube', 'vídeo', 'playlist', 'canal', 'transcrição', 'extrair vídeo', 'pesquisa vídeos'." +version: "1.0.0" +created: 2026-04-04 +tools: [Bash] +--- + +# Skill: /youtube-extract + +Extrai transcrições e metadados de vídeos, playlists e canais YouTube usando o script `youtube-pesquisa-videos.py`. Adiciona automaticamente ao ficheiro de pesquisa do StackDescomplicar. + +--- + +## Ficheiros relevantes + +| Ficheiro | Caminho | +|----------|---------| +| **Script** | `/media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py` | +| **Destino padrão** | `/media/ealmeida/Dados/Hub/04-Stack/Stack_Pesquisa_Videos.md` | + +--- + +## Processo de execução + +### 1. Identificar o pedido + +Detectar na mensagem do utilizador: +- **URLs** — vídeos individuais, playlists (`?list=`), canais (`@canal`, `/c/`, `/channel/`) +- **Limite** — "primeiros 10", "máx 5", etc. → usar `--max N` +- **Destino** — ficheiro alternativo? → usar `--output caminho` +- **Modo** — adicionar ao ficheiro (`--append`) vs mostrar no terminal (sem flag) + +### 2. Construir o comando + +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + URL1 URL2 ... \ + [--max N] \ + [--append] \ + [--output /caminho/alternativo.md] \ + [--file lista.txt] +``` + +### 3. Exemplos por tipo de URL + +**Vídeo individual:** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + "https://youtu.be/dQw4w9WgXcQ" --append +``` + +**Playlist completa:** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + "https://youtube.com/playlist?list=PLxxx" --append +``` + +**Playlist com limite:** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + "https://youtube.com/playlist?list=PLxxx" --max 10 --append +``` + +**Canal completo (máx. 20):** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + "https://youtube.com/@NomeCanal" --max 20 --append +``` + +**Mix de URLs:** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + "https://youtu.be/ID1" \ + "https://youtube.com/playlist?list=PLxxx" \ + --max 5 --append +``` + +**Ficheiro de lista:** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + --file /caminho/lista.txt --append +``` + +**Pré-visualizar sem gravar:** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + "https://youtu.be/ID1" +``` + +--- + +## Comportamento padrão + +| Situação | Acção | +|----------|-------| +| URL única de vídeo | Extrair e perguntar se adiciona ao ficheiro | +| Múltiplos vídeos | Extrair todos e adicionar com `--append` | +| Playlist/canal sem limite | Alertar o utilizador — perguntar limite antes de executar | +| Ficheiro de destino não especificado | Usar `Stack_Pesquisa_Videos.md` | + +> **Aviso obrigatório para playlists/canais sem `--max`:** Informar o utilizador do número de vídeos antes de processar — canais podem ter centenas. + +--- + +## Após a extracção + +1. Informar quantos vídeos foram adicionados e os números `#N` atribuídos +2. Sugerir ao utilizador que complete os campos `*(a completar)*` no ficheiro +3. Se houver erros (transcrição indisponível), mencionar quais os vídeos afectados +4. Opcional: abrir o ficheiro no editor — `xdg-open "Stack_Pesquisa_Videos.md"` + +--- + +## Pré-requisitos + +- `yt-dlp` instalado: `pip install yt-dlp` ou `brew install yt-dlp` +- Python 3.8+ +- Acesso à internet + +Verificar disponibilidade: +```bash +yt-dlp --version && python3 --version +``` + +--- + +## Casos especiais + +**ID curto do YouTube (11 chars):** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py dQw4w9WgXcQ --append +``` + +**Destino alternativo (outro projecto):** +```bash +python3 /media/ealmeida/Dados/Dev/ClaudeDev/youtube-pesquisa-videos.py \ + "https://youtu.be/ID1" \ + --output "/media/ealmeida/Dados/Hub/05-Projectos/MeuProjecto/videos.md" \ + --append +``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/.claude-plugin/plugin.json b/gestao/.claude-plugin/plugin.json index 4f5696b..460e5d1 100644 --- a/gestao/.claude-plugin/plugin.json +++ b/gestao/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gestao", "description": "Project management, time tracking, daily checkups, worklogs, reflections, knowledge management, archiving and compliance auditing. Backed by NotebookLM notebooks.", - "version": "1.3.0", + "version": "1.4.0", "author": { "name": "Descomplicar - Crescimento Digital", "url": "https://descomplicar.pt" diff --git a/gestao/CHANGELOG.md b/gestao/CHANGELOG.md new file mode 100644 index 0000000..6f7d4a0 --- /dev/null +++ b/gestao/CHANGELOG.md @@ -0,0 +1,30 @@ +# Changelog — Plugin gestao + +Todas as alterações relevantes a este plugin. Segue [Semantic Versioning](https://semver.org/). + +--- + +## [1.4.0] — 2026-04-07 + +### Adicionado + +- **Nova skill `/clip-instructions`** — gerir AGENTS.md de agentes Paperclip por nome: ver, editar, criar, rever histórico de versões e rollback via API config revisions + +### Corrigido + +- **`/clip-health`** — check 1 reescrito: `systemctl` substituído por `ps aux` (Paperclip não usa systemd); check 6 reescrito: `npx paperclipai doctor` substituído por `curl http://localhost:3100/health`; adicionado check de memória partilhada POSIX (`/dev/shm/PostgreSQL.*`) — causa raiz do bug pós-reboot; score actualizado 21→22; 2 entradas no Healing Log +- **`/clip-agent`** — curl de atribuição de skills corrigido: adicionado `-H "Authorization: Bearer $PAPERCLIP_API_KEY"` (sem header dava 401); documentadas notas sobre agentes analyst (`process` adapter, `claude-sonnet-4-6`, heartbeat desactivado); checklist "Criar agente novo" actualizada com `instructionsBundleMode: "external"`, `instructionsRootPath`, `instructionsEntryFile`; 3 entradas no Healing Log +- **`/clip-issue`** — `author_user_id` corrigido: `'board'` → `'v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO'` (ID real de Emanuel); adicionado modo checkout/release com endpoints API e fallback SQL; entrada no Healing Log +- **`/clip-skill`** — modelo mental corrigido: "ephemeral/symlinks" → "injecção de contexto em runtime a cada heartbeat"; adicionado `-H "Authorization: Bearer $PAPERCLIP_API_KEY"` aos dois curls de API (`/skills/import` e `/skills/sync`); nota sobre adapter `process` para agentes analyst; entrada no Healing Log + +### Notas técnicas + +- Todas as correcções baseadas em aprendizagens dos vídeos Paperclip (sessão 07-04-2026) +- Chave de autenticação Paperclip: `Authorization: Bearer $PAPERCLIP_API_KEY` obrigatória em todos os endpoints da API local +- Agentes criados via SQL directamente (fora do fluxo OpenClaw) **não** recebem `company_memberships` automaticamente — inserção manual obrigatória + +--- + +## [1.3.0] — anterior + +- Versão base (sem changelog registado) diff --git a/gestao/agents/reflect-agent.md b/gestao/agents/reflect-agent.md index e6a1472..f2979cc 100644 --- a/gestao/agents/reflect-agent.md +++ b/gestao/agents/reflect-agent.md @@ -4,7 +4,7 @@ description: Auto-reflexão e melhoria contínua do sistema. Analisa sessões, i padrões, sugere optimizações. Auto-trigger >20 tool calls. role: Auto-reflexão e melhoria contínua do sistema domain: Dev -model: sonnet +model: haiku tools: Read, Write, Edit, Glob, ToolSearch # Dependencies diff --git a/gestao/skills/aiktop-tasks/SKILL.md b/gestao/skills/aiktop-tasks/SKILL.md index e4cf8ad..12651bd 100644 --- a/gestao/skills/aiktop-tasks/SKILL.md +++ b/gestao/skills/aiktop-tasks/SKILL.md @@ -132,3 +132,15 @@ exit $EXIT_CODE --- *Skill v1.0.0 | 04-03-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/archive/SKILL.md b/gestao/skills/archive/SKILL.md index 6c6a040..da898e7 100644 --- a/gestao/skills/archive/SKILL.md +++ b/gestao/skills/archive/SKILL.md @@ -221,3 +221,15 @@ Output: [resultado esperado] Input: [caso complexo] Output: [resultado detalhado] ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/calendar-manager/SKILL.md b/gestao/skills/calendar-manager/SKILL.md index 248ac7d..17fd92b 100644 --- a/gestao/skills/calendar-manager/SKILL.md +++ b/gestao/skills/calendar-manager/SKILL.md @@ -175,3 +175,15 @@ mcp__google_workspace__create_event({ - **Workflows detalhados:** `references/workflows-detalhados.md` - **MCP tools e constantes:** `references/mcp-tools-referencia.md` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/cleanup-downloads/SKILL.md b/gestao/skills/cleanup-downloads/SKILL.md index c83e339..42f8c25 100644 --- a/gestao/skills/cleanup-downloads/SKILL.md +++ b/gestao/skills/cleanup-downloads/SKILL.md @@ -1,7 +1,6 @@ --- name: cleanup-downloads description: Limpeza e triagem da pasta Transferências (Downloads). Verifica cada ficheiro individualmente, apaga descartáveis, classifica o restante por categoria. Usar quando "transferências", "downloads", "limpar downloads", "cleanup", "limpeza pasta". -disable-model-invocation: true --- # Cleanup Downloads @@ -105,3 +104,15 @@ Após mover documentos financeiros (regra 3), lançar despesas via `/expense`: ## Integração /today Incluir contagem de ficheiros na pasta quando >10 ficheiros. + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/clip-health/SKILL.md b/gestao/skills/clip-health/SKILL.md index e451ee7..729d9b9 100644 --- a/gestao/skills/clip-health/SKILL.md +++ b/gestao/skills/clip-health/SKILL.md @@ -168,7 +168,7 @@ echo "Tunnel: $TUNNEL_PORT | Servidor: $ACTUAL_PORT" ### Check 11: Agentes sem permissoes bash -Invocar tool MCP: `mcp__paperclip__diag_agents_missing_permissions` +Invocar tool MCP: `mcp__paperclip__diag_agents_without_skip_permissions` - 0 = OK - 1+ = CRITICO (agentes vao ficar bloqueados ao executar bash — corrigir com `/clip-agent`) diff --git a/gestao/skills/daily-digest/SKILL.md b/gestao/skills/daily-digest/SKILL.md index a6a4922..89ac297 100644 --- a/gestao/skills/daily-digest/SKILL.md +++ b/gestao/skills/daily-digest/SKILL.md @@ -122,3 +122,15 @@ Gerar alertas se: --- *Skill v1.0.0 | 04-03-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/deep-research/SKILL.md b/gestao/skills/deep-research/SKILL.md new file mode 100644 index 0000000..1d0e598 --- /dev/null +++ b/gestao/skills/deep-research/SKILL.md @@ -0,0 +1,137 @@ +--- +name: deep-research +description: > + Pesquisa profunda em 3 layers: Hub Obsidian (Layer 1) + NotebookLM análise (Layer 2) + + Web/LightRAG externo (Layer 3). Para questões complexas que requerem síntese de múltiplas fontes. + Upgrade do /research com NotebookLM integrado e RAG trinity completo. + Usar quando: análise competitiva profunda, pesquisa mercado, due diligence, relatório estratégico. +--- + +# /deep-research — Pesquisa Profunda com RAG Trinity + +Pesquisa em 3 camadas com síntese final. Mais profundo que `/research`, mais estruturado que `/hub-search`. + +--- + +## Quando Usar + +| Situação | Skill Correcta | +|---------|----------------| +| "Onde está X no Hub?" | `/hub-search` | +| "Analisa este documento" | `/research` | +| "Pesquisa profunda + síntese de múltiplas fontes" | `/deep-research` ← este | +| "Análise competitiva completa" | `/deep-research` + `/research competitive` | + +--- + +## Protocolo (3 Layers) + +### Layer 1 — Hub Obsidian (conhecimento interno) + +```bash +# 1a. Busca full-text no Hub +obsidian search query="" format=json limit=10 + +# 1b. Se Obsidian não responde (offline), fallback via Grep +grep -r "" /media/ealmeida/Dados/Hub/ --include="*.md" -l | head -20 + +# 1c. Verificar LightRAG para contexto interno +mcp__lightrag__lightrag_query({ + query: "", + mode: "hybrid" +}) +``` + +**Critério de suficiência Layer 1:** Encontrou 3+ documentos relevantes com contexto concreto. +- SE suficiente para questão simples → responder + registar fonte +- SE questão requer análise profunda → continuar para Layer 2 + +### Layer 2 — NotebookLM (análise profunda) + +Seleccionar notebook relevante com base no domínio: + +| Domínio | Notebook ID | +|---------|-------------| +| Estratégia e Empreendedorismo | 79d43410-0e29-4be1-881d-84db6bdc239a | +| Stack Tecnológico | [consultar mcp__notebooklm__ lista] | +| Marketing e Vendas | [consultar mcp__notebooklm__ lista] | + +```javascript +// Consultar notebook relevante +mcp__notebooklm__notebook_query({ + notebook_id: "", + query: "" +}) +``` + +**Critério de suficiência Layer 2:** NotebookLM retornou análise com citações específicas. +- SE suficiente → sintetizar com Layer 1 + responder +- SE requer dados externos → continuar para Layer 3 + +### Layer 3 — Web + LightRAG (conhecimento externo) + +```javascript +// 3a. LightRAG para KB externa (PDFs, transcripts) +mcp__lightrag__lightrag_query({ + query: "", + mode: "global" // para análise de padrões amplos +}) + +// 3b. Web search para dados actuais +mcp__web-search__search({ + query: " site:scholar.google.com OR filetype:pdf", + num_results: 10 +}) +``` + +--- + +## Síntese Final + +Após recolher de 2+ layers, sintetizar: + +```markdown +## Síntese — [Tópico] + +**Fontes consultadas:** Layer 1 (Hub), Layer 2 (NotebookLM [Notebook X]), Layer 3 (Web/LightRAG) + +### O que sabemos (interno) +[Resumo Layer 1 — conhecimento já documentado] + +### Análise profunda +[Resumo Layer 2 — análise NotebookLM com citações] + +### Contexto externo +[Resumo Layer 3 — se consultado] + +### Síntese e Recomendação +[Cruzamento das layers — resposta directa à questão] + +### Próximos Passos +- [ ] Acção 1 derivada da pesquisa +- [ ] Acção 2 +``` + +--- + +## Self-Improving Loop + +Após cada execução, registar preferências para melhorar futuras pesquisas: + +```bash +# Guardar aprendizagem em Hub +echo "$(date '+%Y-%m-%d') — deep-research — [TÓPICO] — [O QUE FUNCIONOU/NÃO FUNCIONOU]" \ + >> /media/ealmeida/Dados/Hub/00-Inbox/research-preferences.md +``` + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +--- + +*Skill /deep-research v1.0 | 06-04-2026 | Eixo 7B — RAG Trinity + NotebookLM integrado* diff --git a/gestao/skills/delegate/SKILL.md b/gestao/skills/delegate/SKILL.md index 60d90c9..0de2a74 100644 --- a/gestao/skills/delegate/SKILL.md +++ b/gestao/skills/delegate/SKILL.md @@ -339,3 +339,15 @@ Output: [resultado esperado] Input: [caso complexo] Output: [resultado detalhado] ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/doc-coauthoring/SKILL.md b/gestao/skills/doc-coauthoring/SKILL.md index 5910c94..07cdea8 100644 --- a/gestao/skills/doc-coauthoring/SKILL.md +++ b/gestao/skills/doc-coauthoring/SKILL.md @@ -440,3 +440,15 @@ Após concluir o documento: --- **Versão**: 1.0.0 | **Data**: 2026-03-06 | **Autor**: Descomplicar® + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/hub-search/SKILL.md b/gestao/skills/hub-search/SKILL.md new file mode 100644 index 0000000..fde8f15 --- /dev/null +++ b/gestao/skills/hub-search/SKILL.md @@ -0,0 +1,138 @@ +--- +name: hub-search +description: > + Pesquisa no vault Hub Obsidian com relevance scoring e backlinks. + Layer 1 da arquitectura RAG trinity (CLI → NotebookLM → LightRAG). + Usar quando: (1) pesquisar conteúdo no Hub por termo ou conceito, + (2) encontrar notas relacionadas via backlinks, (3) localizar PROCs/QR/docs + antes de executar tarefas, (4) verificar se existe documentação antes de criar. +--- + +# /hub-search — Pesquisa no Hub (Layer 1 RAG) + +Pesquisa rápida no vault Hub via Obsidian CLI. Requer Obsidian aberto. +Fallback automático para Grep se Obsidian não estiver a correr. + +--- + +## Uso + +``` +/hub-search "termo" +/hub-search "LightRAG configuração" --backlinks +/hub-search "PROC-MCP" --files +``` + +--- + +## Workflow + +### Passo 1 — Tentar via Obsidian CLI + +```bash +# Pesquisa básica +obsidian search query="TERMO" format=json + +# Com backlinks (recomendado para conceitos) +obsidian search query="TERMO" format=json +obsidian backlinks file="NOTA" + +# Limitar resultados +obsidian search query="TERMO" limit=10 format=json +``` + +**Indicador de sucesso:** saída JSON com `results` array. +**Indicador de falha:** mensagem `unable to find Obsidian` → ir para fallback. + +### Passo 2 — Fallback: Grep no Hub + +Se CLI falhar (Obsidian fechado): + +``` +Grep "TERMO" /media/ealmeida/Dados/Hub/ --type md +``` + +Adicionar contexto ao utilizador: "Obsidian não está a correr — usando busca directa nos ficheiros." + +### Passo 3 — Apresentar resultados + +**Formato de output:** + +```markdown +## Resultados: "[termo]" + +**Fonte:** Obsidian CLI v1.12.7 | **Backlinks:** Sim/Não + +### Encontrado em N notas + +| Nota | Path | Relevância | +|------|------|-----------| +| [título] | `path/relativo.md` | Alta/Média/Baixa | + +### Notas com backlinks para este termo +- `nota-a.md` → referencia `nota-b.md` + +### Relacionados sugeridos +- [links relevantes encontrados nos resultados] +``` + +--- + +## Regras + +1. **Sempre tentar CLI primeiro** — é mais preciso (scoring semântico) +2. **--include-backlinks por defeito** quando o termo é um conceito (não um comando) +3. **Fallback silencioso** — não perguntar, só mencionar que usou Grep +4. **Max 10 resultados** — se mais, mostrar top 10 por relevância +5. **Paths relativos** na apresentação (ex: `04-Stack/02.03-IA/` não path absoluto) + +--- + +## Integração com RAG Trinity + +``` +/hub-search "termo" → Layer 1: Obsidian CLI (este skill) +/knowledge "termo" → Layer 2: NotebookLM (58 notebooks) +mcp__lightrag__lightrag_query → Layer 3: LightRAG (conteúdo externo) +``` + +**Quando escalar para Layer 2 ou 3:** +- Resultado CLI score < 50% ou 0 resultados → sugerir `/knowledge` +- Conteúdo externo (PDFs, transcripts) → sugerir LightRAG diretamente + +--- + +## Referência CLI + +```bash +# Sintaxe correcta: parâmetros com = (não flags com --) +obsidian search query="TERMO" format=json +obsidian search query="TERMO" limit=10 format=json +obsidian backlinks file="NOTA" +obsidian tags sort=count counts +obsidian tasks daily todo +obsidian version +obsidian help # lista todos os comandos disponíveis +``` + +**Nota:** A skill oficial kepano (`obsidian-cli`) tem referência completa de todos os comandos. + +**Requer:** Obsidian aberto + CLI activado em Settings → General → Advanced +**Wrapper:** `~/.local/bin/obsidian` (define XDG_RUNTIME_DIR Flatpak) +**Docs:** `04-Stack/02.03-IA/Obsidian-CLI.md` + +--- + +*Skill v1.0.0 | 06-04-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/imap-triage/SKILL.md b/gestao/skills/imap-triage/SKILL.md index 406b828..653f3ab 100644 --- a/gestao/skills/imap-triage/SKILL.md +++ b/gestao/skills/imap-triage/SKILL.md @@ -234,3 +234,15 @@ Quando invocado directamente (sem /today): --- *Skill v1.0.0 | 04-03-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/index-update/SKILL.md b/gestao/skills/index-update/SKILL.md index bef38f6..a0588b3 100644 --- a/gestao/skills/index-update/SKILL.md +++ b/gestao/skills/index-update/SKILL.md @@ -391,3 +391,15 @@ Checklist automática: --- *Skill v1.0.0 | 2026-02-13 | Plugin gestao | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/knowledge/SKILL.md b/gestao/skills/knowledge/SKILL.md index 3666b4f..bad5b21 100644 --- a/gestao/skills/knowledge/SKILL.md +++ b/gestao/skills/knowledge/SKILL.md @@ -288,3 +288,15 @@ if (resultado.score < 50 || !resultado.encontrado) { - `references/routing-guide.md` - Mapeamento detalhado com codigo de routing - Inventario completo: `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/mindmap/SKILL.md b/gestao/skills/mindmap/SKILL.md index f6d1f5d..2ff17ca 100644 --- a/gestao/skills/mindmap/SKILL.md +++ b/gestao/skills/mindmap/SKILL.md @@ -150,3 +150,15 @@ Ou abrir a app e usar File > Open para navegar ate ao ficheiro. - **Texto curto:** 2-5 palavras por node (mindmap, nao documento) - **Template adequado:** Fish-bone para causa/efeito, structure para hierarquias, right para processos - **Nome descritivo:** Usar nome do topico no ficheiro (nao "mindmap1.km") + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/notebooklm/SKILL.md b/gestao/skills/notebooklm/SKILL.md index 5c9b4bc..ef18551 100644 --- a/gestao/skills/notebooklm/SKILL.md +++ b/gestao/skills/notebooklm/SKILL.md @@ -392,3 +392,15 @@ Auth guardada em: `~/.notebooklm-mcp-cli/profiles//auth.json` --- **Versão**: 1.0.0 | **Data**: 24-02-2026 | **Autor**: Descomplicar® + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/office-hours/SKILL.md b/gestao/skills/office-hours/SKILL.md new file mode 100644 index 0000000..0a43720 --- /dev/null +++ b/gestao/skills/office-hours/SKILL.md @@ -0,0 +1,116 @@ +--- +name: office-hours +description: > + Persona YC que reframe problemas antes de escrever código. Desafia pressupostos, + faz as perguntas difíceis que um investidor faria. Usar ANTES de qualquer implementação + significativa. Baseado no gstack /office-hours. Eixo 2B. +--- + +# /office-hours — Consulta YC antes de Codar + +Persona: sócio de uma YC top-tier que passou 20 anos a ver startups falharem por resolver o problema errado. +Objetivo: garantir que o que vais construir é o que deve ser construído. + +--- + +## Quando Usar (OBRIGATÓRIO) + +- Antes de implementar uma feature nova +- Antes de refactoring significativo +- Quando a solução parece óbvia demais +- Quando o problema está mal definido +- Quando o utilizador pediu X mas pode precisar de Y + +**Anti-pattern:** Saltar para o código sem office-hours = construir a coisa certa de forma errada, ou a coisa errada certo. + +--- + +## Protocolo + +### Passo 1 — Escutar sem julgar + +"O que estás a tentar resolver? Conta-me como se eu não soubesse nada do teu negócio." + +Deixar o utilizador descrever o problema completamente. Não interromper. Tomar notas mentais dos seguintes sinais: +- Soluções disfarçadas de problemas ("preciso de um botão que...") +- Pressupostos não verificados ("os utilizadores querem...") +- Scope excessivo ("e depois também...") +- Urgência artificial ("precisa de estar pronto até...") + +### Passo 2 — As 5 Perguntas + +``` +1. "Por que é que este problema existe agora? O que mudou?" + → Detecta se é problema real ou hipotético + +2. "Quem perde o emprego se este problema não for resolvido?" + → Identifica o owner real e urgência verdadeira + +3. "O que acontece se não fizermos nada?" + → Valida se é crítico ou nice-to-have + +4. "Já tentaste resolver isto de forma mais simples? O que aconteceu?" + → Evita over-engineering, descobre tentativas anteriores + +5. "Se tivesses de demonstrar que isto funciona em 24h, o que farias?" + → Força a pensar em MVP mínimo viável +``` + +### Passo 3 — Reframe (se necessário) + +SE o problema apresentado é uma solução disfarçada: +``` +"Percebo que queres [solução X]. Mas o problema que describes é [problema Y]. +Podemos resolver [Y] de forma mais simples: [alternativa Z]. +Queres explorar Z antes de construir X?" +``` + +### Passo 4 — Aprovação ou Alternativa + +``` +APROVADO se: +- Problema claramente definido +- Solução proposta é a mais simples +- ROI claro (tempo poupado, receita gerada, risco eliminado) +- Utilizador entende o trade-off + +ALTERNATIVA se: +- Há solução mais simples não considerada +- O problema não está suficientemente validado +- Scope excessivo para o valor gerado +``` + +### Passo 5 — Output + +```markdown +## Office Hours — [Data] + +**Problema original:** [o que o utilizador apresentou] +**Problema real:** [reframe se necessário] +**Decisão:** AVANÇAR | REFRAMED | ADIAR +**Justificação:** [1-2 frases] +**Próximo passo:** [acção concreta] +``` + +--- + +## Exemplos de Reframe + +| Pedido original | Reframe YC | +|----------------|-----------| +| "Preciso de um dashboard de métricas" | "O que decides diferente com o dashboard? Se nada, não precisas dele." | +| "Quero migrar para microserviços" | "Qual é o problema do monolito actual? Quantos utilizadores tens?" | +| "Refactoring completo do código" | "O que não consegues fazer agora por causa do código? Isso é o problema." | +| "Automatizar este processo" | "Quanto tempo demora? Quantas vezes por semana? Vale a automação?" | + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +--- + +*Skill /office-hours v1.0 | 06-04-2026 | Eixo 2B — gstack pattern* diff --git a/gestao/skills/onboarding/SKILL.md b/gestao/skills/onboarding/SKILL.md new file mode 100644 index 0000000..86a50f6 --- /dev/null +++ b/gestao/skills/onboarding/SKILL.md @@ -0,0 +1,111 @@ +--- +name: onboarding +category: gestao +description: "Checklist e automacao de onboarding de novo colaborador. Criacao de contas, documentacao, equipamento. Usar quando 'onboarding', 'novo colaborador', 'contratar', 'integrar pessoa', 'RH novo'." +version: "1.0.0" +created: 2026-04-07 +tools: [mcp__desk-crm-v3__create_task, mcp__desk-crm-v3__add_task_checklist_item, mcp__google-workspace__gmail_send_email] +--- + +# Skill: /onboarding + +Checklist e automacao de onboarding de novo colaborador. Baseado em PROC-Onboarding.md (RH-001). + +--- + +## Referencia + +Procedimento completo em: `Hub/06-Operacoes/Procedimentos/D4-RH/PROC-Onboarding.md` +Esta skill executa os passos — o PROC define as regras. + +--- + +## Processo + +### 1. Recolher dados do novo colaborador + +Perguntar ao utilizador: +- **Nome completo** +- **Email pessoal** +- **Funcao/cargo** +- **Data de inicio** +- **Tipo:** colaborador / freelancer / estagiario +- **Departamento:** D1-D7 + +### 2. Criar tarefa no Desk CRM + +``` +mcp__desk-crm-v3__create_task({ + name: "Onboarding — [Nome]", + project_id: 65, + startdate: [data inicio], + duedate: [data inicio + 5 dias uteis], + priority: 2, + description: "Onboarding de [Nome] como [Funcao] no departamento [Dept]" +}) +``` + +### 3. Adicionar checklist de onboarding + +Items obrigatorios (adicionar via `add_task_checklist_item`): + +**Contas e acessos:** +- [ ] Email @descomplicar.pt criado +- [ ] Conta Desk CRM criada (staff) +- [ ] Acesso Gitea (se tecnico) +- [ ] Acesso Google Workspace +- [ ] Password manager configurado + +**Documentacao:** +- [ ] Contrato assinado +- [ ] NIF e dados fiscais recolhidos +- [ ] Ficha de colaborador preenchida +- [ ] RGPD — consentimento assinado + +**Equipamento:** +- [ ] PC/portatil atribuido +- [ ] Acessos VPN/SSH (se aplicavel) +- [ ] Ferramentas de trabalho instaladas + +**Integracao:** +- [ ] Reuniao de boas-vindas agendada +- [ ] Apresentacao a equipa +- [ ] Acesso a documentacao interna (Hub) +- [ ] Mentor atribuido (primeiras 2 semanas) + +### 4. Enviar email de boas-vindas (opcional) + +Se o utilizador aprovar, enviar email via Google Workspace: + +``` +Assunto: Bem-vindo(a) a Descomplicar — [Nome] +Corpo: Template de boas-vindas com: +- Data de inicio +- Links uteis (Desk, email, Git) +- Contacto do mentor +- Primeiros passos +``` + +### 5. Resumo + +Apresentar ao utilizador: +- Tarefa Desk criada (ID + link) +- Checklist com N items +- Proximos passos manuais (contrato, equipamento) + +--- + +## Regras + +- **Nunca criar contas automaticamente** — apenas checklist para lembrar +- **Contrato e dados fiscais sao responsabilidade do Emanuel** — skill so lembra +- **Email de boas-vindas requer aprovacao** antes de enviar +- **Tipo freelancer** tem checklist reduzida (sem equipamento, sem VPN) + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/gestao/skills/proc-creator/SKILL.md b/gestao/skills/proc-creator/SKILL.md index 6601c0f..6bc58eb 100644 --- a/gestao/skills/proc-creator/SKILL.md +++ b/gestao/skills/proc-creator/SKILL.md @@ -364,3 +364,15 @@ Checklist automática: --- *Skill v1.0.0 | 2026-02-13 | Plugin gestao | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/report-templates/SKILL.md b/gestao/skills/report-templates/SKILL.md index d60fcaf..a2a07f5 100644 --- a/gestao/skills/report-templates/SKILL.md +++ b/gestao/skills/report-templates/SKILL.md @@ -183,3 +183,15 @@ Gera revisao mensal completa e publica como comentario na tarefa Desk do cliente --- *Skill v1.0.0 | 2026-03-10 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/report/SKILL.md b/gestao/skills/report/SKILL.md index ed5d027..c530352 100644 --- a/gestao/skills/report/SKILL.md +++ b/gestao/skills/report/SKILL.md @@ -214,3 +214,15 @@ Relatórios podem ser guardados em: --- *Skill v1.0.0 | 2026-02-05 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/research-pipeline/SKILL.md b/gestao/skills/research-pipeline/SKILL.md new file mode 100644 index 0000000..ff08670 --- /dev/null +++ b/gestao/skills/research-pipeline/SKILL.md @@ -0,0 +1,153 @@ +--- +name: research-pipeline +description: > + Pipeline de pesquisa RAG trinity: Layer 1 (Obsidian CLI Hub), Layer 2 (NotebookLM), + Layer 3 (LightRAG externo). Orquestra as 3 camadas em sequência para pesquisas + profundas. Usar quando /hub-search ou /knowledge isolados não são suficientes, + quando o tema cruza conteúdo interno+externo, ou para research antes de executar + tarefas complexas (Eixo 7B, Stack Q2 2026). +--- + +# /research-pipeline — Pipeline Trinity de Pesquisa + +Orquestra as 3 camadas RAG em sequência para obter contexto completo antes de executar tarefas. + +``` +Layer 1: Obsidian CLI → conteúdo Hub (notas, PROCs, docs internas) +Layer 2: NotebookLM → análise profunda (58 notebooks temáticos) +Layer 3: LightRAG → conteúdo externo (1612 docs, PDFs, transcripts) +``` + +--- + +## Uso + +``` +/research-pipeline "tema ou pergunta" +/research-pipeline "LightRAG configuração" --layers 1,2 +/research-pipeline "PROC-MCP" --quick (só Layer 1) +/research-pipeline "n8n webhook setup" --deep (todas as layers) +``` + +--- + +## Workflow + +### Passo 1 — Layer 1: Hub via Obsidian CLI + +```bash +obsidian search "TERMO" --include-backlinks --format json +``` + +**Se CLI offline:** fallback para Grep no Hub. + +Registar: `L1_results`, `L1_score` (0-100, baseado em nº resultados). + +### Passo 2 — Avaliar se Layer 2 é necessária + +``` +SE L1_score >= 80 E query é operacional (PROC, QR, path): + → PARAR — resultado suficiente, retornar L1 +SE L1_score < 80 OU query é conceptual/analítica: + → Avançar para Layer 2 +``` + +### Passo 3 — Layer 2: NotebookLM (análise profunda) + +Usar routing da skill `/knowledge` para seleccionar notebooks relevantes. + +```javascript +// Max 2 notebooks para performance +mcp__notebooklm__notebook_query({ notebook_id, query }) +``` + +Registar: `L2_results`, `L2_confidence`. + +### Passo 4 — Avaliar se Layer 3 é necessária + +``` +SE query menciona PDFs, vídeos, transcripts, conteúdo externo: + → Avançar para Layer 3 +SE L2_confidence >= 70: + → PARAR — retornar L1+L2 combinados +``` + +### Passo 5 — Layer 3: LightRAG (conteúdo externo) + +```javascript +mcp__lightrag__lightrag_query({ + query: "TERMO", + mode: "hybrid" // combina vector + graph +}) +``` + +### Passo 6 — Síntese e output + +```markdown +## Research: "[termo]" + +### Hub (Layer 1) — [N notas encontradas] +[Resultados mais relevantes com paths] + +### NotebookLM (Layer 2) — [notebook usado] +[Insights e contexto analítico] + +### Externo (Layer 3) — [N docs] +[Conteúdo complementar de fontes externas] + +### Síntese +[Resposta integrada das 3 camadas] + +### Qualidade +- L1: [N resultados] +- L2: [confidence%] via [notebook] +- L3: [N docs] +- Tempo: ~[X]s +``` + +--- + +## Modos rápidos + +| Flag | Layers activas | Uso | +|------|---------------|-----| +| `--quick` | L1 apenas | PROCs, paths, comandos | +| (default) | L1 + L2 | Maioria das queries | +| `--deep` | L1 + L2 + L3 | Investigação completa | + +--- + +## Integração com outras skills + +``` +Antes de /wp-dev → /research-pipeline --quick "PROC-WordPress" +Antes de /cwp-* → /research-pipeline --quick "PROC-CWP" +Antes de design → /research-pipeline "design guidelines descomplicar" +Para /deep-research → /research-pipeline --deep (base de contexto) +``` + +--- + +## Regras + +1. **Layer 1 sempre primeiro** — mais rápido e frequentemente suficiente +2. **Max 2 notebooks NotebookLM** por query (performance) +3. **L3 só para conteúdo externo** — não duplicar com L1 +4. **Timeout L3:** 30s — se exceder, retornar L1+L2 +5. **Citar fonte** de cada resultado no output + +--- + +*Skill v1.0.0 | 06-04-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/review-corrections/SKILL.md b/gestao/skills/review-corrections/SKILL.md new file mode 100644 index 0000000..e405445 --- /dev/null +++ b/gestao/skills/review-corrections/SKILL.md @@ -0,0 +1,131 @@ +--- +name: review-corrections +description: > + Analisa correcções feitas pelo utilizador nas últimas sessões e gera sugestões + de regras para CLAUDE.md. Lê ~/.claude-work/corrections.jsonl, agrupa por padrão, + e propõe melhorias concretas. Usar semanalmente (via /schedule) ou quando há >5 + correcções acumuladas. Faz parte do loop de auto-melhoria (Eixo 3, Stack Q2 2026). +--- + +# /review-corrections — Análise de Correcções e Auto-melhoria + +Analisa padrões de correcção do utilizador para melhorar o CLAUDE.md autonomamente. + +--- + +## Workflow + +### Passo 1 — Ler ficheiro de correcções + +```bash +cat ~/.claude-work/corrections.jsonl +``` + +Cada linha é um JSON: +```json +{"ts":"2026-04-06T14:30:00","type":"correction","prompt":"não assim, usa grep","session":"abc","cwd":"/Hub/"} +``` + +### Passo 2 — Agrupar por padrão + +Categorias de correcção: + +| Padrão | Keywords | Acção sugerida | +|--------|---------|----------------| +| **Ferramenta errada** | "usa grep", "não uses bash", "usa read" | Regra de preferência de ferramenta | +| **Língua/formato** | "em português", "sem emojis", "com acentos" | Regra de output | +| **Abordagem** | "não assim", "de outra forma", "mais simples" | Regra de heurística | +| **Scope** | "não faças isso", "não toques em", "só X" | Regra de limites | +| **Verificação** | "verifica primeiro", "não inventar", "confirma" | Regra anti-alucinação | + +### Passo 3 — Gerar sugestões de regras + +Para cada padrão com ≥2 ocorrências, propor regra no formato: + +```markdown +**Regra candidata:** +> [Padrão detectado N vezes] → Sugestão: "Nunca [X], sempre [Y]" + +**Evidência:** +- "prompt1" (data) +- "prompt2" (data) + +**Proposta CLAUDE.md:** +| NN | [Texto da regra concisa] | +``` + +### Passo 4 — Apresentar ao utilizador + +```markdown +## Revisão de Correcções — [data] + +**Total analisado:** N correcções em M sessões +**Padrões encontrados:** P + +### Regras candidatas (aprovação necessária) + +[lista de propostas] + +### Limpar ficheiro? +[ ] Sim — arquivar em ~/.claude-work/corrections-archive-YYYY-MM.jsonl +[ ] Não — manter para próxima revisão +``` + +### Passo 5 — Aplicar regras aprovadas + +Se o utilizador aprovar uma regra: +1. Abrir `~/.claude/CLAUDE.md` +2. Adicionar na tabela de REGRAS CORE com número sequencial +3. Confirmar: "Regra #NN adicionada." + +Se o utilizador recusar: +- Arquivar correcção com tag `rejected` +- Não propor de novo + +--- + +## Quando usar + +- **Semanal** (via `/schedule` às segundas-feiras com `/today`) +- **Manual** quando corrections.jsonl tem >5 entradas +- **Após incidente** (mesmo erro 2+ vezes consecutivos) + +--- + +## Integração auto-trigger + +O hook `capture-corrections.sh` regista automaticamente em `~/.claude-work/corrections.jsonl`. +Esta skill consome esse ficheiro e fecha o loop de auto-melhoria. + +**Loop completo:** +``` +Correcção utilizador + → capture-corrections.sh (regista) + → /review-corrections (analisa) + → CLAUDE.md (actualiza) + → Comportamento melhora +``` + +--- + +## Anti-patterns + +- Nunca aplicar regras sem aprovação explícita do utilizador +- Nunca propor regras com <2 ocorrências (pode ser caso isolado) +- Nunca eliminar regras existentes — apenas adicionar ou reformular + +--- + +*Skill v1.0.0 | 06-04-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/spec-coauthor/SKILL.md b/gestao/skills/spec-coauthor/SKILL.md index ac650a4..35e8f73 100644 --- a/gestao/skills/spec-coauthor/SKILL.md +++ b/gestao/skills/spec-coauthor/SKILL.md @@ -338,3 +338,15 @@ mcp__desk-crm-v3__create_task ou update_task: --- *Skill v1.0.0 | 2026-03-10 | Plugin gestao | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/task-state/SKILL.md b/gestao/skills/task-state/SKILL.md new file mode 100644 index 0000000..665eee4 --- /dev/null +++ b/gestao/skills/task-state/SKILL.md @@ -0,0 +1,124 @@ +--- +name: task-state +description: Gestão de estado persistente de tarefas entre sessões. Cria, actualiza e lê .task-state.md para tarefas complexas. Usar quando tarefa tem >2 sessões, múltiplos ficheiros, ou risco de perder contexto por compaction. +context: fork +--- + +# /task-state — Gestão de Estado de Tarefa + +Persiste decisões, ficheiros e checkpoints entre sessões. Sobrevive a context compaction. + +--- + +## Quando usar + +**Usar quando:** +- Tarefa com >1 sessão de trabalho +- Múltiplos ficheiros a modificar (>3) +- Risco de context compaction apagar contexto crítico +- Tarefas que requerem aprovação por checkpoint + +**Não usar quando:** +- Tarefas de <30 minutos +- Edições simples de 1-2 ficheiros +- Respostas a perguntas + +--- + +## Comandos + +### /task-state init + +Cria `.task-state.md` no directório actual baseado no template. + +```bash +# Verificar se já existe +[ -f ".task-state.md" ] && echo "AVISO: já existe — usar /task-state update" && exit 1 + +# Copiar template +cp ~/.claude-work/task-state-template.md .task-state.md +echo "Criado: .task-state.md" +``` + +Após criar, preencher os campos de Identificação manualmente. + +### /task-state read + +Lê e apresenta o estado actual — útil ao retomar uma tarefa interrompida: + +```bash +cat .task-state.md +``` + +Ao retomar: ler "Próximo passo imediato" e "Bloqueantes actuais" primeiro. + +### /task-state checkpoint N + +Marca checkpoint N como concluído: + +```bash +# Exemplo: marcar checkpoint 2 como feito +sed -i "s/- \[ \] Sub-issue 2:/- [x] Sub-issue 2:/" .task-state.md +``` + +### /task-state update + +Actualizar campos específicos ao longo do trabalho: +- Adicionar ficheiros modificados à lista +- Registar decisões tomadas +- Actualizar "Próximo passo imediato" +- Adicionar bloqueantes encontrados + +--- + +## Padrão Vertical Plans + +Diferença para planos monolíticos: + +| Monolítico | Vertical Plans | +|------------|----------------| +| Lê o plano completo | Divide em sub-issues com checkpoint | +| Implementa tudo | Implementa 1 sub-issue | +| Verifica no final | Testa + valida antes de avançar | +| Falha tarde | Falha cedo e barato | + +**Regra:** Nunca avançar para sub-issue N+1 sem N estar testado e marcado. + +--- + +## Integração com writing-plans + +1. `/writing-plans` → cria plano com sub-issues e critérios de sucesso +2. `/task-state init ` → cria ficheiro de estado +3. A cada sub-issue: implementar → testar → `/task-state checkpoint N` → commit +4. Se sessão interromper: ler `.task-state.md` → continuar no "Próximo passo imediato" + +--- + +## Template + +O template está em `~/.claude-work/task-state-template.md`. +Actualizar o template para reflectir necessidades do projecto actual. + +--- + +## Contexto crítico — o que documentar + +Documentar TUDO que está só na cabeça do Emanuel e que o agente precisa: +- "Este servidor é produção — não tocar sem aprovação" +- "O cliente X é sensível a preços — nunca mencionar concorrentes" +- "A BD usa UTF-8 mas tem registos ISO-8859 antigos — cuidado com migrações" + +**Fonte:** Regra #361 — agente apagou BD de produção porque "é live" estava só na cabeça do humano. + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/tasks-overview/SKILL.md b/gestao/skills/tasks-overview/SKILL.md index aafd1e2..e8e4585 100644 --- a/gestao/skills/tasks-overview/SKILL.md +++ b/gestao/skills/tasks-overview/SKILL.md @@ -108,3 +108,15 @@ Apos listar tarefas, sugerir ate 6 accoes concretas: --- *Skill v1.0.0 | 04-03-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/time/SKILL.md b/gestao/skills/time/SKILL.md index cfa1f62..39f973f 100644 --- a/gestao/skills/time/SKILL.md +++ b/gestao/skills/time/SKILL.md @@ -250,3 +250,15 @@ const ALERT_HOURS = 4; // Alertar após 4h --- *Skill v2.0.0 | 2026-02-05 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/today/SKILL.md b/gestao/skills/today/SKILL.md index 627bd26..c06e298 100644 --- a/gestao/skills/today/SKILL.md +++ b/gestao/skills/today/SKILL.md @@ -233,6 +233,24 @@ Filename: `DD-MM-YYYY-checkup.md` (Regra #45: formato DD-MM-YYYY) Repo agentes: `git.descomplicar.pt/ealmeida/claude_automations_dev` + + +--- + +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/today.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + --- *Skill v10.0.0 | 05-03-2026 | Descomplicar®* + + +## Healing Log + diff --git a/gestao/skills/validate-component/SKILL.md b/gestao/skills/validate-component/SKILL.md index edaa3a5..fe46955 100644 --- a/gestao/skills/validate-component/SKILL.md +++ b/gestao/skills/validate-component/SKILL.md @@ -363,3 +363,15 @@ Ver secção "Referências e Documentação" em: --- *Skill v1.0.0 | 2026-02-13 | Plugin gestao | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/gestao/skills/worklog/SKILL.md b/gestao/skills/worklog/SKILL.md index 31d1eff..0aa13f0 100644 --- a/gestao/skills/worklog/SKILL.md +++ b/gestao/skills/worklog/SKILL.md @@ -327,6 +327,32 @@ Perguntas ao analisar sessão: - Auto-trigger ao parar timer - Formato HTML alinhado com Regra #27 + + +--- + +## Self-Healing + +Antes de executar, ler `~/.claude-work/healing/worklog.jsonl` (se existir). Cada linha é um padrão de erro conhecido: + +```json +{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"} +``` + +Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido. + --- *Skill v4.2.0 | 2026-03-12 | Descomplicar(R)* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/agents/easypanel-specialist.md b/infraestrutura/agents/easypanel-specialist.md index 7683e93..d396f51 100644 --- a/infraestrutura/agents/easypanel-specialist.md +++ b/infraestrutura/agents/easypanel-specialist.md @@ -23,6 +23,8 @@ skills: - easypanel-deploy - easypanel-troubleshoot - easypanel-rollback +- easypanel-monitor +- easypanel-cicd - easypanel-api desk_task: 1502 desk_project: 65 diff --git a/infraestrutura/skills/authentik/SKILL.md b/infraestrutura/skills/authentik/SKILL.md index d3d7590..5b17455 100644 --- a/infraestrutura/skills/authentik/SKILL.md +++ b/infraestrutura/skills/authentik/SKILL.md @@ -216,3 +216,15 @@ curl -sk "https://auth.descomplicar.pt/api/v3/admin/system/" \ 3. Pesquisar duplicados antes de criar users (como CRM) 4. Passwords devem ter minimo 12 caracteres 5. Verificar groups existentes antes de associar + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/backup-strategies/SKILL.md b/infraestrutura/skills/backup-strategies/SKILL.md index fd99c2f..5611b27 100644 --- a/infraestrutura/skills/backup-strategies/SKILL.md +++ b/infraestrutura/skills/backup-strategies/SKILL.md @@ -182,3 +182,15 @@ Ver runbook completo passo-a-passo em `references/scripts.md` (seccao Runbook Di | Ficheiro | Conteudo | |----------|----------| | [references/scripts.md](references/scripts.md) | Scripts MySQL/PostgreSQL/WordPress/CWP, rotacao GFS, cron, rclone, teste restore, runbook DR | + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-accounts/SKILL.md b/infraestrutura/skills/cwp-accounts/SKILL.md index 3ea5d3b..82c577d 100644 --- a/infraestrutura/skills/cwp-accounts/SKILL.md +++ b/infraestrutura/skills/cwp-accounts/SKILL.md @@ -257,3 +257,15 @@ curl -sI http://DOMINIO | head -5 **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** wiki.centos-webpanel.com/cwp-admin-api, wiki.centos-webpanel.com/cwp-scripts + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-backup/SKILL.md b/infraestrutura/skills/cwp-backup/SKILL.md index c892404..a00cb47 100644 --- a/infraestrutura/skills/cwp-backup/SKILL.md +++ b/infraestrutura/skills/cwp-backup/SKILL.md @@ -227,3 +227,15 @@ rm -rf /tmp/restore_test **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** wiki.centos-webpanel.com/cwp-scripts, wiki.centos-webpanel.com/category/backups + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-email/SKILL.md b/infraestrutura/skills/cwp-email/SKILL.md index c7761b2..00d8fea 100644 --- a/infraestrutura/skills/cwp-email/SKILL.md +++ b/infraestrutura/skills/cwp-email/SKILL.md @@ -240,3 +240,15 @@ tail -100 /var/log/maillog **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** wiki.centos-webpanel.com + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-php/SKILL.md b/infraestrutura/skills/cwp-php/SKILL.md index 61ca0c6..db1d792 100644 --- a/infraestrutura/skills/cwp-php/SKILL.md +++ b/infraestrutura/skills/cwp-php/SKILL.md @@ -239,3 +239,15 @@ Integrar insights do NotebookLM nas recomendações e decisões. **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** wiki.centos-webpanel.com/php-selector, wiki.centos-webpanel.com/php-version-switcher + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-scripts/SKILL.md b/infraestrutura/skills/cwp-scripts/SKILL.md index a4a00a9..588d7d2 100644 --- a/infraestrutura/skills/cwp-scripts/SKILL.md +++ b/infraestrutura/skills/cwp-scripts/SKILL.md @@ -274,3 +274,15 @@ Integrar insights do NotebookLM nas recomendações e decisões. **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** wiki.centos-webpanel.com/cwp-scripts + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-security/SKILL.md b/infraestrutura/skills/cwp-security/SKILL.md index 2107db1..b37cc9c 100644 --- a/infraestrutura/skills/cwp-security/SKILL.md +++ b/infraestrutura/skills/cwp-security/SKILL.md @@ -315,3 +315,15 @@ Integrar insights do NotebookLM nas recomendações e decisões. **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** wiki.centos-webpanel.com/csf-firewall-command-line + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-ssl/SKILL.md b/infraestrutura/skills/cwp-ssl/SKILL.md index 0b82794..e346e4e 100644 --- a/infraestrutura/skills/cwp-ssl/SKILL.md +++ b/infraestrutura/skills/cwp-ssl/SKILL.md @@ -250,3 +250,15 @@ curl -sI https://DOMINIO | head -5 **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** Documentação oficial CWP (docs.control-webpanel.com, wiki.centos-webpanel.com) + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/cwp-webserver/SKILL.md b/infraestrutura/skills/cwp-webserver/SKILL.md index 1ebbceb..69880ed 100644 --- a/infraestrutura/skills/cwp-webserver/SKILL.md +++ b/infraestrutura/skills/cwp-webserver/SKILL.md @@ -266,3 +266,15 @@ tail -20 /var/log/nginx/error.log **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** wiki.centos-webpanel.com/cwp-admin-api, wiki.centos-webpanel.com/cwp-scripts + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-api/SKILL.md b/infraestrutura/skills/easypanel-api/SKILL.md index 7281c71..ebc1a86 100644 --- a/infraestrutura/skills/easypanel-api/SKILL.md +++ b/infraestrutura/skills/easypanel-api/SKILL.md @@ -71,6 +71,8 @@ curl -s -X POST "http://localhost:3000/api/trpc/projects.createProject" \ Endpoints completos com exemplos curl: ver [references/services-api.md](references/services-api.md) +**Verificados 12-03-2026** (engenharia reversa do backend.js minificado): + | Endpoint | Tipo | Descrição | |----------|------|-----------| | `services.app.createService` | POST | Criar serviço app | @@ -79,10 +81,14 @@ Endpoints completos com exemplos curl: ver [references/services-api.md](referenc | `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.stopService` | POST | Parar serviço | +| `services.app.startService` | POST | Iniciar serviço | +| `services.app.restartService` | POST | Reiniciar serviço | | `services.app.destroyService` | POST | Destruir serviço | +**Endpoints que NAO existem** (removidos da versao anterior): +`enableService`, `disableService` — usar `startService`/`stopService` em vez disso. + **Parâmetros obrigatórios:** `projectName` + `serviceName` em todos os endpoints de serviços. **Regra Descomplicar:** `projectName:"descomplicar"` para serviços próprios. @@ -93,19 +99,70 @@ Endpoints completos com exemplos curl: ver [references/services-api.md](referenc Endpoints completos com exemplos curl: ver [references/service-config-api.md](references/service-config-api.md) -| 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 | +**Verificados 12-03-2026:** + +| Endpoint | Descrição | Verificado | +|----------|-----------|:----------:| +| `services.app.updateSourceGithub` | Source GitHub (`owner`, `repo`, `ref`, `path`) | Sim | +| `services.app.updateSourceGit` | Source Git custom (`repo`, `ref`, `path`) — params no nivel raiz, NAO dentro de `source` | Sim | +| `services.app.updateSourceImage` | Source Docker image (`image`) | Sim | +| `services.app.updateEnv` | Variáveis de ambiente (`env` como string multi-linha) | Sim | +| `services.app.updateBuild` | Build config (`type`, `buildCommand`, `startCommand`) | Sim | +| `services.app.updateResources` | CPU/RAM (`memoryLimit`, `cpuLimit`, etc.) | Sim | +| `services.app.updateAdvanced` | Deploy avançado (`replicas`, `command`, `zeroDowntime`) | Sim | +| `services.app.updateRedirects` | Redireccionamentos HTTP | Sim | +| `services.app.updateBasicAuth` | Autenticacao basica | Sim | +| `services.app.updateMaintenance` | Modo manutencao | Sim | + +**Endpoints que NAO existem na versao instalada:** +- ~~`services.app.updateDomains`~~ — dominios so via UI do EasyPanel +- ~~`services.app.updateMounts`~~ — nao encontrado +- ~~`services.app.updatePorts`~~ — nao encontrado + +--- + +## Domains API (Verificado 12-03-2026) + +Os dominios NAO sao geridos por `services.app.*` mas sim pelo namespace `domains.*`. + +| Endpoint | Tipo | Descricao | +|----------|------|-----------| +| `domains.listDomains` | GET | Listar dominios do projecto (`projectName`) | +| `domains.createDomain` | POST | Criar dominio | +| `domains.updateDomain` | POST | Actualizar dominio | +| `domains.deleteDomain` | POST | Remover dominio | + +```bash +# Listar dominios +INPUT='{"json":{"projectName":"descomplicar"}}' +ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))") +curl -s "http://localhost:3000/api/trpc/domains.listDomains?input=$ENCODED" \ + -H "Authorization: Bearer $TOKEN" + +# Criar dominio para servico +curl -s -X POST "http://localhost:3000/api/trpc/domains.createDomain" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "id":"meu-dominio-id", + "https":true, + "host":"app.descomplicar.pt", + "path":"/", + "middlewares":[], + "certificateResolver":"letsencrypt", + "wildcard":false, + "destinationType":"service", + "serviceDestination":{ + "protocol":"http", + "port":3000, + "path":"/", + "projectName":"descomplicar", + "serviceName":"meu-servico" + } + }}' +``` + +**Nota:** O `id` pode ser qualquer string unica (cuid ou slug). O `certificateResolver` deve ser `"letsencrypt"` para HTTPS com certificado automatico, ou `""` para dominios internos. --- @@ -214,11 +271,11 @@ O EasyPanel usa Docker Swarm internamente. Isto impõe limitações nos mounts q 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. +2. **Sem suporte nativo a NFS/CIFS** — O EasyPanel nao suporta drivers de volume remotos (NFS, CIFS, etc.) directamente via API. Para volumes partilhados, e necessario criar o volume Docker manualmente com o driver adequado e depois referencia-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. +4. **Substituicao total** — Mounts sao geridos via UI do EasyPanel. O endpoint `updateMounts` NAO foi encontrado na versao instalada. Configurar mounts directamente na interface web. ### Workarounds conhecidos @@ -259,14 +316,21 @@ docker volume create --driver local \ --- +## Seguranca + +**ATENCAO:** `services.app.inspectService` retorna TODAS as variaveis de ambiente em texto limpo, incluindo passwords, tokens API e credenciais de base de dados. Nunca incluir output bruto de `inspectService` em reports, logs ou comentarios. Sanitizar sempre antes de mostrar ao utilizador. + +Campos sensiveis tipicos no `env`: `DB_PASS`, `API_TOKEN`, `SERVER_PASS`, `GATEWAY_PASS`, `EASYPANEL_API_TOKEN`. + ## Anti-Patterns | Anti-Pattern | Risco | Alternativa | |--------------|-------|-------------| -| Expor API externamente | Segurança crítica | Usar apenas via SSH localhost | +| Expor API externamente | Seguranca critica | 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` | +| Nao validar response | Erros silenciosos | Verificar `result.data.json` | | POST sem `Content-Type` | Request falha | Sempre incluir header | +| Mostrar output de inspectService | Expoe passwords em texto limpo | Sanitizar env vars | --- @@ -274,5 +338,17 @@ docker volume create --driver local \ | 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) | +| [references/services-api.md](references/services-api.md) | Endpoints de servicos com curl completo (create, inspect, deploy, stop/start/restart, destroy) | +| [references/service-config-api.md](references/service-config-api.md) | Endpoints de configuracao (source, env, resources, build, deploy, domains, backup BD) | + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-api/references/service-config-api.md b/infraestrutura/skills/easypanel-api/references/service-config-api.md index d04f6d7..85e26f4 100644 --- a/infraestrutura/skills/easypanel-api/references/service-config-api.md +++ b/infraestrutura/skills/easypanel-api/references/service-config-api.md @@ -1,5 +1,9 @@ # EasyPanel API - Service Configuration +**Verificado:** 12-03-2026 (engenharia reversa do backend.js) + +--- + ## Actualizar Source (GitHub) ```bash @@ -18,6 +22,8 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGithub" ## Actualizar Source (Git Custom) +**IMPORTANTE:** Os parametros `repo`, `ref`, `path` devem estar no nivel RAIZ do JSON, NAO dentro de um objecto `source`. + ```bash curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGit" \ -H "Authorization: Bearer $TOKEN" \ @@ -25,12 +31,22 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGit" \ -d '{"json":{ "projectName":"descomplicar", "serviceName":"minha-api", - "repo":"https://git.descomplicar.pt/org/repo", + "repo":"https://ealmeida:TOKEN@git.descomplicar.pt/ealmeida/repo", "ref":"main", "path":"/" }}' ``` +**Errado (causa zodErrors):** +```json +{"json":{"projectName":"x","serviceName":"y","source":{"type":"git","repo":"...","ref":"main","path":"/"}}} +``` + +**Correcto:** +```json +{"json":{"projectName":"x","serviceName":"y","repo":"...","ref":"main","path":"/"}} +``` + ## Actualizar Source (Docker Image) ```bash @@ -57,48 +73,20 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateEnv" \ }}' ``` -## Actualizar Domains +## Actualizar Build Config ```bash -curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateDomains" \ +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", - "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"} - ] + "build":{ + "type":"nixpacks", + "buildCommand":"npm run build", + "startCommand":"npm start" + } }}' ``` @@ -120,23 +108,6 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateResources" \ }}' ``` -## 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 @@ -154,6 +125,45 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateAdvanced" \ }}' ``` +## Actualizar Redirects + +```bash +curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateRedirects" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "projectName":"descomplicar", + "serviceName":"minha-api", + "redirects":[] + }}' +``` + +## Actualizar Basic Auth + +```bash +curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateBasicAuth" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "projectName":"descomplicar", + "serviceName":"minha-api", + "basicAuth":{"enabled":false} + }}' +``` + +## Actualizar Maintenance Mode + +```bash +curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateMaintenance" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "projectName":"descomplicar", + "serviceName":"minha-api", + "maintenance":{"enabled":false} + }}' +``` + ## Database Backup Config ```bash @@ -176,3 +186,98 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.postgres.updateBackup" } }}' ``` + +--- + +## Domains API (Namespace separado) + +**IMPORTANTE:** Os dominios NAO sao geridos por `services.app.*` mas sim pelo namespace `domains.*`. + +### Listar Dominios (GET) + +```bash +INPUT='{"json":{"projectName":"descomplicar"}}' +ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))") +curl -s "http://localhost:3000/api/trpc/domains.listDomains?input=$ENCODED" \ + -H "Authorization: Bearer $TOKEN" +``` + +### Criar Dominio (POST) + +```bash +curl -s -X POST "http://localhost:3000/api/trpc/domains.createDomain" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{ + "id":"meu-dominio-id", + "https":true, + "host":"app.descomplicar.pt", + "path":"/", + "middlewares":[], + "certificateResolver":"letsencrypt", + "wildcard":false, + "destinationType":"service", + "serviceDestination":{ + "protocol":"http", + "port":3000, + "path":"/", + "projectName":"descomplicar", + "serviceName":"meu-servico" + } + }}' +``` + +**Notas:** +- O `id` pode ser qualquer string unica (cuid ou slug) +- `certificateResolver`: `"letsencrypt"` para HTTPS, `""` para dominios internos +- `destinationType`: `"service"` para servicos EasyPanel, `"custom"` para destinos externos + +### Actualizar Dominio (POST) + +```bash +curl -s -X POST "http://localhost:3000/api/trpc/domains.updateDomain" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{...mesmo schema de createDomain...}}' +``` + +### Remover Dominio (POST) + +```bash +curl -s -X POST "http://localhost:3000/api/trpc/domains.deleteDomain" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{"id":"meu-dominio-id"}}' +``` + +--- + +## Resumo de Endpoints de Configuracao + +| Endpoint | Tipo | Descricao | Verificado | +|----------|------|-----------|:----------:| +| `services.app.updateSourceGithub` | POST | Source GitHub (`owner`,`repo`,`ref`,`path`) | Sim | +| `services.app.updateSourceGit` | POST | Source Git custom (`repo`,`ref`,`path` RAIZ) | Sim | +| `services.app.updateSourceImage` | POST | Source Docker image (`image`) | Sim | +| `services.app.updateEnv` | POST | Variaveis de ambiente (`env` string) | Sim | +| `services.app.updateBuild` | POST | Build config (`type`,`buildCommand`,`startCommand`) | Sim | +| `services.app.updateResources` | POST | CPU/RAM limits | Sim | +| `services.app.updateAdvanced` | POST | Deploy avancado (replicas, command, zeroDowntime) | Sim | +| `services.app.updateRedirects` | POST | Redireccionamentos HTTP | Sim | +| `services.app.updateBasicAuth` | POST | Autenticacao basica | Sim | +| `services.app.updateMaintenance` | POST | Modo manutencao | Sim | +| `domains.listDomains` | GET | Listar dominios (`projectName`) | Sim | +| `domains.createDomain` | POST | Criar dominio | Sim | +| `domains.updateDomain` | POST | Actualizar dominio | Sim | +| `domains.deleteDomain` | POST | Remover dominio | Sim | + +**Endpoints que NAO existem na versao instalada:** +- ~~`services.app.updateDomains`~~ — usar `domains.createDomain` +- ~~`services.app.updateMounts`~~ — nao encontrado +- ~~`services.app.updatePorts`~~ — nao encontrado +- ~~`services.app.saveDomains`~~ — nao existe +- ~~`services.app.saveGithubSource`~~ — usar `updateSourceGithub` ou `updateSourceGit` + +--- + +*Actualizado: 12-03-2026* diff --git a/infraestrutura/skills/easypanel-api/references/services-api.md b/infraestrutura/skills/easypanel-api/references/services-api.md index 93f668d..1030209 100644 --- a/infraestrutura/skills/easypanel-api/references/services-api.md +++ b/infraestrutura/skills/easypanel-api/references/services-api.md @@ -1,10 +1,12 @@ # EasyPanel API - Services +**Verificado:** 12-03-2026 (engenharia reversa do backend.js) + ## Service Types | Type | Descricao | |------|-----------| -| `app` | Aplicacao (Node.js, Python, Go, etc.) | +| `app` | Aplicacao (Node.js, Python, Go, Rust, etc.) | | `mysql` | MySQL database | | `mariadb` | MariaDB database | | `postgres` | PostgreSQL database | @@ -42,14 +44,16 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.redis.createService" \ -d '{"json":{"projectName":"descomplicar","serviceName":"cache"}}' ``` -## Inspeccionar Servico +## Inspeccionar Servico (GET) ```bash -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" \ +INPUT='{"json":{"projectName":"descomplicar","serviceName":"dashboard_descomplicar"}}' +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" ``` -Response: +Response parcial: ```json { "projectName": "descomplicar", @@ -74,22 +78,30 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.deployService" \ -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}' ``` -## Enable/Disable Servico +## Stop / Start / Restart Servico ```bash -# Disable -curl -s -X POST "http://localhost:3000/api/trpc/services.app.disableService" \ +# Parar servico +curl -s -X POST "http://localhost:3000/api/trpc/services.app.stopService" \ -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" \ +# Iniciar servico +curl -s -X POST "http://localhost:3000/api/trpc/services.app.startService" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}' + +# Reiniciar servico +curl -s -X POST "http://localhost:3000/api/trpc/services.app.restartService" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}' ``` +**IMPORTANTE:** `enableService` e `disableService` NAO existem na versao instalada. Usar `startService`/`stopService`. + ## Destruir Servico ```bash @@ -98,3 +110,26 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.destroyService" \ -H "Content-Type: application/json" \ -d '{"json":{"projectName":"descomplicar","serviceName":"minha-api"}}' ``` + +--- + +## Resumo de Endpoints + +| Endpoint | Tipo | Descricao | Verificado | +|----------|------|-----------|:----------:| +| `services.app.createService` | POST | Criar servico app | Sim | +| `services.postgres.createService` | POST | Criar PostgreSQL | Sim | +| `services.mysql.createService` | POST | Criar MySQL | Sim | +| `services.redis.createService` | POST | Criar Redis | Sim | +| `services.app.inspectService` | GET | Inspeccionar servico | Sim | +| `services.app.deployService` | POST | Fazer deploy | Sim | +| `services.app.stopService` | POST | Parar servico | Sim | +| `services.app.startService` | POST | Iniciar servico | Sim | +| `services.app.restartService` | POST | Reiniciar servico | Sim | +| `services.app.destroyService` | POST | Destruir servico | Sim | + +**Endpoints que NAO existem:** `enableService`, `disableService`, `redeployService` + +--- + +*Actualizado: 12-03-2026* diff --git a/infraestrutura/skills/easypanel-cicd/SKILL.md b/infraestrutura/skills/easypanel-cicd/SKILL.md new file mode 100644 index 0000000..1803e33 --- /dev/null +++ b/infraestrutura/skills/easypanel-cicd/SKILL.md @@ -0,0 +1,359 @@ +--- +name: easypanel-cicd +description: Configuracao de CI/CD com Gitea Actions para auto-deploy no EasyPanel via webhook — setup de workflows, secrets e validacao. +--- + +# /easypanel-cicd - CI/CD Gitea Actions para EasyPanel + +Configuracao completa de pipelines CI/CD que ligam repositorios Gitea ao EasyPanel para auto-deploy. + +--- + +## Quando usar + +- Configurar auto-deploy de um repositorio Gitea para EasyPanel +- Criar workflow Gitea Actions com testes + deploy +- Obter e configurar webhook URL de um servico +- Diagnosticar pipelines CI/CD falhados +- Adicionar CI/CD a projectos existentes no EasyPanel + +## Quando nao usar + +- Para deploy manual (usar `/easypanel-deploy`) +- Para scaffold de projecto novo (usar `/easypanel-init`) +- Para troubleshooting de containers (usar `/easypanel-troubleshoot`) + +--- + +## Sintaxe + +```bash +/easypanel-cicd # Setup completo (workflow + secrets + webhook) +/easypanel-cicd --webhook-only # Apenas obter/configurar webhook +/easypanel-cicd --diagnose # Diagnosticar pipeline falhado +``` + +--- + +## Arquitectura + +``` +Gitea (push main) --> Gitea Actions Runner --> Testes + Build --> Webhook POST --> EasyPanel Redeploy + (3 runners activos) (deploy URL) (build + container) +``` + +**Componentes:** +- **Gitea Actions Runners:** 3 replicas activas (`descomplicar_gitea-runner`) +- **Webhook URL:** Cada servico EasyPanel tem `deploymentUrl` unico +- **Formato:** `http://:3000/api/deploy/` + +--- + +## Workflow completo + +### 1. Obter webhook URL do servico + +```bash +TOKEN=$(cat /etc/easypanel/.api-token) + +# Via inspectService — campo deploymentUrl +INPUT='{"json":{"projectName":"descomplicar","serviceName":"SERVICE_NAME"}}' +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" \ + | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['result']['data']['json']['deploymentUrl'])" +``` + +**Formato da URL:** `http://178.63.18.51:3000/api/deploy/` + +**Nota:** O token e unico por servico e nao expira. Nao confundir com o API token geral. + +### 2. Configurar secret no repositorio Gitea + +Via MCP Gitea: +``` +mcp__gitea__upsert_repo_action_secret({ + owner: "ealmeida", + repo: "REPO_NAME", + secretname: "EASYPANEL_DEPLOY_URL", + body: { data: "http://178.63.18.51:3000/api/deploy/" } +}) +``` + +Secrets adicionais recomendados: +- `EASYPANEL_DEPLOY_URL` — webhook URL (obrigatorio) +- `DEPLOY_DOMAIN` — dominio do servico (opcional, para health check) + +### 3. Criar workflow Gitea Actions + +Criar `.gitea/workflows/deploy.yml` no repositorio: + +#### Template basico (apenas deploy) + +```yaml +name: Deploy to EasyPanel + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Trigger EasyPanel Deploy + run: | + RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}") + if [ "$RESPONSE" != "200" ]; then + echo "Deploy trigger failed with HTTP $RESPONSE" + exit 1 + fi + echo "Deploy triggered successfully" +``` + +#### Template completo (testes + build + deploy + health check) + +```yaml +name: CI/CD Pipeline + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Lint + run: npm run lint --if-present + + - name: Test + run: npm test --if-present + + - name: Build + run: npm run build + + deploy: + needs: test + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + steps: + - name: Trigger EasyPanel Deploy + run: | + echo "Triggering deploy..." + RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}") + if [ "$RESPONSE" != "200" ]; then + echo "Deploy trigger failed with HTTP $RESPONSE" + exit 1 + fi + echo "Deploy triggered (HTTP $RESPONSE)" + + - name: Wait for deployment + run: sleep 120 + + - name: Health check + if: ${{ secrets.DEPLOY_DOMAIN != '' }} + run: | + for i in 1 2 3 4 5; do + STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://${{ secrets.DEPLOY_DOMAIN }}/health" || echo "000") + echo "Health check $i/5: HTTP $STATUS" + if [ "$STATUS" = "200" ]; then + echo "Service healthy" + exit 0 + fi + sleep 15 + done + echo "Health check failed after 5 attempts" + exit 1 +``` + +#### Template Python + +```yaml +name: CI/CD Pipeline (Python) + +on: + push: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: pip install -r requirements.txt + - run: python -m pytest --if-present + + deploy: + needs: test + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + steps: + - name: Trigger EasyPanel Deploy + run: | + curl -sf -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}" || exit 1 +``` + +### 4. Commit e push + +```bash +git add .gitea/workflows/deploy.yml +git commit -m "ci: add Gitea Actions deploy pipeline" +git push origin main +``` + +### 5. Validar pipeline + +```bash +# Via MCP Gitea — verificar runs +mcp__gitea__list_repo_action_runs({ + owner: "ealmeida", + repo: "REPO_NAME", + limit: 5 +}) +``` + +Ou verificar logs: +```bash +mcp__gitea__list_repo_action_run_jobs({ + owner: "ealmeida", + repo: "REPO_NAME", + run_id: RUN_ID +}) +``` + +--- + +## Diagnostico (--diagnose) + +### Pipeline nao dispara + +1. Verificar se o ficheiro esta em `.gitea/workflows/` (nao `.github/workflows/`) +2. Verificar se o branch e `main` (ou o configurado no `on.push.branches`) +3. Verificar se os runners estao activos: + ```bash + docker service ls | grep gitea-runner + # Esperado: 3/3 replicas + ``` + +### Webhook falha (HTTP != 200) + +1. Verificar se o `deploymentUrl` esta correcto (servico pode ter sido recriado) +2. Verificar se o EasyPanel esta acessivel internamente: + ```bash + curl -s http://localhost:3000/api/trpc/projects.listProjects -H "Authorization: Bearer $TOKEN" + ``` +3. Verificar se o token do servico nao mudou (re-obter via inspectService) + +### Build falha no EasyPanel + +1. Verificar Dockerfile: + ```bash + /easypanel-validate + ``` +2. Verificar logs do build: + ```bash + /easypanel-troubleshoot SERVICE_NAME + ``` + +### Testes falham no runner + +1. Verificar logs do job: + ```bash + mcp__gitea__get_repo_action_job_log_preview({ + owner: "ealmeida", + repo: "REPO_NAME", + job_id: JOB_ID + }) + ``` +2. Verificar se dependencias estao no `package.json`/`requirements.txt` +3. Verificar se env vars de teste estao configuradas + +--- + +## Servicos com CI/CD activo (inventario) + +Para listar todos os servicos com source git (candidatos a CI/CD): + +```bash +TOKEN=$(cat /etc/easypanel/.api-token) +curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \ + -H "Authorization: Bearer $TOKEN" \ + | python3 -c " +import sys,json +d=json.load(sys.stdin)['result']['data']['json'] +for s in d.get('services',[]): + src=s.get('source',{}) or {} + if src.get('type')=='git' and s.get('type')=='app': + repo=src.get('repo','').split('@')[-1] if '@' in src.get('repo','') else src.get('repo','') + print(f\"{s['projectName']}/{s['name']} | repo={repo} | ref={src.get('ref','?')}\") +" +``` + +--- + +## Checklist de execucao + +- [ ] Identificar servico EasyPanel alvo (projectName + serviceName) +- [ ] Obter deploymentUrl via inspectService (SSH ao servidor easy) +- [ ] Criar secret EASYPANEL_DEPLOY_URL no repo Gitea (via MCP) +- [ ] Criar secret DEPLOY_DOMAIN no repo Gitea (opcional, para health check) +- [ ] Criar `.gitea/workflows/deploy.yml` com template adequado +- [ ] Commit e push do workflow +- [ ] Verificar que o primeiro run dispara (list_repo_action_runs) +- [ ] Verificar que o deploy completa no EasyPanel +- [ ] Health check do servico apos deploy + +--- + +## MCPs necessarios + +- `ssh-unified` — Acesso ao servidor easy para obter deploymentUrl +- `gitea` — Criar secrets e verificar action runs + +--- + +## Skills relacionadas + +| Skill | Quando usar | +|-------|-------------| +| `/easypanel-deploy` | Deploy manual com validacao completa | +| `/easypanel-validate` | Validar projecto antes de configurar CI/CD | +| `/easypanel-init` | Scaffold novo projecto (ja inclui workflow template) | +| `/easypanel-troubleshoot` | Diagnosticar deploy falhado | +| `/easypanel-api` | Referencia API tRPC | + +--- + +*Skill v1.0.0 | 24-03-2026 | Descomplicar(r)* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-deploy/SKILL.md b/infraestrutura/skills/easypanel-deploy/SKILL.md index cfad9d3..9d2227c 100644 --- a/infraestrutura/skills/easypanel-deploy/SKILL.md +++ b/infraestrutura/skills/easypanel-deploy/SKILL.md @@ -314,26 +314,34 @@ Root cause detected: App listening on port 8080, Traefik expects 3000 ## Integration com CI/CD +O deploy automatico via Gitea Actions usa o webhook do EasyPanel (nao esta skill directamente). +Cada servico tem um `deploymentUrl` unico (visivel em `inspectService`). + ```yaml # .gitea/workflows/deploy.yml steps: - - name: Deploy + - name: Trigger EasyPanel Deploy run: | - /easypanel-deploy --skip-tests - env: - EASYPANEL_TOKEN: ${{ secrets.EASYPANEL_TOKEN }} + curl -s -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}" + # EASYPANEL_DEPLOY_URL = http://IP:3000/api/deploy/ ``` +Ver skill `/easypanel-cicd` para configuracao completa de CI/CD com Gitea Actions. + ## API Endpoints Usados Ver skill `/easypanel-api` para documentação completa. -| Acção | Endpoint | -|-------|----------| -| Deploy serviço | `POST services.app.deployService` | -| Redeploy | `POST services.app.redeployService` | -| Estado serviço | `GET services.app.inspectService` | -| Logs | `GET services.app.getServiceLogs` | +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Deploy serviço | `POST services.app.deployService` | Sim | +| Estado serviço | `GET services.app.inspectService` | Sim | +| Parar serviço | `POST services.app.stopService` | Sim | +| Iniciar serviço | `POST services.app.startService` | Sim | +| Reiniciar serviço | `POST services.app.restartService` | Sim | +| Logs serviço | `GET logs.getServiceLogs` | Sim | + +**Endpoints que NAO existem:** `redeployService` — usar `deployService` para re-deploy. ## MCPs Necessários @@ -403,4 +411,15 @@ Status: 4 (Em progresso) → 5 (Concluído) --- -**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ \ No newline at end of file +**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-init/SKILL.md b/infraestrutura/skills/easypanel-init/SKILL.md index 70aad8a..1b781e2 100644 --- a/infraestrutura/skills/easypanel-init/SKILL.md +++ b/infraestrutura/skills/easypanel-init/SKILL.md @@ -259,20 +259,43 @@ curl -s -X POST "http://localhost:3000/api/trpc/services.app.createService" \ -H "Content-Type: application/json" \ -d '{"json":{"projectName":"PROJECT_NAME","serviceName":"app"}}' -# Configurar domínio -curl -s -X POST "http://localhost:3000/api/trpc/services.app.saveDomains" \ +# Configurar dominio (namespace domains.*, NAO services.app.*) +curl -s -X POST "http://localhost:3000/api/trpc/domains.createDomain" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"json":{"projectName":"PROJECT_NAME","serviceName":"app","domains":[{"host":"DOMAIN"}]}}' + -d '{"json":{ + "id":"PROJECT_NAME-app", + "https":true, + "host":"DOMAIN", + "path":"/", + "middlewares":[], + "certificateResolver":"letsencrypt", + "wildcard":false, + "destinationType":"service", + "serviceDestination":{ + "protocol":"http", + "port":3000, + "path":"/", + "projectName":"PROJECT_NAME", + "serviceName":"app" + } + }}' -# Configurar Git source -curl -s -X POST "http://localhost:3000/api/trpc/services.app.saveGithubSource" \ +# Configurar Git source (params RAIZ, NAO dentro de source) +# Para repos Gitea privados, incluir token no URL +curl -s -X POST "http://localhost:3000/api/trpc/services.app.updateSourceGit" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"json":{"projectName":"PROJECT_NAME","serviceName":"app","owner":"ORG","repo":"REPO","ref":"refs/heads/main","autoDeploy":true}}' + -d '{"json":{ + "projectName":"PROJECT_NAME", + "serviceName":"app", + "repo":"https://ealmeida:GITEA_TOKEN@git.descomplicar.pt/ealmeida/REPO", + "ref":"main", + "path":"/" + }}' ``` -### 5. Optional: Push to Gitea +### 5. Push to Gitea (opcional) ```bash # Criar repo via MCP Gitea @@ -287,7 +310,7 @@ git remote add origin git@git.descomplicar.pt:ORG/PROJECT_NAME.git git push -u origin main ``` -### 5. Output Summary +### 6. Output Summary ``` ✅ Project scaffolded: PROJECT_NAME @@ -383,13 +406,16 @@ Similar ao PostgreSQL, usando `mysql:8-alpine`. Ver skill `/easypanel-api` para documentação completa. -| Acção | Endpoint | -|-------|----------| -| Criar projecto | `POST projects.createProject` | -| Criar serviço | `POST services.app.createService` | -| Configurar domínio | `POST services.app.saveDomains` | -| Configurar Git source | `POST services.app.saveGithubSource` | -| Deploy inicial | `POST services.app.deployService` | +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Criar projecto | `POST projects.createProject` | Sim | +| Criar serviço | `POST services.app.createService` | Sim | +| Configurar dominio | `POST domains.createDomain` | Sim | +| Configurar Git source | `POST services.app.updateSourceGit` | Sim | +| Configurar GitHub source | `POST services.app.updateSourceGithub` | Sim | +| Deploy inicial | `POST services.app.deployService` | Sim | + +**Endpoints que NAO existem:** `saveDomains`, `saveGithubSource` — usar `domains.createDomain` e `updateSourceGit`/`updateSourceGithub`. ## Validation @@ -458,9 +484,12 @@ Status: 4 (Em progresso) → 5 (Concluído) --- +## Healing Log -## Quando NÃO Usar +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. -- Para tarefas fora do domínio de especialização desta skill -- Quando outra skill mais específica está disponível -- Para operações que requerem confirmação manual do utilizador +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-monitor/SKILL.md b/infraestrutura/skills/easypanel-monitor/SKILL.md index 1d37856..237c25e 100644 --- a/infraestrutura/skills/easypanel-monitor/SKILL.md +++ b/infraestrutura/skills/easypanel-monitor/SKILL.md @@ -74,8 +74,58 @@ Para cada servico DOWN, obter logs: docker service logs --tail 10 --no-trunc 2>&1 ``` -### Passo 3: Uso de recursos (docker stats) +### Passo 3: Uso de recursos via API (preferido) +```bash +TOKEN=$(cat /etc/easypanel/.api-token) + +# Stats do sistema — retorna estrutura aninhada +curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \ + -H "Authorization: Bearer $TOKEN" +``` + +**Estrutura real da resposta (verificado 24-03-2026):** +```json +{ + "result": { + "data": { + "json": { + "uptime": 3118351.41, + "memInfo": { + "totalMemMb": 32096.51, + "usedMemMb": 16885.52, + "freeMemMb": 15210.99, + "usedMemPercentage": 52.61, + "freeMemPercentage": 47.39 + }, + "diskInfo": { + "totalGb": "192.7", + "usedGb": "89.7", + "freeGb": "103.0", + "usedPercentage": "46.5", + "freePercentage": "53.5" + }, + "cpuInfo": { + "usedPercentage": 13.65, + "count": 6, + "loadavg": [5.58, 6.34, 6.51] + }, + "network": { + "inputMb": 0, + "outputMb": 0 + } + } + } + } +} +``` + +**Campos a usar:** +- CPU: `cpuInfo.usedPercentage` +- RAM: `memInfo.usedMemPercentage` e `memInfo.usedMemMb` +- Disco: `diskInfo.usedPercentage` e `diskInfo.usedGb` + +**Fallback via SSH (se API indisponivel):** ```bash docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}" ``` @@ -88,7 +138,9 @@ docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\ | RAM | <70% | 70-85% | >85% | | RAM absoluto | <512MB | 512MB-1GB | >1GB | -### Passo 4: Espaco em disco +### Passo 4: Espaco em disco (via API ou fallback) + +Usar `diskInfo` da resposta do passo 3. Fallback: ```bash df -h / /var/lib/docker @@ -208,16 +260,17 @@ docker stats --no-stream --filter "name=" ## Integracao com API EasyPanel -Alternativa via API tRPC (ver `/easypanel-api`): +A API e o metodo **preferido** (ver `/easypanel-api`). Os comandos Docker sao fallback. ```bash TOKEN=$(cat /etc/easypanel/.api-token) -# Stats do sistema +# Stats do sistema (CPU, RAM, Disco — ver estrutura no Passo 3) curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \ -H "Authorization: Bearer $TOKEN" -# Stats Docker tasks +# Stats Docker tasks (actual/desired replicas por servico) +# Resposta: {"serviceName": {"actual": 1, "desired": 1}, ...} curl -s "http://localhost:3000/api/trpc/monitor.getDockerTaskStats" \ -H "Authorization: Bearer $TOKEN" @@ -226,6 +279,8 @@ curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \ -H "Authorization: Bearer $TOKEN" ``` +**Nota de seguranca:** `inspectService` expoe variaveis de ambiente em texto limpo (incluindo passwords e tokens). Nunca incluir output bruto de `inspectService` em reports — sanitizar sempre. + --- ## MCPs necessarios @@ -278,4 +333,16 @@ curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \ --- -*Skill v1.0.0 | 12-03-2026 | Descomplicar(r)* +*Skill v1.1.0 | 24-03-2026 | Descomplicar(r) | Fix: estrutura real monitor.getSystemStats (nested memInfo/cpuInfo/diskInfo)* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-rollback/SKILL.md b/infraestrutura/skills/easypanel-rollback/SKILL.md index 13831b4..41583eb 100644 --- a/infraestrutura/skills/easypanel-rollback/SKILL.md +++ b/infraestrutura/skills/easypanel-rollback/SKILL.md @@ -134,8 +134,8 @@ git push origin main # Obter token TOKEN=$(cat /etc/easypanel/.api-token) -# Trigger redeploy via API -curl -s -X POST "http://localhost:3000/api/trpc/services.app.redeployService" \ +# Trigger deploy via API (redeployService NAO existe, usar deployService) +curl -s -X POST "http://localhost:3000/api/trpc/services.app.deployService" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}' @@ -378,12 +378,13 @@ Quando `/easypanel-deploy` detecta falha, chama automaticamente: Ver skill `/easypanel-api` para documentação completa. -| Acção | Endpoint | -|-------|----------| -| Inspeccionar serviço | `GET services.app.inspectService` | -| Redeploy | `POST services.app.redeployService` | -| Obter logs | `GET services.app.getServiceLogs` | -| Estado serviço | `GET services.app.inspectService` | +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Inspeccionar serviço | `GET services.app.inspectService` | Sim | +| Deploy (redeploy) | `POST services.app.deployService` | Sim | +| Obter logs | `GET logs.getServiceLogs` | Sim | + +**Endpoints que NAO existem:** `redeployService`, `getServiceLogs` (logs estao em `logs.*`, nao `services.app.*`). ## MCPs Necessários @@ -455,9 +456,14 @@ Status: 4 (Em progresso) → 5 (Concluído) --- +--- -## Quando NÃO Usar +## Healing Log -- Para tarefas fora do domínio de especialização desta skill -- Quando outra skill mais específica está disponível -- Para operações que requerem confirmação manual do utilizador +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-troubleshoot/SKILL.md b/infraestrutura/skills/easypanel-troubleshoot/SKILL.md index 928accd..600aaf7 100644 --- a/infraestrutura/skills/easypanel-troubleshoot/SKILL.md +++ b/infraestrutura/skills/easypanel-troubleshoot/SKILL.md @@ -51,8 +51,8 @@ TOKEN=$(cat /etc/easypanel/.api-token) curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}' | jq -sRr @uri)" \ -H "Authorization: Bearer $TOKEN" | jq '.result.data.json' -# Obter logs via API -curl -s "http://localhost:3000/api/trpc/services.app.getServiceLogs?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE","lines":100}}' | jq -sRr @uri)" \ +# Obter logs via API (namespace logs.*, NAO services.app.*) +curl -s "http://localhost:3000/api/trpc/logs.getServiceLogs?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE","tail":100}}' | jq -sRr @uri)" \ -H "Authorization: Bearer $TOKEN" ``` @@ -203,12 +203,15 @@ CPU: X% Ver skill `/easypanel-api` para documentação completa. -| Acção | Endpoint | -|-------|----------| -| Estado serviço | `GET services.app.inspectService` | -| Logs serviço | `GET services.app.getServiceLogs` | -| Listar projectos | `GET projects.listProjects` | -| Estatísticas monitor | `GET monitor.getStats` | +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Estado serviço | `GET services.app.inspectService` | Sim | +| Logs serviço | `GET logs.getServiceLogs` | Sim | +| Listar projectos | `GET projects.listProjects` | Sim | +| Stats sistema | `GET monitor.getSystemStats` | Sim | +| Stats Docker | `GET monitor.getDockerTaskStats` | Sim | + +**Endpoints que NAO existem:** `services.app.getServiceLogs` (usar `logs.getServiceLogs`), `monitor.getStats` (usar `monitor.getSystemStats`). ## MCPs Necessários @@ -278,4 +281,15 @@ Status: 4 (Em progresso) → 5 (Concluído) --- -**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ \ No newline at end of file +**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/ +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/easypanel-validate/SKILL.md b/infraestrutura/skills/easypanel-validate/SKILL.md index 5925f72..fd93d62 100644 --- a/infraestrutura/skills/easypanel-validate/SKILL.md +++ b/infraestrutura/skills/easypanel-validate/SKILL.md @@ -165,8 +165,8 @@ TOKEN=$(cat /etc/easypanel/.api-token) curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}' | jq -sRr @uri)" \ -H "Authorization: Bearer $TOKEN" | jq '.result.data.json' -# Verificar estatísticas de recursos -curl -s "http://localhost:3000/api/trpc/monitor.getStats" \ +# Verificar estatisticas de recursos +curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \ -H "Authorization: Bearer $TOKEN" ``` @@ -262,12 +262,14 @@ Uso em CI/CD: Ver skill `/easypanel-api` para documentação completa. -| Acção | Endpoint | -|-------|----------| -| Inspeccionar serviço | `GET services.app.inspectService` | -| Estatísticas monitor | `GET monitor.getStats` | -| Listar projectos | `GET projects.listProjects` | -| Estado do sistema | `GET settings.getSystemInfo` | +| Acção | Endpoint | Verificado | +|-------|----------|:----------:| +| Inspeccionar serviço | `GET services.app.inspectService` | Sim | +| Stats sistema | `GET monitor.getSystemStats` | Sim | +| Listar projectos | `GET projects.listProjects` | Sim | +| IP servidor | `GET settings.getServerIp` | Sim | + +**Endpoints que NAO existem:** `monitor.getStats` (usar `monitor.getSystemStats`), `settings.getSystemInfo` (usar `settings.getServerIp`). ## Tools Necessários @@ -338,18 +340,14 @@ Status: 4 (Em progresso) → 5 (Concluído) --- +--- -## Quando NÃO Usar +## Healing Log -- Para tarefas fora do domínio de especialização desta skill -- Quando outra skill mais específica está disponível -- Para operações que requerem confirmação manual do utilizador +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` -## Protocolo - -1. Analisar requisitos da tarefa -2. Verificar disponibilidade de ferramentas necessárias -3. Executar operações de forma incremental -4. Validar resultados antes de concluir -5. Reportar status e próximos passos +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/gateway-check/SKILL.md b/infraestrutura/skills/gateway-check/SKILL.md index bfac94e..1eb2e38 100644 --- a/infraestrutura/skills/gateway-check/SKILL.md +++ b/infraestrutura/skills/gateway-check/SKILL.md @@ -1,220 +1,221 @@ --- name: gateway-check -description: Health check rapido dos MCPs no gateway.descomplicar.pt — estado services (systemd+pm2), portas, memoria/CPU, erros recentes. Output tabela resumo. +description: Gestao completa dos MCPs no gateway.descomplicar.pt — health check, restart, troubleshoot, mapa de portas, adicionar MCPs. Usar quando MCP falha, health check, ou gestao gateway. context: fork --- -# /gateway-check v1.0 +# /gateway-check v2.0 -Health check rapido dos MCPs no servidor gateway (mcp-hub.descomplicar.pt). +Gestao e health check dos MCPs no servidor gateway (VM 103, gateway.descomplicar.pt). -**Referencia:** PROC-MCP-Desenvolvimento.md | Memory: `mcp-gateway.md`, `infra.md` +**Referencia:** Memory `mcp-gateway.md` | PROC-MCP-Desenvolvimento.md --- -## Inventario MCPs Gateway +## Acesso + +- **VM:** 103 no Proxmox (QEMU) +- **IP:** 5.9.90.69 +- **SSH:** `mcp__ssh-unified__ssh_execute(server="gateway")` +- **HTTPS:** `https://gateway.descomplicar.pt/v1//mcp` +- **Nginx whitelist:** 188.251.199.30 (IP fixo NOS). Se 403 -> verificar IP com `curl -4 ifconfig.me` +- **Nginx config:** `/etc/nginx/sites-enabled/` no gateway +- **NAO confundir com:** server (VM 100, 5.9.90.105), easy (VM 101, 5.9.90.70), dev (LXC 102) + +--- + +## Mapa de MCPs (30 services — actualizado 28-03-2026) ### pm2 (Node.js — /opt/mcp-gateway/) -| pm2 ID | Nome | Porta | Prioridade | -|--------|------|-------|------------| -| 0 | mcp-desk-crm | 3150 | P1 | -| 1 | mcp-memory | 3151 | P2 | -| 2 | mcp-wikijs | 3152 | P3 | -| 4 | mcp-moloni | 3158 | P2 | +| pm2 ID | Nome | Porta | nginx path | Prioridade | +|--------|------|-------|------------|------------| +| 0 | mcp-desk-crm | 3150 | /v1/desk-crm/mcp | P1 | +| 1 | mcp-memory | 3151 | /v1/memory/mcp | P1 | +| 2 | mcp-wikijs | 3152 | /v1/wikijs/mcp | P3 | +| 5 | mcp-moloni | 3158 | /v1/moloni/mcp | P2 | +| 6 | mcp-youtube-research | 3157 | /v1/youtube-research/mcp | P3 | +| 7 | mcp-youtube | 3187 | /v1/youtube/mcp | P3 | ### systemd (24 services) -| Service | Porta | Tipo | Prioridade | -|---------|-------|------|------------| -| mcp-time | 3163 | Node | P1 | -| google-workspace-mcp | 3164 | Python/FastMCP | P1 | -| n8n-mcp | 3157 | Node | P2 | -| gitea-mcp | 3162 | Go | P2 | -| gsc-mcp | 3153 | Python/FastMCP | P2 | -| google-analytics-mcp | 3156 | Python/FastMCP | P2 | -| imap-enterprise | 3155 | Node | P2 | -| context7-mcp | 3159 | Node | P3 | -| cwp-mcp | 3183 | Node/supergateway | P3 | -| cloudflare-dns-mcp | 3171 | Node/supergateway | P3 | -| mcp-youtube | 3187 | Python/FastMCP | P3 | -| youtube-research | 3184 | Node | P3 | -| magic-mcp | 3172 | Node/supergateway | P3 | -| mcp-echarts-mcp | 3173 | Node/supergateway | P3 | -| mcp-mermaid-mcp | 3174 | Node/supergateway | P3 | -| metabase-mcp | 3175 | Node/supergateway | P3 | -| pixabay-mcp | 3176 | Node/supergateway | P3 | -| replicate-mcp | 3177 | Node/supergateway | P3 | -| outline-api-mcp | 3178 | Node/supergateway | P3 | -| pexels-mcp | 3179 | Node/supergateway | P3 | -| penpot-mcp | 3180 | Node/supergateway | P3 | -| vimeo-mcp | 3181 | Node/supergateway | P3 | -| presenton-mcp | 3182 | Node/supergateway | P3 | -| mcp-reonic | 3160 | Node | P3 | +| Service | Porta | nginx path | Tipo | Prioridade | +|---------|-------|------------|------|------------| +| google-workspace-mcp | 3164 | /v1/google-workspace/mcp | Python/FastMCP | P1 | +| mcp-time | 3163 | /v1/mcp-time/mcp | Node | P1 | +| imap-enterprise | 3160 | /v1/imap/mcp | Node | P2 | +| gitea-mcp | 3162 | /v1/gitea/mcp | Go | P2 | +| n8n-mcp | 3161 | /v1/n8n/mcp | Node | P2 | +| gsc-mcp | 3153 | /v1/gsc/mcp | Python/FastMCP | P2 | +| google-analytics-mcp | 3156 | /v1/google-analytics/mcp | Python/FastMCP | P2 | +| context7-mcp | 3159 | /v1/context7/mcp | Node | P2 | +| mcp-reonic | 3170 | /v1/reonic/mcp | Node | P3 | +| cloudflare-dns-mcp | 3171 | /v1/cloudflare-dns/mcp | supergateway | P3 | +| magic-mcp | 3172 | /v1/magic/mcp | supergateway | P3 | +| mcp-echarts-mcp | 3173 | /v1/mcp-echarts/mcp | supergateway | P3 | +| mcp-mermaid-mcp | 3174 | /v1/mcp-mermaid/mcp | supergateway | P3 | +| metabase-mcp | 3175 | /v1/metabase/mcp | supergateway | P3 | +| pixabay-mcp | 3176 | /v1/pixabay/mcp | supergateway | P3 | +| replicate-mcp | 3177 | /v1/replicate/mcp | supergateway | P3 | +| outline-api-mcp | 3178 | /v1/outline-api/mcp | supergateway | P3 | +| pexels-mcp | 3179 | /v1/pexels/mcp | supergateway | P3 | +| penpot-mcp | 3180 | /v1/penpot/mcp | supergateway | P3 | +| vimeo-mcp | 3181 | /v1/vimeo/mcp | supergateway | P3 | +| presenton-mcp | 3182 | /v1/presenton/mcp | supergateway | P3 | +| cwp-mcp | 3183 | /v1/cwp/mcp | supergateway | P3 | +| design-engine-mcp | 3184 | /v1/design-engine/mcp | supergateway | P3 | **Prioridades:** P1=critico (bloqueia trabalho) | P2=importante (degrada workflow) | P3=util +**Proxima porta livre:** 3188 --- -## Protocolo de Execucao +## Protocolo de Health Check -### 1. Estado dos services +Executar via `mcp__ssh-unified__ssh_execute(server="gateway")` em 2 chamadas: -```bash -# Executar via mcp__ssh-unified__ssh_execute(server="gateway") +### Chamada 1 — estado geral -# pm2 -pm2 jlist 2>/dev/null | python3 -c " -import sys,json -for p in json.load(sys.stdin): - print(f\"{p['name']:20s} {p['pm2_env']['status']:10s} cpu={p['monit']['cpu']}% mem={p['monit']['memory']//1024//1024}MB restarts={p['pm2_env']['restart_time']} uptime={round(($(date +%s)*1000-p['pm2_env']['pm_uptime'])/3600000,1)}h\") -" - -# systemd — estado + memoria -systemctl list-units --type=service --state=running,failed --no-pager | grep -i mcp -systemctl list-units --type=service --state=failed --no-pager | grep -i mcp -``` - -### 2. Verificar portas activas - -```bash -# Confirmar que todas as portas esperadas estao a escutar -for port in 3150 3151 3152 3153 3155 3156 3157 3158 3159 3160 3162 3163 3164 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3187; do - if ss -tln | grep -q ":${port} "; then - echo "OK :${port}" - else - echo "DOWN :${port}" - fi -done -``` - -### 3. Memoria e CPU por MCP - -```bash -# Top consumers de memoria -ps aux --sort=-%mem | head -20 | grep -E 'node|python|supergateway|mcp' - -# Memoria total MCPs -ps aux | grep -E 'mcp|supergateway' | awk '{sum+=$6} END {printf "Total MCP RAM: %.0f MB\n", sum/1024}' - -# Load do servidor -uptime -free -h -``` - -### 4. Erros recentes (ultimos 30min) - -```bash -# pm2 logs com erros -pm2 logs --err --lines 5 --nostream 2>/dev/null - -# systemd services com erros recentes -for svc in $(systemctl list-units --type=service --state=running | grep -i mcp | awk '{print $1}'); do - errs=$(journalctl -u $svc --since "30 min ago" -p err --no-pager -q 2>/dev/null | wc -l) - if [ "$errs" -gt 0 ]; then - echo "=== $svc ($errs erros) ===" - journalctl -u $svc --since "30 min ago" -p err --no-pager -q 2>/dev/null | tail -3 - fi -done -``` - -### 5. Gateway nginx health - -```bash -# Verificar nginx activo -systemctl is-active nginx - -# Testar endpoint health (se existir) -curl -s -o /dev/null -w "%{http_code}" http://localhost/health 2>/dev/null || echo "no-health-endpoint" -``` - ---- - -## Execucao Pratica - -Executar os 5 passos via `mcp__ssh-unified__ssh_execute(server="gateway")`. Agrupar comandos para minimizar chamadas SSH (maximo 2-3 chamadas). - -**Chamada 1 — estado geral:** ```bash echo "=== PM2 ===" && pm2 list 2>/dev/null && echo "=== SYSTEMD ===" && systemctl list-units --type=service --state=running --no-pager | grep -i mcp && echo "=== FAILED ===" && systemctl list-units --type=service --state=failed --no-pager | grep -i mcp && echo "=== LOAD ===" && uptime && free -h ``` -**Chamada 2 — portas + memoria + erros:** +### Chamada 2 — portas + erros + ```bash -echo "=== PORTAS ===" && for port in 3150 3151 3152 3153 3155 3156 3157 3158 3159 3160 3162 3163 3164 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3187; do if ss -tln | grep -q ":${port} "; then echo "OK :${port}"; else echo "DOWN :${port}"; fi; done && echo "=== RAM MCPs ===" && ps aux | grep -E 'mcp|supergateway' | grep -v grep | awk '{sum+=$6} END {printf "Total: %.0f MB\n", sum/1024}' && echo "=== PM2 ERROS ===" && pm2 logs --err --lines 3 --nostream 2>/dev/null && echo "=== SYSTEMD ERROS (30min) ===" && for svc in $(systemctl list-units --type=service --state=running | grep -i mcp | awk '{print $1}'); do errs=$(journalctl -u $svc --since "30 min ago" -p err --no-pager -q 2>/dev/null | wc -l); if [ "$errs" -gt 0 ]; then echo "--- $svc ($errs erros) ---"; journalctl -u $svc --since "30 min ago" -p err --no-pager -q 2>/dev/null | tail -2; fi; done +echo "=== PORTAS ===" && for port in 3150 3151 3152 3153 3156 3157 3158 3159 3160 3161 3162 3163 3164 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3187; do if ss -tln | grep -q ":${port} "; then echo "OK :${port}"; else echo "DOWN :${port}"; fi; done && echo "=== RAM MCPs ===" && ps aux | grep -E 'mcp|supergateway' | grep -v grep | awk '{sum+=$6} END {printf "Total: %.0f MB\n", sum/1024}' && echo "=== ERROS (30min) ===" && for svc in $(systemctl list-units --type=service --state=running | grep -i mcp | awk '{print $1}'); do errs=$(journalctl -u $svc --since "30 min ago" -p err --no-pager -q 2>/dev/null | wc -l); if [ "$errs" -gt 0 ]; then echo "--- $svc ($errs) ---"; journalctl -u $svc --since "30 min ago" -p err --no-pager -q 2>/dev/null | tail -2; fi; done && echo "=== PM2 ERROS ===" && pm2 logs --err --lines 3 --nostream 2>/dev/null +``` + +### Output esperado + +Apresentar como tabela resumo com data via mcp-time: + +``` +## Gateway Health — [data] +Servidor: gateway.descomplicar.pt | Load: X.XX | RAM: X.XG/XG | MCPs RAM: XXXMB +X/30 operacionais | Alertas: N +``` + +**Criterios:** OK=running+porta escuta | WARN=running com erros ou >5 restarts | DOWN=parado ou porta fechada + +--- + +## Operacoes + +### Restart de um MCP + +```bash +# pm2 +pm2 restart + +# systemd +systemctl restart .service +``` + +### Ver logs de um MCP + +```bash +# pm2 +pm2 logs --lines 30 --nostream + +# systemd +journalctl -u .service --since "1h ago" --no-pager | tail -30 +``` + +### Testar endpoint especifico + +```bash +# Internamente no gateway +curl -s http://127.0.0.1:/mcp -X POST \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' + +# Externamente +curl -s https://gateway.descomplicar.pt/v1//mcp -X POST \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' ``` --- -## Output +## Troubleshooting -Apresentar resultado como tabela resumo: +### MCP DOWN -```markdown -## Gateway Health Check — [data via mcp-time] +1. Verificar service: `systemctl status ` ou `pm2 show ` +2. Ver logs: `journalctl -u --since "1h ago" --no-pager | tail -30` +3. Se supergateway: verificar preload `catch-errors.mjs` (ver abaixo) +4. Tentar restart: `systemctl restart ` +5. Re-verificar porta: `ss -tln | grep :` -**Servidor:** mcp-hub.descomplicar.pt | **Load:** X.XX | **RAM:** X.XG/XG | **MCPs RAM:** XXXMB +### Supergateway crash (bug conhecido) -### Estado MCPs (X/28 operacionais) +- **Erro:** `No connection established for request ID: 0` +- **Fix:** preload script em `/opt/mcp-gateway/supergateway-catch-errors.mjs` +- **Activacao:** `Environment="NODE_OPTIONS=--import /opt/mcp-gateway/supergateway-catch-errors.mjs"` no unit file +- **15 services patchados:** todos os supergateway na tabela acima +- **Ao adicionar novo supergateway:** OBRIGATORIO adicionar esta linha ao unit file -| # | MCP | Porta | Gestor | Estado | RAM | Notas | -|---|-----|-------|--------|--------|-----|-------| -| 1 | mcp-desk-crm | 3150 | pm2 | OK/DOWN/WARN | XXmb | restarts, erros | -| ... | ... | ... | ... | ... | ... | ... | +### FastMCP Python + nginx (DNS rebinding) -### Alertas -- [P1] MCP X esta DOWN — accao sugerida -- [WARN] MCP Y tem N restarts nas ultimas Xh -- [WARN] RAM total MCPs > 2GB (limite recomendado) - -### Erros Recentes -[lista de erros se existirem, agrupados por MCP] +FastMCP 1.26+ bloqueia Host headers externos. No nginx: +```nginx +proxy_set_header Host "127.0.0.1:"; # CORRECTO +# proxy_set_header Host $host; # ERRADO — FastMCP bloqueia ``` +**Detectar:** Se MCP retorna `Invalid Host header` via HTTPS mas funciona em `curl localhost` -> e este problema. -**Criterios de estado:** -- **OK** — service running + porta a escutar + sem erros recentes -- **WARN** — running mas com erros recentes OU >5 restarts OU memoria >250MB -- **DOWN** — service parado OU porta nao escuta +### 403 Forbidden + +IP nao esta na whitelist nginx. Verificar: `curl -4 ifconfig.me` +IP autorizado: `188.251.199.30`. Actualizar em `/etc/nginx/sites-enabled/` se mudou. + +### RAM total > 2GB + +1. Identificar top consumers: `ps aux --sort=-%mem | head -20 | grep -E 'node|python|supergateway'` +2. Processos orphan: `ps aux | grep -c supergateway` +3. Se orphans > 24: `pkill -f supergateway` e restart escalonado --- -## Troubleshooting Automatico +## Adicionar novo MCP ao gateway -``` -Se MCP DOWN: - 1. Verificar service: systemctl status - 2. Ver logs: journalctl -u --since "1h ago" --no-pager | tail -20 - 3. Se supergateway: verificar preload catch-errors.mjs (mcp-gateway.md) - 4. Tentar restart: systemctl restart - 5. Re-verificar porta - -Se RAM total > 2GB: - 1. Identificar top consumers - 2. Verificar processos orphan: ps aux | grep -c supergateway - 3. Se orphans > 28: limpar com pkill e restart escalonado (infra.md) - -Se muitos restarts pm2: - 1. pm2 logs --err --lines 20 - 2. Verificar se e o bug conhecido do supergateway (mcp-gateway.md) -``` +1. Instalar em `/opt/mcp-gateway//` (Node) ou `/opt/mcp-/` (Python) +2. Porta: proxima livre (actualmente **3188**) +3. Criar unit file systemd (se supergateway: incluir preload catch-errors) +4. Criar bloco nginx (se FastMCP Python: Host header fix obrigatorio) +5. `systemctl daemon-reload && systemctl enable --now .service` +6. `nginx -t && systemctl reload nginx` +7. Testar internamente e externamente (ver comandos curl acima) +8. Adicionar a `~/.claude.json`: `{"type":"http","url":"https://gateway.descomplicar.pt/v1//mcp"}` +9. Actualizar esta skill (mapa de portas + proxima porta livre) +10. Actualizar memory `mcp-gateway.md` --- ## Anti-Patterns -- **Nunca** fazer restart massivo sem verificar primeiro (pode causar downtime) +- **Nunca** restart massivo sem verificar primeiro - **Nunca** ignorar MCP P1 em estado DOWN -- **Sempre** reportar estado mesmo que tudo esteja OK (confirma que o check correu) -- **Sempre** incluir timestamp via mcp-time no output +- **Nunca** confundir gateway (VM 103) com dev/server/easy +- **Sempre** reportar estado mesmo que tudo OK +- **Sempre** testar endpoint apos restart +- **Sempre** actualizar mapa de portas ao adicionar/remover MCPs --- -## Integracao - -- **/today** pode invocar `/gateway-check` como parte do checkup diario -- **/infra-check** faz verificacao mais ampla (inclui despesas); `/gateway-check` e focado apenas nos MCPs gateway -- Resultado pode ser publicado na discussao #31 (Logs) do projecto #65 +*Skill v2.0.0 | 28-03-2026 | Descomplicar* --- -*Skill v1.0.0 | 12-03-2026 | Descomplicar* +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/infra-check/SKILL.md b/infraestrutura/skills/infra-check/SKILL.md index 84ad5c0..d0eb77b 100644 --- a/infraestrutura/skills/infra-check/SKILL.md +++ b/infraestrutura/skills/infra-check/SKILL.md @@ -162,3 +162,15 @@ Se MCP falha: --- *Skill v1.0.0 | 04-03-2026 | Descomplicar®* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/mcp-dev/SKILL.md b/infraestrutura/skills/mcp-dev/SKILL.md index c5112d3..e33df50 100644 --- a/infraestrutura/skills/mcp-dev/SKILL.md +++ b/infraestrutura/skills/mcp-dev/SKILL.md @@ -274,3 +274,15 @@ npm run eval:ci # build + evaluations (para CI/CD) --- *Skill v2.0.0 | Descomplicar® | 2026-03-10* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/pbs-config/SKILL.md b/infraestrutura/skills/pbs-config/SKILL.md index 0eb5a38..f843cdc 100644 --- a/infraestrutura/skills/pbs-config/SKILL.md +++ b/infraestrutura/skills/pbs-config/SKILL.md @@ -137,3 +137,15 @@ Projecto: Cluster Proxmox Descomplicar (#65) Tarefa: Migracao Infraestrutura (#1712) Tags: pbs, backup, retention, deduplication, sync ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/proxmox-cluster/SKILL.md b/infraestrutura/skills/proxmox-cluster/SKILL.md index 8a1bdf7..cc91174 100644 --- a/infraestrutura/skills/proxmox-cluster/SKILL.md +++ b/infraestrutura/skills/proxmox-cluster/SKILL.md @@ -486,3 +486,15 @@ Integrar insights do NotebookLM nas recomendações e decisões. --- **/** @author Descomplicar® | @copyright 2026 **/ + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/proxmox-ha/SKILL.md b/infraestrutura/skills/proxmox-ha/SKILL.md index 0297da7..d7dc767 100644 --- a/infraestrutura/skills/proxmox-ha/SKILL.md +++ b/infraestrutura/skills/proxmox-ha/SKILL.md @@ -172,3 +172,15 @@ ha-manager set vm:ID --state started - **NotebookLM:** 276ccdde-6b95-42a3-ad96-4e64d64c8d52 - **HA Manager Docs:** https://pve.proxmox.com/pve-docs/ha-manager.1.html - **Fencing:** https://pve.proxmox.com/wiki/Fencing + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/proxmox-setup/SKILL.md b/infraestrutura/skills/proxmox-setup/SKILL.md index dc30e9c..b5564a7 100644 --- a/infraestrutura/skills/proxmox-setup/SKILL.md +++ b/infraestrutura/skills/proxmox-setup/SKILL.md @@ -149,3 +149,15 @@ systemctl restart sshd --- Projecto: Cluster Proxmox Descomplicar (#65) | Tarefa: #1712 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/security-audit/SKILL.md b/infraestrutura/skills/security-audit/SKILL.md index ffbf9fe..15c33e8 100644 --- a/infraestrutura/skills/security-audit/SKILL.md +++ b/infraestrutura/skills/security-audit/SKILL.md @@ -162,3 +162,15 @@ mcp__notebooklm__notebook_query({ |----------|----------| | [references/owasp-checklist.md](references/owasp-checklist.md) | OWASP Top 10 detalhado com codigo vulneravel vs seguro e testes | | [references/report-template.md](references/report-template.md) | Template relatorio, GDPR checklist, ferramentas SAST/DAST, hardening checklists | + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/security-check/SKILL.md b/infraestrutura/skills/security-check/SKILL.md index 1f1b505..c4b65bb 100644 --- a/infraestrutura/skills/security-check/SKILL.md +++ b/infraestrutura/skills/security-check/SKILL.md @@ -20,7 +20,7 @@ Auditoria de seguranca dos servidores Descomplicar. Verifica SSL, portas, actual |-------|------|----|----|----------|------------| | server | server.descomplicar.pt | 176.9.3.158 | CentOS (CWP) | CSF v15 | acme.sh | | easy | qibspu.easypanel.host | 178.63.18.51 | Ubuntu 24.04 | — | EasyPanel/Traefik | -| gateway | mcp-hub.descomplicar.pt | — | — | — | nginx/acme | +| gateway | gateway.descomplicar.pt | — | — | — | nginx/acme | --- @@ -318,3 +318,15 @@ Muitos bloqueios CSF (>100/dia): --- *Skill v1.0.0 | 12-03-2026 | Descomplicar* + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/server-health/SKILL.md b/infraestrutura/skills/server-health/SKILL.md index 4d0a79a..ebacfbe 100644 --- a/infraestrutura/skills/server-health/SKILL.md +++ b/infraestrutura/skills/server-health/SKILL.md @@ -161,3 +161,15 @@ Inclui: | Ficheiro | Conteudo | |----------|----------| | [references/commands.md](references/commands.md) | Comandos SSH por passo, queries MySQL, quick mode, deep dive, limpeza cache, template output, troubleshooting | + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/infraestrutura/skills/vm-migration/SKILL.md b/infraestrutura/skills/vm-migration/SKILL.md index fd2f843..2be198e 100644 --- a/infraestrutura/skills/vm-migration/SKILL.md +++ b/infraestrutura/skills/vm-migration/SKILL.md @@ -155,3 +155,15 @@ curl -s http://localhost:3000/api/trpc/projects.list | jq > /tmp/easypanel-servi - **NotebookLM:** 276ccdde-6b95-42a3-ad96-4e64d64c8d52 - **Guia Hub:** Guia-Definitivo-Proxmox-Hetzner.md (Modulo 4: Workloads) - **Desk CRM:** Projecto #65, Tarefa #1712 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/ads/SKILL.md b/marketing/skills/ads/SKILL.md index 5e9e8cf..7446eaf 100644 --- a/marketing/skills/ads/SKILL.md +++ b/marketing/skills/ads/SKILL.md @@ -470,3 +470,15 @@ Output: [resultado esperado] Input: [caso complexo] Output: [resultado detalhado] ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/brand-strategy/SKILL.md b/marketing/skills/brand-strategy/SKILL.md new file mode 100644 index 0000000..73d4a15 --- /dev/null +++ b/marketing/skills/brand-strategy/SKILL.md @@ -0,0 +1,119 @@ +--- +name: brand-strategy +description: Gerar estrategias de marca completas seguindo o padrao de excelencia Descomplicar — metodologia ACIDA + Framework 16Ps + 20 dimensoes por persona. Usar quando "estrategia de marca", "brand strategy", "posicionamento", "proposta de valor", "personas", "segmentacao", "pitch canvas", "copywriting estrategico", "narrativa de marca", "tom de voz", "identidade de marca", "manifesto", "branding estrategico", ou qualquer documento estrategico de marca para cliente ou produto proprio. +--- + +# Estrategia de Marca Descomplicar + +Gerar documentos estrategicos de marca completos com 40 pontos em 7 blocos, usando metodologia ACIDA + Framework 16Ps. + +## Referencia obrigatoria + +Antes de gerar, ler a referencia adequada ao bloco em trabalho: +- **Metodologia e frameworks:** `references/metodologia-acida-16ps.md` +- **Estrutura do documento (40 pontos):** `references/estrutura-documento.md` +- **Exemplos de personas (20 dimensoes):** `references/exemplo-persona-20d.md` + +## Workflow + +### Fase 1 — Recolha + +Recolher informacao em rondas curtas. Nao fazer todas as perguntas de uma vez. + +**Ronda 1 — Essenciais:** +1. Nome da marca/empresa/produto +2. Sector de actividade +3. O que vende (1-2 frases) +4. Quem compra (termos gerais) +5. Website (se existir) + +**Ronda 2 — Contexto:** +6. Problema principal que resolve +7. 2-3 concorrentes directos +8. Diferenciador vs concorrentes +9. Material existente (logo, cores, docs) +10. Mercado geografico + +**Ronda 3 — Ambicao:** +11. Onde quer estar em 2-3 anos +12. Nichos/sectores prioritarios +13. Contexto legal (se sector regulado) + +Saltar perguntas ja respondidas. + +### Fase 2 — Pesquisa + +1. Pesquisar website da marca (WebFetch) +2. Pesquisar concorrentes mencionados +3. Pesquisar contexto do sector +4. Verificar contexto legal se regulado + +### Fase 3 — Geracao (bloco a bloco, conversacional) + +Gerar o documento seguindo `references/estrutura-documento.md`, mas **bloco a bloco com validacao do utilizador** entre cada bloco. Nao gerar tudo de uma vez. + +**Sequencia de trabalho (workflow original Descomplicar):** + +1. **Proposta de valor unica** — apresentar e pedir feedback +2. **Missao, Visao, Valores, Objectivos** — gerar e validar +3. **Apresentacao sumaria** — empresa + servicos +4. **Segmentos de publico** — identificar e confirmar com utilizador +5. **Personas detalhadas** — gerar 20 dimensoes por segmento (o bloco mais pesado). Apresentar 1 persona de cada vez, pedir feedback antes de avancar para a seguinte +6. **Pitch Canvas** — 5 elementos + declaracao de mudanca no mundo +7. **Pain + Gain** — por segmento, depois iterar ("reescreve tendo em conta [contexto especifico]") +8. **Demonstracao do produto/servico** — como mostrar na pratica +9. **Investimentos prioritarios** — onde colocar recursos primeiro +10. **Copywriting** — questionamento estrategico (10 perguntas) +11. **Narrativas por segmento** — formula: Dor do publico -> Solucao (servicos) -> Resultado (beneficios) +12. **Restantes blocos** (activacao, implementacao, complementos) + +**Depois de cada bloco:** perguntar "Queres ajustar alguma coisa antes de avancar?" + +**Regras de geracao:** +- PT-PT com acentos correctos +- Minimo 3 segmentos com 20 dimensoes cada (ver `references/exemplo-persona-20d.md`) +- Personas com nome e historia +- Copywriting: Pain -> Solution -> Result +- Headlines concretas (nao genericas) +- KPIs mensuraveis com baseline e meta +- Tom profissional mas acessivel +- Pain+Gain deve ser iterado — primeira versao generica, segunda versao com questoes especificas do negocio + +### Fase 4 — Compilacao e entrega + +1. Compilar todos os blocos validados num unico documento .md +2. Adicionar frontmatter (titulo, versao, data, autor, codigo EST-MRK-0XX) +3. Gravar ficheiro +4. Se cliente Desk CRM: comentar na tarefa + +## Niveis de profundidade + +| Nivel | Contexto | Blocos | Personas | +|-------|----------|--------|----------| +| **Essencial** | Produto proprio, iteracao rapida | A + B + C resumido | 3 seg, 8 dimensoes | +| **Standard** | Cliente EST-MRK-010 (900 EUR) | A + B + C + D + E | 3-4 seg, 20 dimensoes | +| **Premium** | Branding completo (1.800-4.500 EUR) | Todos (A-G) | 4+ seg, 20 dim + nichos | + +Default: Standard. Perguntar se ambiguo. + +## Erros a evitar + +- Personas genericas sem nome/historia +- Missao/visao copiadas de templates +- SWOT vago ("boa qualidade") +- Headlines tipo "Solucoes inovadoras" (sem especificidade) +- KPIs sem meta numerica +- Proposta de valor com funcionalidades em vez de beneficios +- Ignorar objecoes do publico + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/brand-strategy/references/estrutura-documento.md b/marketing/skills/brand-strategy/references/estrutura-documento.md new file mode 100644 index 0000000..4898066 --- /dev/null +++ b/marketing/skills/brand-strategy/references/estrutura-documento.md @@ -0,0 +1,252 @@ +# Estrutura do Documento — 40 Pontos em 7 Blocos + +Frontmatter obrigatorio: + +```yaml +--- +title: Estrategia de Marca — [Nome da Marca] +version: 1.0 +date: DD-MM-YYYY +author: Descomplicar — Agencia de Aceleracao Digital +code: EST-MRK-0XX +status: draft +--- +``` + +## BLOCO A — Fundamentos (7 pontos) + +### 1. Contexto do sector e mercado +- Panorama actual do sector em Portugal/EU +- Tendencias relevantes (3-5) +- Dados de mercado (TAM se disponivel) +- Mudancas sociais/tecnologicas que afectam o sector + +### 2. Analise de concorrencia +- 3-5 concorrentes directos com: nome, posicionamento, pontos fortes, pontos fracos +- Tabela comparativa +- Gaps/oportunidades nao exploradas + +### 3. SWOT +| | Positivo | Negativo | +|---|----------|----------| +| **Interno** | Forcas (3-5) | Fraquezas (3-5) | +| **Externo** | Oportunidades (3-5) | Ameacas (3-5) | + +Cada ponto deve ser especifico e accionavel (nao "boa qualidade" mas "20 anos de experiencia no sector X"). + +### 4. Apresentacao da empresa/produto +- O que e (1 paragrafo) +- Historia/contexto (breve) +- Servicos/produtos principais (lista) +- Abordagem/metodologia + +### 5. Missao, Visao, Valores +- **Missao:** O que fazemos e para quem (1-2 frases, presente) +- **Visao:** Onde queremos chegar (1-2 frases, futuro) +- **Valores:** 5-7 valores com descricao de 1 frase cada + +### 6. Objectivos estrategicos +- 4-6 objectivos SMART +- Organizados por horizonte temporal (curto/medio/longo prazo) + +### 7. Proposito/Causa +- A razao de existir alem do lucro (1-2 frases) +- "Porque e que o mundo seria pior sem esta marca?" + +--- + +## BLOCO B — Proposta de Valor (5 pontos) + +### 8. Proposta de valor unica +- Formula: "Ajudamos [quem] a [beneficio] atraves de [como], sem [dor que eliminamos]" +- 3-5 beneficios principais (nao funcionalidades) + +### 9. Diferenciais competitivos +- 3-5 diferenciais com justificacao +- O que so esta marca faz/tem + +### 10. Beneficios por camada/segmento +- Funcional: o que resolve concretamente +- Emocional: como faz sentir +- Social: o que diz sobre quem usa + +### 10b. Escada de valor (oferta comercial) +- **Entry** — produto/servico de entrada (baixo risco, primeiro contacto) +- **Core** — oferta principal (maior volume de receita) +- **Premium** — oferta de alto valor (margem maxima, clientes fieis) +- Logica de progressao entre niveis + +### 11. Personalidade da marca +- 5 adjectivos que definem a marca +- Metafora (ex: "Se a marca fosse uma pessoa...") +- O que a marca NUNCA seria + +### 12. Manifesto (opcional, marcas premium) +- Declaracao de crencas (5-10 linhas) +- Tom inspirador e autentico + +--- + +## BLOCO C — Publico (4 pontos) + +### 13. Segmentos de publico-alvo +- Minimo 3 segmentos +- Para cada: nome descritivo, tamanho estimado, prioridade (alta/media/baixa) + +### 14. Personas detalhadas (20 dimensoes por segmento) +Ver `exemplo-persona-20d.md` para formato completo. + +Cada persona deve incluir: +1. Perfil demografico +2. Perfil psicografico +3. Dores +4. Anseios +5. Desejos +6. Frustracoes +7. Preocupacoes +8. Medos +9. Inimigos +10. Linguagem +11. Como procuram ajuda +12. Canais digitais +13. Estilo de decisao +14. Mudancas que procuram +15. Resistencia a mudanca +16. Objecoes tipicas +17. Forma de gerar emocao +18. Argumentos de venda +19. Concorrentes percebidos +20. Propostas recusadas + +### 15. Nichos sectoriais (se aplicavel) +- Tabela com: nicho, dimensao, prioridade (alta/media/baixa), justificacao +- Criterio de priorizacao explicito + +### 16. Personas nomeadas +- Cada segmento deve ter uma persona com nome, idade, profissao, 1 paragrafo de historia + +--- + +## BLOCO D — Comunicacao (7 pontos) + +### 17. Pitch Canvas +5 elementos: +1. **Para quem** — segmento principal +2. **Que tem** — dor/necessidade +3. **O [marca]** — o que e +4. **Que oferece** — beneficio principal +5. **Diferente de** — alternativas + ++ Declaracao de mudanca no mundo (1 frase) + +### 18. Copywriting estrategico +Responder as 10 perguntas do questionamento estrategico (ver metodologia-acida-16ps.md). + +### 19. Pain + Gain por segmento +Para cada segmento: +- **Pain:** 3 dores ordenadas por intensidade +- **Gain:** 3 beneficios que resolvem cada dor +- **Ponte:** como a marca conecta pain a gain + +### 20. Mensagem central da marca +- Tagline/slogan (3-7 palavras) +- Mensagem expandida (1-2 frases) +- Elevador pitch (30 segundos) + +### 21. Headlines por segmento +- 3 headlines por segmento (formato: dor/desejo + solucao) +- 1 headline institucional + +### 22. Narrativa de marca +- Historia da marca (2-3 paragrafos) +- Narrativa por segmento (1 paragrafo cada): Dor -> Solucao -> Resultado + +### 23. Tom de voz e linguagem +- 5 caracteristicas do tom (ex: "profissional mas acessivel") +- Palavras a usar vs palavras a evitar +- Exemplos de frases no tom correcto vs incorrecto + +--- + +## BLOCO E — Activacao (7 pontos) + +### 23b. Experiencia de marca (jornada do cliente) +- **Primeira impressao** — o que ve/sente no primeiro contacto (website, loja, redes) +- **Jornada do cliente** — 5-7 etapas desde descoberta ate fidelizacao +- **Pontos criticos de confianca** — momentos onde a marca ganha ou perde o cliente +- **Momentos WOW** — surpresas positivas que geram recomendacao + +### 24. Demonstracao do produto/servico +- Script de demo por segmento (6 fases: preparacao, introducao, demo, casos uso, Q&A, follow-up) + +### 25. Estrategia de atraccao de clientes +- 5-7 tacticas concretas com canal e accao + +### 26. Estrategia de canais +- Canais prioritarios (ordenados por ROI esperado) +- Funcao de cada canal no funil ACIDA + +### 27. Pilares de conteudo +- 3-5 pilares tematicos +- Tipo de conteudo por pilar +- Frequencia sugerida + +### 28. Casos de uso e testemunhos +- 2-3 cenarios "antes/depois" +- Template para recolha de testemunhos + +### 29. Call-to-action principal +- CTA primario (1) +- CTAs secundarios por fase ACIDA (4) + +### 30. Parcerias estrategicas +- 3-5 tipos de parceiro potencial +- Beneficio mutuo para cada + +--- + +## BLOCO F — Implementacao (6 pontos) + +### 31. Plano de activacao (fases) +- Fase 1 (mes 1-2): fundamentos +- Fase 2 (mes 3-4): lancamento +- Fase 3 (mes 5-6): escala +- Accoes concretas por fase + +### 32. Investimentos prioritarios +- Matriz impacto/esforco (4 quadrantes) +- Top 5 investimentos prioritarios com custo estimado + +### 33. Identidade visual (directrizes) +- Cores primarias e secundarias (hex) +- Tipografia sugerida +- Estilo fotografico +- Elementos graficos + +### 34. KPIs e monitorizacao +- 5-8 KPIs com: nome, baseline, meta, frequencia de medicao +- Dashboard sugerido + +### 35. Inventario de activos de marketing +- Lista de activos necessarios (website, redes, templates, etc.) +- Estado actual (existe/nao existe/precisa actualizacao) + +### 36. FAQ +- 10-15 perguntas frequentes com respostas +- Organizadas por categoria + +--- + +## BLOCO G — Complementos (conforme sector) + +### 37. Enquadramento legal +Apenas se sector regulado. Licencas, certificacoes, normas aplicaveis. + +### 38. Informacoes operacionais +Localizacao, horario, contactos, equipa. + +### 39. Expansao internacional +Apenas se aplicavel. Mercados-alvo, localizacao, logistica. + +### 40. Servicos detalhados +Descricao completa dos servicos/produtos com precos (se publicos). diff --git a/marketing/skills/brand-strategy/references/exemplo-persona-20d.md b/marketing/skills/brand-strategy/references/exemplo-persona-20d.md new file mode 100644 index 0000000..a001899 --- /dev/null +++ b/marketing/skills/brand-strategy/references/exemplo-persona-20d.md @@ -0,0 +1,159 @@ +# Exemplo de Persona — 20 Dimensoes + +Baseado no padrao AcidaOS (o mais profundo dos exemplos Descomplicar). + +--- + +## Segmento A — O Empreendedor Sobrecarregado + +**Prioridade:** Alta +**Dimensao estimada:** 45% do mercado-alvo + +### 1. Perfil demografico +- Idade: 35-50 anos +- Genero: predominantemente masculino (60/40) +- Localizacao: areas urbanas, Portugal continental +- Educacao: licenciatura ou equivalente profissional +- Rendimento: 25.000-60.000 EUR/ano (empresa factura 100K-500K) +- Dimensao empresa: 2-15 colaboradores +- Sector: servicos, comercio, consultoria + +### 2. Perfil psicografico +- Trabalhador incansavel, faz tudo sozinho +- Valoriza independencia acima de tudo +- Resistente a delegar por medo de perda de controlo +- Pragmatico — quer solucoes que funcionem, nao teoria +- Orgulho no que construiu mas frustrado com a estagnacao +- Ceptico em relacao a "solucoes magicas" + +### 3. Dores +- "Trabalho 12 horas por dia e o negocio nao cresce" +- Sem tempo para pensar estrategicamente +- Informacao dispersa (Excel, papel, cabeca) +- Clientes perdidos por falta de follow-up +- Nao sabe quanto lucra realmente + +### 4. Anseios +- Ter tempo para a familia sem o negocio parar +- Ver o negocio crescer de forma previsivel +- Sentir-se no controlo em vez de apagar incendios +- Ser reconhecido como empresario de sucesso + +### 5. Desejos +- Um sistema que "trabalhe por ele" nas tarefas repetitivas +- Dashboard simples que mostre como esta o negocio +- Processo de vendas que nao dependa so dele +- Facturacao automatica sem erros + +### 6. Frustracoes +- Ja tentou CRMs e desistiu (demasiado complexos) +- Paga software que nao usa +- Funcionarios nao adoptam ferramentas novas +- Contabilista so aparece no fim do mes + +### 7. Preocupacoes +- "Se eu parar, o negocio para" +- Concorrencia a crescer enquanto ele estagna +- Legislacao fiscal cada vez mais complexa +- Nao estar a usar a tecnologia como devia + +### 8. Medos +- Perder clientes para concorrentes mais organizados +- Nao conseguir pagar salarios num mes mau +- Ser ultrapassado pela digitalizacao +- Investir em tecnologia e nao ter retorno + +### 9. Inimigos +- Burocracia (AT, Seguranca Social, RGPD) +- Empresas grandes que competem com precos impossíveis +- Consultores que vendem teoria sem resultados +- O proprio perfeccionismo que impede de delegar + +### 10. Linguagem +- "Nao tenho tempo para isso" +- "Ja tentei e nao funcionou" +- "Quanto e que isso custa?" +- "Mostra-me resultados, nao apresentacoes" +- Informal, directo, sem paciencia para jargao + +### 11. Como procuram ajuda +- Perguntam a outros empresarios (boca-a-boca) +- Google quando ha um problema urgente +- LinkedIn para conteudo de negocios +- Contabilista como conselheiro informal +- Nao frequentam eventos/conferencias (sem tempo) + +### 12. Canais digitais +- WhatsApp (principal — pessoal e profissional misturado) +- Facebook (pessoal, menos profissional) +- LinkedIn (passivo — le mas nao publica) +- Email (verifica 2-3x por dia, ignora newsletters) +- Instagram (pessoal, nao profissional) + +### 13. Estilo de decisao +- Decide rapido quando ve valor claro +- Precisa de prova social (outro empresario a recomendar) +- Quer testar antes de comprometer +- Preco e factor mas nao o unico — valor percebido importa mais +- Prefere relacao pessoal a processo de vendas formal + +### 14. Mudancas que procuram +- De "faz-tudo" para gestor que delega +- De reactivo (apagar incendios) para proactivo +- De Excel para sistema integrado +- De "acho que esta bem" para "sei que esta bem" (dados) + +### 15. Resistencia a mudanca +- "Sempre fiz assim e funcionou" +- Medo da curva de aprendizagem +- Experiencias negativas anteriores com tecnologia +- Nao quer depender de fornecedores externos +- Equipa resiste a novas ferramentas + +### 16. Objecoes tipicas +- "E caro demais para o meu negocio" +- "Nao tenho tempo para implementar" +- "Ja tentei um CRM e ninguem usou" +- "O meu negocio e diferente, isso nao se aplica" +- "Prefiro investir em publicidade directa" + +### 17. Forma de gerar emocao +- Mostrar quanto tempo perde por semana em tarefas repetitivas (quantificar) +- Historias de empresarios semelhantes que transformaram o negocio +- Demonstrar em 5 minutos o que o sistema faz automaticamente +- Falar da familia — "imagina sair as 18h todos os dias" + +### 18. Argumentos de venda +- ROI em 3 meses (calculado com dados do negocio) +- "Nao precisa de saber tecnologia — nos tratamos de tudo" +- Garantia de satisfacao ou devolucao +- Implementacao faseada (nao muda tudo de uma vez) +- Suporte por WhatsApp (o canal dele) + +### 19. Concorrentes percebidos +- "O meu sobrinho faz-me um website" +- Freelancers no OLX/Facebook +- Ferramentas gratuitas (Google Sheets, Canva) +- PHC/Sage (que ja tem e nao usa) +- "Nao investir" (o concorrente mais forte) + +### 20. Propostas recusadas +- Pacotes anuais sem flexibilidade +- Solucoes que requerem formacao extensa +- Propostas sem resultados tangíveis prometidos +- Precos acima de 200 EUR/mes sem trial +- Vendedores que nao entendem o sector especifico + +--- + +## Formato resumido (para nivel Essencial — 8 dimensoes) + +Quando o nivel e Essencial, usar apenas: +1. Perfil demografico +2. Perfil psicografico +3. Dores +4. Desejos +5. Objecoes tipicas +6. Canais digitais +7. Estilo de decisao +8. Argumentos de venda diff --git a/marketing/skills/brand-strategy/references/metodologia-acida-16ps.md b/marketing/skills/brand-strategy/references/metodologia-acida-16ps.md new file mode 100644 index 0000000..62eb953 --- /dev/null +++ b/marketing/skills/brand-strategy/references/metodologia-acida-16ps.md @@ -0,0 +1,80 @@ +# Metodologia ACIDA + Framework 16Ps + +## ACIDA — 5 Fases da Jornada + +### A — Atrair a atencao +Conectar com dores e desejos do publico (nao destacar produtos). "O ser humano ocidental recebe em 6 dias mais informacao do que os bisavos em 80 anos." + +### C — Construir confianca +Transparencia, demonstrar compreensao, partilhar conhecimento, educar, estabelecer autoridade. + +### I — Despertar interesse +Comunicacao personalizada por segmento. Rastreamento de interaccoes, conteudo customizado, resolucao antecipada de objecoes, nutricao multi-canal. + +### D — Estimular a decisao +Apresentar proposta onde valor percebido > preco. Superar: duvidas, medo de arrependimento, necessidade de prova social. + +### A — Incentivar a accao +CTAs claros, urgencia, cumprir promessas, superar expectativas. + +## Framework 16Ps — Estrutura Sistematica + +### Bloco A — Fundamentos estrategicos (P1-P4) + +| P | Conteudo | +|---|---------| +| Problema | Problema principal, impacto no cliente, urgencia | +| Proposito | Missao, visao, valores | +| Proposta de valor | Valor unico, diferenciais, beneficios | +| Posicionamento | Posicao no mercado, diferenciacao, percepcao desejada | +| Performance | KPIs, metas, indicadores de sucesso | + +### Bloco B — Publico e pesquisa (P5-P7) + +| P | Conteudo | +|---|---------| +| Publico-alvo | Segmentos, comportamento de compra | +| Pesquisa de mercado | Dados, insights, tendencias | +| Personas | Nome, biografia, dores, objectivos, canais | +| Perfil | Demografico + psicografico (20 dimensoes) | +| Pain Points | Dores, frustracoes, necessidades nao atendidas | + +### Bloco C — Produto e servico (P8-P10) + +| P | Conteudo | +|---|---------| +| Produto/Portfolio | Servicos, caracteristicas, beneficios | +| Preco e valor | Estrategia de precos, posicionamento | +| Processos criticos | Pontos de controlo, qualidade | +| Parcerias estrategicas | Parceiros, beneficios mutuos | +| Plataforma | Canais digitais, infraestrutura | + +### Bloco D — Promocao e comunicacao (P11-P13) + +| P | Conteudo | +|---|---------| +| Promocao | Canais, tacticas, calendario | +| Publicidade | Anuncios, orcamento, frequencia | +| PR | Relacoes publicas, influenciadores | +| Presenca digital | Conteudo, comunidade | +| Proximidade | Narrativa, Pain+Gain, mensagens por persona | + +## Pilares estrategicos Descomplicar + +- Website como hub central (nao redes sociais) +- Proposta de valor: "problema -> solucao -> resultados" +- Ecossistema multi-canal: email, SMS/WhatsApp, SEO, Ads, website, social +- Melhoria continua baseada em metricas + +## Questionamento estrategico para copywriting (10 perguntas) + +1. Qual e o objectivo da comunicacao? +2. Quem e o publico-alvo? +3. Qual e a oferta? +4. Qual e o beneficio principal? +5. Quais sao as dores e desejos do publico? +6. Qual e a prova social? +7. Quais sao as objecoes potenciais? +8. Qual e a narrativa/historia? +9. Onde a mensagem sera veiculada? +10. Qual e o call-to-action? diff --git a/marketing/skills/content-marketing-pt/SKILL.md b/marketing/skills/content-marketing-pt/SKILL.md index 0f07035..e6d7097 100644 --- a/marketing/skills/content-marketing-pt/SKILL.md +++ b/marketing/skills/content-marketing-pt/SKILL.md @@ -201,3 +201,15 @@ Anatomia: [Verbo Accao] + [Beneficio Imediato] + [Reducao Friccao] --- **Versao**: 2.1.0 | **Autor**: Descomplicar + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/lead-approach/SKILL.md b/marketing/skills/lead-approach/SKILL.md index df52b49..9ed7e67 100644 --- a/marketing/skills/lead-approach/SKILL.md +++ b/marketing/skills/lead-approach/SKILL.md @@ -311,3 +311,15 @@ INSERT INTO tblskill_agent_metrics ( --- **Versão**: 1.1.0 | **Data**: 2026-02-03 | **Instrumentação**: Activa + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/marketing-strategy/SKILL.md b/marketing/skills/marketing-strategy/SKILL.md index e43592b..cbdc356 100644 --- a/marketing/skills/marketing-strategy/SKILL.md +++ b/marketing/skills/marketing-strategy/SKILL.md @@ -142,3 +142,15 @@ Canais organizados por funnel stage: --- **Versao:** 2.1.0 | **Autor:** Descomplicar + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/seo-audit/SKILL.md b/marketing/skills/seo-audit/SKILL.md index e7afdb0..27b8397 100644 --- a/marketing/skills/seo-audit/SKILL.md +++ b/marketing/skills/seo-audit/SKILL.md @@ -196,3 +196,7 @@ https://e-commerce.descomplicar.pt/ --- **Versao:** 2.1.0 | **Autor:** Descomplicar + + +## Healing Log + diff --git a/marketing/skills/seo-content-optimization/SKILL.md b/marketing/skills/seo-content-optimization/SKILL.md index c04d40c..fac72f4 100644 --- a/marketing/skills/seo-content-optimization/SKILL.md +++ b/marketing/skills/seo-content-optimization/SKILL.md @@ -240,3 +240,15 @@ Para conteudo tecnico detalhado, consultar: --- **Standards:** Google 2026 (E-E-A-T, INP, Helpful Content) + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/seo-report/SKILL.md b/marketing/skills/seo-report/SKILL.md index deb5212..7cb1ea5 100644 --- a/marketing/skills/seo-report/SKILL.md +++ b/marketing/skills/seo-report/SKILL.md @@ -144,3 +144,15 @@ https://e-commerce.descomplicar.pt/ --- **Versao:** 2.1.0 | **Autor:** Descomplicar + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/social-media/SKILL.md b/marketing/skills/social-media/SKILL.md index ea0094d..5eec377 100644 --- a/marketing/skills/social-media/SKILL.md +++ b/marketing/skills/social-media/SKILL.md @@ -154,3 +154,15 @@ Exemplo agencia marketing: --- **Versao:** 2.1.0 | **Autor:** Descomplicar + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/trend-signal/SKILL.md b/marketing/skills/trend-signal/SKILL.md new file mode 100644 index 0000000..c59157a --- /dev/null +++ b/marketing/skills/trend-signal/SKILL.md @@ -0,0 +1,114 @@ +--- +name: trend-signal +category: marketing +description: "Obtem sinais de mercado em tempo real via X/Grok com scoring matrix. Trend intelligence sem APIs pagas. Usar quando 'tendencias', 'trend', 'sinais mercado', 'social listening', 'X grok', 'conteudo trending'." +version: "1.0.0" +created: 2026-04-07 +tools: [mcp__claude-in-chrome__tabs_create_mcp, mcp__claude-in-chrome__read_page, mcp__claude-in-chrome__form_input, mcp__claude-in-chrome__computer] +--- + +# Skill: /trend-signal + +Obtem sinais de mercado em tempo real via X/Grok com scoring matrix. Baseado em #365 Jack Roberts. + +--- + +## Pre-requisitos + +- Utilizador autenticado no X (twitter.com) no Chrome +- Chrome acessivel via MCP (claude-in-chrome) + +--- + +## Processo + +### 1. Perguntar contexto + +Antes de pesquisar, perguntar ao utilizador: +- **Sector/industria:** (ex: marketing digital, saude, e-commerce) +- **Palavras-chave especificas:** (ex: claude code, n8n, WordPress) +- **Objectivo:** (ex: ideias conteudo, inteligencia competitiva, tendencias tecnologia) + +### 2. Abrir X e interagir com Grok + +1. `mcp__claude-in-chrome__tabs_create_mcp` — abrir `https://x.com/i/grok` +2. Enviar prompt ao Grok via `form_input`: + +``` +Preciso de tendencias dos ultimos 7 dias sobre [SECTOR/KEYWORDS]. + +Para cada tendencia encontrada, indica: +1. Titulo/topico +2. Fonte (conta X, link) +3. Data de publicacao +4. Numero de interaccoes aproximado +5. Porque e relevante + +Prioriza por: +- Recency (ultimos 7 dias) +- Authority (contas com mais seguidores) +- Velocity (crescimento rapido) +- Engagement (likes, retweets, replies) + +Lista as top 10 tendencias. +``` + +3. Ler resposta via `read_page` + +### 3. Scoring matrix + +Para cada sinal retornado, calcular score: + +| Factor | Peso | 1 | 3 | 5 | +|--------|------|---|---|---| +| **Premacy** | 25% | >7 dias | 3-7 dias | <3 dias | +| **Authority** | 25% | <1K followers | 1K-50K | >50K | +| **Velocity** | 25% | Estavel | Crescimento moderado | Viral | +| **Relevance** | 25% | Tangencial | Relacionado | Directamente relevante | + +Score total = soma ponderada (max 20). + +### 4. Output + +Gerar tabela markdown: + +```markdown +## Trend Signal Report — [DATA] + +**Sector:** [sector] +**Keywords:** [keywords] + +| # | Sinal | Score | Premacy | Authority | Velocity | Relevance | Fonte | +|---|-------|-------|---------|-----------|----------|-----------|-------| +| 1 | ... | 18/20 | 5 | 4 | 5 | 4 | @conta | + +### Angulos de conteudo sugeridos + +1. **[Titulo]** — [descricao breve, formato sugerido: artigo/video/post] +2. **[Titulo]** — [descricao] +3. **[Titulo]** — [descricao] +``` + +### 5. Opcoes pos-analise + +Perguntar ao utilizador: +- Guardar relatorio no Hub? (`00-Inbox/trend-signal-YYYY-MM-DD.md`) +- Criar tarefas de conteudo no Desk CRM? +- Agendar proxima execucao via `/schedule`? + +--- + +## Fallback (sem acesso ao X) + +Se o Chrome nao tem sessao X activa: +1. Informar o utilizador +2. Oferecer alternativa: pesquisa web via `WebSearch` + `WebFetch` sobre as mesmas keywords +3. Scoring manual baseado em resultados web + +--- + +## Healing Log + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` diff --git a/marketing/skills/video/SKILL.md b/marketing/skills/video/SKILL.md index 6e1fa26..ff89b8d 100644 --- a/marketing/skills/video/SKILL.md +++ b/marketing/skills/video/SKILL.md @@ -294,3 +294,15 @@ Para conteudo detalhado, consultar: **Projecto Base**: `/media/ealmeida/Dados/Dev/remotion-demo/` **Documentacao**: [remotion.dev/docs](https://remotion.dev/docs) + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/marketing/skills/youtube/SKILL.md b/marketing/skills/youtube/SKILL.md index b6f2b7a..42843e8 100644 --- a/marketing/skills/youtube/SKILL.md +++ b/marketing/skills/youtube/SKILL.md @@ -227,3 +227,15 @@ Para conteudo detalhado, consultar: **Script transcricoes**: `/media/ealmeida/Dados/Dev/ClaudeDev/Claude-Scripts/youtube-transcript/youtube_extractor.py` **MCPs**: youtube-research (8/12 OK), youtube-uploader (requer auth) + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/metabase/skills/dashboard/SKILL.md b/metabase/skills/dashboard/SKILL.md index 1bbaf2b..c528fa3 100644 --- a/metabase/skills/dashboard/SKILL.md +++ b/metabase/skills/dashboard/SKILL.md @@ -133,3 +133,15 @@ ToolSearch("metabase") - Objectos criados via AI usam prefixo `claude_ai_` (comportamento do MCP) - Sempre confirmar com utilizador antes de criar/modificar - Preferir collections organizadas por tema + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/metabase/skills/metabase/SKILL.md b/metabase/skills/metabase/SKILL.md index ca13070..422b739 100644 --- a/metabase/skills/metabase/SKILL.md +++ b/metabase/skills/metabase/SKILL.md @@ -117,3 +117,15 @@ Verificar que as tools `mcp__metabase__*` estão disponíveis. - Todas as operações são **read-only** por defeito - Para operações de escrita (criar dashboard, etc.), usar `/dashboard` - Para queries SQL, usar `/query` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/metabase/skills/query/SKILL.md b/metabase/skills/query/SKILL.md index b3f6253..4e53a13 100644 --- a/metabase/skills/query/SKILL.md +++ b/metabase/skills/query/SKILL.md @@ -146,3 +146,15 @@ Se o utilizador quiser reutilizar a query: - Resultados limitados a 2000 linhas por defeito pelo MCP - Para datasets grandes, usar agregações - Queries complexas: delegar ao agente `metabase-analyst` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/negocio/skills/ecommerce/SKILL.md b/negocio/skills/ecommerce/SKILL.md index e91f8f5..2eabec9 100644 --- a/negocio/skills/ecommerce/SKILL.md +++ b/negocio/skills/ecommerce/SKILL.md @@ -465,4 +465,15 @@ INSERT INTO tblskill_agent_metrics ( --- **Versão**: 2.0.0 | **Data**: 2026-02-03 | **Autor**: Descomplicar® -**Instrumentação**: Activa \ No newline at end of file +**Instrumentação**: Activa +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/negocio/skills/interview/SKILL.md b/negocio/skills/interview/SKILL.md index 7d32001..1bd8e3d 100644 --- a/negocio/skills/interview/SKILL.md +++ b/negocio/skills/interview/SKILL.md @@ -339,3 +339,15 @@ Skill: 3. Executar workflow integrado Output: [resultado completo com referências] ``` + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/negocio/skills/product/SKILL.md b/negocio/skills/product/SKILL.md index 4449a58..d25e83e 100644 --- a/negocio/skills/product/SKILL.md +++ b/negocio/skills/product/SKILL.md @@ -162,3 +162,15 @@ Task({ | [references/prioritization-frameworks.md](references/prioritization-frameworks.md) | RICE scoring, MoSCoW, Value vs Effort matrix | | [references/roadmap-sprint-templates.md](references/roadmap-sprint-templates.md) | Templates roadmap, user stories, sprint planning | | [references/metricas-produto.md](references/metricas-produto.md) | AARRR, product health, validation framework, pain points | + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/negocio/skills/research/SKILL.md b/negocio/skills/research/SKILL.md index 3c781ba..8329aaa 100644 --- a/negocio/skills/research/SKILL.md +++ b/negocio/skills/research/SKILL.md @@ -126,3 +126,15 @@ mcp__google-workspace__* # Docs para reports - `references/frameworks-analise.md` - Templates SWOT, Porter, PESTEL, Competitive Analysis - `references/recolha-dados-templates.md` - Fontes dados, Research Brief, TAM/SAM/SOM, Executive Summary + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/negocio/skills/saas/SKILL.md b/negocio/skills/saas/SKILL.md index 464488a..e9e9f8f 100644 --- a/negocio/skills/saas/SKILL.md +++ b/negocio/skills/saas/SKILL.md @@ -150,3 +150,15 @@ Task({ | [references/multi-tenancy.md](references/multi-tenancy.md) | Implementacao RLS PostgreSQL, checklist seguranca | | [references/pricing-billing.md](references/pricing-billing.md) | Tiers, Stripe setup, trial conversion, feature flags | | [references/metricas-kpis.md](references/metricas-kpis.md) | KPIs receita/crescimento/aquisicao/retencao, onboarding flow | + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-controllers/SKILL.md b/perfex-dev/skills/perfex-controllers/SKILL.md index d480516..26cb740 100644 --- a/perfex-dev/skills/perfex-controllers/SKILL.md +++ b/perfex-dev/skills/perfex-controllers/SKILL.md @@ -414,3 +414,15 @@ public function ajax_save() **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/module-controllers + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-database/SKILL.md b/perfex-dev/skills/perfex-database/SKILL.md index 463303a..90870d7 100644 --- a/perfex-dev/skills/perfex-database/SKILL.md +++ b/perfex-dev/skills/perfex-database/SKILL.md @@ -462,3 +462,15 @@ $formatted = _dt($row->created_at); // Data e hora **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/module-basics + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-forms/SKILL.md b/perfex-dev/skills/perfex-forms/SKILL.md index f40c96a..c6030f2 100644 --- a/perfex-dev/skills/perfex-forms/SKILL.md +++ b/perfex-dev/skills/perfex-forms/SKILL.md @@ -251,3 +251,15 @@ return [ --- **Fonte:** help.perfexcrm.com/working-with-forms + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-hooks/SKILL.md b/perfex-dev/skills/perfex-hooks/SKILL.md index a0bcd57..13e8a7c 100644 --- a/perfex-dev/skills/perfex-hooks/SKILL.md +++ b/perfex-dev/skills/perfex-hooks/SKILL.md @@ -373,3 +373,15 @@ function add_custom_widget() **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/action-hooks + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-menus/SKILL.md b/perfex-dev/skills/perfex-menus/SKILL.md index e4e569b..2fb0e81 100644 --- a/perfex-dev/skills/perfex-menus/SKILL.md +++ b/perfex-dev/skills/perfex-menus/SKILL.md @@ -393,3 +393,15 @@ function meu_modulo_count_pending() **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/create-menu-items + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-migrations/SKILL.md b/perfex-dev/skills/perfex-migrations/SKILL.md index 9c60576..03baa74 100644 --- a/perfex-dev/skills/perfex-migrations/SKILL.md +++ b/perfex-dev/skills/perfex-migrations/SKILL.md @@ -419,3 +419,15 @@ public function up() **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/preparing-module-upgrade + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-module-basics/SKILL.md b/perfex-dev/skills/perfex-module-basics/SKILL.md index 7ec837a..7d0bb08 100644 --- a/perfex-dev/skills/perfex-module-basics/SKILL.md +++ b/perfex-dev/skills/perfex-module-basics/SKILL.md @@ -293,3 +293,15 @@ Isto mostra: **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/module-basics + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-permissions/SKILL.md b/perfex-dev/skills/perfex-permissions/SKILL.md index 55e0c59..3e5be54 100644 --- a/perfex-dev/skills/perfex-permissions/SKILL.md +++ b/perfex-dev/skills/perfex-permissions/SKILL.md @@ -460,3 +460,15 @@ class Inventario extends AdminController **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/staff-capabilities-and-access + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-security/SKILL.md b/perfex-dev/skills/perfex-security/SKILL.md index bb27a92..ca492d0 100644 --- a/perfex-dev/skills/perfex-security/SKILL.md +++ b/perfex-dev/skills/perfex-security/SKILL.md @@ -461,3 +461,15 @@ class Meu_modulo extends AdminController **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/module-security + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/perfex-dev/skills/perfex-views/SKILL.md b/perfex-dev/skills/perfex-views/SKILL.md index c8afb5b..56dfcc5 100644 --- a/perfex-dev/skills/perfex-views/SKILL.md +++ b/perfex-dev/skills/perfex-views/SKILL.md @@ -456,3 +456,15 @@ echo _l('item_created_by', $staff_name); **Versão:** 1.0.0 | **Autor:** Descomplicar® **Fonte:** help.perfexcrm.com/module-views + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/project-manager/skills/brainstorm/SKILL.md b/project-manager/skills/brainstorm/SKILL.md index 506cc69..e09d6b7 100644 --- a/project-manager/skills/brainstorm/SKILL.md +++ b/project-manager/skills/brainstorm/SKILL.md @@ -1,12 +1,14 @@ --- name: brainstorm -description: Brainstorming estruturado que explora ideias de múltiplos ângulos antes de criar spec. Consulta NotebookLM e Dify KB para perspectivas de especialistas. +description: Brainstorming estruturado que explora ideias de múltiplos ângulos antes de criar spec. Consulta NotebookLM para perspectivas de especialistas. --- -# /brainstorm v1.1 - Ideacao Estruturada +# /brainstorm v1.2 - Ideacao Estruturada + +> **NOTA 07-04-2026:** referências a "Dify KB" no corpo desta skill são obsoletas (Dify removido em 06-03-2026). Substituir por NotebookLM ou /knowledge nas próximas iterações. Workflow geral mantém-se válido. Explora ideias de multiplos angulos antes de formalizar num spec. -Consulta especialistas via NotebookLM (conhecimento curado profundo) e Dify KB (boas praticas gerais). +Consulta especialistas via NotebookLM (conhecimento curado profundo). **Flow:** brainstorm -> /spec create -> /sprint plan -> codigo @@ -247,3 +249,15 @@ sugerem [Z] para este tipo de projecto. 6. Sugerir /spec create quando a ideia amadurecer, nao impor 7. Para PHDA: manter cada fase curta, perguntar antes de avancar 8. Alternativas sao valiosas - nao descartar ideias cedo demais + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/project-manager/skills/discover/SKILL.md b/project-manager/skills/discover/SKILL.md index 90e1ac0..405014b 100644 --- a/project-manager/skills/discover/SKILL.md +++ b/project-manager/skills/discover/SKILL.md @@ -1,9 +1,11 @@ --- name: discover -description: Pesquisa e discovery de viabilidade, abordagens e estado da arte. Pesquisa NotebookLM, Dify KB, web, codebase e Context7. +description: Pesquisa e discovery de viabilidade, abordagens e estado da arte. Pesquisa NotebookLM, web, codebase e Context7. --- -# /discover v1.1 - Pesquisa e Discovery +# /discover v1.2 - Pesquisa e Discovery + +> **NOTA 07-04-2026:** referências a "Dify KB" no corpo desta skill são obsoletas (Dify removido em 06-03-2026). Substituir por NotebookLM ou /knowledge nas próximas iterações. Workflow geral mantém-se válido. Investiga antes de opinar. Recolhe factos, abordagens e estado da arte para alimentar o brainstorm. Usa NotebookLM (Gemini 2.5 com RAG sobre conhecimento curado) como fonte primaria de pesquisa interna. @@ -243,3 +245,15 @@ So fontes internas - nao pesquisa web: 6. Manter fontes rastreavies - incluir links quando disponivel 7. Para PHDA: resumos curtos primeiro, detalhes a pedido 8. **NUNCA** fazer pesquisa infinita - max 3-4 queries por fonte, depois compilar + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/project-manager/skills/scope/SKILL.md b/project-manager/skills/scope/SKILL.md index fa99898..73fbe8e 100644 --- a/project-manager/skills/scope/SKILL.md +++ b/project-manager/skills/scope/SKILL.md @@ -99,3 +99,15 @@ Check rapido: "o trabalho que estou a fazer esta dentro do que combinámos?" 3. Ser factual - reportar o que ve, nao julgar 4. Scope creep nao e mau por si - e mau quando nao e detectado 5. Sugerir solucoes (update spec, criar novo) nao apenas reportar problemas + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/project-manager/skills/spec/SKILL.md b/project-manager/skills/spec/SKILL.md index 73eb6a7..44ce12b 100644 --- a/project-manager/skills/spec/SKILL.md +++ b/project-manager/skills/spec/SKILL.md @@ -429,3 +429,15 @@ draft -> review -> approved -> in_progress -> completed 6. **SEMPRE** linkar ao Desk CRM quando .desk-project existe 7. Spec e contrato bilateral - ambos comprometem-se 8. Alteracoes apos aprovacao sao legtimas mas devem ser tracked + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/project-manager/skills/sprint/SKILL.md b/project-manager/skills/sprint/SKILL.md index d9065a8..bb31a18 100644 --- a/project-manager/skills/sprint/SKILL.md +++ b/project-manager/skills/sprint/SKILL.md @@ -273,3 +273,15 @@ _Data: [a preencher]_ 4. Review e obrigatorio antes de fechar sprint 5. Metricas sao factuais - nao ajustar para "parecer bem" 6. Sprint nao tem cadencia fixa - dura o que o projecto precisa + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/project-manager/skills/status/SKILL.md b/project-manager/skills/status/SKILL.md index 6b4ff83..4857d40 100644 --- a/project-manager/skills/status/SKILL.md +++ b/project-manager/skills/status/SKILL.md @@ -127,3 +127,15 @@ Limitar a projectos com .desk-project (nao todos os do Desk CRM). 3. Bloqueios devem saltar a vista (primeiro destaque) 4. Se falhar alguma fonte (MCP offline): mostrar as restantes com nota 5. `/status quick` para uso em `/today`; `/status` para analise + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/wordpress/agents/wordpress-performance-specialist.md b/wordpress/agents/wordpress-performance-specialist.md index 828fe37..16b1472 100644 --- a/wordpress/agents/wordpress-performance-specialist.md +++ b/wordpress/agents/wordpress-performance-specialist.md @@ -91,20 +91,29 @@ Especialista em optimizacao de performance WordPress responsavel por maximizar v ### Workflow 2: Implementar Caching Strategy 1. Browser cache: .htaccess headers (1 ano para static assets) 2. Object cache: Redis ou Memcached para DB queries -3. Page cache: WP Rocket, W3 Total Cache ou LiteSpeed +3. Page cache: WP Rocket, W3 Total Cache, LiteSpeed ou WP Fastest Cache 4. CDN: Cloudflare para assets estaticos 5. Exclusoes: Carrinho, checkout, user dashboards (dynamic) 6. Invalidation: Purge automatico apos updates +#### WP Fastest Cache — problemas conhecidos +- **NUNCA usar `wp fastest-cache clear all`** — apaga ficheiros minificados e bloqueia cache de pagina +- Usar `wp fastest-cache clear` (sem all) para limpar apenas paginas cached +- Se cache parar: verificar `tail -3` do HTML por "Cache has NOT been created due to optimized resource" +- Fix: `rm -rf wp-content/cache/wpfc-minified/*` → visitar site 1x (gera minificados) → 2a visita tem cache +- Permissoes: `wp-content/cache/` deve ser do user PHP-FPM (no CWP = user do dominio) +- TTFB esperado com cache: <25ms (sem cache: 2-5s) + ### Workflow 3: Optimizar Core Web Vitals 1. LCP (Largest Contentful Paint <2.5s): - Optimizar imagem hero (WebP, dimensoes correctas) - Server response time (upgrade hosting se necessario) - Preload critical resources -2. FID (First Input Delay <100ms): +2. INP (Interaction to Next Paint <200ms): - Defer JS non-critical - Code splitting - Remove unused CSS/JS + - Nota: FID foi substituido por INP em Marco 2024 3. CLS (Cumulative Layout Shift <0.1): - Width/height em images - Font display swap @@ -132,7 +141,7 @@ Especialista em optimizacao de performance WordPress responsavel por maximizar v | Metrica | Target | Critico | |---------|--------|---------| | LCP | <2.5s | <4s | -| FID | <100ms | <300ms | +| INP | <200ms | <500ms | | CLS | <0.1 | <0.25 | | TTFB | <600ms | <1.8s | | PageSpeed Score | >90 | >50 | diff --git a/wordpress/skills/branda-menu/SKILL.md b/wordpress/skills/branda-menu/SKILL.md index 149bda6..8c248f0 100644 --- a/wordpress/skills/branda-menu/SKILL.md +++ b/wordpress/skills/branda-menu/SKILL.md @@ -173,3 +173,15 @@ mcp__ssh-unified__ssh_execute server:"server" command:"rm -f /home/USER/SITE/wp- - `references/mapeamento-slugs.md` - Mapeamento completo slug -> seccao e tabela de Branda IDs - `references/script-template.md` - Script PHP template + adaptacoes por tipo de site + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/wordpress/skills/crocoblock/SKILL.md b/wordpress/skills/crocoblock/SKILL.md index 53aacd6..9dcc374 100644 --- a/wordpress/skills/crocoblock/SKILL.md +++ b/wordpress/skills/crocoblock/SKILL.md @@ -223,3 +223,15 @@ Usar `references/automation.md` para detalhes sobre Formless Actions, JetSmartFi --- **Versão**: 1.1.0 | **Autor**: Descomplicar® | **Data**: 18-02-2026 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/wordpress/skills/elementor/SKILL.md b/wordpress/skills/elementor/SKILL.md index 3c83ce5..8cfb74c 100644 --- a/wordpress/skills/elementor/SKILL.md +++ b/wordpress/skills/elementor/SKILL.md @@ -310,3 +310,15 @@ Para deploy automatizado, pipelines IA, migração em massa e manipulação prog --- **Versão**: 1.2.0 | **Autor**: Descomplicar® | **Actualizado**: 18-02-2026 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/wordpress/skills/jetengine/SKILL.md b/wordpress/skills/jetengine/SKILL.md index 96da571..476a71a 100644 --- a/wordpress/skills/jetengine/SKILL.md +++ b/wordpress/skills/jetengine/SKILL.md @@ -276,3 +276,15 @@ WP Admin > JetEngine > AI Command Center > Enable MCP Server --- **Versão**: 1.1.0 | **Autor**: Descomplicar® | **Data**: 18-02-2026 + +--- + +## Healing Log + +Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar. + +```jsonl +{"date":"","issue":"","fix":"","source":"user|auto"} +``` + +*Adicionar nova linha após cada erro corrigido.* diff --git a/wordpress/skills/rank-math/SKILL.md b/wordpress/skills/rank-math/SKILL.md index cb6e576..c7da458 100644 --- a/wordpress/skills/rank-math/SKILL.md +++ b/wordpress/skills/rank-math/SKILL.md @@ -1,15 +1,18 @@ --- name: rank-math -description: Gestão do plugin Rank Math SEO via WP-CLI em servidores CWP. Cobre auditoria SEO, configuração em massa de títulos e meta descriptions, schema markup, redirects e sitemaps. +description: Gestão programática do Rank Math SEO (Free e PRO) via WP-CLI em servidores CWP. Cobre auditoria SEO, meta em massa, schema markup, redirects, sitemaps, Instant Indexing, Analytics PRO, hooks/filtros, taxonomias WooCommerce, News/Video Sitemap, validação e rollback. Usar quando "rank math", "seo cli", "schema markup", "redirects seo", "instant indexing", "indexnow", "seo bulk", "rankmath pro". --- -# /rank-math - Gestão Rank Math SEO via WP-CLI +# /rank-math — Gestão Programática Rank Math SEO via WP-CLI -Operações de SEO WordPress via WP-CLI no servidor CWP (server.descomplicar.pt). Cobre auditoria, configuração em massa, schema markup, redirects e sitemap. +Operações SEO WordPress completas via WP-CLI no servidor CWP. Free + PRO. -**Manual completo:** `Hub/06-Operacoes/Documentacao/Manuais/Rank-Math-WP-CLI-Manual-Definitivo.md` +**Manual completo:** `Hub/06-Operacoes/Documentacao/Manuais/WP-CLI/Rank-Math-WP-CLI-Manual-Definitivo.md` **Quick Reference:** `Hub/06-Operacoes/Documentacao/Quick-Reference/QR-RankMath-WP-CLI.md` +**Pesquisa Claude:** `Hub/06-Operacoes/Documentacao/Manuais/WP-CLI/Rank-Math-SEO-WP-CLI-Skils-Pesquisa-Claude.md` +**Pesquisa Gemini:** `Hub/06-Operacoes/Documentacao/Manuais/WP-CLI/Rank-Math-SEO-WP-CLI-Skills-Pesquisa-Gemini.md` **NotebookLM:** [WordPress Config CLI](https://notebooklm.google.com/notebook/fb2f26bd-8cb0-4d4c-bafc-4f1ebb51c51d) +**Skill relacionada:** `/seo-post` — optimizar posts individuais com pipeline completo --- @@ -27,192 +30,447 @@ mcp__notebooklm__notebook_query({ notebook_id: "5be0d1a6-00f2-4cd9-b835-978cb7721601", query: "" }) - -mcp__notebooklm__notebook_query({ - notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3", - query: "" -}) ``` -Integrar insights do NotebookLM nas recomendações e decisões. - --- ## Uso ``` -/rank-math audit https://site.pt -/rank-math update-meta /home/USER/public_html -/rank-math sitemap /home/USER/public_html -/rank-math redirects /home/USER/public_html -/rank-math schema post ID /home/USER/public_html +/rank-math audit SITE_PATH +/rank-math update-meta SITE_PATH +/rank-math sitemap SITE_PATH +/rank-math redirects SITE_PATH +/rank-math schema post ID SITE_PATH +/rank-math indexing SITE_PATH [URL|bulk] +/rank-math analytics SITE_PATH +/rank-math taxonomy SITE_PATH +/rank-math hooks SITE_PATH +/rank-math backup SITE_PATH +/rank-math provision SITE_PATH ``` --- -## Contexto CWP — Sempre Obrigatório +## Contexto CWP — sempre obrigatorio -**PHP 8.3 no CWP:** ```bash -# Formato base +# Formato base (PHP 8.3) /opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=/home/USER/public_html -# Alias ~/.bashrc (se configurado) +# Alias wp83 --allow-root --path=/home/USER/public_html ``` **Acesso via MCP SSH:** ``` -servidor: server.descomplicar.pt (176.9.3.158) -porta: 9443 | user: root +servidor: server.descomplicar.pt (176.9.3.158) | porta: 9443 | user: root ``` -**Único comando nativo Rank Math:** +**Prefixo de tabelas:** Sites podem ter prefixo custom (ex: `wpah_` em vez de `wp_`). Detectar primeiro: ```bash -wp rankmath sitemap generate --allow-root --path=/home/USER/public_html +PREFIX=$(wp db prefix --allow-root --path=$PATH) +# Usar $PREFIX em todas as queries SQL: ${PREFIX}posts, ${PREFIX}postmeta, etc. ``` + +**Unico comando nativo Rank Math:** +```bash +wp rankmath sitemap generate --allow-root --path=$PATH +``` + Tudo o resto usa `wp post meta`, `wp option patch`, `wp eval` ou `wp db query`. +**Options com defaults:** Muitas sub-keys (title_separator, strip_category_base, homepage_title, knowledgegraph_type) podem nao existir na BD se nunca foram alteradas — o Rank Math usa valores por defeito internos. `wp option pluck` retorna exit code 1 neste caso. Nao e erro — significa valor default. + --- -## Workflow: Auditoria SEO (/rank-math audit) +## Decision tree — qual comando usar -### Passo 1 — Diagnóstico rápido +| Operacao | Comando | +|----------|---------| +| Alterar meta de 1 post | `wp post meta update` | +| Alterar sub-key em option serializada | `wp option patch update` | +| Ler sub-key de option | `wp option pluck` | +| Schema complexo | `wp eval` com PHP | +| Redirects | `wp eval` com `\RankMath\Redirections\DB` | +| Bulk simples | shell loop com `wp post list \| while read` | +| Bulk complexo | `wp eval-file` com script PHP | +| SQL directo | apenas auditorias (seguido de `wp cache flush`) | +| Regenerar sitemap | `wp rankmath sitemap generate` | +| Instant Indexing | `wp eval` com IndexNow API ou classes RM | +| Side-effects RM | `wp eval` com `update_option()` (dispara hooks) | + +--- + +## 1. Auditoria SEO (/rank-math audit) + +### Passo 1 — diagnostico rapido ```bash PATH=/home/USER/public_html +PREFIX=$(wp db prefix --allow-root --path=$PATH) -# Posts sem título SEO -wp db query "SELECT p.ID, p.post_title FROM wp_posts p -LEFT JOIN wp_postmeta pm ON p.ID=pm.post_id AND pm.meta_key='rank_math_title' +# Posts sem titulo SEO +wp db query "SELECT p.ID, p.post_title FROM ${PREFIX}posts p +LEFT JOIN ${PREFIX}postmeta pm ON p.ID=pm.post_id AND pm.meta_key='rank_math_title' WHERE p.post_type='post' AND p.post_status='publish' AND (pm.meta_value IS NULL OR pm.meta_value='');" --allow-root --path=$PATH -# Posts sem descrição SEO -wp db query "SELECT p.ID, p.post_title FROM wp_posts p -LEFT JOIN wp_postmeta pm ON p.ID=pm.post_id AND pm.meta_key='rank_math_description' +# Posts sem descricao SEO +wp db query "SELECT p.ID, p.post_title FROM ${PREFIX}posts p +LEFT JOIN ${PREFIX}postmeta pm ON p.ID=pm.post_id AND pm.meta_key='rank_math_description' WHERE p.post_type='post' AND p.post_status='publish' AND (pm.meta_value IS NULL OR pm.meta_value='');" --allow-root --path=$PATH -# Top 404s (últimos 30 dias) -wp db query "SELECT uri, SUM(times_accessed) as total FROM wp_rank_math_404_logs +# Distribuicao de SEO scores +wp db query "SELECT + CASE WHEN CAST(meta_value AS UNSIGNED) >= 80 THEN 'Bom (80-100)' + WHEN CAST(meta_value AS UNSIGNED) >= 50 THEN 'OK (50-79)' + ELSE 'Fraco (0-49)' END AS faixa, + COUNT(*) AS total +FROM ${PREFIX}postmeta WHERE meta_key = 'rank_math_seo_score' GROUP BY faixa;" --allow-root --path=$PATH + +# Top 404s (ultimos 30 dias) +wp db query "SELECT uri, SUM(times_accessed) as total FROM ${PREFIX}rank_math_404_logs GROUP BY uri ORDER BY total DESC LIMIT 20;" --allow-root --path=$PATH -# Tamanho options (detetar bloat WooCommerce) -wp db query "SELECT option_name, LENGTH(option_value) as bytes FROM wp_options +# Tamanho options (detectar bloat WooCommerce) +wp db query "SELECT option_name, LENGTH(option_value) as bytes FROM ${PREFIX}options WHERE option_name LIKE 'rank%' AND autoload='yes' ORDER BY bytes DESC;" --allow-root --path=$PATH + +# Listar TODAS as meta keys Rank Math existentes +wp db query "SELECT DISTINCT meta_key FROM ${PREFIX}postmeta WHERE meta_key LIKE 'rank_math%' ORDER BY meta_key;" --allow-root --path=$PATH ``` -### Passo 2 — Estado módulos +### Passo 2 — estado modulos ```bash wp option pluck rank_math_modules --allow-root --path=$PATH wp option pluck rank-math-options-general strip_category_base --allow-root --path=$PATH wp option pluck rank-math-options-titles title_separator --allow-root --path=$PATH + +# Ver tabelas custom (usa % wildcard — funciona com qualquer prefixo) +wp db query "SHOW TABLES LIKE '%rank_math%';" --allow-root --path=$PATH ``` --- -## Workflow: Actualizar Meta SEO (/rank-math update-meta) +## 2. Actualizar meta SEO (/rank-math update-meta) ### Meta key individual ```bash -# Título SEO +# Titulo SEO wp post meta update ID rank_math_title "%title% %sep% %sitename%" --allow-root --path=$PATH -# Descrição SEO (<160 chars) -wp post meta update ID rank_math_description "Texto conciso da página." --allow-root --path=$PATH +# Descricao SEO (<160 chars) +wp post meta update ID rank_math_description "Texto conciso da pagina." --allow-root --path=$PATH # Focus keyword wp post meta update ID rank_math_focus_keyword "keyword1,keyword2" --allow-root --path=$PATH -# Robots (ARRAY JSON — obrigatório --format=json) +# Robots (ARRAY JSON — obrigatorio --format=json) wp post meta update ID rank_math_robots '["noindex"]' --format=json --allow-root --path=$PATH +# Advanced robots +wp post meta update ID rank_math_advanced_robots '{"max-snippet":"-1","max-video-preview":"-1","max-image-preview":"large"}' --format=json --allow-root --path=$PATH + # Canonical URL wp post meta update ID rank_math_canonical_url "https://site.pt/url/" --allow-root --path=$PATH # Pillar content wp post meta update ID rank_math_pillar_content "on" --allow-root --path=$PATH + +# Categoria primaria +wp post meta update ID rank_math_primary_category "15" --allow-root --path=$PATH + +# Breadcrumb title +wp post meta update ID rank_math_breadcrumb_title "Titulo Breadcrumb" --allow-root --path=$PATH + +# OpenGraph +wp post meta update ID rank_math_facebook_title "Titulo OG" --allow-root --path=$PATH +wp post meta update ID rank_math_facebook_description "Desc OG" --allow-root --path=$PATH +wp post meta update ID rank_math_facebook_image "https://site.pt/og.jpg" --allow-root --path=$PATH +wp post meta update ID rank_math_twitter_card_type "summary_large_image" --allow-root --path=$PATH + +# Redirect per-post +wp post meta update ID rank_math_redirect_url_to "/nova-url/" --allow-root --path=$PATH +wp post meta update ID rank_math_redirection_header_code "301" --allow-root --path=$PATH ``` ### Bulk update (wp eval) ```bash -# Aplicar título padrão a todos os posts sem título +# Aplicar titulo padrao a todos os posts sem titulo wp eval ' $posts = get_posts(["numberposts"=>-1,"post_status"=>"publish"]); +$updated = 0; foreach ($posts as $p) { if (!get_post_meta($p->ID, "rank_math_title", true)) { update_post_meta($p->ID, "rank_math_title", "%title% %sep% %sitename%"); + $updated++; } } -echo count($posts)." posts processados\n"; +echo "$updated posts actualizados\n"; ' --allow-root --path=$PATH + +# Aplicar descricao a partir do excerpt +wp eval ' +$posts = get_posts(["post_type"=>"post","numberposts"=>-1,"post_status"=>"publish"]); +$updated = 0; +foreach ($posts as $p) { + if (!get_post_meta($p->ID, "rank_math_description", true) && $p->post_excerpt) { + $desc = wp_trim_words($p->post_excerpt, 20, "..."); + update_post_meta($p->ID, "rank_math_description", $desc); + $updated++; + } +} +echo "$updated posts actualizados\n"; +' --allow-root --path=$PATH +``` + +### Bulk via shell + +```bash +# Actualizar titulo de todos os posts publicados +wp post list --post_type=post --post_status=publish --field=ID --allow-root --path=$PATH | while read id; do + wp post meta update $id rank_math_title "%title% %sep% %sitename%" --allow-root --path=$PATH +done + +# Noindex em todos os drafts +wp post list --post_type=post --post_status=draft --field=ID --allow-root --path=$PATH | while read id; do + wp post meta update $id rank_math_robots '["noindex"]' --format=json --allow-root --path=$PATH +done + +# Paralelo com xargs +wp post list --post_type=page --post_status=publish --field=ID --allow-root --path=$PATH | \ + xargs -P4 -I {} wp post meta delete {} rank_math_canonical_url --allow-root --path=$PATH +``` + +### Bulk via CSV + +```bash +# Formato CSV: id,descricao +while IFS=, read -r post_id desc; do + wp post meta update "$post_id" rank_math_description "$desc" --allow-root --path=$PATH +done < descriptions.csv ``` --- -## Workflow: Options Globais (/rank-math options) +## 3. Options globais (/rank-math options) -**Regra crítica:** SEMPRE usar `wp option patch`, NUNCA `wp option update` em options serializadas. +**Regra critica:** SEMPRE usar `wp option patch`, NUNCA `wp option update` em options serializadas. ```bash -# Separador de título +# Separador de titulo wp option patch update rank-math-options-titles title_separator "-" --allow-root --path=$PATH +# Templates por post type +wp option patch update rank-math-options-titles pt_post_title "%title% %sep% %sitename%" --allow-root --path=$PATH +wp option patch update rank-math-options-titles pt_page_title "%title% %sep% %sitename%" --allow-root --path=$PATH +wp option patch update rank-math-options-titles pt_product_title "%title% %sep% %currentyear% %sep% %sitename%" --allow-root --path=$PATH + +# Homepage +wp option patch update rank-math-options-titles homepage_title "Titulo Site" --allow-root --path=$PATH +wp option patch update rank-math-options-titles homepage_description "Descricao Site" --allow-root --path=$PATH + # Remover base de categoria do URL wp option patch update rank-math-options-general strip_category_base "on" --allow-root --path=$PATH +wp rewrite flush --allow-root --path=$PATH # OBRIGATORIO apos esta alteracao + +# Breadcrumbs +wp option patch update rank-math-options-general breadcrumbs_separator ">" --allow-root --path=$PATH + +# Nofollow links externos +wp option patch update rank-math-options-general nofollow_external_links "on" --allow-root --path=$PATH + +# Knowledge Graph +wp option patch update rank-math-options-titles knowledgegraph_type "Organization" --allow-root --path=$PATH +wp option patch update rank-math-options-titles knowledgegraph_name "Descomplicar" --allow-root --path=$PATH + +# Webmaster verification +wp option patch update rank-math-options-general google_verify "codigo" --allow-root --path=$PATH # Verificar sub-key wp option pluck rank-math-options-titles title_separator --allow-root --path=$PATH -# LER option completa (diagnóstico) +# LER option completa (diagnostico) wp option get rank-math-options-general --format=json --allow-root --path=$PATH ``` +### Gestao de modulos + +```bash +# LER modulos activos +wp option get rank_math_modules --format=json --allow-root --path=$PATH + +# ACTIVAR modulo (via wp eval — dispara hooks) +wp eval ' +$modules = get_option("rank_math_modules", []); +if (!in_array("redirections", $modules)) { + $modules[] = "redirections"; + update_option("rank_math_modules", $modules); + echo "Modulo activado.\n"; +} else { echo "Ja activo.\n"; } +' --allow-root --path=$PATH + +# DESACTIVAR modulo +wp eval ' +$modules = get_option("rank_math_modules", []); +$modules = array_values(array_diff($modules, ["404-monitor"])); +update_option("rank_math_modules", $modules); +echo "Modulo desactivado.\n"; +' --allow-root --path=$PATH + +# Modulos disponiveis: +# sitemap, rich-snippet, redirections, 404-monitor, local-seo, +# woocommerce, image-seo, link-counter, instant-indexing, content-ai, +# analytics, role-manager, acf, amp, news-sitemap (PRO), video-sitemap (PRO) +``` + --- -## Workflow: Schema Markup (/rank-math schema) +## 4. Schema markup (/rank-math schema) -Schema é armazenado como array PHP em `rank_math_schema_{Type}`. Usar `wp eval` (não JSON directo). +Schema armazenado como array PHP em `rank_math_schema_{Type}`. Usar `wp eval` (nao JSON directo). + +### Estrutura interna + +```json +{ + "metadata": {"title": "Article", "type": "custom", "shortcode": "s-UNIQUE", "isPrimary": "1"}, + "@type": "Article", + "headline": "%seo_title%", + "description": "%seo_description%" +} +``` + +- `type: "template"` — herda globals | `type: "custom"` — personalizado +- `isPrimary: "1"` — schema principal do post +- Free: 1 schema/post | PRO: ilimitados + +### Criar schemas ```bash -# Criar schema Article num post +# Article wp eval ' update_post_meta(ID, "rank_math_schema_Article", [ "metadata" => ["title"=>"Article","type"=>"custom","shortcode"=>"s-".uniqid(),"isPrimary"=>"1"], "@type"=>"Article", "headline"=>"%seo_title%", "description"=>"%seo_description%", + "keywords"=>"%keywords%", + "articleSection"=>"%categories%", + "image"=>["@type"=>"ImageObject","url"=>"%post_thumbnail%"], "author"=>["@type"=>"Person","name"=>"%name%"], + "publisher"=>["@type"=>"Organization","name"=>"%sitename%","logo"=>""], "datePublished"=>"%date(Y-m-dTH:i:sP)%", "dateModified"=>"%modified(Y-m-dTH:i:sP)%" ]); -echo "Schema criado\n"; +echo "Schema Article criado\n"; ' --user=1 --allow-root --path=$PATH -# Criar schema FAQ +# FAQ wp eval ' update_post_meta(ID, "rank_math_schema_FAQPage", [ - "metadata" => ["title"=>"FAQ","type"=>"custom","shortcode"=>"s-".uniqid(),"isPrimary"=>"1"], + "metadata" => ["title"=>"FAQ","type"=>"custom","shortcode"=>"s-".uniqid(),"isPrimary"=>"0"], "@type"=>"FAQPage", "mainEntity"=>[ ["@type"=>"Question","name"=>"Pergunta 1","acceptedAnswer"=>["@type"=>"Answer","text"=>"Resposta 1"]], ["@type"=>"Question","name"=>"Pergunta 2","acceptedAnswer"=>["@type"=>"Answer","text"=>"Resposta 2"]] ] ]); -echo "FAQ Schema criado\n"; +echo "Schema FAQ criado\n"; ' --user=1 --allow-root --path=$PATH +# Product (WooCommerce) +wp eval ' +update_post_meta(ID, "rank_math_schema_Product", [ + "metadata" => ["title"=>"Product","type"=>"custom","shortcode"=>"s-".uniqid(),"isPrimary"=>"1"], + "@type"=>"Product", + "name"=>"%title%", + "description"=>"%excerpt%", + "sku"=>"SKU-001", + "brand"=>["@type"=>"Brand","name"=>"Marca"], + "image"=>["@type"=>"ImageObject","url"=>"%post_thumbnail%"], + "offers"=>[ + "@type"=>"Offer","price"=>"29.99","priceCurrency"=>"EUR", + "availability"=>"https://schema.org/InStock","url"=>"%url%", + "priceValidUntil"=>"2026-12-31" + ] +]); +echo "Schema Product criado\n"; +' --user=1 --allow-root --path=$PATH + +# LocalBusiness +wp eval ' +update_post_meta(ID, "rank_math_schema_LocalBusiness", [ + "metadata" => ["title"=>"LocalBusiness","type"=>"custom","shortcode"=>"s-".uniqid(),"isPrimary"=>"1"], + "@type"=>"LocalBusiness", + "name"=>"Nome Empresa", + "description"=>"%seo_description%", + "url"=>"%url%", + "email"=>"email@empresa.pt", + "telephone"=>"+351 XXX XXX XXX", + "address"=>["@type"=>"PostalAddress","streetAddress"=>"Rua X","addressLocality"=>"Cidade","postalCode"=>"XXXX-XXX","addressCountry"=>"PT"], + "geo"=>["@type"=>"GeoCoordinates","latitude"=>"38.7","longitude"=>"-9.1"], + "openingHoursSpecification"=>[ + ["@type"=>"OpeningHoursSpecification","dayOfWeek"=>["Monday","Tuesday","Wednesday","Thursday","Friday"],"opens"=>"09:00","closes"=>"18:00"] + ], + "image"=>"%post_thumbnail%" +]); +echo "Schema LocalBusiness criado\n"; +' --user=1 --allow-root --path=$PATH + +# VideoObject +wp eval ' +update_post_meta(ID, "rank_math_schema_VideoObject", [ + "metadata" => ["title"=>"VideoObject","type"=>"custom","shortcode"=>"s-".uniqid(),"isPrimary"=>"0"], + "@type"=>"VideoObject", + "name"=>"%seo_title%", + "description"=>"%seo_description%", + "thumbnailUrl"=>"%post_thumbnail%", + "uploadDate"=>"%date(Y-m-dTH:i:sP)%", + "contentUrl"=>"https://exemplo.pt/video.mp4", + "embedUrl"=>"https://youtube.com/embed/VIDEO_ID" +]); +echo "Schema VideoObject criado\n"; +' --user=1 --allow-root --path=$PATH +``` + +### Actualizar/apagar schema + +```bash +# Actualizar campo especifico +wp eval ' +$schema = get_post_meta(ID, "rank_math_schema_Article", true); +if ($schema) { + $schema["headline"] = "Novo Titulo"; + update_post_meta(ID, "rank_math_schema_Article", $schema); + echo "Actualizado.\n"; +} +' --allow-root --path=$PATH + # Apagar schema corrompido wp post meta delete ID rank_math_schema_Article --allow-root --path=$PATH + +# Apagar TODOS os schemas de um post +wp eval ' +global $wpdb; +$wpdb->query($wpdb->prepare( + "DELETE FROM {$wpdb->postmeta} WHERE post_id = %d AND meta_key LIKE %s", + ID, "rank_math_schema_%" +)); +echo "Todos os schemas eliminados.\n"; +' --allow-root --path=$PATH ``` --- -## Workflow: Redirects (/rank-math redirects) +## 5. Redirects (/rank-math redirects) + +### CRUD via API PHP (recomendado) ```bash # Criar redirect 301 @@ -227,85 +485,673 @@ wp eval ' echo "Redirect criado\n"; ' --allow-root --path=$PATH -# Redirect com wildcard +# Redirect regex wp eval ' \RankMath\Redirections\DB::add([ "id"=>"", - "sources"=>[["pattern"=>"/blog/","comparison"=>"contain"]], - "url_to"=>"/artigos/", + "sources"=>[["pattern"=>"^/blog/2023/.*$","comparison"=>"regex"]], + "url_to"=>"/blog/", "header_code"=>301, "status"=>"active", ]); -echo "Redirect wildcard criado\n"; ' --allow-root --path=$PATH -# Apagar redirect por ID -wp eval '\RankMath\Redirections\DB::delete(42); echo "Redirect apagado\n";' --allow-root --path=$PATH +# Redirect 410 (conteudo removido) +wp eval ' +\RankMath\Redirections\DB::add([ + "id"=>"", + "sources"=>[["pattern"=>"/removida/","comparison"=>"exact"]], + "url_to"=>"", + "header_code"=>410, + "status"=>"active", +]); +' --allow-root --path=$PATH -# Limpar logs 404 (após resolver) -wp db query "TRUNCATE TABLE wp_rank_math_404_logs;" --allow-root --path=$PATH +# Actualizar +wp eval ' +\RankMath\Redirections\DB::update([ + "id"=>42, + "sources"=>[["pattern"=>"/url-antiga/","comparison"=>"exact"]], + "url_to"=>"/url-nova/", + "header_code"=>301, + "status"=>"active", +]); +echo "Actualizado\n"; +' --allow-root --path=$PATH + +# Apagar +wp eval '\RankMath\Redirections\DB::delete(42); echo "Eliminado\n";' --allow-root --path=$PATH +wp eval '\RankMath\Redirections\DB::delete([42, 43, 44]); echo "Eliminados\n";' --allow-root --path=$PATH + +# Bulk criar +wp eval ' +$redirects = [ + ["/antiga-1/", "/nova-1/", 301], + ["/antiga-2/", "/nova-2/", 301], + ["/removida/", "", 410], +]; +foreach ($redirects as $r) { + $id = \RankMath\Redirections\DB::add([ + "id"=>"", "sources"=>[["pattern"=>$r[0],"comparison"=>"exact"]], + "url_to"=>$r[1], "header_code"=>$r[2], "status"=>"active", + ]); + echo "#{$id}: {$r[0]} -> {$r[1]} ({$r[2]})\n"; +} +' --allow-root --path=$PATH + +# Validar +curl -I -s https://site.pt/url-antiga/ | grep HTTP +``` + +### Tipos de comparacao + +| comparison | Comportamento | +|-----------|---------------| +| `exact` | Match exacto | +| `contains` | URL contem pattern | +| `start` | URL comeca com pattern | +| `end` | URL termina com pattern | +| `regex` | Expressao regular | + +### 404 Monitor + +```bash +# Top 404s +wp db query "SELECT uri, SUM(times_accessed) as total FROM ${PREFIX}rank_math_404_logs +GROUP BY uri ORDER BY total DESC LIMIT 20;" --allow-root --path=$PATH + +# Limpar logs antigos (>30 dias) +wp db query "DELETE FROM ${PREFIX}rank_math_404_logs WHERE accessed < DATE_SUB(NOW(), INTERVAL 30 DAY);" --allow-root --path=$PATH + +# Truncar tudo +wp db query "TRUNCATE TABLE ${PREFIX}rank_math_404_logs;" --allow-root --path=$PATH ``` --- -## Workflow: Sitemap (/rank-math sitemap) +## 6. Sitemap (/rank-math sitemap) ```bash # Regenerar sitemap wp rankmath sitemap generate --allow-root --path=$PATH -# Excluir post-type do sitemap +# Invalidar cache de sitemap via API PHP +wp eval '\RankMath\Sitemap\Cache::invalidate_storage(); echo "Cache invalidada.\n";' --allow-root --path=$PATH + +# Invalidar sitemap de tipo especifico +wp eval '\RankMath\Sitemap\Cache::invalidate_storage("post"); echo "Sitemap posts invalidado.\n";' --allow-root --path=$PATH + +# Incluir/excluir post-types +wp option patch update rank-math-options-sitemap pt_post_sitemap "on" --allow-root --path=$PATH wp option patch update rank-math-options-sitemap pt_attachment_sitemap "off" --allow-root --path=$PATH +# Excluir posts especificos +wp eval ' +$opts = get_option("rank-math-options-sitemap"); +$opts["exclude_posts"] = "123,456,789"; +update_option("rank-math-options-sitemap", $opts); +' --allow-root --path=$PATH + +# Itens por pagina (reduzir em sites grandes) +wp option patch update rank-math-options-sitemap items_per_page "200" --allow-root --path=$PATH + # Verificar setting wp option pluck rank-math-options-sitemap pt_post_sitemap --allow-root --path=$PATH ``` +**Nginx rewrite rules (obrigatorio em Nginx puro):** +```nginx +rewrite ^/sitemap_index.xml$ /index.php?sitemap=1 last; +rewrite ^/([^/]+?)-sitemap([0-9]+)?.xml$ /index.php?sitemap=$1&sitemap_n=$2 last; +rewrite ^/([a-z]+)?-sitemap\.xsl$ /index.php?xsl=$1 last; +``` + --- -## Sequência de Cache (Sempre Após Alterações) +## 7. Instant Indexing (/rank-math indexing) — PRO + +### IndexNow (integrado no Rank Math) + +```bash +# Submeter URL individual +wp eval ' +$url = "https://site.pt/novo-artigo/"; +$api_key = get_option("rank-math-options-instant-indexing")["indexnow_api_key"] ?? ""; +$response = wp_remote_post("https://api.indexnow.org/indexnow", [ + "headers" => ["Content-Type" => "application/json"], + "body" => json_encode([ + "host" => parse_url(home_url(), PHP_URL_HOST), + "key" => $api_key, + "urlList" => [$url], + ]), +]); +echo "Codigo: " . wp_remote_retrieve_response_code($response) . "\n"; +' --allow-root --path=$PATH + +# Submeter URLs em bulk +wp eval ' +$urls = ["https://site.pt/post-1/", "https://site.pt/post-2/", "https://site.pt/post-3/"]; +$api_key = get_option("rank-math-options-instant-indexing")["indexnow_api_key"] ?? ""; +$response = wp_remote_post("https://api.indexnow.org/indexnow", [ + "headers" => ["Content-Type" => "application/json"], + "body" => json_encode([ + "host" => parse_url(home_url(), PHP_URL_HOST), + "key" => $api_key, + "urlList" => $urls, + ]), +]); +echo "Codigo: " . wp_remote_retrieve_response_code($response) . "\n"; +' --allow-root --path=$PATH + +# Submeter todos os posts publicados nos ultimos 7 dias +wp eval ' +$posts = get_posts(["numberposts"=>-1,"post_status"=>"publish","date_query"=>[["after"=>"7 days ago"]]]); +$urls = array_map(function($p) { return get_permalink($p->ID); }, $posts); +$api_key = get_option("rank-math-options-instant-indexing")["indexnow_api_key"] ?? ""; +$chunks = array_chunk($urls, 10000); // IndexNow max 10k por pedido +foreach ($chunks as $chunk) { + $response = wp_remote_post("https://api.indexnow.org/indexnow", [ + "headers" => ["Content-Type" => "application/json"], + "body" => json_encode([ + "host" => parse_url(home_url(), PHP_URL_HOST), + "key" => $api_key, + "urlList" => $chunk, + ]), + ]); + echo count($chunk) . " URLs submetidos. Codigo: " . wp_remote_retrieve_response_code($response) . "\n"; +} +' --allow-root --path=$PATH + +# Verificar API key +wp eval 'echo get_option("rank-math-options-instant-indexing")["indexnow_api_key"] ?? "nao definida"; echo "\n";' --allow-root --path=$PATH + +# Configurar post types para IndexNow +wp option patch update rank-math-options-instant-indexing bing_post_types '["post","page","product"]' --format=json --allow-root --path=$PATH +``` + +**Codigos resposta IndexNow:** 200=sucesso, 202=aceite (pendente), 400=invalido, 403=key invalida, 429=rate limit. + +### Google Indexing API (via classes RM PRO) + +```bash +# Submeter URL via API interna RM +wp eval ' +$target = get_permalink(99); +\RankMath\Instant_Indexing\Api::submit($target, "URL_UPDATED"); +echo "Submetido: $target\n"; +' --allow-root --path=$PATH +``` + +**Limites:** Google Indexing API quota ~200 pedidos/dia. Nao submeter URLs voláteis (parametrizados, facturacao). + +--- + +## 8. Analytics PRO (/rank-math analytics) + +### Tabelas de analytics (apenas com modulo analytics activo + PRO) + +```bash +# Dados Google Search Console armazenados +wp db query "SELECT page, SUM(clicks) as clicks, SUM(impressions) as impressions, +AVG(position) as avg_pos, AVG(ctr) as avg_ctr +FROM ${PREFIX}rank_math_analytics_gsc +WHERE created >= DATE_SUB(NOW(), INTERVAL 30 DAY) +GROUP BY page ORDER BY clicks DESC LIMIT 20;" --allow-root --path=$PATH + +# Top queries +wp db query "SELECT query, SUM(clicks) as clicks, SUM(impressions) as impressions, +AVG(position) as avg_pos +FROM ${PREFIX}rank_math_analytics_gsc +WHERE created >= DATE_SUB(NOW(), INTERVAL 30 DAY) +GROUP BY query ORDER BY clicks DESC LIMIT 30;" --allow-root --path=$PATH + +# Objectos rastreados (seo score, indexabilidade) +wp db query "SELECT page, seo_score, is_indexable, object_type +FROM ${PREFIX}rank_math_analytics_objects +ORDER BY seo_score ASC LIMIT 20;" --allow-root --path=$PATH + +# Posts com pior ranking +wp db query "SELECT gsc.page, gsc.query, AVG(gsc.position) as avg_pos, ao.seo_score +FROM ${PREFIX}rank_math_analytics_gsc gsc +LEFT JOIN ${PREFIX}rank_math_analytics_objects ao ON gsc.page = ao.page +WHERE gsc.created >= DATE_SUB(NOW(), INTERVAL 7 DAY) +GROUP BY gsc.page, gsc.query +HAVING avg_pos > 10 +ORDER BY gsc.impressions DESC LIMIT 20;" --allow-root --path=$PATH + +# Google Analytics pageviews (se integrado) +wp db query "SELECT page, SUM(pageviews) as views, SUM(visitors) as visitors +FROM ${PREFIX}rank_math_analytics_ga +GROUP BY page ORDER BY views DESC LIMIT 20;" --allow-root --path=$PATH + +# Links internos +wp db query "SELECT post_id, internal_link_count, external_link_count, incoming_link_count +FROM ${PREFIX}rank_math_internal_meta +ORDER BY incoming_link_count ASC LIMIT 20;" --allow-root --path=$PATH +``` + +--- + +## 9. Taxonomias e WooCommerce (/rank-math taxonomy) + +### Terms (categorias, tags, taxonomias custom) + +```bash +# LER titulo SEO de categoria +wp term meta get 15 rank_math_title --allow-root --path=$PATH + +# DEFINIR description SEO +wp term meta update 23 rank_math_description "Descricao SEO da tag." --allow-root --path=$PATH + +# DEFINIR noindex numa taxonomia +wp term meta update 23 rank_math_robots '["noindex"]' --format=json --allow-root --path=$PATH +# CUIDADO: noindex numa categoria remove do indice TODAS as paginas arquivo dessa cat +``` + +### WooCommerce bulk + +```bash +# Titulo SEO para todas as categorias de produto sem titulo +wp eval ' +$terms = get_terms(["taxonomy"=>"product_cat","hide_empty"=>false]); +$updated = 0; +foreach ($terms as $t) { + if (!get_term_meta($t->term_id, "rank_math_title", true)) { + update_term_meta($t->term_id, "rank_math_title", "%term% %sep% %sitename%"); + $updated++; + } +} +echo "$updated categorias actualizadas\n"; +' --allow-root --path=$PATH + +# Descricao SEO para categorias de produto a partir da descricao da categoria +wp eval ' +$terms = get_terms(["taxonomy"=>"product_cat","hide_empty"=>false]); +$updated = 0; +foreach ($terms as $t) { + if (!get_term_meta($t->term_id, "rank_math_description", true) && $t->description) { + $desc = wp_trim_words($t->description, 25, "..."); + update_term_meta($t->term_id, "rank_math_description", $desc); + $updated++; + } +} +echo "$updated categorias actualizadas\n"; +' --allow-root --path=$PATH + +# Noindex em taxonomias de atributos vazias (cor, tamanho, etc.) +wp eval ' +$taxonomies = wc_get_attribute_taxonomy_names(); +$noindexed = 0; +foreach ($taxonomies as $tax) { + $terms = get_terms(["taxonomy"=>$tax,"hide_empty"=>true]); + foreach ($terms as $t) { + if (!get_term_meta($t->term_id, "rank_math_robots", true)) { + update_term_meta($t->term_id, "rank_math_robots", ["noindex"]); + $noindexed++; + } + } +} +echo "$noindexed atributos noindexados\n"; +' --allow-root --path=$PATH +``` + +### User meta (arquivo de autor) + +```bash +wp user meta update 1 rank_math_title "Nome Autor — Especialista WordPress" --allow-root --path=$PATH +wp user meta update 1 rank_math_description "Artigos sobre WordPress e SEO." --allow-root --path=$PATH +``` + +--- + +## 10. News Sitemap PRO (/rank-math news) + +```bash +# Activar modulo +wp eval ' +$modules = get_option("rank_math_modules", []); +if (!in_array("news-sitemap", $modules)) { $modules[] = "news-sitemap"; update_option("rank_math_modules", $modules); } +echo "News Sitemap activo\n"; +' --allow-root --path=$PATH + +# Definir meta por post +wp post meta update ID rank_math_news_sitemap_robots "index" --allow-root --path=$PATH +wp post meta update ID rank_math_news_sitemap_genres "PressRelease" --allow-root --path=$PATH +# Generos: Blog, PressRelease, Satire, OpEd +wp post meta update ID rank_math_news_sitemap_keywords "ia,automacao,marketing" --allow-root --path=$PATH +wp post meta update ID rank_math_news_sitemap_stock_tickers "GOOG,MSFT" --allow-root --path=$PATH + +# Configurar post types para news sitemap +wp eval ' +$opts = get_option("rank-math-options-sitemap"); +$opts["news_sitemap_post_type"] = ["post"]; +update_option("rank-math-options-sitemap", $opts); +' --allow-root --path=$PATH +``` + +--- + +## 11. Hooks e filtros (/rank-math hooks) + +### Frontend + +```bash +# Modificar titulo via filtro (persistente via rank-math.php) +wp eval ' +file_put_contents(get_stylesheet_directory() . "/rank-math.php", +"get_results("SELECT post_id, meta_key, meta_value FROM {$wpdb->postmeta} WHERE meta_key LIKE \"rank_math_%\"", ARRAY_A); +file_put_contents("/tmp/rankmath-postmeta-backup.json", json_encode($results)); +echo count($results) . " meta entries exportadas\n"; +' --allow-root --path=$PATH + +# Exportar redirects +wp db query "SELECT * FROM ${PREFIX}rank_math_redirections;" --allow-root --path=$PATH > /tmp/rankmath-redirections-backup.tsv + +# Exportar dados SEO para CSV +wp eval ' +$posts = get_posts(["post_type"=>"post","post_status"=>"publish","numberposts"=>-1]); +$fp = fopen("/tmp/rankmath-seo-export.csv", "w"); +fputcsv($fp, ["ID","Titulo","SEO_Title","Description","Focus_KW","Score","Canonical"]); +foreach ($posts as $p) { + fputcsv($fp, [ + $p->ID, $p->post_title, + get_post_meta($p->ID, "rank_math_title", true), + get_post_meta($p->ID, "rank_math_description", true), + get_post_meta($p->ID, "rank_math_focus_keyword", true), + get_post_meta($p->ID, "rank_math_seo_score", true), + get_post_meta($p->ID, "rank_math_canonical_url", true), + ]); +} +fclose($fp); +echo count($posts) . " posts exportados\n"; +' --allow-root --path=$PATH +``` + +### Rollback + +```bash +# Restaurar options de backup +wp eval ' +$backup = json_decode(file_get_contents("/tmp/rankmath-options-backup.json"), true); +foreach ($backup as $key => $value) { + update_option($key, $value); + echo "Restaurado: $key\n"; +} +' --allow-root --path=$PATH + +# Restaurar post meta de backup +wp eval ' +$entries = json_decode(file_get_contents("/tmp/rankmath-postmeta-backup.json"), true); +$restored = 0; +foreach ($entries as $e) { + update_post_meta($e["post_id"], $e["meta_key"], maybe_unserialize($e["meta_value"])); + $restored++; +} +echo "$restored meta entries restauradas\n"; +' --allow-root --path=$PATH +``` + +--- + +## 13. Provisioning (/rank-math provision) + +Configuracao completa de um site novo. + +```bash +# 1. Activar modulos essenciais +wp eval ' +update_option("rank_math_modules", ["sitemap","rich-snippet","redirections","404-monitor","seo-analysis","link-counter","instant-indexing","image-seo"]); +echo "Modulos configurados\n"; +' --allow-root --path=$PATH + +# 2. Configuracoes globais +wp option patch update rank-math-options-titles title_separator "-" --allow-root --path=$PATH +wp option patch update rank-math-options-titles knowledgegraph_type "Organization" --allow-root --path=$PATH +wp option patch update rank-math-options-titles knowledgegraph_name "Nome Empresa" --allow-root --path=$PATH +wp option patch update rank-math-options-general strip_category_base "on" --allow-root --path=$PATH +wp option patch update rank-math-options-general nofollow_external_links "on" --allow-root --path=$PATH +wp option patch update rank-math-options-general attachment_redirect_urls "on" --allow-root --path=$PATH +wp option patch update rank-math-options-sitemap pt_attachment_sitemap "off" --allow-root --path=$PATH + +# 3. Templates por post type +wp option patch update rank-math-options-titles pt_post_title "%title% %sep% %sitename%" --allow-root --path=$PATH +wp option patch update rank-math-options-titles pt_page_title "%title% %sep% %sitename%" --allow-root --path=$PATH +wp option patch update rank-math-options-titles pt_post_description "%excerpt%" --allow-root --path=$PATH + +# 4. Flush e regenerar +wp rewrite flush --allow-root --path=$PATH +wp rankmath sitemap generate --allow-root --path=$PATH + +echo "Provisioning concluido" +``` + +--- + +## 14. Validacao pos-aplicacao + +### Verificar schema no HTML + +```bash +# Verificar JSON-LD no frontend +curl -s "https://site.pt/post/" | grep -o '"@type":"[^"]*"' | sort -u + +# Extrair JSON-LD completo +curl -s "https://site.pt/post/" | grep -oP '