sinapse-ai 1.25.1 → 1.25.2

package/docs/installation/windows.md

@@ -155,8 +155,9 @@ The installer automatically:
 
 - ✅ Detects Windows and applies platform-specific configurations
 - ✅ Creates necessary directories with proper permissions
-- ✅ Configures IDE paths for Windows locations:
-  - Claude: `%USERPROFILE%\.claude\`
+- ✅ Configures provider adapters in the project:
+  - Claude Code agents: `.claude\agents\`
+  - Codex agents and skills: `.codex\agents\` and `.agents\skills\`
 - ✅ Handles Windows path separators (backslashes)
 - ✅ Configures line endings correctly (CRLF for batch, LF for scripts)
 - ✅ Sets up npm scripts compatible with cmd.exe and PowerShell
@@ -165,16 +166,15 @@ The installer automatically:
 
 ## IDE-Specific Setup
 
-### Claude Code (CLI)
+### Claude Code
 
-1. Install Claude Code:
+1. Agent adapters are installed in `.claude\agents\`.
+2. Use `@developer` or another canonical agent ID to activate an agent.
 
-   ```powershell
-   npm install -g @anthropic-ai/claude-code
-   ```
+### Codex
 
-2. Commands are installed to `.claude\commands\SINAPSE\`
-3. Use `/agent-name` to activate agents
+1. Agent descriptors are installed in `.codex\agents\`, with skills in `.agents\skills\`.
+2. Use `$snps` for routing or `$sinapse-agent developer` for direct activation.
 
 ---
 
@@ -403,12 +403,8 @@ See the complete [Uninstallation Guide](./uninstallation.md) for detailed steps.
 Quick uninstall via PowerShell:
 
 ```powershell
