sinapse-ai 1.25.1 → 1.25.3

package/docs/pt/guides/user-guide.md

@@ -48,13 +48,15 @@ cd my-project
 # Liste agentes disponíveis
 npx sinapse-ai agents list
 
-# Ative um agente
+# Claude Code: ative um agente
 @developer
 
 # Obtenha ajuda
 *help
 ```
 
+No Codex, use `$snps` para roteamento ou `$sinapse-agent developer` para ativação direta.
+
 ---
 
 ## Conceitos Fundamentais
@@ -72,7 +74,7 @@ O SINAPSE fornece estrutura orquestrada enquanto permite flexibilidade na comuni
 
 | Desenvolvimento Tradicional com IA | SINAPSE                                        |
 | ---------------------------------- | ------------------------------------------- |
-| Agentes descoordenados             | 11 agentes especializados com papéis claros |
+| Agentes descoordenados             | 172 agentes especializados em 17 squads     |
 | Resultados inconsistentes          | Workflows estruturados com quality gates    |
 | Contexto perdido entre sessões     | Memória persistente e aprendizado           |
 | Reinventando a roda                | Tasks, workflows e squads reutilizáveis     |
@@ -81,7 +83,10 @@ O SINAPSE fornece estrutura orquestrada enquanto permite flexibilidade na comuni
 
 ## Agentes
 
-O SINAPSE inclui 11 agentes especializados, cada um com papel e personalidade distintos:
+O SINAPSE inclui 172 agentes especializados em 17 squads. A tabela abaixo destaca os agentes core de desenvolvimento:
+
+Os IDs da tabela usam a sintaxe `@agent-name` do Claude Code. No Codex, use
+`$sinapse-agent agent-id`; para o orquestrador principal, use `$snps`.
 
 | Agente    | ID               | Arquétipo    | Responsabilidade          |
 | --------- | ---------------- | ------------ | ------------------------- |
@@ -100,7 +105,7 @@ O SINAPSE inclui 11 agentes especializados, cada um com papel e personalidade di
 ### Ativação de Agentes
 
 ```bash
-# Ative um agente usando sintaxe @
+# Claude Code: ative um agente usando sintaxe @
 @developer                # Ativar Pixel (Desenvolvedor)
 @quality-gate                 # Ativar Litmus (QA)
 @architect          # Ativar Stratum (Arquiteto)
@@ -112,6 +117,13 @@ O SINAPSE inclui 11 agentes especializados, cada um com papel e personalidade di
 *exit               # Desativar agente
 ```
 
+Ativação no Codex:
+
+```text
+$snps
+$sinapse-agent developer
+```
+
 ### Contexto do Agente
 
 Quando um agente está ativo:
@@ -336,16 +348,15 @@ NODE_ENV=development
 SINAPSE_DEBUG=false
 ```
 
-### Integração com IDE
+### Integração com Provedores
 
-O SINAPSE suporta múltiplas IDEs. A configuração é sincronizada entre:
+O SINAPSE sincroniza os mesmos agentes canônicos para os dois provedores suportados:
 
-- Claude Code (`.claude/`)
-- Cursor (`.cursor/`)
-- VS Code (`.vscode/`)
+- Agentes do Claude Code: `.claude/agents/` (ative com `@developer`)
+- Agentes e skills do Codex: `.codex/agents/` e `.agents/skills/` (ative com `$snps` ou `$sinapse-agent developer`)
 
 ```bash
-# Sincronizar agentes para sua IDE
+# Sincronizar adapters do Claude Code e Codex
 npm run sync:ide
 ```
 
@@ -468,4 +479,3 @@ construir um agente novo do zero.
 ---
 
 _Guia do Usuário SINAPSE v1.21.0_
-

package/docs/pt/installation/README.md

@@ -86,10 +86,8 @@ npx sinapse-ai install --force-upgrade
 
 | IDE            | Ativação de Agentes |
 | -------------- | ------------------- |
