sinapse-ai 7.7.11 → 8.0.0

package/README.md

@@ -1,206 +1,332 @@
-# SINAPSE AI
+[![npm version](https://img.shields.io/npm/v/sinapse-ai.svg)](https://www.npmjs.com/package/sinapse-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
+[![CI](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml)
+[![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-> [English](README.en.md) | **Portugues**
+# SINAPSE-AI
 
-[![npm](https://img.shields.io/npm/v/sinapse-ai.svg)](https://www.npmjs.com/package/sinapse-ai)
-[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Open Source](https://img.shields.io/badge/Open%20Source-Yes-success.svg)](LICENSE)
+> **Squads de IA que constroem com voce, nao para voce.**
 
-> **175 agentes de IA. 18 squads especializados. Uma CLI.**
->
-> O SINAPSE AI e um framework open source que organiza agentes de IA em squads especializados para resolver problemas reais de negocios, marketing, desenvolvimento, copy, design e mais. Funciona direto no seu terminal com Claude Code, Codex CLI ou qualquer IDE compativel.
+[**Portugues**] | [English](README.en.md)
 
 ---
 
-## O que e o SINAPSE AI
+## O que e o SINAPSE?
 
-O SINAPSE AI nao e mais um chatbot. E um sistema de orquestracao onde cada agente tem um papel claro, cada squad domina uma disciplina, e tudo funciona via CLI.
+SINAPSE e um framework open source que organiza **175 agentes de IA em 18 squads especializados**, operando direto no terminal via Claude Code ou Codex CLI. Cada agente tem um papel definido, cada squad domina uma disciplina, e o sistema inteiro e governado por uma **Constitution com enforcement real** — 19 hooks ativos que bloqueiam violacoes em tempo de execucao, nao depois.
 
-**O que voce ganha ao instalar:**
+Diferente de ferramentas que apenas conversam com IA, o SINAPSE estrutura o trabalho. Antes de qualquer linha de codigo, o pipeline **Documentation-First** exige que uma story seja criada, validada e rastreada. Isso nao e uma sugestao — e uma regra que o framework impoe automaticamente. Nenhum agente escreve codigo sem uma story aprovada.
 
-- **18 orquestradores de squad (orqx)** prontos para ativar direto no terminal
-- **175 agentes especializados** com knowledge bases proprias
-- **Workflows completos** de planejamento, desenvolvimento, QA e deploy
-- **Documentation-First Development** com pipeline automatico de epics, stories e validacao
-- **Compatibilidade multi-IDE**: Claude Code e Codex CLI
-
-### Arquitetura: CLI First
-
-```
-CLI First > Observability Second > UI Third
-```
-
-Toda inteligencia vive na CLI. Dashboards observam. A UI nunca e requisito.
+O resultado e um sistema onde desenvolvimento, branding, copy, cybersecurity, growth, design e mais de uma dezena de outros dominios operam com a mesma disciplina: squads especializados, workflows automaticos, quality gates antes de merge, e tudo governado por principios inegociaveis. Tudo via CLI.
 
 ---
 
-## Instalacao (2 minutos)
+## Quick Start
+
+### 1. Instale
 
 ```bash
-# Novo projeto
+# Projeto novo
 npx sinapse-ai init meu-projeto
 
 # Projeto existente
 cd seu-projeto && npx sinapse-ai install
-
-# Atualizar instalacao existente
-npx sinapse-ai@latest install
 ```
 
-O wizard detecta seu ambiente, configura sua IDE, instala os squads e ativa o **Chrome Brain** (browser automation) automaticamente.
+### 2. Verifique
 
 ```bash
-# Diagnostico
 npx sinapse-ai doctor
+```
+
+```
+  SINAPSE Doctor v7.7.11
+  ----------------------
+  [PASS] Node.js >= 18
+  [PASS] .sinapse-ai/ structure
+  [PASS] core-config.yaml
+  [PASS] IDE: claude-code
+  [PASS] 18 squads loaded
+  [PASS] 175 agents available
+  [PASS] Constitution v2.2.0
+
+  Result: ALL CHECKS PASSED
+```
+
+### 3. Ative seu primeiro agente
+
+No **Claude Code**:
+```
+@developer          # Ativa o agente de desenvolvimento
+*help               # Lista comandos disponiveis
+```
+
+No **Codex CLI**:
+```
+/skills             # Lista todos os agentes
+$sinapse-dev        # Ativa o developer
+```
+
+Pronto. Voce tem 18 squads operando no seu terminal.
+
+---
+
+## O que voce quer fazer?
+
+| Objetivo | Comece aqui |
+|----------|-------------|
+| Comecar um projeto novo | [Getting Started](docs/getting-started.md) |
+| Entender a arquitetura | [Architecture Overview](docs/architecture-overview.md) |
+| Ver os agentes disponiveis | [Agent Reference](docs/guides/agent-reference.md) |
+| Entender os workflows | [Workflows](docs/GUIDING-PRINCIPLES.md) |
+| Contribuir com o framework | [Contributing](CONTRIBUTING.md) |
+| Reportar vulnerabilidade | [Security](SECURITY.md) |
+
+---
+
+## Arquitetura: CLI First
 
-# Informacoes do sistema
-npx sinapse-ai info
+```
+CLI First  >  Observability Second  >  UI Third
+```
+
+Toda inteligencia vive no terminal. Dashboards observam. A UI nunca e requisito para operar o sistema. Esse e o Artigo I da Constitution — inegociavel.
+
+---
+
+## IDE Support
+
+| IDE | Status | Ativacao | Destaques |
+|-----|--------|----------|-----------|
+| **Claude Code** | Completo | `@agent-name` | Hooks, rules contextuais, deny/allow, Chrome Brain auto-launch |
+| **Codex CLI** | Completo | `/skills` ou `$skill-name` | Skills nativas, multi-model, `codex exec` para CI/CD |
+
+Ambas as IDEs tem acesso a todos os 18 squads, 175 agentes, workflows e knowledge bases. O installer detecta e configura automaticamente.
+
+---
+
+## Agentes Core
+
+O SINAPSE inclui 12 agentes core que cobrem o ciclo completo de desenvolvimento:
+
+| Agente | Persona | Papel |
+|--------|---------|-------|
+| `sinapse-orqx` | **Imperator** | Orquestrador principal — routing, diagnostico, coordenacao cross-squad |
+| `developer` | **Pixel** | Implementacao de codigo, story development |
+| `quality-gate` | **Litmus** | Testes, QA, quality gates, verdicts |
+| `architect` | **Stratum** | Arquitetura, design tecnico, decisoes de tecnologia |
+| `project-lead` | **Beacon** | Product management, epics, spec pipeline |
+| `product-lead` | **Axis** | Validacao de stories, backlog, priorizacao |
+| `sprint-lead` | **Sync** | Criacao de stories, sprints, templates |
+| `analyst` | **Scope** | Pesquisa, analise de negocios, inteligencia |
+| `data-engineer` | **Tensor** | Database design, migrations, RLS, otimizacao |
+| `ux-design-expert` | **Mosaic** | UX/UI design, experiencia do usuario |
+| `devops` | **Pipeline** | CI/CD, git push (exclusivo), releases, PRs |
+| `squad-creator` | **Loom** | Criacao de novos squads personalizados |
+
+### Workflow de Desenvolvimento
+
+```
+@sprint-lead cria story
+       |
+@product-lead valida
+       |
+@developer implementa
+       |
+@quality-gate testa
+       |
+@devops push + PR
 ```
 
-**Requisitos:** Node.js 18+ (v20+ recomendado)
+Esse fluxo e automatico. O framework garante que nenhuma etapa seja pulada.
 
 ---
 
-## Squads Disponiveis
+## 18 Squads Especializados
 
-Cada squad e uma equipe de agentes especializados com knowledge base, workflows e tasks proprias. Todos os squads sao **gratuitos e open source**.
+Cada squad e uma equipe autonoma com orquestrador, agentes especialistas, knowledge base, tasks e workflows proprios. Todos sao gratuitos e open source.
 
-| Squad | Foco | Agentes |
-|-------|------|---------|
-| **squad-brand** | Estrategia de marca, arquetipos, auditoria | 15 |
+| Squad | Dominio | Agentes |
+|-------|---------|---------|
+| **squad-brand** | Estrategia de marca, arquetipos, auditoria visual | 15 |
+| **squad-design** | Design systems, componentes, tokens, UI | 15 |
 | **squad-copy** | Copywriting persuasivo, headlines, conversao | 14 |
-| **squad-council** | Advisors estrategicos (Munger, Dalio, Thiel) | 11 |
+| **squad-council** | Advisors estrategicos (Munger, Dalio, Thiel, ...) | 11 |
 | **squad-storytelling** | Narrativa, roteiros, frameworks de historia | 11 |
-| **squad-commercial** | Vendas, funil, revenue, pipeline | 11 |
-| **squad-animations** | Motion design, CSS, particulas, 3D | 9 |
+| **squad-commercial** | Vendas, funil, revenue, pipeline comercial | 11 |
 | **squad-paidmedia** | Meta Ads, Google Ads, campanhas, otimizacao | 10 |
-| **squad-claude** | Claude Code, MCP, integracao avancada | 10 |
-| **squad-cloning** | Clonagem cognitiva, mind synthesis | 9 |
-| **squad-courses** | Cursos, curriculos, assessments, launch | 8 |
-| **squad-cybersecurity** | Seguranca, threat intel, pentest | 9 |
-| **squad-design** | Design systems, componentes, tokens | 15 |
+| **squad-claude** | Claude Code avancado, MCP, integracao profunda | 10 |
+| **squad-animations** | Motion design, CSS, particulas, 3D | 9 |
+| **squad-cloning** | Clonagem cognitiva, mind synthesis, digital twins | 9 |
+| **squad-cybersecurity** | Threat intel, pentest, compliance, LGPD | 9 |
+| **squad-courses** | Cursos, curriculos, assessments, launch educacional | 8 |
+| **squad-research** | Market analysis, inteligencia competitiva | 8 |
 | **squad-content** | Governanca editorial, estrategia de conteudo | 7 |
 | **squad-product** | Product discovery, estrategia, operacoes | 7 |
-| **squad-research** | Market analysis, inteligencia competitiva | 8 |
 | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
 | **squad-finance** | Budget, pricing, profitability analysis | 5 |
-| **claude-code-mastery** | Dominio avancado do Claude Code | 8 |
+| **claude-code-mastery** | Dominio avancado do Claude Code como ferramenta | 8 |
 
 **Total: 18 squads, 175 agentes especializados**
 
+Cada squad e ativado via seu orquestrador:
+
+```
+@brand-orqx         # Squad de brand
+@copy-orqx          # Squad de copy
+@cyber-orqx         # Squad de cybersecurity
+@research-orqx      # Squad de research
+@growth-orqx        # Squad de growth
+```
+
+O orquestrador recebe seu pedido e delega automaticamente ao especialista correto dentro do squad.
+
 ---
 
-## Chrome Brain — Browser Automation
+## Constitution
 
-Todos os agentes do SINAPSE podem controlar o Chrome em tempo real: navegar sites, clonar paginas, preencher formularios, auditar performance e extrair dados.
+O SINAPSE e governado por uma **Constitution formal** (v2.2.0) com 10 artigos. Nao sao diretrizes — sao regras que o framework impoe via hooks e gates automaticos.
 
-**Instalado automaticamente** pelo wizard. Zero configuracao manual.
+| Artigo | Principio | Severidade |
+|--------|-----------|------------|
+| I | CLI First | NON-NEGOTIABLE |
+| II | Agent Authority | NON-NEGOTIABLE |
+| III | Documentation-First Development | NON-NEGOTIABLE |
+| IV | No Invention | MUST |
+| V | Quality First | MUST |
+| VI | Absolute Imports | SHOULD |
+| VII | Ecosystem Metrics Accuracy | NON-NEGOTIABLE |
+| VIII | Mandatory Delegation | NON-NEGOTIABLE |
+| IX | Safe Collaboration | NON-NEGOTIABLE |
+| X | Security & Data Protection | NON-NEGOTIABLE |
 
-```bash
-# Verificar status
-sinapse chrome-brain status
+**6 artigos sao NON-NEGOTIABLE** — violacoes sao bloqueadas automaticamente.
 
-# Reinstalar/atualizar
-sinapse chrome-brain install
-```
+### Enforcement Real
 
-**Como funciona:**
-1. Voce diz: "abre o site google.com"
-2. Chrome Brain auto-ativa (sem comando manual)
-3. Chrome inicia automaticamente na porta 9222
-4. Agente usa 29 tools do Chrome DevTools MCP
-5. Resultado entregue ao squad do dominio
+O SINAPSE nao apenas documenta regras — ele as impoe:
 
-**Suporte:** macOS, Linux, Windows (Git Bash/WSL)
+- **19 hooks ativos** interceptam operacoes em tempo real
+- `enforce-git-push-authority.sh` — bloqueia push por agentes nao autorizados
+- `enforce-story-gate.cjs` — bloqueia codigo sem story validada
+- `sql-governance.py` — bloqueia SQL perigoso (injection patterns)
+- `enforce-delegation.cjs` — bloqueia orquestradores executando trabalho de dominio
+- `enforce-architecture-first.cjs` — bloqueia codigo em paths protegidos sem documentacao
+
+Se um agente tenta violar a Constitution, a operacao e bloqueada antes de executar. Nao depois.
 
 ---
 
-## Como Usar
+## Workflows
 
-### No Claude Code
+O SINAPSE opera com 4 workflows principais:
 
-Ative qualquer orquestrador pelo nome:
+### 1. Story Development Cycle (SDC) — Principal
+
+O fluxo padrao para todo desenvolvimento:
 
 ```
-/sinapse            # Orquestrador principal
-@brand-orqx         # Squad de brand
-@copy-orqx          # Squad de copy
-@research-orqx      # Squad de research
+  Briefing
+     |
+  @sprint-lead *draft        [Cria story]
+     |
+  @product-lead *validate    [Valida com checklist de 10 pontos]
+     |
+  @developer *develop        [Implementa em YOLO/Interactive/Pre-Flight]
+     |
+  @quality-gate *qa-gate     [7 quality checks, verdict: PASS/FAIL]
+     |
+  @devops *push              [Push + PR com reviewer assignment]
 ```
 
-Ou use os agentes de desenvolvimento:
+### 2. QA Loop — Ciclo Iterativo
 
 ```
-@developer           # Implementacao de codigo
-@quality-gate        # Testes e qualidade
-@architect           # Arquitetura e design
-@sprint-lead         # Criacao de stories
-@product-lead        # Validacao de stories
-@project-lead        # Product management
-@analyst             # Pesquisa e analise
-@data-engineer       # Database design
-@devops              # CI/CD e git push (exclusivo)
+  @quality-gate review  -->  verdict
+         |                      |
+     APPROVE              REJECT --> @developer fix --> re-review
+         |                                              (max 5x)
+       Done
 ```
 
-### No Codex CLI
+### 3. Spec Pipeline — Pre-Implementacao
+
+Para features complexas que precisam de especificacao formal:
 
 ```
-/skills              # Lista todos os agentes disponiveis
-sinapse-dev          # Ativa o developer
-sinapse-architect    # Ativa o architect
+  Gather --> Assess --> Research --> Write Spec --> Critique --> Plan
+  (@pm)    (@arch)    (@analyst)     (@pm)        (@qa)      (@arch)
 ```
 
-### Comandos dos Agentes
+### 4. Brownfield Discovery — Avaliacao de Legado
+
+Avaliacao completa de 10 fases para projetos existentes, cobrindo arquitetura, database, frontend, technical debt e plano de acao.
 
-Dentro de qualquer agente, use `*` para comandos:
+---
+
+## Documentation-First Development
+
+Todo desenvolvimento no SINAPSE segue um pipeline de documentacao automatico. Isso e o Artigo III da Constitution — NON-NEGOTIABLE.
 
 ```
-*help                # Comandos disponiveis
-*create-story        # Criar story de desenvolvimento
-*task <nome>         # Executar task especifica
-*exit                # Sair do agente
+Briefing do usuario
+       |
+   Epic definida (ou existente identificada)
+       |
+   Story criada em docs/stories/ com:
+     - Acceptance criteria (Given/When/Then)
+     - Escopo definido (IN/OUT)
+     - Dependencias mapeadas
+     - Estimativa de complexidade
+       |
+   Story validada por @product-lead (status >= Ready)
+       |
+   Implementacao liberada
 ```
 
+Se voce pedir "implementa feature X", o SINAPSE cria a story primeiro, valida, e so entao implementa. Se voce pedir para pular a documentacao, o framework recusa. Sem excecoes.
+
 ---
 
-## Agentes de Desenvolvimento
-
-O SINAPSE vem com 12 agentes core para o ciclo completo de desenvolvimento:
-
-| Agente | Persona | Escopo |
-|--------|---------|--------|
-| `sinapse-orqx` | Imperator | Orquestrador principal de todos os squads |
-| `developer` | Dex | Implementacao de codigo |
-| `quality-gate` | Quinn | Testes, QA e quality gates |
-| `architect` | Aria | Arquitetura e design tecnico |
-| `project-lead` | Morgan | Product management e epics |
-| `product-lead` | Pax | Validacao de stories e backlog |
-| `sprint-lead` | River | Criacao de stories e sprints |
-| `analyst` | Alex | Pesquisa e analise de negocios |
-| `data-engineer` | Dara | Database design e migrations |
-| `ux-design-expert` | Uma | UX/UI design e experiencia |
-| `devops` | Gage | CI/CD, git push (exclusivo) |
-| `squad-creator` | - | Criacao de novos squads |
+## Chrome Brain
 
-### Workflow de Desenvolvimento
+Todos os agentes do SINAPSE podem controlar o Chrome em tempo real: navegar sites, auditar performance, extrair dados, preencher formularios.
 
+```bash
+# Verificar status
+sinapse chrome-brain status
+
+# Instalar/reinstalar
+sinapse chrome-brain install
 ```
-@sprint-lead cria story > @product-lead valida > @developer implementa > @quality-gate testa > @devops push
-```
+
+**No Claude Code:** auto-ativa por hooks. Zero configuracao manual.
+**No Codex CLI:** via MCP ou skill chrome-cdp.
+
+**Suporte:** macOS, Linux, Windows (Git Bash/WSL)
 
 ---
 
-## Documentation-First Development
+## Seguranca
+
+A seguranca e o Artigo X da Constitution — NON-NEGOTIABLE desde o primeiro commit.
+
+### 25 Deployment Blockers
+
+Nenhum projeto vai para producao sem passar por todos:
+
+- **Tier 1 (10 blockers absolutos):** RLS em toda tabela, zero API keys hardcoded, service_role nunca no frontend, MFA obrigatorio, APIs autenticadas, SQL parametrizado, sem vulnerabilidades critical/high, sem secrets no codebase, sem credenciais default, TLS obrigatorio.
 
-Todo desenvolvimento no SINAPSE segue o pipeline de documentacao automatico (NON-NEGOTIABLE):
+- **Tier 2 (7 blockers de compliance):** DPO designado, capacidade de notificacao de breach em 3 dias, mecanismo de consentimento, portal de direitos do titular, SCCs para transferencia internacional, protecao de dados de criancas, politica de privacidade publicada.
 
-1. **Epic definida** para cada iniciativa
-2. **Stories em** `docs/stories/` com acceptance criteria claros
-3. **Validacao** por @product-lead antes de qualquer codigo
-4. **Progresso rastreado** via checkboxes `[ ]` > `[x]`
-5. **File List** mantida atualizada na story
-6. **Quality gates** automaticos antes de merge
+- **Tier 3 (8 blockers operacionais):** Inventario de ativos, logging centralizado, plano de resposta a incidentes, verificacao de backup, vulnerability scanning, segmentacao de rede, avaliacao de vendors, SSL enforcement no database.
+
+### LGPD
+
+Compliance total com a Lei Geral de Protecao de Dados e parte do framework. Consentimento, direitos do titular, notificacao de breach, DPO — tudo documentado e enforced.
+
+Veja [SECURITY.md](SECURITY.md) para detalhes completos e politica de reporte de vulnerabilidades.
 
 ---
 
@@ -217,92 +343,59 @@ squads/meu-squad/
   workflows/            # Workflows do squad
 ```
 
-Use `@squad-creator` ou veja o [Guia de Squads](docs/guides/squads-guide.md).
+Use `@squad-creator` (Loom) para criacao guiada, ou veja o [Guia de Squads](docs/guides/squads-guide.md).
 
 ---
 
-## Claude Code vs Codex CLI — Comparativo Completo
-
-O SINAPSE funciona em ambas as IDEs. Ambas suportam a maioria das funcionalidades com abordagens diferentes.
-
-### Funcionalidades
-
-| Funcionalidade | Claude Code | Codex CLI | Notas |
-|---------------|:-----------:|:---------:|-------|
-| **18 squads com 175 agentes** | SIM | SIM | Identico em ambas |
-| **Knowledge bases por squad** | SIM | SIM | Identico em ambas |
-| **Tasks e workflows** | SIM | SIM | Identico em ambas |
-| **Documentation-First Development** | SIM | SIM | Identico em ambas |
-| **Agent commands (`*help`, `*task`)** | SIM | SIM | Identico em ambas |
-| **Squad awareness auto-routing** | SIM | SIM | Identico em ambas |
-| **NSN Mode (Never Say Never)** | SIM | SIM | Regra global em ambas |
-| **Chrome Brain (browser automation)** | SIM | SIM | Claude: hooks auto-launch. Codex: via MCP ou chrome-cdp-skill |
-| **MCP servers** | SIM | SIM | Claude: `~/.claude.json`. Codex: `config.toml` ou `codex mcp add` |
-| **Hooks (PreToolUse / PostToolUse)** | SIM | PARCIAL | Codex: so Bash tool, desabilitado no Windows |
-| **Agent handoff protocol** | SIM | SIM | Via instructions + skills em ambas |
-| **SYNAPSE context engine** | SIM | PARCIAL | Codex: via instructions.md + skills (sem regras dinamicas) |
-| **Skills system nativo** | NAO | SIM | Codex tem `$skill-name` com progressive disclosure |
-| **Multi-model (Claude + outros)** | NAO | SIM | Codex suporta qualquer modelo OpenAI |
-| **Subagents paralelos** | SIM | SIM | Codex: max 6 threads configuraveis |
-| **CI/CD non-interactive** | NAO | SIM | Codex: `codex exec` com `--json` |
-
-### Como Ativar Agentes
-
-| Acao | Claude Code | Codex CLI |
-|------|-------------|-----------|
-| Orquestrador principal | `/SINAPSE:agents:sinapse-orqx` | `@sinapse-orqx` ou `$sinapse-orqx` |
-| Squad de brand | `@brand-orqx` | `@brand-orqx` ou `$sinapse-brand` |
-| Squad de copy | `@copy-orqx` | `@copy-orqx` ou `$sinapse-copy` |
-| Developer | `@developer` | `@developer` ou `$sinapse-dev` |
-| Listar agentes | `@sinapse-orqx *help` | `/skills` |
-| Chrome Brain | Auto-ativa por prompt | `codex mcp add chrome-devtools` |
-
-### Onde Cada IDE Brilha
-
-**Claude Code** — Experiencia mais integrada:
-- Chrome Brain auto-ativa por hooks (zero configuracao manual)
-- Context engine injeta regras automaticamente por dominio e arquivo
-- Deny/allow rules protegem arquivos deterministicamente
-- Maior ecossistema de MCP servers (Figma, Supabase, Notion, etc.)
-
-**Codex CLI** — Mais flexivel e extensivel:
-- Skills nativas com `$skill-name` e progressive disclosure
-- Suporta qualquer modelo OpenAI (nao apenas Claude)
-- `codex exec` para automacao CI/CD sem interacao
-- Pode rodar como MCP server (outros agentes invocam Codex)
-- Profiles para alternar configuracoes rapidamente
-- Subagents com max 6 threads paralelos
-
-### Setup Chrome Brain no Codex CLI
+## Instalacao Detalhada
+
+### Requisitos
+
+- **Node.js 18+** (v20+ recomendado)
+- **Claude Code** e/ou **Codex CLI** instalados
+- **Git** configurado
+
+### Comandos
 
 ```bash
-# Adicionar Chrome DevTools MCP ao Codex
-codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+# Criar projeto novo com wizard interativo
+npx sinapse-ai init meu-projeto
 
-# OU instalar a skill chrome-cdp (conexao direta, sem Puppeteer)
-# pi install git:github.com/pasky/chrome-cdp-skill@v1.0.1
-```
+# Instalar em projeto existente
+cd seu-projeto && npx sinapse-ai install
+
+# Atualizar instalacao existente
+npx sinapse-ai@latest install
+
+# Diagnostico completo
+npx sinapse-ai doctor
+
+# Diagnostico com auto-fix
+npx sinapse-ai doctor --fix
 
-### Recomendacao
+# Informacoes do sistema
+npx sinapse-ai info
+
+# Remover instalacao
+npx sinapse-ai uninstall
+```
 
-> **Claude Code** para quem quer a experiencia mais integrada e automatizada — Chrome Brain auto-ativa, hooks rodam sozinhos, context engine injeta regras.
->
-> **Codex CLI** para quem quer flexibilidade de modelo, skills nativas, e automacao CI/CD — com setup manual minimo para Chrome Brain.
+O wizard detecta seu ambiente, configura a IDE selecionada, instala os squads e ativa o Chrome Brain automaticamente.
 
 ---
 
-## CLI
+## CLI Reference
 
 ```bash
-npx sinapse-ai init <projeto>      # Criar projeto
-npx sinapse-ai install             # Instalar no projeto atual
-npx sinapse-ai update              # Atualizar
-npx sinapse-ai doctor              # Diagnostico
-npx sinapse-ai doctor --fix        # Corrigir problemas
-npx sinapse-ai info                # Info do sistema
-npx sinapse-ai uninstall           # Remover
-sinapse chrome-brain install       # Instalar Chrome Brain
-sinapse chrome-brain status        # Status do Chrome Brain
+npx sinapse-ai init <nome>       # Criar projeto
+npx sinapse-ai install           # Instalar no projeto atual
+npx sinapse-ai update            # Atualizar framework
+npx sinapse-ai doctor            # Diagnostico do sistema
+npx sinapse-ai doctor --fix      # Diagnostico com correcao
+npx sinapse-ai info              # Informacoes do sistema
+npx sinapse-ai uninstall         # Remover framework
+sinapse chrome-brain install     # Instalar Chrome Brain
+sinapse chrome-brain status      # Status do Chrome Brain
 ```
 
 ---
@@ -316,27 +409,54 @@ npm test               # Testes
 npm run test:coverage  # Cobertura
 ```
 
-Pre-commit e pre-push hooks validam automaticamente.
+Pre-commit e pre-push hooks validam automaticamente antes de cada operacao.
 
 ---
 
-## Documentacao
+## Estrutura do Projeto
 
-| Recurso | Link |
-|---------|------|
-| Guia do Usuario | [docs/guides/user-guide.md](docs/guides/user-guide.md) |
-| Arquitetura | [docs/pt/architecture/](docs/pt/architecture/) |
-| Guia de Squads | [docs/guides/squads-guide.md](docs/guides/squads-guide.md) |
-| Primeiros Passos | [docs/getting-started.md](docs/getting-started.md) |
-| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
-| Principios | [docs/GUIDING-PRINCIPLES.md](docs/GUIDING-PRINCIPLES.md) |
+```
+sinapse-ai/
+  .sinapse-ai/              # Core do framework
+    core/                   # Modulos principais (orchestration, memory, permissions)
+    data/                   # Knowledge base, entity registry
+    development/            # Agents, tasks, templates, checklists, scripts
+    infrastructure/         # CI/CD templates, scripts
+  bin/                      # CLI executaveis (sinapse-init.js, sinapse.js)
+  docs/                     # Documentacao
+    stories/                # Development stories (active/, completed/)
+  packages/                 # Shared packages
+  squads/                   # Squad expansions
+  tests/                    # Testes
+```
+
+---
+
+## Claude Code vs Codex CLI
+
+Ambas as IDEs suportam o ecossistema completo. A escolha depende do seu fluxo de trabalho:
+
+| Funcionalidade | Claude Code | Codex CLI |
+|---------------|:-----------:|:---------:|
+| 18 squads, 175 agentes | SIM | SIM |
+| Knowledge bases, tasks, workflows | SIM | SIM |
+| Documentation-First Development | SIM | SIM |
+| Chrome Brain | Auto-launch via hooks | Via MCP ou skill |
+| Context engine dinamico | SIM | Parcial (via instructions) |
+| Hooks (19 ativos) | SIM | Parcial (Bash only) |
+| Skills nativas | NAO | SIM |
+| Multi-model | NAO | SIM |
+| CI/CD non-interactive | NAO | SIM (`codex exec`) |
+
+**Claude Code** para experiencia integrada e automatizada.
+**Codex CLI** para flexibilidade de modelo e automacao CI/CD.
 
 ---
 
 ## Contribuindo
 
 ```bash
-git clone https://github.com/SinapseAI/sinapse-ai.git
+git clone https://github.com/caioimori/sinapse-ai.git
 cd sinapse-ai && npm install
 ```
 
@@ -346,25 +466,31 @@ cd sinapse-ai && npm install
 4. Push (`git push origin feat/minha-feature`)
 5. Abra um Pull Request
 
-Veja [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes.
+Veja [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes completos sobre processo, code standards e guidelines.
 
 ---
 
 ## Legal
 
-| Doc | Link |
-|-----|------|
+| Documento | Link |
+|-----------|------|
 | Licenca | [MIT](LICENSE) |
-| Privacidade | [Privacy](docs/legal/privacy.md) |
-| Termos | [Terms](docs/legal/terms.md) |
-| Conduta | [Code of Conduct](CODE_OF_CONDUCT.md) |
-| Seguranca | [Security](docs/security.md) |
+| Privacidade | [Politica de Privacidade](docs/legal/privacy.md) |
+| Termos de Uso | [Termos](docs/legal/terms.md) |
+| Seguranca | [SECURITY.md](SECURITY.md) |
+| Codigo de Conduta | [Code of Conduct](CODE_OF_CONDUCT.md) |
+| Contribuicao | [CONTRIBUTING.md](CONTRIBUTING.md) |
 
 ---
 
-## Contribuidores
+## Maintainers
+
+- [@caioimori](https://github.com/caioimori) -- Lead Maintainer
+- [@Matheus-soier](https://github.com/Matheus-soier) -- Co-Maintainer
+
+---
 
-[![Contributors](https://contrib.rocks/image?repo=SinapseAI/sinapse-ai)](https://github.com/SinapseAI/sinapse-ai/graphs/contributors)
+[![Contributors](https://contrib.rocks/image?repo=caioimori/sinapse-ai)](https://github.com/caioimori/sinapse-ai/graphs/contributors)
 
 ---