📦 Downloads

4 arquivos em 2 pacotes. Os .bat são os launchers — só dar dois cliques.

Pacote 1 — Instalador (Parte 1)

Pacote 2 — Conector (Parte 2)

Como executar

✅ Opção 1 — Dois cliques no .bat (recomendada)

Dê dois cliques em instalar.bat (ou conectar.bat). O terminal abre, roda o script e fica aberto ao final — se houver erro, o terminal mostra a mensagem para você copiar e enviar ao suporte.

Opção 2 — Clique direito no .ps1

Clique com o botão direito no arquivo .ps1 → "Executar com PowerShell". Se pedir confirmação, clique em "Sim".

Opção 3 — Via terminal (controle total)

powershell -ExecutionPolicy Bypass -File C:\caminho\para\instalar.ps1

Opção 4 — Liberar política permanentemente (avançado)

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

🔍 Pré-requisitos

O que você precisa ter antes de rodar o instalador. Não se preocupe — o próprio script instala o que estiver faltando.

O que o script instala automaticamente

O que você instala manualmente (uma vez)

Verificação manual (opcional)

Se quiser verificar antes de rodar o script, abra o PowerShell e teste:

python --version
node --version
npm --version

⚙️ Executar instalar.ps1

Guia de acompanhamento para quando o script estiver rodando.

Etapa 1 — Perguntas de Configuração

O script vai perguntar 4 coisas. Anote suas respostas antes:

Etapa 2 — Instalação de Dependências

O script vai detectar e instalar automaticamente. Pode demorar alguns minutos se for a primeira vez. Mensagens normais que você vai ver:

[OK] Python encontrado: Python 3.11.x
[OK] Node.js encontrado: v20.x.x
  Instalando requests...
  Instalando google-ads...
[OK] Pacotes Python instalados.
[OK] Claude Code instalado.

Etapas 3 a 9 — Criação Automática

O script cria tudo sozinho. Você não precisa fazer nada — só aguardar:

Resultado esperado

Ao final, o script mostra:

============================================================
  INSTALACAO CONCLUIDA
============================================================

  Sistema instalado com sucesso em:
  C:\minha-agencia\

  [OK] Estrutura de pastas completa
  [OK] CLAUDE.md personalizado para Minha Agencia
  [OK] index.md, log.md, wiki/overview.md
  [OK] Tabelas de referencia: credenciais-apis.md + meta-ads-validador.md
  [OK] guia-boas-praticas.md (personalizado para seu perfil)
  [OK] Skills em .claude/commands/
  [OK] 3 agentes IA em system-prompts/agents/
  [OK] 4 scripts Python de coleta e automacao
  [OK] Templates de credenciais em credentials/
  [OK] Dependencias Python instaladas
  [OK] Claude Code instalado

🗂️ Configurar o Obsidian

O Obsidian é onde você vai visualizar e navegar pelo seu wiki. O LLM escreve, você lê.

Instalar o Obsidian

Plugins recomendados (opcional)

Vá em Configurações (ícone de engrenagem) → Community Plugins → Browse:

O que você deve ver no Obsidian

No painel esquerdo (explorador de arquivos), a estrutura deve aparecer assim:

📁 minha-agencia
├── 📄 CLAUDE.md
├── 📄 index.md
├── 📄 log.md
├── 📄 guia-boas-praticas.md       ← personalizado para o seu perfil
├── 📁 raw/
├── 📁 wiki/
│   ├── 📄 overview.md
│   ├── 📁 clients/
│   │   └── 📄 meta-ads-validador.md
│   ├── 📁 references/
│   │   └── 📄 credenciais-apis.md
│   ├── 📁 segments/
│   └── 📁 sources/
├── 📁 outputs/
└── 📁 agente-performance/

🤖 Primeiro Acesso ao Claude Code

Claude Code é o terminal inteligente que vai escrever e manter seu wiki.

Abrir o Claude Code

cd C:\minha-agencia

claude

Resposta esperada do /status

Olá! Estou orientado e pronto.

**Status atual — [Nome do Negócio]**

- Clientes ativos: nenhum ainda
- Fontes ingeridas: 0
- Páginas wiki: 3 (overview, index, log)
- Último lint: nunca

**Próximos passos:**
1. Executar conectar.ps1 para configurar tokens de API
2. Adicionar primeiro cliente com /novo-cliente
3. Ingerir primeiras fontes com /ingerir

Conta Anthropic

