knowzcode 0.1.0

package/bin/knowzcode.mjs

@@ -0,0 +1,869 @@
+#!/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 (.github/copilot-instructions.md)',
+  },
+  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 ─────────────────────────────────────────────────
+
+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;
+
+    // Find the code fence after this header
+    const afterHeader = content.slice(headerIdx);
+    const fenceStart = afterHeader.indexOf('```markdown');
+    if (fenceStart === -1) continue;
+
+    const contentStart = afterHeader.indexOf('\n', fenceStart) + 1;
+    const fenceEnd = afterHeader.indexOf('\n```', contentStart);
+    if (fenceEnd === -1) continue;
+
+    templates.set(id, afterHeader.slice(contentStart, fenceEnd));
+  }
+
+  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;
+}
+
+// ─── 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(dir) {
+  const claudeDir = join(dir, '.claude');
+  ensureDir(claudeDir);
+  const settingsFile = join(claudeDir, '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 .claude/settings.local.json');
+}
+
+// ─── 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}/`);
+      copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+      copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+      copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+      adapterFiles.push(claudeDir + '/commands/', claudeDir + '/agents/', claudeDir + '/skills/');
+    } else {
+      // Other platforms: extract template and write adapter file
+      const template = templates.get(platformId);
+      if (!template) {
+        log.warn(`No adapter template found for ${platform.name} — skipping`);
+        continue;
+      }
+
+      const adapterFile = platform.adapterPath(dir);
+      ensureDir(dirname(adapterFile));
+      writeFileSync(adapterFile, template);
+      adapterFiles.push(adapterFile);
+      log.ok(`${platform.name} adapter: ${adapterFile}`);
+    }
+  }
+
+  // 4. Agent Teams enablement
+  let agentTeamsEnabled = false;
+  if (opts.agentTeams) {
+    enableAgentTeams(dir);
+    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(dir);
+      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. Start building: /kc:work "Your first feature"');
+  } 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 });
+    }
+  }
+
+  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);
+    }
+  }
+
+  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...');
+    copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+    copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+    copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+  }
+
+  // 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 template = templates.get(platformId);
+    if (!template) continue;
+
+    writeFileSync(adapterFile, template);
+    regenerated.push(platform.name);
+  }
+
+  // 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 components to ~/.claude/
+  --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);
+});