-# Remove SINAPSE from project
-Remove-Item -Recurse -Force .sinapse-ai
-Remove-Item -Recurse -Force .claude\commands\SINAPSE
-
-# Remove global npm packages
-npm uninstall -g @sinapse/sinapse
+# Remove SINAPSE through the package-managed uninstaller
+npx sinapse-ai uninstall
 ```
 
 ---

package/docs/pt/guides/project-status-feature.md

@@ -32,10 +32,11 @@ Isso fornece contexto imediato sobre seu trabalho sem precisar executar manualme
 
 ## Exemplo de Exibição
 
-Quando você ativa um agente (ex: `/dev`), você verá:
+Quando você ativa um agente (`@developer` no Claude Code ou
+`$sinapse-agent developer` no Codex), você verá:
 
-```
-Dex (Builder) ready. Let's build something great!
+```text
+Pixel the Builder ready to innovate!
 
 Current Project Status:
   - Branch: main
@@ -52,24 +53,15 @@ Type *help to see available commands!
 ### Pré-requisitos
 
 - **Repositório Git** - Projeto deve ser inicializado com `git init`
-- **Framework SINAPSE-FullStack** instalado
+- **Framework SINAPSE AI** instalado
 - **Node.js 18+** com pacotes necessários
 
 ### Configuração Inicial
 
-Execute o comando de inicialização via agente @devops:
-
-```bash
-/devops
-*init-project-status
-```
-
-Isso irá:
-1. Detectar seu repositório git
-2. Habilitar `projectStatus` no `core-config.yaml`
-3. Criar arquivo de cache `.sinapse/project-status.yaml`
-4. Adicionar arquivo de cache ao `.gitignore`
-5. Testar a exibição do status
+Nenhum comando de agente é necessário. Nas instalações atuais, `projectStatus`
+fica habilitado em `.sinapse-ai/core-config.yaml` e carrega automaticamente na
+ativação dos agentes. O loader detecta o repositório Git e mantém
+`.sinapse/project-status.yaml` como cache de runtime.
 
 **Configuração Manual Alternativa:**
 
@@ -219,19 +211,24 @@ Mostra apenas stories com status: `InProgress` ou `In Progress`.
 
 ## Agentes Afetados
 
-Todos os 11 agentes SINAPSE exibem status do projeto:
-
-1. **@dev** (Dex - Builder)
-2. **@po** (Pax - Balancer)
-3. **@qa** (Quinn - Guardian)
-4. **@sm** (River - Facilitator)
-5. **@pm** (Morgan - Strategist)
-6. **@architect** (Aria - Visionary)
-7. **@analyst** (Atlas - Decoder)
-8. **@devops** (Gage - Operator)
-9. **@data-engineer** (Dara - Sage)
-10. **@ux-design-expert** (Uma - Empathizer)
-11. **@sinapse-orqx** (Orion - Orchestrator)
+O SINAPSE inclui 172 agentes especializados em 17 squads. O status de projeto
+é uma capacidade compartilhada do framework; a lista abaixo é o subconjunto
+core de desenvolvimento, não o catálogo completo:
+
+1. `developer` (Pixel)
+2. `product-lead` (Axis)
+3. `quality-gate` (Litmus)
+4. `sprint-lead` (Sync)
+5. `project-lead` (Beacon)
+6. `architect` (Stratum)
+7. `analyst` (Scope)
+8. `devops` (Pipeline)
+9. `data-engineer` (Tensor)
+10. `ux-design-expert` (Mosaic)
+11. `snps-orqx` (Imperator)
+
+Ative esses IDs com `@agent-id` no Claude Code ou `$sinapse-agent agent-id` no
+Codex; para roteamento principal no Codex, use `$snps`.
 
 ---
 
@@ -247,12 +244,9 @@ Todos os 11 agentes SINAPSE exibem status do projeto:
 3. O arquivo `.sinapse-ai/infrastructure/scripts/project-status-loader.js` existe?
 4. Há erros na saída de ativação do agente?
 
-**Solução:**
-```bash
-# Re-run initialization
-/devops
-*init-project-status
-```
+**Solução:** Execute `npx sinapse-ai@latest doctor`, confirme as verificações
+acima e reinicie a sessão do provider. O status recarrega automaticamente; não
+existe task pointer público `init-project-status` no Codex.
 
 ### Dados de Status Desatualizados
 
@@ -368,28 +362,15 @@ await clearCache();
 
 ### Remoção Completa
 
-Para remover completamente a funcionalidade:
+Não apague scripts, testes ou tasks do framework. Desabilite a funcionalidade
+em `.sinapse-ai/core-config.yaml` e remova somente o cache de runtime:
 
 ```bash
-# Remove script
-rm .sinapse-ai/infrastructure/scripts/project-status-loader.js
-
-# Remove task
-rm .sinapse-ai/tasks/init-project-status.md
-
-# Remove cache
 rm .sinapse/project-status.yaml
-
-# Remove tests
-rm .sinapse-ai/infrastructure/scripts/__tests__/project-status-loader.test.js
-
-# Remove config section from core-config.yaml
-# (manually edit file)
-
-# Revert agent files to pre-6.1.2.4 state
-git revert <commit-hash>
 ```
 
+Defina `projectStatus.enabled: false`; os arquivos protegidos permanecem instalados.
+
 ---
 
 ## Compatibilidade de Versão do Git
@@ -463,7 +444,7 @@ R: Sim, todos os agentes usam o mesmo arquivo de cache (`.sinapse/project-status
 - **Story:** `docs/stories/sinapse migration/story-6.1.2.4-project-status-context.md`
 - **Config:** `.sinapse-ai/core-config.yaml` (seção projectStatus)
 - **Script:** `.sinapse-ai/infrastructure/scripts/project-status-loader.js`
-- **Task de Init:** `.sinapse-ai/tasks/init-project-status.md`
+- **Inicialização:** automática quando `projectStatus.enabled` está habilitado
 - **Testes:** `.sinapse-ai/infrastructure/scripts/__tests__/project-status-loader.test.js`
 
 ---
@@ -471,4 +452,3 @@ R: Sim, todos os agentes usam o mesmo arquivo de cache (`.sinapse/project-status
 **Versão:** 1.0
 **Status:** Pronto para Produção
 **Última Atualização:** 2025-01-14
-

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]