Para usar o Claude Code você precisa de uma conta em anthropic.com. O plano gratuito tem limite de mensagens. Para uso profissional, recomendamos o plano pago para ter acesso sem restrições.

✅ Checklist — Parte 1 Concluída

Confirme cada item antes de avançar para a Parte 2. Clique nos itens para marcar.

Instalação

• ☐ instalar.bat (ou instalar.ps1) executado sem erros críticos
• ☐ Python instalado e funcionando (python --version)
• ☐ Node.js instalado e funcionando (node --version)
• ☐ Claude Code instalado (claude --version)
• ☐ Pasta do vault criada com estrutura completa
• ☐ CLAUDE.md criado com nome do negócio correto
• ☐ Guia de boas práticas criado em guia-boas-praticas.md (raiz do vault)
• ☐ Tabelas de referência criadas: credenciais-apis.md e meta-ads-validador.md
• ☐ Scripts Python presentes em agente-performance/

Obsidian

• ☐ Obsidian instalado
• ☐ Vault apontado para a pasta correta
• ☐ Estrutura de pastas visível no explorador do Obsidian
• ☐ CLAUDE.md abre corretamente com o conteúdo personalizado

Claude Code

• ☐ Claude Code abre no terminal da pasta do vault
• ☐ Login com conta Anthropic concluído
• ☐ /status responde com o estado do wiki

📘 Meta Ads: Token Permanente

Um token que nunca expira — a base de toda automação com Meta Ads e Instagram.

Conceito: O que é um System User

É um "usuário técnico" dentro do seu Business Manager — não é uma pessoa real, é uma credencial de sistema. Ele tem as permissões que você define e gera um token permanente.

Pré-requisito: Acesso ao Business Manager

Você precisa ser administrador do Business Manager. Se for gerenciar campanhas de clientes, o token deve ser criado no BM do cliente (ou o cliente deve fazer esses passos e te passar o token).

Passo 1 — Criar App no Meta for Developers

Passo 2 — Adicionar Marketing API

ads_read
ads_management
business_management
instagram_basic
pages_read_engagement

Passo 3 — Criar System User

Passo 4 — Gerar Token Permanente

Passo 5 — Atribuir Ativos ao System User

Ainda na tela do usuário do sistema:

Invoke-RestMethod "https://graph.facebook.com/v22.0/me?access_token=SEU_TOKEN"

Se retornar name e id, o token está válido.

🔵 Google Ads: API OAuth2

Mais passos que o Meta, mas feito uma vez. Depois é automático para sempre.

Os 4 componentes

Passo 1 — MCC (Conta Gerenciadora)

O MCC gerencia todas as contas de clientes. Se já tem, anote o ID. Se não tem:

Passo 2 — Developer Token

Passo 3 — Google Cloud Project

C:\minha-agencia\agente-performance\credentials\client_secret.json

Passo 4 — Gerar Refresh Token

Com o client_secret.json na pasta certa, execute no terminal:

cd C:\minha-agencia\agente-performance
python google-ads\lib\generate_refresh_token.py

Um browser vai abrir. Faça login com a conta Google do MCC. Após autorizar, o script mostra os três valores — copie todos.

🔌 Executar conectar.ps1

Com os dados das páginas anteriores em mãos, o script faz o resto.

Como executar

powershell -ExecutionPolicy Bypass -File C:\caminho\para\conectar.ps1

O que acontece em cada parte

Parte A — Meta Ads

Parte B — Google Ads

Resultado esperado ao final

============================================================
  CONEXOES CONFIGURADAS
============================================================

  [OK] Meta Ads: TOKEN CONFIGURADO
  [OK] Google Ads: CREDENCIAIS CONFIGURADAS

  PROXIMOS PASSOS:
  1. Abra o Obsidian apontando para: C:\minha-agencia
  2. Abra o terminal e execute: claude
  3. Teste com: /status  /novo-cliente  /gerar-relatorio-meta

✅ Checklist — Parte 2 Concluída

Confirme cada item antes de usar o sistema com clientes reais.

Meta Ads

• ☐ App criado no Meta for Developers
• ☐ Marketing API adicionada com permissões corretas
• ☐ System User criado no Business Manager
• ☐ Token permanente gerado (expiração: Nunca)
• ☐ Contas de anúncios atribuídas ao System User
• ☐ Token validado pelo conectar.ps1 (apareceu nome do usuário)
• ☐ credentials/meta.env criado com token real

Google Ads