-| Claude Code    | `/dev`, `/qa`, etc. |
-| Cursor         | `@dev`, `@qa`, etc. |
-| Gemini CLI     | Menção no prompt    |
-| GitHub Copilot | Modos de chat       |
+| Claude Code    | `@developer`, `@quality-gate`, etc. |
+| Codex CLI      | `$snps` ou `$sinapse-agent <id>` |
 
 ---
 

package/docs/pt/installation/faq.md

@@ -83,11 +83,11 @@ npx sinapse-ai install
 O instalador irá:
 
 - Criar o diretório `.sinapse-ai/` (arquivos do framework)
-- Criar configuração de IDE (`.claude/`, `.cursor/`, etc.)
+- Criar adapters do Claude Code e Codex (`.claude/`, `.codex/` e `.agents/skills/`)
 - NÃO modificar seu código-fonte existente
 - NÃO sobrescrever documentação existente a menos que você escolha
 
-**Importante:** Se você tiver um diretório `.claude/` ou `.cursor/` existente, o instalador perguntará antes de modificar.
+**Importante:** Diretórios existentes dos provedores são reconciliados de forma conservadora; mantenha arquivos customizados fora dos nomes gerenciados pelo framework.
 
 ---
 
@@ -114,29 +114,26 @@ Fatores que afetam o tempo de instalação:
 
 **Resposta:** O SINAPSE cria a seguinte estrutura:
 
-```
+```text
 your-project/
-├── .sinapse-ai/                 # Core do framework (200+ arquivos)
-│   ├── agents/                 # 11+ definições de agentes
-│   ├── tasks/                  # 60+ workflows de tarefas
-│   ├── templates/              # 20+ templates de documentos
-│   ├── checklists/             # Checklists de validação
-│   ├── scripts/                # Scripts utilitários
-│   └── core-config.yaml        # Configuração do framework
+├── .sinapse-ai/                 # Runtime, configuração e assets de desenvolvimento
+│   └── core-config.yaml         # Configuração do framework
 │
 ├── .claude/                    # Claude Code (se selecionado)
-│   └── agents/                    # Agentes nativos do Claude
+│   ├── agents/                 # Adapters de agentes nativos do Claude
+│   └── skills/                 # Skills do Claude Code
+│
+├── .codex/                     # Codex (se selecionado)
+│   └── agents/                 # Descritores de agentes nativos do Codex
 │
-├── .cursor/                    # Cursor (se selecionado)
-│   └── rules/                  # Regras de agentes
+├── .agents/skills/             # Skills SINAPSE compatíveis com Codex
 │
 ├── docs/                       # Estrutura de documentação
 │   ├── stories/                # Stories de desenvolvimento
 │   ├── architecture/           # Docs de arquitetura
 │   └── prd/                    # Requisitos de produto
 │
-└── Squads/            # (se instalado)
-    └── squad-brand/             # Pack HybridOps
+└── squads/                      # 17 squads e seus assets
 ```
 
 ---
@@ -231,7 +228,7 @@ mv .sinapse-ai.backup .sinapse-ai
 npx sinapse-ai install
 
 # Empacotar para uso offline
-tar -czvf sinapse-offline.tar.gz .sinapse-ai/ .claude/ .cursor/
+tar -czvf sinapse-offline.tar.gz .sinapse-ai/ .claude/ .codex/ .agents/ squads/
 ```
 
 **Na máquina air-gapped:**
@@ -262,7 +259,7 @@ tar -xzvf sinapse-offline.tar.gz
    # Instalar e empacotar
    npx sinapse-ai install
    cd your-project
