@skill-map/cli 0.9.0 → 0.11.0

package/dist/cli.js

@@ -180,7 +180,7 @@ function extractLogLevelFlag(argv) {
 var LOGGER_ENV_VAR = ENV_VAR;
 
 // cli/commands/check.ts
-import { Command, Option } from "clipanion";
+import { Command as Command2, Option as Option2 } from "clipanion";
 
 // kernel/i18n/registry.texts.ts
 var REGISTRY_TEXTS = {
@@ -297,7 +297,14 @@ var SKILL_MAP_DIR = ".skill-map";
 var DB_FILENAME = "skill-map.db";
 var JOBS_DIRNAME = "jobs";
 var PLUGINS_DIRNAME = "plugins";
+var SETTINGS_FILENAME = "settings.json";
+var LOCAL_SETTINGS_FILENAME = "settings.local.json";
+var IGNORE_FILENAME = ".skill-mapignore";
 var DEFAULT_DB_REL = `${SKILL_MAP_DIR}/${DB_FILENAME}`;
+var GITIGNORE_ENTRIES = [
+  `${SKILL_MAP_DIR}/${LOCAL_SETTINGS_FILENAME}`,
+  `${SKILL_MAP_DIR}/${DB_FILENAME}`
+];
 function resolveDbPath(options) {
   if (options.db) return resolve(options.db);
   if (options.global) return join(options.homedir, DEFAULT_DB_REL);
@@ -315,6 +322,18 @@ function defaultProjectPluginsDir(ctx) {
 function defaultUserPluginsDir(ctx) {
   return join(ctx.homedir, SKILL_MAP_DIR, PLUGINS_DIRNAME);
 }
+function defaultDbPath(scopeRoot) {
+  return join(scopeRoot, SKILL_MAP_DIR, DB_FILENAME);
+}
+function defaultSettingsPath(scopeRoot) {
+  return join(scopeRoot, SKILL_MAP_DIR, SETTINGS_FILENAME);
+}
+function defaultLocalSettingsPath(scopeRoot) {
+  return join(scopeRoot, SKILL_MAP_DIR, LOCAL_SETTINGS_FILENAME);
+}
+function defaultIgnoreFilePath(scopeRoot) {
+  return join(scopeRoot, IGNORE_FILENAME);
+}
 function assertDbExists(path, stderr) {
   if (path === ":memory:" || existsSync(path)) return true;
   stderr.write(tx(UTIL_TEXTS.dbNotFound, { path }));
@@ -390,11 +409,11 @@ function buildIgnoreFilter(opts = {}) {
     ig.add(opts.ignoreFileText);
   }
   return {
-    ignores(relativePath) {
-      if (relativePath === "" || relativePath === "." || relativePath === "./") {
+    ignores(relativePath2) {
+      if (relativePath2 === "" || relativePath2 === "." || relativePath2 === "./") {
         return false;
       }
-      const normalised = relativePath.replace(/^\.\//, "").replace(/\\/g, "/").replace(/^\//, "");
+      const normalised = relativePath2.replace(/^\.\//, "").replace(/\\/g, "/").replace(/^\//, "");
       if (normalised === "") return false;
       return ig.ignores(normalised);
     }
@@ -605,31 +624,79 @@ var claudeProvider = {
   // pairs the relative manifest-style schema path (mirrors what the
   // spec's provider.schema.json validates) with the loaded JSON Schema
   // (`schemaJson`) the kernel registers with AJV at scan boot.
+  // Step 14.5.d: each kind declares its UI presentation (label, color,
+  // dark variant, icon). The UI consumes this registry via the
+  // `kindRegistry` field embedded in REST envelopes; it derives bg/fg
+  // tints from `color` per theme via a deterministic helper, so the
+  // Provider only declares intent (one base color per theme) instead of
+  // four hex values. Colors and SVG paths transplanted verbatim from
+  // the previous static UI catalog (`ui/src/styles.css` for hex,
+  // `ui/src/app/components/kind-icon/kind-icon.html` for SVG path data,
+  // `ui/src/i18n/kinds.texts.ts` for labels).
   kinds: {
     agent: {
       schema: "./schemas/agent.schema.json",
       schemaJson: agent_schema_default,
-      defaultRefreshAction: "claude/summarize-agent"
+      defaultRefreshAction: "claude/summarize-agent",
+      ui: {
+        label: "Agents",
+        color: "#3b82f6",
+        colorDark: "#60a5fa",
+        icon: { kind: "pi", id: "pi-user" }
+      }
     },
     command: {
       schema: "./schemas/command.schema.json",
       schemaJson: command_schema_default,
-      defaultRefreshAction: "claude/summarize-command"
+      defaultRefreshAction: "claude/summarize-command",
+      ui: {
+        label: "Commands",
+        color: "#f59e0b",
+        colorDark: "#fbbf24",
+        icon: {
+          kind: "svg",
+          path: "M4 17 L10 11 L4 5 M12 19 L20 19"
+        }
+      }
     },
     hook: {
       schema: "./schemas/hook.schema.json",
       schemaJson: hook_schema_default,
-      defaultRefreshAction: "claude/summarize-hook"
+      defaultRefreshAction: "claude/summarize-hook",
+      ui: {
+        label: "Hooks",
+        color: "#8b5cf6",
+        colorDark: "#a78bfa",
+        icon: {
+          kind: "svg",
+          path: "M12 2 a3 3 0 1 0 0 6 a3 3 0 1 0 0 -6 M12 8 L12 22 M5 12 H2 a10 10 0 0 0 20 0 H19"
+        }
+      }
     },
     skill: {
       schema: "./schemas/skill.schema.json",
       schemaJson: skill_schema_default,
-      defaultRefreshAction: "claude/summarize-skill"
+      defaultRefreshAction: "claude/summarize-skill",
+      ui: {
+        label: "Skills",
+        color: "#10b981",
+        colorDark: "#34d399",
+        icon: { kind: "pi", id: "pi-bolt" }
+      }
     },
     note: {
       schema: "./schemas/note.schema.json",
       schemaJson: note_schema_default,
-      defaultRefreshAction: "claude/summarize-note"
+      defaultRefreshAction: "claude/summarize-note",
+      ui: {
+        label: "Notes",
+        color: "#5b908c",
+        colorDark: "#9bbcb8",
+        icon: {
+          kind: "svg",
+          path: "M14 2 H6 a2 2 0 0 0 -2 2 V20 a2 2 0 0 0 2 2 H18 a2 2 0 0 0 2 -2 V8 L14 2 M14 2 V8 H20 M16 13 H8 M16 17 H8 M10 9 H8"
+        }
+      }
     }
   },
   async *walk(roots, options = {}) {
@@ -1367,8 +1434,15 @@ import { readFileSync as readFileSync2 } from "fs";
 import { dirname as dirname2, resolve as resolve3 } from "path";
 import { createRequire } from "module";
 import { Ajv2020 } from "ajv/dist/2020.js";
+
+// kernel/util/ajv-interop.ts
 import addFormatsModule from "ajv-formats";
 var addFormats = addFormatsModule.default ?? addFormatsModule;
+function applyAjvFormats(ajv) {
+  addFormats(ajv);
+}
+
+// kernel/adapters/schema-validators.ts
 var SCHEMA_FILES = {
   node: "schemas/node.schema.json",
   link: "schemas/link.schema.json",
@@ -1407,7 +1481,7 @@ function buildSchemaValidators() {
     allErrors: true,
     allowUnionTypes: true
   });
-  addFormats(ajv);
+  applyAjvFormats(ajv);
   for (const rel of SUPPORTING_SCHEMAS) {
     const file = resolve3(specRoot, rel);
     if (!existsSyncSafe(file)) continue;
@@ -1462,7 +1536,7 @@ function buildProviderFrontmatterValidator(providers) {
     allErrors: true,
     allowUnionTypes: true
   });
-  addFormats(ajv);
+  applyAjvFormats(ajv);
   const baseFile = resolve3(specRoot, "schemas/frontmatter/base.schema.json");
   const baseSchema = JSON.parse(readFileSync2(baseFile, "utf8"));
   ajv.addSchema(baseSchema);
@@ -1683,7 +1757,6 @@ import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync }
 import { isAbsolute, join as join3, relative as relative2, resolve as resolve4 } from "path";
 import { pathToFileURL } from "url";
 import { Ajv2020 as Ajv20202 } from "ajv/dist/2020.js";
-import addFormatsModule2 from "ajv-formats";
 import semver from "semver";
 
 // kernel/i18n/plugin-loader.texts.ts
@@ -1728,7 +1801,6 @@ var HOOK_TRIGGERS = Object.freeze([
 ]);
 
 // kernel/adapters/plugin-loader.ts
-var addFormats2 = addFormatsModule2.default ?? addFormatsModule2;
 var DEFAULT_PLUGIN_IMPORT_TIMEOUT_MS = 5e3;
 function createPluginLoader(options) {
   return new PluginLoader(options);
@@ -2243,7 +2315,7 @@ function compilePluginSchema(pluginPath, relPath) {
   }
   try {
     const ajv = new Ajv20202({ strict: false, allErrors: true, allowUnionTypes: true });
-    addFormats2(ajv);
+    applyAjvFormats(ajv);
     const compiled = ajv.compile(raw);
     return { ok: true, validate: compiled };
   } catch (err) {
@@ -2628,7 +2700,7 @@ var AsyncMutex = class {
       this.#locked = true;
       return;
     }
-    await new Promise((resolve19) => this.#waiters.push(resolve19));
+    await new Promise((resolve20) => this.#waiters.push(resolve20));
     this.#locked = true;
   }
   unlock() {
@@ -4627,11 +4699,111 @@ function formatWarning(plugin) {
   });
 }
 
+// cli/util/sm-command.ts
+import { Command, Option } from "clipanion";
+
+// cli/util/elapsed.ts
+function startElapsed() {
+  const startNs = process.hrtime.bigint();
+  return {
+    ms() {
+      const elapsedNs = Number(process.hrtime.bigint() - startNs);
+      return Math.round(elapsedNs / 1e6);
+    },
+    formatted() {
+      return formatElapsed(this.ms());
+    }
+  };
+}
+function formatElapsed(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 6e4);
+  const seconds = Math.round(ms % 6e4 / 1e3);
+  return `${minutes}m ${seconds}s`;
+}
+function emitDoneStderr(stderr, elapsed, quiet = false) {
+  if (quiet) return;
+  stderr.write(tx(UTIL_TEXTS.doneIn, { elapsed: elapsed.formatted() }));
+}
+
+// cli/util/sm-command.ts
+function isEnvSet(value) {
+  return value !== void 0 && value !== "";
+}
+var SmCommand = class extends Command {
+  global = Option.Boolean("-g,--global", false, {
+    description: "Operate on ~/.skill-map/ instead of ./.skill-map/."
+  });
+  json = Option.Boolean("--json", false, {
+    description: "Emit machine-readable output on stdout. Suppresses pretty printing."
+  });
+  quiet = Option.Boolean("-q,--quiet", false, {
+    description: 'Suppress non-error stderr output (including "done in <\u2026>").'
+  });
+  noColor = Option.Boolean("--no-color", false, {
+    description: "Disable ANSI color codes."
+  });
+  verbose = Option.Counter("-v,--verbose", 0, {
+    description: "Increase log level (-v=info, -vv=debug, -vvv=trace)."
+  });
+  db = Option.String("--db", { required: false, description: "Override the database file location (escape hatch)." });
+  /**
+   * Subclasses set this to `false` to opt out of the trailing
+   * `done in <…>` line — appropriate for interactive verbs (`db shell`),
+   * watcher loops (`watch`), and meta verbs that report a fixed
+   * version (`version`, `help`).
+   */
+  emitElapsed = true;
+  /**
+   * Wall-clock timer started just before `run()`. Subclasses that need
+   * to embed `elapsedMs` in their `--json` output read `this.elapsed.ms()`.
+   * `null` only between `Command` construction and the first
+   * `execute()` call.
+   */
+  elapsed = null;
+  async execute() {
+    this.applyEnvOverrides();
+    this.applyVerboseLogger();
+    this.elapsed = startElapsed();
+    try {
+      return await this.run();
+    } finally {
+      if (this.emitElapsed) emitDoneStderr(this.context.stderr, this.elapsed, this.quiet);
+    }
+  }
+  /**
+   * Promote spec env vars into flag values when the flag was left at
+   * default. CLI flag wins over env var (spec § Global flags
+   * precedence: "CLI flag wins over env var. Env var wins over config
+   * file.").
+   */
+  applyEnvOverrides() {
+    const env = process.env;
+    this.noColor = this.noColor || isEnvSet(env["NO_COLOR"]);
+    this.global = this.global || env["SKILL_MAP_SCOPE"] === "global";
+    this.json = this.json || isEnvSet(env["SKILL_MAP_JSON"]);
+    if (this.db === void 0 && isEnvSet(env["SKILL_MAP_DB"])) {
+      this.db = env["SKILL_MAP_DB"];
+    }
+  }
+  /**
+   * `-v` / `-vv` / `-vvv` reconfigures the kernel logger. Skipped
+   * when `verbose === 0` so the level configured at `entry.ts` boot
+   * (from `--log-level` / `SKILL_MAP_LOG_LEVEL`) stays in effect.
+   */
+  applyVerboseLogger() {
+    if (this.verbose <= 0) return;
+    const level = this.verbose >= 3 ? "trace" : this.verbose === 2 ? "debug" : "info";
+    configureLogger(new Logger({ level, stream: process.stderr }));
+  }
+};
+
 // cli/commands/check.ts
 var SEVERITY_ORDER = ["error", "warn", "info"];
-var CheckCommand = class extends Command {
+var CheckCommand = class extends SmCommand {
   static paths = [["check"]];
-  static usage = Command.Usage({
+  static usage = Command2.Usage({
     category: "Browse",
     description: "Print all current issues (reads from DB, faster than sm scan --json | jq).",
     details: `
@@ -4656,27 +4828,24 @@ var CheckCommand = class extends Command {
       ["Use a non-default DB file", "$0 check --db /path/to/skill-map.db"]
     ]
   });
-  global = Option.Boolean("-g,--global", false);
-  db = Option.String("--db", { required: false });
-  json = Option.Boolean("--json", false);
-  node = Option.String("-n,--node", {
+  node = Option2.String("-n,--node", {
     required: false,
     description: "Restrict to issues whose nodeIds include the given path. Combines with --rules and --include-prob."
   });
-  rules = Option.String("--rules", {
+  rules = Option2.String("--rules", {
     required: false,
     description: "Comma-separated rule ids (qualified or short). Restrict the issue read; with --include-prob, also filters which prob rules surface in the advisory."
   });
-  includeProb = Option.Boolean("--include-prob", false, {
+  includeProb = Option2.Boolean("--include-prob", false, {
     description: "Detect probabilistic Rules and emit a stub advisory naming them (full dispatch lands at Step 10). Default off \u2192 deterministic-only, CI-safe."
   });
-  async = Option.Boolean("--async", false, {
+  async = Option2.Boolean("--async", false, {
     description: "Reserved companion to --include-prob: once jobs ship, returns job ids without waiting. No effect today."
   });
-  noPlugins = Option.Boolean("--no-plugins", false, {
+  noPlugins = Option2.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery; only kernel built-ins participate in the prob detection. Same flag shape as `sm scan`."
   });
-  async execute() {
+  async run() {
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(dbPath, this.context.stderr)) return ExitCode.NotFound;
     const ruleFilter = parseRulesFlag(this.rules);
@@ -4785,32 +4954,7 @@ import {
   writeFileSync
 } from "fs";
 import { dirname as dirname5, join as join7 } from "path";
-import { Command as Command2, Option as Option2 } from "clipanion";
-
-// cli/util/elapsed.ts
-function startElapsed() {
-  const startNs = process.hrtime.bigint();
-  return {
-    ms() {
-      const elapsedNs = Number(process.hrtime.bigint() - startNs);
-      return Math.round(elapsedNs / 1e6);
-    },
-    formatted() {
-      return formatElapsed(this.ms());
-    }
-  };
-}
-function formatElapsed(ms) {
-  if (ms < 1e3) return `${ms}ms`;
-  if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
-  const minutes = Math.floor(ms / 6e4);
-  const seconds = Math.round(ms % 6e4 / 1e3);
-  return `${minutes}m ${seconds}s`;
-}
-function emitDoneStderr(stderr, elapsed, quiet = false) {
-  if (quiet) return;
-  stderr.write(tx(UTIL_TEXTS.doneIn, { elapsed: elapsed.formatted() }));
-}
+import { Command as Command3, Option as Option3 } from "clipanion";
 
 // cli/util/error-reporter.ts
 function formatErrorMessage(err) {
@@ -4970,9 +5114,9 @@ function formatValueHuman(v) {
   if (Array.isArray(v) || typeof v === "object" && v !== null) return JSON.stringify(v);
   return String(v);
 }
-var ConfigListCommand = class extends Command2 {
+var ConfigListCommand = class extends SmCommand {
   static paths = [["config", "list"]];
-  static usage = Command2.Usage({
+  static usage = Command3.Usage({
     category: "Config",
     description: "Print the effective config after layered merge.",
     details: `
@@ -4981,10 +5125,11 @@ var ConfigListCommand = class extends Command2 {
       Exempt from "done in <\u2026>" per spec/cli-contract.md \xA7Elapsed time.
     `
   });
-  json = Option2.Boolean("--json", false);
-  global = Option2.Boolean("-g,--global", false);
-  strict = Option2.Boolean("--strict", false);
-  async execute() {
+  strict = Option3.Boolean("--strict", false);
+  // Read-only config inspection: spec § Elapsed time exempts the
+  // config family from the trailing "done in" line.
+  emitElapsed = false;
+  async run() {
     const result = tryLoadConfig(
       { scope: this.global ? "global" : "project", strict: this.strict, ...defaultRuntimeContext() },
       this.context.stderr
@@ -5005,9 +5150,9 @@ var ConfigListCommand = class extends Command2 {
     return ExitCode.Ok;
   }
 };
-var ConfigGetCommand = class extends Command2 {
+var ConfigGetCommand = class extends SmCommand {
   static paths = [["config", "get"]];
-  static usage = Command2.Usage({
+  static usage = Command3.Usage({
     category: "Config",
     description: "Read a single config value by dot-path key.",
     details: `
@@ -5015,11 +5160,10 @@ var ConfigGetCommand = class extends Command2 {
       Exempt from "done in <\u2026>".
     `
   });
-  key = Option2.String({ required: true });
-  json = Option2.Boolean("--json", false);
-  global = Option2.Boolean("-g,--global", false);
-  strict = Option2.Boolean("--strict", false);
-  async execute() {
+  key = Option3.String({ required: true });
+  strict = Option3.Boolean("--strict", false);
+  emitElapsed = false;
+  async run() {
     const result = tryLoadConfig(
       { scope: this.global ? "global" : "project", strict: this.strict, ...defaultRuntimeContext() },
       this.context.stderr
@@ -5049,9 +5193,9 @@ var ConfigGetCommand = class extends Command2 {
     return ExitCode.Ok;
   }
 };
-var ConfigShowCommand = class extends Command2 {
+var ConfigShowCommand = class extends SmCommand {
   static paths = [["config", "show"]];
-  static usage = Command2.Usage({
+  static usage = Command3.Usage({
     category: "Config",
     description: "Show a config value with the layer that set it (--source).",
     details: `
@@ -5061,17 +5205,16 @@ var ConfigShowCommand = class extends Command2 {
       Exempt from "done in <\u2026>".
     `
   });
-  key = Option2.String({ required: true });
-  source = Option2.Boolean("--source", false);
-  json = Option2.Boolean("--json", false);
-  global = Option2.Boolean("-g,--global", false);
-  strict = Option2.Boolean("--strict", false);
+  key = Option3.String({ required: true });
+  source = Option3.Boolean("--source", false);
+  strict = Option3.Boolean("--strict", false);
+  emitElapsed = false;
   // CLI orchestrator: each branch (load failure, forbidden segment,
   // unknown key, --json + --source 2x2 dispatch) is one validation gate
   // or output-format pick. Splitting per branch scatters the gate from
   // the value it gates.
   // eslint-disable-next-line complexity
-  async execute() {
+  async run() {
     const result = tryLoadConfig(
       { scope: this.global ? "global" : "project", strict: this.strict, ...defaultRuntimeContext() },
       this.context.stderr
@@ -5134,9 +5277,9 @@ var LAYER_RANK = {
   "project-local": 4,
   override: 5
 };
-var ConfigSetCommand = class extends Command2 {
+var ConfigSetCommand = class extends SmCommand {
   static paths = [["config", "set"]];
-  static usage = Command2.Usage({
+  static usage = Command3.Usage({
     category: "Config",
     description: "Write a config key. Project file by default; -g writes to user.",
     details: `
@@ -5147,11 +5290,9 @@ var ConfigSetCommand = class extends Command2 {
       Schema violation \u2192 exit 2, no write performed.
     `
   });
-  key = Option2.String({ required: true });
-  value = Option2.String({ required: true });
-  global = Option2.Boolean("-g,--global", false);
-  async execute() {
-    const elapsed = startElapsed();
+  key = Option3.String({ required: true });
+  value = Option3.String({ required: true });
+  async run() {
     const ctx = defaultRuntimeContext();
     const target = this.global ? "user" : "project";
     const path = targetSettingsPath(target, ctx.cwd, ctx.homedir);
@@ -5162,7 +5303,6 @@ var ConfigSetCommand = class extends Command2 {
     } catch (err) {
       if (err instanceof ForbiddenSegmentError) {
         this.context.stderr.write(tx(CONFIG_TEXTS.forbiddenKeySegment, { segment: err.segment, key: err.key }));
-        emitDoneStderr(this.context.stderr, elapsed);
         return ExitCode.Error;
       }
       throw err;
@@ -5171,18 +5311,16 @@ var ConfigSetCommand = class extends Command2 {
     const result = validators.validate("project-config", current);
     if (!result.ok) {
       this.context.stderr.write(tx(CONFIG_TEXTS.invalidAfterSet, { errors: result.errors }));
-      emitDoneStderr(this.context.stderr, elapsed);
       return ExitCode.Error;
     }
     writeJsonAtomic(path, current);
     this.context.stdout.write(tx(CONFIG_TEXTS.setWritten, { key: this.key, value: formatValueHuman(value), path }));
-    emitDoneStderr(this.context.stderr, elapsed);
     return ExitCode.Ok;
   }
 };
-var ConfigResetCommand = class extends Command2 {
+var ConfigResetCommand = class extends SmCommand {
   static paths = [["config", "reset"]];
-  static usage = Command2.Usage({
+  static usage = Command3.Usage({
     category: "Config",
     description: "Remove a config key from the target file (project default; -g for user).",
     details: `
@@ -5190,16 +5328,13 @@ var ConfigResetCommand = class extends Command2 {
       Idempotent \u2014 running twice is safe; absent key prints an info note and exits 0.
     `
   });
-  key = Option2.String({ required: true });
-  global = Option2.Boolean("-g,--global", false);
-  async execute() {
-    const elapsed = startElapsed();
+  key = Option3.String({ required: true });
+  async run() {
     const ctx = defaultRuntimeContext();
     const target = this.global ? "user" : "project";
     const path = targetSettingsPath(target, ctx.cwd, ctx.homedir);
     if (!existsSync8(path)) {
       this.context.stdout.write(tx(CONFIG_TEXTS.unsetNoOverride, { path, key: this.key }));
-      emitDoneStderr(this.context.stderr, elapsed);
       return ExitCode.Ok;
     }
     const current = readJsonObjectOrEmpty(path);
@@ -5209,19 +5344,16 @@ var ConfigResetCommand = class extends Command2 {
     } catch (err) {
       if (err instanceof ForbiddenSegmentError) {
         this.context.stderr.write(tx(CONFIG_TEXTS.forbiddenKeySegment, { segment: err.segment, key: err.key }));
-        emitDoneStderr(this.context.stderr, elapsed);
         return ExitCode.Error;
       }
       throw err;
     }
     if (!removed) {
       this.context.stdout.write(tx(CONFIG_TEXTS.unsetNoOverride, { path, key: this.key }));
-      emitDoneStderr(this.context.stderr, elapsed);
       return ExitCode.Ok;
     }
     writeJsonAtomic(path, current);
     this.context.stdout.write(tx(CONFIG_TEXTS.unsetRemoved, { key: this.key, path }));
-    emitDoneStderr(this.context.stderr, elapsed);
     return ExitCode.Ok;
   }
 };
@@ -5237,7 +5369,7 @@ var CONFIG_COMMANDS = [
 import { existsSync as existsSync11, readFileSync as readFileSync9 } from "fs";
 import { dirname as dirname7, resolve as resolve11 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import { Command as Command3, Option as Option3 } from "clipanion";
+import { Command as Command4, Option as Option4 } from "clipanion";
 
 // conformance/index.ts
 import { spawnSync } from "child_process";
@@ -5700,9 +5832,9 @@ function resolveBinary() {
   }
   return resolve11(here, "..", "..", "bin", "sm.js");
 }
-var ConformanceRunCommand = class extends Command3 {
+var ConformanceRunCommand = class extends SmCommand {
   static paths = [["conformance", "run"]];
-  static usage = Command3.Usage({
+  static usage = Command4.Usage({
     category: "Introspection",
     description: "Run the conformance suite \u2014 spec-owned cases plus every built-in Provider.",
     details: `
@@ -5736,14 +5868,14 @@ var ConformanceRunCommand = class extends Command3 {
       ]
     ]
   });
-  scope = Option3.String("--scope", {
+  scope = Option4.String("--scope", {
     required: false,
     description: "Suite selector: 'all' (default), 'spec', or 'provider:<id>'."
   });
   // CLI orchestrator: scope resolution + per-case run loop +
   // per-result render branches + global pass/fail decision.
   // eslint-disable-next-line complexity
-  async execute() {
+  async run() {
     let scopes;
     try {
       scopes = selectConformanceScopes(this.scope);
@@ -5864,7 +5996,7 @@ var CONFORMANCE_COMMANDS = [ConformanceRunCommand];
 
 // cli/commands/db.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { chmod, copyFile, mkdir, rm, stat as stat2 } from "fs/promises";
+import { chmod, copyFile, mkdir, rm } from "fs/promises";
 import { dirname as dirname8, join as join9, resolve as resolve12 } from "path";
 import { DatabaseSync as DatabaseSync4 } from "node:sqlite";
 
@@ -5940,13 +6072,10 @@ var DB_TEXTS = {
 };
 
 // cli/commands/db.ts
-import { Command as Command4, Option as Option4 } from "clipanion";
-var SAFE_SQL_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-function assertSafeIdentifier(name) {
-  if (!SAFE_SQL_IDENTIFIER_RE.test(name)) {
-    throw new Error(`refusing to operate on non-identifier table name: ${JSON.stringify(name)}`);
-  }
-}
+import { Command as Command5, Option as Option5 } from "clipanion";
+
+// cli/util/fs.ts
+import { stat as stat2 } from "fs/promises";
 async function pathExists(path) {
   try {
     await stat2(path);
@@ -5964,15 +6093,23 @@ async function statOrNull(path) {
     throw err;
   }
 }
+
+// cli/commands/db.ts
+var SAFE_SQL_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertSafeIdentifier(name) {
+  if (!SAFE_SQL_IDENTIFIER_RE.test(name)) {
+    throw new Error(`refusing to operate on non-identifier table name: ${JSON.stringify(name)}`);
+  }
+}
 async function chmodOwnerOnlyBestEffort(target) {
   try {
     await chmod(target, 384);
   } catch {
   }
 }
-var DbBackupCommand = class extends Command4 {
+var DbBackupCommand = class extends SmCommand {
   static paths = [["db", "backup"]];
-  static usage = Command4.Usage({
+  static usage = Command5.Usage({
     category: "Database",
     description: "WAL checkpoint + copy the DB file to a backup.",
     details: `
@@ -5982,10 +6119,8 @@ var DbBackupCommand = class extends Command4 {
       running sm scan afterwards refreshes scan_*.
     `
   });
-  global = Option4.Boolean("-g,--global", false);
-  db = Option4.String("--db", { required: false });
-  out = Option4.String("--out", { required: false });
-  async execute() {
+  out = Option5.String("--out", { required: false });
+  async run() {
     const path = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(path, this.context.stderr)) return ExitCode.NotFound;
     const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
@@ -5997,9 +6132,9 @@ var DbBackupCommand = class extends Command4 {
     return ExitCode.Ok;
   }
 };
-var DbRestoreCommand = class extends Command4 {
+var DbRestoreCommand = class extends SmCommand {
   static paths = [["db", "restore"]];
-  static usage = Command4.Usage({
+  static usage = Command5.Usage({
     category: "Database",
     description: "Replace the active DB file with a backup.",
     details: `
@@ -6010,14 +6145,12 @@ var DbRestoreCommand = class extends Command4 {
       Dry-run bypasses the confirmation prompt.
     `
   });
-  source = Option4.String({ required: true });
-  global = Option4.Boolean("-g,--global", false);
-  db = Option4.String("--db", { required: false });
-  yes = Option4.Boolean("--yes,--force", false);
-  dryRun = Option4.Boolean("-n,--dry-run", false, {
+  source = Option5.String({ required: true });
+  yes = Option5.Boolean("--yes,--force", false);
+  dryRun = Option5.Boolean("-n,--dry-run", false, {
     description: "Preview the restore without overwriting the live DB."
   });
-  async execute() {
+  async run() {
     const target = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     const sourcePath = resolve12(this.source);
     const sourceStat = await statOrNull(sourcePath);
@@ -6059,9 +6192,9 @@ var DbRestoreCommand = class extends Command4 {
     return ExitCode.Ok;
   }
 };
-var DbResetCommand = class extends Command4 {
+var DbResetCommand = class extends SmCommand {
   static paths = [["db", "reset"]];
-  static usage = Command4.Usage({
+  static usage = Command5.Usage({
     category: "Database",
     description: "Drop scan_* (default), optionally state_*, or delete the DB entirely.",
     details: `
@@ -6075,12 +6208,10 @@ var DbResetCommand = class extends Command4 {
       preview itself is non-destructive).
     `
   });
-  global = Option4.Boolean("-g,--global", false);
-  db = Option4.String("--db", { required: false });
-  state = Option4.Boolean("--state", false);
-  hard = Option4.Boolean("--hard", false);
-  yes = Option4.Boolean("--yes,--force", false);
-  dryRun = Option4.Boolean("-n,--dry-run", false, {
+  state = Option5.Boolean("--state", false);
+  hard = Option5.Boolean("--hard", false);
+  yes = Option5.Boolean("--yes,--force", false);
+  dryRun = Option5.Boolean("-n,--dry-run", false, {
     description: "Preview the reset without dropping any tables or unlinking any files."
   });
   // CLI orchestrator: --state vs --hard flag combo + --dry-run + --yes
@@ -6088,7 +6219,7 @@ var DbResetCommand = class extends Command4 {
   // expression of the flag semantics; splitting per branch would
   // distance the validations from their guards.
   // eslint-disable-next-line complexity
-  async execute() {
+  async run() {
     if (this.state && this.hard) {
       this.context.stderr.write(DB_TEXTS.resetStateAndHardMutex);
       return ExitCode.Error;
@@ -6176,9 +6307,9 @@ var DbResetCommand = class extends Command4 {
     return ExitCode.Ok;
   }
 };
-var DbShellCommand = class extends Command4 {
+var DbShellCommand = class extends SmCommand {
   static paths = [["db", "shell"]];
-  static usage = Command4.Usage({
+  static usage = Command5.Usage({
     category: "Database",
     description: "Open an interactive sqlite3 shell on the DB file.",
     details: `
@@ -6187,9 +6318,11 @@ var DbShellCommand = class extends Command4 {
       sm db dump for a read-only inspection.
     `
   });
-  global = Option4.Boolean("-g,--global", false);
-  db = Option4.String("--db", { required: false });
-  async execute() {
+  // Interactive shell: the spawned `sqlite3` owns the terminal. No
+  // `done in <…>` line — the user expects to see the shell's own
+  // prompt + farewell, not a follow-up trailer once they exit.
+  emitElapsed = false;
+  async run() {
     const path = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(path, this.context.stderr)) return ExitCode.NotFound;
     const result = spawnSync2("sqlite3", [path], { stdio: "inherit" });
@@ -6200,22 +6333,20 @@ var DbShellCommand = class extends Command4 {
     return result.status ?? 0;
   }
 };
-var DbDumpCommand = class extends Command4 {
+var DbDumpCommand = class extends SmCommand {
   static paths = [["db", "dump"]];
-  static usage = Command4.Usage({
+  static usage = Command5.Usage({
     category: "Database",
     description: "SQL dump to stdout.",
     details: "Read-only. Use --tables <names...> to limit the dump to specific tables."
   });
-  global = Option4.Boolean("-g,--global", false);
-  db = Option4.String("--db", { required: false });
-  tables = Option4.Array("--tables", { required: false });
+  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 execute() {
+  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"];
@@ -6236,9 +6367,9 @@ var DbDumpCommand = class extends Command4 {
     return result.status ?? 0;
   }
 };
-var DbMigrateCommand = class extends Command4 {
+var DbMigrateCommand = class extends SmCommand {
   static paths = [["db", "migrate"]];
-  static usage = Command4.Usage({
+  static usage = Command5.Usage({
     category: "Database",
     description: "Apply pending kernel + plugin migrations (default) or inspect plan.",
     details: `
@@ -6259,21 +6390,19 @@ var DbMigrateCommand = class extends Command4 {
       object outside the prefix.
     `
   });
-  global = Option4.Boolean("-g,--global", false);
-  db = Option4.String("--db", { required: false });
-  dryRun = Option4.Boolean("--dry-run", false);
-  status = Option4.Boolean("--status", false);
-  to = Option4.String("--to", { required: false });
-  noBackup = Option4.Boolean("--no-backup", false);
-  kernelOnly = Option4.Boolean("--kernel-only", false);
-  pluginId = Option4.String("--plugin", { required: false });
+  dryRun = Option5.Boolean("-n,--dry-run", false);
+  status = Option5.Boolean("--status", false);
+  to = Option5.String("--to", { required: false });
+  noBackup = Option5.Boolean("--no-backup", false);
+  kernelOnly = Option5.Boolean("--kernel-only", false);
+  pluginId = Option5.String("--plugin", { required: false });
   // Multi-flag CLI orchestrator: validates flag combos, optionally
   // discovers plugins, fans out into status / apply branches against
   // both the kernel ledger and per-plugin ledgers. Splitting per branch
   // would scatter the close-to-call-site flag handling without making
   // the verb easier to follow.
   // eslint-disable-next-line complexity
-  async execute() {
+  async run() {
     if (this.kernelOnly && this.pluginId !== void 0) {
       this.context.stderr.write(DB_TEXTS.migrateKernelOnlyAndPluginMutex);
       return ExitCode.Error;
@@ -6455,7 +6584,7 @@ var DB_COMMANDS = [
 ];
 
 // cli/commands/export.ts
-import { Command as Command5, Option as Option5 } from "clipanion";
+import { Command as Command6, Option as Option6 } from "clipanion";
 
 // kernel/scan/query.ts
 var HAS_VALUES = /* @__PURE__ */ new Set(["issues"]);
@@ -6612,9 +6741,9 @@ var SUPPORTED_FORMATS = ["json", "md"];
 var DEFERRED_FORMATS = {
   mermaid: EXPORT_TEXTS.formatDeferredReasonMermaid
 };
-var ExportCommand = class extends Command5 {
+var ExportCommand = class extends SmCommand {
   static paths = [["export"]];
-  static usage = Command5.Usage({
+  static usage = Command6.Usage({
     category: "Browse",
     description: "Filtered export. Query syntax is implementation-defined pre-1.0.",
     details: `
@@ -6638,11 +6767,9 @@ var ExportCommand = class extends Command5 {
       ["Whole graph as Markdown", '$0 export "" --format md']
     ]
   });
-  query = Option5.String({ required: true });
-  format = Option5.String("--format", { required: false });
-  global = Option5.Boolean("-g,--global", false);
-  db = Option5.String("--db", { required: false });
-  async execute() {
+  query = Option6.String({ required: true });
+  format = Option6.String("--format", { required: false });
+  async run() {
     const format = (this.format ?? "json").toLowerCase();
     if (DEFERRED_FORMATS[format]) {
       this.context.stderr.write(
@@ -6826,7 +6953,7 @@ function pickTitle2(node) {
 }
 
 // cli/commands/graph.ts
-import { Command as Command6, Option as Option6 } from "clipanion";
+import { Command as Command7, Option as Option7 } from "clipanion";
 
 // cli/i18n/graph.texts.ts
 var GRAPH_TEXTS = {
@@ -6836,9 +6963,9 @@ var GRAPH_TEXTS = {
 
 // cli/commands/graph.ts
 var DEFAULT_FORMAT = "ascii";
-var GraphCommand = class extends Command6 {
+var GraphCommand = class extends SmCommand {
   static paths = [["graph"]];
-  static usage = Command6.Usage({
+  static usage = Command7.Usage({
     category: "Browse",
     description: "Render the full graph via the named formatter.",
     details: `
@@ -6855,15 +6982,13 @@ var GraphCommand = class extends Command6 {
       ["Use a non-default DB file", "$0 graph --db /path/to/skill-map.db"]
     ]
   });
-  format = Option6.String("--format", DEFAULT_FORMAT, {
+  format = Option7.String("--format", DEFAULT_FORMAT, {
     description: `Formatter format. Must match the \`formatId\` field of a registered formatter. Default: ${DEFAULT_FORMAT}.`
   });
-  global = Option6.Boolean("-g,--global", false);
-  db = Option6.String("--db", { required: false });
-  noPlugins = Option6.Boolean("--no-plugins", false, {
+  noPlugins = Option7.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery. Only built-in formatters participate."
   });
-  async execute() {
+  async run() {
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(dbPath, this.context.stderr)) return ExitCode.NotFound;
     const pluginRuntime = this.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: this.global ? "global" : "project" });
@@ -6898,12 +7023,12 @@ var GraphCommand = class extends Command6 {
 import { readFileSync as readFileSync10 } from "fs";
 import { createRequire as createRequire4 } from "module";
 import { resolve as resolve13 } from "path";
-import { Command as Command7, Option as Option7 } from "clipanion";
+import { Command as Command8, Option as Option8 } from "clipanion";
 
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.9.0",
+  version: "0.11.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -6950,6 +7075,7 @@ var package_default = {
   scripts: {
     build: "tsup",
     dev: "tsup --watch",
+    "dev:serve": "node ../scripts/dev-serve.js",
     typecheck: "tsc --noEmit",
     lint: "eslint .",
     "lint:fix": "eslint . --fix",
@@ -6960,17 +7086,20 @@ var package_default = {
     clean: "rm -rf dist coverage"
   },
   dependencies: {
+    "@hono/node-server": "2.0.1",
     "@skill-map/spec": "*",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
     clipanion: "4.0.0-rc.4",
+    hono: "4.12.16",
     ignore: "7.0.5",
     "js-tiktoken": "1.0.21",
     "js-yaml": "4.1.1",
     kysely: "0.28.16",
     semver: "7.7.4",
-    typanion: "3.14.0"
+    typanion: "3.14.0",
+    ws: "8.20.0"
   },
   devDependencies: {
     "@eslint/js": "10.0.1",
@@ -6978,6 +7107,7 @@ var package_default = {
     "@types/js-yaml": "4.0.9",
     "@types/node": "24.12.2",
     "@types/semver": "7.7.1",
+    "@types/ws": "8.18.1",
     c8: "11.0.0",
     eslint: "10.2.1",
     "eslint-plugin-import-x": "4.16.2",
@@ -7074,9 +7204,9 @@ var HELP_TEXTS = {
 };
 
 // cli/commands/help.ts
-var HelpCommand = class extends Command7 {
+var HelpCommand = class extends Command8 {
   static paths = [["help"]];
-  static usage = Command7.Usage({
+  static usage = Command8.Usage({
     category: "Introspection",
     description: "Self-describing introspection. --format human|md|json.",
     details: `
@@ -7090,8 +7220,8 @@ var HelpCommand = class extends Command7 {
         json            \u2014 structured surface dump per spec/cli-contract.md.
     `
   });
-  verbParts = Option7.Rest({ required: 0 });
-  format = Option7.String("--format", "human");
+  verbParts = Option8.Rest({ required: 0 });
+  format = Option8.String("--format", "human");
   async execute() {
     const format = normalizeFormat(this.format);
     if (!format) {
@@ -7409,8 +7539,8 @@ function renderCompactOverview(verbs) {
   lines.push(HELP_TEXTS.compactFooter);
   return lines.join("\n") + "\n";
 }
-var RootHelpCommand = class extends Command7 {
-  static paths = [["-h"], ["--help"], Command7.Default];
+var RootHelpCommand = class extends Command8 {
+  static paths = [["-h"], ["--help"], Command8.Default];
   async execute() {
     const rawDefs = this.cli.definitions();
     const verbs = rawDefs.filter((d) => !isBuiltin(d)).map(normalizeDefinition).sort(byPath);
@@ -7465,9 +7595,9 @@ function registeredVerbPaths(cli2) {
 }
 
 // cli/commands/init.ts
-import { mkdir as mkdir2, readFile as readFile2, stat as stat3, writeFile } from "fs/promises";
+import { mkdir as mkdir2, readFile as readFile2, writeFile } from "fs/promises";
 import { join as join10 } from "path";
-import { Command as Command8, Option as Option8 } from "clipanion";
+import { Command as Command9, Option as Option9 } from "clipanion";
 
 // kernel/orchestrator.ts
 import { createHash } from "crypto";
@@ -8629,22 +8759,9 @@ function createCliProgressEmitter(stderr) {
 }
 
 // cli/commands/init.ts
-var GITIGNORE_ENTRIES = [
-  ".skill-map/settings.local.json",
-  ".skill-map/skill-map.db"
-];
-async function pathExists2(path) {
-  try {
-    await stat3(path);
-    return true;
-  } catch (err) {
-    if (err.code === "ENOENT") return false;
-    throw err;
-  }
-}
-var InitCommand = class extends Command8 {
+var InitCommand = class extends SmCommand {
   static paths = [["init"]];
-  static usage = Command8.Usage({
+  static usage = Command9.Usage({
     category: "Setup",
     description: "Bootstrap the current scope: scaffold .skill-map/, provision DB, run first scan.",
     details: `
@@ -8668,19 +8785,16 @@ var InitCommand = class extends Command8 {
       ["Preview what would be created", "$0 init --dry-run"]
     ]
   });
-  global = Option8.Boolean("-g,--global", false, {
-    description: "Initialise ~/.skill-map/ instead of ./.skill-map/."
-  });
-  noScan = Option8.Boolean("--no-scan", false, {
+  noScan = Option9.Boolean("--no-scan", false, {
     description: "Skip the first scan after scaffolding."
   });
-  force = Option8.Boolean("--force", false, {
+  force = Option9.Boolean("--force", false, {
     description: "Overwrite an existing settings.json / settings.local.json / .skill-mapignore."
   });
-  strict = Option8.Boolean("--strict", false, {
+  strict = Option9.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 = Option8.Boolean("-n,--dry-run", false, {
+  dryRun = Option9.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
@@ -8688,18 +8802,16 @@ var InitCommand = class extends Command8 {
   // gitignore management + DB provision + first scan delegation).
   // The first-scan branch already lives in `runFirstScan`.
   // eslint-disable-next-line complexity
-  async execute() {
-    const elapsed = startElapsed();
+  async run() {
     const ctx = defaultRuntimeContext();
     const scopeRoot = this.global ? ctx.homedir : ctx.cwd;
     const skillMapDir = join10(scopeRoot, SKILL_MAP_DIR);
-    const settingsPath = join10(skillMapDir, "settings.json");
-    const localPath = join10(skillMapDir, "settings.local.json");
-    const ignorePath = join10(scopeRoot, ".skill-mapignore");
-    const dbPath = join10(skillMapDir, "skill-map.db");
-    if (await pathExists2(settingsPath) && !this.force) {
+    const settingsPath = defaultSettingsPath(scopeRoot);
+    const localPath = defaultLocalSettingsPath(scopeRoot);
+    const ignorePath = defaultIgnoreFilePath(scopeRoot);
+    const dbPath = defaultDbPath(scopeRoot);
+    if (await pathExists(settingsPath) && !this.force) {
       this.context.stderr.write(tx(INIT_TEXTS.alreadyInitialised, { settingsPath }));
-      emitDoneStderr(this.context.stderr, elapsed);
       return ExitCode.Error;
     }
     if (this.dryRun) {
@@ -8714,15 +8826,14 @@ var InitCommand = class extends Command8 {
         global: this.global,
         noScan: this.noScan
       });
-      emitDoneStderr(this.context.stderr, elapsed);
       return ExitCode.Ok;
     }
     await mkdir2(skillMapDir, { recursive: true });
     await writeFile(settingsPath, JSON.stringify({ schemaVersion: 1 }, null, 2) + "\n");
-    if (!await pathExists2(localPath) || this.force) {
+    if (!await pathExists(localPath) || this.force) {
       await writeFile(localPath, "{}\n");
     }
-    if (!await pathExists2(ignorePath) || this.force) {
+    if (!await pathExists(ignorePath) || this.force) {
       await writeFile(ignorePath, loadBundledIgnoreText());
     }
     if (!this.global) {
@@ -8740,25 +8851,20 @@ var InitCommand = class extends Command8 {
     await withSqlite({ databasePath: dbPath, autoBackup: false }, async () => {
     });
     this.context.stdout.write(tx(INIT_TEXTS.initialised, { skillMapDir }));
-    if (this.noScan) {
-      emitDoneStderr(this.context.stderr, elapsed);
-      return ExitCode.Ok;
-    }
-    const scanCode = await runFirstScan(scopeRoot, ctx.homedir, dbPath, this.strict, this.context.stdout, this.context.stderr);
-    emitDoneStderr(this.context.stderr, elapsed);
-    return scanCode;
+    if (this.noScan) return ExitCode.Ok;
+    return runFirstScan(scopeRoot, ctx.homedir, dbPath, this.strict, this.context.stdout, this.context.stderr);
   }
 };
 async function writeDryRunPlan(stdout, opts) {
   stdout.write(INIT_TEXTS.dryRunHeader);
-  if (!await pathExists2(opts.skillMapDir)) {
+  if (!await pathExists(opts.skillMapDir)) {
     stdout.write(tx(INIT_TEXTS.dryRunWouldCreateDir, { path: opts.skillMapDir }));
   }
   stdout.write(await dryRunFileMessage(opts.settingsPath));
-  if (!await pathExists2(opts.localPath) || opts.force) {
+  if (!await pathExists(opts.localPath) || opts.force) {
     stdout.write(await dryRunFileMessage(opts.localPath));
   }
-  if (!await pathExists2(opts.ignorePath) || opts.force) {
+  if (!await pathExists(opts.ignorePath) || opts.force) {
     stdout.write(await dryRunFileMessage(opts.ignorePath));
   }
   if (!opts.global) await writeDryRunGitignorePlan(stdout, opts.scopeRoot);
@@ -8768,7 +8874,7 @@ async function writeDryRunPlan(stdout, opts) {
   );
 }
 async function dryRunFileMessage(path) {
-  return await pathExists2(path) ? tx(INIT_TEXTS.dryRunWouldOverwriteFile, { path }) : tx(INIT_TEXTS.dryRunWouldWriteFile, { path });
+  return await pathExists(path) ? tx(INIT_TEXTS.dryRunWouldOverwriteFile, { path }) : tx(INIT_TEXTS.dryRunWouldWriteFile, { path });
 }
 async function writeDryRunGitignorePlan(stdout, scopeRoot) {
   const wouldAdd = await previewGitignoreEntries(scopeRoot, GITIGNORE_ENTRIES);
@@ -8848,7 +8954,7 @@ async function runFirstScan(scopeRoot, homedir2, dbPath, strict, stdout, stderr)
 }
 async function previewGitignoreEntries(scopeRoot, entries) {
   const path = join10(scopeRoot, ".gitignore");
-  const body = await pathExists2(path) ? await readFile2(path, "utf8") : "";
+  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("#"))
   );
@@ -8857,7 +8963,7 @@ async function previewGitignoreEntries(scopeRoot, entries) {
 async function ensureGitignoreEntries(scopeRoot, entries) {
   const path = join10(scopeRoot, ".gitignore");
   let body = "";
-  if (await pathExists2(path)) {
+  if (await pathExists(path)) {
     body = await readFile2(path, "utf8");
   }
   const present = new Set(
@@ -8877,7 +8983,7 @@ async function ensureGitignoreEntries(scopeRoot, entries) {
 }
 
 // cli/commands/history.ts
-import { Command as Command9, Option as Option9 } from "clipanion";
+import { Command as Command10, Option as Option10 } from "clipanion";
 
 // cli/i18n/option-validators.texts.ts
 var OPTION_VALIDATORS_TEXTS = {
@@ -8964,9 +9070,9 @@ function parseStatuses(input, stderr) {
   }
   return parts;
 }
-var HistoryCommand = class extends Command9 {
+var HistoryCommand = class extends SmCommand {
   static paths = [["history"]];
-  static usage = Command9.Usage({
+  static usage = Command10.Usage({
     category: "History",
     description: "Filter execution records. --json emits an array conforming to execution-record.schema.json.",
     details: `
@@ -8986,24 +9092,19 @@ var HistoryCommand = class extends Command9 {
       ["Machine-readable, scoped to one node", "$0 history -n skills/foo.md --json"]
     ]
   });
-  global = Option9.Boolean("-g,--global", false);
-  db = Option9.String("--db", { required: false });
-  node = Option9.String("-n", { required: false });
-  action = Option9.String("--action", { required: false });
-  status = Option9.String("--status", { required: false });
-  since = Option9.String("--since", { required: false });
-  until = Option9.String("--until", { required: false });
-  limit = Option9.String("--limit", { required: false });
-  json = Option9.Boolean("--json", false);
-  quiet = Option9.Boolean("--quiet", false);
+  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 });
   // 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
   // branch is single-purpose; splitting per flag would distance the
   // validations from the filter they shape.
   // eslint-disable-next-line complexity
-  async execute() {
-    const elapsed = startElapsed();
+  async run() {
     const filter = {};
     if (this.node !== void 0) filter.nodePath = this.node;
     if (this.action !== void 0) filter.actionId = this.action;
@@ -9038,14 +9139,13 @@ var HistoryCommand = class extends Command9 {
       } else {
         this.context.stdout.write(renderTable(rows));
       }
-      emitDoneStderr(this.context.stderr, elapsed, this.quiet);
       return ExitCode.Ok;
     });
   }
 };
-var HistoryStatsCommand = class extends Command9 {
+var HistoryStatsCommand = class extends SmCommand {
   static paths = [["history", "stats"]];
-  static usage = Command9.Usage({
+  static usage = Command10.Usage({
     category: "History",
     description: "Aggregate counts, tokens, periods, top nodes, and error rates over state_executions. --json conforms to history-stats.schema.json.",
     details: `
@@ -9063,20 +9163,16 @@ var HistoryStatsCommand = class extends Command9 {
       ["Top 5 nodes, JSON", "$0 history stats --top 5 --json"]
     ]
   });
-  global = Option9.Boolean("-g,--global", false);
-  db = Option9.String("--db", { required: false });
-  since = Option9.String("--since", { required: false });
-  until = Option9.String("--until", { required: false });
-  period = Option9.String("--period", { required: false });
-  top = Option9.String("--top", { required: false });
-  json = Option9.Boolean("--json", false);
-  quiet = Option9.Boolean("--quiet", false);
+  since = Option10.String("--since", { required: false });
+  until = Option10.String("--until", { required: false });
+  period = Option10.String("--period", { required: false });
+  top = Option10.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`.
   // eslint-disable-next-line complexity
-  async execute() {
-    const elapsed = startElapsed();
+  async run() {
+    const elapsed = this.elapsed;
     let sinceMs = null;
     let untilMs = Date.now();
     if (this.since !== void 0) {
@@ -9140,7 +9236,6 @@ var HistoryStatsCommand = class extends Command9 {
       } else {
         this.context.stdout.write(renderStats(stats));
       }
-      emitDoneStderr(this.context.stderr, elapsed, this.quiet);
       return ExitCode.Ok;
     });
   }
@@ -9161,8 +9256,8 @@ function renderTable(rows) {
     HISTORY_TEXTS.tableHeaderTokens,
     HISTORY_TEXTS.tableHeaderNodes
   );
-  const sep4 = "-".repeat(header.length);
-  const lines = [header, sep4];
+  const sep5 = "-".repeat(header.length);
+  const lines = [header, sep5];
   for (const r of rows) {
     const tokens = `${r.tokensIn ?? 0}/${r.tokensOut ?? 0}`;
     const duration = r.durationMs === null || r.durationMs === void 0 ? "-" : formatElapsed(r.durationMs);
@@ -9252,7 +9347,7 @@ function formatRow(...cols) {
 
 // cli/commands/jobs.ts
 import { unlink } from "fs/promises";
-import { Command as Command10, Option as Option10 } from "clipanion";
+import { Command as Command11, Option as Option11 } from "clipanion";
 
 // kernel/jobs/orphan-files.ts
 import { readdirSync as readdirSync6, statSync as statSync4 } from "fs";
@@ -9260,8 +9355,8 @@ import { join as join11, resolve as resolve15 } from "path";
 function findOrphanJobFiles(jobsDir, referencedPaths) {
   let entries;
   try {
-    const stat4 = statSync4(jobsDir);
-    if (!stat4.isDirectory()) {
+    const stat3 = statSync4(jobsDir);
+    if (!stat3.isDirectory()) {
       return { orphanFilePaths: [], referencedCount: referencedPaths.size };
     }
     entries = readdirSync6(jobsDir);
@@ -9298,9 +9393,9 @@ var JOBS_TEXTS = {
 };
 
 // cli/commands/jobs.ts
-var JobPruneCommand = class extends Command10 {
+var JobPruneCommand = class extends SmCommand {
   static paths = [["job", "prune"]];
-  static usage = Command10.Usage({
+  static usage = Command11.Usage({
     category: "Jobs",
     description: "Retention GC for completed / failed jobs (per config policy). --orphan-files removes MD files with no DB row.",
     details: `
@@ -9327,16 +9422,13 @@ var JobPruneCommand = class extends Command10 {
       ["Preview without touching the DB", "$0 job prune --dry-run --json"]
     ]
   });
-  orphanFiles = Option10.Boolean("--orphan-files", false, {
+  orphanFiles = Option11.Boolean("--orphan-files", false, {
     description: "Also remove MD files in .skill-map/jobs/ that have no matching state_jobs row."
   });
-  dryRun = Option10.Boolean("-n,--dry-run", false, {
+  dryRun = Option11.Boolean("-n,--dry-run", false, {
     description: "Report what would be pruned without touching the DB or filesystem."
   });
-  json = Option10.Boolean("--json", false, {
-    description: "Emit a structured prune-result document on stdout."
-  });
-  async execute() {
+  async run() {
     const ctx = defaultRuntimeContext();
     const dbPath = defaultProjectDbPath(ctx);
     const jobsDir = defaultProjectJobsDir(ctx);
@@ -9450,7 +9542,7 @@ function formatPolicy(seconds) {
 }
 
 // cli/commands/list.ts
-import { Command as Command11, Option as Option11 } from "clipanion";
+import { Command as Command12, Option as Option12 } from "clipanion";
 
 // cli/i18n/list.texts.ts
 var LIST_TEXTS = {
@@ -9476,9 +9568,9 @@ var SORT_BY = {
   external_refs_count: { column: "externalRefsCount", direction: "desc" }
 };
 var PATH_COL_WIDTH = 50;
-var ListCommand = class extends Command11 {
+var ListCommand = class extends SmCommand {
   static paths = [["list"]];
-  static usage = Command11.Usage({
+  static usage = Command12.Usage({
     category: "Browse",
     description: "Tabular listing of nodes. --json emits an array conforming to node.schema.json.",
     details: `
@@ -9499,14 +9591,11 @@ var ListCommand = class extends Command11 {
       ["Only nodes with issues, machine-readable", "$0 list --issue --json"]
     ]
   });
-  global = Option11.Boolean("-g,--global", false);
-  db = Option11.String("--db", { required: false });
-  kind = Option11.String("--kind", { required: false });
-  issue = Option11.Boolean("--issue", false);
-  sortBy = Option11.String("--sort-by", { required: false });
-  limit = Option11.String("--limit", { required: false });
-  json = Option11.Boolean("--json", false);
-  async execute() {
+  kind = Option12.String("--kind", { required: false });
+  issue = Option12.Boolean("--issue", false);
+  sortBy = Option12.String("--sort-by", { required: false });
+  limit = Option12.String("--limit", { required: false });
+  async run() {
     let sortColumn = "path";
     let sortDirection = "asc";
     if (this.sortBy !== void 0) {
@@ -9577,8 +9666,8 @@ function renderTable2(nodes, issuesByNode) {
     LIST_TEXTS.tableHeaderIssues,
     LIST_TEXTS.tableHeaderBytes
   );
-  const sep4 = "-".repeat(header.length);
-  const lines = [header, sep4];
+  const sep5 = "-".repeat(header.length);
+  const lines = [header, sep5];
   for (const node of nodes) {
     lines.push(
       formatRow2(
@@ -9607,7 +9696,7 @@ function formatRow2(path, kind, out, inCount, ext, issues, bytes) {
 }
 
 // cli/commands/orphans.ts
-import { Command as Command12, Option as Option12 } from "clipanion";
+import { Command as Command13, Option as Option13 } from "clipanion";
 
 // cli/i18n/orphans.texts.ts
 var ORPHANS_TEXTS = {
@@ -9660,9 +9749,9 @@ async function findActiveOrphanIssues(adapter, predicate) {
 function isStringArray(v) {
   return Array.isArray(v) && v.every((s) => typeof s === "string");
 }
-var OrphansCommand = class extends Command12 {
+var OrphansCommand = class extends SmCommand {
   static paths = [["orphans"]];
-  static usage = Command12.Usage({
+  static usage = Command13.Usage({
     category: "Browse",
     description: "List orphan / auto-rename issues from the last scan. --json emits an array conforming to issue.schema.json.",
     details: `
@@ -9677,13 +9766,8 @@ var OrphansCommand = class extends Command12 {
       ["Just the ambiguous ones, JSON", "$0 orphans --kind ambiguous --json"]
     ]
   });
-  global = Option12.Boolean("-g,--global", false);
-  db = Option12.String("--db", { required: false });
-  kind = Option12.String("--kind", { required: false });
-  json = Option12.Boolean("--json", false);
-  quiet = Option12.Boolean("--quiet", false);
-  async execute() {
-    const elapsed = startElapsed();
+  kind = Option13.String("--kind", { required: false });
+  async run() {
     let ruleFilter = null;
     if (this.kind !== void 0) {
       const map = {
@@ -9714,14 +9798,13 @@ var OrphansCommand = class extends Command12 {
       } else {
         this.context.stdout.write(renderOrphans(found.map((f) => f.issue)));
       }
-      emitDoneStderr(this.context.stderr, elapsed, this.quiet);
       return ExitCode.Ok;
     });
   }
 };
-var OrphansReconcileCommand = class extends Command12 {
+var OrphansReconcileCommand = class extends SmCommand {
   static paths = [["orphans", "reconcile"]];
-  static usage = Command12.Usage({
+  static usage = Command13.Usage({
     category: "Browse",
     description: "Migrate state_* FKs from an orphan path to a live node, resolving the orphan issue.",
     details: `
@@ -9737,14 +9820,10 @@ var OrphansReconcileCommand = class extends Command12 {
       ["Reattach orphan history", "$0 orphans reconcile skills/old.md --to skills/new.md"]
     ]
   });
-  global = Option12.Boolean("-g,--global", false);
-  db = Option12.String("--db", { required: false });
-  orphanPath = Option12.String({ required: true });
-  to = Option12.String("--to", { required: true });
-  dryRun = Option12.Boolean("-n,--dry-run", false);
-  quiet = Option12.Boolean("--quiet", false);
-  async execute() {
-    const elapsed = startElapsed();
+  orphanPath = Option13.String({ required: true });
+  to = Option13.String("--to", { required: true });
+  dryRun = Option13.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;
     return withSqlite({ databasePath: dbPath, autoBackup: false }, async (adapter) => {
@@ -9807,14 +9886,13 @@ var OrphansReconcileCommand = class extends Command12 {
           )
         );
       }
-      emitDoneStderr(this.context.stderr, elapsed, this.quiet);
       return ExitCode.Ok;
     });
   }
 };
-var OrphansUndoRenameCommand = class extends Command12 {
+var OrphansUndoRenameCommand = class extends SmCommand {
   static paths = [["orphans", "undo-rename"]];
-  static usage = Command12.Usage({
+  static usage = Command13.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: `
@@ -9834,15 +9912,11 @@ var OrphansUndoRenameCommand = class extends Command12 {
       ["Undo an ambiguous, picking a candidate", "$0 orphans undo-rename skills/new.md --from skills/old-a.md"]
     ]
   });
-  global = Option12.Boolean("-g,--global", false);
-  db = Option12.String("--db", { required: false });
-  newPath = Option12.String({ required: true });
-  from = Option12.String("--from", { required: false });
-  force = Option12.Boolean("--force", false);
-  dryRun = Option12.Boolean("-n,--dry-run", false);
-  quiet = Option12.Boolean("--quiet", false);
-  async execute() {
-    const elapsed = startElapsed();
+  newPath = Option13.String({ required: true });
+  from = Option13.String("--from", { required: false });
+  force = Option13.Boolean("--force", false);
+  dryRun = Option13.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;
     return withSqlite({ databasePath: dbPath, autoBackup: false }, async (adapter) => {
@@ -9914,7 +9988,6 @@ var OrphansUndoRenameCommand = class extends Command12 {
           rows: summaryTotal(summary)
         })
       );
-      emitDoneStderr(this.context.stderr, elapsed, this.quiet);
       return ExitCode.Ok;
     });
   }
@@ -10008,7 +10081,7 @@ 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 Command13, Option as Option13 } from "clipanion";
+import { Command as Command14, Option as Option14 } from "clipanion";
 
 // cli/i18n/plugins.texts.ts
 var PLUGINS_TEXTS = {
@@ -10151,17 +10224,15 @@ function builtInRows(resolveEnabled) {
     };
   });
 }
-var PluginsListCommand = class extends Command13 {
+var PluginsListCommand = class extends SmCommand {
   static paths = [["plugins", "list"]];
-  static usage = Command13.Usage({
+  static usage = Command14.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."
   });
-  global = Option13.Boolean("-g,--global", false);
-  pluginDir = Option13.String("--plugin-dir", { required: false });
-  json = Option13.Boolean("--json", false);
-  async execute() {
+  pluginDir = Option14.String("--plugin-dir", { required: false });
+  async run() {
     const plugins = await loadAll({ global: this.global, pluginDir: this.pluginDir });
     const resolveEnabled = await buildResolver(this.global);
     const builtIns2 = builtInRows(resolveEnabled);
@@ -10220,24 +10291,24 @@ function renderPluginRow(p) {
     tail
   }) + "\n";
 }
-var PluginsShowCommand = class extends Command13 {
+var PluginsShowCommand = class extends SmCommand {
   static paths = [["plugins", "show"]];
-  static usage = Command13.Usage({
+  static usage = Command14.Usage({
     category: "Plugins",
     description: "Show a single plugin's manifest + loaded extensions."
   });
-  id = Option13.String({ required: true });
-  global = Option13.Boolean("-g,--global", false);
-  pluginDir = Option13.String("--plugin-dir", { required: false });
-  json = Option13.Boolean("--json", false);
-  async execute() {
+  id = Option14.String({ required: true });
+  pluginDir = Option14.String("--plugin-dir", { required: false });
+  async run() {
     const plugins = await loadAll({ global: this.global, pluginDir: this.pluginDir });
     const resolveEnabled = await buildResolver(this.global);
     const builtIns2 = builtInRows(resolveEnabled);
     const builtIn = builtIns2.find((b) => b.id === this.id);
     const match = plugins.find((p) => p.id === this.id);
     if (!builtIn && !match) {
-      this.context.stderr.write(tx(PLUGINS_TEXTS.pluginNotFound, { id: this.id }) + "\n");
+      this.context.stderr.write(
+        tx(PLUGINS_TEXTS.pluginNotFound, { id: sanitizeForTerminal(this.id) }) + "\n"
+      );
       return ExitCode.NotFound;
     }
     if (this.json) {
@@ -10423,15 +10494,14 @@ function collectExplorationDirWarnings(plugins, homedir2) {
   });
   return out;
 }
-var PluginsDoctorCommand = class extends Command13 {
+var PluginsDoctorCommand = class extends SmCommand {
   static paths = [["plugins", "doctor"]];
-  static usage = Command13.Usage({
+  static usage = Command14.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."
   });
-  global = Option13.Boolean("-g,--global", false);
-  pluginDir = Option13.String("--plugin-dir", { required: false });
+  pluginDir = Option14.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
@@ -10439,7 +10509,7 @@ var PluginsDoctorCommand = class extends Command13 {
   // `collectApplicableKindWarnings`, `collectExplorationDirWarnings`)
   // already encapsulate the data gathering.
   // eslint-disable-next-line complexity
-  async execute() {
+  async run() {
     const plugins = await loadAll({ global: this.global, pluginDir: this.pluginDir });
     const resolveEnabled = await buildResolver(this.global);
     const builtIns2 = builtInRows(resolveEnabled);
@@ -10548,17 +10618,25 @@ function resolveToggleTarget(id, catalogue, verb) {
   if (id.includes("/")) {
     const [bundleId, extId, ...rest] = id.split("/");
     if (!bundleId || !extId || rest.length > 0) {
-      return { error: tx(PLUGINS_TEXTS.qualifiedIdUnknownBundle, { bundleId: id }) };
+      return {
+        error: tx(PLUGINS_TEXTS.qualifiedIdUnknownBundle, {
+          bundleId: sanitizeForTerminal(id)
+        })
+      };
     }
     const bundle2 = catalogue.find((b) => b.id === bundleId);
     if (!bundle2) {
-      return { error: tx(PLUGINS_TEXTS.qualifiedIdUnknownBundle, { bundleId }) };
+      return {
+        error: tx(PLUGINS_TEXTS.qualifiedIdUnknownBundle, {
+          bundleId: sanitizeForTerminal(bundleId)
+        })
+      };
     }
     if (bundle2.granularity === "bundle") {
       return {
         error: tx(PLUGINS_TEXTS.granularityBundleRejectsQualified, {
-          bundleId,
-          extId,
+          bundleId: sanitizeForTerminal(bundleId),
+          extId: sanitizeForTerminal(extId),
           verb
         })
       };
@@ -10566,9 +10644,9 @@ function resolveToggleTarget(id, catalogue, verb) {
     if (!bundle2.extensionIds.includes(extId)) {
       return {
         error: tx(PLUGINS_TEXTS.qualifiedIdNotFound, {
-          id,
-          bundleId,
-          extId
+          id: sanitizeForTerminal(id),
+          bundleId: sanitizeForTerminal(bundleId),
+          extId: sanitizeForTerminal(extId)
         })
       };
     }
@@ -10576,34 +10654,30 @@ function resolveToggleTarget(id, catalogue, verb) {
   }
   const bundle = catalogue.find((b) => b.id === id);
   if (!bundle) {
-    return { error: tx(PLUGINS_TEXTS.pluginNotFound, { id }) };
+    return { error: tx(PLUGINS_TEXTS.pluginNotFound, { id: sanitizeForTerminal(id) }) };
   }
   if (bundle.granularity === "extension") {
     return {
       error: tx(PLUGINS_TEXTS.granularityExtensionRejectsBundleId, {
-        bundleId: id,
+        bundleId: sanitizeForTerminal(id),
         verb
       })
     };
   }
   return { key: bundle.id };
 }
-var TogglePluginsBase = class extends Command13 {
-  global = Option13.Boolean("-g,--global", false);
-  all = Option13.Boolean("--all", false);
-  id = Option13.String({ required: false });
+var TogglePluginsBase = class extends SmCommand {
+  all = Option14.Boolean("--all", false);
+  id = Option14.String({ required: false });
   // eslint-disable-next-line complexity
   async toggle(enabled) {
-    const elapsed = startElapsed();
     const verb = enabled ? "enable" : "disable";
     if (this.all && this.id) {
       this.context.stderr.write(PLUGINS_TEXTS.toggleBothIdAndAll);
-      emitDoneStderr(this.context.stderr, elapsed);
       return ExitCode.Error;
     }
     if (!this.all && !this.id) {
       this.context.stderr.write(PLUGINS_TEXTS.toggleNeitherIdNorAll);
-      emitDoneStderr(this.context.stderr, elapsed);
       return ExitCode.Error;
     }
     const plugins = await loadAll({
@@ -10618,7 +10692,6 @@ var TogglePluginsBase = class extends Command13 {
       const resolved = resolveToggleTarget(this.id, catalogue, verb);
       if ("error" in resolved) {
         this.context.stderr.write(tx(PLUGINS_TEXTS.toggleResolveError, { error: resolved.error }));
-        emitDoneStderr(this.context.stderr, elapsed);
         return ExitCode.NotFound;
       }
       targets = [resolved.key];
@@ -10641,13 +10714,12 @@ var TogglePluginsBase = class extends Command13 {
         this.context.stdout.write(tx(PLUGINS_TEXTS.toggleAppliedManyRow, { id }));
       }
     }
-    emitDoneStderr(this.context.stderr, elapsed);
     return ExitCode.Ok;
   }
 };
 var PluginsEnableCommand = class extends TogglePluginsBase {
   static paths = [["plugins", "enable"]];
-  static usage = Command13.Usage({
+  static usage = Command14.Usage({
     category: "Plugins",
     description: "Enable a plugin (or --all). Persists in config_plugins.",
     details: `
@@ -10663,13 +10735,13 @@ var PluginsEnableCommand = class extends TogglePluginsBase {
       with directed guidance.
     `
   });
-  async execute() {
+  async run() {
     return this.toggle(true);
   }
 };
 var PluginsDisableCommand = class extends TogglePluginsBase {
   static paths = [["plugins", "disable"]];
-  static usage = Command13.Usage({
+  static usage = Command14.Usage({
     category: "Plugins",
     description: "Disable a plugin (or --all). Persists in config_plugins; does not delete files.",
     details: `
@@ -10685,7 +10757,7 @@ var PluginsDisableCommand = class extends TogglePluginsBase {
       with directed guidance.
     `
   });
-  async execute() {
+  async run() {
     return this.toggle(false);
   }
 };
@@ -10706,7 +10778,7 @@ var PLUGIN_COMMANDS = [
 // cli/commands/refresh.ts
 import { readFile as readFile3 } from "fs/promises";
 import { resolve as resolve18 } from "path";
-import { Command as Command14, Option as Option14 } from "clipanion";
+import { Command as Command15, Option as Option15 } from "clipanion";
 
 // cli/i18n/refresh.texts.ts
 var REFRESH_TEXTS = {
@@ -10747,9 +10819,9 @@ function assertContained2(cwd, rel) {
 }
 
 // cli/commands/refresh.ts
-var RefreshCommand = class extends Command14 {
+var RefreshCommand = class extends SmCommand {
   static paths = [["refresh"]];
-  static usage = Command14.Usage({
+  static usage = Command15.Usage({
     category: "Scan",
     description: "Refresh enrichment rows: granular (single node) or batch (every stale row).",
     details: `
@@ -10774,11 +10846,11 @@ var RefreshCommand = class extends Command14 {
       ["Refresh every node with stale enrichments", "$0 refresh --stale"]
     ]
   });
-  nodePath = Option14.String({ name: "node", required: false });
-  stale = Option14.Boolean("--stale", false, {
+  nodePath = Option15.String({ name: "node", required: false });
+  stale = Option15.Boolean("--stale", false, {
     description: "Refresh every node whose probabilistic enrichment row is flagged stale=1."
   });
-  noPlugins = Option14.Boolean("--no-plugins", false, {
+  noPlugins = Option15.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
@@ -10787,7 +10859,7 @@ var RefreshCommand = class extends Command14 {
   // catch, plus the `if (probSkipCount > 0)` advisory. The inner work
   // already lives in `#resolveTargetNodes` and `#runDetExtractorsAcrossNodes`.
   // eslint-disable-next-line complexity
-  async execute() {
+  async run() {
     if (this.stale && this.nodePath !== void 0) {
       this.context.stderr.write(REFRESH_TEXTS.nodeAndStaleMutex);
       return ExitCode.Error;
@@ -10963,7 +11035,7 @@ function stripFrontmatterFence(text) {
 var REFRESH_COMMANDS = [RefreshCommand];
 
 // cli/commands/scan.ts
-import { Command as Command16, Option as Option16 } from "clipanion";
+import { Command as Command17, Option as Option17 } from "clipanion";
 
 // cli/i18n/scan.texts.ts
 var SCAN_TEXTS = {
@@ -11006,8 +11078,156 @@ var SCAN_TEXTS = {
   compareDeltaIssueRemoved: "- [{{severity}}] {{ruleId}}: {{message}}"
 };
 
-// cli/commands/watch.ts
-import { Command as Command15, Option as Option15 } from "clipanion";
+// cli/util/scan-runner.ts
+async function runScanForCommand(opts) {
+  const ctx = opts.ctx ?? defaultRuntimeContext();
+  const dbPath = defaultProjectDbPath(ctx);
+  const kernel = createKernel();
+  const pluginRuntime = await preparePluginRuntime(opts);
+  const extensions = registerExtensions(kernel, pluginRuntime, opts);
+  let cfg;
+  try {
+    cfg = loadConfig({ scope: "project", strict: opts.strict, ...ctx }).effective;
+  } catch (err) {
+    return { kind: "config-error", message: formatErrorMessage(err) };
+  }
+  const ignoreFilter = buildScanIgnoreFilter(cfg, ctx.cwd);
+  const strict = opts.strict || cfg.scan.strict === true;
+  const loadPrior = makePriorLoader(opts.noBuiltIns, strict);
+  const runScanWith = makeScanRunner(kernel, opts, ignoreFilter, strict, extensions);
+  const willPersist = !opts.noBuiltIns && !opts.dryRun;
+  return willPersist ? runPersistPath(opts, dbPath, strict, loadPrior, runScanWith) : runEphemeralPath(opts, dbPath, strict, loadPrior, runScanWith);
+}
+async function preparePluginRuntime(opts) {
+  const pluginRuntime = opts.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: "project" });
+  for (const warn of pluginRuntime.warnings) opts.stderr.write(`${warn}
+`);
+  return pluginRuntime;
+}
+function registerExtensions(kernel, pluginRuntime, opts) {
+  const extensions = composeScanExtensions({
+    noBuiltIns: opts.noBuiltIns,
+    pluginRuntime
+  });
+  if (!opts.noBuiltIns) {
+    const enabledBuiltIns = filterBuiltInManifests(listBuiltIns(), pluginRuntime.resolveEnabled);
+    for (const manifest of enabledBuiltIns) kernel.registry.register(manifest);
+  }
+  for (const manifest of pluginRuntime.manifests) kernel.registry.register(manifest);
+  return extensions;
+}
+function buildScanIgnoreFilter(cfg, cwd) {
+  const ignoreFileText = readIgnoreFileText(cwd);
+  const ignoreFilterOpts = {};
+  if (cfg.ignore.length > 0) ignoreFilterOpts.configIgnore = cfg.ignore;
+  if (ignoreFileText !== void 0) ignoreFilterOpts.ignoreFileText = ignoreFileText;
+  return buildIgnoreFilter(ignoreFilterOpts);
+}
+function makePriorLoader(noBuiltIns, strict) {
+  return async (adapter) => {
+    if (noBuiltIns) return null;
+    const loaded = await adapter.scans.load();
+    if (loaded.nodes.length === 0) return null;
+    if (strict) {
+      const validators = loadSchemaValidators();
+      const result = validators.validate("scan-result", loaded);
+      if (!result.ok) {
+        throw new Error(tx(SCAN_TEXTS.priorSchemaValidationFailed, { errors: result.errors }));
+      }
+    }
+    return loaded;
+  };
+}
+function makeScanRunner(kernel, opts, ignoreFilter, strict, extensions) {
+  return async (prior, priorExtractorRuns) => {
+    if (opts.changed && prior === null) {
+      opts.stderr.write(SCAN_TEXTS.changedNoPriorWarning);
+    }
+    const runOptions = {
+      roots: opts.roots,
+      // Hardcoded `'project'`: spec § Global flags lists `-g/--global`
+      // as universal, but the per-verb § Scan table does not list it
+      // and the semantics of "scan global" are undefined. The
+      // ScanCommand surface accepts `-g` (inherited from SmCommand)
+      // but ignores it here. Wire to `opts.scope` once spec defines
+      // the contract.
+      scope: "project",
+      tokenize: !opts.noTokens,
+      ignoreFilter,
+      strict,
+      emitter: createCliProgressEmitter(opts.stderr)
+    };
+    if (extensions) runOptions.extensions = extensions;
+    if (prior) {
+      runOptions.priorSnapshot = prior;
+      runOptions.enableCache = opts.changed;
+    }
+    if (priorExtractorRuns) runOptions.priorExtractorRuns = priorExtractorRuns;
+    return runScanWithRenames(kernel, runOptions);
+  };
+}
+async function runPersistPath(opts, dbPath, strict, loadPrior, runScanWith) {
+  let outcome;
+  try {
+    outcome = await withSqlite({ databasePath: dbPath }, async (adapter) => {
+      const prior = await loadPrior(adapter);
+      const priorExtractorRuns = opts.changed && prior ? await adapter.scans.loadExtractorRuns() : void 0;
+      let scanned;
+      try {
+        scanned = await runScanWith(prior, priorExtractorRuns);
+      } catch (err) {
+        return { kind: "scan-error", message: formatErrorMessage(err) };
+      }
+      if (scanned.result.stats.nodesCount === 0 && !opts.allowEmpty) {
+        const counts = await adapter.scans.countRows();
+        const existing = counts.nodes + counts.links + counts.issues;
+        if (existing > 0) return { kind: "guard", existing };
+      }
+      await adapter.scans.persist(scanned.result, {
+        renameOps: scanned.renameOps,
+        extractorRuns: scanned.extractorRuns,
+        enrichments: scanned.enrichments
+      });
+      return { kind: "ok", ...scanned };
+    });
+  } catch (err) {
+    return { kind: "scan-error", message: formatErrorMessage(err) };
+  }
+  if (outcome.kind === "scan-error") return outcome;
+  if (outcome.kind === "guard") return { kind: "guard-trip", existing: outcome.existing };
+  return {
+    kind: "ok",
+    result: outcome.result,
+    renameOps: outcome.renameOps,
+    persistedTo: dbPath,
+    dbPath,
+    strict
+  };
+}
+async function runEphemeralPath(opts, dbPath, strict, loadPrior, runScanWith) {
+  let prior;
+  try {
+    prior = opts.noBuiltIns ? null : await tryWithSqlite({ databasePath: dbPath, autoBackup: false }, loadPrior);
+  } catch (err) {
+    return { kind: "scan-error", message: formatErrorMessage(err) };
+  }
+  try {
+    const scanned = await runScanWith(prior);
+    return {
+      kind: "ok",
+      result: scanned.result,
+      renameOps: scanned.renameOps,
+      persistedTo: null,
+      dbPath,
+      strict
+    };
+  } catch (err) {
+    return { kind: "scan-error", message: formatErrorMessage(err) };
+  }
+}
+
+// cli/commands/watch.ts
+import { Command as Command16, Option as Option16 } from "clipanion";
 
 // cli/i18n/watch.texts.ts
 var WATCH_TEXTS = {
@@ -11020,10 +11240,12 @@ var WATCH_TEXTS = {
   ready: "sm watch: ready. Press Ctrl+C to stop.\n",
   stopped: "sm watch: stopped after {{batchCount}} batch(es).\n",
   scannedSummary: "scanned {{nodes}} nodes / {{links}} links / {{issues}} issues in {{durationMs}}ms\n",
-  priorSchemaValidationFailed: "prior scan-result loaded from DB failed schema validation: {{errors}}"
+  priorSchemaValidationFailed: "prior scan-result loaded from DB failed schema validation: {{errors}}",
+  breakerTripped: "sm watch: {{count}} consecutive batch failures \u2014 shutting down. Last error: {{message}}\n"
 };
 
 // cli/commands/watch.ts
+var DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
 async function runWatchLoop(opts) {
   const { context } = opts;
   const runtimeCtx = defaultRuntimeContext();
@@ -11087,21 +11309,8 @@ async function runWatchLoop(opts) {
       runOptions.enableCache = true;
     }
     if (priorExtractorRuns) runOptions.priorExtractorRuns = priorExtractorRuns;
-    let result;
-    let renameOps;
-    let extractorRuns;
-    let enrichments;
-    try {
-      const ran = await runScanWithRenames(kernel, runOptions);
-      result = ran.result;
-      renameOps = ran.renameOps;
-      extractorRuns = ran.extractorRuns;
-      enrichments = ran.enrichments;
-    } catch (err) {
-      const message = formatErrorMessage(err);
-      context.stderr.write(tx(WATCH_TEXTS.scanFailed, { message }));
-      return;
-    }
+    const ran = await runScanWithRenames(kernel, runOptions);
+    const { result, renameOps, extractorRuns, enrichments } = ran;
     await withSqlite(
       { databasePath: dbPath },
       (writer) => writer.scans.persist(result, { renameOps, extractorRuns, enrichments })
@@ -11135,21 +11344,38 @@ async function runWatchLoop(opts) {
   const stopped = new Promise((r) => {
     stopResolve = r;
   });
+  const breakerLimit = opts.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES;
+  let consecutiveFailures = 0;
+  let exitCode2 = ExitCode.Ok;
+  const handleBatch = async () => {
+    if (stopRequested) return "stop";
+    batchCount++;
+    try {
+      await runOnePass();
+      consecutiveFailures = 0;
+    } catch (err) {
+      const message = formatErrorMessage(err);
+      context.stderr.write(tx(WATCH_TEXTS.batchFailed, { message }));
+      consecutiveFailures += 1;
+      if (breakerLimit > 0 && consecutiveFailures >= breakerLimit) {
+        context.stderr.write(
+          tx(WATCH_TEXTS.breakerTripped, { count: consecutiveFailures, message })
+        );
+        exitCode2 = ExitCode.Error;
+        return "stop";
+      }
+    }
+    if (opts.maxBatches !== void 0 && batchCount >= opts.maxBatches) return "stop";
+    return "continue";
+  };
   const watcher = createChokidarWatcher({
     roots: opts.roots,
     cwd,
     debounceMs,
     ignoreFilter,
     onBatch: async () => {
-      if (stopRequested) return;
-      batchCount++;
-      try {
-        await runOnePass();
-      } catch (err) {
-        const message = formatErrorMessage(err);
-        context.stderr.write(tx(WATCH_TEXTS.batchFailed, { message }));
-      }
-      if (opts.maxBatches !== void 0 && batchCount >= opts.maxBatches) {
+      const next = await handleBatch();
+      if (next === "stop") {
         stopRequested = true;
         stopResolve?.();
       }
@@ -11176,11 +11402,11 @@ async function runWatchLoop(opts) {
   if (!opts.json) {
     context.stderr.write(tx(WATCH_TEXTS.stopped, { batchCount }));
   }
-  return ExitCode.Ok;
+  return exitCode2;
 }
-var WatchCommand = class extends Command15 {
+var WatchCommand = class extends SmCommand {
   static paths = [["watch"]];
-  static usage = Command15.Usage({
+  static usage = Command16.Usage({
     category: "Scan",
     description: "Watch roots and run an incremental scan after each debounced batch of filesystem events.",
     details: `
@@ -11204,36 +11430,55 @@ var WatchCommand = class extends Command15 {
       ["Stream ScanResult per batch as ndjson", "$0 watch --json"]
     ]
   });
-  roots = Option15.Rest({ name: "roots" });
-  json = Option15.Boolean("--json", false, {
-    description: "Emit one ScanResult document per batch as ndjson on stdout."
-  });
-  noTokens = Option15.Boolean("--no-tokens", false, {
+  roots = Option16.Rest({ name: "roots" });
+  noTokens = Option16.Boolean("--no-tokens", false, {
     description: "Skip per-node token counts (cl100k_base BPE)."
   });
-  strict = Option15.Boolean("--strict", false, {
+  strict = Option16.Boolean("--strict", false, {
     description: "Promote frontmatter-validation findings from warn to error inside each batch. Does not change the watcher exit code."
   });
-  noPlugins = Option15.Boolean("--no-plugins", false, {
+  noPlugins = Option16.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery for the watcher session."
   });
-  async execute() {
+  maxConsecutiveFailures = Option16.String("--max-consecutive-failures", {
+    required: false,
+    description: "Shut down with exit 2 after N consecutive batch failures (default 5; 0 disables the breaker)."
+  });
+  // Long-running verb — the watcher prints its own "stopped" line on
+  // SIGINT / SIGTERM. Adding `done in <…>` after that would be noise.
+  emitElapsed = false;
+  async run() {
     const roots = this.roots.length > 0 ? this.roots : ["."];
-    return runWatchLoop({
+    const breaker = parseBreakerLimit(this.maxConsecutiveFailures, this.context.stderr);
+    if (breaker === null) return ExitCode.Error;
+    const watchOpts = {
       roots,
       json: this.json,
       noTokens: this.noTokens,
       strict: this.strict,
       noPlugins: this.noPlugins,
       context: this.context
-    });
+    };
+    if (breaker !== void 0) watchOpts.maxConsecutiveFailures = breaker;
+    return runWatchLoop(watchOpts);
   }
 };
+function parseBreakerLimit(raw, stderr) {
+  if (raw === void 0) return void 0;
+  const trimmed = raw.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== trimmed) {
+    stderr.write(`sm watch: --max-consecutive-failures must be a non-negative integer (got ${raw})
+`);
+    return null;
+  }
+  return parsed;
+}
 
 // cli/commands/scan.ts
-var ScanCommand = class extends Command16 {
+var ScanCommand = class extends SmCommand {
   static paths = [["scan"]];
-  static usage = Command16.Usage({
+  static usage = Command17.Usage({
     category: "Scan",
     description: "Scan roots for markdown nodes, run extractors and rules.",
     details: `
@@ -11262,198 +11507,87 @@ var ScanCommand = class extends Command16 {
       ["What would the next incremental scan persist?", "$0 scan --changed -n --json"]
     ]
   });
-  roots = Option16.Rest({ name: "roots" });
-  json = Option16.Boolean("--json", false, {
-    description: "Emit a machine-readable ScanResult document on stdout."
-  });
-  noBuiltIns = Option16.Boolean("--no-built-ins", false, {
+  roots = Option17.Rest({ name: "roots" });
+  noBuiltIns = Option17.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 = Option16.Boolean("--no-plugins", false, {
+  noPlugins = Option17.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 = Option16.Boolean("--no-tokens", false, {
+  noTokens = Option17.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 = Option16.Boolean("-n,--dry-run", false, {
+  dryRun = Option17.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 = Option16.Boolean("--changed", false, {
+  changed = Option17.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 = Option16.Boolean("--allow-empty", false, {
+  allowEmpty = Option17.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 = Option16.Boolean("--strict", false, {
+  strict = Option17.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 = Option16.Boolean("--watch", false, {
+  watch = Option17.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`."
   });
-  // The biggest CLI orchestrator — watch alias dispatch + flag combo
-  // checks + plugin runtime + config + ignore filter + prior-snapshot
-  // load + persist branch (with stranded-orphan guard) + dry-run branch
-  // + JSON / human render with strict self-validation. The core scan
-  // pipeline lives in `runScan` / `runScanWithRenames`; the
-  // `loadPrior` and `runScanWith` closures below encapsulate the DB +
-  // option wiring. Splitting per branch would scatter Clipanion's
-  // `this.<flag>` reads from the validations they shape.
-  // eslint-disable-next-line complexity
-  async execute() {
-    if (this.watch) {
-      if (this.noBuiltIns || this.dryRun || this.changed || this.allowEmpty) {
-        this.context.stderr.write(SCAN_TEXTS.watchCannotCombine);
-        return ExitCode.Error;
-      }
-      const roots2 = this.roots.length > 0 ? this.roots : ["."];
-      return runWatchLoop({
-        roots: roots2,
-        json: this.json,
-        noTokens: this.noTokens,
-        strict: this.strict,
-        noPlugins: this.noPlugins,
-        context: this.context
-      });
-    }
+  async run() {
+    if (this.watch) return this.runWatchAlias();
     if (this.changed && this.noBuiltIns) {
       this.context.stderr.write(SCAN_TEXTS.changedWithoutBuiltIns);
       return ExitCode.Error;
     }
-    const kernel = createKernel();
     const roots = this.roots.length > 0 ? this.roots : ["."];
-    const pluginRuntime = this.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: "project" });
-    for (const warn of pluginRuntime.warnings) {
-      this.context.stderr.write(`${warn}
-`);
-    }
-    const extensions = composeScanExtensions({
+    const outcome = await runScanForCommand({
+      roots,
       noBuiltIns: this.noBuiltIns,
-      pluginRuntime
+      noPlugins: this.noPlugins,
+      noTokens: this.noTokens,
+      dryRun: this.dryRun,
+      changed: this.changed,
+      allowEmpty: this.allowEmpty,
+      strict: this.strict,
+      stderr: this.context.stderr
     });
-    if (!this.noBuiltIns) {
-      const enabledBuiltIns = filterBuiltInManifests(listBuiltIns(), pluginRuntime.resolveEnabled);
-      for (const manifest of enabledBuiltIns) kernel.registry.register(manifest);
-    }
-    for (const manifest of pluginRuntime.manifests) kernel.registry.register(manifest);
-    const ctx = defaultRuntimeContext();
-    const dbPath = defaultProjectDbPath(ctx);
-    let cfg;
-    try {
-      cfg = loadConfig({ scope: "project", strict: this.strict, ...ctx }).effective;
-    } catch (err) {
-      const message = formatErrorMessage(err);
-      this.context.stderr.write(tx(SCAN_TEXTS.scanFailure, { message }));
+    return outcome.kind === "ok" ? this.renderOutcome(outcome.result, outcome.persistedTo, outcome.dbPath, outcome.strict) : this.renderFailure(outcome);
+  }
+  /**
+   * `--watch` is a thin alias for the `sm watch` verb. Combining
+   * `--watch` with one-shot-only flags is incoherent — the watcher
+   * always persists incrementally over the prior snapshot.
+   */
+  async runWatchAlias() {
+    if (this.noBuiltIns || this.dryRun || this.changed || this.allowEmpty) {
+      this.context.stderr.write(SCAN_TEXTS.watchCannotCombine);
       return ExitCode.Error;
     }
-    const ignoreFileText = readIgnoreFileText(ctx.cwd);
-    const ignoreFilterOpts = {};
-    if (cfg.ignore.length > 0) ignoreFilterOpts.configIgnore = cfg.ignore;
-    if (ignoreFileText !== void 0) ignoreFilterOpts.ignoreFileText = ignoreFileText;
-    const ignoreFilter = buildIgnoreFilter(ignoreFilterOpts);
-    const strict = this.strict || cfg.scan.strict === true;
-    const loadPrior = async (adapter) => {
-      if (this.noBuiltIns) return null;
-      const loaded = await adapter.scans.load();
-      if (loaded.nodes.length === 0) return null;
-      if (strict) {
-        const validators = loadSchemaValidators();
-        const result2 = validators.validate("scan-result", loaded);
-        if (!result2.ok) {
-          throw new Error(tx(SCAN_TEXTS.priorSchemaValidationFailed, { errors: result2.errors }));
-        }
-      }
-      return loaded;
-    };
-    const runScanWith = async (prior, priorExtractorRuns) => {
-      if (this.changed && prior === null) {
-        this.context.stderr.write(SCAN_TEXTS.changedNoPriorWarning);
-      }
-      const runOptions = {
-        roots,
-        // `--global` for `sm scan` lands in Step 6 (config + onboarding).
-        // The orchestrator already accepts the scope override; the CLI
-        // surface defaults to `'project'` until the flag is wired.
-        scope: "project",
-        tokenize: !this.noTokens,
-        ignoreFilter,
-        strict,
-        emitter: createCliProgressEmitter(this.context.stderr)
-      };
-      if (extensions) runOptions.extensions = extensions;
-      if (prior) {
-        runOptions.priorSnapshot = prior;
-        runOptions.enableCache = this.changed;
-      }
-      if (priorExtractorRuns) runOptions.priorExtractorRuns = priorExtractorRuns;
-      return await runScanWithRenames(kernel, runOptions);
-    };
-    const willPersist = !this.noBuiltIns && !this.dryRun;
-    let result;
-    let renameOps;
-    let persistedTo = null;
-    let outcome;
-    if (willPersist) {
-      try {
-        outcome = await withSqlite({ databasePath: dbPath }, async (adapter) => {
-          const prior = await loadPrior(adapter);
-          const priorExtractorRuns = this.changed && prior ? await adapter.scans.loadExtractorRuns() : void 0;
-          let scanned;
-          try {
-            scanned = await runScanWith(prior, priorExtractorRuns);
-          } catch (err) {
-            const message = formatErrorMessage(err);
-            return { kind: "scan-error", message };
-          }
-          if (scanned.result.stats.nodesCount === 0 && !this.allowEmpty) {
-            const counts = await adapter.scans.countRows();
-            const existing = counts.nodes + counts.links + counts.issues;
-            if (existing > 0) return { kind: "guard", existing };
-          }
-          await adapter.scans.persist(scanned.result, {
-            renameOps: scanned.renameOps,
-            extractorRuns: scanned.extractorRuns,
-            enrichments: scanned.enrichments
-          });
-          return { kind: "ok", ...scanned };
-        });
-      } catch (err) {
-        const message = formatErrorMessage(err);
-        this.context.stderr.write(tx(SCAN_TEXTS.scanFailure, { message }));
-        return ExitCode.Error;
-      }
-      if (outcome.kind === "scan-error") {
-        this.context.stderr.write(tx(SCAN_TEXTS.scanFailure, { message: outcome.message }));
-        return ExitCode.Error;
-      }
-      if (outcome.kind === "guard") {
-        this.context.stderr.write(tx(SCAN_TEXTS.guardWipeRefused, { existing: outcome.existing }));
-        return ExitCode.Error;
-      }
-      result = outcome.result;
-      renameOps = outcome.renameOps;
-      persistedTo = dbPath;
-    } else {
-      let prior;
-      try {
-        prior = this.noBuiltIns ? null : await tryWithSqlite(
-          { databasePath: dbPath, autoBackup: false },
-          loadPrior
-        );
-      } catch (err) {
-        const message = formatErrorMessage(err);
-        this.context.stderr.write(tx(SCAN_TEXTS.scanFailure, { message }));
-        return ExitCode.Error;
-      }
-      try {
-        const scanned = await runScanWith(prior);
-        result = scanned.result;
-        renameOps = scanned.renameOps;
-      } catch (err) {
-        const message = formatErrorMessage(err);
-        this.context.stderr.write(tx(SCAN_TEXTS.scanFailure, { message }));
-        return ExitCode.Error;
-      }
+    this.emitElapsed = false;
+    const roots = this.roots.length > 0 ? this.roots : ["."];
+    return runWatchLoop({
+      roots,
+      json: this.json,
+      noTokens: this.noTokens,
+      strict: this.strict,
+      noPlugins: this.noPlugins,
+      context: this.context
+    });
+  }
+  /** Render the failure branch of `IScanRunResult` to stderr. */
+  renderFailure(outcome) {
+    if (outcome.kind === "guard-trip") {
+      this.context.stderr.write(tx(SCAN_TEXTS.guardWipeRefused, { existing: outcome.existing }));
+      return ExitCode.Error;
     }
+    this.context.stderr.write(tx(SCAN_TEXTS.scanFailure, { message: outcome.message }));
+    return ExitCode.Error;
+  }
+  /**
+   * Render the successful outcome to stdout (JSON or human) and compute
+   * the exit code. Exit 1 only when at least one issue is at `error`
+   * severity (mirrors `sm check`, per spec § Exit codes).
+   */
+  renderOutcome(result, persistedTo, dbPath, strict) {
     const exitCode2 = result.issues.some((i) => i.severity === "error") ? ExitCode.Issues : ExitCode.Ok;
     if (this.json) {
       if (strict) {
@@ -11494,10 +11628,10 @@ var ScanCommand = class extends Command16 {
 
 // cli/commands/scan-compare.ts
 import { existsSync as existsSync14, readFileSync as readFileSync11 } from "fs";
-import { Command as Command17, Option as Option17 } from "clipanion";
-var ScanCompareCommand = class extends Command17 {
+import { Command as Command18, Option as Option18 } from "clipanion";
+var ScanCompareCommand = class extends SmCommand {
   static paths = [["scan", "compare-with"]];
-  static usage = Command17.Usage({
+  static usage = Command18.Usage({
     category: "Scan",
     description: "Run a fresh scan in memory and emit a delta against the saved ScanResult dump at <dump>. Read-only.",
     details: `
@@ -11525,18 +11659,15 @@ var ScanCompareCommand = class extends Command17 {
       ["JSON output for tooling", "$0 scan compare-with baseline.json --json"]
     ]
   });
-  dump = Option17.String({ required: true });
-  roots = Option17.Rest({ name: "roots" });
-  json = Option17.Boolean("--json", false, {
-    description: "Emit the IScanDelta document as JSON on stdout."
-  });
-  noTokens = Option17.Boolean("--no-tokens", false, {
+  dump = Option18.String({ required: true });
+  roots = Option18.Rest({ name: "roots" });
+  noTokens = Option18.Boolean("--no-tokens", false, {
     description: "Skip per-node token counts during the fresh scan."
   });
-  strict = Option17.Boolean("--strict", false, {
+  strict = Option18.Boolean("--strict", false, {
     description: "Promote layered-config warnings and frontmatter-validation findings from warn to error."
   });
-  noPlugins = Option17.Boolean("--no-plugins", false, {
+  noPlugins = Option18.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery."
   });
   // Cyclomatic count comes from CLI ergonomics: 3 distinct try/catch
@@ -11544,7 +11675,7 @@ var ScanCompareCommand = class extends Command17 {
   // for the JSON branch. The pure pieces already live in
   // `loadAndValidateDump` and `computeScanDelta`.
   // eslint-disable-next-line complexity
-  async execute() {
+  async run() {
     const ctx = defaultRuntimeContext();
     const roots = this.roots.length > 0 ? this.roots : ["."];
     let prior;
@@ -11719,55 +11850,1768 @@ function renderDeltaIssues(issues) {
   return lines;
 }
 
-// cli/commands/show.ts
-import { Command as Command18, Option as Option18 } from "clipanion";
+// cli/commands/serve.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync18 } from "fs";
+import { Command as Command19, Option as Option19 } from "clipanion";
 
-// cli/i18n/show.texts.ts
-var SHOW_TEXTS = {
-  nodeNotFound: "Node not found: {{nodePath}}\n",
-  // --- renderHuman labels ------------------------------------------------
-  sectionFrontmatter: "Frontmatter:",
-  sectionLinksOut: "Links out",
-  sectionLinksIn: "Links in",
-  sectionIssues: "Issues",
-  placeholderNone: "  (none)",
-  sectionHeader: "{{label}} ({{count}}, {{unique}} unique):",
-  issuesHeader: "Issues ({{count}}):",
-  issueRow: "  - [{{severity}}] {{ruleId}}: {{message}}",
-  // --- formatGroupedLink ------------------------------------------------
-  /**
-   * Bullet line for one grouped link in the in/out lists. `{{kind}}` and
-   * `{{endpoint}}` are pre-sanitized by the caller; `{{dup}}` is the
-   * `(×N)` count when the row collapses multiple identical edges, empty
-   * otherwise; `{{sources}}` is the trailing `  sources: a, b` segment
-   * (empty when the link has no sources).
-   */
-  groupedLinkHead: "  - [{{kind}}/{{confidence}}] {{arrow}} {{endpoint}}{{dup}}{{sources}}",
-  groupedLinkDup: " (\xD7{{count}})",
-  groupedLinkSources: "  sources: {{values}}",
-  // --- renderNodeHeader labels ------------------------------------------
-  nodeIdentity: "{{path}} [{{kind}}] (provider: {{provider}})",
-  nodeFieldTitle: "title:        {{value}}",
-  nodeFieldDescription: "description:  {{value}}",
-  nodeFieldStability: "stability:    {{value}}",
-  nodeFieldVersion: "version:      {{value}}",
-  nodeFieldAuthor: "author:       {{value}}",
-  nodeWeight: "Weight: bytes {{total}} total / {{frontmatter}} frontmatter / {{body}} body",
-  nodeTokens: "        tokens {{total}} total / {{frontmatter}} frontmatter / {{body}} body",
-  nodeExternalRefs: "External refs: {{count}}"
-};
+// server/index.ts
+import { serve } from "@hono/node-server";
+import { WebSocketServer } from "ws";
 
-// cli/commands/show.ts
-var ShowCommand = class extends Command18 {
-  static paths = [["show"]];
-  static usage = Command18.Usage({
-    category: "Browse",
-    description: "Node detail: weight, frontmatter, links, issues, findings, summary.",
-    details: `
+// server/app.ts
+import { Hono } from "hono";
+import { HTTPException as HTTPException5 } from "hono/http-exception";
+
+// server/routes/config.ts
+import { HTTPException } from "hono/http-exception";
+
+// server/envelope.ts
+var REST_ENVELOPE_SCHEMA_VERSION = "1";
+function buildListEnvelope(opts) {
+  const counts = {
+    total: opts.total,
+    returned: opts.items.length
+  };
+  if (opts.page) counts.page = opts.page;
+  return {
+    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+    kind: opts.kind,
+    items: opts.items,
+    filters: opts.filters,
+    counts,
+    kindRegistry: opts.kindRegistry
+  };
+}
+function buildValueEnvelope(kind, value, kindRegistry) {
+  return {
+    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+    kind,
+    value,
+    kindRegistry
+  };
+}
+
+// server/routes/config.ts
+function registerConfigRoute(app, deps) {
+  app.get("/api/config", (c) => {
+    let loaded;
+    try {
+      loaded = loadConfig({
+        scope: deps.options.scope,
+        cwd: deps.runtimeContext.cwd,
+        homedir: deps.runtimeContext.homedir
+      });
+    } catch (err) {
+      throw new HTTPException(500, { message: formatErrorMessage(err) });
+    }
+    for (const warn of loaded.warnings) {
+      process.stderr.write(`${warn}
+`);
+    }
+    return c.json(buildValueEnvelope("config", loaded.effective, deps.kindRegistry));
+  });
+}
+
+// server/routes/graph.ts
+import { HTTPException as HTTPException2 } from "hono/http-exception";
+
+// server/i18n/server.texts.ts
+var SERVER_TEXTS = {
+  // Boot banner — printed by the server itself when it begins to listen.
+  // The CLI verb `sm serve` formats its own boot banner separately
+  // (SERVE_TEXTS.boot) so the two surfaces can diverge if needed.
+  listening: "skill-map server listening on http://{{host}}:{{port}}\n",
+  // UI bundle missing — non-fatal when the path was auto-resolved (the
+  // server keeps running with an inline placeholder at `/`). Becomes
+  // ExitCode.Error when `--ui-dist <path>` was explicit.
+  uiBundleMissing: 'skill-map server: UI bundle not found at {{path}} \u2014 serving inline placeholder at "/" (run "npm run build --workspace=ui" to populate).\n',
+  // Loopback-only deprecation hint — Decision #119. Logged once at boot
+  // when `--host` resolves to a non-loopback address. Multi-host serve
+  // re-opens post-v0.6.0.
+  hostNonLoopbackHint: "skill-map server: --host {{host}} is non-loopback \u2014 through v0.6.0 the BFF assumes loopback-only (no auth). See Decision #119 in ROADMAP.\n",
+  // Shutdown trace — printed by the close path so test runs that bring
+  // the server up and down have a clear marker.
+  closed: "skill-map server: closed.\n",
+  // ---- error envelope messages (Step 14.2) ---------------------------------
+  // Persisted scan absent and the route can't degrade to an empty result.
+  // Hint nudges the user toward `sm scan` so the SPA can call it via the
+  // CLI side-by-side with the server.
+  dbMissingHint: "No persisted scan available at {{path}}. Run `sm scan` to populate the DB.",
+  // `?fresh=1` was requested but the server was booted with --no-built-ins
+  // or --no-plugins. A fresh scan with neither pipeline yields an empty /
+  // partial result that would surprise the SPA. Reject up front.
+  freshScanRequiresPipeline: "?fresh=1 cannot run while the server was started with --no-built-ins or --no-plugins (would yield empty / partial results).",
+  // Unknown formatter on /api/graph — the user asked for a `format` value
+  // that no registered formatter advertises. Mirrors `sm graph`'s message.
+  graphUnknownFormat: 'Unknown graph format "{{format}}". Available: {{available}}.',
+  // Pagination caps on /api/nodes.
+  paginationLimitTooLarge: "limit={{value}} exceeds the maximum of {{max}}.",
+  paginationInvalidInteger: "{{name}}={{value}} is not a non-negative integer.",
+  // Node lookup miss on /api/nodes/:pathB64. Both the missing-node and
+  // the malformed-pathB64 cases funnel here — the client experience is
+  // the same (the resource isn't there).
+  nodeNotFound: 'No node with path "{{path}}".',
+  pathB64Malformed: "Malformed pathB64 \u2014 not a valid base64url-encoded node.path.",
+  // ---- WS broadcaster + watcher (Step 14.4.a) ------------------------------
+  // Logged once on watcher boot after chokidar's initial walk completes.
+  // Marks the broadcaster as armed and the live event stream as flowing.
+  watcherReady: 'skill-map server: watcher ready (roots="{{roots}}", debounceMs={{debounceMs}}).\n',
+  // Watcher boot failure inside `createServer`. Non-fatal — the REST
+  // surface stays alive so the operator can fix the underlying issue
+  // (config, plugin, FS permission) and restart.
+  watcherBootFailed: "skill-map server: watcher boot failed \u2014 {{message}}. /api/* still serving; pass --no-watcher to silence this on the next boot.\n",
+  // Per-batch failure inside the watcher's scan+persist pipeline. The
+  // watcher loop continues — a transient FS error must not kill the
+  // broadcaster.
+  watcherBatchFailed: "skill-map server: watcher batch failed \u2014 {{message}}.\n",
+  // chokidar surfaced an error. The watcher stays open per IFsWatcher's
+  // contract; the BFF also broadcasts a `watcher.error` advisory so the
+  // SPA can surface it in the live event log.
+  watcherError: "skill-map server: watcher error \u2014 {{message}}.\n",
+  // chokidar.close() rejected during graceful shutdown. Logged but not
+  // surfaced — close() is best-effort and idempotent.
+  watcherCloseFailed: "skill-map server: watcher close failed \u2014 {{message}}.\n",
+  // A connected client's outbound buffer exceeded the backpressure
+  // threshold. The broadcaster closes the client with code 1009 and
+  // unregisters it. Logged so operators can spot a wedged consumer.
+  wsBackpressureEvicted: "skill-map server: ws client evicted (bufferedAmount={{buffered}} > threshold={{threshold}}).\n",
+  // `WebSocket.send()` threw on a registered client. The client is
+  // unregistered; the broadcast continues with the remaining clients.
+  wsClientSendFailed: "skill-map server: ws send failed \u2014 {{message}}.\n",
+  // `JSON.stringify(envelope)` threw inside `broadcast()`. The event is
+  // dropped. Per spec/job-events.md §Error handling, the right shape
+  // is a synthetic `emitter.error` event; v14.4.a does not yet route
+  // it through the broadcaster (would re-enter the same stringify
+  // path), so we degrade to a logged warning.
+  wsBroadcastSerializeFailed: "skill-map server: ws broadcast dropped \u2014 failed to serialize event: {{message}}.\n"
+};
+
+// server/routes/graph.ts
+var DEFAULT_FORMAT2 = "ascii";
+function registerGraphRoute(app, deps) {
+  app.get("/api/graph", async (c) => {
+    const format = c.req.query("format") ?? DEFAULT_FORMAT2;
+    const pluginRuntime = deps.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: deps.options.scope });
+    for (const warn of pluginRuntime.warnings) {
+      process.stderr.write(`${warn}
+`);
+    }
+    const formatters = composeFormatters({
+      noBuiltIns: deps.options.noBuiltIns,
+      pluginRuntime
+    });
+    const formatter = formatters.find((f) => f.formatId === format);
+    if (!formatter) {
+      const available = formatters.map((f) => f.formatId).sort().join(", ");
+      throw new HTTPException2(400, {
+        message: tx(SERVER_TEXTS.graphUnknownFormat, {
+          format,
+          available: available || "(none)"
+        })
+      });
+    }
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.load()
+    );
+    const scan = loaded ?? { nodes: [], links: [], issues: [] };
+    const text = formatter.format({
+      nodes: scan.nodes,
+      links: scan.links,
+      issues: scan.issues
+    });
+    const body = text.endsWith("\n") ? text : text + "\n";
+    return c.body(body, 200, { "content-type": contentTypeFor(format) });
+  });
+}
+function contentTypeFor(format) {
+  if (format === "json") return "application/json; charset=utf-8";
+  if (format === "md" || format === "markdown" || format === "mermaid") {
+    return "text/markdown; charset=utf-8";
+  }
+  return "text/plain; charset=utf-8";
+}
+
+// server/health.ts
+import { existsSync as existsSync15 } from "fs";
+var FALLBACK_SCHEMA_VERSION = "1";
+function buildHealth(deps) {
+  return {
+    ok: true,
+    schemaVersion: FALLBACK_SCHEMA_VERSION,
+    specVersion: deps.specVersion,
+    implVersion: VERSION,
+    scope: deps.scope,
+    db: existsSync15(deps.dbPath) ? "present" : "missing"
+  };
+}
+async function resolveSpecVersion2() {
+  try {
+    const mod = await import("@skill-map/spec", { with: { type: "json" } });
+    const version = mod.default?.specPackageVersion;
+    return version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// server/routes/health.ts
+function registerHealthRoute(app, deps) {
+  app.get("/api/health", (c) => {
+    const payload = buildHealth({
+      dbPath: deps.options.dbPath,
+      scope: deps.options.scope,
+      specVersion: deps.specVersion
+    });
+    return c.json(payload);
+  });
+}
+
+// server/routes/issues.ts
+function registerIssuesRoute(app, deps) {
+  app.get("/api/issues", async (c) => {
+    const params = new URL(c.req.url).searchParams;
+    const severityFilter = parseCsv(params.get("severity"));
+    const ruleFilter = parseRulesFilter(params.get("ruleId"));
+    const nodePath = params.get("node");
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.issues.listAll()
+    );
+    const allIssues = loaded ?? [];
+    const filtered = allIssues.filter((issue) => {
+      if (severityFilter && !severityFilter.includes(issue.severity)) return false;
+      if (ruleFilter && !matchesRuleFilter2(issue.ruleId, ruleFilter)) return false;
+      if (nodePath !== null && !issue.nodeIds.includes(nodePath)) return false;
+      return true;
+    });
+    return c.json(
+      buildListEnvelope({
+        kind: "issues",
+        items: filtered,
+        filters: {
+          severity: severityFilter ?? null,
+          ruleId: ruleFilter ? [...ruleFilter] : null,
+          node: nodePath ?? null
+        },
+        total: filtered.length,
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function parseCsv(raw) {
+  if (raw === null) return null;
+  const list = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return list.length > 0 ? list : null;
+}
+function parseRulesFilter(raw) {
+  const list = parseCsv(raw);
+  return list ? new Set(list) : null;
+}
+function matchesRuleFilter2(ruleId, filter) {
+  if (filter.has(ruleId)) return true;
+  const slashIdx = ruleId.indexOf("/");
+  if (slashIdx >= 0) {
+    const short = ruleId.slice(slashIdx + 1);
+    if (filter.has(short)) return true;
+  }
+  return false;
+}
+
+// server/routes/links.ts
+function registerLinksRoute(app, deps) {
+  app.get("/api/links", async (c) => {
+    const params = new URL(c.req.url).searchParams;
+    const kindFilter = parseCsv2(params.get("kind"));
+    const from = params.get("from");
+    const to = params.get("to");
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.load()
+    );
+    const allLinks = loaded?.links ?? [];
+    const filtered = allLinks.filter((link2) => {
+      if (kindFilter && !kindFilter.includes(link2.kind)) return false;
+      if (from !== null && link2.source !== from) return false;
+      if (to !== null && link2.target !== to) return false;
+      return true;
+    });
+    return c.json(
+      buildListEnvelope({
+        kind: "links",
+        items: filtered,
+        filters: {
+          kind: kindFilter ?? null,
+          from: from ?? null,
+          to: to ?? null
+        },
+        total: filtered.length,
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function parseCsv2(raw) {
+  if (raw === null) return null;
+  const list = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return list.length > 0 ? list : null;
+}
+
+// server/routes/nodes.ts
+import { HTTPException as HTTPException3 } from "hono/http-exception";
+
+// server/node-body.ts
+import { readFile as readFile4 } from "fs/promises";
+import { isAbsolute as isAbsolute4, resolve as resolvePath, relative as relativePath, sep as sep4 } from "path";
+async function readNodeBody(cwd, relPath) {
+  if (isAbsolute4(relPath)) return null;
+  const absRoot = resolvePath(cwd);
+  const absFile = resolvePath(absRoot, relPath);
+  const rel = relativePath(absRoot, absFile);
+  if (rel.startsWith("..") || rel.startsWith(sep4) || rel.length === 0) {
+    return null;
+  }
+  let raw;
+  try {
+    raw = await readFile4(absFile, "utf-8");
+  } catch (err) {
+    if (isExpectedFsError(err)) return null;
+    throw err;
+  }
+  return stripFrontmatter(raw);
+}
+function stripFrontmatter(raw) {
+  if (!raw.startsWith("---")) return raw;
+  const match = raw.match(/^---\r?\n[\s\S]*?^---\r?\n?/m);
+  if (!match) return raw;
+  return raw.slice(match[0].length);
+}
+var EXPECTED_FS_ERROR_CODES = /* @__PURE__ */ new Set(["ENOENT", "EACCES", "EISDIR", "ENOTDIR"]);
+function isExpectedFsError(err) {
+  if (err === null || typeof err !== "object") return false;
+  const code = err.code;
+  return typeof code === "string" && EXPECTED_FS_ERROR_CODES.has(code);
+}
+
+// server/path-codec.ts
+var PathCodecError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PathCodecError";
+  }
+};
+function encodeNodePath(path) {
+  return Buffer.from(path, "utf8").toString("base64url");
+}
+function decodeNodePath(encoded) {
+  if (encoded.length === 0) {
+    throw new PathCodecError("empty pathB64");
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(encoded)) {
+    throw new PathCodecError("pathB64 contains characters outside the base64url alphabet");
+  }
+  const decoded = Buffer.from(encoded, "base64url").toString("utf8");
+  if (encodeNodePath(decoded) !== encoded) {
+    throw new PathCodecError("pathB64 did not round-trip cleanly through base64url");
+  }
+  return decoded;
+}
+
+// server/query-adapter.ts
+function urlParamsToExportQuery(params) {
+  const filters = {};
+  const tokens = [];
+  const kindRaw = params.get("kind");
+  if (kindRaw !== null) {
+    const kinds = splitCsv(kindRaw);
+    if (kinds.length === 0) {
+      throw new ExportQueryError("kind: empty value list");
+    }
+    filters.kinds = kinds;
+    tokens.push(`kind=${kinds.join(",")}`);
+  }
+  const hasIssuesRaw = params.get("hasIssues");
+  if (hasIssuesRaw !== null) {
+    const lower = hasIssuesRaw.toLowerCase();
+    if (lower === "true") {
+      filters.hasIssues = true;
+      tokens.push("has=issues");
+    } else if (lower === "false") {
+      filters.hasIssues = false;
+    } else {
+      throw new ExportQueryError(`hasIssues: expected "true" or "false", got "${hasIssuesRaw}"`);
+    }
+  }
+  const pathRaw = params.get("path");
+  if (pathRaw !== null) {
+    const globs = splitCsv(pathRaw);
+    if (globs.length === 0) {
+      throw new ExportQueryError("path: empty value list");
+    }
+    filters.pathGlobs = globs;
+    tokens.push(`path=${globs.join(",")}`);
+  }
+  const raw = tokens.join(" ");
+  const query = parseExportQuery(raw);
+  return { query, filters };
+}
+function filterNodesWithoutIssues(nodes, issues) {
+  if (issues.length === 0) return nodes;
+  const nodesWithIssues = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    for (const id of issue.nodeIds) nodesWithIssues.add(id);
+  }
+  return nodes.filter((n) => !nodesWithIssues.has(n.path));
+}
+function splitCsv(raw) {
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// server/routes/nodes.ts
+var DEFAULT_LIMIT = 100;
+var MAX_LIMIT = 1e3;
+function registerNodesRoutes(app, deps) {
+  app.get("/api/nodes/:pathB64", async (c) => {
+    const pathB64 = c.req.param("pathB64");
+    let nodePath;
+    try {
+      nodePath = decodeNodePath(pathB64);
+    } catch (err) {
+      if (err instanceof PathCodecError) {
+        throw new HTTPException3(404, { message: SERVER_TEXTS.pathB64Malformed });
+      }
+      throw err;
+    }
+    const bundle = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.findNode(nodePath)
+    );
+    if (!bundle) {
+      throw new HTTPException3(404, {
+        message: tx(SERVER_TEXTS.nodeNotFound, { path: nodePath })
+      });
+    }
+    const includes = parseIncludes(new URL(c.req.url).searchParams.get("include"));
+    const item = includes.has("body") ? { ...bundle.node, body: await readNodeBody(deps.runtimeContext.cwd, nodePath) } : bundle.node;
+    return c.json({
+      schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+      kind: "node",
+      item,
+      links: { incoming: bundle.linksIn, outgoing: bundle.linksOut },
+      issues: bundle.issues,
+      kindRegistry: deps.kindRegistry
+    });
+  });
+  app.get("/api/nodes", async (c) => {
+    const params = new URL(c.req.url).searchParams;
+    const { query, filters } = urlParamsToExportQuery(params);
+    const { offset, limit } = parsePagination(params);
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.load()
+    );
+    const scan = loaded ?? { nodes: [], links: [], issues: [] };
+    const subset = applyExportQuery(scan, query);
+    let nodes = subset.nodes;
+    if (filters.hasIssues === false) {
+      nodes = filterNodesWithoutIssues(nodes, scan.issues);
+    }
+    const total = nodes.length;
+    const items = nodes.slice(offset, offset + limit);
+    return c.json(
+      buildListEnvelope({
+        kind: "nodes",
+        items,
+        filters: {
+          kind: filters.kinds ?? null,
+          hasIssues: filters.hasIssues ?? null,
+          path: filters.pathGlobs ?? null
+        },
+        total,
+        page: { offset, limit },
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function parsePagination(params) {
+  const offset = parseNonNegativeInt(params.get("offset"), "offset", 0);
+  const limit = parseNonNegativeInt(params.get("limit"), "limit", DEFAULT_LIMIT);
+  if (limit > MAX_LIMIT) {
+    throw new HTTPException3(400, {
+      message: tx(SERVER_TEXTS.paginationLimitTooLarge, { value: limit, max: MAX_LIMIT })
+    });
+  }
+  return { offset, limit };
+}
+function parseNonNegativeInt(raw, name, fallback) {
+  if (raw === null || raw.length === 0) return fallback;
+  const trimmed = raw.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== trimmed) {
+    throw new HTTPException3(400, {
+      message: tx(SERVER_TEXTS.paginationInvalidInteger, { name, value: raw })
+    });
+  }
+  return parsed;
+}
+function parseIncludes(raw) {
+  if (raw === null || raw.length === 0) return /* @__PURE__ */ new Set();
+  return new Set(raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0));
+}
+
+// server/routes/plugins.ts
+function registerPluginsRoute(app, deps) {
+  app.get("/api/plugins", async (c) => {
+    const pluginRuntime = deps.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: deps.options.scope });
+    for (const warn of pluginRuntime.warnings) {
+      process.stderr.write(`${warn}
+`);
+    }
+    const items = [
+      ...deps.options.noBuiltIns ? [] : buildBuiltInItems(pluginRuntime.resolveEnabled),
+      ...buildDiscoveredItems(pluginRuntime.discovered, deps)
+    ];
+    return c.json(
+      buildListEnvelope({
+        kind: "plugins",
+        items,
+        filters: {},
+        total: items.length,
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function buildBuiltInItems(resolveEnabled) {
+  return builtInBundles.map((bundle) => ({
+    id: bundle.id,
+    version: firstVersion(bundle.extensions),
+    kinds: uniqueKinds(bundle.extensions.map((e) => e.kind)),
+    status: resolveEnabled(bundle.id) ? "enabled" : "disabled",
+    reason: null,
+    source: "built-in"
+  }));
+}
+function buildDiscoveredItems(discovered, deps) {
+  return discovered.map((plugin) => ({
+    id: plugin.id,
+    version: plugin.manifest?.version ?? null,
+    kinds: uniqueKinds(plugin.extensions?.map((e) => e.kind) ?? []),
+    status: plugin.status,
+    reason: plugin.reason ?? null,
+    source: classifyPluginSource(plugin.path, deps)
+  }));
+}
+function uniqueKinds(kinds) {
+  return [...new Set(kinds)].sort();
+}
+function firstVersion(extensions) {
+  for (const ext of extensions) {
+    if (ext.version) return ext.version;
+  }
+  return null;
+}
+function classifyPluginSource(pluginPath, deps) {
+  const projectDir = defaultProjectPluginsDir(deps.runtimeContext);
+  return pluginPath.startsWith(projectDir) ? "project" : "global";
+}
+
+// server/routes/scan.ts
+import { HTTPException as HTTPException4 } from "hono/http-exception";
+function registerScanRoute(app, deps) {
+  app.get("/api/scan", async (c) => {
+    const fresh = c.req.query("fresh");
+    if (fresh === "1" || fresh === "true") {
+      return c.json(await runFreshScan(deps));
+    }
+    return c.json(await loadPersistedScan(deps));
+  });
+}
+async function loadPersistedScan(deps) {
+  const loaded = await tryWithSqlite(
+    { databasePath: deps.options.dbPath, autoBackup: false },
+    (adapter) => adapter.scans.load()
+  );
+  if (loaded !== null) return loaded;
+  return emptyScanResult();
+}
+async function runFreshScan(deps) {
+  if (deps.options.noBuiltIns || deps.options.noPlugins) {
+    throw new HTTPException4(400, { message: SERVER_TEXTS.freshScanRequiresPipeline });
+  }
+  const outcome = await runScanForCommand({
+    roots: [deps.runtimeContext.cwd],
+    noBuiltIns: false,
+    noPlugins: false,
+    noTokens: false,
+    dryRun: true,
+    changed: false,
+    allowEmpty: true,
+    strict: false,
+    stderr: process.stderr,
+    ctx: deps.runtimeContext
+  });
+  if (outcome.kind !== "ok") {
+    throw new HTTPException4(500, {
+      message: outcome.kind === "guard-trip" ? `fresh scan refused (existing rows: ${outcome.existing})` : outcome.message
+    });
+  }
+  return outcome.result;
+}
+function emptyScanResult() {
+  return {
+    schemaVersion: 1,
+    scannedAt: Date.now(),
+    scope: "project",
+    roots: ["."],
+    providers: [],
+    nodes: [],
+    links: [],
+    issues: [],
+    stats: {
+      filesWalked: 0,
+      filesSkipped: 0,
+      nodesCount: 0,
+      linksCount: 0,
+      issuesCount: 0,
+      durationMs: 0
+    }
+  };
+}
+
+// server/static.ts
+import { existsSync as existsSync16 } from "fs";
+import { readFile as readFile5 } from "fs/promises";
+import { extname, join as join13 } from "path";
+import { serveStatic } from "@hono/node-server/serve-static";
+var INDEX_HTML = "index.html";
+var PLACEHOLDER_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="skill-map-mode" content="live" />
+    <title>skill-map server</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 2rem; max-width: 36rem; line-height: 1.5; }
+      code { background: #f4f4f4; padding: 0.1rem 0.3rem; border-radius: 3px; }
+      h1 { font-size: 1.4rem; }
+    </style>
+  </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 REST API is available at <code>/api/health</code>.</p>
+  </body>
+</html>
+`;
+function createStaticHandler(uiDist) {
+  if (uiDist === null) return placeholderRootMiddleware();
+  return serveStatic({ root: uiDist });
+}
+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);
+    return fileResponse(c, indexPath);
+  };
+}
+function placeholderRootMiddleware() {
+  return async (c, next) => {
+    if (c.req.method !== "GET" && c.req.method !== "HEAD") return next();
+    if (c.req.path === "/" || c.req.path === "/index.html") {
+      return htmlResponse(c, PLACEHOLDER_HTML);
+    }
+    return next();
+  };
+}
+var MIME_TYPES = {
+  ".html": "text/html; charset=UTF-8",
+  ".js": "application/javascript; charset=UTF-8",
+  ".mjs": "application/javascript; charset=UTF-8",
+  ".css": "text/css; charset=UTF-8",
+  ".json": "application/json; charset=UTF-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".txt": "text/plain; charset=UTF-8",
+  ".map": "application/json; charset=UTF-8"
+};
+function mimeFor(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] ?? "application/octet-stream";
+}
+function htmlResponse(c, html) {
+  return c.body(html, 200, { "content-type": "text/html; charset=UTF-8" });
+}
+async function fileResponse(c, absPath) {
+  const buf = await readFile5(absPath);
+  return c.body(buf, 200, { "content-type": mimeFor(absPath) });
+}
+
+// server/ws.ts
+import { upgradeWebSocket } from "@hono/node-server";
+var WS_PATH = "/ws";
+function attachBroadcasterRoute(app, broadcaster) {
+  app.get(
+    WS_PATH,
+    upgradeWebSocket(() => ({
+      onOpen(_event, ws) {
+        const raw = ws.raw;
+        if (!raw) {
+          broadcaster.register({
+            send: (data) => ws.send(data),
+            close: (code, reason) => ws.close(code, reason),
+            bufferedAmount: 0,
+            readyState: ws.readyState
+          });
+          return;
+        }
+        broadcaster.register(raw);
+      },
+      onClose(_event, ws) {
+        const raw = ws.raw;
+        if (raw) broadcaster.unregister(raw);
+      },
+      onError(event, ws) {
+        const raw = ws.raw;
+        if (raw) broadcaster.unregister(raw);
+        const message = event?.message ?? "unknown";
+        log.warn(
+          tx(SERVER_TEXTS.wsClientSendFailed, {
+            message: sanitizeForTerminal(message)
+          })
+        );
+      }
+    }))
+  );
+}
+
+// server/app.ts
+function createApp(deps) {
+  const app = new Hono();
+  if (deps.options.devCors) {
+    app.use("*", async (c, next) => {
+      await next();
+      c.res.headers.set("access-control-allow-origin", "*");
+      c.res.headers.set("access-control-allow-methods", "GET,POST,PUT,DELETE,OPTIONS");
+      c.res.headers.set("access-control-allow-headers", "content-type, authorization");
+    });
+    app.options("*", (c) => c.body(null, 204));
+  }
+  registerHealthRoute(app, { options: deps.options, specVersion: deps.specVersion });
+  const routeDeps = {
+    options: deps.options,
+    runtimeContext: deps.runtimeContext,
+    kindRegistry: deps.kindRegistry
+  };
+  registerScanRoute(app, routeDeps);
+  registerNodesRoutes(app, routeDeps);
+  registerLinksRoute(app, routeDeps);
+  registerIssuesRoute(app, routeDeps);
+  registerGraphRoute(app, routeDeps);
+  registerConfigRoute(app, routeDeps);
+  registerPluginsRoute(app, routeDeps);
+  app.all("/api/*", (c) => {
+    throw new HTTPException5(404, { message: `Unknown API endpoint: ${c.req.path}` });
+  });
+  attachBroadcasterRoute(app, deps.broadcaster);
+  app.use("*", createStaticHandler(deps.options.uiDist));
+  app.get("*", createSpaFallback(deps.options.uiDist));
+  app.notFound((c) => {
+    throw new HTTPException5(404, { message: `Not found: ${c.req.path}` });
+  });
+  app.onError((err, c) => {
+    return formatError2(err, c);
+  });
+  return app;
+}
+function codeForStatus(status) {
+  if (status === 404) return "not-found";
+  if (status === 400) return "bad-query";
+  return "internal";
+}
+function formatError2(err, c) {
+  if (err instanceof HTTPException5) {
+    const status = err.status;
+    const envelope2 = {
+      ok: false,
+      error: {
+        code: codeForStatus(status),
+        message: err.message,
+        details: null
+      }
+    };
+    return c.json(envelope2, status);
+  }
+  if (err instanceof ExportQueryError) {
+    const envelope2 = {
+      ok: false,
+      error: {
+        code: "bad-query",
+        message: err.message,
+        details: null
+      }
+    };
+    return c.json(envelope2, 400);
+  }
+  const envelope = {
+    ok: false,
+    error: {
+      code: "internal",
+      message: formatErrorMessage(err),
+      details: null
+    }
+  };
+  return c.json(envelope, 500);
+}
+
+// server/broadcaster.ts
+var MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
+var CLOSE_CODE_GOING_AWAY = 1001;
+var CLOSE_CODE_MESSAGE_TOO_BIG = 1009;
+var READY_STATE_OPEN = 1;
+var WsBroadcaster = class {
+  #clients = /* @__PURE__ */ new Set();
+  #shutDown = false;
+  /** Number of currently-registered clients. Read-only — for tests / `/api/health`. */
+  get clientCount() {
+    return this.#clients.size;
+  }
+  /**
+   * Register a client. Called from the `/ws` `onOpen` handler with the
+   * raw `WebSocket` instance. After shutdown the broadcaster refuses
+   * new registrations and immediately closes the offered socket so a
+   * late upgrade doesn't leak.
+   */
+  register(ws) {
+    if (this.#shutDown) {
+      try {
+        ws.close(CLOSE_CODE_GOING_AWAY, "server shutdown");
+      } catch {
+      }
+      return;
+    }
+    this.#clients.add(ws);
+  }
+  /**
+   * Unregister a client. Called from the `/ws` `onClose` / `onError`
+   * handlers and from the backpressure path. Idempotent — calling on a
+   * client that was never registered (or was already removed) is a no-op.
+   */
+  unregister(ws) {
+    this.#clients.delete(ws);
+  }
+  /**
+   * Serialize the envelope once and fan out to every open client.
+   * Closed / closing clients are silently skipped (the `onClose` handler
+   * has already removed them, but we double-check `readyState` because a
+   * close in the middle of the loop is observable as a transient
+   * `OPEN → CLOSING` flip).
+   *
+   * Per-client `send()` failures are caught: one rogue socket cannot
+   * stop the rest from receiving the event. A failing socket is closed
+   * + unregistered so the next broadcast doesn't waste cycles on it.
+   *
+   * Backpressure check (per AGENTS.md §Watcher integration): if a
+   * client's `bufferedAmount` exceeds `MAX_BUFFERED_BYTES`, it's evicted
+   * with close code 1009. The check runs BEFORE `send` so the threshold
+   * acts as an admission gate, not a post-mortem.
+   */
+  broadcast(envelope) {
+    if (this.#shutDown) return;
+    let payload;
+    try {
+      payload = JSON.stringify(envelope);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(
+        tx(SERVER_TEXTS.wsBroadcastSerializeFailed, {
+          message: sanitizeForTerminal(message)
+        })
+      );
+      return;
+    }
+    const snapshot = Array.from(this.#clients);
+    for (const client of snapshot) {
+      this.#deliver(client, payload);
+    }
+  }
+  /**
+   * Drain every connected socket with code 1001 ('going away') + reason
+   * `'server shutdown'`. Idempotent — a second call after the first
+   * `shutdown()` is a no-op. After shutdown, `register()` immediately
+   * closes any new client offered.
+   */
+  shutdown() {
+    if (this.#shutDown) return;
+    this.#shutDown = true;
+    const snapshot = Array.from(this.#clients);
+    this.#clients.clear();
+    for (const client of snapshot) {
+      try {
+        client.close(CLOSE_CODE_GOING_AWAY, "server shutdown");
+      } catch {
+      }
+    }
+  }
+  /**
+   * Per-client delivery: backpressure check, then `send()`. Eviction +
+   * unregistration on either failure mode.
+   */
+  #deliver(client, payload) {
+    if (client.readyState !== READY_STATE_OPEN) {
+      this.#clients.delete(client);
+      return;
+    }
+    if (client.bufferedAmount > MAX_BUFFERED_BYTES) {
+      this.#clients.delete(client);
+      try {
+        client.close(CLOSE_CODE_MESSAGE_TOO_BIG, "backpressure exceeded");
+      } catch {
+      }
+      log.warn(
+        tx(SERVER_TEXTS.wsBackpressureEvicted, {
+          buffered: String(client.bufferedAmount),
+          threshold: String(MAX_BUFFERED_BYTES)
+        })
+      );
+      return;
+    }
+    try {
+      client.send(payload);
+    } catch (err) {
+      this.#clients.delete(client);
+      try {
+        client.close();
+      } catch {
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(
+        tx(SERVER_TEXTS.wsClientSendFailed, {
+          message: sanitizeForTerminal(message)
+        })
+      );
+    }
+  }
+};
+
+// server/kind-registry.ts
+function buildKindRegistry(providers) {
+  const registry = {};
+  for (const provider of providers) {
+    for (const [kindName, kindEntry] of Object.entries(provider.kinds)) {
+      if (registry[kindName]) continue;
+      const ui = kindEntry.ui;
+      const entry = {
+        providerId: provider.id,
+        label: ui.label,
+        color: ui.color
+      };
+      if (ui.colorDark !== void 0) entry.colorDark = ui.colorDark;
+      if (ui.emoji !== void 0) entry.emoji = ui.emoji;
+      if (ui.icon !== void 0) entry.icon = ui.icon;
+      registry[kindName] = entry;
+    }
+  }
+  return registry;
+}
+
+// server/events.ts
+function buildWatcherStartedEvent(data) {
+  return {
+    type: "watcher.started",
+    timestamp: Date.now(),
+    jobId: null,
+    data
+  };
+}
+function buildWatcherErrorEvent(data) {
+  return {
+    type: "watcher.error",
+    timestamp: Date.now(),
+    jobId: null,
+    data
+  };
+}
+
+// server/watcher.ts
+var WATCH_ROOT = ".";
+function createWatcherService(opts) {
+  let chokidarHandle = null;
+  let stopped = false;
+  const start = async () => {
+    const cfg = loadConfig({
+      scope: opts.options.scope,
+      cwd: opts.runtimeContext.cwd,
+      homedir: opts.runtimeContext.homedir
+    }).effective;
+    const ignoreFileText = readIgnoreFileText(opts.runtimeContext.cwd);
+    const ignoreFilterOpts = {};
+    if (cfg.ignore.length > 0) ignoreFilterOpts.configIgnore = cfg.ignore;
+    if (ignoreFileText !== void 0) ignoreFilterOpts.ignoreFileText = ignoreFileText;
+    const ignoreFilter = buildIgnoreFilter(ignoreFilterOpts);
+    const debounceMs = opts.debounceMsOverride ?? cfg.scan.watch.debounceMs;
+    const pluginRuntime = opts.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: opts.options.scope });
+    for (const warn of pluginRuntime.warnings) {
+      log.warn(sanitizeForTerminal(warn));
+    }
+    const runOneBatch = async () => {
+      const kernel = createKernel();
+      registerKernelExtensions(kernel, pluginRuntime, opts.options.noBuiltIns);
+      const emitter = buildBroadcasterEmitter(opts.broadcaster);
+      const priorState = await loadPriorState(opts.options.dbPath);
+      const composed = composeScanExtensions({
+        noBuiltIns: opts.options.noBuiltIns,
+        pluginRuntime
+      });
+      const runOptions = assembleRunOptions({
+        scope: opts.options.scope,
+        tokenize: cfg.scan.tokenize !== false,
+        strict: cfg.scan.strict === true,
+        ignoreFilter,
+        emitter,
+        composed,
+        priorState
+      });
+      const ran = await runScanWithRenames(kernel, runOptions);
+      await persistOutcome(opts.options.dbPath, ran);
+    };
+    chokidarHandle = createChokidarWatcher({
+      roots: [WATCH_ROOT],
+      cwd: opts.runtimeContext.cwd,
+      debounceMs,
+      ignoreFilter,
+      onBatch: async () => {
+        if (stopped) return;
+        try {
+          await runOneBatch();
+        } catch (err) {
+          const message = formatErrorMessage(err);
+          log.warn(
+            tx(SERVER_TEXTS.watcherBatchFailed, {
+              message: sanitizeForTerminal(message)
+            })
+          );
+        }
+      },
+      onError: (err) => {
+        const message = err.message;
+        log.warn(
+          tx(SERVER_TEXTS.watcherError, {
+            message: sanitizeForTerminal(message)
+          })
+        );
+        opts.broadcaster.broadcast(buildWatcherErrorEvent({ message }));
+      }
+    });
+    if ("ready" in chokidarHandle && chokidarHandle.ready instanceof Promise) {
+      await chokidarHandle.ready;
+    }
+    opts.broadcaster.broadcast(
+      buildWatcherStartedEvent({ roots: [WATCH_ROOT], debounceMs })
+    );
+    log.info(
+      tx(SERVER_TEXTS.watcherReady, {
+        roots: WATCH_ROOT,
+        debounceMs: String(debounceMs)
+      })
+    );
+  };
+  const stop = async () => {
+    if (stopped) return;
+    stopped = true;
+    if (chokidarHandle) {
+      try {
+        await chokidarHandle.close();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.warn(
+          tx(SERVER_TEXTS.watcherCloseFailed, {
+            message: sanitizeForTerminal(message)
+          })
+        );
+      }
+      chokidarHandle = null;
+    }
+  };
+  return { start, stop };
+}
+function registerKernelExtensions(kernel, pluginRuntime, noBuiltIns) {
+  if (!noBuiltIns) {
+    const enabledBuiltIns = filterBuiltInManifests(
+      listBuiltIns(),
+      pluginRuntime.resolveEnabled
+    );
+    for (const manifest of enabledBuiltIns) kernel.registry.register(manifest);
+  }
+  for (const manifest of pluginRuntime.manifests) kernel.registry.register(manifest);
+}
+function buildBroadcasterEmitter(broadcaster) {
+  return {
+    emit(event) {
+      broadcaster.broadcast(event);
+    },
+    subscribe() {
+      return () => {
+      };
+    }
+  };
+}
+async function loadPriorState(dbPath) {
+  return tryWithSqlite({ databasePath: dbPath, autoBackup: false }, async (reader) => {
+    const loaded = await reader.scans.load();
+    if (loaded.nodes.length === 0) return null;
+    const extractorRuns = await reader.scans.loadExtractorRuns();
+    return { snapshot: loaded, extractorRuns };
+  });
+}
+function assembleRunOptions(args2) {
+  const runOptions = {
+    roots: [WATCH_ROOT],
+    scope: args2.scope,
+    tokenize: args2.tokenize,
+    ignoreFilter: args2.ignoreFilter,
+    strict: args2.strict,
+    emitter: args2.emitter
+  };
+  if (args2.composed) runOptions.extensions = args2.composed;
+  if (args2.priorState) {
+    runOptions.priorSnapshot = args2.priorState.snapshot;
+    runOptions.enableCache = true;
+    runOptions.priorExtractorRuns = args2.priorState.extractorRuns;
+  }
+  return runOptions;
+}
+async function persistOutcome(dbPath, ran) {
+  const { result, renameOps, extractorRuns, enrichments } = ran;
+  await withSqlite(
+    { databasePath: dbPath },
+    (writer) => writer.scans.persist(result, { renameOps, extractorRuns, enrichments })
+  );
+}
+
+// server/options.ts
+var DEFAULT_PORT = 4242;
+var DEFAULT_HOST = "127.0.0.1";
+var DEFAULT_SCOPE = "project";
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "localhost", "0:0:0:0:0:0:0:1"]);
+function isLoopbackHost(host) {
+  return LOOPBACK_HOSTS.has(host.toLowerCase());
+}
+function validateServerOptions(input) {
+  const filled = applyDefaults(input);
+  const portError = validatePort(filled.port);
+  if (portError !== null) return { ok: false, error: portError };
+  const scopeError = validateScope(filled.scope);
+  if (scopeError !== null) return { ok: false, error: scopeError };
+  const hostError = validateHost(filled.host, filled.devCors);
+  if (hostError !== null) return { ok: false, error: hostError };
+  const watcherError = validateWatcher(filled.noWatcher, filled.noBuiltIns, filled.noPlugins);
+  if (watcherError !== null) return { ok: false, error: watcherError };
+  const debounceError = validateWatcherDebounce(input.watcherDebounceMs);
+  if (debounceError !== null) return { ok: false, error: debounceError };
+  const options = {
+    port: filled.port,
+    host: filled.host,
+    scope: filled.scope,
+    dbPath: input.dbPath,
+    uiDist: filled.uiDist,
+    noBuiltIns: filled.noBuiltIns,
+    noPlugins: filled.noPlugins,
+    open: filled.open,
+    devCors: filled.devCors,
+    noWatcher: filled.noWatcher
+  };
+  if (input.watcherDebounceMs !== void 0) {
+    options.watcherDebounceMs = input.watcherDebounceMs;
+  }
+  return { ok: true, options };
+}
+function applyDefaults(input) {
+  return {
+    port: input.port ?? DEFAULT_PORT,
+    host: input.host ?? DEFAULT_HOST,
+    scope: input.scope ?? DEFAULT_SCOPE,
+    uiDist: input.uiDist ?? null,
+    noBuiltIns: input.noBuiltIns ?? false,
+    noPlugins: input.noPlugins ?? false,
+    open: input.open ?? true,
+    devCors: input.devCors ?? false,
+    noWatcher: input.noWatcher ?? false
+  };
+}
+function validatePort(port) {
+  if (!Number.isInteger(port)) {
+    return { code: "port-invalid", message: `port must be an integer (got ${port})`, value: String(port) };
+  }
+  if (port < 0 || port > 65535) {
+    return {
+      code: "port-out-of-range",
+      message: `port must be in [0, 65535] (got ${port})`,
+      value: String(port)
+    };
+  }
+  return null;
+}
+function validateScope(scope) {
+  if (scope !== "project" && scope !== "global") {
+    return { code: "scope-invalid", message: `scope must be "project" or "global"`, value: String(scope) };
+  }
+  return null;
+}
+function validateHost(host, devCors) {
+  if (devCors && !isLoopbackHost(host)) {
+    return {
+      code: "host-dev-cors-rejected",
+      message: `--dev-cors requires a loopback --host (got ${host})`,
+      value: host
+    };
+  }
+  return null;
+}
+function validateWatcher(noWatcher, noBuiltIns, _noPlugins) {
+  if (noWatcher) return null;
+  if (noBuiltIns) {
+    return {
+      code: "watcher-requires-pipeline",
+      message: "the watcher cannot run with --no-built-ins (would persist empty scans on every batch). Pass --no-watcher to opt out, or drop --no-built-ins.",
+      value: "no-built-ins"
+    };
+  }
+  return null;
+}
+function validateWatcherDebounce(value) {
+  if (value === void 0) return null;
+  if (!Number.isInteger(value) || value < 0) {
+    return {
+      code: "watcher-debounce-invalid",
+      message: `--watcher-debounce-ms must be a non-negative integer (got ${value})`,
+      value: String(value)
+    };
+  }
+  return null;
+}
+
+// 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");
+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;
+}
+function resolveExplicitUiDist(ctx, raw) {
+  return isAbsolute5(raw) ? raw : resolve19(ctx.cwd, raw);
+}
+function isUiBundleDir(path) {
+  if (!existsSync17(path)) return false;
+  try {
+    if (!statSync5(path).isDirectory()) return false;
+    return existsSync17(join14(path, INDEX_HTML2));
+  } catch {
+    return false;
+  }
+}
+
+// server/index.ts
+async function createServer(options, extra = {}) {
+  const specVersion = await resolveSpecVersion2();
+  const runtimeContext = extra.runtimeContext ?? defaultRuntimeContext();
+  const broadcaster = new WsBroadcaster();
+  const kindRegistry = await assembleKindRegistry(options);
+  const app = createApp({
+    options,
+    specVersion,
+    broadcaster,
+    runtimeContext,
+    kindRegistry
+  });
+  const wss = new WebSocketServer({ noServer: true });
+  const server = await listenAsync(app.fetch, wss, options.host, options.port);
+  const addr = server.address();
+  const address = normalizeAddress(addr, options.host, options.port);
+  let watcherService = null;
+  if (!options.noWatcher) {
+    const debounce = options.watcherDebounceMs;
+    const svcOpts = {
+      options,
+      runtimeContext,
+      broadcaster
+    };
+    if (debounce !== void 0) svcOpts.debounceMsOverride = debounce;
+    const candidate = createWatcherService(svcOpts);
+    try {
+      await candidate.start();
+      watcherService = candidate;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(
+        tx(SERVER_TEXTS.watcherBootFailed, {
+          message: sanitizeForTerminal(message)
+        })
+      );
+      try {
+        await candidate.stop();
+      } catch {
+      }
+    }
+  }
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    if (watcherService) {
+      try {
+        await watcherService.stop();
+      } catch {
+      }
+    }
+    broadcaster.shutdown();
+    await closeServer(server);
+    wss.close();
+  };
+  return { address, close, broadcaster };
+}
+async function assembleKindRegistry(options) {
+  const pluginRuntime = options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: options.scope });
+  for (const warn of pluginRuntime.warnings) {
+    log.warn(sanitizeForTerminal(warn));
+  }
+  const composed = composeScanExtensions({
+    noBuiltIns: options.noBuiltIns,
+    pluginRuntime
+  });
+  return buildKindRegistry(composed?.providers ?? []);
+}
+function listenAsync(fetchCallback, wss, host, port) {
+  return new Promise((resolveListen, rejectListen) => {
+    let settled = false;
+    const server = serve(
+      {
+        fetch: fetchCallback,
+        hostname: host,
+        port,
+        websocket: { server: wss }
+      },
+      () => {
+        if (settled) return;
+        settled = true;
+        server.removeListener("error", onBindError);
+        resolveListen(server);
+      }
+    );
+    const onBindError = (err) => {
+      if (settled) return;
+      settled = true;
+      rejectListen(err);
+    };
+    server.once("error", onBindError);
+  });
+}
+function closeServer(server) {
+  return new Promise((resolveClose, rejectClose) => {
+    server.close((err) => {
+      if (err) {
+        rejectClose(err);
+      } else {
+        resolveClose();
+      }
+    });
+    server.closeAllConnections?.();
+  });
+}
+function normalizeAddress(addr, fallbackHost, fallbackPort) {
+  if (addr === null || typeof addr === "string") {
+    return { host: fallbackHost, port: fallbackPort, family: "IPv4" };
+  }
+  return { host: addr.address, port: addr.port, family: addr.family };
+}
+
+// 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",
+  // 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",
+  // Bind failure (port in use, EACCES, etc.) → ExitCode.Error.
+  bindFailed: "sm serve: failed to bind {{host}}:{{port}} \u2014 {{message}}\n",
+  // Flag-validation failures — ExitCode.Error.
+  hostDevCorsRejected: "sm serve: --dev-cors requires a loopback --host (got {{host}}). Refusing per Decision #119.\n",
+  portOutOfRange: "sm serve: --port must be an integer in [0, 65535] (got {{value}}).\n",
+  portInvalid: "sm serve: --port must be a non-negative integer (got {{value}}).\n",
+  scopeInvalid: 'sm serve: --scope must be "project" or "global" (got {{value}}).\n',
+  // Watcher option failures — ExitCode.Error.
+  watcherRequiresPipeline: "sm serve: --no-built-ins is incompatible with the watcher (would persist empty scans on every batch). Pass --no-watcher to opt out, or drop --no-built-ins.\n",
+  watcherDebounceInvalid: "sm serve: --watcher-debounce-ms must be a non-negative integer (got {{value}}).\n",
+  // Generic operational error — surfaced when the server itself throws
+  // before the listener binds (e.g. UI bundle missing under explicit
+  // --ui-dist).
+  startupFailed: "sm serve: startup failed \u2014 {{message}}\n",
+  // DB-not-found (--db <path> doesn't exist) → ExitCode.NotFound.
+  dbNotFound: "sm serve: --db {{path}} does not exist.\n",
+  // Shutdown trace — printed once the listener has closed.
+  shutdown: "sm serve: shutdown complete.\n"
+};
+
+// cli/commands/serve.ts
+var ServeCommand = class extends SmCommand {
+  static paths = [["serve"]];
+  static usage = Command19.Usage({
+    category: "Setup",
+    description: "Start the Hono BFF (single-port: REST + WebSocket + SPA bundle).",
+    details: `
+      Boots the skill-map Web UI's backing server. One Node process
+      serves the Angular SPA, the REST API under /api/*, and the
+      WebSocket at /ws \u2014 single-port mandate, no proxy.
+
+      Default port is 4242, default host is 127.0.0.1. The server boots
+      even when the project DB is missing \u2014 /api/health reports
+      'db: missing' so the SPA renders an empty-state CTA instead of
+      failing the connection.
+
+      Loopback-only assumption through v0.6.0 (no per-connection auth on
+      /ws). Combining --dev-cors with a non-loopback --host is rejected.
+
+      SIGINT / SIGTERM trigger a graceful shutdown.
+    `,
+    examples: [
+      ["Start on the default port and open the browser", "$0 serve"],
+      ["Custom port, no browser auto-open", "$0 serve --port 5000 --no-open"],
+      ["Use the global scope DB", "$0 serve --scope global"],
+      ["Point at a pre-built UI bundle", "$0 serve --ui-dist ./ui/dist/browser"]
+    ]
+  });
+  port = Option19.String("--port", {
+    required: false,
+    description: "Listening port (default 4242). 0 = OS-assigned."
+  });
+  host = Option19.String("--host", {
+    required: false,
+    description: "Listening host (default 127.0.0.1). Loopback-only enforced when --dev-cors is set."
+  });
+  scope = Option19.String("--scope", {
+    required: false,
+    description: "project | global. Alias for -g/--global. Default: project."
+  });
+  noBuiltIns = Option19.Boolean("--no-built-ins", false, {
+    description: "Skip built-in plugin registration (parity with sm scan --no-built-ins)."
+  });
+  noPlugins = Option19.Boolean("--no-plugins", false, {
+    description: "Skip drop-in plugin discovery."
+  });
+  // `Option.Boolean('--open', true)` — Clipanion's parser auto-derives
+  // the `--no-open` inverse for every boolean flag (search for
+  // `--no-${name.slice(2)}` in clipanion's core), so the explicit
+  // `--no-open` descriptor must NOT be declared here or the parser sees
+  // 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, {
+    description: "Auto-open the SPA in the user's default browser after listen. --no-open opts out."
+  });
+  devCors = Option19.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, {
+    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 });
+  // Long-running daemon — `done in <…>` after a graceful shutdown is
+  // noise. Mirrors `sm watch`'s opt-out.
+  emitElapsed = false;
+  // CLI orchestrator with multi-flag handling — each `if (this.flag)`
+  // branch is one cyclomatic point. Splitting per branch scatters the
+  // validation away from the flag it gates. Per AGENTS.md §Linting
+  // category 1 ("CLI orchestrators with multi-flag handling").
+  // eslint-disable-next-line complexity
+  async run() {
+    const runtimeCtx = defaultRuntimeContext();
+    const scopeResult = resolveScope(this.scope, this.global);
+    if (!scopeResult.ok) {
+      this.context.stderr.write(
+        tx(SERVE_TEXTS.scopeInvalid, { value: sanitizeForTerminal(scopeResult.value) })
+      );
+      return ExitCode.Error;
+    }
+    const scope = scopeResult.scope;
+    if (scope === "global") this.global = true;
+    const portResult = parsePort(this.port);
+    if (!portResult.ok) {
+      this.context.stderr.write(
+        tx(SERVE_TEXTS.portInvalid, { value: sanitizeForTerminal(portResult.value) })
+      );
+      return ExitCode.Error;
+    }
+    const dbPath = resolveDbPath({ global: this.global, db: this.db, ...runtimeCtx });
+    if (this.db !== void 0 && !existsSync18(dbPath)) {
+      this.context.stderr.write(
+        tx(SERVE_TEXTS.dbNotFound, { path: sanitizeForTerminal(dbPath) })
+      );
+      return ExitCode.NotFound;
+    }
+    const uiDistResult = resolveUiDist(runtimeCtx, this.uiDist);
+    if (!uiDistResult.ok) {
+      this.context.stderr.write(
+        tx(SERVE_TEXTS.startupFailed, { message: sanitizeForTerminal(uiDistResult.message) })
+      );
+      return ExitCode.Error;
+    }
+    const debounceResult = parseDebounce(this.watcherDebounceMs);
+    if (!debounceResult.ok) {
+      this.context.stderr.write(
+        tx(SERVE_TEXTS.watcherDebounceInvalid, {
+          value: sanitizeForTerminal(debounceResult.value)
+        })
+      );
+      return ExitCode.Error;
+    }
+    const input = {
+      dbPath,
+      scope,
+      uiDist: uiDistResult.uiDist,
+      noBuiltIns: this.noBuiltIns,
+      noPlugins: this.noPlugins,
+      open: this.open,
+      devCors: this.devCors,
+      noWatcher: this.noWatcher
+    };
+    if (portResult.port !== void 0) input.port = portResult.port;
+    if (this.host !== void 0) input.host = this.host;
+    if (debounceResult.value !== void 0) input.watcherDebounceMs = debounceResult.value;
+    const validation = validateServerOptions(input);
+    if (!validation.ok) {
+      this.context.stderr.write(formatValidationError(validation.error));
+      return ExitCode.Error;
+    }
+    let handle;
+    try {
+      handle = await createServer(validation.options);
+    } catch (err) {
+      const message = formatErrorMessage(err);
+      this.context.stderr.write(
+        tx(SERVE_TEXTS.bindFailed, {
+          host: sanitizeForTerminal(validation.options.host),
+          port: validation.options.port,
+          message: sanitizeForTerminal(message)
+        })
+      );
+      return ExitCode.Error;
+    }
+    this.context.stderr.write(
+      tx(SERVE_TEXTS.boot, {
+        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
+      })
+    );
+    if (validation.options.open) {
+      const url = `http://${handle.address.host}:${handle.address.port}/`;
+      tryOpenBrowser(url, this.context.stderr);
+    }
+    await waitForShutdown();
+    await handle.close();
+    this.context.stderr.write(SERVE_TEXTS.shutdown);
+    return ExitCode.Ok;
+  }
+};
+function parsePort(raw) {
+  if (raw === void 0) return { ok: true, port: void 0 };
+  const trimmed = raw.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== trimmed) {
+    return { ok: false, value: raw };
+  }
+  return { ok: true, port: parsed };
+}
+function parseDebounce(raw) {
+  if (raw === void 0) return { ok: true, value: void 0 };
+  const trimmed = raw.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== trimmed) {
+    return { ok: false, value: raw };
+  }
+  return { ok: true, value: parsed };
+}
+function resolveScope(rawScope, global) {
+  if (rawScope === void 0) return { ok: true, scope: global ? "global" : "project" };
+  if (rawScope === "project" || rawScope === "global") {
+    return { ok: true, scope: rawScope };
+  }
+  return { ok: false, value: rawScope };
+}
+function resolveUiDist(ctx, raw) {
+  if (raw === void 0) {
+    return { ok: true, uiDist: resolveDefaultUiDist(ctx) };
+  }
+  const abs = resolveExplicitUiDist(ctx, raw);
+  if (!isUiBundleDir(abs)) {
+    return {
+      ok: false,
+      message: `--ui-dist ${abs} does not exist or is not a directory containing index.html`
+    };
+  }
+  return { ok: true, uiDist: abs };
+}
+function formatValidationError(err) {
+  switch (err.code) {
+    case "host-dev-cors-rejected":
+      return tx(SERVE_TEXTS.hostDevCorsRejected, { host: sanitizeForTerminal(err.value) });
+    case "port-out-of-range":
+      return tx(SERVE_TEXTS.portOutOfRange, { value: sanitizeForTerminal(err.value) });
+    case "port-invalid":
+      return tx(SERVE_TEXTS.portInvalid, { value: sanitizeForTerminal(err.value) });
+    case "scope-invalid":
+      return tx(SERVE_TEXTS.scopeInvalid, { value: sanitizeForTerminal(err.value) });
+    case "watcher-requires-pipeline":
+      return tx(SERVE_TEXTS.watcherRequiresPipeline, { value: sanitizeForTerminal(err.value) });
+    case "watcher-debounce-invalid":
+      return tx(SERVE_TEXTS.watcherDebounceInvalid, { value: sanitizeForTerminal(err.value) });
+    default:
+      return tx(SERVE_TEXTS.startupFailed, { message: sanitizeForTerminal(err.message) });
+  }
+}
+function waitForShutdown() {
+  return new Promise((resolveShutdown) => {
+    const onSignal = () => {
+      process.removeListener("SIGINT", onSignal);
+      process.removeListener("SIGTERM", onSignal);
+      resolveShutdown();
+    };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+  });
+}
+function tryOpenBrowser(url, stderr) {
+  try {
+    const platform = process.platform;
+    let command;
+    let args2;
+    if (platform === "darwin") {
+      command = "open";
+      args2 = [url];
+    } else if (platform === "win32") {
+      command = "cmd";
+      args2 = ["/c", "start", '""', url];
+    } else {
+      command = "xdg-open";
+      args2 = [url];
+    }
+    const child = spawn(command, args2, { detached: true, stdio: "ignore" });
+    child.on("error", (err) => {
+      stderr.write(
+        tx(SERVE_TEXTS.openFailed, {
+          message: sanitizeForTerminal(formatErrorMessage(err)),
+          url: sanitizeForTerminal(url)
+        })
+      );
+    });
+    child.unref();
+  } catch (err) {
+    stderr.write(
+      tx(SERVE_TEXTS.openFailed, {
+        message: sanitizeForTerminal(formatErrorMessage(err)),
+        url: sanitizeForTerminal(url)
+      })
+    );
+  }
+}
+
+// cli/commands/show.ts
+import { Command as Command20, Option as Option20 } from "clipanion";
+
+// cli/i18n/show.texts.ts
+var SHOW_TEXTS = {
+  nodeNotFound: "Node not found: {{nodePath}}\n",
+  // --- renderHuman labels ------------------------------------------------
+  sectionFrontmatter: "Frontmatter:",
+  sectionLinksOut: "Links out",
+  sectionLinksIn: "Links in",
+  sectionIssues: "Issues",
+  placeholderNone: "  (none)",
+  sectionHeader: "{{label}} ({{count}}, {{unique}} unique):",
+  issuesHeader: "Issues ({{count}}):",
+  issueRow: "  - [{{severity}}] {{ruleId}}: {{message}}",
+  // --- formatGroupedLink ------------------------------------------------
+  /**
+   * Bullet line for one grouped link in the in/out lists. `{{kind}}` and
+   * `{{endpoint}}` are pre-sanitized by the caller; `{{dup}}` is the
+   * `(×N)` count when the row collapses multiple identical edges, empty
+   * otherwise; `{{sources}}` is the trailing `  sources: a, b` segment
+   * (empty when the link has no sources).
+   */
+  groupedLinkHead: "  - [{{kind}}/{{confidence}}] {{arrow}} {{endpoint}}{{dup}}{{sources}}",
+  groupedLinkDup: " (\xD7{{count}})",
+  groupedLinkSources: "  sources: {{values}}",
+  // --- renderNodeHeader labels ------------------------------------------
+  nodeIdentity: "{{path}} [{{kind}}] (provider: {{provider}})",
+  nodeFieldTitle: "title:        {{value}}",
+  nodeFieldDescription: "description:  {{value}}",
+  nodeFieldStability: "stability:    {{value}}",
+  nodeFieldVersion: "version:      {{value}}",
+  nodeFieldAuthor: "author:       {{value}}",
+  nodeWeight: "Weight: bytes {{total}} total / {{frontmatter}} frontmatter / {{body}} body",
+  nodeTokens: "        tokens {{total}} total / {{frontmatter}} frontmatter / {{body}} body",
+  nodeExternalRefs: "External refs: {{count}}"
+};
+
+// cli/commands/show.ts
+var ShowCommand = class extends SmCommand {
+  static paths = [["show"]];
+  static usage = Command20.Usage({
+    category: "Browse",
+    description: "Node detail: weight, frontmatter, links, issues.",
+    details: `
       Loads a single node from the persisted snapshot, plus every link
-      (in and out) and every current issue touching it. Findings and
-      summaries are reserved slots and remain empty / null until the
-      Step 10 / Step 11 features land.
+      (in and out) and every current issue touching it. Step 10
+      (findings) and Step 11 (summary) will add fields when their
+      backing tables ship.
 
       Run \`sm scan\` first to populate the DB.
     `,
@@ -11776,11 +13620,8 @@ var ShowCommand = class extends Command18 {
       ["Machine-readable detail", "$0 show .claude/agents/architect.md --json"]
     ]
   });
-  nodePath = Option18.String({ required: true });
-  global = Option18.Boolean("-g,--global", false);
-  db = Option18.String("--db", { required: false });
-  json = Option18.Boolean("--json", false);
-  async execute() {
+  nodePath = Option20.String({ required: true });
+  async run() {
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(dbPath, this.context.stderr)) return ExitCode.NotFound;
     return withSqlite({ databasePath: dbPath, autoBackup: false }, async (adapter) => {
@@ -11793,9 +13634,7 @@ var ShowCommand = class extends Command18 {
         node: bundle.node,
         linksOut: bundle.linksOut,
         linksIn: bundle.linksIn,
-        issues: bundle.issues,
-        findings: [],
-        summary: null
+        issues: bundle.issues
       };
       if (this.json) {
         this.context.stdout.write(JSON.stringify(doc) + "\n");
@@ -11930,7 +13769,7 @@ function rankConfidenceForGrouping(c) {
 }
 
 // cli/commands/stubs.ts
-import { Command as Command19, Option as Option19 } from "clipanion";
+import { Command as Command21, Option as Option21 } from "clipanion";
 
 // cli/i18n/stubs.texts.ts
 var STUBS_TEXTS = {
@@ -11945,9 +13784,9 @@ function notImplemented(cmd, verb) {
   cmd.context.stderr.write(tx(STUBS_TEXTS.notImplemented, { verb }));
   return ExitCode.Error;
 }
-var DoctorCommand = class extends Command19 {
+var DoctorCommand = class extends Command21 {
   static paths = [["doctor"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Setup",
     description: planned("Diagnostic report: DB integrity, pending migrations, orphan rows, plugin status, runner availability.")
   });
@@ -11955,23 +13794,23 @@ var DoctorCommand = class extends Command19 {
     return notImplemented(this, "doctor");
   }
 };
-var FindingsCommand = class extends Command19 {
+var FindingsCommand = class extends Command21 {
   static paths = [["findings"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Browse",
     description: planned("Probabilistic findings: injection, stale summaries, low confidence.")
   });
-  kind = Option19.String("--kind", { required: false });
-  since = Option19.String("--since", { required: false });
-  threshold = Option19.String("--threshold", { required: false });
-  json = Option19.Boolean("--json", false);
+  kind = Option21.String("--kind", { required: false });
+  since = Option21.String("--since", { required: false });
+  threshold = Option21.String("--threshold", { required: false });
+  json = Option21.Boolean("--json", false);
   async execute() {
     return notImplemented(this, "findings");
   }
 };
-var ActionsListCommand = class extends Command19 {
+var ActionsListCommand = class extends Command21 {
   static paths = [["actions", "list"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Registered action types (manifest view).")
   });
@@ -11979,138 +13818,125 @@ var ActionsListCommand = class extends Command19 {
     return notImplemented(this, "actions list");
   }
 };
-var ActionsShowCommand = class extends Command19 {
+var ActionsShowCommand = class extends Command21 {
   static paths = [["actions", "show"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Full action manifest, including preconditions and expected duration.")
   });
-  id = Option19.String({ required: true });
+  id = Option21.String({ required: true });
   async execute() {
     return notImplemented(this, "actions show");
   }
 };
-var JobSubmitCommand = class extends Command19 {
+var JobSubmitCommand = class extends Command21 {
   static paths = [["job", "submit"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Enqueue a single job or fan out to every matching node (--all).")
   });
-  action = Option19.String({ required: true });
-  node = Option19.String("-n", { required: false });
-  all = Option19.Boolean("--all", false);
-  run = Option19.Boolean("--run", false);
-  force = Option19.Boolean("--force", false);
-  ttl = Option19.String("--ttl", { required: false });
-  priority = Option19.String("--priority", { required: false });
+  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 });
   async execute() {
     return notImplemented(this, "job submit");
   }
 };
-var JobListCommand = class extends Command19 {
+var JobListCommand = class extends Command21 {
   static paths = [["job", "list"]];
-  static usage = Command19.Usage({ category: "Jobs", description: planned("List jobs.") });
-  status = Option19.String("--status", { required: false });
-  action = Option19.String("--action", { required: false });
-  node = Option19.String("--node", { required: false });
+  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 });
   async execute() {
     return notImplemented(this, "job list");
   }
 };
-var JobShowCommand = class extends Command19 {
+var JobShowCommand = class extends Command21 {
   static paths = [["job", "show"]];
-  static usage = Command19.Usage({ category: "Jobs", description: planned("Job detail: state, claim time, TTL, runner, content hash.") });
-  id = Option19.String({ required: true });
+  static usage = Command21.Usage({ category: "Jobs", description: planned("Job detail: state, claim time, TTL, runner, content hash.") });
+  id = Option21.String({ required: true });
   async execute() {
     return notImplemented(this, "job show");
   }
 };
-var JobPreviewCommand = class extends Command19 {
+var JobPreviewCommand = class extends Command21 {
   static paths = [["job", "preview"]];
-  static usage = Command19.Usage({ category: "Jobs", description: planned("Render the job MD file without executing.") });
-  id = Option19.String({ required: true });
+  static usage = Command21.Usage({ category: "Jobs", description: planned("Render the job MD file without executing.") });
+  id = Option21.String({ required: true });
   async execute() {
     return notImplemented(this, "job preview");
   }
 };
-var JobClaimCommand = class extends Command19 {
+var JobClaimCommand = class extends Command21 {
   static paths = [["job", "claim"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Atomic primitive: return next queued job id, mark it running.")
   });
-  filter = Option19.String("--filter", { required: false });
+  filter = Option21.String("--filter", { required: false });
   async execute() {
     return notImplemented(this, "job claim");
   }
 };
-var JobRunCommand = class extends Command19 {
+var JobRunCommand = class extends Command21 {
   static paths = [["job", "run"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Full CLI-runner loop: claim + spawn + record.")
   });
-  all = Option19.Boolean("--all", false);
-  max = Option19.String("--max", { required: false });
+  all = Option21.Boolean("--all", false);
+  max = Option21.String("--max", { required: false });
   async execute() {
     return notImplemented(this, "job run");
   }
 };
-var JobStatusCommand = class extends Command19 {
+var JobStatusCommand = class extends Command21 {
   static paths = [["job", "status"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Counts (per status) or single-job status.")
   });
-  id = Option19.String({ required: false });
+  id = Option21.String({ required: false });
   async execute() {
     return notImplemented(this, "job status");
   }
 };
-var JobCancelCommand = class extends Command19 {
+var JobCancelCommand = class extends Command21 {
   static paths = [["job", "cancel"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Force a running job to failed with reason user-cancelled.")
   });
-  id = Option19.String({ required: false });
-  all = Option19.Boolean("--all", false);
+  id = Option21.String({ required: false });
+  all = Option21.Boolean("--all", false);
   async execute() {
     return notImplemented(this, "job cancel");
   }
 };
-var RecordCommand = class extends Command19 {
+var RecordCommand = class extends Command21 {
   static paths = [["record"]];
-  static usage = Command19.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Close a running job with success or failure. Nonce is the sole credential.")
   });
-  id = Option19.String("--id", { required: true });
-  nonce = Option19.String("--nonce", { required: true });
-  status = Option19.String("--status", { required: true });
-  report = Option19.String("--report", { required: false });
-  tokensIn = Option19.String("--tokens-in", { required: false });
-  tokensOut = Option19.String("--tokens-out", { required: false });
-  durationMs = Option19.String("--duration-ms", { required: false });
-  model = Option19.String("--model", { required: false });
-  error = Option19.String("--error", { required: false });
+  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 });
   async execute() {
     return notImplemented(this, "record");
   }
 };
-var ServeCommand = class extends Command19 {
-  static paths = [["serve"]];
-  static usage = Command19.Usage({
-    category: "Setup",
-    description: planned("Start Hono + WebSocket for the Web UI. Single-port mandate: SPA + REST + WS under one listener.")
-  });
-  port = Option19.String("--port", { required: false });
-  host = Option19.String("--host", { required: false });
-  noOpen = Option19.Boolean("--no-open", false);
-  async execute() {
-    return notImplemented(this, "serve");
-  }
-};
 var STUB_COMMANDS = [
   DoctorCommand,
   FindingsCommand,
@@ -12124,12 +13950,11 @@ var STUB_COMMANDS = [
   JobRunCommand,
   JobStatusCommand,
   JobCancelCommand,
-  RecordCommand,
-  ServeCommand
+  RecordCommand
 ];
 
 // cli/commands/version.ts
-import { Command as Command20, Option as Option20 } from "clipanion";
+import { Command as Command22 } from "clipanion";
 
 // cli/i18n/version.texts.ts
 var VERSION_TEXTS = {
@@ -12139,17 +13964,19 @@ var VERSION_TEXTS = {
 };
 
 // cli/commands/version.ts
-var VersionCommand = class extends Command20 {
+var VersionCommand = class extends SmCommand {
   static paths = [["version"]];
-  static usage = Command20.Usage({
+  static usage = Command22.Usage({
     category: "Introspection",
     description: "Print the CLI / kernel / spec / runtime / db-schema version matrix."
   });
-  json = Option20.Boolean("--json", false);
-  async execute() {
+  // Informational verb — no `done in <…>` line; the version matrix is
+  // the entire output.
+  emitElapsed = false;
+  async run() {
     const runtime = `Node ${process.version}`;
     const kernelVersion = VERSION;
-    const specVersion = await resolveSpecVersion2();
+    const specVersion = await resolveSpecVersion3();
     const dbSchema = await resolveDbSchemaVersion();
     if (this.json) {
       const payload = {
@@ -12175,7 +14002,7 @@ var VersionCommand = class extends Command20 {
     return ExitCode.Ok;
   }
 };
-async function resolveSpecVersion2() {
+async function resolveSpecVersion3() {
   try {
     const mod = await import("@skill-map/spec", { with: { type: "json" } });
     const version = mod.default?.specPackageVersion;
@@ -12211,6 +14038,7 @@ cli.register(HelpCommand);
 cli.register(InitCommand);
 cli.register(ScanCommand);
 cli.register(ScanCompareCommand);
+cli.register(ServeCommand);
 cli.register(WatchCommand);
 cli.register(VersionCommand);
 cli.register(ListCommand);