@skill-map/cli 0.14.0 → 0.15.0

package/dist/cli.js

@@ -7353,108 +7353,16 @@ var GraphCommand = class extends SmCommand {
   }
 };
 
-// cli/commands/guide.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "fs";
-import { writeFile } from "fs/promises";
-import { dirname as dirname9, join as join10, resolve as resolve13 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
-import { Command as Command8, Option as Option8 } from "clipanion";
-
-// cli/i18n/guide.texts.ts
-var GUIDE_TEXTS = {
-  // Success — written to stdout after `<cwd>/sm-guide.md` is created.
-  written: 'Listo. sm-guide.md creado en {{cwd}}. Abr\xED Claude Code ac\xE1 y decile "gu\xEDame" para arrancar la gu\xEDa interactiva.\n',
-  // Refusal — `sm-guide.md` already exists and `--force` was not set.
-  // Goes to stderr, exit code 2 (operational error per spec § Exit codes).
-  alreadyExists: "sm guide: sm-guide.md ya existe en {{cwd}}. Us\xE1 `--force` para sobrescribir.\n",
-  // I/O failure on write or on reading the bundled SKILL source.
-  writeFailed: "sm guide: no se pudo escribir sm-guide.md: {{message}}\n",
-  sourceMissing: "sm guide: no se pudo leer la gu\xEDa empaquetada (SKILL.md) desde la instalaci\xF3n. Reinstal\xE1 @skill-map/cli o report\xE1 el bug.\n"
-};
-
-// cli/commands/guide.ts
-var SM_GUIDE_FILENAME = "sm-guide.md";
-var GuideCommand = class extends SmCommand {
-  static paths = [["guide"]];
-  static usage = Command8.Usage({
-    category: "Setup",
-    description: "Materialize the interactive tester guide (sm-guide.md) in the current directory.",
-    details: `
-      Drops the canonical SKILL.md content as ./sm-guide.md so a tester
-      can open Claude Code in the cwd and trigger the sm-guide skill
-      ("gu\xEDame"). Top-level only \u2014 no subdirectory is created.
-
-      Does NOT require an initialized .skill-map/ project. Refuses to
-      overwrite an existing sm-guide.md unless --force is passed.
-    `,
-    examples: [
-      ["Materialize the guide in the cwd", "$0 guide"],
-      ["Overwrite an existing sm-guide.md", "$0 guide --force"]
-    ]
-  });
-  force = Option8.Boolean("--force", false, {
-    description: "Overwrite an existing sm-guide.md without prompting."
-  });
-  async run() {
-    const ctx = defaultRuntimeContext();
-    const target = join10(ctx.cwd, SM_GUIDE_FILENAME);
-    if (await pathExists(target) && !this.force) {
-      this.context.stderr.write(tx(GUIDE_TEXTS.alreadyExists, { cwd: ctx.cwd }));
-      return ExitCode.Error;
-    }
-    let body;
-    try {
-      body = loadBundledGuideText();
-    } catch {
-      this.context.stderr.write(GUIDE_TEXTS.sourceMissing);
-      return ExitCode.Error;
-    }
-    try {
-      await writeFile(target, body);
-    } catch (err) {
-      this.context.stderr.write(
-        tx(GUIDE_TEXTS.writeFailed, { message: formatErrorMessage(err) })
-      );
-      return ExitCode.Error;
-    }
-    this.context.stdout.write(tx(GUIDE_TEXTS.written, { cwd: ctx.cwd }));
-    return ExitCode.Ok;
-  }
-};
-var cachedGuide = null;
-function loadBundledGuideText() {
-  if (cachedGuide !== null) return cachedGuide;
-  cachedGuide = readGuideFromDisk();
-  return cachedGuide;
-}
-function readGuideFromDisk() {
-  const here = dirname9(fileURLToPath5(import.meta.url));
-  const candidates = [
-    // dev: src/cli/commands/ → repo-root .claude/skills/sm-guide/SKILL.md
-    resolve13(here, "../../../.claude/skills/sm-guide/SKILL.md"),
-    // bundled: dist/cli.js → dist/cli/guide/sm-guide.md (sibling)
-    resolve13(here, "cli/guide/sm-guide.md"),
-    // bundled fallback: any-depth → cli/guide/sm-guide.md
-    resolve13(here, "../cli/guide/sm-guide.md")
-  ];
-  for (const candidate of candidates) {
-    if (existsSync12(candidate)) {
-      return readFileSync10(candidate, "utf8");
-    }
-  }
-  throw new Error(`SKILL.md not found in any candidate location (last tried: ${candidates[candidates.length - 1]})`);
-}
-
 // cli/commands/help.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 import { createRequire as createRequire4 } from "module";
-import { resolve as resolve14 } from "path";
-import { Command as Command9, Option as Option9 } from "clipanion";
+import { resolve as resolve13 } from "path";
+import { Command as Command8, Option as Option8 } from "clipanion";
 
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.14.0",
+  version: "0.15.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -7513,7 +7421,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "0.14.1",
+    "@skill-map/spec": "0.15.0",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -7630,9 +7538,9 @@ var HELP_TEXTS = {
 };
 
 // cli/commands/help.ts
-var HelpCommand = class extends Command9 {
+var HelpCommand = class extends Command8 {
   static paths = [["help"]];
-  static usage = Command9.Usage({
+  static usage = Command8.Usage({
     category: "Introspection",
     description: "Self-describing introspection. --format human|md|json.",
     details: `
@@ -7646,8 +7554,8 @@ var HelpCommand = class extends Command9 {
         json            \u2014 structured surface dump per spec/cli-contract.md.
     `
   });
-  verbParts = Option9.Rest({ required: 0 });
-  format = Option9.String("--format", "human");
+  verbParts = Option8.Rest({ required: 0 });
+  format = Option8.String("--format", "human");
   async execute() {
     const format = normalizeFormat(this.format);
     if (!format) {
@@ -7769,8 +7677,8 @@ function resolveSpecVersion() {
   try {
     const req = createRequire4(import.meta.url);
     const indexPath = req.resolve("@skill-map/spec/index.json");
-    const pkgPath = resolve14(indexPath, "..", "package.json");
-    const pkg = JSON.parse(readFileSync11(pkgPath, "utf8"));
+    const pkgPath = resolve13(indexPath, "..", "package.json");
+    const pkg = JSON.parse(readFileSync10(pkgPath, "utf8"));
     return pkg.version;
   } catch {
     return "unknown";
@@ -7965,7 +7873,7 @@ function renderCompactOverview(verbs) {
   lines.push(HELP_TEXTS.compactFooter);
   return lines.join("\n") + "\n";
 }
-var RootHelpCommand = class extends Command9 {
+var RootHelpCommand = class extends Command8 {
   static paths = [["-h"], ["--help"]];
   async execute() {
     const rawDefs = this.cli.definitions();
@@ -8021,13 +7929,13 @@ function registeredVerbPaths(cli2) {
 }
 
 // cli/commands/init.ts
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
-import { join as join11 } from "path";
-import { Command as Command10, Option as Option10 } from "clipanion";
+import { mkdir as mkdir2, readFile as readFile2, writeFile } from "fs/promises";
+import { join as join10 } from "path";
+import { Command as Command9, Option as Option9 } from "clipanion";
 
 // kernel/orchestrator.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync13, statSync as statSync3 } from "fs";
+import { existsSync as existsSync12, statSync as statSync3 } from "fs";
 import { Tiktoken } from "js-tiktoken/lite";
 import cl100k_base from "js-tiktoken/ranks/cl100k_base";
 import yaml2 from "js-yaml";
@@ -8162,7 +8070,7 @@ function validateRoots(roots) {
     throw new Error(ORCHESTRATOR_TEXTS.runScanRootEmptyArray);
   }
   for (const root of roots) {
-    if (!existsSync13(root) || !statSync3(root).isDirectory()) {
+    if (!existsSync12(root) || !statSync3(root).isDirectory()) {
       throw new Error(tx(ORCHESTRATOR_TEXTS.runScanRootMissing, { root }));
     }
   }
@@ -8938,10 +8846,10 @@ function recomputeExternalRefsCount(nodes, externalLinks, cachedPaths) {
 }
 
 // kernel/scan/watcher.ts
-import { resolve as resolve15, relative as relative4, sep as sep2 } from "path";
+import { resolve as resolve14, relative as relative4, sep as sep2 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
-  const absRoots = opts.roots.map((r) => resolve15(opts.cwd, r));
+  const absRoots = opts.roots.map((r) => resolve14(opts.cwd, r));
   const ignoreFilter = opts.ignoreFilter;
   const ignored = ignoreFilter ? (path) => {
     const rel = relativePathFromRoots(path, absRoots);
@@ -9187,7 +9095,7 @@ function createCliProgressEmitter(stderr) {
 // cli/commands/init.ts
 var InitCommand = class extends SmCommand {
   static paths = [["init"]];
-  static usage = Command10.Usage({
+  static usage = Command9.Usage({
     category: "Setup",
     description: "Bootstrap the current scope: scaffold .skill-map/, provision DB, run first scan.",
     details: `
@@ -9211,16 +9119,16 @@ var InitCommand = class extends SmCommand {
       ["Preview what would be created", "$0 init --dry-run"]
     ]
   });
-  noScan = Option10.Boolean("--no-scan", false, {
+  noScan = Option9.Boolean("--no-scan", false, {
     description: "Skip the first scan after scaffolding."
   });
-  force = Option10.Boolean("--force", false, {
+  force = Option9.Boolean("--force", false, {
     description: "Overwrite an existing settings.json / settings.local.json / .skill-mapignore."
   });
-  strict = Option10.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 = Option10.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
@@ -9231,7 +9139,7 @@ var InitCommand = class extends SmCommand {
   async run() {
     const ctx = defaultRuntimeContext();
     const scopeRoot = this.global ? ctx.homedir : ctx.cwd;
-    const skillMapDir = join11(scopeRoot, SKILL_MAP_DIR);
+    const skillMapDir = join10(scopeRoot, SKILL_MAP_DIR);
     const settingsPath = defaultSettingsPath(scopeRoot);
     const localPath = defaultLocalSettingsPath(scopeRoot);
     const ignorePath = defaultIgnoreFilePath(scopeRoot);
@@ -9255,17 +9163,17 @@ var InitCommand = class extends SmCommand {
       return ExitCode.Ok;
     }
     await mkdir2(skillMapDir, { recursive: true });
-    await writeFile2(settingsPath, JSON.stringify({ schemaVersion: 1 }, null, 2) + "\n");
+    await writeFile(settingsPath, JSON.stringify({ schemaVersion: 1 }, null, 2) + "\n");
     if (!await pathExists(localPath) || this.force) {
-      await writeFile2(localPath, "{}\n");
+      await writeFile(localPath, "{}\n");
     }
     if (!await pathExists(ignorePath) || this.force) {
-      await writeFile2(ignorePath, loadBundledIgnoreText());
+      await writeFile(ignorePath, loadBundledIgnoreText());
     }
     if (!this.global) {
       const updated = await ensureGitignoreEntries(scopeRoot, GITIGNORE_ENTRIES);
       if (updated) {
-        const gitignorePath = join11(scopeRoot, ".gitignore");
+        const gitignorePath = join10(scopeRoot, ".gitignore");
         this.context.stdout.write(
           GITIGNORE_ENTRIES.length === 1 ? tx(INIT_TEXTS.gitignoreUpdatedSingular, { path: gitignorePath }) : tx(INIT_TEXTS.gitignoreUpdatedPlural, {
             path: gitignorePath,
@@ -9304,7 +9212,7 @@ async function dryRunFileMessage(path) {
 }
 async function writeDryRunGitignorePlan(stdout, scopeRoot) {
   const wouldAdd = await previewGitignoreEntries(scopeRoot, GITIGNORE_ENTRIES);
-  const gitignorePath = join11(scopeRoot, ".gitignore");
+  const gitignorePath = join10(scopeRoot, ".gitignore");
   if (wouldAdd.length === 0) {
     stdout.write(tx(INIT_TEXTS.dryRunWouldLeaveGitignoreUnchanged, { path: gitignorePath }));
   } else if (wouldAdd.length === 1) {
@@ -9324,13 +9232,13 @@ async function writeDryRunGitignorePlan(stdout, scopeRoot) {
     );
   }
 }
-async function runFirstScan(scopeRoot, homedir2, dbPath, strict, stdout, stderr) {
+async function runFirstScan(scopeRoot, homedir3, dbPath, strict, stdout, stderr) {
   stdout.write(INIT_TEXTS.runningFirstScan);
   const kernel = createKernel();
   for (const manifest of listBuiltIns()) kernel.registry.register(manifest);
   let cfg;
   try {
-    cfg = loadConfig({ scope: "project", cwd: scopeRoot, homedir: homedir2, strict }).effective;
+    cfg = loadConfig({ scope: "project", cwd: scopeRoot, homedir: homedir3, strict }).effective;
   } catch (err) {
     const message = formatErrorMessage(err);
     stderr.write(tx(INIT_TEXTS.configLoadFailure, { message }));
@@ -9379,7 +9287,7 @@ async function runFirstScan(scopeRoot, homedir2, dbPath, strict, stdout, stderr)
   return hasErrors ? ExitCode.Issues : ExitCode.Ok;
 }
 async function previewGitignoreEntries(scopeRoot, entries) {
-  const path = join11(scopeRoot, ".gitignore");
+  const path = join10(scopeRoot, ".gitignore");
   const body = await pathExists(path) ? await readFile2(path, "utf8") : "";
   const present = new Set(
     body.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"))
@@ -9387,7 +9295,7 @@ async function previewGitignoreEntries(scopeRoot, entries) {
   return entries.filter((entry) => !present.has(entry));
 }
 async function ensureGitignoreEntries(scopeRoot, entries) {
-  const path = join11(scopeRoot, ".gitignore");
+  const path = join10(scopeRoot, ".gitignore");
   let body = "";
   if (await pathExists(path)) {
     body = await readFile2(path, "utf8");
@@ -9404,12 +9312,12 @@ async function ensureGitignoreEntries(scopeRoot, entries) {
     present.add(entry);
     changed = true;
   }
-  if (changed) await writeFile2(path, body);
+  if (changed) await writeFile(path, body);
   return changed;
 }
 
 // cli/commands/history.ts
-import { Command as Command11, Option as Option11 } from "clipanion";
+import { Command as Command10, Option as Option10 } from "clipanion";
 
 // cli/i18n/option-validators.texts.ts
 var OPTION_VALIDATORS_TEXTS = {
@@ -9498,7 +9406,7 @@ function parseStatuses(input, stderr) {
 }
 var HistoryCommand = class extends SmCommand {
   static paths = [["history"]];
-  static usage = Command11.Usage({
+  static usage = Command10.Usage({
     category: "History",
     description: "Filter execution records. --json emits an array conforming to execution-record.schema.json.",
     details: `
@@ -9518,12 +9426,12 @@ var HistoryCommand = class extends SmCommand {
       ["Machine-readable, scoped to one node", "$0 history -n skills/foo.md --json"]
     ]
   });
-  node = Option11.String("-n", { required: false });
-  action = Option11.String("--action", { required: false });
-  status = Option11.String("--status", { required: false });
-  since = Option11.String("--since", { required: false });
-  until = Option11.String("--until", { required: false });
-  limit = Option11.String("--limit", { required: false });
+  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
@@ -9571,7 +9479,7 @@ var HistoryCommand = class extends SmCommand {
 };
 var HistoryStatsCommand = class extends SmCommand {
   static paths = [["history", "stats"]];
-  static usage = Command11.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: `
@@ -9589,10 +9497,10 @@ var HistoryStatsCommand = class extends SmCommand {
       ["Top 5 nodes, JSON", "$0 history stats --top 5 --json"]
     ]
   });
-  since = Option11.String("--since", { required: false });
-  until = Option11.String("--until", { required: false });
-  period = Option11.String("--period", { required: false });
-  top = Option11.String("--top", { required: 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`.
@@ -9773,11 +9681,11 @@ function formatRow(...cols) {
 
 // cli/commands/jobs.ts
 import { unlink } from "fs/promises";
-import { Command as Command12, Option as Option12 } 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";
-import { join as join12, resolve as resolve16 } from "path";
+import { join as join11, resolve as resolve15 } from "path";
 function findOrphanJobFiles(jobsDir, referencedPaths) {
   let entries;
   try {
@@ -9792,7 +9700,7 @@ function findOrphanJobFiles(jobsDir, referencedPaths) {
   const orphans = [];
   for (const name of entries) {
     if (!name.endsWith(".md")) continue;
-    const abs = resolve16(join12(jobsDir, name));
+    const abs = resolve15(join11(jobsDir, name));
     if (!referencedPaths.has(abs)) orphans.push(abs);
   }
   orphans.sort();
@@ -9821,7 +9729,7 @@ var JOBS_TEXTS = {
 // cli/commands/jobs.ts
 var JobPruneCommand = class extends SmCommand {
   static paths = [["job", "prune"]];
-  static usage = Command12.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: `
@@ -9848,10 +9756,10 @@ var JobPruneCommand = class extends SmCommand {
       ["Preview without touching the DB", "$0 job prune --dry-run --json"]
     ]
   });
-  orphanFiles = Option12.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 = Option12.Boolean("-n,--dry-run", false, {
+  dryRun = Option11.Boolean("-n,--dry-run", false, {
     description: "Report what would be pruned without touching the DB or filesystem."
   });
   async run() {
@@ -9968,7 +9876,7 @@ function formatPolicy(seconds) {
 }
 
 // cli/commands/list.ts
-import { Command as Command13, Option as Option13 } from "clipanion";
+import { Command as Command12, Option as Option12 } from "clipanion";
 
 // cli/i18n/list.texts.ts
 var LIST_TEXTS = {
@@ -9996,7 +9904,7 @@ var SORT_BY = {
 var PATH_COL_WIDTH = 50;
 var ListCommand = class extends SmCommand {
   static paths = [["list"]];
-  static usage = Command13.Usage({
+  static usage = Command12.Usage({
     category: "Browse",
     description: "Tabular listing of nodes. --json emits an array conforming to node.schema.json.",
     details: `
@@ -10017,10 +9925,10 @@ var ListCommand = class extends SmCommand {
       ["Only nodes with issues, machine-readable", "$0 list --issue --json"]
     ]
   });
-  kind = Option13.String("--kind", { required: false });
-  issue = Option13.Boolean("--issue", false);
-  sortBy = Option13.String("--sort-by", { required: false });
-  limit = Option13.String("--limit", { required: false });
+  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";
@@ -10122,7 +10030,7 @@ function formatRow2(path, kind, out, inCount, ext, issues, bytes) {
 }
 
 // cli/commands/orphans.ts
-import { Command as Command14, Option as Option14 } from "clipanion";
+import { Command as Command13, Option as Option13 } from "clipanion";
 
 // cli/i18n/orphans.texts.ts
 var ORPHANS_TEXTS = {
@@ -10177,7 +10085,7 @@ function isStringArray(v) {
 }
 var OrphansCommand = class extends SmCommand {
   static paths = [["orphans"]];
-  static usage = Command14.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: `
@@ -10192,7 +10100,7 @@ var OrphansCommand = class extends SmCommand {
       ["Just the ambiguous ones, JSON", "$0 orphans --kind ambiguous --json"]
     ]
   });
-  kind = Option14.String("--kind", { required: false });
+  kind = Option13.String("--kind", { required: false });
   async run() {
     let ruleFilter = null;
     if (this.kind !== void 0) {
@@ -10230,7 +10138,7 @@ var OrphansCommand = class extends SmCommand {
 };
 var OrphansReconcileCommand = class extends SmCommand {
   static paths = [["orphans", "reconcile"]];
-  static usage = Command14.Usage({
+  static usage = Command13.Usage({
     category: "Browse",
     description: "Migrate state_* FKs from an orphan path to a live node, resolving the orphan issue.",
     details: `
@@ -10246,9 +10154,9 @@ var OrphansReconcileCommand = class extends SmCommand {
       ["Reattach orphan history", "$0 orphans reconcile skills/old.md --to skills/new.md"]
     ]
   });
-  orphanPath = Option14.String({ required: true });
-  to = Option14.String("--to", { required: true });
-  dryRun = Option14.Boolean("-n,--dry-run", false);
+  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;
@@ -10318,7 +10226,7 @@ var OrphansReconcileCommand = class extends SmCommand {
 };
 var OrphansUndoRenameCommand = class extends SmCommand {
   static paths = [["orphans", "undo-rename"]];
-  static usage = Command14.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: `
@@ -10338,10 +10246,10 @@ var OrphansUndoRenameCommand = class extends SmCommand {
       ["Undo an ambiguous, picking a candidate", "$0 orphans undo-rename skills/new.md --from skills/old-a.md"]
     ]
   });
-  newPath = Option14.String({ required: true });
-  from = Option14.String("--from", { required: false });
-  force = Option14.Boolean("--force", false);
-  dryRun = Option14.Boolean("-n,--dry-run", false);
+  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;
@@ -10505,9 +10413,9 @@ var ORPHANS_COMMANDS = [
 ];
 
 // cli/commands/plugins.ts
-import { existsSync as existsSync14 } from "fs";
-import { join as join13, resolve as resolve17 } from "path";
-import { Command as Command15, Option as Option15 } from "clipanion";
+import { existsSync as existsSync13 } from "fs";
+import { join as join12, resolve as resolve16 } from "path";
+import { Command as Command14, Option as Option14 } from "clipanion";
 
 // cli/i18n/plugins.texts.ts
 var PLUGINS_TEXTS = {
@@ -10554,8 +10462,8 @@ var PLUGINS_TEXTS = {
   rowStatusOkPad: "ok  ",
   rowStatusOffPad: "off ",
   builtInBundleHeader: "{{status}}     {{id}}@built-in (granularity={{granularity}})",
-  builtInBundleKindsLine: "        {{kinds}}",
-  builtInExtensionRow: "  {{stat}} {{kind}}:{{qualifiedId}}@{{version}}",
+  builtInBundleKindsLine: "         {{kinds}}",
+  builtInExtensionRow: "{{stat}}       {{kind}}:{{qualifiedId}}@{{version}}",
   pluginRow: "{{statusIcon}} {{id}}@{{version}}{{granularitySuffix}}{{tail}}",
   pluginRowGranularitySuffix: " (granularity={{granularity}})",
   pluginRowTailEnabled: " \xB7 {{kinds}}",
@@ -10582,9 +10490,9 @@ var PLUGINS_TEXTS = {
 };
 
 // cli/commands/plugins.ts
-function resolveSearchPaths2(opts, cwd, homedir2) {
-  if (opts.pluginDir) return [resolve17(opts.pluginDir)];
-  const ctx = { cwd, homedir: homedir2 };
+function resolveSearchPaths2(opts, cwd, homedir3) {
+  if (opts.pluginDir) return [resolve16(opts.pluginDir)];
+  const ctx = { cwd, homedir: homedir3 };
   const project = defaultProjectPluginsDir(ctx);
   const user = defaultUserPluginsDir(ctx);
   return opts.global ? [user] : [project, user];
@@ -10652,12 +10560,12 @@ function builtInRows(resolveEnabled) {
 }
 var PluginsListCommand = class extends SmCommand {
   static paths = [["plugins", "list"]];
-  static usage = Command15.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."
   });
-  pluginDir = Option15.String("--plugin-dir", { required: false });
+  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);
@@ -10687,13 +10595,15 @@ function renderBuiltInBundleRow(bundle) {
     })
   );
   if (bundle.granularity === "bundle") {
-    const kinds = bundle.extensions.map((e) => `${e.kind}:${qualifiedExtensionId(bundle.id, e.id)}`).join(", ");
-    lines.push(tx(PLUGINS_TEXTS.builtInBundleKindsLine, { kinds }));
+    for (const ext of bundle.extensions) {
+      const line = `${ext.kind}:${qualifiedExtensionId(bundle.id, ext.id)}@${ext.version}`;
+      lines.push(tx(PLUGINS_TEXTS.builtInBundleKindsLine, { kinds: line }));
+    }
   } else {
     for (const ext of bundle.extensions) {
       lines.push(
         tx(PLUGINS_TEXTS.builtInExtensionRow, {
-          stat: ext.enabled ? PLUGINS_TEXTS.rowStatusOkPad : PLUGINS_TEXTS.rowStatusOffPad,
+          stat: ext.enabled ? PLUGINS_TEXTS.rowStatusOk : PLUGINS_TEXTS.rowStatusOff,
           kind: ext.kind,
           qualifiedId: qualifiedExtensionId(bundle.id, ext.id),
           version: ext.version
@@ -10719,12 +10629,12 @@ function renderPluginRow(p) {
 }
 var PluginsShowCommand = class extends SmCommand {
   static paths = [["plugins", "show"]];
-  static usage = Command15.Usage({
+  static usage = Command14.Usage({
     category: "Plugins",
     description: "Show a single plugin's manifest + loaded extensions."
   });
-  id = Option15.String({ required: true });
-  pluginDir = Option15.String("--plugin-dir", { required: false });
+  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);
@@ -10899,18 +10809,18 @@ function appendUnknownKindWarnings(out, extractorQualifiedId, applicableKinds, k
     if (!knownKinds.has(k)) out.push({ extractorQualifiedId, unknownKind: k });
   }
 }
-function expandHome(p, homedir2) {
-  if (p === "~") return homedir2;
-  if (p.startsWith("~/")) return join13(homedir2, p.slice(2));
+function expandHome(p, homedir3) {
+  if (p === "~") return homedir3;
+  if (p.startsWith("~/")) return join12(homedir3, p.slice(2));
   return p;
 }
-function collectExplorationDirWarnings(plugins, homedir2) {
+function collectExplorationDirWarnings(plugins, homedir3) {
   const out = [];
   forEachProviderInstance(plugins, ({ id, pluginId, instance }) => {
     const dir = instance["explorationDir"];
     if (typeof dir !== "string" || dir.length === 0) return;
-    const resolved = expandHome(dir, homedir2);
-    if (!existsSync14(resolved)) {
+    const resolved = expandHome(dir, homedir3);
+    if (!existsSync13(resolved)) {
       out.push({
         providerQualifiedId: qualifiedExtensionId(pluginId, id),
         explorationDir: dir,
@@ -10922,12 +10832,12 @@ function collectExplorationDirWarnings(plugins, homedir2) {
 }
 var PluginsDoctorCommand = class extends SmCommand {
   static paths = [["plugins", "doctor"]];
-  static usage = Command15.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."
   });
-  pluginDir = Option15.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
@@ -11093,8 +11003,8 @@ function resolveToggleTarget(id, catalogue, verb) {
   return { key: bundle.id };
 }
 var TogglePluginsBase = class extends SmCommand {
-  all = Option15.Boolean("--all", false);
-  id = Option15.String({ required: false });
+  all = Option14.Boolean("--all", false);
+  id = Option14.String({ required: false });
   // eslint-disable-next-line complexity
   async toggle(enabled) {
     const verb = enabled ? "enable" : "disable";
@@ -11145,7 +11055,7 @@ var TogglePluginsBase = class extends SmCommand {
 };
 var PluginsEnableCommand = class extends TogglePluginsBase {
   static paths = [["plugins", "enable"]];
-  static usage = Command15.Usage({
+  static usage = Command14.Usage({
     category: "Plugins",
     description: "Enable a plugin (or --all). Persists in config_plugins.",
     details: `
@@ -11167,7 +11077,7 @@ var PluginsEnableCommand = class extends TogglePluginsBase {
 };
 var PluginsDisableCommand = class extends TogglePluginsBase {
   static paths = [["plugins", "disable"]];
-  static usage = Command15.Usage({
+  static usage = Command14.Usage({
     category: "Plugins",
     description: "Disable a plugin (or --all). Persists in config_plugins; does not delete files.",
     details: `
@@ -11203,8 +11113,8 @@ var PLUGIN_COMMANDS = [
 
 // cli/commands/refresh.ts
 import { readFile as readFile3 } from "fs/promises";
-import { resolve as resolve19 } from "path";
-import { Command as Command16, Option as Option16 } from "clipanion";
+import { resolve as resolve18 } from "path";
+import { Command as Command15, Option as Option15 } from "clipanion";
 
 // cli/i18n/refresh.texts.ts
 var REFRESH_TEXTS = {
@@ -11233,12 +11143,12 @@ var REFRESH_TEXTS = {
 };
 
 // cli/util/path-guard.ts
-import { isAbsolute as isAbsolute3, resolve as resolve18, sep as sep3 } from "path";
+import { isAbsolute as isAbsolute3, resolve as resolve17, sep as sep3 } from "path";
 function assertContained2(cwd, rel) {
   if (isAbsolute3(rel)) {
     throw new Error(`node path is absolute, refusing to read: ${rel}`);
   }
-  const abs = resolve18(cwd, rel);
+  const abs = resolve17(cwd, rel);
   if (abs !== cwd && !abs.startsWith(cwd + sep3)) {
     throw new Error(`node path escapes repo root: ${rel}`);
   }
@@ -11247,7 +11157,7 @@ function assertContained2(cwd, rel) {
 // cli/commands/refresh.ts
 var RefreshCommand = class extends SmCommand {
   static paths = [["refresh"]];
-  static usage = Command16.Usage({
+  static usage = Command15.Usage({
     category: "Scan",
     description: "Refresh enrichment rows: granular (single node) or batch (every stale row).",
     details: `
@@ -11272,11 +11182,11 @@ var RefreshCommand = class extends SmCommand {
       ["Refresh every node with stale enrichments", "$0 refresh --stale"]
     ]
   });
-  nodePath = Option16.String({ name: "node", required: false });
-  stale = Option16.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 = Option16.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
@@ -11412,7 +11322,7 @@ var RefreshCommand = class extends SmCommand {
       let body;
       try {
         assertContained2(cwd, node.path);
-        const raw = await readFile3(resolve19(cwd, node.path), "utf8");
+        const raw = await readFile3(resolve18(cwd, node.path), "utf8");
         body = stripFrontmatterFence(raw);
       } catch (err) {
         this.context.stderr.write(
@@ -11461,7 +11371,7 @@ function stripFrontmatterFence(text) {
 var REFRESH_COMMANDS = [RefreshCommand];
 
 // cli/commands/scan.ts
-import { Command as Command18, Option as Option18 } from "clipanion";
+import { Command as Command17, Option as Option17 } from "clipanion";
 
 // cli/i18n/scan.texts.ts
 var SCAN_TEXTS = {
@@ -11653,7 +11563,7 @@ async function runEphemeralPath(opts, dbPath, strict, loadPrior, runScanWith) {
 }
 
 // cli/commands/watch.ts
-import { Command as Command17, Option as Option17 } from "clipanion";
+import { Command as Command16, Option as Option16 } from "clipanion";
 
 // cli/i18n/watch.texts.ts
 var WATCH_TEXTS = {
@@ -11832,7 +11742,7 @@ async function runWatchLoop(opts) {
 }
 var WatchCommand = class extends SmCommand {
   static paths = [["watch"]];
-  static usage = Command17.Usage({
+  static usage = Command16.Usage({
     category: "Scan",
     description: "Watch roots and run an incremental scan after each debounced batch of filesystem events.",
     details: `
@@ -11856,17 +11766,17 @@ var WatchCommand = class extends SmCommand {
       ["Stream ScanResult per batch as ndjson", "$0 watch --json"]
     ]
   });
-  roots = Option17.Rest({ name: "roots" });
-  noTokens = Option17.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 = Option17.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 = Option17.Boolean("--no-plugins", false, {
+  noPlugins = Option16.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery for the watcher session."
   });
-  maxConsecutiveFailures = Option17.String("--max-consecutive-failures", {
+  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)."
   });
@@ -11904,7 +11814,7 @@ function parseBreakerLimit(raw, stderr) {
 // cli/commands/scan.ts
 var ScanCommand = class extends SmCommand {
   static paths = [["scan"]];
-  static usage = Command18.Usage({
+  static usage = Command17.Usage({
     category: "Scan",
     description: "Scan roots for markdown nodes, run extractors and rules.",
     details: `
@@ -11933,29 +11843,29 @@ var ScanCommand = class extends SmCommand {
       ["What would the next incremental scan persist?", "$0 scan --changed -n --json"]
     ]
   });
-  roots = Option18.Rest({ name: "roots" });
-  noBuiltIns = Option18.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 = Option18.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 = Option18.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 = Option18.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 = Option18.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 = Option18.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 = Option18.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 = Option18.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`."
   });
   async run() {
@@ -12053,11 +11963,11 @@ var ScanCommand = class extends SmCommand {
 };
 
 // cli/commands/scan-compare.ts
-import { existsSync as existsSync15, readFileSync as readFileSync12 } from "fs";
-import { Command as Command19, Option as Option19 } from "clipanion";
+import { existsSync as existsSync14, readFileSync as readFileSync11 } from "fs";
+import { Command as Command18, Option as Option18 } from "clipanion";
 var ScanCompareCommand = class extends SmCommand {
   static paths = [["scan", "compare-with"]];
-  static usage = Command19.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: `
@@ -12085,15 +11995,15 @@ var ScanCompareCommand = class extends SmCommand {
       ["JSON output for tooling", "$0 scan compare-with baseline.json --json"]
     ]
   });
-  dump = Option19.String({ required: true });
-  roots = Option19.Rest({ name: "roots" });
-  noTokens = Option19.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 = Option19.Boolean("--strict", false, {
+  strict = Option18.Boolean("--strict", false, {
     description: "Promote layered-config warnings and frontmatter-validation findings from warn to error."
   });
-  noPlugins = Option19.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
@@ -12164,12 +12074,12 @@ var ScanCompareCommand = class extends SmCommand {
   }
 };
 function loadAndValidateDump(path) {
-  if (!existsSync15(path)) {
+  if (!existsSync14(path)) {
     throw new Error(tx(SCAN_TEXTS.compareDumpNotFound, { path }));
   }
   let raw;
   try {
-    raw = readFileSync12(path, "utf8");
+    raw = readFileSync11(path, "utf8");
   } catch (err) {
     const message = formatErrorMessage(err);
     throw new Error(tx(SCAN_TEXTS.compareDumpReadFailed, { path, message }), { cause: err });
@@ -12278,8 +12188,8 @@ function renderDeltaIssues(issues) {
 
 // cli/commands/serve.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync19 } from "fs";
-import { Command as Command20, Option as Option20 } from "clipanion";
+import { existsSync as existsSync18 } from "fs";
+import { Command as Command19, Option as Option19 } from "clipanion";
 
 // server/index.ts
 import { serve } from "@hono/node-server";
@@ -12460,7 +12370,7 @@ function contentTypeFor(format) {
 }
 
 // server/health.ts
-import { existsSync as existsSync16 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 var FALLBACK_SCHEMA_VERSION = "1";
 function buildHealth(deps) {
   return {
@@ -12469,7 +12379,7 @@ function buildHealth(deps) {
     specVersion: deps.specVersion,
     implVersion: VERSION,
     scope: deps.scope,
-    db: existsSync16(deps.dbPath) ? "present" : "missing"
+    db: existsSync15(deps.dbPath) ? "present" : "missing"
   };
 }
 async function resolveSpecVersion2() {
@@ -12909,9 +12819,9 @@ function emptyScanResult() {
 }
 
 // server/static.ts
-import { existsSync as existsSync17 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 import { readFile as readFile5 } from "fs/promises";
-import { extname, join as join14 } from "path";
+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>
@@ -12942,8 +12852,8 @@ function createSpaFallback(uiDist) {
   return async (c, _next) => {
     if (c.req.method !== "GET" && c.req.method !== "HEAD") return c.notFound();
     if (uiDist === null) return htmlResponse(c, PLACEHOLDER_HTML);
-    const indexPath = join14(uiDist, INDEX_HTML);
-    if (!existsSync17(indexPath)) return htmlResponse(c, PLACEHOLDER_HTML);
+    const indexPath = join13(uiDist, INDEX_HTML);
+    if (!existsSync16(indexPath)) return htmlResponse(c, PLACEHOLDER_HTML);
     return fileResponse(c, indexPath);
   };
 }
@@ -13347,6 +13257,7 @@ function createWatcherService(opts) {
     if ("ready" in chokidarHandle && chokidarHandle.ready instanceof Promise) {
       await chokidarHandle.ready;
     }
+    await runInitialBatch({ isStopped: () => stopped, runOneBatch });
     opts.broadcaster.broadcast(
       buildWatcherStartedEvent({ roots: [WATCH_ROOT], debounceMs })
     );
@@ -13429,6 +13340,19 @@ async function persistOutcome(dbPath, ran) {
     (writer) => writer.scans.persist(result, { renameOps, extractorRuns, enrichments })
   );
 }
+async function runInitialBatch(deps) {
+  if (deps.isStopped()) return;
+  try {
+    await deps.runOneBatch();
+  } catch (err) {
+    const message = formatErrorMessage(err);
+    log.warn(
+      tx(SERVER_TEXTS.watcherBatchFailed, {
+        message: sanitizeForTerminal(message)
+      })
+    );
+  }
+}
 
 // server/options.ts
 var DEFAULT_PORT = 4242;
@@ -13533,10 +13457,10 @@ function validateWatcherDebounce(value) {
 }
 
 // server/paths.ts
-import { existsSync as existsSync18, statSync as statSync5 } from "fs";
-import { dirname as dirname10, isAbsolute as isAbsolute5, join as join15, resolve as resolve20 } from "path";
-import { fileURLToPath as fileURLToPath6 } from "url";
-var DEFAULT_UI_REL = join15("ui", "dist", "ui", "browser");
+import { existsSync as existsSync17, statSync as statSync5 } from "fs";
+import { dirname as dirname9, isAbsolute as isAbsolute5, join as join14, resolve as resolve19 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
+var DEFAULT_UI_REL = join14("ui", "dist", "ui", "browser");
 var PACKAGE_UI_REL = "ui";
 var INDEX_HTML2 = "index.html";
 function resolveDefaultUiDist(ctx) {
@@ -13545,13 +13469,13 @@ function resolveDefaultUiDist(ctx) {
   return walkUpForUi(ctx.cwd);
 }
 function resolveExplicitUiDist(ctx, raw) {
-  return isAbsolute5(raw) ? raw : resolve20(ctx.cwd, raw);
+  return isAbsolute5(raw) ? raw : resolve19(ctx.cwd, raw);
 }
 function isUiBundleDir(path) {
-  if (!existsSync18(path)) return false;
+  if (!existsSync17(path)) return false;
   try {
     if (!statSync5(path).isDirectory()) return false;
-    return existsSync18(join15(path, INDEX_HTML2));
+    return existsSync17(join14(path, INDEX_HTML2));
   } catch {
     return false;
   }
@@ -13559,7 +13483,7 @@ function isUiBundleDir(path) {
 function resolvePackageBundledUi() {
   let here;
   try {
-    here = dirname10(fileURLToPath6(import.meta.url));
+    here = dirname9(fileURLToPath5(import.meta.url));
   } catch {
     return null;
   }
@@ -13568,22 +13492,22 @@ function resolvePackageBundledUi() {
 function resolvePackageBundledUiFrom(here) {
   let current = here;
   for (let i = 0; i < 8; i++) {
-    const candidate = join15(current, PACKAGE_UI_REL);
+    const candidate = join14(current, PACKAGE_UI_REL);
     if (isUiBundleDir(candidate)) return candidate;
-    const distHere = join15(current, "dist", PACKAGE_UI_REL);
+    const distHere = join14(current, "dist", PACKAGE_UI_REL);
     if (isUiBundleDir(distHere)) return distHere;
-    const parent = dirname10(current);
+    const parent = dirname9(current);
     if (parent === current) return null;
     current = parent;
   }
   return null;
 }
 function walkUpForUi(startDir) {
-  let current = resolve20(startDir);
+  let current = resolve19(startDir);
   for (let i = 0; i < 64; i++) {
-    const candidate = join15(current, DEFAULT_UI_REL);
+    const candidate = join14(current, DEFAULT_UI_REL);
     if (isUiBundleDir(candidate)) return candidate;
-    const parent = dirname10(current);
+    const parent = dirname9(current);
     if (parent === current) return null;
     current = parent;
   }
@@ -13706,17 +13630,13 @@ function normalizeAddress(addr, fallbackHost, fallbackPort) {
 
 // cli/i18n/serve.texts.ts
 var SERVE_TEXTS = {
-  // Banner emitted to stderr after the listener binds. Mirrors `sm watch`
-  // by writing operational status to stderr (stdout is reserved for
-  // future `--json` boot payloads).
-  boot: "sm serve: listening on http://{{host}}:{{port}} (scope={{scope}}, db={{db}})\n",
-  // Hint shown after the boot line. Branches on --open: when auto-open
-  // is on (default), the message states intent ("opening …"); when
-  // --no-open, it instructs the user to visit the URL manually.
-  // Both end with the Ctrl+C reminder so the operational tail is
-  // identical regardless of branch.
-  bootOpening: "sm serve: opening http://{{host}}:{{port}}/ in your browser. Press Ctrl+C to stop.\n",
-  bootVisitHint: "sm serve: visit http://{{host}}:{{port}}/ in your browser. Press Ctrl+C to stop.\n",
+  // The boot banner (TTY box / flat-line fallback) is rendered by
+  // `cli/util/serve-banner.ts` rather than templated through `tx` —
+  // ANSI escapes + box-drawing aren't a good fit for the flat
+  // `{{name}}` interpolation surface. The flat-mode strings live in
+  // that helper and stay byte-equivalent to the pre-banner format so
+  // existing pipes / redirects ('listening on <url>' scrapers) don't
+  // break.
   // Browser-open failure. Non-fatal — the URL is already printed; the
   // user can open it manually.
   openFailed: "sm serve: could not auto-open browser ({{message}}). Visit {{url}} manually.\n",
@@ -13740,10 +13660,140 @@ var SERVE_TEXTS = {
   shutdown: "sm serve: shutdown complete.\n"
 };
 
+// cli/util/serve-banner.ts
+import { homedir as homedir2 } from "os";
+import { relative as relative5, isAbsolute as isAbsolute6 } from "path";
+var ESC = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  underline: "\x1B[4m",
+  /** 256-color violet (xterm 141). */
+  violet: "\x1B[38;5;141m",
+  /** 256-color green (xterm 42). */
+  green: "\x1B[38;5;42m"
+};
+var LOGO_LINES = [
+  "  ____  _    _ _ _   __  __             ",
+  " / ___|| | _(_) | | |  \\/  | __ _ _ __  ",
+  " \\___ \\| |/ / | | | | |\\/| |/ _` | '_ \\ ",
+  "  ___) |   <| | | | | |  | | (_| | |_) |",
+  " |____/|_|\\_\\_|_|_| |_|  |_|\\__,_| .__/ ",
+  "                                 |_|    "
+];
+var LOGO_WIDTH = 40;
+function renderBanner(input) {
+  const url = `http://${input.host}:${input.port}`;
+  const dbDisplay = formatDbPath(input.dbPath, input.cwd);
+  const browserLine = input.openBrowser ? "Opening browser\u2026  Press Ctrl+C to stop." : `Visit ${url}/ in your browser.  Press Ctrl+C to stop.`;
+  if (!input.isTTY) {
+    return renderFlat({
+      host: input.host,
+      port: input.port,
+      scope: input.scope,
+      dbPath: input.dbPath,
+      openBrowser: input.openBrowser
+    });
+  }
+  return renderFiglet({
+    version: input.version,
+    url,
+    scope: input.scope,
+    dbDisplay,
+    pathDisplay: formatCwdPath(input.cwd),
+    browserLine,
+    colorEnabled: input.colorEnabled
+  });
+}
+function resolveColorEnabled(opts) {
+  if (opts.noColorFlag) return false;
+  const noColor = opts.env["NO_COLOR"];
+  if (noColor !== void 0 && noColor !== "") return false;
+  const forceColor = opts.env["FORCE_COLOR"];
+  if (forceColor !== void 0 && forceColor !== "") return true;
+  return opts.isTTY;
+}
+function renderFlat(input) {
+  const safeHost = sanitizeForTerminal(input.host);
+  const safeDb = sanitizeForTerminal(input.dbPath);
+  const url = `http://${safeHost}:${input.port}`;
+  const linesOut = [];
+  linesOut.push(`sm serve: listening on ${url} (scope=${input.scope}, db=${safeDb})`);
+  if (input.openBrowser) {
+    linesOut.push(`sm serve: opening ${url}/ in your browser. Press Ctrl+C to stop.`);
+  } else {
+    linesOut.push(`sm serve: visit ${url}/ in your browser. Press Ctrl+C to stop.`);
+  }
+  return linesOut.join("\n") + "\n";
+}
+function renderFiglet(input) {
+  const {
+    dimOpen,
+    dimClose,
+    greenUnderline,
+    greenUnderlineClose,
+    violetOpen,
+    violetClose
+  } = resolveAnsi(input.colorEnabled);
+  const logoLines = LOGO_LINES.map((line) => `${violetOpen}${line}${violetClose}`);
+  const versionText = `v${input.version}`;
+  const versionPad = Math.max(0, LOGO_WIDTH - versionText.length);
+  const versionLine = `${" ".repeat(versionPad)}${dimOpen}${versionText}${dimClose}`;
+  const lines = [];
+  lines.push(...logoLines);
+  lines.push("");
+  lines.push(versionLine);
+  lines.push("");
+  lines.push(`  ${dimOpen}Server${dimClose}   ${greenUnderline}${input.url}${greenUnderlineClose}`);
+  lines.push(`  ${dimOpen}Scope${dimClose}    ${input.scope}`);
+  lines.push(`  ${dimOpen}Path${dimClose}     ${input.pathDisplay}`);
+  lines.push(`  ${dimOpen}DB${dimClose}       ${input.dbDisplay}`);
+  lines.push("");
+  lines.push(`  ${dimOpen}${input.browserLine}${dimClose}`);
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+var EMPTY_ANSI = {
+  dimOpen: "",
+  dimClose: "",
+  greenUnderline: "",
+  greenUnderlineClose: "",
+  violetOpen: "",
+  violetClose: ""
+};
+var ENABLED_ANSI = {
+  dimOpen: ESC.dim,
+  dimClose: ESC.reset,
+  greenUnderline: `${ESC.green}${ESC.underline}`,
+  greenUnderlineClose: ESC.reset,
+  violetOpen: ESC.violet,
+  violetClose: ESC.reset
+};
+function resolveAnsi(colorEnabled) {
+  return colorEnabled ? ENABLED_ANSI : EMPTY_ANSI;
+}
+function formatDbPath(dbPath, cwd) {
+  const safe = sanitizeForTerminal(dbPath);
+  if (!isAbsolute6(safe)) return safe;
+  const rel = relative5(cwd, safe);
+  if (rel === "" || rel.startsWith("..") || isAbsolute6(rel)) {
+    return safe;
+  }
+  return rel;
+}
+function formatCwdPath(cwd) {
+  const safe = sanitizeForTerminal(cwd);
+  const home = homedir2();
+  if (home && (safe === home || safe.startsWith(`${home}/`))) {
+    return `~${safe.slice(home.length)}`;
+  }
+  return safe;
+}
+
 // cli/commands/serve.ts
 var ServeCommand = class extends SmCommand {
   static paths = [["serve"]];
-  static usage = Command20.Usage({
+  static usage = Command19.Usage({
     category: "Setup",
     description: "Start the Hono BFF (single-port: REST + WebSocket + SPA bundle).",
     details: `
@@ -13768,22 +13818,22 @@ var ServeCommand = class extends SmCommand {
       ["Point at a pre-built UI bundle", "$0 serve --ui-dist ./ui/dist/browser"]
     ]
   });
-  port = Option20.String("--port", {
+  port = Option19.String("--port", {
     required: false,
     description: "Listening port (default 4242). 0 = OS-assigned."
   });
-  host = Option20.String("--host", {
+  host = Option19.String("--host", {
     required: false,
     description: "Listening host (default 127.0.0.1). Loopback-only enforced when --dev-cors is set."
   });
-  scope = Option20.String("--scope", {
+  scope = Option19.String("--scope", {
     required: false,
     description: "project | global. Alias for -g/--global. Default: project."
   });
-  noBuiltIns = Option20.Boolean("--no-built-ins", false, {
+  noBuiltIns = Option19.Boolean("--no-built-ins", false, {
     description: "Skip built-in plugin registration (parity with sm scan --no-built-ins)."
   });
-  noPlugins = Option20.Boolean("--no-plugins", false, {
+  noPlugins = Option19.Boolean("--no-plugins", false, {
     description: "Skip drop-in plugin discovery."
   });
   // `Option.Boolean('--open', true)` — Clipanion's parser auto-derives
@@ -13793,24 +13843,24 @@ var ServeCommand = class extends SmCommand {
   // two registrations for the same flag and rejects the invocation
   // with "Ambiguous Syntax Error". Same convention shipped by every
   // other `--no-...` flag in the CLI tree.
-  open = Option20.Boolean("--open", true, {
+  open = Option19.Boolean("--open", true, {
     description: "Auto-open the SPA in the user's default browser after listen. --no-open opts out."
   });
-  devCors = Option20.Boolean("--dev-cors", false, {
+  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 = Option20.String("--ui-dist", { required: false, hidden: true });
-  noWatcher = Option20.Boolean("--no-watcher", false, {
+  uiDist = Option19.String("--ui-dist", { required: false, hidden: true });
+  noWatcher = Option19.Boolean("--no-watcher", false, {
     description: "Disable the chokidar-fed scan-and-broadcast loop. Use only for CI / read-only deployments."
   });
   // `--watcher-debounce-ms` is undocumented sugar for advanced users
   // who want to tighten / relax the watcher's batching window without
   // editing settings.json. Hidden flag — the Usage block omits it.
-  watcherDebounceMs = Option20.String("--watcher-debounce-ms", { required: false, hidden: true });
+  watcherDebounceMs = Option19.String("--watcher-debounce-ms", { required: false, hidden: true });
   // Long-running daemon — `done in <…>` after a graceful shutdown is
   // noise. Mirrors `sm watch`'s opt-out.
   emitElapsed = false;
@@ -13838,7 +13888,7 @@ var ServeCommand = class extends SmCommand {
       return ExitCode.Error;
     }
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...runtimeCtx });
-    if (this.db !== void 0 && !existsSync19(dbPath)) {
+    if (this.db !== void 0 && !existsSync18(dbPath)) {
       this.context.stderr.write(
         tx(SERVE_TEXTS.dbNotFound, { path: sanitizeForTerminal(dbPath) })
       );
@@ -13892,18 +13942,24 @@ var ServeCommand = class extends SmCommand {
       );
       return ExitCode.Error;
     }
+    const stderr = this.context.stderr;
+    const isTTY = stderr.isTTY === true;
+    const colorEnabled = resolveColorEnabled({
+      isTTY,
+      noColorFlag: this.noColor,
+      env: process.env
+    });
     this.context.stderr.write(
-      tx(SERVE_TEXTS.boot, {
+      renderBanner({
+        version: VERSION,
         host: sanitizeForTerminal(handle.address.host),
         port: handle.address.port,
         scope,
-        db: sanitizeForTerminal(dbPath)
-      })
-    );
-    this.context.stderr.write(
-      tx(validation.options.open ? SERVE_TEXTS.bootOpening : SERVE_TEXTS.bootVisitHint, {
-        host: sanitizeForTerminal(handle.address.host),
-        port: handle.address.port
+        dbPath,
+        cwd: runtimeCtx.cwd,
+        openBrowser: validation.options.open,
+        isTTY,
+        colorEnabled
       })
     );
     if (validation.options.open) {
@@ -14019,7 +14075,7 @@ function tryOpenBrowser(url, stderr) {
 }
 
 // cli/commands/show.ts
-import { Command as Command21, Option as Option21 } from "clipanion";
+import { Command as Command20, Option as Option20 } from "clipanion";
 
 // cli/i18n/show.texts.ts
 var SHOW_TEXTS = {
@@ -14059,7 +14115,7 @@ var SHOW_TEXTS = {
 // cli/commands/show.ts
 var ShowCommand = class extends SmCommand {
   static paths = [["show"]];
-  static usage = Command21.Usage({
+  static usage = Command20.Usage({
     category: "Browse",
     description: "Node detail: weight, frontmatter, links, issues.",
     details: `
@@ -14075,7 +14131,7 @@ var ShowCommand = class extends SmCommand {
       ["Machine-readable detail", "$0 show .claude/agents/architect.md --json"]
     ]
   });
-  nodePath = Option21.String({ required: true });
+  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;
@@ -14224,7 +14280,7 @@ function rankConfidenceForGrouping(c) {
 }
 
 // cli/commands/stubs.ts
-import { Command as Command22, Option as Option22 } from "clipanion";
+import { Command as Command21, Option as Option21 } from "clipanion";
 
 // cli/i18n/stubs.texts.ts
 var STUBS_TEXTS = {
@@ -14239,9 +14295,9 @@ function notImplemented(cmd, verb) {
   cmd.context.stderr.write(tx(STUBS_TEXTS.notImplemented, { verb }));
   return ExitCode.Error;
 }
-var DoctorCommand = class extends Command22 {
+var DoctorCommand = class extends Command21 {
   static paths = [["doctor"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Setup",
     description: planned("Diagnostic report: DB integrity, pending migrations, orphan rows, plugin status, runner availability.")
   });
@@ -14249,23 +14305,23 @@ var DoctorCommand = class extends Command22 {
     return notImplemented(this, "doctor");
   }
 };
-var FindingsCommand = class extends Command22 {
+var FindingsCommand = class extends Command21 {
   static paths = [["findings"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Browse",
     description: planned("Probabilistic findings: injection, stale summaries, low confidence.")
   });
-  kind = Option22.String("--kind", { required: false });
-  since = Option22.String("--since", { required: false });
-  threshold = Option22.String("--threshold", { required: false });
-  json = Option22.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 Command22 {
+var ActionsListCommand = class extends Command21 {
   static paths = [["actions", "list"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Registered action types (manifest view).")
   });
@@ -14273,121 +14329,121 @@ var ActionsListCommand = class extends Command22 {
     return notImplemented(this, "actions list");
   }
 };
-var ActionsShowCommand = class extends Command22 {
+var ActionsShowCommand = class extends Command21 {
   static paths = [["actions", "show"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Full action manifest, including preconditions and expected duration.")
   });
-  id = Option22.String({ required: true });
+  id = Option21.String({ required: true });
   async execute() {
     return notImplemented(this, "actions show");
   }
 };
-var JobSubmitCommand = class extends Command22 {
+var JobSubmitCommand = class extends Command21 {
   static paths = [["job", "submit"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Enqueue a single job or fan out to every matching node (--all).")
   });
-  action = Option22.String({ required: true });
-  node = Option22.String("-n", { required: false });
-  all = Option22.Boolean("--all", false);
-  run = Option22.Boolean("--run", false);
-  force = Option22.Boolean("--force", false);
-  ttl = Option22.String("--ttl", { required: false });
-  priority = Option22.String("--priority", { required: false });
+  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 Command22 {
+var JobListCommand = class extends Command21 {
   static paths = [["job", "list"]];
-  static usage = Command22.Usage({ category: "Jobs", description: planned("List jobs.") });
-  status = Option22.String("--status", { required: false });
-  action = Option22.String("--action", { required: false });
-  node = Option22.String("--node", { required: false });
+  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 Command22 {
+var JobShowCommand = class extends Command21 {
   static paths = [["job", "show"]];
-  static usage = Command22.Usage({ category: "Jobs", description: planned("Job detail: state, claim time, TTL, runner, content hash.") });
-  id = Option22.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 Command22 {
+var JobPreviewCommand = class extends Command21 {
   static paths = [["job", "preview"]];
-  static usage = Command22.Usage({ category: "Jobs", description: planned("Render the job MD file without executing.") });
-  id = Option22.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 Command22 {
+var JobClaimCommand = class extends Command21 {
   static paths = [["job", "claim"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Atomic primitive: return next queued job id, mark it running.")
   });
-  filter = Option22.String("--filter", { required: false });
+  filter = Option21.String("--filter", { required: false });
   async execute() {
     return notImplemented(this, "job claim");
   }
 };
-var JobRunCommand = class extends Command22 {
+var JobRunCommand = class extends Command21 {
   static paths = [["job", "run"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Full CLI-runner loop: claim + spawn + record.")
   });
-  all = Option22.Boolean("--all", false);
-  max = Option22.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 Command22 {
+var JobStatusCommand = class extends Command21 {
   static paths = [["job", "status"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Counts (per status) or single-job status.")
   });
-  id = Option22.String({ required: false });
+  id = Option21.String({ required: false });
   async execute() {
     return notImplemented(this, "job status");
   }
 };
-var JobCancelCommand = class extends Command22 {
+var JobCancelCommand = class extends Command21 {
   static paths = [["job", "cancel"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Force a running job to failed with reason user-cancelled.")
   });
-  id = Option22.String({ required: false });
-  all = Option22.Boolean("--all", false);
+  id = Option21.String({ required: false });
+  all = Option21.Boolean("--all", false);
   async execute() {
     return notImplemented(this, "job cancel");
   }
 };
-var RecordCommand = class extends Command22 {
+var RecordCommand = class extends Command21 {
   static paths = [["record"]];
-  static usage = Command22.Usage({
+  static usage = Command21.Usage({
     category: "Jobs",
     description: planned("Close a running job with success or failure. Nonce is the sole credential.")
   });
-  id = Option22.String("--id", { required: true });
-  nonce = Option22.String("--nonce", { required: true });
-  status = Option22.String("--status", { required: true });
-  report = Option22.String("--report", { required: false });
-  tokensIn = Option22.String("--tokens-in", { required: false });
-  tokensOut = Option22.String("--tokens-out", { required: false });
-  durationMs = Option22.String("--duration-ms", { required: false });
-  model = Option22.String("--model", { required: false });
-  error = Option22.String("--error", { required: false });
+  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");
   }
@@ -14408,6 +14464,99 @@ var STUB_COMMANDS = [
   RecordCommand
 ];
 
+// cli/commands/tutorial.ts
+import { existsSync as existsSync19, readFileSync as readFileSync12 } from "fs";
+import { writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname10, join as join15, resolve as resolve20 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
+import { Command as Command22, Option as Option22 } from "clipanion";
+
+// cli/i18n/tutorial.texts.ts
+var TUTORIAL_TEXTS = {
+  // Success — written to stdout after `<cwd>/sm-tutorial.md` is created.
+  written: 'Done. sm-tutorial.md created at {{cwd}}. Open Claude Code here and tell it "run @sm-tutorial.md" to start the interactive tutorial.\n',
+  // Refusal — `sm-tutorial.md` already exists and `--force` was not set.
+  // Goes to stderr, exit code 2 (operational error per spec § Exit codes).
+  alreadyExists: "sm tutorial: sm-tutorial.md already exists at {{cwd}}. Pass `--force` to overwrite.\n",
+  // I/O failure on write or on reading the bundled SKILL source.
+  writeFailed: "sm tutorial: failed to write sm-tutorial.md: {{message}}\n",
+  sourceMissing: "sm tutorial: could not read the bundled tutorial (SKILL.md) from the install. Reinstall @skill-map/cli or report the bug.\n"
+};
+
+// cli/commands/tutorial.ts
+var SM_TUTORIAL_FILENAME = "sm-tutorial.md";
+var TutorialCommand = class extends SmCommand {
+  static paths = [["tutorial"]];
+  static usage = Command22.Usage({
+    category: "Setup",
+    description: "Materialize the interactive tester tutorial (sm-tutorial.md) in the current directory.",
+    details: `
+      Drops the canonical SKILL.md content as ./sm-tutorial.md so a tester
+      can open Claude Code in the cwd and load the file as a skill by
+      typing "ejecut\xE1 @sm-tutorial.md". Top-level only \u2014 no subdirectory
+      is created.
+
+      Does NOT require an initialized .skill-map/ project. Refuses to
+      overwrite an existing sm-tutorial.md unless --force is passed.
+    `,
+    examples: [
+      ["Materialize the tutorial in the cwd", "$0 tutorial"],
+      ["Overwrite an existing sm-tutorial.md", "$0 tutorial --force"]
+    ]
+  });
+  force = Option22.Boolean("--force", false, {
+    description: "Overwrite an existing sm-tutorial.md without prompting."
+  });
+  async run() {
+    const ctx = defaultRuntimeContext();
+    const target = join15(ctx.cwd, SM_TUTORIAL_FILENAME);
+    if (await pathExists(target) && !this.force) {
+      this.context.stderr.write(tx(TUTORIAL_TEXTS.alreadyExists, { cwd: ctx.cwd }));
+      return ExitCode.Error;
+    }
+    let body;
+    try {
+      body = loadBundledTutorialText();
+    } catch {
+      this.context.stderr.write(TUTORIAL_TEXTS.sourceMissing);
+      return ExitCode.Error;
+    }
+    try {
+      await writeFile2(target, body);
+    } catch (err) {
+      this.context.stderr.write(
+        tx(TUTORIAL_TEXTS.writeFailed, { message: formatErrorMessage(err) })
+      );
+      return ExitCode.Error;
+    }
+    this.context.stdout.write(tx(TUTORIAL_TEXTS.written, { cwd: ctx.cwd }));
+    return ExitCode.Ok;
+  }
+};
+var cachedTutorial = null;
+function loadBundledTutorialText() {
+  if (cachedTutorial !== null) return cachedTutorial;
+  cachedTutorial = readTutorialFromDisk();
+  return cachedTutorial;
+}
+function readTutorialFromDisk() {
+  const here = dirname10(fileURLToPath6(import.meta.url));
+  const candidates = [
+    // dev: src/cli/commands/ → repo-root .claude/skills/sm-tutorial/SKILL.md
+    resolve20(here, "../../../.claude/skills/sm-tutorial/SKILL.md"),
+    // bundled: dist/cli.js → dist/cli/tutorial/sm-tutorial.md (sibling)
+    resolve20(here, "cli/tutorial/sm-tutorial.md"),
+    // bundled fallback: any-depth → cli/tutorial/sm-tutorial.md
+    resolve20(here, "../cli/tutorial/sm-tutorial.md")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync19(candidate)) {
+      return readFileSync12(candidate, "utf8");
+    }
+  }
+  throw new Error(`SKILL.md not found in any candidate location (last tried: ${candidates[candidates.length - 1]})`);
+}
+
 // cli/commands/version.ts
 import { Command as Command23 } from "clipanion";
 
@@ -14491,7 +14640,7 @@ cli.register(Builtins.VersionCommand);
 cli.register(RootHelpCommand);
 cli.register(HelpCommand);
 cli.register(InitCommand);
-cli.register(GuideCommand);
+cli.register(TutorialCommand);
 cli.register(ScanCommand);
 cli.register(ScanCompareCommand);
 cli.register(ServeCommand);