-   tar -czvf sinapse-transfer.tar.gz .sinapse-ai/ .claude/ .cursor/ docs/
+   tar -czvf sinapse-transfer.tar.gz .sinapse-ai/ .claude/ .codex/ .agents/ squads/ docs/
    ```
 
 2. **Transferir o arquivo** via USB, transferência segura, etc.
@@ -286,36 +283,23 @@ tar -xzvf sinapse-offline.tar.gz
 
 | IDE                | Status         | Ativação de Agentes |
 | ------------------ | -------------- | ------------------- |
-| **Claude Code**    | Suporte Completo | `/dev`, `/qa`, etc. |
-| **Cursor**         | Suporte Completo | `@dev`, `@qa`, etc. |
-| **Gemini CLI**     | Suporte Completo | Menção no prompt    |
-| **GitHub Copilot** | Suporte Completo | Modos de chat       |
-
-**Adicionar suporte para uma nova IDE:** Abra uma issue no GitHub com a especificação de agentes/regras da IDE.
+| **Claude Code**    | Suporte Completo | `@developer`, `@quality-gate`, etc. |
+| **Codex CLI**      | Suporte Completo | `$snps` ou `$sinapse-agent <id>` |
 
 ---
 
 ### Q12: Posso configurar o SINAPSE para múltiplas IDEs?
 
-**Resposta:** Sim! Selecione múltiplas IDEs durante a instalação:
-
-**Interativo:**
-
-```
-? Which IDE(s) do you want to configure?
-❯ ◉ Cursor
-  ◉ Claude Code
-```
-
-**Linha de comando:**
-
-```bash
-```
+**Resposta:** Sim. Claude Code e Codex podem usar a mesma instalação canônica
+do SINAPSE. Execute `npx sinapse-ai install`; o instalador gera os adapters
+nativos de cada provedor:
 
-Cada IDE recebe seu próprio diretório de configuração:
+- Agentes do Claude Code: `.claude/agents/`
+- Agentes do Codex: `.codex/agents/`
+- Skills do Codex: `.agents/skills/`
 
-- `.cursor/rules/` para Cursor
-- `.claude/commands/` para Claude Code
+Ative com `@developer` no Claude Code ou `$sinapse-agent developer` no Codex.
+Use `$snps` no Codex quando quiser que o orquestrador principal roteie o pedido.
 
 ---
 
@@ -330,8 +314,8 @@ Se `.sinapse-ai/` está commitado no seu repositório:
 git clone your-repo
 cd your-repo
 
-# Opcionalmente configurar a IDE preferida
-npx sinapse-ai install --ide cursor
+# Gerar ou reconciliar os adapters do Claude Code e Codex
+npx sinapse-ai install
 ```
 
 Se `.sinapse-ai/` não está commitado:
@@ -350,55 +334,36 @@ npx sinapse-ai install
 
 ### Q14: Quais agentes estão incluídos?
 
-**Resposta:** O SINAPSE inclui 11+ agentes especializados:
-
-| Agente          | Papel                    | Melhor Para                           |
-| --------------- | ------------------------ | ------------------------------------- |
-| `dev`           | Desenvolvedor Full-Stack | Implementação de código, debugging    |
-| `qa`            | Engenheiro de QA         | Testes, code review                   |
-| `architect`     | Arquiteto de Sistema     | Design, decisões de arquitetura       |
-| `pm`            | Gerente de Projeto       | Planejamento, acompanhamento          |
-| `po`            | Product Owner            | Backlog, requisitos                   |
-| `sm`            | Scrum Master             | Facilitação, gestão de sprints        |
-| `analyst`       | Analista de Negócios     | Análise de requisitos                 |
-| `ux-expert`     | Designer UX              | Design de experiência do usuário      |
-| `data-engineer` | Engenheiro de Dados      | Pipelines de dados, ETL               |
-| `devops`        | Engenheiro DevOps        | CI/CD, deployment                     |
-| `db-sage`       | Arquiteto de Banco       | Design de schema, queries             |
+**Resposta:** O SINAPSE inclui **172 agentes em 17 squads**. A camada de squads
+reúne 160 membros e a camada do framework reúne 12. O conjunto do framework é:
+
+| Agente | Persona | Papel |
+| ------ | ------- | ----- |
+| `snps-orqx` | Imperator | Orquestrador principal cross-squad |
+| `developer` | Pixel | Implementação full-stack e debugging |
+| `quality-gate` | Litmus | Testes, revisão e quality gates |
+| `architect` | Stratum | Arquitetura e decisões de tecnologia |
+| `project-lead` | Beacon | Product management e epics |
+| `product-lead` | Axis | Validação de stories e priorização |
+| `sprint-lead` | Sync | Criação de stories e facilitação de sprints |
+| `analyst` | Scope | Pesquisa e análise de negócios |
+| `data-engineer` | Tensor | Database design, migrations e RLS |
+| `ux-design-expert` | Mosaic | UX/UI e design systems |
+| `devops` | Pipeline | CI/CD, autoridade exclusiva de push e releases |
+| `squad-creator` | Loom | Criação e extensão de squads |
+
+No Claude Code, ative um agente com `@agent-id`. No Codex, use `$snps` para
+roteamento ou `$sinapse-agent agent-id` para ativação direta. Os dois provedores
+resolvem as mesmas fontes canônicas de agentes e tasks.
 
 ---
 
 ### Q15: Como crio um agente customizado?
 
