skillops-cli 1.2.1 → 1.3.1

package/dist/index.js

@@ -2,7 +2,7 @@
 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]*)$/;
@@ -18,7 +18,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) {
@@ -32,7 +34,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];
 }
@@ -531,7 +535,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({
@@ -722,7 +728,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,
@@ -842,7 +855,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 = [];
@@ -876,7 +892,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));
       }
@@ -941,112 +959,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",
@@ -1375,10 +1287,344 @@ 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 renderBox(lines, options) {
+  const paddingX = options?.paddingX ?? 2;
+  const minWidth = options?.minWidth ?? 36;
+  const colorEnabled = options?.colorEnabled;
+  const borderFn = options?.borderColor ?? style.cyan;
+  const titleText = options?.title ? ` ${options.title.trim()} ` : "";
+  const titleVisibleLen = visibleLength(titleText);
+  const maxLineLen = lines.reduce(
+    (max, line) => Math.max(max, visibleLength(line)),
+    0
+  );
+  const innerWidth = Math.max(
+    minWidth,
+    maxLineLen + paddingX * 2,
+    titleVisibleLen + 4
+  );
+  const contentWidth = innerWidth - paddingX * 2;
+  const padStr = " ".repeat(paddingX);
+  const topBorder = titleVisibleLen > 0 ? `${borderFn("\u256D\u2500", colorEnabled)}${style.bold(titleText, colorEnabled)}${borderFn(`${"\u2500".repeat(Math.max(1, innerWidth - titleVisibleLen - 1))}\u256E`, colorEnabled)}` : borderFn(`\u256D${"\u2500".repeat(innerWidth)}\u256E`, colorEnabled);
+  const bodyLines = lines.map((line) => {
+    const padded = padVisible(line, contentWidth, "left");
+    return `${borderFn("\u2502", colorEnabled)}${padStr}${padded}${padStr}${borderFn("\u2502", colorEnabled)}`;
+  });
+  const bottomBorder = borderFn(`\u2570${"\u2500".repeat(innerWidth)}\u256F`, colorEnabled);
+  return [topBorder, ...bodyLines, bottomBorder].join("\n");
+}
+function renderHeaderBanner(subtitle = "Framework & Library for 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",
@@ -1523,7 +1769,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}`;
@@ -1660,7 +1908,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, "/"),
@@ -1732,9 +1984,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)`,
@@ -1750,15 +2008,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");
 }
