skillops-cli 1.2.1 → 1.3.0

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import fs9 from "fs";
-import path9 from "path";
+import fs10 from "fs";
+import path10 from "path";
 import { fileURLToPath, pathToFileURL } from "url";
-import YAML5 from "yaml";
+import YAML6 from "yaml";
 
 // src/auditor/parser.ts
 import fs2 from "fs";
@@ -14,7 +14,7 @@ import path from "path";
 import fs from "fs";
 import YAML from "yaml";
 import { z } from "zod";
-var SKILLOPS_VERSION = "1.2.1";
+var SKILLOPS_VERSION = "1.3.0";
 var SKILL_NAME_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var SEMVER_REGEX = /^\d+\.\d+\.\d+$/;
 var FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -1389,6 +1389,342 @@ function auditCatalog(catalogDir, options = {}) {
 import fs3 from "fs";
 import path2 from "path";
 import YAML2 from "yaml";
+
+// src/ui/terminal.ts
+var ESC = String.fromCharCode(27);
+var ANSI_ESCAPE_REGEX = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
+function isColorEnabled(options) {
+  const env = options?.env ?? process.env;
+  const isTTY = options?.isTTY ?? Boolean(process.stdout?.isTTY);
+  if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") {
+    return false;
+  }
+  if (env.FORCE_COLOR !== void 0) {
+    const val = env.FORCE_COLOR.trim().toLowerCase();
+    if (val === "0" || val === "false") {
+      return false;
+    }
+    if (val === "1" || val === "2" || val === "3" || val === "true") {
+      return true;
+    }
+  }
+  if (env.TERM === "dumb") {
+    return false;
+  }
+  return isTTY;
+}
+function wrapAnsi(openCode, closeCode, text, enabled) {
+  const useColor = enabled ?? isColorEnabled();
+  if (!useColor || text.length === 0) {
+    return text;
+  }
+  return `${ESC}[${openCode}m${text}${ESC}[${closeCode}m`;
+}
+var style = {
+  bold: (text, enabled) => wrapAnsi("1", "22", text, enabled),
+  dim: (text, enabled) => wrapAnsi("2", "22", text, enabled),
+  italic: (text, enabled) => wrapAnsi("3", "23", text, enabled),
+  underline: (text, enabled) => wrapAnsi("4", "24", text, enabled),
+  cyan: (text, enabled) => wrapAnsi("36", "39", text, enabled),
+  green: (text, enabled) => wrapAnsi("32", "39", text, enabled),
+  yellow: (text, enabled) => wrapAnsi("33", "39", text, enabled),
+  red: (text, enabled) => wrapAnsi("31", "39", text, enabled),
+  magenta: (text, enabled) => wrapAnsi("35", "39", text, enabled),
+  blue: (text, enabled) => wrapAnsi("34", "39", text, enabled),
+  gray: (text, enabled) => wrapAnsi("90", "39", text, enabled),
+  white: (text, enabled) => wrapAnsi("37", "39", text, enabled)
+};
+function stripAnsi(text) {
+  return text.replace(ANSI_ESCAPE_REGEX, "");
+}
+function visibleLength(text) {
+  return Array.from(stripAnsi(text)).length;
+}
+function padVisible(text, width, align = "left") {
+  const len = visibleLength(text);
+  if (len >= width) {
+    return text;
+  }
+  const diff = width - len;
+  if (align === "right") {
+    return `${" ".repeat(diff)}${text}`;
+  }
+  if (align === "center") {
+    const left = Math.floor(diff / 2);
+    const right = diff - left;
+    return `${" ".repeat(left)}${text}${" ".repeat(right)}`;
+  }
+  return `${text}${" ".repeat(diff)}`;
+}
+function renderBox(lines, options) {
+  const paddingX = options?.paddingX ?? 2;
+  const minWidth = options?.minWidth ?? 64;
+  const colorEnabled = options?.colorEnabled;
+  const borderFn = options?.borderColor ?? style.cyan;
+  const titleText = options?.title ? ` ${options.title.trim()} ` : "";
+  const titleVisibleLen = visibleLength(titleText);
+  const maxLineLen = lines.reduce(
+    (max, line) => Math.max(max, visibleLength(line)),
+    0
+  );
+  const innerWidth = Math.max(
+    minWidth,
+    maxLineLen + paddingX * 2,
+    titleVisibleLen + 4
+  );
+  const contentWidth = innerWidth - paddingX * 2;
+  const padStr = " ".repeat(paddingX);
+  const topBorder = titleVisibleLen > 0 ? `${borderFn("\u256D\u2500", colorEnabled)}${style.bold(titleText, colorEnabled)}${borderFn(`${"\u2500".repeat(Math.max(1, innerWidth - titleVisibleLen - 1))}\u256E`, colorEnabled)}` : borderFn(`\u256D${"\u2500".repeat(innerWidth)}\u256E`, colorEnabled);
+  const bodyLines = lines.map((line) => {
+    const padded = padVisible(line, contentWidth, "left");
+    return `${borderFn("\u2502", colorEnabled)}${padStr}${padded}${padStr}${borderFn("\u2502", colorEnabled)}`;
+  });
+  const bottomBorder = borderFn(`\u2570${"\u2500".repeat(innerWidth)}\u256F`, colorEnabled);
+  return [topBorder, ...bodyLines, bottomBorder].join("\n");
+}
+function renderHeaderBanner(subtitle = "Framework & Library for High-End AI Coding Skills & Subagents", options) {
+  const ver = options?.version ?? SKILLOPS_VERSION;
+  const c = options?.colorEnabled;
+  const headline = `${style.bold(style.cyan(`\u26A1 SkillOps v${ver}`, c), c)} ${style.dim("\u2014", c)} ${subtitle}`;
+  return renderBox([headline], {
+    borderColor: style.cyan,
+    paddingX: 2,
+    minWidth: 72,
+    colorEnabled: c
+  });
+}
+function renderTable(headers, rows, options) {
+  const indent = " ".repeat(options?.indent ?? 2);
+  const c = options?.colorEnabled;
+  const colCount = headers.length;
+  const widths = headers.map((h) => visibleLength(h));
+  for (const row of rows) {
+    for (let i = 0; i < colCount; i++) {
+      const cell = row[i] ?? "";
+      widths[i] = Math.max(widths[i] ?? 0, visibleLength(cell));
+    }
+  }
+  const aligns = options?.align ?? headers.map(() => "left");
+  const headerLine = headers.map(
+    (h, i) => style.bold(
+      style.cyan(padVisible(h, widths[i] ?? 0, aligns[i] ?? "left"), c),
+      c
+    )
+  ).join("  ");
+  const separatorLine = widths.map((w) => style.dim("\u2500".repeat(Math.max(1, w)), c)).join("  ");
+  const bodyLines = rows.map(
+    (row) => headers.map(
+      (_, i) => padVisible(row[i] ?? "", widths[i] ?? 0, aligns[i] ?? "left")
+    ).join("  ")
+  );
+  return [
+    `${indent}${headerLine}`,
+    `${indent}${separatorLine}`,
+    ...bodyLines.map((line) => `${indent}${line}`)
+  ].join("\n");
+}
+function renderTokenBar(current, max, options) {
+  const width = options?.width ?? 18;
+  const unit = options?.unit ?? "tokens";
+  const c = options?.colorEnabled;
+  const safeMax = max > 0 ? max : 1;
+  const ratio = Math.max(0, current / safeMax);
+  const clampedRatio = Math.min(1, ratio);
+  const filledCount = Math.round(clampedRatio * width);
+  const emptyCount = Math.max(0, width - filledCount);
+  const colorFn = ratio > 1 ? style.red : ratio > 0.85 ? style.yellow : style.green;
+  const filledStr = colorFn("\u2588".repeat(filledCount), c);
+  const emptyStr = style.dim("\u2591".repeat(emptyCount), c);
+  const pctStr = `${(ratio * 100).toFixed(1)}%`;
+  const prefix = options?.label ? `${style.bold(options.label, c)} ` : "";
+  return `${prefix}[${filledStr}${emptyStr}] ${style.bold(pctStr, c)} (${current} / ${max} ${unit})`;
+}
+var renderProgressBar = renderTokenBar;
+function renderSectionHeader(title, colorEnabled) {
+  const c = colorEnabled;
+  return `
+  ${style.bold(style.cyan(title, c), c)}
+  ${style.dim("\u2500".repeat(Math.max(24, visibleLength(title))), c)}`;
+}
+function formatBadge(type, customLabel, colorEnabled) {
+  switch (type) {
+    case "pass":
+      return style.bold(
+        style.green(`\u2714 ${customLabel ?? "PASS"}`, colorEnabled),
+        colorEnabled
+      );
+    case "warn":
+      return style.bold(
+        style.yellow(`\u26A0 ${customLabel ?? "WARN"}`, colorEnabled),
+        colorEnabled
+      );
+    case "fail":
+      return style.bold(
+        style.red(`\u2716 ${customLabel ?? "FAIL"}`, colorEnabled),
+        colorEnabled
+      );
+    case "info":
+      return style.bold(
+        style.cyan(`\u2139 ${customLabel ?? "INFO"}`, colorEnabled),
+        colorEnabled
+      );
+    case "skill":
+      return style.bold(
+        style.cyan(`[${customLabel ?? "SKILL"}]`, colorEnabled),
+        colorEnabled
+      );
+    case "subagent":
+      return style.bold(
+        style.magenta(`[${customLabel ?? "SUBAGENT"}]`, colorEnabled),
+        colorEnabled
+      );
+  }
+}
+function renderStep(step, total, title, detail, status = "done", colorEnabled) {
+  const icon = status === "done" ? style.green("\u2714", colorEnabled) : status === "warn" ? style.yellow("\u26A0", colorEnabled) : style.dim("\u25CB", colorEnabled);
+  const stepBadge = style.dim(`[${step}/${total}]`, colorEnabled);
+  const titleStyled = style.bold(padVisible(title, 28, "left"), colorEnabled);
+  const detailStyled = detail ? ` ${style.dim("\u2022", colorEnabled)} ${detail}` : "";
+  return `  ${icon} ${stepBadge} ${titleStyled}${detailStyled}`;
+}
+function renderNextSteps(hints, colorEnabled) {
+  if (hints.length === 0) {
+    return "";
+  }
+  const c = colorEnabled;
+  const maxCmdLen = hints.reduce(
+    (m, h) => Math.max(m, visibleLength(h.command)),
+    0
+  );
+  const lines = [
+    "",
+    `  ${style.bold(style.cyan("\u{1F4A1} Next Steps:", c), c)}`,
+    ...hints.map(
+      (h) => `     ${style.green(padVisible(h.command, maxCmdLen + 2, "left"), c)} ${style.dim(`# ${h.description}`, c)}`
+    ),
+    ""
+  ];
+  return lines.join("\n");
+}
+function renderAiUsageGuide(targets, skills, subagents, colorEnabled) {
+  const c = colorEnabled;
+  const sampleSkill = skills[0] ?? "systematic-debugging";
+  const sampleAgent = subagents[0] ?? "context-scout";
+  const lines = [
+    `${style.bold("How to use your installed Skills & Subagents inside your AI:", c)}`,
+    ""
+  ];
+  const targetSet = new Set(targets);
+  if (targetSet.has("claude") || targetSet.size === 0) {
+    lines.push(
+      `\u2022 ${style.bold("Claude Code:", c)} Ask naturally (auto-routed via .claude/skills/${sampleSkill}/SKILL.md) or delegate to @${sampleAgent}`
+    );
+  }
+  if (targetSet.has("cursor")) {
+    lines.push(
+      `\u2022 ${style.bold("Cursor IDE:", c)} Type ${style.cyan(`@${sampleSkill}`, c)} in Cursor Chat/Composer or let .cursor/rules/${sampleSkill}.mdc auto-attach`
+    );
+  }
+  if (targetSet.has("antigravity")) {
+    lines.push(
+      `\u2022 ${style.bold("Antigravity / Gemini:", c)} Auto-activated from .agent/skills/${sampleSkill}/SKILL.md when your prompt matches its domain`
+    );
+  }
+  if (targetSet.has("copilot")) {
+    lines.push(
+      `\u2022 ${style.bold("GitHub Copilot:", c)} Use ${style.cyan(`/${sampleSkill}`, c)} prompt in Copilot Chat or reference .github/instructions/${sampleSkill}.instructions.md`
+    );
+  }
+  if (targetSet.has("windsurf") || targetSet.has("cline") || targetSet.has("roocode") || targetSet.has("kilocode")) {
+    lines.push(
+      `\u2022 ${style.bold("Windsurf / Cline / Roo / Kilo:", c)} Rules in .windsurf/rules/, .clinerules/, .roo/rules/, .kilocode/rules/ activate automatically`
+    );
+  }
+  lines.push(
+    `\u2022 ${style.bold("Inspect any Skill/Agent:", c)} Run ${style.green(`npx skillops-cli info ${sampleSkill}`, c)} to view triggers, L3 scripts & prompts`
+  );
+  return renderBox(lines, {
+    title: "\u{1F680} Using Your Skills & Subagents",
+    borderColor: style.green,
+    paddingX: 2,
+    minWidth: 72,
+    colorEnabled: c
+  });
+}
+function levenshteinDistance(a, b) {
+  const s1 = a.toLowerCase();
+  const s2 = b.toLowerCase();
+  const m = s1.length;
+  const n = s2.length;
+  let prevRow = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const currRow = [i];
+    for (let j = 1; j <= n; j++) {
+      const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+      const deletion = (prevRow[j] ?? 0) + 1;
+      const insertion = (currRow[j - 1] ?? 0) + 1;
+      const substitution = (prevRow[j - 1] ?? 0) + cost;
+      currRow[j] = Math.min(deletion, insertion, substitution);
+    }
+    prevRow = currRow;
+  }
+  return prevRow[n] ?? 0;
+}
+var DEFAULT_VALID_COMMANDS = [
+  "quickstart",
+  "setup",
+  "init",
+  "list",
+  "search",
+  "find",
+  "info",
+  "show",
+  "inspect",
+  "add",
+  "install",
+  "remove",
+  "uninstall",
+  "rm",
+  "clean",
+  "create",
+  "new",
+  "harnesses",
+  "doctor",
+  "status",
+  "tokens",
+  "budget",
+  "audit",
+  "route",
+  "recommend",
+  "sync",
+  "eval",
+  "mcp",
+  "mcp-setup"
+];
+function suggestCommand(unknownCommand, validCommands = DEFAULT_VALID_COMMANDS) {
+  const needle = unknownCommand.trim().toLowerCase();
+  if (!needle) {
+    return null;
+  }
+  for (const candidate of validCommands) {
+    if (candidate.startsWith(needle) || needle.startsWith(candidate)) {
+      return candidate;
+    }
+  }
+  let bestMatch = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of validCommands) {
+    const dist = levenshteinDistance(needle, candidate);
+    if (dist < bestDistance) {
+      bestDistance = dist;
+      bestMatch = candidate;
+    }
+  }
+  const maxAllowedDistance = Math.max(2, Math.floor(needle.length * 0.45));
+  return bestDistance <= maxAllowedDistance ? bestMatch : null;
+}
+
+// src/auditor/token_economy.ts
 var ALWAYS_ON_INSTRUCTION_CANDIDATES = [
   "CLAUDE.md",
   ".claude/CLAUDE.md",
@@ -1533,7 +1869,9 @@ function analyzeRepoTokenEconomy(repoPath, options = {}) {
   ];
   for (const ruleGroup of scopedRuleDirs) {
     if (fs3.existsSync(ruleGroup.dirPath) && fs3.statSync(ruleGroup.dirPath).isDirectory()) {
-      const entries = fs3.readdirSync(ruleGroup.dirPath, { withFileTypes: true }).filter((e) => e.isFile() && (e.name.endsWith(".mdc") || e.name.endsWith(".md"))).sort((a, b) => a.name.localeCompare(b.name));
+      const entries = fs3.readdirSync(ruleGroup.dirPath, { withFileTypes: true }).filter(
+        (e) => e.isFile() && (e.name.endsWith(".mdc") || e.name.endsWith(".md"))
+      ).sort((a, b) => a.name.localeCompare(b.name));
       for (const entry of entries) {
         const fullPath = path2.join(ruleGroup.dirPath, entry.name);
         const relPath = `${ruleGroup.relPrefix}/${entry.name}`;
@@ -1670,7 +2008,11 @@ function analyzeRepoTokenEconomy(repoPath, options = {}) {
     0,
     monolithicEquivalentTokens - progressiveDisclosureL1Tokens
   );
-  const tokenSavingsPct = monolithicEquivalentTokens > 0 ? Number((estimatedTokensSaved / monolithicEquivalentTokens * 100).toFixed(2)) : 0;
+  const tokenSavingsPct = monolithicEquivalentTokens > 0 ? Number(
+    (estimatedTokensSaved / monolithicEquivalentTokens * 100).toFixed(
+      2
+    )
+  ) : 0;
   return TokenEconomyReportSchema.parse({
     repo_path: resolvedRepo.replace(/\\/g, "/"),
     catalog_path: resolvedCatalog.replace(/\\/g, "/"),
@@ -1742,9 +2084,15 @@ function formatTokenEconomyReport(report, format = "table") {
     return `${lines2.join("\n")}
 `;
   }
+  const startupBar = renderProgressBar(
+    report.startup_token_tax,
+    report.startup_tax_budget,
+    { width: 18, unit: "tokens" }
+  );
   const lines = [
     "=== SkillOps Token Economy & Startup Context Tax Analyzer ===",
     `Startup Token Tax        : ${report.startup_token_tax} / ${report.startup_tax_budget} tokens [${report.passed_budget ? "PASS" : "OVER BUDGET"}]`,
+    `Startup Budget Meter     : ${startupBar}`,
     `Monolithic Equivalent    : ${report.monolithic_equivalent_tokens} tokens`,
     `Progressive L1 Footprint : ${report.progressive_disclosure_l1_tokens} tokens`,
     `Token Savings            : ${report.estimated_tokens_saved} tokens (${report.token_savings_pct.toFixed(2)}% saved)`,
@@ -1760,6 +2108,18 @@ function formatTokenEconomyReport(report, format = "table") {
       );
     }
   }
+  lines.push(
+    renderNextSteps([
+      {
+        command: "npx skillops-cli quickstart",
+        description: "Sync Progressive Disclosure Skills & Context-Isolated Subagents"
+      },
+      {
+        command: "npx skillops-cli doctor",
+        description: "Inspect repository lockfile & startup tax diagnostics"
+      }
+    ]).trimEnd()
+  );
   return `${lines.join("\n")}
 `;
 }
@@ -2368,6 +2728,11 @@ ${rows}
   ].join("\n");
 }
 
+// src/framework/index.ts
+import fs9 from "fs";
+import path9 from "path";
+import YAML5 from "yaml";
+
 // src/mcp/index.ts
 import fs7 from "fs";
 import path7 from "path";
@@ -2639,7 +3004,10 @@ function scoreSkillAgainstProfile(parsedSkill, profile, taskPrompt = "") {
       matchedSignals.push(`lang:${lang}`);
     }
   }
-  for (const dep of [...manifest.routing_signals.dependencies_any, ...manifest.tags]) {
+  for (const dep of [
+    ...manifest.routing_signals.dependencies_any,
+    ...manifest.tags
+  ]) {
     const lowerDep = dep.toLowerCase();
     const depTokens = tokenizeRoutingText(lowerDep);
     if (repoSignalSet.has(lowerDep) || depTokens.some((t) => repoSignalSet.has(t))) {
@@ -2676,7 +3044,9 @@ function compileSkillBundle(profile, catalogDir, options = {}) {
   const taskPrompt = options.taskPrompt ?? "";
   const resolvedCatalog = path6.resolve(catalogDir);
   const skillDirs = discoverSkillDirectories(resolvedCatalog);
-  const parsedSkills = skillDirs.map((dir) => parseSkillDirectory(dir, { requireLayout: false }));
+  const parsedSkills = skillDirs.map(
+    (dir) => parseSkillDirectory(dir, { requireLayout: false })
+  );
   const featureVectors = /* @__PURE__ */ new Map();
   for (const p of parsedSkills) {
     featureVectors.set(p.manifest.name, extractSkillFeatures(p.manifest));
@@ -2792,7 +3162,7 @@ function routeRepository(repoPath, catalogDir, options = {}) {
   const profile = fingerprintRepository(repoPath);
   return compileSkillBundle(profile, catalogDir, options);
 }
-function formatRoutedBundle(bundle, format = "table") {
+function formatRoutedBundle(bundle, format = "table", colorEnabled) {
   if (format === "json") {
     return `${JSON.stringify(bundle, null, 2)}
 `;
@@ -2815,16 +3185,40 @@ function formatRoutedBundle(bundle, format = "table") {
       ""
     ].join("\n");
   }
+  const topSkill = bundle.selected_skills[0]?.name ?? "security-sast-gate";
+  const l1Bar = renderProgressBar(
+    bundle.total_l1_tokens,
+    bundle.max_l1_tokens,
+    {
+      width: 18,
+      unit: "tokens",
+      colorEnabled
+    }
+  );
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: "npx skillops-cli quickstart",
+        description: "Install this recommended bundle & wire MCP in 1 step"
+      },
+      {
+        command: `npx skillops-cli info ${topSkill}`,
+        description: `Inspect ${topSkill} triggers, L3 scripts & AI invocation guide`
+      }
+    ],
+    colorEnabled
+  );
   return [
     "=== SkillOps Context-Aware Router ===",
     `Repo       : ${bundle.repo_profile.repo_path}`,
     `Stack      : languages=[${bundle.repo_profile.languages.join(", ")}] frameworks=[${bundle.repo_profile.frameworks.join(", ")}] db=[${bundle.repo_profile.databases.join(", ")}]`,
     `Selected   : ${bundle.selected_skills.length}/${bundle.max_skills} skills (${bundle.total_l1_tokens}/${bundle.max_l1_tokens} L1 tokens, max cosine=${bundle.max_pairwise_similarity.toFixed(4)})`,
+    `L1 Budget  : ${l1Bar}`,
     `Subagents  : ${bundle.recommended_subagents.join(", ") || "none"}`,
     ...bundle.selected_skills.map(
       (s) => `  + ${s.name} [${s.track}] score=${s.relevance_score} (${s.l1_tokens} L1 tokens) signals=[${s.matched_signals.join(", ")}]`
     ),
-    ""
+    nextSteps
   ].join("\n");
 }
 
@@ -3701,8 +4095,12 @@ function applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle,
       total_l1_tokens: routedBundle.total_l1_tokens,
       artifacts: newLockArtifacts
     });
-    fs8.writeFileSync(lockfilePath, `${JSON.stringify(lockData, null, 2)}
-`, "utf-8");
+    fs8.writeFileSync(
+      lockfilePath,
+      `${JSON.stringify(lockData, null, 2)}
+`,
+      "utf-8"
+    );
   }
   return SyncReportSchema.parse({
     repo_path: resolvedRepo.replace(/\\/g, "/"),
@@ -3753,15 +4151,26 @@ function syncRepository(repoPath, catalogDir, options = {}) {
         target: "codex",
         itemName: "codex-agents-index",
         relativePath: "AGENTS.md",
-        content: renderCodexAgentsIndex(existingAgentsMd, selectedSkills, selectedSubagents)
+        content: renderCodexAgentsIndex(
+          existingAgentsMd,
+          selectedSkills,
+          selectedSubagents
+        )
       });
     }
   }
