@skill-map/cli 0.24.5 → 0.26.0

package/dist/cli.js

@@ -748,19 +748,19 @@ var annotationsExtractor = {
   pluginId: "core",
   kind: "extractor",
   version: "1.0.0",
-  description: "Turns the `supersedes`, `requires`, `related`, `conflictsWith`, and `supersededBy` entries you write in a node's `.sm` sidecar into the arrows (edges) shown between nodes in the graph.",
+  description: "Turns the `supersedes` and `supersededBy` entries you write in a node's `.sm` sidecar into the arrows (edges) shown between nodes in the graph.",
   stability: "stable",
-  emitsLinkKinds: ["supersedes", "references"],
+  emitsLinkKinds: ["supersedes"],
   defaultConfidence: "high",
   scope: "frontmatter",
   extract(ctx) {
     const sourcePath = ctx.node.path;
     const seen = /* @__PURE__ */ new Set();
-    function emit(source, target, kind) {
-      const key = `${source} ${target} ${kind}`;
+    function emit(source, target) {
+      const key = `${source} ${target}`;
       if (seen.has(key)) return;
       seen.add(key);
-      ctx.emitLink(link(source, target, kind));
+      ctx.emitLink(link(source, target));
     }
     const ann = pickAnnotations(ctx.node);
     if (ann) processBlock(ann, sourcePath, emit);
@@ -768,20 +768,11 @@ var annotationsExtractor = {
 };
 function processBlock(block, sourcePath, emit) {
   for (const target of stringArray(block["supersedes"])) {
-    emit(sourcePath, target, "supersedes");
+    emit(sourcePath, target);
   }
   const supersededBy = block["supersededBy"];
   if (typeof supersededBy === "string" && supersededBy.length > 0) {
-    emit(supersededBy, sourcePath, "supersedes");
-  }
-  for (const target of stringArray(block["requires"])) {
-    emit(sourcePath, target, "references");
-  }
-  for (const target of stringArray(block["related"])) {
-    emit(sourcePath, target, "references");
-  }
-  for (const target of stringArray(block["conflictsWith"])) {
-    emit(sourcePath, target, "references");
+    emit(supersededBy, sourcePath);
   }
 }
 function pickAnnotations(node) {
@@ -797,11 +788,11 @@ function stringArray(value) {
   if (!Array.isArray(value)) return [];
   return value.filter((v) => typeof v === "string" && v.length > 0);
 }
-function link(source, target, kind) {
+function link(source, target) {
   return {
     source,
     target,
-    kind,
+    kind: "supersedes",
     confidence: "high",
     sources: [ID]
   };
@@ -2318,7 +2309,13 @@ var VALIDATE_ALL_TEXTS = {
   /** `Node <path> failed schema validation: <errors>` */
   nodeFailure: "Node {{path}} failed schema validation: {{errors}}",
   /** `Link <source> → <target> failed schema validation: <errors>` */
-  linkFailure: "Link {{source}} \u2192 {{target}} failed schema validation: {{errors}}"
+  linkFailure: "Link {{source}} \u2192 {{target}} failed schema validation: {{errors}}",
+  /** `Node <path> is missing required frontmatter fields: <missing>` */
+  frontmatterBaseFailure: "Node {{path}} is missing required frontmatter fields: {{missing}}.",
+  /** Singular tooltip on the alert / chip when a node has exactly one validation failure. */
+  alertTooltipSingle: "Frontmatter or schema validation failed.",
+  /** Plural tooltip; `{{count}}` capped at 99 in the chip badge but the tooltip text shows the raw count. */
+  alertTooltipMany: "{{count}} schema validation issues on this node."
 };
 
 // built-in-plugins/analyzers/validate-all/index.ts
@@ -2331,15 +2328,56 @@ var validateAllAnalyzer = {
   description: "Detects and flags nodes or links violating the project schemas.",
   stability: "stable",
   mode: "deterministic",
+  viewContributions: {
+    // Corner badge on the graph card; surfaces when the node body /
+    // frontmatter fails schema validation (parse error, missing
+    // `name`/`description`, malformed YAML, etc.). Same visual
+    // chassis as `core/broken-ref`, danger severity.
+    alert: {
+      slot: "graph.node.alert",
+      icon: "fa-solid fa-triangle-exclamation",
+      emitWhenEmpty: false
+    },
+    // Footer chip that mirrors the corner alert with the actual
+    // count so the operator can scan the cards and prioritise.
+    // Outlined (vs the filled corner alert) per the broken-ref
+    // pattern: two beats of the same signal.
+    chip: {
+      slot: "card.footer.right",
+      icon: "fa-regular fa-triangle-exclamation",
+      emitWhenEmpty: false,
+      priority: 35
+    }
+  },
   evaluate(ctx) {
     const validators = loadSchemaValidators();
     const findings = [];
+    const perNode = /* @__PURE__ */ new Map();
     for (const node of ctx.nodes) {
+      const before = findings.length;
       collectNodeFindings(validators, node, findings);
+      collectFrontmatterBaseFindings(node, findings);
+      if (findings.length > before) {
+        perNode.set(node.path, (perNode.get(node.path) ?? 0) + (findings.length - before));
+      }
     }
     for (const link2 of ctx.links) {
       collectLinkFindings(validators, link2, findings);
     }
+    for (const [nodePath, count] of perNode) {
+      const tooltip = count === 1 ? VALIDATE_ALL_TEXTS.alertTooltipSingle : tx(VALIDATE_ALL_TEXTS.alertTooltipMany, { count });
+      const capped = Math.min(count, 99);
+      ctx.emitContribution(nodePath, "alert", {
+        icon: "fa-solid fa-triangle-exclamation",
+        severity: "danger",
+        tooltip
+      });
+      ctx.emitContribution(nodePath, "chip", {
+        value: capped,
+        severity: "danger",
+        tooltip
+      });
+    }
     return findings;
   }
 };
@@ -2357,6 +2395,33 @@ function collectNodeFindings(v, node, out) {
     data: { target: "node", path: node.path }
   });
 }
+function collectFrontmatterBaseFindings(node, out) {
+  if (node.provider === "markdown") return;
+  if (node.bytes.frontmatter === 0) return;
+  const fm = node.frontmatter ?? {};
+  const missing = [];
+  if (isMissingStringField(fm, "name")) missing.push("name");
+  if (isMissingStringField(fm, "description")) missing.push("description");
+  if (missing.length === 0) return;
+  out.push({
+    analyzerId: ID19,
+    // `warn` (not `error`) so the default `sm scan` exit code stays
+    // 0 even when nodes are missing frontmatter base fields. Strict
+    // mode (`sm scan --strict`) still escalates to exit 1. Matches
+    // the `frontmatter-invalid` severity policy of the orchestrator.
+    severity: "warn",
+    nodeIds: [node.path],
+    message: tx(VALIDATE_ALL_TEXTS.frontmatterBaseFailure, {
+      path: node.path,
+      missing: missing.join(", ")
+    }),
+    data: { target: "frontmatter", path: node.path, missing }
+  });
+}
+function isMissingStringField(fm, field) {
+  const v = fm[field];
+  return typeof v !== "string" || v.length === 0;
+}
 function collectLinkFindings(v, link2, out) {
   const result = v.validate("link", toLinkForSchema(link2));
   if (result.ok) return;
@@ -2401,6 +2466,54 @@ function toLinkForSchema(link2) {
   };
 }
 
+// kernel/util/trigger-resolve.ts
+function buildNameIndex(nodes) {
+  const out = /* @__PURE__ */ new Map();
+  indexByCanonicalName(nodes, out);
+  fillIndexWithPathBasename(nodes, out);
+  return out;
+}
+function indexByCanonicalName(nodes, out) {
+  for (const node of nodes) {
+    const raw = canonicalName(node);
+    if (raw === null) continue;
+    const key = normalizeTrigger(raw);
+    if (!out.has(key)) out.set(key, node.path);
+  }
+}
+function fillIndexWithPathBasename(nodes, out) {
+  for (const node of nodes) {
+    if (canonicalName(node) !== null) continue;
+    const derived = pathBasenameForLink(node.path);
+    if (derived.length === 0) continue;
+    const key = normalizeTrigger(derived);
+    if (!out.has(key)) out.set(key, node.path);
+  }
+}
+function canonicalName(node) {
+  const raw = node.frontmatter?.["name"];
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  return raw;
+}
+function pathBasenameForLink(path) {
+  const segments = path.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) return path;
+  const last = segments[segments.length - 1];
+  if (last === "SKILL.md" && segments.length >= 2) {
+    return segments[segments.length - 2];
+  }
+  return last.replace(/\.md$/, "");
+}
+function resolveLinkTargetToPath(link2, nameIndex) {
+  const raw = link2.target;
+  const sigil = raw.charAt(0);
+  if (sigil !== "/" && sigil !== "@") return raw;
+  const normalizedTrigger = link2.trigger?.normalizedTrigger;
+  const normalized = typeof normalizedTrigger === "string" ? normalizedTrigger.replace(/^[/@]/, "").trim() : normalizeTrigger(raw.slice(1));
+  const resolved = nameIndex.get(normalized);
+  return resolved ?? raw;
+}
+
 // built-in-plugins/analyzers/link-counts/index.ts
 var ID20 = "link-counts";
 var linkCountsAnalyzer = {
@@ -2428,10 +2541,12 @@ var linkCountsAnalyzer = {
     }
   },
   evaluate(ctx) {
+    const nameIndex = buildNameIndex(ctx.nodes);
     const perTarget = /* @__PURE__ */ new Map();
     const perSource = /* @__PURE__ */ new Map();
     for (const link2 of ctx.links) {
-      bump(perTarget, link2.target, link2.kind);
+      const resolvedTarget = resolveLinkTargetToPath(link2, nameIndex);
+      bump(perTarget, resolvedTarget, link2.kind);
       bump(perSource, link2.source, link2.kind);
     }
     for (const node of ctx.nodes) {
@@ -4614,8 +4729,8 @@ async function saveUpdateCheckCache(db, cache) {
 var SORT_BY_COLUMNS = /* @__PURE__ */ new Set([
   "path",
   "kind",
-  "bytes_total",
-  "bytesTotal",
+  "tokens_total",
+  "tokensTotal",
   "links_out_count",
   "linksOutCount",
   "links_in_count",
@@ -4626,7 +4741,7 @@ var SORT_BY_COLUMNS = /* @__PURE__ */ new Set([
 var SORT_BY_DEFAULT_DIRECTION = {
   path: "asc",
   kind: "asc",
-  bytesTotal: "desc",
+  tokensTotal: "desc",
   linksOutCount: "desc",
   linksInCount: "desc",
   externalRefsCount: "desc"
@@ -5747,7 +5862,7 @@ var UPDATE_CHECK_TEXTS = {
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.24.5",
+  version: "0.26.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -6705,16 +6820,25 @@ var BUMP_TEXTS = {
   // --- failures -------------------------------------------------------------
   bumpFailed: "{{glyph}}  sm bump: {{message}}\n",
   storeFailedDetail: "sidecar write failed for {{path}}: {{message}}",
-  resolveAbsPathFailed: "cannot resolve absolute path for {{nodePath}}: {{message}}",
+  resolveAbsPathFailed: "cannot resolve absolute path for {{nodePath}}: {{message}}"
   // --- .sm consent gate ---------------------------------------------------
+  // The shared strings live in `consent.texts.ts` (CONSENT_TEXTS); they
+  // are used by every verb that writes a sidecar (`sm bump`,
+  // `sm sidecar refresh`, `sm sidecar annotate`) with a `{{verb}}`
+  // placeholder for the directed prefix.
+};
+
+// cli/i18n/consent.texts.ts
+var CONSENT_TEXTS = {
   /**
    * Pre-prompt context shown before the interactive `confirm()` so the
-   * operator sees what they are about to opt into. `.skill-map/settings.local.json`
-   * is gitignored, the choice is saved per-checkout, never travels via the repo.
+   * operator sees what they are about to opt into.
+   * `.skill-map/settings.local.json` is gitignored, the choice is saved
+   * per-checkout, never travels via the repo.
    */
-  consentPrompt: "skill-map needs your consent to create .sm sidecar files next to your\nsource files in this project. The choice is saved to\n.skill-map/settings.local.json (gitignored, per-checkout) so this prompt\nnever appears again. Decline to abort without persisting the rejection.\n\nAllow .sm sidecar writes in this project?",
-  consentAborted: "{{glyph}}  sm bump: aborted by user. No .sm sidecar files were written.\n",
-  consentRequiredNonTty: "{{glyph}}  sm bump: consent required to write .sm sidecar files in this project.\n   {{hint}}\n",
+  consentPrompt: "{{glyph}}  skill-map needs consent to create .sm sidecar files next to your\n   .md sources. Your choice is saved to .skill-map/settings.local.json\n   (gitignored) and this prompt will not appear again.\n\nAllow .sm sidecar writes in this project?",
+  consentAborted: "{{glyph}}  {{verb}}: aborted by user. No .sm sidecar files were written.\n",
+  consentRequiredNonTty: "{{glyph}}  {{verb}}: consent required to write .sm sidecar files in this project.\n   {{hint}}\n",
   consentRequiredNonTtyHint: "Pass --yes to grant (writes to .skill-map/settings.local.json, gitignored)."
 };
 
@@ -7112,21 +7236,25 @@ var BumpCommand = class extends SmCommand {
       const isTTY = stdin.isTTY === true;
       if (!isTTY || this.yes) {
         this.printer.error(
-          tx(BUMP_TEXTS.consentRequiredNonTty, {
+          tx(CONSENT_TEXTS.consentRequiredNonTty, {
             glyph: ansi.red("\u2715"),
-            hint: ansi.dim(BUMP_TEXTS.consentRequiredNonTtyHint)
+            verb: "sm bump",
+            hint: ansi.dim(CONSENT_TEXTS.consentRequiredNonTtyHint)
           })
         );
         return ExitCode.Error;
       }
       const ok = await confirm(
-        BUMP_TEXTS.consentPrompt,
+        tx(CONSENT_TEXTS.consentPrompt, { glyph: ansi.cyan("\u2139") }),
         { stdin, stderr },
         { defaultAnswer: "yes" }
       );
       if (!ok) {
         this.printer.info(
-          tx(BUMP_TEXTS.consentAborted, { glyph: ansi.cyan("\u2139") })
+          tx(CONSENT_TEXTS.consentAborted, {
+            glyph: ansi.cyan("\u2139"),
+            verb: "sm bump"
+          })
         );
         return ExitCode.Error;
       }
@@ -12502,6 +12630,26 @@ function validateLink(extractor, link2, emitter) {
   const confidence = link2.confidence ?? extractor.defaultConfidence;
   return { ...link2, confidence };
 }
+function dedupeLinks(links) {
+  const out = /* @__PURE__ */ new Map();
+  for (const link2 of links) {
+    const trigger = link2.trigger?.normalizedTrigger ?? "";
+    const key = `${link2.source}\0${link2.target}\0${link2.kind}\0${trigger}`;
+    const existing = out.get(key);
+    if (existing) {
+      const seen = new Set(existing.sources);
+      for (const src of link2.sources) {
+        if (!seen.has(src)) {
+          seen.add(src);
+          existing.sources = [...existing.sources, src];
+        }
+      }
+      continue;
+    }
+    out.set(key, link2);
+  }
+  return [...out.values()];
+}
 function recomputeLinkCounts(nodes, links) {
   const byPath3 = /* @__PURE__ */ new Map();
   for (const node of nodes) {
@@ -13492,6 +13640,7 @@ async function runScanInternal(_kernel, options) {
     providerFrontmatter: setup.providerFrontmatter,
     pluginStores: options.pluginStores
   });
+  walked.internalLinks = dedupeLinks(walked.internalLinks);
   recomputeLinkCounts(walked.nodes, walked.internalLinks);
   recomputeExternalRefsCount(walked.nodes, walked.externalLinks, walked.cachedPaths);
   await dispatchExtractorCompleted(exts.extractors, emitter, hookDispatcher);
@@ -15209,7 +15358,7 @@ var LIST_TEXTS = {
   tableHeaderIn: "IN",
   tableHeaderExt: "EXT",
   tableHeaderIssues: "ISSUES",
-  tableHeaderBytes: "BYTES",
+  tableHeaderTokens: "TOKENS",
   /** Footer line: count of rendered nodes (`3 nodes` / `1 node`). */
   tableFooterCount: "{{count}} {{noun}}\n",
   tableFooterNounSingular: "node",
@@ -15222,7 +15371,7 @@ var LIST_TEXTS = {
 var SORT_BY = {
   path: { column: "path", direction: "asc" },
   kind: { column: "kind", direction: "asc" },
-  bytes_total: { column: "bytesTotal", direction: "desc" },
+  tokens_total: { column: "tokensTotal", direction: "desc" },
   links_out_count: { column: "linksOutCount", direction: "desc" },
   links_in_count: { column: "linksInCount", direction: "desc" },
   external_refs_count: { column: "externalRefsCount", direction: "desc" }
@@ -15241,7 +15390,7 @@ var ListCommand = class extends SmCommand {
       and sidecar.annotations.tags by default; --tag-source author|user
       narrows to one side).
 
-      --sort-by accepts: path, kind, bytes_total, links_out_count,
+      --sort-by accepts: path, kind, tokens_total, links_out_count,
       links_in_count, external_refs_count. Default: path. --limit N caps
       the result; default is no limit.
 
@@ -15250,7 +15399,7 @@ var ListCommand = class extends SmCommand {
     examples: [
       ["List every node", "$0 list"],
       ["List only agents", "$0 list --kind agent"],
-      ["Top 5 by total bytes", "$0 list --sort-by bytes_total --limit 5"],
+      ["Top 5 by total tokens", "$0 list --sort-by tokens_total --limit 5"],
       ["Only nodes with issues, machine-readable", "$0 list --issue --json"],
       ["Filter by tag (author or user surfaces)", "$0 list --tag urgent"],
       ["Filter by user-only tag", "$0 list --tag wip --tag-source user"]
@@ -15393,7 +15542,7 @@ function renderTable2(nodes, issuesByNode, ansi) {
     in: n.linksInCount,
     ext: n.externalRefsCount,
     issues: issuesByNode.get(n.path) ?? 0,
-    bytes: n.bytes.total
+    tokens: n.tokens?.total ?? null
   }));
   const widths = computeWidths(rows);
   const lines = [];
@@ -15421,9 +15570,12 @@ function computeWidths(rows) {
     in: Math.max(headerLen(LIST_TEXTS.tableHeaderIn), ...rows.map((r) => String(r.in).length)),
     ext: Math.max(headerLen(LIST_TEXTS.tableHeaderExt), ...rows.map((r) => String(r.ext).length)),
     issues: Math.max(headerLen(LIST_TEXTS.tableHeaderIssues), ...rows.map((r) => String(r.issues).length)),
-    bytes: Math.max(headerLen(LIST_TEXTS.tableHeaderBytes), ...rows.map((r) => String(r.bytes).length))
+    tokens: Math.max(headerLen(LIST_TEXTS.tableHeaderTokens), ...rows.map((r) => formatTokens(r.tokens).length))
   };
 }
+function formatTokens(value) {
+  return value === null ? "-" : String(value);
+}
 function clampMax(value, max) {
   return value > max ? max : value;
 }
@@ -15436,7 +15588,7 @@ function formatHeaderRow(w, ansi) {
     ansi.dim(LIST_TEXTS.tableHeaderIn.padStart(w.in)),
     ansi.dim(LIST_TEXTS.tableHeaderExt.padStart(w.ext)),
     ansi.dim(LIST_TEXTS.tableHeaderIssues.padStart(w.issues)),
-    ansi.dim(LIST_TEXTS.tableHeaderBytes.padStart(w.bytes))
+    ansi.dim(LIST_TEXTS.tableHeaderTokens.padStart(w.tokens))
   ].join("  ");
 }
 function formatDataRow(r, w, ansi) {
@@ -15449,7 +15601,7 @@ function formatDataRow(r, w, ansi) {
     String(r.in).padStart(w.in),
     String(r.ext).padStart(w.ext),
     issuesCol,
-    String(r.bytes).padStart(w.bytes)
+    formatTokens(r.tokens).padStart(w.tokens)
   ].join("  ");
 }
 
@@ -22308,7 +22460,7 @@ var SHOW_TEXTS = {
   /** Tail appended to `nodeHeader` when provider differs from kind. */
   providerSuffix: "   {{label}}",
   providerSuffixLabel: "provider: {{provider}}",
-  // --- field block (Title / Description / Bytes / Tokens / …) ---------
+  // --- field block (Title / Description / Tokens / …) -----------------
   /** Field row, label padded by the renderer to align values. */
   fieldRow: "  {{label}}  {{value}}\n",
   /** Continuation indent for multi-line values (description, etc.). */
@@ -22317,7 +22469,6 @@ var SHOW_TEXTS = {
   fieldLabelDescription: "Description",
   fieldLabelStability: "Stability",
   fieldLabelVersion: "Version",
-  fieldLabelBytes: "Bytes",
   fieldLabelTokens: "Tokens",
   fieldLabelExternalRefs: "External refs",
   /** `{{total}} total · {{frontmatter}} frontmatter · {{body}} body`. */
@@ -22431,23 +22582,13 @@ function collectNodeFields(node) {
     fields.push({ label: SHOW_TEXTS.fieldLabelVersion, value: sanitizeForTerminal(String(projected.version)) });
   }
   fields.push({
-    label: SHOW_TEXTS.fieldLabelBytes,
-    value: tx(SHOW_TEXTS.weightSplit, {
-      total: node.bytes.total,
-      frontmatter: node.bytes.frontmatter,
-      body: node.bytes.body
-    })
+    label: SHOW_TEXTS.fieldLabelTokens,
+    value: node.tokens ? tx(SHOW_TEXTS.weightSplit, {
+      total: node.tokens.total,
+      frontmatter: node.tokens.frontmatter,
+      body: node.tokens.body
+    }) : "-"
   });
-  if (node.tokens) {
-    fields.push({
-      label: SHOW_TEXTS.fieldLabelTokens,
-      value: tx(SHOW_TEXTS.weightSplit, {
-        total: node.tokens.total,
-        frontmatter: node.tokens.frontmatter,
-        body: node.tokens.body
-      })
-    });
-  }
   fields.push({ label: SHOW_TEXTS.fieldLabelExternalRefs, value: String(node.externalRefsCount) });
   return fields;
 }
@@ -22631,17 +22772,12 @@ var SIDECAR_TEXTS = {
   annotateCreated: "{{glyph}}  Created {{sidecarPath}}. Edit it, then run `sm bump {{nodePath}}` to commit the version.\n",
   /** Trailing dim tag for sidecar prune dry-run (matches the orphans pattern). */
   sidecarDryRunTag: "  (no changes made)",
-  annotateFailed: "{{glyph}}  sm sidecar annotate: {{message}}\n",
-  // --- .sm consent gate (shared across refresh + annotate) -----------------
-  /**
-   * Pre-prompt context shown before the interactive `confirm()` so the
-   * operator sees what they are about to opt into. `.skill-map/settings.local.json`
-   * is gitignored, the choice is saved per-checkout, never travels via the repo.
-   */
-  consentPrompt: "skill-map needs your consent to create .sm sidecar files next to your\nsource files in this project. The choice is saved to\n.skill-map/settings.local.json (gitignored, per-checkout) so this prompt\nnever appears again. Decline to abort without persisting the rejection.\n\nAllow .sm sidecar writes in this project?",
-  consentAborted: "{{glyph}}  sm sidecar: aborted by user. No .sm sidecar files were written.\n",
-  consentRequiredNonTty: "{{glyph}}  sm sidecar: consent required to write .sm sidecar files in this project.\n   {{hint}}\n",
-  consentRequiredNonTtyHint: "Pass --yes to grant (writes to .skill-map/settings.local.json, gitignored)."
+  annotateFailed: "{{glyph}}  sm sidecar annotate: {{message}}\n"
+  // --- .sm consent gate ---------------------------------------------------
+  // The shared strings live in `consent.texts.ts` (CONSENT_TEXTS); they
+  // are used by every verb that writes a sidecar (`sm bump`,
+  // `sm sidecar refresh`, `sm sidecar annotate`) with a `{{verb}}`
+  // placeholder for the directed prefix.
 };
 
 // cli/commands/sidecar.ts
@@ -22654,21 +22790,25 @@ async function runWithSidecarConsent(bag, ansi, dispatch) {
     if (!isTTY || bag.yes) {
       const errGlyph = ansi.red("\u2715");
       bag.printError(
-        tx(SIDECAR_TEXTS.consentRequiredNonTty, {
+        tx(CONSENT_TEXTS.consentRequiredNonTty, {
           glyph: errGlyph,
-          hint: ansi.dim(SIDECAR_TEXTS.consentRequiredNonTtyHint)
+          verb: "sm sidecar",
+          hint: ansi.dim(CONSENT_TEXTS.consentRequiredNonTtyHint)
         })
       );
       return ExitCode.Error;
     }
     const ok = await confirm(
-      SIDECAR_TEXTS.consentPrompt,
+      tx(CONSENT_TEXTS.consentPrompt, { glyph: ansi.cyan("\u2139") }),
       { stdin: bag.stdin, stderr: bag.stderr },
       { defaultAnswer: "yes" }
     );
     if (!ok) {
       bag.printInfo(
-        tx(SIDECAR_TEXTS.consentAborted, { glyph: ansi.cyan("\u2139") })
+        tx(CONSENT_TEXTS.consentAborted, {
+          glyph: ansi.cyan("\u2139"),
+          verb: "sm sidecar"
+        })
       );
       return ExitCode.Error;
     }
@@ -23291,7 +23431,7 @@ import { Command as Command37, Option as Option35 } from "clipanion";
 
 // cli/i18n/tutorial.texts.ts
 var TUTORIAL_TEXTS = {
-  // Success, written to stdout after `<cwd>/sm-tutorial.md` is created.
+  // Success, written to stdout after `<cwd>/{{filename}}` is created.
   // Multi-line layout: the two trigger phrases (English / Spanish) are
   // indented and labelled so they're the most visible part of the
   // output. The reminder above them surfaces the SKILL's language
@@ -23303,55 +23443,91 @@ var TUTORIAL_TEXTS = {
    * `English` / `Español` labels print dim, the eye lands on the
    * trigger phrases the user is going to copy / paste.
    */
-  written: "  {{glyph}}  sm-tutorial.md created at {{cwd}}\n\n  Open Claude Code in this directory. Your first message sets\n  the tutorial language for the rest of the session:\n\n      {{enLabel}}  run @sm-tutorial.md\n      {{esLabel}}  ejecut\xE1 @sm-tutorial.md\n",
+  written: "  {{glyph}}  {{filename}} created at {{cwd}}\n\n  Open Claude Code in this directory. Your first message sets\n  the tutorial language for the rest of the session:\n\n      {{enLabel}}  run @{{filename}}\n      {{esLabel}}  ejecut\xE1 @{{filename}}\n",
   writtenLabelEn: "English",
   writtenLabelEs: "Espa\xF1ol",
-  // Refusal, `sm-tutorial.md` already exists and `--force` was not set.
+  // Refusal, `{{filename}}` already exists and `--force` was not set.
   // Goes to stderr, exit code 2 (operational error per spec § Exit codes).
   // Mirrors the success body shape: glyph + headline, then a dim hint
   // line spelling the fix.
-  alreadyExists: "{{glyph}}  sm-tutorial.md already exists at {{cwd}}\n   {{hint}}\n",
+  alreadyExists: "{{glyph}}  {{filename}} already exists at {{cwd}}\n   {{hint}}\n",
   alreadyExistsHint: "Pass `--force` to overwrite.",
+  // Invalid `variant` positional argument. Goes to stderr, exit code 2.
+  // Mirrors `alreadyExists`: glyph + headline + dim hint enumerating the
+  // valid values.
+  invalidVariant: "{{glyph}}  sm tutorial: unknown variant '{{variant}}'\n   {{hint}}\n",
+  invalidVariantHint: "Valid values: tutorial (default), master.",
   // I/O failure on write or on reading the bundled SKILL source.
-  writeFailed: "{{glyph}}  sm tutorial: failed to write sm-tutorial.md: {{message}}\n",
-  sourceMissing: "{{glyph}}  sm tutorial: could not read the bundled tutorial (SKILL.md) from the install.\n   {{hint}}\n",
+  writeFailed: "{{glyph}}  sm tutorial: failed to write {{filename}}: {{message}}\n",
+  sourceMissing: "{{glyph}}  sm tutorial: could not read the bundled tutorial ({{filename}}) from the install.\n   {{hint}}\n",
   sourceMissingHint: "Reinstall @skill-map/cli or report the bug."
 };
 
 // cli/commands/tutorial.ts
-var SM_TUTORIAL_FILENAME = "sm-tutorial.md";
+var VALID_VARIANTS = ["tutorial", "master"];
+var DEFAULT_VARIANT = "tutorial";
+var VARIANT_SPECS = {
+  tutorial: {
+    filename: "sm-tutorial.md",
+    sourcePath: ".claude/skills/sm-tutorial/SKILL.md",
+    bundledName: "sm-tutorial.md"
+  },
+  master: {
+    filename: "sm-master.md",
+    sourcePath: ".claude/skills/sm-master/SKILL.md",
+    bundledName: "sm-master.md"
+  }
+};
 var TutorialCommand = class extends SmCommand {
   static paths = [["tutorial"]];
   static usage = Command37.Usage({
     category: "Setup",
-    description: "Materialize the interactive tester tutorial (sm-tutorial.md) in the current directory.",
+    description: "Materialize an interactive tester tutorial (sm-tutorial.md or sm-master.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; no subdirectory
-      is created.
+      Drops the canonical SKILL.md content as ./sm-tutorial.md (default)
+      or ./sm-master.md (when invoked as \`sm tutorial master\`) so a
+      tester can open Claude Code in the cwd and load the file as a
+      skill by typing "ejecut\xE1 @sm-tutorial.md" (or "@sm-master.md").
+      Top-level only; no subdirectory is created.
 
       Does NOT require an initialized .skill-map/ project. Refuses to
-      overwrite an existing sm-tutorial.md unless --force is passed.
+      overwrite the target file unless --force is passed. Valid values
+      for the positional argument are: tutorial (default), master.
     `,
     examples: [
-      ["Materialize the tutorial in the cwd", "$0 tutorial"],
-      ["Overwrite an existing sm-tutorial.md", "$0 tutorial --force"]
+      ["Materialize the basic tutorial in the cwd", "$0 tutorial"],
+      ["Materialize the advanced tutorial in the cwd", "$0 tutorial master"],
+      ["Overwrite an existing target file", "$0 tutorial --force"]
     ]
   });
+  variant = Option35.String({ required: false });
   force = Option35.Boolean("--force", false, {
-    description: "Overwrite an existing sm-tutorial.md without prompting."
+    description: "Overwrite an existing target file without prompting."
   });
   async run() {
     const ctx = defaultRuntimeContext();
-    const target = join17(ctx.cwd, SM_TUTORIAL_FILENAME);
     const stderr = this.context.stderr;
     const stderrAnsi = this.ansiFor("stderr");
     const errGlyph = stderrAnsi.red("\u2715");
+    const rawVariant = this.variant;
+    if (rawVariant !== void 0 && !isTutorialVariant(rawVariant)) {
+      this.printer.error(
+        tx(TUTORIAL_TEXTS.invalidVariant, {
+          glyph: errGlyph,
+          variant: rawVariant,
+          hint: stderrAnsi.dim(TUTORIAL_TEXTS.invalidVariantHint)
+        })
+      );
+      return ExitCode.Error;
+    }
+    const variant = rawVariant ?? DEFAULT_VARIANT;
+    const spec = VARIANT_SPECS[variant];
+    const target = join17(ctx.cwd, spec.filename);
     if (await pathExists(target) && !this.force) {
       this.printer.error(
         tx(TUTORIAL_TEXTS.alreadyExists, {
           glyph: errGlyph,
+          filename: spec.filename,
           cwd: stderrAnsi.dim(displayCwd(ctx.cwd)),
           hint: stderrAnsi.dim(TUTORIAL_TEXTS.alreadyExistsHint)
         })
@@ -23360,11 +23536,12 @@ var TutorialCommand = class extends SmCommand {
     }
     let body;
     try {
-      body = loadBundledTutorialText();
+      body = loadBundledTutorialText(variant);
     } catch {
       this.printer.error(
         tx(TUTORIAL_TEXTS.sourceMissing, {
           glyph: errGlyph,
+          filename: spec.filename,
           hint: stderrAnsi.dim(TUTORIAL_TEXTS.sourceMissingHint)
         })
       );
@@ -23376,6 +23553,7 @@ var TutorialCommand = class extends SmCommand {
       this.printer.error(
         tx(TUTORIAL_TEXTS.writeFailed, {
           glyph: errGlyph,
+          filename: spec.filename,
           message: formatErrorMessage(err)
         })
       );
@@ -23391,6 +23569,7 @@ var TutorialCommand = class extends SmCommand {
     this.printer.data(
       tx(TUTORIAL_TEXTS.written, {
         glyph: ansi.green("\u2713"),
+        filename: spec.filename,
         cwd: ansi.dim(displayCwd(ctx.cwd)),
         enLabel: ansi.dim(TUTORIAL_TEXTS.writtenLabelEn),
         esLabel: ansi.dim(TUTORIAL_TEXTS.writtenLabelEs)
@@ -23399,26 +23578,32 @@ var TutorialCommand = class extends SmCommand {
     return ExitCode.Ok;
   }
 };
+function isTutorialVariant(value) {
+  return VALID_VARIANTS.includes(value);
+}
 function displayCwd(cwd) {
   const segments = cwd.split("/").filter((s) => s.length > 0);
   if (segments.length === 0) return "./";
   return `./${segments[segments.length - 1]}/`;
 }
-var cachedTutorial = null;
-function loadBundledTutorialText() {
-  if (cachedTutorial !== null) return cachedTutorial;
-  cachedTutorial = readTutorialFromDisk();
-  return cachedTutorial;
+var cachedTutorials = /* @__PURE__ */ new Map();
+function loadBundledTutorialText(variant) {
+  const cached = cachedTutorials.get(variant);
+  if (cached !== void 0) return cached;
+  const body = readTutorialFromDisk(variant);
+  cachedTutorials.set(variant, body);
+  return body;
 }
-function readTutorialFromDisk() {
+function readTutorialFromDisk(variant) {
+  const spec = VARIANT_SPECS[variant];
   const here = dirname18(fileURLToPath6(import.meta.url));
   const candidates = [
-    // dev: src/cli/commands/ → repo-root .claude/skills/sm-tutorial/SKILL.md
-    resolve36(here, "../../../.claude/skills/sm-tutorial/SKILL.md"),
-    // bundled: dist/cli.js → dist/cli/tutorial/sm-tutorial.md (sibling)
-    resolve36(here, "cli/tutorial/sm-tutorial.md"),
-    // bundled fallback: any-depth → cli/tutorial/sm-tutorial.md
-    resolve36(here, "../cli/tutorial/sm-tutorial.md")
+    // dev: src/cli/commands/ → repo-root .claude/skills/<slug>/SKILL.md
+    resolve36(here, "../../..", spec.sourcePath),
+    // bundled: dist/cli.js → dist/cli/tutorial/<filename> (sibling)
+    resolve36(here, "cli/tutorial", spec.bundledName),
+    // bundled fallback: any-depth → cli/tutorial/<filename>
+    resolve36(here, "../cli/tutorial", spec.bundledName)
   ];
   for (const candidate of candidates) {
     if (existsSync28(candidate)) {