• ☐ MCC configurado com contas de clientes vinculadas
• ☐ Developer Token solicitado (aguardando aprovação se produção)
• ☐ Projeto criado no Google Cloud
• ☐ Google Ads API ativada no projeto
• ☐ client_secret.json na pasta credentials/
• ☐ Refresh Token gerado com sucesso
• ☐ credentials/google-ads.yaml preenchido
• ☐ Teste de conexão listou contas do MCC

Tabelas de Referência — Regra de Credenciais

• ☐ wiki/references/credenciais-apis.md preenchido com seu(s) token(s) Meta permanentes
• ☐ wiki/clients/meta-ads-validador.md preenchido com Ad Account ID (act_...) de cada cliente
• ☐ Testado: peça ao agente "relatório de [cliente]" — ele deve identificar a conta sem pedir token

⚙️ 9 Skills Base do Sistema

Instaladas automaticamente pelo instalar.ps1. São a espinha dorsal do wiki — gestão de conhecimento e coleta de dados.

Cole o conteúdo ou indique o arquivo:
/ingerir
> Cole aqui o relatório de campanha...

🚀 10 Skills Avançadas

Adicionadas ao sistema para otimizar o tempo do gestor nas tarefas de maior recorrência e impacto. Cada skill resolve um problema real do dia a dia.

/copy-meta support-health leads-whatsapp

/proposta medicina-integrativa

Mapa completo: todas as 19 skills

🚀 Primeiros Comandos

Sistema instalado e conectado. Aqui estão os primeiros passos para operação real.

Sequência recomendada para o primeiro dia

cd C:\minha-agencia && claude

/status

/novo-cliente

/ingerir

/gerar-relatorio-meta

Referência rápida de todos os comandos

Rotina semanal sugerida

Segunda:   /diagnostico-conta (verificar todas as contas)
Quarta:    /consultar "o que está pendente esta semana?"
Sexta:     Registrar reuniões da semana com /reuniao

Fechamento mensal:
  /gerar-relatorio-meta (todos os clientes)
  /gerar-relatorio-google (todos os clientes)
  /segmento (análise cruzada)
  /lint (saúde do wiki)

❓ Problemas Comuns

Soluções para os erros mais frequentes durante a instalação e uso.

Arquivos .bat

❌ Duplo clique no .bat abre e fecha o terminal instantaneamente

Isso acontece quando o .bat não encontra o arquivo .ps1 ao lado. Verifique se os dois arquivos estão na mesma pasta. Se você mover só o .bat, ele quebra. Mantenha sempre instalar.bat e instalar.ps1 juntos.

❌ "Não é possível carregar o arquivo" ao rodar o .bat

O Windows bloqueou o arquivo porque foi baixado da internet. Clique direito no .ps1 → Propriedades → marque "Desbloquear" na parte inferior → OK. Depois execute o .bat normalmente.

❓ Qual a diferença entre .bat e .ps1?

O .bat é só um launcher: ele abre o PowerShell com as configurações certas e executa o .ps1. O .ps1 é o script real com toda a lógica. Use sempre o .bat para executar — é mais simples e mais robusto. O .ps1 existe para quem prefere mais controle ou precisa resolver problemas.

Regra de Credenciais (Meta Ads)

❓ O agente ainda pede token mesmo depois de preencher as tabelas

Verifique se o arquivo wiki/references/credenciais-apis.md está na pasta certa dentro do vault. O agente só lê arquivos dentro da pasta onde o Claude Code foi aberto. Certifique-se de abrir o Claude Code dentro da pasta do vault (cd C:\minha-agencia && claude).

❓ Como funcionam as tabelas de referência de credenciais?

Quando você menciona um cliente por nome, o agente lê automaticamente credenciais-apis.md (token Meta) e meta-ads-validador.md (Ad Account ID, Page ID, Instagram) e cruza as informações pelo nome do cliente — aceita correspondência parcial ("Ipatinga" encontra "Integrative Ipatinga"). Só depois pergunta se pode executar. Você nunca mais precisa colar token em conversa.

Instalação

❌ "winget não é reconhecido como comando"

O winget requer Windows 10 versão 1809+. Solução: instale Python e Node.js manualmente pelos sites oficiais antes de rodar o script.

# Verificar versão do Windows
winver

❌ "Acesso negado" ao criar pastas

Execute o PowerShell como Administrador. Clique com botão direito no ícone do PowerShell → "Executar como Administrador".

❌ "claude não é reconhecido"

Feche e reabra o terminal. Se persistir:

