sinapse-ai 1.25.0 → 1.25.1

package/docs/pt/installation/troubleshooting.md

@@ -554,7 +554,7 @@ nvm use 16
 
    ```bash
    # Claude Code
-   ls .claude/commands/SINAPSE/agents/
+   ls .claude/agents/
 
    # Cursor
    ls .cursor/rules/
@@ -576,7 +576,7 @@ nvm use 16
 
 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: Arquivos devem estar em `.claude/commands/`
+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
 
 ---
@@ -733,4 +733,3 @@ ls -la .sinapse-ai/
 ## Documentação Relacionada
 
 - [FAQ](./faq.md)
-

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

@@ -200,7 +200,7 @@ seu-projeto/
 │       ├── integrations/          # Adaptadores de PM tools
 │       └── templates/             # Templates de configuração
 ├── .claude/                       # Configuração Claude Code
-│   ├── commands/SINAPSE/agents/      # Skills de agentes
+│   ├── agents/                       # Agentes nativos do Claude
 │   └── rules/                     # Regras de agentes
 ├── docs/                          # Documentação
 │   └── stories/                   # Stories de desenvolvimento
@@ -267,4 +267,3 @@ git clone https://github.com/caioimori/sinapse-ai.git
 ---
 
 **Bem-vindo ao SINAPSE! Bom coding!**
-

package/docs/pt/platforms/claude-code.md

@@ -403,7 +403,7 @@ O Claude Code mostra status em tempo real:
 flowchart LR
     Source["SINAPSE Core<br/>.sinapse-ai/development/agents"] --> Parser["Parser de Agente"]
     Parser --> Transform["Transformador Claude"]
-    Transform --> Output[".claude/commands/SINAPSE/agents"]
+    Transform --> Output[".claude/agents"]
 ```
 
 ### Comandos de Sincronização
@@ -450,7 +450,7 @@ activation: /dev
 
 Quando conflitos ocorrem:
 
-1. Alterações locais são salvas em `.claude/commands/SINAPSE/agents/.backup/`
+1. Alterações locais são salvas em `.claude/agents/.backup/`
 2. Sync solicita resolução
 3. Escolha: manter local, usar remoto ou mesclar
 
@@ -524,7 +524,7 @@ Error: Unknown command '/xyz'
 npm run sync:ide
 
 # Verificar se o agente existe
-ls .claude/commands/SINAPSE/agents/
+ls .claude/agents/
 ```
 
 #### Permissão de Ferramenta Negada
@@ -588,7 +588,7 @@ R: Simplesmente use o comando slash para o agente desejado: `/dev`, `/qa`, etc.
 R: Sim, através do Task tool que pode criar subagentes.
 
 **P: Onde as definições de agentes são armazenadas?**
-R: Em `.claude/commands/SINAPSE/agents/` após a sincronização.
+R: Em `.claude/agents/` após a sincronização.
 
 **P: Com que frequência devo sincronizar agentes?**
 R: Após atualizar o SINAPSE ou quando agentes são modificados no core.

package/docs/sinapse-agent-flows/analyst-system.md

@@ -56,7 +56,7 @@ O agente Analyst e projetado para:
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/analyst.md` | Definição core do agente Analyst |
-| `.claude/commands/SINAPSE/agents/analyst.md` | Comando Claude Code para ativar @analyst |
+| `.claude/agents/analyst.md` | Comando Claude Code para ativar @analyst |
 
 ### Tasks do Analyst
 

package/docs/sinapse-agent-flows/architect-system.md