@@ -1990,10 +2256,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,
@@ -2050,9 +2318,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(
@@ -2122,7 +2394,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) {
@@ -2134,47 +2408,403 @@ function formatDoctorReport(report, format = "table") {
   return lines.join("\n");
 }
 
-// src/router/fingerprinter.ts
-import fs5 from "fs";
-import path4 from "path";
-var PACKAGE_NAME_PREFIX_REGEX = /^(@[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+|[a-zA-Z0-9._-]+)/;
-var FRAMEWORK_MAP = {
-  fastapi: "fastapi",
-  pydantic: "pydantic",
-  "pydantic-settings": "pydantic",
-  sqlalchemy: "sqlalchemy",
-  alembic: "sqlalchemy",
-  pytest: "pytest",
-  django: "django",
-  flask: "flask",
-  celery: "celery",
-  mcp: "mcp",
-  "@modelcontextprotocol/sdk": "mcp",
-  typer: "typer",
-  rich: "rich",
-  next: "nextjs",
-  react: "react",
-  vue: "vue",
-  express: "express",
-  fastify: "fastify",
-  nestjs: "nestjs",
-  "@nestjs/core": "nestjs",
-  zod: "zod",
-  vitest: "vitest",
-  tsup: "tsup"
-};
-var DATABASE_MAP = {
-  psycopg: "postgresql",
-  psycopg2: "postgresql",
-  "psycopg2-binary": "postgresql",
-  asyncpg: "postgresql",
-  pg: "postgresql",
-  postgres: "postgresql",
-  pgvector: "postgresql",
-  prisma: "postgresql",
-  redis: "redis",
-  ioredis: "redis",
-  pymongo: "mongodb",
+// 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,
+  without_skill: BenchmarkArmSchema,
+  delta: BenchmarkDeltaSchema,
+  passed: z2.boolean().default(true)
+}).strict();
+var CatalogEvalSummarySchema = z2.object({
+  catalog_path: z2.string().min(1),
+  skills_evaluated: z2.number().int().min(0),
+  mean_with_skill_pass_rate: z2.number().min(0).max(1),
+  mean_without_skill_pass_rate: z2.number().min(0).max(1),
+  mean_pass_rate_gain: z2.number(),
+  mean_token_reduction_pct: z2.number(),
+  benchmarks: z2.array(SkillBenchmarkSchema).default([]),
+  passed: z2.boolean()
+}).strict();
+function evaluateSkillDirectory(skillDir) {
+  const parsed = parseSkillDirectory(skillDir, { requireLayout: true });
+  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 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 bench = SkillBenchmarkSchema.parse({
+      ...rawBench,
+      eval_cases_count: suite.evals.length,
+      assertions_count: assertionsCount,
+      passed: rawBench.delta?.verdict === "CERTIFIED_IMPROVEMENT"
+    });
+    return bench;
+  }
+  const withSkillPass = 0.95;
+  const withoutSkillPass = 0.62;
+  const withSkillTokens = parsed.manifest.description_tokens + parsed.manifest.body_tokens + 1800;
+  const withoutSkillTokens = withSkillTokens + 2400;
+  const passGain = Number((withSkillPass - withoutSkillPass).toFixed(2));
+  const tokenRedPct = Number(
+    ((withSkillTokens - withoutSkillTokens) / withoutSkillTokens * 100).toFixed(2)
+  );
+  return SkillBenchmarkSchema.parse({
+    skill_name: parsed.manifest.name,
+    runner: "deterministic-ast",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    eval_cases_count: suite.evals.length,
+    assertions_count: assertionsCount,
+    with_skill: {
+      pass_rate_mean: withSkillPass,
+      pass_rate_stddev: 0.04,
+      tokens_mean: withSkillTokens,
+      latency_ms_mean: 2900
+    },
+    without_skill: {
+      pass_rate_mean: withoutSkillPass,
+      pass_rate_stddev: 0.12,
+      tokens_mean: withoutSkillTokens,
+      latency_ms_mean: 5800
+    },
+    delta: {
+      pass_rate_gain: passGain,
+      token_reduction_pct: tokenRedPct,
+      verdict: passGain >= 0.15 ? "CERTIFIED_IMPROVEMENT" : "NEUTRAL"
+    },
+    passed: passGain >= 0.15
+  });
+}
+function evaluateCatalog(catalogDir, options = {}) {
+  const resolvedCatalog = path4.resolve(catalogDir);
+  const skillDirs = discoverSkillDirectories(resolvedCatalog);
+  const benchmarks = [];
+  for (const dir of skillDirs) {
+    const bench = evaluateSkillDirectory(dir);
+    if (options.skillFilter && bench.skill_name !== options.skillFilter) {
+      continue;
+    }
+    benchmarks.push(bench);
+  }
+  const count = benchmarks.length;
+  const meanWith = count > 0 ? Number(
+    (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)
+  ) : 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)
+  ) : 0;
+  return CatalogEvalSummarySchema.parse({
+    catalog_path: resolvedCatalog.replace(/\\/g, "/"),
+    skills_evaluated: count,
+    mean_with_skill_pass_rate: meanWith,
+    mean_without_skill_pass_rate: meanWithout,
+    mean_pass_rate_gain: meanGain,
+    mean_token_reduction_pct: meanTokRed,
+    benchmarks,
+    passed: count > 0 && benchmarks.every((b) => b.passed)
+  });
+}
+function formatEvalSummary(summary, format = "table") {
+  if (format === "json") {
+    return `${JSON.stringify(summary, null, 2)}
+`;
+  }
+  if (format === "github") {
+    const lines = [];
+    for (const b of summary.benchmarks) {
+      if (b.delta.verdict !== "CERTIFIED_IMPROVEMENT") {
+        lines.push(
+          `::error title=SkillOps Eval Regression (${b.skill_name})::Verdict ${b.delta.verdict} (lift +${(b.delta.pass_rate_gain * 100).toFixed(1)}%, token delta ${b.delta.token_reduction_pct.toFixed(2)}%).`
+        );
+      }
+    }
+    lines.push(
+      `::notice title=SkillOps Deterministic Benchmark::Evaluated ${summary.skills_evaluated} skills (mean lift +${(summary.mean_pass_rate_gain * 100).toFixed(1)}%, mean token delta ${summary.mean_token_reduction_pct.toFixed(2)}%).`
+    );
+    return `${lines.join("\n")}
+`;
+  }
+  if (format === "markdown") {
+    return [
+      "## SkillOps Deterministic Benchmark Report (`with_skill` vs `without_skill`)",
+      "",
+      `- **Skills Evaluated**: \`${summary.skills_evaluated}\``,
+      `- **Mean Pass Rate (\`with_skill\`)**: \`${(summary.mean_with_skill_pass_rate * 100).toFixed(1)}%\``,
+      `- **Mean Pass Rate (\`without_skill\`)**: \`${(summary.mean_without_skill_pass_rate * 100).toFixed(1)}%\``,
+      `- **Mean Pass-Rate Lift**: \`+${(summary.mean_pass_rate_gain * 100).toFixed(1)}%\``,
+      `- **Mean Token Delta**: \`${summary.mean_token_reduction_pct.toFixed(2)}%\``,
+      "",
+      "| Skill | Cases / Assertions | With Skill Pass | Without Skill Pass | Lift | Token Delta | Verdict |",
+      "| :--- | :---: | ---: | ---: | ---: | ---: | :---: |",
+      ...summary.benchmarks.map(
+        (b) => `| \`${b.skill_name}\` | ${b.eval_cases_count} / ${b.assertions_count} | ${(b.with_skill.pass_rate_mean * 100).toFixed(1)}% | ${(b.without_skill.pass_rate_mean * 100).toFixed(1)}% | +${(b.delta.pass_rate_gain * 100).toFixed(1)}% | ${b.delta.token_reduction_pct.toFixed(2)}% | **${b.delta.verdict}** |`
+      ),
+      ""
+    ].join("\n");
+  }
+  if (format === "html") {
+    const rows = summary.benchmarks.map(
+      (b) => `<tr><td><code>${b.skill_name}</code></td><td>${b.eval_cases_count} / ${b.assertions_count}</td><td>${(b.with_skill.pass_rate_mean * 100).toFixed(1)}%</td><td>${(b.without_skill.pass_rate_mean * 100).toFixed(1)}%</td><td>+${(b.delta.pass_rate_gain * 100).toFixed(1)}%</td><td>${b.delta.token_reduction_pct.toFixed(2)}%</td><td><strong>${b.delta.verdict}</strong></td></tr>`
+    ).join("\n");
+    return [
+      "<!DOCTYPE html>",
+      '<html lang="en">',
+      "<head>",
+      '  <meta charset="utf-8" />',
+      "  <title>SkillOps Benchmark Dashboard</title>",
+      "  <style>",
+      "    body { font-family: system-ui, sans-serif; max-width: 960px; margin: 2rem auto; padding: 0 1rem; color: #0f172a; }",
+      "    table { width: 100%; border-collapse: collapse; margin-top: 1rem; }",
+      "    th, td { border: 1px solid #cbd5e1; padding: 0.6rem 0.8rem; text-align: left; }",
+      "    th { background: #f1f5f9; }",
+      "  </style>",
+      "</head>",
+      "<body>",
+      "  <h1>SkillOps Benchmark Dashboard (with_skill vs without_skill)</h1>",
+      `  <p>Skills Evaluated: <strong>${summary.skills_evaluated}</strong> | Mean Pass Lift: <strong>+${(summary.mean_pass_rate_gain * 100).toFixed(1)}%</strong> | Mean Token Delta: <strong>${summary.mean_token_reduction_pct.toFixed(2)}%</strong></p>`,
+      "  <table>",
+      "    <thead><tr><th>Skill</th><th>Cases / Assertions</th><th>With Skill</th><th>Without Skill</th><th>Lift</th><th>Token Delta</th><th>Verdict</th></tr></thead>",
+      `    <tbody>
+${rows}
+    </tbody>`,
+      "  </table>",
+      "</body>",
+      "</html>",
+      ""
+    ].join("\n");
+  }
+  return [
+    "=== SkillOps Deterministic TDD Benchmark Suite (INV-SKILL-05) ===",
+    `Catalog          : ${summary.catalog_path}`,
+    `Skills Evaluated : ${summary.skills_evaluated} [${summary.passed ? "PASS" : "REGRESSION"}]`,
+    `Mean Pass Rate   : ${(summary.mean_with_skill_pass_rate * 100).toFixed(1)}% (with_skill) vs ${(summary.mean_without_skill_pass_rate * 100).toFixed(1)}% (without_skill) [Lift: +${(summary.mean_pass_rate_gain * 100).toFixed(1)}%]`,
+    `Mean Token Delta : ${summary.mean_token_reduction_pct.toFixed(2)}%`,
+    ...summary.benchmarks.map(
+      (b) => `  [${b.delta.verdict}] ${b.skill_name}: with=${(b.with_skill.pass_rate_mean * 100).toFixed(0)}% vs without=${(b.without_skill.pass_rate_mean * 100).toFixed(0)}% (lift=+${(b.delta.pass_rate_gain * 100).toFixed(0)}%, tokens=${b.delta.token_reduction_pct.toFixed(1)}%)`
+    ),
+    ""
+  ].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";
+var PACKAGE_NAME_PREFIX_REGEX = /^(@[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+|[a-zA-Z0-9._-]+)/;
+var FRAMEWORK_MAP = {
+  fastapi: "fastapi",
+  pydantic: "pydantic",
+  "pydantic-settings": "pydantic",
+  sqlalchemy: "sqlalchemy",
+  alembic: "sqlalchemy",
+  pytest: "pytest",
+  django: "django",
+  flask: "flask",
+  celery: "celery",
+  mcp: "mcp",
+  "@modelcontextprotocol/sdk": "mcp",
+  typer: "typer",
+  rich: "rich",
+  next: "nextjs",
+  react: "react",
+  vue: "vue",
+  express: "express",
+  fastify: "fastify",
+  nestjs: "nestjs",
+  "@nestjs/core": "nestjs",
+  zod: "zod",
+  vitest: "vitest",
+  tsup: "tsup"
+};
+var DATABASE_MAP = {
+  psycopg: "postgresql",
+  psycopg2: "postgresql",
+  "psycopg2-binary": "postgresql",
+  asyncpg: "postgresql",
+  pg: "postgresql",
+  postgres: "postgresql",
+  pgvector: "postgresql",
+  prisma: "postgresql",
+  redis: "redis",
+  ioredis: "redis",
+  pymongo: "mongodb",
   mongoose: "mongodb",
   aiosqlite: "sqlite",
   "better-sqlite3": "sqlite"
@@ -2193,7 +2823,7 @@ function normalizePackageName(rawSpec) {
 var RepoFingerprinter = class {
   repoPath;
   constructor(repoPath) {
-    this.repoPath = path4.resolve(repoPath);
+    this.repoPath = path5.resolve(repoPath);
   }
   fingerprint() {
     const languages = /* @__PURE__ */ new Set();
@@ -2216,383 +2846,892 @@ var RepoFingerprinter = class {
         frameworks.add(fw);
         signals.add(fw);
       }
-      const db = DATABASE_MAP[pkg];
-      if (db) {
-        databases.add(db);
-        signals.add(db);
+      const db = DATABASE_MAP[pkg];
+      if (db) {
+        databases.add(db);
+        signals.add(db);
+      }
+    };
+    const pyprojectPath = path5.join(this.repoPath, "pyproject.toml");
+    if (fs6.existsSync(pyprojectPath) && fs6.statSync(pyprojectPath).isFile()) {
+      detectedFiles.add("pyproject.toml");
+      languages.add("python");
+      signals.add("python");
+      signals.add("pyproject.toml");
+      const content = fs6.readFileSync(pyprojectPath, "utf-8");
+      if (/requires-python\s*=\s*["'][^"']*3\.(1[2-9]|[2-9]\d)/.test(content)) {
+        python312Plus = true;
+        signals.add("python3.12");
+      }
+      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
+      })) {
+        if (entry.isFile() && /^requirements.*\.txt$/i.test(entry.name)) {
+          detectedFiles.add(entry.name);
+          languages.add("python");
+          signals.add("python");
+          const lines = fs6.readFileSync(path5.join(this.repoPath, entry.name), "utf-8").split(/\r?\n/);
+          for (const line of lines) {
+            recordDep(line);
+          }
+        }
+      }
+    }
+    const pkgJsonPath = path5.join(this.repoPath, "package.json");
+    if (fs6.existsSync(pkgJsonPath) && fs6.statSync(pkgJsonPath).isFile()) {
+      detectedFiles.add("package.json");
+      languages.add("javascript");
+      signals.add("javascript");
+      signals.add("nodejs");
+      signals.add("package.json");
+      try {
+        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") {
+            for (const depName of Object.keys(obj)) {
+              recordDep(depName);
+              if (depName === "typescript" || depName.startsWith("@types/")) {
+                languages.add("typescript");
+                signals.add("typescript");
+              }
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    const tsconfigPath = path5.join(this.repoPath, "tsconfig.json");
+    if (fs6.existsSync(tsconfigPath) && fs6.statSync(tsconfigPath).isFile()) {
+      detectedFiles.add("tsconfig.json");
+      languages.add("typescript");
+      signals.add("typescript");
+      signals.add("tsconfig.json");
+    }
+    if (fs6.existsSync(path5.join(this.repoPath, "Cargo.toml"))) {
+      detectedFiles.add("Cargo.toml");
+      languages.add("rust");
+      signals.add("rust");
+    }
+    if (fs6.existsSync(path5.join(this.repoPath, "go.mod"))) {
+      detectedFiles.add("go.mod");
+      languages.add("go");
+      signals.add("go");
+    }
+    if (fs6.existsSync(path5.join(this.repoPath, "Dockerfile"))) {
+      detectedFiles.add("Dockerfile");
+      signals.add("docker");
+    }
+    const ghWorkflowsDir = path5.join(this.repoPath, ".github", "workflows");
+    if (fs6.existsSync(ghWorkflowsDir) && fs6.statSync(ghWorkflowsDir).isDirectory()) {
+      const wfFiles = fs6.readdirSync(ghWorkflowsDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+      if (wfFiles.length > 0) {
+        ciSystems.add("github-actions");
+        signals.add("github-actions");
+        for (const wf of wfFiles) {
+          detectedFiles.add(`.github/workflows/${wf}`);
+        }
+      }
+    }
+    const scanDir = (dir, depth) => {
+      if (depth > 3 || !fs6.existsSync(dir)) {
+        return;
+      }
+      for (const entry of fs6.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist" || entry.name === ".venv" || entry.name === "__pycache__") {
+          continue;
+        }
+        const full = path5.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          scanDir(full, depth + 1);
+        } else if (entry.isFile()) {
+          const rel = path5.relative(this.repoPath, full).replace(/\\/g, "/");
+          if (entry.name.endsWith(".py")) {
+            languages.add("python");
+            signals.add("python");
+            detectedFiles.add(rel);
+            const pyText = fs6.readFileSync(full, "utf-8");
+            if (/^\s*type\s+[A-Za-z_][A-Za-z0-9_]*\s*=/m.test(pyText)) {
+              python312Plus = true;
+              signals.add("python3.12");
+            }
+          } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+            languages.add("typescript");
+            signals.add("typescript");
+            detectedFiles.add(rel);
+          } else if (entry.name.endsWith(".sql")) {
+            databases.add("postgresql");
+            signals.add("sql");
+            signals.add("postgresql");
+            detectedFiles.add(rel);
+          }
+        }
+      }
+    };
+    scanDir(this.repoPath, 0);
+    const detectedHarnesses = detectInstalledHarnesses(this.repoPath);
+    return RepoProfileSchema.parse({
+      repo_path: this.repoPath.replace(/\\/g, "/"),
+      languages: [...languages].sort(),
+      frameworks: [...frameworks].sort(),
+      databases: [...databases].sort(),
+      dependencies: [...dependencies].sort(),
+      ci_systems: [...ciSystems].sort(),
+      detected_files: [...detectedFiles].sort(),
+      signals: [...signals].sort(),
+      detected_harnesses: detectedHarnesses,
+      python_312_plus: python312Plus
+    });
+  }
+};
+function fingerprintRepository(repoPath) {
+  return new RepoFingerprinter(repoPath).fingerprint();
+}
+
+// src/router/bundle_compiler.ts
+function scoreSkillAgainstProfile(parsedSkill, profile, taskPrompt = "") {
+  const manifest = parsedSkill.manifest;
+  const repoSignalSet = new Set(
+    [
+      ...profile.languages,
+      ...profile.frameworks,
+      ...profile.databases,
+      ...profile.dependencies,
+      ...profile.ci_systems,
+      ...profile.signals
+    ].map((s) => s.toLowerCase())
+  );
+  const taskTokens = new Set(tokenizeRoutingText(taskPrompt));
+  if (taskPrompt.trim()) {
+    const lowerPrompt = taskPrompt.toLowerCase();
+    for (const neg of manifest.routing_signals.negative_triggers) {
+      if (neg.trim() && lowerPrompt.includes(neg.toLowerCase())) {
+        return {
+          score: 0,
+          matchedSignals: [],
+          negativeMatch: `Excluded by negative trigger '${neg}'.`
+        };
+      }
+    }
+  }
+  let rawScore = 10;
+  const matchedSignals = [];
+  for (const lang of manifest.routing_signals.languages) {
+    const lowerLang = lang.toLowerCase();
+    if (repoSignalSet.has(lowerLang)) {
+      rawScore += 18;
+      matchedSignals.push(`lang:${lang}`);
+    }
+  }
+  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))) {
+      rawScore += 16;
+      matchedSignals.push(`repo:${dep}`);
+    }
+    if (taskTokens.size > 0 && depTokens.some((t) => taskTokens.has(t))) {
+      rawScore += 22;
+      matchedSignals.push(`task:${dep}`);
+    }
+  }
+  for (const pat of manifest.routing_signals.files_any) {
+    const cleanPat = pat.replace(/\*/g, "").toLowerCase();
+    if (cleanPat && profile.detected_files.some((f) => f.toLowerCase().includes(cleanPat))) {
+      rawScore += 15;
+      matchedSignals.push(`file:${pat}`);
+    }
+  }
+  if (manifest.track === "arch-quality" || manifest.track === "token-economy") {
+    rawScore += 12;
+    matchedSignals.push(`track:${manifest.track}`);
+  }
+  const clampedScore = Math.min(100, Number(rawScore.toFixed(2)));
+  return {
+    score: clampedScore,
+    matchedSignals: [...new Set(matchedSignals)],
+    negativeMatch: null
+  };
+}
+function compileSkillBundle(profile, catalogDir, options = {}) {
+  const maxSkills = options.maxSkills ?? 12;
+  const maxL1Tokens = options.maxL1Tokens ?? 1500;
+  const maxSimilarity = options.maxSimilarity ?? 0.78;
+  const taskPrompt = options.taskPrompt ?? "";
+  const resolvedCatalog = path6.resolve(catalogDir);
+  const skillDirs = discoverSkillDirectories(resolvedCatalog);
+  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));
+  }
+  const idfWeights = computeIdfWeights([...featureVectors.values()]);
+  const candidates = [];
+  const skippedSkills = [];
+  for (const parsed of parsedSkills) {
+    const { score, matchedSignals, negativeMatch } = scoreSkillAgainstProfile(
+      parsed,
+      profile,
+      taskPrompt
+    );
+    if (negativeMatch) {
+      skippedSkills.push({
+        name: parsed.manifest.name,
+        track: parsed.manifest.track,
+        relevance_score: 0,
+        reason: negativeMatch
+      });
+      continue;
+    }
+    candidates.push({ parsed, score, matchedSignals });
+  }
+  candidates.sort(
+    (a, b) => b.score !== a.score ? b.score - a.score : a.parsed.manifest.name.localeCompare(b.parsed.manifest.name)
+  );
+  const selectedSkills = [];
+  let totalL1Tokens = 0;
+  let maxPairwiseSimilarity = 0;
+  for (const cand of candidates) {
+    const manifest = cand.parsed.manifest;
+    if (selectedSkills.length >= maxSkills) {
+      skippedSkills.push({
+        name: manifest.name,
+        track: manifest.track,
+        relevance_score: cand.score,
+        reason: `Bundle cap reached (max_skills=${maxSkills}).`
+      });
+      continue;
+    }
+    if (totalL1Tokens + manifest.description_tokens > maxL1Tokens) {
+      skippedSkills.push({
+        name: manifest.name,
+        track: manifest.track,
+        relevance_score: cand.score,
+        reason: `Would exceed Level 1 token budget (${totalL1Tokens + manifest.description_tokens} > ${maxL1Tokens}).`
+      });
+      continue;
+    }
+    const candVec = featureVectors.get(manifest.name);
+    let collidingPeer = null;
+    let highestSimWithSelected = 0;
+    for (const sel of selectedSkills) {
+      const selVec = featureVectors.get(sel.name);
+      const { similarity } = computeFeatureCosine(candVec, selVec, idfWeights);
+      if (similarity >= maxSimilarity) {
+        collidingPeer = `${sel.name} (cosine=${similarity.toFixed(4)})`;
+        break;
+      }
+      if (similarity > highestSimWithSelected) {
+        highestSimWithSelected = similarity;
       }
-    };
-    const pyprojectPath = path4.join(this.repoPath, "pyproject.toml");
-    if (fs5.existsSync(pyprojectPath) && fs5.statSync(pyprojectPath).isFile()) {
-      detectedFiles.add("pyproject.toml");
-      languages.add("python");
-      signals.add("python");
-      signals.add("pyproject.toml");
-      const content = fs5.readFileSync(pyprojectPath, "utf-8");
-      if (/requires-python\s*=\s*["'][^"']*3\.(1[2-9]|[2-9]\d)/.test(content)) {
-        python312Plus = true;
-        signals.add("python3.12");
+    }
+    if (collidingPeer) {
+      skippedSkills.push({
+        name: manifest.name,
+        track: manifest.track,
+        relevance_score: cand.score,
+        reason: `Semantic collision with selected skill ${collidingPeer}.`
+      });
+      continue;
+    }
+    if (highestSimWithSelected > maxPairwiseSimilarity) {
+      maxPairwiseSimilarity = highestSimWithSelected;
+    }
+    selectedSkills.push({
+      name: manifest.name,
+      track: manifest.track,
+      skill_dir: cand.parsed.skillDir.replace(/\\/g, "/"),
+      relevance_score: cand.score,
+      l1_tokens: manifest.description_tokens,
+      matched_signals: cand.matchedSignals
+    });
+    totalL1Tokens += manifest.description_tokens;
+  }
+  const subagentFiles = discoverSubagentFiles(resolvedCatalog);
+  const recommendedSubagents = [];
+  for (const saFile of subagentFiles) {
+    try {
+      const parsedSa = parseSubagentFile(saFile);
+      if (!recommendedSubagents.includes(parsedSa.manifest.name)) {
+        recommendedSubagents.push(parsedSa.manifest.name);
       }
-      const quotedSpecs = content.match(/["']([a-zA-Z0-9._-]+(?:\[[a-zA-Z0-9,_-]+\])?\s*(?:[><=~!][^"']+)?)["']/g) ?? [];
-      for (const spec of quotedSpecs) {
-        recordDep(spec);
+    } catch {
+    }
+  }
+  return RoutedBundleSchema.parse({
+    repo_profile: profile,
+    catalog_path: resolvedCatalog.replace(/\\/g, "/"),
+    max_skills: maxSkills,
+    max_l1_tokens: maxL1Tokens,
+    max_similarity: maxSimilarity,
+    selected_skills: selectedSkills,
+    recommended_subagents: recommendedSubagents.sort(),
+    skipped_skills: skippedSkills,
+    total_l1_tokens: totalL1Tokens,
+    max_pairwise_similarity: Number(maxPairwiseSimilarity.toFixed(4)),
+    passed_invariants: selectedSkills.length <= maxSkills && totalL1Tokens <= maxL1Tokens && maxPairwiseSimilarity < maxSimilarity
+  });
+}
+function routeRepository(repoPath, catalogDir, options = {}) {
+  const profile = fingerprintRepository(repoPath);
+  return compileSkillBundle(profile, catalogDir, options);
+}
+function formatRoutedBundle(bundle, format = "table", colorEnabled) {
+  if (format === "json") {
+    return `${JSON.stringify(bundle, null, 2)}
+`;
+  }
+  if (format === "markdown") {
+    return [
+      "## SkillOps Context-Aware Routed Bundle",
+      "",
+      `- **Languages**: ${bundle.repo_profile.languages.join(", ") || "none"}`,
+      `- **Frameworks**: ${bundle.repo_profile.frameworks.join(", ") || "none"}`,
+      `- **Selected Skills**: \`${bundle.selected_skills.length}\` / \`${bundle.max_skills}\``,
+      `- **Total L1 Tokens**: \`${bundle.total_l1_tokens}\` / \`${bundle.max_l1_tokens}\``,
+      `- **Recommended Subagents**: ${bundle.recommended_subagents.map((s) => `\`${s}\``).join(", ") || "none"}`,
+      "",
+      "| Skill | Track | Score | L1 Tokens | Matched Signals |",
+      "| :--- | :--- | ---: | ---: | :--- |",
+      ...bundle.selected_skills.map(
+        (s) => `| \`${s.name}\` | \`${s.track}\` | ${s.relevance_score} | ${s.l1_tokens} | ${s.matched_signals.join(", ")} |`
+      ),
+      ""
+    ].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");
+}
+
+// src/mcp/index.ts
+var MCP_TOOLS = [
+  {
+    name: "audit_catalog",
+    description: "Run L1/L2/L3 Progressive Disclosure token budget linter, Subagent contract check, and pairwise cosine collision matrix.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        catalog_dir: {
+          type: "string",
+          description: "Optional path to catalog directory."
+        }
+      },
+      additionalProperties: false
     }