npm install -g @anthropic-ai/claude-code
# Fechar e reabrir o terminal

Meta Ads

❌ Token retorna erro "Invalid OAuth access token"

O token foi copiado com espaços ou quebra de linha. Copie novamente clicando diretamente no token no Business Manager, sem arrastar para selecionar.

❌ "User does not have permission" ao listar contas

O System User não foi atribuído às contas de anúncios. Volte ao Business Manager → Usuários do Sistema → Atribuir ativos → Contas de anúncios.

❌ Token expira mesmo sendo "permanente"

Isso acontece se o app foi criado com tipo errado ou se as permissões foram revogadas. Gere um novo token com o mesmo processo — o mesmo System User pode ter múltiplos tokens.

Google Ads

❌ "Developer token has not been approved"

Normal. O token de produção precisa de aprovação manual do Google (até 5 dias úteis). Enquanto aguarda, você pode usar Meta Ads normalmente. O Google Ads vai funcionar quando o token for aprovado.

❌ "The caller does not have permission" no teste de conexão

A conta Google usada para gerar o refresh token não tem acesso ao MCC. Use a mesma conta Gmail que é administradora do MCC para gerar o token.

❌ "client_secret.json não encontrado"

Verifique o nome exato do arquivo e o caminho:

C:\minha-agencia\agente-performance\credentials\client_secret.json

O nome deve ser exatamente client_secret.json — sem outros caracteres no nome.

Claude Code

❌ Agente não lê o CLAUDE.md

Verifique se o Claude Code foi aberto dentro da pasta do vault:

cd C:\minha-agencia
claude

❌ "/status" retorna resposta genérica sem mencionar o nome do negócio

O Claude Code não está lendo o CLAUDE.md correto. Verifique se o arquivo está na raiz da pasta do vault e abra o Claude Code na pasta certa.

❌ Script Python retorna "Credenciais não configuradas"

Execute o conectar.ps1 primeiro. Os scripts verificam se meta.env e google-ads.yaml estão preenchidos antes de rodar.

💡 Boas Práticas de Uso

Como usar o sistema para obter o máximo resultado — e gastar o mínimo de tokens do Claude Code.

1. Economia de Tokens — Por que o Wiki Economiza

O Claude Code cobra por tokens usados em cada sessão. A diferença entre usar o sistema certo e errado é enorme:

2. Regra de Credenciais — Auto-Lookup por Nome

Este sistema tem uma regra automática: ao mencionar qualquer cliente, o agente localiza token e Ad Account sem perguntar. Funciona assim:

3. Estrutura de Pastas — O que vai onde

4. Planejamento de Sessão — Comandos por Frequência

Use os comandos certos no momento certo. O sistema é mais eficiente quando os dados estão atualizados antes de pedir análises.

5. Rotina Recomendada por Perfil

Gestor de Tráfego (Agência)

Início de semana (Seg/Ter):
  /status                          (orientar)
  /diagnostico-conta               (todos os clientes)
  Se anomalia: /alerta-anomalia [cliente]

Meio de semana (Qua):
  /consultar "o que está pendente esta semana?"
  /prep-reuniao [cliente]          (antes de calls)

Fim de semana (Sex):
  /reuniao [cliente]               (registrar calls)
  /ingerir                         (relatórios recebidos)

Fechamento mensal:
  /gerar-relatorio-meta + /gerar-relatorio-google
  /segmento [nome]                 (aprendizados cruzados)
  /lint                            (saúde do wiki)

Profissional Solo (Freelancer)

Antes de cada cliente:
  /prep-reuniao [cliente]
  /resumo-executivo [cliente]      (contexto rápido)

Após reunião:
  /reuniao [cliente]
  /plano-testes [cliente]          (se crescimento travado)

Criação de campanhas:
  /checklist-ativacao [cliente] meta
  /copy-meta [cliente] leads-whatsapp

Ao final do mês:
  /gerar-relatorio-meta
  /redistribuir-budget [cliente]   (realocar orçamento)

In-house (Marketing Interno)

Início da semana:
  /status
  /diagnostico-conta               (verificação rápida)

Antes de reuniões de diretoria:
  /resumo-executivo [empresa]
  /gerar-relatorio-meta

Ao criar campanhas novas:
  /checklist-ativacao [empresa] [plataforma]
  /copy-meta [empresa] [objetivo]

Mensal:
  /autopsia-campanha [empresa] [campanha]  (análise do mês)
  /lint                                    (saúde do wiki)

6. Regras de Ouro