sinapse-ai 1.24.0 → 1.25.1

package/bin/commands/update.js

@@ -29,7 +29,14 @@ const {
 } = require('../lib/detection');
 const { promptLlmChoice } = require('../lib/prompts');
 const { generateSquadAwareness } = require('./install');
+const {
+  recordInstalledAgents,
+  reconcileInstalledAgents,
+  removeManagedGlobalSkills,
+} = require('./uninstall');
 const { regenerateAgentCommands } = require('../lib/command-generator');
+const { deliverGlobalProviderAdapters, getGlobalCommandStagingDir } = require('../lib/global-provider-adapters');
+const { assertProviderAdapterParity } = require('../lib/provider-parity');
 const { execSync } = require('child_process');
 
 // Query the latest version published to npm. Returns null when npm is unreachable.
@@ -146,39 +153,46 @@ async function cmdUpdateGlobal() {
     logger.always(`  ${GREEN}OK${NC} sinapse (orqx)`);
   }
 
+  const coreDevelopmentSrc = path.join(ROOT, '.sinapse-ai', 'development');
+  const coreDevelopmentDest = path.join(SINAPSE_HOME, 'core');
+  if (fs.existsSync(coreDevelopmentSrc)) {
+    const delta = syncDirSync(coreDevelopmentSrc, coreDevelopmentDest);
+    totalDelta.added += delta.added;
+    totalDelta.updated += delta.updated;
+    totalDelta.unchanged += delta.unchanged;
+    totalDelta.removed += delta.removed;
+    logger.always(`  ${GREEN}OK${NC} core development`);
+  }
+
   // Phase 2: Regenerate commands — shared with `install` so `update` produces the
   // SAME complete set (every specialist command + the rich master Imperator stubs),
   // not just the `-orqx` subset it used to write.
   logger.always(`\n${CYAN}Phase 2:${NC} Regenerating commands`);
-  rmDirSync(CLAUDE_COMMANDS_DIR);
+  const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
+  rmDirSync(commandStagingDir);
   const { writtenAgents, totalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
-    commandsDir: CLAUDE_COMMANDS_DIR,
+    commandsDir: commandStagingDir,
     squads,
     sinapseMasterDest: path.join(SINAPSE_HOME, 'sinapse'),
+    coreDevelopmentDest,
   });
   logger.always(`  ${GREEN}OK${NC} ${writtenAgents.size} command files (${totalAgents} agents total)`);
 
   // Phase 2b: Install global agents based on LLM choice
-  if (llmChoice === 'claude-code' || llmChoice === 'both') {
-    const globalAgentsDir = path.join(HOME, '.claude', 'agents');
-    fs.mkdirSync(globalAgentsDir, { recursive: true });
-    // Copy all generated agent commands as global agents
-    for (const f of fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'))) {
-      fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(globalAgentsDir, f));
-    }
-    logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${writtenAgents.size})`);
-  }
+  const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
+  const activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  if (globalAdapters.claude.length) logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${globalAdapters.claude.length})`);
+  if (globalAdapters.codex.length) logger.always(`  ${GREEN}OK${NC} Codex global agents (${globalAdapters.codex.length} TOML, ${globalAdapters.skills.length} skills)`);
 
-  if (llmChoice === 'codex' || llmChoice === 'both') {
-    const codexAgentsDir = path.join(HOME, '.codex', 'agents');
-    fs.mkdirSync(codexAgentsDir, { recursive: true });
-    // Copy all generated agent commands for Codex
-    for (const f of fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'))) {
-      fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(codexAgentsDir, f));
-    }
-    logger.always(`  ${GREEN}OK${NC} Codex global agents (${writtenAgents.size})`);
-  }
+  const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
+  reconcileInstalledAgents(HOME, installedAgentFilenames);
+  if (llmChoice === 'claude-code') removeManagedGlobalSkills(HOME, { providers: ['codex'] });
+  if (llmChoice === 'codex') removeManagedGlobalSkills(HOME, { providers: ['claude-code'] });
+  const installedIdes = [];
+  if (globalAdapters.claude.length) installedIdes.push('claude-code');
+  if (globalAdapters.codex.length) installedIdes.push('codex');
+  recordInstalledAgents(installedAgentFilenames, installedIdes);
 
   // Phase 3: Regenerate awareness
   logger.always(`\n${CYAN}Phase 3:${NC} Updating squad-awareness`);