@@ -56,7 +56,7 @@ O agente **@architect** (Aria) e o **Holistic System Architect & Full-Stack Tech
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/architect.md` | Definição core do agente Architect |
-| `.claude/commands/SINAPSE/agents/architect.md` | Comando Claude Code para ativar @architect |
+| `.claude/agents/architect.md` | Comando Claude Code para ativar @architect |
 
 ### Arquivos de Templates do @architect
 

package/docs/sinapse-agent-flows/data-engineer-system.md

@@ -89,7 +89,7 @@ O agente **@data-engineer (Dara)** e o Database Architect & Operations Engineer
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/data-engineer.md` | Definição core do agente @data-engineer (persona, comandos, workflows) |
-| `.claude/commands/SINAPSE/agents/data-engineer.md` | Comando Claude Code para ativar @data-engineer |
+| `.claude/agents/data-engineer.md` | Comando Claude Code para ativar @data-engineer |
 
 ### Arquivos de Templates SQL
 

package/docs/sinapse-agent-flows/dev-system.md

@@ -55,7 +55,7 @@ O agente **@developer (Dex)** e o Full Stack Developer do SINAPSE, responsavel p
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/developer.md` | Definição core do agente @developer (persona, comandos, workflows) |
-| `.claude/commands/SINAPSE/agents/developer.md` | Comando Claude Code para ativar @developer |
+| `.claude/agents/developer.md` | Comando Claude Code para ativar @developer |
 
 ### Arquivos de Checklists Usados pelo @dev
 

package/docs/sinapse-agent-flows/pm-system.md

@@ -41,7 +41,7 @@ O agente PM e projetado para:
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/project-lead.md` | Definição core do agente PM |
-| `.claude/commands/SINAPSE/agents/project-lead.md` | Comando Claude Code para ativar @project-lead |
+| `.claude/agents/project-lead.md` | Comando Claude Code para ativar @project-lead |
 
 ### Tasks do @pm
 

package/docs/sinapse-agent-flows/qa-system.md

@@ -64,7 +64,7 @@ O agente **@quality-gate (Quinn)** e o Test Architect & Quality Advisor do SINAP
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/quality-gate.md` | Definição completa do agente QA |
-| `.claude/commands/SINAPSE/agents/quality-gate.md` | Comando Claude Code para ativar @quality-gate |
+| `.claude/agents/quality-gate.md` | Comando Claude Code para ativar @quality-gate |
 
 ### Arquivos de Workflow
 

package/docs/sinapse-agent-flows/sm-system.md

@@ -43,7 +43,7 @@ O agente **@sprint-lead (River)** e o Scrum Master tecnico do SINAPSE, especiali
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/sprint-lead.md` | Definição core do agente SM |
-| `.claude/commands/SINAPSE/agents/sprint-lead.md` | Comando Claude Code para ativar @sprint-lead |
+| `.claude/agents/sprint-lead.md` | Comando Claude Code para ativar @sprint-lead |
 | `.cursor/rules/sm.md` | Regras para Cursor IDE |
 | `.cursor/rules/sm.mdc` | Regras compiladas para Cursor |
 

package/docs/sinapse-agent-flows/snps-orqx-system.md

@@ -60,7 +60,7 @@ O **@sinapse-orqx** (Orion - The Orchestrator) e o meta-agente principal do fram
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/sinapse-orqx.md` | Definição completa do agente (persona, comandos, dependencias) |
-| `.claude/commands/SINAPSE/agents/sinapse-orqx.md` | Comando Claude Code para ativar @sinapse-orqx |
+| `.claude/agents/sinapse-orqx.md` | Comando Claude Code para ativar @sinapse-orqx |
 
 ### Arquivos de Templates do @sinapse-orqx
 

package/docs/sinapse-agent-flows/squad-creator-system.md

@@ -39,7 +39,7 @@ Este sistema implementa a **arquitetura task-first** do SINAPSE, onde tasks sao
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/squad-creator.md` | Definição core do agente Squad Creator |
-| `.claude/commands/SINAPSE/agents/squad-creator.md` | Comando Claude Code para ativar @squad-creator |
+| `.claude/agents/squad-creator.md` | Comando Claude Code para ativar @squad-creator |
 
 ### Arquivos de Tasks do @squad-creator
 
