multimodel-dev-os 1.1.0 → 2.0.0

package/bin/multimodel-dev-os.js

@@ -13,7 +13,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const sourceRoot = resolve(__dirname, '..');
 
-let version = '0.5.1';
+let version = '2.0.0';
 try {
   const pkgData = JSON.parse(readFileSync(resolve(sourceRoot, 'package.json'), 'utf8'));
   version = pkgData.version;
@@ -31,7 +31,18 @@ function parseArgs(args) {
     caveman: false,
     dryRun: false,
     force: false,
-    help: false
+    help: false,
+    tokens: false,
+    modelPreset: null,
+    agent: null,
+    stack: null,
+    mobile: null,
+    aiApp: null,
+    json: false,
+    threshold: null,
+    registry: null,
+    allRegistries: false,
+    release: false
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -50,6 +61,28 @@ function parseArgs(args) {
       params.force = true;
     } else if (arg === '--help' || arg === '-h') {
       params.help = true;
+    } else if (arg === '--tokens') {
+      params.tokens = true;
+    } else if (arg === '--all-registries') {
+      params.allRegistries = true;
+    } else if (arg === '--release') {
+      params.release = true;
+    } else if (arg === '--json') {
+      params.json = true;
+    } else if (arg === '--threshold') {
+      params.threshold = args[++i];
+    } else if (arg === '--registry') {
+      params.registry = args[++i];
+    } else if (arg === '--model-preset') {
+      params.modelPreset = args[++i];
+    } else if (arg === '--agent') {
+      params.agent = args[++i];
+    } else if (arg === '--stack') {
+      params.stack = args[++i];
+    } else if (arg === '--mobile') {
+      params.mobile = args[++i];
+    } else if (arg === '--ai-app') {
+      params.aiApp = args[++i];
     } else if (!params.command && !arg.startsWith('-')) {
       params.command = arg;
     }
@@ -60,43 +93,41 @@ function parseArgs(args) {
 const params = parseArgs(ARGS);
 const COMMAND = params.command;
 
-const TEMPLATES = {
-  'nextjs-saas': {
-    name: 'nextjs-saas',
-    description: 'Next.js App Router starter with TypeScript, Prisma database, Tailwind CSS, and Stripe subscription setup.',
-    stack: 'Next.js 14, React 18, TypeScript, Tailwind CSS, Prisma ORM, Stripe payments',
-    skill: 'nextjs-action-build.md',
-    skillDesc: 'React Server Actions secure implementation conventions.'
-  },
-  'wordpress-site': {
-    name: 'wordpress-site',
-    description: 'WordPress custom block theme and plugin development profile with secure PHP database query rules.',
-    stack: 'WordPress Core, PHP, Gutenberg Block APIs, theme customization hooks',
-    skill: 'plugin-boilerplate.md',
-    skillDesc: 'PHP hook registrations and sanitization gates boilerplate.'
-  },
-  'ecommerce-store': {
-    name: 'ecommerce-store',
-    description: 'PCI-compliant headless e-commerce store with secure checkout loops, card state validations, and Stripe webhooks.',
-    stack: 'Headless Store API, cart states, secure payment webhooks, order database triggers',
-    skill: 'webhook-handler.md',
-    skillDesc: 'Stripe order checkout webhook secure listener verification rules.'
-  },
-  'seo-landing-page': {
-    name: 'seo-landing-page',
-    description: 'Ultra-fast static landing page layout optimized for Astro, high Core Web Vitals scores, and JSON-LD schema markup.',
-    stack: 'Astro, HTML5, structured JSON-LD SEO markup, asset minification frameworks',
-    skill: 'seo-audit.md',
-    skillDesc: 'Lighthouse audits optimization guidelines and Core Web Vitals targets.'
-  },
-  'general-app': {
-    name: 'general-app',
-    description: 'Baseline generic fallback profile for standard backend systems (Python, Go, Node, Rust) and universal git workflows.',
-    stack: 'Universal backends baseline structure, default git flow parameters',
-    skill: 'example-skill.md',
-    skillDesc: 'Generic baseline instructions and coding standards.'
-  }
-};
+function loadTemplates(customPath) {
+  let path = customPath || join(sourceRoot, '.ai', 'templates', 'registry.yaml');
+  try {
+    if (existsSync(path)) {
+      const templatesRegistry = parseYaml(readFileSync(path, 'utf8'));
+      return templatesRegistry.templates || {};
+    }
+  } catch (e) {}
+  return {
+    'general-app': {
+      name: 'general-app',
+      description: 'Baseline generic fallback profile for standard backend systems.',
+      stack: 'Universal backends baseline structure',
+      skill: 'example-skill.md',
+      skillDesc: 'Generic baseline instructions and coding standards.',
+      status: 'stable',
+      maturity: 'production-ready',
+      required_files: ['AGENTS.md', 'MEMORY.md', 'TASKS.md', 'RUNBOOK.md', '.ai/config.yaml']
+    }
+  };
+}
+
+function loadAdapters(customPath) {
+  let path = customPath || join(sourceRoot, '.ai', 'adapters', 'registry.yaml');
+  try {
+    if (existsSync(path)) {
+      const adaptersRegistry = parseYaml(readFileSync(path, 'utf8'));
+      return adaptersRegistry.adapters || {};
+    }
+  } catch (e) {}
+  return {};
+}
+
+const TEMPLATES = loadTemplates(params.registry);
+const ADAPTERS = loadAdapters(params.registry);
 
 if (params.help || !COMMAND) {
   showHelp();
@@ -104,11 +135,16 @@ if (params.help || !COMMAND) {
 }
 
 if (COMMAND === 'init') {
+  if (params.mobile === 'android') {
+    params.template = 'expo-react-native-android';
+  } else if (params.aiApp === 'rag') {
+    params.template = 'rag-knowledge-base';
+  }
   handleInit(params);
 } else if (COMMAND === 'verify') {
   handleVerify(params);
 } else if (COMMAND === 'templates' || COMMAND === 'list-templates') {
-  handleListTemplates();
+  handleListTemplates(params);
 } else if (COMMAND === 'show-template') {
   const tName = ARGS[1];
   if (!tName || tName.startsWith('-')) {
@@ -120,6 +156,63 @@ if (COMMAND === 'init') {
   handleDoctor(params);
 } else if (COMMAND === 'validate') {
   handleValidate(params);
+} else if (COMMAND === 'validate-template') {
+  const tName = ARGS[1];
+  if (!tName || tName.startsWith('-')) {
+    console.error('\x1b[31mError: Please specify a template name. Example: node bin/multimodel-dev-os.js validate-template nextjs-saas\x1b[0m');
+    process.exit(1);
+  }
+  handleValidateTemplate(tName);
+} else if (COMMAND === 'validate-adapter') {
+  const aName = ARGS[1];
+  if (!aName || aName.startsWith('-')) {
+    console.error('\x1b[31mError: Please specify an adapter name. Example: node bin/multimodel-dev-os.js validate-adapter cursor\x1b[0m');
+    process.exit(1);
+  }
+  handleValidateAdapter(aName);
+} else if (COMMAND === 'validate-skill') {
+  const sName = ARGS[1];
+  if (!sName || sName.startsWith('-')) {
+    console.error('\x1b[31mError: Please specify a skill name. Example: node bin/multimodel-dev-os.js validate-skill custom-skill.example\x1b[0m');
+    process.exit(1);
+  }
+  handleValidateSkill(sName, params);
+} else if (COMMAND === 'models') {
+  handleListModels(params);
+} else if (COMMAND === 'show-model') {
+  const mName = ARGS[1];
+  if (!mName || mName.startsWith('-')) {
+    console.error('\x1b[31mError: Please specify a model name. Example: node bin/multimodel-dev-os.js show-model claude-sonnet-latest\x1b[0m');
+    process.exit(1);
+  }
+  handleShowModel(mName);
+} else if (COMMAND === 'providers') {
+  handleListProviders();
+} else if (COMMAND === 'route-model') {
+  const taskName = ARGS[1];
+  if (!taskName || taskName.startsWith('-')) {
+    console.error('\x1b[31mError: Please specify a task. Example: node bin/multimodel-dev-os.js route-model planning\x1b[0m');
+    process.exit(1);
+  }
+  handleRouteModel(taskName);
+} else if (COMMAND === 'adapters') {
+  handleListAdapters(params);
+} else if (COMMAND === 'show-adapter') {
+  const aName = ARGS[1];
+  if (!aName || aName.startsWith('-')) {
+    console.error('\x1b[31mError: Please specify an adapter name. Example: node bin/multimodel-dev-os.js show-adapter cursor\x1b[0m');
+    process.exit(1);
+  }
+  handleShowAdapter(aName);
+} else if (COMMAND === 'skills') {
+  handleListSkills(params);
+} else if (COMMAND === 'show-skill') {
+  const sName = ARGS[1];
+  if (!sName || sName.startsWith('-')) {
+    console.error('\x1b[31mError: Please specify a skill name. Example: node bin/multimodel-dev-os.js show-skill bug-fix\x1b[0m');
+    process.exit(1);
+  }
+  handleShowSkill(sName, params);
 } else {
   console.error(`\x1b[31mUnknown command: ${COMMAND}\x1b[0m`);
   showHelp();
@@ -137,23 +230,42 @@ function showHelp() {
   console.log('  list-templates    Alias for templates command');
   console.log('  show-template <t> Inspect detailed stack specifications of template <t>');
   console.log('  doctor            Advisory checkup of project compatibility loops and ignored folders');
-  console.log('  validate          Strict validation checks to verify directory schema compliance\n');
+  console.log('  validate          Strict validation checks to verify directory schema compliance');
+  console.log('  validate-template Validate registry keys and source folder files for template');
+  console.log('  validate-adapter  Validate registry keys and source assets for IDE adapter');
+  console.log('  validate-skill    Verify custom skill conforms to core prompt structure');
+  console.log('  models            List registered model aliases in the capabilities registry');
+  console.log('  show-model <m>    View specifications of model <m> in registry');
+  console.log('  providers         List configured AI provider API endpoints');
+  console.log('  route-model <tsk> Suggest optimal model mapping for task <tsk>');
+  console.log('  adapters          List IDE and terminal tool adapters');
+  console.log('  show-adapter <a>  Inspect config specifications of adapter <a>');
+  console.log('  skills            List active skills custom prompts in target workspace');
+  console.log('  show-skill <s>    View prompt contents of target workspace skill <s>\n');
   console.log('Options:');
   console.log('  -t, --target <path>     Target folder destination (default: current working directory)');
-  console.log('  --template <name>       Template profile: nextjs-saas, wordpress-site, ecommerce-store,');
-  console.log('                          seo-landing-page, general-app (default: general-app)');
-  console.log('  -a, --adapter <name>    Inject specific adapter: codex, antigravity, cursor, claude, gemini, vscode');
+  console.log('  --template <name>       Template profile: nextjs-saas, expo-react-native-android, etc.');
+  console.log('  -a, --adapter <name>    Inject specific adapter: cursor, claude, vscode, gemini, etc.');
   console.log('  --caveman               Use minimal-token templates (~79% fewer tokens)');
+  console.log('  --tokens                Run a deeper token-sink size analysis during doctor checkup');
+  console.log('  --json                  Output raw JSON data for listing commands (models, adapters, templates)');
+  console.log('  --threshold <val>       Set custom size threshold for doctor tokens checks (e.g. 50KB)');
+  console.log('  --registry <path>       Override default registry (for templates/adapters list or check)');
   console.log('  -d, --dry-run           Preview planned file actions without modifying the filesystem');
   console.log('  -f, --force             Overwrite existing files without prompting\n');
 }
 
-function handleListTemplates() {
+function handleListTemplates(options) {
+  if (options && options.json) {
+    console.log(JSON.stringify(TEMPLATES, null, 2));
+    return;
+  }
   console.log(`\n🧠 \x1b[36mBuilt-in Template Profiles [v${version}]\x1b[0m`);
   console.log('==================================================');
   Object.keys(TEMPLATES).forEach(key => {
     const t = TEMPLATES[key];
-    console.log(`\n\x1b[32m* ${t.name}\x1b[0m`);
+    const statusStr = t.status === 'planned' ? ' (Planned)' : t.status === 'experimental' ? ' (Experimental)' : '';
+    console.log(`\n\x1b[32m* ${t.name}${statusStr}\x1b[0m`);
     console.log(`  \x1b[33mStack:\x1b[0m ${t.stack}`);
     console.log(`  \x1b[37mDescription:\x1b[0m ${t.description}`);
   });
@@ -163,16 +275,20 @@ function handleListTemplates() {
 function handleShowTemplate(name) {
   const t = TEMPLATES[name];
   if (!t) {
-    console.error(`\n\x1b[31mError: Template '${name}' does not exist. Available: nextjs-saas, wordpress-site, ecommerce-store, seo-landing-page, general-app\x1b[0m\n`);
+    const available = Object.keys(TEMPLATES).join(', ');
+    console.error(`\n\x1b[31mError: Template '${name}' does not exist. Available: ${available}\x1b[0m\n`);
     process.exit(1);
   }
 
-  console.log(`\n🔍 \x1b[36mTemplate Profile: ${t.name}\x1b[0m`);
+  const statusStr = t.status === 'planned' ? ' (Planned)' : t.status === 'experimental' ? ' (Experimental)' : ' (Stable)';
+  console.log(`\n🔍 \x1b[36mTemplate Profile: ${t.name}${statusStr}\x1b[0m`);
   console.log('==================================================');
   console.log(`\x1b[33mStack Blueprint:\x1b[0m ${t.stack}`);
   console.log(`\x1b[33mOverview:\x1b[0m ${t.description}`);
-  console.log(`\x1b[33mHighlighted Skill:\x1b[0m .ai/skills/${t.skill}`);
-  console.log(`  └─> ${t.skillDesc}`);
+  if (t.skill) {
+    console.log(`\x1b[33mHighlighted Skill:\x1b[0m .ai/skills/${t.skill}`);
+    console.log(`  └─> ${t.skillDesc}`);
+  }
   console.log('\n\x1b[33mScaffolding Directory Layout:\x1b[0m');
   console.log('  ├── AGENTS.md                   (Stack building conventions)');
   console.log('  ├── MEMORY.md                   (Architectural constraints record)');
@@ -186,12 +302,25 @@ function handleShowTemplate(name) {
   console.log('      │   ├── model-map.md        (AI routing specifications)');
   console.log('      │   └── context-budget.md   (Token allocation guidelines)');
   console.log(`      └── skills/`);
-  console.log(`          └── ${t.skill}     (Custom template skills code boiler)`);
+  if (t.skill) {
+    console.log(`          └── ${t.skill}     (Custom template skills code boiler)`);
+  } else {
+    console.log(`          └── [custom-skill].md   (Custom template skills code boiler)`);
+  }
   console.log('\nUse \x1b[32minit --template ' + t.name + '\x1b[0m to bootstrap this profile.\n');
 }
 
 function handleInit(options) {
   console.log(`\n\x1b[34mInitializing multimodel-dev-os in: ${options.target}\x1b[0m`);
+  
+  // Check if requested template is planned
+  const tInfo = TEMPLATES[options.template];
+  if (tInfo && tInfo.status === 'planned') {
+    console.warn(`  \x1b[33m[WARNING] Template '${options.template}' is a PLANNED template in the roadmap.\x1b[0m`);
+    console.warn(`  It is not fully scaffolded yet and will fall back to bootstrapping the 'general-app' profile.\n`);
+    options.template = 'general-app';
+  }
+
   console.log(`Template profile: \x1b[32m${options.template}\x1b[0m`);
   if (options.caveman) console.log('Bone variant: \x1b[33mCaveman Mode Active\x1b[0m');
   if (options.dryRun) console.log('\x1b[36mDry Run active - no actual modifications will occur\x1b[0m');
@@ -337,44 +466,15 @@ function handleInit(options) {
   // Copy root-level adapter rule files if selected
   if (!options.dryRun) {
     options.adapters.forEach(adapter => {
-      if (adapter === 'cursor') {
-        const srcFile = join(sourceRoot, 'adapters/cursor/.cursorrules');
-        const destFile = join(options.target, '.cursorrules');
-        if (existsSync(srcFile)) {
-          writeFileSync(destFile, readFileSync(srcFile));
-          console.log(`  \x1b[32mCREATE ROOT ADAPTER FILE:\x1b[0m .cursorrules`);
-        }
-      } else if (adapter === 'claude') {
-        const srcFile = join(sourceRoot, 'adapters/claude/CLAUDE.md');
-        const destFile = join(options.target, 'CLAUDE.md');
-        if (existsSync(srcFile)) {
-          writeFileSync(destFile, readFileSync(srcFile));
-          console.log(`  \x1b[32mCREATE ROOT ADAPTER FILE:\x1b[0m CLAUDE.md`);
-        }
-      } else if (adapter === 'vscode') {
-        const srcFile = join(sourceRoot, 'adapters/vscode/.vscode/settings.json');
-        const destDir = join(options.target, '.vscode');
-        const destFile = join(destDir, 'settings.json');
+      const a = ADAPTERS[adapter];
+      if (a && a.rules_file) {
+        const srcFile = join(sourceRoot, 'adapters', adapter, a.rules_file);
+        const destFile = join(options.target, a.rules_file);
+        const destDir = dirname(destFile);
         if (existsSync(srcFile)) {
           if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
           writeFileSync(destFile, readFileSync(srcFile));
-          console.log(`  \x1b[32mCREATE ROOT ADAPTER FILE:\x1b[0m .vscode/settings.json`);
-        }
-      } else if (adapter === 'gemini') {
-        const srcFile = join(sourceRoot, 'adapters/gemini/GEMINI.md');
-        const destFile = join(options.target, 'GEMINI.md');
-        if (existsSync(srcFile)) {
-          writeFileSync(destFile, readFileSync(srcFile));
-          console.log(`  \x1b[32mCREATE ROOT ADAPTER FILE:\x1b[0m GEMINI.md`);
-        }
-      } else if (adapter === 'antigravity') {
-        const srcFile = join(sourceRoot, 'adapters/antigravity/.gemini/settings.json');
-        const destDir = join(options.target, '.gemini');
-        const destFile = join(destDir, 'settings.json');
-        if (existsSync(srcFile)) {
-          if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
-          writeFileSync(destFile, readFileSync(srcFile));
-          console.log(`  \x1b[32mCREATE ROOT ADAPTER FILE:\x1b[0m .gemini/settings.json`);
+          console.log(`  \x1b[32mCREATE ROOT ADAPTER FILE:\x1b[0m ${a.rules_file}`);
         }
       }
     });
@@ -393,11 +493,10 @@ function handleInit(options) {
   } else {
     // Dry run notes
     options.adapters.forEach(adapter => {
-      if (adapter === 'cursor') console.log(`  \x1b[36m[DRY-RUN] WOULD CREATE ROOT ADAPTER FILE:\x1b[0m .cursorrules`);
-      else if (adapter === 'claude') console.log(`  \x1b[36m[DRY-RUN] WOULD CREATE ROOT ADAPTER FILE:\x1b[0m CLAUDE.md`);
-      else if (adapter === 'vscode') console.log(`  \x1b[36m[DRY-RUN] WOULD CREATE ROOT ADAPTER FILE:\x1b[0m .vscode/settings.json`);
-      else if (adapter === 'gemini') console.log(`  \x1b[36m[DRY-RUN] WOULD CREATE ROOT ADAPTER FILE:\x1b[0m GEMINI.md`);
-      else if (adapter === 'antigravity') console.log(`  \x1b[36m[DRY-RUN] WOULD CREATE ROOT ADAPTER FILE:\x1b[0m .gemini/settings.json`);
+      const a = ADAPTERS[adapter];
+      if (a && a.rules_file) {
+        console.log(`  \x1b[36m[DRY-RUN] WOULD CREATE ROOT ADAPTER FILE:\x1b[0m ${a.rules_file}`);
+      }
     });
   }
 
@@ -458,6 +557,14 @@ function handleVerify(options) {
 }
 
 function handleDoctor(options) {
+  if (options.tokens) {
+    handleDoctorTokens(options);
+    return;
+  }
+  if (options.release) {
+    handleDoctorRelease(options);
+    return;
+  }
   console.log(`\n🩺 \x1b[36mRunning advisory doctor checkup in: ${options.target}\x1b[0m\n`);
 
   let warnings = 0;
@@ -562,6 +669,10 @@ function handleDoctor(options) {
 }
 
 function handleValidate(options) {
+  if (options && options.allRegistries) {
+    handleValidateAllRegistries();
+    return;
+  }
   console.log(`\n🛡 \x1b[34mRunning strict schema validation in: ${options.target}\x1b[0m\n`);
 
   let errors = 0;
@@ -642,6 +753,26 @@ function handleValidate(options) {
     assertAdapter('antigravity', '.gemini/settings.json');
   }
 
+  // Template-specific validation
+  if (options.template) {
+    const tInfo = TEMPLATES[options.template];
+    if (tInfo && Array.isArray(tInfo.required_files)) {
+      console.log(`\n📋 Validating required files for template '${options.template}':`);
+      tInfo.required_files.forEach(f => assertPath(f, 'file'));
+    } else if (options.template === 'expo-react-native-android') {
+      const mobileFiles = [
+        'app.json',
+        'eas.json',
+        'app.config.ts',
+        'jest.config.js',
+        'src/app/_layout.tsx',
+        'src/lib/secure-storage.ts',
+        'src/services/api-client.ts'
+      ];
+      mobileFiles.forEach(f => assertPath(f, 'file'));
+    }
+  }
+
   console.log('\n==================================================');
   if (errors > 0) {
     console.error(`  \x1b[31mValidation FAILED. Found ${errors} strict structural compliance errors.\x1b[0m\n`);
@@ -651,3 +782,591 @@ function handleValidate(options) {
     process.exit(0);
   }
 }
+
+// --- YAML Parser Helper ---
+function parseYaml(content) {
+  try {
+    const root = {};
+    const stack = [{ obj: root, indent: -1, key: null, isArray: false }];
+
+    const lines = content.split(/\r?\n/);
+    for (let line of lines) {
+      const commentIdx = line.indexOf('#');
+      if (commentIdx !== -1) {
+        line = line.substring(0, commentIdx);
+      }
+      line = line.trimEnd();
+      if (!line.trim()) continue;
+
+      const indent = line.match(/^ */)[0].length;
+      let trimmed = line.trim();
+
+      while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+        stack.pop();
+      }
+
+      const parent = stack[stack.length - 1];
+
+      if (trimmed.startsWith('-')) {
+        trimmed = trimmed.substring(1).trim();
+        if (!Array.isArray(parent.obj)) {
+          const grandparent = stack[stack.length - 2];
+          if (grandparent) {
+            grandparent.obj[parent.key] = [];
+            parent.obj = grandparent.obj[parent.key];
+          }
+        }
+        
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1) {
+          parent.obj.push(trimmed);
+        } else {
+          const key = trimmed.substring(0, colonIdx).trim();
+          let val = trimmed.substring(colonIdx + 1).trim();
+          if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.substring(1, val.length - 1);
+          }
+          if (val === 'true') val = true;
+          else if (val === 'false') val = false;
+          else if (val === 'null') val = null;
+          else if (/^\d+$/.test(val)) val = parseInt(val, 10);
+
+          const newObj = { [key]: val };
+          parent.obj.push(newObj);
+          stack.push({ obj: newObj, indent: indent, key: key, isArray: false });
+        }
+      } else {
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1) continue;
+
+        const key = trimmed.substring(0, colonIdx).trim();
+        let val = trimmed.substring(colonIdx + 1).trim();
+
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.substring(1, val.length - 1);
+        }
+        if (val === 'true') val = true;
+        else if (val === 'false') val = false;
+        else if (val === 'null') val = null;
+        else if (/^\d+$/.test(val)) val = parseInt(val, 10);
+
+        if (val === '') {
+          parent.obj[key] = {};
+          stack.push({ obj: parent.obj[key], indent: indent, key: key, isArray: false });
+        } else {
+          parent.obj[key] = val;
+        }
+      }
+    }
+    return root;
+  } catch (e) {
+    console.warn(`\x1b[33m[WARNING] Failed to parse YAML: ${e.message}\x1b[0m`);
+    return {};
+  }
+}
+
+// --- Command Handler Functions ---
+function handleListModels(options) {
+  const registryPath = join(sourceRoot, '.ai', 'models', 'registry.yaml');
+  if (!existsSync(registryPath)) {
+    console.error('Error: Model registry not found.');
+    process.exit(1);
+  }
+  const registry = parseYaml(readFileSync(registryPath, 'utf8'));
+  const models = registry.models || {};
+  if (options && options.json) {
+    console.log(JSON.stringify(models, null, 2));
+    return;
+  }
+  console.log(`\n🤖 \x1b[36mModel Registry [v${version}]\x1b[0m`);
+  console.log('==================================================');
+  Object.keys(models).forEach(name => {
+    const m = models[name];
+    console.log(`\n\x1b[32m* ${name}\x1b[0m (${m.alias || ''})`);
+    console.log(`  \x1b[33mProvider:\x1b[0m ${m.provider}`);
+    console.log(`  \x1b[33mOfficial ID:\x1b[0m ${m.official_id}`);
+    console.log(`  \x1b[33mContext Window:\x1b[0m ${m.context_window} tokens`);
+    console.log(`  \x1b[33mTiers:\x1b[0m Cost: ${m.tiers?.cost}, Reasoning: ${m.tiers?.reasoning}, Coding: ${m.tiers?.coding}`);
+  });
+  console.log('\nUse \x1b[36mshow-model <model-alias>\x1b[0m to view detailed model capabilities.\n');
+}
+
+function handleShowModel(name) {
+  const registryPath = join(sourceRoot, '.ai', 'models', 'registry.yaml');
+  if (!existsSync(registryPath)) {
+    console.error('Error: Model registry not found.');
+    process.exit(1);
+  }
+  const registry = parseYaml(readFileSync(registryPath, 'utf8'));
+  const models = registry.models || {};
+  const m = models[name];
+  if (!m) {
+    console.error(`\x1b[31mError: Model alias '${name}' not found in registry.\x1b[0m`);
+    process.exit(1);
+  }
+  console.log(`\n🔍 \x1b[36mModel: ${name}\x1b[0m`);
+  console.log('==================================================');
+  console.log(`\x1b[33mProvider:\x1b[0m ${m.provider}`);
+  console.log(`\x1b[33mAlias:\x1b[0m ${m.alias}`);
+  console.log(`\x1b[33mOfficial ID:\x1b[0m ${m.official_id}`);
+  console.log(`\x1b[33mContext Window:\x1b[0m ${m.context_window} tokens`);
+  console.log(`\x1b[33mCapabilities:\x1b[0m`);
+  console.log(`  ├─ Vision: ${m.capabilities?.vision ? 'Yes' : 'No'}`);
+  console.log(`  └─ Tool Use: ${m.capabilities?.tool_use ? 'Yes' : 'No'}`);
+  console.log(`\x1b[33mTiers:\x1b[0m`);
+  console.log(`  ├─ Cost: ${m.tiers?.cost}`);
+  console.log(`  ├─ Speed: ${m.tiers?.speed}`);
+  console.log(`  ├─ Reasoning: ${m.tiers?.reasoning}`);
+  console.log(`  └─ Coding: ${m.tiers?.coding}`);
+  console.log();
+}
+
+function handleListProviders() {
+  const providersPath = join(sourceRoot, '.ai', 'models', 'providers.yaml');
+  if (!existsSync(providersPath)) {
+    console.error('Error: Providers registry not found.');
+    process.exit(1);
+  }
+  const reg = parseYaml(readFileSync(providersPath, 'utf8'));
+  const providers = reg.providers || {};
+  console.log(`\n🔌 \x1b[36mAI Providers [v${version}]\x1b[0m`);
+  console.log('==================================================');
+  Object.keys(providers).forEach(name => {
+    const p = providers[name];
+    console.log(`\n\x1b[32m* ${p.name || name}\x1b[0m (${name})`);
+    console.log(`  \x1b[33mEndpoint:\x1b[0m ${p.api_endpoint || 'Local'}`);
+    console.log(`  \x1b[33mEnv Key:\x1b[0m ${p.env_key || 'None'}`);
+  });
+  console.log();
+}
+
+function handleRouteModel(task) {
+  const presetsPath = join(sourceRoot, '.ai', 'models', 'routing-presets.yaml');
+  if (!existsSync(presetsPath)) {
+    console.error('Error: Routing presets not found.');
+    process.exit(1);
+  }
+  const reg = parseYaml(readFileSync(presetsPath, 'utf8'));
+  const presets = reg.presets || {};
+  const preset = presets[task];
+  if (!preset) {
+    console.error(`\x1b[31mError: Routing preset for task '${task}' not found. Available: ${Object.keys(presets).join(', ')}\x1b[0m`);
+    process.exit(1);
+  }
+  console.log(`\n🎯 \x1b[36mRouting Suggestion for: ${task}\x1b[0m`);
+  console.log('==================================================');
+  console.log(`\x1b[33mPrimary Model:\x1b[0m \x1b[32m${preset.primary}\x1b[0m`);
+  console.log(`\x1b[33mFallback Model:\x1b[0m \x1b[33m${preset.fallback}\x1b[0m`);
+  console.log();
+}
+
+function handleListAdapters(options) {
+  const adaptersPath = join(sourceRoot, '.ai', 'adapters', 'registry.yaml');
+  if (!existsSync(adaptersPath)) {
+    console.error('Error: Adapters registry not found.');
+    process.exit(1);
+  }
+  const reg = parseYaml(readFileSync(adaptersPath, 'utf8'));
+  const adapters = reg.adapters || {};
+  if (options && options.json) {
+    console.log(JSON.stringify(adapters, null, 2));
+    return;
+  }
+  console.log(`\n🔌 \x1b[36mIDE & Agent Adapters [v${version}]\x1b[0m`);
+  console.log('==================================================');
+  Object.keys(adapters).forEach(name => {
+    const a = adapters[name];
+    console.log(`\n\x1b[32m* ${a.name || name}\x1b[0m (${name})`);
+    console.log(`  \x1b[33mRules File:\x1b[0m ${a.rules_file}`);
+    console.log(`  \x1b[33mAdapter Type:\x1b[0m ${a.type}`);
+    console.log(`  \x1b[33mRule Format:\x1b[0m ${a.format}`);
+  });
+  console.log('\nUse \x1b[36mshow-adapter <adapter-name>\x1b[0m to view detailed adapter metadata.\n');
+}
+
+function handleShowAdapter(name) {
+  const adaptersPath = join(sourceRoot, '.ai', 'adapters', 'registry.yaml');
+  if (!existsSync(adaptersPath)) {
+    console.error('Error: Adapters registry not found.');
+    process.exit(1);
+  }
+  const reg = parseYaml(readFileSync(adaptersPath, 'utf8'));
+  const adapters = reg.adapters || {};
+  const a = adapters[name];
+  if (!a) {
+    console.error(`\x1b[31mError: Adapter '${name}' not found in registry.\x1b[0m`);
+    process.exit(1);
+  }
+  console.log(`\n🔍 \x1b[36mAdapter: ${a.name || name}\x1b[0m`);
+  console.log('==================================================');
+  console.log(`\x1b[33mRules File:\x1b[0m ${a.rules_file}`);
+  console.log(`\x1b[33mType:\x1b[0m ${a.type}`);
+  console.log(`\x1b[33mFormat:\x1b[0m ${a.format}`);
+  console.log();
+}
+
+function handleListSkills(options) {
+  const skillsDir = join(options.target, '.ai', 'skills');
+  if (!existsSync(skillsDir)) {
+    console.log('\n\x1b[33m[Notice] .ai/skills directory is not initialized in the target workspace.\x1b[0m\n');
+    return;
+  }
+  const files = readdirSync(skillsDir).filter(f => f.endsWith('.md'));
+  console.log(`\n🧠 \x1b[36mAvailable Skills in Target [v${version}]\x1b[0m`);
+  console.log('==================================================');
+  files.forEach(f => {
+    console.log(`  \x1b[32m- ${f.replace('.md', '')}\x1b[0m (file: .ai/skills/${f})`);
+  });
+  console.log('\nUse \x1b[36mshow-skill <skill-name>\x1b[0m to read a skill\'s prompt text.\n');
+}
+
+function handleShowSkill(name, options) {
+  const skillsDir = join(options.target, '.ai', 'skills');
+  const skillFile = join(skillsDir, name.endsWith('.md') ? name : `${name}.md`);
+  if (!existsSync(skillFile)) {
+    console.error(`\x1b[31mError: Skill '${name}' not found in target .ai/skills/.\x1b[0m`);
+    process.exit(1);
+  }
+  console.log(`\n📖 \x1b[36mSkill Prompt: ${name}\x1b[0m`);
+  console.log('==================================================');
+  console.log(readFileSync(skillFile, 'utf8'));
+  console.log();
+}
+
+function parseThresholdToBytes(val) {
+  if (!val) return 100 * 1024; // Default 100KB
+  const matches = val.match(/^(\d+)(KB|MB|B)?$/i);
+  if (!matches) return 100 * 1024;
+  const num = parseInt(matches[1], 10);
+  const unit = (matches[2] || '').toUpperCase();
+  if (unit === 'MB') return num * 1024 * 1024;
+  if (unit === 'KB') return num * 1024;
+  return num;
+}
+
+function handleDoctorTokens(options) {
+  console.log(`\n🪙 \x1b[36mRunning Token Budget & Sink Audit in: ${options.target}\x1b[0m\n`);
+  
+  const filesFound = [];
+  const ignoredDirs = ['.git', 'node_modules', 'dist', 'build', '.next', '.expo', 'bin', 'assets', 'docs', 'web-build', 'out', 'coverage', '.nuxt', '.svelte-kit', 'bower_components', 'vendor'];
+  
+  function scan(dir) {
+    if (!existsSync(dir)) return;
+    const items = readdirSync(dir);
+    for (const item of items) {
+      if (ignoredDirs.includes(item)) continue;
+      const fullPath = join(dir, item);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          scan(fullPath);
+        } else if (stat.isFile()) {
+          filesFound.push({
+            relPath: replaceBackslashes(fullPath.replace(options.target, '')),
+            size: stat.size
+          });
+        }
+      } catch (e) {}
+    }
+  }
+
+  function replaceBackslashes(p) {
+    let clean = p.replace(/\\/g, '/');
+    if (clean.startsWith('/')) clean = clean.substring(1);
+    return clean;
+  }
+
+  scan(options.target);
+  
+  filesFound.sort((a, b) => b.size - a.size);
+  
+  const thresholdBytes = parseThresholdToBytes(options.threshold);
+  const thresholdStr = options.threshold || '100KB';
+
+  console.log('Top 10 Largest Files in Scanned Workspace:');
+  filesFound.slice(0, 10).forEach(f => {
+    let sizeDesc = `${f.size} bytes`;
+    if (f.size > 1024 * 1024) sizeDesc = `${(f.size / (1024 * 1024)).toFixed(2)} MB`;
+    else if (f.size > 1024) sizeDesc = `${(f.size / 1024).toFixed(2)} KB`;
+    
+    let color = '\x1b[32m';
+    if (f.size > thresholdBytes) color = '\x1b[31m';
+    else if (f.size > thresholdBytes * 0.3) color = '\x1b[33m';
+    
+    console.log(`  ${color}* ${f.relPath}\x1b[0m (${sizeDesc})`);
+  });
+  
+  console.log('\n==================================================');
+  console.log(`Total Scanned Files: ${filesFound.length}`);
+  console.log(`Recommendation: Exclude files in red (>${thresholdStr}) from active coding prompts or add them to your adapter ignore rules.`);
+  console.log();
+}
+
+function handleValidateTemplate(name) {
+  const t = TEMPLATES[name];
+  if (!t) {
+    console.error(`\x1b[31mError: Template '${name}' not found in registry.\x1b[0m`);
+    process.exit(1);
+  }
+  console.log(`\n📋 \x1b[34mValidating Template: ${name}\x1b[0m`);
+  
+  let errors = 0;
+  const reqKeys = ['name', 'description', 'stack', 'category', 'status', 'maturity', 'required_files'];
+  reqKeys.forEach(k => {
+    if (t[k] === undefined || t[k] === null) {
+      console.error(`  \x1b[31m✗ Missing registry key: ${k}\x1b[0m`);
+      errors++;
+    } else {
+      console.log(`  \x1b[32m✓\x1b[0m Registry key: ${k}`);
+    }
+  });
+
+  const templateDir = join(sourceRoot, 'examples', name);
+  if (!existsSync(templateDir)) {
+    console.error(`  \x1b[31m✗ Source folder missing: examples/${name}\x1b[0m`);
+    errors++;
+  } else {
+    console.log(`  \x1b[32m✓\x1b[0m Source folder: examples/${name}`);
+    if (Array.isArray(t.required_files)) {
+      t.required_files.forEach(f => {
+        const filePath = join(templateDir, f);
+        const globalPath = join(sourceRoot, f);
+        if (existsSync(filePath)) {
+          console.log(`  \x1b[32m✓\x1b[0m Required file (template override): ${f}`);
+        } else if (existsSync(globalPath)) {
+          console.log(`  \x1b[32m✓\x1b[0m Required file (global fallback): ${f}`);
+        } else {
+          console.error(`  \x1b[31m✗ Required file missing: ${f}\x1b[0m`);
+          errors++;
+        }
+      });
+    }
+  }
+
+  if (errors > 0) {
+    console.error(`\n\x1b[31mValidation FAILED with ${errors} errors.\x1b[0m\n`);
+    process.exit(1);
+  } else {
+    console.log(`\n\x1b[32m✔ Template '${name}' is fully valid and compliant!\x1b[0m\n`);
+    process.exit(0);
+  }
+}
+
+function handleValidateAdapter(name) {
+  const a = ADAPTERS[name];
+  if (!a) {
+    console.error(`\x1b[31mError: Adapter '${name}' not found in registry.\x1b[0m`);
+    process.exit(1);
+  }
+  console.log(`\n📋 \x1b[34mValidating Adapter: ${name}\x1b[0m`);
+  
+  let errors = 0;
+  const reqKeys = ['name', 'rules_file', 'format', 'type'];
+  reqKeys.forEach(k => {
+    if (!a[k]) {
+      console.error(`  \x1b[31m✗ Missing registry key: ${k}\x1b[0m`);
+      errors++;
+    } else {
+      console.log(`  \x1b[32m✓\x1b[0m Registry key: ${k}`);
+    }
+  });
+
+  const adapterDir = join(sourceRoot, 'adapters', name);
+  if (!existsSync(adapterDir)) {
+    console.error(`  \x1b[31m✗ Source folder missing: adapters/${name}\x1b[0m`);
+    errors++;
+  } else {
+    console.log(`  \x1b[32m✓\x1b[0m Source folder: adapters/${name}`);
+    const setupFile = join(adapterDir, 'setup.md');
+    if (existsSync(setupFile)) {
+      console.log(`  \x1b[32m✓\x1b[0m Required file: setup.md`);
+    } else {
+      console.error(`  \x1b[31m✗ Required file missing: adapters/${name}/setup.md\x1b[0m`);
+      errors++;
+    }
+
+    if (a.rules_file) {
+      const rulesFile = join(adapterDir, a.rules_file);
+      if (existsSync(rulesFile)) {
+        console.log(`  \x1b[32m✓\x1b[0m Rules file: ${a.rules_file}`);
+      } else {
+        console.error(`  \x1b[31m✗ Rules file missing: adapters/${name}/${a.rules_file}\x1b[0m`);
+        errors++;
+      }
+    }
+  }
+
+  if (errors > 0) {
+    console.error(`\n\x1b[31mValidation FAILED with ${errors} errors.\x1b[0m\n`);
+    process.exit(1);
+  } else {
+    console.log(`\n\x1b[32m✔ Adapter '${name}' is fully valid and compliant!\x1b[0m\n`);
+    process.exit(0);
+  }
+}
+
+function handleValidateSkill(name, options) {
+  const skillsDir = join(options.target, '.ai', 'skills');
+  let skillFile = join(skillsDir, name.endsWith('.md') ? name : `${name}.md`);
+  if (!existsSync(skillFile)) {
+    skillFile = join(sourceRoot, '.ai', 'skills', name.endsWith('.md') ? name : `${name}.md`);
+  }
+
+  if (!existsSync(skillFile)) {
+    console.error(`\x1b[31mError: Skill '${name}' not found.\x1b[0m`);
+    process.exit(1);
+  }
+
+  console.log(`\n📋 \x1b[34mValidating Skill: ${name}\x1b[0m`);
+  const content = readFileSync(skillFile, 'utf8');
+  let errors = 0;
+
+  const reqHeaders = [
+    { header: '# Purpose', regex: /^#\s+Purpose/mi },
+    { header: '# Activation Trigger', regex: /^#\s+Activation\s+Trigger/mi },
+    { header: '# Input Context', regex: /^#\s+Input\s+Context/mi },
+    { header: '# Output Contract', regex: /^#\s+Output\s+Contract/mi },
+    { header: '# Token Budget', regex: /^#\s+Token\s+Budget/mi }
+  ];
+
+  reqHeaders.forEach(req => {
+    if (req.regex.test(content)) {
+      console.log(`  \x1b[32m✓\x1b[0m Found required header: ${req.header}`);
+    } else {
+      console.error(`  \x1b[31m✗ Missing required header: ${req.header}\x1b[0m`);
+      errors++;
+    }
+  });
+
+  if (errors > 0) {
+    console.error(`\n\x1b[31mValidation FAILED with ${errors} errors.\x1b[0m\n`);
+    process.exit(1);
+  } else {
+    console.log(`\n\x1b[32m✔ Skill '${name}' is fully valid and compliant!\x1b[0m\n`);
+    process.exit(0);
+  }
+}
+
+function handleValidateAllRegistries() {
+  console.log(`\n🛡 \x1b[34mValidating All Registry Entries\x1b[0m\n`);
+  let errors = 0;
+
+  // Validate all templates
+  console.log('--- Templates Registry Validation ---');
+  Object.keys(TEMPLATES).forEach(name => {
+    const t = TEMPLATES[name];
+    console.log(`\nValidating Template: ${name}`);
+    const reqKeys = ['name', 'description', 'stack', 'category', 'status', 'maturity'];
+    if (t.status !== 'planned') {
+      reqKeys.push('required_files');
+    }
+    reqKeys.forEach(k => {
+      if (t[k] === undefined || t[k] === null) {
+        console.error(`  \x1b[31m✗ Missing registry key: ${k}\x1b[0m`);
+        errors++;
+      }
+    });
+
+    const templateDir = join(sourceRoot, 'examples', name);
+    if (t.status === 'stable' && !existsSync(templateDir)) {
+      console.error(`  \x1b[31m✗ Stable template source folder missing: examples/${name}\x1b[0m`);
+      errors++;
+    }
+  });
+
+  // Validate all adapters
+  console.log('\n--- Adapters Registry Validation ---');
+  Object.keys(ADAPTERS).forEach(name => {
+    const a = ADAPTERS[name];
+    console.log(`Validating Adapter: ${name}`);
+    const reqKeys = ['name', 'rules_file', 'format', 'type'];
+    reqKeys.forEach(k => {
+      if (!a[k]) {
+        console.error(`  \x1b[31m✗ Missing registry key: ${k}\x1b[0m`);
+        errors++;
+      }
+    });
+  });
+
+  console.log('\n==================================================');
+  if (errors > 0) {
+    console.error(`  \x1b[31mAll Registries validation FAILED. Found ${errors} schema errors.\x1b[0m\n`);
+    process.exit(1);
+  } else {
+    console.log('  \x1b[32m✔ All Registries validation PASSED. All templates and adapters are valid.\x1b[0m\n');
+    process.exit(0);
+  }
+}
+
+function handleDoctorRelease(options) {
+  console.log(`\n🩺 \x1b[36mRunning release audit doctor in: ${sourceRoot}\x1b[0m\n`);
+  let warnings = 0;
+
+  // 1. Version checks
+  let packageVersion = 'unknown';
+  try {
+    const pkg = JSON.parse(readFileSync(join(sourceRoot, 'package.json'), 'utf8'));
+    packageVersion = pkg.version;
+    console.log(`  \x1b[32m✓\x1b[0m package.json version: ${packageVersion}`);
+  } catch (e) {
+    console.warn('  \x1b[31m✗\x1b[0m Failed to parse package.json');
+    warnings++;
+  }
+
+  const checkInstallScript = (filename, regex) => {
+    const filePath = join(sourceRoot, filename);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, 'utf8');
+      const match = content.match(regex);
+      if (match && match[1] === packageVersion) {
+        console.log(`  \x1b[32m✓\x1b[0m ${filename} version aligns: ${match[1]}`);
+      } else {
+        console.warn(`  \x1b[33m[WARNING]\x1b[0m ${filename} version mismatch (found ${match ? match[1] : 'none'}, expected ${packageVersion})`);
+        warnings++;
+      }
+    }
+  };
+
+  checkInstallScript('scripts/install.sh', /VERSION="([^"]+)"/i);
+  checkInstallScript('scripts/install.ps1', /\$VERSION\s*=\s*"([^"]+)"/i);
+
+  // 2. Blacklisted files audit
+  const blacklist = ['.npmrc'];
+  blacklist.forEach(file => {
+    const fullPath = join(sourceRoot, file);
+    if (existsSync(fullPath)) {
+      console.warn(`  \x1b[33m[WARNING]\x1b[0m Blacklisted file found in release root: ${file}`);
+      warnings++;
+    } else {
+      console.log(`  \x1b[32m✓\x1b[0m No root blacklisted file: ${file}`);
+    }
+  });
+
+  // Recursively scan examples/ for .env and keystores
+  const scanSafety = (dir) => {
+    if (!existsSync(dir)) return;
+    const items = readdirSync(dir);
+    for (const item of items) {
+      const fullPath = join(dir, item);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          scanSafety(fullPath);
+        } else if (stat.isFile()) {
+          if (item === '.env' || item.endsWith('.keystore') || item.endsWith('.jks')) {
+            console.warn(`  \x1b[33m[WARNING]\x1b[0m Unsafe file inside templates/examples: ${fullPath.replace(sourceRoot, '')}`);
+            warnings++;
+          }
+        }
+      } catch (e) {}
+    }
+  };
+  scanSafety(join(sourceRoot, 'examples'));
+
+  console.log('\n==================================================');
+  if (warnings > 0) {
+    console.warn(`  \x1b[33mRelease doctor complete with ${warnings} warnings.\x1b[0m\n`);
+  } else {
+    console.log('  \x1b[32m✔ Release hygiene checks PASSED successfully!\x1b[0m\n');
+  }
+}