sinapse-ai 9.3.0 → 9.5.0

package/LICENSE

@@ -1,34 +1,34 @@
-MIT License
-
-Copyright (c) 2025 BMad Code, LLC (BMad Method - original work)
-Copyright (c) 2025 Synkra AIOX Inc. (AIOX Framework - intermediate work)
-Copyright (c) 2025 SinapseAI Inc. (SINAPSE Framework - derivative work)
-
-Portions of this software were derived from works distributed under the
-MIT License by the copyright holders listed above. SINAPSE is NOT
-affiliated with, endorsed by, or sanctioned by any of the above parties.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-TRADEMARK NOTICE:
-BMad, BMad Method, and BMad Core are trademarks of BMad Code, LLC.
-These trademarks are NOT licensed under the MIT License. See the BMad Method
-TRADEMARK.md (https://github.com/bmad-code-org/BMAD-METHOD/blob/main/TRADEMARK.md)
-for detailed guidelines on trademark usage.
-
+MIT License
+
+Copyright (c) 2025 BMad Code, LLC (BMad Method - original work)
+Copyright (c) 2025 Synkra AIOX Inc. (AIOX Framework - intermediate work)
+Copyright (c) 2025 SinapseAI Inc. (SINAPSE Framework - derivative work)
+
+Portions of this software were derived from works distributed under the
+MIT License by the copyright holders listed above. SINAPSE is NOT
+affiliated with, endorsed by, or sanctioned by any of the above parties.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+BMad, BMad Method, and BMad Core are trademarks of BMad Code, LLC.
+These trademarks are NOT licensed under the MIT License. See the BMad Method
+TRADEMARK.md (https://github.com/bmad-code-org/BMAD-METHOD/blob/main/TRADEMARK.md)
+for detailed guidelines on trademark usage.
+

package/README.en.md

@@ -27,6 +27,16 @@ Unlike tools that just chat with AI, SINAPSE enforces discipline. The **Document
 
 ---
 
+## Why does SINAPSE exist?
+
+Generative AI has a known problem: the more you ask of it, the worse it gets. A single assistant trying to do everything -- code, copy, branding, testing, deployment -- loses context, invents features, and suffers from context amnesia after just a few long iterations.
+
+SINAPSE solves this the way human teams solve it: **coordinated specialization**. Instead of one tired generalist, you have 186 agents in 18 squads, each with a defined role, its own knowledge base, and executable tasks. An orchestrator routes your request to whoever actually knows how to solve it -- automatically, without you needing to memorize agent names or commands.
+
+The differential isn't just the quantity of agents. It's **real governance**: 19 active hooks intercept operations at runtime, a Constitution with 10 articles governs the framework, and 6 of those articles are NON-NEGOTIABLE -- violations are blocked before execution, not detected afterwards. **Speed with rigor, without choosing between the two.**
+
+---
+
 ## Quick Start
 
 ### 1. Install
@@ -54,6 +64,58 @@ Done. You have 18 squads operating in your terminal.
 
 ---
 
+## Why install in every project?
+
+Every first installation raises objections. All of them legitimate. Answered here, in the spirit of SINAPSE culture -- direct, no defensiveness.
+
+### "I'll have multiple copies on my computer. Isn't that wasteful?"
+
+No. Each project has its own `.sinapse-ai/` -- just like it has its own `package.json` or `node_modules/`. And this **isn't waste, it's isolation**.
+
+Real footprint: `.sinapse-ai/` weighs ~500KB. Twenty projects = 10MB. Smaller than a single `node_modules/` of a typical Next.js project (300MB+). The disk cost is marginal. The isolation gain is essential.
+
+### "Why not install once globally and be done with it?"
+
+Because open source projects need to be **self-contained**. When you share a project (or someone clones yours), the framework needs to travel with it.
+
+**With local installation:** `git clone` and you're done. Framework, rules, agents, Constitution, context -- everything comes with the project. Any person, any machine, any time: it works the same.
+
+**With global installation:** whoever clones the project has to install SINAPSE separately, ensure the same version, copy rules manually, and pray there's no drift between machines. Open source dies like that.
+
+### "What's the actual difference between global and local?"
+
+| Aspect | Global | Local (recommended) |
+|--------|:------:|:-------------------:|
+| Disk space | Smaller (1 copy) | Larger (~500KB/project) |
+| Per-project versioning | No | Yes |
+| Clone = working | No | Yes |
+| Project-specific custom rules | No | Yes |
+| Team collaboration | Broken | Perfect |
+| Update without breaking other projects | No | Yes |
+| Open source compatible | No | Yes |
+
+### "Does it work on Windows?"
+
+Yes. Tested on Windows 11, macOS, and Linux. The installer detects the OS automatically. WSL is not required (but recommended for advanced features like automated CodeRabbit review).
+
+### "How do I update without losing my customizations?"
+
+```bash
+npx sinapse-ai update
+```
+
+The update is **idempotent by design**. L1 (framework core) and L2 (templates) get updated. L3 (configuration) and L4 (your stories, packages, customizations) **are never touched**. You can run `update` as many times as you want, including after customizing rules locally. Nothing is lost.
+
+### TL;DR
+
+Local installation = a bit more disk, much more robustness.
+
+If you work alone and never share projects, global will technically work -- but the moment you join a team, publish open source, or need multiple versions in parallel, local becomes essential.
+
+SINAPSE optimizes for the generic case: **your project should work for anyone who clones it, on any machine, at any time**.
+
+---
+
 ## Architecture
 
 ### CLI First
@@ -68,6 +130,39 @@ All intelligence lives in the terminal. Dashboards observe. The UI is never requ
 
 SINAPSE separates framework and project artifacts into 4 layers with automatic protection:
 
+```mermaid
+graph TB
+    subgraph L4["L4 - PROJECT (always mutable)"]
+        L4A[Stories]
+        L4B[Packages]
+        L4C[Squads]
+        L4D[Tests]
+    end
+    subgraph L3["L3 - CONFIGURATION (restricted)"]
+        L3A[Entity Registry]
+        L3B[Agent Memory]
+        L3C[Config files]
+    end
+    subgraph L2["L2 - TEMPLATES (immutable)"]
+        L2A[Tasks]
+        L2B[Templates]
+        L2C[Checklists]
+        L2D[Workflows]
+    end
+    subgraph L1["L1 - FRAMEWORK CORE (immutable)"]
+        L1A[.sinapse-ai/core]
+        L1B[bin/]
+        L1C[Constitution]
+    end
+
+    L1 --> L2 --> L3 --> L4
+
+    style L1 fill:#0f172a,stroke:#ef4444,color:#fff
+    style L2 fill:#1e293b,stroke:#f59e0b,color:#fff
+    style L3 fill:#1e293b,stroke:#8b5cf6,color:#fff
+    style L4 fill:#1e293b,stroke:#10b981,color:#fff
+```
+
 | Layer | Mutability | Content |
 |-------|-----------|---------|
 | **L1** Framework Core | Never | `.sinapse-ai/core/`, `bin/`, Constitution |
@@ -75,7 +170,7 @@ SINAPSE separates framework and project artifacts into 4 layers with automatic p
 | **L3** Configuration | Restricted | Entity registry, agent memory, config |
 | **L4** Project | Always | Stories, packages, squads, tests |
 
-Deny rules in `.claude/settings.json` enforce this deterministically.
+Deny rules in `.claude/settings.json` enforce this deterministically. **Framework updates touch L1+L2, never L3+L4** — your customizations are preserved.
 
 ### Constitution
 
@@ -121,19 +216,25 @@ Activate any agent with `@agent-name` and use `*help` to see its commands.
 
 ### Development Workflow
 
-```
-@sprint-lead creates story
-       |
-@product-lead validates
-       |
-@developer implements
-       |
-@quality-gate tests
-       |
-@devops push + PR
+```mermaid
+flowchart LR
+    A([User briefing]) --> B[sprint-lead<br/>creates story]
+    B --> C{product-lead<br/>validates}
+    C -->|GO| D[developer<br/>implements]
+    C -->|NO-GO| B
+    D --> E{quality-gate<br/>tests}
+    E -->|PASS| F[devops<br/>push + PR]
+    E -->|FAIL| D
+    F --> G([Merged to main])
+
+    style B fill:#1e293b,stroke:#3b82f6,color:#fff
+    style C fill:#1e293b,stroke:#8b5cf6,color:#fff
+    style D fill:#1e293b,stroke:#10b981,color:#fff
+    style E fill:#1e293b,stroke:#f59e0b,color:#fff
+    style F fill:#1e293b,stroke:#ef4444,color:#fff
 ```
 
-The framework ensures no step is skipped.
+The framework ensures no step is skipped. Each gate blocks automatically if the previous one wasn't fulfilled.
 
 ---
 
@@ -208,6 +309,28 @@ Both IDEs have access to all 18 squads, 186 agents, workflows, and knowledge bas
 
 ---
 
+## Who is SINAPSE for?
+
+SINAPSE isn't for everyone. It's opinionated, rigorous, and demands discipline. But for those who need speed **with rigor**, it transforms generative AI from a toy into real infrastructure.
+
+### Ideal for
+
+- **Technical founders** building SaaS solo or in small teams who need to operate like a large team
+- **Consultants and agencies** delivering complete projects (brand + copy + dev + deploy) who need consistent quality across clients
+- **Product teams** who want to eliminate inconsistency between requirements, design, implementation, and QA
+- **Educators** teaching applied AI who need a real framework to demonstrate in class
+- **Independent builders** who treat AI as infrastructure, not as a toy
+
+### Not for
+
+- One-shot projects without continuity or process discipline
+- Teams that prefer total flexibility over governance
+- Users who expect "magic AI" without methodology
+
+If you identify with the first group, you're in the right place.
+
+---
+
 ## Quality and Security
 
 ### Constitutional Enforcement
@@ -257,16 +380,28 @@ Pre-commit and pre-push hooks validate automatically before each operation.
 
 ## CLI Reference
 
+The public surface is intentional -- four canonical lifecycle commands, two diagnostics, one advanced sub-command.
+
 ```bash
-npx sinapse-ai init <name>       # Create project
-npx sinapse-ai install           # Install in current project
-npx sinapse-ai update            # Update framework
-npx sinapse-ai doctor            # System diagnostics
-npx sinapse-ai doctor --fix      # Diagnostics with auto-fix
-npx sinapse-ai info              # System information
-npx sinapse-ai uninstall         # Remove framework
+# Lifecycle
+npx sinapse-ai install           # Install (idempotent -- re-runs are upserts)
+npx sinapse-ai install --force   # Reinstall from scratch, ignoring existing state
+npx sinapse-ai update            # Update to the latest version
+npx sinapse-ai uninstall         # Remove the framework from the project
+
+# Diagnostics
+npx sinapse-ai status            # Installation state + list of squads
+npx sinapse-ai doctor            # 12 health checks against the environment
+npx sinapse-ai doctor --fix      # Auto-fix detected issues
+npx sinapse-ai doctor --json     # Machine-readable output for CI
+npx sinapse-ai doctor --dry-run  # Show what `--fix` would do without applying
+
+# Advanced
+npx sinapse-ai chrome-brain install   # Install browser automation
 ```
 
+All commands are safe to re-run. To list active agents after installing, open Claude Code or Codex CLI and type `@` to autocomplete.
+
 ---
 
 ## Contributing
@@ -304,6 +439,18 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
 
 ---
 
-Built for builders.
+## Ready to start?
+
+```bash
+npx sinapse-ai install
+```
+
+One command. 18 squads. 186 agents. Constitutional governance. All operating directly in the terminal.
+
+**[Full documentation](docs/guides/getting-started.md)** • **[Report issue](https://github.com/caioimori/sinapse-ai/issues)** • **[Discussions](https://github.com/caioimori/sinapse-ai/discussions)**
+
+---
+
+**Built for builders. Governed by a Constitution. Operating 100% in the terminal.**
 
 **[Back to top](#sinapse-ai)**

package/README.md

@@ -2,6 +2,8 @@
 [![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)
+[![Tests](https://img.shields.io/badge/tests-10729%20passed-success)](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml)
+[![Constitution](https://img.shields.io/badge/Constitution-10%20articles-blueviolet)](.sinapse-ai/constitution.md)
 
 ```
  ____  ___ _   _    _    ____  ____  _____
@@ -27,6 +29,16 @@ Diferente de ferramentas que apenas conversam com IA, o SINAPSE impoe disciplina
 
 ---
 
+## Por que SINAPSE existe?
+
+IA generativa tem um problema conhecido: quanto mais voce pede, pior fica. Um unico assistente tentando fazer tudo — codigo, copy, branding, testes, deploy — perde contexto, inventa features e sofre de context amnesia depois de poucas iteracoes longas.
+
+SINAPSE resolve isso do jeito que times humanos resolvem: **especializacao coordenada**. Em vez de um generalista cansado, voce tem 186 agentes em 18 squads, cada um com papel definido, knowledge base propria e tasks executaveis. Um orquestrador roteia seu pedido para quem realmente sabe resolver — automaticamente, sem voce precisar decorar agent names ou comandos.
+
+O diferencial nao e apenas quantidade de agentes. E **governanca real**: 19 hooks ativos interceptam operacoes em tempo de execucao, uma Constitution com 10 artigos rege o framework, e 6 desses artigos sao NON-NEGOTIABLE — violacoes sao bloqueadas antes de executar, nao detectadas depois. **Velocidade com rigor, sem escolher entre os dois.**
+
+---
+
 ## Quick Start
 
 ### 1. Instale
@@ -35,14 +47,17 @@ Diferente de ferramentas que apenas conversam com IA, o SINAPSE impoe disciplina
 npx sinapse-ai install
 ```
 
-O wizard detecta seu ambiente, configura a IDE e instala os squads automaticamente.
+O wizard detecta seu ambiente, escolhe a IDE (Claude Code ou Codex), e instala os 18 squads automaticamente. Re-rodar o comando faz upsert idempotente — preserva suas customizacoes e so atualiza o que mudou.
 
 ### 2. Verifique
 
 ```bash
-npx sinapse-ai doctor
+npx sinapse-ai status   # Lista de squads + agentes instalados
+npx sinapse-ai doctor   # 12 health checks contra o ambiente
 ```
 
+Se algo estiver fora do lugar, `doctor --fix` corrige automaticamente.
+
 ### 3. Ative seu primeiro agente
 
 ```
@@ -52,6 +67,74 @@ npx sinapse-ai doctor
 
 Pronto. Voce tem 18 squads operando no seu terminal.
 
+> **Nota sobre `npm install`:** A partir da v10.0.0-rc.4, o SINAPSE roda um postinstall automatico que sincroniza agents para o Claude Code, cria os diretorios de runtime (`.sinapse/handoffs/`, `.sinapse/scratchpad/`) e executa um health check rapido. Para desabilitar (CI, pipelines avancadas), defina `SINAPSE_SKIP_POSTINSTALL=1` antes do `npm install`, ou rode `npm install --ignore-scripts` (comportamento nativo do npm — nenhum postinstall eh executado). Nesse caso, rode `sinapse doctor --fix` apos a instalacao para garantir que o ambiente esteja pronto.
+
+---
+
+## Por que instalar em cada projeto?
+
+Toda primeira instalacao levanta objecoes. Todas legitimas. Respondidas aqui, no espirito da cultura SINAPSE — direto, sem defensivo.
+
+### "Vou ter multiplas copias no computador. Nao e desperdicio?"
+
+Nao. Cada projeto tem seu proprio `.sinapse-ai/` — assim como tem seu proprio `package.json` ou `node_modules/`. E isso **nao e desperdicio, e isolamento**.
+
+Tamanho real: `.sinapse-ai/` pesa ~500KB. Vinte projetos = 10MB. Menor que um unico `node_modules/` de um projeto Next.js tipico (300MB+). O custo de espaco e marginal. O ganho de isolamento e essencial.
+
+### "Por que nao instalar uma vez global e pronto?"
+
+Porque projetos open source precisam ser **auto-contidos**. Quando voce compartilha um projeto (ou alguem clona o seu), o framework precisa viajar junto.
+
+**Com instalacao local:** `git clone` e pronto. Framework, rules, agentes, Constitution, contexto — tudo ja vem no projeto. Qualquer pessoa, qualquer maquina, qualquer horario: funciona igual.
+
+**Com instalacao global:** quem clona o projeto precisa instalar SINAPSE separado, garantir a mesma versao, copiar rules manualmente, torcer pra nao ter drift entre maquinas. Open source morre assim.
+
+### "Qual a diferenca real entre global e local?"
+
+| Aspecto | Global | Local (recomendado) |
+|---------|:------:|:-------------------:|
+| Espaco em disco | Menor (1 copia) | Maior (~500KB/projeto) |
+| Versionamento per-project | Nao | Sim |
+| Clone e funcionando | Nao | Sim |
+| Rules customizadas por projeto | Nao | Sim |
+| Colaboracao em time | Quebrada | Perfeita |
+| Atualizar sem quebrar outros projetos | Nao | Sim |
+| Open source compativel | Nao | Sim |
+
+### "Funciona no Windows?"
+
+Sim. Testado em Windows 11, macOS e Linux. O instalador detecta o OS automaticamente. WSL nao e obrigatorio (mas recomendado para algumas features avancadas como review automatizado via CodeRabbit).
+
+### Matriz de plataformas suportadas
+
+Cada release passa por uma matriz de instalacao de 27 combinacoes (3 OSes x 3 package managers x 3 metodos) executada em CI. A tabela abaixo resume os caminhos oficialmente suportados:
+
+| OS | npm | pnpm | Yarn v2+ (Berry) | Yarn v1 (Classic) |
+|----|:---:|:----:|:----------------:|:-----------------:|
+| Windows 11 | Sim | Sim | Sim | **Nao** |
+| macOS (latest) | Sim | Sim | Sim | Sim |
+| Linux (Ubuntu 22.04) | Sim | Sim | Sim | Sim |
+
+**Sobre Yarn v1 no Windows:** Yarn v1 (Classic) esta em modo manutencao desde 2020, com Yarn v2+ (Berry) como sucessor oficial. A combinacao Windows + Yarn v1 apresenta falhas de resolucao de wrapper que nao compensam investigar por ser ecossistema em declinio. Usuarios Windows em Yarn v1 devem migrar para Yarn v2+ (recomendado) ou usar npm/pnpm. macOS e Linux em Yarn v1 continuam suportados.
+
+Registro completo da decisao e resultados: [docs/audits/install-matrix-2026-04-16.md](docs/audits/install-matrix-2026-04-16.md).
+
+### "Como atualizar sem perder minhas customizacoes?"
+
+```bash
+npx sinapse-ai update
+```
+
+O update e **idempotente por design**. L1 (framework core) e L2 (templates) sao atualizados. L3 (configuracao) e L4 (suas stories, packages, customizacoes) **nunca sao tocados**. Voce pode rodar `update` quantas vezes quiser, inclusive apos customizar rules localmente. Nada se perde.
+
+### TL;DR
+
+Instalacao local = um pouco mais de disco, muito mais robustez.
+
+Se voce trabalha sozinho e nunca compartilha projetos, global ate funciona — mas assim que voce entra em time, publica open source ou precisa de multiplas versoes em paralelo, local vira imprescindivel.
+
+O SINAPSE otimiza para o caso generico: **seu projeto deve funcionar para qualquer pessoa que clone ele, em qualquer maquina, a qualquer hora**.
+
 ---
 
 ## Arquitetura
@@ -68,6 +151,39 @@ Toda inteligencia vive no terminal. Dashboards observam. A UI nunca e requisito
 
 O SINAPSE separa artefatos do framework e do projeto em 4 camadas com protecao automatica:
 
+```mermaid
+graph TB
+    subgraph L4["L4 - PROJETO (sempre mutavel)"]
+        L4A[Stories]
+        L4B[Packages]
+        L4C[Squads]
+        L4D[Tests]
+    end
+    subgraph L3["L3 - CONFIGURACAO (com restricoes)"]
+        L3A[Entity Registry]
+        L3B[Agent Memory]
+        L3C[Config files]
+    end
+    subgraph L2["L2 - TEMPLATES (imutavel)"]
+        L2A[Tasks]
+        L2B[Templates]
+        L2C[Checklists]
+        L2D[Workflows]
+    end
+    subgraph L1["L1 - FRAMEWORK CORE (imutavel)"]
+        L1A[.sinapse-ai/core]
+        L1B[bin/]
+        L1C[Constitution]
+    end
+
+    L1 --> L2 --> L3 --> L4
+
+    style L1 fill:#0f172a,stroke:#ef4444,color:#fff
+    style L2 fill:#1e293b,stroke:#f59e0b,color:#fff
+    style L3 fill:#1e293b,stroke:#8b5cf6,color:#fff
+    style L4 fill:#1e293b,stroke:#10b981,color:#fff
+```
+
 | Camada | Mutabilidade | Conteudo |
 |--------|-------------|----------|
 | **L1** Framework Core | Nunca | `.sinapse-ai/core/`, `bin/`, Constitution |
@@ -75,7 +191,7 @@ O SINAPSE separa artefatos do framework e do projeto em 4 camadas com protecao a
 | **L3** Configuracao | Com restricoes | Entity registry, agent memory, config |
 | **L4** Projeto | Sempre | Stories, packages, squads, testes |
 
-Deny rules em `.claude/settings.json` reforcam isso deterministicamente.
+Deny rules em `.claude/settings.json` reforcam isso deterministicamente. **Update do framework atualiza L1+L2, nunca L3+L4** — suas customizacoes sao preservadas.
 
 ### Constitution
 
@@ -121,19 +237,25 @@ Ative qualquer agente com `@agent-name` e use `*help` para ver seus comandos.
 
 ### Workflow de Desenvolvimento
 
-```
-@sprint-lead cria story
-       |
-@product-lead valida
-       |
-@developer implementa
-       |
-@quality-gate testa
-       |
-@devops push + PR
+```mermaid
+flowchart LR
+    A([User briefing]) --> B[sprint-lead<br/>cria story]
+    B --> C{product-lead<br/>valida}
+    C -->|GO| D[developer<br/>implementa]
+    C -->|NO-GO| B
+    D --> E{quality-gate<br/>testa}
+    E -->|PASS| F[devops<br/>push + PR]
+    E -->|FAIL| D
+    F --> G([Merged em main])
+
+    style B fill:#1e293b,stroke:#3b82f6,color:#fff
+    style C fill:#1e293b,stroke:#8b5cf6,color:#fff
+    style D fill:#1e293b,stroke:#10b981,color:#fff
+    style E fill:#1e293b,stroke:#f59e0b,color:#fff
+    style F fill:#1e293b,stroke:#ef4444,color:#fff
 ```
 
-O framework garante que nenhuma etapa seja pulada.
+O framework garante que nenhuma etapa seja pulada. Cada gate bloqueia automaticamente se a anterior nao foi cumprida.
 
 ---
 
@@ -208,6 +330,28 @@ Ambas as IDEs tem acesso a todos os 18 squads, 186 agentes, workflows e knowledg
 
 ---
 
+## Para quem e o SINAPSE?
+
+O SINAPSE nao e para todo mundo. Ele e opinativo, rigoroso e exige disciplina. Mas para quem precisa de velocidade **com rigor**, ele transforma IA generativa de brinquedo em infraestrutura real.
+
+### Ideal para
+
+- **Founders tecnicos** que constroem SaaS sozinho ou em times pequenos e precisam operar como um time grande
+- **Consultores e agencias** que entregam projetos completos (brand + copy + dev + deploy) e precisam de qualidade consistente entre clientes
+- **Teams de produto** que querem eliminar inconsistencia entre requisitos, design, implementacao e QA
+- **Educadores** que ensinam IA aplicada e precisam de um framework real para demonstrar em aula
+- **Builders independentes** que tratam IA como infraestrutura, nao como brinquedo
+
+### Nao e para
+
+- Projetos one-shot sem continuidade ou disciplina processual
+- Equipes que preferem flexibilidade total sobre governanca
+- Usuarios que esperam "IA magica" sem metodologia
+
+Se voce se identifica com o primeiro grupo, voce esta no lugar certo.
+
+---
+
 ## Qualidade e Seguranca
 
 ### Enforcement Constitucional
@@ -257,16 +401,28 @@ Pre-commit e pre-push hooks validam automaticamente antes de cada operacao.
 
 ## CLI Reference
 
+A superficie publica e proposital — quatro comandos canonicos de lifecycle, dois diagnosticos, um sub-comando avancado.
+
 ```bash
-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
+# Lifecycle
+npx sinapse-ai install           # Instala (idempotente — re-runs sao upserts)
+npx sinapse-ai install --force   # Reinstala do zero, ignorando estado existente
+npx sinapse-ai update            # Atualiza para a versao mais recente
+npx sinapse-ai uninstall         # Remove o framework do projeto
+
+# Diagnostico
+npx sinapse-ai status            # Estado da instalacao + lista de squads
+npx sinapse-ai doctor            # 12 health checks contra o ambiente
+npx sinapse-ai doctor --fix      # Auto-corrige problemas detectados
+npx sinapse-ai doctor --json     # Saida machine-readable para CI
+npx sinapse-ai doctor --dry-run  # Mostra o que `--fix` faria sem aplicar
+
+# Avancado
+npx sinapse-ai chrome-brain install   # Instala browser automation
 ```
 
+Todos os comandos sao seguros para re-rodar. Para listar agentes ativos depois de instalar, abra Claude Code ou Codex CLI e digite `@` para autocompletar.
+
 ---
 
 ## Contribuindo
@@ -304,6 +460,18 @@ Veja [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes completos.
 
 ---
 
-Construido para quem constroi.
+## Pronto para comecar?
+
+```bash
+npx sinapse-ai install
+```
+
+Um comando. 18 squads. 186 agentes. Governanca constitucional. Tudo operando direto no terminal.
+
+**[Documentacao completa](docs/guides/getting-started.md)** • **[Reportar issue](https://github.com/caioimori/sinapse-ai/issues)** • **[Discussions](https://github.com/caioimori/sinapse-ai/discussions)**
+
+---
+
+**Construido para quem constroi. Governado por uma Constitution. Operando 100% no terminal.**
 
 **[Voltar ao topo](#sinapse-ai)**