@skill-map/cli 0.9.0 → 0.10.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 }));
@@ -1367,8 +1386,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 +1433,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 +1488,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 +1709,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 +1753,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 +2267,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 +2652,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 +4651,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 +4780,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 +4906,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 +5066,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 +5077,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 +5102,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 +5112,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 +5145,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 +5157,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 +5229,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 +5242,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 +5255,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 +5263,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 +5280,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 +5296,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 +5321,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 +5784,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 +5820,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 +5948,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 +6024,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 +6045,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 +6071,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 +6084,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 +6097,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 +6144,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 +6160,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 +6171,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 +6259,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 +6270,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 +6285,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 +6319,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 +6342,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 +6536,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 +6693,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 +6719,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 +6905,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 +6915,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 +6934,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 +6975,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.10.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -6950,6 +7027,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 +7038,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 +7059,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 +7156,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 +7172,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 +7491,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 +7547,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 +8711,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 +8737,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 +8754,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 +8778,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 +8803,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 +8826,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 +8906,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 +8915,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 +8935,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 +9022,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 +9044,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 +9091,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 +9115,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 +9188,6 @@ var HistoryStatsCommand = class extends Command9 {
       } else {
         this.context.stdout.write(renderStats(stats));
       }
-      emitDoneStderr(this.context.stderr, elapsed, this.quiet);
       return ExitCode.Ok;
     });
   }
@@ -9252,7 +9299,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 +9307,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 +9345,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 +9374,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 +9494,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 +9520,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 +9543,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) {
@@ -9607,7 +9648,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 +9701,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 +9718,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 +9750,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 +9772,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 +9838,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 +9864,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 +9940,6 @@ var OrphansUndoRenameCommand = class extends Command12 {
           rows: summaryTotal(summary)
         })
       );
-      emitDoneStderr(this.context.stderr, elapsed, this.quiet);
       return ExitCode.Ok;
     });
   }
