Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs(pt-BR): add commands translation

Paulo Victor Gomes1ef8bc1e72a3
diff --git a/docs/pt-BR/commands/build-fix.md b/docs/pt-BR/commands/build-fix.md
new file mode 100644
index 000000000..feda490a3
--- /dev/null
+++ b/docs/pt-BR/commands/build-fix.md
@@ -0,0 +1,62 @@
+# Build e Correção
+
+Corrija erros de build e de tipos incrementalmente com mudanças mínimas e seguras.
+
+## Passo 1: Detectar Sistema de Build
+
+Identifique a ferramenta de build do projeto e execute o build:
+
+| Indicator | Build Command |
+|-----------|---------------|
+| `package.json` with `build` script | `npm run build` or `pnpm build` |
+| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |
+| `Cargo.toml` | `cargo build 2>&1` |
+| `pom.xml` | `mvn compile` |
+| `build.gradle` | `./gradlew compileJava` |
+| `go.mod` | `go build ./...` |
+| `pyproject.toml` | `python -m py_compile` or `mypy .` |
+
+## Passo 2: Parsear e Agrupar Erros
+
+1. Execute o comando de build e capture o stderr
+2. Agrupe erros por caminho de arquivo
+3. Ordene por ordem de dependência (corrija imports/tipos antes de erros de lógica)
+4. Conte o total de erros para acompanhamento de progresso
+
+## Passo 3: Loop de Correção (Um Erro por Vez)
+
+Para cada erro:
+
+1. **Leia o arquivo** — Use a ferramenta Read para ver o contexto do erro (10 linhas ao redor do erro)
+2. **Diagnostique** — Identifique a causa raiz (import ausente, tipo errado, erro de sintaxe)
+3. **Corrija minimamente** — Use a ferramenta Edit para a menor mudança que resolve o erro
+4. **Rode o build novamente** — Verifique que o erro sumiu e que nenhum novo erro foi introduzido
+5. **Vá para o próximo** — Continue com os erros restantes
+
+## Passo 4: Guardrails
+
+Pare e pergunte ao usuário se:
+- Uma correção introduz **mais erros do que resolve**
+- O **mesmo erro persiste após 3 tentativas** (provavelmente há um problema mais profundo)
+- A correção exige **mudanças arquiteturais** (não apenas correção de build)
+- Os erros de build vêm de **dependências ausentes** (precisa de `npm install`, `cargo add`, etc.)
+
+## Passo 5: Resumo
+
+Mostre resultados:
+- Erros corrigidos (com caminhos de arquivos)
+- Erros restantes (se houver)
+- Novos erros introduzidos (deve ser zero)
+- Próximos passos sugeridos para problemas não resolvidos
+
+## Estratégias de Recuperação
+
+| Situation | Action |
+|-----------|--------|
+| Missing module/import | Check if package is installed; suggest install command |
+| Type mismatch | Read both type definitions; fix the narrower type |
+| Circular dependency | Identify cycle with import graph; suggest extraction |
+| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |
+| Build tool misconfiguration | Read config file; compare with working defaults |
+
+Corrija um erro por vez por segurança. Prefira diffs mínimos em vez de refatoração.
diff --git a/docs/pt-BR/commands/checkpoint.md b/docs/pt-BR/commands/checkpoint.md
new file mode 100644
index 000000000..c69c1e6b9
--- /dev/null
+++ b/docs/pt-BR/commands/checkpoint.md
@@ -0,0 +1,74 @@
+# Comando Checkpoint
+
+Crie ou verifique um checkpoint no seu fluxo.
+
+## Uso
+
+`/checkpoint [create|verify|list] [name]`
+
+## Criar Checkpoint
+
+Ao criar um checkpoint:
+
+1. Rode `/verify quick` para garantir que o estado atual está limpo
+2. Crie um git stash ou commit com o nome do checkpoint
+3. Registre o checkpoint em `.claude/checkpoints.log`:
+
+```bash
+echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
+```
+
+4. Informe que o checkpoint foi criado
+
+## Verificar Checkpoint
+
+Ao verificar contra um checkpoint:
+
+1. Leia o checkpoint no log
+2. Compare o estado atual com o checkpoint:
+ - Arquivos adicionados desde o checkpoint
+ - Arquivos modificados desde o checkpoint
+ - Taxa de testes passando agora vs antes
+ - Cobertura agora vs antes
+
+3. Reporte:
+```
+CHECKPOINT COMPARISON: $NAME
+============================
+Files changed: X
+Tests: +Y passed / -Z failed
+Coverage: +X% / -Y%
+Build: [PASS/FAIL]
+```
+
+## Listar Checkpoints
+
+Mostre todos os checkpoints com:
+- Nome
+- Timestamp
+- Git SHA
+- Status (current, behind, ahead)
+
+## Fluxo
+
+Fluxo típico de checkpoint:
+
+```
+[Start] --> /checkpoint create "feature-start"
+ |
+[Implement] --> /checkpoint create "core-done"
+ |
+[Test] --> /checkpoint verify "core-done"
+ |
+[Refactor] --> /checkpoint create "refactor-done"
+ |
+[PR] --> /checkpoint verify "feature-start"
+```
+
+## Argumentos
+
+$ARGUMENTS:
+- `create <name>` - Criar checkpoint nomeado
+- `verify <name>` - Verificar contra checkpoint nomeado
+- `list` - Mostrar todos os checkpoints
+- `clear` - Remover checkpoints antigos (mantém os últimos 5)
diff --git a/docs/pt-BR/commands/code-review.md b/docs/pt-BR/commands/code-review.md
new file mode 100644
index 000000000..52b9e90d7
--- /dev/null
+++ b/docs/pt-BR/commands/code-review.md
@@ -0,0 +1,40 @@
+# Code Review
+
+Revisão completa de segurança e qualidade das mudanças não commitadas:
+
+1. Obtenha arquivos alterados: git diff --name-only HEAD
+
+2. Para cada arquivo alterado, verifique:
+
+**Problemas de Segurança (CRITICAL):**
+- Credenciais, chaves de API ou tokens hardcoded
+- Vulnerabilidades de SQL injection
+- Vulnerabilidades de XSS
+- Falta de validação de entrada
+- Dependências inseguras
+- Riscos de path traversal
+
+**Qualidade de Código (HIGH):**
+- Funções > 50 linhas
+- Arquivos > 800 linhas
+- Profundidade de aninhamento > 4 níveis
+- Falta de tratamento de erro
+- Statements de console.log
+- Comentários TODO/FIXME
+- Falta de JSDoc para APIs públicas
+
+**Boas Práticas (MEDIUM):**
+- Padrões de mutação (usar imutável no lugar)
+- Uso de emoji em código/comentários
+- Falta de testes para código novo
+- Problemas de acessibilidade (a11y)
+
+3. Gere relatório com:
+ - Severidade: CRITICAL, HIGH, MEDIUM, LOW
+ - Localização no arquivo e números de linha
+ - Descrição do problema
+ - Correção sugerida
+
+4. Bloqueie commit se houver problemas CRITICAL ou HIGH
+
+Nunca aprove código com vulnerabilidades de segurança!
diff --git a/docs/pt-BR/commands/e2e.md b/docs/pt-BR/commands/e2e.md
new file mode 100644
index 000000000..41b77f5dd
--- /dev/null
+++ b/docs/pt-BR/commands/e2e.md
@@ -0,0 +1,365 @@
+---
+description: Gere e rode testes end-to-end com Playwright. Cria jornadas de teste, executa testes, captura screenshots/videos/traces e faz upload de artefatos.
+---
+
+# Comando E2E
+
+Este comando invoca o agente **e2e-runner** para gerar, manter e executar testes end-to-end usando Playwright.
+
+## O Que Este Comando Faz
+
+1. **Gerar Jornadas de Teste** - Cria testes Playwright para fluxos de usuário
+2. **Rodar Testes E2E** - Executa testes em múltiplos navegadores
+3. **Capturar Artefatos** - Screenshots, vídeos, traces em falhas
+4. **Upload de Resultados** - Relatórios HTML e JUnit XML
+5. **Identificar Testes Flaky** - Coloca testes instáveis em quarentena
+
+## Quando Usar
+
+Use `/e2e` quando:
+- Testar jornadas críticas de usuário (login, trading, pagamentos)
+- Verificar fluxos multi-etapa de ponta a ponta
+- Testar interações de UI e navegação
+- Validar integração entre frontend e backend
+- Preparar para deploy em produção
+
+## Como Funciona
+
+O agente e2e-runner vai:
+
+1. **Analisar o fluxo de usuário** e identificar cenários de teste
+2. **Gerar teste Playwright** usando padrão Page Object Model
+3. **Rodar testes** em múltiplos navegadores (Chrome, Firefox, Safari)
+4. **Capturar falhas** com screenshots, vídeos e traces
+5. **Gerar relatório** com resultados e artefatos
+6. **Identificar testes flaky** e recomendar correções
+
+## Exemplo de Uso
+
+```
+User: /e2e Test the market search and view flow
+
+Agent (e2e-runner):
+# E2E Test Generation: Market Search and View Flow
+
+## Test Scenario Identified
+
+**User Journey:** Market Search → View Results → Click Market → View Details
+
+**Test Coverage:**
+1. Navigate to markets page
+2. Perform semantic search
+3. Verify search results
+4. Click on first result
+5. Verify market details page loads
+6. Verify chart renders
+
+## Generated Test Code
+
+```typescript
+// tests/e2e/markets/search-and-view.spec.ts
+import { test, expect } from '@playwright/test'
+import { MarketsPage } from '../../pages/MarketsPage'
+import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
+
+test.describe('Market Search and View Flow', () => {
+ test('user can search markets and view details', async ({ page }) => {
+ // 1. Navigate to markets page
+ const marketsPage = new MarketsPage(page)
+ await marketsPage.goto()
+
+ // Verify page loaded
+ await expect(page).toHaveTitle(/Markets/)
+ await expect(page.locator('h1')).toContainText('Markets')
+
+ // 2. Perform semantic search
+ await marketsPage.searchMarkets('election')
+
+ // Wait for API response
+ await page.waitForResponse(resp =>
+ resp.url().includes('/api/markets/search') && resp.status() === 200
+ )
+
+ // 3. Verify search results
+ const marketCards = marketsPage.marketCards
+ await expect(marketCards.first()).toBeVisible()
+ const resultCount = await marketCards.count()
+ expect(resultCount).toBeGreaterThan(0)
+
+ // Take screenshot of search results
+ await page.screenshot({ path: 'artifacts/search-results.png' })
+
+ // 4. Click on first result
+ const firstMarketTitle = await marketCards.first().textContent()
+ await marketCards.first().click()
+
+ // 5. Verify market details page loads
+ await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
+
+ const detailsPage = new MarketDetailsPage(page)
+ await expect(detailsPage.marketName).toBeVisible()
+ await expect(detailsPage.marketDescription).toBeVisible()
+
+ // 6. Verify chart renders
+ await expect(detailsPage.priceChart).toBeVisible()
+
+ // Verify market name matches
+ const detailsTitle = await detailsPage.marketName.textContent()
+ expect(detailsTitle?.toLowerCase()).toContain(
+ firstMarketTitle?.toLowerCase().substring(0, 20) || ''
+ )
+
+ // Take screenshot of market details
+ await page.screenshot({ path: 'artifacts/market-details.png' })
+ })
+
+ test('search with no results shows empty state', async ({ page }) => {
+ const marketsPage = new MarketsPage(page)
+ await marketsPage.goto()
+
+ // Search for non-existent market
+ await marketsPage.searchMarkets('xyznonexistentmarket123456')
+
+ // Verify empty state
+ await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+ await expect(page.locator('[data-testid="no-results"]')).toContainText(
+ /no.*results|no.*markets/i
+ )
+
+ const marketCount = await marketsPage.marketCards.count()
+ expect(marketCount).toBe(0)
+ })
+
+ test('can clear search and see all markets again', async ({ page }) => {
+ const marketsPage = new MarketsPage(page)
+ await marketsPage.goto()
+
+ // Initial market count
+ const initialCount = await marketsPage.marketCards.count()
+
+ // Perform search
+ await marketsPage.searchMarkets('trump')
+ await page.waitForLoadState('networkidle')
+
+ // Verify filtered results
+ const filteredCount = await marketsPage.marketCards.count()
+ expect(filteredCount).toBeLessThan(initialCount)
+
+ // Clear search
+ await marketsPage.searchInput.clear()
+ await page.waitForLoadState('networkidle')
+
+ // Verify all markets shown again
+ const finalCount = await marketsPage.marketCards.count()
+ expect(finalCount).toBe(initialCount)
+ })
+})
+```
+
+## Rodando os Testes
+
+```bash
+# Run the generated test
+npx playwright test tests/e2e/markets/search-and-view.spec.ts
+
+Running 3 tests using 3 workers
+
+ ✓ [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
+ ✓ [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
+ ✓ [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
+
+ 3 passed (9.1s)
+
+Artifacts generated:
+- artifacts/search-results.png
+- artifacts/market-details.png
+- playwright-report/index.html
+```
+
+## Relatório de Teste
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║ E2E Test Results ║
+╠══════════════════════════════════════════════════════════════╣
+║ Status: ✅ ALL TESTS PASSED ║
+║ Total: 3 tests ║
+║ Passed: 3 (100%) ║
+║ Failed: 0 ║
+║ Flaky: 0 ║
+║ Duration: 9.1s ║
+╚══════════════════════════════════════════════════════════════╝
+
+Artifacts:
+📸 Screenshots: 2 files
+📹 Videos: 0 files (only on failure)
+🔍 Traces: 0 files (only on failure)
+📊 HTML Report: playwright-report/index.html
+
+View report: npx playwright show-report
+```
+
+✅ E2E test suite ready for CI/CD integration!
+```
+
+## Artefatos de Teste
+
+Quando os testes rodam, os seguintes artefatos são capturados:
+
+**Em Todos os Testes:**
+- Relatório HTML com timeline e resultados
+- JUnit XML para integração com CI
+
+**Somente em Falha:**
+- Screenshot do estado de falha
+- Gravação em vídeo do teste
+- Arquivo de trace para debug (replay passo a passo)
+- Logs de rede
+- Logs de console
+
+## Visualizando Artefatos
+
+```bash
+# View HTML report in browser
+npx playwright show-report
+
+# View specific trace file
+npx playwright show-trace artifacts/trace-abc123.zip
+
+# Screenshots are saved in artifacts/ directory
+open artifacts/search-results.png
+```
+
+## Detecção de Teste Flaky
+
+Se um teste falhar de forma intermitente:
+
+```
+⚠️ FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
+
+Test passed 7/10 runs (70% pass rate)
+
+Common failure:
+"Timeout waiting for element '[data-testid="confirm-btn"]'"
+
+Recommended fixes:
+1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]')
+2. Increase timeout: { timeout: 10000 }
+3. Check for race conditions in component
+4. Verify element is not hidden by animation
+
+Quarantine recommendation: Mark as test.fixme() until fixed
+```
+
+## Configuração de Navegador
+
+Os testes rodam em múltiplos navegadores por padrão:
+- ✅ Chromium (Desktop Chrome)
+- ✅ Firefox (Desktop)
+- ✅ WebKit (Desktop Safari)
+- ✅ Mobile Chrome (optional)
+
+Configure em `playwright.config.ts` para ajustar navegadores.
+
+## Integração CI/CD
+
+Adicione ao seu pipeline de CI:
+
+```yaml
+# .github/workflows/e2e.yml
+- name: Install Playwright
+ run: npx playwright install --with-deps
+
+- name: Run E2E tests
+ run: npx playwright test
+
+- name: Upload artifacts
+ if: always()
+ uses: actions/upload-artifact@v3
+ with:
+ name: playwright-report
+ path: playwright-report/
+```
+
+## Fluxos Críticos Específicos do PMX
+
+Para PMX, priorize estes testes E2E:
+
+**🔴 CRITICAL (Must Always Pass):**
+1. User can connect wallet
+2. User can browse markets
+3. User can search markets (semantic search)
+4. User can view market details
+5. User can place trade (with test funds)
+6. Market resolves correctly
+7. User can withdraw funds
+
+**🟡 IMPORTANT:**
+1. Market creation flow
+2. User profile updates
+3. Real-time price updates
+4. Chart rendering
+5. Filter and sort markets
+6. Mobile responsive layout
+
+## Boas Práticas
+
+**DO:**
+- ✅ Use Page Object Model para manutenção
+- ✅ Use atributos data-testid para seletores
+- ✅ Aguarde respostas de API, não timeouts arbitrários
+- ✅ Teste jornadas críticas de usuário end-to-end
+- ✅ Rode testes antes de mergear em main
+- ✅ Revise artefatos quando testes falharem
+
+**DON'T:**
+- ❌ Use seletores frágeis (classes CSS podem mudar)
+- ❌ Teste detalhes de implementação
+- ❌ Rode testes contra produção
+- ❌ Ignore testes flaky
+- ❌ Pule revisão de artefatos em falhas
+- ❌ Teste todo edge case com E2E (use testes unitários)
+
+## Notas Importantes
+
+**CRITICAL para PMX:**
+- Testes E2E envolvendo dinheiro real DEVEM rodar apenas em testnet/staging
+- Nunca rode testes de trading em produção
+- Defina `test.skip(process.env.NODE_ENV === 'production')` para testes financeiros
+- Use carteiras de teste com fundos de teste pequenos apenas
+
+## Integração com Outros Comandos
+
+- Use `/plan` para identificar jornadas críticas a testar
+- Use `/tdd` para testes unitários (mais rápidos e granulares)
+- Use `/e2e` para integração e jornadas de usuário
+- Use `/code-review` para verificar qualidade dos testes
+
+## Agentes Relacionados
+
+Este comando invoca o agente `e2e-runner` fornecido pelo ECC.
+
+Para instalações manuais, o arquivo fonte fica em:
+`agents/e2e-runner.md`
+
+## Comandos Rápidos
+
+```bash
+# Run all E2E tests
+npx playwright test
+
+# Run specific test file
+npx playwright test tests/e2e/markets/search.spec.ts
+
+# Run in headed mode (see browser)
+npx playwright test --headed
+
+# Debug test
+npx playwright test --debug
+
+# Generate test code
+npx playwright codegen http://localhost:3000
+
+# View report
+npx playwright show-report
+```
diff --git a/docs/pt-BR/commands/eval.md b/docs/pt-BR/commands/eval.md
new file mode 100644
index 000000000..438efda59
--- /dev/null
+++ b/docs/pt-BR/commands/eval.md
@@ -0,0 +1,120 @@
+# Comando Eval
+
+Gerencie o fluxo de desenvolvimento orientado por evals.
+
+## Uso
+
+`/eval [define|check|report|list] [feature-name]`
+
+## Definir Evals
+
+`/eval define feature-name`
+
+Crie uma nova definição de eval:
+
+1. Crie `.claude/evals/feature-name.md` com o template:
+
+```markdown
+## EVAL: feature-name
+Created: $(date)
+
+### Capability Evals
+- [ ] [Description of capability 1]
+- [ ] [Description of capability 2]
+
+### Regression Evals
+- [ ] [Existing behavior 1 still works]
+- [ ] [Existing behavior 2 still works]
+
+### Success Criteria
+- pass@3 > 90% for capability evals
+- pass^3 = 100% for regression evals
+```
+
+2. Peça ao usuário para preencher os critérios específicos
+
+## Verificar Evals
+
+`/eval check feature-name`
+
+Rode evals para uma feature:
+
+1. Leia a definição de eval em `.claude/evals/feature-name.md`
+2. Para cada eval de capability:
+ - Tente verificar o critério
+ - Registre PASS/FAIL
+ - Salve tentativa em `.claude/evals/feature-name.log`
+3. Para cada eval de regressão:
+ - Rode os testes relevantes
+ - Compare com baseline
+ - Registre PASS/FAIL
+4. Reporte status atual:
+
+```
+EVAL CHECK: feature-name
+========================
+Capability: X/Y passing
+Regression: X/Y passing
+Status: IN PROGRESS / READY
+```
+
+## Relatório de Evals
+
+`/eval report feature-name`
+
+Gere relatório completo de eval:
+
+```
+EVAL REPORT: feature-name
+=========================
+Generated: $(date)
+
+CAPABILITY EVALS
+----------------
+[eval-1]: PASS (pass@1)
+[eval-2]: PASS (pass@2) - required retry
+[eval-3]: FAIL - see notes
+
+REGRESSION EVALS
+----------------
+[test-1]: PASS
+[test-2]: PASS
+[test-3]: PASS
+
+METRICS
+-------
+Capability pass@1: 67%
+Capability pass@3: 100%
+Regression pass^3: 100%
+
+NOTES
+-----
+[Any issues, edge cases, or observations]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## Listar Evals
+
+`/eval list`
+
+Mostre todas as definições de eval:
+
+```
+EVAL DEFINITIONS
+================
+feature-auth [3/5 passing] IN PROGRESS
+feature-search [5/5 passing] READY
+feature-export [0/4 passing] NOT STARTED
+```
+
+## Argumentos
+
+$ARGUMENTS:
+- `define <name>` - Criar nova definição de eval
+- `check <name>` - Rodar e verificar evals
+- `report <name>` - Gerar relatório completo
+- `list` - Mostrar todos os evals
+- `clean` - Remover logs antigos de eval (mantém as últimas 10 execuções)
diff --git a/docs/pt-BR/commands/go-build.md b/docs/pt-BR/commands/go-build.md
new file mode 100644
index 000000000..2e620bf99
--- /dev/null
+++ b/docs/pt-BR/commands/go-build.md
@@ -0,0 +1,183 @@
+---
+description: Corrija erros de build em Go, avisos de go vet e problemas de lint incrementalmente. Invoca o agente go-build-resolver para correções mínimas e cirúrgicas.
+---
+
+# Build e Correção Go
+
+Este comando invoca o agente **go-build-resolver** para corrigir erros de build Go incrementalmente com mudanças mínimas.
+
+## O Que Este Comando Faz
+
+1. **Rodar Diagnósticos**: Executa `go build`, `go vet`, `staticcheck`
+2. **Parsear Erros**: Agrupa por arquivo e ordena por severidade
+3. **Corrigir Incrementalmente**: Um erro por vez
+4. **Verificar Cada Correção**: Roda build de novo após cada mudança
+5. **Reportar Resumo**: Mostra o que foi corrigido e o que resta
+
+## Quando Usar
+
+Use `/go-build` quando:
+- `go build ./...` falhar com erros
+- `go vet ./...` reportar problemas
+- `golangci-lint run` mostrar avisos
+- Dependências do módulo estiverem quebradas
+- Após puxar mudanças que quebraram o build
+
+## Comandos de Diagnóstico Executados
+
+```bash
+# Primary build check
+go build ./...
+
+# Static analysis
+go vet ./...
+
+# Extended linting (if available)
+staticcheck ./...
+golangci-lint run
+
+# Module issues
+go mod verify
+go mod tidy -v
+```
+
+## Exemplo de Sessão
+
+```text
+User: /go-build
+
+Agent:
+# Go Build Resolution
+
+## Initial Diagnostics
+
+```bash
+$ go build ./...
+internal/service/user.go:25:15: undefined: UserRepository
+internal/handler/api.go:42:9: cannot use x (type string) as type int
+internal/handler/api.go:58:2: missing return at end of function
+```
+
+Errors found: 3
+
+## Fix 1: Undefined Identifier
+
+File: internal/service/user.go:25
+Error: undefined: UserRepository
+Cause: Missing import
+
+```go
+// Added import
+import "project/internal/repository"
+
+// Changed
+var repo UserRepository
+// To
+var repo repository.UserRepository
+```
+
+```bash
+$ go build ./...
+# 2 errors remaining
+```
+
+## Fix 2: Type Mismatch
+
+File: internal/handler/api.go:42
+Error: cannot use x (type string) as type int
+
+```go
+// Changed
+count := params.Get("count")
+// To
+countStr := params.Get("count")
+count, _ := strconv.Atoi(countStr)
+```
+
+```bash
+$ go build ./...
+# 1 error remaining
+```
+
+## Fix 3: Missing Return
+
+File: internal/handler/api.go:58
+Error: missing return at end of function
+
+```go
+func GetUser(id string) (*User, error) {
+ if id == "" {
+ return nil, ErrInvalidID
+ }
+ user := findUser(id)
+ // Added missing return
+ return user, nil
+}
+```
+
+```bash
+$ go build ./...
+# Build successful!
+```
+
+## Final Verification
+
+```bash
+$ go vet ./...
+# No issues
+
+$ go test ./...
+ok project/internal/service 0.015s
+ok project/internal/handler 0.023s
+```
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Build errors fixed | 3 |
+| Vet warnings fixed | 0 |
+| Files modified | 2 |
+| Remaining issues | 0 |
+
+Build Status: ✅ SUCCESS
+```
+
+## Erros Comuns Corrigidos
+
+| Error | Typical Fix |
+|-------|-------------|
+| `undefined: X` | Add import or fix typo |
+| `cannot use X as Y` | Type conversion or fix assignment |
+| `missing return` | Add return statement |
+| `X does not implement Y` | Add missing method |
+| `import cycle` | Restructure packages |
+| `declared but not used` | Remove or use variable |
+| `cannot find package` | `go get` or `go mod tidy` |
+
+## Estratégia de Correção
+
+1. **Erros de build primeiro** - O código precisa compilar
+2. **Avisos do vet depois** - Corrigir construções suspeitas
+3. **Avisos de lint por último** - Estilo e boas práticas
+4. **Uma correção por vez** - Verificar cada mudança
+5. **Mudanças mínimas** - Não refatorar, apenas corrigir
+
+## Condições de Parada
+
+O agente vai parar e reportar se:
+- O mesmo erro persistir após 3 tentativas
+- A correção introduzir mais erros
+- Exigir mudanças arquiteturais
+- Faltarem dependências externas
+
+## Comandos Relacionados
+
+- `/go-test` - Rode testes após o build passar
+- `/go-review` - Revise qualidade do código
+- `/verify` - Loop completo de verificação
+
+## Relacionado
+
+- Agent: `agents/go-build-resolver.md`
+- Skill: `skills/golang-patterns/`
diff --git a/docs/pt-BR/commands/go-review.md b/docs/pt-BR/commands/go-review.md
new file mode 100644
index 000000000..fb8e10d8e
--- /dev/null
+++ b/docs/pt-BR/commands/go-review.md
@@ -0,0 +1,148 @@
+---
+description: Revisão completa de código Go para padrões idiomáticos, segurança de concorrência, tratamento de erro e segurança. Invoca o agente go-reviewer.
+---
+
+# Code Review Go
+
+Este comando invoca o agente **go-reviewer** para revisão abrangente e específica de Go.
+
+## O Que Este Comando Faz
+
+1. **Identificar Mudanças Go**: Encontra arquivos `.go` modificados via `git diff`
+2. **Rodar Análise Estática**: Executa `go vet`, `staticcheck` e `golangci-lint`
+3. **Varredura de Segurança**: Verifica SQL injection, command injection e race conditions
+4. **Revisão de Concorrência**: Analisa segurança de goroutines, uso de channels e padrões com mutex
+5. **Checagem de Go Idiomático**: Verifica se o código segue convenções e boas práticas de Go
+6. **Gerar Relatório**: Categoriza problemas por severidade
+
+## Quando Usar
+
+Use `/go-review` quando:
+- Após escrever ou modificar código Go
+- Antes de commitar mudanças Go
+- Ao revisar pull requests com código Go
+- Ao entrar em um novo codebase Go
+- Ao aprender padrões idiomáticos Go
+
+## Categorias de Revisão
+
+### CRITICAL (Obrigatório Corrigir)
+- Vulnerabilidades de SQL/Command injection
+- Race conditions sem sincronização
+- Vazamento de goroutine
+- Credenciais hardcoded
+- Uso inseguro de ponteiros
+- Erros ignorados em caminhos críticos
+
+### HIGH (Deve Corrigir)
+- Falta de wrapping de erro com contexto
+- Panic em vez de retorno de erro
+- Context não propagado
+- Canais não bufferizados causando deadlock
+- Erros de interface não satisfeita
+- Falta de proteção com mutex
+
+### MEDIUM (Considere)
+- Padrões não idiomáticos
+- Falta de comentários godoc em exports
+- Concatenação de string ineficiente
+- Slice sem pré-alocação
+- Table-driven tests não usados
+
+## Checagens Automáticas Executadas
+
+```bash
+# Static analysis
+go vet ./...
+
+# Advanced checks (if installed)
+staticcheck ./...
+golangci-lint run
+
+# Race detection
+go build -race ./...
+
+# Security vulnerabilities
+govulncheck ./...
+```
+
+## Exemplo de Uso
+
+```text
+User: /go-review
+
+Agent:
+# Go Code Review Report
+
+## Files Reviewed
+- internal/handler/user.go (modified)
+- internal/service/auth.go (modified)
+
+## Static Analysis Results
+✓ go vet: No issues
+✓ staticcheck: No issues
+
+## Issues Found
+
+[CRITICAL] Race Condition
+File: internal/service/auth.go:45
+Issue: Shared map accessed without synchronization
+```go
+var cache = map[string]*Session{} // Concurrent access!
+
+func GetSession(id string) *Session {
+ return cache[id] // Race condition
+}
+```
+Fix: Use sync.RWMutex or sync.Map
+```go
+var (
+ cache = map[string]*Session{}
+ cacheMu sync.RWMutex
+)
+
+func GetSession(id string) *Session {
+ cacheMu.RLock()
+ defer cacheMu.RUnlock()
+ return cache[id]
+}
+```
+
+[HIGH] Missing Error Context
+File: internal/handler/user.go:28
+Issue: Error returned without context
+```go
+return err // No context
+```
+Fix: Wrap with context
+```go
+return fmt.Errorf("get user %s: %w", userID, err)
+```
+
+## Summary
+- CRITICAL: 1
+- HIGH: 1
+- MEDIUM: 0
+
+Recommendation: ❌ Block merge until CRITICAL issue is fixed
+```
+
+## Critérios de Aprovação
+
+| Status | Condition |
+|--------|-----------|
+| ✅ Approve | No CRITICAL or HIGH issues |
+| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
+| ❌ Block | CRITICAL or HIGH issues found |
+
+## Integração com Outros Comandos
+
+- Use `/go-test` primeiro para garantir que os testes passam
+- Use `/go-build` se houver erros de build
+- Use `/go-review` antes de commitar
+- Use `/code-review` para preocupações não específicas de Go
+
+## Relacionado
+
+- Agent: `agents/go-reviewer.md`
+- Skills: `skills/golang-patterns/`, `skills/golang-testing/`
diff --git a/docs/pt-BR/commands/go-test.md b/docs/pt-BR/commands/go-test.md
new file mode 100644
index 000000000..d608c8257
--- /dev/null
+++ b/docs/pt-BR/commands/go-test.md
@@ -0,0 +1,268 @@
+---
+description: Impõe fluxo de TDD para Go. Escreva table-driven tests primeiro e depois implemente. Verifique cobertura de 80%+ com go test -cover.
+---
+
+# Comando TDD Go
+
+Este comando impõe a metodologia de desenvolvimento orientado a testes para código Go usando padrões idiomáticos de teste em Go.
+
+## O Que Este Comando Faz
+
+1. **Definir Tipos/Interfaces**: Estrutura assinaturas de função primeiro
+2. **Escrever Table-Driven Tests**: Criar casos de teste abrangentes (RED)
+3. **Rodar Testes**: Verificar que os testes falham pelo motivo certo
+4. **Implementar Código**: Escrever código mínimo para passar (GREEN)
+5. **Refatorar**: Melhorar mantendo testes verdes
+6. **Checar Cobertura**: Garantir 80%+ de cobertura
+
+## Quando Usar
+
+Use `/go-test` quando:
+- Implementar novas funções Go
+- Adicionar cobertura de testes a código existente
+- Corrigir bugs (escreva primeiro o teste que falha)
+- Construir lógica de negócio crítica
+- Aprender fluxo TDD em Go
+
+## Ciclo TDD
+
+```
+RED → Write failing table-driven test
+GREEN → Implement minimal code to pass
+REFACTOR → Improve code, tests stay green
+REPEAT → Next test case
+```
+
+## Exemplo de Sessão
+
+````
+User: /go-test I need a function to validate email addresses
+
+Agent:
+# TDD Session: Email Validator
+
+## Step 1: Define Interface
+
+```go
+// validator/email.go
+package validator
+
+// ValidateEmail checks if the given string is a valid email address.
+// Returns nil if valid, error describing the issue otherwise.
+func ValidateEmail(email string) error {
+ panic("not implemented")
+}
+```
+
+## Step 2: Write Table-Driven Tests (RED)
+
+```go
+// validator/email_test.go
+package validator
+
+import (
+ "testing"
+)
+
+func TestValidateEmail(t *testing.T) {
+ tests := []struct {
+ name string
+ email string
+ wantErr bool
+ }{
+ // Valid emails
+ {"simple email", "[email protected]", false},
+ {"with subdomain", "[email protected]", false},
+ {"with plus", "[email protected]", false},
+ {"with dots", "[email protected]", false},
+
+ // Invalid emails
+ {"empty string", "", true},
+ {"no at sign", "userexample.com", true},
+ {"no domain", "user@", true},
+ {"no local part", "@example.com", true},
+ {"double at", "user@@example.com", true},
+ {"spaces", "user @example.com", true},
+ {"no tld", "user@example", true},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ err := ValidateEmail(tt.email)
+ if tt.wantErr && err == nil {
+ t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
+ }
+ if !tt.wantErr && err != nil {
+ t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
+ }
+ })
+ }
+}
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+$ go test ./validator/...
+
+--- FAIL: TestValidateEmail (0.00s)
+ --- FAIL: TestValidateEmail/simple_email (0.00s)
+ panic: not implemented
+
+FAIL
+```
+
+✓ Tests fail as expected (panic).
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```go
+// validator/email.go
+package validator
+
+import (
+ "errors"
+ "regexp"
+)
+
+var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
+
+var (
+ ErrEmailEmpty = errors.New("email cannot be empty")
+ ErrEmailInvalid = errors.New("email format is invalid")
+)
+
+func ValidateEmail(email string) error {
+ if email == "" {
+ return ErrEmailEmpty
+ }
+ if !emailRegex.MatchString(email) {
+ return ErrEmailInvalid
+ }
+ return nil
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+$ go test ./validator/...
+
+PASS
+ok project/validator 0.003s
+```
+
+✓ All tests passing!
+
+## Step 6: Check Coverage
+
+```bash
+$ go test -cover ./validator/...
+
+PASS
+coverage: 100.0% of statements
+ok project/validator 0.003s
+```
+
+✓ Coverage: 100%
+
+## TDD Complete!
+````
+
+## Padrões de Teste
+
+### Table-Driven Tests
+```go
+tests := []struct {
+ name string
+ input InputType
+ want OutputType
+ wantErr bool
+}{
+ {"case 1", input1, want1, false},
+ {"case 2", input2, want2, true},
+}
+
+for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got, err := Function(tt.input)
+ // assertions
+ })
+}
+```
+
+### Testes Paralelos
+```go
+for _, tt := range tests {
+ tt := tt // Capture
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ // test body
+ })
+}
+```
+
+### Helpers de Teste
+```go
+func setupTestDB(t *testing.T) *sql.DB {
+ t.Helper()
+ db := createDB()
+ t.Cleanup(func() { db.Close() })
+ return db
+}
+```
+
+## Comandos de Cobertura
+
+```bash
+# Basic coverage
+go test -cover ./...
+
+# Coverage profile
+go test -coverprofile=coverage.out ./...
+
+# View in browser
+go tool cover -html=coverage.out
+
+# Coverage by function
+go tool cover -func=coverage.out
+
+# With race detection
+go test -race -cover ./...
+```
+
+## Metas de Cobertura
+
+| Code Type | Target |
+|-----------|--------|
+| Critical business logic | 100% |
+| Public APIs | 90%+ |
+| General code | 80%+ |
+| Generated code | Exclude |
+
+## Boas Práticas de TDD
+
+**DO:**
+- Escreva teste PRIMEIRO, antes de qualquer implementação
+- Rode testes após cada mudança
+- Use table-driven tests para cobertura abrangente
+- Teste comportamento, não detalhes de implementação
+- Inclua casos de borda (empty, nil, max values)
+
+**DON'T:**
+- Escrever implementação antes dos testes
+- Pular a fase RED
+- Testar funções privadas diretamente
+- Usar `time.Sleep` em testes
+- Ignorar testes flaky
+
+## Comandos Relacionados
+
+- `/go-build` - Corrigir erros de build
+- `/go-review` - Revisar código após implementação
+- `/verify` - Rodar loop completo de verificação
+
+## Relacionado
+
+- Skill: `skills/golang-testing/`
+- Skill: `skills/tdd-workflow/`
diff --git a/docs/pt-BR/commands/learn.md b/docs/pt-BR/commands/learn.md
new file mode 100644
index 000000000..6c6154d23
--- /dev/null
+++ b/docs/pt-BR/commands/learn.md
@@ -0,0 +1,70 @@
+# /learn - Extrair Padrões Reutilizáveis
+
+Analise a sessão atual e extraia padrões que valem ser salvos como skills.
+
+## Trigger
+
+Rode `/learn` em qualquer ponto da sessão quando você tiver resolvido um problema não trivial.
+
+## O Que Extrair
+
+Procure por:
+
+1. **Padrões de Resolução de Erro**
+ - Qual erro ocorreu?
+ - Qual foi a causa raiz?
+ - O que corrigiu?
+ - Isso é reutilizável para erros semelhantes?
+
+2. **Técnicas de Debug**
+ - Passos de debug não óbvios
+ - Combinações de ferramentas que funcionaram
+ - Padrões de diagnóstico
+
+3. **Workarounds**
+ - Quirks de bibliotecas
+ - Limitações de API
+ - Correções específicas de versão
+
+4. **Padrões Específicos do Projeto**
+ - Convenções de codebase descobertas
+ - Decisões de arquitetura tomadas
+ - Padrões de integração
+
+## Formato de Saída
+
+Crie um arquivo de skill em `~/.claude/skills/learned/[pattern-name].md`:
+
+```markdown
+# [Descriptive Pattern Name]
+
+**Extracted:** [Date]
+**Context:** [Brief description of when this applies]
+
+## Problem
+[What problem this solves - be specific]
+
+## Solution
+[The pattern/technique/workaround]
+
+## Example
+[Code example if applicable]
+
+## When to Use
+[Trigger conditions - what should activate this skill]
+```
+
+## Processo
+
+1. Revise a sessão para identificar padrões extraíveis
+2. Identifique o insight mais valioso/reutilizável
+3. Esboce o arquivo de skill
+4. Peça confirmação do usuário antes de salvar
+5. Salve em `~/.claude/skills/learned/`
+
+## Notas
+
+- Não extraia correções triviais (typos, erros simples de sintaxe)
+- Não extraia problemas de uso único (indisponibilidade específica de API etc.)
+- Foque em padrões que vão economizar tempo em sessões futuras
+- Mantenha skills focadas - um padrão por skill
diff --git a/docs/pt-BR/commands/orchestrate.md b/docs/pt-BR/commands/orchestrate.md
new file mode 100644
index 000000000..b192321ca
--- /dev/null
+++ b/docs/pt-BR/commands/orchestrate.md
@@ -0,0 +1,231 @@
+---
+description: Orientação de orquestração sequencial e tmux/worktree para fluxos multiagente.
+---
+
+# Comando Orchestrate
+
+Fluxo sequencial de agentes para tarefas complexas.
+
+## Uso
+
+`/orchestrate [workflow-type] [task-description]`
+
+## Tipos de Workflow
+
+### feature
+Workflow completo de implementação de feature:
+```
+planner -> tdd-guide -> code-reviewer -> security-reviewer
+```
+
+### bugfix
+Workflow de investigação e correção de bug:
+```
+planner -> tdd-guide -> code-reviewer
+```
+
+### refactor
+Workflow de refatoração segura:
+```
+architect -> code-reviewer -> tdd-guide
+```
+
+### security
+Revisão focada em segurança:
+```
+security-reviewer -> code-reviewer -> architect
+```
+
+## Padrão de Execução
+
+Para cada agente no workflow:
+
+1. **Invoque o agente** com contexto do agente anterior
+2. **Colete saída** como documento estruturado de handoff
+3. **Passe para o próximo agente** na cadeia
+4. **Agregue resultados** em um relatório final
+
+## Formato do Documento de Handoff
+
+Entre agentes, crie um documento de handoff:
+
+```markdown
+## HANDOFF: [previous-agent] -> [next-agent]
+
+### Context
+[Summary of what was done]
+
+### Findings
+[Key discoveries or decisions]
+
+### Files Modified
+[List of files touched]
+
+### Open Questions
+[Unresolved items for next agent]
+
+### Recommendations
+[Suggested next steps]
+```
+
+## Exemplo: Workflow de Feature
+
+```
+/orchestrate feature "Add user authentication"
+```
+
+Executa:
+
+1. **Planner Agent**
+ - Analisa requisitos
+ - Cria plano de implementação
+ - Identifica dependências
+ - Saída: `HANDOFF: planner -> tdd-guide`
+
+2. **TDD Guide Agent**
+ - Lê handoff do planner
+ - Escreve testes primeiro
+ - Implementa para passar testes
+ - Saída: `HANDOFF: tdd-guide -> code-reviewer`
+
+3. **Code Reviewer Agent**
+ - Revisa implementação
+ - Verifica problemas
+ - Sugere melhorias
+ - Saída: `HANDOFF: code-reviewer -> security-reviewer`
+
+4. **Security Reviewer Agent**
+ - Auditoria de segurança
+ - Verificação de vulnerabilidades
+ - Aprovação final
+ - Saída: Relatório Final
+
+## Formato do Relatório Final
+
+```
+ORCHESTRATION REPORT
+====================
+Workflow: feature
+Task: Add user authentication
+Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
+
+SUMMARY
+-------
+[One paragraph summary]
+
+AGENT OUTPUTS
+-------------
+Planner: [summary]
+TDD Guide: [summary]
+Code Reviewer: [summary]
+Security Reviewer: [summary]
+
+FILES CHANGED
+-------------
+[List all files modified]
+
+TEST RESULTS
+------------
+[Test pass/fail summary]
+
+SECURITY STATUS
+---------------
+[Security findings]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## Execução Paralela
+
+Para verificações independentes, rode agentes em paralelo:
+
+```markdown
+### Parallel Phase
+Run simultaneously:
+- code-reviewer (quality)
+- security-reviewer (security)
+- architect (design)
+
+### Merge Results
+Combine outputs into single report
+```
+
+Para workers externos em tmux panes com git worktrees separados, use `node scripts/orchestrate-worktrees.js plan.json --execute`. O padrão embutido de orquestração permanece no processo atual; o helper é para sessões longas ou cross-harness.
+
+Quando os workers precisarem enxergar arquivos locais sujos ou não rastreados do checkout principal, adicione `seedPaths` ao arquivo de plano. O ECC faz overlay apenas desses caminhos selecionados em cada worktree do worker após `git worktree add`, mantendo o branch isolado e ainda expondo scripts, planos ou docs em andamento.
+
+```json
+{
+ "sessionName": "workflow-e2e",
+ "seedPaths": [
+ "scripts/orchestrate-worktrees.js",
+ "scripts/lib/tmux-worktree-orchestrator.js",
+ ".claude/plan/workflow-e2e-test.json"
+ ],
+ "workers": [
+ { "name": "docs", "task": "Update orchestration docs." }
+ ]
+}
+```
+
+Para exportar um snapshot do control plane para uma sessão tmux/worktree ao vivo, rode:
+
+```bash
+node scripts/orchestration-status.js .claude/plan/workflow-visual-proof.json
+```
+
+O snapshot inclui atividade da sessão, metadados de pane do tmux, estado dos workers, objetivos, overlays semeados e resumos recentes de handoff em formato JSON.
+
+## Handoff de Command Center do Operador
+
+Quando o workflow atravessar múltiplas sessões, worktrees ou panes tmux, acrescente um bloco de control plane ao handoff final:
+
+```markdown
+CONTROL PLANE
+-------------
+Sessions:
+- active session ID or alias
+- branch + worktree path for each active worker
+- tmux pane or detached session name when applicable
+
+Diffs:
+- git status summary
+- git diff --stat for touched files
+- merge/conflict risk notes
+
+Approvals:
+- pending user approvals
+- blocked steps awaiting confirmation
+
+Telemetry:
+- last activity timestamp or idle signal
+- estimated token or cost drift
+- policy events raised by hooks or reviewers
+```
+
+Isso mantém planner, implementador, revisor e loop workers legíveis pela superfície de operação.
+
+## Argumentos
+
+$ARGUMENTS:
+- `feature <description>` - Workflow completo de feature
+- `bugfix <description>` - Workflow de correção de bug
+- `refactor <description>` - Workflow de refatoração
+- `security <description>` - Workflow de revisão de segurança
+- `custom <agents> <description>` - Sequência customizada de agentes
+
+## Exemplo de Workflow Customizado
+
+```
+/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
+```
+
+## Dicas
+
+1. **Comece com planner** para features complexas
+2. **Sempre inclua code-reviewer** antes do merge
+3. **Use security-reviewer** para auth/pagamento/PII
+4. **Mantenha handoffs concisos** - foque no que o próximo agente precisa
+5. **Rode verificação** entre agentes quando necessário
diff --git a/docs/pt-BR/commands/plan.md b/docs/pt-BR/commands/plan.md
new file mode 100644
index 000000000..e21e2b4d7
--- /dev/null
+++ b/docs/pt-BR/commands/plan.md
@@ -0,0 +1,115 @@
+---
+description: Reafirme requisitos, avalie riscos e crie plano de implementação passo a passo. ESPERE confirmação do usuário ANTES de tocar em qualquer código.
+---
+
+# Comando Plan
+
+Este comando invoca o agente **planner** para criar um plano abrangente de implementação antes de escrever qualquer código.
+
+## O Que Este Comando Faz
+
+1. **Reafirmar Requisitos** - Esclarecer o que precisa ser construído
+2. **Identificar Riscos** - Levantar problemas e bloqueios potenciais
+3. **Criar Plano em Etapas** - Quebrar implementação em fases
+4. **Aguardar Confirmação** - DEVE receber aprovação do usuário antes de prosseguir
+
+## Quando Usar
+
+Use `/plan` quando:
+- Estiver iniciando uma nova feature
+- For fazer mudanças arquiteturais significativas
+- Estiver trabalhando em refatoração complexa
+- Múltiplos arquivos/componentes serão afetados
+- Requisitos estiverem pouco claros ou ambíguos
+
+## Como Funciona
+
+O agente planner vai:
+
+1. **Analisar o pedido** e reafirmar os requisitos de forma clara
+2. **Quebrar em fases** com etapas específicas e acionáveis
+3. **Identificar dependências** entre componentes
+4. **Avaliar riscos** e possíveis bloqueios
+5. **Estimar complexidade** (High/Medium/Low)
+6. **Apresentar o plano** e AGUARDAR sua confirmação explícita
+
+## Exemplo de Uso
+
+```
+User: /plan I need to add real-time notifications when markets resolve
+
+Agent (planner):
+# Implementation Plan: Real-Time Market Resolution Notifications
+
+## Requirements Restatement
+- Send notifications to users when markets they're watching resolve
+- Support multiple notification channels (in-app, email, webhook)
+- Ensure notifications are delivered reliably
+- Include market outcome and user's position result
+
+## Implementation Phases
+
+### Phase 1: Database Schema
+- Add notifications table with columns: id, user_id, market_id, type, status, created_at
+- Add user_notification_preferences table for channel preferences
+- Create indexes on user_id and market_id for performance
+
+### Phase 2: Notification Service
+- Create notification service in lib/notifications.ts
+- Implement notification queue using BullMQ/Redis
+- Add retry logic for failed deliveries
+- Create notification templates
+
+### Phase 3: Integration Points
+- Hook into market resolution logic (when status changes to "resolved")
+- Query all users with positions in market
+- Enqueue notifications for each user
+
+### Phase 4: Frontend Components
+- Create NotificationBell component in header
+- Add NotificationList modal
+- Implement real-time updates via Supabase subscriptions
+- Add notification preferences page
+
+## Dependencies
+- Redis (for queue)
+- Email service (SendGrid/Resend)
+- Supabase real-time subscriptions
+
+## Risks
+- HIGH: Email deliverability (SPF/DKIM required)
+- MEDIUM: Performance with 1000+ users per market
+- MEDIUM: Notification spam if markets resolve frequently
+- LOW: Real-time subscription overhead
+
+## Estimated Complexity: MEDIUM
+- Backend: 4-6 hours
+- Frontend: 3-4 hours
+- Testing: 2-3 hours
+- Total: 9-13 hours
+
+**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)
+```
+
+## Notas Importantes
+
+**CRITICAL**: O agente planner **NÃO** vai escrever código até você confirmar explicitamente o plano com "yes", "proceed" ou resposta afirmativa similar.
+
+Se quiser mudanças, responda com:
+- "modify: [your changes]"
+- "different approach: [alternative]"
+- "skip phase 2 and do phase 3 first"
+
+## Integração com Outros Comandos
+
+Após planejar:
+- Use `/tdd` para implementar com test-driven development
+- Use `/build-fix` se ocorrerem erros de build
+- Use `/code-review` para revisar a implementação concluída
+
+## Agentes Relacionados
+
+Este comando invoca o agente `planner` fornecido pelo ECC.
+
+Para instalações manuais, o arquivo fonte fica em:
+`agents/planner.md`
diff --git a/docs/pt-BR/commands/refactor-clean.md b/docs/pt-BR/commands/refactor-clean.md
new file mode 100644
index 000000000..cf8573d9a
--- /dev/null
+++ b/docs/pt-BR/commands/refactor-clean.md
@@ -0,0 +1,80 @@
+# Refactor Clean
+
+Identifique e remova código morto com segurança, com verificação de testes em cada passo.
+
+## Passo 1: Detectar Código Morto
+
+Rode ferramentas de análise com base no tipo do projeto:
+
+| Tool | What It Finds | Command |
+|------|--------------|---------|
+| knip | Unused exports, files, dependencies | `npx knip` |
+| depcheck | Unused npm dependencies | `npx depcheck` |
+| ts-prune | Unused TypeScript exports | `npx ts-prune` |
+| vulture | Unused Python code | `vulture src/` |
+| deadcode | Unused Go code | `deadcode ./...` |
+| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
+
+Se nenhuma ferramenta estiver disponível, use Grep para encontrar exports com zero imports:
+```
+# Find exports, then check if they're imported anywhere
+```
+
+## Passo 2: Categorizar Achados
+
+Classifique os achados em níveis de segurança:
+
+| Tier | Examples | Action |
+|------|----------|--------|
+| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
+| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
+| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
+
+## Passo 3: Loop de Remoção Segura
+
+Para cada item SAFE:
+
+1. **Rode a suíte completa de testes** — Estabeleça baseline (tudo verde)
+2. **Delete o código morto** — Use a ferramenta Edit para remoção cirúrgica
+3. **Rode a suíte de testes novamente** — Verifique se nada quebrou
+4. **Se testes falharem** — Reverta imediatamente com `git checkout -- <file>` e pule este item
+5. **Se testes passarem** — Vá para o próximo item
+
+## Passo 4: Tratar Itens CAUTION
+
+Antes de deletar itens CAUTION:
+- Procure imports dinâmicos: `import()`, `require()`, `__import__`
+- Procure referências em string: nomes de rota, nomes de componente em configs
+- Verifique se é exportado por API pública de pacote
+- Verifique ausência de consumidores externos (dependents, se publicado)
+
+## Passo 5: Consolidar Duplicatas
+
+Depois de remover código morto, procure:
+- Funções quase duplicadas (>80% similares) — mesclar em uma
+- Definições de tipo redundantes — consolidar
+- Funções wrapper sem valor — inline
+- Re-exports sem propósito — remover indireção
+
+## Passo 6: Resumo
+
+Reporte resultados:
+
+```
+Dead Code Cleanup
+──────────────────────────────
+Deleted: 12 unused functions
+ 3 unused files
+ 5 unused dependencies
+Skipped: 2 items (tests failed)
+Saved: ~450 lines removed
+──────────────────────────────
+All tests passing ✅
+```
+
+## Regras
+
+- **Nunca delete sem rodar testes antes**
+- **Uma remoção por vez** — Mudanças atômicas facilitam rollback
+- **Se houver dúvida, pule** — Melhor manter código morto do que quebrar produção
+- **Não refatore durante limpeza** — Separe responsabilidades (limpar primeiro, refatorar depois)
diff --git a/docs/pt-BR/commands/setup-pm.md b/docs/pt-BR/commands/setup-pm.md
new file mode 100644
index 000000000..ca978774a
--- /dev/null
+++ b/docs/pt-BR/commands/setup-pm.md
@@ -0,0 +1,80 @@
+---
+description: Configure seu package manager preferido (npm/pnpm/yarn/bun)
+disable-model-invocation: true
+---
+
+# Configuração de Package Manager
+
+Configure seu package manager preferido para este projeto ou globalmente.
+
+## Uso
+
+```bash
+# Detect current package manager
+node scripts/setup-package-manager.js --detect
+
+# Set global preference
+node scripts/setup-package-manager.js --global pnpm
+
+# Set project preference
+node scripts/setup-package-manager.js --project bun
+
+# List available package managers
+node scripts/setup-package-manager.js --list
+```
+
+## Prioridade de Detecção
+
+Ao determinar qual package manager usar, esta ordem é verificada:
+
+1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER`
+2. **Project config**: `.claude/package-manager.json`
+3. **package.json**: `packageManager` field
+4. **Lock file**: Presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
+5. **Global config**: `~/.claude/package-manager.json`
+6. **Fallback**: First available package manager (pnpm > bun > yarn > npm)
+
+## Arquivos de Configuração
+
+### Configuração Global
+```json
+// ~/.claude/package-manager.json
+{
+ "packageManager": "pnpm"
+}
+```
+
+### Configuração do Projeto
+```json
+// .claude/package-manager.json
+{
+ "packageManager": "bun"
+}
+```
+
+### package.json
+```json
+{
+ "packageManager": "[email protected]"
+}
+```
+
+## Variável de Ambiente
+
+Defina `CLAUDE_PACKAGE_MANAGER` para sobrescrever todos os outros métodos de detecção:
+
+```bash
+# Windows (PowerShell)
+$env:CLAUDE_PACKAGE_MANAGER = "pnpm"
+
+# macOS/Linux
+export CLAUDE_PACKAGE_MANAGER=pnpm
+```
+
+## Rodar a Detecção
+
+Para ver os resultados atuais da detecção de package manager, rode:
+
+```bash
+node scripts/setup-package-manager.js --detect
+```
diff --git a/docs/pt-BR/commands/tdd.md b/docs/pt-BR/commands/tdd.md
new file mode 100644
index 000000000..341b98cf8
--- /dev/null
+++ b/docs/pt-BR/commands/tdd.md
@@ -0,0 +1,328 @@
+---
+description: Impõe fluxo de desenvolvimento orientado a testes. Estruture interfaces, gere testes PRIMEIRO e depois implemente código mínimo para passar. Garanta cobertura de 80%+.
+---
+
+# Comando TDD
+
+Este comando invoca o agente **tdd-guide** para impor a metodologia de desenvolvimento orientado a testes.
+
+## O Que Este Comando Faz
+
+1. **Estruturar Interfaces** - Definir tipos/interfaces primeiro
+2. **Gerar Testes Primeiro** - Escrever testes que falham (RED)
+3. **Implementar Código Mínimo** - Escrever apenas o suficiente para passar (GREEN)
+4. **Refatorar** - Melhorar o código mantendo testes verdes (REFACTOR)
+5. **Verificar Cobertura** - Garantir cobertura de testes de 80%+
+
+## Quando Usar
+
+Use `/tdd` quando:
+- Implementar novas features
+- Adicionar novas funções/componentes
+- Corrigir bugs (escrever primeiro teste que reproduz o bug)
+- Refatorar código existente
+- Construir lógica de negócio crítica
+
+## Como Funciona
+
+O agente tdd-guide vai:
+
+1. **Definir interfaces** para entradas/saídas
+2. **Escrever testes que vão FALHAR** (porque o código ainda não existe)
+3. **Rodar testes** e verificar que falham pelo motivo correto
+4. **Escrever implementação mínima** para fazer testes passarem
+5. **Rodar testes** e verificar que passam
+6. **Refatorar** código mantendo testes verdes
+7. **Checar cobertura** e adicionar mais testes se estiver abaixo de 80%
+
+## Ciclo TDD
+
+```
+RED → GREEN → REFACTOR → REPEAT
+
+RED: Write a failing test
+GREEN: Write minimal code to pass
+REFACTOR: Improve code, keep tests passing
+REPEAT: Next feature/scenario
+```
+
+## Exemplo de Uso
+
+```
+User: /tdd I need a function to calculate market liquidity score
+
+Agent (tdd-guide):
+# TDD Session: Market Liquidity Score Calculator
+
+## Step 1: Define Interface (SCAFFOLD)
+
+```typescript
+// lib/liquidity.ts
+export interface MarketData {
+ totalVolume: number
+ bidAskSpread: number
+ activeTraders: number
+ lastTradeTime: Date
+}
+
+export function calculateLiquidityScore(market: MarketData): number {
+ // TODO: Implementation
+ throw new Error('Not implemented')
+}
+```
+
+## Step 2: Write Failing Test (RED)
+
+```typescript
+// lib/liquidity.test.ts
+import { calculateLiquidityScore } from './liquidity'
+
+describe('calculateLiquidityScore', () => {
+ it('should return high score for liquid market', () => {
+ const market = {
+ totalVolume: 100000,
+ bidAskSpread: 0.01,
+ activeTraders: 500,
+ lastTradeTime: new Date()
+ }
+
+ const score = calculateLiquidityScore(market)
+
+ expect(score).toBeGreaterThan(80)
+ expect(score).toBeLessThanOrEqual(100)
+ })
+
+ it('should return low score for illiquid market', () => {
+ const market = {
+ totalVolume: 100,
+ bidAskSpread: 0.5,
+ activeTraders: 2,
+ lastTradeTime: new Date(Date.now() - 86400000) // 1 day ago
+ }
+
+ const score = calculateLiquidityScore(market)
+
+ expect(score).toBeLessThan(30)
+ expect(score).toBeGreaterThanOrEqual(0)
+ })
+
+ it('should handle edge case: zero volume', () => {
+ const market = {
+ totalVolume: 0,
+ bidAskSpread: 0,
+ activeTraders: 0,
+ lastTradeTime: new Date()
+ }
+
+ const score = calculateLiquidityScore(market)
+
+ expect(score).toBe(0)
+ })
+})
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+npm test lib/liquidity.test.ts
+
+FAIL lib/liquidity.test.ts
+ ✕ should return high score for liquid market (2 ms)
+ Error: Not implemented
+
+1 test failed, 0 passed
+```
+
+✅ Tests fail as expected. Ready to implement.
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```typescript
+// lib/liquidity.ts
+export function calculateLiquidityScore(market: MarketData): number {
+ // Handle zero volume edge case
+ if (market.totalVolume === 0) {
+ return 0
+ }
+
+ // Calculate component scores (0-100 scale)
+ const volumeScore = Math.min(market.totalVolume / 1000, 100)
+ const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)
+ const traderScore = Math.min(market.activeTraders / 10, 100)
+
+ // Recent activity bonus
+ const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
+ const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0)
+
+ // Weighted average
+ const score = (
+ volumeScore * 0.4 +
+ spreadScore * 0.3 +
+ traderScore * 0.2 +
+ recencyScore * 0.1
+ )
+
+ return Math.min(Math.max(score, 0), 100) // Clamp to 0-100
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+npm test lib/liquidity.test.ts
+
+PASS lib/liquidity.test.ts
+ ✓ should return high score for liquid market (3 ms)
+ ✓ should return low score for illiquid market (2 ms)
+ ✓ should handle edge case: zero volume (1 ms)
+
+3 tests passed
+```
+
+✅ All tests passing!
+
+## Step 6: Refactor (IMPROVE)
+
+```typescript
+// lib/liquidity.ts - Refactored with constants and better readability
+const WEIGHTS = {
+ VOLUME: 0.4,
+ SPREAD: 0.3,
+ TRADERS: 0.2,
+ RECENCY: 0.1,
+} as const
+
+const SCALE_FACTORS = {
+ VOLUME: 1000,
+ SPREAD: 1000,
+ TRADERS: 10,
+ RECENCY_PENALTY: 10,
+} as const
+
+function clamp(value: number, min: number, max: number): number {
+ return Math.min(Math.max(value, min), max)
+}
+
+export function calculateLiquidityScore(market: MarketData): number {
+ if (market.totalVolume === 0) return 0
+
+ const volumeScore = Math.min(market.totalVolume / SCALE_FACTORS.VOLUME, 100)
+ const spreadScore = clamp(100 - (market.bidAskSpread * SCALE_FACTORS.SPREAD), 0, 100)
+ const traderScore = Math.min(market.activeTraders / SCALE_FACTORS.TRADERS, 100)
+
+ const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
+ const recencyScore = clamp(100 - (hoursSinceLastTrade * SCALE_FACTORS.RECENCY_PENALTY), 0, 100)
+
+ const weightedScore =
+ volumeScore * WEIGHTS.VOLUME +
+ spreadScore * WEIGHTS.SPREAD +
+ traderScore * WEIGHTS.TRADERS +
+ recencyScore * WEIGHTS.RECENCY
+
+ return clamp(weightedScore, 0, 100)
+}
+```
+
+## Step 7: Verify Tests Still Pass
+
+```bash
+npm test lib/liquidity.test.ts
+
+PASS lib/liquidity.test.ts
+ ✓ should return high score for liquid market (3 ms)
+ ✓ should return low score for illiquid market (2 ms)
+ ✓ should handle edge case: zero volume (1 ms)
+
+3 tests passed
+```
+
+✅ Refactoring complete, tests still passing!
+
+## Step 8: Check Coverage
+
+```bash
+npm test -- --coverage lib/liquidity.test.ts
+
+File | % Stmts | % Branch | % Funcs | % Lines
+---------------|---------|----------|---------|--------
+liquidity.ts | 100 | 100 | 100 | 100
+
+Coverage: 100% ✅ (Target: 80%)
+```
+
+✅ TDD session complete!
+```
+
+## Boas Práticas de TDD
+
+**DO:**
+- ✅ Escreva o teste PRIMEIRO, antes da implementação
+- ✅ Rode testes e confirme que FALHAM antes de implementar
+- ✅ Escreva código mínimo para fazer passar
+- ✅ Refatore só depois que os testes estiverem verdes
+- ✅ Adicione casos de borda e cenários de erro
+- ✅ Mire 80%+ de cobertura (100% para código crítico)
+
+**DON'T:**
+- ❌ Escrever implementação antes de testes
+- ❌ Pular execução de testes após cada mudança
+- ❌ Escrever código demais de uma vez
+- ❌ Ignorar testes falhando
+- ❌ Testar detalhes de implementação (teste comportamento)
+- ❌ Fazer mock de tudo (prefira testes de integração)
+
+## Tipos de Teste a Incluir
+
+**Testes Unitários** (nível de função):
+- Cenários happy path
+- Casos de borda (vazio, null, valores máximos)
+- Condições de erro
+- Valores de fronteira
+
+**Testes de Integração** (nível de componente):
+- Endpoints de API
+- Operações de banco de dados
+- Chamadas a serviços externos
+- Componentes React com hooks
+
+**Testes E2E** (use comando `/e2e`):
+- Fluxos críticos de usuário
+- Processos multi-etapa
+- Integração full stack
+
+## Requisitos de Cobertura
+
+- **Mínimo de 80%** para todo o código
+- **100% obrigatório** para:
+ - Cálculos financeiros
+ - Lógica de autenticação
+ - Código crítico de segurança
+ - Lógica de negócio central
+
+## Notas Importantes
+
+**MANDATÓRIO**: Os testes devem ser escritos ANTES da implementação. O ciclo TDD é:
+
+1. **RED** - Escrever teste que falha
+2. **GREEN** - Implementar para passar
+3. **REFACTOR** - Melhorar código
+
+Nunca pule a fase RED. Nunca escreva código antes dos testes.
+
+## Integração com Outros Comandos
+
+- Use `/plan` primeiro para entender o que construir
+- Use `/tdd` para implementar com testes
+- Use `/build-fix` se ocorrerem erros de build
+- Use `/code-review` para revisar implementação
+- Use `/test-coverage` para verificar cobertura
+
+## Agentes Relacionados
+
+Este comando invoca o agente `tdd-guide` fornecido pelo ECC.
+
+A skill relacionada `tdd-workflow` também é distribuída com o ECC.
+
+Para instalações manuais, os arquivos fonte ficam em:
+- `agents/tdd-guide.md`
+- `skills/tdd-workflow/SKILL.md`
diff --git a/docs/pt-BR/commands/test-coverage.md b/docs/pt-BR/commands/test-coverage.md
new file mode 100644
index 000000000..e1c67d6d4
--- /dev/null
+++ b/docs/pt-BR/commands/test-coverage.md
@@ -0,0 +1,69 @@
+# Cobertura de Testes
+
+Analise cobertura de testes, identifique lacunas e gere testes faltantes para alcançar cobertura de 80%+.
+
+## Passo 1: Detectar Framework de Teste
+
+| Indicator | Coverage Command |
+|-----------|-----------------|
+| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
+| `vitest.config.*` | `npx vitest run --coverage` |
+| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
+| `Cargo.toml` | `cargo llvm-cov --json` |
+| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
+| `go.mod` | `go test -coverprofile=coverage.out ./...` |
+
+## Passo 2: Analisar Relatório de Cobertura
+
+1. Rode o comando de cobertura
+2. Parseie a saída (resumo em JSON ou saída de terminal)
+3. Liste arquivos **abaixo de 80% de cobertura**, ordenados do pior para o melhor
+4. Para cada arquivo abaixo da meta, identifique:
+ - Funções ou métodos sem teste
+ - Cobertura de branch faltante (if/else, switch, caminhos de erro)
+ - Código morto que infla o denominador
+
+## Passo 3: Gerar Testes Faltantes
+
+Para cada arquivo abaixo da meta, gere testes seguindo esta prioridade:
+
+1. **Happy path** — Funcionalidade principal com entradas válidas
+2. **Tratamento de erro** — Entradas inválidas, dados ausentes, falhas de rede
+3. **Casos de borda** — Arrays vazios, null/undefined, valores de fronteira (0, -1, MAX_INT)
+4. **Cobertura de branch** — Cada if/else, caso de switch, ternário
+
+### Regras para Geração de Testes
+
+- Coloque testes adjacentes ao código-fonte: `foo.ts` → `foo.test.ts` (ou convenção do projeto)
+- Use padrões de teste existentes do projeto (estilo de import, biblioteca de asserção, abordagem de mocking)
+- Faça mock de dependências externas (banco, APIs, sistema de arquivos)
+- Cada teste deve ser independente — sem estado mutável compartilhado entre testes
+- Nomeie testes de forma descritiva: `test_create_user_with_duplicate_email_returns_409`
+
+## Passo 4: Verificar
+
+1. Rode a suíte completa de testes — todos os testes devem passar
+2. Rode cobertura novamente — confirme a melhoria
+3. Se ainda estiver abaixo de 80%, repita o Passo 3 para as lacunas restantes
+
+## Passo 5: Reportar
+
+Mostre comparação antes/depois:
+
+```
+Coverage Report
+──────────────────────────────
+File Before After
+src/services/auth.ts 45% 88%
+src/utils/validation.ts 32% 82%
+──────────────────────────────
+Overall: 67% 84% ✅
+```
+
+## Áreas de Foco
+
+- Funções com branching complexo (alta complexidade ciclomática)
+- Error handlers e blocos catch
+- Funções utilitárias usadas em todo o codebase
+- Handlers de endpoint de API (fluxo request → response)
+- Casos de borda: null, undefined, string vazia, array vazio, zero, números negativos
diff --git a/docs/pt-BR/commands/update-codemaps.md b/docs/pt-BR/commands/update-codemaps.md
new file mode 100644
index 000000000..8a5cb90fe
--- /dev/null
+++ b/docs/pt-BR/commands/update-codemaps.md
@@ -0,0 +1,72 @@
+# Atualizar Codemaps
+
+Analise a estrutura do codebase e gere documentação arquitetural enxuta em tokens.
+
+## Passo 1: Escanear Estrutura do Projeto
+
+1. Identifique o tipo de projeto (monorepo, app única, library, microservice)
+2. Encontre todos os diretórios de código-fonte (src/, lib/, app/, packages/)
+3. Mapeie entry points (main.ts, index.ts, app.py, main.go, etc.)
+
+## Passo 2: Gerar Codemaps
+
+Crie ou atualize codemaps em `docs/CODEMAPS/` (ou `.reports/codemaps/`):
+
+| File | Contents |
+|------|----------|
+| `architecture.md` | High-level system diagram, service boundaries, data flow |
+| `backend.md` | API routes, middleware chain, service → repository mapping |
+| `frontend.md` | Page tree, component hierarchy, state management flow |
+| `data.md` | Database tables, relationships, migration history |
+| `dependencies.md` | External services, third-party integrations, shared libraries |
+
+### Formato de Codemap
+
+Cada codemap deve ser enxuto em tokens — otimizado para consumo de contexto por IA:
+
+```markdown
+# Backend Architecture
+
+## Routes
+POST /api/users → UserController.create → UserService.create → UserRepo.insert
+GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
+
+## Key Files
+src/services/user.ts (business logic, 120 lines)
+src/repos/user.ts (database access, 80 lines)
+
+## Dependencies
+- PostgreSQL (primary data store)
+- Redis (session cache, rate limiting)
+- Stripe (payment processing)
+```
+
+## Passo 3: Detecção de Diff
+
+1. Se codemaps anteriores existirem, calcule a porcentagem de diff
+2. Se mudanças > 30%, mostre o diff e solicite aprovação do usuário antes de sobrescrever
+3. Se mudanças <= 30%, atualize in-place
+
+## Passo 4: Adicionar Metadados
+
+Adicione um cabeçalho de freshness em cada codemap:
+
+```markdown
+<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
+```
+
+## Passo 5: Salvar Relatório de Análise
+
+Escreva um resumo em `.reports/codemap-diff.txt`:
+- Arquivos adicionados/removidos/modificados desde o último scan
+- Novas dependências detectadas
+- Mudanças de arquitetura (novas rotas, novos serviços etc.)
+- Alertas de obsolescência para docs sem atualização em 90+ dias
+
+## Dicas
+
+- Foque em **estrutura de alto nível**, não em detalhes de implementação
+- Prefira **caminhos de arquivo e assinaturas de função** em vez de blocos de código completos
+- Mantenha cada codemap abaixo de **1000 tokens** para carregamento eficiente de contexto
+- Use diagramas ASCII para fluxo de dados em vez de descrições verbosas
+- Rode após grandes adições de feature ou sessões de refatoração
diff --git a/docs/pt-BR/commands/update-docs.md b/docs/pt-BR/commands/update-docs.md
new file mode 100644
index 000000000..9563299c5
--- /dev/null
+++ b/docs/pt-BR/commands/update-docs.md
@@ -0,0 +1,84 @@
+# Atualizar Documentação
+
+Sincronize a documentação com o codebase, gerando a partir de arquivos fonte da verdade.
+
+## Passo 1: Identificar Fontes da Verdade
+
+| Source | Generates |
+|--------|-----------|
+| `package.json` scripts | Available commands reference |
+| `.env.example` | Environment variable documentation |
+| `openapi.yaml` / route files | API endpoint reference |
+| Source code exports | Public API documentation |
+| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs |
+
+## Passo 2: Gerar Referência de Scripts
+
+1. Leia `package.json` (ou `Makefile`, `Cargo.toml`, `pyproject.toml`)
+2. Extraia todos os scripts/comandos com suas descrições
+3. Gere uma tabela de referência:
+
+```markdown
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with hot reload |
+| `npm run build` | Production build with type checking |
+| `npm test` | Run test suite with coverage |
+```
+
+## Passo 3: Gerar Documentação de Ambiente
+
+1. Leia `.env.example` (ou `.env.template`, `.env.sample`)
+2. Extraia todas as variáveis e seus propósitos
+3. Categorize como required vs optional
+4. Documente formato esperado e valores válidos
+
+```markdown
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
+| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |
+```
+
+## Passo 4: Atualizar Guia de Contribuição
+
+Gere ou atualize `docs/CONTRIBUTING.md` com:
+- Setup do ambiente de desenvolvimento (pré-requisitos, passos de instalação)
+- Scripts disponíveis e seus propósitos
+- Procedimentos de teste (como rodar, como escrever novos testes)
+- Enforcement de estilo de código (linter, formatter, hooks pre-commit)
+- Checklist de submissão de PR
+
+## Passo 5: Atualizar Runbook
+
+Gere ou atualize `docs/RUNBOOK.md` com:
+- Procedimentos de deploy (passo a passo)
+- Endpoints de health check e monitoramento
+- Problemas comuns e suas correções
+- Procedimentos de rollback
+- Caminhos de alerta e escalonamento
+
+## Passo 6: Checagem de Obsolescência
+
+1. Encontre arquivos de documentação sem modificação há 90+ dias
+2. Cruze com mudanças recentes no código-fonte
+3. Sinalize docs potencialmente desatualizadas para revisão manual
+
+## Passo 7: Mostrar Resumo
+
+```
+Documentation Update
+──────────────────────────────
+Updated: docs/CONTRIBUTING.md (scripts table)
+Updated: docs/ENV.md (3 new variables)
+Flagged: docs/DEPLOY.md (142 days stale)
+Skipped: docs/API.md (no changes detected)
+──────────────────────────────
+```
+
+## Regras
+
+- **Fonte única da verdade**: Sempre gere a partir do código, nunca edite manualmente seções geradas
+- **Preserve seções manuais**: Atualize apenas seções geradas; mantenha prosa escrita manualmente intacta
+- **Marque conteúdo gerado**: Use marcadores `<!-- AUTO-GENERATED -->` ao redor das seções geradas
+- **Não crie docs sem solicitação**: Só crie novos arquivos de docs se o comando solicitar explicitamente
diff --git a/docs/pt-BR/commands/verify.md b/docs/pt-BR/commands/verify.md
new file mode 100644
index 000000000..5916a529b
--- /dev/null
+++ b/docs/pt-BR/commands/verify.md
@@ -0,0 +1,59 @@
+# Comando Verification
+
+Rode verificação abrangente no estado atual do codebase.
+
+## Instruções
+
+Execute a verificação nesta ordem exata:
+
+1. **Build Check**
+ - Rode o comando de build deste projeto
+ - Se falhar, reporte erros e PARE
+
+2. **Type Check**
+ - Rode o TypeScript/type checker
+ - Reporte todos os erros com file:line
+
+3. **Lint Check**
+ - Rode o linter
+ - Reporte warnings e errors
+
+4. **Test Suite**
+ - Rode todos os testes
+ - Reporte contagem de pass/fail
+ - Reporte percentual de cobertura
+
+5. **Console.log Audit**
+ - Procure por console.log em arquivos de código-fonte
+ - Reporte localizações
+
+6. **Git Status**
+ - Mostre mudanças não commitadas
+ - Mostre arquivos modificados desde o último commit
+
+## Saída
+
+Produza um relatório conciso de verificação:
+
+```
+VERIFICATION: [PASS/FAIL]
+
+Build: [OK/FAIL]
+Types: [OK/X errors]
+Lint: [OK/X issues]
+Tests: [X/Y passed, Z% coverage]
+Secrets: [OK/X found]
+Logs: [OK/X console.logs]
+
+Ready for PR: [YES/NO]
+```
+
+Se houver problemas críticos, liste-os com sugestões de correção.
+
+## Argumentos
+
+$ARGUMENTS podem ser:
+- `quick` - Apenas build + types
+- `full` - Todas as checagens (padrão)
+- `pre-commit` - Checagens relevantes para commits
+- `pre-pr` - Checagens completas mais security scan