@skill-map/cli 0.13.0 → 0.14.1

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
@@ -58,6 +58,7 @@ var ENTRY_TEXTS = {
   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.",
@@ -275,6 +276,46 @@ 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;
@@ -297,10 +338,7 @@ function formatParseError(params) {
     return renderError(error.message.trim(), null);
   }
   const verbPrefix = matchedVerbPrefix(args2, verbPaths);
-  if (verbPrefix) {
-    const headline = tx(ENTRY_TEXTS.parseErrorVerbUsage, { verb: verbPrefix, message: error.message.trim() });
-    return renderError(headline, tx(ENTRY_TEXTS.parseErrorVerbHelpHint, { verb: verbPrefix }));
-  }
+  if (verbPrefix) return formatVerbScopedError(verbPrefix, error.message);
   const subcommands = subcommandsUnder(firstToken, verbPaths);
   if (subcommands.length > 0) {
     const headline = tx(ENTRY_TEXTS.parseErrorIncompleteCommand, { name: firstToken });
@@ -313,6 +351,22 @@ function formatParseError(params) {
   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);
@@ -342,6 +396,16 @@ 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;
@@ -349,34 +413,6 @@ function suggestFlag(token) {
   const longForm = "-" + token;
   return tx(ENTRY_TEXTS.parseErrorFlagSuggestion, { suggestion: longForm });
 }
-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 closestVerbs(typed, verbPaths) {
   const target = typed.toLowerCase();
   const distanceCap = target.length <= 4 ? 2 : 3;
@@ -983,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",
@@ -1126,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 = {
   /**
@@ -1152,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",
@@ -1259,7 +1366,7 @@ function analyzeTriggerBucket(normalized, claims) {
     part: parts[0]
   });
   return {
-    ruleId: ID5,
+    ruleId: ID6,
     severity: "error",
     nodeIds,
     message,
@@ -1278,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",
@@ -1294,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, {
@@ -1342,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",
@@ -1359,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, {
@@ -1380,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",
@@ -1431,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, {
@@ -1477,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",
@@ -1743,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",
@@ -1768,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, {
@@ -1782,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, {
@@ -1843,6 +1950,7 @@ var builtInBundles = [
     granularity: "extension",
     extensions: [
       externalUrlCounterExtractor,
+      markdownLinkExtractor,
       triggerCollisionRule,
       brokenRefRule,
       supersededRule,
@@ -2850,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() {
@@ -4097,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;
@@ -4104,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 : [];
 }
@@ -5114,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",
@@ -5143,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);
@@ -5244,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];
@@ -5321,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) {
@@ -6195,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",
@@ -6488,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)) {
@@ -6507,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({
@@ -6906,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();
@@ -6942,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 }));
@@ -7169,16 +7353,109 @@ 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 "ejecut\xE1 @sm-guide.md" 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 load the file as a skill by
+      typing "ejecut\xE1 @sm-guide.md". 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.13.0",
+  version: "0.14.1",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -7237,7 +7514,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",
@@ -7354,9 +7631,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: `
@@ -7370,8 +7647,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) {
@@ -7493,8 +7770,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";
@@ -7689,7 +7966,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();
@@ -7745,13 +8022,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";
@@ -7886,7 +8163,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 }));
     }
   }
@@ -8662,10 +8939,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);
@@ -8911,7 +9188,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: `
@@ -8935,16 +9212,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
@@ -8955,7 +9232,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);
@@ -8979,17 +9256,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,
@@ -9028,7 +9305,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) {
@@ -9048,13 +9325,13 @@ async function writeDryRunGitignorePlan(stdout, scopeRoot) {
     );
   }
 }
-async function runFirstScan(scopeRoot, homedir2, dbPath, strict, stdout, stderr) {
+async function runFirstScan(scopeRoot, homedir3, dbPath, strict, stdout, stderr) {
   stdout.write(INIT_TEXTS.runningFirstScan);
   const kernel = createKernel();
   for (const manifest of listBuiltIns()) kernel.registry.register(manifest);
   let cfg;
   try {
-    cfg = loadConfig({ scope: "project", cwd: scopeRoot, homedir: homedir2, strict }).effective;
+    cfg = loadConfig({ scope: "project", cwd: scopeRoot, homedir: homedir3, strict }).effective;
   } catch (err) {
     const message = formatErrorMessage(err);
     stderr.write(tx(INIT_TEXTS.configLoadFailure, { message }));
@@ -9103,7 +9380,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("#"))
@@ -9111,7 +9388,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");
@@ -9128,12 +9405,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 = {
@@ -9222,7 +9499,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: `
@@ -9242,12 +9519,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
@@ -9295,7 +9572,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: `
@@ -9313,10 +9590,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`.
@@ -9497,11 +9774,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 {
@@ -9516,7 +9793,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();
@@ -9545,7 +9822,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: `
@@ -9572,10 +9849,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() {
@@ -9692,7 +9969,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 = {
@@ -9720,7 +9997,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: `
@@ -9741,10 +10018,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";
@@ -9846,7 +10123,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 = {
@@ -9901,7 +10178,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: `
@@ -9916,7 +10193,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) {
@@ -9954,7 +10231,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: `
@@ -9970,9 +10247,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;
@@ -10042,7 +10319,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: `
@@ -10062,10 +10339,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;
@@ -10229,9 +10506,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 = {
@@ -10306,9 +10583,9 @@ var PLUGINS_TEXTS = {
 };
 
 // cli/commands/plugins.ts
-function resolveSearchPaths2(opts, cwd, homedir2) {
-  if (opts.pluginDir) return [resolve16(opts.pluginDir)];
-  const ctx = { cwd, homedir: homedir2 };
+function resolveSearchPaths2(opts, cwd, homedir3) {
+  if (opts.pluginDir) return [resolve17(opts.pluginDir)];
+  const ctx = { cwd, homedir: homedir3 };
   const project = defaultProjectPluginsDir(ctx);
   const user = defaultUserPluginsDir(ctx);
   return opts.global ? [user] : [project, user];
@@ -10376,12 +10653,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);
@@ -10443,12 +10720,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);
@@ -10623,18 +10900,18 @@ function appendUnknownKindWarnings(out, extractorQualifiedId, applicableKinds, k
     if (!knownKinds.has(k)) out.push({ extractorQualifiedId, unknownKind: k });
   }
 }
-function expandHome(p, homedir2) {
-  if (p === "~") return homedir2;
-  if (p.startsWith("~/")) return join12(homedir2, p.slice(2));
+function expandHome(p, homedir3) {
+  if (p === "~") return homedir3;
+  if (p.startsWith("~/")) return join13(homedir3, p.slice(2));
   return p;
 }
-function collectExplorationDirWarnings(plugins, homedir2) {
+function collectExplorationDirWarnings(plugins, homedir3) {
   const out = [];
   forEachProviderInstance(plugins, ({ id, pluginId, instance }) => {
     const dir = instance["explorationDir"];
     if (typeof dir !== "string" || dir.length === 0) return;
-    const resolved = expandHome(dir, homedir2);
-    if (!existsSync13(resolved)) {
+    const resolved = expandHome(dir, homedir3);
+    if (!existsSync14(resolved)) {
       out.push({
         providerQualifiedId: qualifiedExtensionId(pluginId, id),
         explorationDir: dir,
@@ -10646,12 +10923,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
@@ -10817,8 +11094,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";
@@ -10869,7 +11146,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: `
@@ -10891,7 +11168,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: `
@@ -10927,8 +11204,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 = {
@@ -10957,12 +11234,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}`);
   }
@@ -10971,7 +11248,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: `
@@ -10996,11 +11273,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
@@ -11136,7 +11413,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(
@@ -11185,7 +11462,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 = {
@@ -11377,7 +11654,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 = {
@@ -11556,7 +11833,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: `
@@ -11580,17 +11857,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)."
   });
@@ -11628,7 +11905,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: `
@@ -11657,29 +11934,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() {
@@ -11777,11 +12054,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: `
@@ -11809,15 +12086,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
@@ -11888,12 +12165,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 });
@@ -12002,8 +12279,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";
@@ -12184,7 +12461,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 {
@@ -12193,7 +12470,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() {
@@ -12633,9 +12910,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>
@@ -12666,8 +12943,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);
   };
 }
@@ -13257,10 +13534,10 @@ 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";
-import { fileURLToPath as fileURLToPath5 } from "url";
-var DEFAULT_UI_REL = join14("ui", "dist", "ui", "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) {
@@ -13269,13 +13546,13 @@ function resolveDefaultUiDist(ctx) {
   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;
   }
@@ -13283,7 +13560,7 @@ function isUiBundleDir(path) {
 function resolvePackageBundledUi() {
   let here;
   try {
-    here = dirname9(fileURLToPath5(import.meta.url));
+    here = dirname10(fileURLToPath6(import.meta.url));
   } catch {
     return null;
   }
@@ -13292,22 +13569,22 @@ function resolvePackageBundledUi() {
 function resolvePackageBundledUiFrom(here) {
   let current = here;
   for (let i = 0; i < 8; i++) {
-    const candidate = join14(current, PACKAGE_UI_REL);
+    const candidate = join15(current, PACKAGE_UI_REL);
     if (isUiBundleDir(candidate)) return candidate;
-    const distHere = join14(current, "dist", PACKAGE_UI_REL);
+    const distHere = join15(current, "dist", PACKAGE_UI_REL);
     if (isUiBundleDir(distHere)) return distHere;
-    const parent = dirname9(current);
+    const parent = dirname10(current);
     if (parent === current) return null;
     current = parent;
   }
   return null;
 }
 function walkUpForUi(startDir) {
-  let current = resolve19(startDir);
+  let current = resolve20(startDir);
   for (let i = 0; i < 64; i++) {
-    const candidate = join14(current, DEFAULT_UI_REL);
+    const candidate = join15(current, DEFAULT_UI_REL);
     if (isUiBundleDir(candidate)) return candidate;
-    const parent = dirname9(current);
+    const parent = dirname10(current);
     if (parent === current) return null;
     current = parent;
   }
@@ -13430,17 +13707,13 @@ function normalizeAddress(addr, fallbackHost, fallbackPort) {
 
 // cli/i18n/serve.texts.ts
 var SERVE_TEXTS = {
-  // Banner emitted to stderr after the listener binds. Mirrors `sm watch`
-  // by writing operational status to stderr (stdout is reserved for
-  // future `--json` boot payloads).
-  boot: "sm serve: listening on http://{{host}}:{{port}} (scope={{scope}}, db={{db}})\n",
-  // Hint shown after the boot line. Branches on --open: when auto-open
-  // is on (default), the message states intent ("opening …"); when
-  // --no-open, it instructs the user to visit the URL manually.
-  // Both end with the Ctrl+C reminder so the operational tail is
-  // identical regardless of branch.
-  bootOpening: "sm serve: opening http://{{host}}:{{port}}/ in your browser. Press Ctrl+C to stop.\n",
-  bootVisitHint: "sm serve: visit http://{{host}}:{{port}}/ in your browser. Press Ctrl+C to stop.\n",
+  // The boot banner (TTY box / flat-line fallback) is rendered by
+  // `cli/util/serve-banner.ts` rather than templated through `tx` —
+  // ANSI escapes + box-drawing aren't a good fit for the flat
+  // `{{name}}` interpolation surface. The flat-mode strings live in
+  // that helper and stay byte-equivalent to the pre-banner format so
+  // existing pipes / redirects ('listening on <url>' scrapers) don't
+  // break.
   // Browser-open failure. Non-fatal — the URL is already printed; the
   // user can open it manually.
   openFailed: "sm serve: could not auto-open browser ({{message}}). Visit {{url}} manually.\n",
@@ -13464,10 +13737,150 @@ var SERVE_TEXTS = {
   shutdown: "sm serve: shutdown complete.\n"
 };
 
+// cli/util/serve-banner.ts
+import { homedir as homedir2 } from "os";
+import { relative as relative5, isAbsolute as isAbsolute6 } from "path";
+var ESC = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  underline: "\x1B[4m",
+  /** 256-color violet (xterm 141). */
+  violet: "\x1B[38;5;141m",
+  /** 256-color green (xterm 42). */
+  green: "\x1B[38;5;42m"
+};
+var LOGO_LINES = [
+  "  ____  _    _ _ _   __  __             ",
+  " / ___|| | _(_) | | |  \\/  | __ _ _ __  ",
+  " \\___ \\| |/ / | | | | |\\/| |/ _` | '_ \\ ",
+  "  ___) |   <| | | | | |  | | (_| | |_) |",
+  " |____/|_|\\_\\_|_|_| |_|  |_|\\__,_| .__/ ",
+  "                                 |_|    "
+];
+var LOGO_WIDTH = 40;
+function renderBanner(input) {
+  const url = `http://${input.host}:${input.port}`;
+  const dbDisplay = formatDbPath(input.dbPath, input.cwd);
+  const browserLine = input.openBrowser ? "Opening browser\u2026  Press Ctrl+C to stop." : `Visit ${url}/ in your browser.  Press Ctrl+C to stop.`;
+  if (!input.isTTY) {
+    return renderFlat({
+      host: input.host,
+      port: input.port,
+      scope: input.scope,
+      dbPath: input.dbPath,
+      openBrowser: input.openBrowser
+    });
+  }
+  return renderFiglet({
+    version: input.version,
+    url,
+    scope: input.scope,
+    dbDisplay,
+    pathDisplay: formatCwdPath(input.cwd),
+    browserLine,
+    colorEnabled: input.colorEnabled
+  });
+}
+function resolveColorEnabled(opts) {
+  if (opts.noColorFlag) return false;
+  const noColor = opts.env["NO_COLOR"];
+  if (noColor !== void 0 && noColor !== "") return false;
+  const forceColor = opts.env["FORCE_COLOR"];
+  if (forceColor !== void 0 && forceColor !== "") return true;
+  return opts.isTTY;
+}
+function renderFlat(input) {
+  const safeHost = sanitizeForTerminal(input.host);
+  const safeDb = sanitizeForTerminal(input.dbPath);
+  const url = `http://${safeHost}:${input.port}`;
+  const linesOut = [];
+  linesOut.push(`sm serve: listening on ${url} (scope=${input.scope}, db=${safeDb})`);
+  if (input.openBrowser) {
+    linesOut.push(`sm serve: opening ${url}/ in your browser. Press Ctrl+C to stop.`);
+  } else {
+    linesOut.push(`sm serve: visit ${url}/ in your browser. Press Ctrl+C to stop.`);
+  }
+  return linesOut.join("\n") + "\n";
+}
+function renderFiglet(input) {
+  const {
+    dimOpen,
+    dimClose,
+    greenUnderline,
+    greenUnderlineClose,
+    violetOpen,
+    violetClose,
+    greenOpen,
+    greenClose
+  } = resolveAnsi(input.colorEnabled);
+  const logoLines = LOGO_LINES.map((line, i) => {
+    const open = i < 3 ? violetOpen : greenOpen;
+    const close = i < 3 ? violetClose : greenClose;
+    return `${open}${line}${close}`;
+  });
+  const versionText = `v${input.version}`;
+  const versionPad = Math.max(0, LOGO_WIDTH - versionText.length);
+  const versionLine = `${" ".repeat(versionPad)}${dimOpen}${versionText}${dimClose}`;
+  const lines = [];
+  lines.push(...logoLines);
+  lines.push("");
+  lines.push(versionLine);
+  lines.push("");
+  lines.push(`  ${dimOpen}Server${dimClose}   ${greenUnderline}${input.url}${greenUnderlineClose}`);
+  lines.push(`  ${dimOpen}Scope${dimClose}    ${input.scope}`);
+  lines.push(`  ${dimOpen}Path${dimClose}     ${input.pathDisplay}`);
+  lines.push(`  ${dimOpen}DB${dimClose}       ${input.dbDisplay}`);
+  lines.push("");
+  lines.push(`  ${dimOpen}${input.browserLine}${dimClose}`);
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+var EMPTY_ANSI = {
+  dimOpen: "",
+  dimClose: "",
+  greenUnderline: "",
+  greenUnderlineClose: "",
+  violetOpen: "",
+  violetClose: "",
+  greenOpen: "",
+  greenClose: ""
+};
+var ENABLED_ANSI = {
+  dimOpen: ESC.dim,
+  dimClose: ESC.reset,
+  greenUnderline: `${ESC.green}${ESC.underline}`,
+  greenUnderlineClose: ESC.reset,
+  violetOpen: ESC.violet,
+  violetClose: ESC.reset,
+  greenOpen: ESC.green,
+  greenClose: ESC.reset
+};
+function resolveAnsi(colorEnabled) {
+  return colorEnabled ? ENABLED_ANSI : EMPTY_ANSI;
+}
+function formatDbPath(dbPath, cwd) {
+  const safe = sanitizeForTerminal(dbPath);
+  if (!isAbsolute6(safe)) return safe;
+  const rel = relative5(cwd, safe);
+  if (rel === "" || rel.startsWith("..") || isAbsolute6(rel)) {
+    return safe;
+  }
+  return rel;
+}
+function formatCwdPath(cwd) {
+  const safe = sanitizeForTerminal(cwd);
+  const home = homedir2();
+  if (home && (safe === home || safe.startsWith(`${home}/`))) {
+    return `~${safe.slice(home.length)}`;
+  }
+  return safe;
+}
+
 // 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: `
@@ -13492,22 +13905,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
@@ -13517,24 +13930,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;
@@ -13562,7 +13975,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) })
       );