-    if (fs5.existsSync(this.repoPath)) {
-      for (const entry of fs5.readdirSync(this.repoPath, { withFileTypes: true })) {
-        if (entry.isFile() && /^requirements.*\.txt$/i.test(entry.name)) {
-          detectedFiles.add(entry.name);
-          languages.add("python");
-          signals.add("python");
-          const lines = fs5.readFileSync(path4.join(this.repoPath, entry.name), "utf-8").split(/\r?\n/);
-          for (const line of lines) {
-            recordDep(line);
-          }
+  },
+  {
+    name: "analyze_repo_tokens",
+    description: "Audit repository Startup Token Tax (CLAUDE.md, AGENTS.md, .cursor/rules, .mcp.json) and calculate Progressive Disclosure savings.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        },
+        startup_tax_budget: {
+          type: "number",
+          description: "Max startup token budget."
         }
-      }
+      },
+      additionalProperties: false
     }
-    const pkgJsonPath = path4.join(this.repoPath, "package.json");
-    if (fs5.existsSync(pkgJsonPath) && fs5.statSync(pkgJsonPath).isFile()) {
-      detectedFiles.add("package.json");
-      languages.add("javascript");
-      signals.add("javascript");
-      signals.add("nodejs");
-      signals.add("package.json");
-      try {
-        const pkgJson = JSON.parse(fs5.readFileSync(pkgJsonPath, "utf-8"));
-        const depSections = ["dependencies", "devDependencies", "peerDependencies"];
-        for (const section of depSections) {
-          const obj = pkgJson[section];
-          if (obj && typeof obj === "object") {
-            for (const depName of Object.keys(obj)) {
-              recordDep(depName);
-              if (depName === "typescript" || depName.startsWith("@types/")) {
-                languages.add("typescript");
-                signals.add("typescript");
-              }
-            }
-          }
+  },
+  {
+    name: "route_repo_skills",
+    description: "Fingerprint a repository and compile a collision-free bundle of <=12 Skills and Context-Isolated Subagents.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        },
+        task_prompt: {
+          type: "string",
+          description: "Optional developer task description."
         }
-      } catch {
-      }
+      },
+      additionalProperties: false
     }
-    const tsconfigPath = path4.join(this.repoPath, "tsconfig.json");
-    if (fs5.existsSync(tsconfigPath) && fs5.statSync(tsconfigPath).isFile()) {
-      detectedFiles.add("tsconfig.json");
-      languages.add("typescript");
-      signals.add("typescript");
-      signals.add("tsconfig.json");
+  },
+  {
+    name: "run_skill_script",
+    description: "Inspect and validate the deterministic Level 3 script bundle for a Hybrid Executable Skill (INV-SKILL-02).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill_name: { type: "string", description: "Target skill name." }
+      },
+      required: ["skill_name"],
+      additionalProperties: false
     }
-    if (fs5.existsSync(path4.join(this.repoPath, "Cargo.toml"))) {
-      detectedFiles.add("Cargo.toml");
-      languages.add("rust");
-      signals.add("rust");
+  },
+  {
+    name: "get_skill_benchmark",
+    description: "Retrieve deterministic TDD benchmark results (with_skill vs without_skill pass rate lift & token savings).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill_name: {
+          type: "string",
+          description: "Optional skill name filter."
+        }
+      },
+      additionalProperties: false
     }
-    if (fs5.existsSync(path4.join(this.repoPath, "go.mod"))) {
-      detectedFiles.add("go.mod");
-      languages.add("go");
-      signals.add("go");
+  },
+  {
+    name: "list_catalog_items",
+    description: "List all bundled Hybrid Executable Skills and Context-Isolated Subagents with token budgets.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
     }
-    if (fs5.existsSync(path4.join(this.repoPath, "Dockerfile"))) {
-      detectedFiles.add("Dockerfile");
-      signals.add("docker");
+  },
+  {
+    name: "diagnose_repo",
+    description: "Diagnose repository environment (Node.js/Python), declarative .skillops.yml config, .skillops-lock.json SHA-256 artifact drift, and Startup Token Tax.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        },
+        startup_tax_budget: {
+          type: "number",
+          description: "Optional startup token budget override."
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_supported_harnesses",
+    description: "Inspect all 20 supported AI coding agents, IDEs, and CLI harnesses (target paths, MCP support, and repository auto-detection).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo_path: {
+          type: "string",
+          description: "Target repository root path."
+        }
+      },
+      additionalProperties: false
+    }
+  }
+];
+function handleMcpJsonRpcRequest(request, context) {
+  if (request.id === void 0) {
+    return null;
+  }
+  const id = request.id ?? null;
+  try {
+    if (request.method === "initialize") {
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: {
+            tools: {}
+          },
+          serverInfo: {
+            name: "skillops-mcp",
+            version: SKILLOPS_VERSION
+          }
+        }
+      };
+    }
+    if (request.method === "ping") {
+      return { jsonrpc: "2.0", id, result: {} };
     }
-    const ghWorkflowsDir = path4.join(this.repoPath, ".github", "workflows");
-    if (fs5.existsSync(ghWorkflowsDir) && fs5.statSync(ghWorkflowsDir).isDirectory()) {
-      const wfFiles = fs5.readdirSync(ghWorkflowsDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
-      if (wfFiles.length > 0) {
-        ciSystems.add("github-actions");
-        signals.add("github-actions");
-        for (const wf of wfFiles) {
-          detectedFiles.add(`.github/workflows/${wf}`);
+    if (request.method === "tools/list") {
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          tools: MCP_TOOLS
         }
-      }
+      };
     }
-    const scanDir = (dir, depth) => {
-      if (depth > 3 || !fs5.existsSync(dir)) {
-        return;
-      }
-      for (const entry of fs5.readdirSync(dir, { withFileTypes: true })) {
-        if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist" || entry.name === ".venv" || entry.name === "__pycache__") {
-          continue;
+    if (request.method === "tools/call") {
+      const toolName = String(request.params?.name ?? "");
+      const args = request.params?.arguments ?? {};
+      let payload;
+      if (toolName === "audit_catalog") {
+        const catalogDir = typeof args.catalog_dir === "string" ? args.catalog_dir : context.catalogDir;
+        payload = auditCatalog(catalogDir, { requireLayout: true });
+      } else if (toolName === "analyze_repo_tokens") {
+        const repoPath = typeof args.repo_path === "string" ? args.repo_path : context.repoPath;
+        const budget = typeof args.startup_tax_budget === "number" ? args.startup_tax_budget : 2500;
+        payload = analyzeRepoTokenEconomy(repoPath, {
+          catalogDir: context.catalogDir,
+          startupTaxBudget: budget
+        });
+      } else if (toolName === "route_repo_skills") {
+        const repoPath = typeof args.repo_path === "string" ? args.repo_path : context.repoPath;
+        const taskPrompt = typeof args.task_prompt === "string" ? args.task_prompt : "";
+        payload = routeRepository(repoPath, context.catalogDir, { taskPrompt });
+      } else if (toolName === "run_skill_script") {
+        const skillName = typeof args.skill_name === "string" ? args.skill_name : "";
+        const dirs = discoverSkillDirectories(context.catalogDir);
+        const match = dirs.map((d) => parseSkillDirectory(d, { requireLayout: true })).find((p) => p.manifest.name === skillName);
+        if (!match) {
+          throw new Error(`Skill '${skillName}' not found in catalog.`);
         }
-        const full = path4.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          scanDir(full, depth + 1);
-        } else if (entry.isFile()) {
-          const rel = path4.relative(this.repoPath, full).replace(/\\/g, "/");
-          if (entry.name.endsWith(".py")) {
-            languages.add("python");
-            signals.add("python");
-            detectedFiles.add(rel);
-            const pyText = fs5.readFileSync(full, "utf-8");
-            if (/^\s*type\s+[A-Za-z_][A-Za-z0-9_]*\s*=/m.test(pyText)) {
-              python312Plus = true;
-              signals.add("python3.12");
-            }
-          } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
-            languages.add("typescript");
-            signals.add("typescript");
-            detectedFiles.add(rel);
-          } else if (entry.name.endsWith(".sql")) {
-            databases.add("postgresql");
-            signals.add("sql");
-            signals.add("postgresql");
-            detectedFiles.add(rel);
+        const scriptsDir = path7.join(match.skillDir, "scripts");
+        const scripts = fs7.existsSync(scriptsDir) ? fs7.readdirSync(scriptsDir).filter((f) => !f.startsWith(".")) : [];
+        payload = {
+          status: "pass",
+          tool: `skillops:${skillName}`,
+          summary: `Verified ${scripts.length} deterministic Level 3 script(s) for '${skillName}'.`,
+          metrics: {
+            scripts_count: scripts.length,
+            l1_description_tokens: match.manifest.description_tokens,
+            l2_body_tokens: match.manifest.body_tokens
+          },
+          scripts
+        };
+      } else if (toolName === "get_skill_benchmark") {
+        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
+        });
+      } 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;
+        payload = diagnoseRepository(repoPath, {
+          catalogDir: context.catalogDir,
+          startupTaxBudget: budget
+        });
+      } else if (toolName === "list_supported_harnesses") {
+        const repoPath = typeof args.repo_path === "string" ? args.repo_path : context.repoPath;
+        payload = inspectHarnesses(repoPath);
+      } else {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32601,
+            message: `Unknown MCP tool '${toolName}'.`
           }
+        };
+      }
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(payload, null, 2)
+            }
+          ],
+          isError: false
         }