@@ -192,7 +206,8 @@ async function cmdUpdateGlobal() {
   meta.updatedAt = new Date().toISOString();
   meta.version = VERSION;
   meta.squads = squads.length;
-  meta.commands = writtenAgents.size;
+  meta.agents = activeAgentCount;
+  meta.commands = activeAgentCount;
   meta.llm = llmChoice;
   fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
 
@@ -235,9 +250,9 @@ async function cmdUpdateGlobal() {
   logger.always(`${GREEN}  SINAPSE AI atualizado para v${VERSION}!${NC}`);
   logger.always(`${GREEN}══════════════════════════════════════════════════════════════${NC}`);
   logger.always('');
-  logger.always(`  ${BOLD}${squads.length} squads${NC} | ${BOLD}${totalAgents} agents${NC} | ${BOLD}${writtenAgents.size} command files${NC}`);
+  logger.always(`  ${BOLD}${squads.length} squads${NC} | ${BOLD}${activeAgentCount} agents${NC} | ${BOLD}${activeAgentCount} native adapters${NC}`);
   logger.always(`  ${startCmd}`);
   logger.always('');
 }
 
-module.exports = { cmdUpdateGlobal };
+module.exports = { cmdUpdateGlobal, assertProviderAdapterParity };

package/bin/lib/command-generator.js

@@ -116,7 +116,7 @@ Tasks: \`${squadPath}/tasks/\` · Workflows: \`${squadPath}/workflows/\` · Mani
 `;
 }
 
