sinapse-ai 1.25.1 → 1.25.2

package/.sinapse-ai/install-manifest.yaml

@@ -7,7 +7,7 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.25.1
+version: 1.25.2
 generator: scripts/generate-install-manifest.js
 file_count: 1156
 files:

package/CHANGELOG.md

@@ -1,14 +1,16 @@
-## [1.25.1](https://github.com/caioimori/sinapse-ai/compare/1.25.0...1.25.1) (2026-07-15)
+## [1.25.2](https://github.com/caioimori/sinapse-ai/compare/1.25.1...1.25.2) (2026-07-15)
 
 ### Bug Fixes
 
-* **ci:** derive Codex skill count from payload [Story sinapse-only-catalog-cleanup] ([e371a0d](https://github.com/caioimori/sinapse-ai/commit/e371a0ddf9daf944ca803a75dac9807b89d8e257))
-* **installer:** enforce conservative provider ownership [Story sinapse-only-catalog-cleanup] ([1b4f896](https://github.com/caioimori/sinapse-ai/commit/1b4f896d520a02124dc3107c604106f8ba8c8fae))
-* **installer:** harden ownership and hook validation [Story sinapse-only-catalog-cleanup] ([4575a84](https://github.com/caioimori/sinapse-ai/commit/4575a84d6062feb8198e9480f15365e6218b7e61))
-* **installer:** preserve provider-owned state [Story sinapse-only-catalog-cleanup] ([df67e88](https://github.com/caioimori/sinapse-ai/commit/df67e8836e4f2f42a2cb075d6063a01e0b8ad4c6))
-* **installer:** reconcile provider-native catalogs [Story sinapse-only-catalog-cleanup] ([830b36c](https://github.com/caioimori/sinapse-ai/commit/830b36c8108610de2067d09426bfd7e13d315672))
-* **security:** harden managed file reconciliation [Story sinapse-only-catalog-cleanup] ([3899921](https://github.com/caioimori/sinapse-ai/commit/3899921579851a6490e4866e7284ed88afe67c92))
-* **test:** resolve Bash paths across Windows runtimes [Story sinapse-only-catalog-cleanup] ([a788b04](https://github.com/caioimori/sinapse-ai/commit/a788b0434f9718eb74c1caa6dc0ae091ea4dac65))
+* **docs:** align public Claude and Codex guidance [Story Cross-Provider] ([8c005ec](https://github.com/caioimori/sinapse-ai/commit/8c005ec4f0c5702131564cb5d3d52fee8ed85b50))
+* **docs:** close public provider guidance gaps [Story Cross-Provider] ([43f76e2](https://github.com/caioimori/sinapse-ai/commit/43f76e2b405ffae61598d8999f043a1d24ea24a5))
+
+### Documentation
+
+* harden provider backup guidance [Story cross-provider-cli-quality] ([5f4bffd](https://github.com/caioimori/sinapse-ai/commit/5f4bffd351c7ac1c0ee5cde2d7388e34409e0566))
+* **story:** normalize validation terminology [Story sinapse-only-catalog-cleanup] ([7e0ecb9](https://github.com/caioimori/sinapse-ai/commit/7e0ecb9fb01a6626ccc7c665d262c38c61196120))
+* **story:** reconcile post-release evidence [Story sinapse-only-catalog-cleanup] ([3c10c65](https://github.com/caioimori/sinapse-ai/commit/3c10c65fcfdca77ec0d1c1af6a2831af39b0adf0))
+* **story:** record SINAPSE 1.25.1 release [Story sinapse-only-catalog-cleanup] ([ba9f776](https://github.com/caioimori/sinapse-ai/commit/ba9f77607879c6efe8511e38cfeab6c71d2335c4))
 
 # Changelog
 

package/README.en.md

@@ -19,9 +19,9 @@
 
 ## What is SINAPSE?
 
-SINAPSE is an open-source meta-framework that organizes **172 AI agents into 17 specialized squads**, operating directly in the terminal via Claude Code or Codex CLI. Each agent has a defined role, each squad masters a discipline, and the entire system is governed by a **Constitution with real enforcement** -- 17 active hooks that block violations at runtime.
+SINAPSE is an open-source meta-framework that organizes **172 AI agents into 17 specialized squads**, operating directly in the terminal via Claude Code or Codex CLI. Each agent has a defined role, each squad masters a discipline, and the entire system is governed by a **Constitution with real enforcement** -- 20 registered Claude Code hooks and 9 Codex lifecycle events through the compatibility bridge.
 
-The core concept is simple: instead of a single AI assistant trying to do everything, SINAPSE structures work into specialized teams. A branding squad handles visual identity. A cybersecurity squad handles compliance and pentesting. A copywriting squad handles persuasion and conversion. Each with its own knowledge base, workflows, and tasks -- totaling **1,200 executable tasks** ready to use.
+The core concept is simple: instead of a single AI assistant trying to do everything, SINAPSE structures work into specialized teams. A branding squad handles visual identity. A cybersecurity squad handles compliance and pentesting. A copywriting squad handles persuasion and conversion. The runtime measures **1,412 task files**: **1,201 squad tasks** and **211 development tasks**. Of those files, **1,348 pointers are resolvable** by real agents.
 
 Unlike tools that just chat with AI, SINAPSE enforces discipline. The **Documentation-First** pipeline requires a story to be created and validated before any code is written. Quality gates run automatically before merge. Unauthorized agents are blocked from pushing. All via hooks that intercept operations in real time -- not after the fact.
 
@@ -33,7 +33,7 @@ Generative AI has a known problem: the more you ask of it, the worse it gets. A
 
 SINAPSE solves this the way human teams solve it: **coordinated specialization**. Instead of one tired generalist, you have 172 agents in 17 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**: 17 active hooks intercept operations at runtime, a Constitution with 11 articles governs the framework, and 7 of those articles are NON-NEGOTIABLE -- violations are blocked before execution, not detected afterwards. **Speed with rigor, without choosing between the two.**
+The differential isn't just the quantity of agents. It's **real governance**: 20 Claude Code hook registrations and 9 Codex lifecycle events intercept operations at runtime, a Constitution with 11 articles governs the framework, and 7 of those articles are NON-NEGOTIABLE -- violations are blocked before execution, not detected afterwards. **Speed with rigor, without choosing between the two.**
 
 ---
 
@@ -55,9 +55,18 @@ npx sinapse-ai doctor
 
 ### 3. Activate your first agent
 
+Claude Code:
+
+```text
+@developer
+*help
 ```
-@developer          # Activate the development agent
-*help               # List available commands
+
+Codex:
+
+```text
+$snps
+$sinapse-agent developer
 ```
 
 Done. You have 17 squads operating in your terminal.
@@ -174,7 +183,7 @@ Deny rules in `.claude/settings.json` enforce this deterministically. **Framewor
 
 ### Constitution
 
-SINAPSE is governed by a formal Constitution with 11 articles and 17 enforcement hooks:
+SINAPSE is governed by a formal Constitution with 11 articles and provider-specific enforcement surfaces: 20 Claude Code hook registrations and 9 Codex lifecycle events.
 
 | Article | Principle | Severity |
 |---------|-----------|----------|
@@ -213,7 +222,7 @@ SINAPSE includes 12 core agents covering the complete development cycle:
 | `devops` | **Pipeline** | CI/CD, git push (exclusive), releases |
 | `squad-creator` | **Loom** | New squad creation |
 
-Activate any agent with `@agent-name` and use `*help` to see its commands.
+In Claude Code, activate an agent with `@agent-name` and use `*help` to see its commands. In Codex, start with `$snps` for routing or use `$sinapse-agent agent-id` for direct activation.
 
 ### Development Workflow
 
@@ -263,15 +272,19 @@ Each squad is an autonomous team with its own orchestrator, specialist agents, k
 | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
 | **squad-finance** | Budget, pricing, profitability analysis | 8 |
 
-**Total: 17 squads, 172 specialized agents, 1,201 tasks**
+**Total: 17 squads, 172 specialized agents, and 1,412 task files** (**1,201 squad tasks + 211 development tasks; 1,348 resolvable pointers**)
 
-Activate any squad via its orchestrator:
+Activate any squad via its orchestrator using the provider-native syntax:
 
-```
+```text
+# Claude Code
 @brand-orqx         # Brand squad
 @copy-orqx          # Copy squad
-@cyber-orqx         # Cybersecurity squad
-@research-orqx      # Research squad
+
+# Codex
+$sinapse-agent brand-orqx
+$sinapse-agent copy-orqx
+$snps               # Route through the primary orchestrator
 ```
 
 The orchestrator receives your request and automatically delegates to the right specialist within the squad.
@@ -285,27 +298,22 @@ SINAPSE supports two IDEs with deep integrations:
 | IDE | Activation | Highlights |
 |-----|------------|------------|
 | **Claude Code** | `@agent-name` | Hooks, contextual rules, deny/allow, Chrome Brain |
-| **Codex CLI** | `/skills` or `$skill-name` | Native skills, multi-model, `codex exec` for CI/CD |
+| **Codex CLI** | `$snps` or `$sinapse-agent agent-id` | Native skills, multi-model, `codex exec` for CI/CD |
 
 Both IDEs have access to all 17 squads, 172 agents, workflows, and knowledge bases. The installer detects and configures automatically.
 
 ### Parity Table
 
-| Feature | Claude Code | Codex CLI |
-|---------|:-----------:|:---------:|
-| Agent activation (@agent) | Full | Full |
-| Constitutional hooks (20) | Full | Partial (5) |
-| Story-driven development | Full | Full |
-| Quality gates | Full | Full |
-| Delegation enforcement | Full | Partial |
-| Secret scanning | Full | Manual |
-| CodeRabbit integration | Full | N/A |
-| Skills system | Full | Commands |
-| MCP servers | Full | N/A |
-| Terminal Bus | Full | N/A |
-
-**Claude Code** for the most integrated and automated experience.
-**Codex CLI** for model flexibility and CI/CD automation.
+| Measured surface | Claude Code | Codex CLI |
+|------------------|:-----------:|:---------:|
+| Native agents | 172 | 172 |
+| Direct activation | `@agent-name` | `$sinapse-agent agent-id` |
+| Primary routing | `@sinapse-orqx` | `$snps` |
+| Installed skills | 36 | 37 |
+| Registered hooks | 20 native registrations | 9 lifecycle events through the bridge |
+| Validation source | `npm run validate:providers` | `npm run validate:codex-native` |
+
+Both providers resolve the same agents, tasks, workflows, and knowledge bases. Their activation and hook surfaces are different native adapters validated independently by the parity gate.
 
 ---
 
@@ -335,7 +343,7 @@ If you identify with the first group, you're in the right place.
 
 ### Constitutional Enforcement
 
-SINAPSE doesn't just document rules -- it enforces them with **17 active hooks**:
+SINAPSE doesn't just document rules -- Claude Code uses **20 registered hooks**, while Codex exposes **9 lifecycle events** through the compatibility bridge:
 
 - `enforce-git-push-authority.sh` -- blocks push by unauthorized agents
 - `enforce-story-gate.cjs` -- blocks code without a validated story
@@ -400,7 +408,7 @@ npx sinapse-ai doctor --dry-run  # Show what `--fix` would do without applying
 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.
+All commands are safe to re-run. After installing, use `@agent-name` in Claude Code or `$snps` / `$sinapse-agent agent-id` in Codex.
 
 ---
 

package/README.md

@@ -23,7 +23,7 @@
 
 SINAPSE é um meta-framework open source que organiza **172 agentes de IA em 17 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 é governado por uma **Constitution com enforcement real** — 20 hooks registrados que bloqueiam violações em tempo de execução.
 
-O conceito central é simples: em vez de um único assistente de IA tentando fazer tudo, o SINAPSE estrutura o trabalho em equipes especializadas. Um squad de branding cuida da identidade visual. Um squad de cybersecurity cuida de compliance e pentest. Um squad de copywriting cuida de persuasão e conversão. Cada um com sua própria knowledge base, workflows e tasks — totalizando **1.201 tasks executáveis** prontas para uso, distribuídas pelos 17 squads.
+O conceito central é simples: em vez de um único assistente de IA tentando fazer tudo, o SINAPSE estrutura o trabalho em equipes especializadas. Um squad de branding cuida da identidade visual. Um squad de cybersecurity cuida de compliance e pentest. Um squad de copywriting cuida de persuasão e conversão. Cada um com sua própria knowledge base, workflows e tasks. O runtime mede **1.412 task files**: **1.201 squad tasks** nos 17 squads e **211 development tasks**. Desses arquivos, **1.348 são resolvíveis** pelos ponteiros reais dos agentes.
 
 Diferente de ferramentas que apenas conversam com IA, o SINAPSE impõe disciplina. O pipeline **Documentation-First** exige que uma story seja criada e validada antes de qualquer linha de código. Quality gates rodam automaticamente antes de merge. Agentes não autorizados são bloqueados de fazer push. Tudo isso via hooks que interceptam operações em tempo real — não depois.
 
@@ -63,9 +63,18 @@ Se algo estiver fora do lugar, `doctor --fix` corrige automaticamente.
 
 ### 3. Ative seu primeiro agente
 
+Claude Code:
+
+```text
+@developer
+*help
 ```
-@developer          # Ativa o agente de desenvolvimento
-*help               # Lista comandos disponíveis
+
+Codex:
+
+```text
+$snps
+$sinapse-agent developer
 ```
 
 Pronto. Você tem 17 squads operando no seu terminal.
@@ -235,7 +244,7 @@ O SINAPSE inclui 12 agentes core que cobrem o ciclo completo de desenvolvimento:
 | `devops` | **Pipeline** | CI/CD, git push (exclusivo), releases |
 | `squad-creator` | **Loom** | Criação de novos squads |
 
-Ative qualquer agente com `@agent-name` e use `*help` para ver seus comandos.
+No Claude Code, ative um agente com `@agent-name` e use `*help` para ver seus comandos. No Codex, comece com `$snps` para roteamento ou use `$sinapse-agent agent-id` para ativação direta.
 
 ### Workflow de Desenvolvimento
 
@@ -285,15 +294,19 @@ Cada squad é uma equipe autônoma com orquestrador, agentes especialistas, know
 | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
 | **squad-finance** | Budget, pricing, profitability analysis | 8 |
 
-**Total: 17 squads, 172 agentes especializados, 1.201 tasks**
+**Total: 17 squads, 172 agentes especializados e 1.412 task files** (**1.201 squad tasks + 211 development tasks; 1.348 ponteiros resolvíveis**)
 
-Cada squad é ativado via seu orquestrador:
+Cada squad é ativado via seu orquestrador, com a sintaxe nativa do provedor:
 
-```
+```text
+# Claude Code
 @brand-orqx         # Squad de brand
 @copy-orqx          # Squad de copy
-@cyber-orqx         # Squad de cybersecurity
-@research-orqx      # Squad de research
+
+# Codex
+$sinapse-agent brand-orqx
+$sinapse-agent copy-orqx
+$snps               # Roteamento pelo orquestrador principal
 ```
 
 O orquestrador recebe seu pedido e delega automaticamente ao especialista correto dentro do squad.
@@ -306,28 +319,23 @@ O SINAPSE suporta duas IDEs com integrações profundas:
 
 | IDE | Ativação | Destaques |
 |-----|----------|-----------|
-| **Claude Code** | `@agent-name` ou `/skill-name` | Subagentes e skills nativos, hooks e rules contextuais |
+| **Claude Code** | `@agent-name` | Subagentes e skills nativos, hooks e rules contextuais |
 | **Codex CLI** | `$snps` ou `$sinapse-agent agent-id` | Agentes TOML, skills nativas e `codex exec` para CI/CD |
 
 Ambas as IDEs têm acesso a todos os 17 squads, 172 agentes, workflows e knowledge bases. O installer detecta e configura automaticamente.
 
 ### Tabela de Paridade
 
-| Funcionalidade | Claude Code | Codex CLI |
-|---------------|:-----------:|:---------:|
-| Ativação dos 172 agentes | `@agent-name` | `$sinapse-agent agent-id` |
-| Hooks constitucionais (20) | Completo | Parcial (5) |
-| Story-driven development | Completo | Completo |
-| Quality gates | Completo | Completo |
-| Enforcement de delegação | Completo | Parcial |
-| Secret scanning | Completo | Manual |
-| Integração CodeRabbit | Completo | N/A |
-| Sistema de skills | Completo | Comandos |
-| MCP servers | Completo | N/A |
-| Terminal Bus | Completo | N/A |
-
-**Claude Code** para a experiência mais integrada e automatizada.
-**Codex CLI** para flexibilidade de modelo e automação CI/CD.
+| Superfície medida | Claude Code | Codex CLI |
+|-------------------|:-----------:|:---------:|
+| Agentes nativos | 172 | 172 |
+| Ativação direta | `@agent-name` | `$sinapse-agent agent-id` |
+| Roteamento principal | `@sinapse-orqx` | `$snps` |
+| Skills instaladas | 36 | 37 |
+| Hooks registrados | 20 registros nativos | 9 eventos de lifecycle via bridge |
+| Fonte de validação | `npm run validate:providers` | `npm run validate:codex-native` |
+
+Os dois providers resolvem os mesmos agents, tasks, workflows e knowledge bases. As superfícies de ativação e hooks são adapters nativos diferentes e são validadas separadamente pelo gate de paridade.
 
 ---
 

package/docs/getting-started.md

@@ -27,14 +27,22 @@ Se algo falhar: `npx sinapse-ai doctor --fix` corrige automaticamente.
 
 ## Ativar primeiro agente
 
-No prompt do Claude Code ou Codex:
+No Claude Code:
 
-```
+```text
 @developer
 *help
 ```
 
-`@developer` ativa o agente de implementação. `*help` lista comandos disponíveis.
+No Codex, use o roteador ou a ativação direta:
+
+```text
+$snps
+$sinapse-agent developer
+```
+
+`@developer` e `*help` pertencem à superfície do Claude Code. No Codex, `$snps`
+roteia a solicitação e `$sinapse-agent developer` ativa o agente de implementação.
 
 ## Próximos passos
 
@@ -61,9 +69,9 @@ npx sinapse-ai uninstall               # remove tudo
 ## Conceitos chave (em 30 segundos)
 
 - **Squad**: equipe de agentes especializados (ex: squad-design tem 15 agentes de design/UX)
-- **Agente**: persona de IA com expertise e comandos específicos (`@developer`, `@architect`, etc.)
+- **Agente**: persona de IA com especialização e comandos específicos (`@developer` no Claude Code; `$sinapse-agent developer` no Codex)
 - **Hook**: enforcement runtime que bloqueia violações da Constitution (ex: PR sem story)
-- **Constitution**: 10 artigos que governam o framework (ver `.sinapse-ai/constitution.md`)
+- **Constitution**: 11 artigos que governam o framework (ver `.sinapse-ai/constitution.md`)
 - **Story**: arquivo `.md` que documenta requisitos antes do código (Documentation-First)
 
 ---

package/docs/guides/codex-config.md

@@ -1,6 +1,6 @@
 # AGENTS.md - SINAPSE
 
-Este arquivo configura o comportamento esperado de agentes no Codex CLI neste repositorio.
+Este arquivo configura o comportamento esperado de agentes no Codex CLI neste repositório.
 
 ## Constitution
 
@@ -14,7 +14,7 @@ Siga `.sinapse-ai/constitution.md` como fonte de verdade:
 - Ecosystem Metrics Accuracy (NON-NEGOTIABLE)
 - Mandatory Delegation (NON-NEGOTIABLE)
 
-## Workflow Obrigatorio
+## Workflow Obrigatório
 
 1. Inicie por uma story em `docs/stories/`
 2. Implemente apenas o que os acceptance criteria pedem
@@ -35,31 +35,31 @@ npm test
 - CLI: `bin/`
 - Pacotes: `packages/`
 - Testes: `tests/`
-- Documentacao: `docs/`
+- Documentação: `docs/`
 
 ## IDE/Agent Sync
 
 - Sincronizar regras/agentes: `npm run sync:ide`
 - Validar drift: `npm run sync:ide:check`
-- Rodar paridade multi-IDE (Claude/Codex/Gemini): `npm run validate:parity`
+- Rodar paridade Claude/Codex: `npm run validate:parity`
 - Sync Claude Code: `npm run sync:ide:claude`
-- Sincronizar Gemini CLI: `npm run sync:ide:gemini`
+- Sincronizar Codex: `npm run sync:ide:codex`
 - Validar Codex sync/integration: `npm run validate:codex-sync`; `npm run validate:codex-integration`
 - Validar command/task registry do Codex: `npm run validate:codex-commands`
-- Validar matriz de delegacao do Codex: `npm run validate:codex-delegation`
+- Validar matriz de delegação do Codex: `npm run validate:codex-delegation`
 - Gerar skills locais do Codex: `npm run sync:skills:codex`
-- Este repositorio usa **local-first**: `.agents/skills` e a unica raiz de skills SINAPSE versionada no projeto
+- Este repositório usa **local-first**: `.agents/skills` é a única raiz de skills SINAPSE versionada no projeto
 - Use `sync:skills:codex:global` apenas para testes fora deste repo
 
 ## Command Resolution (Codex)
 
-Quando um agente no Codex receber um `*comando`, prefira resolver a execucao por esta ordem:
+Quando um agente no Codex receber um `*comando`, prefira resolver a execução por esta ordem:
 
 1. Consultar `.codex/command-registry.json`
 2. Opcionalmente usar `node .codex/scripts/resolve-codex-command.js <skill-ou-agent> <comando>`
 3. Carregar a task/workflow/checklist/template mapeada
 
-Isso evita "file hunting" manual e torna a execucao de workflows/tasks mais deterministica no Codex.
+Isso evita "file hunting" manual e torna a execução de workflows/tasks mais determinística no Codex.
 
 ## Delegation Resolution (Codex)
 
@@ -72,68 +72,52 @@ Quando um orqx no Codex precisar decidir um handoff:
    - `codex-shim`
    - `exploratory`
 
-No Codex, nao trate handoffs exploratorios como se fossem caminhos garantidos pelo validator.
+No Codex, não trate handoffs exploratórios como se fossem caminhos garantidos pelo validator.
 
-## Agent Shortcuts (Codex)
+## Ativação de agentes (Codex)
 
-Preferencia de ativacao no Codex CLI:
-1. Use `/skills` e selecione `sinapse-<agent-id>` vindo de `.agents/skills` (ex.: `sinapse-architect`)
-2. Se preferir, use os atalhos abaixo (`@architect`, `/architect`, etc.)
-
-Quando a mensagem do usuario for um atalho de agente, carregue o arquivo correspondente em `.sinapse-ai/development/agents/` (fallback: `.codex/agents/`), renderize o greeting via `generate-greeting.js` e assuma a persona ate receber `*exit`.
-
-Atalhos aceitos por agente (nome completo + alias):
-- `@sinapse-orqx` -> `.sinapse-ai/development/agents/sinapse-orqx.md`
-- `@developer` ou `@dev` -> `.sinapse-ai/development/agents/developer.md`
-- `@quality-gate` ou `@qa` -> `.sinapse-ai/development/agents/quality-gate.md`
-- `@project-lead` ou `@pm` -> `.sinapse-ai/development/agents/project-lead.md`
-- `@product-lead` ou `@po` -> `.sinapse-ai/development/agents/product-lead.md`
-- `@sprint-lead` ou `@sm` -> `.sinapse-ai/development/agents/sprint-lead.md`
-- `@analyst` -> `.sinapse-ai/development/agents/analyst.md`
-- `@architect` -> `.sinapse-ai/development/agents/architect.md`
-- `@data-engineer` -> `.sinapse-ai/development/agents/data-engineer.md`
-- `@devops` -> `.sinapse-ai/development/agents/devops.md`
-- `@squad-creator` -> `.sinapse-ai/development/agents/squad-creator.md`
-- `@ux-design-expert` -> `.sinapse-ai/development/agents/ux-design-expert.md`
-
-Resposta esperada ao ativar atalho:
-1. Confirmar agente ativado
-2. Mostrar 3-6 comandos principais (`*help`, etc.)
-3. Seguir na persona do agente
+- Use `$snps` para roteamento pelo orquestrador principal.
+- Use `$sinapse-agent <agent-id>` para ativação direta, por exemplo
+  `$sinapse-agent developer` ou `$sinapse-agent architect`.
+- O ativador paramétrico resolve a fonte canônica e apenas tasks existentes;
+  não interprete `@agent`, slash commands ou aliases curtos como ativação Codex.
 
 ## Orquestradores (18 orqx: 17 squad + 1 master)
 
-Cada orqx coordena um squad completo de agentes especializados. Ative via `/skills` > `sinapse-<orqx>` ou `@<orqx>`:
+Cada orqx coordena um squad completo de agentes especializados. Use `$snps` para
+roteamento ou `$sinapse-agent <orqx-id>` para ativação direta:
 
 | Orqx | Squad | Foco |
 |------|-------|------|
 | `sinapse-orqx` | Core | Orquestrador principal de todos os squads |
-| `brand-orqx` | Brand | Estrategia de marca, arquetipos, auditoria |
-| `copy-orqx` | Copy | Copywriting persuasivo, headlines, conversao |
-| `content-orqx` | Content | Governanca editorial, estrategia de conteudo |
-| `storytelling-orqx` | Storytelling | Narrativa, roteiros, frameworks de historia |
+| `brand-orqx` | Brand | Estratégia de marca, arquétipos, auditoria |
+| `copy-orqx` | Copy | Copywriting persuasivo, headlines, conversão |
+| `content-orqx` | Content | Governança editorial, estratégia de conteúdo |
+| `storytelling-orqx` | Storytelling | Narrativa, roteiros, frameworks de história |
 | `commercial-orqx` | Commercial | Vendas, funil, revenue, pipeline |
 | `paidmedia-orqx` | Paid Media | Meta Ads, Google Ads, campanhas |
 | `growth-orqx` | Growth | Analytics, CRO, SEO, growth hacking |
-| `research-orqx` | Research | Market analysis, inteligencia competitiva |
-| `product-orqx` | Product | Product discovery, estrategia, operacoes |
+| `research-orqx` | Research | Market analysis, inteligência competitiva |
+| `product-orqx` | Product | Product discovery, estratégia, operações |
 | `design-orqx` | Design | Design systems, componentes, tokens |
-| `animations-orqx` | Animations | Motion design, CSS, particulas, 3D |
-| `cyber-orqx` | Cybersecurity | Seguranca, threat intel, pentest |
+| `animations-orqx` | Animations | Motion design, CSS, partículas, 3D |
+| `cyber-orqx` | Cybersecurity | Segurança, threat intel, pentest |
 | `finance-orqx` | Finance | Budget, pricing, profitability |
-| `courses-orqx` | Courses | Curriculos, assessments, launch |
+| `courses-orqx` | Courses | Currículos, assessments, launch |
 | `cloning-orqx` | Cloning | Clonagem cognitiva, mind synthesis |
-| `council-orqx` | Council | Advisors estrategicos (Munger, Dalio, Thiel) |
-| `swarm-orqx` | Mastery | Claude Code, MCP, integracao avancada |
+| `council-orqx` | Council | Advisors estratégicos (Munger, Dalio, Thiel) |
+| `swarm-orqx` | Mastery | Claude Code, MCP, integração avançada |
 
-Agents de arquivo: `.codex/agents/<orqx>.md` ou `.claude/agents/<orqx>.md`
+Adapters de arquivo: `.claude/agents/sinapse-<orqx-id>.md` no Claude Code e
+`.codex/agents/<orqx-id>.toml` (com companion `.md`) no Codex.
 
 ## Agentes Especializados (160)
 
-Existem 172 agentes organizados em 17 squads (160 em squads + 12 framework agents, incluindo o master orchestrator). Eles sao acessiveis via:
-- `.codex/agents/<agent-name>.md` - arquivo direto
+Existem 172 agentes organizados em 17 squads (160 em squads + 12 framework agents, incluindo o master orchestrator). Eles são acessíveis via:
+- `.claude/agents/sinapse-<agent-id>.md` - agent nativo do Claude Code
+- `.codex/agents/<agent-id>.toml` e `.codex/agents/<agent-id>.md` - adapters Codex
 - Chamada interna pelo orqx do squad
 
 Exemplos: `brand-strategist`, `ad-copywriter`, `penetration-tester`, `content-writer`, `ga-analytics-engineer`, etc.
 
-Use `*help` dentro de qualquer orqx para ver os especialistas disponiveis no squad.
+Use `*help` dentro de qualquer orqx para ver os especialistas disponíveis no squad.

package/docs/guides/ide-integration.md

@@ -19,40 +19,39 @@ SINAPSE supports the following AI-powered development platforms:
 
 | IDE/CLI | Overall Status | How to Activate an Agent | Auto-Checks Before/After Actions |
 | --- | --- | --- | --- |
-| Claude Code | Works | `/agent-name` commands | Works (full) |
-| Codex CLI | Limited | `/skills` then `sinapse-<agent-id>` | Limited (some checks need manual sync) |
+| Claude Code | Works | `@agent-name` | 20 native hook registrations |
+| Codex CLI | Works | `$snps` or `$sinapse-agent <id>` | 9 lifecycle events through the bridge |
 
 Legend:
-- `Works`: fully recommended for new users.
-- `Limited`: usable with the documented workaround.
+- `Works`: supported by provider-native adapters and release validators.
 
-### What You Lose Without Full Auto-Checks
+### Provider-Native Differences
 
-Some IDEs run automatic checks before and after each action (e.g., validating context, enforcing rules). Where this is not available, you compensate manually:
+Both providers expose native lifecycle surfaces. Their registration models differ, so parity is measured semantically instead of by requiring identical hook files:
 
-| IDE | Auto-Check Level | What Is Reduced | How to Compensate |
-| --- | --- | --- | --- |
-| Claude Code | Full | Nothing | Built-in checks handle everything |
-| Codex CLI | Partial | Less automatic session tracking; some pre/post-action checks need manual trigger | Use `AGENTS.md` + `/skills` + sync/validation scripts |
+| Measured surface | Claude Code | Codex CLI |
+| --- | --- | --- |
+| Native agents | 172 | 172 |
+| Installed skills | 36 | 37 |
+| Registered hooks | 20 native registrations | 9 lifecycle events through the bridge |
+| Activation | `@agent-name` | `$snps` or `$sinapse-agent <id>` |
 
 ### Beginner Decision Guide
 
 If your goal is to get started as fast as possible:
 
-1. **Best option:** Use `Claude Code` -- it has the most automation and fewest manual steps.
-2. **Good option:** Use `Codex CLI` if you prefer a terminal-first workflow and can follow the `/skills` activation flow.
+1. Use **Claude Code** when you want its native `@agent-name` interaction.
+2. Use **Codex CLI** when you want `$snps`, direct parametric activation and its terminal-first workflow.
 
 ### Practical Consequences by Capability
 
 - **Session tracking** (automatic start/end detection):
-  - Automatic on Claude Code.
-  - Manual or partial on Codex CLI.
+  - Registered through native lifecycle adapters on both providers.
 - **Pre/post-action guardrails** (checks that run before and after each tool use):
-  - Full on Claude Code.
-  - Partial on Codex CLI (run sync scripts to compensate).
+  - Claude Code uses native hook registrations.
+  - Codex maps native lifecycle events through the compatibility bridge.
 - **Automatic audit trail** (record of what happened in each session):
-  - Richest on Claude Code.
-  - Reduced on Codex CLI (compensate with manual logging or validator output).
+  - Provider-specific telemetry uses the same canonical SINAPSE governance sources.
 
 ---
 
@@ -60,12 +59,12 @@ If your goal is to get started as fast as possible:
 
 ### Claude Code
 
-**Recommendation Level:** Best SINAPSE integration
+**Recommendation Level:** Native SINAPSE integration
 
 ```yaml
 config_file: .claude/CLAUDE.md
 agent_folder: .claude/agents
-activation: /agent-name (slash commands)
+activation: '@agent-name'
 format: full-markdown-yaml
 mcp_support: native
 special_features:
@@ -79,7 +78,7 @@ special_features:
 **Setup:**
 
 1. SINAPSE automatically creates `.claude/` directory on init
-2. Agents are available as slash commands: `/dev`, `/qa`, `/architect`
+2. Agents are available through `@developer`, `@quality-gate`, `@architect`, etc.
 3. Configure MCP servers in `~/.claude.json`
 
 **Configuration:**
@@ -107,7 +106,7 @@ format: markdown
 mcp_support: native via Codex tooling
 special_features:
   - AGENTS.md project instructions
-  - /skills activators (sinapse-<agent-id>)
+  - $snps and $sinapse-agent <id> activators
   - Strong CLI workflow support
   - Easy integration with repository scripts
   - Notify command plus emerging tool hooks in recent Codex releases
@@ -118,7 +117,7 @@ special_features:
 1. Keep `AGENTS.md` at repository root
 2. Run `npm run sync:ide:codex` to sync auxiliary agent files
 3. Run `npm run sync:skills:codex` to generate project-local skills in `.agents/skills`
-4. Use `/skills` and choose `sinapse-architect`, `sinapse-dev`, etc.
+4. Use `$snps` or `$sinapse-agent architect`, `$sinapse-agent developer`, etc.
 5. Use `npm run sync:skills:codex:global` only when you explicitly want global installation
 
 **Configuration:**