-  return applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle, plannedFiles, {
-    dryRun,
-    force,
-    preserveUnlistedLockEntries: false
-  });
+  return applyPlannedFiles(
+    resolvedRepo,
+    resolvedCatalog,
+    targets,
+    routedBundle,
+    plannedFiles,
+    {
+      dryRun,
+      force,
+      preserveUnlistedLockEntries: false
+    }
+  );
 }
 function addSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
   const resolvedRepo = path8.resolve(repoPath);
@@ -3805,15 +4214,24 @@ function addSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
       plannedFiles.push(...renderSkillFilesForRuntime(matchedSkill, target));
     }
     if (matchedSubagent) {
-      plannedFiles.push(...renderSubagentFilesForRuntime(matchedSubagent, target));
+      plannedFiles.push(
+        ...renderSubagentFilesForRuntime(matchedSubagent, target)
+      );
     }
   }
   const routedBundle = routeRepository(resolvedRepo, resolvedCatalog);
-  return applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle, plannedFiles, {
-    dryRun,
-    force,
-    preserveUnlistedLockEntries: true
-  });
+  return applyPlannedFiles(
+    resolvedRepo,
+    resolvedCatalog,
+    targets,
+    routedBundle,
+    plannedFiles,
+    {
+      dryRun,
+      force,
+      preserveUnlistedLockEntries: true
+    }
+  );
 }
 function pruneEmptyParentDirs(filePath, stopAtRepoRoot) {
   const normalizedStop = path8.resolve(stopAtRepoRoot);
@@ -3867,7 +4285,9 @@ function removeSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
       `No synced artifacts found for '${itemName}' in .skillops-lock.json.`
     );
   }
-  const newLockArtifacts = { ...existingLock.artifacts };
+  const newLockArtifacts = {
+    ...existingLock.artifacts
+  };
   const artifacts = [];
   const driftConflicts = [];
   for (const [relPath, entry] of matchingEntries) {
@@ -3913,8 +4333,12 @@ function removeSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
       selected_subagents: updatedSubagents,
       artifacts: newLockArtifacts
     });
-    fs8.writeFileSync(lockfilePath, `${JSON.stringify(lockData, null, 2)}
-`, "utf-8");
+    fs8.writeFileSync(
+      lockfilePath,
+      `${JSON.stringify(lockData, null, 2)}
+`,
+      "utf-8"
+    );
   }
   const routedBundle = routeRepository(resolvedRepo, resolvedCatalog);
   return SyncReportSchema.parse({
@@ -4009,7 +4433,7 @@ function cleanSyncedArtifacts(repoPath, catalogDir, options = {}) {
     passed: driftConflicts.length === 0
   });
 }
