multimodel-dev-os 3.0.1 → 3.2.0

package/scripts/verify.js

@@ -6,7 +6,7 @@
  * Runs on Windows, macOS, and Linux with zero external dependencies.
  */
 
-import { existsSync, readFileSync, statSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, statSync, readdirSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import { join, resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -189,6 +189,21 @@ checkFile('scripts/pack-template.sh');
 checkFile('scripts/prepublish-guard.js');
 checkFile('bin/multimodel-dev-os.js');
 
+// --- Modular Source Files ---
+console.log('\nModular Source Files:');
+checkFile('src/cli/main.js');
+checkFile('src/cli/args.js');
+checkFile('src/cli/help.js');
+checkFile('src/core/yaml.js');
+checkFile('src/core/hashes.js');
+checkFile('src/core/policy.js');
+checkFile('src/core/security.js');
+checkFile('src/core/globals.js');
+checkFile('src/registry/validation.js');
+checkFile('src/registry/sources.js');
+checkFile('src/catalog/loader.js');
+checkFile('src/plugin/manifest.js');
+
 // --- GitHub Integration ---
 console.log('\nGitHub Workflows:');
 checkFile('.github/workflows/verify.yml');
@@ -203,7 +218,7 @@ checkFile('docs/adapters.md');
 checkFile('docs/installers.md');
 checkFile('docs/cli-roadmap.md');
 checkFile('docs/faq.md');
-checkFile('docs/testing-v0.2.md');
+checkFile('docs/testing.md');
 checkFile('docs/npm-publishing.md');
 checkFile('docs/templates-guide.md');
 checkFile('docs/protocol.md');
@@ -549,7 +564,7 @@ try {
     }
   }
 
-  // Test 2: Allows version 3.0.1 with MMDO_ALLOW_PUBLISH=true
+  // Test 2: Allows version 3.2.0 with MMDO_ALLOW_PUBLISH=true
   try {
     const output = execSync('node scripts/prepublish-guard.js', { 
       cwd: projectRoot, 
@@ -557,7 +572,7 @@ try {
       encoding: 'utf8' 
     });
     if (output.includes('Prepublish guard passed')) {
-      console.log(`  ${GREEN}✓${NC} prepublish guard allows version 3.0.1 when MMDO_ALLOW_PUBLISH=true`);
+      console.log(`  ${GREEN}✓${NC} prepublish guard allows version 3.2.0 when MMDO_ALLOW_PUBLISH=true`);
       pass++;
     } else {
       console.error(`  ${RED}✗${NC} prepublish guard passed but stdout missing success indicator`);
@@ -565,7 +580,7 @@ try {
     }
   } catch (err) {
     const errText = err.stderr ? err.stderr.toString() : '';
-    console.error(`  ${RED}✗${NC} prepublish guard blocked version 3.0.1: ${errText || err.message}`);
+    console.error(`  ${RED}✗${NC} prepublish guard blocked version 3.2.0: ${errText || err.message}`);
     fail++;
   }
 
@@ -579,12 +594,12 @@ try {
     pass++;
   }
 
-  // Test 4: Package.json version is exactly 3.0.1
-  if (expectedVersion === '3.0.1') {
-    console.log(`  ${GREEN}✓${NC} package.json version is exactly 3.0.1`);
+  // Test 4: Package.json version is exactly 3.2.0
+  if (expectedVersion === '3.2.0') {
+    console.log(`  ${GREEN}✓${NC} package.json version is exactly 3.2.0`);
     pass++;
   } else {
-    console.error(`  ${RED}✗${NC} package.json version is not 3.0.1 (found ${expectedVersion})`);
+    console.error(`  ${RED}✗${NC} package.json version is not 3.2.0 (found ${expectedVersion})`);
     fail++;
   }
 } catch (e) {
@@ -592,6 +607,52 @@ try {
   fail++;
 }
 
+// --- Post-build Generated CLI Checks ---
+console.log('\nPost-build Generated CLI Checks:');
+try {
+  // 0. Check build freshness
+  try {
+    execSync('node scripts/check-build-fresh.js', { cwd: projectRoot, stdio: 'ignore' });
+    console.log(`  ${GREEN}✓${NC} generated bin matches current source layout`);
+    pass++;
+  } catch (err) {
+    console.error(`  ${RED}✗${NC} generated bin is stale! Run 'npm run build' and commit bin/multimodel-dev-os.js`);
+    fail++;
+  }
+
+  const buildPath = join(projectRoot, 'bin', 'multimodel-dev-os.js');
+  const binContent = readFileSync(buildPath, 'utf8');
+  
+  const totalShebangs = (binContent.match(/#!/g) || []).length;
+  if (binContent.startsWith('#!/usr/bin/env node') && totalShebangs === 1) {
+    console.log(`  ${GREEN}✓${NC} generated bin has exactly one shebang at the top`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} generated bin has invalid shebang layout (count: ${totalShebangs})`);
+    fail++;
+  }
+  
+  if (binContent.includes('// Generated from src/. Do not edit directly.')) {
+    console.log(`  ${GREEN}✓${NC} generated bin has warning header`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} generated bin is missing the warning header`);
+    fail++;
+  }
+  
+  const hasUnsafeSync = binContent.includes("mod.get('${targetUrl}'") || (binContent.includes('execSync(`node -e "') && binContent.includes('${targetUrl}'));
+  if (!hasUnsafeSync && binContent.includes('execFileSync(process.execPath')) {
+    console.log(`  ${GREEN}✓${NC} generated bin is free of unsafe URL interpolation and uses execFileSync`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} generated bin fails safety scan (unsafe interpolation found)`);
+    fail++;
+  }
+} catch (e) {
+  console.error(`  ${RED}✗${NC} post-build generated CLI checks failed: ${e.message}`);
+  fail++;
+}
+
 // --- v2.8.0 / v2.8.1 Dashboard & Plugin Tests ---
 console.log('\nRunning TUI Dashboard & Plugin Pre-Flight Tests...');
 
@@ -921,22 +982,77 @@ try {
   fail++;
 }
 
-// Verify npm pack dry-run shows current version dynamically
+// Verify npm pack dry-run shows current version dynamically and has clean hygiene
 try {
-  const packOutput = execSync('npm pack --dry-run', { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-  if (packOutput.includes(`multimodel-dev-os@${expectedVersion}`) || packOutput.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || packOutput.includes(`version: ${expectedVersion}`)) {
+  const packOutput = execSync('npm pack --dry-run 2>&1', { cwd: projectRoot, encoding: 'utf8' });
+  const combinedOutput = packOutput;
+  
+  const hasVersion = combinedOutput.includes(`multimodel-dev-os@${expectedVersion}`) || combinedOutput.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || combinedOutput.includes(`version: ${expectedVersion}`);
+  if (hasVersion) {
     console.log(`  ${GREEN}✓${NC} npm pack --dry-run reports version ${expectedVersion}`);
     pass++;
   } else {
-    console.error(`  ${RED}✗${NC} npm pack --dry-run did not report ${expectedVersion} in stdout`);
+    console.error(`  ${RED}✗${NC} npm pack --dry-run did not report ${expectedVersion} in output`);
+    fail++;
+  }
+
+  // Hygiene checks
+  const lines = combinedOutput.split('\n');
+  const files = lines
+    .filter(l => l.includes('npm notice') && !l.includes('Tarball Details') && !l.includes('Tarball Filename') && !l.includes('package size:') && !l.includes('unpacked size:') && !l.includes('shasum:') && !l.includes('integrity:') && !l.includes('total files:'))
+    .map(l => {
+      const match = l.match(/npm notice\s+\d+(\.\d+)?[a-zA-Z]+\s+(.+)$/);
+      return match ? match[2].trim() : '';
+    })
+    .filter(f => f !== '');
+
+  const hasSrc = files.some(f => f.startsWith('src/'));
+  const hasTests = files.some(f => f.startsWith('tests/'));
+  
+  if (hasSrc && hasTests) {
+    console.log(`  ${GREEN}✓${NC} npm pack includes 'src/' and 'tests/' directories`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} npm pack is missing 'src/' or 'tests/' directory`);
+    fail++;
+  }
+
+  const hasBlacklisted = files.some(f => f.includes('.npmrc') || f.includes('.env') || f.includes('node_modules') || f.endsWith('.tgz') || f.includes('coverage/'));
+  if (!hasBlacklisted) {
+    console.log(`  ${GREEN}✓${NC} npm pack excludes sensitive and temporary files (.npmrc, .env, node_modules, .tgz, coverage)`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} npm pack contains blacklisted files!`);
     fail++;
   }
 } catch (e) {
   const stdErrOut = e.stderr ? e.stderr.toString() : '';
   const stdOutOut = e.stdout ? e.stdout.toString() : '';
-  if (stdErrOut.includes(`multimodel-dev-os@${expectedVersion}`) || stdErrOut.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || stdOutOut.includes(`multimodel-dev-os-${expectedVersion}.tgz`)) {
+  const combined = stdErrOut + '\n' + stdOutOut;
+  
+  const hasVersion = combined.includes(`multimodel-dev-os@${expectedVersion}`) || combined.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || combined.includes(`version: ${expectedVersion}`);
+  if (hasVersion) {
     console.log(`  ${GREEN}✓${NC} npm pack --dry-run reports version ${expectedVersion}`);
     pass++;
+    
+    const hasSrc = combined.includes('src/') || combined.includes('src\\');
+    const hasTests = combined.includes('tests/') || combined.includes('tests\\');
+    if (hasSrc && hasTests) {
+      console.log(`  ${GREEN}✓${NC} npm pack includes 'src/' and 'tests/' directories`);
+      pass++;
+    } else {
+      console.error(`  ${RED}✗${NC} npm pack is missing 'src/' or 'tests/' directory`);
+      fail++;
+    }
+
+    const hasBlacklisted = combined.includes('.npmrc') || combined.includes('.env') || combined.includes('node_modules') || combined.includes('.tgz') || combined.includes('coverage/');
+    if (!hasBlacklisted) {
+      console.log(`  ${GREEN}✓${NC} npm pack excludes sensitive and temporary files`);
+      pass++;
+    } else {
+      console.error(`  ${RED}✗${NC} npm pack contains blacklisted files!`);
+      fail++;
+    }
   } else {
     console.error(`  ${RED}✗${NC} npm pack --dry-run failed or did not report ${expectedVersion}: ${e.message}`);
     fail++;
@@ -1127,6 +1243,97 @@ try {
   fail++;
 }
 
+// Security Hotfix v3.0.2 Regression checks
+console.log('\nSecurity Hotfix v3.0.2 Regression checks:');
+
+const tempPolicyDir = join(projectRoot, 'temp-verify-policy');
+const tempPolicySubdir = join(tempPolicyDir, '.ai', 'policies');
+const tempPolicyFile = join(tempPolicySubdir, 'registry-policy.yaml');
+
+try {
+  // Create temporary policy directory and file
+  mkdirSync(tempPolicySubdir, { recursive: true });
+  writeFileSync(tempPolicyFile, 'allow_remote_registries: true\n', 'utf8');
+
+  // 1. registry add rejects malformed URL
+  try {
+    execSync(`node bin/multimodel-dev-os.js registry add testmalformed not-a-url --approved --target "${tempPolicyDir}"`, { cwd: projectRoot, stdio: 'pipe' });
+    console.error(`  ${RED}✗${NC} registry add should have rejected malformed URL`);
+    fail++;
+  } catch (err) {
+    const errText = err.stderr ? err.stderr.toString() : '';
+    if (errText.includes('invalid') || errText.includes('malformed')) {
+      console.log(`  ${GREEN}✓${NC} registry add rejects malformed URL`);
+      pass++;
+    } else {
+      console.error(`  ${RED}✗${NC} registry add malformed URL failed with unexpected error: ${errText}`);
+      fail++;
+    }
+  }
+
+  // 2. registry add rejects URL containing quote/shell-injection characters
+  try {
+    execSync(`node bin/multimodel-dev-os.js registry add testinjection "https://example.com'console.log(1)" --approved --target "${tempPolicyDir}"`, { cwd: projectRoot, stdio: 'pipe' });
+    console.error(`  ${RED}✗${NC} registry add should have rejected URL containing single quote`);
+    fail++;
+  } catch (err) {
+    const errText = err.stderr ? err.stderr.toString() : '';
+    if (errText.includes('quote') || errText.includes('invalid') || errText.includes('metacharacter')) {
+      console.log(`  ${GREEN}✓${NC} registry add rejects URL containing quote/shell-injection characters`);
+      pass++;
+    } else {
+      console.error(`  ${RED}✗${NC} registry add URL with quotes failed with unexpected error: ${errText}`);
+      fail++;
+    }
+  }
+
+  // 3. registry add rejects non-HTTPS remote URL
+  try {
+    execSync(`node bin/multimodel-dev-os.js registry add testnonhttps http://example.com/catalog.yaml --approved --target "${tempPolicyDir}"`, { cwd: projectRoot, stdio: 'pipe' });
+    console.error(`  ${RED}✗${NC} registry add should have rejected non-HTTPS URL`);
+    fail++;
+  } catch (err) {
+    const errText = err.stderr ? err.stderr.toString() : '';
+    if (errText.includes('Only HTTPS is permitted') || errText.includes('protocol') || errText.includes('invalid')) {
+      console.log(`  ${GREEN}✓${NC} registry add rejects non-HTTPS remote URL`);
+      pass++;
+    } else {
+      console.error(`  ${RED}✗${NC} registry add non-HTTPS URL failed with unexpected error: ${errText}`);
+      fail++;
+    }
+  }
+} catch (tempErr) {
+  console.error(`  ${RED}✗${NC} Setting up temporary policy folder failed: ${tempErr.message}`);
+  fail++;
+} finally {
+  // Clean up temporary policy directory
+  try {
+    if (existsSync(tempPolicyDir)) {
+      rmSync(tempPolicyDir, { recursive: true, force: true });
+    }
+  } catch (e) {}
+}
+
+// 4. Codebase structural checks for shell-based fetch URL interpolation
+try {
+  const cliCode = readFileSync(join(projectRoot, 'bin', 'multimodel-dev-os.js'), 'utf8');
+  
+  // Check for mod.get('${targetUrl}') or similar interpolation in node -e
+  const hasUnsafeSync = cliCode.includes("mod.get('${targetUrl}'") || (cliCode.includes('execSync(`node -e "') && cliCode.includes('${targetUrl}'));
+  const usesExecFileSync = cliCode.includes('execFileSync(process.execPath');
+  
+  if (!hasUnsafeSync && usesExecFileSync) {
+    console.log(`  ${GREEN}✓${NC} fetch helper uses execFileSync and does not use shell-based URL interpolation`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} codebase security check failed. Unsafe shell execution or URL interpolation detected.`);
+    fail++;
+  }
+} catch (e) {
+  console.error(`  ${RED}✗${NC} codebase structural check failed: ${e.message}`);
+  fail++;
+}
+
 // Backward compatibility catalog checks
 try {
   const catList = execSync('node bin/multimodel-dev-os.js catalog list', { cwd: projectRoot, encoding: 'utf8' });

package/scripts/verify.sh

@@ -190,8 +190,10 @@ check_file "docs/adapters.md"
 check_file "docs/installers.md"
 check_file "docs/cli-roadmap.md"
 check_file "docs/faq.md"
-check_file "docs/testing-v0.2.md"
+check_file "docs/testing.md"
 check_file "docs/npm-publishing.md"
+check_file "docs/release-policy.md"
+check_file "docs/package-safety.md"
 
 # --- CLI & Packaging Pre-Flight Tests ---
 echo ""
@@ -235,6 +237,14 @@ else
   PASS=$((PASS + 1))
 fi
 
+if ! npm run check:build >/dev/null; then
+  echo -e "  ${RED}✗${NC} Generated CLI is stale. Run npm run build."
+  FAIL=$((FAIL + 1))
+else
+  echo -e "  ${GREEN}✓${NC} Generated CLI is fresh"
+  PASS=$((PASS + 1))
+fi
+
 if ! node bin/multimodel-dev-os.js init --dry-run --force >/dev/null; then
   echo -e "  ${RED}✗${NC} node bin/multimodel-dev-os.js init --dry-run failed"
   FAIL=$((FAIL + 1))

package/src/catalog/loader.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { sourceRoot } from '../core/globals.js';
+import { parseYaml } from '../core/yaml.js';
+import { loadRegistrySources } from '../registry/sources.js';
+import { loadRegistryPolicy } from '../core/policy.js';
+import { validateRegistryUrl } from '../registry/validation.js';
+
+export function loadCatalog(options = {}) {
+  let catalog;
+  if (options.allSources) {
+    catalog = loadAllCatalogs(options);
+  } else if (options.source) {
+    catalog = loadCatalogFromSource(options.source, options);
+  } else {
+    const path = join(sourceRoot, '.ai', 'plugins', 'catalog.yaml');
+    try {
+      if (existsSync(path)) {
+        const reg = parseYaml(readFileSync(path, 'utf8'));
+        catalog = reg.catalog || { plugins: [] };
+      } else {
+        catalog = { plugins: [] };
+      }
+    } catch (e) {
+      catalog = { plugins: [] };
+    }
+    (catalog.plugins || []).forEach(p => { p._source = 'bundled'; });
+  }
+  return catalog;
+}
+
+export function loadCatalogFromSource(source, options = {}) {
+  if (!source || source === 'bundled') {
+    return loadCatalog();
+  } else if (source === 'local') {
+    const localPath = join(options.target || process.cwd(), '.ai', 'plugins', 'catalog.yaml');
+    try {
+      if (existsSync(localPath)) {
+        const reg = parseYaml(readFileSync(localPath, 'utf8'));
+        const catalog = reg.catalog || { plugins: [] };
+        (catalog.plugins || []).forEach(p => { p._source = 'local'; });
+        return catalog;
+      }
+    } catch (e) {}
+    return { plugins: [] };
+  } else if (source.startsWith('remote:')) {
+    const regName = source.substring(7);
+    const sources = loadRegistrySources();
+    const src = sources.find(s => s.name === regName);
+    if (src && src.type !== 'local') {
+      const policy = loadRegistryPolicy(options.target || process.cwd());
+      try {
+        validateRegistryUrl(src.url, policy);
+      } catch (err) {
+        console.error(`\x1b[31mError: Registry '${regName}' has an invalid URL: ${err.message}\x1b[0m`);
+        process.exit(1);
+      }
+    }
+    const cachePath = join(sourceRoot, '.ai', 'registry-cache', regName, 'catalog.yaml');
+    try {
+      if (existsSync(cachePath)) {
+        const reg = parseYaml(readFileSync(cachePath, 'utf8'));
+        const catalog = reg.catalog || { plugins: [] };
+        (catalog.plugins || []).forEach(p => { p._source = `remote:${regName}`; });
+        return catalog;
+      }
+    } catch (e) {}
+    return { plugins: [] };
+  }
+  return { plugins: [] };
+}
+
+export function loadAllCatalogs(options = {}) {
+  const sources = loadRegistrySources();
+  const policy = loadRegistryPolicy(options.target || process.cwd());
+  const allPlugins = [];
+
+  // Always include bundled
+  const bundled = loadCatalog();
+  (bundled.plugins || []).forEach(p => { p._source = 'bundled'; allPlugins.push(p); });
+
+  // Include local workspace catalog if different from bundled
+  const localPath = join(options.target || process.cwd(), '.ai', 'plugins', 'catalog.yaml');
+  if (existsSync(localPath)) {
+    try {
+      const localCat = parseYaml(readFileSync(localPath, 'utf8'));
+      const localPlugins = (localCat.catalog || {}).plugins || [];
+      localPlugins.forEach(p => {
+        if (!allPlugins.some(bp => bp.slug === p.slug)) {
+          p._source = 'local';
+          allPlugins.push(p);
+        }
+      });
+    } catch (e) {}
+  }
+
+  // Include remote caches if policy allows
+  if (policy.allow_remote_registries) {
+    sources.filter(s => s.type !== 'local' && s.enabled).forEach(s => {
+      const cachePath = join(sourceRoot, '.ai', 'registry-cache', s.name, 'catalog.yaml');
+      if (existsSync(cachePath)) {
+        try {
+          const remoteCat = parseYaml(readFileSync(cachePath, 'utf8'));
+          const remotePlugins = (remoteCat.catalog || {}).plugins || [];
+          remotePlugins.forEach(p => {
+            if (!allPlugins.some(bp => bp.slug === p.slug)) {
+              p._source = `remote:${s.name}`;
+              allPlugins.push(p);
+            }
+          });
+        } catch (e) {}
+      }
+    });
+  }
+
+  return { plugins: allPlugins };
+}

package/src/cli/args.js

@@ -0,0 +1,118 @@
+import { resolve } from 'path';
+
+export function parseArgs(args) {
+  const params = {
+    command: null,
+    target: process.cwd(),
+    template: 'general-app',
+    adapters: [],
+    caveman: false,
+    dryRun: false,
+    force: 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,
+    type: 'unknown',
+    tags: '',
+    files: '',
+    title: null,
+    approved: false,
+    intelligence: false,
+    onboarding: false,
+    listActions: false,
+    category: null,
+    source: null,
+    allSources: false
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--target' || arg === '-t') {
+      params.target = resolve(args[++i]);
+    } else if (arg === '--template') {
+      params.template = args[++i];
+    } else if (arg === '--adapter' || arg === '-a') {
+      params.adapters.push(args[++i]);
+    } else if (arg === '--caveman') {
+      params.caveman = true;
+    } else if (arg === '--dry-run' || arg === '-d') {
+      params.dryRun = true;
+    } else if (arg === '--list-actions') {
+      params.listActions = true;
+    } else if (arg === '--force' || arg === '-f') {
+      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 === '--intelligence') {
+      params.intelligence = true;
+    } else if (arg === '--onboarding') {
+      params.onboarding = 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 === '--type') {
+      params.type = args[++i];
+    } else if (arg === '--tags') {
+      params.tags = args[++i];
+    } else if (arg === '--files') {
+      params.files = args[++i];
+    } else if (arg === '--title') {
+      params.title = args[++i];
+    } else if (arg === '--approved') {
+      params.approved = true;
+    } else if (arg === '--category') {
+      params.category = args[++i];
+    } else if (arg === '--source') {
+      params.source = args[++i];
+    } else if (arg === '--all-sources') {
+      params.allSources = true;
+    } else if (!params.command && !arg.startsWith('-')) {
+      params.command = arg;
+    }
+  }
+  return params;
+}
+
+export function getPositionalArgs(args) {
+  const positionalArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--target' || arg === '-t' || arg === '--template' || arg === '--adapter' || arg === '-a' ||
+        arg === '--threshold' || arg === '--registry' || arg === '--model-preset' || arg === '--agent' ||
+        arg === '--stack' || arg === '--mobile' || arg === '--type' || arg === '--tags' || arg === '--files' ||
+        arg === '--title' || arg === '--category') {
+      i++; // skip next arg (its value)
+    } else if (arg.startsWith('-')) {
+      // it's a flag, skip
+    } else {
+      positionalArgs.push(arg);
+    }
+  }
+  return positionalArgs;
+}

package/src/cli/help.js

@@ -0,0 +1,60 @@
+import { version } from '../core/globals.js';
+
+export function showHelp() {
+  console.log(`\n🧠 \x1b[36mmultimodel-dev-os CLI v${version}\x1b[0m`);
+  console.log('====================================');
+  console.log('Usage: node bin/multimodel-dev-os.js <command> [options]\n');
+  console.log('Commands:');
+  console.log('  init              Initialize a project with configs and adapters');
+  console.log('  scan              Scan project structure and framework signals');
+  console.log('  status            Show compact dashboard summarizing repository intelligence state');
+  console.log('  dashboard         Launch the interactive terminal command center (alias: ui)');
+  console.log('  memory <subcmd>   Manage hash-compressed codebase memory (subcmd: build, refresh, diff)');
+  console.log('  feedback <subcmd> Manage developer feedback loops (subcmd: add, list, summarize)');
+  console.log('  improve <subcmd>  Manage codebase self-improvement proposals (subcmd: propose, review, status, validate, diff, apply, log)');
+  console.log('  workflow <subcmd> Orchestrate read-only development workflow pipelines (subcmd: list, show, plan, run)');
+  console.log('  handoff <subcmd>  Compile or print token-compressed agent session summaries (subcmd: build, show)');
+  console.log('  onboard <subcmd>  Safely integrate MultiModel Dev OS into existing repo (subcmd: analyze, recommend, plan, apply, status)');
+  console.log('  adapter <subcmd>  Manage and sync rule/settings files for IDE adapters (subcmd: status, diff, sync)');
+  console.log('  plugin <subcmd>   Manage declarative plugins (subcmd: list, show, validate, install, status)');
+  console.log('  catalog <subcmd>  Manage Workflow Marketplace & Plugin Catalog (subcmd: list, search, show, categories, recommend, install, status)');
+  console.log('  registry <subcmd> Manage trusted remote catalog registries (subcmd: list, add, remove, sync, status, verify, show, cache)');
+  console.log('  verify            Validate structural integrity of an existing project');
+  console.log('  templates         List all built-in template profiles with details');
+  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');
+  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('  --type <type>           Feedback classification (correction, preference, bug, etc.)');
+  console.log('  --tags <list>           Comma-separated descriptor tags for feedback');
+  console.log('  --files <list>          Comma-separated target files for feedback');
+  console.log('  --category <name>       Filter catalog plugins list by category');
+  console.log('  --source <src>          Catalog source filter: bundled, local, or remote:<name>');
+  console.log('  --all-sources           Include all enabled catalog sources in listings');
+  console.log('  --title <text>          Specifies title for codebase improvement proposal');
+  console.log('  --approved              Explicitly approve and execute proposal/onboarding/adapter sync writes');
+  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('  --intelligence          Run diagnostic checkup of repository intelligence config');
+  console.log('  --onboarding            Run diagnostic checkup of repository onboarding setup');
+  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');
+}