knowzcode 0.4.0 → 0.5.2

package/bin/knowzcode.mjs

@@ -1,1199 +1,1457 @@
-#!/usr/bin/env node
-
-// KnowzCode CLI — Zero-dependency Node.js installer
-// Usage: npx knowzcode [install|uninstall|upgrade|detect] [options]
-
-import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync } from 'fs';
-import { join, resolve, dirname, basename } from 'path';
-import { fileURLToPath } from 'url';
-import { createInterface } from 'readline/promises';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const PKG_ROOT = resolve(__dirname, '..');
-const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version;
-
-// ─── Colors ──────────────────────────────────────────────────────────────────
-
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-};
-
-const log = {
-  info: (msg) => console.log(`${c.blue}[INFO]${c.reset} ${msg}`),
-  ok: (msg) => console.log(`${c.green}[OK]${c.reset} ${msg}`),
-  warn: (msg) => console.log(`${c.yellow}[WARN]${c.reset} ${msg}`),
-  err: (msg) => console.error(`${c.red}[ERROR]${c.reset} ${msg}`),
-};
-
-// ─── Platform Definitions ────────────────────────────────────────────────────
-
-const PLATFORMS = {
-  claude: {
-    name: 'Claude Code',
-    detect: (dir) => existsSync(join(dir, '.claude')) || existsSync(join(dir, '.claude-plugin')),
-    adapterPath: null, // Claude uses .claude/ dir structure, not a single adapter file
-  },
-  codex: {
-    name: 'OpenAI Codex',
-    detect: (dir) => existsSync(join(dir, 'AGENTS.md')) || existsSync(join(dir, 'AGENTS.override.md')) || existsSync(join(dir, '.codex')),
-    adapterPath: (dir) => join(dir, 'AGENTS.md'),
-    templateHeader: '## OpenAI Codex (AGENTS.md)',
-  },
-  gemini: {
-    name: 'Gemini CLI',
-    detect: (dir) => existsSync(join(dir, 'GEMINI.md')) || existsSync(join(dir, '.gemini')),
-    adapterPath: (dir) => join(dir, 'GEMINI.md'),
-    templateHeader: '## Google Gemini CLI (GEMINI.md)',
-  },
-  cursor: {
-    name: 'Cursor',
-    detect: (dir) => existsSync(join(dir, '.cursor', 'rules')) || existsSync(join(dir, '.cursorrules')),
-    adapterPath: (dir) => join(dir, '.cursor', 'rules', 'knowzcode.mdc'),
-    templateHeader: '## Cursor (`.cursor/rules/knowzcode.mdc`)',
-  },
-  copilot: {
-    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',
-  },
-  windsurf: {
-    name: 'Windsurf',
-    detect: (dir) => existsSync(join(dir, '.windsurf', 'rules')) || existsSync(join(dir, '.windsurfrules')),
-    adapterPath: (dir) => join(dir, '.windsurf', 'rules', 'knowzcode.md'),
-    templateHeader: '## Windsurf (`.windsurf/rules/knowzcode.md`)',
-  },
-};
-
-// ─── CLI Argument Parser ─────────────────────────────────────────────────────
-
-function parseArgs(argv) {
-  const args = argv.slice(2);
-  const opts = {
-    command: null,
-    target: process.cwd(),
-    platforms: [],
-    force: false,
-    global: false,
-    verbose: false,
-    agentTeams: false,
-  };
-
-  let i = 0;
-  while (i < args.length) {
-    const arg = args[i];
-    if (arg === '--target' && i + 1 < args.length) {
-      opts.target = resolve(args[++i]);
-    } else if (arg === '--platforms' && i + 1 < args.length) {
-      opts.platforms = args[++i].split(',').map((p) => p.trim().toLowerCase());
-    } else if (arg === '--force') {
-      opts.force = true;
-    } else if (arg === '--global') {
-      opts.global = true;
-    } else if (arg === '--agent-teams') {
-      opts.agentTeams = true;
-    } else if (arg === '--verbose') {
-      opts.verbose = true;
-    } else if (arg === '--help' || arg === '-h') {
-      opts.command = 'help';
-    } else if (arg === '--version' || arg === '-v') {
-      opts.command = 'version';
-    } else if (!arg.startsWith('-') && !opts.command) {
-      opts.command = arg.toLowerCase();
-    }
-    i++;
-  }
-
-  return opts;
-}
-
-// ─── Platform Detection ──────────────────────────────────────────────────────
-
-function detectPlatforms(dir) {
-  const detected = [];
-  for (const [id, platform] of Object.entries(PLATFORMS)) {
-    if (platform.detect(dir)) {
-      detected.push(id);
-    }
-  }
-  return detected;
-}
-
-// ─── 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;
-  const fenceEnd = text.indexOf('\n```', contentStart);
-  if (fenceEnd === -1) return null;
-  return { content: text.slice(contentStart, fenceEnd), endIdx: fenceEnd + 4 };
-}
-
-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;
-  }
-
-  // Primary: ```markdown fence (GEMINI.md)
-  const primaryFence = extractFence(section, '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: #### .codex/skills/kc/{name}.md headers
-  const headerRegex = /#### (\.codex\/skills\/kc\/[\w-]+\.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');
-  if (!existsSync(adaptersPath)) {
-    log.warn('platform_adapters.md not found — adapter generation will be skipped');
-    return new Map();
-  }
-
-  const content = readFileSync(adaptersPath, 'utf8');
-  const templates = new Map();
-
-  for (const [id, platform] of Object.entries(PLATFORMS)) {
-    if (!platform.templateHeader) continue;
-
-    const headerIdx = content.indexOf(platform.templateHeader);
-    if (headerIdx === -1) continue;
-
-    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;
-}
-
-// ─── File Copy Helpers ───────────────────────────────────────────────────────
-
-function ensureDir(dir) {
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-}
-
-function copyDirContents(src, dst) {
-  ensureDir(dst);
-  if (!existsSync(src)) return;
-
-  for (const entry of readdirSync(src, { withFileTypes: true })) {
-    const srcPath = join(src, entry.name);
-    const dstPath = join(dst, entry.name);
-    if (entry.isDirectory()) {
-      copyDirContents(srcPath, dstPath);
-    } else {
-      writeFileSync(dstPath, readFileSync(srcPath));
-    }
-  }
-}
-
-function listFilesRecursive(dir, base = dir) {
-  const files = [];
-  if (!existsSync(dir)) return files;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...listFilesRecursive(full, base));
-    } else {
-      files.push(full);
-    }
-  }
-  return files;
-}
-
-// ─── Marketplace Config ──────────────────────────────────────────────────────
-
-function setMarketplaceConfig(claudeDir) {
-  ensureDir(claudeDir);
-  const settingsFile = join(claudeDir, 'settings.json');
-  let settings = {};
-
-  if (existsSync(settingsFile)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
-    } catch {
-      settings = {};
-    }
-  }
-
-  if (!settings.extraKnownMarketplaces) settings.extraKnownMarketplaces = {};
-  settings.extraKnownMarketplaces.knowzcode = {
-    source: { source: 'github', repo: 'knowz-io/knowzcode' },
-  };
-
-  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-}
-
-function removeMarketplaceConfig(claudeDir) {
-  const settingsFile = join(claudeDir, 'settings.json');
-  if (!existsSync(settingsFile)) return;
-
-  try {
-    const settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
-    if (settings.extraKnownMarketplaces && settings.extraKnownMarketplaces.knowzcode) {
-      delete settings.extraKnownMarketplaces.knowzcode;
-      writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-    }
-  } catch {
-    // Ignore parse errors
-  }
-}
-
-// ─── Stale File Cleanup ─────────────────────────────────────────────────────
-
-function removeStaleFiles(sourceDir, targetDir) {
-  if (!existsSync(targetDir) || !existsSync(sourceDir)) return;
-
-  const sourceFiles = new Set(
-    readdirSync(sourceDir)
-      .filter((f) => f.endsWith('.md'))
-  );
-
-  for (const entry of readdirSync(targetDir)) {
-    if (entry.endsWith('.md') && !sourceFiles.has(entry)) {
-      const stale = join(targetDir, entry);
-      if (existsSync(stale) && statSync(stale).isFile()) {
-        log.info(`Removing stale file: ${stale}`);
-        rmSync(stale, { force: true });
-      }
-    }
-  }
-}
-
-// ─── Tracker & Log Initializers ──────────────────────────────────────────────
-
-function initTracker(filePath) {
-  writeFileSync(filePath, `# KnowzCode - Status Map
-
-**Purpose:** This document tracks the development status of all implementable components (NodeIDs) defined in \`knowzcode_architecture.md\`.
-
----
-**Progress: 0%**
----
-
-| Status | WorkGroupID | Node ID | Label | Dependencies | Logical Grouping | Spec Link | Classification | Notes / Issues |
-| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| | | | | | | | | |
-
----
-### Status Legend:
-
-*   ⚪️ **\`[TODO]\`**: Task is defined and ready to be picked up if dependencies are met.
-*   📝 **\`[NEEDS_SPEC]\`**: Node has been identified but requires a detailed specification.
-*   ◆ **\`[WIP]\`**: Work In Progress. The KnowzCode AI Agent is currently working on this node.
-*   🟢 **\`[VERIFIED]\`**: Node has been implemented and verified.
-*   ❗ **\`[ISSUE]\`**: A significant issue or blocker has been identified.
-
----
-*(This table will be populated as you define your architecture and NodeIDs.)*
-`);
-}
-
-function initLog(filePath) {
-  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
-  writeFileSync(filePath, `# KnowzCode - Operational Record
-
-**Purpose:** Chronological record of significant events, decisions, and verification outcomes.
-
----
-
-## Section 1: Operational Log
-
----
-**[NEWEST ENTRIES APPEAR HERE - DO NOT REMOVE THIS MARKER]**
----
-**Type:** SystemInitialization
-**Timestamp:** ${ts}
-**NodeID(s):** Project-Wide
-**Logged By:** knowzcode-cli
-**Details:**
-KnowzCode framework installed via \`npx knowzcode\`.
-- Framework files initialized
-- Ready for first feature
----
-
-## Section 2: Reference Quality Criteria (ARC-Based Verification)
-
-### Core Quality Criteria
-1.  **Maintainability:** Ease of modification, clarity of code and design.
-2.  **Reliability:** Robustness of error handling, fault tolerance.
-3.  **Testability:** Adequacy of unit test coverage, ease of testing.
-4.  **Performance:** Responsiveness, efficiency in resource utilization.
-5.  **Security:** Resistance to common vulnerabilities.
-
-### Structural Criteria
-6.  **Readability:** Code clarity, adherence to naming conventions.
-7.  **Complexity Management:** Avoidance of overly complex logic.
-8.  **Modularity:** Adherence to Single Responsibility Principle.
-9.  **Code Duplication (DRY):** Minimization of redundant code.
-10. **Standards Compliance:** Adherence to language best practices.
-
-*(Refer to these criteria during ARC-Based Verification.)*
-`);
-}
-
-// ─── Interactive Prompt ──────────────────────────────────────────────────────
-
-async function promptPlatforms(detected) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const ids = Object.keys(PLATFORMS);
-
-  console.log('');
-  console.log(`${c.bold}Select platforms to generate adapters for:${c.reset}`);
-  console.log('');
-  ids.forEach((id, i) => {
-    const p = PLATFORMS[id];
-    const tag = detected.includes(id) ? ` ${c.green}(detected)${c.reset}` : '';
-    console.log(`  [${i + 1}] ${p.name}${tag}`);
-  });
-  console.log(`  [A] All platforms`);
-  console.log(`  [S] Skip adapters (core framework only)`);
-  console.log('');
-
-  const answer = await rl.question('Select platforms (comma-separated, e.g. 1,2): ');
-  rl.close();
-
-  const trimmed = answer.trim().toUpperCase();
-  if (trimmed === 'S' || trimmed === '') return [];
-  if (trimmed === 'A') return ids;
-
-  const selected = [];
-  for (const part of trimmed.split(',')) {
-    const num = parseInt(part.trim(), 10);
-    if (num >= 1 && num <= ids.length) {
-      selected.push(ids[num - 1]);
-    }
-  }
-  return [...new Set(selected)];
-}
-
-async function promptConfirm(message) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await rl.question(`${message} [y/N]: `);
-  rl.close();
-  return answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes';
-}
-
-// ─── Agent Teams Enablement ──────────────────────────────────────────────────
-
-function enableAgentTeams(claudeDir, isGlobal) {
-  ensureDir(claudeDir);
-  const settingsFile = join(claudeDir, isGlobal ? 'settings.json' : 'settings.local.json');
-
-  let settings = {};
-  if (existsSync(settingsFile)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
-    } catch {
-      settings = {};
-    }
-  }
-
-  if (!settings.env) settings.env = {};
-  settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
-
-  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-  log.ok(`Agent Teams enabled in ${settingsFile}`);
-}
-
-// ─── Commands ────────────────────────────────────────────────────────────────
-
-// DETECT
-function cmdDetect(opts) {
-  const dir = opts.target;
-  console.log('');
-  console.log(`${c.bold}KnowzCode Platform Detection${c.reset}`);
-  console.log(`${c.dim}Scanning: ${dir}${c.reset}`);
-  console.log('');
-
-  const detected = detectPlatforms(dir);
-  const hasKnowzcode = existsSync(join(dir, 'knowzcode'));
-
-  console.log(`  KnowzCode framework: ${hasKnowzcode ? `${c.green}installed${c.reset}` : `${c.dim}not found${c.reset}`}`);
-
-  if (hasKnowzcode) {
-    const versionFile = join(dir, 'knowzcode', '.knowzcode-version');
-    if (existsSync(versionFile)) {
-      const ver = readFileSync(versionFile, 'utf8').trim();
-      console.log(`  Installed version:   ${c.cyan}${ver}${c.reset}`);
-    }
-  }
-
-  console.log('');
-  console.log(`  ${c.bold}Platforms:${c.reset}`);
-
-  for (const [id, platform] of Object.entries(PLATFORMS)) {
-    const found = detected.includes(id);
-    const indicator = found ? `${c.green}detected${c.reset}` : `${c.dim}not detected${c.reset}`;
-    console.log(`    ${platform.name.padEnd(18)} ${indicator}`);
-  }
-
-  console.log('');
-  if (detected.length === 0) {
-    console.log(`  No platforms detected. Run ${c.cyan}npx knowzcode install${c.reset} to set up.`);
-  } else {
-    console.log(`  ${detected.length} platform(s) detected.`);
-  }
-  console.log('');
-}
-
-// INSTALL
-async function cmdInstall(opts) {
-  const dir = opts.target;
-  const kcDir = join(dir, 'knowzcode');
-
-  console.log('');
-  console.log(`${c.bold}KnowzCode Install${c.reset}`);
-  console.log(`${c.dim}Target: ${dir}${c.reset}`);
-  console.log('');
-
-  // Check for existing installation
-  if (existsSync(kcDir) && !opts.force) {
-    log.warn('KnowzCode already installed at ' + kcDir);
-    log.warn('Use --force to overwrite.');
-    process.exit(1);
-  }
-
-  if (!existsSync(dir)) {
-    log.err('Target directory does not exist: ' + dir);
-    process.exit(1);
-  }
-
-  // 1. Copy knowzcode/ template directory
-  log.info('Installing core framework...');
-  const srcKc = join(PKG_ROOT, 'knowzcode');
-  ensureDir(kcDir);
-  ensureDir(join(kcDir, 'specs'));
-  ensureDir(join(kcDir, 'workgroups'));
-  ensureDir(join(kcDir, 'prompts'));
-
-  // Create workgroups/README.md (workgroups/ is gitignored and excluded from npm)
-  writeFileSync(join(kcDir, 'workgroups', 'README.md'), '# WorkGroups\n\nSession-specific WorkGroup files are stored here.\nThis directory is gitignored — contents are local to each checkout.\n');
-
-  // Copy .md files (skip tracker and log — generate fresh)
-  for (const entry of readdirSync(srcKc)) {
-    const srcPath = join(srcKc, entry);
-    const stat = statSync(srcPath);
-    if (stat.isFile() && entry.endsWith('.md') && entry !== 'knowzcode_tracker.md' && entry !== 'knowzcode_log.md') {
-      writeFileSync(join(kcDir, entry), readFileSync(srcPath));
-    } else if (stat.isFile() && !entry.endsWith('.md')) {
-      // Copy non-md files, handling gitignore.template → .gitignore rename
-      if (entry === 'gitignore.template') {
-        writeFileSync(join(kcDir, '.gitignore'), readFileSync(srcPath));
-      } else {
-        writeFileSync(join(kcDir, entry), readFileSync(srcPath));
-      }
-    }
-  }
-
-  // Copy prompts/
-  if (existsSync(join(srcKc, 'prompts'))) {
-    copyDirContents(join(srcKc, 'prompts'), join(kcDir, 'prompts'));
-  }
-
-  // Copy specs readme
-  if (existsSync(join(srcKc, 'specs', 'Readme.md'))) {
-    writeFileSync(join(kcDir, 'specs', 'Readme.md'), readFileSync(join(srcKc, 'specs', 'Readme.md')));
-  }
-
-  // Copy enterprise/ if exists
-  if (existsSync(join(srcKc, 'enterprise'))) {
-    copyDirContents(join(srcKc, 'enterprise'), join(kcDir, 'enterprise'));
-  }
-
-  // Initialize fresh tracker and log
-  initTracker(join(kcDir, 'knowzcode_tracker.md'));
-  initLog(join(kcDir, 'knowzcode_log.md'));
-
-  // Write version marker
-  writeFileSync(join(kcDir, '.knowzcode-version'), VERSION + '\n');
-
-  log.ok('Core framework installed');
-
-  // 2. Platform detection + selection
-  const detected = detectPlatforms(dir);
-  let selectedPlatforms;
-
-  if (opts.platforms.length > 0) {
-    if (opts.platforms.includes('all')) {
-      selectedPlatforms = Object.keys(PLATFORMS);
-    } else {
-      selectedPlatforms = opts.platforms.filter((p) => p in PLATFORMS);
-    }
-  } else if (opts.force) {
-    // Non-interactive mode with --force: install for detected platforms only
-    selectedPlatforms = detected;
-  } else {
-    selectedPlatforms = await promptPlatforms(detected);
-  }
-
-  // 3. Generate adapters
-  const templates = parseAdapterTemplates();
-  const adapterFiles = [];
-
-  for (const platformId of selectedPlatforms) {
-    const platform = PLATFORMS[platformId];
-
-    if (platformId === 'claude') {
-      // Claude Code: copy agents, commands, skills
-      const claudeDir = opts.global ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude') : join(dir, '.claude');
-
-      log.info(`Installing Claude Code components to ${claudeDir}/`);
-
-      // Remove stale files before copying on --force
-      if (opts.force) {
-        removeStaleFiles(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
-        removeStaleFiles(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
-        removeStaleFiles(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
-      }
-
-      copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
-      copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
-      copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
-
-      // Pre-register marketplace in settings.json
-      setMarketplaceConfig(claudeDir);
-
-      adapterFiles.push(claudeDir + '/commands/', claudeDir + '/agents/', claudeDir + '/skills/');
-    } else {
-      // 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, injectVersion(templateSet.primary));
-      adapterFiles.push(adapterFile);
-      log.ok(`${platform.name} adapter: ${adapterFile}`);
-
-      // Write additional files (prompts, TOMLs, skills)
-      for (const [relativePath, { content }] of templateSet.files) {
-        let filePath;
-        if (platformId === 'codex' && opts.global && relativePath.startsWith('.codex/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)`);
-      }
-    }
-  }
-
-  // 4. Agent Teams enablement
-  const agentTeamsClaudeDir = opts.global
-    ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude')
-    : join(dir, '.claude');
-  let agentTeamsEnabled = false;
-  if (opts.agentTeams) {
-    enableAgentTeams(agentTeamsClaudeDir, opts.global);
-    agentTeamsEnabled = true;
-  } else if (selectedPlatforms.includes('claude') && !opts.force) {
-    // Interactive prompt for Claude Code users
-    console.log('');
-    console.log(`${c.bold}Agent Teams${c.reset} enables multi-agent coordination where specialized`);
-    console.log(`teammates handle each workflow phase. ${c.dim}(experimental)${c.reset}`);
-    const wantTeams = await promptConfirm('Enable Agent Teams? (recommended for Claude Code)');
-    if (wantTeams) {
-      enableAgentTeams(agentTeamsClaudeDir, opts.global);
-      agentTeamsEnabled = true;
-    }
-  }
-
-  // 5. Summary
-  console.log('');
-  console.log(`${c.green}${c.bold}Installation complete!${c.reset}`);
-  console.log('');
-  console.log('  Framework:  ' + kcDir + '/');
-  if (adapterFiles.length > 0) {
-    console.log('  Adapters:');
-    for (const f of adapterFiles) {
-      console.log('    ' + f);
-    }
-  }
-  if (agentTeamsEnabled) {
-    console.log('  Agent Teams: enabled');
-  }
-  console.log('');
-  console.log(`${c.bold}Next steps:${c.reset}`);
-  console.log('  1. Edit knowzcode/knowzcode_project.md — set project name, stack, standards');
-  console.log('  2. Edit knowzcode/environment_context.md — configure build/test commands');
-  if (selectedPlatforms.includes('claude')) {
-    console.log('  3. Install the KnowzCode plugin (recommended):');
-    console.log('     /plugin install kc@knowzcode');
-    console.log('  4. Start building:');
-    console.log('     /kc:work "Your first feature"');
-    console.log('');
-    console.log('  Note: Commands also work without plugin as /work, /plan, /fix, etc.');
-  } else {
-    console.log('  3. Start building: use knowzcode/prompts/[LOOP_1A]__Propose_Change_Set.md');
-  }
-  console.log('');
-}
-
-// UNINSTALL
-async function cmdUninstall(opts) {
-  const dir = opts.target;
-  const kcDir = join(dir, 'knowzcode');
-
-  console.log('');
-  console.log(`${c.bold}KnowzCode Uninstall${c.reset}`);
-  console.log(`${c.dim}Target: ${dir}${c.reset}`);
-  console.log('');
-
-  // Scan for installed components
-  const components = [];
-
-  if (existsSync(kcDir)) {
-    components.push({ label: 'Core framework', path: kcDir });
-  }
-
-  // Claude Code components
-  const claudeDir = join(dir, '.claude');
-  for (const sub of ['commands', 'agents', 'skills']) {
-    const p = join(claudeDir, sub);
-    if (existsSync(p)) {
-      components.push({ label: `Claude Code ${sub}`, path: p });
-    }
-  }
-
-  // Platform adapter files
-  const adapterChecks = {
-    codex: join(dir, 'AGENTS.md'),
-    gemini: join(dir, 'GEMINI.md'),
-    cursor: join(dir, '.cursor', 'rules', 'knowzcode.mdc'),
-    copilot: join(dir, '.github', 'copilot-instructions.md'),
-    windsurf: join(dir, '.windsurf', 'rules', 'knowzcode.md'),
-  };
-
-  for (const [id, path] of Object.entries(adapterChecks)) {
-    if (existsSync(path)) {
-      components.push({ label: `${PLATFORMS[id].name} adapter`, path });
-    }
-  }
-
-  // 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 });
-  }
-  const codexSkillDir = join(dir, '.codex', 'skills', 'kc');
-  if (existsSync(codexSkillDir)) {
-    components.push({ label: 'Codex skills (kc/)', path: codexSkillDir });
-  }
-  const globalCodexSkillDir = join(process.env.HOME || process.env.USERPROFILE || '~', '.codex', 'skills', 'kc');
-  if (existsSync(globalCodexSkillDir)) {
-    components.push({ label: 'Codex skills — global (~/.codex/skills/kc/)', path: globalCodexSkillDir });
-  }
-
-  if (components.length === 0) {
-    log.info('No KnowzCode installation found.');
-    return;
-  }
-
-  console.log('  Components found:');
-  for (const comp of components) {
-    console.log(`    ${comp.label}: ${comp.path}`);
-  }
-  console.log('');
-
-  // Ask about preserving user data
-  let preserveUserData = false;
-  if (existsSync(kcDir) && !opts.force) {
-    preserveUserData = await promptConfirm('Preserve user data (specs/, architecture, tracker, log)?');
-  }
-
-  if (!opts.force) {
-    const confirmed = await promptConfirm('Remove all listed components?');
-    if (!confirmed) {
-      log.info('Uninstall cancelled.');
-      return;
-    }
-  }
-
-  const removed = [];
-
-  // Remove components
-  for (const comp of components) {
-    if (comp.path === kcDir && preserveUserData) {
-      // Selective removal — keep user data
-      const preserve = ['specs', 'knowzcode_architecture.md', 'knowzcode_tracker.md', 'knowzcode_log.md', 'knowzcode_project.md'];
-
-      for (const entry of readdirSync(kcDir)) {
-        if (preserve.includes(entry)) continue;
-        const entryPath = join(kcDir, entry);
-        rmSync(entryPath, { recursive: true, force: true });
-      }
-      removed.push(comp.label + ' (user data preserved)');
-    } else {
-      rmSync(comp.path, { recursive: true, force: true });
-      removed.push(comp.label);
-    }
-  }
-
-  // Clean up marketplace config from settings.json
-  removeMarketplaceConfig(claudeDir);
-
-  console.log('');
-  log.ok('Uninstall complete');
-  console.log('  Removed:');
-  for (const r of removed) {
-    console.log(`    ${r}`);
-  }
-  console.log('');
-}
-
-// UPGRADE
-async function cmdUpgrade(opts) {
-  const dir = opts.target;
-  const kcDir = join(dir, 'knowzcode');
-
-  console.log('');
-  console.log(`${c.bold}KnowzCode Upgrade${c.reset}`);
-  console.log(`${c.dim}Target: ${dir}${c.reset}`);
-  console.log('');
-
-  if (!existsSync(kcDir)) {
-    log.err('No KnowzCode installation found. Run `npx knowzcode install` first.');
-    process.exit(1);
-  }
-
-  // Read current version
-  const versionFile = join(kcDir, '.knowzcode-version');
-  const currentVersion = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : 'unknown';
-
-  if (currentVersion === VERSION && !opts.force) {
-    log.info(`Already at version ${VERSION}. Use --force to reinstall.`);
-    return;
-  }
-
-  log.info(`Upgrading: ${currentVersion} → ${VERSION}`);
-
-  // Files to preserve (never overwrite)
-  const preserveFiles = new Set([
-    'knowzcode_tracker.md',
-    'knowzcode_log.md',
-    'knowzcode_architecture.md',
-    'knowzcode_project.md',
-    'environment_context.md',
-    'user_preferences.md',
-  ]);
-  const preserveDirs = new Set(['specs', 'workgroups']);
-
-  // Files to replace (always update)
-  const srcKc = join(PKG_ROOT, 'knowzcode');
-
-  // Update .md files
-  for (const entry of readdirSync(srcKc)) {
-    const srcPath = join(srcKc, entry);
-    const dstPath = join(kcDir, entry);
-    const stat = statSync(srcPath);
-
-    if (stat.isFile()) {
-      if (preserveFiles.has(entry)) {
-        if (opts.verbose) log.info(`Preserved: ${entry}`);
-        continue;
-      }
-      // Handle gitignore.template → .gitignore rename
-      if (entry === 'gitignore.template') {
-        writeFileSync(join(kcDir, '.gitignore'), readFileSync(srcPath));
-        if (opts.verbose) log.info('Updated: .gitignore (from gitignore.template)');
-      } else {
-        writeFileSync(dstPath, readFileSync(srcPath));
-        if (opts.verbose) log.info(`Updated: ${entry}`);
-      }
-    }
-  }
-
-  // Update prompts/ (always replace)
-  if (existsSync(join(srcKc, 'prompts'))) {
-    const promptsDst = join(kcDir, 'prompts');
-    // Remove old prompts, copy new ones
-    if (existsSync(promptsDst)) rmSync(promptsDst, { recursive: true, force: true });
-    copyDirContents(join(srcKc, 'prompts'), promptsDst);
-    if (opts.verbose) log.info('Updated: prompts/');
-  }
-
-  // Update enterprise/ (always replace)
-  if (existsSync(join(srcKc, 'enterprise'))) {
-    const entDst = join(kcDir, 'enterprise');
-    if (existsSync(entDst)) rmSync(entDst, { recursive: true, force: true });
-    copyDirContents(join(srcKc, 'enterprise'), entDst);
-    if (opts.verbose) log.info('Updated: enterprise/');
-  }
-
-  // Update Claude Code components if present
-  const claudeDir = join(dir, '.claude');
-  if (existsSync(join(claudeDir, 'commands')) || existsSync(join(claudeDir, 'agents'))) {
-    log.info('Updating Claude Code components...');
-    // Remove stale files before copying
-    removeStaleFiles(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
-    removeStaleFiles(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
-    removeStaleFiles(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
-    copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
-    copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
-    copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
-    // Ensure marketplace config is up to date
-    setMarketplaceConfig(claudeDir);
-  }
-
-  // Regenerate adapters for detected platforms
-  const detected = detectPlatforms(dir);
-  const templates = parseAdapterTemplates();
-  const regenerated = [];
-
-  for (const platformId of detected) {
-    if (platformId === 'claude') continue; // Already handled above
-    const platform = PLATFORMS[platformId];
-    if (!platform.adapterPath) continue;
-
-    const adapterFile = platform.adapterPath(dir);
-    if (!existsSync(adapterFile)) continue; // Only update existing adapters
-
-    const templateSet = templates.get(platformId);
-    if (!templateSet) continue;
-
-    // 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 });
-          }
-        }
-      }
-    } else if (platformId === 'codex') {
-      const skillDir = join(dir, '.codex', 'skills', 'kc');
-      if (existsSync(skillDir)) {
-        for (const f of readdirSync(skillDir)) {
-          if (f.endsWith('.md') && !currentPaths.has(`.codex/skills/kc/${f}`)) {
-            log.info(`Removing stale skill: ${f}`);
-            rmSync(join(skillDir, f), { force: true });
-          }
-        }
-      }
-    }
-  }
-
-  // Check for global codex skills
-  const globalCodexSkillDir = join(process.env.HOME || process.env.USERPROFILE || '~', '.codex', 'skills', 'kc');
-  if (existsSync(globalCodexSkillDir)) {
-    const codexTemplateSet = templates.get('codex');
-    if (codexTemplateSet) {
-      const currentPaths = new Set([...codexTemplateSet.files.keys()]);
-      // Stale cleanup
-      for (const f of readdirSync(globalCodexSkillDir)) {
-        if (f.endsWith('.md') && !currentPaths.has(`.codex/skills/kc/${f}`)) {
-          log.info(`Removing stale global skill: ${f}`);
-          rmSync(join(globalCodexSkillDir, f), { force: true });
-        }
-      }
-      // Regenerate global skills
-      for (const [relativePath, { content }] of codexTemplateSet.files) {
-        if (relativePath.startsWith('.codex/skills/')) {
-          const filePath = join(process.env.HOME || process.env.USERPROFILE || '~', relativePath);
-          ensureDir(dirname(filePath));
-          writeFileSync(filePath, injectVersion(content));
-        }
-      }
-      log.info('Updated global Codex skills');
-    }
-  }
-
-  // Write new version
-  writeFileSync(versionFile, VERSION + '\n');
-
-  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}Updated:${c.reset}   loop, prompts, adapters, enterprise templates`);
-  if (regenerated.length > 0) {
-    console.log(`  ${c.bold}Adapters:${c.reset}  ${regenerated.join(', ')}`);
-  }
-  console.log('');
-}
-
-// HELP
-function cmdHelp() {
-  console.log(`
-${c.bold}KnowzCode CLI${c.reset} v${VERSION}
-Platform-agnostic AI development methodology
-
-${c.bold}Usage:${c.reset}
-  npx knowzcode                          Interactive mode
-  npx knowzcode install [options]        Install to current/target directory
-  npx knowzcode uninstall [options]      Remove KnowzCode
-  npx knowzcode upgrade [options]        Upgrade preserving user data
-  npx knowzcode detect                   Show detected platforms (dry run)
-
-${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 to ~/.claude/, Codex skills to ~/.codex/
-  --agent-teams        Enable Agent Teams in .claude/settings.local.json
-  --verbose            Show detailed output
-  -h, --help           Show this help
-  -v, --version        Show version
-
-${c.bold}Examples:${c.reset}
-  npx knowzcode install --platforms claude,cursor
-  npx knowzcode install --platforms all --force
-  npx knowzcode upgrade --target ./my-project
-  npx knowzcode uninstall --force
-  npx knowzcode detect
-`);
-}
-
-// INTERACTIVE
-async function cmdInteractive(opts) {
-  console.log('');
-  console.log(`${c.bold}  ╔═══════════════════════════════════════╗${c.reset}`);
-  console.log(`${c.bold}  ║          KnowzCode v${VERSION.padEnd(14)}   ║${c.reset}`);
-  console.log(`${c.bold}  ║  AI Development Methodology Installer ║${c.reset}`);
-  console.log(`${c.bold}  ╚═══════════════════════════════════════╝${c.reset}`);
-  console.log('');
-
-  const dir = opts.target;
-  const kcDir = join(dir, 'knowzcode');
-  const detected = detectPlatforms(dir);
-
-  if (detected.length > 0) {
-    log.info('Detected platforms: ' + detected.map((d) => PLATFORMS[d].name).join(', '));
-  }
-
-  if (existsSync(kcDir)) {
-    const versionFile = join(kcDir, '.knowzcode-version');
-    const currentVersion = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : 'unknown';
-
-    if (currentVersion !== VERSION) {
-      log.info(`Installed version: ${currentVersion}, available: ${VERSION}`);
-      const doUpgrade = await promptConfirm('Upgrade to latest version?');
-      if (doUpgrade) {
-        return cmdUpgrade(opts);
-      }
-    } else {
-      log.info(`KnowzCode ${currentVersion} already installed.`);
-      const rl = createInterface({ input: process.stdin, output: process.stdout });
-      console.log('');
-      console.log('  [1] Reinstall (overwrite)');
-      console.log('  [2] Uninstall');
-      console.log('  [3] Detect platforms');
-      console.log('  [4] Exit');
-      console.log('');
-      const answer = await rl.question('Select action: ');
-      rl.close();
-
-      const choice = answer.trim();
-      if (choice === '1') return cmdInstall({ ...opts, force: true });
-      if (choice === '2') return cmdUninstall(opts);
-      if (choice === '3') return cmdDetect(opts);
-      return;
-    }
-  } else {
-    log.info('No existing installation found. Starting install...');
-    console.log('');
-    return cmdInstall(opts);
-  }
-}
-
-// ─── Main ────────────────────────────────────────────────────────────────────
-
-async function main() {
-  const opts = parseArgs(process.argv);
-
-  switch (opts.command) {
-    case 'install':
-      return cmdInstall(opts);
-    case 'uninstall':
-      return cmdUninstall(opts);
-    case 'upgrade':
-      return cmdUpgrade(opts);
-    case 'detect':
-      return cmdDetect(opts);
-    case 'help':
-      return cmdHelp();
-    case 'version':
-      console.log(VERSION);
-      return;
-    default:
-      return cmdInteractive(opts);
-  }
-}
-
-main().catch((err) => {
-  log.err(err.message);
-  process.exit(1);
-});
+#!/usr/bin/env node
+
+// KnowzCode CLI — Zero-dependency Node.js installer
+// Usage: npx knowzcode [install|uninstall|upgrade|detect] [options]
+
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync } from 'fs';
+import { join, resolve, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { createInterface } from 'readline/promises';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = resolve(__dirname, '..');
+const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version;
+
+// ─── Colors ──────────────────────────────────────────────────────────────────
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+const log = {
+  info: (msg) => console.log(`${c.blue}[INFO]${c.reset} ${msg}`),
+  ok: (msg) => console.log(`${c.green}[OK]${c.reset} ${msg}`),
+  warn: (msg) => console.log(`${c.yellow}[WARN]${c.reset} ${msg}`),
+  err: (msg) => console.error(`${c.red}[ERROR]${c.reset} ${msg}`),
+};
+
+// ─── Platform Definitions ────────────────────────────────────────────────────
+
+const PLATFORMS = {
+  claude: {
+    name: 'Claude Code',
+    detect: (dir) => existsSync(join(dir, '.claude')) || existsSync(join(dir, '.claude-plugin')),
+    adapterPath: null, // Claude uses .claude/ dir structure, not a single adapter file
+  },
+  codex: {
+    name: 'OpenAI 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)',
+  },
+  gemini: {
+    name: 'Gemini CLI',
+    detect: (dir) => existsSync(join(dir, 'GEMINI.md')) || existsSync(join(dir, '.gemini')),
+    adapterPath: (dir) => join(dir, 'GEMINI.md'),
+    templateHeader: '## Google Gemini CLI (GEMINI.md)',
+  },
+  cursor: {
+    name: 'Cursor',
+    detect: (dir) => existsSync(join(dir, '.cursor', 'rules')) || existsSync(join(dir, '.cursorrules')),
+    adapterPath: (dir) => join(dir, '.cursor', 'rules', 'knowzcode.mdc'),
+    templateHeader: '## Cursor (`.cursor/rules/knowzcode.mdc`)',
+  },
+  copilot: {
+    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',
+  },
+  windsurf: {
+    name: 'Windsurf',
+    detect: (dir) => existsSync(join(dir, '.windsurf', 'rules')) || existsSync(join(dir, '.windsurfrules')),
+    adapterPath: (dir) => join(dir, '.windsurf', 'rules', 'knowzcode.md'),
+    templateHeader: '## Windsurf (`.windsurf/rules/knowzcode.md`)',
+  },
+};
+
+// ─── CLI Argument Parser ─────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = {
+    command: null,
+    target: process.cwd(),
+    platforms: [],
+    force: false,
+    global: false,
+    verbose: false,
+    agentTeams: false,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === '--target' && i + 1 < args.length) {
+      opts.target = resolve(args[++i]);
+    } else if (arg === '--platforms' && i + 1 < args.length) {
+      opts.platforms = args[++i].split(',').map((p) => p.trim().toLowerCase());
+    } else if (arg === '--force') {
+      opts.force = true;
+    } else if (arg === '--global') {
+      opts.global = true;
+    } else if (arg === '--agent-teams') {
+      opts.agentTeams = true;
+    } else if (arg === '--verbose') {
+      opts.verbose = true;
+    } else if (arg === '--help' || arg === '-h') {
+      opts.command = 'help';
+    } else if (arg === '--version' || arg === '-v') {
+      opts.command = 'version';
+    } else if (!arg.startsWith('-') && !opts.command) {
+      opts.command = arg.toLowerCase();
+    }
+    i++;
+  }
+
+  return opts;
+}
+
+// ─── Platform Detection ──────────────────────────────────────────────────────
+
+function detectPlatforms(dir) {
+  const detected = [];
+  for (const [id, platform] of Object.entries(PLATFORMS)) {
+    if (platform.detect(dir)) {
+      detected.push(id);
+    }
+  }
+  return detected;
+}
+
+// ─── 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');
+  if (!existsSync(adaptersPath)) {
+    log.warn('platform_adapters.md not found — adapter generation will be skipped');
+    return new Map();
+  }
+
+  const content = readFileSync(adaptersPath, 'utf8');
+  const templates = new Map();
+
+  for (const [id, platform] of Object.entries(PLATFORMS)) {
+    if (!platform.templateHeader) continue;
+
+    const headerIdx = content.indexOf(platform.templateHeader);
+    if (headerIdx === -1) continue;
+
+    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;
+}
+
+// ─── File Copy Helpers ───────────────────────────────────────────────────────
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function copyDirContents(src, dst) {
+  ensureDir(dst);
+  if (!existsSync(src)) return;
+
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const dstPath = join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDirContents(srcPath, dstPath);
+    } else {
+      writeFileSync(dstPath, readFileSync(srcPath));
+    }
+  }
+}
+
+function listFilesRecursive(dir, base = dir) {
+  const files = [];
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listFilesRecursive(full, base));
+    } else {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+// ─── Marketplace Config ──────────────────────────────────────────────────────
+
+function setMarketplaceConfig(claudeDir) {
+  ensureDir(claudeDir);
+  const settingsFile = join(claudeDir, 'settings.json');
+  let settings = {};
+
+  if (existsSync(settingsFile)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.extraKnownMarketplaces) settings.extraKnownMarketplaces = {};
+  settings.extraKnownMarketplaces.knowzcode = {
+    source: { source: 'github', repo: 'knowz-io/knowzcode' },
+  };
+
+  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+}
+
+function removeMarketplaceConfig(claudeDir) {
+  const settingsFile = join(claudeDir, 'settings.json');
+  if (!existsSync(settingsFile)) return;
+
+  try {
+    const settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+    if (settings.extraKnownMarketplaces && settings.extraKnownMarketplaces.knowzcode) {
+      delete settings.extraKnownMarketplaces.knowzcode;
+      writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+    }
+  } catch {
+    // Ignore parse errors
+  }
+}
+
+// ─── 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) {
+  if (!existsSync(targetDir) || !existsSync(sourceDir)) return;
+
+  const sourceFiles = new Set(
+    readdirSync(sourceDir)
+      .filter((f) => f.endsWith('.md'))
+  );
+
+  for (const entry of readdirSync(targetDir)) {
+    if (entry.endsWith('.md') && !sourceFiles.has(entry)) {
+      const stale = join(targetDir, entry);
+      if (existsSync(stale) && statSync(stale).isFile()) {
+        log.info(`Removing stale file: ${stale}`);
+        rmSync(stale, { force: true });
+      }
+    }
+  }
+}
+
+// ─── Tracker & Log Initializers ──────────────────────────────────────────────
+
+function initTracker(filePath) {
+  writeFileSync(filePath, `# KnowzCode - Status Map
+
+**Purpose:** This document tracks the development status of all implementable components (NodeIDs) defined in \`knowzcode_architecture.md\`.
+
+---
+**Progress: 0%**
+---
+
+| Status | WorkGroupID | Node ID | Label | Dependencies | Logical Grouping | Spec Link | Classification | Notes / Issues |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| | | | | | | | | |
+
+---
+### Status Legend:
+
+*   ⚪️ **\`[TODO]\`**: Task is defined and ready to be picked up if dependencies are met.
+*   📝 **\`[NEEDS_SPEC]\`**: Node has been identified but requires a detailed specification.
+*   ◆ **\`[WIP]\`**: Work In Progress. The KnowzCode AI Agent is currently working on this node.
+*   🟢 **\`[VERIFIED]\`**: Node has been implemented and verified.
+*   ❗ **\`[ISSUE]\`**: A significant issue or blocker has been identified.
+
+---
+*(This table will be populated as you define your architecture and NodeIDs.)*
+`);
+}
+
+function initLog(filePath) {
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  writeFileSync(filePath, `# KnowzCode - Operational Record
+
+**Purpose:** Chronological record of significant events, decisions, and verification outcomes.
+
+---
+
+## Section 1: Operational Log
+
+---
+**[NEWEST ENTRIES APPEAR HERE - DO NOT REMOVE THIS MARKER]**
+---
+**Type:** SystemInitialization
+**Timestamp:** ${ts}
+**NodeID(s):** Project-Wide
+**Logged By:** knowzcode-cli
+**Details:**
+KnowzCode framework installed via \`npx knowzcode\`.
+- Framework files initialized
+- Ready for first feature
+---
+
+## Section 2: Reference Quality Criteria (ARC-Based Verification)
+
+### Core Quality Criteria
+1.  **Maintainability:** Ease of modification, clarity of code and design.
+2.  **Reliability:** Robustness of error handling, fault tolerance.
+3.  **Testability:** Adequacy of unit test coverage, ease of testing.
+4.  **Performance:** Responsiveness, efficiency in resource utilization.
+5.  **Security:** Resistance to common vulnerabilities.
+
+### Structural Criteria
+6.  **Readability:** Code clarity, adherence to naming conventions.
+7.  **Complexity Management:** Avoidance of overly complex logic.
+8.  **Modularity:** Adherence to Single Responsibility Principle.
+9.  **Code Duplication (DRY):** Minimization of redundant code.
+10. **Standards Compliance:** Adherence to language best practices.
+
+*(Refer to these criteria during ARC-Based Verification.)*
+`);
+}
+
+// ─── Interactive Prompt ──────────────────────────────────────────────────────
+
+async function promptPlatforms(detected) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ids = Object.keys(PLATFORMS);
+
+  console.log('');
+  console.log(`${c.bold}Select platforms to generate adapters for:${c.reset}`);
+  console.log('');
+  ids.forEach((id, i) => {
+    const p = PLATFORMS[id];
+    const tag = detected.includes(id) ? ` ${c.green}(detected)${c.reset}` : '';
+    console.log(`  [${i + 1}] ${p.name}${tag}`);
+  });
+  console.log(`  [A] All platforms`);
+  console.log(`  [S] Skip adapters (core framework only)`);
+  console.log('');
+
+  const answer = await rl.question('Select platforms (comma-separated, e.g. 1,2): ');
+  rl.close();
+
+  const trimmed = answer.trim().toUpperCase();
+  if (trimmed === 'S' || trimmed === '') return [];
+  if (trimmed === 'A') return ids;
+
+  const selected = [];
+  for (const part of trimmed.split(',')) {
+    const num = parseInt(part.trim(), 10);
+    if (num >= 1 && num <= ids.length) {
+      selected.push(ids[num - 1]);
+    }
+  }
+  return [...new Set(selected)];
+}
+
+async function promptConfirm(message) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(`${message} [y/N]: `);
+  rl.close();
+  return answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes';
+}
+
+// ─── Agent Teams Enablement ──────────────────────────────────────────────────
+
+function enableAgentTeams(claudeDir, isGlobal) {
+  ensureDir(claudeDir);
+  const settingsFile = join(claudeDir, isGlobal ? 'settings.json' : 'settings.local.json');
+
+  let settings = {};
+  if (existsSync(settingsFile)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.env) settings.env = {};
+  settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+
+  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+  log.ok(`Agent Teams enabled in ${settingsFile}`);
+}
+
+// ─── Commands ────────────────────────────────────────────────────────────────
+
+// DETECT
+function cmdDetect(opts) {
+  const dir = opts.target;
+  console.log('');
+  console.log(`${c.bold}KnowzCode Platform Detection${c.reset}`);
+  console.log(`${c.dim}Scanning: ${dir}${c.reset}`);
+  console.log('');
+
+  const detected = detectPlatforms(dir);
+  const hasKnowzcode = existsSync(join(dir, 'knowzcode'));
+
+  console.log(`  KnowzCode framework: ${hasKnowzcode ? `${c.green}installed${c.reset}` : `${c.dim}not found${c.reset}`}`);
+
+  if (hasKnowzcode) {
+    const versionFile = join(dir, 'knowzcode', '.knowzcode-version');
+    if (existsSync(versionFile)) {
+      const ver = readFileSync(versionFile, 'utf8').trim();
+      console.log(`  Installed version:   ${c.cyan}${ver}${c.reset}`);
+    }
+  }
+
+  console.log('');
+  console.log(`  ${c.bold}Platforms:${c.reset}`);
+
+  for (const [id, platform] of Object.entries(PLATFORMS)) {
+    const found = detected.includes(id);
+    const indicator = found ? `${c.green}detected${c.reset}` : `${c.dim}not detected${c.reset}`;
+    console.log(`    ${platform.name.padEnd(18)} ${indicator}`);
+  }
+
+  console.log('');
+  if (detected.length === 0) {
+    console.log(`  No platforms detected. Run ${c.cyan}npx knowzcode install${c.reset} to set up.`);
+  } else {
+    console.log(`  ${detected.length} platform(s) detected.`);
+  }
+  console.log('');
+}
+
+// INSTALL
+async function cmdInstall(opts) {
+  const dir = opts.target;
+  const kcDir = join(dir, 'knowzcode');
+
+  console.log('');
+  console.log(`${c.bold}KnowzCode Install${c.reset}`);
+  console.log(`${c.dim}Target: ${dir}${c.reset}`);
+  console.log('');
+
+  // Check for existing installation
+  if (existsSync(kcDir) && !opts.force) {
+    log.warn('KnowzCode already installed at ' + kcDir);
+    log.warn('Use --force to overwrite.');
+    process.exit(1);
+  }
+
+  if (!existsSync(dir)) {
+    log.err('Target directory does not exist: ' + dir);
+    process.exit(1);
+  }
+
+  // 1. Copy knowzcode/ template directory
+  log.info('Installing core framework...');
+  const srcKc = join(PKG_ROOT, 'knowzcode');
+  ensureDir(kcDir);
+  ensureDir(join(kcDir, 'specs'));
+  ensureDir(join(kcDir, 'workgroups'));
+  ensureDir(join(kcDir, 'prompts'));
+
+  // Create workgroups/README.md (workgroups/ is gitignored and excluded from npm)
+  writeFileSync(join(kcDir, 'workgroups', 'README.md'), '# WorkGroups\n\nSession-specific WorkGroup files are stored here.\nThis directory is gitignored — contents are local to each checkout.\n');
+
+  // Copy .md files (skip tracker and log — generate fresh)
+  for (const entry of readdirSync(srcKc)) {
+    const srcPath = join(srcKc, entry);
+    const stat = statSync(srcPath);
+    if (stat.isFile() && entry.endsWith('.md') && entry !== 'knowzcode_tracker.md' && entry !== 'knowzcode_log.md') {
+      writeFileSync(join(kcDir, entry), readFileSync(srcPath));
+    } else if (stat.isFile() && !entry.endsWith('.md')) {
+      // Copy non-md files, handling gitignore.template → .gitignore rename
+      if (entry === 'gitignore.template') {
+        writeFileSync(join(kcDir, '.gitignore'), readFileSync(srcPath));
+      } else {
+        writeFileSync(join(kcDir, entry), readFileSync(srcPath));
+      }
+    }
+  }
+
+  // Copy prompts/
+  if (existsSync(join(srcKc, 'prompts'))) {
+    copyDirContents(join(srcKc, 'prompts'), join(kcDir, 'prompts'));
+  }
+
+  // Copy specs readme
+  if (existsSync(join(srcKc, 'specs', 'Readme.md'))) {
+    writeFileSync(join(kcDir, 'specs', 'Readme.md'), readFileSync(join(srcKc, 'specs', 'Readme.md')));
+  }
+
+  // Copy enterprise/ if exists
+  if (existsSync(join(srcKc, 'enterprise'))) {
+    copyDirContents(join(srcKc, 'enterprise'), join(kcDir, 'enterprise'));
+  }
+
+  // Initialize fresh tracker and log
+  initTracker(join(kcDir, 'knowzcode_tracker.md'));
+  initLog(join(kcDir, 'knowzcode_log.md'));
+
+  // Write version marker
+  writeFileSync(join(kcDir, '.knowzcode-version'), VERSION + '\n');
+
+  log.ok('Core framework installed');
+
+  // 2. Platform detection + selection
+  const detected = detectPlatforms(dir);
+  let selectedPlatforms;
+
+  if (opts.platforms.length > 0) {
+    if (opts.platforms.includes('all')) {
+      selectedPlatforms = Object.keys(PLATFORMS);
+    } else {
+      selectedPlatforms = opts.platforms.filter((p) => p in PLATFORMS);
+    }
+  } else if (opts.force) {
+    // Non-interactive mode with --force: install for detected platforms only
+    selectedPlatforms = detected;
+  } else {
+    selectedPlatforms = await promptPlatforms(detected);
+  }
+
+  // 3. Generate adapters
+  const templates = parseAdapterTemplates();
+  const adapterFiles = [];
+
+  for (const platformId of selectedPlatforms) {
+    const platform = PLATFORMS[platformId];
+
+    if (platformId === 'claude') {
+      // Claude Code: copy agents, commands, skills
+      const claudeDir = opts.global ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude') : join(dir, '.claude');
+
+      log.info(`Installing Claude Code components to ${claudeDir}/`);
+
+      // Remove stale files before copying on --force
+      if (opts.force) {
+        removeStaleFiles(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+        removeStaleFiles(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+        removeStaleFiles(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+      }
+
+      copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+      copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+      copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+
+      // Pre-register marketplace in settings.json
+      setMarketplaceConfig(claudeDir);
+
+      adapterFiles.push(claudeDir + '/commands/', claudeDir + '/agents/', claudeDir + '/skills/');
+    } else {
+      // 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, 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.');
+      }
+    }
+  }
+
+  // 4. Agent Teams enablement
+  const agentTeamsClaudeDir = opts.global
+    ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude')
+    : join(dir, '.claude');
+  let agentTeamsEnabled = false;
+  if (opts.agentTeams) {
+    enableAgentTeams(agentTeamsClaudeDir, opts.global);
+    agentTeamsEnabled = true;
+  } else if (selectedPlatforms.includes('claude') && !opts.force) {
+    // Interactive prompt for Claude Code users
+    console.log('');
+    console.log(`${c.bold}Agent Teams${c.reset} enables multi-agent coordination where specialized`);
+    console.log(`teammates handle each workflow phase. ${c.dim}(experimental)${c.reset}`);
+    const wantTeams = await promptConfirm('Enable Agent Teams? (recommended for Claude Code)');
+    if (wantTeams) {
+      enableAgentTeams(agentTeamsClaudeDir, opts.global);
+      agentTeamsEnabled = true;
+    }
+  }
+
+  // 5. Summary
+  console.log('');
+  console.log(`${c.green}${c.bold}Installation complete!${c.reset}`);
+  console.log('');
+  console.log('  Framework:  ' + kcDir + '/');
+  if (adapterFiles.length > 0) {
+    console.log('  Adapters:');
+    for (const f of adapterFiles) {
+      console.log('    ' + f);
+    }
+  }
+  if (agentTeamsEnabled) {
+    console.log('  Agent Teams: enabled');
+  }
+  console.log('');
+  console.log(`${c.bold}Next steps:${c.reset}`);
+  console.log('  1. Edit knowzcode/knowzcode_project.md — set project name, stack, standards');
+  console.log('  2. Edit knowzcode/environment_context.md — configure build/test commands');
+  if (selectedPlatforms.includes('claude')) {
+    console.log('  3. Install the KnowzCode plugin (recommended):');
+    console.log('     /plugin install kc@knowzcode');
+    console.log('  4. Start building:');
+    console.log('     /kc:work "Your first feature"');
+    console.log('');
+    console.log('  Note: Commands also work without plugin as /work, /plan, /fix, etc.');
+  } else {
+    console.log('  3. Start building: use knowzcode/prompts/[LOOP_1A]__Propose_Change_Set.md');
+  }
+  console.log('');
+}
+
+// UNINSTALL
+async function cmdUninstall(opts) {
+  const dir = opts.target;
+  const kcDir = join(dir, 'knowzcode');
+
+  console.log('');
+  console.log(`${c.bold}KnowzCode Uninstall${c.reset}`);
+  console.log(`${c.dim}Target: ${dir}${c.reset}`);
+  console.log('');
+
+  // Scan for installed components
+  const components = [];
+
+  if (existsSync(kcDir)) {
+    components.push({ label: 'Core framework', path: kcDir });
+  }
+
+  // Claude Code components
+  const claudeDir = join(dir, '.claude');
+  for (const sub of ['commands', 'agents', 'skills']) {
+    const p = join(claudeDir, sub);
+    if (existsSync(p)) {
+      components.push({ label: `Claude Code ${sub}`, path: p });
+    }
+  }
+
+  // Platform adapter files
+  const adapterChecks = {
+    codex: join(dir, 'AGENTS.md'),
+    gemini: join(dir, 'GEMINI.md'),
+    cursor: join(dir, '.cursor', 'rules', 'knowzcode.mdc'),
+    copilot: join(dir, '.github', 'copilot-instructions.md'),
+    windsurf: join(dir, '.windsurf', 'rules', 'knowzcode.md'),
+  };
+
+  for (const [id, path] of Object.entries(adapterChecks)) {
+    if (existsSync(path)) {
+      components.push({ label: `${PLATFORMS[id].name} adapter`, path });
+    }
+  }
+
+  // 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;
+  }
+
+  console.log('  Components found:');
+  for (const comp of components) {
+    console.log(`    ${comp.label}: ${comp.path}`);
+  }
+  console.log('');
+
+  // Ask about preserving user data
+  let preserveUserData = false;
+  if (existsSync(kcDir) && !opts.force) {
+    preserveUserData = await promptConfirm('Preserve user data (specs/, architecture, tracker, log)?');
+  }
+
+  if (!opts.force) {
+    const confirmed = await promptConfirm('Remove all listed components?');
+    if (!confirmed) {
+      log.info('Uninstall cancelled.');
+      return;
+    }
+  }
+
+  const removed = [];
+
+  // Remove components
+  for (const comp of components) {
+    if (comp.path === kcDir && preserveUserData) {
+      // Selective removal — keep user data
+      const preserve = ['specs', 'knowzcode_architecture.md', 'knowzcode_tracker.md', 'knowzcode_log.md', 'knowzcode_project.md'];
+
+      for (const entry of readdirSync(kcDir)) {
+        if (preserve.includes(entry)) continue;
+        const entryPath = join(kcDir, entry);
+        rmSync(entryPath, { recursive: true, force: true });
+      }
+      removed.push(comp.label + ' (user data preserved)');
+    } else {
+      rmSync(comp.path, { recursive: true, force: true });
+      removed.push(comp.label);
+    }
+  }
+
+  // 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:');
+  for (const r of removed) {
+    console.log(`    ${r}`);
+  }
+  console.log('');
+}
+
+// UPGRADE
+async function cmdUpgrade(opts) {
+  const dir = opts.target;
+  const kcDir = join(dir, 'knowzcode');
+
+  console.log('');
+  console.log(`${c.bold}KnowzCode Upgrade${c.reset}`);
+  console.log(`${c.dim}Target: ${dir}${c.reset}`);
+  console.log('');
+
+  if (!existsSync(kcDir)) {
+    log.err('No KnowzCode installation found. Run `npx knowzcode install` first.');
+    process.exit(1);
+  }
+
+  // Read current version
+  const versionFile = join(kcDir, '.knowzcode-version');
+  const currentVersion = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : 'unknown';
+
+  if (currentVersion === VERSION && !opts.force) {
+    log.info(`Already at version ${VERSION}. Use --force to reinstall.`);
+    return;
+  }
+
+  log.info(`Upgrading: ${currentVersion} → ${VERSION}`);
+
+  // Files to preserve (never overwrite)
+  const preserveFiles = new Set([
+    'knowzcode_tracker.md',
+    'knowzcode_log.md',
+    'knowzcode_architecture.md',
+    'knowzcode_project.md',
+    'environment_context.md',
+    'user_preferences.md',
+  ]);
+  const preserveDirs = new Set(['specs', 'workgroups']);
+
+  // Files to replace (always update)
+  const srcKc = join(PKG_ROOT, 'knowzcode');
+
+  // Update .md files
+  for (const entry of readdirSync(srcKc)) {
+    const srcPath = join(srcKc, entry);
+    const dstPath = join(kcDir, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isFile()) {
+      if (preserveFiles.has(entry)) {
+        if (opts.verbose) log.info(`Preserved: ${entry}`);
+        continue;
+      }
+      // Handle gitignore.template → .gitignore rename
+      if (entry === 'gitignore.template') {
+        writeFileSync(join(kcDir, '.gitignore'), readFileSync(srcPath));
+        if (opts.verbose) log.info('Updated: .gitignore (from gitignore.template)');
+      } else {
+        writeFileSync(dstPath, readFileSync(srcPath));
+        if (opts.verbose) log.info(`Updated: ${entry}`);
+      }
+    }
+  }
+
+  // Update prompts/ (always replace)
+  if (existsSync(join(srcKc, 'prompts'))) {
+    const promptsDst = join(kcDir, 'prompts');
+    // Remove old prompts, copy new ones
+    if (existsSync(promptsDst)) rmSync(promptsDst, { recursive: true, force: true });
+    copyDirContents(join(srcKc, 'prompts'), promptsDst);
+    if (opts.verbose) log.info('Updated: prompts/');
+  }
+
+  // Update enterprise/ (always replace)
+  if (existsSync(join(srcKc, 'enterprise'))) {
+    const entDst = join(kcDir, 'enterprise');
+    if (existsSync(entDst)) rmSync(entDst, { recursive: true, force: true });
+    copyDirContents(join(srcKc, 'enterprise'), entDst);
+    if (opts.verbose) log.info('Updated: enterprise/');
+  }
+
+  // Update Claude Code components if present
+  const claudeDir = join(dir, '.claude');
+  if (existsSync(join(claudeDir, 'commands')) || existsSync(join(claudeDir, 'agents'))) {
+    log.info('Updating Claude Code components...');
+    // Remove stale files before copying
+    removeStaleFiles(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+    removeStaleFiles(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+    removeStaleFiles(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+    copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+    copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+    copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+    // Ensure marketplace config is up to date
+    setMarketplaceConfig(claudeDir);
+  }
+
+  // Regenerate adapters for detected platforms
+  const detected = detectPlatforms(dir);
+  const templates = parseAdapterTemplates();
+  const regenerated = [];
+
+  for (const platformId of detected) {
+    if (platformId === 'claude') continue; // Already handled above
+    const platform = PLATFORMS[platformId];
+    if (!platform.adapterPath) continue;
+
+    const adapterFile = platform.adapterPath(dir);
+    if (!existsSync(adapterFile)) continue; // Only update existing adapters
+
+    const templateSet = templates.get(platformId);
+    if (!templateSet) continue;
+
+    // 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
+  writeFileSync(versionFile, VERSION + '\n');
+
+  console.log('');
+  log.ok(`Upgraded to ${VERSION}`);
+  console.log('');
+  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(', ')}`);
+  }
+  console.log('');
+}
+
+// HELP
+function cmdHelp() {
+  console.log(`
+${c.bold}KnowzCode CLI${c.reset} v${VERSION}
+Platform-agnostic AI development methodology
+
+${c.bold}Usage:${c.reset}
+  npx knowzcode                          Interactive mode
+  npx knowzcode install [options]        Install to current/target directory
+  npx knowzcode uninstall [options]      Remove KnowzCode
+  npx knowzcode upgrade [options]        Upgrade preserving user data
+  npx knowzcode detect                   Show detected platforms (dry run)
+
+${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 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
+  -v, --version        Show version
+
+${c.bold}Examples:${c.reset}
+  npx knowzcode install --platforms claude,cursor
+  npx knowzcode install --platforms all --force
+  npx knowzcode upgrade --target ./my-project
+  npx knowzcode uninstall --force
+  npx knowzcode detect
+`);
+}
+
+// INTERACTIVE
+async function cmdInteractive(opts) {
+  console.log('');
+  console.log(`${c.bold}  ╔═══════════════════════════════════════╗${c.reset}`);
+  console.log(`${c.bold}  ║          KnowzCode v${VERSION.padEnd(14)}   ║${c.reset}`);
+  console.log(`${c.bold}  ║  AI Development Methodology Installer ║${c.reset}`);
+  console.log(`${c.bold}  ╚═══════════════════════════════════════╝${c.reset}`);
+  console.log('');
+
+  const dir = opts.target;
+  const kcDir = join(dir, 'knowzcode');
+  const detected = detectPlatforms(dir);
+
+  if (detected.length > 0) {
+    log.info('Detected platforms: ' + detected.map((d) => PLATFORMS[d].name).join(', '));
+  }
+
+  if (existsSync(kcDir)) {
+    const versionFile = join(kcDir, '.knowzcode-version');
+    const currentVersion = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : 'unknown';
+
+    if (currentVersion !== VERSION) {
+      log.info(`Installed version: ${currentVersion}, available: ${VERSION}`);
+      const doUpgrade = await promptConfirm('Upgrade to latest version?');
+      if (doUpgrade) {
+        return cmdUpgrade(opts);
+      }
+    } else {
+      log.info(`KnowzCode ${currentVersion} already installed.`);
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      console.log('');
+      console.log('  [1] Reinstall (overwrite)');
+      console.log('  [2] Uninstall');
+      console.log('  [3] Detect platforms');
+      console.log('  [4] Exit');
+      console.log('');
+      const answer = await rl.question('Select action: ');
+      rl.close();
+
+      const choice = answer.trim();
+      if (choice === '1') return cmdInstall({ ...opts, force: true });
+      if (choice === '2') return cmdUninstall(opts);
+      if (choice === '3') return cmdDetect(opts);
+      return;
+    }
+  } else {
+    log.info('No existing installation found. Starting install...');
+    console.log('');
+    return cmdInstall(opts);
+  }
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  switch (opts.command) {
+    case 'install':
+      return cmdInstall(opts);
+    case 'uninstall':
+      return cmdUninstall(opts);
+    case 'upgrade':
+      return cmdUpgrade(opts);
+    case 'detect':
+      return cmdDetect(opts);
+    case 'help':
+      return cmdHelp();
+    case 'version':
+      console.log(VERSION);
+      return;
+    default:
+      return cmdInteractive(opts);
+  }
+}
+
+main().catch((err) => {
+  log.err(err.message);
+  process.exit(1);
+});