@lucapimenta/copy-chief-black 1.0.0

package/framework/GUIA-INSTALACAO.md

@@ -0,0 +1,382 @@
+# Guia de Instalação - Ecossistema de Copywriting v4.9.6
+
+**Versão:** 4.9.6
+**Atualizado:** 2026-01-26
+**Plataformas:** macOS, Windows (WSL), Linux
+
+---
+
+## Pré-Requisitos
+
+### Todos os Sistemas
+
+| Requisito | Versão Mínima | Verificar |
+|-----------|---------------|-----------|
+| Claude Code | Última | `claude --version` |
+| Python 3 | 3.8+ | `python3 --version` |
+| Git | 2.0+ | `git --version` |
+| Bun (para hooks) | 1.0+ | `bun --version` |
+
+### Dependências Python
+
+```bash
+pip3 install pyyaml
+```
+
+---
+
+## INSTALAÇÃO NO MAC
+
+### Passo 1: Baixar Claude Code
+
+```bash
+# Via Homebrew (recomendado)
+brew install claude-code
+
+# Ou via npm
+npm install -g @anthropic/claude-code
+```
+
+### Passo 2: Instalar Bun (para hooks)
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Passo 3: Extrair o Ecossistema
+
+**IMPORTANTE:** Extrair no Desktop, NUNCA dentro de ~/copywriting-ecosystem
+
+```bash
+cd ~/Desktop
+unzip ecossistema-v4.9.6-installer.zip
+cd ecossistema-v4.9.6-installer
+```
+
+### Passo 4: Executar Instalador
+
+```bash
+./install.sh
+```
+
+O instalador faz:
+1. Copia `payload/.claude/` → `~/.claude/`
+2. Copia `payload/copywriting-ecosystem/` → `~/copywriting-ecosystem/`
+3. Instala dependências Python
+4. Configura permissões
+
+### Passo 5: Verificar Instalação
+
+```bash
+cd ~/copywriting-ecosystem && claude
+```
+
+Na sessão Claude, digite:
+```
+mostrar status do ecossistema
+```
+
+Deve retornar: `🟢 OPERACIONAL`
+
+---
+
+## INSTALAÇÃO NO WINDOWS (WSL)
+
+### Passo 1: Instalar WSL
+
+Abra PowerShell como Administrador:
+
+```powershell
+wsl --install
+```
+
+Reinicie o computador quando solicitado.
+
+### Passo 2: Configurar Ubuntu
+
+Após reiniciar, abra "Ubuntu" no menu iniciar.
+
+Crie usuário e senha quando solicitado.
+
+### Passo 3: Atualizar Sistema
+
+```bash
+sudo apt update && sudo apt upgrade -y
+```
+
+### Passo 4: Instalar Dependências
+
+```bash
+# Python e pip
+sudo apt install python3 python3-pip -y
+
+# Git
+sudo apt install git -y
+
+# Node.js (para Claude Code)
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install nodejs -y
+
+# Bun (para hooks)
+curl -fsSL https://bun.sh/install | bash
+source ~/.bashrc
+```
+
+### Passo 5: Instalar Claude Code
+
+```bash
+npm install -g @anthropic/claude-code
+```
+
+### Passo 6: Transferir ZIP para WSL
+
+**Opção A: Via Explorer**
+1. No Explorer Windows, navegue até `\\wsl$\Ubuntu\home\SEU_USUARIO\`
+2. Copie o ZIP para lá
+
+**Opção B: Via comando**
+```bash
+# No WSL
+cp /mnt/c/Users/SEU_USUARIO/Desktop/ecossistema-v4.9.6-installer.zip ~/
+```
+
+### Passo 7: Extrair e Instalar
+
+```bash
+cd ~
+unzip ecossistema-v4.9.6-installer.zip
+cd ecossistema-v4.9.6-installer
+chmod +x install.sh
+./install.sh
+```
+
+### Passo 8: Instalar PyYAML
+
+```bash
+pip3 install pyyaml
+```
+
+### Passo 9: Verificar Instalação
+
+```bash
+cd ~/copywriting-ecosystem && claude
+```
+
+---
+
+## INSTALAÇÃO NO LINUX
+
+Mesmos passos do WSL, exceto:
+- Pular passos 1-2 (WSL)
+- Instalar dependências conforme sua distro
+
+### Ubuntu/Debian
+```bash
+sudo apt install python3 python3-pip git nodejs npm unzip -y
+```
+
+### Fedora
+```bash
+sudo dnf install python3 python3-pip git nodejs npm unzip -y
+```
+
+### Arch
+```bash
+sudo pacman -S python python-pip git nodejs npm unzip
+```
+
+---
+
+## ESTRUTURA APÓS INSTALAÇÃO
+
+```
+~/
+├── .claude/                          ← Configuração global
+│   ├── CLAUDE.md                     ← Instruções autoritativas
+│   ├── CHANGELOG.md                  ← Histórico de versões
+│   ├── GUIA-INSTALACAO.md            ← Este arquivo
+│   ├── ecosystem-status.md           ← Status dos componentes
+│   ├── settings.json                 ← Hooks e permissões
+│   ├── .version                      ← Single Source of Truth
+│   ├── skills/                       ← 10+ skills instaladas
+│   ├── commands/                     ← Slash commands
+│   ├── agents/                       ← Subagents
+│   ├── templates/                    ← Templates de research
+│   ├── hooks/                        ← Hooks TypeScript
+│   └── scripts/                      ← Scripts de manutenção
+│
+└── copywriting-ecosystem/            ← Diretório de trabalho
+    ├── TUTORIAL-COMO-USAR.md         ← Guia passo-a-passo
+    ├── scripts/                      ← Scripts de validação
+    │   ├── sync-tracking.py          ← Enforcement automático
+    │   ├── validate-research.sh      ← Validação de gate
+    │   └── validate-gate.py          ← Validação Python
+    ├── concursos/                    ← Nicho: Concursos
+    │   ├── hacker/                   ← Oferta 1
+    │   ├── gpt-dos-aprovados/        ← Oferta 2
+    │   ├── gabaritando-lei-seca/     ← Oferta 3
+    │   └── concursa-ai/              ← Oferta 4
+    └── templates/                    ← Templates de oferta
+```
+
+---
+
+## VERIFICAÇÃO COMPLETA
+
+### 1. Verificar Claude Code
+
+```bash
+claude --version
+```
+
+### 2. Verificar Hooks
+
+```bash
+ls ~/.claude/hooks/
+# Deve mostrar: session-start.ts, user-prompt.ts, curation.ts
+```
+
+### 3. Verificar Skills
+
+```bash
+ls ~/.claude/skills/
+# Deve mostrar: 10+ diretórios de skills
+```
+
+### 4. Verificar Scripts
+
+```bash
+python3 ~/copywriting-ecosystem/scripts/sync-tracking.py --check
+```
+
+### 5. Teste Completo
+
+```bash
+cd ~/copywriting-ecosystem && claude
+```
+
+Digite:
+```
+validar gate research para hacker
+```
+
+Deve retornar resultado da validação.
+
+---
+
+## TROUBLESHOOTING
+
+### "bun: command not found"
+
+```bash
+# Recarregar shell
+source ~/.bashrc
+# Ou
+source ~/.zshrc
+
+# Se ainda não funcionar
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+```
+
+### "python3: command not found"
+
+```bash
+# Mac
+brew install python3
+
+# Ubuntu/WSL
+sudo apt install python3 python3-pip -y
+```
+
+### "ModuleNotFoundError: No module named 'yaml'"
+
+```bash
+pip3 install pyyaml
+```
+
+### "Permission denied" no install.sh
+
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+### "Claude não reconhece skills"
+
+```bash
+# Verificar se CLAUDE.md existe
+cat ~/.claude/CLAUDE.md | head -20
+
+# Se não existir, reinstalar
+cd ~/Desktop/ecossistema-v4.9.6-installer
+./install.sh
+```
+
+### Hooks não executam
+
+```bash
+# Verificar settings.json
+cat ~/.claude/settings.json | grep -A5 "SessionEnd"
+
+# Deve mostrar hooks configurados
+```
+
+---
+
+## ATUALIZAÇÃO
+
+### De versão anterior para v4.9.6
+
+1. **Backup (opcional)**
+```bash
+cp -r ~/copywriting-ecosystem ~/copywriting-ecosystem-backup
+cp -r ~/.claude ~/.claude-backup
+```
+
+2. **Extrair novo installer**
+```bash
+cd ~/Desktop
+unzip ecossistema-v4.9.6-installer.zip
+cd ecossistema-v4.9.6-installer
+```
+
+3. **Executar instalador**
+```bash
+./install.sh
+```
+
+O instalador preserva:
+- Ofertas existentes em `~/copywriting-ecosystem/concursos/`
+- Dados de research e briefings
+- project_state.yaml de cada oferta
+
+---
+
+## SUPORTE
+
+### Diagnóstico Automático
+
+```bash
+cd ~/copywriting-ecosystem
+./scripts/diagnose.sh
+```
+
+### Verificar Status
+
+```bash
+cd ~/copywriting-ecosystem && claude
+# Digite: mostrar ecosystem status
+```
+
+### Logs de Hooks
+
+```bash
+# Ver erros recentes
+cat ~/.claude/debug/hooks.log 2>/dev/null || echo "Sem logs"
+```
+
+---
+
+*Guia criado: 2026-01-24*
+*Versão: v4.9.6*

package/framework/GUIA-USO-ECOSSISTEMA.md

@@ -0,0 +1,238 @@
+# Guia de Uso Consistente do Ecossistema de Copywriting v4.9
+
+## TL;DR (Resumo Rápido)
+
+```bash
+# SEMPRE abrir assim:
+cd ~/copywriting-ecosystem && claude
+
+# NUNCA abrir assim:
+cd ~/copywriting-ecosystem/concursos/hacker && claude  # ❌
+```
+
+---
+
+## 1. Regras de Ouro
+
+### Regra #1: SEMPRE Abrir do Mesmo Diretório
+
+```bash
+cd ~/copywriting-ecosystem && claude
+```
+
+**Por quê?** Claude Code carrega CLAUDE.md do diretório atual. Abrir de locais diferentes = instruções diferentes = contexto bagunçado.
+
+### Regra #2: Nunca Extrair ZIP Dentro do Ecossistema
+
+```bash
+# ✅ CORRETO
+cd ~/Desktop && unzip ecossistema-vXX-installer.zip
+
+# ❌ INCORRETO (cria duplicados)
+cd ~/copywriting-ecosystem && unzip *.zip
+```
+
+### Regra #3: Manter Apenas 1 Installer
+
+Após atualização, deletar installers antigos:
+```bash
+rm ~/Desktop/ecossistema-v{versoes_antigas}*.zip
+# Manter apenas a versão atual
+```
+
+---
+
+## 2. Hierarquia de Contexto
+
+```
+~/.claude/CLAUDE.md              ← GLOBAL (sempre carregado, AUTORITATIVO)
+    ↓
+~/copywriting-ecosystem/CLAUDE.md    ← PROJETO (carregado se abrir daqui)
+    ↓
+{nicho}/CLAUDE.md                    ← NICHO (OPCIONAL, não recomendado)
+    ↓
+{oferta}/CLAUDE.md                   ← OFERTA (OPCIONAL, não recomendado)
+```
+
+**Recomendação:** Concentrar instruções APENAS em `~/.claude/CLAUDE.md`.
+
+---
+
+## 3. Estrutura de Diretórios v4.9
+
+```
+~/copywriting-ecosystem/
+├── {nicho}/                         ← Pasta do nicho (concursos, saude, etc)
+│   ├── biblioteca_nicho_*.md        ← VOC consolidada do nicho
+│   └── {oferta}/                    ← Pasta da oferta
+│       ├── research/
+│       │   ├── voc/
+│       │   │   ├── raw/             ← Nunca carregar no contexto
+│       │   │   ├── processed/       ← Carregar quando necessário
+│       │   │   ├── summary.md       ← SEMPRE carregar primeiro (≤500 tokens)
+│       │   │   └── trends-analysis.md
+│       │   ├── competitors/
+│       │   ├── mechanism/
+│       │   └── avatar/
+│       ├── briefings/
+│       │   ├── phases/              ← 10 fases HELIX
+│       │   └── validations/         ← copy-critic verdicts
+│       ├── production/
+│       │   ├── vsl/ ou landing-page/
+│       │   ├── creatives/
+│       │   └── emails/
+│       ├── reviews/
+│       ├── task_plan.md
+│       ├── findings.md
+│       └── progress.md
+├── templates/
+├── task_plan.md                     ← Planejamento global
+├── findings.md
+└── progress.md
+```
+
+---
+
+## 4. Onde Armazenar Cada Tipo de Contexto
+
+| Tipo | Localização | Carregamento |
+|------|-------------|--------------|
+| Instruções globais | `~/.claude/CLAUDE.md` | Automático |
+| Skills/Agentes | `~/.claude/skills/` | On-demand |
+| Templates | `~/.claude/templates/` | Referência manual |
+| Memória entre sessões | claude-mem plugin | Automático |
+| Planejamento global | `~/copywriting-ecosystem/task_plan.md` | Manual |
+| Planejamento oferta | `{oferta}/task_plan.md` | Manual |
+| Pesquisa VOC | `{oferta}/research/voc/summary.md` | Carregar primeiro |
+| Briefing HELIX | `{oferta}/briefings/phases/` | Por fase |
+| Produção | `{oferta}/production/` | Gerar aqui |
+
+---
+
+## 5. Workflow de Início de Sessão
+
+```
+1. Abrir terminal
+2. cd ~/copywriting-ecosystem
+3. claude
+4. Ler task_plan.md global
+5. Verificar qual oferta está em andamento
+6. Ler task_plan.md da oferta específica
+7. Continuar trabalho
+```
+
+---
+
+## 6. Workflow de Atualização do Ecossistema
+
+```bash
+# 1. Backup
+cp -r ~/copywriting-ecosystem ~/copywriting-ecosystem-backup-$(date +%Y%m%d)
+
+# 2. Extrair novo installer no Desktop
+cd ~/Desktop && unzip ecossistema-vXX-installer.zip
+
+# 3. Copiar APENAS templates/configs atualizados
+# NÃO substituir todo o diretório (perderia seu trabalho)
+
+# 4. Deletar backup após confirmar que tudo funciona
+rm -rf ~/copywriting-ecosystem-backup-*
+```
+
+---
+
+## 7. Checklist de Manutenção Semanal
+
+- [ ] Verificar duplicados: `find ~/copywriting-ecosystem -name "copywriting-ecosystem" -type d`
+- [ ] Atualizar task_plan.md com status real
+- [ ] Fazer commit: `cd ~/copywriting-ecosystem && git add . && git commit -m "weekly update"`
+- [ ] Verificar versão do ecossistema vs installer
+- [ ] Limpar arquivos temporários em `raw/`
+
+---
+
+## 8. Comandos de Diagnóstico
+
+```bash
+# Verificar estrutura
+ls -la ~/copywriting-ecosystem/
+
+# Verificar ofertas ativas
+ls ~/copywriting-ecosystem/concursos/
+
+# Verificar se há duplicados
+find ~/copywriting-ecosystem -name "copywriting-ecosystem" -type d
+
+# Verificar versão do installer
+ls ~/Desktop/ecossistema-v*.zip
+
+# Verificar tamanho do ecossistema
+du -sh ~/copywriting-ecosystem/
+```
+
+---
+
+## 9. Troubleshooting
+
+### Problema: "Contexto diferente do esperado"
+**Causa:** Abriu Claude Code de diretório errado
+**Solução:** Fechar e reabrir com `cd ~/copywriting-ecosystem && claude`
+
+### Problema: "Diretórios duplicados aparecendo"
+**Causa:** Extraiu ZIP dentro do ecossistema
+**Solução:**
+```bash
+rm -rf ~/copywriting-ecosystem/copywriting-ecosystem/
+```
+
+### Problema: "task_plan.md desatualizado"
+**Causa:** Não atualizou após progresso
+**Solução:** Ler status real das ofertas e atualizar manualmente
+
+### Problema: "Instruções conflitantes"
+**Causa:** Múltiplos CLAUDE.md com conteúdo diferente
+**Solução:** Concentrar tudo em `~/.claude/CLAUDE.md`, limpar os outros
+
+---
+
+## 10. Versões Canônicas
+
+| Componente | Versão | Localização |
+|------------|--------|-------------|
+| Ecossistema | v4.9 | `~/.claude/CLAUDE.md` |
+| Ads Library Spy | v4.9 | Mesmo arquivo |
+| VOC Quality Protocol | v4.2 | Mesmo arquivo |
+| trends-analysis | v2.0 | `~/.claude/templates/` |
+| Installer | v4.9 | `~/Desktop/ecossistema-v49-installer.zip` |
+
+---
+
+## 11. Skills Disponíveis
+
+| Trigger | Skill | Função |
+|---------|-------|--------|
+| VOC, audience, pesquisa | audience-research-agent | Pesquisa de público |
+| helix, briefing, fases | helix-system-agent | Briefing estratégico |
+| criativo, hook, anúncio | criativos-agent | Produção de ads |
+| LP, landing, página | landing-page-agent | Landing pages |
+| validar, testar, criticar | copy-critic | Validação adversarial |
+| fragmentar, dividir, RAG | fragment-agent | Otimização para Projects |
+| prompt, setup, agente | ai-setup-architect | Meta-arquitetura |
+
+---
+
+## 12. Slash Commands
+
+| Comando | Função |
+|---------|--------|
+| `/helix-parallel [offer]` | Pesquisa sequencial (4 módulos) |
+| `/squad-research [offer]` | Pesquisa paralela via claude-squad |
+| `/produce-offer [offer]` | Produção paralela (4 módulos) |
+| `/review-all [offer]` | Review multi-model |
+| `/create-offer [offer]` | Criar estrutura nova oferta |
+| `/update-ecosystem` | Atualizar installer |
+
+---
+
+*Guia criado: 2026-01-21*
+*Versão: v4.9*