@@ -13616,18 +14029,24 @@ var ServeCommand = class extends SmCommand {
       );
       return ExitCode.Error;
     }
+    const stderr = this.context.stderr;
+    const isTTY = stderr.isTTY === true;
+    const colorEnabled = resolveColorEnabled({
+      isTTY,
+      noColorFlag: this.noColor,
+      env: process.env
+    });
     this.context.stderr.write(
-      tx(SERVE_TEXTS.boot, {
+      renderBanner({
+        version: VERSION,
         host: sanitizeForTerminal(handle.address.host),
         port: handle.address.port,
         scope,
-        db: sanitizeForTerminal(dbPath)
-      })
-    );
-    this.context.stderr.write(
-      tx(validation.options.open ? SERVE_TEXTS.bootOpening : SERVE_TEXTS.bootVisitHint, {
-        host: sanitizeForTerminal(handle.address.host),
-        port: handle.address.port
+        dbPath,
+        cwd: runtimeCtx.cwd,
+        openBrowser: validation.options.open,
+        isTTY,
+        colorEnabled
       })
     );
     if (validation.options.open) {
@@ -13743,7 +14162,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 = {
@@ -13783,7 +14202,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: `
@@ -13799,7 +14218,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;
@@ -13948,7 +14367,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 = {
@@ -13963,9 +14382,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.")
   });
@@ -13973,23 +14392,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).")
   });
@@ -13997,121 +14416,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");
   }
@@ -14133,7 +14552,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 = {
@@ -14145,7 +14564,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."
   });
@@ -14215,6 +14634,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);
@@ -14272,7 +14692,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 }));