-**Resposta:**
-
-1. **Copie um agente existente:**
-
-   ```bash
-   cp .sinapse-ai/agents/developer.md .sinapse-ai/agents/my-agent.md
-   ```
-
-2. **Edite o frontmatter YAML:**
-
-   ```yaml
-   agent:
-     name: MyAgent
-     id: my-agent
-     title: My Custom Agent
-     icon: 🔧
-
-   persona:
-     role: Expert in [your domain]
-     style: [communication style]
-   ```
-
-3. **Adicione à configuração da IDE:**
-
-   ```bash
-   npx sinapse-ai install --ide claude-code
-   ```
-
-4. **Ative:** `/my-agent` ou `@my-agent`
+**Resposta:** Mantenha os agentes do framework imutáveis e crie extensões pelo
+workflow de squads. No Claude Code, ative `@squad-creator`; no Codex, use
+`$sinapse-agent squad-creator`. Depois de validar a definição, execute
+`npx sinapse-ai@latest install --reconfigure` para regenerar os adapters.
 
 ---
 
@@ -411,10 +376,10 @@ npx sinapse-ai install
 - Registra todas as decisões em `.ai/decision-log-{story-id}.md`
 - Pode ser parado a qualquer momento
 
-**Habilitar yolo mode:**
+**Habilitar yolo mode:** Ative `@developer` no Claude Code ou
+`$sinapse-agent developer` no Codex e execute:
 