@@ -668,7 +668,7 @@ flowchart LR
 - [Script: squad-validator.js](../../.sinapse-ai/development/scripts/squad/squad-validator.js)
 - [Schema: squad-schema.json](../../.sinapse-ai/schemas/squad-schema.json)
 - [Agent: squad-creator.md](../../.sinapse-ai/development/agents/squad-creator.md)
-- [Command: squad-creator.md](../../.claude/commands/SINAPSE/agents/squad-creator.md)
+- [Command: squad-creator.md](../../.claude/agents/squad-creator.md)
 
 ---
 

package/docs/sinapse-agent-flows/ux-design-expert-system.md

@@ -88,7 +88,7 @@ flowchart TB
 | Arquivo | Propósito |
 |---------|-----------|
 | `.sinapse-ai/development/agents/ux-design-expert.md` | Definição completa do agente (persona, comandos, workflows) |
-| `.claude/commands/SINAPSE/agents/ux-design-expert.md` | Comando Claude Code para ativar @ux-design-expert |
+| `.claude/agents/ux-design-expert.md` | Comando Claude Code para ativar @ux-design-expert |
 
 ### Tasks por Fase
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.25.0",
+  "version": "1.25.1",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",
@@ -31,6 +31,7 @@
     "!.sinapse-ai/node_modules",
     "!**/node_modules/**",
     ".claude/CLAUDE.md",
+    ".claude/settings.json",
     ".claude/rules/",
     ".claude/hooks/",
     ".claude/agents/",
@@ -50,7 +51,6 @@
     ".codex/hooks/",
     ".codex/agents/",
     ".codex/scripts/",
-    ".codex/skills/",
     ".codex/tasks/",
     ".agents/skills/",
     "AGENTS.md",
@@ -113,29 +113,29 @@
     "validate:manifest": "node scripts/validate-manifest.js",
     "validate:manifest:parity": "node .sinapse-ai/infrastructure/scripts/validate-manifest-parity.js",
     "validate:agents": "node .sinapse-ai/infrastructure/scripts/validate-agents.js",
-    "sync:ide": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js sync",
-    "sync:ide:validate": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate",
-    "sync:ide:check": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --strict",
-    "sync:ide:claude": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js sync --ide claude-code",
+    "sync:ide": "node scripts/sync-provider-adapters.js",
+    "sync:ide:validate": "node scripts/validate-provider-adapters.js",
+    "sync:ide:check": "node scripts/validate-provider-adapters.js",
+    "sync:ide:claude": "node scripts/sync-provider-adapters.js",
     "sync:ide:codex": "node .sinapse-ai/infrastructure/scripts/sync-codex-local-first.js && node .codex/scripts/sync-codex-native.js",
     "sync:providers": "node scripts/sync-provider-adapters.js",
-    "validate:claude-sync": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --ide claude-code --strict",
-    "validate:claude-integration": "node .sinapse-ai/infrastructure/scripts/validate-claude-integration.js",
+    "validate:claude-sync": "node scripts/validate-provider-adapters.js",
+    "validate:claude-integration": "node scripts/validate-provider-adapters.js",
     "validate:providers": "node scripts/validate-provider-adapters.js",
     "validate:engineering-applicability": "jest tests/unit/engineering-applicability.test.js --runInBand",
     "validate:squad-schema": "node scripts/validate-squad-yaml.js",
     "validate:squad-schema:strict": "node scripts/validate-squad-yaml.js --strict",
-    "validate:codex-sync": "node .sinapse-ai/infrastructure/scripts/validate-codex-sync.js && node .codex/scripts/validate-codex-native.js",
+    "validate:codex-sync": "node .codex/scripts/validate-codex-native.js && node scripts/validate-codex-command-registry.js && node .sinapse-ai/infrastructure/scripts/validate-codex-integration.js && node .sinapse-ai/infrastructure/scripts/validate-codex-delegation.js",
     "validate:codex-native": "node .codex/scripts/validate-codex-native.js",
     "validate:codex-integration": "node .sinapse-ai/infrastructure/scripts/validate-codex-integration.js",