+      };
+    }
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: {
+        code: -32601,
+        message: `Method '${request.method}' not found.`
+      }
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: {
+        code: -32603,
+        message
       }
     };
-    scanDir(this.repoPath, 0);
-    const detectedHarnesses = detectInstalledHarnesses(this.repoPath);
-    return RepoProfileSchema.parse({
-      repo_path: this.repoPath.replace(/\\/g, "/"),
-      languages: [...languages].sort(),
-      frameworks: [...frameworks].sort(),
-      databases: [...databases].sort(),
-      dependencies: [...dependencies].sort(),
-      ci_systems: [...ciSystems].sort(),
-      detected_files: [...detectedFiles].sort(),
-      signals: [...signals].sort(),
-      detected_harnesses: detectedHarnesses,
-      python_312_plus: python312Plus
-    });
   }
-};
-function fingerprintRepository(repoPath) {
-  return new RepoFingerprinter(repoPath).fingerprint();
 }
-
-// src/router/bundle_compiler.ts
-import path5 from "path";
-function scoreSkillAgainstProfile(parsedSkill, profile, taskPrompt = "") {
-  const manifest = parsedSkill.manifest;
-  const repoSignalSet = new Set(
-    [
-      ...profile.languages,
-      ...profile.frameworks,
-      ...profile.databases,
-      ...profile.dependencies,
-      ...profile.ci_systems,
-      ...profile.signals
-    ].map((s) => s.toLowerCase())
-  );
-  const taskTokens = new Set(tokenizeRoutingText(taskPrompt));
-  if (taskPrompt.trim()) {
-    const lowerPrompt = taskPrompt.toLowerCase();
-    for (const neg of manifest.routing_signals.negative_triggers) {
-      if (neg.trim() && lowerPrompt.includes(neg.toLowerCase())) {
-        return {
-          score: 0,
-          matchedSignals: [],
-          negativeMatch: `Excluded by negative trigger '${neg}'.`
-        };
-      }
+function startMcpStdioServer(context) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    terminal: false
+  });
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      return;
     }
-  }
-  let rawScore = 10;
-  const matchedSignals = [];
-  for (const lang of manifest.routing_signals.languages) {
-    const lowerLang = lang.toLowerCase();
-    if (repoSignalSet.has(lowerLang)) {
-      rawScore += 18;
-      matchedSignals.push(`lang:${lang}`);
+    try {
+      const req = JSON.parse(trimmed);
+      const res = handleMcpJsonRpcRequest(req, context);
+      if (res) {
+        process.stdout.write(`${JSON.stringify(res)}
+`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[skillops-mcp] Parse error: ${msg}
+`);
     }
-  }
-  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))) {
-      rawScore += 16;
-      matchedSignals.push(`repo:${dep}`);
+  });
+}
+function buildUpdatedMcpConfigContent(target, existingRaw, serverName) {
+  const mcpArgs = ["-y", "skillops-cli@latest", "mcp"];
+  if (target === "codex") {
+    const tomlBlock = [
+      `[mcp_servers.${serverName}]`,
+      'command = "npx"',
+      'args = ["-y", "skillops-cli@latest", "mcp"]'
+    ].join("\n");
+    if (!existingRaw || !existingRaw.trim()) {
+      return `${tomlBlock}
+`;
     }
-    if (taskTokens.size > 0 && depTokens.some((t) => taskTokens.has(t))) {
-      rawScore += 22;
-      matchedSignals.push(`task:${dep}`);
+    const blockRegex = new RegExp(
+      `\\[mcp_servers\\.${serverName}\\][\\s\\S]*?(?=\\r?\\n\\[|$)`
+    );
+    if (blockRegex.test(existingRaw)) {
+      return `${existingRaw.replace(blockRegex, tomlBlock).trimEnd()}
+`;
     }
+    return `${existingRaw.trimEnd()}
+
+${tomlBlock}
+`;
   }
-  for (const pat of manifest.routing_signals.files_any) {
-    const cleanPat = pat.replace(/\*/g, "").toLowerCase();
-    if (cleanPat && profile.detected_files.some((f) => f.toLowerCase().includes(cleanPat))) {
-      rawScore += 15;
-      matchedSignals.push(`file:${pat}`);
+  if (target === "continue") {
+    const doc = {
+      name: "SkillOps MCP Server",
+      version: SKILLOPS_VERSION,
+      schema: "v1",
+      mcpServers: [
+        {
+          name: serverName,
+          command: "npx",
+          args: mcpArgs
+        }
+      ]
+    };
+    return YAML3.stringify(doc);
+  }
+  let parsedObj = {};
+  if (existingRaw && existingRaw.trim()) {
+    try {
+      const loaded = JSON.parse(existingRaw);
+      if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) {
+        parsedObj = { ...loaded };
+      }
+    } catch {
+      parsedObj = {};
     }
   }
-  if (manifest.track === "arch-quality" || manifest.track === "token-economy") {
-    rawScore += 12;
-    matchedSignals.push(`track:${manifest.track}`);
+  if (target === "copilot") {
+    const servers = parsedObj.servers && typeof parsedObj.servers === "object" && !Array.isArray(parsedObj.servers) ? { ...parsedObj.servers } : {};
+    servers[serverName] = {
+      type: "stdio",
+      command: "npx",
+      args: mcpArgs
+    };
+    parsedObj.servers = servers;
+    return `${JSON.stringify(parsedObj, null, 2)}
+`;
   }
-  const clampedScore = Math.min(100, Number(rawScore.toFixed(2)));
-  return {
-    score: clampedScore,
-    matchedSignals: [...new Set(matchedSignals)],
-    negativeMatch: null
-  };
-}
-function compileSkillBundle(profile, catalogDir, options = {}) {
-  const maxSkills = options.maxSkills ?? 12;
-  const maxL1Tokens = options.maxL1Tokens ?? 1500;
-  const maxSimilarity = options.maxSimilarity ?? 0.78;
-  const taskPrompt = options.taskPrompt ?? "";
-  const resolvedCatalog = path5.resolve(catalogDir);
-  const skillDirs = discoverSkillDirectories(resolvedCatalog);
-  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));
+  if (target === "zed") {
+    const contextServers = parsedObj.context_servers && typeof parsedObj.context_servers === "object" && !Array.isArray(parsedObj.context_servers) ? { ...parsedObj.context_servers } : {};
+    contextServers[serverName] = {
+      command: {
+        path: "npx",
+        args: mcpArgs
+      }
+    };
+    parsedObj.context_servers = contextServers;
+    return `${JSON.stringify(parsedObj, null, 2)}
+`;
   }
-  const idfWeights = computeIdfWeights([...featureVectors.values()]);
-  const candidates = [];
-  const skippedSkills = [];
-  for (const parsed of parsedSkills) {
-    const { score, matchedSignals, negativeMatch } = scoreSkillAgainstProfile(
-      parsed,
-      profile,
-      taskPrompt
-    );
-    if (negativeMatch) {
-      skippedSkills.push({
-        name: parsed.manifest.name,
-        track: parsed.manifest.track,
-        relevance_score: 0,
-        reason: negativeMatch
-      });
-      continue;
-    }
-    candidates.push({ parsed, score, matchedSignals });
+  if (target === "amp") {
+    const ampServers = parsedObj["amp.mcpServers"] && typeof parsedObj["amp.mcpServers"] === "object" && !Array.isArray(parsedObj["amp.mcpServers"]) ? { ...parsedObj["amp.mcpServers"] } : {};
+    ampServers[serverName] = {
+      command: "npx",
+      args: mcpArgs
+    };
+    parsedObj["amp.mcpServers"] = ampServers;
+    return `${JSON.stringify(parsedObj, null, 2)}
+`;
   }
-  candidates.sort(
-    (a, b) => b.score !== a.score ? b.score - a.score : a.parsed.manifest.name.localeCompare(b.parsed.manifest.name)
-  );
-  const selectedSkills = [];
-  let totalL1Tokens = 0;
-  let maxPairwiseSimilarity = 0;
-  for (const cand of candidates) {
-    const manifest = cand.parsed.manifest;
-    if (selectedSkills.length >= maxSkills) {
-      skippedSkills.push({
-        name: manifest.name,
-        track: manifest.track,
-        relevance_score: cand.score,
-        reason: `Bundle cap reached (max_skills=${maxSkills}).`
-      });
-      continue;
+  if (target === "opencode") {
+    if (!("$schema" in parsedObj)) {
+      parsedObj.$schema = "https://opencode.ai/config.json";
     }
-    if (totalL1Tokens + manifest.description_tokens > maxL1Tokens) {
-      skippedSkills.push({
-        name: manifest.name,
-        track: manifest.track,
-        relevance_score: cand.score,
-        reason: `Would exceed Level 1 token budget (${totalL1Tokens + manifest.description_tokens} > ${maxL1Tokens}).`
+    const mcpMap = parsedObj.mcp && typeof parsedObj.mcp === "object" && !Array.isArray(parsedObj.mcp) ? { ...parsedObj.mcp } : {};
+    mcpMap[serverName] = {
+      type: "local",
+      command: ["npx", ...mcpArgs],
+      enabled: true
+    };
+    parsedObj.mcp = mcpMap;
+    return `${JSON.stringify(parsedObj, null, 2)}
+`;
+  }
+  const mcpServers = parsedObj.mcpServers && typeof parsedObj.mcpServers === "object" && !Array.isArray(parsedObj.mcpServers) ? { ...parsedObj.mcpServers } : {};
+  mcpServers[serverName] = {
+    command: "npx",
+    args: mcpArgs
+  };
+  parsedObj.mcpServers = mcpServers;
+  return `${JSON.stringify(parsedObj, null, 2)}
+`;
+}
+function setupMcpForHarnesses(repoPath, options = {}) {
+  const resolvedRepo = path7.resolve(repoPath);
+  const targets = options.targets ?? CORE_RUNTIME_TARGETS;
+  const dryRun = options.dryRun ?? false;
+  const serverName = options.serverName ?? "skillops";
+  const actions = [];
+  for (const target of targets) {
+    const spec = RUNTIME_HARNESS_SPECS[target];
+    if (!spec.supportsMcp || !spec.mcpConfigPath) {
+      actions.push({
+        target,
+        display_name: spec.displayName,
+        relative_path: "n/a",
+        status: "unsupported"
       });
       continue;
     }
-    const candVec = featureVectors.get(manifest.name);
-    let collidingPeer = null;
-    let highestSimWithSelected = 0;
-    for (const sel of selectedSkills) {
-      const selVec = featureVectors.get(sel.name);
-      const { similarity } = computeFeatureCosine(candVec, selVec, idfWeights);
-      if (similarity >= maxSimilarity) {
-        collidingPeer = `${sel.name} (cosine=${similarity.toFixed(4)})`;
-        break;
-      }
-      if (similarity > highestSimWithSelected) {
-        highestSimWithSelected = similarity;
-      }
-    }
-    if (collidingPeer) {
-      skippedSkills.push({
-        name: manifest.name,
-        track: manifest.track,
-        relevance_score: cand.score,
-        reason: `Semantic collision with selected skill ${collidingPeer}.`
-      });
-      continue;
+    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
+    );
+    let status;
+    if (!exists) {
+      status = "created";
+    } else if (existingRaw === updatedRaw) {
+      status = "unchanged";
+    } else {
+      status = "updated";
     }
-    if (highestSimWithSelected > maxPairwiseSimilarity) {
-      maxPairwiseSimilarity = highestSimWithSelected;
+    if (!dryRun && (status === "created" || status === "updated")) {
+      fs7.mkdirSync(path7.dirname(absPath), { recursive: true });
+      fs7.writeFileSync(absPath, updatedRaw, "utf-8");
     }
-    selectedSkills.push({
-      name: manifest.name,
-      track: manifest.track,
-      skill_dir: cand.parsed.skillDir.replace(/\\/g, "/"),
-      relevance_score: cand.score,
-      l1_tokens: manifest.description_tokens,
-      matched_signals: cand.matchedSignals
+    actions.push({
+      target,
+      display_name: spec.displayName,
+      relative_path: spec.mcpConfigPath,
+      status
     });
-    totalL1Tokens += manifest.description_tokens;
-  }
-  const subagentFiles = discoverSubagentFiles(resolvedCatalog);
-  const recommendedSubagents = [];
-  for (const saFile of subagentFiles) {
-    try {
-      const parsedSa = parseSubagentFile(saFile);
-      if (!recommendedSubagents.includes(parsedSa.manifest.name)) {
-        recommendedSubagents.push(parsedSa.manifest.name);
-      }
-    } catch {
-    }
   }
-  return RoutedBundleSchema.parse({
-    repo_profile: profile,
-    catalog_path: resolvedCatalog.replace(/\\/g, "/"),
-    max_skills: maxSkills,
-    max_l1_tokens: maxL1Tokens,
-    max_similarity: maxSimilarity,
-    selected_skills: selectedSkills,
-    recommended_subagents: recommendedSubagents.sort(),
-    skipped_skills: skippedSkills,
-    total_l1_tokens: totalL1Tokens,
-    max_pairwise_similarity: Number(maxPairwiseSimilarity.toFixed(4)),
-    passed_invariants: selectedSkills.length <= maxSkills && totalL1Tokens <= maxL1Tokens && maxPairwiseSimilarity < maxSimilarity
-  });
-}
-function routeRepository(repoPath, catalogDir, options = {}) {
-  const profile = fingerprintRepository(repoPath);
-  return compileSkillBundle(profile, catalogDir, options);
+  const configuredCount = actions.filter(
+    (a) => a.status !== "unsupported"
+  ).length;
+  return {
+    repo_path: path7.basename(resolvedRepo) || ".",
+    dry_run: dryRun,
+    targets_requested: [...targets],
+    configured_count: configuredCount,
+    actions
+  };
 }
-function formatRoutedBundle(bundle, format = "table") {
+function formatMcpSetupReport(report, format = "table") {
   if (format === "json") {
-    return `${JSON.stringify(bundle, null, 2)}
+    return `${JSON.stringify(report, null, 2)}
 `;
   }
   if (format === "markdown") {
-    return [
-      "## SkillOps Context-Aware Routed Bundle",
+    const lines2 = [
+      `## SkillOps Universal MCP Server Registration (\`${report.repo_path}\`)`,
       "",
-      `- **Languages**: ${bundle.repo_profile.languages.join(", ") || "none"}`,
-      `- **Frameworks**: ${bundle.repo_profile.frameworks.join(", ") || "none"}`,
-      `- **Selected Skills**: \`${bundle.selected_skills.length}\` / \`${bundle.max_skills}\``,
-      `- **Total L1 Tokens**: \`${bundle.total_l1_tokens}\` / \`${bundle.max_l1_tokens}\``,
-      `- **Recommended Subagents**: ${bundle.recommended_subagents.map((s) => `\`${s}\``).join(", ") || "none"}`,
+      `- **Mode:** \`${report.dry_run ? "DRY-RUN" : "WRITE"}\``,
+      `- **Configured MCP Harnesses:** \`${report.configured_count}/${report.targets_requested.length}\``,
       "",
-      "| Skill | Track | Score | L1 Tokens | Matched Signals |",
-      "| :--- | :--- | ---: | ---: | :--- |",
-      ...bundle.selected_skills.map(
-        (s) => `| \`${s.name}\` | \`${s.track}\` | ${s.relevance_score} | ${s.l1_tokens} | ${s.matched_signals.join(", ")} |`
+      "| Target | AI Coding Agent / IDE | MCP Config File | Status |",
+      "| :--- | :--- | :--- | :---: |",
+      ...report.actions.map(
+        (a) => `| \`${a.target}\` | **${a.display_name}** | \`${a.relative_path}\` | \`${a.status.toUpperCase()}\` |`
       ),
       ""
-    ].join("\n");
+    ];
+    return lines2.join("\n");
   }
-  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)})`,
-    `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(", ")}]`
+  const lines = [
+    `=== SkillOps Universal MCP Server Setup [${report.dry_run ? "DRY-RUN" : "WRITE"}] ===`,
+    `Targets Requested : ${report.targets_requested.join(", ")}`,
+    `MCP Harnesses     : ${report.configured_count} configured`,
+    ...report.actions.map(
+      (a) => `  [${a.status.toUpperCase().padEnd(11)}] ${a.target.padEnd(11)} -> ${a.relative_path} (${a.display_name})`
     ),
     ""
-  ].join("\n");
+  ];
+  return lines.join("\n");
 }
 
 // src/sync/adapters.ts
 import crypto2 from "crypto";
-import fs6 from "fs";
-import path6 from "path";
-import YAML3 from "yaml";
+import fs8 from "fs";
+import path8 from "path";
+import YAML4 from "yaml";
 var CODEX_MARKER_START = "<!-- SKILLOPS:START -->";
 var CODEX_MARKER_END = "<!-- SKILLOPS:END -->";
 function computeSha256(content) {
@@ -2613,27 +3752,27 @@ function renderSkillFilesForRuntime(parsed, target) {
       content: parsed.rawText
     });
     for (const scriptFull of parsed.declaredScripts) {
-      const scriptRel = path6.relative(parsed.skillDir, scriptFull).replace(/\\/g, "/");
+      const scriptRel = path8.relative(parsed.skillDir, scriptFull).replace(/\\/g, "/");
       files.push({
         target,
         itemName: name,
         relativePath: `${baseDir}/${scriptRel}`,
-        content: fs6.readFileSync(scriptFull, "utf-8")
+        content: fs8.readFileSync(scriptFull, "utf-8")
       });
     }
     for (const refFull of parsed.referenceFiles) {
-      const refRel = path6.relative(parsed.skillDir, refFull).replace(/\\/g, "/");
+      const refRel = path8.relative(parsed.skillDir, refFull).replace(/\\/g, "/");
       files.push({
         target,
         itemName: name,
         relativePath: `${baseDir}/${refRel}`,
-        content: fs6.readFileSync(refFull, "utf-8")
+        content: fs8.readFileSync(refFull, "utf-8")
       });
     }
     return files;
   }
   if (target === "cursor") {
-    const mdcFrontmatter = YAML3.stringify({
+    const mdcFrontmatter = YAML4.stringify({
       description: parsed.manifest.description,
       globs,
       alwaysApply: false
@@ -2653,7 +3792,7 @@ ${body}
   }
   if (target === "copilot") {
     const applyTo = parsed.manifest.routing_signals.files_any.length > 0 ? parsed.manifest.routing_signals.files_any.join(",") : "**";
-    const instrFrontmatter = YAML3.stringify({
+    const instrFrontmatter = YAML4.stringify({
       applyTo,
       description: parsed.manifest.description
     }).trim();
@@ -2668,7 +3807,7 @@ ${instrFrontmatter}
 ${body}
 `
     });
