sinapse-ai 1.16.0 → 1.19.0

package/packages/installer/src/wizard/i18n.js

@@ -51,6 +51,45 @@ const TRANSLATIONS = {
     installingDeps: 'Installing dependencies...',
     configuringEnv: 'Configuring environment...',
     validating: 'Validating installation...',
+    installingGlobalAgents: 'Installing global agent definitions...',
+    skippingGlobalAgentsCodex: 'Skipping global Claude agents (Codex-only install)',
+    ideSyncDriftWarning: 'IDE sync out of date — run: sinapse doctor --fix',
+    entityRegistrySkippedNoDeps:
+      'Core dependencies (.sinapse-ai) not found — skipping entity registry setup',
+    generatingBoundaryRules: 'Generating boundary rules...',
+    copyingSkills: 'Copying skills...',
+    copyingExtraCommands: 'Copying extra commands...',
+    runningIdeSync: 'Running IDE sync...',
+    runningCodexSync: 'Running Codex local-first sync...',
+    bootstrappingEntityRegistry: 'Setting up entity registry...',
+    installingLlmRouting: 'Installing LLM routing commands...',
+    dependencyInstallation: 'Dependency installation...',
+
+    // Validation report (AF-20260629 — i18n migration)
+    reportTitle: 'Installation Validation Report',
+    reportIdeConfig: 'IDE Configuration',
+    reportEnvConfig: 'Environment Configuration',
+    reportCoreConfig: 'Core Configuration',
+    reportMcpConfig: 'MCP Configuration',
+    reportMcpInstallation: 'MCP Installation',
+    reportMcpHealthy: 'healthy',
+    reportMcpWarnings: 'warnings',
+    reportMcpFailed: 'failed',
+    reportMcpsNotInstalled: 'MCPs not installed (skipped)',
+    reportDependencies: 'Dependencies',
+    reportChecksPassed: '{passed}/{total} checks passed',
+    reportWarnings: 'Warnings ({count}):',
+    reportErrors: 'Errors ({count}):',
+    reportSolution: 'Solution: {solution}',
+    reportNextSteps: 'Next Steps:',
+    reportNextStep1: '1. Review the errors above',
+    reportNextStep2: '2. Fix the critical issues',
+    reportNextStep3: '3. Re-run the installation: npx sinapse-ai@latest install',
+    reportOverallStatus: 'Overall Status',
+    reportAllPassed: 'All checks passed!',
+    reportPartialSuccess: 'PARTIAL SUCCESS ({count} issue(s) to review)',
+    reportFailedStatus: 'FAILED ({count} error(s))',
+    reportUnknownStatus: 'UNKNOWN',
 
     // Status
     success: 'Success',
@@ -134,6 +173,45 @@ const TRANSLATIONS = {
     installingDeps: 'Instalando dependências...',
     configuringEnv: 'Configurando ambiente...',
     validating: 'Validando instalação...',
+    installingGlobalAgents: 'Instalando definições globais de agentes...',
+    skippingGlobalAgentsCodex: 'Pulando agentes globais do Claude (instalação somente Codex)',
+    ideSyncDriftWarning: 'Sincronização de IDE desatualizada — rode: sinapse doctor --fix',
+    entityRegistrySkippedNoDeps:
+      'Dependências do núcleo (.sinapse-ai) não encontradas — pulando o registro de entidades',
+    generatingBoundaryRules: 'Gerando regras de proteção...',
+    copyingSkills: 'Copiando skills...',
+    copyingExtraCommands: 'Copiando comandos extras...',
+    runningIdeSync: 'Sincronizando IDEs...',
+    runningCodexSync: 'Sincronizando Codex (local-first)...',
+    bootstrappingEntityRegistry: 'Preparando o registro de entidades...',
+    installingLlmRouting: 'Instalando comandos de roteamento de LLM...',
+    dependencyInstallation: 'Instalação de dependências...',
+
+    // Validation report (AF-20260629 — i18n migration)
+    reportTitle: 'Relatório de Validação da Instalação',
+    reportIdeConfig: 'Configuração de IDE',
+    reportEnvConfig: 'Configuração de Ambiente',
+    reportCoreConfig: 'Configuração do Núcleo',
+    reportMcpConfig: 'Configuração de MCP',
+    reportMcpInstallation: 'Instalação de MCP',
+    reportMcpHealthy: 'saudáveis',
+    reportMcpWarnings: 'avisos',
+    reportMcpFailed: 'falharam',
+    reportMcpsNotInstalled: 'MCPs não instalados (pulado)',
+    reportDependencies: 'Dependências',
+    reportChecksPassed: '{passed}/{total} verificações OK',
+    reportWarnings: 'Avisos ({count}):',
+    reportErrors: 'Erros ({count}):',
+    reportSolution: 'Solução: {solution}',
+    reportNextSteps: 'Próximos Passos:',
+    reportNextStep1: '1. Revise os erros acima',
+    reportNextStep2: '2. Corrija os problemas críticos',
+    reportNextStep3: '3. Rode a instalação novamente: npx sinapse-ai@latest install',
+    reportOverallStatus: 'Status Geral',
+    reportAllPassed: 'Todas as verificações passaram!',
+    reportPartialSuccess: 'SUCESSO PARCIAL ({count} ponto(s) a revisar)',
+    reportFailedStatus: 'FALHOU ({count} erro(s))',
+    reportUnknownStatus: 'DESCONHECIDO',
 
     // Status
     success: 'Sucesso',

package/packages/installer/src/wizard/ide-config-generator.js

@@ -11,7 +11,10 @@ const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
 const ora = require('ora');
-const { spawnSync } = require('child_process');
+// cross-spawn resolves gemini's Windows .cmd/.ps1 shim WITHOUT a shell and
+// escapes argv properly (CVE-2024-27980), so a path with spaces in extensionDir
+// stays intact — shell:true would split it and break the link silently.
+const crossSpawn = require('cross-spawn');
 const { getIDEConfig } = require('../config/ide-configs');
 const { validateProjectName } = require('./validators');
 const { getMergeStrategy, hasMergeStrategy } = require('../merger/index.js');
@@ -539,6 +542,7 @@ async function copyClaudeHooksFolder(projectRoot) {
     'enforce-architecture-first.cjs',
     'enforce-delegation.cjs',
     'enforce-story-gate.cjs',
+    'doc-first-gate.cjs',
     'enforce-framework-boundary.cjs',
     'secret-scanning.cjs',
     'write-path-validation.cjs',
@@ -603,6 +607,11 @@ const HOOK_EVENT_MAP = {
     matcher: 'Write|Edit',
     timeout: 5,
   },
+  'doc-first-gate.cjs': {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit',
+    timeout: 5,
+  },
   // Boundary L1-L4 — protects untouchable framework core when
   // boundary.frameworkProtection=true (read dynamically from core-config.yaml).
   'enforce-framework-boundary.cjs': {
@@ -931,19 +940,17 @@ async function linkGeminiExtension(projectRoot) {
 
   // On Windows, `gemini` is a .cmd/.ps1 shim — spawnSync without a shell throws
   // EINVAL. Run through the shell on win32 so the shim resolves.
-  const versionCheck = spawnSync('gemini', ['--version'], {
+  const versionCheck = crossSpawn.sync('gemini', ['--version'], {
     encoding: 'utf8',
-    shell: process.platform === 'win32',
   });
   if (versionCheck.status !== 0) {
     return { status: 'skipped', reason: 'gemini-cli-not-available' };
   }
 
-  let linkResult = spawnSync('gemini', ['extensions', 'link', extensionDir, '--consent'], {
+  let linkResult = crossSpawn.sync('gemini', ['extensions', 'link', extensionDir, '--consent'], {
     cwd: projectRoot,
     encoding: 'utf8',
     timeout: 30000,
-    shell: process.platform === 'win32',
   });
 
   if (linkResult.status === 0) {
@@ -954,22 +961,20 @@ async function linkGeminiExtension(projectRoot) {
 
   // When already installed, perform idempotent relink.
   if (output.includes('already installed')) {
-    const uninstall = spawnSync('gemini', ['extensions', 'uninstall', 'sinapse'], {
+    const uninstall = crossSpawn.sync('gemini', ['extensions', 'uninstall', 'sinapse'], {
       cwd: projectRoot,
       encoding: 'utf8',
       timeout: 30000,
-      shell: process.platform === 'win32',
     });
 
     if (uninstall.status !== 0) {
       return { status: 'skipped', reason: 'uninstall-failed' };
     }
 
-    linkResult = spawnSync('gemini', ['extensions', 'link', extensionDir, '--consent'], {
+    linkResult = crossSpawn.sync('gemini', ['extensions', 'link', extensionDir, '--consent'], {
       cwd: projectRoot,
       encoding: 'utf8',
       timeout: 30000,
-      shell: process.platform === 'win32',
     });
 
     if (linkResult.status === 0) {

package/packages/installer/src/wizard/index.js

@@ -503,7 +503,7 @@ async function runWizard(options = {}) {
     }
 
     // Story 1.4: Install SINAPSE core framework (agents, tasks, workflows, templates)
-    console.log('\n📦 Installing SINAPSE core framework...');
+    console.log('\n📦 ' + t('installingCore'));
     let sinapseCoreResult = null;
     try {
       sinapseCoreResult = await installSinapseCore({
@@ -530,7 +530,7 @@ async function runWizard(options = {}) {
     // Install global orqx agent definitions to ~/.claude/agents/ (only for Claude Code)
     const selectedLLM = answers.selectedLLM || 'claude-code';
     if (selectedLLM === 'claude-code' || selectedLLM === 'both') {
-      console.log('\n🤖 Installing global agent definitions...');
+      console.log('\n🤖 ' + t('installingGlobalAgents'));
       try {
         const globalAgentsResult = await installGlobalAgents();
         if (globalAgentsResult.success) {
@@ -546,7 +546,7 @@ async function runWizard(options = {}) {
         answers.globalAgentsInstalled = 0;
       }
     } else {
-      console.log('\n🤖 Skipping global Claude agents (Codex-only install)');
+      console.log('\n🤖 ' + t('skippingGlobalAgentsCodex'));
       answers.globalAgentsInstalled = 0;
     }
 
@@ -681,7 +681,7 @@ async function runWizard(options = {}) {
     }
 
     // Story INS-4.3: Wire settings.json boundary generator after .sinapse-ai/ copy
-    console.log('\n🔒 Generating boundary rules...');
+    console.log('\n🔒 ' + t('generatingBoundaryRules'));
     try {
       const settingsGenerator = require('../../../../.sinapse-ai/infrastructure/scripts/generate-settings-json');
       settingsGenerator.generate(process.cwd());
@@ -697,7 +697,7 @@ async function runWizard(options = {}) {
     }
 
     // Story INS-4.3: Copy skills (Gap #11)
-    console.log('\n📚 Copying skills...');
+    console.log('\n📚 ' + t('copyingSkills'));
     try {
       const skillsResult = await copySkillFiles(process.cwd());
       if (skillsResult.skipped) {
@@ -713,7 +713,7 @@ async function runWizard(options = {}) {
     }
 
     // Story INS-4.3: Copy extra commands (Gap #12)
-    console.log('\n📋 Copying extra commands...');
+    console.log('\n📋 ' + t('copyingExtraCommands'));
     try {
       const commandsResult = await copyExtraCommandFiles(process.cwd());
       if (commandsResult.skipped) {
@@ -729,7 +729,7 @@ async function runWizard(options = {}) {
     }
 
     // Story INS-4.5: IDE Sync — transform agents/skills/commands for each configured IDE
-    console.log('\n🔄 Running IDE sync...');
+    console.log('\n🔄 ' + t('runningIdeSync'));
     const targetProjectRoot = process.cwd();
     const savedCwd = process.cwd();
     try {
@@ -750,7 +750,7 @@ async function runWizard(options = {}) {
         console.log = _origLog;
       }
       if (answers.ideSyncValidation === 'drift') {
-        console.warn('⚠️  IDE sync validation: drift detected — run \'sinapse doctor --fix\' post-install');
+        console.warn('⚠️  ' + t('ideSyncDriftWarning'));
       }
     } catch (syncError) {
       console.warn(`⚠️  IDE sync failed: ${syncError.message} — run 'sinapse doctor --fix' post-install`);
@@ -765,7 +765,7 @@ async function runWizard(options = {}) {
     // source (the static .codex payload — scripts/tasks/JSONs — was already
     // copied by installSinapseCore when Codex was selected). Codex installs only.
     if (selectedLLM === 'codex' || selectedLLM === 'both') {
-      console.log('\n🔄 Running Codex local-first sync...');
+      console.log('\n🔄 ' + t('runningCodexSync'));
       const savedCwdCodex = process.cwd();
       try {
         const { syncCodexLocalFirst } = require('../../../../.sinapse-ai/infrastructure/scripts/sync-codex-local-first');
@@ -786,14 +786,14 @@ async function runWizard(options = {}) {
     // Story INS-4.12: Fix module resolution + bootstrap timing
     // Bootstrap runs AFTER .sinapse-ai deps are installed (sinapse-ai-installer.js:324-345)
     // NODE_PATH ensures spawned scripts can resolve packages from .sinapse-ai/node_modules/
-    console.log('\n📇 Bootstrapping entity registry...');
+    console.log('\n📇 ' + t('bootstrappingEntityRegistry'));
     try {
       const registryScript = path.join(process.cwd(), '.sinapse-ai', 'development', 'scripts', 'populate-entity-registry.js');
       if (fse.existsSync(registryScript)) {
         // INS-4.12 AC3: Guard — skip bootstrap if .sinapse-ai deps are not installed
         const sinapseCoreNodeModules = path.join(process.cwd(), '.sinapse-ai', 'node_modules');
         if (!fse.existsSync(sinapseCoreNodeModules)) {
-          console.warn('⚠️  .sinapse-ai/node_modules/ not found — skipping entity registry bootstrap');
+          console.warn('⚠️  ' + t('entityRegistrySkippedNoDeps'));
           console.warn('   Run: cd .sinapse-ai && npm install --production');
           answers.entityRegistryStatus = 'skipped-no-deps';
         } else {
@@ -834,7 +834,7 @@ async function runWizard(options = {}) {
     }
 
     // Story 1.6: Environment Configuration
-    console.log('\n📝 Configuring environment...');
+    console.log('\n📝 ' + t('configuringEnv'));
 
     try {
       const envResult = await configureEnvironment({
@@ -901,7 +901,7 @@ async function runWizard(options = {}) {
 
     if (!packageJsonExists) {
       // Greenfield project - no package.json, skip dependency installation
-      console.log('\n📦 Dependency installation...');
+      console.log('\n📦 ' + t('dependencyInstallation'));
       console.log('   ℹ️  No package.json found (greenfield project)');
       console.log('   💡 Dependencies will be installed when you add a package.json');
       answers.depsInstalled = true; // Mark as success since there's nothing to install
@@ -909,7 +909,7 @@ async function runWizard(options = {}) {
       answers.packageManager = detectPackageManager();
     } else {
       // Brownfield project or existing project - has package.json
-      console.log('\n📦 Installing dependencies...');
+      console.log('\n📦 ' + t('installingDeps'));
 
       // Auto-detect package manager (no longer asked as question)
       const detectedPM = detectPackageManager();
@@ -1015,7 +1015,7 @@ async function runWizard(options = {}) {
     // }
 
     // Story 6.7: LLM Routing Installation
-    console.log('\nInstalling LLM Routing commands...');
+    console.log('\n' + t('installingLlmRouting'));
     try {
       // Check if already installed
       if (isLLMRoutingInstalled()) {
@@ -1052,7 +1052,7 @@ async function runWizard(options = {}) {
     answers.proInstalled = false;
 
     // Story 1.8: Installation Validation
-    console.log('\n🔍 Validating installation...\n');
+    console.log('\n🔍 ' + t('validating') + '\n');
 
     try {
       const validation = await validateInstallation(

package/packages/installer/src/wizard/validation/report-generator.js

@@ -6,6 +6,7 @@
  */
 
 const chalk = require('chalk');
+const { t, tf } = require('../i18n');
 
 /**
  * Generate formatted validation report
@@ -19,18 +20,18 @@ async function generateReport(validationResults) {
   // Header
   lines.push('');
   lines.push(chalk.bold.cyan('═══════════════════════════════════════════════'));
-  lines.push(chalk.bold.cyan('🔍 Installation Validation Report'));
+  lines.push(chalk.bold.cyan('🔍 ' + t('reportTitle')));
   lines.push(chalk.bold.cyan('═══════════════════════════════════════════════'));
   lines.push('');
 
   // File Structure Section
   if (validationResults.components.files) {
     const fileResults = validationResults.components.files;
-    lines.push(formatComponentSection('IDE Configuration', fileResults, 'IDE Config'));
-    lines.push(formatComponentSection('Environment Configuration', fileResults, 'Environment'));
-    lines.push(formatComponentSection('Core Configuration', fileResults, 'Core Config'));
+    lines.push(formatComponentSection(t('reportIdeConfig'), fileResults, 'IDE Config'));
+    lines.push(formatComponentSection(t('reportEnvConfig'), fileResults, 'Environment'));
+    lines.push(formatComponentSection(t('reportCoreConfig'), fileResults, 'Core Config'));
     if (fileResults.checks.some((c) => c.component === 'MCP Config')) {
-      lines.push(formatComponentSection('MCP Configuration', fileResults, 'MCP Config'));
+      lines.push(formatComponentSection(t('reportMcpConfig'), fileResults, 'MCP Config'));
     }
   }
 
@@ -56,11 +57,11 @@ async function generateReport(validationResults) {
   );
   if (importantWarnings.length > 0) {
     lines.push('');
-    lines.push(chalk.bold.yellow(`⚠️  Warnings (${importantWarnings.length}):`));
+    lines.push(chalk.bold.yellow('⚠️  ' + tf('reportWarnings', { count: importantWarnings.length })));
     importantWarnings.forEach((warning) => {
       lines.push(chalk.yellow(`  - ${warning.message}`));
       if (warning.solution) {
-        lines.push(chalk.dim(`    Solution: ${warning.solution}`));
+        lines.push(chalk.dim('    ' + tf('reportSolution', { solution: warning.solution })));
       }
     });
   }
@@ -68,11 +69,11 @@ async function generateReport(validationResults) {
   // Errors Section
   if (validationResults.errors.length > 0) {
     lines.push('');
-    lines.push(chalk.bold.red(`❌ Errors (${validationResults.errors.length}):`));
+    lines.push(chalk.bold.red('❌ ' + tf('reportErrors', { count: validationResults.errors.length })));
     validationResults.errors.forEach((error) => {
       lines.push(chalk.red(`  - ${error.message}`));
       if (error.solution) {
-        lines.push(chalk.dim(`    Solution: ${error.solution}`));
+        lines.push(chalk.dim('    ' + tf('reportSolution', { solution: error.solution })));
       }
     });
   }
@@ -83,10 +84,10 @@ async function generateReport(validationResults) {
     validationResults.overallStatus === 'failed'
   ) {
     lines.push('');
-    lines.push(chalk.bold.red('❌ Next Steps:'));
-    lines.push(chalk.red('  1. Review errors above'));
-    lines.push(chalk.red('  2. Fix critical issues'));
-    lines.push(chalk.red('  3. Re-run installation: npx @caioimori/sinapse@latest init'));
+    lines.push(chalk.bold.red('❌ ' + t('reportNextSteps')));
+    lines.push(chalk.red('  ' + t('reportNextStep1')));
+    lines.push(chalk.red('  ' + t('reportNextStep2')));
+    lines.push(chalk.red('  ' + t('reportNextStep3')));
   }
   // Success cases show completion message in showCompletion()
 
@@ -109,7 +110,7 @@ function formatComponentSection(title, componentResults, componentName) {
   const allSuccess = passed === total;
   const icon = allSuccess ? chalk.green('✅') : chalk.yellow('⚠️');
 
-  const lines = [`${icon} ${chalk.bold(title)}: ${passed}/${total} checks passed`];
+  const lines = [`${icon} ${chalk.bold(title)}: ${tf('reportChecksPassed', { passed, total })}`];
 
   // Only show individual checks if there are failures
   if (!allSuccess) {
@@ -134,7 +135,7 @@ function formatMCPSection(mcpResults) {
   const healthChecks = mcpResults.healthChecks;
 
   if (!healthChecks || healthChecks.length === 0) {
-    return chalk.dim('  MCPs not installed (skipped)\n');
+    return chalk.dim('  ' + t('reportMcpsNotInstalled') + '\n');
   }
 
   const totalMCPs = healthChecks.length;
@@ -150,7 +151,7 @@ function formatMCPSection(mcpResults) {
         : chalk.red('❌');
 
   const lines = [
-    `${icon} ${chalk.bold('MCP Installation')} (${healthyMCPs}/${totalMCPs} healthy${warningMCPs > 0 ? `, ${warningMCPs} warnings` : ''}${failedMCPs > 0 ? `, ${failedMCPs} failed` : ''})`,
+    `${icon} ${chalk.bold(t('reportMcpInstallation'))} (${healthyMCPs}/${totalMCPs} ${t('reportMcpHealthy')}${warningMCPs > 0 ? `, ${warningMCPs} ${t('reportMcpWarnings')}` : ''}${failedMCPs > 0 ? `, ${failedMCPs} ${t('reportMcpFailed')}` : ''})`,
   ];
 
   healthChecks.forEach((health) => {
@@ -198,7 +199,7 @@ function formatDependenciesSection(depsResults) {
   );
   const icon = allSuccess ? chalk.green('✅') : chalk.yellow('⚠️');
 
-  const lines = [`${icon} ${chalk.bold('Dependencies')}`];
+  const lines = [`${icon} ${chalk.bold(t('reportDependencies'))}`];
 
   depsResults.checks.forEach((check) => {
     let statusIcon, statusText;
@@ -237,20 +238,20 @@ function formatOverallStatus(validationResults) {
     case 'success':
     case 'warning':
       // Treat warnings as success - they're just informational
-      return chalk.bold.green('Overall Status: ✅ All checks passed!');
+      return chalk.bold.green(`${t('reportOverallStatus')}: ✅ ${t('reportAllPassed')}`);
 
     case 'partial':
       return chalk.bold.yellow(
-        `Overall Status: ⚠️  PARTIAL SUCCESS (${errorCount} issue${errorCount !== 1 ? 's' : ''} to review)`,
+        `${t('reportOverallStatus')}: ⚠️  ${tf('reportPartialSuccess', { count: errorCount })}`,
       );
 
     case 'failed':
       return chalk.bold.red(
-        `Overall Status: ❌ FAILED (${errorCount} error${errorCount !== 1 ? 's' : ''})`,
+        `${t('reportOverallStatus')}: ❌ ${tf('reportFailedStatus', { count: errorCount })}`,
       );
 
     default:
-      return chalk.bold.gray('Overall Status: ❓ UNKNOWN');
+      return chalk.bold.gray(`${t('reportOverallStatus')}: ❓ ${t('reportUnknownStatus')}`);
   }
 }
 

package/packages/installer/src/wizard/validation/troubleshooting-system.js

@@ -8,6 +8,12 @@
 const chalk = require('chalk');
 const inquirer = require('inquirer');
 
+// Canonical repo + docs locations. The legacy `docs.SinapseAI.com` domain never
+// existed; every help link points at real, shipped docs in the GitHub repo
+// (see package.json "bugs"/"repository").
+const REPO_URL = 'https://github.com/caioimori/sinapse-ai';
+const DOCS_BASE = `${REPO_URL}/blob/main/docs`;
+
 /**
  * Troubleshooting database
  * Maps error codes to detailed troubleshooting information
@@ -21,11 +27,11 @@ const TROUBLESHOOTING_DATABASE = {
       '.env accidentally deleted',
     ],
     solutions: [
-      'Re-run wizard: npx @caioimori/sinapse@latest init',
+      'Re-run wizard: npx sinapse-ai@latest install',
       'Manually create .env from template: cp .env.example .env',
       'Check file permissions in project directory',
     ],
-    docs: 'https://docs.SinapseAI.com/installation/environment',
+    docs: `${DOCS_BASE}/installation/troubleshooting.md`,
     priority: 'critical',
   },
 
@@ -37,11 +43,11 @@ const TROUBLESHOOTING_DATABASE = {
       'File creation failed',
     ],
     solutions: [
-      'Re-run wizard: npx @caioimori/sinapse@latest init',
+      'Re-run wizard: npx sinapse-ai@latest install',
       'Check .sinapse-ai directory exists',
       'Manually create from template',
     ],
-    docs: 'https://docs.SinapseAI.com/configuration/core-config',
+    docs: `${DOCS_BASE}/troubleshooting.md`,
     priority: 'high',
   },
 
@@ -60,7 +66,7 @@ const TROUBLESHOOTING_DATABASE = {
       'Check MCP service status',
       'Verify npx can access package: npx -y [package-name] --version',
     ],
-    docs: 'https://docs.SinapseAI.com/mcps/troubleshooting',
+    docs: `${DOCS_BASE}/troubleshooting.md`,
     priority: 'medium',
   },
 
@@ -79,7 +85,7 @@ const TROUBLESHOOTING_DATABASE = {
       'Configure API keys in .env',
       'Delete .mcp.json and reinstall',
     ],
-    docs: 'https://docs.SinapseAI.com/mcps/troubleshooting',
+    docs: `${DOCS_BASE}/troubleshooting.md`,
     priority: 'high',
   },
 
@@ -95,7 +101,7 @@ const TROUBLESHOOTING_DATABASE = {
       'Copy from template: .env, node_modules, *.key, *.pem',
       'Initialize git if needed: git init',
     ],
-    docs: 'https://docs.SinapseAI.com/security/gitignore',
+    docs: `${DOCS_BASE}/security/security-best-practices.md`,
     priority: 'high',
   },
 
@@ -114,7 +120,7 @@ const TROUBLESHOOTING_DATABASE = {
       'Try different package manager: yarn or pnpm',
       'Check disk space: df -h (Unix) or dir (Windows)',
     ],
-    docs: 'https://docs.SinapseAI.com/installation/dependencies',
+    docs: `${DOCS_BASE}/installation/troubleshooting.md`,
     priority: 'critical',
   },
 
@@ -131,7 +137,7 @@ const TROUBLESHOOTING_DATABASE = {
       'Reinstall: npm install',
       'Try clean install: npm ci',
     ],
-    docs: 'https://docs.SinapseAI.com/installation/dependencies',
+    docs: `${DOCS_BASE}/installation/troubleshooting.md`,
     priority: 'high',
   },
 
@@ -161,7 +167,7 @@ const TROUBLESHOOTING_DATABASE = {
       'Run: chmod 600 .env',
       'Verify: ls -la .env',
     ],
-    docs: 'https://docs.SinapseAI.com/security/file-permissions',
+    docs: `${DOCS_BASE}/security/security-best-practices.md`,
     priority: 'medium',
   },
 };
@@ -244,15 +250,15 @@ async function offerTroubleshooting(errors) {
   if (openDocs) {
     console.log('');
     console.log(chalk.green('📚 Documentation:'));
-    console.log(chalk.green('  https://docs.SinapseAI.com/troubleshooting'));
+    console.log(chalk.green(`  ${DOCS_BASE}/troubleshooting.md`));
     console.log('');
   }
 
   // Offer support contact
   console.log('');
   console.log(chalk.bold('💬 Need Help?'));
-  console.log(chalk.dim('  - GitHub Issues: https://github.com/caioimori/sinapse/issues'));
-  console.log(chalk.dim('  - Documentation: https://docs.SinapseAI.com'));
+  console.log(chalk.dim(`  - GitHub Issues: ${REPO_URL}/issues`));
+  console.log(chalk.dim(`  - Documentation: ${DOCS_BASE}/troubleshooting.md`));
   console.log('');
 }
 

package/scripts/gen-agent-badges.js

@@ -71,7 +71,7 @@ for (const line of fs.readFileSync(MANIFEST, 'utf8').split('\n')) {
 }
 
 let squadDirs = [];
-try { squadDirs = fs.readdirSync(SQUADS_DIR).filter((d) => fs.statSync(path.join(SQUADS_DIR, d)).isDirectory()); } catch {}
+try { squadDirs = fs.readdirSync(SQUADS_DIR).filter((d) => fs.statSync(path.join(SQUADS_DIR, d)).isDirectory()); } catch { /* SQUADS_DIR absent — no squads to badge */ }
 for (const squad of squadDirs) {
   const dir = path.join(SQUADS_DIR, squad, 'agents');
   let files = [];

package/scripts/install-chrome-brain.sh

@@ -504,8 +504,8 @@ Nao precisa rodar `chrome-debug` manualmente.
 3. Testar em nova aba → comparar com original → iterar
 
 **Casos validados:**
-- itsoffbrand.com hero (orb WebGL, parallax, blend-mode) — 15min
-- sinapse.club face 3D (Three.js r183, WaltHead.obj, bloom) — 20min
+- Hero com orb WebGL (parallax, blend-mode) — ~15min
+- Cena 3D facial (Three.js, modelo .obj, bloom) — ~20min
 
 ### Animacoes 3D via AI
 

package/scripts/package-synapse.js

@@ -150,11 +150,20 @@ function main() {
   if (fs.existsSync(zipPath)) fs.unlinkSync(zipPath);
 
   try {
-    // Use PowerShell Compress-Archive on Windows
-    execFileSync('powershell', [
-      '-Command',
-      `Compress-Archive -Path '${OUT_DIR}\\*' -DestinationPath '${zipPath}' -Force`,
-    ], { stdio: 'inherit' });
+    if (process.platform === 'win32') {
+      // PowerShell Compress-Archive on Windows
+      execFileSync('powershell', [
+        '-Command',
+        `Compress-Archive -Path '${OUT_DIR}${path.sep}*' -DestinationPath '${zipPath}' -Force`,
+      ], { stdio: 'inherit' });
+    } else {
+      // `zip` is standard on macOS and most Linux; the surrounding catch degrades
+      // gracefully (keeps the unzipped dir) if it is not installed.
+      execFileSync('zip', ['-r', '-q', zipPath, path.basename(OUT_DIR)], {
+        cwd: path.dirname(OUT_DIR),
+        stdio: 'inherit',
+      });
+    }
     console.log(`\nZIP created: ${ZIP_NAME}`);
     console.log(`Size: ${(fs.statSync(zipPath).size / 1024).toFixed(1)} KB`);
   } catch (err) {

package/scripts/prepare-hooks.js

@@ -56,3 +56,22 @@ const managedReady = fs.existsSync(path.join(projectRoot, managedDir, 'pre-commi
 if (inGitWorkTree && managedReady) {
   runDirect('git', ['config', 'core.hooksPath', managedDir]);
 }
+
+// 3. On Unix, ensure the managed hook entrypoints are executable. Git SILENTLY
+//    ignores hooks that lack the +x bit, so without this the SINAPSE guards
+//    (secret scan, SQL guard, protected-files) would not run on macOS/Linux —
+//    they would only fire on Windows (which ignores the bit entirely). The
+//    tracked git mode is already 100755, but a Windows-side `npm pack` or a
+//    permissive checkout can drop it; this makes the executable bit deterministic.
+if (managedReady && !onWindows) {
+  for (const hook of ['pre-commit', 'pre-push', 'post-commit']) {
+    const hookPath = path.join(projectRoot, managedDir, hook);
+    try {
+      if (fs.existsSync(hookPath)) {
+        fs.chmodSync(hookPath, 0o755);
+      }
+    } catch {
+      // best-effort — never break `npm install` over a chmod
+    }
+  }
+}