skillops-cli 1.2.1 → 1.3.1

package/dist/cli.js

@@ -1,20 +1,16 @@
 #!/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";
-
-// src/auditor/parser.ts
-import fs2 from "fs";
-import path from "path";
+import YAML6 from "yaml";
 
 // src/models.ts
 import fs from "fs";
 import YAML from "yaml";
 import { z } from "zod";
-var SKILLOPS_VERSION = "1.2.1";
+var SKILLOPS_VERSION = "1.3.1";
 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]*)$/;
@@ -30,7 +26,9 @@ function estimateTokenCount(text) {
     return 0;
   }
   const words = countWords(stripped);
-  const punctBonus = Math.floor((stripped.match(PUNCT_CODE_REGEX)?.length ?? 0) / 4);
+  const punctBonus = Math.floor(
+    (stripped.match(PUNCT_CODE_REGEX)?.length ?? 0) / 4
+  );
   return Math.max(1, Math.ceil(words * 1.33) + punctBonus);
 }
 function splitFrontmatter(rawText, sourceLabel) {
@@ -44,7 +42,9 @@ function splitFrontmatter(rawText, sourceLabel) {
   const body = match[2] ?? "";
   const parsed = YAML.parse(yamlText);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`YAML frontmatter in '${sourceLabel}' must evaluate to a key-value mapping.`);
+    throw new Error(
+      `YAML frontmatter in '${sourceLabel}' must evaluate to a key-value mapping.`
+    );
   }
   return [parsed, body];
 }
@@ -543,7 +543,9 @@ var SubagentManifestSchema = z.object({
       });
     }
   }),
