@skill-map/cli 0.12.0 → 0.14.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 // cli/entry.ts
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 import { Builtins, Cli as Cli2 } from "clipanion";
 
 // kernel/adapters/silent-logger.ts
@@ -50,7 +50,19 @@ function tx(template, vars = {}) {
 
 // cli/i18n/entry.texts.ts
 var ENTRY_TEXTS = {
-  bareNoProject: 'No skill-map project found in {{cwd}}.\nRun "sm init" to bootstrap one, or "sm --help" to see all commands.\n'
+  bareNoProject: 'No skill-map project found in {{cwd}}.\nRun "sm init" to bootstrap one, or "sm --help" to see all commands.\n',
+  parseErrorHeadline: "sm: {{message}}",
+  parseErrorUnknownOption: "unknown option '{{name}}'",
+  parseErrorUnknownOptionForVerb: "{{verb}}: unknown option '{{name}}'",
+  parseErrorUnknownCommand: "unknown command '{{name}}'",
+  parseErrorIncompleteCommand: "incomplete command '{{name}}'",
+  parseErrorSubcommandList: "Available subcommands: {{suggestions}}.",
+  parseErrorVerbUsage: "{{verb}}: {{message}}",
+  parseErrorMissingPositional: "{{verb}}: missing required positional argument(s) {{positionals}}",
+  parseErrorFlagSuggestion: "Did you mean '{{suggestion}}'?",
+  parseErrorVerbSuggestion: "Did you mean {{suggestions}}?",
+  parseErrorVerbHelpHint: "Run 'sm help {{verb}}' for usage.",
+  parseErrorFooter: "Run 'sm help' to see the full command list."
 };
 
 // kernel/ports/logger.ts
@@ -264,6 +276,174 @@ var ExitCode = {
   NotFound: 5
 };
 
+// cli/util/edit-distance.ts
+function editDistance(a, b, max) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  let curr = new Array(n + 1);
+  for (let i = 1; i <= m; i++) {
+    const rowMin = fillEditRow({ a, b, i, prev, curr });
+    if (rowMin > max) return max + 1;
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+function fillEditRow(args2) {
+  const { a, b, i, prev, curr } = args2;
+  curr[0] = i;
+  let rowMin = curr[0];
+  for (let j = 1; j < curr.length; j++) {
+    const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+    const value = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    curr[j] = value;
+    if (value < rowMin) rowMin = value;
+  }
+  return rowMin;
+}
+function closestMatches(target, candidates, options) {
+  const lcTarget = target.toLowerCase();
+  const ranked = [];
+  for (const c of candidates) {
+    const distance = editDistance(lcTarget, c.toLowerCase(), options.maxDistance);
+    if (distance <= options.maxDistance) ranked.push({ value: c, distance });
+  }
+  ranked.sort((a, b) => a.distance - b.distance || a.value.localeCompare(b.value));
+  return ranked.slice(0, options.topN).map((r) => r.value);
+}
+
+// cli/util/parse-error.ts
+function isClipanionParseError(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  if (typeof e.name !== "string") return false;
+  if (!Array.isArray(e.input)) return false;
+  return e.name === "UnknownSyntaxError" || e.name === "AmbiguousSyntaxError";
+}
+function formatParseError(params) {
+  const { args: args2, verbPaths, error } = params;
+  const firstToken = args2[0] ?? "";
+  const offendingFlag = extractOffendingFlag(error.message);
+  if (offendingFlag !== null) {
+    const verbPrefix2 = matchedVerbPrefix(args2, verbPaths);
+    const suggestion2 = suggestFlag(offendingFlag);
+    const headline = verbPrefix2 ? tx(ENTRY_TEXTS.parseErrorUnknownOptionForVerb, { verb: verbPrefix2, name: offendingFlag }) : tx(ENTRY_TEXTS.parseErrorUnknownOption, { name: offendingFlag });
+    return renderError(headline, suggestion2);
+  }
+  if (firstToken === "") {
+    return renderError(error.message.trim(), null);
+  }
+  const verbPrefix = matchedVerbPrefix(args2, verbPaths);
+  if (verbPrefix) return formatVerbScopedError(verbPrefix, error.message);
+  const subcommands = subcommandsUnder(firstToken, verbPaths);
+  if (subcommands.length > 0) {
+    const headline = tx(ENTRY_TEXTS.parseErrorIncompleteCommand, { name: firstToken });
+    const suggestion2 = tx(ENTRY_TEXTS.parseErrorSubcommandList, {
+      suggestions: formatSuggestionList(subcommands)
+    });
+    return renderError(headline, suggestion2);
+  }
+  const candidates = closestVerbs(firstToken, verbPaths);
+  const suggestion = candidates.length > 0 ? tx(ENTRY_TEXTS.parseErrorVerbSuggestion, { suggestions: formatSuggestionList(candidates) }) : null;
+  return renderError(tx(ENTRY_TEXTS.parseErrorUnknownCommand, { name: firstToken }), suggestion);
+}
+function formatVerbScopedError(verbPrefix, errorMessage) {
+  const helpHint = tx(ENTRY_TEXTS.parseErrorVerbHelpHint, { verb: verbPrefix });
+  const missing = extractMissingPositionals(errorMessage);
+  if (missing !== null) {
+    const headline2 = tx(ENTRY_TEXTS.parseErrorMissingPositional, {
+      verb: verbPrefix,
+      positionals: missing
+    });
+    return renderError(headline2, helpHint);
+  }
+  const headline = tx(ENTRY_TEXTS.parseErrorVerbUsage, {
+    verb: verbPrefix,
+    message: firstLine(errorMessage)
+  });
+  return renderError(headline, helpHint);
+}
+function subcommandsUnder(namespace, verbPaths) {
+  const matches = verbPaths.filter((path) => path.length >= 2 && path[0] === namespace).map((path) => path.join(" ")).sort();
+  return matches.slice(0, 3);
+}
+function matchedVerbPrefix(args2, verbPaths) {
+  const leading = [];
+  for (const tok of args2) {
+    if (tok.startsWith("-")) break;
+    leading.push(tok);
+  }
+  if (leading.length === 0) return "";
+  let best = [];
+  for (const path of verbPaths) {
+    if (path.length > leading.length) continue;
+    const matches = path.every((tok, i) => leading[i] === tok);
+    if (matches && path.length > best.length) best = path;
+  }
+  return best.join(" ");
+}
+function renderError(headline, suggestion) {
+  const lines = [tx(ENTRY_TEXTS.parseErrorHeadline, { message: headline })];
+  if (suggestion) lines.push(suggestion);
+  lines.push(ENTRY_TEXTS.parseErrorFooter);
+  return lines.join("\n") + "\n";
+}
+function extractOffendingFlag(message) {
+  const match = /Unsupported option name \("([^"]+)"\)/.exec(message);
+  return match ? match[1] : null;
+}
+function extractMissingPositionals(message) {
+  if (!message.startsWith("Not enough positional arguments")) return null;
+  const hintLine = message.split("\n").map((l) => l.trim()).find((l) => l.startsWith("$"));
+  if (!hintLine) return "";
+  const names = [...hintLine.matchAll(/<([A-Za-z][A-Za-z0-9_-]*)>/g)].map((m) => `<${m[1]}>`);
+  return names.length > 0 ? names.join(" ") : "";
+}
+function firstLine(message) {
+  return message.split("\n")[0].trim();
+}
+function suggestFlag(token) {
+  if (!token.startsWith("-")) return null;
+  if (token.startsWith("--")) return null;
+  if (token.length <= 2) return null;
+  const longForm = "-" + token;
+  return tx(ENTRY_TEXTS.parseErrorFlagSuggestion, { suggestion: longForm });
+}
+function closestVerbs(typed, verbPaths) {
+  const target = typed.toLowerCase();
+  const distanceCap = target.length <= 4 ? 2 : 3;
+  const ranked = [];
+  for (const path of verbPaths) {
+    const verb = path.join(" ");
+    const head = path[0];
+    const distHead = editDistance(target, head.toLowerCase(), distanceCap);
+    const distFull = editDistance(target, verb.replace(/\s+/g, "").toLowerCase(), distanceCap);
+    const distance = Math.min(distHead, distFull);
+    if (distance <= distanceCap) ranked.push({ verb, distance });
+  }
+  ranked.sort((a, b) => a.distance - b.distance || a.verb.localeCompare(b.verb));
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const { verb } of ranked) {
+    const head = verb.split(" ")[0];
+    if (seen.has(head)) continue;
+    seen.add(head);
+    out.push(verb);
+    if (out.length === 3) break;
+  }
+  return out;
+}
+function formatSuggestionList(items) {
+  const quoted = items.map((s) => `'${s}'`);
+  if (quoted.length <= 1) return quoted[0] ?? "";
+  if (quoted.length === 2) return `${quoted[0]} or ${quoted[1]}`;
+  return `${quoted.slice(0, -1).join(", ")}, or ${quoted[quoted.length - 1]}`;
+}
+
 // cli/util/runtime-context.ts
 import { homedir } from "os";
 function defaultRuntimeContext() {
@@ -839,7 +1019,7 @@ function normalizeTrigger(source) {
 
 // built-in-plugins/extractors/slash/index.ts
 var ID2 = "slash";
-var SLASH_RE = /(?:^|[^A-Za-z0-9_/])(\/[a-z0-9][a-z0-9_-]*(?::[a-z0-9][a-z0-9_-]*)?)/gi;
+var SLASH_RE = /(?<![A-Za-z0-9_/.:?#])(\/[a-z0-9][a-z0-9_-]*(?::[a-z0-9][a-z0-9_-]*)?)/gi;
 var slashExtractor = {
   id: ID2,
   pluginId: "claude",
@@ -982,6 +1162,77 @@ function lineFor(lineStarts, offset) {
   return lo + 1;
 }
 
+// built-in-plugins/extractors/markdown-link/index.ts
+import { posix as pathPosix } from "path";
+var ID5 = "markdown-link";
+var LINK_RE = /(?<!!)\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+var URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+var markdownLinkExtractor = {
+  id: ID5,
+  pluginId: "core",
+  kind: "extractor",
+  version: "1.0.0",
+  description: "Detects [text](path) markdown links and emits one references link per resolved file path.",
+  stability: "stable",
+  mode: "deterministic",
+  emitsLinkKinds: ["references"],
+  defaultConfidence: "high",
+  scope: "body",
+  extract(ctx) {
+    const seen = /* @__PURE__ */ new Set();
+    const lineStarts = computeLineStarts2(ctx.body);
+    const sourceDir = pathPosix.dirname(ctx.node.path);
+    for (const match of ctx.body.matchAll(LINK_RE)) {
+      const original = match[2];
+      const resolved = resolveTarget(sourceDir, original);
+      if (resolved === null) continue;
+      if (seen.has(resolved)) continue;
+      seen.add(resolved);
+      const offset = match.index ?? 0;
+      const link2 = {
+        source: ctx.node.path,
+        target: resolved,
+        kind: "references",
+        confidence: "high",
+        sources: [ID5],
+        trigger: {
+          originalTrigger: original,
+          normalizedTrigger: resolved
+        },
+        location: { line: lineFor2(lineStarts, offset) }
+      };
+      ctx.emitLink(link2);
+    }
+  }
+};
+function resolveTarget(sourceDir, raw) {
+  const noFragment = raw.split("#", 1)[0];
+  const noQuery = noFragment.split("?", 1)[0];
+  const trimmed = noQuery.trim();
+  if (trimmed.length === 0) return null;
+  if (URL_SCHEME_RE.test(trimmed)) return null;
+  if (trimmed.startsWith("/")) return null;
+  const joined = sourceDir === "." ? trimmed : `${sourceDir}/${trimmed}`;
+  return pathPosix.normalize(joined);
+}
+function computeLineStarts2(body) {
+  const starts = [0];
+  for (let i = 0; i < body.length; i += 1) {
+    if (body.charCodeAt(i) === 10) starts.push(i + 1);
+  }
+  return starts;
+}
+function lineFor2(lineStarts, offset) {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo < hi) {
+    const mid = lo + hi + 1 >>> 1;
+    if (lineStarts[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
 // built-in-plugins/i18n/trigger-collision.texts.ts
 var TRIGGER_COLLISION_TEXTS = {
   /**
@@ -1008,14 +1259,14 @@ var TRIGGER_COLLISION_TEXTS = {
 };
 
 // built-in-plugins/rules/trigger-collision/index.ts
-var ID5 = "trigger-collision";
+var ID6 = "trigger-collision";
 var ADVERTISING_KINDS = /* @__PURE__ */ new Set([
   "command",
   "skill",
   "agent"
 ]);
 var triggerCollisionRule = {
-  id: ID5,
+  id: ID6,
   pluginId: "core",
   kind: "rule",
   mode: "deterministic",
@@ -1115,7 +1366,7 @@ function analyzeTriggerBucket(normalized, claims) {
     part: parts[0]
   });
   return {
-    ruleId: ID5,
+    ruleId: ID6,
     severity: "error",
     nodeIds,
     message,
@@ -1134,9 +1385,9 @@ var BROKEN_REF_TEXTS = {
 };
 
 // built-in-plugins/rules/broken-ref/index.ts
-var ID6 = "broken-ref";
+var ID7 = "broken-ref";
 var brokenRefRule = {
-  id: ID6,
+  id: ID7,
   pluginId: "core",
   kind: "rule",
   version: "1.0.0",
@@ -1150,7 +1401,7 @@ var brokenRefRule = {
     for (const link2 of ctx.links) {
       if (isResolved(link2, byPath3, byNormalizedName)) continue;
       issues.push({
-        ruleId: ID6,
+        ruleId: ID7,
         severity: "warn",
         nodeIds: [link2.source],
         message: tx(BROKEN_REF_TEXTS.message, {
@@ -1198,9 +1449,9 @@ var SUPERSEDED_TEXTS = {
 };
 
 // built-in-plugins/rules/superseded/index.ts
-var ID7 = "superseded";
+var ID8 = "superseded";
 var supersededRule = {
-  id: ID7,
+  id: ID8,
   pluginId: "core",
   kind: "rule",
   version: "1.0.0",
@@ -1215,7 +1466,7 @@ var supersededRule = {
       const supersededBy = meta["supersededBy"];
       if (typeof supersededBy !== "string" || supersededBy.length === 0) continue;
       issues.push({
-        ruleId: ID7,
+        ruleId: ID8,
         severity: "info",
         nodeIds: [node.path],
         message: tx(SUPERSEDED_TEXTS.message, {
@@ -1236,9 +1487,9 @@ var LINK_CONFLICT_TEXTS = {
 };
 
 // built-in-plugins/rules/link-conflict/index.ts
-var ID8 = "link-conflict";
+var ID9 = "link-conflict";
 var linkConflictRule = {
-  id: ID8,
+  id: ID9,
   pluginId: "core",
   kind: "rule",
   version: "1.0.0",
@@ -1287,7 +1538,7 @@ var linkConflictRule = {
       const [source, target] = key.split("\0");
       const kindList = variants.map((v) => v.kind).join(" / ");
       issues.push({
-        ruleId: ID8,
+        ruleId: ID9,
         severity: "warn",
         nodeIds: [source, target],
         message: tx(LINK_CONFLICT_TEXTS.message, {
@@ -1333,10 +1584,10 @@ var ASCII_FORMATTER_TEXTS = {
 };
 
 // built-in-plugins/formatters/ascii/index.ts
-var ID9 = "ascii";
+var ID10 = "ascii";
 var KIND_ORDER = ["agent", "command", "hook", "skill", "note"];
 var asciiFormatter = {
-  id: ID9,
+  id: ID10,
   pluginId: "core",
   kind: "formatter",
   version: "1.0.0",
@@ -1599,9 +1850,9 @@ var VALIDATE_ALL_TEXTS = {
 };
 
 // built-in-plugins/rules/validate-all/index.ts
-var ID10 = "validate-all";
+var ID11 = "validate-all";
 var validateAllRule = {
-  id: ID10,
+  id: ID11,
   pluginId: "core",
   kind: "rule",
   version: "1.0.0",
@@ -1624,7 +1875,7 @@ function collectNodeFindings(v, node, out) {
   const result = v.validate("node", toNodeForSchema(node));
   if (result.ok) return;
   out.push({
-    ruleId: ID10,
+    ruleId: ID11,
     severity: "error",
     nodeIds: [node.path],
     message: tx(VALIDATE_ALL_TEXTS.nodeFailure, {
@@ -1638,7 +1889,7 @@ function collectLinkFindings(v, link2, out) {
   const result = v.validate("link", toLinkForSchema(link2));
   if (result.ok) return;
   out.push({
-    ruleId: ID10,
+    ruleId: ID11,
     severity: "error",
     nodeIds: [link2.source],
     message: tx(VALIDATE_ALL_TEXTS.linkFailure, {
@@ -1699,6 +1950,7 @@ var builtInBundles = [
     granularity: "extension",
     extensions: [
       externalUrlCounterExtractor,
+      markdownLinkExtractor,
       triggerCollisionRule,
       brokenRefRule,
       supersededRule,
@@ -2706,7 +2958,7 @@ var AsyncMutex = class {
       this.#locked = true;
       return;
     }
-    await new Promise((resolve20) => this.#waiters.push(resolve20));
+    await new Promise((resolve21) => this.#waiters.push(resolve21));
     this.#locked = true;
   }
   unlock() {
@@ -3953,6 +4205,7 @@ async function loadNodeEnrichments(db, nodePath) {
   }));
 }
 function parseJsonObject(s) {
+  if (s === null || s === void 0) return {};
   const parsed = JSON.parse(s);
   if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
     return parsed;
@@ -3960,6 +4213,7 @@ function parseJsonObject(s) {
   return {};
 }
 function parseJsonArray(s) {
+  if (s === null || s === void 0) return [];
   const parsed = JSON.parse(s);
   return Array.isArray(parsed) ? parsed : [];
 }
@@ -4970,6 +5224,7 @@ function formatErrorMessage(err) {
 // cli/i18n/config.texts.ts
 var CONFIG_TEXTS = {
   unknownKey: "Unknown config key: {{key}}\n",
+  unknownKeySuggestion: "Did you mean {{suggestions}}?\n",
   valueWithLayer: "{{value}}  (from {{layer}})\n",
   invalidAfterSet: "Invalid config after set: {{errors}}\n",
   setWritten: "{{key}} = {{value}}  (wrote {{path}})\n",
@@ -4999,6 +5254,29 @@ function assertSafeSegments(segments, key) {
     if (FORBIDDEN_SEGMENTS.has(seg)) throw new ForbiddenSegmentError(seg, key);
   }
 }
+function isPlainObject2(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function enumerateConfigPaths(obj, prefix = "") {
+  if (!isPlainObject2(obj)) return prefix ? [prefix] : [];
+  const out = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject2(value)) {
+      out.push(...enumerateConfigPaths(value, path));
+    } else {
+      out.push(path);
+    }
+  }
+  return out;
+}
+function suggestConfigKey(effective, typed) {
+  const candidates = enumerateConfigPaths(effective);
+  const matches = closestMatches(typed, candidates, { topN: 3, maxDistance: 3 });
+  if (matches.length === 0) return null;
+  const formatted = matches.map((m) => `'${m}'`).join(", ");
+  return tx(CONFIG_TEXTS.unknownKeySuggestion, { suggestions: formatted });
+}
 function getAtPath(obj, dotPath) {
   const segments = dotPath.split(".").filter(Boolean);
   assertSafeSegments(segments, dotPath);
@@ -5100,6 +5378,17 @@ function tryLoadConfig(opts, stderr) {
     return { ok: false, exitCode: ExitCode.Error };
   }
 }
+function safeGetAtPath(effective, key, stderr) {
+  try {
+    return { ok: true, value: getAtPath(effective, key) };
+  } catch (err) {
+    if (err instanceof ForbiddenSegmentError) {
+      stderr.write(tx(CONFIG_TEXTS.forbiddenKeySegment, { segment: err.segment, key: err.key }));
+      return { ok: false, exitCode: ExitCode.Error };
+    }
+    throw err;
+  }
+}
 function* iterDotPaths(obj, prefix = "") {
   if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
     if (prefix) yield [prefix, obj];
@@ -5177,18 +5466,13 @@ var ConfigGetCommand = class extends SmCommand {
     if (!result.ok) return result.exitCode;
     const { effective, warnings } = result.loaded;
     for (const w of warnings) this.context.stderr.write(w + "\n");
-    let value;
-    try {
-      value = getAtPath(effective, this.key);
-    } catch (err) {
-      if (err instanceof ForbiddenSegmentError) {
-        this.context.stderr.write(tx(CONFIG_TEXTS.forbiddenKeySegment, { segment: err.segment, key: err.key }));
-        return ExitCode.Error;
-      }
-      throw err;
-    }
+    const lookup = safeGetAtPath(effective, this.key, this.context.stderr);
+    if (!lookup.ok) return lookup.exitCode;
+    const { value } = lookup;
     if (value === void 0) {
       this.context.stderr.write(tx(CONFIG_TEXTS.unknownKey, { key: this.key }));
+      const suggestion = suggestConfigKey(effective, this.key);
+      if (suggestion !== null) this.context.stderr.write(suggestion);
       return ExitCode.NotFound;
     }
     if (this.json) {
@@ -6051,9 +6335,9 @@ var DB_TEXTS = {
   migrateKernelUpToDate: "kernel \xB7 Already up to date.\n",
   migrateKernelApplied: "kernel \xB7 Applied {{count}} migration(s)\n",
   migrateKernelAppliedWithBackup: "kernel \xB7 Applied {{count}} migration(s) \xB7 backup: {{backupPath}}\n",
-  // --- shell / dump (system sqlite3 binary required) ------------------
+  // --- shell (system sqlite3 binary required for the interactive REPL) ---
   shellSqlite3NotFound: "sqlite3 binary not found on PATH. Install it (macOS: brew install sqlite; Debian/Ubuntu: apt install sqlite3) or use `sm db dump` for read-only inspection.\n",
-  dumpSqlite3NotFound: "sqlite3 binary not found on PATH. Install it to use `sm db dump`.\n",
+  // --- dump (pure node:sqlite, no external binary) ----------------------
   dumpInvalidTable: "--tables: refusing non-identifier name {{table}}. Table names must match [a-zA-Z_][a-zA-Z0-9_]*\n",
   // --- plugin migration runner -----------------------------------------
   pluginMigrateFailure: "plugin {{pluginId}} \xB7 {{reason}}\n",
@@ -6344,18 +6628,12 @@ var DbDumpCommand = class extends SmCommand {
   static usage = Command5.Usage({
     category: "Database",
     description: "SQL dump to stdout.",
-    details: "Read-only. Use --tables <names...> to limit the dump to specific tables."
+    details: "Read-only. Pure node:sqlite \u2014 no external `sqlite3` binary required. Use --tables <names...> to limit the dump to specific tables."
   });
   tables = Option5.Array("--tables", { required: false });
-  // CLI orchestrator: each branch (db existence, per-table identifier
-  // gate, sqlite3-not-found fallback, exit-status passthrough) is a
-  // single dispatcher decision. Splitting per branch scatters the gate
-  // away from the value it gates.
-  // eslint-disable-next-line complexity
   async run() {
     const path = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(path, this.context.stderr)) return ExitCode.NotFound;
-    const args2 = ["-readonly", path, ".dump"];
     if (this.tables && this.tables.length > 0) {
       for (const t of this.tables) {
         if (!SAFE_SQL_IDENTIFIER_RE.test(t)) {
@@ -6363,16 +6641,65 @@ var DbDumpCommand = class extends SmCommand {
           return ExitCode.Error;
         }
       }
-      args2.push(...this.tables);
     }
-    const result = spawnSync2("sqlite3", args2, { stdio: ["ignore", "inherit", "inherit"] });
-    if (result.error && result.error.code === "ENOENT") {
-      this.context.stderr.write(DB_TEXTS.dumpSqlite3NotFound);
+    try {
+      dumpDatabaseToStream(path, this.context.stdout, this.tables ?? null);
+      return ExitCode.Ok;
+    } catch (err) {
+      this.context.stderr.write(`sm db dump: ${err.message}
+`);
       return ExitCode.Error;
     }
-    return result.status ?? 0;
   }
 };
+function dumpDatabaseToStream(dbPath, out, tables) {
+  const db = new DatabaseSync4(dbPath, { readOnly: true });
+  try {
+    out.write("PRAGMA foreign_keys=OFF;\n");
+    out.write("BEGIN TRANSACTION;\n");
+    const objects = listSchemaObjects(db, tables);
+    for (const obj of objects) {
+      if (!obj.sql) continue;
+      out.write(`${obj.sql};
+`);
+    }
+    for (const obj of objects) {
+      if (obj.type !== "table") continue;
+      writeTableData(db, out, obj.name);
+    }
+    out.write("COMMIT;\n");
+  } finally {
+    db.close();
+  }
+}
+function listSchemaObjects(db, tables) {
+  const baseQuery = "SELECT type, name, sql FROM sqlite_master WHERE type IN ('table','index','trigger','view') AND name NOT LIKE 'sqlite_%'";
+  if (tables === null || tables.length === 0) {
+    return db.prepare(`${baseQuery} ORDER BY rootpage`).all();
+  }
+  const placeholders = tables.map(() => "?").join(",");
+  const sql4 = `${baseQuery} AND (name IN (${placeholders}) OR tbl_name IN (${placeholders})) ORDER BY rootpage`;
+  return db.prepare(sql4).all(...tables, ...tables);
+}
+function writeTableData(db, out, tableName) {
+  const quoted = `"${tableName.replace(/"/g, '""')}"`;
+  for (const row of db.prepare(`SELECT * FROM ${quoted}`).iterate()) {
+    const values = Object.values(row).map(formatSqlValue).join(",");
+    out.write(`INSERT INTO ${quoted} VALUES(${values});
+`);
+  }
+}
+function formatSqlNumber(value) {
+  return Number.isFinite(value) ? String(value) : "NULL";
+}
+function formatSqlValue(value) {
+  if (value === null || value === void 0) return "NULL";
+  if (typeof value === "number") return formatSqlNumber(value);
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "boolean") return value ? "1" : "0";
+  if (value instanceof Uint8Array) return `X'${Buffer.from(value).toString("hex")}'`;
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
 var DbMigrateCommand = class extends SmCommand {
   static paths = [["db", "migrate"]];
   static usage = Command5.Usage({
@@ -6762,18 +7089,19 @@ var ExportCommand = class extends SmCommand {
       (POSIX glob \u2014 \`*\` matches a single segment, \`**\` matches across
       segments).
 
-      Pass an empty query (\`""\`) to export every node.
+      Pass an empty query (\`""\`) \u2014 or omit the argument entirely \u2014 to
+      export every node.
 
       Run \`sm scan\` first to populate the DB.
     `,
     examples: [
+      ["Whole graph (no query)", "$0 export --format md"],
       ["Every command node", '$0 export "kind=command" --format json'],
       ["Skills + agents with issues", '$0 export "kind=skill,agent has=issues" --format md'],
-      ["Files under a path glob", '$0 export "path=.claude/commands/**" --format json'],
-      ["Whole graph as Markdown", '$0 export "" --format md']
+      ["Files under a path glob", '$0 export "path=.claude/commands/**" --format json']
     ]
   });
-  query = Option6.String({ required: true });
+  query = Option6.String({ required: false });
   format = Option6.String("--format", { required: false });
   async run() {
     const format = (this.format ?? "json").toLowerCase();
@@ -6798,7 +7126,7 @@ var ExportCommand = class extends SmCommand {
     }
     let parsedQuery;
     try {
-      parsedQuery = parseExportQuery(this.query);
+      parsedQuery = parseExportQuery(this.query ?? "");
     } catch (err) {
       if (err instanceof ExportQueryError) {
         this.context.stderr.write(tx(EXPORT_TEXTS.errorPrefix, { message: err.message }));
@@ -7025,16 +7353,108 @@ var GraphCommand = class extends SmCommand {
   }
 };
 
+// cli/commands/guide.ts
+import { existsSync as existsSync12, readFileSync as readFileSync10 } from "fs";
+import { writeFile } from "fs/promises";
+import { dirname as dirname9, join as join10, resolve as resolve13 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
+import { Command as Command8, Option as Option8 } from "clipanion";
+
+// cli/i18n/guide.texts.ts
+var GUIDE_TEXTS = {
+  // Success — written to stdout after `<cwd>/sm-guide.md` is created.
+  written: 'Listo. sm-guide.md creado en {{cwd}}. Abr\xED Claude Code ac\xE1 y decile "gu\xEDame" para arrancar la gu\xEDa interactiva.\n',
+  // Refusal — `sm-guide.md` already exists and `--force` was not set.
+  // Goes to stderr, exit code 2 (operational error per spec § Exit codes).
+  alreadyExists: "sm guide: sm-guide.md ya existe en {{cwd}}. Us\xE1 `--force` para sobrescribir.\n",
+  // I/O failure on write or on reading the bundled SKILL source.
+  writeFailed: "sm guide: no se pudo escribir sm-guide.md: {{message}}\n",
+  sourceMissing: "sm guide: no se pudo leer la gu\xEDa empaquetada (SKILL.md) desde la instalaci\xF3n. Reinstal\xE1 @skill-map/cli o report\xE1 el bug.\n"
+};
+
+// cli/commands/guide.ts
+var SM_GUIDE_FILENAME = "sm-guide.md";
+var GuideCommand = class extends SmCommand {
+  static paths = [["guide"]];
+  static usage = Command8.Usage({
+    category: "Setup",
+    description: "Materialize the interactive tester guide (sm-guide.md) in the current directory.",
+    details: `
+      Drops the canonical SKILL.md content as ./sm-guide.md so a tester
+      can open Claude Code in the cwd and trigger the sm-guide skill
+      ("gu\xEDame"). Top-level only \u2014 no subdirectory is created.
+
+      Does NOT require an initialized .skill-map/ project. Refuses to
+      overwrite an existing sm-guide.md unless --force is passed.
+    `,
+    examples: [
+      ["Materialize the guide in the cwd", "$0 guide"],
+      ["Overwrite an existing sm-guide.md", "$0 guide --force"]
+    ]
+  });
+  force = Option8.Boolean("--force", false, {
+    description: "Overwrite an existing sm-guide.md without prompting."
+  });
+  async run() {
+    const ctx = defaultRuntimeContext();
+    const target = join10(ctx.cwd, SM_GUIDE_FILENAME);
+    if (await pathExists(target) && !this.force) {
+      this.context.stderr.write(tx(GUIDE_TEXTS.alreadyExists, { cwd: ctx.cwd }));
+      return ExitCode.Error;
+    }
+    let body;
+    try {
+      body = loadBundledGuideText();
+    } catch {
+      this.context.stderr.write(GUIDE_TEXTS.sourceMissing);
+      return ExitCode.Error;
+    }
+    try {
+      await writeFile(target, body);
+    } catch (err) {
+      this.context.stderr.write(
+        tx(GUIDE_TEXTS.writeFailed, { message: formatErrorMessage(err) })
+      );
+      return ExitCode.Error;
+    }
+    this.context.stdout.write(tx(GUIDE_TEXTS.written, { cwd: ctx.cwd }));
+    return ExitCode.Ok;
+  }
+};
+var cachedGuide = null;
+function loadBundledGuideText() {
+  if (cachedGuide !== null) return cachedGuide;
+  cachedGuide = readGuideFromDisk();
+  return cachedGuide;
+}
+function readGuideFromDisk() {
+  const here = dirname9(fileURLToPath5(import.meta.url));
+  const candidates = [
+    // dev: src/cli/commands/ → repo-root .claude/skills/sm-guide/SKILL.md
+    resolve13(here, "../../../.claude/skills/sm-guide/SKILL.md"),
+    // bundled: dist/cli.js → dist/cli/guide/sm-guide.md (sibling)
+    resolve13(here, "cli/guide/sm-guide.md"),
+    // bundled fallback: any-depth → cli/guide/sm-guide.md
+    resolve13(here, "../cli/guide/sm-guide.md")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync12(candidate)) {
+      return readFileSync10(candidate, "utf8");
+    }
+  }
+  throw new Error(`SKILL.md not found in any candidate location (last tried: ${candidates[candidates.length - 1]})`);
+}
+
 // cli/commands/help.ts
-import { readFileSync as readFileSync10 } from "fs";
+import { readFileSync as readFileSync11 } from "fs";
 import { createRequire as createRequire4 } from "module";
-import { resolve as resolve13 } from "path";
-import { Command as Command8, Option as Option8 } from "clipanion";
+import { resolve as resolve14 } from "path";
+import { Command as Command9, Option as Option9 } from "clipanion";
 
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.12.0",
+  version: "0.14.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -7093,7 +7513,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "*",
+    "@skill-map/spec": "0.14.1",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -7210,9 +7630,9 @@ var HELP_TEXTS = {
 };
 
 // cli/commands/help.ts
-var HelpCommand = class extends Command8 {
+var HelpCommand = class extends Command9 {
   static paths = [["help"]];
-  static usage = Command8.Usage({
+  static usage = Command9.Usage({
     category: "Introspection",
     description: "Self-describing introspection. --format human|md|json.",
     details: `
@@ -7226,8 +7646,8 @@ var HelpCommand = class extends Command8 {
         json            \u2014 structured surface dump per spec/cli-contract.md.
     `
   });
-  verbParts = Option8.Rest({ required: 0 });
-  format = Option8.String("--format", "human");
+  verbParts = Option9.Rest({ required: 0 });
+  format = Option9.String("--format", "human");
   async execute() {
     const format = normalizeFormat(this.format);
     if (!format) {
@@ -7349,8 +7769,8 @@ function resolveSpecVersion() {
   try {
     const req = createRequire4(import.meta.url);
     const indexPath = req.resolve("@skill-map/spec/index.json");
-    const pkgPath = resolve13(indexPath, "..", "package.json");
-    const pkg = JSON.parse(readFileSync10(pkgPath, "utf8"));
+    const pkgPath = resolve14(indexPath, "..", "package.json");
+    const pkg = JSON.parse(readFileSync11(pkgPath, "utf8"));
     return pkg.version;
   } catch {
     return "unknown";
@@ -7545,7 +7965,7 @@ function renderCompactOverview(verbs) {
   lines.push(HELP_TEXTS.compactFooter);
   return lines.join("\n") + "\n";
 }
-var RootHelpCommand = class extends Command8 {
+var RootHelpCommand = class extends Command9 {
   static paths = [["-h"], ["--help"]];
   async execute() {
     const rawDefs = this.cli.definitions();
@@ -7601,13 +8021,13 @@ function registeredVerbPaths(cli2) {
 }
 
 // cli/commands/init.ts
-import { mkdir as mkdir2, readFile as readFile2, writeFile } from "fs/promises";
-import { join as join10 } from "path";
-import { Command as Command9, Option as Option9 } from "clipanion";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { join as join11 } from "path";
+import { Command as Command10, Option as Option10 } from "clipanion";
 
 // kernel/orchestrator.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync12, statSync as statSync3 } from "fs";
+import { existsSync as existsSync13, statSync as statSync3 } from "fs";
 import { Tiktoken } from "js-tiktoken/lite";
 import cl100k_base from "js-tiktoken/ranks/cl100k_base";
 import yaml2 from "js-yaml";
@@ -7742,7 +8162,7 @@ function validateRoots(roots) {
     throw new Error(ORCHESTRATOR_TEXTS.runScanRootEmptyArray);
   }
   for (const root of roots) {
-    if (!existsSync12(root) || !statSync3(root).isDirectory()) {
+    if (!existsSync13(root) || !statSync3(root).isDirectory()) {
       throw new Error(tx(ORCHESTRATOR_TEXTS.runScanRootMissing, { root }));
     }
   }
@@ -8518,10 +8938,10 @@ function recomputeExternalRefsCount(nodes, externalLinks, cachedPaths) {
 }
 
 // kernel/scan/watcher.ts
-import { resolve as resolve14, relative as relative4, sep as sep2 } from "path";
+import { resolve as resolve15, relative as relative4, sep as sep2 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
-  const absRoots = opts.roots.map((r) => resolve14(opts.cwd, r));
+  const absRoots = opts.roots.map((r) => resolve15(opts.cwd, r));
   const ignoreFilter = opts.ignoreFilter;
   const ignored = ignoreFilter ? (path) => {
     const rel = relativePathFromRoots(path, absRoots);
@@ -8767,7 +9187,7 @@ function createCliProgressEmitter(stderr) {
 // cli/commands/init.ts
 var InitCommand = class extends SmCommand {
   static paths = [["init"]];
-  static usage = Command9.Usage({
+  static usage = Command10.Usage({
     category: "Setup",
     description: "Bootstrap the current scope: scaffold .skill-map/, provision DB, run first scan.",
     details: `
@@ -8791,16 +9211,16 @@ var InitCommand = class extends SmCommand {
       ["Preview what would be created", "$0 init --dry-run"]
     ]
   });
-  noScan = Option9.Boolean("--no-scan", false, {
+  noScan = Option10.Boolean("--no-scan", false, {
     description: "Skip the first scan after scaffolding."
   });
-  force = Option9.Boolean("--force", false, {
+  force = Option10.Boolean("--force", false, {
     description: "Overwrite an existing settings.json / settings.local.json / .skill-mapignore."
   });
-  strict = Option9.Boolean("--strict", false, {
+  strict = Option10.Boolean("--strict", false, {
     description: "Strict mode: fail on any layered-loader warning AND promote frontmatter warnings to errors during the first scan. Same flag as sm scan / sm config."
   });
-  dryRun = Option9.Boolean("-n,--dry-run", false, {
+  dryRun = Option10.Boolean("-n,--dry-run", false, {
     description: "Preview the scope provisioning without touching the filesystem or the DB. Honours --force for the would-overwrite preview. Skips the first scan unconditionally \u2014 dry-run never persists."
   });
   // CLI orchestrator: paths setup + dry-run branch (delegated to
@@ -8811,7 +9231,7 @@ var InitCommand = class extends SmCommand {
   async run() {
     const ctx = defaultRuntimeContext();
     const scopeRoot = this.global ? ctx.homedir : ctx.cwd;
-    const skillMapDir = join10(scopeRoot, SKILL_MAP_DIR);
+    const skillMapDir = join11(scopeRoot, SKILL_MAP_DIR);
     const settingsPath = defaultSettingsPath(scopeRoot);
     const localPath = defaultLocalSettingsPath(scopeRoot);
     const ignorePath = defaultIgnoreFilePath(scopeRoot);
@@ -8835,17 +9255,17 @@ var InitCommand = class extends SmCommand {
       return ExitCode.Ok;
     }
     await mkdir2(skillMapDir, { recursive: true });
-    await writeFile(settingsPath, JSON.stringify({ schemaVersion: 1 }, null, 2) + "\n");
+    await writeFile2(settingsPath, JSON.stringify({ schemaVersion: 1 }, null, 2) + "\n");
     if (!await pathExists(localPath) || this.force) {
-      await writeFile(localPath, "{}\n");
+      await writeFile2(localPath, "{}\n");
     }
     if (!await pathExists(ignorePath) || this.force) {
-      await writeFile(ignorePath, loadBundledIgnoreText());
+      await writeFile2(ignorePath, loadBundledIgnoreText());
     }
     if (!this.global) {
       const updated = await ensureGitignoreEntries(scopeRoot, GITIGNORE_ENTRIES);
       if (updated) {
-        const gitignorePath = join10(scopeRoot, ".gitignore");
+        const gitignorePath = join11(scopeRoot, ".gitignore");
         this.context.stdout.write(
           GITIGNORE_ENTRIES.length === 1 ? tx(INIT_TEXTS.gitignoreUpdatedSingular, { path: gitignorePath }) : tx(INIT_TEXTS.gitignoreUpdatedPlural, {
             path: gitignorePath,
@@ -8884,7 +9304,7 @@ async function dryRunFileMessage(path) {
 }
 async function writeDryRunGitignorePlan(stdout, scopeRoot) {
   const wouldAdd = await previewGitignoreEntries(scopeRoot, GITIGNORE_ENTRIES);
-  const gitignorePath = join10(scopeRoot, ".gitignore");
+  const gitignorePath = join11(scopeRoot, ".gitignore");
   if (wouldAdd.length === 0) {
     stdout.write(tx(INIT_TEXTS.dryRunWouldLeaveGitignoreUnchanged, { path: gitignorePath }));
   } else if (wouldAdd.length === 1) {
@@ -8959,7 +9379,7 @@ async function runFirstScan(scopeRoot, homedir2, dbPath, strict, stdout, stderr)
   return hasErrors ? ExitCode.Issues : ExitCode.Ok;
 }
 async function previewGitignoreEntries(scopeRoot, entries) {
-  const path = join10(scopeRoot, ".gitignore");
+  const path = join11(scopeRoot, ".gitignore");
   const body = await pathExists(path) ? await readFile2(path, "utf8") : "";
   const present = new Set(
     body.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"))
@@ -8967,7 +9387,7 @@ async function previewGitignoreEntries(scopeRoot, entries) {
   return entries.filter((entry) => !present.has(entry));
 }
 async function ensureGitignoreEntries(scopeRoot, entries) {
-  const path = join10(scopeRoot, ".gitignore");
+  const path = join11(scopeRoot, ".gitignore");
   let body = "";
   if (await pathExists(path)) {
     body = await readFile2(path, "utf8");
@@ -8984,12 +9404,12 @@ async function ensureGitignoreEntries(scopeRoot, entries) {
     present.add(entry);
     changed = true;
   }
-  if (changed) await writeFile(path, body);
+  if (changed) await writeFile2(path, body);
   return changed;
 }
 
 // cli/commands/history.ts
-import { Command as Command10, Option as Option10 } from "clipanion";
+import { Command as Command11, Option as Option11 } from "clipanion";
 
 // cli/i18n/option-validators.texts.ts
 var OPTION_VALIDATORS_TEXTS = {
@@ -9078,7 +9498,7 @@ function parseStatuses(input, stderr) {
 }
 var HistoryCommand = class extends SmCommand {
   static paths = [["history"]];
-  static usage = Command10.Usage({
+  static usage = Command11.Usage({
     category: "History",
     description: "Filter execution records. --json emits an array conforming to execution-record.schema.json.",
     details: `
@@ -9098,12 +9518,12 @@ var HistoryCommand = class extends SmCommand {
       ["Machine-readable, scoped to one node", "$0 history -n skills/foo.md --json"]
     ]
   });
-  node = Option10.String("-n", { required: false });
-  action = Option10.String("--action", { required: false });
-  status = Option10.String("--status", { required: false });
-  since = Option10.String("--since", { required: false });
-  until = Option10.String("--until", { required: false });
-  limit = Option10.String("--limit", { required: false });
+  node = Option11.String("-n", { required: false });
+  action = Option11.String("--action", { required: false });
+  status = Option11.String("--status", { required: false });
+  since = Option11.String("--since", { required: false });
+  until = Option11.String("--until", { required: false });
+  limit = Option11.String("--limit", { required: false });
   // CLI list verb: many optional filter flags (`--node`, `--action`,
   // `--status`, `--since`, `--until`, `--limit`, `--json`, `--quiet`)
   // each adding a guarded mutation to the filter or render path. Each
@@ -9151,7 +9571,7 @@ var HistoryCommand = class extends SmCommand {
 };
 var HistoryStatsCommand = class extends SmCommand {
   static paths = [["history", "stats"]];
-  static usage = Command10.Usage({
+  static usage = Command11.Usage({
     category: "History",
     description: "Aggregate counts, tokens, periods, top nodes, and error rates over state_executions. --json conforms to history-stats.schema.json.",
     details: `
@@ -9169,10 +9589,10 @@ var HistoryStatsCommand = class extends SmCommand {
       ["Top 5 nodes, JSON", "$0 history stats --top 5 --json"]
     ]
   });
-  since = Option10.String("--since", { required: false });
-  until = Option10.String("--until", { required: false });
-  period = Option10.String("--period", { required: false });
-  top = Option10.String("--top", { required: false });
+  since = Option11.String("--since", { required: false });
+  until = Option11.String("--until", { required: false });
+  period = Option11.String("--period", { required: false });
+  top = Option11.String("--top", { required: false });
   // CLI stats verb: range parsing + window flags + period flag + JSON
   // branch + per-period iteration. Each branch is a single-purpose
   // gate; the data work lives in `aggregateHistoryStats`.
@@ -9353,11 +9773,11 @@ function formatRow(...cols) {
 
 // cli/commands/jobs.ts
 import { unlink } from "fs/promises";
-import { Command as Command11, Option as Option11 } from "clipanion";
+import { Command as Command12, Option as Option12 } from "clipanion";
 
 // kernel/jobs/orphan-files.ts
 import { readdirSync as readdirSync6, statSync as statSync4 } from "fs";
-import { join as join11, resolve as resolve15 } from "path";
+import { join as join12, resolve as resolve16 } from "path";
 function findOrphanJobFiles(jobsDir, referencedPaths) {
   let entries;
   try {
@@ -9372,7 +9792,7 @@ function findOrphanJobFiles(jobsDir, referencedPaths) {
   const orphans = [];
   for (const name of entries) {
     if (!name.endsWith(".md")) continue;
-    const abs = resolve15(join11(jobsDir, name));
+    const abs = resolve16(join12(jobsDir, name));
     if (!referencedPaths.has(abs)) orphans.push(abs);
   }
   orphans.sort();
@@ -9401,7 +9821,7 @@ var JOBS_TEXTS = {
 // cli/commands/jobs.ts
 var JobPruneCommand = class extends SmCommand {
   static paths = [["job", "prune"]];
-  static usage = Command11.Usage({
+  static usage = Command12.Usage({
     category: "Jobs",
     description: "Retention GC for completed / failed jobs (per config policy). --orphan-files removes MD files with no DB row.",
     details: `
@@ -9428,10 +9848,10 @@ var JobPruneCommand = class extends SmCommand {
       ["Preview without touching the DB", "$0 job prune --dry-run --json"]
     ]
   });
-  orphanFiles = Option11.Boolean("--orphan-files", false, {
+  orphanFiles = Option12.Boolean("--orphan-files", false, {
     description: "Also remove MD files in .skill-map/jobs/ that have no matching state_jobs row."
   });
-  dryRun = Option11.Boolean("-n,--dry-run", false, {
+  dryRun = Option12.Boolean("-n,--dry-run", false, {
     description: "Report what would be pruned without touching the DB or filesystem."
   });
   async run() {
@@ -9548,7 +9968,7 @@ function formatPolicy(seconds) {
 }
 
 // cli/commands/list.ts
-import { Command as Command12, Option as Option12 } from "clipanion";
+import { Command as Command13, Option as Option13 } from "clipanion";
 
 // cli/i18n/list.texts.ts
 var LIST_TEXTS = {
@@ -9576,7 +9996,7 @@ var SORT_BY = {
 var PATH_COL_WIDTH = 50;
 var ListCommand = class extends SmCommand {
   static paths = [["list"]];
-  static usage = Command12.Usage({
+  static usage = Command13.Usage({
     category: "Browse",
     description: "Tabular listing of nodes. --json emits an array conforming to node.schema.json.",
     details: `
@@ -9597,10 +10017,10 @@ var ListCommand = class extends SmCommand {
       ["Only nodes with issues, machine-readable", "$0 list --issue --json"]
     ]
   });
-  kind = Option12.String("--kind", { required: false });
-  issue = Option12.Boolean("--issue", false);
-  sortBy = Option12.String("--sort-by", { required: false });
-  limit = Option12.String("--limit", { required: false });
+  kind = Option13.String("--kind", { required: false });
+  issue = Option13.Boolean("--issue", false);
+  sortBy = Option13.String("--sort-by", { required: false });
+  limit = Option13.String("--limit", { required: false });
   async run() {
     let sortColumn = "path";
     let sortDirection = "asc";
@@ -9702,7 +10122,7 @@ function formatRow2(path, kind, out, inCount, ext, issues, bytes) {
 }
 
 // cli/commands/orphans.ts
-import { Command as Command13, Option as Option13 } from "clipanion";
+import { Command as Command14, Option as Option14 } from "clipanion";
 
 // cli/i18n/orphans.texts.ts
 var ORPHANS_TEXTS = {
@@ -9757,7 +10177,7 @@ function isStringArray(v) {
 }
 var OrphansCommand = class extends SmCommand {
   static paths = [["orphans"]];
-  static usage = Command13.Usage({
+  static usage = Command14.Usage({
     category: "Browse",
     description: "List orphan / auto-rename issues from the last scan. --json emits an array conforming to issue.schema.json.",
     details: `
@@ -9772,7 +10192,7 @@ var OrphansCommand = class extends SmCommand {
       ["Just the ambiguous ones, JSON", "$0 orphans --kind ambiguous --json"]
     ]
   });
-  kind = Option13.String("--kind", { required: false });
+  kind = Option14.String("--kind", { required: false });
   async run() {
     let ruleFilter = null;
     if (this.kind !== void 0) {
@@ -9810,7 +10230,7 @@ var OrphansCommand = class extends SmCommand {
 };
 var OrphansReconcileCommand = class extends SmCommand {
   static paths = [["orphans", "reconcile"]];
-  static usage = Command13.Usage({
+  static usage = Command14.Usage({
     category: "Browse",
     description: "Migrate state_* FKs from an orphan path to a live node, resolving the orphan issue.",
     details: `
@@ -9826,9 +10246,9 @@ var OrphansReconcileCommand = class extends SmCommand {
       ["Reattach orphan history", "$0 orphans reconcile skills/old.md --to skills/new.md"]
     ]
   });
-  orphanPath = Option13.String({ required: true });
-  to = Option13.String("--to", { required: true });
-  dryRun = Option13.Boolean("-n,--dry-run", false);
+  orphanPath = Option14.String({ required: true });
+  to = Option14.String("--to", { required: true });
+  dryRun = Option14.Boolean("-n,--dry-run", false);
   async run() {
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(dbPath, this.context.stderr)) return ExitCode.NotFound;
@@ -9898,7 +10318,7 @@ var OrphansReconcileCommand = class extends SmCommand {
 };
 var OrphansUndoRenameCommand = class extends SmCommand {
   static paths = [["orphans", "undo-rename"]];
-  static usage = Command13.Usage({
+  static usage = Command14.Usage({
     category: "Browse",
     description: "Reverse a medium- or ambiguous-confidence auto-rename. Migrates state_* FKs back, emits a new orphan on the prior path.",
     details: `
@@ -9918,10 +10338,10 @@ var OrphansUndoRenameCommand = class extends SmCommand {
       ["Undo an ambiguous, picking a candidate", "$0 orphans undo-rename skills/new.md --from skills/old-a.md"]
     ]
   });
-  newPath = Option13.String({ required: true });
-  from = Option13.String("--from", { required: false });
-  force = Option13.Boolean("--force", false);
-  dryRun = Option13.Boolean("-n,--dry-run", false);
+  newPath = Option14.String({ required: true });
+  from = Option14.String("--from", { required: false });
+  force = Option14.Boolean("--force", false);
+  dryRun = Option14.Boolean("-n,--dry-run", false);
   async run() {
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(dbPath, this.context.stderr)) return ExitCode.NotFound;
@@ -10085,9 +10505,9 @@ var ORPHANS_COMMANDS = [
 ];
 
 // cli/commands/plugins.ts
-import { existsSync as existsSync13 } from "fs";
-import { join as join12, resolve as resolve16 } from "path";
-import { Command as Command14, Option as Option14 } from "clipanion";
+import { existsSync as existsSync14 } from "fs";
+import { join as join13, resolve as resolve17 } from "path";
+import { Command as Command15, Option as Option15 } from "clipanion";
 
 // cli/i18n/plugins.texts.ts
 var PLUGINS_TEXTS = {
@@ -10163,7 +10583,7 @@ var PLUGINS_TEXTS = {
 
 // cli/commands/plugins.ts
 function resolveSearchPaths2(opts, cwd, homedir2) {
-  if (opts.pluginDir) return [resolve16(opts.pluginDir)];
+  if (opts.pluginDir) return [resolve17(opts.pluginDir)];
   const ctx = { cwd, homedir: homedir2 };
   const project = defaultProjectPluginsDir(ctx);
   const user = defaultUserPluginsDir(ctx);
@@ -10232,12 +10652,12 @@ function builtInRows(resolveEnabled) {
 }
 var PluginsListCommand = class extends SmCommand {
   static paths = [["plugins", "list"]];
-  static usage = Command14.Usage({
+  static usage = Command15.Usage({
     category: "Plugins",
     description: "List discovered plugins and their load status.",
     details: "Scans <scope>/.skill-map/plugins and ~/.skill-map/plugins (or --plugin-dir <path>). Built-in bundles (claude, core) are listed alongside user plugins."
   });
-  pluginDir = Option14.String("--plugin-dir", { required: false });
+  pluginDir = Option15.String("--plugin-dir", { required: false });
   async run() {
     const plugins = await loadAll({ global: this.global, pluginDir: this.pluginDir });
     const resolveEnabled = await buildResolver(this.global);
@@ -10299,12 +10719,12 @@ function renderPluginRow(p) {
 }
 var PluginsShowCommand = class extends SmCommand {
   static paths = [["plugins", "show"]];
-  static usage = Command14.Usage({
+  static usage = Command15.Usage({
     category: "Plugins",
     description: "Show a single plugin's manifest + loaded extensions."
   });
-  id = Option14.String({ required: true });
-  pluginDir = Option14.String("--plugin-dir", { required: false });
+  id = Option15.String({ required: true });
+  pluginDir = Option15.String("--plugin-dir", { required: false });
   async run() {
     const plugins = await loadAll({ global: this.global, pluginDir: this.pluginDir });
     const resolveEnabled = await buildResolver(this.global);
@@ -10481,7 +10901,7 @@ function appendUnknownKindWarnings(out, extractorQualifiedId, applicableKinds, k
 }
 function expandHome(p, homedir2) {
   if (p === "~") return homedir2;
-  if (p.startsWith("~/")) return join12(homedir2, p.slice(2));
+  if (p.startsWith("~/")) return join13(homedir2, p.slice(2));
   return p;
 }
 function collectExplorationDirWarnings(plugins, homedir2) {
@@ -10490,7 +10910,7 @@ function collectExplorationDirWarnings(plugins, homedir2) {
     const dir = instance["explorationDir"];
     if (typeof dir !== "string" || dir.length === 0) return;
     const resolved = expandHome(dir, homedir2);
-    if (!existsSync13(resolved)) {
+    if (!existsSync14(resolved)) {
       out.push({
         providerQualifiedId: qualifiedExtensionId(pluginId, id),
         explorationDir: dir,
@@ -10502,12 +10922,12 @@ function collectExplorationDirWarnings(plugins, homedir2) {
 }
 var PluginsDoctorCommand = class extends SmCommand {
   static paths = [["plugins", "doctor"]];
-  static usage = Command14.Usage({
+  static usage = Command15.Usage({
     category: "Plugins",
     description: "Run the full load pass and summarise by failure mode.",
     details: "Exit code 0 when every plugin loads or is intentionally disabled; 1 when any plugin is in an error / incompat state."
   });
-  pluginDir = Option14.String("--plugin-dir", { required: false });
+  pluginDir = Option15.String("--plugin-dir", { required: false });
   // Doctor verb: counts by status + applicableKinds warnings +
   // explorationDir warnings + bad-plugins issues, each with its own
   // gated render. Branching is intrinsic to the multi-section diagnostic
@@ -10673,8 +11093,8 @@ function resolveToggleTarget(id, catalogue, verb) {
   return { key: bundle.id };
 }
 var TogglePluginsBase = class extends SmCommand {
-  all = Option14.Boolean("--all", false);
-  id = Option14.String({ required: false });
+  all = Option15.Boolean("--all", false);
+  id = Option15.String({ required: false });
   // eslint-disable-next-line complexity
   async toggle(enabled) {
     const verb = enabled ? "enable" : "disable";
@@ -10725,7 +11145,7 @@ var TogglePluginsBase = class extends SmCommand {
 };
 var PluginsEnableCommand = class extends TogglePluginsBase {
   static paths = [["plugins", "enable"]];
-  static usage = Command14.Usage({
+  static usage = Command15.Usage({
     category: "Plugins",
     description: "Enable a plugin (or --all). Persists in config_plugins.",
     details: `
@@ -10747,7 +11167,7 @@ var PluginsEnableCommand = class extends TogglePluginsBase {
 };
 var PluginsDisableCommand = class extends TogglePluginsBase {
   static paths = [["plugins", "disable"]];
-  static usage = Command14.Usage({
+  static usage = Command15.Usage({
     category: "Plugins",
     description: "Disable a plugin (or --all). Persists in config_plugins; does not delete files.",
     details: `
@@ -10783,8 +11203,8 @@ var PLUGIN_COMMANDS = [
 
 // cli/commands/refresh.ts
 import { readFile as readFile3 } from "fs/promises";
-import { resolve as resolve18 } from "path";
-import { Command as Command15, Option as Option15 } from "clipanion";
+import { resolve as resolve19 } from "path";
+import { Command as Command16, Option as Option16 } from "clipanion";
 
 // cli/i18n/refresh.texts.ts
 var REFRESH_TEXTS = {
@@ -10813,12 +11233,12 @@ var REFRESH_TEXTS = {
 };
 
 // cli/util/path-guard.ts
-import { isAbsolute as isAbsolute3, resolve as resolve17, sep as sep3 } from "path";
+import { isAbsolute as isAbsolute3, resolve as resolve18, sep as sep3 } from "path";
 function assertContained2(cwd, rel) {
   if (isAbsolute3(rel)) {
     throw new Error(`node path is absolute, refusing to read: ${rel}`);
   }
-  const abs = resolve17(cwd, rel);
+  const abs = resolve18(cwd, rel);
   if (abs !== cwd && !abs.startsWith(cwd + sep3)) {
     throw new Error(`node path escapes repo root: ${rel}`);
   }
@@ -10827,7 +11247,7 @@ function assertContained2(cwd, rel) {
 // cli/commands/refresh.ts
 var RefreshCommand = class extends SmCommand {
   static paths = [["refresh"]];
-  static usage = Command15.Usage({
+  static usage = Command16.Usage({
     category: "Scan",
     description: "Refresh enrichment rows: granular (single node) or batch (every stale row).",
     details: `
@@ -10852,11 +11272,11 @@ var RefreshCommand = class extends SmCommand {
       ["Refresh every node with stale enrichments", "$0 refresh --stale"]
     ]
   });
-  nodePath = Option15.String({ name: "node", required: false });
-  stale = Option15.Boolean("--stale", false, {
+  nodePath = Option16.String({ name: "node", required: false });
+  stale = Option16.Boolean("--stale", false, {
     description: "Refresh every node whose probabilistic enrichment row is flagged stale=1."
   });
-  noPlugins = Option15.Boolean("--no-plugins", false, {
+  noPlugins = Option16.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery; use only the built-in extractor set."
   });
   // The remaining cyclomatic count comes from CLI ergonomics that don't
@@ -10992,7 +11412,7 @@ var RefreshCommand = class extends SmCommand {
       let body;
       try {
         assertContained2(cwd, node.path);
-        const raw = await readFile3(resolve18(cwd, node.path), "utf8");
+        const raw = await readFile3(resolve19(cwd, node.path), "utf8");
         body = stripFrontmatterFence(raw);
       } catch (err) {
         this.context.stderr.write(
@@ -11041,7 +11461,7 @@ function stripFrontmatterFence(text) {
 var REFRESH_COMMANDS = [RefreshCommand];
 
 // cli/commands/scan.ts
-import { Command as Command17, Option as Option17 } from "clipanion";
+import { Command as Command18, Option as Option18 } from "clipanion";
 
 // cli/i18n/scan.texts.ts
 var SCAN_TEXTS = {
@@ -11233,7 +11653,7 @@ async function runEphemeralPath(opts, dbPath, strict, loadPrior, runScanWith) {
 }
 
 // cli/commands/watch.ts
-import { Command as Command16, Option as Option16 } from "clipanion";
+import { Command as Command17, Option as Option17 } from "clipanion";
 
 // cli/i18n/watch.texts.ts
 var WATCH_TEXTS = {
@@ -11412,7 +11832,7 @@ async function runWatchLoop(opts) {
 }
 var WatchCommand = class extends SmCommand {
   static paths = [["watch"]];
-  static usage = Command16.Usage({
+  static usage = Command17.Usage({
     category: "Scan",
     description: "Watch roots and run an incremental scan after each debounced batch of filesystem events.",
     details: `
@@ -11436,17 +11856,17 @@ var WatchCommand = class extends SmCommand {
       ["Stream ScanResult per batch as ndjson", "$0 watch --json"]
     ]
   });
-  roots = Option16.Rest({ name: "roots" });
-  noTokens = Option16.Boolean("--no-tokens", false, {
+  roots = Option17.Rest({ name: "roots" });
+  noTokens = Option17.Boolean("--no-tokens", false, {
     description: "Skip per-node token counts (cl100k_base BPE)."
   });
-  strict = Option16.Boolean("--strict", false, {
+  strict = Option17.Boolean("--strict", false, {
     description: "Promote frontmatter-validation findings from warn to error inside each batch. Does not change the watcher exit code."
   });
-  noPlugins = Option16.Boolean("--no-plugins", false, {
+  noPlugins = Option17.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery for the watcher session."
   });
-  maxConsecutiveFailures = Option16.String("--max-consecutive-failures", {
+  maxConsecutiveFailures = Option17.String("--max-consecutive-failures", {
     required: false,
     description: "Shut down with exit 2 after N consecutive batch failures (default 5; 0 disables the breaker)."
   });
@@ -11484,7 +11904,7 @@ function parseBreakerLimit(raw, stderr) {
 // cli/commands/scan.ts
 var ScanCommand = class extends SmCommand {
   static paths = [["scan"]];
-  static usage = Command17.Usage({
+  static usage = Command18.Usage({
     category: "Scan",
     description: "Scan roots for markdown nodes, run extractors and rules.",
     details: `
@@ -11513,29 +11933,29 @@ var ScanCommand = class extends SmCommand {
       ["What would the next incremental scan persist?", "$0 scan --changed -n --json"]
     ]
   });
-  roots = Option17.Rest({ name: "roots" });
-  noBuiltIns = Option17.Boolean("--no-built-ins", false, {
+  roots = Option18.Rest({ name: "roots" });
+  noBuiltIns = Option18.Boolean("--no-built-ins", false, {
     description: "Skip the built-in extension set. Yields a zero-filled ScanResult (kernel-empty-boot parity); skips DB persistence."
   });
-  noPlugins = Option17.Boolean("--no-plugins", false, {
+  noPlugins = Option18.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery. Only the built-in set runs. Combine with --no-built-ins for a fully empty pipeline."
   });
-  noTokens = Option17.Boolean("--no-tokens", false, {
+  noTokens = Option18.Boolean("--no-tokens", false, {
     description: "Skip per-node token counts (cl100k_base BPE). Leaves node.tokens undefined; spec-valid since the field is optional."
   });
-  dryRun = Option17.Boolean("-n,--dry-run", false, {
+  dryRun = Option18.Boolean("-n,--dry-run", false, {
     description: "Run the scan in memory and skip every DB write. Combined with --changed, still opens the DB read-side to load the prior snapshot."
   });
-  changed = Option17.Boolean("--changed", false, {
+  changed = Option18.Boolean("--changed", false, {
     description: "Incremental scan: reuse unchanged nodes from the persisted prior snapshot. Degrades to a full scan if no prior snapshot exists."
   });
-  allowEmpty = Option17.Boolean("--allow-empty", false, {
+  allowEmpty = Option18.Boolean("--allow-empty", false, {
     description: "Allow a zero-result scan to wipe an already-populated DB (replace-all replace by zero rows). Off by default to avoid the typo-trap where an invalid root silently clears your data."
   });
-  strict = Option17.Boolean("--strict", false, {
+  strict = Option18.Boolean("--strict", false, {
     description: "Promote frontmatter-validation findings from warn to error (exit code 1 on any violation). Overrides scan.strict from config when both are set."
   });
-  watch = Option17.Boolean("--watch", false, {
+  watch = Option18.Boolean("--watch", false, {
     description: "Long-running mode: watch the roots and trigger an incremental scan after each debounced batch of filesystem events. Alias of `sm watch`."
   });
   async run() {
@@ -11633,11 +12053,11 @@ var ScanCommand = class extends SmCommand {
 };
 
 // cli/commands/scan-compare.ts
-import { existsSync as existsSync14, readFileSync as readFileSync11 } from "fs";
-import { Command as Command18, Option as Option18 } from "clipanion";
+import { existsSync as existsSync15, readFileSync as readFileSync12 } from "fs";
+import { Command as Command19, Option as Option19 } from "clipanion";
 var ScanCompareCommand = class extends SmCommand {
   static paths = [["scan", "compare-with"]];
-  static usage = Command18.Usage({
+  static usage = Command19.Usage({
     category: "Scan",
     description: "Run a fresh scan in memory and emit a delta against the saved ScanResult dump at <dump>. Read-only.",
     details: `
@@ -11665,15 +12085,15 @@ var ScanCompareCommand = class extends SmCommand {
       ["JSON output for tooling", "$0 scan compare-with baseline.json --json"]
     ]
   });
-  dump = Option18.String({ required: true });
-  roots = Option18.Rest({ name: "roots" });
-  noTokens = Option18.Boolean("--no-tokens", false, {
+  dump = Option19.String({ required: true });
+  roots = Option19.Rest({ name: "roots" });
+  noTokens = Option19.Boolean("--no-tokens", false, {
     description: "Skip per-node token counts during the fresh scan."
   });
-  strict = Option18.Boolean("--strict", false, {
+  strict = Option19.Boolean("--strict", false, {
     description: "Promote layered-config warnings and frontmatter-validation findings from warn to error."
   });
-  noPlugins = Option18.Boolean("--no-plugins", false, {
+  noPlugins = Option19.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery."
   });
   // Cyclomatic count comes from CLI ergonomics: 3 distinct try/catch
@@ -11744,12 +12164,12 @@ var ScanCompareCommand = class extends SmCommand {
   }
 };
 function loadAndValidateDump(path) {
-  if (!existsSync14(path)) {
+  if (!existsSync15(path)) {
     throw new Error(tx(SCAN_TEXTS.compareDumpNotFound, { path }));
   }
   let raw;
   try {
-    raw = readFileSync11(path, "utf8");
+    raw = readFileSync12(path, "utf8");
   } catch (err) {
     const message = formatErrorMessage(err);
     throw new Error(tx(SCAN_TEXTS.compareDumpReadFailed, { path, message }), { cause: err });
@@ -11858,8 +12278,8 @@ function renderDeltaIssues(issues) {
 
 // cli/commands/serve.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync18 } from "fs";
-import { Command as Command19, Option as Option19 } from "clipanion";
+import { existsSync as existsSync19 } from "fs";
+import { Command as Command20, Option as Option20 } from "clipanion";
 
 // server/index.ts
 import { serve } from "@hono/node-server";
@@ -12040,7 +12460,7 @@ function contentTypeFor(format) {
 }
 
 // server/health.ts
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 var FALLBACK_SCHEMA_VERSION = "1";
 function buildHealth(deps) {
   return {
@@ -12049,7 +12469,7 @@ function buildHealth(deps) {
     specVersion: deps.specVersion,
     implVersion: VERSION,
     scope: deps.scope,
-    db: existsSync15(deps.dbPath) ? "present" : "missing"
+    db: existsSync16(deps.dbPath) ? "present" : "missing"
   };
 }
 async function resolveSpecVersion2() {
@@ -12489,9 +12909,9 @@ function emptyScanResult() {
 }
 
 // server/static.ts
-import { existsSync as existsSync16 } from "fs";
+import { existsSync as existsSync17 } from "fs";
 import { readFile as readFile5 } from "fs/promises";
-import { extname, join as join13 } from "path";
+import { extname, join as join14 } from "path";
 import { serveStatic } from "@hono/node-server/serve-static";
 var INDEX_HTML = "index.html";
 var PLACEHOLDER_HTML = `<!doctype html>
@@ -12509,7 +12929,7 @@ var PLACEHOLDER_HTML = `<!doctype html>
   </head>
   <body>
     <h1>skill-map server is running</h1>
-    <p>The UI bundle was not found. Run <code>npm run build --workspace=ui</code> from the repo root, or pass <code>--ui-dist &lt;path&gt;</code>, then restart <code>sm serve</code>.</p>
+    <p>The UI bundle was not found. If you installed <code>@skill-map/cli</code> from npm, this is a packaging bug \u2014 please report it. If you're developing in the monorepo, run <code>npm run build --workspace=ui</code> from the repo root and restart <code>sm serve</code> (or pass <code>--ui-dist &lt;path&gt;</code> to point at a custom build).</p>
     <p>The REST API is available at <code>/api/health</code>.</p>
   </body>
 </html>
@@ -12522,8 +12942,8 @@ function createSpaFallback(uiDist) {
   return async (c, _next) => {
     if (c.req.method !== "GET" && c.req.method !== "HEAD") return c.notFound();
     if (uiDist === null) return htmlResponse(c, PLACEHOLDER_HTML);
-    const indexPath = join13(uiDist, INDEX_HTML);
-    if (!existsSync16(indexPath)) return htmlResponse(c, PLACEHOLDER_HTML);
+    const indexPath = join14(uiDist, INDEX_HTML);
+    if (!existsSync17(indexPath)) return htmlResponse(c, PLACEHOLDER_HTML);
     return fileResponse(c, indexPath);
   };
 }
@@ -13113,33 +13533,62 @@ function validateWatcherDebounce(value) {
 }
 
 // server/paths.ts
-import { existsSync as existsSync17, statSync as statSync5 } from "fs";
-import { dirname as dirname9, isAbsolute as isAbsolute5, join as join14, resolve as resolve19 } from "path";
-var DEFAULT_UI_REL = join14("ui", "dist", "browser");
+import { existsSync as existsSync18, statSync as statSync5 } from "fs";
+import { dirname as dirname10, isAbsolute as isAbsolute5, join as join15, resolve as resolve20 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
+var DEFAULT_UI_REL = join15("ui", "dist", "ui", "browser");
+var PACKAGE_UI_REL = "ui";
 var INDEX_HTML2 = "index.html";
 function resolveDefaultUiDist(ctx) {
-  let current = resolve19(ctx.cwd);
-  for (let i = 0; i < 64; i++) {
-    const candidate = join14(current, DEFAULT_UI_REL);
-    if (isUiBundleDir(candidate)) return candidate;
-    const parent = dirname9(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-  return null;
+  const bundled = resolvePackageBundledUi();
+  if (bundled !== null) return bundled;
+  return walkUpForUi(ctx.cwd);
 }
 function resolveExplicitUiDist(ctx, raw) {
-  return isAbsolute5(raw) ? raw : resolve19(ctx.cwd, raw);
+  return isAbsolute5(raw) ? raw : resolve20(ctx.cwd, raw);
 }
 function isUiBundleDir(path) {
-  if (!existsSync17(path)) return false;
+  if (!existsSync18(path)) return false;
   try {
     if (!statSync5(path).isDirectory()) return false;
-    return existsSync17(join14(path, INDEX_HTML2));
+    return existsSync18(join15(path, INDEX_HTML2));
   } catch {
     return false;
   }
 }
+function resolvePackageBundledUi() {
+  let here;
+  try {
+    here = dirname10(fileURLToPath6(import.meta.url));
+  } catch {
+    return null;
+  }
+  return resolvePackageBundledUiFrom(here);
+}
+function resolvePackageBundledUiFrom(here) {
+  let current = here;
+  for (let i = 0; i < 8; i++) {
+    const candidate = join15(current, PACKAGE_UI_REL);
+    if (isUiBundleDir(candidate)) return candidate;
+    const distHere = join15(current, "dist", PACKAGE_UI_REL);
+    if (isUiBundleDir(distHere)) return distHere;
+    const parent = dirname10(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+function walkUpForUi(startDir) {
+  let current = resolve20(startDir);
+  for (let i = 0; i < 64; i++) {
+    const candidate = join15(current, DEFAULT_UI_REL);
+    if (isUiBundleDir(candidate)) return candidate;
+    const parent = dirname10(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
 
 // server/index.ts
 async function createServer(options, extra = {}) {
@@ -13294,7 +13743,7 @@ var SERVE_TEXTS = {
 // cli/commands/serve.ts
 var ServeCommand = class extends SmCommand {
   static paths = [["serve"]];
-  static usage = Command19.Usage({
+  static usage = Command20.Usage({
     category: "Setup",
     description: "Start the Hono BFF (single-port: REST + WebSocket + SPA bundle).",
     details: `
@@ -13319,22 +13768,22 @@ var ServeCommand = class extends SmCommand {
       ["Point at a pre-built UI bundle", "$0 serve --ui-dist ./ui/dist/browser"]
     ]
   });
-  port = Option19.String("--port", {
+  port = Option20.String("--port", {
     required: false,
     description: "Listening port (default 4242). 0 = OS-assigned."
   });
-  host = Option19.String("--host", {
+  host = Option20.String("--host", {
     required: false,
     description: "Listening host (default 127.0.0.1). Loopback-only enforced when --dev-cors is set."
   });
-  scope = Option19.String("--scope", {
+  scope = Option20.String("--scope", {
     required: false,
     description: "project | global. Alias for -g/--global. Default: project."
   });
-  noBuiltIns = Option19.Boolean("--no-built-ins", false, {
+  noBuiltIns = Option20.Boolean("--no-built-ins", false, {
     description: "Skip built-in plugin registration (parity with sm scan --no-built-ins)."
   });
-  noPlugins = Option19.Boolean("--no-plugins", false, {
+  noPlugins = Option20.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery."
   });
   // `Option.Boolean('--open', true)` — Clipanion's parser auto-derives
@@ -13344,24 +13793,24 @@ var ServeCommand = class extends SmCommand {
   // two registrations for the same flag and rejects the invocation
   // with "Ambiguous Syntax Error". Same convention shipped by every
   // other `--no-...` flag in the CLI tree.
-  open = Option19.Boolean("--open", true, {
+  open = Option20.Boolean("--open", true, {
     description: "Auto-open the SPA in the user's default browser after listen. --no-open opts out."
   });
-  devCors = Option19.Boolean("--dev-cors", false, {
+  devCors = Option20.Boolean("--dev-cors", false, {
     description: "Enable permissive CORS for the Angular dev-server proxy workflow."
   });
   // `--ui-dist` is intentionally undocumented in the Usage block above
   // (the demo build pipeline + tests rely on it; everyday users never
   // need it). Clipanion still exposes it on the parser; the Usage
   // omission is the "hidden" contract per the 14.1 brief.
-  uiDist = Option19.String("--ui-dist", { required: false, hidden: true });
-  noWatcher = Option19.Boolean("--no-watcher", false, {
+  uiDist = Option20.String("--ui-dist", { required: false, hidden: true });
+  noWatcher = Option20.Boolean("--no-watcher", false, {
     description: "Disable the chokidar-fed scan-and-broadcast loop. Use only for CI / read-only deployments."
   });
   // `--watcher-debounce-ms` is undocumented sugar for advanced users
   // who want to tighten / relax the watcher's batching window without
   // editing settings.json. Hidden flag — the Usage block omits it.
-  watcherDebounceMs = Option19.String("--watcher-debounce-ms", { required: false, hidden: true });
+  watcherDebounceMs = Option20.String("--watcher-debounce-ms", { required: false, hidden: true });
   // Long-running daemon — `done in <…>` after a graceful shutdown is
   // noise. Mirrors `sm watch`'s opt-out.
   emitElapsed = false;
@@ -13389,7 +13838,7 @@ var ServeCommand = class extends SmCommand {
       return ExitCode.Error;
     }
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...runtimeCtx });
-    if (this.db !== void 0 && !existsSync18(dbPath)) {
+    if (this.db !== void 0 && !existsSync19(dbPath)) {
       this.context.stderr.write(
         tx(SERVE_TEXTS.dbNotFound, { path: sanitizeForTerminal(dbPath) })
       );
@@ -13570,7 +14019,7 @@ function tryOpenBrowser(url, stderr) {
 }
 
 // cli/commands/show.ts
-import { Command as Command20, Option as Option20 } from "clipanion";
+import { Command as Command21, Option as Option21 } from "clipanion";
 
 // cli/i18n/show.texts.ts
 var SHOW_TEXTS = {
@@ -13610,7 +14059,7 @@ var SHOW_TEXTS = {
 // cli/commands/show.ts
 var ShowCommand = class extends SmCommand {
   static paths = [["show"]];
-  static usage = Command20.Usage({
+  static usage = Command21.Usage({
     category: "Browse",
     description: "Node detail: weight, frontmatter, links, issues.",
     details: `
@@ -13626,7 +14075,7 @@ var ShowCommand = class extends SmCommand {
       ["Machine-readable detail", "$0 show .claude/agents/architect.md --json"]
     ]
   });
-  nodePath = Option20.String({ required: true });
+  nodePath = Option21.String({ required: true });
   async run() {
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(dbPath, this.context.stderr)) return ExitCode.NotFound;
@@ -13775,7 +14224,7 @@ function rankConfidenceForGrouping(c) {
 }
 
 // cli/commands/stubs.ts
-import { Command as Command21, Option as Option21 } from "clipanion";
+import { Command as Command22, Option as Option22 } from "clipanion";
 
 // cli/i18n/stubs.texts.ts
 var STUBS_TEXTS = {
@@ -13790,9 +14239,9 @@ function notImplemented(cmd, verb) {
   cmd.context.stderr.write(tx(STUBS_TEXTS.notImplemented, { verb }));
   return ExitCode.Error;
 }
-var DoctorCommand = class extends Command21 {
+var DoctorCommand = class extends Command22 {
   static paths = [["doctor"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Setup",
     description: planned("Diagnostic report: DB integrity, pending migrations, orphan rows, plugin status, runner availability.")
   });
@@ -13800,23 +14249,23 @@ var DoctorCommand = class extends Command21 {
     return notImplemented(this, "doctor");
   }
 };
-var FindingsCommand = class extends Command21 {
+var FindingsCommand = class extends Command22 {
   static paths = [["findings"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Browse",
     description: planned("Probabilistic findings: injection, stale summaries, low confidence.")
   });
-  kind = Option21.String("--kind", { required: false });
-  since = Option21.String("--since", { required: false });
-  threshold = Option21.String("--threshold", { required: false });
-  json = Option21.Boolean("--json", false);
+  kind = Option22.String("--kind", { required: false });
+  since = Option22.String("--since", { required: false });
+  threshold = Option22.String("--threshold", { required: false });
+  json = Option22.Boolean("--json", false);
   async execute() {
     return notImplemented(this, "findings");
   }
 };
-var ActionsListCommand = class extends Command21 {
+var ActionsListCommand = class extends Command22 {
   static paths = [["actions", "list"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Registered action types (manifest view).")
   });
@@ -13824,121 +14273,121 @@ var ActionsListCommand = class extends Command21 {
     return notImplemented(this, "actions list");
   }
 };
-var ActionsShowCommand = class extends Command21 {
+var ActionsShowCommand = class extends Command22 {
   static paths = [["actions", "show"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Full action manifest, including preconditions and expected duration.")
   });
-  id = Option21.String({ required: true });
+  id = Option22.String({ required: true });
   async execute() {
     return notImplemented(this, "actions show");
   }
 };
-var JobSubmitCommand = class extends Command21 {
+var JobSubmitCommand = class extends Command22 {
   static paths = [["job", "submit"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Enqueue a single job or fan out to every matching node (--all).")
   });
-  action = Option21.String({ required: true });
-  node = Option21.String("-n", { required: false });
-  all = Option21.Boolean("--all", false);
-  run = Option21.Boolean("--run", false);
-  force = Option21.Boolean("--force", false);
-  ttl = Option21.String("--ttl", { required: false });
-  priority = Option21.String("--priority", { required: false });
+  action = Option22.String({ required: true });
+  node = Option22.String("-n", { required: false });
+  all = Option22.Boolean("--all", false);
+  run = Option22.Boolean("--run", false);
+  force = Option22.Boolean("--force", false);
+  ttl = Option22.String("--ttl", { required: false });
+  priority = Option22.String("--priority", { required: false });
   async execute() {
     return notImplemented(this, "job submit");
   }
 };
-var JobListCommand = class extends Command21 {
+var JobListCommand = class extends Command22 {
   static paths = [["job", "list"]];
-  static usage = Command21.Usage({ category: "Jobs", description: planned("List jobs.") });
-  status = Option21.String("--status", { required: false });
-  action = Option21.String("--action", { required: false });
-  node = Option21.String("--node", { required: false });
+  static usage = Command22.Usage({ category: "Jobs", description: planned("List jobs.") });
+  status = Option22.String("--status", { required: false });
+  action = Option22.String("--action", { required: false });
+  node = Option22.String("--node", { required: false });
   async execute() {
     return notImplemented(this, "job list");
   }
 };
-var JobShowCommand = class extends Command21 {
+var JobShowCommand = class extends Command22 {
   static paths = [["job", "show"]];
-  static usage = Command21.Usage({ category: "Jobs", description: planned("Job detail: state, claim time, TTL, runner, content hash.") });
-  id = Option21.String({ required: true });
+  static usage = Command22.Usage({ category: "Jobs", description: planned("Job detail: state, claim time, TTL, runner, content hash.") });
+  id = Option22.String({ required: true });
   async execute() {
     return notImplemented(this, "job show");
   }
 };
-var JobPreviewCommand = class extends Command21 {
+var JobPreviewCommand = class extends Command22 {
   static paths = [["job", "preview"]];
-  static usage = Command21.Usage({ category: "Jobs", description: planned("Render the job MD file without executing.") });
-  id = Option21.String({ required: true });
+  static usage = Command22.Usage({ category: "Jobs", description: planned("Render the job MD file without executing.") });
+  id = Option22.String({ required: true });
   async execute() {
     return notImplemented(this, "job preview");
   }
 };
-var JobClaimCommand = class extends Command21 {
+var JobClaimCommand = class extends Command22 {
   static paths = [["job", "claim"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Atomic primitive: return next queued job id, mark it running.")
   });
-  filter = Option21.String("--filter", { required: false });
+  filter = Option22.String("--filter", { required: false });
   async execute() {
     return notImplemented(this, "job claim");
   }
 };
-var JobRunCommand = class extends Command21 {
+var JobRunCommand = class extends Command22 {
   static paths = [["job", "run"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Full CLI-runner loop: claim + spawn + record.")
   });
-  all = Option21.Boolean("--all", false);
-  max = Option21.String("--max", { required: false });
+  all = Option22.Boolean("--all", false);
+  max = Option22.String("--max", { required: false });
   async execute() {
     return notImplemented(this, "job run");
   }
 };
-var JobStatusCommand = class extends Command21 {
+var JobStatusCommand = class extends Command22 {
   static paths = [["job", "status"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Counts (per status) or single-job status.")
   });
-  id = Option21.String({ required: false });
+  id = Option22.String({ required: false });
   async execute() {
     return notImplemented(this, "job status");
   }
 };
-var JobCancelCommand = class extends Command21 {
+var JobCancelCommand = class extends Command22 {
   static paths = [["job", "cancel"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Force a running job to failed with reason user-cancelled.")
   });
-  id = Option21.String({ required: false });
-  all = Option21.Boolean("--all", false);
+  id = Option22.String({ required: false });
+  all = Option22.Boolean("--all", false);
   async execute() {
     return notImplemented(this, "job cancel");
   }
 };
-var RecordCommand = class extends Command21 {
+var RecordCommand = class extends Command22 {
   static paths = [["record"]];
-  static usage = Command21.Usage({
+  static usage = Command22.Usage({
     category: "Jobs",
     description: planned("Close a running job with success or failure. Nonce is the sole credential.")
   });
-  id = Option21.String("--id", { required: true });
-  nonce = Option21.String("--nonce", { required: true });
-  status = Option21.String("--status", { required: true });
-  report = Option21.String("--report", { required: false });
-  tokensIn = Option21.String("--tokens-in", { required: false });
-  tokensOut = Option21.String("--tokens-out", { required: false });
-  durationMs = Option21.String("--duration-ms", { required: false });
-  model = Option21.String("--model", { required: false });
-  error = Option21.String("--error", { required: false });
+  id = Option22.String("--id", { required: true });
+  nonce = Option22.String("--nonce", { required: true });
+  status = Option22.String("--status", { required: true });
+  report = Option22.String("--report", { required: false });
+  tokensIn = Option22.String("--tokens-in", { required: false });
+  tokensOut = Option22.String("--tokens-out", { required: false });
+  durationMs = Option22.String("--duration-ms", { required: false });
+  model = Option22.String("--model", { required: false });
+  error = Option22.String("--error", { required: false });
   async execute() {
     return notImplemented(this, "record");
   }
@@ -13960,7 +14409,7 @@ var STUB_COMMANDS = [
 ];
 
 // cli/commands/version.ts
-import { Command as Command22 } from "clipanion";
+import { Command as Command23 } from "clipanion";
 
 // cli/i18n/version.texts.ts
 var VERSION_TEXTS = {
@@ -13972,7 +14421,7 @@ var VERSION_TEXTS = {
 // cli/commands/version.ts
 var VersionCommand = class extends SmCommand {
   static paths = [["version"]];
-  static usage = Command22.Usage({
+  static usage = Command23.Usage({
     category: "Introspection",
     description: "Print the CLI / kernel / spec / runtime / db-schema version matrix."
   });
@@ -14042,6 +14491,7 @@ cli.register(Builtins.VersionCommand);
 cli.register(RootHelpCommand);
 cli.register(HelpCommand);
 cli.register(InitCommand);
+cli.register(GuideCommand);
 cli.register(ScanCommand);
 cli.register(ScanCompareCommand);
 cli.register(ServeCommand);
@@ -14072,6 +14522,25 @@ var logLevel = resolveLogLevel({
 configureLogger(new Logger({ level: logLevel, stream: process.stderr }));
 var bareArgs = args.length === 0 ? resolveBareDefault() : null;
 var routedArgs = routeHelpArgs(bareArgs ?? args, cli);
+try {
+  cli.process(routedArgs, {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr
+  });
+} catch (err) {
+  if (isClipanionParseError(err)) {
+    process.stderr.write(
+      formatParseError({
+        args: routedArgs,
+        verbPaths: registeredVerbPaths(cli),
+        error: err
+      })
+    );
+    process.exit(ExitCode.Error);
+  }
+  throw err;
+}
 var exitCode = await cli.run(routedArgs, {
   stdin: process.stdin,
   stdout: process.stdout,
@@ -14080,7 +14549,7 @@ var exitCode = await cli.run(routedArgs, {
 process.exit(exitCode);
 function resolveBareDefault() {
   const ctx = defaultRuntimeContext();
-  if (existsSync19(defaultProjectDbPath(ctx))) {
+  if (existsSync20(defaultProjectDbPath(ctx))) {
     return ["serve"];
   }
   process.stderr.write(tx(ENTRY_TEXTS.bareNoProject, { cwd: ctx.cwd }));