-    "validate:codex-commands": "node .sinapse-ai/infrastructure/scripts/validate-codex-command-registry.js",
+    "validate:codex-commands": "node scripts/validate-codex-command-registry.js",
     "validate:codex-delegation": "node .sinapse-ai/infrastructure/scripts/validate-codex-delegation.js",
-    "sync:skills:codex": "node .sinapse-ai/infrastructure/scripts/codex-skills-sync/index.js",
-    "sync:skills:codex:global": "node .sinapse-ai/infrastructure/scripts/codex-skills-sync/index.js --global --global-only",
-    "validate:codex-skills": "node .sinapse-ai/infrastructure/scripts/codex-skills-sync/validate.js --strict",
+    "sync:skills:codex": "node .codex/scripts/sync-codex-native.js",
+    "sync:skills:codex:global": "node bin/cli.js install --llm=codex --global-only",
+    "validate:codex-skills": "node .codex/scripts/validate-codex-native.js",
     "validate:paths": "node .sinapse-ai/infrastructure/scripts/validate-paths.js",
-    "validate:parity": "node .sinapse-ai/infrastructure/scripts/validate-parity.js",
-    "validate:parity:fast": "node .sinapse-ai/infrastructure/scripts/validate-parity.js --fast --quiet",
+    "validate:parity": "node scripts/validate-provider-adapters.js && node .codex/scripts/validate-codex-native.js && node scripts/validate-codex-command-registry.js && node .sinapse-ai/infrastructure/scripts/validate-codex-integration.js && node .sinapse-ai/infrastructure/scripts/validate-codex-delegation.js && node .sinapse-ai/infrastructure/scripts/validate-paths.js",
+    "validate:parity:fast": "node scripts/validate-provider-adapters.js && node scripts/validate-codex-command-registry.js",
     "collab:adopt": "node bin/utils/collab-start.js --adopt-current",
     "collab:check": "node bin/utils/collab-start.js --check",
     "collab:start": "node bin/utils/collab-start.js",
@@ -264,5 +264,10 @@
     "ip-address": "^10.1.1",
     "@babel/core": "^7.29.6",
     "js-yaml": "^4.2.0"
-  }
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "type": "commonjs"
 }

package/packages/installer/src/config/ide-configs.js