-  tools: z.array(z.string().min(1)).min(1, { message: "Subagent must declare an explicit non-empty tool allowlist per INV-SKILL-04." }).superRefine((tools, ctx) => {
+  tools: z.array(z.string().min(1)).min(1, {
+    message: "Subagent must declare an explicit non-empty tool allowlist per INV-SKILL-04."
+  }).superRefine((tools, ctx) => {
     for (const tool of tools) {
       if (FORBIDDEN_WILDCARD_TOOLS.has(tool.trim().toLowerCase())) {
         ctx.addIssue({
@@ -734,7 +736,14 @@ var SyncedArtifactSchema = z.object({
   skill_name: z.string().min(1),
   relative_path: z.string().min(1),
   sha256: z.string().regex(/^[0-9a-f]{64}$/),
-  action: z.enum(["created", "updated", "unchanged", "removed", "planned", "conflict"])
+  action: z.enum([
+    "created",
+    "updated",
+    "unchanged",
+    "removed",
+    "planned",
+    "conflict"
+  ])
 }).strict();
 var SyncLockEntrySchema = z.object({
   target: RuntimeTargetSchema,
@@ -820,6 +829,8 @@ function loadSkillOpsConfig(repoPath) {
 }
 
 // src/auditor/parser.ts
+import fs2 from "fs";
+import path from "path";
 function walkForFilesNamed(rootDir, targetFilename) {
   if (!fs2.existsSync(rootDir)) {
     return [];
@@ -852,7 +863,10 @@ function parseSkillDirectory(skillDir, options = {}) {
   const rawText = fs2.readFileSync(skillMdPath, "utf-8");
   const lines = rawText.split(/\r?\n/);
   const totalLines = rawText.endsWith("\n") ? lines.length - 1 : lines.length;
-  const [, markdownBody] = splitFrontmatter(rawText, skillMdPath.replace(/\\/g, "/"));
+  const [, markdownBody] = splitFrontmatter(
+    rawText,
+    skillMdPath.replace(/\\/g, "/")
+  );
   const manifest = parseSkillMdFile(skillMdPath);
   const declaredScripts = [];
   const missingDeclaredScripts = [];
@@ -886,7 +900,9 @@ function parseSkillDirectory(skillDir, options = {}) {
   const referencesDir = path.join(skillDir, "references");
   const referenceFiles = [];
   if (fs2.existsSync(referencesDir) && fs2.statSync(referencesDir).isDirectory()) {
-    for (const entry of fs2.readdirSync(referencesDir, { withFileTypes: true })) {
+    for (const entry of fs2.readdirSync(referencesDir, {
+      withFileTypes: true
+    })) {
       if (entry.isFile() && entry.name.endsWith(".md")) {
         referenceFiles.push(path.join(referencesDir, entry.name));
       }
@@ -951,112 +967,6 @@ function parseSubagentFile(filePath) {
   };
 }
 
-// src/auditor/token_budget.ts
-function auditSkillTokenBudget(skillDir, options = {}) {
-  const requireLayout = options.requireLayout ?? false;
-  try {
-    const parsed = parseSkillDirectory(skillDir, { requireLayout });
-    const warnings = [];
-    const errors = [];
-    if (parsed.manifest.routing_signals.negative_triggers.length === 0 && !parsed.manifest.description.toLowerCase().includes("do not trigger")) {
-      warnings.push(
-        `Skill '${parsed.manifest.name}' has no explicit negative triggers ('Do not trigger for...' or routing_signals.negative_triggers).`
-      );
-    }
-    if (requireLayout && parsed.missingDeclaredScripts.length > 0) {
-      errors.push(
-        `Skill '${parsed.manifest.name}' is missing declared script(s): ${parsed.missingDeclaredScripts.join(", ")}`
-      );
-    }
-    return {
-      skillName: parsed.manifest.name,
-      skillDir: skillDir.replace(/\\/g, "/"),
-      l1Words: parsed.manifest.description_words,
-      l1Tokens: parsed.manifest.description_tokens,
-      l2Lines: parsed.manifest.body_lines,
-      l2Tokens: parsed.manifest.body_tokens,
-      totalLines: parsed.totalLines,
-      scriptsCount: parsed.declaredScripts.length,
-      passed: errors.length === 0,
-      errors,
-      warnings
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      skillName: skillDir.split(/[\\/]/).pop() ?? "unknown",
-      skillDir: skillDir.replace(/\\/g, "/"),
-      l1Words: 0,
-      l1Tokens: 0,
-      l2Lines: 0,
-      l2Tokens: 0,
-      totalLines: 0,
-      scriptsCount: 0,
-      passed: false,
-      errors: [message],
-      warnings: []
-    };
-  }
-}
-function auditSubagentTokenBudget(filePath) {
-  try {
-    const parsed = parseSubagentFile(filePath);
-    return {
-      subagentName: parsed.manifest.name,
-      filePath: filePath.replace(/\\/g, "/"),
-      descriptionTokens: parsed.manifest.description_tokens,
-      systemPromptLines: parsed.manifest.system_prompt_lines,
-      systemPromptTokens: parsed.manifest.system_prompt_tokens,
-      maxOutputTokens: parsed.manifest.max_output_tokens,
-      tools: parsed.manifest.tools,
-      passed: true,
-      errors: []
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      subagentName: filePath.split(/[\\/]/).pop() ?? "unknown",
-      filePath: filePath.replace(/\\/g, "/"),
-      descriptionTokens: 0,
-      systemPromptLines: 0,
-      systemPromptTokens: 0,
-      maxOutputTokens: 0,
-      tools: [],
-      passed: false,
-      errors: [message]
-    };
-  }
-}
-function auditCatalogTokenBudgets(catalogDir, options = {}) {
-  const skillDirs = discoverSkillDirectories(catalogDir);
-  const subagentFiles = discoverSubagentFiles(catalogDir);
-  const skills = skillDirs.map((dir) => auditSkillTokenBudget(dir, options));
-  const subagents = subagentFiles.map((file) => auditSubagentTokenBudget(file));
-  const errors = [];
-  const warnings = [];
-  let totalL1Tokens = 0;
-  let totalSubagentPromptTokens = 0;
-  for (const s of skills) {
-    totalL1Tokens += s.l1Tokens;
-    errors.push(...s.errors);
-    warnings.push(...s.warnings);
-  }
-  for (const sa of subagents) {
-    totalSubagentPromptTokens += sa.systemPromptTokens;
-    errors.push(...sa.errors);
-  }
-  return {
-    catalogPath: catalogDir.replace(/\\/g, "/"),
-    skills,
-    subagents,
-    totalL1Tokens,
-    totalSubagentPromptTokens,
-    errors,
-    warnings,
-    passed: errors.length === 0
-  };
-}
-
 // src/auditor/collision.ts
 var ROUTING_STOPWORDS = /* @__PURE__ */ new Set([
   "a",
@@ -1385,10 +1295,318 @@ function auditCatalog(catalogDir, options = {}) {
   });
 }
 
+// src/auditor/doctor.ts
+import { spawnSync } from "child_process";
+import crypto from "crypto";
+import fs4 from "fs";
+import path3 from "path";
+
 // src/auditor/token_economy.ts
 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 renderHeaderBanner(subtitle = "Framework & Library for AI Skills & Subagents", options) {
+  const ver = options?.version ?? SKILLOPS_VERSION;
+  const c = options?.colorEnabled;
+  return `${style.bold(style.cyan(`\u25C6 SkillOps v${ver}`, c), c)} ${style.dim("\u2014", c)} ${subtitle}`;
+}
+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 ?? 10;
+  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.dim("\u2502", c)}
+${style.dim("\u251C\u2500", c)} ${style.bold(style.cyan(title, c), 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, 20, "left"), colorEnabled);
+  const detailStyled = detail ? ` ${style.dim("\xB7", colorEnabled)} ${detail}` : "";
+  return `${style.dim("\u2502", colorEnabled)}  ${icon} ${stepBadge} ${titleStyled}${detailStyled}`;
+}
+function renderNextSteps(hints, colorEnabled) {
+  if (hints.length === 0) {
+    return "";
+  }
+  const c = colorEnabled;
+  const maxCmdLen = Math.min(
+    44,
+    hints.reduce((m, h) => Math.max(m, visibleLength(h.command)), 0)
+  );
+  const lines = [
+    style.dim("\u2502", c),
+    `${style.dim("\u2570\u2500", c)} ${style.bold(style.cyan("Next Steps:", c), c)}`,
+    ...hints.map((h) => {
+      const cmdPadded = padVisible(h.command, maxCmdLen, "left");
+      const prefixCols = 5 + visibleLength(cmdPadded) + 3;
+      const maxDescCols = Math.max(10, 76 - prefixCols);
+      const desc = h.description.length > maxDescCols ? `${h.description.slice(0, maxDescCols - 1)}\u2026` : h.description;
+      return `   ${style.dim("$", c)} ${style.green(cmdPadded, c)} ${style.dim(`\u2014 ${desc}`, 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 bar = style.dim("\u2502", c);
+  const lines = [
+    bar,
+    `${style.dim("\u251C\u2500", c)} ${style.bold(style.cyan("Using Your Skills & Subagents", c), c)}`
+  ];
+  const targetSet = new Set(targets);
+  if (targetSet.has("claude") || targetSet.size === 0) {
+    lines.push(
+      `${bar}  \u2022 ${style.bold("Claude Code:", c)} Auto-routed (${sampleSkill}) or @${sampleAgent}`
+    );
+  }
+  if (targetSet.has("cursor")) {
+    lines.push(
+      `${bar}  \u2022 ${style.bold("Cursor IDE:", c)} Type ${style.cyan(`@${sampleSkill}`, c)} in Chat (.cursor/rules/)`
+    );
+  }
+  if (targetSet.has("antigravity")) {
+    lines.push(
+      `${bar}  \u2022 ${style.bold("Antigravity:", c)} Auto-activated (.agent/skills/${sampleSkill})`
+    );
+  }
+  if (targetSet.has("copilot")) {
+    lines.push(
+      `${bar}  \u2022 ${style.bold("Copilot:", c)} Use ${style.cyan(`/${sampleSkill}`, c)} in Chat (.github/instructions/)`
+    );
+  }
+  if (targetSet.has("windsurf") || targetSet.has("cline") || targetSet.has("roocode") || targetSet.has("kilocode")) {
+    lines.push(
+      `${bar}  \u2022 ${style.bold("Windsurf/Cline/Roo/Kilo:", c)} Workspace rules load automatically`
+    );
+  }
+  lines.push(
+    `${bar}  \u2022 ${style.bold("Inspect:", c)} ${style.green(`npx skillops-cli info ${sampleSkill}`, c)}`
+  );
+  return lines.join("\n");
+}
+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 +1751,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 +1890,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 +1966,15 @@ function formatTokenEconomyReport(report, format = "table") {
     return `${lines2.join("\n")}
 `;
   }
+  const startupBar = renderProgressBar(
+    report.startup_token_tax,
+    report.startup_tax_budget,
+    { width: 10, 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,15 +1990,23 @@ function formatTokenEconomyReport(report, format = "table") {
       );
     }
   }
+  lines.push(
+    renderNextSteps([
+      {
+        command: "npx skillops-cli quickstart",
+        description: "Sync Progressive Disclosure Skills & Subagents"
+      },
+      {
+        command: "npx skillops-cli doctor",
+        description: "Inspect lockfile & startup tax diagnostics"
+      }
+    ]).trimEnd()
+  );
   return `${lines.join("\n")}
 `;
 }
 
 // src/auditor/doctor.ts
-import { spawnSync } from "child_process";
-import crypto from "crypto";
-import fs4 from "fs";
-import path3 from "path";
 function computeFileSha256(content) {
   return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
 }
@@ -2000,10 +2238,12 @@ function inspectHarnesses(repoPath) {
   const repoLabel = path3.basename(resolvedRepo) || ".";
   const detectedHarnesses = detectInstalledHarnesses(resolvedRepo);
   const detectedSet = new Set(detectedHarnesses);
-  const harnesses = ALL_RUNTIME_TARGETS.map((target) => ({
-    ...RUNTIME_HARNESS_SPECS[target],
-    detected: detectedSet.has(target)
-  }));
+  const harnesses = ALL_RUNTIME_TARGETS.map(
+    (target) => ({
+      ...RUNTIME_HARNESS_SPECS[target],
+      detected: detectedSet.has(target)
+    })
+  );
   return {
     repo_path: repoLabel,
     total_supported: harnesses.length,
@@ -2060,9 +2300,13 @@ function formatDoctorReport(report, format = "table") {
     }
     for (const check of report.checks) {
       if (check.status === "fail") {
-        lines2.push(`::error title=SkillOps Doctor (${check.title})::${check.summary}`);
+        lines2.push(
+          `::error title=SkillOps Doctor (${check.title})::${check.summary}`
+        );
       } else if (check.status === "warn") {
-        lines2.push(`::warning title=SkillOps Doctor (${check.title})::${check.summary}`);
+        lines2.push(
+          `::warning title=SkillOps Doctor (${check.title})::${check.summary}`
+        );
       }
     }
     lines2.push(
@@ -2132,7 +2376,9 @@ function formatDoctorReport(report, format = "table") {
     lines.push("-".repeat(64), "Tracked Lockfile Artifacts:");
     for (const art of report.artifacts) {
       const badge = art.status === "healthy" ? "[HEALTHY]" : art.status === "drifted" ? "[DRIFTED]" : "[MISSING]";
-      lines.push(`  ${badge} ${art.relative_path} (${art.target} :: ${art.item_name})`);
+      lines.push(
+        `  ${badge} ${art.relative_path} (${art.target} :: ${art.item_name})`
+      );
     }
   }
   if (report.remediation.length > 0) {
@@ -2144,43 +2390,149 @@ function formatDoctorReport(report, format = "table") {
   return lines.join("\n");
 }
 
-// src/eval/index.ts
-import fs5 from "fs";
-import path4 from "path";
-import { z as z2 } from "zod";
-var EvalAssertionSchema = z2.object({
-  id: z2.string().min(1),
-  type: z2.string().min(1),
-  target: z2.string().min(1),
-  description: z2.string().min(1)
-}).strict();
-var EvalCaseSchema = z2.object({
-  id: z2.string().min(1),
-  name: z2.string().min(1),
-  prompt: z2.string().min(1),
-  fixtures: z2.array(z2.string()).default([]),
-  assertions: z2.array(EvalAssertionSchema).min(1)
-}).strict();
-var SkillEvalSuiteSchema = z2.object({
-  skill_name: z2.string().min(1),
-  schema_version: z2.string().default("1.0"),
-  evals: z2.array(EvalCaseSchema).min(1)
-}).strict();
-var BenchmarkArmSchema = z2.object({
-  pass_rate_mean: z2.number().min(0).max(1),
-  pass_rate_stddev: z2.number().min(0).max(1),
-  tokens_mean: z2.number().min(0),
-  latency_ms_mean: z2.number().min(0)
-}).strict();
-var BenchmarkDeltaSchema = z2.object({
-  pass_rate_gain: z2.number(),
-  token_reduction_pct: z2.number(),
-  verdict: z2.enum(["CERTIFIED_IMPROVEMENT", "NEUTRAL", "REGRESSION"])
-}).strict();
-var SkillBenchmarkSchema = z2.object({
-  skill_name: z2.string().min(1),
-  runner: z2.string().default("deterministic-ast"),
-  timestamp: z2.string().min(1),
+// src/auditor/token_budget.ts
+function auditSkillTokenBudget(skillDir, options = {}) {
+  const requireLayout = options.requireLayout ?? false;
+  try {
+    const parsed = parseSkillDirectory(skillDir, { requireLayout });
+    const warnings = [];
+    const errors = [];
+    if (parsed.manifest.routing_signals.negative_triggers.length === 0 && !parsed.manifest.description.toLowerCase().includes("do not trigger")) {
+      warnings.push(
+        `Skill '${parsed.manifest.name}' has no explicit negative triggers ('Do not trigger for...' or routing_signals.negative_triggers).`
+      );
+    }
+    if (requireLayout && parsed.missingDeclaredScripts.length > 0) {
+      errors.push(
+        `Skill '${parsed.manifest.name}' is missing declared script(s): ${parsed.missingDeclaredScripts.join(", ")}`
+      );
+    }
+    return {
+      skillName: parsed.manifest.name,
+      skillDir: skillDir.replace(/\\/g, "/"),
+      l1Words: parsed.manifest.description_words,
+      l1Tokens: parsed.manifest.description_tokens,
+      l2Lines: parsed.manifest.body_lines,
+      l2Tokens: parsed.manifest.body_tokens,
+      totalLines: parsed.totalLines,
+      scriptsCount: parsed.declaredScripts.length,
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      skillName: skillDir.split(/[\\/]/).pop() ?? "unknown",
+      skillDir: skillDir.replace(/\\/g, "/"),
+      l1Words: 0,
+      l1Tokens: 0,
+      l2Lines: 0,
+      l2Tokens: 0,
+      totalLines: 0,
+      scriptsCount: 0,
+      passed: false,
+      errors: [message],
+      warnings: []
+    };
+  }
+}
+function auditSubagentTokenBudget(filePath) {
+  try {
+    const parsed = parseSubagentFile(filePath);
+    return {
+      subagentName: parsed.manifest.name,
+      filePath: filePath.replace(/\\/g, "/"),
+      descriptionTokens: parsed.manifest.description_tokens,
+      systemPromptLines: parsed.manifest.system_prompt_lines,
+      systemPromptTokens: parsed.manifest.system_prompt_tokens,
+      maxOutputTokens: parsed.manifest.max_output_tokens,
+      tools: parsed.manifest.tools,
+      passed: true,
+      errors: []
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      subagentName: filePath.split(/[\\/]/).pop() ?? "unknown",
+      filePath: filePath.replace(/\\/g, "/"),
+      descriptionTokens: 0,
+      systemPromptLines: 0,
+      systemPromptTokens: 0,
+      maxOutputTokens: 0,
+      tools: [],
+      passed: false,
+      errors: [message]
+    };
+  }
+}
+function auditCatalogTokenBudgets(catalogDir, options = {}) {
+  const skillDirs = discoverSkillDirectories(catalogDir);
+  const subagentFiles = discoverSubagentFiles(catalogDir);
+  const skills = skillDirs.map((dir) => auditSkillTokenBudget(dir, options));
+  const subagents = subagentFiles.map((file) => auditSubagentTokenBudget(file));
+  const errors = [];
+  const warnings = [];
+  let totalL1Tokens = 0;
+  let totalSubagentPromptTokens = 0;
+  for (const s of skills) {
+    totalL1Tokens += s.l1Tokens;
+    errors.push(...s.errors);
+    warnings.push(...s.warnings);
+  }
+  for (const sa of subagents) {
+    totalSubagentPromptTokens += sa.systemPromptTokens;
+    errors.push(...sa.errors);
+  }
+  return {
+    catalogPath: catalogDir.replace(/\\/g, "/"),
+    skills,
+    subagents,
+    totalL1Tokens,
+    totalSubagentPromptTokens,
+    errors,
+    warnings,
+    passed: errors.length === 0
+  };
+}
+
+// src/eval/index.ts
+import fs5 from "fs";
+import path4 from "path";
+import { z as z2 } from "zod";
+var EvalAssertionSchema = z2.object({
+  id: z2.string().min(1),
+  type: z2.string().min(1),
+  target: z2.string().min(1),
+  description: z2.string().min(1)
+}).strict();
+var EvalCaseSchema = z2.object({
+  id: z2.string().min(1),
+  name: z2.string().min(1),
+  prompt: z2.string().min(1),
+  fixtures: z2.array(z2.string()).default([]),
+  assertions: z2.array(EvalAssertionSchema).min(1)
+}).strict();
+var SkillEvalSuiteSchema = z2.object({
+  skill_name: z2.string().min(1),
+  schema_version: z2.string().default("1.0"),
+  evals: z2.array(EvalCaseSchema).min(1)
+}).strict();
+var BenchmarkArmSchema = z2.object({
+  pass_rate_mean: z2.number().min(0).max(1),
+  pass_rate_stddev: z2.number().min(0).max(1),
+  tokens_mean: z2.number().min(0),
+  latency_ms_mean: z2.number().min(0)
+}).strict();
+var BenchmarkDeltaSchema = z2.object({
+  pass_rate_gain: z2.number(),
+  token_reduction_pct: z2.number(),
+  verdict: z2.enum(["CERTIFIED_IMPROVEMENT", "NEUTRAL", "REGRESSION"])
+}).strict();
+var SkillBenchmarkSchema = z2.object({
+  skill_name: z2.string().min(1),
+  runner: z2.string().default("deterministic-ast"),
+  timestamp: z2.string().min(1),
   eval_cases_count: z2.number().int().min(1).default(1),
   assertions_count: z2.number().int().min(1).default(1),
   with_skill: BenchmarkArmSchema,
@@ -2203,10 +2555,15 @@ function evaluateSkillDirectory(skillDir) {
   const evalsPath = path4.join(skillDir, "evals", "evals.json");
   const rawSuite = JSON.parse(fs5.readFileSync(evalsPath, "utf-8"));
   const suite = SkillEvalSuiteSchema.parse(rawSuite);
-  const assertionsCount = suite.evals.reduce((acc, c) => acc + c.assertions.length, 0);
+  const assertionsCount = suite.evals.reduce(
+    (acc, c) => acc + c.assertions.length,
+    0
+  );
   const benchmarkPath = path4.join(skillDir, "evals", "benchmark.json");
   if (fs5.existsSync(benchmarkPath) && fs5.statSync(benchmarkPath).isFile()) {
-    const rawBench = JSON.parse(fs5.readFileSync(benchmarkPath, "utf-8"));
+    const rawBench = JSON.parse(
+      fs5.readFileSync(benchmarkPath, "utf-8")
+    );
     const bench = SkillBenchmarkSchema.parse({
       ...rawBench,
       eval_cases_count: suite.evals.length,
@@ -2262,18 +2619,25 @@ function evaluateCatalog(catalogDir, options = {}) {
   }
   const count = benchmarks.length;
   const meanWith = count > 0 ? Number(
-    (benchmarks.reduce((acc, b) => acc + b.with_skill.pass_rate_mean, 0) / count).toFixed(4)
+    (benchmarks.reduce(
+      (acc, b) => acc + b.with_skill.pass_rate_mean,
+      0
+    ) / count).toFixed(4)
   ) : 0;
   const meanWithout = count > 0 ? Number(
-    (benchmarks.reduce((acc, b) => acc + b.without_skill.pass_rate_mean, 0) / count).toFixed(
-      4
-    )
+    (benchmarks.reduce(
+      (acc, b) => acc + b.without_skill.pass_rate_mean,
+      0
+    ) / count).toFixed(4)
   ) : 0;
   const meanGain = count > 0 ? Number(
     (benchmarks.reduce((acc, b) => acc + b.delta.pass_rate_gain, 0) / count).toFixed(4)
   ) : 0;
   const meanTokRed = count > 0 ? Number(
-    (benchmarks.reduce((acc, b) => acc + b.delta.token_reduction_pct, 0) / count).toFixed(2)
+    (benchmarks.reduce(
+      (acc, b) => acc + b.delta.token_reduction_pct,
+      0
+    ) / count).toFixed(2)
   ) : 0;
   return CatalogEvalSummarySchema.parse({
     catalog_path: resolvedCatalog.replace(/\\/g, "/"),
@@ -2368,12 +2732,20 @@ ${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";
 import readline from "readline";
 import YAML3 from "yaml";
 
+// src/router/bundle_compiler.ts
+import path6 from "path";
+
 // src/router/fingerprinter.ts
 import fs6 from "fs";
 import path5 from "path";
@@ -2473,13 +2845,17 @@ var RepoFingerprinter = class {
         python312Plus = true;
         signals.add("python3.12");
       }
-      const quotedSpecs = content.match(/["']([a-zA-Z0-9._-]+(?:\[[a-zA-Z0-9,_-]+\])?\s*(?:[><=~!][^"']+)?)["']/g) ?? [];
+      const quotedSpecs = content.match(
+        /["']([a-zA-Z0-9._-]+(?:\[[a-zA-Z0-9,_-]+\])?\s*(?:[><=~!][^"']+)?)["']/g
+      ) ?? [];
       for (const spec of quotedSpecs) {
         recordDep(spec);
       }
     }
     if (fs6.existsSync(this.repoPath)) {
-      for (const entry of fs6.readdirSync(this.repoPath, { withFileTypes: true })) {
+      for (const entry of fs6.readdirSync(this.repoPath, {
+        withFileTypes: true
+      })) {
         if (entry.isFile() && /^requirements.*\.txt$/i.test(entry.name)) {
           detectedFiles.add(entry.name);
           languages.add("python");
@@ -2499,8 +2875,14 @@ var RepoFingerprinter = class {
       signals.add("nodejs");
       signals.add("package.json");
       try {
-        const pkgJson = JSON.parse(fs6.readFileSync(pkgJsonPath, "utf-8"));
-        const depSections = ["dependencies", "devDependencies", "peerDependencies"];
+        const pkgJson = JSON.parse(
+          fs6.readFileSync(pkgJsonPath, "utf-8")
+        );
+        const depSections = [
+          "dependencies",
+          "devDependencies",
+          "peerDependencies"
+        ];
         for (const section of depSections) {
           const obj = pkgJson[section];
           if (obj && typeof obj === "object") {
@@ -2604,7 +2986,6 @@ function fingerprintRepository(repoPath) {
 }
 
 // src/router/bundle_compiler.ts
-import path6 from "path";
 function scoreSkillAgainstProfile(parsedSkill, profile, taskPrompt = "") {
   const manifest = parsedSkill.manifest;
   const repoSignalSet = new Set(
@@ -2639,7 +3020,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 +3060,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 +3178,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 +3201,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: 10,
+      unit: "tokens",
+      colorEnabled
+    }
+  );
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: "npx skillops-cli quickstart",
+        description: "Install recommended bundle & wire MCP"
+      },
+      {
+        command: `npx skillops-cli info ${topSkill}`,
+        description: `Inspect ${topSkill} triggers & L3 scripts`
+      }
+    ],
+    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");
 }
 
@@ -2836,7 +3246,10 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        catalog_dir: { type: "string", description: "Optional path to catalog directory." }
+        catalog_dir: {
+          type: "string",
+          description: "Optional path to catalog directory."
+        }
       },
       additionalProperties: false
     }
@@ -2847,8 +3260,14 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        repo_path: { type: "string", description: "Target repository root path." },
-        startup_tax_budget: { type: "number", description: "Max startup token budget." }
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        },
+        startup_tax_budget: {
+          type: "number",
+          description: "Max startup token budget."
+        }
       },
       additionalProperties: false
     }
@@ -2859,8 +3278,14 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        repo_path: { type: "string", description: "Target repository root path." },
-        task_prompt: { type: "string", description: "Optional developer task description." }
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        },
+        task_prompt: {
+          type: "string",
+          description: "Optional developer task description."
+        }
       },
       additionalProperties: false
     }
@@ -2883,7 +3308,10 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        skill_name: { type: "string", description: "Optional skill name filter." }
+        skill_name: {
+          type: "string",
+          description: "Optional skill name filter."
+        }
       },
       additionalProperties: false
     }
@@ -2903,8 +3331,14 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        repo_path: { type: "string", description: "Target repository root path." },
-        startup_tax_budget: { type: "number", description: "Optional startup token budget override." }
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        },
+        startup_tax_budget: {
+          type: "number",
+          description: "Optional startup token budget override."
+        }
       },
       additionalProperties: false
     }
@@ -2915,7 +3349,10 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        repo_path: { type: "string", description: "Target repository root path." }
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        }
       },
       additionalProperties: false
     }
@@ -2997,7 +3434,9 @@ function handleMcpJsonRpcRequest(request, context) {
         const skillFilter = typeof args.skill_name === "string" ? args.skill_name : void 0;
         payload = evaluateCatalog(context.catalogDir, { skillFilter });
       } else if (toolName === "list_catalog_items") {
-        payload = auditCatalogTokenBudgets(context.catalogDir, { requireLayout: false });
+        payload = auditCatalogTokenBudgets(context.catalogDir, {
+          requireLayout: false
+        });
       } else if (toolName === "diagnose_repo") {
         const repoPath = typeof args.repo_path === "string" ? args.repo_path : context.repoPath;
         const budget = typeof args.startup_tax_budget === "number" ? args.startup_tax_budget : void 0;
@@ -3202,7 +3641,11 @@ function setupMcpForHarnesses(repoPath, options = {}) {
     const absPath = path7.join(resolvedRepo, spec.mcpConfigPath);
     const exists = fs7.existsSync(absPath) && fs7.statSync(absPath).isFile();
     const existingRaw = exists ? fs7.readFileSync(absPath, "utf-8") : null;
-    const updatedRaw = buildUpdatedMcpConfigContent(target, existingRaw, serverName);
+    const updatedRaw = buildUpdatedMcpConfigContent(
+      target,
+      existingRaw,
+      serverName
+    );
     let status;
     if (!exists) {
       status = "created";
@@ -3222,7 +3665,9 @@ function setupMcpForHarnesses(repoPath, options = {}) {
       status
     });
   }
-  const configuredCount = actions.filter((a) => a.status !== "unsupported").length;
+  const configuredCount = actions.filter(
+    (a) => a.status !== "unsupported"
+  ).length;
   return {
     repo_path: path7.basename(resolvedRepo) || ".",
     dry_run: dryRun,
@@ -3701,8 +4146,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 +4202,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 +4265,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 +4336,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 +4384,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 +4484,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 +4506,30 @@ 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 ? renderAiUsageGuide(
+    report.targets,
+    [firstSkill],
+    report.routed_bundle.recommended_subagents,
+    c
+  ) : "";
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli info ${firstSkill}`,
+        description: "Inspect triggers, token budget & L3 scripts"
+      },
+      {
+        command: "npx skillops-cli doctor",
+        description: "Verify lockfile SHA-256 & Startup Token Tax"
+      }
+    ],
+    c
+  );
   return [
     "=== SkillOps Multi-Runtime Transpiler & Sync Engine ===",
     `Repo       : ${report.repo_path}`,
@@ -4040,101 +4539,1644 @@ 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, route & sync",
+    usage: "npx skillops-cli quickstart [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Target repository directory (default: cwd)"
       },
-      detected_stack: {
-        languages: profile.languages,
-        frameworks: profile.frameworks
+      {
+        flags: "-t, --harness <list|auto|all>",
+        description: "Target AI coding harnesses (claude,cursor...)"
       },
-      targets: initTargets
-    });
-    const configPath = path9.join(repoPath, ".skillops.yml");
-    fs9.mkdirSync(repoPath, { recursive: true });
+      {
+        flags: "--top, --max-skills <n>",
+        description: "Max Skills to activate in bundle (default: 12)"
+      },
+      {
+        flags: "--skip-mcp, --no-mcp",
+        description: "Skip automatic MCP server registration"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview planned changes without writing files"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite locally modified artifacts"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output report format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli quickstart",
+        description: "Auto-detect stack, sync Skills & wire MCP"
+      },
+      {
+        command: "npx skillops-cli quickstart -t cursor,claude --top 6",
+        description: "Sync top 6 Skills to Cursor & Claude Code"
+      }
+    ]
+  },
+  {
+    name: "list",
+    aliases: [],
+    pillar: "library",
+    summary: "Browse all 10 Skills & 9 Subagents",
+    usage: "npx skillops-cli list [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Custom catalog directory to list"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli list",
+        description: "Display all 10 Skills & 9 Subagents"
+      },
+      {
+        command: "npx skillops-cli info security-sast-gate",
+        description: "Inspect a specific Skill from the Library"
+      }
+    ]
+  },
+  {
+    name: "search",
+    aliases: ["find"],
+    pillar: "library",
+    summary: "Search catalog by keyword, stack or domain",
+    usage: "npx skillops-cli search <query> [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Custom catalog directory to search"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli search security",
+        description: "Find Skills/Subagents matching security/SAST"
+      },
+      {
+        command: "npx skillops-cli find postgres",
+        description: "Find database & PostgreSQL optimization Skills"
+      }
+    ]
+  },
+  {
+    name: "info",
+    aliases: ["show", "inspect"],
+    pillar: "library",
+    summary: "Inspect triggers, L2 budget & AI usage",
+    usage: "npx skillops-cli info <name> [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Custom catalog directory"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli info bug-reproducer-tdd",
+        description: "Inspect triggers, L3 scripts & IDE invocation"
+      },
+      {
+        command: "npx skillops-cli show red-team-breaker",
+        description: "Inspect the red-team-breaker Subagent card"
+      }
+    ]
+  },
+  {
+    name: "add",
+    aliases: ["install"],
+    pillar: "library",
+    summary: "Install Skills/Subagents into AI harnesses",
+    usage: "npx skillops-cli add <name...> [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "-t, --harness <list|auto|all>",
+        description: "Target AI harnesses (claude,cursor,all...)"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview planned writes without modifying disk"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite locally drifted files"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli install security-sast-gate",
+        description: "Install security-sast-gate into harnesses"
+      },
+      {
+        command: "npx skillops-cli add mcp-architect -t claude,cursor",
+        description: "Install mcp-architect into Claude & Cursor"
+      }
+    ]
+  },
+  {
+    name: "remove",
+    aliases: ["uninstall", "rm"],
+    pillar: "library",
+    summary: "Remove a Skill/Subagent from harnesses",
+    usage: "npx skillops-cli remove <name...> [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "-t, --harness <list>",
+        description: "Restrict removal to specific harnesses"
+      },
+      {
+        flags: "--force",
+        description: "Remove even if SHA-256 drift is detected"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli uninstall mcp-architect",
+        description: "Remove runtime files & update lockfile"
+      }
+    ]
+  },
+  {
+    name: "route",
+    aliases: ["recommend"],
+    pillar: "library",
+    summary: "Recommend optimal <=12 Skill bundle",
+    usage: "npx skillops-cli recommend [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Repository directory to fingerprint"
+      },
+      {
+        flags: "--task <prompt>",
+        description: "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 L1 routing token budget (default: 1500)"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli recommend",
+        description: "Recommend best Skills for current repo stack"
+      },
+      {
+        command: 'npx skillops-cli route --task "slow postgres" --top 4',
+        description: "Route top 4 Skills for a specific task"
+      }
+    ]
+  },
+  {
+    name: "create",
+    aliases: ["new"],
+    pillar: "framework",
+    summary: "Scaffold custom Skill or Subagent template",
+    usage: "npx skillops-cli create <skill|subagent> <name> [options]",
+    options: [
+      {
+        flags: "-d, --description <text>",
+        description: "Custom trigger description (INV-SKILL-01..04)"
+      },
+      {
+        flags: "--catalog <dir>",
+        description: "Target catalog directory (default: ./catalog)"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite existing Skill or Subagent template"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli create skill graphql-schema-guard",
+        description: "Scaffold a new Skill with L3 script & evals"
+      },
+      {
+        command: "npx skillops-cli create subagent migration-reviewer",
+        description: "Scaffold a new Context-Isolated Subagent"
+      }
+    ]
+  },
+  {
+    name: "audit",
+    aliases: [],
+    pillar: "framework",
+    summary: "Verify L1/L2 budgets & TF-IDF collisions",
+    usage: "npx skillops-cli audit [options]",
+    options: [
+      {
+        flags: "--catalog <dir>",
+        description: "Catalog directory to audit"
+      },
+      {
+        flags: "--require-layout",
+        description: "Enforce evals/evals.json and L3 scripts"
+      },
+      {
+        flags: "--strict",
+        description: "Fail on HIGH_RISK as well as BLOCKING collisions"
+      },
+      {
+        flags: "-f, --format <table|json|gh>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli audit --require-layout --strict",
+        description: "Certify token budgets & zero collisions"
+      }
+    ]
+  },
+  {
+    name: "eval",
+    aliases: [],
+    pillar: "framework",
+    summary: "Run deterministic A/B TDD benchmarks",
+    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 benchmark report (HTML/Markdown) to disk"
+      },
+      {
+        flags: "--strict",
+        description: "Exit 4 if any Skill fails CERTIFIED_IMPROVEMENT"
+      },
+      {
+        flags: "-f, --format <table|json|html>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli eval --strict",
+        description: "Run deterministic A/B evals across catalog"
+      },
+      {
+        command: "npx skillops-cli eval -f html --out benchmark.html",
+        description: "Export standalone HTML benchmark dashboard"
+      }
+    ]
+  },
+  {
+    name: "init",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Create .skillops.yml and detect harnesses",
+    usage: "npx skillops-cli init [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "-t, --harness <list|auto|all>",
+        description: "Initial target harnesses for .skillops.yml"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli init",
+        description: "Create .skillops.yml with detected harnesses"
+      }
+    ]
+  },
+  {
+    name: "sync",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Transpile bundle across 20 AI agents",
+    usage: "npx skillops-cli sync [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "-t, --harness <list|auto|all>",
+        description: "Target AI harnesses (default: .skillops.yml)"
+      },
+      {
+        flags: "--top, --max-skills <n>",
+        description: "Maximum Skills to sync"
+      },
+      {
+        flags: "--dry-run",
+        description: "Preview planned artifacts without writing"
+      },
+      {
+        flags: "--force",
+        description: "Overwrite locally drifted files"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli sync --auto",
+        description: "Sync bundle into all detected AI harnesses"
+      },
+      {
+        command: "npx skillops-cli sync --harness all",
+        description: "Transpile across all 20 supported AI agents"
+      }
+    ]
+  },
+  {
+    name: "clean",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Remove all tracked runtime artifacts",
+    usage: "npx skillops-cli clean [options]",
+    options: [
+      {
+        flags: "-p, --project <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: "Remove all synced artifacts & lockfile"
+      }
+    ]
+  },
+  {
+    name: "tokens",
+    aliases: ["budget"],
+    pillar: "runtime",
+    summary: "Analyze Startup Token Tax & context bloat",
+    usage: "npx skillops-cli budget [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Repository directory to inspect"
+      },
+      {
+        flags: "--budget <tokens>",
+        description: "Startup Token Tax ceiling (default: 2500)"
+      },
+      {
+        flags: "--strict",
+        description: "Exit 3 if Startup Token Tax exceeds budget"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli budget",
+        description: "Inspect repository Startup Token Tax & savings"
+      }
+    ]
+  },
+  {
+    name: "doctor",
+    aliases: ["status"],
+    pillar: "runtime",
+    summary: "Diagnose environment, drift & token budget",
+    usage: "npx skillops-cli doctor [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Repository directory to diagnose"
+      },
+      {
+        flags: "--strict",
+        description: "Fail on warnings as well as errors"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        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 20 supported AI agents & repo status",
+    usage: "npx skillops-cli harnesses [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Repository directory to scan for AI harnesses"
+      },
+      {
+        flags: "-f, --format <table|json|md>",
+        description: "Output format (default: table)"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli harnesses",
+        description: "View all 20 supported AI IDEs/CLI agents"
+      }
+    ]
+  },
+  {
+    name: "mcp-setup",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Wire MCP server across 13 AI IDEs & agents",
+    usage: "npx skillops-cli mcp-setup [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Target repository directory"
+      },
+      {
+        flags: "-t, --harness <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: "Wire SkillOps MCP into detected IDEs"
+      }
+    ]
+  },
+  {
+    name: "mcp",
+    aliases: [],
+    pillar: "runtime",
+    summary: "Start stdio JSON-RPC 2.0 MCP server",
+    usage: "npx skillops-cli mcp [options]",
+    options: [
+      {
+        flags: "-p, --project <dir>",
+        description: "Repository root served over MCP"
+      }
+    ],
+    examples: [
+      {
+        command: "npx skillops-cli mcp",
+        description: "Start stdio MCP server for 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 bar = style.dim("\u2502", c);
+  const banner = renderHeaderBanner(
+    "Framework & Library for AI Skills & Subagents",
+    {
+      version,
+      colorEnabled: c
+    }
+  );
+  const formatCmdSection = (pillar) => {
+    const specs = COMMAND_HELP_SPECS.filter((s) => s.pillar === pillar);
+    return specs.map((s) => {
+      const aliasPart = s.aliases.length > 0 ? style.dim(` (${s.aliases.join(", ")})`, c) : "";
+      const cmdCol = padVisible(
+        `${style.bold(style.cyan(s.name, c), c)}${aliasPart}`,
+        23,
+        "left"
+      );
+      return `${bar}  ${cmdCol}${s.summary}`;
+    }).join("\n");
+  };
+  return [
+    banner,
+    `${bar}  Usage: npx skillops-cli <command> [options]`,
+    renderSectionHeader("Quickstart (Library + Framework)", c),
+    `${bar}  ${style.dim("$", c)} ${style.bold(style.green("npx skillops-cli quickstart", c), c)}          ${style.dim("\u2014 Detect stack, sync Skills & MCP", c)}`,
+    `${bar}  ${style.dim("$", c)} ${style.bold(style.cyan("npx skillops-cli info <name>", c), c)}         ${style.dim("\u2014 Inspect Skill/Subagent & usage", c)}`,
+    `${bar}  ${style.dim("$", c)} ${style.bold(style.magenta("npx skillops-cli create skill <name>", c), c)} ${style.dim("\u2014 Scaffold a custom Skill", c)}`,
+    renderSectionHeader("1. Library of High-End Skills & Subagents", c),
+    formatCmdSection("library"),
+    renderSectionHeader(
+      "2. Framework for Building Custom Skills & Subagents",
+      c
+    ),
+    formatCmdSection("framework"),
+    renderSectionHeader(
+      "3. Universal Runtime Sync, Token Economy & Diagnostics",
+      c
+    ),
+    formatCmdSection("runtime"),
+    bar,
+    `${style.dim("\u2570\u2500", c)} ${style.bold("Global Flags:", c)} ${style.cyan("-p <dir>", c)} \xB7 ${style.cyan("-t <harnesses>", c)} \xB7 ${style.cyan("-f <table|json|md>", c)} \xB7 ${style.cyan("-h <cmd>", c)}`
+  ].join("\n");
+}
+function renderCommandHelp(spec, version, colorEnabled) {
+  const c = colorEnabled;
+  const bar = style.dim("\u2502", c);
+  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 headerLines = [
+    `${style.bold(style.cyan(`\u25C6 SkillOps v${version}`, c), c)} ${style.dim("\u2014", c)} ${style.bold(`skillops ${spec.name}`, c)}${aliasText} ${pillarBadge}`,
+    `${bar}  ${spec.summary}`,
+    `${bar}  ${style.bold("Usage:", c)} ${style.green(spec.usage, c)}`
+  ].join("\n");
+  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: 3 }
+    )
+  ].join("\n") : "";
+  const examplesSection = renderNextSteps(spec.examples, c);
+  return [headerLines, 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 bar = style.dim("\u2502", c);
+  const badge = info.kind === "skill" ? formatBadge("skill", "HYBRID EXECUTABLE SKILL", c) : formatBadge("subagent", "CONTEXT-ISOLATED SUBAGENT", c);
+  const shortDesc = info.description.length > 68 ? `${info.description.slice(0, 65)}...` : info.description;
+  const cardLines = [
+    `${style.bold(style.cyan(`\u25C6 SkillOps Library Inspector \u2014 ${info.name}`, c), c)}`,
+    `${bar}  ${badge}`,
+    `${bar}  ${shortDesc}`,
+    bar
+  ];
+  if (info.kind === "skill") {
+    cardLines.push(
+      `${style.dim("\u251C\u2500", c)} ${style.bold(style.cyan("Token Economy (INV-SKILL-01..03)", c), c)}`,
+      `${bar}  \u2022 L1 Routing     : ${style.green(`${info.l1Tokens} tokens`, c)} (<= 160 budget)`,
+      `${bar}  \u2022 L2 Playbook    : ${info.l2Lines} lines (${info.l2Tokens}t, <= 250 lines)`,
+      `${bar}  \u2022 Token Savings  : ${style.bold(style.green(`${info.savingsPct}%`, c), c)} Startup Tax saved`,
+      `${bar}  \u2022 L3 Scripts (${info.scripts.length}) : ${info.scripts.length > 0 ? style.cyan(info.scripts.join(", "), c) : "none"}`,
+      `${bar}  \u2022 TDD Evals      : ${info.evalCasesCount} deterministic cases`
+    );
+  } else {
+    cardLines.push(
+      `${style.dim("\u251C\u2500", c)} ${style.bold(style.cyan("Context Isolation Contract (INV-SKILL-04)", c), c)}`,
+      `${bar}  \u2022 System Prompt  : ${style.green(`${info.l1Tokens} tokens`, c)}`,
+      `${bar}  \u2022 Max Output Cap : <= ${style.bold(`${info.maxOutputTokens} tokens`, c)}`,
+      `${bar}  \u2022 Isolation Mode : ${style.cyan(info.isolation ?? "context-isolated", c)}`,
+      `${bar}  \u2022 Allowed Tools  : ${info.tools.join(", ")}`
+    );
+  }
+  if (info.headings.length > 0) {
+    cardLines.push(
+      bar,
+      `${style.dim("\u251C\u2500", c)} ${style.bold(style.cyan("Playbook Sections", c), c)}`,
+      ...info.headings.slice(0, 5).map((h) => `${bar}  \u2022 ${h}`)
+    );
+  }
+  cardLines.push(
+    bar,
+    `${style.dim("\u251C\u2500", c)} ${style.bold(style.cyan("How to Invoke in Your AI Agent", c), c)}`,
+    `${bar}  \u2022 ${style.bold("Install:", c)} ${style.green(`npx skillops-cli add ${info.name}`, c)}`,
+    info.kind === "skill" ? `${bar}  \u2022 ${style.bold("IDE Chat:", c)} Reference ${style.cyan(`@${info.name}`, c)} or ${style.cyan(`/${info.name}`, c)}` : `${bar}  \u2022 ${style.bold("Delegate:", c)} Ask main agent to run ${style.magenta(`@${info.name}`, c)}`
+  );
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli add ${info.name}`,
+        description: "Install into AI agents"
+      },
+      ...info.kind === "skill" ? [
+        {
+          command: `npx skillops-cli eval --skill ${info.name}`,
+          description: "Run TDD benchmark"
+        }
+      ] : [],
+      {
+        command: "npx skillops-cli list",
+        description: "Browse 10 Skills & 9 Subagents"
+      }
+    ],
+    c
+  );
+  return `${cardLines.join("\n")}
+${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 > 30 ? `${parsed.manifest.description.slice(0, 27)}...` : 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 > 30 ? `${parsed.manifest.description.slice(0, 27)}...` : 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 bar = style.dim("\u2502", c);
+  const header = `${style.bold(style.cyan("\u25C6 SkillOps Library Search", c), c)} ${style.dim("\u2014", c)} Query: ${style.bold(`"${report.query || "*"}"`, c)} (${report.total_matches} matches)`;
+  if (report.matches.length === 0) {
+    return `${header}
+${bar}  ${formatBadge("warn", "No matching Skills or Subagents found.", c)}
+${renderNextSteps([{ command: "npx skillops-cli list", description: "View all 10 Skills & 9 Subagents" }], c)}`;
+  }
+  const table = renderTable(
+    ["Type", "Name", "Tokens", "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, indent: 3 }
+  );
+  const topItem = report.matches[0]?.name ?? "bug-reproducer-tdd";
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli info ${topItem}`,
+        description: "Inspect triggers & usage"
+      },
+      {
+        command: `npx skillops-cli add ${topItem}`,
+        description: "Install into AI agents"
+      }
+    ],
+    c
+  );
+  return `${header}
+${bar}
+${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 bar = style.dim("\u2502", c);
+  const treeHeader = [
+    `${style.bold(style.cyan("\u25C6 SkillOps Framework Scaffolder", c), c)} ${style.dim("\u2014", c)} ${formatBadge("pass", "CREATED", c)} ${style.bold(result.kind.toUpperCase(), c)} ${style.bold(style.cyan(result.name, c), c)}`,
+    bar,
+    `${style.dim("\u251C\u2500", c)} ${style.bold("Generated Files:", c)}`,
+    ...result.created_files.map((f) => `${bar}  \u2022 ${style.green(f, c)}`)
+  ].join("\n");
+  const nextSteps = renderNextSteps(
+    [
+      {
+        command: `npx skillops-cli info ${result.name}`,
+        description: `Inspect new ${result.kind} metadata & budget`
+      },
+      {
+        command: "npx skillops-cli audit --require-layout",
+        description: "Verify INV-SKILL-01..04 & collisions"
+      },
+      {
+        command: `npx skillops-cli add ${result.name}`,
+        description: `Install '${result.name}' into AI agents`
+      }
+    ],
+    c
+  );
+  return `${treeHeader}
+${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 bar = style.dim("\u2502", c);
+  const stackLabel = [...report.detected_languages, ...report.detected_frameworks].join(", ") || "general";
+  const targetsLabel = report.active_targets.length > 4 ? `${report.active_targets.slice(0, 4).join(", ")} (+${report.active_targets.length - 4})` : report.active_targets.join(", ");
+  const banner = renderHeaderBanner(
+    `Quickstart Setup ${report.dry_run ? "[DRY-RUN]" : "[READY]"}`,
+    { colorEnabled: c }
+  );
+  const stepsBlock = [
+    renderStep(
+      1,
+      4,
+      "Detect Stack & Agents",
+      `${style.cyan(stackLabel, c)} \xB7 ${style.bold(targetsLabel, c)}`,
+      "done",
+      c
+    ),
+    renderStep(
+      2,
+      4,
+      "Route Library Bundle",
+      `${style.green(`${report.selected_skills.length} Skills`, c)} + ${style.magenta(`${report.selected_subagents.length} Subagents`, c)}`,
+      "done",
+      c
+    ),
+    renderStep(
+      3,
+      4,
+      "Transpile & Sync",
+      `${report.synced_files_count} files (${report.dry_run ? "dry-run" : ".skillops.yml + lockfile"})`,
+      "done",
+      c
+    ),
+    renderStep(
+      4,
+      4,
+      "Register MCP Server",
+      `${report.mcp_configured_count} MCP agent config(s) wired`,
+      "done",
+      c
+    )
+  ].join("\n");
+  const tokenBar = `${bar}  ${renderTokenBar(
+    report.total_l1_tokens,
+    report.max_l1_budget,
+    {
+      label: "L1 Routing Budget:",
+      colorEnabled: c
+    }
+  )}`;
+  const bundleTree = [
+    bar,
+    `${style.dim("\u251C\u2500", c)} ${style.bold(style.cyan(`Active Bundle (${report.selected_skills.length} Skills \xB7 ${report.selected_subagents.length} Subagents)`, c), c)}`,
+    `${bar}  \u2022 ${style.bold("Skills:", c)} ${report.selected_skills.slice(0, 2).map((s) => style.cyan(s, c)).join(
+      ", "
+    )}${report.selected_skills.length > 2 ? ` (+${report.selected_skills.length - 2} more)` : ""}`,
+    `${bar}  \u2022 ${style.bold("Subagents:", c)} ${report.selected_subagents.slice(0, 2).map((a) => style.magenta(a, c)).join(
+      ", "
+    )}${report.selected_subagents.length > 2 ? ` (+${report.selected_subagents.length - 2} more)` : ""}`
+  ].join("\n");
+  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 Skill triggers & L3 scripts"
+      },
+      {
+        command: "npx skillops-cli list",
+        description: "Browse all 10 Skills & 9 Subagents"
+      },
+      {
+        command: "npx skillops-cli create skill my-skill",
+        description: "Create a custom Skill"
+      },
+      {
+        command: "npx skillops-cli doctor",
+        description: "Verify lockfile & Startup Token Tax"
+      }
+    ],
+    c
+  );
+  return [
+    banner,
+    bar,
+    stepsBlock,
+    tokenBar,
+    bundleTree,
+    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, "/")}
 `
@@ -4142,18 +6184,20 @@ function runCli(argv) {
     return ExitCode.SUCCESS;
   }
   if (command === "list") {
-    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 formatIdx = args.indexOf("--format");
-    const rawFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : "table";
-    const summary = auditCatalogTokenBudgets(catalogDir, { requireLayout: false });
+    const rawFormat = getFlagValue(args, "--format", "-f") ?? "table";
+    const summary = auditCatalogTokenBudgets(catalogDir, {
+      requireLayout: false
+    });
     if (rawFormat === "json") {
       process.stdout.write(`${JSON.stringify(summary, null, 2)}
 `);
@@ -4185,9 +6229,15 @@ function runCli(argv) {
       process.stdout.write(lines2.join("\n"));
       return ExitCode.SUCCESS;
     }
+    const l1Bar = renderProgressBar(summary.totalL1Tokens, 1500, {
+      width: 10,
+      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}`
       ),
@@ -4195,25 +6245,38 @@ function runCli(argv) {
       ...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 & usage"
+        },
+        {
+          command: "npx skillops-cli search <keyword>",
+          description: "Search Skills & Subagents"
+        },
+        {
+          command: "npx skillops-cli quickstart",
+          description: "Auto-detect & install"
+        }
+      ])
     ];
     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 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 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 +6325,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 +6351,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 +6381,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 +6442,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 +6485,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 +6531,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 +6573,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 +6610,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 +6640,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 +6660,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;