sinapse-ai 1.24.0 → 1.25.0

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.200 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 — totalizando **1.201 tasks executáveis** prontas para uso, distribuídas pelos 17 squads.
 
 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.
 
@@ -41,10 +41,13 @@ O diferencial não é apenas a quantidade de agentes. É **governança real**: 2
 
 ## Quick Start
 
+> Use `@latest` nos comandos publicos para evitar que o cache do `npx` execute
+> uma versao anterior durante instalacoes e atualizacoes.
+
 ### 1. Instale
 
 ```bash
-npx sinapse-ai install
+npx sinapse-ai@latest install
 ```
 
 O wizard detecta seu ambiente, escolhe a IDE (Claude Code ou Codex) e instala os 17 squads automaticamente. Re-rodar o comando faz upsert idempotente — preserva suas customizações e só atualiza o que mudou.
@@ -52,8 +55,8 @@ O wizard detecta seu ambiente, escolhe a IDE (Claude Code ou Codex) e instala os
 ### 2. Verifique
 
 ```bash
-npx sinapse-ai status   # Lista de squads + agentes instalados
-npx sinapse-ai doctor   # 16 health checks contra o ambiente
+npx sinapse-ai@latest status   # Lista de squads + agentes instalados
+npx sinapse-ai@latest doctor   # 16 health checks contra o ambiente
 ```
 
 Se algo estiver fora do lugar, `doctor --fix` corrige automaticamente.