-function generateCommandMd(agentId, agentName, agentIcon, squadName, squadPath, agentFile) {
+function generateCommandMd(agentId, agentName, agentIcon, squadName, squadPath, agentFile, options = {}) {
   // Detecta se é orquestrador: id termina em -orqx OU é Imperator (snps-orqx/sinapse-orqx)
   // ou um dos apelidos curtos do master (sinapse/snps).
   const isOrchestrator = /-orqx$/.test(agentId) || agentId === 'snps-orqx' || agentId === 'sinapse-orqx' || agentId === 'sinapse' || agentId === 'snps';
@@ -139,6 +139,12 @@ function generateCommandMd(agentId, agentName, agentIcon, squadName, squadPath,
   const fmDesc = (isOrchestrator
     ? `${agentName || agentId} — orchestrator for ${squadName}; diagnoses, routes to specialists and auto-generates an orchestration plan`
     : `${agentName || agentId} — ${squadName} specialist`).replace(/["\n\r]/g, ' ').trim();
+  const manifestActivation = options.hasManifest === false
+    ? '2. Use the installed core development module as canonical context'
+    : `2. Load the squad manifest at \`${squadPath}/squad.yaml\` for context`;
+  const manifestReference = options.hasManifest === false
+    ? `- **Canonical module:** \`${squadPath}/\``
+    : `- **Squad Manifest:** \`${squadPath}/squad.yaml\``;
 
   return `---
 name: ${agentId}
@@ -151,7 +157,7 @@ ACTIVATION-NOTICE: This command activates an agent from ${squadName}.
 
 CRITICAL: Read the agent definition file at \`${squadPath}/agents/${agentFile}\` to understand your full operating parameters. Then:
 1. Adopt the persona defined in that file (name: ${agentName}, icon: ${agentIcon})
-2. Load the squad manifest at \`${squadPath}/squad.yaml\` for context
+${manifestActivation}
 3. Display a greeting showing your agent name, role, and available commands
 ${step4}
 
@@ -159,7 +165,7 @@ ${step4}
 - **Agent ID:** ${agentId}
 - **Squad:** ${squadName}
 - **Definition:** \`${squadPath}/agents/${agentFile}\`
-- **Squad Manifest:** \`${squadPath}/squad.yaml\`
+${manifestReference}
 - **Tasks:** \`${squadPath}/tasks/\`
 - **Knowledge Bases:** \`${squadPath}/knowledge-base/\`
 - **Workflows:** \`${squadPath}/workflows/\`
@@ -209,6 +215,7 @@ function regenerateAgentCommands(deps = {}) {
     commandsDir = CLAUDE_COMMANDS_DIR,
     squads,
     sinapseMasterDest = path.join(sinapseHome, 'sinapse'),
+    coreDevelopmentDest = path.join(sinapseHome, 'core'),
   } = deps;
 
   if (!Array.isArray(squads)) {
@@ -244,6 +251,21 @@ function regenerateAgentCommands(deps = {}) {
     }
   }
 
+  // Core agents are mirrored by the global installer so definitions and tasks
+  // remain resolvable after the npm process exits.
+  const coreAgentsDir = path.join(coreDevelopmentDest, 'agents');
+  if (fs.existsSync(coreAgentsDir)) {
+    const coreBase = toForwardSlash(coreDevelopmentDest);
+    for (const file of fs.readdirSync(coreAgentsDir).filter(f => f.endsWith('.md'))) {
+      if (file === 'README.md' || file === 'MEMORY.md' || file.startsWith('_') || writtenAgents.has(file)) continue;
+      const agentId = file.replace('.md', '');
+      const meta = extractAgentMeta(path.join(coreAgentsDir, file));
+      const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'core', coreBase, file, { hasManifest: false });
+      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
+      writtenAgents.add(file);
+    }
+  }
+
   // 2. Commands for sinapse/ master squad agents.
   if (fs.existsSync(sinapseMasterDest)) {
     const masterAgentsDir = path.join(sinapseMasterDest, 'agents');

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

@@ -0,0 +1,199 @@
+'use strict';
+
+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`;
+  return { name, description: raw.replace(/^['"]|['"]$/g, '') };
+}
+
+function renderCodexToml(name, description, instructions) {
+  return [
+    `name = ${JSON.stringify(name)}`,
+    `description = ${JSON.stringify(description)}`,
+    `developer_instructions = ${JSON.stringify(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 [
+    '---',
+    `name: ${skillId}`,
+    `description: ${generic ? 'Resolve and activate any globally installed SINAPSE agent by ID.' : 'Activate the globally installed SINAPSE supreme orchestrator.'}`,
+    '---', '',
+    '<!-- SINAPSE-MANAGED:global-skill -->', '',
+    generic ? '# SINAPSE Global Agent Activator' : '# SINAPSE Global Orchestrator', '',
+    generic
+      ? '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.', '',
+  ].join('\n');
+}
+
+function writeFileAtomically(filePath, content) {
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  let handle;
+  try {
+    handle = fs.openSync(temporaryPath, 'wx', 0o600);
+    fs.writeFileSync(handle, content, 'utf8');
+    fs.fsyncSync(handle);
+    fs.closeSync(handle);
+    handle = undefined;
+    fs.renameSync(temporaryPath, filePath);
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+    try { fs.unlinkSync(temporaryPath); } catch { /* already published or cleanup is best-effort */ }
+  }
+}
+
+function writeGlobalSkillIfManaged(skillPath, content) {
+  fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+
+  let handle;
+  try {
+    const noFollow = fs.constants.O_NOFOLLOW || 0;
+    handle = fs.openSync(skillPath, fs.constants.O_RDONLY | noFollow);
+  } catch (error) {
+    if (error.code === 'ELOOP') return false;
+    if (error.code !== 'ENOENT') throw error;
+    try {
+      handle = fs.openSync(skillPath, 'wx');
+    } catch (createError) {
+      if (createError.code === 'EEXIST') return writeGlobalSkillIfManaged(skillPath, content);
+      throw createError;
+    }
+    try {
+      fs.writeFileSync(handle, content, 'utf8');
+      return true;
+    } finally {
+      fs.closeSync(handle);
+    }
+  }
+
+  try {
+    if (!fs.fstatSync(handle).isFile()) return false;
+    const existing = fs.readFileSync(handle, 'utf8');
+    if (!existing.includes('SINAPSE-MANAGED:global-skill')) return false;
+    fs.closeSync(handle);
+    handle = undefined;
+    writeFileAtomically(skillPath, content);
+    return true;
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+}
+
+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 }) {
+  let commandFiles = fs.existsSync(commandsDir)
+    ? fs.readdirSync(commandsDir).filter((file) => file.endsWith('.md')).sort()
+    : [];
+  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) {
+      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 = markGlobalAgent(fs.readFileSync(path.join(commandsDir, file), 'utf8'), file);
+      const id = file.replace(/\.md$/, '');
+      const metadata = parseAgentMarkdown(markdown, id);
+      const tomlName = `${id}.toml`;
+      fs.writeFileSync(path.join(targetDir, tomlName), renderCodexToml(metadata.name, metadata.description, markdown), 'utf8');
+      const staleMarkdown = path.join(targetDir, file);
+      if (fs.existsSync(staleMarkdown)) fs.unlinkSync(staleMarkdown);
+      written.codex.push(tomlName);
+    }
+    const skillsRoot = path.join(home, '.agents', 'skills');
+    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))) {
+        written.skills.push(skillId);
+      }
+    }
+  }
+  return written;
+}
+
+function getGlobalCommandStagingDir({ llmChoice, sinapseHome, claudeCommandsDir }) {
+  void llmChoice;
+  void claudeCommandsDir;
+  return path.join(sinapseHome, '.generated', 'agents');
+}
+
+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/bin/utils/validate-publish.js

@@ -15,31 +15,64 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execFileSync, execSync } = require('child_process');
 
 const PROJECT_ROOT = path.join(__dirname, '..', '..');
 const MIN_FILE_COUNT = 50;
 
+function isNewerVersion(candidate, current) {
+  const left = String(candidate).replace(/^v/, '').split(/[.-]/).slice(0, 3).map(Number);
+  const right = String(current).replace(/^v/, '').split(/[.-]/).slice(0, 3).map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const delta = (left[i] || 0) - (right[i] || 0);
+    if (delta !== 0) return delta > 0;
+  }
+  return false;
+}
+
 let passed = true;
 let fileCount = 0;
 
 console.log('--- Publish Safety Gate (INS-4.10) ---\n');
 
+// Check 0: npm never accepts re-publishing an existing version. Surface the
+// collision before the expensive package scan so release readiness stays
+// honest and operators know that a semantic version bump is still required.
+try {
+  const localVersion = require(path.join(PROJECT_ROOT, 'package.json')).version;
+  const npmCli = process.env.npm_execpath;
+  const npmExecutable = npmCli ? process.execPath : (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+  const npmArgs = npmCli
+    ? [npmCli, 'view', 'sinapse-ai', 'version']
+    : ['view', 'sinapse-ai', 'version'];
+  const publishedVersion = execFileSync(npmExecutable, npmArgs, {
+    encoding: 'utf8',
+    cwd: PROJECT_ROOT,
+    timeout: 15000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  if (!isNewerVersion(localVersion, publishedVersion)) {
+    console.error(`FAIL: local version ${localVersion} is not newer than npm latest ${publishedVersion}.`);
+    console.error('  A semantic version bump is required before publishing.');
+    passed = false;
+  } else {
+    console.log(`PASS: local version ${localVersion} is newer than npm latest ${publishedVersion}`);
+  }
+} catch (err) {
+  console.error(`FAIL: could not verify the npm version boundary: ${err.message}`);
+  passed = false;
+}
+
 // Check 1: File count threshold via npm pack --dry-run
 try {
-  const packOutput = execSync('npm pack --dry-run 2>&1', {
+  const packOutput = execSync('npm pack --dry-run --json', {
     encoding: 'utf8',
     cwd: PROJECT_ROOT,
     timeout: 30000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 32 * 1024 * 1024,
   });
-  // npm pack --dry-run outputs lines starting with "npm notice" for each file
-  const fileLines = packOutput.split('\n').filter(line =>
-    line.includes('npm notice') && !line.includes('Tarball') && !line.includes('name:') &&
-    !line.includes('version:') && !line.includes('filename:') && !line.includes('package size:') &&
-    !line.includes('unpacked size:') && !line.includes('shasum:') && !line.includes('integrity:') &&
-    !line.includes('total files:'),
-  );
-  fileCount = fileLines.length;
+  fileCount = ((JSON.parse(packOutput)[0] || {}).files || []).length;
 
   if (fileCount < MIN_FILE_COUNT) {
     console.error(`FAIL: Package has only ${fileCount} files, expected >= ${MIN_FILE_COUNT}.`);

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
-