-function formatSyncReport(report, format = "table") {
+function formatSyncReport(report, format = "table", colorEnabled) {
   if (format === "json") {
     return `${JSON.stringify(report, null, 2)}
 `;
@@ -4031,6 +4455,38 @@ function formatSyncReport(report, format = "table") {
       ""
     ].join("\n");
   }
+  const c = colorEnabled;
+  const activeArtifacts = report.artifacts.filter(
+    (a) => a.action === "created" || a.action === "updated" || a.action === "unchanged"
+  );
+  const firstSkill = activeArtifacts.find((a) => a.skill_name !== "codex-agents-index")?.skill_name ?? report.routed_bundle.selected_skills[0]?.name ?? "security-sast-gate";
+  const usageBox = activeArtifacts.length > 0 ? renderBox(
+    [
+      `${style.bold("How to use your installed Skills & Subagents inside your AI:", c)}`,
+      `  \u2022 ${style.cyan("Claude Code / Antigravity:", c)} Ask naturally (auto-routed via SKILL.md) or delegate to a Subagent`,
+      `  \u2022 ${style.cyan("Cursor / Windsurf / Cline / Copilot:", c)} Reference ${style.green(`@${firstSkill}`, c)} in Chat or let rules auto-attach`,
+      `  \u2022 ${style.cyan("Deep-Inspect:", c)} Run ${style.green(`npx skillops-cli info ${firstSkill}`, c)} to view triggers & Level 3 scripts`
+    ],
+    {
+      title: "\u{1F680} Using Your Skills & Subagents",
+      borderColor: style.cyan,
+      minWidth: 74,
+      colorEnabled: c
+    }
+  ) : "";
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli info ${firstSkill}`,
+        description: "Inspect triggers, token budget & Level 3 scripts"
+      },
+      {
+        command: "npx skillops-cli doctor",
+        description: "Verify lockfile SHA-256 integrity & Startup Token Tax"
+      }
+    ],
+    c
+  );
   return [
     "=== SkillOps Multi-Runtime Transpiler & Sync Engine ===",
     `Repo       : ${report.repo_path}`,
@@ -4040,180 +4496,1810 @@ function formatSyncReport(report, format = "table") {
       (a) => `  [${a.action.toUpperCase()}] (${a.target}) ${a.relative_path}`
     ),
     ...report.drift_conflicts.map(
-      (c) => `  [DRIFT CONFLICT] ${c} modified locally. Re-run with --force to overwrite.`
+      (cItem) => `  [DRIFT CONFLICT] ${cItem} modified locally. Re-run with --force to overwrite.`
     ),
-    ""
-  ].join("\n");
+    usageBox,
+    nextSteps
+  ].filter(Boolean).join("\n");
 }
 
-// src/cli.ts
-var PACKAGE_ROOT = path9.resolve(path9.dirname(fileURLToPath(import.meta.url)), "..");
-function resolveCatalogDir(args, repoPath, loadedConfig) {
-  const catalogIdx = args.indexOf("--catalog");
-  if (catalogIdx !== -1 && args[catalogIdx + 1]) {
-    return path9.resolve(args[catalogIdx + 1]);
-  }
-  const baseRepo = repoPath ? path9.resolve(repoPath) : process.cwd();
-  if (loadedConfig?.catalog_dir) {
-    const cfgCatalog = path9.resolve(baseRepo, loadedConfig.catalog_dir);
-    if (fs9.existsSync(cfgCatalog)) {
-      return cfgCatalog;
-    }
-  }
-  if (repoPath) {
-    const repoCatalog = path9.join(path9.resolve(repoPath), "catalog");
-    if (fs9.existsSync(repoCatalog)) {
-      return repoCatalog;
-    }
-  }
-  const cwdCatalog = path9.resolve(process.cwd(), "catalog");
-  if (fs9.existsSync(cwdCatalog)) {
-    return cwdCatalog;
-  }
-  return path9.join(PACKAGE_ROOT, "catalog");
-}
-function runCli(argv) {
-  const args = argv.slice(2);
-  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(
-      [
-        `SkillOps v${SKILLOPS_VERSION} \u2014 The Zero-API NPX Engine for High-End AI Skills & Subagents`,
-        "",
-        "Usage: npx skillops@latest <command> [options]",
-        "",
-        "Commands:",
-        "  init      Scaffold .skillops.yml and detect repository agent harnesses",
-        "  list      Browse bundled high-end Skills & Subagents with token budgets",
-        "  add       Install a specific high-end Skill or Subagent into active runtimes",
-        "  remove    Surgically uninstall a synced Skill or Subagent from active runtimes",
-        "  clean     Remove all SkillOps-managed runtime artifacts tracked in .skillops-lock.json",
-        "  harnesses List all 20 supported AI coding agents, target paths, MCP support & repo detection",
-        "  doctor    Diagnose Node/Python environment, .skillops.yml config & lockfile SHA-256 drift",
-        "  status    Alias for 'doctor' \u2014 inspect repository lockfile drift and token tax status",
-        "  tokens    Analyze repository Startup Token Tax and Progressive Disclosure savings",
-        "  audit     Run L1/L2/L3 token budget linter, Subagent check & collision matrix",
-        "  route     Fingerprint repository stack and compile optimal <=12 skill bundle",
-        "  sync      Transpile Skills & Subagents across all 20 AI coding agents (Claude, Cursor, Windsurf, etc.)",
-        "  eval      Execute zero-API deterministic TDD benchmarks (with_skill vs without_skill)",
-        "  mcp       Start native JSON-RPC 2.0 stdio Model Context Protocol server",
-        "  mcp-setup Register SkillOps MCP server across all MCP-compatible AI coding IDEs & agents",
-        ""
-      ].join("\n")
-    );
-    return ExitCode.SUCCESS;
-  }
-  if (args.includes("--version") || args.includes("-V") || args[0] === "version") {
-    process.stdout.write(`skillops ${SKILLOPS_VERSION}
-`);
-    return ExitCode.SUCCESS;
-  }
-  const command = args[0];
-  if (command === "init") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = path9.resolve(
-      repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd()
-    );
-    const catalogDir = resolveCatalogDir(args, repoPath);
-    const profile = fingerprintRepository(repoPath);
-    const targetsIdx = args.indexOf("--targets");
-    const initTargets = targetsIdx !== -1 && args[targetsIdx + 1] ? resolveRuntimeTargets(args[targetsIdx + 1], repoPath) : profile.detected_harnesses.length > 0 ? profile.detected_harnesses : [...CORE_RUNTIME_TARGETS];
-    const configPayload = SkillOpsConfigSchema.parse({
-      version: "1.0",
-      catalog_dir: path9.relative(repoPath, catalogDir).replace(/\\/g, "/") || "catalog",
-      token_economy: {
-        startup_tax_budget: 2500,
-        max_active_skills: 12,
-        max_l1_tokens: 1500,
-        max_similarity: 0.78
+// src/ui/help.ts
+var COMMAND_HELP_SPECS = [
+  {
+    name: "quickstart",
+    aliases: ["setup"],
+    pillar: "library",
+    summary: "1-step onboarding: detect project stack, route optimal Skills & Subagents, sync to AI harnesses & wire MCP",
+    usage: "npx skillops-cli quickstart [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Target repository directory (default: current directory)"
       },
-      detected_stack: {
-        languages: profile.languages,
-        frameworks: profile.frameworks
+      {
+        flags: "--harness, --targets, -t <list|auto|all>",
+        description: "Target AI coding harnesses (e.g. claude,cursor,windsurf or auto/all)"
       },
-      targets: initTargets
-    });
-    const configPath = path9.join(repoPath, ".skillops.yml");
-    fs9.mkdirSync(repoPath, { recursive: true });
-    fs9.writeFileSync(configPath, YAML5.stringify(configPayload), "utf-8");
-    process.stdout.write(
-      `Initialized SkillOps configuration at ${configPath.replace(/\\/g, "/")}
-`
-    );
-    return ExitCode.SUCCESS;
-  }
-  if (command === "list") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
-    const cfgRes = loadSkillOpsConfig(repoPath);
-    if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
-      return ExitCode.BUDGET_OR_CONTRACT_ERROR;
-    }
-    const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
-    const summary = auditCatalogTokenBudgets(catalogDir, { requireLayout: false });
-    if (rawFormat === "json") {
-      process.stdout.write(`${JSON.stringify(summary, null, 2)}
-`);
-      return ExitCode.SUCCESS;
-    }
-    if (rawFormat === "markdown") {
-      const lines2 = [
-        "## SkillOps Catalog \u2014 High-End Skills & Context-Isolated Subagents",
-        "",
-        "### Hybrid Executable Skills (`INV-SKILL-01` .. `03`)",
-        "",
-        "| Skill | L1 Tokens | L2 Lines | L2 Tokens | Scripts |Savings |",
-        "| :--- | ---: | ---: | ---: | ---: | ---: |",
-        ...summary.skills.map((s) => {
-          const totalRaw = s.l1Tokens + s.l2Tokens;
-          const savingsPct = totalRaw > 0 ? ((totalRaw - s.l1Tokens) / totalRaw * 100).toFixed(1) : "0.0";
-          return `| \`${s.skillName}\` | ${s.l1Tokens} | ${s.l2Lines} | ${s.l2Tokens} | ${s.scriptsCount} | ${savingsPct}% |`;
-        }),
-        "",
-        "### Context-Isolated Subagents (`INV-SKILL-04`)",
-        "",
-        "| Subagent | Prompt Tokens | Max Output Tokens | Tools |",
-        "| :--- | ---: | ---: | ---: |",
-        ...summary.subagents.map(
-          (a) => `| \`${a.subagentName}\` | ${a.systemPromptTokens} | <= ${a.maxOutputTokens} | ${a.tools.length} |`
-        ),
-        ""
-      ];
-      process.stdout.write(lines2.join("\n"));
-      return ExitCode.SUCCESS;
-    }
-    const lines = [
-      `=== SkillOps Catalog (v${SKILLOPS_VERSION}) ===`,
-      `Skills (${summary.skills.length}) \u2014 Total L1 Routing Tax: ${summary.totalL1Tokens} tokens`,
-      ...summary.skills.map(
-        (s) => `  [SKILL] ${s.skillName} \u2014 L1: ${s.l1Tokens}t | L2: ${s.l2Lines} lines (${s.l2Tokens}t) | L3 Scripts: ${s.scriptsCount}`
-      ),
-      `Subagents (${summary.subagents.length}) \u2014 Context-Isolated Specialist Agents:`,
-      ...summary.subagents.map(
-        (a) => `  [SUBAGENT] ${a.subagentName} (prompt=${a.systemPromptTokens}t, max_out<=${a.maxOutputTokens}t, tools=${a.tools.length})`
-      ),
-      ""
-    ];
-    process.stdout.write(lines.join("\n"));
-    return ExitCode.SUCCESS;
-  }
-  if (command === "audit") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
-    const cfgRes = loadSkillOpsConfig(repoPath);
+      {
+        flags: "--top, --max-skills <n>",
+        description: "Maximum number of Skills to activate in the bundle (default: 12)"
+      },
+      {
+        flags: "--skip-mcp, --no-mcp",
+        description: "Skip automatic MCP server registration"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview planned changes without writing files to disk"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite locally modified artifacts if drift is detected"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output report format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli quickstart",
+        description: "Auto-detect stack & harnesses, install optimal Skills/Subagents, and configure MCP"
+      },
+      {
+        command: "npx skillops-cli quickstart --harness cursor,claude --top 6",
+        description: "Quickstart specifically for Cursor and Claude Code with top 6 Skills"
+      }
+    ]
+  },
+  {
+    name: "list",
+    aliases: [],
+    pillar: "library",
+    summary: "Browse all bundled Hybrid Executable Skills & Context-Isolated Subagents with token budgets",
+    usage: "npx skillops-cli list [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Custom catalog directory to list"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli list",
+        description: "Display all 10 Skills and 9 Subagents with L1/L2 token footprints"
+      },
+      {
+        command: "npx skillops-cli info security-sast-gate",
+        description: "Deep-inspect a specific Skill from the Library after listing"
+      }
+    ]
+  },
+  {
+    name: "search",
+    aliases: ["find"],
+    pillar: "library",
+    summary: "Search the Library of Skills & Subagents by keyword, domain, framework, or routing signal",
+    usage: "npx skillops-cli search <query> [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Custom catalog directory to search"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli search security",
+        description: "Find Skills and Subagents matching security/SAST/OWASP signals"
+      },
+      {
+        command: "npx skillops-cli find postgres",
+        description: "Find database & PostgreSQL optimization Skills in the Library"
+      }
+    ]
+  },
+  {
+    name: "info",
+    aliases: ["show", "inspect"],
+    pillar: "library",
+    summary: "Inspect a Skill or Subagent's L1 routing triggers, L2 token budget, L3 scripts & how to use it in your AI",
+    usage: "npx skillops-cli info <skill-or-subagent-name> [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Custom catalog directory"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli info bug-reproducer-tdd",
+        description: "Inspect routing triggers, L3 scripts & IDE invocation guide for bug-reproducer-tdd"
+      },
+      {
+        command: "npx skillops-cli show red-team-breaker",
+        description: "Inspect the red-team-breaker Context-Isolated Subagent card"
+      }
+    ]
+  },
+  {
+    name: "add",
+    aliases: ["install", "i"],
+    pillar: "library",
+    summary: "Install one or more Skills or Subagents into your active AI coding harnesses",
+    usage: "npx skillops-cli add <name...> [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "--harness, --targets, -t <list|auto|all>",
+        description: "Target AI coding harnesses (e.g. claude,cursor,windsurf or all)"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview planned file writes without modifying disk"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite locally drifted files"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli install security-sast-gate",
+        description: "Install the security-sast-gate Skill into configured/default harnesses"
+      },
+      {
+        command: "npx skillops-cli add mcp-architect context-scout --harness claude,cursor",
+        description: "Install both a Skill and a Subagent into Claude & Cursor"
+      }
+    ]
+  },
+  {
+    name: "remove",
+    aliases: ["uninstall", "rm"],
+    pillar: "library",
+    summary: "Surgically uninstall a synced Skill or Subagent from active AI harnesses",
+    usage: "npx skillops-cli remove <name...> [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "--harness, --targets, -t <list>",
+        description: "Restrict removal to specific harnesses"
+      },
+      {
+        flags: "--force",
+        description: "Remove even if local SHA-256 drift is detected"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli uninstall mcp-architect",
+        description: "Remove all transpiled runtime files for mcp-architect and update .skillops-lock.json"
+      }
+    ]
+  },
+  {
+    name: "route",
+    aliases: ["recommend"],
+    pillar: "library",
+    summary: "Fingerprint repository stack and recommend the optimal collision-free <=12 Skill bundle",
+    usage: "npx skillops-cli recommend [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Repository directory to fingerprint"
+      },
+      {
+        flags: "--task <prompt>",
+        description: "Optional natural-language task prompt to boost task-specific Skills"
+      },
+      {
+        flags: "--top, --max-skills <n>",
+        description: "Maximum Skills to select (default: 12)"
+      },
+      {
+        flags: "--max-l1-tokens <n>",
+        description: "Maximum total L1 routing token budget (default: 1500)"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli recommend",
+        description: "Recommend the best Skills & Subagents for the current repository stack"
+      },
+      {
+        command: 'npx skillops-cli route --task "optimize slow postgres queries in FastAPI" --top 4',
+        description: "Route top 4 Skills tailored to a specific engineering task"
+      }
+    ]
+  },
+  {
+    name: "create",
+    aliases: ["new"],
+    pillar: "framework",
+    summary: "Scaffold a custom Skill (SKILL.md + L3 script + evals.json) or Subagent (SUBAGENT.md) using the SkillOps Framework",
+    usage: "npx skillops-cli create <skill|subagent> <kebab-case-name> [options]",
+    options: [
+      {
+        flags: "--description, -d <text>",
+        description: "Custom trigger description (automatically normalized to INV-SKILL-01..04 contracts)"
+      },
+      {
+        flags: "--catalog <dir>",
+        description: "Target catalog directory (default: ./catalog)"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite existing Skill or Subagent template"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli create skill graphql-schema-guard",
+        description: "Scaffold a new INV-SKILL-01..03 compliant Skill with Level 3 script & eval suite"
+      },
+      {
+        command: "npx skillops-cli create subagent migration-reviewer",
+        description: "Scaffold a new INV-SKILL-04 compliant Context-Isolated Subagent"
+      }
+    ]
+  },
+  {
+    name: "audit",
+    aliases: [],
+    pillar: "framework",
+    summary: "Run L1/L2/L3 token budget linter, Subagent contract verifier & TF-IDF cosine collision matrix",
+    usage: "npx skillops-cli audit [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Catalog directory to audit"
+      },
+      {
+        flags: "--require-layout",
+        description: "Enforce full directory layout including evals/evals.json and executable L3 scripts"
+      },
+      {
+        flags: "--strict",
+        description: "Fail with non-zero exit code on HIGH_RISK collisions as well as BLOCKING collisions"
+      },
+      {
+        flags: "--format, -f <table|json|github>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli audit --require-layout --strict",
+        description: "Certify that all Skills & Subagents pass token budgets and zero-collision invariants"
+      }
+    ]
+  },
+  {
+    name: "eval",
+    aliases: [],
+    pillar: "framework",
+    summary: "Execute zero-API deterministic TDD benchmarks (with_skill vs without_skill) and export dashboards",
+    usage: "npx skillops-cli eval [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Catalog directory to evaluate"
+      },
+      {
+        flags: "--skill <name>",
+        description: "Evaluate a single Skill by name"
+      },
+      {
+        flags: "--out <file>",
+        description: "Write formatted benchmark report (e.g. HTML/Markdown) to disk"
+      },
+      {
+        flags: "--strict",
+        description: "Exit with code 4 if any Skill fails CERTIFIED_IMPROVEMENT"
+      },
+      {
+        flags: "--format, -f <table|json|markdown|html|github>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli eval --strict",
+        description: "Run deterministic A/B evals across all Skills in the catalog"
+      },
+      {
+        command: "npx skillops-cli eval --format html --out benchmark.html",
+        description: "Export a standalone HTML benchmark dashboard"
+      }
+    ]
+  },
+  {
+    name: "init",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Scaffold declarative .skillops.yml and detect repository AI coding harnesses",
+    usage: "npx skillops-cli init [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "--harness, --targets, -t <list|auto|all>",
+        description: "Initial target harnesses to record in .skillops.yml"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli init",
+        description: "Create .skillops.yml with auto-detected stack and harnesses"
+      }
+    ]
+  },
+  {
+    name: "sync",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Transpile routed Skills & Subagents across up to 20 AI coding agents with SHA-256 lockfile protection",
+    usage: "npx skillops-cli sync [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "--harness, --targets, -t <list|auto|all>",
+        description: "Target AI coding harnesses (default: .skillops.yml targets or core 5)"
+      },
+      {
+        flags: "--top, --max-skills <n>",
+        description: "Maximum Skills to sync"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview planned artifacts without writing files"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite locally drifted files"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli sync --auto",
+        description: "Sync optimal Skills & Subagents into all AI harnesses detected in the repo"
+      },
+      {
+        command: "npx skillops-cli sync --harness all",
+        description: "Transpile across all 20 supported AI coding agents"
+      }
+    ]
+  },
+  {
+    name: "clean",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Remove all SkillOps-managed runtime artifacts tracked in .skillops-lock.json",
+    usage: "npx skillops-cli clean [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview files that would be removed"
+      },
+      {
+        flags: "--force",
+        description: "Remove even if local edits are detected"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli clean",
+        description: "Cleanly remove all synced artifacts and .skillops-lock.json"
+      }
+    ]
+  },
+  {
+    name: "tokens",
+    aliases: ["budget"],
+    pillar: "runtime",
+    summary: "Analyze repository Startup Token Tax, Progressive Disclosure savings & context bloat hotspots",
+    usage: "npx skillops-cli budget [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Repository directory to inspect"
+      },
+      {
+        flags: "--budget <tokens>",
+        description: "Startup Token Tax ceiling (default: 2500)"
+      },
+      {
+        flags: "--strict",
+        description: "Fail with exit code 3 if Startup Token Tax exceeds budget"
+      },
+      {
+        flags: "--format, -f <table|json|markdown|github>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli budget",
+        description: "Inspect repository Startup Token Tax and Progressive Disclosure savings"
+      }
+    ]
+  },
+  {
+    name: "doctor",
+    aliases: ["status"],
+    pillar: "runtime",
+    summary: "Diagnose Node/Python environment, .skillops.yml validity, lockfile SHA-256 drift & Startup Token Tax",
+    usage: "npx skillops-cli doctor [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Repository directory to diagnose"
+      },
+      {
+        flags: "--strict",
+        description: "Fail on warnings as well as errors"
+      },
+      {
+        flags: "--format, -f <table|json|markdown|github>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli doctor",
+        description: "Run full repository & lockfile health check"
+      }
+    ]
+  },
+  {
+    name: "harnesses",
+    aliases: [],
+    pillar: "runtime",
+    summary: "List all 20 supported AI coding agents, target paths, MCP support & repository detection status",
+    usage: "npx skillops-cli harnesses [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Repository directory to scan for AI harnesses"
+      },
+      {
+        flags: "--format, -f <table|json|markdown>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli harnesses",
+        description: "View all 20 supported AI coding IDEs/CLI agents and which ones are active in your repo"
+      }
+    ]
+  },
+  {
+    name: "mcp-setup",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Register SkillOps MCP server across all 13 MCP-compatible AI coding IDEs & agents",
+    usage: "npx skillops-cli mcp-setup [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "--harness, --targets, -t <list|auto|all>",
+        description: "Target harnesses to configure MCP for"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview MCP config files without writing"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli mcp-setup --auto",
+        description: "Automatically wire SkillOps MCP server into detected IDEs (.mcp.json, .cursor/mcp.json, etc.)"
+      }
+    ]
+  },
+  {
+    name: "mcp",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Start native JSON-RPC 2.0 stdio Model Context Protocol server",
+    usage: "npx skillops-cli mcp [options]",
+    options: [
+      {
+        flags: "--project, --repo, -p <dir>",
+        description: "Repository root served over MCP"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli mcp",
+        description: "Start stdio MCP server (invoked automatically by AI IDEs)"
+      }
+    ]
+  }
+];
+function findCommandHelpSpec(commandOrAlias) {
+  const normalized = commandOrAlias.trim().toLowerCase();
+  return COMMAND_HELP_SPECS.find(
+    (spec) => spec.name === normalized || spec.aliases.includes(normalized)
+  );
+}
+function renderGlobalHelp(version, colorEnabled) {
+  const c = colorEnabled;
+  const banner = renderHeaderBanner(
+    "The Zero-API Framework & Library for High-End AI Coding Skills & Context-Isolated Subagents",
+    {
+      version,
+      colorEnabled: c
+    }
+  );
+  const quickstartBox = renderBox(
+    [
+      `${style.bold(style.green("npx skillops-cli quickstart", c), c)}    ${style.dim("# 1-step setup: detect stack, install Skills/Subagents & wire MCP", c)}`,
+      `${style.bold(style.cyan("npx skillops-cli info <name>", c), c)}   ${style.dim("# Inspect any Skill/Subagent & see how to invoke it in your AI", c)}`,
+      `${style.bold(style.magenta("npx skillops-cli create skill <name>", c), c)} ${style.dim("# Scaffold your own custom Skill using the SkillOps Framework", c)}`
+    ],
+    {
+      title: "\u{1F680} 10-Second Quickstart (Library + Framework)",
+      borderColor: style.cyan,
+      minWidth: 88,
+      colorEnabled: c
+    }
+  );
+  const formatCmdSection = (pillar) => {
+    const specs = COMMAND_HELP_SPECS.filter((s) => s.pillar === pillar);
+    return renderTable(
+      ["Command", "Aliases", "Description"],
+      specs.map((s) => [
+        style.bold(style.cyan(s.name, c), c),
+        s.aliases.length > 0 ? style.dim(s.aliases.join(", "), c) : style.dim("\u2014", c),
+        s.summary
+      ]),
+      { colorEnabled: c, indent: 2 }
+    );
+  };
+  const globalFlagsTable = renderTable(
+    ["Global Flag", "Description"],
+    [
+      [
+        style.cyan("--project, --repo, -p <dir>", c),
+        "Target project/repository directory (default: current working directory)"
+      ],
+      [
+        style.cyan("--harness, --targets, -t <list|auto|all>", c),
+        "Target AI coding harnesses (e.g. claude,cursor,windsurf,copilot or auto/all)"
+      ],
+      [
+        style.cyan("--format, -f <table|json|markdown|github>", c),
+        "Output format for reports and CI pipelines (default: table)"
+      ],
+      [
+        style.cyan("--help, -h / --version, -V", c),
+        "Show global or per-command help (`npx skillops-cli <cmd> --help`) / CLI version"
+      ]
+    ],
+    { colorEnabled: c, indent: 2 }
+  );
+  return [
+    `SkillOps v${version} \u2014 The Zero-API NPX Engine for High-End AI Skills & Subagents`,
+    "Usage: npx skillops-cli <command> [options]",
+    "",
+    banner,
+    quickstartBox,
+    renderSectionHeader(
+      "\u{1F4DA} 1. Library of High-End Skills & Subagents (Explore, Search & Install)",
+      c
+    ),
+    formatCmdSection("library"),
+    renderSectionHeader(
+      "\u{1F6E0}\uFE0F 2. Framework for Building Custom Skills & Subagents (Scaffold, Audit & Certify)",
+      c
+    ),
+    formatCmdSection("framework"),
+    renderSectionHeader(
+      "\u2699\uFE0F 3. Universal Runtime Sync, Token Economy & Diagnostics (Top 20 AI Harnesses)",
+      c
+    ),
+    formatCmdSection("runtime"),
+    renderSectionHeader("\u{1F310} Global Options", c),
+    globalFlagsTable,
+    "",
+    `  ${style.dim("\u{1F4A1} Tip: Run", c)} ${style.bold(style.cyan("npx skillops-cli <command> --help", c), c)} ${style.dim("for detailed flags and copy-paste examples.", c)}`,
+    ""
+  ].join("\n");
+}
+function renderCommandHelp(spec, version, colorEnabled) {
+  const c = colorEnabled;
+  const pillarBadge = spec.pillar === "library" ? formatBadge("info", "LIBRARY", c) : spec.pillar === "framework" ? formatBadge("pass", "FRAMEWORK", c) : formatBadge("subagent", "RUNTIME", c);
+  const aliasText = spec.aliases.length > 0 ? ` (aliases: ${spec.aliases.map((a) => style.cyan(a, c)).join(", ")})` : "";
+  const headerBox = renderBox(
+    [
+      `${pillarBadge} ${style.bold(style.cyan(`skillops ${spec.name}`, c), c)}${aliasText}`,
+      "",
+      spec.summary,
+      "",
+      `${style.bold("Usage:", c)} ${style.green(spec.usage, c)}`
+    ],
+    {
+      title: `SkillOps v${version} \u2014 Command Reference`,
+      borderColor: style.cyan,
+      minWidth: 78,
+      colorEnabled: c
+    }
+  );
+  const optionsSection = spec.options.length > 0 ? [
+    renderSectionHeader("Options & Flags", c),
+    renderTable(
+      ["Flag", "Description"],
+      spec.options.map((o) => [style.cyan(o.flags, c), o.description]),
+      { colorEnabled: c, indent: 2 }
+    )
+  ].join("\n") : "";
+  const examplesSection = renderNextSteps(spec.examples, c);
+  return [headerBox, optionsSection, examplesSection].filter(Boolean).join("\n");
+}
+
+// src/framework/index.ts
+function extractMarkdownHeadings(markdownBody) {
+  const headings = [];
+  for (const rawLine of markdownBody.split(/\r?\n/)) {
+    const trimmed = rawLine.trim();
+    if (trimmed.startsWith("## ")) {
+      headings.push(trimmed.slice(3).trim());
+    }
+  }
+  return headings;
+}
+function inspectCatalogItem(catalogDir, itemName) {
+  const needle = itemName.trim().toLowerCase();
+  for (const skillDir of discoverSkillDirectories(catalogDir)) {
+    const parsed = parseSkillDirectory(skillDir, { requireLayout: false });
+    if (parsed.manifest.name.toLowerCase() === needle) {
+      const l1Tokens = parsed.manifest.description_tokens;
+      const l2Lines = parsed.manifest.body_lines;
+      const l2Tokens = parsed.manifest.body_tokens;
+      const totalRaw = l1Tokens + l2Tokens;
+      const savingsPct = totalRaw > 0 ? Number(((totalRaw - l1Tokens) / totalRaw * 100).toFixed(1)) : 0;
+      let evalCasesCount = 0;
+      if (parsed.evalsPath && fs9.existsSync(parsed.evalsPath)) {
+        try {
+          const rawEvals = JSON.parse(
+            fs9.readFileSync(parsed.evalsPath, "utf-8")
+          );
+          evalCasesCount = Array.isArray(rawEvals.evals) ? rawEvals.evals.length : 0;
+        } catch {
+          evalCasesCount = 0;
+        }
+      }
+      return {
+        kind: "skill",
+        name: parsed.manifest.name,
+        description: parsed.manifest.description,
+        path: parsed.skillMdPath.replace(/\\/g, "/"),
+        l1Tokens,
+        l2Lines,
+        l2Tokens,
+        savingsPct,
+        scripts: parsed.manifest.entrypoints.scripts.map((s) => s.path),
+        evalCasesCount,
+        tools: [],
+        maxOutputTokens: null,
+        isolation: null,
+        headings: extractMarkdownHeadings(parsed.markdownBody)
+      };
+    }
+  }
+  for (const subPath of discoverSubagentFiles(catalogDir)) {
+    const parsed = parseSubagentFile(subPath);
+    if (parsed.manifest.name.toLowerCase() === needle) {
+      return {
+        kind: "subagent",
+        name: parsed.manifest.name,
+        description: parsed.manifest.description,
+        path: parsed.filePath.replace(/\\/g, "/"),
+        l1Tokens: parsed.manifest.system_prompt_tokens,
+        l2Lines: parsed.manifest.system_prompt_lines,
+        l2Tokens: parsed.manifest.system_prompt_tokens,
+        savingsPct: 0,
+        scripts: [],
+        evalCasesCount: 0,
+        tools: parsed.manifest.tools,
+        maxOutputTokens: parsed.manifest.max_output_tokens,
+        isolation: parsed.manifest.context_isolation ? "context-isolated" : "shared",
+        headings: extractMarkdownHeadings(parsed.systemPromptBody)
+      };
+    }
+  }
+  throw new Error(
+    `Skill or Subagent '${itemName}' not found in catalog '${catalogDir.replace(/\\/g, "/")}'. Run 'npx skillops-cli list' to see all available items.`
+  );
+}
+function formatCatalogItemInfo(info, format = "table", colorEnabled) {
+  if (format === "json") {
+    return `${JSON.stringify(info, null, 2)}
+`;
+  }
+  if (format === "markdown") {
+    const lines = [
+      `## ${info.kind === "skill" ? "Skill" : "Subagent"}: \`${info.name}\``,
+      "",
+      `- **Type:** ${info.kind.toUpperCase()}`,
+      `- **Description:** ${info.description}`,
+      info.kind === "skill" ? `- **Token Economy:** L1=${info.l1Tokens}t | L2=${info.l2Lines} lines (${info.l2Tokens}t) | Savings=${info.savingsPct}%` : `- **Isolation Contract:** Prompt=${info.l1Tokens}t | Max Output <= ${info.maxOutputTokens}t | Isolation=${info.isolation} | Tools=${info.tools.join(", ")}`,
+      ...info.scripts.length > 0 ? [`- **Executable L3 Scripts:** \`${info.scripts.join("`, `")}\``] : [],
+      ...info.headings.length > 0 ? [`- **Workflow Sections:** ${info.headings.join(" \u2022 ")}`] : [],
+      "",
+      "### Quick Install",
+      "```bash",
+      `npx skillops-cli add ${info.name}`,
+      "```",
+      ""
+    ];
+    return lines.join("\n");
+  }
+  const c = colorEnabled;
+  const badge = info.kind === "skill" ? formatBadge("skill", "HYBRID EXECUTABLE SKILL", c) : formatBadge("subagent", "CONTEXT-ISOLATED SUBAGENT", c);
+  const cardLines = [
+    `${badge}  ${style.bold(style.cyan(info.name, c), c)}`,
+    "",
+    `${style.bold("Description:", c)}`,
+    `  ${info.description}`,
+    ""
+  ];
+  if (info.kind === "skill") {
+    cardLines.push(
+      `${style.bold("Token Economy (INV-SKILL-01..03):", c)}`,
+      `  \u2022 L1 Routing Footprint : ${style.green(`${info.l1Tokens} tokens`, c)} (<= 160 budget)`,
+      `  \u2022 L2 Playbook Body     : ${info.l2Lines} lines (${info.l2Tokens} tokens, <= 250 lines)`,
+      `  \u2022 Progressive Savings  : ${style.bold(style.green(`${info.savingsPct}%`, c), c)} Startup Token Tax saved until triggered`,
+      `  \u2022 L3 Scripts (${info.scripts.length})      : ${info.scripts.length > 0 ? style.cyan(info.scripts.join(", "), c) : "none"}`,
+      `  \u2022 TDD Eval Cases       : ${info.evalCasesCount} deterministic benchmark cases`
+    );
+  } else {
+    cardLines.push(
+      `${style.bold("Context Isolation Contract (INV-SKILL-04):", c)}`,
+      `  \u2022 System Prompt Tokens : ${style.green(`${info.l1Tokens} tokens`, c)}`,
+      `  \u2022 Max Output Cap       : <= ${style.bold(`${info.maxOutputTokens} tokens`, c)}`,
+      `  \u2022 Isolation Mode       : ${style.cyan(info.isolation ?? "context-isolated", c)}`,
+      `  \u2022 Allowed Tools (${info.tools.length})    : ${info.tools.join(", ")}`
+    );
+  }
+  if (info.headings.length > 0) {
+    cardLines.push(
+      "",
+      `${style.bold("Workflow Playbook Sections:", c)}`,
+      ...info.headings.slice(0, 6).map((h) => `  \u2022 ${h}`)
+    );
+  }
+  cardLines.push(
+    "",
+    `${style.bold("How to Invoke in Your AI Agent:", c)}`,
+    `  \u2022 ${style.bold("Install into repo:", c)} ${style.green(`npx skillops-cli add ${info.name}`, c)}`,
+    info.kind === "skill" ? `  \u2022 ${style.bold("Cursor / Copilot / Claude:", c)} Reference ${style.cyan(`@${info.name}`, c)} or ${style.cyan(`/${info.name}`, c)} in chat` : `  \u2022 ${style.bold("Delegate Subagent:", c)} Ask your main agent to delegate heavy exploration to ${style.magenta(`@${info.name}`, c)}`
+  );
+  const box = renderBox(cardLines, {
+    title: `\u{1F4E6} SkillOps Library Inspector \u2014 ${info.name}`,
+    borderColor: info.kind === "skill" ? style.cyan : style.magenta,
+    minWidth: 74,
+    colorEnabled: c
+  });
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli add ${info.name}`,
+        description: `Install '${info.name}' into your active AI coding agents`
+      },
+      ...info.kind === "skill" ? [
+        {
+          command: `npx skillops-cli eval --skill ${info.name}`,
+          description: `Run deterministic TDD benchmark for '${info.name}'`
+        }
+      ] : [],
+      {
+        command: "npx skillops-cli list",
+        description: "Browse all 10 Skills & 9 Subagents in the Library"
+      }
+    ],
+    c
+  );
+  return `${box}
+${nextSteps}`;
+}
+function searchCatalog(catalogDir, query) {
+  const rawTerms = query.trim().toLowerCase().split(/[^a-z0-9_-]+/).filter((t) => t.length > 0);
+  const matches = [];
+  for (const skillDir of discoverSkillDirectories(catalogDir)) {
+    const parsed = parseSkillDirectory(skillDir, { requireLayout: false });
+    const haystackName = parsed.manifest.name.toLowerCase();
+    const haystackDesc = parsed.manifest.description.toLowerCase();
+    const haystackBody = parsed.markdownBody.toLowerCase();
+    let score = rawTerms.length === 0 ? 1 : 0;
+    for (const term of rawTerms) {
+      if (haystackName.includes(term)) {
+        score += 5;
+      }
+      if (haystackDesc.includes(term)) {
+        score += 3;
+      }
+      if (haystackBody.includes(term)) {
+        score += 1;
+      }
+    }
+    if (score > 0) {
+      matches.push({
+        kind: "skill",
+        name: parsed.manifest.name,
+        score,
+        tokens: parsed.manifest.description_tokens,
+        summary: parsed.manifest.description.length > 78 ? `${parsed.manifest.description.slice(0, 75)}...` : parsed.manifest.description
+      });
+    }
+  }
+  for (const subPath of discoverSubagentFiles(catalogDir)) {
+    const parsed = parseSubagentFile(subPath);
+    const haystackName = parsed.manifest.name.toLowerCase();
+    const haystackDesc = parsed.manifest.description.toLowerCase();
+    const haystackTools = parsed.manifest.tools.join(" ").toLowerCase();
+    let score = rawTerms.length === 0 ? 1 : 0;
+    for (const term of rawTerms) {
+      if (haystackName.includes(term)) {
+        score += 5;
+      }
+      if (haystackDesc.includes(term)) {
+        score += 3;
+      }
+      if (haystackTools.includes(term)) {
+        score += 2;
+      }
+    }
+    if (score > 0) {
+      matches.push({
+        kind: "subagent",
+        name: parsed.manifest.name,
+        score,
+        tokens: parsed.manifest.system_prompt_tokens,
+        summary: parsed.manifest.description.length > 78 ? `${parsed.manifest.description.slice(0, 75)}...` : parsed.manifest.description
+      });
+    }
+  }
+  matches.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  return {
+    query,
+    total_matches: matches.length,
+    matches
+  };
+}
+function formatCatalogSearchReport(report, format = "table", colorEnabled) {
+  if (format === "json") {
+    return `${JSON.stringify(report, null, 2)}
+`;
+  }
+  if (format === "markdown") {
+    const lines = [
+      `## SkillOps Library Search \u2014 \`${report.query || "*"}\` (${report.total_matches} matches)`,
+      "",
+      "| Type | Name | Tokens | Summary |",
+      "| :--- | :--- | ---: | :--- |",
+      ...report.matches.map(
+        (m) => `| ${m.kind.toUpperCase()} | \`${m.name}\` | ${m.tokens}t | ${m.summary} |`
+      ),
+      ""
+    ];
+    return lines.join("\n");
+  }
+  const c = colorEnabled;
+  const header = renderBox(
+    [
+      `${style.bold(style.cyan("\u{1F50D} SkillOps Library Search", c), c)} \u2014 Query: ${style.bold(`"${report.query || "*"}"`, c)} (${report.total_matches} matches)`
+    ],
+    { minWidth: 74, colorEnabled: c }
+  );
+  if (report.matches.length === 0) {
+    return `${header}
+  ${formatBadge("warn", "No matching Skills or Subagents found.", c)}
+${renderNextSteps([{ command: "npx skillops-cli list", description: "View all 10 Skills & 9 Subagents in the Library" }], c)}`;
+  }
+  const table = renderTable(
+    ["Type", "Name", "Tokens", "When to Use / Summary"],
+    report.matches.map((m) => [
+      m.kind === "skill" ? formatBadge("skill", "SKILL", c) : formatBadge("subagent", "SUBAGENT", c),
+      style.bold(m.name, c),
+      `${m.tokens}t`,
+      m.summary
+    ]),
+    { align: ["left", "left", "right", "left"], colorEnabled: c }
+  );
+  const topItem = report.matches[0]?.name ?? "bug-reproducer-tdd";
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli info ${topItem}`,
+        description: `Inspect '${topItem}' in detail`
+      },
+      {
+        command: `npx skillops-cli add ${topItem}`,
+        description: `Install '${topItem}' into your project's AI agents`
+      }
+    ],
+    c
+  );
+  return `${header}
+
+${table}
+${nextSteps}`;
+}
+function buildValidSkillDescription(name, humanTitle, customDesc) {
+  const domainPhrase = name.replace(/-/g, " ");
+  const defaultDescription = `Use when implementing, auditing, or troubleshooting ${domainPhrase} workflows across production codebases to enforce deterministic ${humanTitle} invariants, structural contracts, boundary-value assertions, and automated Level 3 verification scripts before applying surgical changes. Do not trigger for pure documentation edits, static asset bundling, or unrelated formatting changes.`;
+  if (!customDesc?.trim()) {
+    return defaultDescription;
+  }
+  let candidate = customDesc.trim().replace(/\s+/g, " ");
+  if (!candidate.startsWith("Use when")) {
+    candidate = `Use when working on ${domainPhrase}: ${candidate}`;
+  }
+  const words = countWords(candidate);
+  if (words < 40) {
+    candidate = `${candidate} Enforces deterministic ${humanTitle} invariants, automated Level 3 script verification, architectural boundary checks, and zero-regression guardrails across production repositories. Do not trigger for pure documentation edits, static asset bundling, or unrelated formatting changes.`;
+  }
+  return candidate;
+}
+function scaffoldFrameworkItem(catalogDir, kind, rawName, options = {}) {
+  const name = rawName.trim().toLowerCase();
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+    throw new Error(
+      `Invalid ${kind} name '${rawName}': must be kebab-case ('^[a-z0-9]+(-[a-z0-9]+)*$').`
+    );
+  }
+  const createdFiles = [];
+  if (kind === "skill") {
+    const skillDir = path9.join(catalogDir, "skills", name);
+    const skillMdPath = path9.join(skillDir, "SKILL.md");
+    const snakeName = name.replace(/-/g, "_");
+    const scriptRelPath = `scripts/verify_${snakeName}.py`;
+    const scriptAbsPath = path9.join(
+      skillDir,
+      "scripts",
+      `verify_${snakeName}.py`
+    );
+    const evalsAbsPath = path9.join(skillDir, "evals", "evals.json");
+    if (fs9.existsSync(skillMdPath) && !options.force) {
+      throw new Error(
+        `Skill '${name}' already exists at '${skillMdPath.replace(/\\/g, "/")}'. Pass --force to overwrite.`
+      );
+    }
+    const humanTitle2 = name.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+    const description = buildValidSkillDescription(
+      name,
+      humanTitle2,
+      options.description
+    );
+    const skillMdContent = [
+      "---",
+      `name: "${name}"`,
+      `description: "${description.replace(/"/g, '\\"')}"`,
+      'version: "1.0.0"',
+      'track: "arch-quality"',
+      "tags:",
+      `  - "${name}"`,
+      '  - "verification"',
+      '  - "deterministic-validation"',
+      "routing_signals:",
+      '  languages: ["typescript", "python"]',
+      '  files_any: ["package.json", "pyproject.toml"]',
+      "  dependencies_any: []",
+      "  negative_triggers:",
+      '    - "Do not trigger for pure documentation edits, static asset bundling, or unrelated formatting changes."',
+      "entrypoints:",
+      "  scripts:",
+      `    - path: "${scriptRelPath}"`,
+      `      description: "Executes deterministic structural verification and invariant checks for ${humanTitle2}."`,
+      "---",
+      "",
+      `# ${humanTitle2} (\`${name}\`)`,
+      "",
+      "## When to Use",
+      `- Activate this skill when working on **${humanTitle2}** tasks requiring deterministic validation.`,
+      "- Delegate exploratory repository scans to a Context-Isolated Subagent before modifying production files.",
+      "",
+      "## Step-by-Step Playbook",
+      "1. **Baseline Discovery:** Inspect target modules and identify architectural constraints.",
+      "2. **Deterministic Verification (Level 3 Script):** Run the bundled verification script before and after changes:",
+      "   ```bash",
+      `   python ${scriptRelPath} --target .`,
+      "   ```",
+      "3. **Minimal Surgical Implementation:** Apply focused changes and verify zero regressions.",
+      "",
+      "## Anti-Patterns to Avoid",
+      "- Never skip Level 3 deterministic verification before declaring completion.",
+      "- Avoid loading large raw logs into the primary context window.",
+      ""
+    ].join("\n");
+    const scriptContent = [
+      '"""Deterministic Level 3 verification script generated by SkillOps Framework."""',
+      "",
+      "from __future__ import annotations",
+      "",
+      "import argparse",
+      "import json",
+      "import sys",
+      "",
+      "",
+      "def main() -> int:",
+      `    parser = argparse.ArgumentParser(description="Verify ${humanTitle2} invariants.")`,
+      '    parser.add_argument("--target", default=".", help="Target directory or file path to verify.")',
+      "    args = parser.parse_args()",
+      `    payload = {"skill": "${name}", "target": args.target, "status": "pass"}`,
+      "    print(json.dumps(payload, indent=2))",
+      "    return 0",
+      "",
+      "",
+      'if __name__ == "__main__":',
+      "    sys.exit(main())",
+      ""
+    ].join("\n");
+    const evalsContent = JSON.stringify(
+      {
+        skill_name: name,
+        schema_version: "1.0",
+        evals: [
+          {
+            id: `eval-01-verify-${name}`,
+            name: `Verify ${humanTitle2} deterministic workflow and Level 3 script execution`,
+            prompt: `Audit and enforce ${humanTitle2} invariants using the deterministic verification script.`,
+            fixtures: [],
+            assertions: [
+              {
+                id: "assert-ran-verification-script",
+                type: "tool_call_contains",
+                target: `verify_${snakeName}.py`,
+                description: `Agent executed verify_${snakeName}.py before finalizing changes.`
+              }
+            ]
+          }
+        ]
+      },
+      null,
+      2
+    );
+    fs9.mkdirSync(path9.dirname(scriptAbsPath), { recursive: true });
+    fs9.mkdirSync(path9.dirname(evalsAbsPath), { recursive: true });
+    fs9.writeFileSync(skillMdPath, skillMdContent, "utf-8");
+    fs9.writeFileSync(scriptAbsPath, scriptContent, "utf-8");
+    fs9.writeFileSync(evalsAbsPath, `${evalsContent}
+`, "utf-8");
+    createdFiles.push(
+      skillMdPath.replace(/\\/g, "/"),
+      scriptAbsPath.replace(/\\/g, "/"),
+      evalsAbsPath.replace(/\\/g, "/")
+    );
+    return {
+      kind: "skill",
+      name,
+      target_dir: skillDir.replace(/\\/g, "/"),
+      created_files: createdFiles
+    };
+  }
+  const subagentDir = path9.join(catalogDir, "subagents", name);
+  const subagentMdPath = path9.join(subagentDir, "SUBAGENT.md");
+  if (fs9.existsSync(subagentMdPath) && !options.force) {
+    throw new Error(
+      `Subagent '${name}' already exists at '${subagentMdPath.replace(/\\/g, "/")}'. Pass --force to overwrite.`
+    );
+  }
+  const humanTitle = name.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  const rawSubDesc = options.description?.trim();
+  const defaultSubDescription = rawSubDesc && countWords(rawSubDesc) >= 10 ? rawSubDesc : `Context-isolated specialist subagent for ${humanTitle}. Use when delegating high-volume repository analysis, structural inspection, or verification without polluting the main agent context window.`;
+  const subagentMdContent = [
+    "---",
+    `name: "${name}"`,
+    `description: "${defaultSubDescription.replace(/"/g, '\\"')}"`,
+    "tools:",
+    '  - "Read"',
+    '  - "Grep"',
+    '  - "Glob"',
+    "user_invocable: true",
+    "context_isolation: true",
+    "max_output_tokens: 350",
+    'model_tier: "fast"',
+    "tags:",
+    `  - "${name}"`,
+    '  - "context-isolated"',
+    "---",
+    "",
+    `# ${humanTitle} Subagent`,
+    "",
+    "## Mission & Context Isolation Contract (`INV-SKILL-04`)",
+    `You are the **${humanTitle}** context-isolated subagent. Execute deep inspection in your isolated context window and return a concise structured summary (\`<= 350\` tokens) to the parent orchestrator.`,
+    "",
+    "## Output Format",
+    "1. **Findings Summary:** High-signal bullet points with exact file paths and line numbers.",
+    "2. **Recommended Actions:** Concrete next steps for the parent agent.",
+    ""
+  ].join("\n");
+  fs9.mkdirSync(subagentDir, { recursive: true });
+  fs9.writeFileSync(subagentMdPath, subagentMdContent, "utf-8");
+  createdFiles.push(subagentMdPath.replace(/\\/g, "/"));
+  return {
+    kind: "subagent",
+    name,
+    target_dir: subagentDir.replace(/\\/g, "/"),
+    created_files: createdFiles
+  };
+}
+function formatScaffoldReport(result, format = "table", colorEnabled) {
+  if (format === "json") {
+    return `${JSON.stringify(result, null, 2)}
+`;
+  }
+  if (format === "markdown") {
+    return [
+      `## SkillOps Framework Scaffolder \u2014 Created ${result.kind.toUpperCase()} \`${result.name}\``,
+      "",
+      `- **Target Directory:** \`${result.target_dir}\``,
+      ...result.created_files.map((f) => `- **Created:** \`${f}\``),
+      ""
+    ].join("\n");
+  }
+  const c = colorEnabled;
+  const box = renderBox(
+    [
+      `${formatBadge("pass", "CREATED", c)} Scaffolded new SkillOps Framework ${style.bold(result.kind.toUpperCase(), c)}: ${style.bold(style.cyan(result.name, c), c)}`,
+      "",
+      `${style.bold("Generated Files:", c)}`,
+      ...result.created_files.map((f) => `  \u2022 ${style.green(f, c)}`)
+    ],
+    {
+      title: "\u{1F6E0}\uFE0F SkillOps Framework Scaffolder",
+      borderColor: style.green,
+      minWidth: 74,
+      colorEnabled: c
+    }
+  );
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli info ${result.name}`,
+        description: `Inspect your new ${result.kind} metadata & token budget`
+      },
+      {
+        command: "npx skillops-cli audit --require-layout",
+        description: "Verify INV-SKILL-01..04 contract compliance & cosine collisions"
+      },
+      {
+        command: `npx skillops-cli add ${result.name}`,
+        description: `Transpile & install '${result.name}' into your AI coding agents`
+      }
+    ],
+    c
+  );
+  return `${box}
+${nextSteps}`;
+}
+function runQuickstart(repoPath, catalogDir, options = {}) {
+  const absRepo = path9.resolve(repoPath);
+  const dryRun = options.dryRun ?? false;
+  const force = options.force ?? false;
+  const skipMcp = options.skipMcp ?? false;
+  const profile = fingerprintRepository(absRepo);
+  const existingCfg = loadSkillOpsConfig(absRepo);
+  let activeTargets;
+  if (options.targetsArg) {
+    activeTargets = resolveRuntimeTargets(options.targetsArg, absRepo);
+  } else if (existingCfg.config?.targets && existingCfg.config.targets.length > 0) {
+    activeTargets = [...existingCfg.config.targets];
+  } else if (profile.detected_harnesses.length > 0) {
+    activeTargets = [...profile.detected_harnesses];
+  } else {
+    activeTargets = [...CORE_RUNTIME_TARGETS];
+  }
+  const maxSkills = options.maxSkills ?? existingCfg.config?.token_economy.max_active_skills ?? 12;
+  const maxL1Tokens = existingCfg.config?.token_economy.max_l1_tokens ?? 1500;
+  const maxSimilarity = existingCfg.config?.token_economy.max_similarity ?? 0.78;
+  const configPath = path9.join(absRepo, ".skillops.yml");
+  if (!dryRun) {
+    const configPayload = SkillOpsConfigSchema.parse({
+      version: "1.0",
+      catalog_dir: path9.relative(absRepo, catalogDir).replace(/\\/g, "/") || "catalog",
+      token_economy: {
+        startup_tax_budget: existingCfg.config?.token_economy.startup_tax_budget ?? 2500,
+        max_active_skills: maxSkills,
+        max_l1_tokens: maxL1Tokens,
+        max_similarity: maxSimilarity
+      },
+      detected_stack: {
+        languages: profile.languages,
+        frameworks: profile.frameworks
+      },
+      targets: activeTargets
+    });
+    fs9.mkdirSync(absRepo, { recursive: true });
+    fs9.writeFileSync(configPath, YAML5.stringify(configPayload), "utf-8");
+  }
+  const bundle = routeRepository(absRepo, catalogDir, {
+    maxSkills,
+    maxL1Tokens,
+    maxSimilarity
+  });
+  const syncReport = syncRepository(absRepo, catalogDir, {
+    targets: activeTargets,
+    dryRun,
+    force,
+    maxSkills,
+    maxL1Tokens,
+    maxSimilarity
+  });
+  const mcpReport = skipMcp ? null : setupMcpForHarnesses(absRepo, {
+    targets: activeTargets,
+    dryRun
+  });
+  return {
+    repo_path: absRepo.replace(/\\/g, "/"),
+    config_path: configPath.replace(/\\/g, "/"),
+    dry_run: dryRun,
+    detected_languages: profile.languages,
+    detected_frameworks: profile.frameworks,
+    detected_harnesses: profile.detected_harnesses,
+    active_targets: activeTargets,
+    selected_skills: bundle.selected_skills.map((s) => s.name),
+    selected_subagents: bundle.recommended_subagents,
+    total_l1_tokens: bundle.total_l1_tokens,
+    max_l1_budget: maxL1Tokens,
+    synced_files_count: syncReport.artifacts.filter(
+      (a) => a.action === "created" || a.action === "updated" || a.action === "unchanged" || a.action === "planned"
+    ).length,
+    mcp_configured_count: mcpReport ? mcpReport.configured_count : 0,
+    passed: bundle.passed_invariants && syncReport.passed
+  };
+}
+function formatQuickstartReport(report, format = "table", colorEnabled) {
+  if (format === "json") {
+    return `${JSON.stringify(report, null, 2)}
+`;
+  }
+  if (format === "markdown") {
+    return [
+      `## SkillOps Quickstart Report (${report.dry_run ? "DRY-RUN" : "INSTALLED"})`,
+      "",
+      `- **Repository:** \`${report.repo_path}\``,
+      `- **Stack Detected:** ${[...report.detected_languages, ...report.detected_frameworks].join(", ") || "generic"}`,
+      `- **Target AI Agents (${report.active_targets.length}):** \`${report.active_targets.join("`, `")}\``,
+      `- **Routed Skills (${report.selected_skills.length}):** \`${report.selected_skills.join("`, `")}\``,
+      `- **Routed Subagents (${report.selected_subagents.length}):** \`${report.selected_subagents.join("`, `")}\``,
+      `- **Token Budget:** \`${report.total_l1_tokens} / ${report.max_l1_budget}\` L1 tokens`,
+      `- **Synced Artifacts:** ${report.synced_files_count} files | **MCP Configs:** ${report.mcp_configured_count}`,
+      ""
+    ].join("\n");
+  }
+  const c = colorEnabled;
+  const stackLabel = [...report.detected_languages, ...report.detected_frameworks].join(", ") || "general-purpose";
+  const targetsLabel = report.active_targets.length > 5 ? `${report.active_targets.slice(0, 5).join(", ")} (+${report.active_targets.length - 5} more)` : report.active_targets.join(", ");
+  const banner = renderHeaderBanner(
+    `1-Step Quickstart & AI Agent Library Setup ${report.dry_run ? "[DRY-RUN]" : "[READY]"}`,
+    { colorEnabled: c }
+  );
+  const stepsBlock = [
+    renderStep(
+      1,
+      4,
+      "Detect Stack & AI Agents",
+      `Stack: ${style.cyan(stackLabel, c)} \u2022 Targets: ${style.bold(targetsLabel, c)}`,
+      "done",
+      c
+    ),
+    renderStep(
+      2,
+      4,
+      "Route Optimal Library Bundle",
+      `${style.green(`${report.selected_skills.length} Skills`, c)} + ${style.magenta(`${report.selected_subagents.length} Subagents`, c)} selected`,
+      "done",
+      c
+    ),
+    renderStep(
+      3,
+      4,
+      "Transpile & Sync Artifacts",
+      `${report.synced_files_count} files synced (${report.dry_run ? "dry-run" : ".skillops.yml + .skillops-lock.json"})`,
+      "done",
+      c
+    ),
+    renderStep(
+      4,
+      4,
+      "Register MCP Server",
+      `${report.mcp_configured_count} MCP-compatible agent config(s) updated`,
+      "done",
+      c
+    )
+  ].join("\n");
+  const tokenBar = `  ${renderTokenBar(
+    report.total_l1_tokens,
+    report.max_l1_budget,
+    {
+      label: "L1 Routing Budget:",
+      colorEnabled: c
+    }
+  )}`;
+  const bundleBox = renderBox(
+    [
+      `${style.bold("Installed Hybrid Executable Skills:", c)}`,
+      `  ${report.selected_skills.map((s) => style.cyan(s, c)).join(", ")}`,
+      "",
+      `${style.bold("Installed Context-Isolated Subagents:", c)}`,
+      `  ${report.selected_subagents.map((a) => style.magenta(a, c)).join(", ")}`
+    ],
+    {
+      title: "\u{1F4E6} Active Skills & Subagents Bundle",
+      borderColor: style.cyan,
+      minWidth: 72,
+      colorEnabled: c
+    }
+  );
+  const usageGuide = renderAiUsageGuide(
+    report.active_targets,
+    report.selected_skills,
+    report.selected_subagents,
+    c
+  );
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli info ${report.selected_skills[0] ?? "bug-reproducer-tdd"}`,
+        description: "Inspect a Skill's triggers, L3 scripts & AI invocation syntax"
+      },
+      {
+        command: "npx skillops-cli list",
+        description: "Browse all 10 Skills & 9 Subagents in the Library"
+      },
+      {
+        command: "npx skillops-cli create skill my-custom-skill",
+        description: "Create your own custom Skill using the SkillOps Framework"
+      },
+      {
+        command: "npx skillops-cli doctor",
+        description: "Verify lockfile integrity & Startup Token Tax savings"
+      }
+    ],
+    c
+  );
+  return [
+    banner,
+    "",
+    stepsBlock,
+    "",
+    tokenBar,
+    "",
+    bundleBox,
+    "",
+    usageGuide,
+    nextSteps
+  ].join("\n");
+}
+
+// src/cli.ts
+var PACKAGE_ROOT = path10.resolve(
+  path10.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+function getFlagValue(args, ...flagNames) {
+  for (const flag of flagNames) {
+    const idx = args.indexOf(flag);
+    const val = idx !== -1 ? args[idx + 1] : void 0;
+    if (val && !val.startsWith("-")) {
+      return val;
+    }
+  }
+  return void 0;
+}
+function getPositionalArgs(args) {
+  const valueTakingFlags = /* @__PURE__ */ new Set([
+    "--repo",
+    "--project",
+    "-p",
+    "--targets",
+    "--harness",
+    "--harnesses",
+    "--target",
+    "-t",
+    "--catalog",
+    "--format",
+    "-f",
+    "--top",
+    "--max-skills",
+    "--max-l1-tokens",
+    "--max-similarity",
+    "--budget",
+    "--task",
+    "--skill",
+    "--out",
+    "--description",
+    "-d"
+  ]);
+  const positionals = [];
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      if (valueTakingFlags.has(arg)) {
+        i += 1;
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return positionals;
+}
+function resolveTargetsArg(args) {
+  const explicit = getFlagValue(
+    args,
+    "--targets",
+    "--harness",
+    "--harnesses",
+    "--target",
+    "-t"
+  );
+  if (explicit) {
+    return explicit;
+  }
+  if (args.includes("--auto")) {
+    return "auto";
+  }
+  return void 0;
+}
+function resolveCatalogDir(args, repoPath, loadedConfig) {
+  const catalogFlag = getFlagValue(args, "--catalog");
+  if (catalogFlag) {
+    return path10.resolve(catalogFlag);
+  }
+  const baseRepo = repoPath ? path10.resolve(repoPath) : process.cwd();
+  if (loadedConfig?.catalog_dir) {
+    const cfgCatalog = path10.resolve(baseRepo, loadedConfig.catalog_dir);
+    if (fs10.existsSync(cfgCatalog)) {
+      return cfgCatalog;
+    }
+  }
+  if (repoPath) {
+    const repoCatalog = path10.join(path10.resolve(repoPath), "catalog");
+    if (fs10.existsSync(repoCatalog)) {
+      return repoCatalog;
+    }
+  }
+  const cwdCatalog = path10.resolve(process.cwd(), "catalog");
+  if (fs10.existsSync(cwdCatalog)) {
+    return cwdCatalog;
+  }
+  return path10.join(PACKAGE_ROOT, "catalog");
+}
+function runCli(argv) {
+  const args = argv.slice(2);
+  if (args.includes("--version") || args.includes("-V") || args[0] === "version") {
+    process.stdout.write(`skillops ${SKILLOPS_VERSION}
+`);
+    return ExitCode.SUCCESS;
+  }
+  if (args[0] === "help") {
+    const targetCmd = args[1];
+    if (targetCmd && !targetCmd.startsWith("-")) {
+      const spec = findCommandHelpSpec(targetCmd);
+      if (spec) {
+        process.stdout.write(renderCommandHelp(spec, SKILLOPS_VERSION));
+        return ExitCode.SUCCESS;
+      }
+    }
+    process.stdout.write(renderGlobalHelp(SKILLOPS_VERSION));
+    return ExitCode.SUCCESS;
+  }
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    process.stdout.write(renderGlobalHelp(SKILLOPS_VERSION));
+    return ExitCode.SUCCESS;
+  }
+  if (args.includes("--help") || args.includes("-h")) {
+    const firstCmd = args[0];
+    if (firstCmd) {
+      const spec = findCommandHelpSpec(firstCmd);
+      if (spec) {
+        process.stdout.write(renderCommandHelp(spec, SKILLOPS_VERSION));
+        return ExitCode.SUCCESS;
+      }
+    }
+    process.stdout.write(renderGlobalHelp(SKILLOPS_VERSION));
+    return ExitCode.SUCCESS;
+  }
+  const command = args[0] ?? "";
+  if (command === "quickstart" || command === "setup") {
+    const repoPath = path10.resolve(
+      getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd()
+    );
+    const cfgRes = loadSkillOpsConfig(repoPath);
+    if (cfgRes.error) {
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
+      return ExitCode.BUDGET_OR_CONTRACT_ERROR;
+    }
+    const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
+    const targetsArg = resolveTargetsArg(args);
+    const maxSkillsRaw = getFlagValue(args, "--max-skills", "--top");
+    const maxSkills = maxSkillsRaw ? Number.parseInt(maxSkillsRaw, 10) : void 0;
+    const dryRun = args.includes("--dry-run");
+    const force = args.includes("--force");
+    const skipMcp = args.includes("--skip-mcp") || args.includes("--no-mcp");
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
+    const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
+    try {
+      const report = runQuickstart(repoPath, catalogDir, {
+        targetsArg,
+        maxSkills,
+        dryRun,
+        force,
+        skipMcp
+      });
+      process.stdout.write(formatQuickstartReport(report, format));
+      return report.passed ? ExitCode.SUCCESS : ExitCode.ERROR;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Invalid --targets: ${msg}
+`);
+      return ExitCode.BUDGET_OR_CONTRACT_ERROR;
+    }
+  }
+  if (command === "info" || command === "show" || command === "inspect") {
+    const positionals = getPositionalArgs(args);
+    const itemName = positionals[0];
+    if (!itemName) {
+      process.stderr.write(
+        "Usage: npx skillops-cli info <skill-or-subagent-name> [options]\n"
+      );
+      return ExitCode.ERROR;
+    }
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
+    const cfgRes = loadSkillOpsConfig(repoPath);
+    const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
+    const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
+    try {
+      const info = inspectCatalogItem(catalogDir, itemName);
+      process.stdout.write(formatCatalogItemInfo(info, format));
+      return ExitCode.SUCCESS;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: ${msg}
+`);
+      return ExitCode.ERROR;
+    }
+  }
+  if (command === "search" || command === "find") {
+    const positionals = getPositionalArgs(args);
+    const query = positionals.join(" ");
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
+    const cfgRes = loadSkillOpsConfig(repoPath);
+    const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
+    const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
+    const report = searchCatalog(catalogDir, query);
+    process.stdout.write(formatCatalogSearchReport(report, format));
+    return ExitCode.SUCCESS;
+  }
+  if (command === "create" || command === "new") {
+    const positionals = getPositionalArgs(args);
+    let kind = "skill";
+    let rawName;
+    const firstPos = positionals[0]?.toLowerCase();
+    if (firstPos === "skill" || firstPos === "skills") {
+      kind = "skill";
+      rawName = positionals[1];
+    } else if (firstPos === "subagent" || firstPos === "subagents" || firstPos === "agent" || firstPos === "agents") {
+      kind = "subagent";
+      rawName = positionals[1];
+    } else {
+      rawName = positionals[0];
+    }
+    if (!rawName) {
+      process.stderr.write(
+        "Usage: npx skillops-cli create <skill|subagent> <kebab-case-name> [--description <text>] [--force]\n"
+      );
+      return ExitCode.ERROR;
+    }
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
+    const cfgRes = loadSkillOpsConfig(repoPath);
+    const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
+    const description = getFlagValue(args, "--description", "-d");
+    const force = args.includes("--force");
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
+    const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
+    try {
+      const result = scaffoldFrameworkItem(catalogDir, kind, rawName, {
+        description,
+        force
+      });
+      process.stdout.write(formatScaffoldReport(result, format));
+      return ExitCode.SUCCESS;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: ${msg}
+`);
+      return ExitCode.ERROR;
+    }
+  }
+  if (command === "init") {
+    const repoPath = path10.resolve(
+      getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd()
+    );
+    const catalogDir = resolveCatalogDir(args, repoPath);
+    const profile = fingerprintRepository(repoPath);
+    const targetsArg = resolveTargetsArg(args);
+    let initTargets;
+    try {
+      initTargets = targetsArg ? resolveRuntimeTargets(targetsArg, repoPath) : profile.detected_harnesses.length > 0 ? profile.detected_harnesses : [...CORE_RUNTIME_TARGETS];
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Invalid --targets: ${msg}
+`);
+      return ExitCode.BUDGET_OR_CONTRACT_ERROR;
+    }
+    const configPayload = SkillOpsConfigSchema.parse({
+      version: "1.0",
+      catalog_dir: path10.relative(repoPath, catalogDir).replace(/\\/g, "/") || "catalog",
+      token_economy: {
+        startup_tax_budget: 2500,
+        max_active_skills: 12,
+        max_l1_tokens: 1500,
+        max_similarity: 0.78
+      },
+      detected_stack: {
+        languages: profile.languages,
+        frameworks: profile.frameworks
+      },
+      targets: initTargets
+    });
+    const configPath = path10.join(repoPath, ".skillops.yml");
+    fs10.mkdirSync(repoPath, { recursive: true });
+    fs10.writeFileSync(configPath, YAML6.stringify(configPayload), "utf-8");
+    process.stdout.write(
+      `Initialized SkillOps configuration at ${configPath.replace(/\\/g, "/")}
+`
+    );
+    return ExitCode.SUCCESS;
+  }
+  if (command === "list") {
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
+    const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
+      return ExitCode.BUDGET_OR_CONTRACT_ERROR;
+    }
+    const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
+    const summary = auditCatalogTokenBudgets(catalogDir, {
+      requireLayout: false
+    });
+    if (rawFormat === "json") {
+      process.stdout.write(`${JSON.stringify(summary, null, 2)}
 `);
+      return ExitCode.SUCCESS;
+    }
+    if (rawFormat === "markdown") {
+      const lines2 = [
+        "## SkillOps Catalog \u2014 High-End Skills & Context-Isolated Subagents",
+        "",
+        "### Hybrid Executable Skills (`INV-SKILL-01` .. `03`)",
+        "",
+        "| Skill | L1 Tokens | L2 Lines | L2 Tokens | Scripts |Savings |",
+        "| :--- | ---: | ---: | ---: | ---: | ---: |",
+        ...summary.skills.map((s) => {
+          const totalRaw = s.l1Tokens + s.l2Tokens;
+          const savingsPct = totalRaw > 0 ? ((totalRaw - s.l1Tokens) / totalRaw * 100).toFixed(1) : "0.0";
+          return `| \`${s.skillName}\` | ${s.l1Tokens} | ${s.l2Lines} | ${s.l2Tokens} | ${s.scriptsCount} | ${savingsPct}% |`;
+        }),
+        "",
+        "### Context-Isolated Subagents (`INV-SKILL-04`)",
+        "",
+        "| Subagent | Prompt Tokens | Max Output Tokens | Tools |",
+        "| :--- | ---: | ---: | ---: |",
+        ...summary.subagents.map(
+          (a) => `| \`${a.subagentName}\` | ${a.systemPromptTokens} | <= ${a.maxOutputTokens} | ${a.tools.length} |`
+        ),
+        ""
+      ];
+      process.stdout.write(lines2.join("\n"));
+      return ExitCode.SUCCESS;
+    }
+    const l1Bar = renderProgressBar(summary.totalL1Tokens, 1500, {
+      width: 18,
+      unit: "tokens"
+    });
+    const firstSkill = summary.skills[0]?.skillName ?? "security-sast-gate";
+    const lines = [
+      `=== SkillOps Catalog (v${SKILLOPS_VERSION}) ===`,
+      `Skills (${summary.skills.length}) \u2014 Total L1 Routing Tax: ${summary.totalL1Tokens} tokens`,
+      `L1 Budget Meter: ${l1Bar}`,
+      ...summary.skills.map(
+        (s) => `  [SKILL] ${s.skillName} \u2014 L1: ${s.l1Tokens}t | L2: ${s.l2Lines} lines (${s.l2Tokens}t) | L3 Scripts: ${s.scriptsCount}`
+      ),
+      `Subagents (${summary.subagents.length}) \u2014 Context-Isolated Specialist Agents:`,
+      ...summary.subagents.map(
+        (a) => `  [SUBAGENT] ${a.subagentName} (prompt=${a.systemPromptTokens}t, max_out<=${a.maxOutputTokens}t, tools=${a.tools.length})`
+      ),
+      renderNextSteps([
+        {
+          command: `npx skillops-cli info ${firstSkill}`,
+          description: "Inspect triggers, L3 scripts & how to invoke in your AI"
+        },
+        {
+          command: "npx skillops-cli search <keyword>",
+          description: "Search Skills & Subagents by domain or signal"
+        },
+        {
+          command: "npx skillops-cli quickstart",
+          description: "Auto-detect project stack & install optimal bundle"
+        }
+      ])
+    ];
+    process.stdout.write(lines.join("\n"));
+    return ExitCode.SUCCESS;
+  }
+  if (command === "audit") {
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
+    const cfgRes = loadSkillOpsConfig(repoPath);
+    if (cfgRes.error) {
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
     const strict = args.includes("--strict");
     const requireLayout = args.includes("--require-layout");
-    const formatIdx = args.indexOf("--format");
-    const format = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const format = getFlagValue(args, "--format", "-f") ?? "table";
     const report = auditCatalog(catalogDir, { requireLayout });
     if (format === "json") {
       process.stdout.write(`${JSON.stringify(report, null, 2)}
@@ -4262,20 +6348,20 @@ function runCli(argv) {
     }
     return ExitCode.SUCCESS;
   }
-  if (command === "tokens") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
+  if (command === "tokens" || command === "budget") {
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
     const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
-    const budgetIdx = args.indexOf("--budget");
-    const startupTaxBudget = budgetIdx !== -1 && args[budgetIdx + 1] ? Number.parseInt(args[budgetIdx + 1], 10) : cfgRes.config?.token_economy.startup_tax_budget ?? 2500;
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const budgetRaw = getFlagValue(args, "--budget");
+    const startupTaxBudget = budgetRaw ? Number.parseInt(budgetRaw, 10) : cfgRes.config?.token_economy.startup_tax_budget ?? 2500;
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "github" ? rawFormat : "table";
     const strict = args.includes("--strict");
     const report = analyzeRepoTokenEconomy(repoPath, {
@@ -4288,26 +6374,25 @@ function runCli(argv) {
     }
     return ExitCode.SUCCESS;
   }
-  if (command === "route") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
+  if (command === "route" || command === "recommend") {
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
     const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
-    const taskIdx = args.indexOf("--task");
-    const taskPrompt = taskIdx !== -1 && args[taskIdx + 1] ? args[taskIdx + 1] : "";
-    const maxSkillsIdx = args.indexOf("--max-skills");
-    const maxSkills = maxSkillsIdx !== -1 && args[maxSkillsIdx + 1] ? Number.parseInt(args[maxSkillsIdx + 1], 10) : cfgRes.config?.token_economy.max_active_skills ?? 12;
-    const maxL1Idx = args.indexOf("--max-l1-tokens");
-    const maxL1Tokens = maxL1Idx !== -1 && args[maxL1Idx + 1] ? Number.parseInt(args[maxL1Idx + 1], 10) : cfgRes.config?.token_economy.max_l1_tokens ?? 1500;
-    const maxSimIdx = args.indexOf("--max-similarity");
-    const maxSimilarity = maxSimIdx !== -1 && args[maxSimIdx + 1] ? Number.parseFloat(args[maxSimIdx + 1]) : cfgRes.config?.token_economy.max_similarity ?? 0.78;
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const taskPrompt = getFlagValue(args, "--task") ?? "";
+    const maxSkillsRaw = getFlagValue(args, "--max-skills", "--top");
+    const maxSkills = maxSkillsRaw ? Number.parseInt(maxSkillsRaw, 10) : cfgRes.config?.token_economy.max_active_skills ?? 12;
+    const maxL1Raw = getFlagValue(args, "--max-l1-tokens");
+    const maxL1Tokens = maxL1Raw ? Number.parseInt(maxL1Raw, 10) : cfgRes.config?.token_economy.max_l1_tokens ?? 1500;
+    const maxSimRaw = getFlagValue(args, "--max-similarity");
+    const maxSimilarity = maxSimRaw ? Number.parseFloat(maxSimRaw) : cfgRes.config?.token_economy.max_similarity ?? 0.78;
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
     const bundle = routeRepository(repoPath, catalogDir, {
       taskPrompt,
@@ -4319,60 +6404,59 @@ function runCli(argv) {
     return bundle.passed_invariants ? ExitCode.SUCCESS : ExitCode.ERROR;
   }
   if (command === "sync") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
     const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
-    const targetsIdx = args.indexOf("--targets");
+    const targetsArg = resolveTargetsArg(args);
     let targets;
     try {
-      targets = targetsIdx !== -1 && args[targetsIdx + 1] ? resolveRuntimeTargets(args[targetsIdx + 1], repoPath) : cfgRes.config?.targets ?? [...CORE_RUNTIME_TARGETS];
+      targets = targetsArg ? resolveRuntimeTargets(targetsArg, repoPath) : cfgRes.config?.targets ?? [...CORE_RUNTIME_TARGETS];
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Invalid --targets: ${msg}
 `);
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
+    const maxSkillsRaw = getFlagValue(args, "--max-skills", "--top");
+    const maxSkills = maxSkillsRaw ? Number.parseInt(maxSkillsRaw, 10) : cfgRes.config?.token_economy.max_active_skills;
     const dryRun = args.includes("--dry-run");
     const force = args.includes("--force");
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
     const report = syncRepository(repoPath, catalogDir, {
       targets,
       dryRun,
       force,
-      maxSkills: cfgRes.config?.token_economy.max_active_skills,
+      maxSkills,
       maxL1Tokens: cfgRes.config?.token_economy.max_l1_tokens,
       maxSimilarity: cfgRes.config?.token_economy.max_similarity
     });
     process.stdout.write(formatSyncReport(report, format));
     return report.passed ? ExitCode.SUCCESS : ExitCode.ERROR;
   }
-  if (command === "add") {
-    const itemName = args[1];
-    if (!itemName || itemName.startsWith("-")) {
-      process.stderr.write("Usage: npx skillops@latest add <skill-or-subagent-name> [options]\n");
-      return ExitCode.ERROR;
-    }
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
+  if (command === "add" || command === "install" || command === "i") {
+    const positionals = getPositionalArgs(args);
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
     const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
-    const targetsIdx = args.indexOf("--targets");
+    const targetsArg = resolveTargetsArg(args);
     let targets;
     try {
-      targets = targetsIdx !== -1 && args[targetsIdx + 1] ? resolveRuntimeTargets(args[targetsIdx + 1], repoPath) : cfgRes.config?.targets ?? [...CORE_RUNTIME_TARGETS];
+      targets = targetsArg ? resolveRuntimeTargets(targetsArg, repoPath) : cfgRes.config?.targets ?? [...CORE_RUNTIME_TARGETS];
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Invalid --targets: ${msg}
@@ -4381,14 +6465,42 @@ function runCli(argv) {
     }
     const dryRun = args.includes("--dry-run");
     const force = args.includes("--force");
-    try {
-      const report = addSkillOrSubagent(repoPath, catalogDir, itemName, {
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
+    const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
+    if (positionals.length === 0) {
+      if (command === "add") {
+        process.stderr.write(
+          "Usage: npx skillops-cli add <skill-or-subagent-name> [more-names...] [options]\n"
+        );
+        return ExitCode.ERROR;
+      }
+      const maxSkillsRaw = getFlagValue(args, "--max-skills", "--top");
+      const maxSkills = maxSkillsRaw ? Number.parseInt(maxSkillsRaw, 10) : cfgRes.config?.token_economy.max_active_skills;
+      const report = syncRepository(repoPath, catalogDir, {
         targets,
         dryRun,
-        force
+        force,
+        maxSkills,
+        maxL1Tokens: cfgRes.config?.token_economy.max_l1_tokens,
+        maxSimilarity: cfgRes.config?.token_economy.max_similarity
       });
-      process.stdout.write(formatSyncReport(report, "table"));
+      process.stdout.write(formatSyncReport(report, format));
       return report.passed ? ExitCode.SUCCESS : ExitCode.ERROR;
+    }
+    try {
+      let allPassed = true;
+      for (const itemName of positionals) {
+        const report = addSkillOrSubagent(repoPath, catalogDir, itemName, {
+          targets,
+          dryRun,
+          force
+        });
+        process.stdout.write(formatSyncReport(report, format));
+        if (!report.passed) {
+          allPassed = false;
+        }
+      }
+      return allPassed ? ExitCode.SUCCESS : ExitCode.ERROR;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Error: ${msg}
@@ -4396,37 +6508,44 @@ function runCli(argv) {
       return ExitCode.ERROR;
     }
   }
-  if (command === "remove") {
-    const itemName = args[1];
-    if (!itemName || itemName.startsWith("-")) {
-      process.stderr.write("Usage: npx skillops@latest remove <skill-or-subagent-name> [options]\n");
+  if (command === "remove" || command === "uninstall" || command === "rm") {
+    const positionals = getPositionalArgs(args);
+    if (positionals.length === 0) {
+      process.stderr.write(
+        "Usage: npx skillops-cli remove <skill-or-subagent-name> [options]\n"
+      );
       return ExitCode.ERROR;
     }
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
     const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
-    const targetsIdx = args.indexOf("--targets");
-    const rawTargetsArg = targetsIdx !== -1 && args[targetsIdx + 1] ? args[targetsIdx + 1] : void 0;
+    const rawTargetsArg = resolveTargetsArg(args);
     const dryRun = args.includes("--dry-run");
     const force = args.includes("--force");
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
     try {
       const targets = rawTargetsArg ? resolveRuntimeTargets(rawTargetsArg, repoPath) : void 0;
-      const report = removeSkillOrSubagent(repoPath, catalogDir, itemName, {
-        targets,
-        dryRun,
-        force
-      });
-      process.stdout.write(formatSyncReport(report, format));
-      return report.passed ? ExitCode.SUCCESS : ExitCode.ERROR;
+      let allPassed = true;
+      for (const itemName of positionals) {
+        const report = removeSkillOrSubagent(repoPath, catalogDir, itemName, {
+          targets,
+          dryRun,
+          force
+        });
+        process.stdout.write(formatSyncReport(report, format));
+        if (!report.passed) {
+          allPassed = false;
+        }
+      }
+      return allPassed ? ExitCode.SUCCESS : ExitCode.ERROR;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Error: ${msg}
@@ -4435,39 +6554,40 @@ function runCli(argv) {
     }
   }
   if (command === "clean") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd();
+    const repoPath = getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd();
     const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const catalogDir = resolveCatalogDir(args, repoPath, cfgRes.config);
     const dryRun = args.includes("--dry-run");
     const force = args.includes("--force");
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
-    const report = cleanSyncedArtifacts(repoPath, catalogDir, { dryRun, force });
+    const report = cleanSyncedArtifacts(repoPath, catalogDir, {
+      dryRun,
+      force
+    });
     process.stdout.write(formatSyncReport(report, format));
     return report.passed ? ExitCode.SUCCESS : ExitCode.ERROR;
   }
   if (command === "eval") {
     const catalogDir = resolveCatalogDir(args);
-    const skillIdx = args.indexOf("--skill");
-    const skillFilter = skillIdx !== -1 && args[skillIdx + 1] ? args[skillIdx + 1] : void 0;
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const skillFilter = getFlagValue(args, "--skill");
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "html" || rawFormat === "github" ? rawFormat : "table";
-    const outIdx = args.indexOf("--out");
-    const outPath = outIdx !== -1 && args[outIdx + 1] ? path9.resolve(args[outIdx + 1]) : null;
+    const outRaw = getFlagValue(args, "--out");
+    const outPath = outRaw ? path10.resolve(outRaw) : null;
     const strict = args.includes("--strict");
     const summary = evaluateCatalog(catalogDir, { skillFilter });
     const rendered = formatEvalSummary(summary, format);
     if (outPath) {
-      fs9.mkdirSync(path9.dirname(outPath), { recursive: true });
-      fs9.writeFileSync(outPath, rendered, "utf-8");
+      fs10.mkdirSync(path10.dirname(outPath), { recursive: true });
+      fs10.writeFileSync(outPath, rendered, "utf-8");
     }
     process.stdout.write(rendered);
     if (strict && !summary.passed) {
@@ -4476,26 +6596,26 @@ function runCli(argv) {
     return ExitCode.SUCCESS;
   }
   if (command === "harnesses") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = path9.resolve(
-      repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd()
+    const repoPath = path10.resolve(
+      getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd()
     );
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
     const report = inspectHarnesses(repoPath);
     process.stdout.write(formatHarnessInspectionReport(report, format));
     return ExitCode.SUCCESS;
   }
   if (command === "doctor" || command === "status") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = path9.resolve(
-      repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd()
+    const repoPath = path10.resolve(
+      getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd()
     );
     const loadedConfigRes = loadSkillOpsConfig(repoPath);
-    const catalogDir = resolveCatalogDir(args, repoPath, loadedConfigRes.config);
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const catalogDir = resolveCatalogDir(
+      args,
+      repoPath,
+      loadedConfigRes.config
+    );
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "github" ? rawFormat : "table";
     const strict = args.includes("--strict");
     const report = diagnoseRepository(repoPath, { catalogDir });
@@ -4513,29 +6633,29 @@ function runCli(argv) {
     return ExitCode.SUCCESS;
   }
   if (command === "mcp") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = path9.resolve(
-      repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd()
+    const repoPath = path10.resolve(
+      getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd()
     );
     const catalogDir = resolveCatalogDir(args, repoPath);
     startMcpStdioServer({ repoPath, catalogDir });
     return ExitCode.SUCCESS;
   }
   if (command === "mcp-setup") {
-    const repoIdx = args.indexOf("--repo");
-    const repoPath = path9.resolve(
-      repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : process.cwd()
+    const repoPath = path10.resolve(
+      getFlagValue(args, "--repo", "--project", "-p") ?? process.cwd()
     );
     const cfgRes = loadSkillOpsConfig(repoPath);
     if (cfgRes.error) {
-      process.stderr.write(`Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
-`);
+      process.stderr.write(
+        `Invalid .skillops.yml at ${cfgRes.configPath}: ${cfgRes.error}
+`
+      );
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
-    const targetsIdx = args.indexOf("--targets");
+    const targetsArg = resolveTargetsArg(args);
     let targets;
     try {
-      targets = targetsIdx !== -1 && args[targetsIdx + 1] ? resolveRuntimeTargets(args[targetsIdx + 1], repoPath) : cfgRes.config?.targets ?? [...CORE_RUNTIME_TARGETS];
+      targets = targetsArg ? resolveRuntimeTargets(targetsArg, repoPath) : cfgRes.config?.targets ?? [...CORE_RUNTIME_TARGETS];
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Invalid --targets: ${msg}
@@ -4543,15 +6663,18 @@ function runCli(argv) {
       return ExitCode.BUDGET_OR_CONTRACT_ERROR;
     }
     const dryRun = args.includes("--dry-run");
-    const formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
     const format = rawFormat === "json" || rawFormat === "markdown" ? rawFormat : "table";
     const report = setupMcpForHarnesses(repoPath, { targets, dryRun });
     process.stdout.write(formatMcpSetupReport(report, format));
     return ExitCode.SUCCESS;
   }
-  process.stderr.write(`Unknown command '${command}'. Run 'npx skillops@latest --help'.
-`);
+  const suggestion = suggestCommand(command);
+  const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
+  process.stderr.write(
+    `Unknown command '${command}'.${hint} Run 'npx skillops-cli --help'.
+`
+  );
   return ExitCode.ERROR;
 }
 function isDirectCliInvocation() {
@@ -4560,10 +6683,10 @@ function isDirectCliInvocation() {
     return false;
   }
   try {
-    const resolvedArg = fs9.existsSync(entryArg) ? fs9.realpathSync(entryArg) : path9.resolve(entryArg);
+    const resolvedArg = fs10.existsSync(entryArg) ? fs10.realpathSync(entryArg) : path10.resolve(entryArg);
     const selfPath = fileURLToPath(import.meta.url);
-    const resolvedSelf = fs9.existsSync(selfPath) ? fs9.realpathSync(selfPath) : selfPath;
-    const base = path9.basename(resolvedArg, path9.extname(resolvedArg));
+    const resolvedSelf = fs10.existsSync(selfPath) ? fs10.realpathSync(selfPath) : selfPath;
+    const base = path10.basename(resolvedArg, path10.extname(resolvedArg));
     return pathToFileURL(resolvedArg).href === pathToFileURL(resolvedSelf).href || base === "skillops" || base === "skillops-cli";
   } catch {
     return false;