@@ -120,7 +123,7 @@ Cada release passa por uma matriz de instalação de 27 combinações (3 OSes ×
 ### "Como atualizar sem perder minhas customizações?"
 
 ```bash
-npx sinapse-ai update
+npx sinapse-ai@latest update
 ```
 
 O update é **idempotente por design**. L1 (framework core) e L2 (templates) são atualizados. L3 (configuração) e L4 (suas stories, packages, customizações) **nunca são tocados**. Você pode rodar `update` quantas vezes quiser, inclusive após customizar rules localmente. Nada se perde.
@@ -282,7 +285,7 @@ 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.200 tasks**
+**Total: 17 squads, 172 agentes especializados, 1.201 tasks**
 
 Cada squad é ativado via seu orquestrador:
 
@@ -303,8 +306,8 @@ O SINAPSE suporta duas IDEs com integrações profundas:
 
 | IDE | Ativação | Destaques |
 |-----|----------|-----------|
-| **Claude Code** | `@agent-name` | Hooks, rules contextuais, deny/allow, Chrome Brain |
-| **Codex CLI** | `/skills` ou `$skill-name` | Skills nativas, multi-model, `codex exec` para CI/CD |
+| **Claude Code** | `@agent-name` ou `/skill-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.
 
@@ -312,7 +315,7 @@ Ambas as IDEs têm acesso a todos os 17 squads, 172 agentes, workflows e knowled
 
 | Funcionalidade | Claude Code | Codex CLI |
 |---------------|:-----------:|:---------:|
-| Ativação de agentes (@agent) | Completo | Completo |
+| 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 |
@@ -401,6 +404,18 @@ Pre-commit e pre-push hooks validam automaticamente antes de cada operação.
 
 ## CLI Reference
 
+Comandos deterministas para o pacote publico:
+
+```bash
+# Projeto novo ou existente
+npx sinapse-ai@latest install
+npx sinapse-ai@latest update
+
+# Instalacao global existente
+npm install -g sinapse-ai@latest
+sinapse-ai update
+```
+
 A superfície pública é proposital — quatro comandos canônicos de lifecycle, dois diagnósticos, um sub-comando avançado.
 
 ```bash
@@ -421,7 +436,7 @@ npx sinapse-ai doctor --dry-run  # Mostra o que `--fix` faria sem aplicar
 npx sinapse-ai chrome-brain install   # Instala browser automation
 ```
 
-Todos os comandos são seguros para re-rodar. Para listar agentes ativos depois de instalar, abra o Claude Code ou o Codex CLI e digite `@` para autocompletar.
+Todos os comandos são seguros para re-rodar. No Claude Code, digite `@` para selecionar um subagente ou use `/snps`. No Codex, use `$snps` para o orquestrador supremo e `$sinapse-agent <id>` para qualquer agente do catálogo.
 
 ### Orquestração (avançado)
 

package/bin/commands/install.js

@@ -36,7 +36,11 @@ const {
   warnNonInteractive,
 } = require('../lib/detection');
 const { promptLlmChoice } = require('../lib/prompts');
-const { recordInstalledAgents } = require('./uninstall');
+const {
+  recordInstalledAgents,
+  reconcileInstalledAgents,
+  removeManagedGlobalSkills,
+} = require('./uninstall');
 const { verifyInstall } = require('./status');
 // generateCommandMd is re-exported below for backward-compat (update.js imports it
 // from ./install). regenerateAgentCommands is the shared Phase 2 helper.
@@ -44,6 +48,7 @@ const {
   generateCommandMd,
   regenerateAgentCommands,
 } = require('../lib/command-generator');
+const { deliverGlobalProviderAdapters, getGlobalCommandStagingDir } = require('../lib/global-provider-adapters');
 // Follow-up #13 — wire the transactional backup/rollback engine into the
 // installer so an in-place UPGRADE (upsert) that fails mid-flight is restored
 // to its previous state instead of leaving ~/.sinapse half-updated.
@@ -300,19 +305,10 @@ async function cmdInstallGlobal(opts = {}) {
   // greeting on @sinapse/@snps/-orqx). Re-copy the generated command files LAST so the
   // rich, frontmatter'd stubs are always the final word. Idempotent.
   try {
-    const reTargets = [];
-    if (llmChoice === 'claude-code' || llmChoice === 'both') reTargets.push(path.join(HOME, '.claude', 'agents'));
-    if (llmChoice === 'codex' || llmChoice === 'both') reTargets.push(path.join(HOME, '.codex', 'agents'));
-    if (reTargets.length && fs.existsSync(CLAUDE_COMMANDS_DIR)) {
-      const cmdFiles = fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'));
-      for (const dir of reTargets) {
-        fs.mkdirSync(dir, { recursive: true });
-        for (const f of cmdFiles) {
-          fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(dir, f));
-        }
-      }
-      logger.always(`  ${GREEN}OK${NC} Global agents reconciled (${cmdFiles.length} files — rich stubs authoritative)`);
-    }
+    const commandsDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
+    const reconciled = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir });
+    const total = reconciled.claude.length + reconciled.codex.length + reconciled.skills.length;
+    if (total) logger.always(`  ${GREEN}OK${NC} Global provider adapters reconciled (${total} artifacts)`);
   } catch (e) {
     logger.always(`  ${YELLOW}WARN${NC} Global agent reconciliation: ${e.message}`);
   }
@@ -324,9 +320,14 @@ async function cmdInstallGlobal(opts = {}) {
   // printed above: if any check failed (✗), show a warning banner instead of an
   // unconditional success banner. The exit code is intentionally left unchanged —
   // this only changes the message, not the process result.
+  const verificationCommandsDir = getGlobalCommandStagingDir({
+    llmChoice,
+    sinapseHome: SINAPSE_HOME,
+    claudeCommandsDir: CLAUDE_COMMANDS_DIR,
+  });
   const installVerified =
     fs.existsSync(SINAPSE_HOME) &&
-    fs.existsSync(CLAUDE_COMMANDS_DIR) &&
+    fs.existsSync(verificationCommandsDir) &&
     fs.existsSync(path.join(BIN_DIR, 'sinapse')) &&
     fs.existsSync(path.join(SINAPSE_HOME, '.claude', 'rules', 'squad-awareness.md'));
 
@@ -351,8 +352,13 @@ async function cmdInstallGlobal(opts = {}) {
   logger.always(`  ${startCmd}`);
   logger.always('');
   logger.always(`  ${BOLD}Try an agent:${NC}`);
-  logger.always(`    ${CYAN}/SINAPSE:agents:sinapse-orqx${NC}`);
-  logger.always(`    ${CYAN}/SINAPSE:agents:brand-orqx${NC}`);
+  if (llmChoice === 'codex') {
+    logger.always(`    ${CYAN}$snps${NC}`);
+    logger.always(`    ${CYAN}$sinapse-agent brand-orqx${NC}`);
+  } else {
+    logger.always(`    ${CYAN}@sinapse-orqx${NC}`);
+    logger.always(`    ${CYAN}@brand-orqx${NC}`);
+  }
   logger.always('');
 }
 
@@ -396,7 +402,10 @@ function buildTransactionPaths(llmChoice) {
     CLAUDE_COMMANDS_DIR,   // Phase 2 — generated /SINAPSE:agents:* command files
   ];
   if (llmChoice === 'claude-code' || llmChoice === 'both') dirs.push(path.join(HOME, '.claude', 'agents'));
-  if (llmChoice === 'codex' || llmChoice === 'both') dirs.push(path.join(HOME, '.codex', 'agents'));
+  if (llmChoice === 'codex' || llmChoice === 'both') {
+    dirs.push(path.join(HOME, '.codex', 'agents'));
+    dirs.push(path.join(HOME, '.agents', 'skills'));
+  }
   dirs.push(BIN_DIR);      // Phase 4 — launcher(s)
 
   const files = [path.join(HOME, '.claude', 'settings.json')]; // language save
@@ -520,43 +529,49 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
     logger.always(`  ${GREEN}OK${NC} sinapse (master, ${masterAgents} agents)`);
   }
 
+  const coreDevelopmentSrc = path.join(ROOT, '.sinapse-ai', 'development');
+  const coreDevelopmentDest = path.join(SINAPSE_HOME, 'core');
+  if (fs.existsSync(coreDevelopmentSrc)) {
+    if (isUpsert) {
+      const delta = syncDirSync(coreDevelopmentSrc, coreDevelopmentDest);
+      totalDelta.added += delta.added;
+      totalDelta.updated += delta.updated;
+      totalDelta.unchanged += delta.unchanged;
+      totalDelta.removed += delta.removed;
+    } else {
+      rmDirSync(coreDevelopmentDest);
+      copyDirSync(coreDevelopmentSrc, coreDevelopmentDest);
+    }
+    const coreAgents = getAgentFiles(coreDevelopmentDest).length;
+    totalAgents += coreAgents;
+    logger.always(`  ${GREEN}OK${NC} core development (${coreAgents} agents)`);
+  }
+
   // Phase 2: Generate agent commands (shared with `update` via command-generator).
   logger.always(`\n${CYAN}Phase 2:${NC} Generating agent commands`);
+  const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
   const { writtenAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
-    commandsDir: CLAUDE_COMMANDS_DIR,
+    commandsDir: commandStagingDir,
     squads,
     sinapseMasterDest,
+    coreDevelopmentDest,
   });
   logger.always(`  ${GREEN}OK${NC} ${writtenAgents.size} total command files`);
 
   // Phase 2b: Install global agents based on LLM choice
-  const installedAgentFilenames = new Set();
+  const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
+  const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
   const installedIdes = [];
-  if (llmChoice === 'claude-code' || llmChoice === 'both') {
-    const globalAgentsDir = path.join(HOME, '.claude', 'agents');
-    fs.mkdirSync(globalAgentsDir, { recursive: true });
-    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));
-      installedAgentFilenames.add(f);
-    }
-    installedIdes.push('claude-code');
-    logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${writtenAgents.size})`);
-  }
-
-  if (llmChoice === 'codex' || llmChoice === 'both') {
-    const codexAgentsDir = path.join(HOME, '.codex', 'agents');
-    fs.mkdirSync(codexAgentsDir, { recursive: true });
-    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));
-      installedAgentFilenames.add(f);
-    }
-    installedIdes.push('codex');
-    logger.always(`  ${GREEN}OK${NC} Codex global agents (${writtenAgents.size})`);
-  }
+  if (globalAdapters.claude.length) installedIdes.push('claude-code');
+  if (globalAdapters.codex.length) installedIdes.push('codex');
+  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)`);
 
   // Audit 1 P0 (UN-1) — record manifest so uninstall can remove every file
   // we wrote (not just `*-orqx.md`). Idempotent: re-install overwrites.
+  reconcileInstalledAgents(HOME, installedAgentFilenames);
+  if (llmChoice === 'claude-code') removeManagedGlobalSkills(HOME);
   recordInstalledAgents(installedAgentFilenames, installedIdes);
 
   // Phase 3: Generate squad-awareness.md

package/bin/commands/uninstall.js

@@ -82,12 +82,12 @@ function readInstalledAgentsManifest() {
   }
 }
 
-function removeInstalledAgentsFrom(dir) {
+function removeInstalledAgentsFrom(dir, manifestOverride = null) {
   if (!fs.existsSync(dir)) return { removed: 0, existed: false };
   let removed = 0;
   let candidates;
 
-  const manifest = readInstalledAgentsManifest();
+  const manifest = manifestOverride || readInstalledAgentsManifest();
   if (manifest && Array.isArray(manifest.filenames)) {
     // Manifest path — surgical removal of exactly what install wrote.
     candidates = manifest.filenames;
@@ -97,6 +97,9 @@ function removeInstalledAgentsFrom(dir) {
     // `-orqx.md`, OR start with `name: sinapse-` in their frontmatter.
     try {
       candidates = fs.readdirSync(dir).filter((f) => {
+        if (f.endsWith('.toml')) {
+          try { return /SINAPSE/i.test(fs.readFileSync(path.join(dir, f), 'utf8').slice(0, 4000)); } catch { return false; }
+        }
         if (!f.endsWith('.md')) return false;
         if (/-orqx\.md$/.test(f)) return true;
         try {
@@ -125,6 +128,46 @@ function removeOrqxAgentsFrom(dir) {
   return removeInstalledAgentsFrom(dir);
 }
 
+const MANAGED_GLOBAL_SKILL_IDS = ['snps', 'sinapse', 'snps-orqx', 'sinapse-agent'];
+const MANAGED_GLOBAL_SKILL_MARKER = 'SINAPSE-MANAGED:global-skill';
+
+function removeManagedGlobalSkills(home = HOME) {
+  let removed = 0;
+  for (const skillId of MANAGED_GLOBAL_SKILL_IDS) {
+    const skillDir = path.join(home, '.agents', 'skills', skillId);
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) continue;
+    try {
+      const content = fs.readFileSync(skillPath, 'utf8');
+      if (!content.includes(MANAGED_GLOBAL_SKILL_MARKER)) continue;
+      fs.unlinkSync(skillPath);
+      if (fs.readdirSync(skillDir).length === 0) fs.rmdirSync(skillDir);
+      removed++;
+    } catch { /* best-effort */ }
+  }
+  return { removed };
+}
+
+function reconcileInstalledAgents(home, desiredFilenames) {
+  const manifest = readInstalledAgentsManifest();
+  if (!manifest) return { removed: 0 };
+  const desired = new Set(desiredFilenames);
+  let removed = 0;
+  for (const filename of manifest.filenames) {
+    if (desired.has(filename)) continue;
+    const providerDir = filename.endsWith('.toml')
+      ? path.join(home, '.codex', 'agents')
+      : path.join(home, '.claude', 'agents');
+    const filepath = path.join(providerDir, filename);
+    if (!fs.existsSync(filepath)) continue;
+    try {
+      fs.unlinkSync(filepath);
+      removed++;
+    } catch { /* best-effort */ }
+  }
+  return { removed };
+}
+
 // Story 10.40 — Strip SINAPSE-owned keys from ~/.claude/settings.json without
 // touching anything else the user put there. Safe if the file is missing or
 // already clean.
@@ -176,6 +219,7 @@ async function cmdUninstall(opts = {}) {
   }
 
   logger.always(`${BOLD}Uninstalling Sinapse...${NC}\n`);
+  const installedAgentsManifest = readInstalledAgentsManifest();
 
   // Paths that are fully SINAPSE-owned (directory or launcher file)
   const ownedItems = [
@@ -210,7 +254,7 @@ async function cmdUninstall(opts = {}) {
   const claudeAgentsDir = path.join(HOME, '.claude', 'agents');
   const codexAgentsDir = path.join(HOME, '.codex', 'agents');
 
-  const claudeRemoved = removeInstalledAgentsFrom(claudeAgentsDir);
+  const claudeRemoved = removeInstalledAgentsFrom(claudeAgentsDir, installedAgentsManifest);
   if (!claudeRemoved.existed) {
     logger.always(`  ${YELLOW}-${NC} ~/.claude/agents/ SINAPSE files (dir not found)`);
   } else if (claudeRemoved.removed === 0) {
@@ -219,7 +263,7 @@ async function cmdUninstall(opts = {}) {
     logger.always(`  ${GREEN}✓${NC} Removed ~/.claude/agents/ SINAPSE files (${claudeRemoved.removed} files)`);
   }
 
-  const codexRemoved = removeInstalledAgentsFrom(codexAgentsDir);
+  const codexRemoved = removeInstalledAgentsFrom(codexAgentsDir, installedAgentsManifest);
   if (!codexRemoved.existed) {
     logger.always(`  ${YELLOW}-${NC} ~/.codex/agents/ SINAPSE files (dir not found)`);
   } else if (codexRemoved.removed === 0) {
@@ -229,6 +273,13 @@ async function cmdUninstall(opts = {}) {
   }
 
   // Story 10.40 — clean SINAPSE-owned keys from ~/.claude/settings.json
+  const skillsRemoved = removeManagedGlobalSkills(HOME);
+  if (skillsRemoved.removed > 0) {
+    logger.always(`  ${GREEN}OK${NC} Removed global SINAPSE skills (${skillsRemoved.removed})`);
+  } else {
+    logger.always(`  ${YELLOW}-${NC} Global SINAPSE skills (none present)`);
+  }
+
   const settingsPath = path.join(HOME, '.claude', 'settings.json');
   const settingsClean = cleanClaudeSettingsJson(settingsPath);
   if (settingsClean.touched) {
@@ -259,6 +310,8 @@ module.exports = {
   readInstalledAgentsManifest,
   removeInstalledAgentsFrom,
   removeOrqxAgentsFrom,
+  removeManagedGlobalSkills,
+  reconcileInstalledAgents,
   cleanClaudeSettingsJson,
   removeGitHooksConfig,
   INSTALLED_AGENTS_MANIFEST,

package/bin/commands/update.js

@@ -29,7 +29,13 @@ 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 { execSync } = require('child_process');
 
 // Query the latest version published to npm. Returns null when npm is unreachable.
@@ -146,39 +152,44 @@ 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})`);
-  }
-
-  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 globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
+  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)`);
+
+  const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
+  reconcileInstalledAgents(HOME, installedAgentFilenames);
+  if (llmChoice === 'claude-code') removeManagedGlobalSkills(HOME);
+  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`);

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,136 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+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 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
+      ? 'Use the requested ID from `~/.codex/agents/<id>.toml`; 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 deliverGlobalProviderAdapters({ llmChoice, home, commandsDir }) {
+  const commandFiles = fs.existsSync(commandsDir)
+    ? fs.readdirSync(commandsDir).filter((file) => file.endsWith('.md')).sort()
+    : [];
+  const written = { claude: [], codex: [], skills: [] };
+
+  if (llmChoice === 'claude-code' || llmChoice === 'both') {
+    const targetDir = path.join(home, '.claude', 'agents');
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const file of commandFiles) {
+      fs.copyFileSync(path.join(commandsDir, file), path.join(targetDir, file));
+      written.claude.push(file);
+    }
+  }
+  if (llmChoice === 'codex' || llmChoice === 'both') {
+    const targetDir = path.join(home, '.codex', 'agents');
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const file of commandFiles) {
+      const markdown = fs.readFileSync(path.join(commandsDir, file), 'utf8');
+      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-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 }) {
+  return llmChoice === 'codex'
+    ? path.join(sinapseHome, '.generated', 'agents')
+    : claudeCommandsDir;
+}
+
+module.exports = { parseAgentMarkdown, renderCodexToml, renderGlobalSkill, writeGlobalSkillIfManaged, deliverGlobalProviderAdapters, getGlobalCommandStagingDir };