@@ -38,7 +38,7 @@ const IDE_CONFIGS = {
     requiresDirectory: true,
     format: 'text',
     recommended: true,
-    agentFolder: path.join('.claude', 'commands', 'SINAPSE', 'agents'),
+    agentFolder: path.join('.claude', 'agents'),
   },
   codex: {
     name: 'Codex CLI',

package/packages/installer/src/installer/sinapse-ai-installer.js

@@ -9,10 +9,29 @@
  */
 
 const fs = require('fs-extra');
+const nativeFs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const ora = require('ora');
 const { hashFile } = require('./file-hasher');
 
+const NOFOLLOW_READ_FLAGS = nativeFs.constants.O_RDONLY | (nativeFs.constants.O_NOFOLLOW || 0);
+
+async function readRegularFileNoFollow(filePath) {
+  let handle;
+  try {
+    handle = await nativeFs.promises.open(filePath, NOFOLLOW_READ_FLAGS);
+    const stat = await handle.stat();
+    if (!stat.isFile()) return null;
+    return await handle.readFile();
+  } catch (error) {
+    if (['ENOENT', 'ELOOP', 'EISDIR'].includes(error.code)) return null;
+    throw error;
+  } finally {
+    if (handle) await handle.close();
+  }
+}
+
 /**
  * Get the path to the source .sinapse-ai directory in the package
  * @returns {string} Absolute path to .sinapse-ai source
@@ -62,6 +81,82 @@ const ROOT_FILES_TO_COPY = [
 const CODEX_TOP_LEVEL_DIRS = ['.agents', '.codex'];
 const CLAUDE_SUPPORT_DIRS = ['.claude/hooks', '.claude/rules'];
 
+function getClaudeHookName(command) {
+  const match = String(command || '').replace(/\\/g, '/').match(/\.claude\/hooks\/([^"'\s]+)/);
+  return match ? match[1] : null;
+}
+
+function getClaudeHookRegistrationKey(event, matcher, hookName) {
+  return JSON.stringify([event, matcher ?? null, hookName]);
+}
+
+/** Merge shipped SINAPSE hook registrations without replacing user settings. */
+async function reconcileClaudeHookSettings(packageRoot, targetDir) {
+  const sourcePath = path.join(packageRoot, '.claude', 'settings.json');
+  if (!await fs.pathExists(sourcePath)) return null;
+
+  const targetPath = path.join(targetDir, '.claude', 'settings.local.json');
+  const source = await fs.readJson(sourcePath);
+  let target = {};
+  if (await fs.pathExists(targetPath)) {
+    try {
+      target = await fs.readJson(targetPath);
+    } catch (_error) {
+      // Preserve malformed user settings verbatim. The installer must not turn
+      // a recoverable configuration problem into data loss or a failed install.
+      return null;
+    }
+  }
+  if (!target || typeof target !== 'object' || Array.isArray(target)) return null;
+  if (!target.hooks || typeof target.hooks !== 'object' || Array.isArray(target.hooks)) {
+    target.hooks = {};
+  }
+
+  const existingSettings = [target];
+  const projectSettingsPath = path.join(targetDir, '.claude', 'settings.json');
+  if (await fs.pathExists(projectSettingsPath)) {
+    try {
+      const projectSettings = await fs.readJson(projectSettingsPath);
+      if (projectSettings && typeof projectSettings === 'object' && !Array.isArray(projectSettings)) {
+        existingSettings.push(projectSettings);
+      }
+    } catch (_error) {
+      // An invalid sibling settings file cannot provide reliable registrations;
+      // ignore it while retaining its contents and merge into settings.local.
+    }
+  }
+  const registered = new Set();
+  for (const settings of existingSettings) {
+    for (const [event, groups] of Object.entries(settings.hooks || {})) {
+      for (const group of Array.isArray(groups) ? groups : []) {
+        for (const hook of Array.isArray(group.hooks) ? group.hooks : []) {
+          const hookName = getClaudeHookName(hook.command);
+          if (hookName) registered.add(getClaudeHookRegistrationKey(event, group.matcher, hookName));
+        }
+      }
+    }
+  }
+
+  for (const [event, groups] of Object.entries(source.hooks || {})) {
+    if (!Array.isArray(target.hooks[event])) target.hooks[event] = [];
+    for (const group of groups || []) {
+      for (const hook of group.hooks || []) {
+        const hookName = getClaudeHookName(hook.command);
+        const registrationKey = getClaudeHookRegistrationKey(event, group.matcher, hookName);
+        if (!hookName || registered.has(registrationKey)) continue;
+        const registration = { hooks: [hook] };
+        if (group.matcher) registration.matcher = group.matcher;
+        target.hooks[event].push(registration);
+        registered.add(registrationKey);
+      }
+    }
+  }
+
+  await fs.ensureDir(path.dirname(targetPath));
+  await fs.writeJson(targetPath, target, { spaces: 2 });
+  return path.join('.claude', 'settings.local.json');
+}
+
 /**
  * Replace {root} placeholder in file content
  * @param {string} content - File content
@@ -121,9 +216,22 @@ async function generateVersionJson(options) {
     installedFiles,
     mode = 'project-development',
     providers = [],
+    targetDir = path.dirname(targetSinapseCore),
+    providerFiles = [],
+    providerSourceRoot = targetDir,
   } = options;
 
   const fileHashes = await generateFileHashes(targetSinapseCore, installedFiles);
+  const providerFileHashes = {};
+  for (const relativePath of providerFiles) {
+    const sourcePath = path.join(providerSourceRoot, relativePath);
+    const sourceContent = await readRegularFileNoFollow(sourcePath);
+    if (sourceContent !== null) {
+      const installedContent = replaceRootPlaceholder(sourceContent.toString('utf8'));
+      const digest = crypto.createHash('sha256').update(installedContent).digest('hex');
+      providerFileHashes[relativePath.replace(/\\/g, '/')] = `sha256:${digest}`;
+    }
+  }
 
   const versionJson = {
     version,
@@ -131,6 +239,7 @@ async function generateVersionJson(options) {
     mode,
     providers: [...new Set(providers)].sort(),
     fileHashes,
+    providerFileHashes,
     customized: [],
   };
 
@@ -162,17 +271,158 @@ function isUserOwnedL3(destPath) {
   return false;
 }
 
-function isUserOwnedCodexConfig(destPath) {
-  const norm = String(destPath).replace(/\\/g, '/');
-  if (norm.endsWith('/.codex/config.toml') || norm.endsWith('/.codex/hooks.json')) return true;
-  if (/\/\.agents\/skills\/[^/]+\/SKILL\.md$/.test(norm)) {
-    const compatibilityPath = destPath.replace(
-      `${path.sep}.agents${path.sep}skills${path.sep}`,
-      `${path.sep}.codex${path.sep}skills${path.sep}`,
+function getManagedCodexSkillPaths(packageRoot) {
+  const catalog = fs.readJsonSync(path.join(packageRoot, '.codex', 'catalog.json'));
+  return [...new Set([
+    ...(catalog.expectedSkillIds || []),
+    ...(catalog.publicAliasSkillIds || []),
+    catalog.genericAgentSkillId,
+  ].filter(Boolean))]
+    .sort()
+    .map((skillId) => path.posix.join('.agents', 'skills', skillId, 'SKILL.md'));
+}
+
+function createCodexPreservePredicate(targetDir, packageRoot, previousProviderHashes = {}) {
+  const legacyRegistry = fs.readJsonSync(path.join(
+    packageRoot,
+    'packages',
+    'installer',
+    'src',
+    'migrations',
+    'legacy-codex-native-skill-hashes.json',
+  ));
+  return (destPath) => {
+    const normalized = String(destPath).replace(/\\/g, '/');
+    if (normalized.endsWith('/.codex/config.toml') || normalized.endsWith('/.codex/hooks.json')) return true;
+    if (!/\/(?:\.codex|\.agents)\/skills\/[^/]+\/SKILL\.md$/.test(normalized)) return false;
+    if (!fs.existsSync(destPath)) return false;
+    const relativePath = path.relative(targetDir, destPath).replace(/\\/g, '/');
+    const digest = hashFile(destPath);
+    const previous = String(previousProviderHashes[relativePath] || '').replace(/^sha256:/, '');
+    const legacyHashes = legacyRegistry.files[relativePath] || [];
+    return digest !== previous && !legacyHashes.includes(digest);
+  };
+}
+
+async function reconcileLegacyCodexSkills(targetDir, packageRoot) {
+  const catalogPath = path.join(packageRoot, '.codex', 'catalog.json');
+  if (!await fs.pathExists(catalogPath)) return { removed: 0, migrated: 0, quarantined: 0, ambiguous: [] };
+
+  const catalog = await fs.readJson(catalogPath);
+  const managedIds = [...new Set([
+    ...(catalog.expectedSkillIds || []),
+    ...(catalog.publicAliasSkillIds || []),
+    catalog.genericAgentSkillId,
+  ].filter((id) => /^[a-z0-9][a-z0-9-]*$/.test(String(id))))].sort();
+  const result = { removed: 0, migrated: 0, quarantined: 0, ambiguous: [] };
+
+  for (const skillId of managedIds) {
+    const legacyPath = path.join(targetDir, '.codex', 'skills', skillId, 'SKILL.md');
+    if (!await fs.pathExists(legacyPath)) continue;
+    const legacyContent = await readRegularFileNoFollow(legacyPath);
+    if (legacyContent === null) {
+      result.ambiguous.push(path.relative(targetDir, legacyPath));
+      continue;
+    }
+
+    const nativePath = path.join(targetDir, '.agents', 'skills', skillId, 'SKILL.md');
+    if (!await fs.pathExists(nativePath)) {
+      await fs.ensureDir(path.dirname(nativePath));
+      try {
+        await fs.writeFile(nativePath, legacyContent, { flag: 'wx' });
+      } catch (error) {
+        if (error.code === 'EEXIST') {
+          result.ambiguous.push(path.relative(targetDir, legacyPath));
+          continue;
+        }
+        throw error;
+      }
+      await fs.remove(legacyPath);
+      if ((await fs.readdir(path.dirname(legacyPath))).length === 0) {
+        await fs.remove(path.dirname(legacyPath));
+      }
+      result.migrated += 1;
+      continue;
+    }
+
+    const nativeContent = await readRegularFileNoFollow(nativePath);
+    if (nativeContent === null) {
+      result.ambiguous.push(path.relative(targetDir, legacyPath));
+      continue;
+    }
+    if (legacyContent.equals(nativeContent)) {
+      await fs.remove(legacyPath);
+      if ((await fs.readdir(path.dirname(legacyPath))).length === 0) {
+        await fs.remove(path.dirname(legacyPath));
+      }
+      result.removed += 1;
+      continue;
+    }
+
+    const digest = crypto.createHash('sha256').update(legacyContent).digest('hex').slice(0, 12);
+    const quarantinePath = path.join(
+      targetDir,
+      '.sinapse-ai',
+      'migrations',
+      'codex-skills',
+      `${skillId}.${digest}.legacy.md`,
     );
-    if (!fs.existsSync(destPath) && fs.existsSync(compatibilityPath)) return true;
+    await fs.ensureDir(path.dirname(quarantinePath));
+    try {
+      await fs.writeFile(quarantinePath, legacyContent, { flag: 'wx' });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const quarantinedContent = await readRegularFileNoFollow(quarantinePath);
+      if (quarantinedContent === null || !quarantinedContent.equals(legacyContent)) {
+        result.ambiguous.push(path.relative(targetDir, legacyPath));
+        continue;
+      }
+    }
+    await fs.remove(legacyPath);
+    if ((await fs.readdir(path.dirname(legacyPath))).length === 0) {
+      await fs.remove(path.dirname(legacyPath));
+    }
+    result.quarantined += 1;
+  }
+
+  return result;
+}
+
+async function reconcileLegacyClaudeAgentCommands(targetDir, packageRoot = path.join(__dirname, '..', '..', '..', '..')) {
+  const legacyDir = path.join(targetDir, '.claude', 'commands', 'SINAPSE', 'agents');
+  const result = { removed: 0, preserved: 0, ambiguous: [] };
+  if (!await fs.pathExists(legacyDir)) return result;
+
+  const registryPath = path.join(
+    packageRoot,
+    'packages',
+    'installer',
+    'src',
+    'migrations',
+    'legacy-claude-agent-command-hashes.json',
+  );
+  const registry = await fs.readJson(registryPath);
+  for (const entry of await fs.readdir(legacyDir, { withFileTypes: true })) {
+    const filePath = path.join(legacyDir, entry.name);
+    if (!entry.isFile()) {
+      result.preserved += 1;
+      result.ambiguous.push(path.relative(targetDir, filePath));
+      continue;
+    }
+    const content = await fs.readFile(filePath);
+    const digest = crypto.createHash('sha256').update(content).digest('hex');
+    const knownHashes = registry.files[entry.name] || [];
+    const isMarked = content.includes(Buffer.from('SINAPSE-MANAGED:claude-command'));
+    if (knownHashes.includes(digest) || isMarked) {
+      await fs.remove(filePath);
+      result.removed += 1;
+    } else {
+      result.preserved += 1;
+      result.ambiguous.push(path.relative(targetDir, filePath));
+    }
   }
-  return /\/(?:\.codex|\.agents)\/skills\/[^/]+\/SKILL\.md$/.test(norm);
+  if ((await fs.readdir(legacyDir)).length === 0) await fs.remove(legacyDir);
+  return result;
 }
 
 async function copyFileWithRootReplacement(sourcePath, destPath, replaceRoot = true, preserveExisting = null) {
@@ -350,6 +600,15 @@ async function installSinapseCore(options = {}) {
   try {
     const sourceDir = getSinapseCoreSourcePath();
     const targetSinapseCore = path.join(targetDir, '.sinapse-ai');
+    const previousVersionPath = path.join(targetSinapseCore, 'version.json');
+    let previousProviderHashes = {};
+    if (await fs.pathExists(previousVersionPath)) {
+      try {
+        previousProviderHashes = (await fs.readJson(previousVersionPath)).providerFileHashes || {};
+      } catch (_error) {
+        previousProviderHashes = {};
+      }
+    }
 
     // Check if source exists
     if (!await fs.pathExists(sourceDir)) {
@@ -415,7 +674,7 @@ async function installSinapseCore(options = {}) {
       if (await fs.pathExists(src)) {
         spinner.text = `Copying ${dirName}...`;
         const preserveExisting = dirName === '.codex' || dirName === '.agents'
-          ? isUserOwnedCodexConfig
+          ? createCodexPreservePredicate(targetDir, pkgRoot, previousProviderHashes)
           : null;
         const copied = await copyDirectoryWithRootReplacement(
           src,
@@ -431,6 +690,7 @@ async function installSinapseCore(options = {}) {
     }
 
     if (includeClaude) {
+      result.claudeLegacyAgentCommandReconciliation = await reconcileLegacyClaudeAgentCommands(targetDir, pkgRoot);
       const claude = await deliverClaudeNativeAdapters(pkgRoot, targetDir, { overwriteManaged: overwriteManagedAdapters });
       result.claudeNativeAgentFiles = claude.agents.length;
       result.claudeNativeSkillFiles = claude.skills.length;
@@ -441,6 +701,8 @@ async function installSinapseCore(options = {}) {
       if (await fs.pathExists(claudeContextSource) && await copyFileWithRootReplacement(claudeContextSource, claudeContextDest, true)) {
         result.installedFiles.push(path.join('.claude', 'CLAUDE.md'));
       }
+      const claudeSettings = await reconcileClaudeHookSettings(pkgRoot, targetDir);
+      if (claudeSettings) result.installedFiles.push(claudeSettings);
     }
 
     // AGENTS.md is the Codex CLI's default context file (Imperator greeting +
@@ -455,6 +717,7 @@ async function installSinapseCore(options = {}) {
         result.installedFiles.push('AGENTS.md');
         result.agentsMdInstalled = true;
       }
+      result.codexLegacySkillReconciliation = await reconcileLegacyCodexSkills(targetDir, pkgRoot);
     }
 
     // Create install manifest
@@ -481,6 +744,9 @@ async function installSinapseCore(options = {}) {
       installedFiles: result.installedFiles,
       mode: 'project-development',
       providers: [includeClaude && 'claude-code', includeCodex && 'codex'].filter(Boolean),
+      targetDir,
+      providerFiles: includeCodex ? getManagedCodexSkillPaths(pkgRoot) : [],
+      providerSourceRoot: pkgRoot,
     });
     result.versionInfo = versionInfo;
 
@@ -602,10 +868,16 @@ module.exports = {
   copyFileWithRootReplacement,
   copyDirectoryWithRootReplacement,
   isUserOwnedL3,
+  createCodexPreservePredicate,
+  getManagedCodexSkillPaths,
+  reconcileLegacyCodexSkills,
+  reconcileLegacyClaudeAgentCommands,
   generateVersionJson,
   generateFileHashes,
   deliverCodexRootFiles,
   deliverClaudeNativeAdapters,
+  getClaudeHookName,
+  reconcileClaudeHookSettings,
   FOLDERS_TO_COPY,
   ROOT_FILES_TO_COPY,
   CODEX_ROOT_FILES,