-```bash
-/dev
+```text
 *develop-yolo docs/stories/your-story.md
 ```
 

package/docs/pt/installation/linux.md

@@ -161,9 +161,9 @@ O instalador automaticamente:
 
 - ✅ Detecta sua distribuição Linux e aplica otimizações
 - ✅ Cria diretórios necessários com permissões Unix apropriadas (755/644)
-- ✅ Configura caminhos de IDE para Linux:
-  - Cursor: `~/.config/Cursor/`
-  - Claude: `~/.claude/`
+- ✅ Configura adapters dos provedores no projeto:
+  - Agentes do Claude Code: `.claude/agents/`
+  - Agentes e skills do Codex: `.codex/agents/` e `.agents/skills/`
 - ✅ Configura scripts shell com terminações de linha Unix (LF)
 - ✅ Respeita a especificação XDG Base Directory
 - ✅ Lida com links simbólicos corretamente
@@ -172,33 +172,15 @@ O instalador automaticamente:
 
 ## Configuração Específica por IDE
 
-### Cursor
+### Claude Code
 
-1. Instale o Cursor: Baixe de [cursor.sh](https://cursor.sh/)
-
-   ```bash
-   # Método AppImage
-   chmod +x cursor-*.AppImage
-   ./cursor-*.AppImage
-   ```
-
-2. Regras da IDE são instaladas em `.cursor/rules/`
-3. Atalho de teclado: `Ctrl+L` para abrir chat
-4. Use `@nome-do-agente` para ativar agentes
-
-### Claude Code (CLI)
-
-1. Instale o Claude Code:
-
-   ```bash
-   npm install -g @anthropic-ai/claude-code
-   ```
-
-2. Comandos são instalados em `.claude/commands/SINAPSE/`
-3. Use `/nome-do-agente` para ativar agentes
+1. Os adapters de agentes são instalados em `.claude/agents/`.
+2. Use `@developer` ou outro ID canônico para ativar um agente.
 
+### Codex
 
-3. Use `@nome-do-agente` para ativar agentes
+1. Os descritores são instalados em `.codex/agents/`, com skills em `.agents/skills/`.
+2. Use `$snps` para roteamento ou `$sinapse-agent developer` para ativação direta.
 
 ---
 

package/docs/pt/installation/macos.md

@@ -81,27 +81,23 @@ O instalador automaticamente:
 
 - Detecta o macOS e aplica configurações específicas da plataforma
 - Cria os diretórios necessários com permissões apropriadas
-- Configura caminhos de IDE para localizações do macOS:
-  - Cursor: `~/Library/Application Support/Cursor/`
-  - Claude: `~/.claude/`
+- Configura adapters dos provedores no projeto:
+  - Agentes do Claude Code: `.claude/agents/`
+  - Agentes e skills do Codex: `.codex/agents/` e `.agents/skills/`
 - Configura scripts shell com terminações de linha Unix
 - Lida adequadamente com sistemas de arquivos case-sensitive
 
 ## Configuração Específica por IDE
 
-### Cursor
-
-1. As regras da IDE são instaladas em `.cursor/rules/`
-2. Atalho de teclado: `Cmd+L` para abrir o chat
-3. Use `@agent-name` para ativar agentes
-
 ### Claude Code
 
-1. Os comandos são instalados em `.claude/commands/SINAPSE/`
-2. Use `/agent-name` para ativar agentes
+1. Os adapters de agentes são instalados em `.claude/agents/`.
+2. Use `@developer` ou outro ID canônico para ativar um agente.
 
+### Codex
 
-2. Use `@agent-name` para ativar agentes
+1. Os descritores são instalados em `.codex/agents/`, com skills em `.agents/skills/`.
+2. Use `$snps` para roteamento ou `$sinapse-agent developer` para ativação direta.
 
 ## Solução de Problemas
 

package/docs/pt/installation/troubleshooting.md

@@ -545,7 +545,8 @@ nvm use 16
 
 ### Problema 20: "Agents not appearing in IDE"
 
-**Sintomas:** Comandos de agentes (`/dev`, `@dev`) não funcionam após instalação.
+**Sintomas:** A ativação nativa (`@developer` no Claude Code ou
+`$sinapse-agent developer` no Codex) não funciona após a instalação.
 
 **Solução:**
 
@@ -556,8 +557,9 @@ nvm use 16
    # Claude Code
    ls .claude/agents/
 
-   # Cursor
-   ls .cursor/rules/
+   # Codex
+   ls .codex/agents/
+   ls .agents/skills/
    ```
 
 3. Verifique se as configurações da IDE permitem comandos customizados
@@ -574,10 +576,10 @@ nvm use 16
 
 **Solução:**
 
-1. Verifique se a versão da IDE é compatível
-2. Para Cursor: Certifique-se que os arquivos têm extensão `.mdc`
-3. Para Claude Code: Agentes nativos devem estar em `.claude/agents/`; `.claude/commands/` serve apenas para slash commands
-4. Reinicie a IDE após a instalação
+1. Verifique se a versão do provedor é compatível.
+2. Para Claude Code, os agentes nativos devem estar em `.claude/agents/`.
+3. Para Codex, verifique `.codex/agents/` e `.agents/skills/`.
+4. Reinicie o provedor após a instalação.
 
 ---
 
