knowzcode 0.3.7 → 0.5.2

package/bin/knowzcode.mjs

@@ -43,7 +43,7 @@ const PLATFORMS = {
   },
   codex: {
     name: 'OpenAI Codex',
-    detect: (dir) => existsSync(join(dir, 'AGENTS.md')) || existsSync(join(dir, 'AGENTS.override.md')) || existsSync(join(dir, '.codex')),
+    detect: (dir) => existsSync(join(dir, 'AGENTS.md')) || existsSync(join(dir, 'AGENTS.override.md')) || existsSync(join(dir, '.codex')) || existsSync(join(dir, '.agents')),
     adapterPath: (dir) => join(dir, 'AGENTS.md'),
     templateHeader: '## OpenAI Codex (AGENTS.md)',
   },
@@ -63,7 +63,7 @@ const PLATFORMS = {
     name: 'GitHub Copilot',
     detect: (dir) => existsSync(join(dir, '.github', 'copilot-instructions.md')) || existsSync(join(dir, '.github')),
     adapterPath: (dir) => join(dir, '.github', 'copilot-instructions.md'),
-    templateHeader: '## GitHub Copilot (.github/copilot-instructions.md)',
+    templateHeader: '## GitHub Copilot',
   },
   windsurf: {
     name: 'Windsurf',
@@ -128,6 +128,185 @@ function detectPlatforms(dir) {
 }
 
 // ─── Adapter Template Parser ─────────────────────────────────────────────────
+// Returns Map<platformId, { primary: string, files: Map<relativePath, { content, lang }> }>
+
+function injectVersion(content) {
+  return content.replace(/vX\.Y\.Z/g, `v${VERSION}`);
+}
+
+function extractSection(content, headerIdx) {
+  const afterHeader = content.slice(headerIdx);
+  const nextSection = afterHeader.search(/\r?\n---\r?\n\r?\n## /);
+  return nextSection !== -1 ? afterHeader.slice(0, nextSection) : afterHeader;
+}
+
+function extractFence(text, lang, startFrom = 0) {
+  const marker = '```' + lang;
+  const fenceStart = text.indexOf(marker, startFrom);
+  if (fenceStart === -1) return null;
+  const contentStart = text.indexOf('\n', fenceStart) + 1;
+  // Track nested fences to find the matching closing fence
+  let depth = 0;
+  let pos = contentStart;
+  while (pos < text.length) {
+    const nextFence = text.indexOf('\n```', pos);
+    if (nextFence === -1) return null;
+    const afterBackticks = nextFence + 4;
+    const charAfter = afterBackticks < text.length ? text[afterBackticks] : undefined;
+    if (charAfter && /\w/.test(charAfter)) {
+      // Opening fence (```bash, ```json, etc.)
+      depth++;
+    } else {
+      // Closing fence (``` followed by whitespace/newline/EOF)
+      if (depth === 0) {
+        return { content: text.slice(contentStart, nextFence), endIdx: afterBackticks };
+      }
+      depth--;
+    }
+    pos = afterBackticks;
+  }
+  return null;
+}
+
+function parseCopilotSection(section) {
+  const files = new Map();
+
+  // Section A: copilot-instructions.md (first ```markdown before ### B.)
+  const sectionBIdx = section.indexOf('### B.');
+  const sectionA = sectionBIdx !== -1 ? section.slice(0, sectionBIdx) : section;
+  const primaryFence = extractFence(sectionA, 'markdown');
+  if (!primaryFence) return null;
+
+  // Section B: prompt files (#### kc-*.prompt.md headers)
+  const headerRegex = /#### (kc-[\w-]+\.prompt\.md)/g;
+  const headers = [];
+  let match;
+  while ((match = headerRegex.exec(section)) !== null) {
+    headers.push({ filename: match[1], index: match.index });
+  }
+
+  const sectionCIdx = section.indexOf('### C.');
+  for (let i = 0; i < headers.length; i++) {
+    const start = headers[i].index;
+    const end = i + 1 < headers.length
+      ? headers[i + 1].index
+      : (sectionCIdx !== -1 && sectionCIdx > start ? sectionCIdx : section.length);
+    const subSection = section.slice(start, end);
+
+    const fenceOpen = subSection.indexOf('```markdown');
+    if (fenceOpen === -1) continue;
+    const contentStart = subSection.indexOf('\n', fenceOpen) + 1;
+    // Use lastIndexOf to handle prompt files that contain inner code fences
+    const lastFenceClose = subSection.lastIndexOf('\n```');
+    if (lastFenceClose <= contentStart) continue;
+
+    files.set(`.github/prompts/${headers[i].filename}`, {
+      content: subSection.slice(contentStart, lastFenceClose),
+      lang: 'markdown',
+    });
+  }
+
+  // Section C: .vscode/mcp.json
+  if (sectionCIdx !== -1) {
+    const sectionDIdx = section.indexOf('### D.', sectionCIdx);
+    const sectionC = section.slice(sectionCIdx, sectionDIdx !== -1 ? sectionDIdx : section.length);
+    const jsonFence = extractFence(sectionC, 'json');
+    if (jsonFence) {
+      files.set('.vscode/mcp.json', { content: jsonFence.content, lang: 'json' });
+    }
+  }
+
+  return { primary: primaryFence.content, files };
+}
+
+function parseGeminiSection(section) {
+  const files = new Map();
+
+  // Extract TOML blocks: ```toml fences with # .gemini/commands/kc/{name}.toml comment
+  let searchFrom = 0;
+  while (true) {
+    const fenceStart = section.indexOf('```toml', searchFrom);
+    if (fenceStart === -1) break;
+    const contentStart = section.indexOf('\n', fenceStart) + 1;
+    const fenceEnd = section.indexOf('\n```', contentStart);
+    if (fenceEnd === -1) break;
+    const tomlContent = section.slice(contentStart, fenceEnd);
+    const pathMatch = tomlContent.match(/^# (\.gemini\/commands\/kc\/[\w-]+\.toml)/);
+    if (pathMatch) {
+      files.set(pathMatch[1], { content: tomlContent, lang: 'toml' });
+    }
+    searchFrom = fenceEnd + 4;
+  }
+
+  // Skill files: #### .gemini/skills/kc-{name}/SKILL.md headers
+  const skillRegex = /#### (\.gemini\/skills\/kc-[\w-]+\/SKILL\.md)/g;
+  const skillHeaders = [];
+  let skillMatch;
+  while ((skillMatch = skillRegex.exec(section)) !== null) {
+    skillHeaders.push({ filepath: skillMatch[1], index: skillMatch.index });
+  }
+  // Subagent files: #### .gemini/agents/kc-{name}.md headers
+  const agentRegex = /#### (\.gemini\/agents\/kc-[\w-]+\.md)/g;
+  const agentHeaders = [];
+  let agentMatch;
+  while ((agentMatch = agentRegex.exec(section)) !== null) {
+    agentHeaders.push({ filepath: agentMatch[1], index: agentMatch.index });
+  }
+  // Combine all subsection headers for boundary detection
+  const allSubHeaders = [...skillHeaders, ...agentHeaders].sort((a, b) => a.index - b.index);
+
+  for (let i = 0; i < allSubHeaders.length; i++) {
+    const start = allSubHeaders[i].index;
+    const end = i + 1 < allSubHeaders.length ? allSubHeaders[i + 1].index : section.length;
+    const subSection = section.slice(start, end);
+    const fence = extractFence(subSection, 'markdown');
+    if (fence) {
+      files.set(allSubHeaders[i].filepath, { content: fence.content, lang: 'markdown' });
+    }
+  }
+
+  // Primary: ```markdown fence (GEMINI.md) — extract from content BEFORE first skill/subagent header
+  const firstSubHeader = allSubHeaders.length > 0 ? allSubHeaders[0].index : section.length;
+  const primarySection = section.slice(0, firstSubHeader);
+  const primaryFence = extractFence(primarySection, 'markdown');
+  if (!primaryFence) return null;
+
+  return { primary: primaryFence.content, files };
+}
+
+function parseCodexSection(section) {
+  const files = new Map();
+
+  // Primary: first ```markdown fence (AGENTS.md)
+  const primaryFence = extractFence(section, 'markdown');
+  if (!primaryFence) return null;
+
+  // Skill files: #### .agents/skills/kc-{name}/SKILL.md headers
+  const headerRegex = /#### (\.agents\/skills\/kc-[\w-]+\/SKILL\.md)/g;
+  const headers = [];
+  let match;
+  while ((match = headerRegex.exec(section)) !== null) {
+    headers.push({ filepath: match[1], index: match.index });
+  }
+
+  for (let i = 0; i < headers.length; i++) {
+    const start = headers[i].index;
+    const end = i + 1 < headers.length ? headers[i + 1].index : section.length;
+    const subSection = section.slice(start, end);
+    const fence = extractFence(subSection, 'markdown');
+    if (fence) {
+      files.set(headers[i].filepath, { content: fence.content, lang: 'markdown' });
+    }
+  }
+
+  return { primary: primaryFence.content, files };
+}
+
+function parseSimpleSection(section) {
+  const primaryFence = extractFence(section, 'markdown');
+  if (!primaryFence) return null;
+  return { primary: primaryFence.content, files: new Map() };
+}
 
 function parseAdapterTemplates() {
   const adaptersPath = join(PKG_ROOT, 'knowzcode', 'platform_adapters.md');
@@ -145,16 +324,15 @@ function parseAdapterTemplates() {
     const headerIdx = content.indexOf(platform.templateHeader);
     if (headerIdx === -1) continue;
 
-    // Find the code fence after this header
-    const afterHeader = content.slice(headerIdx);
-    const fenceStart = afterHeader.indexOf('```markdown');
-    if (fenceStart === -1) continue;
-
-    const contentStart = afterHeader.indexOf('\n', fenceStart) + 1;
-    const fenceEnd = afterHeader.indexOf('\n```', contentStart);
-    if (fenceEnd === -1) continue;
-
-    templates.set(id, afterHeader.slice(contentStart, fenceEnd));
+    const section = extractSection(content, headerIdx);
+    let result;
+    switch (id) {
+      case 'copilot': result = parseCopilotSection(section); break;
+      case 'gemini': result = parseGeminiSection(section); break;
+      case 'codex': result = parseCodexSection(section); break;
+      default: result = parseSimpleSection(section); break;
+    }
+    if (result) templates.set(id, result);
   }
 
   return templates;
@@ -233,6 +411,57 @@ function removeMarketplaceConfig(claudeDir) {
   }
 }
 
+// ─── Gemini MCP Config Helpers ────────────────────────────────────────────────
+
+function writeGeminiMcpConfig(settingsPath, apiKey, projectPath, endpoint = 'https://mcp.knowz.io/mcp') {
+  ensureDir(dirname(settingsPath));
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+  if (!settings.mcpServers) settings.mcpServers = {};
+  settings.mcpServers.knowz = {
+    url: endpoint,
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'X-Project-Path': projectPath,
+    },
+  };
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+function removeGeminiMcpConfig(settingsPath) {
+  if (!existsSync(settingsPath)) return false;
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    if (settings.mcpServers && settings.mcpServers.knowz) {
+      delete settings.mcpServers.knowz;
+      if (Object.keys(settings.mcpServers).length === 0) {
+        delete settings.mcpServers;
+      }
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      return true;
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return false;
+}
+
+function hasGeminiMcpConfig(settingsPath) {
+  if (!existsSync(settingsPath)) return false;
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    return !!(settings.mcpServers && settings.mcpServers.knowz);
+  } catch {
+    return false;
+  }
+}
+
 // ─── Stale File Cleanup ─────────────────────────────────────────────────────
 
 function removeStaleFiles(sourceDir, targetDir) {
@@ -550,18 +779,76 @@ async function cmdInstall(opts) {
 
       adapterFiles.push(claudeDir + '/commands/', claudeDir + '/agents/', claudeDir + '/skills/');
     } else {
-      // Other platforms: extract template and write adapter file
-      const template = templates.get(platformId);
-      if (!template) {
+      // Other platforms: extract template and write adapter + additional files
+      const templateSet = templates.get(platformId);
+      if (!templateSet) {
         log.warn(`No adapter template found for ${platform.name} — skipping`);
         continue;
       }
 
+      // Write primary adapter file
       const adapterFile = platform.adapterPath(dir);
       ensureDir(dirname(adapterFile));
-      writeFileSync(adapterFile, template);
+      writeFileSync(adapterFile, injectVersion(templateSet.primary));
       adapterFiles.push(adapterFile);
       log.ok(`${platform.name} adapter: ${adapterFile}`);
+
+      // Write additional files (prompts, TOMLs, skills, subagents)
+      for (const [relativePath, { content }] of templateSet.files) {
+        let filePath;
+        if (platformId === 'codex' && opts.global && relativePath.startsWith('.agents/skills/')) {
+          const homeDir = process.env.HOME || process.env.USERPROFILE || '~';
+          filePath = join(homeDir, relativePath);
+        } else if (platformId === 'gemini' && opts.global && relativePath.startsWith('.gemini/skills/')) {
+          const homeDir = process.env.HOME || process.env.USERPROFILE || '~';
+          filePath = join(homeDir, relativePath);
+        } else {
+          filePath = join(dir, relativePath);
+        }
+        ensureDir(dirname(filePath));
+        writeFileSync(filePath, injectVersion(content));
+        adapterFiles.push(filePath);
+      }
+      if (templateSet.files.size > 0) {
+        log.ok(`  + ${templateSet.files.size} additional file(s)`);
+      }
+
+      // Clean up legacy .codex/skills/kc/ if present (migrated to .agents/skills/)
+      if (platformId === 'codex') {
+        const legacySkillDir = join(dir, '.codex', 'skills', 'kc');
+        if (existsSync(legacySkillDir)) {
+          log.info('Removing legacy .codex/skills/kc/ (migrated to .agents/skills/)');
+          rmSync(legacySkillDir, { recursive: true, force: true });
+        }
+        if (opts.global) {
+          const homeDir = process.env.HOME || process.env.USERPROFILE || '~';
+          const legacyGlobal = join(homeDir, '.codex', 'skills', 'kc');
+          if (existsSync(legacyGlobal)) {
+            log.info('Removing legacy global ~/.codex/skills/kc/');
+            rmSync(legacyGlobal, { recursive: true, force: true });
+          }
+        }
+      }
+    }
+  }
+
+  // 3.5. Gemini MCP config offer (when Gemini is selected and not --force)
+  if (selectedPlatforms.includes('gemini') && !opts.global && !opts.force) {
+    console.log('');
+    console.log(`${c.bold}Gemini MCP Configuration${c.reset}`);
+    console.log(`MCP enables vector search, vault access, and AI-powered Q&A.`);
+    const wantMcp = await promptConfirm('Configure MCP for Gemini CLI? (requires API key)');
+    if (wantMcp) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const apiKey = await rl.question('Enter your KnowzCode API key: ');
+      rl.close();
+      if (apiKey.trim()) {
+        const settingsPath = join(dir, '.gemini', 'settings.json');
+        writeGeminiMcpConfig(settingsPath, apiKey.trim(), dir);
+        log.ok('Gemini MCP configured in .gemini/settings.json');
+      } else {
+        log.warn('No API key provided — skipping MCP config. Use /kc:connect-mcp later.');
+      }
     }
   }
 
@@ -657,6 +944,76 @@ async function cmdUninstall(opts) {
     }
   }
 
+  // Additional platform-specific files/directories
+  const copilotPromptsDir = join(dir, '.github', 'prompts');
+  if (existsSync(copilotPromptsDir)) {
+    for (const f of readdirSync(copilotPromptsDir)) {
+      if (f.startsWith('kc-') && f.endsWith('.prompt.md')) {
+        components.push({ label: `Copilot prompt: ${f}`, path: join(copilotPromptsDir, f) });
+      }
+    }
+  }
+  const vscodeMcp = join(dir, '.vscode', 'mcp.json');
+  if (existsSync(vscodeMcp)) {
+    components.push({ label: 'VS Code MCP config', path: vscodeMcp });
+  }
+  const geminiCmdDir = join(dir, '.gemini', 'commands', 'kc');
+  if (existsSync(geminiCmdDir)) {
+    components.push({ label: 'Gemini commands (kc/)', path: geminiCmdDir });
+  }
+  // Gemini skills: .gemini/skills/kc-*
+  const geminiSkillDir = join(dir, '.gemini', 'skills');
+  if (existsSync(geminiSkillDir)) {
+    for (const entry of readdirSync(geminiSkillDir)) {
+      if (entry.startsWith('kc-')) {
+        components.push({ label: `Gemini skill (${entry}/)`, path: join(geminiSkillDir, entry) });
+      }
+    }
+  }
+  const globalGeminiSkillDir = join(process.env.HOME || process.env.USERPROFILE || '~', '.gemini', 'skills');
+  if (existsSync(globalGeminiSkillDir)) {
+    for (const entry of readdirSync(globalGeminiSkillDir)) {
+      if (entry.startsWith('kc-')) {
+        components.push({ label: `Gemini skill — global (~/.gemini/skills/${entry}/)`, path: join(globalGeminiSkillDir, entry) });
+      }
+    }
+  }
+  // Gemini subagents: .gemini/agents/kc-*.md
+  const geminiAgentDir = join(dir, '.gemini', 'agents');
+  if (existsSync(geminiAgentDir)) {
+    for (const entry of readdirSync(geminiAgentDir)) {
+      if (entry.startsWith('kc-') && entry.endsWith('.md')) {
+        components.push({ label: `Gemini subagent (${entry})`, path: join(geminiAgentDir, entry) });
+      }
+    }
+  }
+  // New path: .agents/skills/kc-*
+  const agentsSkillDir = join(dir, '.agents', 'skills');
+  if (existsSync(agentsSkillDir)) {
+    for (const entry of readdirSync(agentsSkillDir)) {
+      if (entry.startsWith('kc-')) {
+        components.push({ label: `Codex skill (${entry}/)`, path: join(agentsSkillDir, entry) });
+      }
+    }
+  }
+  const globalAgentsSkillDir = join(process.env.HOME || process.env.USERPROFILE || '~', '.agents', 'skills');
+  if (existsSync(globalAgentsSkillDir)) {
+    for (const entry of readdirSync(globalAgentsSkillDir)) {
+      if (entry.startsWith('kc-')) {
+        components.push({ label: `Codex skill — global (~/.agents/skills/${entry}/)`, path: join(globalAgentsSkillDir, entry) });
+      }
+    }
+  }
+  // Legacy path: .codex/skills/kc (remove on uninstall)
+  const legacyCodexSkillDir = join(dir, '.codex', 'skills', 'kc');
+  if (existsSync(legacyCodexSkillDir)) {
+    components.push({ label: 'Codex skills — legacy (.codex/skills/kc/)', path: legacyCodexSkillDir });
+  }
+  const legacyGlobalCodexSkillDir = join(process.env.HOME || process.env.USERPROFILE || '~', '.codex', 'skills', 'kc');
+  if (existsSync(legacyGlobalCodexSkillDir)) {
+    components.push({ label: 'Codex skills — legacy global (~/.codex/skills/kc/)', path: legacyGlobalCodexSkillDir });
+  }
+
   if (components.length === 0) {
     log.info('No KnowzCode installation found.');
     return;
@@ -705,6 +1062,17 @@ async function cmdUninstall(opts) {
   // Clean up marketplace config from settings.json
   removeMarketplaceConfig(claudeDir);
 
+  // Clean up Gemini MCP config (remove only knowz entry, preserve other settings)
+  const geminiSettingsProject = join(dir, '.gemini', 'settings.json');
+  if (removeGeminiMcpConfig(geminiSettingsProject)) {
+    removed.push('Gemini MCP config (.gemini/settings.json)');
+  }
+  const homeDir2 = process.env.HOME || process.env.USERPROFILE || '~';
+  const geminiSettingsUser = join(homeDir2, '.gemini', 'settings.json');
+  if (removeGeminiMcpConfig(geminiSettingsUser)) {
+    removed.push('Gemini MCP config (~/.gemini/settings.json)');
+  }
+
   console.log('');
   log.ok('Uninstall complete');
   console.log('  Removed:');
@@ -821,11 +1189,144 @@ async function cmdUpgrade(opts) {
     const adapterFile = platform.adapterPath(dir);
     if (!existsSync(adapterFile)) continue; // Only update existing adapters
 
-    const template = templates.get(platformId);
-    if (!template) continue;
+    const templateSet = templates.get(platformId);
+    if (!templateSet) continue;
 
-    writeFileSync(adapterFile, template);
+    // Update primary adapter file
+    writeFileSync(adapterFile, injectVersion(templateSet.primary));
     regenerated.push(platform.name);
+
+    // Regenerate additional files
+    const currentPaths = new Set();
+    for (const [relativePath, { content }] of templateSet.files) {
+      const filePath = join(dir, relativePath);
+      ensureDir(dirname(filePath));
+      writeFileSync(filePath, injectVersion(content));
+      currentPaths.add(relativePath);
+    }
+
+    // Stale file cleanup for platform-owned directories
+    if (platformId === 'copilot') {
+      const promptsDir = join(dir, '.github', 'prompts');
+      if (existsSync(promptsDir)) {
+        for (const f of readdirSync(promptsDir)) {
+          if (f.startsWith('kc-') && f.endsWith('.prompt.md') && !currentPaths.has(`.github/prompts/${f}`)) {
+            log.info(`Removing stale prompt: ${f}`);
+            rmSync(join(promptsDir, f), { force: true });
+          }
+        }
+      }
+    } else if (platformId === 'gemini') {
+      const tomlDir = join(dir, '.gemini', 'commands', 'kc');
+      if (existsSync(tomlDir)) {
+        for (const f of readdirSync(tomlDir)) {
+          if (f.endsWith('.toml') && !currentPaths.has(`.gemini/commands/kc/${f}`)) {
+            log.info(`Removing stale command: ${f}`);
+            rmSync(join(tomlDir, f), { force: true });
+          }
+        }
+      }
+      // Stale skill cleanup: .gemini/skills/kc-*
+      const geminiSkillDir = join(dir, '.gemini', 'skills');
+      if (existsSync(geminiSkillDir)) {
+        for (const entry of readdirSync(geminiSkillDir)) {
+          if (entry.startsWith('kc-') && !currentPaths.has(`.gemini/skills/${entry}/SKILL.md`)) {
+            log.info(`Removing stale Gemini skill: ${entry}/`);
+            rmSync(join(geminiSkillDir, entry), { recursive: true, force: true });
+          }
+        }
+      }
+      // Stale subagent cleanup: .gemini/agents/kc-*.md
+      const geminiAgentDir = join(dir, '.gemini', 'agents');
+      if (existsSync(geminiAgentDir)) {
+        for (const entry of readdirSync(geminiAgentDir)) {
+          if (entry.startsWith('kc-') && entry.endsWith('.md') && !currentPaths.has(`.gemini/agents/${entry}`)) {
+            log.info(`Removing stale Gemini subagent: ${entry}`);
+            rmSync(join(geminiAgentDir, entry), { force: true });
+          }
+        }
+      }
+    } else if (platformId === 'codex') {
+      const skillDir = join(dir, '.agents', 'skills');
+      if (existsSync(skillDir)) {
+        for (const entry of readdirSync(skillDir)) {
+          if (entry.startsWith('kc-') && !currentPaths.has(`.agents/skills/${entry}/SKILL.md`)) {
+            log.info(`Removing stale skill: ${entry}/`);
+            rmSync(join(skillDir, entry), { recursive: true, force: true });
+          }
+        }
+      }
+      // Migration: remove legacy .codex/skills/kc/ if present
+      const legacySkillDir = join(dir, '.codex', 'skills', 'kc');
+      if (existsSync(legacySkillDir)) {
+        log.info('Removing legacy .codex/skills/kc/ (migrated to .agents/skills/)');
+        rmSync(legacySkillDir, { recursive: true, force: true });
+      }
+    }
+  }
+
+  // Check for global codex skills
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '~';
+  const globalAgentsSkillDir = join(homeDir, '.agents', 'skills');
+  if (existsSync(globalAgentsSkillDir)) {
+    const codexTemplateSet = templates.get('codex');
+    if (codexTemplateSet) {
+      const currentPaths = new Set([...codexTemplateSet.files.keys()]);
+      // Stale cleanup
+      for (const entry of readdirSync(globalAgentsSkillDir)) {
+        if (entry.startsWith('kc-') && !currentPaths.has(`.agents/skills/${entry}/SKILL.md`)) {
+          log.info(`Removing stale global skill: ${entry}/`);
+          rmSync(join(globalAgentsSkillDir, entry), { recursive: true, force: true });
+        }
+      }
+      // Regenerate global skills
+      for (const [relativePath, { content }] of codexTemplateSet.files) {
+        if (relativePath.startsWith('.agents/skills/')) {
+          const filePath = join(homeDir, relativePath);
+          ensureDir(dirname(filePath));
+          writeFileSync(filePath, injectVersion(content));
+        }
+      }
+      log.info('Updated global Codex skills');
+    }
+  }
+  // Migration: remove legacy global .codex/skills/kc/ if present
+  const legacyGlobalSkillDir = join(homeDir, '.codex', 'skills', 'kc');
+  if (existsSync(legacyGlobalSkillDir)) {
+    log.info('Removing legacy global ~/.codex/skills/kc/ (migrated to ~/.agents/skills/)');
+    rmSync(legacyGlobalSkillDir, { recursive: true, force: true });
+  }
+
+  // Check for global Gemini skills
+  const globalGeminiSkillDir = join(homeDir, '.gemini', 'skills');
+  if (existsSync(globalGeminiSkillDir)) {
+    const geminiTemplateSet = templates.get('gemini');
+    if (geminiTemplateSet) {
+      const currentPaths = new Set([...geminiTemplateSet.files.keys()]);
+      // Stale cleanup
+      for (const entry of readdirSync(globalGeminiSkillDir)) {
+        if (entry.startsWith('kc-') && !currentPaths.has(`.gemini/skills/${entry}/SKILL.md`)) {
+          log.info(`Removing stale global Gemini skill: ${entry}/`);
+          rmSync(join(globalGeminiSkillDir, entry), { recursive: true, force: true });
+        }
+      }
+      // Regenerate global skills
+      for (const [relativePath, { content }] of geminiTemplateSet.files) {
+        if (relativePath.startsWith('.gemini/skills/')) {
+          const filePath = join(homeDir, relativePath);
+          ensureDir(dirname(filePath));
+          writeFileSync(filePath, injectVersion(content));
+        }
+      }
+      log.info('Updated global Gemini skills');
+    }
+  }
+
+  // Preserve Gemini MCP config during upgrade (don't overwrite user's API key)
+  const geminiSettingsPath = join(dir, '.gemini', 'settings.json');
+  const geminiMcpPreserved = hasGeminiMcpConfig(geminiSettingsPath);
+  if (geminiMcpPreserved && opts.verbose) {
+    log.info('Preserved: Gemini MCP config (.gemini/settings.json)');
   }
 
   // Write new version
@@ -834,7 +1335,7 @@ async function cmdUpgrade(opts) {
   console.log('');
   log.ok(`Upgraded to ${VERSION}`);
   console.log('');
-  console.log(`  ${c.bold}Preserved:${c.reset} specs/, tracker, log, architecture, project config`);
+  console.log(`  ${c.bold}Preserved:${c.reset} specs/, tracker, log, architecture, project config${geminiMcpPreserved ? ', Gemini MCP config' : ''}`);
   console.log(`  ${c.bold}Updated:${c.reset}   loop, prompts, adapters, enterprise templates`);
   if (regenerated.length > 0) {
     console.log(`  ${c.bold}Adapters:${c.reset}  ${regenerated.join(', ')}`);
@@ -859,7 +1360,7 @@ ${c.bold}Options:${c.reset}
   --target <path>      Target directory (default: current directory)
   --platforms <list>   Comma-separated: claude,codex,gemini,cursor,copilot,windsurf,all
   --force              Skip confirmation prompts
-  --global             Install Claude Code components to ~/.claude/
+  --global             Install Claude Code to ~/.claude/, Codex skills to ~/.agents/skills/, Gemini skills to ~/.gemini/skills/
   --agent-teams        Enable Agent Teams in .claude/settings.local.json
   --verbose            Show detailed output
   -h, --help           Show this help

package/commands/connect-mcp.md

@@ -87,6 +87,30 @@ Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
    - Parse `--configure-vaults` flag (forces vault prompts)
    - Store parsed values for use in configuration
 
+1.5. **Smart Config Discovery (if no API key in arguments)**
+
+   Before prompting for an API key, check known config sources:
+
+   a. **Environment variable**: Check `KNOWZ_API_KEY`
+      - If set: use as the API key, display "Using API key from KNOWZ_API_KEY (ending ...{last4})"
+
+   b. **Project config**: Read `knowzcode/mcp_config.md`
+      - If `Connected: Yes` and endpoint set: pre-populate endpoint for Step 5
+      - If `API Key (last 4)` set: note for confirmation prompt
+
+   c. **Vault config**: Read `knowzcode/knowzcode_vaults.md`
+      - If vaults have non-empty IDs: note for Step 6 (skip vault prompts unless `--configure-vaults`)
+
+   d. **Cross-platform config files** (check for API key in other platforms):
+      - `.gemini/settings.json` → `mcpServers.knowz.headers.Authorization`
+      - `~/.gemini/settings.json` → same
+      - `.vscode/mcp.json` → `servers.knowz.headers`
+      - If found: extract Bearer token, offer to reuse:
+        "Found existing API key (ending ...{last4}) in {source}. Use this key? [Yes/No]"
+
+   If a key was discovered, skip Step 3 (interactive API key prompt).
+   If vaults were discovered, skip vault prompts in Step 6.
+
 2. **Check for existing configuration**
    - Check if MCP server already configured: `CLAUDECODE= claude mcp get knowz`
    - If already configured, ask if user wants to reconfigure
@@ -324,6 +348,7 @@ Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
      - Set `Connected: Yes`
      - Set `Endpoint: <endpoint-url>`
      - Set `Last Verified: <timestamp>`
+     - Set `API Key (last 4): <last 4 characters of the API key>`
      - Set Ecosystem Vault ID and name (if provided or already set)
      - Set Code Vault ID and name (if provided)
      - Set `Auto-configured: No` (to distinguish from /kc:register setup)