sinapse-ai 1.25.0 → 1.25.1

package/bin/lib/global-provider-adapters.js

@@ -3,6 +3,22 @@
 const fs = require('fs');
 const path = require('path');
 
+const NOFOLLOW_READ_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
+
+function readRegularFileNoFollowSync(filePath, encoding = null) {
+  let handle;
+  try {
+    handle = fs.openSync(filePath, NOFOLLOW_READ_FLAGS);
+    if (!fs.fstatSync(handle).isFile()) return null;
+    return fs.readFileSync(handle, encoding || undefined);
+  } catch (error) {
+    if (['ENOENT', 'ELOOP', 'EISDIR'].includes(error.code)) return null;
+    throw error;
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+}
+
 function parseAgentMarkdown(content, fallbackName) {
   const name = content.match(/^name:\s*([^\r\n]+)$/m)?.[1]?.trim() || fallbackName;
   const raw = content.match(/^description:\s*(.+)$/m)?.[1]?.trim() || `SINAPSE ${name} agent`;
@@ -18,6 +34,15 @@ function renderCodexToml(name, description, instructions) {
   ].join('\n');
 }
 
+function markGlobalAgent(markdown, fileName = '') {
+  let content = markdown;
+  if (fileName === 'snps-orqx.md') {
+    content = content.replace(/^name:\s*snps-orqx\s*$/m, 'name: sinapse-orqx');
+  }
+  if (content.includes('SINAPSE-MANAGED:global-agent')) return content;
+  return `${content.trimEnd()}\n\n<!-- SINAPSE-MANAGED:global-agent -->\n`;
+}
+
 function renderGlobalSkill(skillId) {
   const generic = skillId === 'sinapse-agent';
   return [
@@ -28,7 +53,7 @@ function renderGlobalSkill(skillId) {
     '<!-- SINAPSE-MANAGED:global-skill -->', '',
     generic ? '# SINAPSE Global Agent Activator' : '# SINAPSE Global Orchestrator', '',
     generic
-      ? 'Use the requested ID from `~/.codex/agents/<id>.toml`; reject unknown IDs without guessing.'
+      ? 'Resolve the requested ID through the native agent catalog of the active provider; reject unknown IDs without guessing.'
       : 'Resolve this alias to the `sinapse-orqx` custom agent and preserve its delegation-only authority.',
     'Canonical global persona and task sources live under `~/.sinapse/`.',
     'Use native Codex delegation and never start a nested CLI.', '',
@@ -88,25 +113,63 @@ function writeGlobalSkillIfManaged(skillPath, content) {
   }
 }
 
+function removeStaleManagedAgents(targetDir, expectedFiles, extension) {
+  if (!fs.existsSync(targetDir)) return [];
+  const expected = new Set(expectedFiles);
+  const removed = [];
+  for (const file of fs.readdirSync(targetDir).filter((name) => name.endsWith(extension))) {
+    if (expected.has(file)) continue;
+    const filePath = path.join(targetDir, file);
+    const content = readRegularFileNoFollowSync(filePath, 'utf8');
+    if (content === null) continue;
+    const explicitlyManaged = content.includes('SINAPSE-MANAGED:global-agent');
+    const legacyManaged = content.includes('ACTIVATION-NOTICE: This command activates an agent from sinapse.')
+      && /\.sinapse[\\/]sinapse[\\/]agents[\\/]/.test(content)
+      && content.includes('Load the squad manifest');
+    if (!explicitlyManaged && !legacyManaged) continue;
+    fs.unlinkSync(filePath);
+    removed.push(file);
+  }
+  return removed;
+}
+
 function deliverGlobalProviderAdapters({ llmChoice, home, commandsDir }) {
-  const commandFiles = fs.existsSync(commandsDir)
+  let commandFiles = fs.existsSync(commandsDir)
     ? fs.readdirSync(commandsDir).filter((file) => file.endsWith('.md')).sort()
     : [];
-  const written = { claude: [], codex: [], skills: [] };
+  if (commandFiles.includes('snps-orqx.md')) {
+    const aliasFiles = new Set(['sinapse.md', 'sinapse-orqx.md', 'snps.md']);
+    commandFiles = commandFiles.filter((file) => !aliasFiles.has(file));
+  }
+  const written = { claude: [], claudeSkills: [], codex: [], skills: [] };
 
   if (llmChoice === 'claude-code' || llmChoice === 'both') {
     const targetDir = path.join(home, '.claude', 'agents');
     fs.mkdirSync(targetDir, { recursive: true });
+    removeStaleManagedAgents(targetDir, commandFiles, '.md');
     for (const file of commandFiles) {
-      fs.copyFileSync(path.join(commandsDir, file), path.join(targetDir, file));
+      const markdown = markGlobalAgent(fs.readFileSync(path.join(commandsDir, file), 'utf8'), file);
+      fs.writeFileSync(path.join(targetDir, file), markdown, 'utf8');
       written.claude.push(file);
     }
+    const skillsRoot = path.join(home, '.claude', 'skills');
+    for (const skillId of ['snps', 'sinapse', 'snps-orqx', 'sinapse-orqx', 'sinapse-agent']) {
+      const skillPath = path.join(skillsRoot, skillId, 'SKILL.md');
+      if (writeGlobalSkillIfManaged(skillPath, renderGlobalSkill(skillId))) {
+        written.claudeSkills.push(skillId);
+      }
+    }
   }
   if (llmChoice === 'codex' || llmChoice === 'both') {
     const targetDir = path.join(home, '.codex', 'agents');
     fs.mkdirSync(targetDir, { recursive: true });
+    removeStaleManagedAgents(
+      targetDir,
+      commandFiles.map((file) => file.replace(/\.md$/, '.toml')),
+      '.toml',
+    );
     for (const file of commandFiles) {
-      const markdown = fs.readFileSync(path.join(commandsDir, file), 'utf8');
+      const markdown = markGlobalAgent(fs.readFileSync(path.join(commandsDir, file), 'utf8'), file);
       const id = file.replace(/\.md$/, '');
       const metadata = parseAgentMarkdown(markdown, id);
       const tomlName = `${id}.toml`;
@@ -116,7 +179,7 @@ function deliverGlobalProviderAdapters({ llmChoice, home, commandsDir }) {
       written.codex.push(tomlName);
     }
     const skillsRoot = path.join(home, '.agents', 'skills');
-    for (const skillId of ['snps', 'sinapse', 'snps-orqx', 'sinapse-agent']) {
+    for (const skillId of ['snps', 'sinapse', 'snps-orqx', 'sinapse-orqx', 'sinapse-agent']) {
       const skillDir = path.join(skillsRoot, skillId);
       const skillPath = path.join(skillDir, 'SKILL.md');
       if (writeGlobalSkillIfManaged(skillPath, renderGlobalSkill(skillId))) {
@@ -128,9 +191,9 @@ function deliverGlobalProviderAdapters({ llmChoice, home, commandsDir }) {
 }
 
 function getGlobalCommandStagingDir({ llmChoice, sinapseHome, claudeCommandsDir }) {
-  return llmChoice === 'codex'
-    ? path.join(sinapseHome, '.generated', 'agents')
-    : claudeCommandsDir;
+  void llmChoice;
+  void claudeCommandsDir;
+  return path.join(sinapseHome, '.generated', 'agents');
 }
 
-module.exports = { parseAgentMarkdown, renderCodexToml, renderGlobalSkill, writeGlobalSkillIfManaged, deliverGlobalProviderAdapters, getGlobalCommandStagingDir };
+module.exports = { parseAgentMarkdown, renderCodexToml, markGlobalAgent, renderGlobalSkill, writeGlobalSkillIfManaged, removeStaleManagedAgents, deliverGlobalProviderAdapters, getGlobalCommandStagingDir };

package/bin/lib/provider-parity.js

@@ -0,0 +1,22 @@
+'use strict';
+
+function assertProviderAdapterParity(llmChoice, adapters, canonicalCount) {
+  if (!['claude-code', 'codex', 'both'].includes(llmChoice)) {
+    throw new Error(`Invalid LLM choice for provider parity: ${llmChoice}`);
+  }
+  const providerCounts = [];
+  if (llmChoice === 'claude-code' || llmChoice === 'both') {
+    providerCounts.push(['Claude Code', adapters.claude.length]);
+  }
+  if (llmChoice === 'codex' || llmChoice === 'both') {
+    providerCounts.push(['Codex', adapters.codex.length]);
+  }
+  const divergent = providerCounts.filter(([, count]) => count !== canonicalCount);
+  if (divergent.length) {
+    const details = divergent.map(([provider, count]) => `${provider}: ${count}/${canonicalCount}`).join(', ');
+    throw new Error(`Provider adapter parity failed (${details})`);
+  }
+  return canonicalCount;
+}
+
+module.exports = { assertProviderAdapterParity };

package/bin/postinstall.js

@@ -17,7 +17,7 @@
  *
  * Execution order (see Story A.1 AC 4):
  *   1. env guard (SINAPSE_SKIP_POSTINSTALL / CI)
- *   2. npm run sync:ide -- --ide claude-code
+ *   2. npm run sync:providers
  *   3. mkdir -p .sinapse/handoffs
  *   4. mkdir -p .sinapse/scratchpad
  *   5. sinapse doctor --quiet (exit code 2 = abort, 0/1 = OK)
@@ -30,7 +30,7 @@
  *
  * Exit codes:
  *   0  success OR non-critical warning (framework operational)
- *   2  critical failure (sync:ide failed, or doctor exit >= 2)
+ *   2  critical failure (provider sync failed, or doctor exit >= 2)
  *
  * Note: exit 1 is NOT used. npm treats any non-zero postinstall exit as
  * `command failed`, which scares users when the install is actually operational.
@@ -273,7 +273,7 @@ function run(command, args, opts = {}) {
  * Detect if we're running inside a global npm install.
  * Global installs land in /usr/local/lib/node_modules (Mac/Linux) or
  * %APPDATA%\npm\node_modules (Windows). Agent sync to those paths is pointless
- * — sync:ide must run inside a real project (per-project install).
+ * — sync:providers must run inside a real project (per-project install).
  */
 function isGlobalInstall() {
   if (process.env.npm_config_global === 'true') return true;
@@ -287,8 +287,8 @@ function isGlobalInstall() {
 }
 
 /**
- * Step 1: sync:ide --ide claude-code.
- * Copies agent definitions to .claude/commands/SINAPSE/agents/ so Claude Code can resolve @developer, etc.
+ * Step 1: synchronize native Claude and Codex provider adapters.
+ * Writes Claude agents to .claude/agents and Codex skills to .agents/skills.
  *
  * Skipped on global installs (no project to sync to). EACCES is treated as a
  * non-critical warning — the user can run `sinapse install` inside their project
@@ -296,17 +296,17 @@ function isGlobalInstall() {
  */
 function stepSyncIde() {
   if (isGlobalInstall()) {
-    verboseLog(`${c.dim}sync:ide pulado (install global — rode 'sinapse install' no seu projeto)${c.reset}`);
+    verboseLog(`${c.dim}sync:providers pulado (install global — rode 'sinapse install' no seu projeto)${c.reset}`);
     return { ok: true, critical: false, skipped: true };
   }
-  verboseLog(`${c.cyan}›${c.reset} Sincronizando agents para Claude Code...`);
-  const result = run('npm', ['run', 'sync:ide', '--silent', '--', '--ide', 'claude-code', '--quiet']);
+  verboseLog(`${c.cyan}›${c.reset} Sincronizando adapters para Claude Code e Codex...`);
+  const result = run('npm', ['run', 'sync:providers', '--silent']);
   if (result.error) {
     if (result.error.code === 'EACCES' || result.error.code === 'EPERM') {
       warn("Sem permissão pra sincronizar agents. Rode 'sinapse install' dentro do seu projeto.");
       return { ok: false, critical: false };
     }
-    warn(`sync:ide falhou ao iniciar: ${result.error.message} — rode 'sinapse install' no projeto pra completar.`);
+    warn(`sync:providers falhou ao iniciar: ${result.error.message} — rode 'sinapse install' no projeto pra completar.`);
     return { ok: false, critical: false };
   }
   if (result.status !== 0) {
@@ -315,7 +315,7 @@ function stepSyncIde() {
       warn("Sem permissão pra sincronizar agents (npm global sem write). Rode 'sinapse install' no seu projeto.");
       return { ok: false, critical: false };
     }
-    warn(`sync:ide saiu com código ${result.status} — rode 'sinapse install' no projeto pra completar.`);
+    warn(`sync:providers saiu com código ${result.status} — rode 'sinapse install' no projeto pra completar.`);
     return { ok: false, critical: false };
   }
   verboseLog(`${c.green}✓${c.reset} Agents sincronizados`);
@@ -380,7 +380,7 @@ function stepGenerateSynapse() {
     return { ok: true, critical: false, skipped: true };
   }
   // Run in-process (not a subprocess) — faster, and keeps the shared run()
-  // sequence (sync:ide → doctor) intact for callers/tests. The wrapper's
+  // sequence (sync:providers → doctor) intact for callers/tests. The wrapper's
   // generate() is tolerant and never throws; preserve our own exit code since
   // the underlying generator sets process.exitCode=1 on a miss.
   const savedExit = process.exitCode;

package/docs/framework/codex-parity/codex-integration-process.md

@@ -9,7 +9,7 @@ O Codex hoje e alvo de primeira classe no SINAPSE:
 
 - `AGENTS.md` como contrato operacional do projeto no Codex
 - suporte oficial no installer/sync (`codex` em `ide-configs`)
-- skills nativas via `.codex/skills` com estrategia local-first
+- skills nativas via `.agents/skills` com estrategia local-first e raiz unica
 - pipeline canonico de greeting/ativacao compartilhado
 - validadores dedicados para detectar drift rapidamente
 - suporte a notify command e hooks de ferramenta em releases recentes do Codex CLI
@@ -44,7 +44,7 @@ Regra prática para iniciantes:
 ### Artefatos Codex no projeto
 
 - Agentes auxiliares: `.codex/agents/`
-- Skills locais: `.codex/skills/sinapse-*/SKILL.md`
+- Skills locais: `.agents/skills/sinapse-*/SKILL.md`
 
 ## Fluxo Operacional Recomendado
 
@@ -65,8 +65,8 @@ Fallback: atalhos definidos em `AGENTS.md` (`@architect`, `/architect`, etc.).
 
 Este repositorio usa local-first para skills:
 
-- preferir `.codex/skills` versionado no projeto
-- evitar duplicar com `~/.codex/skills`
+- preferir `.agents/skills` versionado no projeto
+- nao gerar espelhos SINAPSE em `.codex/skills` ou `~/.codex/skills`
 - usar `npm run sync:skills:codex:global` apenas quando quiser instalacao global explicitamente
 
 Isso evita menu duplicado no `/skills` e reduz drift entre equipe/CI.
@@ -97,7 +97,7 @@ Criterio de sucesso:
 
 - `AGENTS.md` presente e coerente
 - `.codex/agents/*.md` existente
-- `.codex/skills/sinapse-*/SKILL.md` existente
+- `.agents/skills/sinapse-*/SKILL.md` existente
 - validadores sem erro
 
 ## Recursos Recentes do Codex (SINAPSE 4.0)
@@ -130,7 +130,7 @@ Mitigacao operacional no SINAPSE:
 ### Skills duplicadas no `/skills`
 
 Causa tipica:
-- artefatos duplicados entre `.codex/skills` e `~/.codex/skills`
+- artefatos SINAPSE duplicados entre raizes de skills descobertas pelo Codex
 
 Correcao:
 - manter local-first neste repo
@@ -168,4 +168,3 @@ Se houver divergencia entre estes documentos, a ordem de verdade para operacao d
 2. scripts reais em `package.json`
 3. este documento
 4. docs de overview
-

package/docs/framework/codex-parity/codex-native-runtime-v2.md

@@ -20,9 +20,9 @@ $sinapse-agent meta-ads-specialist
 ```
 
 `.codex/catalog.json` is the registry for this Codex activation surface. The
-native `.agents/skills` tree is mirrored to `.codex/skills` for compatibility
-with older Codex builds. Clean installs and upgrades reconcile managed files
-idempotently without deleting valid user-owned skills.
+native `.agents/skills` tree is the single Codex discovery surface. Clean
+installs and upgrades remove byte-identical legacy mirrors and quarantine
+divergent managed copies outside discovered skill roots without deleting them.
 
 The default tier deliberately exposes aliases, core agents, orchestrators and
 the parametric activator, not one selector entry per specialist. Users who need
@@ -89,9 +89,9 @@ Current Codex skill entrypoints live under `.agents/skills/`:
 - `sinapse-spec-driven` prepares PRD, Epic, Story, Spec, and Plan delivery.
 - `sinapse-loop` runs an explicitly requested bounded correction loop.
 
-Equivalent `.codex/skills/` copies are compatibility entrypoints for existing
-installations. New Codex discovery should use `.agents/skills/`; both locations
-resolve the same canonical SINAPSE sources.
+Legacy `.codex/skills/sinapse-*` copies are migration inputs only. They are not
+generated or shipped. `.agents/skills/` is the only active Codex skill root for
+SINAPSE.
 
 ## Hook and apply_patch bridge
 
@@ -205,8 +205,8 @@ npm run validate:codex-skills
 npx jest tests/integration/codex-native-golden-journey.test.js --runInBand
 ```
 
-`validate:codex-native` checks project TOML, 1:1 native-agent parity, native and
-compatibility skills, command targets, delegation equivalence, hooks, and the
+`validate:codex-native` checks project TOML, 1:1 native-agent parity, the unique
+native skill root, command targets, delegation equivalence, hooks, and the
 absence of nested Claude/Codex execution. `validate:codex-sync` runs both the
 legacy synchronization validator and the stricter native validator.
 

package/docs/framework/codex-parity/codex-parity-program.md

@@ -118,7 +118,7 @@ Requirements:
 ### Codex Skill Export Layer
 
 Purpose:
-Generate `.codex/skills` from the real Codex catalog, not from an incomplete upstream subset.
+Generate `.agents/skills` from the real Codex catalog, not from an incomplete upstream subset.
 
 Requirements:
 
@@ -222,7 +222,7 @@ Ensure all needed orqx and key framework agents are available through Codex skil
 
 Focus:
 
-- local-first `.codex/skills`
+- local-first `.agents/skills`
 - full orqx coverage
 - clean validation
 - no duplicate global/local skill confusion
@@ -492,7 +492,7 @@ Map the real Codex catalog, its upstreams, and current drift.
 Outputs:
 
 - inventory of `.codex/agents`
-- inventory of `.codex/skills`
+- inventory of `.agents/skills`
 - inventory of canonical sync sources
 - gap matrix between exported Codex artifacts and official sync assumptions
 
@@ -526,7 +526,7 @@ Outputs:
 
 - skill coverage matrix
 - export rules for orqx and core agents
-- clean local-first `.codex/skills` state
+- clean local-first `.agents/skills` state
 
 Success checks:
 

package/docs/framework/codex-parity/codex-total-parity-orchestration-plan.md

@@ -252,7 +252,7 @@ Mitigation:
 ### Risk 2 - Catalog/Skill Drift
 
 Risk:
-Expanded `.codex/agents`, `.codex/skills`, and command/delegation registries can drift apart.
+Expanded `.codex/agents`, `.agents/skills`, and command/delegation registries can drift apart.
 
 Mitigation:
 

package/docs/guides/codex-config.md

@@ -48,7 +48,7 @@ npm test
 - Validar command/task registry do Codex: `npm run validate:codex-commands`
 - Validar matriz de delegacao do Codex: `npm run validate:codex-delegation`
 - Gerar skills locais do Codex: `npm run sync:skills:codex`
-- Este repositorio usa **local-first**: prefira `.codex/skills` versionado no projeto
+- Este repositorio usa **local-first**: `.agents/skills` e a unica raiz de skills SINAPSE versionada no projeto
 - Use `sync:skills:codex:global` apenas para testes fora deste repo
 
 ## Command Resolution (Codex)
@@ -77,7 +77,7 @@ No Codex, nao trate handoffs exploratorios como se fossem caminhos garantidos pe
 ## Agent Shortcuts (Codex)
 
 Preferencia de ativacao no Codex CLI:
-1. Use `/skills` e selecione `sinapse-<agent-id>` vindo de `.codex/skills` (ex.: `sinapse-architect`)
+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`.

package/docs/guides/development-setup.md

@@ -225,7 +225,7 @@ sinapse-ai/
 │       └── checklists/            # Product checklists
 │
 ├── .claude/                       # Claude Code configuration
-│   ├── commands/SINAPSE/agents/      # Agent skill commands
+│   ├── agents/                       # Native Claude agents
 │   ├── hooks/                     # Governance hooks
 │   └── rules/                     # AI behavior rules
 │
@@ -1112,4 +1112,3 @@ node --inspect node_modules/.bin/jest
 
 _SINAPSE Development Setup Guide v1.0.0_
 _Last Updated: 2026-01-29_
-

package/docs/guides/ide-integration.md

@@ -64,7 +64,7 @@ If your goal is to get started as fast as possible:
 
 ```yaml
 config_file: .claude/CLAUDE.md
-agent_folder: .claude/commands/SINAPSE/agents
+agent_folder: .claude/agents
 activation: /agent-name (slash commands)
 format: full-markdown-yaml
 mcp_support: native
@@ -89,7 +89,7 @@ special_features:
 npm run sync:ide
 
 # Verify setup
-ls -la .claude/commands/SINAPSE/agents/
+ls -la .claude/agents/
 ```
 
 ---
@@ -102,7 +102,7 @@ ls -la .claude/commands/SINAPSE/agents/
 config_file: AGENTS.md
 agent_folder: .codex/agents
 activation: terminal instructions
-skills_folder: .codex/skills (source), ~/.codex/skills (Codex menu)
+skills_folder: .agents/skills (single native source)
 format: markdown
 mcp_support: native via Codex tooling
 special_features:
@@ -117,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 `.codex/skills`
+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.
 5. Use `npm run sync:skills:codex:global` only when you explicitly want global installation
 
@@ -132,7 +132,7 @@ npm run validate:codex-integration
 npm run validate:codex-skills
 
 # Verify setup
-ls -la AGENTS.md .codex/agents/ .codex/skills/
+ls -la AGENTS.md .codex/agents/ .agents/skills/
 ```
 
 ---
@@ -194,7 +194,7 @@ npm run sync:ide
 npm run sync:ide:check
 
 # Check platform-specific directory
-ls .claude/commands/SINAPSE/agents/       # Claude Code
+ls .claude/agents/       # Claude Code
 ```
 
 ### Sync Conflicts

package/docs/guides/quality-gates.md

@@ -162,7 +162,7 @@ layer2:
   quinn:
     enabled: true
     autoReview: true
-    agentPath: '.claude/commands/SINAPSE/agents/quality-gate.md'
+    agentPath: '.claude/agents/quality-gate.md'
     severity:
       block: ['CRITICAL']
       warn: ['HIGH', 'MEDIUM']
@@ -528,7 +528,7 @@ layer2:
   quinn:
     enabled: true
     autoReview: true
-    agentPath: '.claude/commands/SINAPSE/agents/quality-gate.md'
+    agentPath: '.claude/agents/quality-gate.md'
     severity:
       block: [CRITICAL]
       warn: [HIGH, MEDIUM]

package/docs/ide-integration.md

@@ -5,7 +5,7 @@
 | IDE | Status | Instructions File | Delegation | Skills |
 |-----|--------|------------------|------------|--------|
 | Claude Code | Works | `.claude/CLAUDE.md` | `.claude/rules/mandatory-delegation.md` | `.claude/commands/` |
-| Codex CLI | Limited | `.codex/instructions.md` | `.codex/delegation-matrix.json` | `.codex/skills/` |
+| Codex CLI | Native | `AGENTS.md` | `.codex/delegation-matrix.json` | `.agents/skills/` |
 
 ## Parity Requirements
 
@@ -19,7 +19,7 @@
 - instructions.md with agent activation rules
 - Delegation matrix in `.codex/delegation-matrix.json`
 - Delegation parity in `.codex/delegation-parity.json`
-- Skills in `.codex/skills/`
+- Skills in `.agents/skills/`
 - Agents in `.codex/agents/`
 
 ## Cross-IDE Contracts

package/docs/installation/faq.md

@@ -117,7 +117,7 @@ your-project/
 │   └── core-config.yaml        # Framework configuration
 │
 ├── .claude/                    # Claude Code (if selected)
-│   └── commands/SINAPSE/agents/   # Agent slash commands
+│   └── agents/                    # Native Claude agents
 │
 ├── docs/                       # Documentation structure
 │   ├── stories/                # Development stories

package/docs/installation/troubleshooting.md

@@ -548,7 +548,7 @@ nvm use 16
 
    ```bash
    # Claude Code
-   ls .claude/commands/SINAPSE/agents/
+   ls .claude/agents/
    ```
 
 3. Check IDE settings allow custom commands
@@ -566,7 +566,7 @@ nvm use 16
 **Solution:**
 
 1. Check IDE version is compatible
-2. For Claude Code: Files should be in `.claude/commands/`
+2. For Claude Code: Native agent files should be in `.claude/agents/`; `.claude/commands/` is only for slash commands
 3. Restart IDE after installation
 
 ---

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

@@ -198,7 +198,7 @@ your-project/
 │       ├── integrations/          # PM tool adapters
 │       └── templates/             # Config templates
 ├── .claude/                       # Claude Code configuration
-│   ├── commands/SINAPSE/agents/      # Agent skills
+│   ├── agents/                       # Native Claude agents
 │   └── rules/                     # Agent rules
 ├── docs/                          # Documentation
 │   └── stories/                   # Development stories

package/docs/pt/contributing.md

@@ -149,7 +149,7 @@ Agents sao personas de IA com expertise e comandos especificos.
 > **Cross-IDE parity (Story 10.18)**
 >
 > O diretorio `.sinapse-ai/development/agents/` e a fonte unica de verdade.
-> Ele se espelha automaticamente para `.claude/commands/SINAPSE/agents/` e
+> Ele se espelha automaticamente para `.claude/agents/` e
 > `.codex/agents/` via `npm run sync:ide`. O hook `lint-staged` ja roda o
 > sync quando voce comita um arquivo de agent, mas se voce editar um agent
 > e empurrar sem deixar o lint-staged rodar, o hook `pre-push` BLOQUEIA o

package/docs/pt/guides/development-setup.md

@@ -225,7 +225,7 @@ sinapse-ai/
 │       └── checklists/            # Checklists de produto
 │
 ├── .claude/                       # Configuração do Claude Code
-│   ├── commands/SINAPSE/agents/      # Comandos de skill dos agentes
+│   ├── agents/                       # Agentes nativos do Claude
 │   ├── hooks/                     # Hooks de governança
 │   └── rules/                     # Regras de comportamento da IA
 │
@@ -1112,4 +1112,3 @@ node --inspect node_modules/.bin/jest
 
 _SINAPSE Development Setup Guide v1.0.0_
 _Última Atualização: 2026-01-29_
-

package/docs/pt/guides/quality-gates.md

@@ -168,7 +168,7 @@ layer2:
   quinn:
     enabled: true
     autoReview: true
-    agentPath: '.claude/commands/SINAPSE/agents/quality-gate.md'
+    agentPath: '.claude/agents/quality-gate.md'
     severity:
       block: ['CRITICAL']
       warn: ['HIGH', 'MEDIUM']
@@ -534,7 +534,7 @@ layer2:
   quinn:
     enabled: true
     autoReview: true
-    agentPath: '.claude/commands/SINAPSE/agents/quality-gate.md'
+    agentPath: '.claude/agents/quality-gate.md'
     severity:
       block: [CRITICAL]
       warn: [HIGH, MEDIUM]

package/docs/pt/ide-integration.md

@@ -61,7 +61,7 @@ O SINAPSE suporta 5 plataformas de desenvolvimento com IA. Escolha a que melhor
 
 ```yaml
 config_file: .claude/CLAUDE.md
-agent_folder: .claude/commands/SINAPSE/agents
+agent_folder: .claude/agents
 activation: /agent-name (slash commands)
 format: full-markdown-yaml
 mcp_support: native
@@ -86,7 +86,7 @@ special_features:
 npm run sync:ide
 
 # Verificar configuração
-ls -la .claude/commands/SINAPSE/agents/
+ls -la .claude/agents/
 ```
 
 ---
@@ -99,7 +99,7 @@ ls -la .claude/commands/SINAPSE/agents/
 config_file: AGENTS.md
 agent_folder: .codex/agents
 activation: /skills + atalhos AGENTS.md
-skills_folder: .codex/skills (local), ~/.codex/skills (global)
+skills_folder: .agents/skills (fonte nativa unica)
 format: markdown
 mcp_support: nativo via Codex
 special_features:
@@ -120,7 +120,7 @@ special_features:
 ```bash
 npm run sync:ide:codex
 npm run sync:skills:codex
-ls -la AGENTS.md .codex/agents/ .codex/skills/
+ls -la AGENTS.md .codex/agents/ .agents/skills/
 ```
 
 ---
@@ -298,7 +298,7 @@ npm run sync:ide:check
 
 # Verificar diretório específico da plataforma
 ls .cursor/rules/  # Para Cursor
-ls .claude/commands/SINAPSE/agents/  # Para Claude Code
+ls .claude/agents/  # Para Claude Code
 ```
 
 ### Conflitos de Sincronização
@@ -367,7 +367,7 @@ cp -r .cursor/rules/ ./rules-backup/
 npm run sync:ide
 
 # Verificar migração
-diff -r ./rules-backup/ .claude/commands/SINAPSE/agents/
+diff -r ./rules-backup/ .claude/agents/
 ```
 
 ### De Claude Code para Cursor

package/docs/pt/installation/faq.md

@@ -125,7 +125,7 @@ your-project/
 │   └── core-config.yaml        # Configuração do framework
 │
 ├── .claude/                    # Claude Code (se selecionado)
-│   └── commands/SINAPSE/agents/   # Comandos slash de agentes
+│   └── agents/                    # Agentes nativos do Claude
 │
 ├── .cursor/                    # Cursor (se selecionado)
 │   └── rules/                  # Regras de agentes