@@ -698,7 +700,7 @@ ls -la .sinapse-ai/
 - SO: [Windows 11 / macOS 14 / Ubuntu 22.04]
 - Versão Node.js: [saída de `node --version`]
 - Versão npm: [saída de `npm --version`]
-- IDE: [Claude Code / Cursor / etc.]
+- Provedor: [Claude Code / Codex CLI]
 
 **Passos para Reproduzir:**
 1. [Primeiro passo]

package/docs/pt/installation/v4-quick-start.md

@@ -109,24 +109,24 @@ Digite *help para ver comandos disponíveis.
 
 ## Passo 4: Explorar Agentes Disponíveis
 
-| Agente              | Ativação             | Propósito                          |
+| Ativação            | Papel                | Propósito                          |
 | ------------------- | -------------------- | ---------------------------------- |
-| `@dev` (Dex)        | Desenvolvimento      | Implementação de código, debugging |
-| `@qa` (Quinn)       | Qualidade            | Testes e validação                 |
-| `@architect` (Aria) | Arquitetura          | Design de sistema e documentação   |
-| `@pm` (Sage)        | Product Manager      | Requisitos e planejamento          |
-| `@devops` (Gage)    | DevOps               | Git push, criação de PR, CI/CD     |
-| `@po` (Maven)       | Product Owner        | Criação de stories e backlog       |
-| `@sm` (River)       | Scrum Master         | Gerenciamento de sprint            |
-| `@analyst` (Nova)   | Analista de Negócios | Análise de requisitos              |
+| `@developer` (Pixel)     | Desenvolvimento    | Implementação de código, debugging |
+| `@quality-gate` (Litmus) | Qualidade          | Testes e validação                 |
+| `@architect` (Stratum)   | Arquitetura        | Design de sistema e documentação   |
+| `@project-lead` (Beacon) | Product Manager    | Requisitos e planejamento          |
+| `@devops` (Pipeline)     | DevOps             | Git push, criação de PR, CI/CD     |
+| `@product-lead` (Axis)   | Product Owner      | Validação de stories e backlog     |
+| `@sprint-lead` (Sync)    | Scrum Master       | Gerenciamento de sprint            |
+| `@analyst` (Scope)       | Analista de Negócios | Análise de requisitos            |
 
 ### Exemplo: Ativar Agente Desenvolvedor
 