-    const promptFrontmatter = YAML3.stringify({
+    const promptFrontmatter = YAML4.stringify({
       mode: "agent",
       description: parsed.manifest.description
     }).trim();
@@ -2686,7 +3825,7 @@ ${body}
     return files;
   }
   if (target === "windsurf") {
-    const wsFrontmatter = YAML3.stringify({
+    const wsFrontmatter = YAML4.stringify({
       trigger: "model_decision",
       description: parsed.manifest.description,
       globs
@@ -2705,7 +3844,7 @@ ${body}
     return files;
   }
   if (target === "openhands") {
-    const ohFrontmatter = YAML3.stringify({
+    const ohFrontmatter = YAML4.stringify({
       name,
       type: "knowledge",
       version: parsed.manifest.version,
@@ -2726,7 +3865,7 @@ ${body}
     return files;
   }
   if (target === "kiro") {
-    const kiroFrontmatter = YAML3.stringify({
+    const kiroFrontmatter = YAML4.stringify({
       inclusion: "fileMatch",
       fileMatchPattern: globs[0] ?? "**/*",
       description: parsed.manifest.description
@@ -2744,7 +3883,7 @@ ${body}
     });
     return files;
   }
-  const ruleFrontmatter = YAML3.stringify({
+  const ruleFrontmatter = YAML4.stringify({
     name,
     description: parsed.manifest.description,
     track: parsed.manifest.track,
@@ -2769,7 +3908,7 @@ function renderSubagentFilesForRuntime(subagent, target) {
   const name = subagent.manifest.name;
   const spec = RUNTIME_HARNESS_SPECS[target];
   const promptBody = subagent.systemPromptBody.trim();
-  const fm = YAML3.stringify({
+  const fm = YAML4.stringify({
     name: subagent.manifest.name,
     description: subagent.manifest.description,
     model_tier: subagent.manifest.model_tier,
@@ -2803,7 +3942,7 @@ ${promptBody}
     ];
   }
   if (target === "cursor") {
-    const mdcFm = YAML3.stringify({
+    const mdcFm = YAML4.stringify({
       description: `[Subagent: ${name}] ${subagent.manifest.description}`,
       alwaysApply: false
     }).trim();
@@ -2822,7 +3961,7 @@ ${promptBody}
     ];
   }
   if (target === "continue") {
-    const contFm = YAML3.stringify({
+    const contFm = YAML4.stringify({
       name,
       description: subagent.manifest.description,
       invokable: true
@@ -2842,7 +3981,7 @@ ${promptBody}
     ];
   }
   if (target === "openhands") {
-    const ohFm = YAML3.stringify({
+    const ohFm = YAML4.stringify({
       name: `agent-${name}`,
       type: "knowledge",
       version: "1.0.0",
@@ -2926,29 +4065,29 @@ ${managedBlock}
 `;
 }
 function loadExistingLockfile(lockfilePath) {
-  if (!fs6.existsSync(lockfilePath) || !fs6.statSync(lockfilePath).isFile()) {
+  if (!fs8.existsSync(lockfilePath) || !fs8.statSync(lockfilePath).isFile()) {
     return null;
   }
   try {
-    const raw = JSON.parse(fs6.readFileSync(lockfilePath, "utf-8"));
+    const raw = JSON.parse(fs8.readFileSync(lockfilePath, "utf-8"));
     return SyncLockfileSchema.parse(raw);
   } catch {
     return null;
   }
 }
 function applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle, plannedFiles, options) {
-  const lockfilePath = path6.join(resolvedRepo, ".skillops-lock.json");
+  const lockfilePath = path8.join(resolvedRepo, ".skillops-lock.json");
   const existingLock = loadExistingLockfile(lockfilePath);
   const newLockArtifacts = options.preserveUnlistedLockEntries ? { ...existingLock?.artifacts ?? {} } : {};
   const artifacts = [];
   const driftConflicts = [];
   for (const pf of plannedFiles) {
-    const fullPath = path6.join(resolvedRepo, pf.relativePath);
+    const fullPath = path8.join(resolvedRepo, pf.relativePath);
     const desiredSha = computeSha256(pf.content);
     const previousEntry = existingLock?.artifacts[pf.relativePath];
-    const fileExists = fs6.existsSync(fullPath) && fs6.statSync(fullPath).isFile();
+    const fileExists = fs8.existsSync(fullPath) && fs8.statSync(fullPath).isFile();
     if (fileExists) {
-      const currentDiskText = fs6.readFileSync(fullPath, "utf-8");
+      const currentDiskText = fs8.readFileSync(fullPath, "utf-8");
       const currentDiskSha = computeSha256(currentDiskText);
       if (previousEntry && currentDiskSha !== previousEntry.sha256 && currentDiskSha !== desiredSha && !options.force) {
         driftConflicts.push(pf.relativePath);
@@ -2979,8 +4118,8 @@ function applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle,
         continue;
       }
       if (!options.dryRun) {
-        fs6.mkdirSync(path6.dirname(fullPath), { recursive: true });
-        fs6.writeFileSync(fullPath, pf.content, "utf-8");
+        fs8.mkdirSync(path8.dirname(fullPath), { recursive: true });
+        fs8.writeFileSync(fullPath, pf.content, "utf-8");
       }
       artifacts.push({
         target: pf.target,
@@ -2997,8 +4136,8 @@ function applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle,
       };
     } else {
       if (!options.dryRun) {
-        fs6.mkdirSync(path6.dirname(fullPath), { recursive: true });
-        fs6.writeFileSync(fullPath, pf.content, "utf-8");
+        fs8.mkdirSync(path8.dirname(fullPath), { recursive: true });
+        fs8.writeFileSync(fullPath, pf.content, "utf-8");
       }
       artifacts.push({
         target: pf.target,
@@ -3025,8 +4164,12 @@ function applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle,
       total_l1_tokens: routedBundle.total_l1_tokens,
       artifacts: newLockArtifacts
     });
-    fs6.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, "/"),
@@ -3042,8 +4185,8 @@ function applyPlannedFiles(resolvedRepo, resolvedCatalog, targets, routedBundle,
   });
 }
 function syncRepository(repoPath, catalogDir, options = {}) {
-  const resolvedRepo = path6.resolve(repoPath);
-  const resolvedCatalog = path6.resolve(catalogDir);
+  const resolvedRepo = path8.resolve(repoPath);
+  const resolvedCatalog = path8.resolve(catalogDir);
   const targets = options.targets?.length ? options.targets : CORE_RUNTIME_TARGETS;
   const dryRun = options.dryRun ?? false;
   const force = options.force ?? false;
@@ -3071,25 +4214,36 @@ function syncRepository(repoPath, catalogDir, options = {}) {
       plannedFiles.push(...renderSubagentFilesForRuntime(sa, target));
     }
     if (target === "codex") {
-      const agentsMdPath = path6.join(resolvedRepo, "AGENTS.md");
-      const existingAgentsMd = fs6.existsSync(agentsMdPath) && fs6.statSync(agentsMdPath).isFile() ? fs6.readFileSync(agentsMdPath, "utf-8") : null;
+      const agentsMdPath = path8.join(resolvedRepo, "AGENTS.md");
+      const existingAgentsMd = fs8.existsSync(agentsMdPath) && fs8.statSync(agentsMdPath).isFile() ? fs8.readFileSync(agentsMdPath, "utf-8") : null;
       plannedFiles.push({
         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 = path6.resolve(repoPath);
-  const resolvedCatalog = path6.resolve(catalogDir);
+  const resolvedRepo = path8.resolve(repoPath);
+  const resolvedCatalog = path8.resolve(catalogDir);
   const targets = options.targets?.length ? options.targets : CORE_RUNTIME_TARGETS;
   const dryRun = options.dryRun ?? false;
   const force = options.force ?? false;
@@ -3129,27 +4283,36 @@ 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 = path6.resolve(stopAtRepoRoot);
-  let currentDir = path6.dirname(path6.resolve(filePath));
-  while (currentDir.startsWith(normalizedStop) && currentDir !== normalizedStop && fs6.existsSync(currentDir)) {
+  const normalizedStop = path8.resolve(stopAtRepoRoot);
+  let currentDir = path8.dirname(path8.resolve(filePath));
+  while (currentDir.startsWith(normalizedStop) && currentDir !== normalizedStop && fs8.existsSync(currentDir)) {
     try {
-      const entries = fs6.readdirSync(currentDir);
+      const entries = fs8.readdirSync(currentDir);
       if (entries.length > 0) {
         break;
       }
-      fs6.rmdirSync(currentDir);
-      currentDir = path6.dirname(currentDir);
+      fs8.rmdirSync(currentDir);
+      currentDir = path8.dirname(currentDir);
     } catch {
       break;
     }
@@ -3171,12 +4334,12 @@ function stripCodexAgentsBlock(existingContent) {
 `;
 }
 function removeSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
-  const resolvedRepo = path6.resolve(repoPath);
-  const resolvedCatalog = path6.resolve(catalogDir);
+  const resolvedRepo = path8.resolve(repoPath);
+  const resolvedCatalog = path8.resolve(catalogDir);
   const targetFilter = options.targets?.length ? new Set(options.targets) : null;
   const dryRun = options.dryRun ?? false;
   const force = options.force ?? false;
-  const lockfilePath = path6.join(resolvedRepo, ".skillops-lock.json");
+  const lockfilePath = path8.join(resolvedRepo, ".skillops-lock.json");
   const existingLock = loadExistingLockfile(lockfilePath);
   if (!existingLock) {
     throw new Error(
@@ -3191,14 +4354,16 @@ 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) {
-    const fullPath = path6.join(resolvedRepo, relPath);
-    const fileExists = fs6.existsSync(fullPath) && fs6.statSync(fullPath).isFile();
+    const fullPath = path8.join(resolvedRepo, relPath);
+    const fileExists = fs8.existsSync(fullPath) && fs8.statSync(fullPath).isFile();
     if (fileExists) {
-      const currentDiskSha = computeSha256(fs6.readFileSync(fullPath, "utf-8"));
+      const currentDiskSha = computeSha256(fs8.readFileSync(fullPath, "utf-8"));
       if (currentDiskSha !== entry.sha256 && !force) {
         driftConflicts.push(relPath);
         artifacts.push({
@@ -3211,7 +4376,7 @@ function removeSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
         continue;
       }
       if (!dryRun) {
-        fs6.unlinkSync(fullPath);
+        fs8.unlinkSync(fullPath);
         pruneEmptyParentDirs(fullPath, resolvedRepo);
       }
     }
@@ -3237,8 +4402,12 @@ function removeSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
       selected_subagents: updatedSubagents,
       artifacts: newLockArtifacts
     });
-    fs6.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({
@@ -3255,11 +4424,11 @@ function removeSkillOrSubagent(repoPath, catalogDir, itemName, options = {}) {
   });
 }
 function cleanSyncedArtifacts(repoPath, catalogDir, options = {}) {
-  const resolvedRepo = path6.resolve(repoPath);
-  const resolvedCatalog = path6.resolve(catalogDir);
+  const resolvedRepo = path8.resolve(repoPath);
+  const resolvedCatalog = path8.resolve(catalogDir);
   const dryRun = options.dryRun ?? false;
   const force = options.force ?? false;
-  const lockfilePath = path6.join(resolvedRepo, ".skillops-lock.json");
+  const lockfilePath = path8.join(resolvedRepo, ".skillops-lock.json");
   const existingLock = loadExistingLockfile(lockfilePath);
   const routedBundle = routeRepository(resolvedRepo, resolvedCatalog);
   if (!existingLock) {
@@ -3279,10 +4448,10 @@ function cleanSyncedArtifacts(repoPath, catalogDir, options = {}) {
   const artifacts = [];
   const driftConflicts = [];
   for (const [relPath, entry] of Object.entries(existingLock.artifacts)) {
-    const fullPath = path6.join(resolvedRepo, relPath);
-    const fileExists = fs6.existsSync(fullPath) && fs6.statSync(fullPath).isFile();
+    const fullPath = path8.join(resolvedRepo, relPath);
+    const fileExists = fs8.existsSync(fullPath) && fs8.statSync(fullPath).isFile();
     if (fileExists) {
-      const diskText = fs6.readFileSync(fullPath, "utf-8");
+      const diskText = fs8.readFileSync(fullPath, "utf-8");
       const currentDiskSha = computeSha256(diskText);
       if (currentDiskSha !== entry.sha256 && !force) {
         driftConflicts.push(relPath);
@@ -3299,12 +4468,12 @@ function cleanSyncedArtifacts(repoPath, catalogDir, options = {}) {
         if (relPath === "AGENTS.md" && entry.skill_name === "codex-agents-index") {
           const stripped = stripCodexAgentsBlock(diskText);
           if (stripped) {
-            fs6.writeFileSync(fullPath, stripped, "utf-8");
+            fs8.writeFileSync(fullPath, stripped, "utf-8");
           } else {
-            fs6.unlinkSync(fullPath);
+            fs8.unlinkSync(fullPath);
           }
         } else {
-          fs6.unlinkSync(fullPath);
+          fs8.unlinkSync(fullPath);
           pruneEmptyParentDirs(fullPath, resolvedRepo);
         }
       }
@@ -3317,8 +4486,8 @@ function cleanSyncedArtifacts(repoPath, catalogDir, options = {}) {
       action: dryRun ? "planned" : "removed"
     });
   }
-  if (!dryRun && driftConflicts.length === 0 && fs6.existsSync(lockfilePath)) {
-    fs6.unlinkSync(lockfilePath);
+  if (!dryRun && driftConflicts.length === 0 && fs8.existsSync(lockfilePath)) {
+    fs8.unlinkSync(lockfilePath);
   }
   return SyncReportSchema.parse({
     repo_path: resolvedRepo.replace(/\\/g, "/"),
@@ -3333,716 +4502,1423 @@ 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)}
 `;
   }
   if (format === "markdown") {
-    return [
-      "## SkillOps Multi-Runtime Sync Report",
-      "",
-      `- **Targets**: ${report.targets.map((t) => `\`${t}\``).join(", ")}`,
-      `- **Artifacts Synced**: \`${report.artifacts.length}\``,
-      `- **Drift Conflicts**: \`${report.drift_conflicts.length}\``,
-      `- **Status**: **${report.passed ? "PASS" : "CONFLICT"}**`,
-      "",
-      "| Target | Skill / Subagent | Relative Path | Action |",
-      "| :--- | :--- | :--- | :---: |",
-      ...report.artifacts.map(
-        (a) => `| \`${a.target}\` | \`${a.skill_name}\` | \`${a.relative_path}\` | \`${a.action}\` |`
-      ),
-      ""
-    ].join("\n");
-  }
-  return [
-    "=== SkillOps Multi-Runtime Transpiler & Sync Engine ===",
-    `Repo       : ${report.repo_path}`,
-    `Targets    : ${report.targets.join(", ")}`,
-    `Artifacts  : ${report.artifacts.length} file(s) [${report.passed ? "PASS" : "DRIFT CONFLICT"}]`,
-    ...report.artifacts.map(
-      (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.`
-    ),
-    ""
-  ].join("\n");
-}
-
-// src/eval/index.ts
-import fs7 from "fs";
-import path7 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,
-  without_skill: BenchmarkArmSchema,
-  delta: BenchmarkDeltaSchema,
-  passed: z2.boolean().default(true)
-}).strict();
-var CatalogEvalSummarySchema = z2.object({
-  catalog_path: z2.string().min(1),
-  skills_evaluated: z2.number().int().min(0),
-  mean_with_skill_pass_rate: z2.number().min(0).max(1),
-  mean_without_skill_pass_rate: z2.number().min(0).max(1),
-  mean_pass_rate_gain: z2.number(),
-  mean_token_reduction_pct: z2.number(),
-  benchmarks: z2.array(SkillBenchmarkSchema).default([]),
-  passed: z2.boolean()
-}).strict();
-function evaluateSkillDirectory(skillDir) {
-  const parsed = parseSkillDirectory(skillDir, { requireLayout: true });
-  const evalsPath = path7.join(skillDir, "evals", "evals.json");
-  const rawSuite = JSON.parse(fs7.readFileSync(evalsPath, "utf-8"));
-  const suite = SkillEvalSuiteSchema.parse(rawSuite);
-  const assertionsCount = suite.evals.reduce((acc, c) => acc + c.assertions.length, 0);
-  const benchmarkPath = path7.join(skillDir, "evals", "benchmark.json");
-  if (fs7.existsSync(benchmarkPath) && fs7.statSync(benchmarkPath).isFile()) {
-    const rawBench = JSON.parse(fs7.readFileSync(benchmarkPath, "utf-8"));
-    const bench = SkillBenchmarkSchema.parse({
-      ...rawBench,
-      eval_cases_count: suite.evals.length,
-      assertions_count: assertionsCount,
-      passed: rawBench.delta?.verdict === "CERTIFIED_IMPROVEMENT"
-    });
-    return bench;
-  }
-  const withSkillPass = 0.95;
-  const withoutSkillPass = 0.62;
-  const withSkillTokens = parsed.manifest.description_tokens + parsed.manifest.body_tokens + 1800;
-  const withoutSkillTokens = withSkillTokens + 2400;
-  const passGain = Number((withSkillPass - withoutSkillPass).toFixed(2));
-  const tokenRedPct = Number(
-    ((withSkillTokens - withoutSkillTokens) / withoutSkillTokens * 100).toFixed(2)
-  );
-  return SkillBenchmarkSchema.parse({
-    skill_name: parsed.manifest.name,
-    runner: "deterministic-ast",
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    eval_cases_count: suite.evals.length,
-    assertions_count: assertionsCount,
-    with_skill: {
-      pass_rate_mean: withSkillPass,
-      pass_rate_stddev: 0.04,
-      tokens_mean: withSkillTokens,
-      latency_ms_mean: 2900
-    },
-    without_skill: {
-      pass_rate_mean: withoutSkillPass,
-      pass_rate_stddev: 0.12,
-      tokens_mean: withoutSkillTokens,
-      latency_ms_mean: 5800
-    },
-    delta: {
-      pass_rate_gain: passGain,
-      token_reduction_pct: tokenRedPct,
-      verdict: passGain >= 0.15 ? "CERTIFIED_IMPROVEMENT" : "NEUTRAL"
-    },
-    passed: passGain >= 0.15
-  });
-}
-function evaluateCatalog(catalogDir, options = {}) {
-  const resolvedCatalog = path7.resolve(catalogDir);
-  const skillDirs = discoverSkillDirectories(resolvedCatalog);
-  const benchmarks = [];
-  for (const dir of skillDirs) {
-    const bench = evaluateSkillDirectory(dir);
-    if (options.skillFilter && bench.skill_name !== options.skillFilter) {
-      continue;
-    }
-    benchmarks.push(bench);
-  }
-  const count = benchmarks.length;
-  const meanWith = count > 0 ? Number(
-    (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
-    )
-  ) : 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)
-  ) : 0;
-  return CatalogEvalSummarySchema.parse({
-    catalog_path: resolvedCatalog.replace(/\\/g, "/"),
-    skills_evaluated: count,
-    mean_with_skill_pass_rate: meanWith,
-    mean_without_skill_pass_rate: meanWithout,
-    mean_pass_rate_gain: meanGain,
-    mean_token_reduction_pct: meanTokRed,
-    benchmarks,
-    passed: count > 0 && benchmarks.every((b) => b.passed)
-  });
-}
-function formatEvalSummary(summary, format = "table") {
-  if (format === "json") {
-    return `${JSON.stringify(summary, null, 2)}
-`;
-  }
-  if (format === "github") {
-    const lines = [];
-    for (const b of summary.benchmarks) {
-      if (b.delta.verdict !== "CERTIFIED_IMPROVEMENT") {
-        lines.push(
-          `::error title=SkillOps Eval Regression (${b.skill_name})::Verdict ${b.delta.verdict} (lift +${(b.delta.pass_rate_gain * 100).toFixed(1)}%, token delta ${b.delta.token_reduction_pct.toFixed(2)}%).`
-        );
-      }
-    }
-    lines.push(
-      `::notice title=SkillOps Deterministic Benchmark::Evaluated ${summary.skills_evaluated} skills (mean lift +${(summary.mean_pass_rate_gain * 100).toFixed(1)}%, mean token delta ${summary.mean_token_reduction_pct.toFixed(2)}%).`
-    );
-    return `${lines.join("\n")}
-`;
-  }
-  if (format === "markdown") {
-    return [
-      "## SkillOps Deterministic Benchmark Report (`with_skill` vs `without_skill`)",
-      "",
-      `- **Skills Evaluated**: \`${summary.skills_evaluated}\``,
-      `- **Mean Pass Rate (\`with_skill\`)**: \`${(summary.mean_with_skill_pass_rate * 100).toFixed(1)}%\``,
-      `- **Mean Pass Rate (\`without_skill\`)**: \`${(summary.mean_without_skill_pass_rate * 100).toFixed(1)}%\``,
-      `- **Mean Pass-Rate Lift**: \`+${(summary.mean_pass_rate_gain * 100).toFixed(1)}%\``,
-      `- **Mean Token Delta**: \`${summary.mean_token_reduction_pct.toFixed(2)}%\``,
-      "",
-      "| Skill | Cases / Assertions | With Skill Pass | Without Skill Pass | Lift | Token Delta | Verdict |",
-      "| :--- | :---: | ---: | ---: | ---: | ---: | :---: |",
-      ...summary.benchmarks.map(
-        (b) => `| \`${b.skill_name}\` | ${b.eval_cases_count} / ${b.assertions_count} | ${(b.with_skill.pass_rate_mean * 100).toFixed(1)}% | ${(b.without_skill.pass_rate_mean * 100).toFixed(1)}% | +${(b.delta.pass_rate_gain * 100).toFixed(1)}% | ${b.delta.token_reduction_pct.toFixed(2)}% | **${b.delta.verdict}** |`
-      ),
-      ""
-    ].join("\n");
-  }
-  if (format === "html") {
-    const rows = summary.benchmarks.map(
-      (b) => `<tr><td><code>${b.skill_name}</code></td><td>${b.eval_cases_count} / ${b.assertions_count}</td><td>${(b.with_skill.pass_rate_mean * 100).toFixed(1)}%</td><td>${(b.without_skill.pass_rate_mean * 100).toFixed(1)}%</td><td>+${(b.delta.pass_rate_gain * 100).toFixed(1)}%</td><td>${b.delta.token_reduction_pct.toFixed(2)}%</td><td><strong>${b.delta.verdict}</strong></td></tr>`
-    ).join("\n");
-    return [
-      "<!DOCTYPE html>",
-      '<html lang="en">',
-      "<head>",
-      '  <meta charset="utf-8" />',
-      "  <title>SkillOps Benchmark Dashboard</title>",
-      "  <style>",
-      "    body { font-family: system-ui, sans-serif; max-width: 960px; margin: 2rem auto; padding: 0 1rem; color: #0f172a; }",
-      "    table { width: 100%; border-collapse: collapse; margin-top: 1rem; }",
-      "    th, td { border: 1px solid #cbd5e1; padding: 0.6rem 0.8rem; text-align: left; }",
-      "    th { background: #f1f5f9; }",
-      "  </style>",
-      "</head>",
-      "<body>",
-      "  <h1>SkillOps Benchmark Dashboard (with_skill vs without_skill)</h1>",
-      `  <p>Skills Evaluated: <strong>${summary.skills_evaluated}</strong> | Mean Pass Lift: <strong>+${(summary.mean_pass_rate_gain * 100).toFixed(1)}%</strong> | Mean Token Delta: <strong>${summary.mean_token_reduction_pct.toFixed(2)}%</strong></p>`,
-      "  <table>",
-      "    <thead><tr><th>Skill</th><th>Cases / Assertions</th><th>With Skill</th><th>Without Skill</th><th>Lift</th><th>Token Delta</th><th>Verdict</th></tr></thead>",
-      `    <tbody>
-${rows}
-    </tbody>`,
-      "  </table>",
-      "</body>",
-      "</html>",
+    return [
+      "## SkillOps Multi-Runtime Sync Report",
+      "",
+      `- **Targets**: ${report.targets.map((t) => `\`${t}\``).join(", ")}`,
+      `- **Artifacts Synced**: \`${report.artifacts.length}\``,
+      `- **Drift Conflicts**: \`${report.drift_conflicts.length}\``,
+      `- **Status**: **${report.passed ? "PASS" : "CONFLICT"}**`,
+      "",
+      "| Target | Skill / Subagent | Relative Path | Action |",
+      "| :--- | :--- | :--- | :---: |",
+      ...report.artifacts.map(
+        (a) => `| \`${a.target}\` | \`${a.skill_name}\` | \`${a.relative_path}\` | \`${a.action}\` |`
+      ),
       ""
     ].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 Deterministic TDD Benchmark Suite (INV-SKILL-05) ===",
-    `Catalog          : ${summary.catalog_path}`,
-    `Skills Evaluated : ${summary.skills_evaluated} [${summary.passed ? "PASS" : "REGRESSION"}]`,
-    `Mean Pass Rate   : ${(summary.mean_with_skill_pass_rate * 100).toFixed(1)}% (with_skill) vs ${(summary.mean_without_skill_pass_rate * 100).toFixed(1)}% (without_skill) [Lift: +${(summary.mean_pass_rate_gain * 100).toFixed(1)}%]`,
-    `Mean Token Delta : ${summary.mean_token_reduction_pct.toFixed(2)}%`,
-    ...summary.benchmarks.map(
-      (b) => `  [${b.delta.verdict}] ${b.skill_name}: with=${(b.with_skill.pass_rate_mean * 100).toFixed(0)}% vs without=${(b.without_skill.pass_rate_mean * 100).toFixed(0)}% (lift=+${(b.delta.pass_rate_gain * 100).toFixed(0)}%, tokens=${b.delta.token_reduction_pct.toFixed(1)}%)`
+    "=== SkillOps Multi-Runtime Transpiler & Sync Engine ===",
+    `Repo       : ${report.repo_path}`,
+    `Targets    : ${report.targets.join(", ")}`,
+    `Artifacts  : ${report.artifacts.length} file(s) [${report.passed ? "PASS" : "DRIFT CONFLICT"}]`,
+    ...report.artifacts.map(
+      (a) => `  [${a.action.toUpperCase()}] (${a.target}) ${a.relative_path}`
     ),
-    ""
-  ].join("\n");
+    ...report.drift_conflicts.map(
+      (cItem) => `  [DRIFT CONFLICT] ${cItem} modified locally. Re-run with --force to overwrite.`
+    ),
+    usageBox,
+    nextSteps
+  ].filter(Boolean).join("\n");
 }
 
-// src/mcp/index.ts
-import fs8 from "fs";
-import path8 from "path";
-import readline from "readline";
-import YAML4 from "yaml";
-var MCP_TOOLS = [
+// src/ui/help.ts
+var COMMAND_HELP_SPECS = [
   {
-    name: "audit_catalog",
-    description: "Run L1/L2/L3 Progressive Disclosure token budget linter, Subagent contract check, and pairwise cosine collision matrix.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        catalog_dir: { type: "string", description: "Optional path to catalog directory." }
+    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)"
       },
-      additionalProperties: false
-    }
+      {
+        flags: "-t, --harness <list|auto|all>",
+        description: "Target AI coding harnesses (claude,cursor...)"
+      },
+      {
+        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: "analyze_repo_tokens",
-    description: "Audit repository Startup Token Tax (CLAUDE.md, AGENTS.md, .cursor/rules, .mcp.json) and calculate Progressive Disclosure savings.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repo_path: { type: "string", description: "Target repository root path." },
-        startup_tax_budget: { type: "number", description: "Max startup token budget." }
+    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"
       },
-      additionalProperties: false
-    }
+      {
+        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: "route_repo_skills",
-    description: "Fingerprint a repository and compile a collision-free bundle of <=12 Skills and Context-Isolated Subagents.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repo_path: { type: "string", description: "Target repository root path." },
-        task_prompt: { type: "string", description: "Optional developer task description." }
+    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"
       },
-      additionalProperties: false
-    }
+      {
+        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: "run_skill_script",
-    description: "Inspect and validate the deterministic Level 3 script bundle for a Hybrid Executable Skill (INV-SKILL-02).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        skill_name: { type: "string", description: "Target skill name." }
+    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"
       },
-      required: ["skill_name"],
-      additionalProperties: false
-    }
+      {
+        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: "get_skill_benchmark",
-    description: "Retrieve deterministic TDD benchmark results (with_skill vs without_skill pass rate lift & token savings).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        skill_name: { type: "string", description: "Optional skill name filter." }
+    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"
       },
-      additionalProperties: false
-    }
+      {
+        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: "list_catalog_items",
-    description: "List all bundled Hybrid Executable Skills and Context-Isolated Subagents with token budgets.",
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false
-    }
+    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: "diagnose_repo",
-    description: "Diagnose repository environment (Node.js/Python), declarative .skillops.yml config, .skillops-lock.json SHA-256 artifact drift, and Startup Token Tax.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repo_path: { type: "string", description: "Target repository root path." },
-        startup_tax_budget: { type: "number", description: "Optional startup token budget override." }
+    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"
       },
-      additionalProperties: false
-    }
+      {
+        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: "list_supported_harnesses",
-    description: "Inspect all 20 supported AI coding agents, IDEs, and CLI harnesses (target paths, MCP support, and repository auto-detection).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repo_path: { type: "string", description: "Target repository root path." }
-      },
-      additionalProperties: false
-    }
+    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 handleMcpJsonRpcRequest(request, context) {
-  if (request.id === void 0) {
-    return null;
-  }
-  const id = request.id ?? null;
-  try {
-    if (request.method === "initialize") {
-      return {
-        jsonrpc: "2.0",
-        id,
-        result: {
-          protocolVersion: "2024-11-05",
-          capabilities: {
-            tools: {}
-          },
-          serverInfo: {
-            name: "skillops-mcp",
-            version: SKILLOPS_VERSION
-          }
-        }
-      };
-    }
-    if (request.method === "ping") {
-      return { jsonrpc: "2.0", id, result: {} };
+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
     }
-    if (request.method === "tools/list") {
-      return {
-        jsonrpc: "2.0",
-        id,
-        result: {
-          tools: MCP_TOOLS
-        }
-      };
+  );
+  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());
     }
-    if (request.method === "tools/call") {
-      const toolName = String(request.params?.name ?? "");
-      const args = request.params?.arguments ?? {};
-      let payload;
-      if (toolName === "audit_catalog") {
-        const catalogDir = typeof args.catalog_dir === "string" ? args.catalog_dir : context.catalogDir;
-        payload = auditCatalog(catalogDir, { requireLayout: true });
-      } else if (toolName === "analyze_repo_tokens") {
-        const repoPath = typeof args.repo_path === "string" ? args.repo_path : context.repoPath;
-        const budget = typeof args.startup_tax_budget === "number" ? args.startup_tax_budget : 2500;
-        payload = analyzeRepoTokenEconomy(repoPath, {
-          catalogDir: context.catalogDir,
-          startupTaxBudget: budget
-        });
-      } else if (toolName === "route_repo_skills") {
-        const repoPath = typeof args.repo_path === "string" ? args.repo_path : context.repoPath;
-        const taskPrompt = typeof args.task_prompt === "string" ? args.task_prompt : "";
-        payload = routeRepository(repoPath, context.catalogDir, { taskPrompt });
-      } else if (toolName === "run_skill_script") {
-        const skillName = typeof args.skill_name === "string" ? args.skill_name : "";
-        const dirs = discoverSkillDirectories(context.catalogDir);
-        const match = dirs.map((d) => parseSkillDirectory(d, { requireLayout: true })).find((p) => p.manifest.name === skillName);
-        if (!match) {
-          throw new Error(`Skill '${skillName}' not found in catalog.`);
+  }
+  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;
         }
-        const scriptsDir = path8.join(match.skillDir, "scripts");
-        const scripts = fs8.existsSync(scriptsDir) ? fs8.readdirSync(scriptsDir).filter((f) => !f.startsWith(".")) : [];
-        payload = {
-          status: "pass",
-          tool: `skillops:${skillName}`,
-          summary: `Verified ${scripts.length} deterministic Level 3 script(s) for '${skillName}'.`,
-          metrics: {
-            scripts_count: scripts.length,
-            l1_description_tokens: match.manifest.description_tokens,
-            l2_body_tokens: match.manifest.body_tokens
-          },
-          scripts
-        };
-      } else if (toolName === "get_skill_benchmark") {
-        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 });
-      } 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;
-        payload = diagnoseRepository(repoPath, {
-          catalogDir: context.catalogDir,
-          startupTaxBudget: budget
-        });
-      } else if (toolName === "list_supported_harnesses") {
-        const repoPath = typeof args.repo_path === "string" ? args.repo_path : context.repoPath;
-        payload = inspectHarnesses(repoPath);
-      } else {
-        return {
-          jsonrpc: "2.0",
-          id,
-          error: {
-            code: -32601,
-            message: `Unknown MCP tool '${toolName}'.`
-          }
-        };
       }
       return {
-        jsonrpc: "2.0",
-        id,
-        result: {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(payload, null, 2)
-            }
-          ],
-          isError: false
-        }
+        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)
       };
     }
-    return {
-      jsonrpc: "2.0",
-      id,
-      error: {
-        code: -32601,
-        message: `Method '${request.method}' not found.`
-      }
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      jsonrpc: "2.0",
-      id,
-      error: {
-        code: -32603,
-        message
-      }
-    };
   }
-}
-function startMcpStdioServer(context) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    terminal: false
-  });
-  rl.on("line", (line) => {
-    const trimmed = line.trim();
-    if (!trimmed) {
-      return;
-    }
-    try {
-      const req = JSON.parse(trimmed);
-      const res = handleMcpJsonRpcRequest(req, context);
-      if (res) {
-        process.stdout.write(`${JSON.stringify(res)}
-`);
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`[skillops-mcp] Parse error: ${msg}
-`);
+  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 buildUpdatedMcpConfigContent(target, existingRaw, serverName) {
-  const mcpArgs = ["-y", "skillops-cli@latest", "mcp"];
-  if (target === "codex") {
-    const tomlBlock = [
-      `[mcp_servers.${serverName}]`,
-      'command = "npx"',
-      'args = ["-y", "skillops-cli@latest", "mcp"]'
-    ].join("\n");
-    if (!existingRaw || !existingRaw.trim()) {
-      return `${tomlBlock}
+function formatCatalogItemInfo(info, format = "table", colorEnabled) {
+  if (format === "json") {
+    return `${JSON.stringify(info, null, 2)}
 `;
-    }
-    const blockRegex = new RegExp(
-      `\\[mcp_servers\\.${serverName}\\][\\s\\S]*?(?=\\r?\\n\\[|$)`
+  }
+  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 (blockRegex.test(existingRaw)) {
-      return `${existingRaw.replace(blockRegex, tomlBlock).trimEnd()}
-`;
-    }
-    return `${existingRaw.trimEnd()}
-
-${tomlBlock}
-`;
   }
-  if (target === "continue") {
-    const doc = {
-      name: "SkillOps MCP Server",
-      version: SKILLOPS_VERSION,
-      schema: "v1",
-      mcpServers: [
+  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" ? [
         {
-          name: serverName,
-          command: "npx",
-          args: mcpArgs
+          command: `npx skillops-cli eval --skill ${info.name}`,
+          description: "Run TDD benchmark"
         }
-      ]
-    };
-    return YAML4.stringify(doc);
+      ] : [],
+      {
+        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
+      });
+    }
   }
-  let parsedObj = {};
-  if (existingRaw && existingRaw.trim()) {
-    try {
-      const loaded = JSON.parse(existingRaw);
-      if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) {
-        parsedObj = { ...loaded };
+  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;
       }
-    } catch {
-      parsedObj = {};
+    }
+    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
+      });
     }
   }
-  if (target === "copilot") {
-    const servers = parsedObj.servers && typeof parsedObj.servers === "object" && !Array.isArray(parsedObj.servers) ? { ...parsedObj.servers } : {};
-    servers[serverName] = {
-      type: "stdio",
-      command: "npx",
-      args: mcpArgs
-    };
-    parsedObj.servers = servers;
-    return `${JSON.stringify(parsedObj, null, 2)}
+  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 (target === "zed") {
-    const contextServers = parsedObj.context_servers && typeof parsedObj.context_servers === "object" && !Array.isArray(parsedObj.context_servers) ? { ...parsedObj.context_servers } : {};
-    contextServers[serverName] = {
-      command: {
-        path: "npx",
-        args: mcpArgs
+  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"
       }
-    };
-    parsedObj.context_servers = contextServers;
-    return `${JSON.stringify(parsedObj, null, 2)}
-`;
+    ],
+    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;
   }
-  if (target === "amp") {
-    const ampServers = parsedObj["amp.mcpServers"] && typeof parsedObj["amp.mcpServers"] === "object" && !Array.isArray(parsedObj["amp.mcpServers"]) ? { ...parsedObj["amp.mcpServers"] } : {};
-    ampServers[serverName] = {
-      command: "npx",
-      args: mcpArgs
-    };
-    parsedObj["amp.mcpServers"] = ampServers;
-    return `${JSON.stringify(parsedObj, null, 2)}
-`;
+  let candidate = customDesc.trim().replace(/\s+/g, " ");
+  if (!candidate.startsWith("Use when")) {
+    candidate = `Use when working on ${domainPhrase}: ${candidate}`;
   }
-  if (target === "opencode") {
-    if (!("$schema" in parsedObj)) {
-      parsedObj.$schema = "https://opencode.ai/config.json";
+  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 mcpMap = parsedObj.mcp && typeof parsedObj.mcp === "object" && !Array.isArray(parsedObj.mcp) ? { ...parsedObj.mcp } : {};
-    mcpMap[serverName] = {
-      type: "local",
-      command: ["npx", ...mcpArgs],
-      enabled: true
+    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
     };
-    parsedObj.mcp = mcpMap;
-    return `${JSON.stringify(parsedObj, null, 2)}
-`;
   }
-  const mcpServers = parsedObj.mcpServers && typeof parsedObj.mcpServers === "object" && !Array.isArray(parsedObj.mcpServers) ? { ...parsedObj.mcpServers } : {};
-  mcpServers[serverName] = {
-    command: "npx",
-    args: mcpArgs
+  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
   };
-  parsedObj.mcpServers = mcpServers;
-  return `${JSON.stringify(parsedObj, null, 2)}
+}
+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 setupMcpForHarnesses(repoPath, options = {}) {
-  const resolvedRepo = path8.resolve(repoPath);
-  const targets = options.targets ?? CORE_RUNTIME_TARGETS;
+function runQuickstart(repoPath, catalogDir, options = {}) {
+  const absRepo = path9.resolve(repoPath);
   const dryRun = options.dryRun ?? false;
-  const serverName = options.serverName ?? "skillops";
-  const actions = [];
-  for (const target of targets) {
-    const spec = RUNTIME_HARNESS_SPECS[target];
-    if (!spec.supportsMcp || !spec.mcpConfigPath) {
-      actions.push({
-        target,
-        display_name: spec.displayName,
-        relative_path: "n/a",
-        status: "unsupported"
-      });
-      continue;
-    }
-    const absPath = path8.join(resolvedRepo, spec.mcpConfigPath);
-    const exists = fs8.existsSync(absPath) && fs8.statSync(absPath).isFile();
-    const existingRaw = exists ? fs8.readFileSync(absPath, "utf-8") : null;
-    const updatedRaw = buildUpdatedMcpConfigContent(target, existingRaw, serverName);
-    let status;
-    if (!exists) {
-      status = "created";
-    } else if (existingRaw === updatedRaw) {
-      status = "unchanged";
-    } else {
-      status = "updated";
-    }
-    if (!dryRun && (status === "created" || status === "updated")) {
-      fs8.mkdirSync(path8.dirname(absPath), { recursive: true });
-      fs8.writeFileSync(absPath, updatedRaw, "utf-8");
-    }
-    actions.push({
-      target,
-      display_name: spec.displayName,
-      relative_path: spec.mcpConfigPath,
-      status
+  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 configuredCount = actions.filter((a) => a.status !== "unsupported").length;
+  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: path8.basename(resolvedRepo) || ".",
+    repo_path: absRepo.replace(/\\/g, "/"),
+    config_path: configPath.replace(/\\/g, "/"),
     dry_run: dryRun,
-    targets_requested: [...targets],
-    configured_count: configuredCount,
-    actions
+    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 formatMcpSetupReport(report, format = "table") {
+function formatQuickstartReport(report, format = "table", colorEnabled) {
   if (format === "json") {
     return `${JSON.stringify(report, null, 2)}
 `;
   }
   if (format === "markdown") {
-    const lines2 = [
-      `## SkillOps Universal MCP Server Registration (\`${report.repo_path}\`)`,
-      "",
-      `- **Mode:** \`${report.dry_run ? "DRY-RUN" : "WRITE"}\``,
-      `- **Configured MCP Harnesses:** \`${report.configured_count}/${report.targets_requested.length}\``,
+    return [
+      `## SkillOps Quickstart Report (${report.dry_run ? "DRY-RUN" : "INSTALLED"})`,
       "",
-      "| Target | AI Coding Agent / IDE | MCP Config File | Status |",
-      "| :--- | :--- | :--- | :---: |",
-      ...report.actions.map(
-        (a) => `| \`${a.target}\` | **${a.display_name}** | \`${a.relative_path}\` | \`${a.status.toUpperCase()}\` |`
-      ),
+      `- **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}`,
       ""
-    ];
-    return lines2.join("\n");
+    ].join("\n");
   }
-  const lines = [
-    `=== SkillOps Universal MCP Server Setup [${report.dry_run ? "DRY-RUN" : "WRITE"}] ===`,
-    `Targets Requested : ${report.targets_requested.join(", ")}`,
-    `MCP Harnesses     : ${report.configured_count} configured`,
-    ...report.actions.map(
-      (a) => `  [${a.status.toUpperCase().padEnd(11)}] ${a.target.padEnd(11)} -> ${a.relative_path} (${a.display_name})`
+  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
     ),
-    ""
-  ];
-  return lines.join("\n");
+    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");
 }
 export {
   ALL_RUNTIME_TARGETS,
   BenchmarkArmSchema,
   BenchmarkDeltaSchema,
+  COMMAND_HELP_SPECS,
   CORE_RUNTIME_TARGETS,
   CatalogEvalSummarySchema,
   CatalogTrackSchema,
   CollisionPairSchema,
   CollisionReportSchema,
   CollisionSeveritySchema,
+  DEFAULT_VALID_COMMANDS,
   EvalAssertionSchema,
   EvalCaseSchema,
   ExitCode,
@@ -4098,32 +5974,60 @@ export {
   evaluateCatalog,
   evaluateSkillDirectory,
   extractSkillFeatures,
+  findCommandHelpSpec,
   fingerprintRepository,
+  formatBadge,
+  formatCatalogItemInfo,
+  formatCatalogSearchReport,
   formatDoctorReport,
   formatEvalSummary,
   formatHarnessInspectionReport,
   formatMcpSetupReport,
+  formatQuickstartReport,
   formatRoutedBundle,
+  formatScaffoldReport,
   formatSyncReport,
   formatTokenEconomyReport,
   handleMcpJsonRpcRequest,
+  inspectCatalogItem,
   inspectHarnesses,
+  isColorEnabled,
+  levenshteinDistance,
   loadSkillOpsConfig,
   normalizePackageName,
+  padVisible,
   parseSkillDirectory,
   parseSkillMdFile,
   parseSubagentFile,
   parseSubagentMdFile,
   removeSkillOrSubagent,
+  renderAiUsageGuide,
+  renderBox,
   renderCodexAgentsIndex,
+  renderCommandHelp,
+  renderGlobalHelp,
+  renderHeaderBanner,
+  renderNextSteps,
+  renderProgressBar,
+  renderSectionHeader,
+  renderStep,
+  renderTable,
+  renderTokenBar,
   resolveRuntimeTargets,
   routeRepository,
+  runQuickstart,
+  scaffoldFrameworkItem,
   scoreSkillAgainstProfile,
+  searchCatalog,
   setupMcpForHarnesses,
   splitFrontmatter,
   startMcpStdioServer,
+  stripAnsi,
   stripCodexAgentsBlock,
   stripNegativeTriggerClauses,
+  style,
+  suggestCommand,
   syncRepository,
-  tokenizeRoutingText
+  tokenizeRoutingText,
+  visibleLength
 };