@@ -10008,7 +10033,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 +10176,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 +10243,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 +10446,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 +10461,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 +10570,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 +10596,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 +10606,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 +10644,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 +10666,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 +10687,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 +10709,7 @@ var PluginsDisableCommand = class extends TogglePluginsBase {
       with directed guidance.
     `
   });
-  async execute() {
+  async run() {
     return this.toggle(false);
   }
 };
@@ -10706,7 +10730,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 +10771,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 +10798,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 +10811,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 +10987,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,24 +11030,174 @@ var SCAN_TEXTS = {
   compareDeltaIssueRemoved: "- [{{severity}}] {{ruleId}}: {{message}}"
 };
 
-// cli/commands/watch.ts
-import { Command as Command15, Option as Option15 } from "clipanion";
-
-// cli/i18n/watch.texts.ts
-var WATCH_TEXTS = {
-  configLoadFailure: "sm watch: {{message}}\n",
-  initialScanFailed: "sm watch: initial scan failed \u2014 {{message}}\n",
-  batchFailed: "sm watch: batch failed \u2014 {{message}}\n",
-  scanFailed: "sm watch: scan failed \u2014 {{message}}\n",
-  watcherError: "sm watch: watcher error \u2014 {{message}}\n",
+// 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 = {
+  configLoadFailure: "sm watch: {{message}}\n",
+  initialScanFailed: "sm watch: initial scan failed \u2014 {{message}}\n",
+  batchFailed: "sm watch: batch failed \u2014 {{message}}\n",
+  scanFailed: "sm watch: scan failed \u2014 {{message}}\n",
+  watcherError: "sm watch: watcher error \u2014 {{message}}\n",
   starting: "sm watch: starting on {{rootsCount}} root(s), debounce {{debounceMs}}ms\n",
   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 +11261,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 +11296,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 +11354,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 +11382,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 +11459,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 +11580,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 +11611,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 +11627,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,8 +11802,646 @@ function renderDeltaIssues(issues) {
   return lines;
 }
 
+// cli/commands/serve.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync18 } from "fs";
+import { Command as Command19, Option as Option19 } from "clipanion";
+
+// server/index.ts
+import { serve } from "@hono/node-server";
+import { WebSocketServer } from "ws";
+
+// server/app.ts
+import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+// 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/static.ts
+import { existsSync as existsSync16 } from "fs";
+import { readFile as readFile4 } 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 readFile4(absPath);
+  return c.body(buf, 200, { "content-type": mimeFor(absPath) });
+}
+
+// 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));
+  }
+  app.get("/api/health", (c) => {
+    const payload = buildHealth({
+      dbPath: deps.options.dbPath,
+      scope: deps.options.scope,
+      specVersion: deps.specVersion
+    });
+    return c.json(payload);
+  });
+  app.all("/api/*", (c) => {
+    throw new HTTPException(404, { message: `Unknown API endpoint: ${c.req.path}` });
+  });
+  deps.attachWs(app);
+  app.use("*", createStaticHandler(deps.options.uiDist));
+  app.get("*", createSpaFallback(deps.options.uiDist));
+  app.notFound((c) => {
+    throw new HTTPException(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 HTTPException) {
+    const status = err.status;
+    const envelope2 = {
+      ok: false,
+      error: {
+        code: codeForStatus(status),
+        message: err.message,
+        details: null
+      }
+    };
+    return c.json(envelope2, status);
+  }
+  const envelope = {
+    ok: false,
+    error: {
+      code: "internal",
+      message: formatErrorMessage(err),
+      details: null
+    }
+  };
+  return c.json(envelope, 500);
+}
+
+// server/ws.ts
+import { upgradeWebSocket } from "@hono/node-server";
+var WS_PATH = "/ws";
+var NOOP_CLOSE_CODE = 1e3;
+var NOOP_CLOSE_REASON = "no broadcaster yet";
+function noopWebSocketRoute(app) {
+  app.get(
+    WS_PATH,
+    upgradeWebSocket(() => ({
+      onOpen(_event, ws) {
+        ws.close(NOOP_CLOSE_CODE, NOOP_CLOSE_REASON);
+      }
+    }))
+  );
+}
+
+// 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 };
+  return {
+    ok: true,
+    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
+    }
+  };
+}
+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
+  };
+}
+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;
+}
+
+// server/paths.ts
+import { existsSync as existsSync17, statSync as statSync5 } from "fs";
+import { dirname as dirname9, isAbsolute as isAbsolute4, 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 isAbsolute4(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) {
+  const specVersion = await resolveSpecVersion2();
+  const app = createApp({ options, specVersion, attachWs: noopWebSocketRoute });
+  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 closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    await closeServer(server);
+    wss.close();
+  };
+  return { address, close };
+}
+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',
+  // 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 });
+  // 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 input = {
+      dbPath,
+      scope,
+      uiDist: uiDistResult.uiDist,
+      noBuiltIns: this.noBuiltIns,
+      noPlugins: this.noPlugins,
+      open: this.open,
+      devCors: this.devCors
+    };
+    if (portResult.port !== void 0) input.port = portResult.port;
+    if (this.host !== void 0) input.host = this.host;
+    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 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) });
+    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 Command18, Option as Option18 } from "clipanion";
+import { Command as Command20, Option as Option20 } from "clipanion";
 
 // cli/i18n/show.texts.ts
 var SHOW_TEXTS = {
@@ -11758,16 +12479,16 @@ var SHOW_TEXTS = {
 };
 
 // cli/commands/show.ts
-var ShowCommand = class extends Command18 {
+var ShowCommand = class extends SmCommand {
   static paths = [["show"]];
-  static usage = Command18.Usage({
+  static usage = Command20.Usage({
     category: "Browse",
-    description: "Node detail: weight, frontmatter, links, issues, findings, summary.",
+    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 +12497,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 +12511,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 +12646,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 +12661,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 +12671,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 +12695,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 +12827,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 +12841,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 +12879,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 +12915,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);