-```
-@dev
+```text
+@developer
 ```
 
-O agente desenvolvedor (Dex) será ativado com uma saudação mostrando:
+O agente desenvolvedor (Pixel) será ativado com uma saudação mostrando:
 
 - Status do projeto
 - Comandos rápidos
@@ -190,7 +190,7 @@ seu-projeto/
 │   │   └── quality-gates/         # Camadas de validação de qualidade
 │   ├── development/               # Assets de desenvolvimento
 │   │   ├── agents/                # Definições de agentes (12 agentes)
-│   │   ├── tasks/                 # Workflows de tarefas (~140 tarefas)
+│   │   ├── tasks/                 # Workflows de development (211 development tasks)
 │   │   └── workflows/             # Workflows multi-etapa
 │   ├── product/                   # Assets de produto
 │   │   ├── templates/             # Templates de documentos
@@ -232,9 +232,9 @@ npm cache clean --force
 
 ### Agente não responde
 
-1. Certifique-se de estar em uma IDE com IA (Cursor, VS Code com Claude, etc.) ou Claude Code CLI
-2. Verifique se está usando sintaxe correta: `@nome-do-agente`
-3. Verifique se o arquivo do agente existe: `ls .sinapse-ai/development/agents/`
+1. Certifique-se de estar usando Claude Code ou Codex CLI.
+2. No Claude Code, use `@developer`; no Codex, use `$sinapse-agent developer` ou `$snps`.
+3. Verifique `.claude/agents/` para Claude Code ou `.codex/agents/` e `.agents/skills/` para Codex.
 
 ### Erros de permissão
 

package/docs/pt/installation/windows.md

@@ -141,8 +141,8 @@ O instalador automaticamente:
 - ✅ Detecta Windows e aplica configurações específicas da plataforma
 - ✅ Cria diretórios necessários com permissões apropriadas
 - ✅ Configura caminhos de IDE para localizações Windows:
-  - Cursor: `%APPDATA%\Cursor\`
-  - Claude: `%USERPROFILE%\.claude\`
+  - Agentes do Claude Code: `.claude\agents\`
+  - Agentes e skills do Codex: `.codex\agents\` e `.agents\skills\`
 - ✅ Lida com separadores de caminho Windows (barras invertidas)
 - ✅ Configura terminações de linha corretamente (CRLF para batch, LF para scripts)
 - ✅ Configura scripts npm compatíveis com cmd.exe e PowerShell
@@ -151,28 +151,15 @@ O instalador automaticamente:
 
 ## Configuração Específica por IDE
 
-### Cursor
+### Claude Code
 
-1. Baixe de [cursor.sh](https://cursor.sh/)
-2. Execute o instalador
-3. Regras da IDE são instaladas em `.cursor\rules\`
-4. Atalho de teclado: `Ctrl+L` para abrir chat
-5. Use `@nome-do-agente` para ativar agentes
+1. Os adapters de agentes são instalados em `.claude\agents\`.
+2. Use `@developer` ou outro ID canônico para ativar um agente.
 
-### Claude Code (CLI)
+### Codex
 
-1. Instale o Claude Code:
-
-   ```powershell
-   npm install -g @anthropic-ai/claude-code
-   ```
-
-2. Comandos são instalados em `.claude\commands\SINAPSE\`
-3. Use `/nome-do-agente` para ativar agentes
-
-
-2. Execute o instalador
-4. Use `@nome-do-agente` para ativar agentes
+1. Os descritores são instalados em `.codex\agents\`, com skills em `.agents\skills\`.
+2. Use `$snps` para roteamento ou `$sinapse-agent developer` para ativação direta.
 
 ---
 

package/docs/troubleshooting.md

@@ -40,10 +40,11 @@ npx sinapse-ai install --target "C:\Users\My User\projeto"
 
 ## Problemas de ativação de agentes
 
-### `@developer` não ativa
-1. Verifique IDE detectada: `cat .claude/settings.json` (Claude Code) ou `cat .codex/instructions.md` (Codex)
-2. Re-sincronize: `npx sinapse-ai install --reconfigure`
-3. Reinicie o IDE
+### O agente não ativa
+1. Confirme a sintaxe do provider: `@developer` no Claude Code; `$snps` ou `$sinapse-agent developer` no Codex.
+2. Verifique a configuração instalada: `.claude/settings.json` no Claude Code ou `.codex/config.toml` no Codex.
+3. Re-sincronize: `npx sinapse-ai@latest install --reconfigure`.
+4. Reinicie o provider.
 
 ### Agente ativa mas sem comandos
 ```bash
@@ -59,12 +60,13 @@ Cheque qual hook bloqueou (mensagem de erro tem o nome). Exemplos:
 - **enforce-git-push-authority**: só `@devops` pode push. Delegue: `@devops *push`.
 - **secret-scanning**: detectou secret. Verifique e remova OU mova pra `.env` (gitignored).
 
-Lista completa de hooks: `.claude/hooks/README.md`.
+Claude Code registra 20 hooks em `.claude/settings.json`. Codex registra 9 eventos
+de lifecycle em `.codex/hooks.json` e os encaminha pelo bridge de compatibilidade.
 
 ### Hook não está rodando
 ```bash
-cat .claude/settings.json | grep hooks    # confirma registro
-ls .claude/hooks/                          # confirma arquivo existe
+cat .claude/settings.json | grep hooks    # Claude Code: confirma registro
+cat .codex/hooks.json                     # Codex: confirma eventos registrados
 ```
 
 ## Problemas de CI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.25.1",
+  "version": "1.25.3",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",