@skill-map/cli 0.20.0 → 0.21.0

package/dist/cli.js

@@ -614,20 +614,23 @@ var geminiProvider = {
   // registry entries (they ship later under the Gemini bundle), but
   // the qualified form is the contract.
   //
-  // UI presentation: Google brand palette — Gemini purple for agents,
-  // Google blue for skills, Claude-equivalent neutral for the markdown
-  // fallback (so the fallback reads consistent across vendors). Light
-  // / dark variants follow the same hue with a luminosity flip.
+  // UI presentation: kind visuals are normalised across Providers — every
+  // Provider that contributes `agent` declares the same color + icon as
+  // Claude, every Provider that contributes `skill` declares the same
+  // color + icon as Claude, etc. The declaration STAYS per-Provider (the
+  // shape allows divergence the day a Provider wants its own identity for
+  // a kind), but today the values mirror Claude so the visual vocabulary
+  // is uniform regardless of where a node was sourced from.
   kinds: {
     agent: {
       schema: "./schemas/agent.schema.json",
       schemaJson: agent_schema_default2,
       defaultRefreshAction: "gemini/summarize-agent",
       ui: {
-        label: "Gemini Agents",
-        color: "#9b72cb",
-        colorDark: "#b794d4",
-        icon: { kind: "pi", id: "pi-sparkles" }
+        label: "Agents",
+        color: "#3b82f6",
+        colorDark: "#60a5fa",
+        icon: { kind: "pi", id: "pi-user" }
       }
     },
     skill: {
@@ -635,9 +638,9 @@ var geminiProvider = {
       schemaJson: skill_schema_default2,
       defaultRefreshAction: "gemini/summarize-skill",
       ui: {
-        label: "Gemini Skills",
-        color: "#4285f4",
-        colorDark: "#669df6",
+        label: "Skills",
+        color: "#10b981",
+        colorDark: "#34d399",
         icon: { kind: "pi", id: "pi-bolt" }
       }
     }
@@ -685,12 +688,9 @@ var agentSkillsProvider = {
       schemaJson: skill_schema_default3,
       defaultRefreshAction: "agent-skills/summarize-skill",
       ui: {
-        label: "Agent Skills",
-        // Neutral slate — distinct from Claude green and Gemini blue
-        // so a node painted with this Provider's color reads as
-        // "vendor-agnostic open-standard" at a glance.
-        color: "#64748b",
-        colorDark: "#94a3b8",
+        label: "Skills",
+        color: "#10b981",
+        colorDark: "#34d399",
         icon: { kind: "pi", id: "pi-bolt" }
       }
     }
@@ -766,7 +766,7 @@ var annotationsExtractor = {
   pluginId: "core",
   kind: "extractor",
   version: "1.0.0",
-  description: "Reads structured references from the sidecar `.sm` `annotations:` block (supersedes, supersededBy, requires, related, conflictsWith).",
+  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.",
   stability: "stable",
   emitsLinkKinds: ["supersedes", "references"],
   defaultConfidence: "high",
@@ -843,25 +843,11 @@ var slashExtractor = {
   pluginId: "core",
   kind: "extractor",
   version: "1.0.0",
-  description: "Detects /command invocation tokens in the node body.",
+  description: "Detects `/command` invocations in a node's body and turns each one into an arrow (edge) between nodes in the graph.",
   stability: "stable",
   emitsLinkKinds: ["invokes"],
   defaultConfidence: "medium",
   scope: "body",
-  /**
-   * View contribution — surface the distinct-invocation count as a
-   * counter chip in `card.footer.left.counter`, alongside the
-   * at-directive and markdown-link counters. `emitWhenEmpty: false`
-   * keeps unrelated nodes free of a `/ 0` decoration.
-   */
-  viewContributions: {
-    count: {
-      slot: "card.footer.left.counter",
-      icon: "/",
-      label: "commands",
-      emitWhenEmpty: false
-    }
-  },
   extract(ctx) {
     const seen = /* @__PURE__ */ new Set();
     for (const match of ctx.body.matchAll(SLASH_RE)) {
@@ -881,9 +867,6 @@ var slashExtractor = {
         }
       });
     }
-    if (seen.size > 0) {
-      ctx.emitContribution("count", { value: seen.size });
-    }
   }
 };
 
@@ -895,25 +878,11 @@ var atDirectiveExtractor = {
   pluginId: "core",
   kind: "extractor",
   version: "1.0.0",
-  description: "Detects @agent-name mentions in the node body.",
+  description: "Detects `@agent-name` mentions in a node's body and turns each one into an arrow (edge) between nodes in the graph.",
   stability: "stable",
   emitsLinkKinds: ["mentions"],
   defaultConfidence: "medium",
   scope: "body",
-  /**
-   * View contribution — surface the distinct-mention count as a
-   * counter chip in `card.footer.left.counter`. `emitWhenEmpty: false`
-   * keeps unrelated nodes (no @-handles in the body) free of a `@ 0`
-   * decoration.
-   */
-  viewContributions: {
-    count: {
-      slot: "card.footer.left.counter",
-      icon: "@",
-      label: "mentions",
-      emitWhenEmpty: false
-    }
-  },
   extract(ctx) {
     const seen = /* @__PURE__ */ new Set();
     for (const match of ctx.body.matchAll(AT_RE)) {
@@ -933,9 +902,6 @@ var atDirectiveExtractor = {
         }
       });
     }
-    if (seen.size > 0) {
-      ctx.emitContribution("count", { value: seen.size });
-    }
   }
 };
 
@@ -948,7 +914,7 @@ var externalUrlCounterExtractor = {
   pluginId: "core",
   kind: "extractor",
   version: "1.0.0",
-  description: "Counts distinct external http(s) URLs in the node body. Emits pseudo-links the orchestrator strips after counting.",
+  description: "Counts the distinct external URLs (`http://` / `https://`) in a node's body and shows the total as a chip on the card.",
   stability: "stable",
   emitsLinkKinds: ["references"],
   defaultConfidence: "low",
@@ -957,14 +923,21 @@ var externalUrlCounterExtractor = {
    * Phase 6 / View contribution system — surface the distinct-URL
    * count as a card-footer-right chip. The chip is silent when zero
    * URLs were emitted (`emitWhenEmpty: false`), so unrelated nodes
-   * do not gain a `🔗 0` decoration. The counter rides on exactly
+   * do not gain a `link 0` decoration. The counter rides on exactly
    * the same data the orchestrator was already going to count — there
    * is no second pass.
+   *
+   * Icon is the PrimeIcons `pi-link` glyph (declared as the bare
+   * `'link'` per `IconString` rules in `view-slots.schema.json`).
+   * Mirrors the look of the legacy hardcoded `pi pi-link` chip in
+   * `node-card.html` it is poised to replace — same icon font, same
+   * sizing inherited from the footer `.sm-gnode__stat` styles cloned
+   * by the `NodeCounter` renderer.
    */
   viewContributions: {
     count: {
       slot: "card.footer.right",
-      icon: "\u{1F517}",
+      icon: "pi-link",
       label: "urls",
       emitWhenEmpty: false
     }
@@ -1040,25 +1013,11 @@ var markdownLinkExtractor = {
   pluginId: "core",
   kind: "extractor",
   version: "1.0.0",
-  description: "Detects [text](path) markdown links and emits one references link per resolved file path.",
+  description: "Detects markdown links (`[text](path)`) in a node's body and turns each one into an arrow (edge) between nodes in the graph.",
   stability: "stable",
   emitsLinkKinds: ["references"],
   defaultConfidence: "high",
   scope: "body",
-  /**
-   * View contribution — surface the distinct-link count as a counter
-   * chip in `card.footer.left.counter`, alongside the at-directive
-   * (`@`) and slash (`/`) counters. `emitWhenEmpty: false` keeps
-   * unrelated nodes (no markdown links) free of a `📎 0` decoration.
-   */
-  viewContributions: {
-    count: {
-      slot: "card.footer.left.counter",
-      icon: "\u{1F4CE}",
-      label: "links",
-      emitWhenEmpty: false
-    }
-  },
   extract(ctx) {
     const seen = /* @__PURE__ */ new Set();
     const lineStarts = computeLineStarts2(ctx.body);
@@ -1084,9 +1043,6 @@ var markdownLinkExtractor = {
       };
       ctx.emitLink(link2);
     }
-    if (seen.size > 0) {
-      ctx.emitContribution("count", { value: seen.size });
-    }
   }
 };
 function resolveTarget(sourceDir, raw) {
@@ -1117,6 +1073,107 @@ function lineFor2(lineStarts, offset) {
   return lo + 1;
 }
 
+// built-in-plugins/extractors/stability/index.ts
+var ID6 = "stability";
+var EXPERIMENTAL_TOOLTIP = "Experimental \u2014 API may change";
+var DEPRECATED_TOOLTIP = "Deprecated \u2014 avoid in new code";
+var stabilityExtractor = {
+  id: ID6,
+  pluginId: "core",
+  kind: "extractor",
+  version: "1.0.0",
+  description: "Shows an icon chip on the card footer when the node is marked `stability: experimental` or `stability: deprecated` (read from the sidecar `annotations:` block, with legacy `metadata:` frontmatter as fallback).",
+  stability: "stable",
+  emitsLinkKinds: [],
+  defaultConfidence: "high",
+  scope: "frontmatter",
+  viewContributions: {
+    experimental: {
+      slot: "card.footer.right",
+      icon: "fa-solid fa-flask",
+      label: "experimental",
+      emitWhenEmpty: false
+    },
+    deprecated: {
+      slot: "card.footer.right",
+      icon: "pi-ban",
+      label: "deprecated",
+      emitWhenEmpty: false
+    }
+  },
+  extract(ctx) {
+    const stability = readStability(ctx);
+    if (stability === "experimental") {
+      ctx.emitContribution("experimental", {
+        value: 0,
+        tooltip: EXPERIMENTAL_TOOLTIP
+      });
+    } else if (stability === "deprecated") {
+      ctx.emitContribution("deprecated", {
+        value: 0,
+        tooltip: DEPRECATED_TOOLTIP,
+        severity: "warn"
+      });
+    }
+  }
+};
+function readStability(ctx) {
+  const ann = ctx.node.sidecar?.annotations;
+  const fromAnn = ann?.["stability"];
+  if (isStability(fromAnn)) return fromAnn;
+  const meta = ctx.frontmatter["metadata"];
+  if (meta && typeof meta === "object" && !Array.isArray(meta)) {
+    const legacy = meta["stability"];
+    if (isStability(legacy)) return legacy;
+  }
+  return null;
+}
+function isStability(value) {
+  return value === "experimental" || value === "deprecated" || value === "stable";
+}
+
+// built-in-plugins/extractors/tools-count/index.ts
+var ID7 = "tools-count";
+var TOOLTIP_MAX = 255;
+var toolsCountExtractor = {
+  id: ID7,
+  pluginId: "core",
+  kind: "extractor",
+  version: "1.0.0",
+  description: "Counts the tools an agent declares in its frontmatter and shows the total as a wrench chip on the agent card.",
+  stability: "stable",
+  emitsLinkKinds: [],
+  defaultConfidence: "high",
+  scope: "frontmatter",
+  applicableKinds: ["agent"],
+  viewContributions: {
+    count: {
+      slot: "card.footer.left",
+      icon: "pi-wrench",
+      label: "tools",
+      emitWhenEmpty: false
+    }
+  },
+  extract(ctx) {
+    const raw = ctx.frontmatter["tools"];
+    if (!Array.isArray(raw)) return;
+    const names = [];
+    for (const t of raw) {
+      if (typeof t === "string" && t.length > 0) names.push(t);
+    }
+    if (names.length === 0) return;
+    ctx.emitContribution("count", {
+      value: names.length,
+      tooltip: buildTooltip(names)
+    });
+  }
+};
+function buildTooltip(names) {
+  const joined = names.join(" \xB7 ");
+  if (joined.length <= TOOLTIP_MAX) return joined;
+  return `${joined.slice(0, TOOLTIP_MAX - 1)}\u2026`;
+}
+
 // built-in-plugins/i18n/trigger-collision.texts.ts
 var TRIGGER_COLLISION_TEXTS = {
   /**
@@ -1143,19 +1200,19 @@ var TRIGGER_COLLISION_TEXTS = {
 };
 
 // built-in-plugins/analyzers/trigger-collision/index.ts
-var ID6 = "trigger-collision";
+var ID8 = "trigger-collision";
 var ADVERTISING_KINDS = /* @__PURE__ */ new Set([
   "command",
   "skill",
   "agent"
 ]);
 var triggerCollisionAnalyzer = {
-  id: ID6,
+  id: ID8,
   pluginId: "core",
   kind: "analyzer",
   mode: "deterministic",
   version: "1.0.0",
-  description: "Flags trigger names (/command, @agent) claimed by multiple distinct nodes \u2014 by advertisement (frontmatter.name) or by invocation.",
+  description: "Flags when two or more nodes claim the same `/command` or `@agent` name \u2014 either by their `name` field or by how they are invoked elsewhere.",
   stability: "stable",
   // Two claim-collection passes (advertisement + invocation) feeding
   // the bucket map. Per-bucket analysis lives in `analyzeTriggerBucket`.
@@ -1250,7 +1307,7 @@ function analyzeTriggerBucket(normalized, claims) {
     part: parts[0]
   });
   return {
-    analyzerId: ID6,
+    analyzerId: ID8,
     severity: "error",
     nodeIds,
     message,
@@ -1268,35 +1325,79 @@ import { resolve } from "path";
 // built-in-plugins/i18n/broken-ref.texts.ts
 var BROKEN_REF_TEXTS = {
   /** `Broken <kind> reference from <source> → <target>` */
-  message: "Broken {{kind}} reference from {{source}} \u2192 {{target}}"
+  message: "Broken {{kind}} reference from {{source}} \u2192 {{target}}",
+  // Tooltips for the per-node view-contribution badges. Singular vs
+  // plural keeps the count grammar correct without a sub-template.
+  alertTooltipSingle: "This node has a broken reference. Open the inspector for details.",
+  alertTooltipMany: "This node has {{count}} broken references. Open the inspector for details."
 };
 
 // built-in-plugins/analyzers/broken-ref/index.ts
-var ID7 = "broken-ref";
+var ID9 = "broken-ref";
 var brokenRefAnalyzer = {
-  id: ID7,
+  id: ID9,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Flags links whose target cannot be resolved to a scanned node.",
+  description: "Flags arrows pointing at a node that is not part of the current scan (broken link).",
   stability: "stable",
   mode: "deterministic",
+  viewContributions: {
+    // Corner badge on the graph card; count omitted when there is a
+    // single broken ref (avoids a noisy "icon + 1" chip).
+    alert: {
+      slot: "graph.node.alert",
+      icon: "fa-solid fa-circle-xmark",
+      emitWhenEmpty: false
+    },
+    // Footer chip on the card. `_counter` shape — `value` always shows,
+    // so the operator sees "how many" at a glance. Renders OUTLINED
+    // (`fa-regular`) so the corner alert (filled, attention-grabbing)
+    // and the footer chip (quieter, paired with a number) read as two
+    // beats of the same signal rather than two identical glyphs.
+    chip: {
+      slot: "card.footer.right",
+      icon: "fa-regular fa-circle-xmark",
+      emitWhenEmpty: false
+    }
+  },
+  // The resolver, the reference-paths escape hatch, the per-source
+  // aggregation, and the dual-slot emit (with single/plural tooltip and
+  // optional count) all live in one flow because they share the per-link
+  // loop. Splitting them would re-walk `ctx.links` three times.
+  // eslint-disable-next-line complexity
   evaluate(ctx) {
     const byPath3 = new Set(ctx.nodes.map((n) => n.path));
     const byNormalizedName = indexByNormalizedName(ctx.nodes);
     const refIndex = ctx.referenceablePaths && ctx.referenceablePaths.size > 0 && ctx.cwd ? { paths: ctx.referenceablePaths, cwd: ctx.cwd } : null;
     const issues = [];
+    const perNode = /* @__PURE__ */ new Map();
     for (const link2 of ctx.links) {
       if (isResolved(link2, byPath3, byNormalizedName)) continue;
       if (refIndex && resolvesViaReferencePaths(link2, refIndex)) continue;
       issues.push(buildIssue(link2));
+      perNode.set(link2.source, (perNode.get(link2.source) ?? 0) + 1);
+    }
+    for (const [nodePath, count] of perNode) {
+      const tooltip = count === 1 ? BROKEN_REF_TEXTS.alertTooltipSingle : tx(BROKEN_REF_TEXTS.alertTooltipMany, { count });
+      const capped = Math.min(count, 99);
+      ctx.emitContribution(nodePath, "alert", {
+        icon: "fa-solid fa-circle-xmark",
+        severity: "danger",
+        tooltip
+      });
+      ctx.emitContribution(nodePath, "chip", {
+        value: capped,
+        severity: "danger",
+        tooltip
+      });
     }
     return issues;
   }
 };
 function buildIssue(link2) {
   return {
-    analyzerId: ID7,
+    analyzerId: ID9,
     severity: "warn",
     nodeIds: [link2.source],
     message: tx(BROKEN_REF_TEXTS.message, {
@@ -1350,13 +1451,13 @@ var SUPERSEDED_TEXTS = {
 };
 
 // built-in-plugins/analyzers/superseded/index.ts
-var ID8 = "superseded";
+var ID10 = "superseded";
 var supersededAnalyzer = {
-  id: ID8,
+  id: ID10,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Surfaces nodes whose sidecar annotations declare a supersededBy replacement.",
+  description: "Marks nodes that have been replaced by a newer one (the sidecar declares `supersededBy`).",
   stability: "stable",
   mode: "deterministic",
   evaluate(ctx) {
@@ -1365,7 +1466,7 @@ var supersededAnalyzer = {
       const supersededBy = pickSupersededBy(node);
       if (supersededBy === null) continue;
       issues.push({
-        analyzerId: ID8,
+        analyzerId: ID10,
         severity: "info",
         nodeIds: [node.path],
         message: tx(SUPERSEDED_TEXTS.message, {
@@ -1395,13 +1496,13 @@ var LINK_CONFLICT_TEXTS = {
 };
 
 // built-in-plugins/analyzers/link-conflict/index.ts
-var ID9 = "link-conflict";
+var ID11 = "link-conflict";
 var linkConflictAnalyzer = {
-  id: ID9,
+  id: ID11,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Flags (source, target) pairs where detectors disagree on the link kind.",
+  description: 'Flags when two extractors disagree on the meaning of the same arrow (e.g. one says "references", the other says "invokes").',
   stability: "stable",
   mode: "deterministic",
   // Bucket links by (source, target), then per-bucket detect distinct
@@ -1446,7 +1547,7 @@ var linkConflictAnalyzer = {
       const [source, target] = key.split("\0");
       const kindList = variants.map((v) => v.kind).join(" / ");
       issues.push({
-        analyzerId: ID9,
+        analyzerId: ID11,
         severity: "warn",
         nodeIds: [source, target],
         message: tx(LINK_CONFLICT_TEXTS.message, {
@@ -1478,19 +1579,44 @@ var ANNOTATION_STALE_TEXTS = {
   /** frontmatter changed since last bump */
   frontmatterDrift: "{{path}}: sidecar `.sm` is stale (frontmatter changed since last bump).",
   /** both body and frontmatter changed */
-  bothDrift: "{{path}}: sidecar `.sm` is stale (body and frontmatter changed since last bump)."
+  bothDrift: "{{path}}: sidecar `.sm` is stale (body and frontmatter changed since last bump).",
+  // Tooltips for the `card.footer.right` clock chip emitted alongside
+  // the issue. Lists only the drifted face(s) — in-sync faces are
+  // omitted so the operator immediately sees what's modified without
+  // scanning prose. No `{{path}}` placeholder — the chip already sits
+  // on the affected node. The hint `sm bump <path>` keeps `<path>` as
+  // a literal placeholder the operator substitutes.
+  bodyTooltip: "Sidecar drift since last bump:\n  \u2022 body\nRun `sm bump <path>` to refresh.",
+  frontmatterTooltip: "Sidecar drift since last bump:\n  \u2022 frontmatter\nRun `sm bump <path>` to refresh.",
+  bothTooltip: "Sidecar drift since last bump:\n  \u2022 body\n  \u2022 frontmatter\nRun `sm bump <path>` to refresh."
 };
 
 // built-in-plugins/analyzers/annotation-stale/index.ts
-var ID10 = "annotation-stale";
+var ID12 = "annotation-stale";
 var annotationStaleAnalyzer = {
-  id: ID10,
+  id: ID12,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Surfaces nodes whose co-located .sm sidecar is stale relative to current hashes.",
+  description: "Marks nodes whose `.sm` sidecar is out of date \u2014 the `.md` content changed since the last sidecar bump. Surfaces an Issue (panel) plus a `pi-clock` chip in the card footer.",
   stability: "stable",
   mode: "deterministic",
+  viewContributions: {
+    // A `pi-clock` chip in the footer-right cluster so the operator
+    // spots drift in the list / inspector view (and on the graph card
+    // body). Emitted with `value: 0` and `emitWhenEmpty: true` so the
+    // renderer treats it as icon-only — drift severity is binary at
+    // this surface (the tooltip carries the per-face detail body /
+    // frontmatter / both). The corner badge on `graph.node.alert` was
+    // dropped on purpose: a tooltip on the footer chip is enough, and
+    // the corner badge stacked on top of broken-ref / unknown-field
+    // alerts produced visual noise.
+    staleIcon: {
+      slot: "card.footer.right",
+      icon: "pi-clock",
+      emitWhenEmpty: true
+    }
+  },
   evaluate(ctx) {
     const issues = [];
     for (const node of ctx.nodes) {
@@ -1499,16 +1625,31 @@ var annotationStaleAnalyzer = {
       if (status === "fresh") continue;
       const message = status === "stale-body" ? tx(ANNOTATION_STALE_TEXTS.bodyDrift, { path: node.path }) : status === "stale-frontmatter" ? tx(ANNOTATION_STALE_TEXTS.frontmatterDrift, { path: node.path }) : tx(ANNOTATION_STALE_TEXTS.bothDrift, { path: node.path });
       issues.push({
-        analyzerId: ID10,
+        analyzerId: ID12,
         severity: "warn",
         nodeIds: [node.path],
         message,
         data: { status }
       });
+      ctx.emitContribution(node.path, "staleIcon", {
+        value: 0,
+        severity: "warn",
+        tooltip: tooltipFor(status)
+      });
     }
     return issues;
   }
 };
+function tooltipFor(status) {
+  switch (status) {
+    case "stale-body":
+      return ANNOTATION_STALE_TEXTS.bodyTooltip;
+    case "stale-frontmatter":
+      return ANNOTATION_STALE_TEXTS.frontmatterTooltip;
+    case "stale-both":
+      return ANNOTATION_STALE_TEXTS.bothTooltip;
+  }
+}
 
 // built-in-plugins/i18n/annotation-orphan.texts.ts
 var ANNOTATION_ORPHAN_TEXTS = {
@@ -1517,13 +1658,13 @@ var ANNOTATION_ORPHAN_TEXTS = {
 };
 
 // built-in-plugins/analyzers/annotation-orphan/index.ts
-var ID11 = "annotation-orphan";
+var ID13 = "annotation-orphan";
 var annotationOrphanAnalyzer = {
-  id: ID11,
+  id: ID13,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Flags .sm sidecars whose accompanying .md node is missing on disk.",
+  description: "Flags `.sm` sidecars whose matching `.md` file no longer exists on disk.",
   stability: "stable",
   mode: "deterministic",
   evaluate(ctx) {
@@ -1533,7 +1674,7 @@ var annotationOrphanAnalyzer = {
     for (const orphan of orphans) {
       const expectedMdRelative = orphan.relativePath.endsWith(".sm") ? `${orphan.relativePath.slice(0, -".sm".length)}.md` : `${orphan.relativePath}.md`;
       issues.push({
-        analyzerId: ID11,
+        analyzerId: ID13,
         severity: "warn",
         nodeIds: [expectedMdRelative],
         message: tx(ANNOTATION_ORPHAN_TEXTS.message, {
@@ -1560,13 +1701,13 @@ var JOB_ORPHAN_FILE_TEXTS = {
 };
 
 // built-in-plugins/analyzers/job-orphan-file/index.ts
-var ID12 = "job-orphan-file";
+var ID14 = "job-orphan-file";
 var jobOrphanFileAnalyzer = {
-  id: ID12,
+  id: ID14,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Flags MD files under .skill-map/jobs/ that no state_jobs row references. Cleanup via `sm job prune --orphan-files`.",
+  description: "Flags leftover job result files in `.skill-map/jobs/` that no live job references. Cleanup via `sm job prune --orphan-files`.",
   stability: "stable",
   mode: "deterministic",
   evaluate(ctx) {
@@ -1575,7 +1716,7 @@ var jobOrphanFileAnalyzer = {
     const issues = [];
     for (const filePath of orphans) {
       issues.push({
-        analyzerId: ID12,
+        analyzerId: ID14,
         severity: "warn",
         nodeIds: [filePath],
         message: tx(JOB_ORPHAN_FILE_TEXTS.message, { filePath }),
@@ -1606,20 +1747,48 @@ var UNKNOWN_FIELD_TEXTS = {
   /** Top-level key is neither reserved, nor a registered plugin namespace, nor a registered root key. */
   unknownRootKey: "{{path}}: sidecar declares unknown top-level key '{{key}}' \u2014 not a reserved block, not a registered plugin namespace, not a registered root contribution.",
   /** Value under a registered plugin namespace fails the contributed schema. */
-  pluginNamespaceInvalid: "{{path}}: sidecar block '{{pluginId}}.{{key}}' fails the schema contributed by plugin '{{pluginId}}' \u2014 {{errors}}."
+  pluginNamespaceInvalid: "{{path}}: sidecar block '{{pluginId}}.{{key}}' fails the schema contributed by plugin '{{pluginId}}' \u2014 {{errors}}.",
+  // Tooltips for the per-node view-contribution badges. Singular vs
+  // plural keeps the count grammar correct without a sub-template.
+  alertTooltipSingle: "This node has 1 unknown field in its sidecar. Open the inspector for details.",
+  alertTooltipMany: "This node has {{count}} unknown fields in its sidecar. Open the inspector for details."
 };
 
 // built-in-plugins/analyzers/unknown-field/index.ts
-var ID13 = "unknown-field";
+var ID15 = "unknown-field";
 var RESERVED_ROOT_BLOCKS = /* @__PURE__ */ new Set(["identity", "annotations", "settings", "audit"]);
 var unknownFieldAnalyzer = {
-  id: ID13,
+  id: ID15,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Tier-1 typo guard. Warns on unknown keys inside annotations: and at the sidecar root, and on plugin-namespaced values that fail their contributed schema.",
+  description: "Catches typos and unrecognized keys inside `.sm` sidecars, including plugin-contributed annotation fields that fail their own schema.",
   stability: "stable",
   mode: "deterministic",
+  viewContributions: {
+    // Corner badge on the graph card; count omitted when there is a
+    // single unknown field (avoids a noisy "icon + 1" chip).
+    alert: {
+      slot: "graph.node.alert",
+      // Filled warning triangle on the corner — matches the broken-ref
+      // alert's "attention-grabbing solid" pattern; the footer chip
+      // below stays outlined for the quieter counter pairing.
+      icon: "fa-solid fa-triangle-exclamation",
+      emitWhenEmpty: false
+    },
+    // Footer chip on the card — `_counter` shape but rendered icon-only
+    // (the analyzer emits `value: 0` so NodeCounter hides the number
+    // and only the glyph shows). PrimeIcons `pi-question-circle` so the
+    // visual weight matches `annotation-stale`'s `pi-clock` chip
+    // sitting next to it on the same footer row. `emitWhenEmpty: true`
+    // is required: with `value: 0` the slot treats the payload as
+    // empty, so the manifest has to opt in to keep the emission.
+    chip: {
+      slot: "card.footer.right",
+      icon: "pi-question-circle",
+      emitWhenEmpty: true
+    }
+  },
   // eslint-disable-next-line complexity
   evaluate(ctx) {
     const sidecarRoots = ctx.sidecarRoots;
@@ -1630,6 +1799,10 @@ var unknownFieldAnalyzer = {
     const rootKeys = indexRootContributions(contributions);
     const knownPluginIds = collectPluginIds(contributions);
     const issues = [];
+    const perNode = /* @__PURE__ */ new Map();
+    const bump2 = (nodePath) => {
+      perNode.set(nodePath, (perNode.get(nodePath) ?? 0) + 1);
+    };
     for (const node of ctx.nodes) {
       const root = sidecarRoots.get(node.path);
       if (!root) continue;
@@ -1638,7 +1811,7 @@ var unknownFieldAnalyzer = {
         for (const key of Object.keys(annotations)) {
           if (!knownAnnotationKeys.has(key)) {
             issues.push({
-              analyzerId: ID13,
+              analyzerId: ID15,
               severity: "warn",
               nodeIds: [node.path],
               message: tx(UNKNOWN_FIELD_TEXTS.unknownAnnotationKey, {
@@ -1647,6 +1820,7 @@ var unknownFieldAnalyzer = {
               }),
               data: { surface: "annotations", key }
             });
+            bump2(node.path);
           }
         }
       }
@@ -1664,7 +1838,7 @@ var unknownFieldAnalyzer = {
             if (validator(value)) continue;
             const errors = (validator.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message ?? e.keyword}`).join("; ");
             issues.push({
-              analyzerId: ID13,
+              analyzerId: ID15,
               severity: "warn",
               nodeIds: [node.path],
               message: tx(UNKNOWN_FIELD_TEXTS.pluginNamespaceInvalid, {
@@ -1675,11 +1849,12 @@ var unknownFieldAnalyzer = {
               }),
               data: { surface: "plugin-namespace", pluginId: key, key: contribKey }
             });
+            bump2(node.path);
           }
           continue;
         }
         issues.push({
-          analyzerId: ID13,
+          analyzerId: ID15,
           severity: "warn",
           nodeIds: [node.path],
           message: tx(UNKNOWN_FIELD_TEXTS.unknownRootKey, {
@@ -1688,8 +1863,22 @@ var unknownFieldAnalyzer = {
           }),
           data: { surface: "root", key }
         });
+        bump2(node.path);
       }
     }
+    for (const [nodePath, count] of perNode) {
+      const tooltip = count === 1 ? UNKNOWN_FIELD_TEXTS.alertTooltipSingle : tx(UNKNOWN_FIELD_TEXTS.alertTooltipMany, { count });
+      ctx.emitContribution(nodePath, "alert", {
+        icon: "fa-solid fa-triangle-exclamation",
+        severity: "warn",
+        tooltip
+      });
+      ctx.emitContribution(nodePath, "chip", {
+        value: 0,
+        severity: "warn",
+        tooltip
+      });
+    }
     return issues;
   }
 };
@@ -1737,11 +1926,11 @@ function collectPluginIds(contributions) {
 }
 
 // built-in-plugins/analyzers/unknown-slot/index.ts
-var ID14 = "unknown-slot";
+var ID16 = "unknown-slot";
 var KNOWN_SLOTS = /* @__PURE__ */ new Set([
   "card.title.right",
   "card.subtitle.left",
-  "card.footer.left.counter",
+  "card.footer.left",
   "card.footer.right",
   "graph.node.alert",
   "inspector.header.badge.counter",
@@ -1752,14 +1941,14 @@ var KNOWN_SLOTS = /* @__PURE__ */ new Set([
   "inspector.body.panel.key-values",
   "inspector.body.panel.link-list",
   "inspector.body.panel.markdown",
-  "topbar.actions.indicator"
+  "topbar.nav.start"
 ]);
 var unknownSlotAnalyzer = {
-  id: ID14,
+  id: ID16,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Warns on plugin view contributions that reference a slot not in the current closed catalog.",
+  description: "Warns when a plugin tries to render in a UI position that does not exist (typo or removed in a newer skill-map version).",
   stability: "stable",
   mode: "deterministic",
   evaluate(ctx) {
@@ -1770,7 +1959,7 @@ var unknownSlotAnalyzer = {
       if (KNOWN_SLOTS.has(c.slot)) continue;
       const qualified = `${c.pluginId}/${c.extensionId}/${c.contributionId}`;
       issues.push({
-        analyzerId: ID14,
+        analyzerId: ID16,
         severity: "warn",
         nodeIds: [],
         message: `Plugin ${qualified} declares unknown slot '${c.slot}'. Run \`sm plugins upgrade ${c.pluginId}\` or update the plugin to a slot in the current catalog (\`sm plugins slots list\`).`,
@@ -1787,13 +1976,13 @@ var unknownSlotAnalyzer = {
 };
 
 // built-in-plugins/analyzers/contribution-orphan/index.ts
-var ID15 = "contribution-orphan";
+var ID17 = "contribution-orphan";
 var contributionOrphanAnalyzer = {
-  id: ID15,
+  id: ID17,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "Warns when scan_contributions rows reference nodes that no longer exist (post-rename heuristic miss).",
+  description: "Warns when a plugin's per-node chips reference a node that was renamed or deleted in the latest scan.",
   stability: "experimental",
   mode: "deterministic",
   evaluate(_ctx) {
@@ -1829,14 +2018,14 @@ var ASCII_FORMATTER_TEXTS = {
 };
 
 // built-in-plugins/formatters/ascii/index.ts
-var ID16 = "ascii";
+var ID18 = "ascii";
 var KIND_ORDER = ["agent", "command", "skill", "markdown"];
 var asciiFormatter = {
-  id: ID16,
+  id: ID18,
   pluginId: "core",
   kind: "formatter",
   version: "1.0.0",
-  description: "Plain-text graph dump, grouped by node kind then links then issues.",
+  description: "Plain-text dump of the scan grouped by kind, then arrows, then issues. Used by `sm scan --format=ascii`.",
   stability: "stable",
   formatId: "ascii",
   // ASCII tree formatter — header + per-kind sections + per-issue
@@ -2005,7 +2194,7 @@ function buildSchemaValidators() {
   const KNOWN_SLOTS2 = /* @__PURE__ */ new Set([
     "card.title.right",
     "card.subtitle.left",
-    "card.footer.left.counter",
+    "card.footer.left",
     "card.footer.right",
     "graph.node.alert",
     "inspector.header.badge.counter",
@@ -2016,7 +2205,7 @@ function buildSchemaValidators() {
     "inspector.body.panel.key-values",
     "inspector.body.panel.link-list",
     "inspector.body.panel.markdown",
-    "topbar.actions.indicator"
+    "topbar.nav.start"
   ]);
   function getContributionValidator(slot) {
     if (!KNOWN_SLOTS2.has(slot)) return null;
@@ -2139,9 +2328,9 @@ var VALIDATE_ALL_TEXTS = {
 };
 
 // built-in-plugins/analyzers/validate-all/index.ts
-var ID17 = "validate-all";
+var ID19 = "validate-all";
 var validateAllAnalyzer = {
-  id: ID17,
+  id: ID19,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
@@ -2164,7 +2353,7 @@ function collectNodeFindings(v, node, out) {
   const result = v.validate("node", toNodeForSchema(node));
   if (result.ok) return;
   out.push({
-    analyzerId: ID17,
+    analyzerId: ID19,
     severity: "error",
     nodeIds: [node.path],
     message: tx(VALIDATE_ALL_TEXTS.nodeFailure, {
@@ -2178,7 +2367,7 @@ function collectLinkFindings(v, link2, out) {
   const result = v.validate("link", toLinkForSchema(link2));
   if (result.ok) return;
   out.push({
-    analyzerId: ID17,
+    analyzerId: ID19,
     severity: "error",
     nodeIds: [link2.source],
     message: tx(VALIDATE_ALL_TEXTS.linkFailure, {
@@ -2219,19 +2408,67 @@ function toLinkForSchema(link2) {
 }
 
 // built-in-plugins/analyzers/link-counts/index.ts
-var ID18 = "link-counts";
+var ID20 = "link-counts";
 var linkCountsAnalyzer = {
-  id: ID18,
+  id: ID20,
   pluginId: "core",
   kind: "analyzer",
   version: "1.0.0",
-  description: "No-op placeholder \u2014 view contributions paused (see file header).",
+  description: "Counts incoming and outgoing links per node and surfaces them as paired footer chips.",
   stability: "stable",
   mode: "deterministic",
-  evaluate(_ctx) {
+  viewContributions: {
+    linksIn: {
+      slot: "card.footer.left",
+      icon: "pi-arrow-up",
+      label: "incoming links",
+      emitWhenEmpty: false
+    },
+    linksOut: {
+      slot: "card.footer.left",
+      icon: "pi-arrow-down",
+      label: "outgoing links",
+      emitWhenEmpty: false
+    }
+  },
+  evaluate(ctx) {
+    const perTarget = /* @__PURE__ */ new Map();
+    const perSource = /* @__PURE__ */ new Map();
+    for (const link2 of ctx.links) {
+      bump(perTarget, link2.target, link2.kind);
+      bump(perSource, link2.source, link2.kind);
+    }
+    for (const node of ctx.nodes) {
+      emitChip(ctx, node.path, "linksIn", perTarget.get(node.path));
+      emitChip(ctx, node.path, "linksOut", perSource.get(node.path));
+    }
     return [];
   }
 };
+function bump(map, key, kind) {
+  let byKind = map.get(key);
+  if (!byKind) {
+    byKind = /* @__PURE__ */ new Map();
+    map.set(key, byKind);
+  }
+  byKind.set(kind, (byKind.get(kind) ?? 0) + 1);
+}
+function emitChip(ctx, nodePath, contributionId, byKind) {
+  if (!byKind) return;
+  let total = 0;
+  for (const n of byKind.values()) total += n;
+  if (total === 0) return;
+  const capped = Math.min(total, 99);
+  const direction = contributionId === "linksIn" ? "in" : "out";
+  ctx.emitContribution(nodePath, contributionId, {
+    value: capped,
+    tooltip: formatBreakdown(byKind, direction)
+  });
+}
+function formatBreakdown(byKind, direction) {
+  const lines = [...byKind.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([kind, n]) => `${kind}: ${n}`);
+  return [direction, ...lines].join("\n");
+}
 
 // kernel/sidecar/parse.ts
 import { existsSync, readFileSync as readFileSync3 } from "fs";
@@ -2335,14 +2572,14 @@ function resolveSpecRoot2() {
 }
 
 // built-in-plugins/actions/bump/index.ts
-var ID19 = "bump";
+var ID21 = "bump";
 var PLUGIN_ID = "core";
 var bumpAction = {
-  id: ID19,
+  id: ID21,
   pluginId: PLUGIN_ID,
   kind: "action",
   version: "1.0.0",
-  description: "Increments the sidecar `annotations.version`, refreshes the identity hashes, and stamps the audit block. Refuses on a fresh (non-stale) node unless `force: true` is passed.",
+  description: "Marks a node as updated \u2014 bumps its version, refreshes the sidecar hashes, and records the timestamp. Refuses on a fresh node unless `force: true` is passed.",
   stability: "stable",
   mode: "deterministic",
   reportSchemaRef: "https://skill-map.dev/spec/v0/bump-report.schema.json",
@@ -3762,7 +3999,7 @@ function rowToIssue(row) {
   return issue;
 }
 async function loadExtractorRuns(db) {
-  const rows = await db.selectFrom("scan_extractor_runs").select(["nodePath", "extractorId", "bodyHashAtRun"]).execute();
+  const rows = await db.selectFrom("scan_extractor_runs").select(["nodePath", "extractorId", "bodyHashAtRun", "sidecarAnnotationsHashAtRun"]).execute();
   const result = /* @__PURE__ */ new Map();
   for (const row of rows) {
     let perNode = result.get(row.nodePath);
@@ -3770,7 +4007,10 @@ async function loadExtractorRuns(db) {
       perNode = /* @__PURE__ */ new Map();
       result.set(row.nodePath, perNode);
     }
-    perNode.set(row.extractorId, row.bodyHashAtRun);
+    perNode.set(row.extractorId, {
+      bodyHash: row.bodyHashAtRun,
+      sidecarAnnotationsHash: row.sidecarAnnotationsHashAtRun
+    });
   }
   return result;
 }
@@ -3837,14 +4077,14 @@ async function replaceAllScanContributions(trx, contributions, livePaths = /* @_
   if (freshlyRunTuples.size > 0) {
     const bufferKeys = /* @__PURE__ */ new Set();
     for (const c of contributions) {
-      bufferKeys.add(`${c.pluginId}/${c.extensionId}/${c.nodePath}/${c.contributionId}`);
+      bufferKeys.add(`${c.pluginId}\0${c.extensionId}\0${c.nodePath}\0${c.contributionId}`);
     }
     const tuplesByPluginExt = /* @__PURE__ */ new Map();
     for (const tuple of freshlyRunTuples) {
-      const lastSlash = tuple.lastIndexOf("/");
-      if (lastSlash < 0) continue;
-      const pe = tuple.slice(0, lastSlash);
-      const node = tuple.slice(lastSlash + 1);
+      const parts = tuple.split("\0");
+      if (parts.length !== 3) continue;
+      const [pluginId, extensionId, node] = parts;
+      const pe = `${pluginId}\0${extensionId}`;
       let nodes = tuplesByPluginExt.get(pe);
       if (!nodes) {
         nodes = /* @__PURE__ */ new Set();
@@ -3853,15 +4093,15 @@ async function replaceAllScanContributions(trx, contributions, livePaths = /* @_
       nodes.add(node);
     }
     for (const [pe, nodes] of tuplesByPluginExt) {
-      const slash = pe.indexOf("/");
-      if (slash < 0) continue;
-      const pluginId = pe.slice(0, slash);
-      const extensionId = pe.slice(slash + 1);
+      const sep6 = pe.indexOf("\0");
+      if (sep6 < 0) continue;
+      const pluginId = pe.slice(0, sep6);
+      const extensionId = pe.slice(sep6 + 1);
       const nodeArr = [...nodes];
       const candidates = await trx.selectFrom("scan_contributions").select(["nodePath", "contributionId"]).where("pluginId", "=", pluginId).where("extensionId", "=", extensionId).where("nodePath", "in", nodeArr).execute();
       const stale = [];
       for (const row of candidates) {
-        const key = `${pluginId}/${extensionId}/${row.nodePath}/${row.contributionId}`;
+        const key = `${pluginId}\0${extensionId}\0${row.nodePath}\0${row.contributionId}`;
         if (!bufferKeys.has(key)) stale.push(row);
       }
       for (const s of stale) {
@@ -3908,6 +4148,14 @@ async function loadContributionLookup(db, pluginId, contributionId, nodePath, ex
   const rows = await query.orderBy("extensionId", "asc").execute();
   return rows.map(rowToContribution);
 }
+async function purgeContributionsByPlugin(db, pluginId, extensionId) {
+  let query = db.deleteFrom("scan_contributions").where("pluginId", "=", pluginId);
+  if (extensionId !== void 0) {
+    query = query.where("extensionId", "=", extensionId);
+  }
+  const result = await query.executeTakeFirst();
+  return Number(result.numDeletedRows ?? 0n);
+}
 function rowToContribution(row) {
   let payload;
   try {
@@ -4174,7 +4422,8 @@ function extractorRunToRow(record) {
     nodePath: record.nodePath,
     extractorId: record.extractorId,
     bodyHashAtRun: record.bodyHashAtRun,
-    ranAt: record.ranAt
+    ranAt: record.ranAt,
+    sidecarAnnotationsHashAtRun: record.sidecarAnnotationsHashAtRun
   };
 }
 function enrichmentToRow(record) {
@@ -4349,7 +4598,8 @@ var SqliteStorageAdapter = class {
     this.contributions = {
       listForNode: (nodePath) => loadContributionsForNode(this.db, nodePath),
       listForPaths: (paths) => loadContributionsForPaths(this.db, paths),
-      lookup: (pluginId, contributionId, nodePath, extensionId) => loadContributionLookup(this.db, pluginId, contributionId, nodePath, extensionId)
+      lookup: (pluginId, contributionId, nodePath, extensionId) => loadContributionLookup(this.db, pluginId, contributionId, nodePath, extensionId),
+      purgeByPlugin: (pluginId, extensionId) => purgeContributionsByPlugin(this.db, pluginId, extensionId)
     };
     this.tags = {
       listForNode: (nodePath) => loadTagsForNode(this.db, nodePath),
@@ -4636,7 +4886,8 @@ var CONFIG_LOADER_TEXTS = {
   invalidJson: "[config:{{layer}}] invalid JSON in {{path}}: {{message}}",
   expectedObject: "[config:{{layer}}] expected a JSON object, got {{type}}; ignored",
   unknownKey: "[config:{{layer}}] unknown key {{key}} ignored",
-  invalidValue: "[config:{{layer}}] invalid value at {{path}}: {{message}}"
+  invalidValue: "[config:{{layer}}] invalid value at {{path}}: {{message}}",
+  projectLocalOnlyStripped: "[config:{{layer}}] key {{key}} is project-local only; stripped from the committed project layer. Move it to .skill-map/settings.local.json (gitignored, per-checkout)."
 };
 
 // kernel/util/skill-map-paths.ts
@@ -4701,6 +4952,7 @@ function kernelLocalSettingsPath(scopeRoot) {
 var defaults_default = {
   schemaVersion: 1,
   autoMigrate: true,
+  allowEditSmFiles: false,
   tokenizer: "cl100k_base",
   providers: [],
   roots: [],
@@ -4738,6 +4990,12 @@ var defaults_default = {
 };
 
 // kernel/config/loader.ts
+var PROJECT_LOCAL_ONLY_KEYS = /* @__PURE__ */ new Set([
+  "allowEditSmFiles",
+  "scan.includeHome",
+  "scan.extraRoots",
+  "scan.referencePaths"
+]);
 var DEFAULTS = defaults_default;
 function loadConfig(opts) {
   const cwd = opts.cwd;
@@ -4763,6 +5021,9 @@ function loadConfig(opts) {
     const partial = readJsonSafe(path, layer, warnings, strict);
     if (partial === null) continue;
     const cleaned = validateAndStrip(validators, partial, layer, warnings, strict);
+    if (layer === "project") {
+      stripProjectLocalOnlyKeys(cleaned, warnings, strict);
+    }
     effective = deepMerge(effective, cleaned);
     recordSources("", cleaned, sources, layer);
   }
@@ -4853,6 +5114,30 @@ function deleteAtPath(root, parentPath, key) {
   }
   if (isPlainObject2(cur)) delete cur[key];
 }
+function stripProjectLocalOnlyKeys(cloned, warnings, strict) {
+  for (const dotKey of PROJECT_LOCAL_ONLY_KEYS) {
+    const segments = dotKey.split(".").filter(Boolean);
+    if (segments.length === 0) continue;
+    const leaf = segments.pop();
+    if (!keyPresentAtPath(cloned, segments, leaf)) continue;
+    const parentPath = "/" + segments.join("/");
+    deleteAtPath(cloned, parentPath, leaf);
+    const msg = tx(CONFIG_LOADER_TEXTS.projectLocalOnlyStripped, {
+      layer: "project",
+      key: dotKey
+    });
+    if (strict) throw new Error(msg);
+    warnings.push(msg);
+  }
+}
+function keyPresentAtPath(root, parentSegments, leaf) {
+  let cur = root;
+  for (const seg of parentSegments) {
+    if (!isPlainObject2(cur)) return false;
+    cur = cur[seg];
+  }
+  return isPlainObject2(cur) && Object.prototype.hasOwnProperty.call(cur, leaf);
+}
 function isPlainObject2(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v);
 }
@@ -5050,6 +5335,16 @@ var UserOnlyKeyError = class extends Error {
   }
   key;
 };
+var ProjectLocalOnlyKeyError = class extends Error {
+  constructor(key) {
+    super(
+      `Config key '${key}' is project-local only. Pass { target: 'project-local' } to write it to .skill-map/settings.local.json (gitignored), or use -g for the user / user-local scope.`
+    );
+    this.key = key;
+    this.name = "ProjectLocalOnlyKeyError";
+  }
+  key;
+};
 function readConfigValue(key, opts) {
   const scope = USER_ONLY_KEYS.has(key) ? "global" : opts.scope;
   const loaded = loadConfigForScope(scope, opts);
@@ -5061,6 +5356,9 @@ function writeConfigValue(key, value, opts) {
   if (USER_ONLY_KEYS.has(key) && opts.target === "project") {
     throw new UserOnlyKeyError(key);
   }
+  if (PROJECT_LOCAL_ONLY_KEYS.has(key) && opts.target === "project") {
+    throw new ProjectLocalOnlyKeyError(key);
+  }
   const path = targetSettingsPath(opts.target, opts.cwd, opts.homedir);
   const merged = readJsonObjectOrEmpty(path);
   setAtPath(merged, key, value);
@@ -5071,6 +5369,9 @@ function removeConfigValue(key, opts) {
   if (USER_ONLY_KEYS.has(key) && opts.target === "project") {
     throw new UserOnlyKeyError(key);
   }
+  if (PROJECT_LOCAL_ONLY_KEYS.has(key) && opts.target === "project") {
+    throw new ProjectLocalOnlyKeyError(key);
+  }
   const path = targetSettingsPath(opts.target, opts.cwd, opts.homedir);
   const merged = readJsonObjectOrEmpty(path);
   const removed = deleteAtPath2(merged, key);
@@ -5088,8 +5389,16 @@ function loadConfigForScope(scope, opts) {
   });
 }
 function targetSettingsPath(target, cwd, home) {
-  const root = target === "user" ? home : cwd;
-  return defaultSettingsPath(root);
+  switch (target) {
+    case "user":
+      return defaultSettingsPath(home);
+    case "user-local":
+      return defaultLocalSettingsPath(home);
+    case "project":
+      return defaultSettingsPath(cwd);
+    case "project-local":
+      return defaultLocalSettingsPath(cwd);
+  }
 }
 function validateOrThrow(content) {
   const validators = loadSchemaValidators();
@@ -5243,7 +5552,7 @@ var UPDATE_CHECK_TEXTS = {
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.20.0",
+  version: "0.21.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -5309,7 +5618,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "0.20.0",
+    "@skill-map/spec": "0.21.0",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -5433,10 +5742,14 @@ function isUpdateCheckEnabled(opts) {
 async function runWithAdapter(adapter, opts) {
   const cache = await adapter.preferences.loadUpdateCheckCache();
   const now = Date.now();
+  let lastShownAt = cache?.shownAt ?? null;
+  let didShowThisRun = false;
   if (cache && isOutdated(VERSION, cache.latestVersion)) {
-    const dueToShow = cache.shownAt === null || now - cache.shownAt > ONE_DAY_MS;
+    const dueToShow = lastShownAt === null || now - lastShownAt > ONE_DAY_MS;
     if (dueToShow) {
       writeBanner(opts, cache.latestVersion);
+      didShowThisRun = true;
+      lastShownAt = now;
       try {
         await adapter.preferences.saveUpdateCheckCache({
           latestVersion: cache.latestVersion,
@@ -5455,11 +5768,18 @@ async function runWithAdapter(adapter, opts) {
   } catch {
     return;
   }
+  if (!didShowThisRun && isOutdated(VERSION, latest)) {
+    const dueToShow = lastShownAt === null || now - lastShownAt > ONE_DAY_MS;
+    if (dueToShow) {
+      writeBanner(opts, latest);
+      lastShownAt = now;
+    }
+  }
   try {
     await adapter.preferences.saveUpdateCheckCache({
       latestVersion: latest,
       checkedAt: now,
-      shownAt: cache?.shownAt ?? null
+      shownAt: lastShownAt
     });
   } catch {
   }
@@ -5484,7 +5804,7 @@ var updateCheckHook = {
   pluginId: "core",
   kind: "hook",
   version: "1.0.0",
-  description: 'Once-per-day "update available" banner. Subscribes to `boot`; runs the registry probe (cache-aware) before the verb routes.',
+  description: "Checks once a day for a newer version of skill-map on npm and shows the `update available` banner when one exists.",
   stability: "stable",
   mode: "deterministic",
   triggers: ["boot"],
@@ -5549,6 +5869,8 @@ var builtInBundles = [
       externalUrlCounterExtractor,
       markdownLinkExtractor,
       slashExtractor,
+      stabilityExtractor,
+      toolsCountExtractor,
       triggerCollisionAnalyzer,
       brokenRefAnalyzer,
       supersededAnalyzer,
@@ -5772,15 +6094,20 @@ var UTIL_TEXTS = {
   // Every verb's body is expected to end on a content line (with or
   // without its own trailing \n); the blank line here is universal.
   doneIn: "\ndone in {{elapsed}}\n",
-  // confirm.ts (default-no prompt suffix)
+  // confirm.ts (default-no prompt suffix — destructive verbs)
   confirmPromptSuffix: " [y/N] ",
+  // confirm.ts (default-yes prompt suffix — consent-style verbs where the
+  // user already triggered the action and is just acknowledging it,
+  // e.g. the .sm write consent gate).
+  confirmPromptSuffixDefaultYes: " [Y/n] ",
   /**
-   * Regex source matching affirmative answers in `confirm()`. Compiled
-   * with the `i` flag in the helper. Pre-i18n today the pattern is
-   * English-only; when a non-English locale lands the catalog grows
-   * alternations (e.g. `^(y(es)?|s(í|i)?)$`).
+   * Regex source matching affirmative / negative answers in `confirm()`.
+   * Compiled with the `i` flag in the helper. Pre-i18n today the
+   * patterns are English-only; when a non-English locale lands each
+   * catalog entry grows alternations (e.g. `^(y(es)?|s(í|i)?)$`).
    */
-  confirmYesPatternSource: "^y(es)?$"
+  confirmYesPatternSource: "^y(es)?$",
+  confirmNoPatternSource: "^no?$"
 };
 
 // cli/util/exit-codes.ts
@@ -5992,6 +6319,41 @@ import { existsSync as existsSync10 } from "fs";
 import { dirname as dirname8, resolve as resolve12 } from "path";
 import { Command as Command2, Option as Option2 } from "clipanion";
 
+// core/config/sidecar-consent.ts
+var EConsentRequiredError = class extends Error {
+  key;
+  hintTarget;
+  constructor(init) {
+    super(
+      `Skill-map needs your consent to create .sm sidecars in this project. Set '${init.key}' to true in .skill-map/settings.local.json (gitignored), or pass --yes / { confirm: true } to grant on the fly.`
+    );
+    this.name = "EConsentRequiredError";
+    this.key = init.key;
+    this.hintTarget = init.hintTarget;
+  }
+};
+function ensureSidecarWritesAllowed(opts) {
+  const allowed = readConfigValue("allowEditSmFiles", {
+    scope: "project",
+    cwd: opts.cwd,
+    homedir: opts.homedir,
+    default: false
+  });
+  if (allowed === true) return;
+  if (opts.confirm === true) {
+    writeConfigValue("allowEditSmFiles", true, {
+      target: "project-local",
+      cwd: opts.cwd,
+      homedir: opts.homedir
+    });
+    return;
+  }
+  throw new EConsentRequiredError({
+    key: "allowEditSmFiles",
+    hintTarget: "project-local"
+  });
+}
+
 // kernel/sidecar/store.ts
 import { existsSync as existsSync9, readFileSync as readFileSync8, renameSync as renameSync2, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2 } from "fs";
 import { dirname as dirname7, resolve as resolve10 } from "path";
@@ -6008,7 +6370,12 @@ var FilesystemSidecarStore = class {
    * files in the repo and entries are tiny).
    */
   #locks = /* @__PURE__ */ new Map();
-  async applyPatch(sidecarAbsPath, changes) {
+  async applyPatch(sidecarAbsPath, changes, consent) {
+    ensureSidecarWritesAllowed({
+      confirm: consent.confirm,
+      cwd: consent.cwd,
+      homedir: consent.homedir
+    });
     const prev = this.#locks.get(sidecarAbsPath) ?? Promise.resolve();
     let release;
     const settled = new Promise((res) => {
@@ -6146,9 +6513,41 @@ 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 ---------------------------------------------------
+  /**
+   * 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 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",
+  consentRequiredNonTtyHint: "Pass --yes to grant (writes to .skill-map/settings.local.json \u2014 gitignored)."
 };
 
+// cli/util/confirm.ts
+import { createInterface } from "readline";
+var YES_PATTERN = new RegExp(UTIL_TEXTS.confirmYesPatternSource, "i");
+var NO_PATTERN = new RegExp(UTIL_TEXTS.confirmNoPatternSource, "i");
+async function confirm(question, streams, opts) {
+  const defaultAnswer = opts?.defaultAnswer ?? "no";
+  const suffix = defaultAnswer === "yes" ? UTIL_TEXTS.confirmPromptSuffixDefaultYes : UTIL_TEXTS.confirmPromptSuffix;
+  const rl = createInterface({ input: streams.stdin, output: streams.stderr });
+  try {
+    const answer = await new Promise(
+      (resolveP) => rl.question(`${question}${suffix}`, resolveP)
+    );
+    const trimmed = answer.trim();
+    if (trimmed === "") return defaultAnswer === "yes";
+    if (YES_PATTERN.test(trimmed)) return true;
+    if (NO_PATTERN.test(trimmed)) return false;
+    return defaultAnswer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
 // cli/util/path-guard.ts
 import { isAbsolute as isAbsolute2, resolve as resolve11, sep } from "path";
 function assertContained(cwd, rel) {
@@ -6337,6 +6736,9 @@ var BumpCommand = class extends SmCommand {
   force = Option2.Boolean("--force", false, {
     description: "Single-node: bump even when the node is fresh. Batch: turn fresh-node refusals into silent no-ops."
   });
+  yes = Option2.Boolean("--yes", false, {
+    description: "Confirm writing .sm sidecar files in this project (sets allowEditSmFiles=true on first run)."
+  });
   // The remaining cyclomatic count is from CLI ergonomics — argument
   // validation guards (3) + dispatch (1) + JSON-vs-pretty branch.
   // eslint-disable-next-line complexity
@@ -6372,10 +6774,53 @@ var BumpCommand = class extends SmCommand {
       );
       return ExitCode.NotFound;
     }
-    if (this.pending) {
-      return this.#runPending(persisted.nodes, ctx.cwd, ansi);
+    return this.#runWithConsent(
+      ansi,
+      () => this.pending ? this.#runPending(persisted.nodes, ctx.cwd, ansi) : this.#runSingle(persisted.nodes, ctx.cwd, ansi)
+    );
+  }
+  /**
+   * Wrap `dispatch` with the `.sm` consent gate: on the first
+   * `EConsentRequiredError` thrown by `FilesystemSidecarStore.applyPatch`
+   * (via `ensureSidecarWritesAllowed`), prompt the operator if stdin is
+   * a TTY and `--yes` was not passed. On accept, flip `this.yes` to
+   * true and re-run `dispatch` (the second pass passes `confirm: true`
+   * to the store and the gate persists the flag to project-local).
+   * On decline or non-TTY without `--yes`, print a directed message
+   * and return `ExitCode.Error`.
+   */
+  async #runWithConsent(ansi, dispatch) {
+    try {
+      return await dispatch();
+    } catch (err) {
+      if (!(err instanceof EConsentRequiredError)) throw err;
+      const stdin = this.context.stdin;
+      const stderr = this.context.stderr;
+      const isTTY = stdin.isTTY === true;
+      if (!isTTY || this.yes) {
+        const errGlyph = ansi.red("\u2715");
+        this.printer.error(
+          tx(BUMP_TEXTS.consentRequiredNonTty, {
+            glyph: errGlyph,
+            hint: ansi.dim(BUMP_TEXTS.consentRequiredNonTtyHint)
+          })
+        );
+        return ExitCode.Error;
+      }
+      const ok = await confirm(
+        BUMP_TEXTS.consentPrompt,
+        { stdin, stderr },
+        { defaultAnswer: "yes" }
+      );
+      if (!ok) {
+        this.printer.info(
+          tx(BUMP_TEXTS.consentAborted, { glyph: ansi.cyan("\u2139") })
+        );
+        return ExitCode.Error;
+      }
+      this.yes = true;
+      return await dispatch();
     }
-    return this.#runSingle(persisted.nodes, ctx.cwd, ansi);
   }
   // --- single-node --------------------------------------------------------
   // Complexity is from CLI ergonomics: not-found / abs-path-resolve /
@@ -6427,15 +6872,21 @@ var BumpCommand = class extends SmCommand {
       return ExitCode.Ok;
     }
     const store = new FilesystemSidecarStore();
+    const ctx = defaultRuntimeContext();
     let sidecarPath;
     try {
       for (const w of result.writes ?? []) {
         if (w.kind === "sidecar") {
-          await store.applyPatch(w.path, w.changes);
+          await store.applyPatch(w.path, w.changes, {
+            confirm: this.yes,
+            cwd: ctx.cwd,
+            homedir: ctx.homedir
+          });
           sidecarPath = w.path;
         }
       }
     } catch (err) {
+      if (err instanceof EConsentRequiredError) throw err;
       this.printer.error(
         tx(BUMP_TEXTS.bumpFailed, {
           glyph: errGlyph,
@@ -6516,9 +6967,11 @@ var BumpCommand = class extends SmCommand {
       this.printer.info(tx(BUMP_TEXTS.pendingBanner, { count: stale.length }));
     }
     const store = new FilesystemSidecarStore();
+    const ctx = defaultRuntimeContext();
+    const consent = { confirm: this.yes, cwd: ctx.cwd, homedir: ctx.homedir };
     const outcomes = [];
     for (const node of stale) {
-      const outcome = await bumpOnePending(node, cwd, this.force, store);
+      const outcome = await bumpOnePending(node, cwd, this.force, store, consent);
       outcomes.push(outcome);
       if (outcome.status === "bumped" && this.staged && outcome.sidecarPath !== void 0) {
         const addErr = stageSidecar(cwd, outcome.sidecarPath);
@@ -6611,7 +7064,7 @@ function invokeBumpFor(node, absPath, force) {
     now: () => /* @__PURE__ */ new Date()
   });
 }
-async function bumpOnePending(node, cwd, force, store) {
+async function bumpOnePending(node, cwd, force, store, consent) {
   let absPath;
   try {
     assertContained(cwd, node.path);
@@ -6643,11 +7096,12 @@ async function bumpOnePending(node, cwd, force, store) {
   try {
     for (const w of result.writes ?? []) {
       if (w.kind === "sidecar") {
-        await store.applyPatch(w.path, w.changes);
+        await store.applyPatch(w.path, w.changes, consent);
         sidecarPath = w.path;
       }
     }
   } catch (err) {
+    if (err instanceof EConsentRequiredError) throw err;
     return {
       nodePath: node.path,
       status: "error",
@@ -7410,7 +7864,18 @@ var LOCKED_PLUGIN_IDS = /* @__PURE__ */ new Set([
   // unclaimed `.md` files"). Disabling it makes every orphan markdown
   // silently invisible — a foot-gun the host product does not want to
   // expose. Lock it in the enabled state.
-  "core/markdown"
+  "core/markdown",
+  // `core/annotations` turns the `supersedes` / `supersededBy` /
+  // `requires` / `related` / `conflictsWith` entries of the sidecar
+  // `annotations:` block into the arrows the graph draws between nodes.
+  // It does NOT own the rest of the block (`version`, `stability`,
+  // `tags`, `description` — those live on the node bundle directly and
+  // keep rendering with the plugin off). Disabling it produces a
+  // confusing "edges disappear but the sidecar metadata stays" split
+  // that no operator actually wants; the lock makes the asymmetry
+  // unreachable from CLI / BFF / UI. Re-evaluate if a third-party ever
+  // ships a competing supersession extractor.
+  "core/annotations"
 ]);
 function isPluginLocked(idOrQualified) {
   return LOCKED_PLUGIN_IDS.has(idOrQualified);
@@ -7557,7 +8022,21 @@ function isBundleEntryEnabled(bundle, extId, resolveEnabled) {
   }
   return resolveEnabled(qualifiedExtensionId(bundle.id, extId));
 }
+function buildGranularityMap(discovered) {
+  const out = /* @__PURE__ */ new Map();
+  for (const plugin of discovered) {
+    out.set(plugin.id, plugin.granularity ?? "bundle");
+  }
+  return out;
+}
+function isPluginExtensionEnabled(ext, granularityMap, resolveEnabled) {
+  const granularity = granularityMap.get(ext.pluginId) ?? "bundle";
+  if (granularity === "bundle") return resolveEnabled(ext.pluginId);
+  return resolveEnabled(qualifiedExtensionId(ext.pluginId, ext.id));
+}
 function composeScanExtensions(opts) {
+  const resolveEnabled = opts.resolveEnabled ?? opts.pluginRuntime.resolveEnabled;
+  const granularityMap = buildGranularityMap(opts.pluginRuntime.discovered);
   const providers = [];
   const extractors = [];
   const analyzers = [];
@@ -7565,13 +8044,21 @@ function composeScanExtensions(opts) {
   if (!opts.noBuiltIns) {
     accumulateBuiltInScanExtensions(
       { providers, extractors, analyzers, hooks },
-      opts.pluginRuntime.resolveEnabled
+      resolveEnabled
     );
   }
-  providers.push(...opts.pluginRuntime.extensions.providers);
-  extractors.push(...opts.pluginRuntime.extensions.extractors);
-  analyzers.push(...opts.pluginRuntime.extensions.analyzers);
-  hooks.push(...opts.pluginRuntime.extensions.hooks);
+  for (const ext of opts.pluginRuntime.extensions.providers) {
+    if (isPluginExtensionEnabled(ext, granularityMap, resolveEnabled)) providers.push(ext);
+  }
+  for (const ext of opts.pluginRuntime.extensions.extractors) {
+    if (isPluginExtensionEnabled(ext, granularityMap, resolveEnabled)) extractors.push(ext);
+  }
+  for (const ext of opts.pluginRuntime.extensions.analyzers) {
+    if (isPluginExtensionEnabled(ext, granularityMap, resolveEnabled)) analyzers.push(ext);
+  }
+  for (const ext of opts.pluginRuntime.extensions.hooks) {
+    if (isPluginExtensionEnabled(ext, granularityMap, resolveEnabled)) hooks.push(ext);
+  }
   const finalProviders = opts.killSwitches?.providers === true ? [] : providers;
   const finalExtractors = opts.killSwitches?.extractors === true ? [] : extractors;
   const finalAnalyzers = opts.killSwitches?.analyzers === true ? [] : analyzers;
@@ -7616,38 +8103,61 @@ function accumulateBuiltInScanExtensions(buckets, resolveEnabled) {
 }
 function composeFormatters(opts) {
   const noBuiltIns = opts.noBuiltIns ?? false;
+  const resolveEnabled = opts.resolveEnabled ?? opts.pluginRuntime.resolveEnabled;
+  const granularityMap = buildGranularityMap(opts.pluginRuntime.discovered);
   const out = [];
   if (!noBuiltIns) {
     for (const bundle of builtInBundles) {
       for (const ext of bundle.extensions) {
         if (ext.kind !== "formatter") continue;
-        if (!isBuiltInExtensionEnabled(bundle, ext, opts.pluginRuntime.resolveEnabled)) continue;
+        if (!isBuiltInExtensionEnabled(bundle, ext, resolveEnabled)) continue;
         out.push(ext);
       }
     }
   }
-  out.push(...opts.pluginRuntime.extensions.formatters);
+  for (const ext of opts.pluginRuntime.extensions.formatters) {
+    if (isPluginExtensionEnabled(ext, granularityMap, resolveEnabled)) out.push(ext);
+  }
   return out;
 }
 function registerEnabledExtensions(kernel, pluginRuntime, options = {}) {
   const noBuiltIns = options.noBuiltIns === true;
+  const resolveEnabled = options.resolveEnabled ?? pluginRuntime.resolveEnabled;
+  const granularityMap = buildGranularityMap(pluginRuntime.discovered);
   if (!noBuiltIns) {
-    const enabledBuiltIns = filterBuiltInManifests(
-      listBuiltIns(),
-      pluginRuntime.resolveEnabled
-    );
+    const enabledBuiltIns = filterBuiltInManifests(listBuiltIns(), resolveEnabled);
     for (const manifest of enabledBuiltIns) kernel.registry.register(manifest);
   }
-  for (const manifest of pluginRuntime.manifests) kernel.registry.register(manifest);
+  for (const manifest of pluginRuntime.manifests) {
+    if (!isPluginExtensionEnabled(manifest, granularityMap, resolveEnabled)) continue;
+    kernel.registry.register(manifest);
+  }
   if (kernel.setRegisteredAnnotationKeys) {
-    kernel.setRegisteredAnnotationKeys(pluginRuntime.annotationContributions);
+    const filteredAnnotations = pluginRuntime.annotationContributions.filter(
+      (entry) => (
+        // Annotation contributions live at plugin-id granularity (the
+        // catalog row carries `pluginId`, not `extensionId`), so the
+        // bundle-level toggle gates the entire row. Extension
+        // granularity falls through to the manifest-level filter above
+        // — this surface is bundle-scoped by design.
+        resolveEnabled(entry.pluginId)
+      )
+    );
+    kernel.setRegisteredAnnotationKeys(filteredAnnotations);
   }
   if (kernel.setRegisteredViewContributions) {
-    const merged = [...pluginRuntime.viewContributions];
+    const userContribs = pluginRuntime.viewContributions.filter(
+      (entry) => isPluginExtensionEnabled(
+        { pluginId: entry.pluginId, id: entry.extensionId },
+        granularityMap,
+        resolveEnabled
+      )
+    );
+    const merged = [...userContribs];
     if (!noBuiltIns) {
       for (const bundle of builtInBundles) {
         for (const ext of bundle.extensions) {
-          if (!isBundleEntryEnabled(bundle, ext.id, pluginRuntime.resolveEnabled)) continue;
+          if (!isBundleEntryEnabled(bundle, ext.id, resolveEnabled)) continue;
           collectViewContributions(ext.pluginId, ext.id, ext, merged);
         }
       }
@@ -8002,6 +8512,15 @@ var CONFIG_TEXTS = {
    */
   userOnlyKeyRejection: '{{glyph}}  sm config: "{{key}}" is a user-scope key.\n   {{hint}}\n',
   userOnlyKeyRejectionHint: "Rerun with -g to write to ~/.skill-map/settings.json.",
+  /**
+   * Surfaced when a PROJECT_LOCAL_ONLY key (`allowEditSmFiles` /
+   * `scan.includeHome` / `scan.extraRoots` / `scan.referencePaths`)
+   * reaches the writer with `target: 'project'` — defensive only, the
+   * CLI auto-routes to `project-local`, but the helper enforces the
+   * rule for any other caller too.
+   */
+  projectLocalOnlyKeyRejection: '{{glyph}}  sm config: "{{key}}" is project-local only and cannot live in committed settings.json.\n   {{hint}}\n',
+  projectLocalOnlyKeyRejectionHint: "Writes to .skill-map/settings.local.json (gitignored), or -g for user scope.",
   /**
    * Surfaced when `sm config set` is invoked on a privacy-sensitive
    * key (`scan.includeHome` / `scan.extraRoots` /
@@ -8040,8 +8559,14 @@ var CONFIG_TEXTS = {
 
 // cli/commands/config.ts
 function targetSettingsPath2(target, cwd, home) {
-  const root = target === "user" ? home : cwd;
-  return defaultSettingsPath(root);
+  const root = target === "user" || target === "user-local" ? home : cwd;
+  return target === "project-local" || target === "user-local" ? defaultLocalSettingsPath(root) : defaultSettingsPath(root);
+}
+function resolveWriteTarget(key, global) {
+  if (PROJECT_LOCAL_ONLY_KEYS.has(key)) {
+    return global ? "user" : "project-local";
+  }
+  return global ? "user" : "project";
 }
 function suggestConfigKey(effective, typed, ansi) {
   const candidates = enumerateConfigPaths(effective);
@@ -8393,7 +8918,7 @@ var ConfigSetCommand = class extends SmCommand {
   // eslint-disable-next-line complexity
   async run() {
     const ctx = defaultRuntimeContext();
-    const target = this.global ? "user" : "project";
+    const target = resolveWriteTarget(this.key, this.global);
     const path = targetSettingsPath2(target, ctx.cwd, ctx.homedir);
     const stderr = this.context.stderr;
     const stderrAnsi = ansiFor({ isTTY: stderr.isTTY === true, noColorFlag: this.noColor });
@@ -8455,6 +8980,16 @@ var ConfigSetCommand = class extends SmCommand {
         );
         return ExitCode.Error;
       }
+      if (err instanceof ProjectLocalOnlyKeyError) {
+        this.printer.info(
+          tx(CONFIG_TEXTS.projectLocalOnlyKeyRejection, {
+            glyph: errGlyph,
+            key: err.key,
+            hint: stderrAnsi.dim(CONFIG_TEXTS.projectLocalOnlyKeyRejectionHint)
+          })
+        );
+        return ExitCode.Error;
+      }
       if (err instanceof ConfigValidationError) {
         this.printer.info(
           tx(CONFIG_TEXTS.invalidAfterSet, { glyph: errGlyph, errors: err.errors })
@@ -8497,7 +9032,7 @@ var ConfigResetCommand = class extends SmCommand {
   // the value they gate.
   async run() {
     const ctx = defaultRuntimeContext();
-    const target = this.global ? "user" : "project";
+    const target = resolveWriteTarget(this.key, this.global);
     const path = targetSettingsPath2(target, ctx.cwd, ctx.homedir);
     const stdout = this.context.stdout;
     const ansi = ansiFor({ isTTY: stdout.isTTY === true, noColorFlag: this.noColor });
@@ -8541,6 +9076,16 @@ var ConfigResetCommand = class extends SmCommand {
         );
         return ExitCode.Error;
       }
+      if (err instanceof ProjectLocalOnlyKeyError) {
+        this.printer.info(
+          tx(CONFIG_TEXTS.projectLocalOnlyKeyRejection, {
+            glyph: ansi.red("\u2715"),
+            key: err.key,
+            hint: ansi.dim(CONFIG_TEXTS.projectLocalOnlyKeyRejectionHint)
+          })
+        );
+        return ExitCode.Error;
+      }
       if (err instanceof ConfigValidationError) {
         this.printer.info(
           tx(CONFIG_TEXTS.invalidAfterSet, { glyph: ansi.red("\u2715"), errors: err.errors })
@@ -9220,21 +9765,6 @@ import { chmod, copyFile, mkdir, rm } from "fs/promises";
 import { dirname as dirname11, join as join7, resolve as resolve18 } from "path";
 import { DatabaseSync as DatabaseSync4 } from "node:sqlite";
 
-// cli/util/confirm.ts
-import { createInterface } from "readline";
-var YES_PATTERN = new RegExp(UTIL_TEXTS.confirmYesPatternSource, "i");
-async function confirm(question, streams) {
-  const rl = createInterface({ input: streams.stdin, output: streams.stderr });
-  try {
-    const answer = await new Promise(
-      (resolveP) => rl.question(`${question}${UTIL_TEXTS.confirmPromptSuffix}`, resolveP)
-    );
-    return YES_PATTERN.test(answer.trim());
-  } finally {
-    rl.close();
-  }
-}
-
 // cli/i18n/db.texts.ts
 var DB_TEXTS = {
   // --- reset -----------------------------------------------------------
@@ -11481,7 +12011,7 @@ async function runScanInternal(_kernel, options) {
   for (const analyzer of exts.analyzers ?? []) {
     if (analyzer.viewContributions === void 0) continue;
     for (const node of walked.nodes) {
-      walked.freshlyRunTuples.add(`${analyzer.pluginId}/${analyzer.id}/${node.path}`);
+      walked.freshlyRunTuples.add(`${analyzer.pluginId}\0${analyzer.id}\0${node.path}`);
     }
   }
   for (const issue of walked.frontmatterIssues) issues.push(issue);
@@ -11697,8 +12227,10 @@ function computeCacheDecision(opts) {
     const priorRunsForNode = opts.priorExtractorRuns.get(opts.nodePath) ?? /* @__PURE__ */ new Map();
     for (const ex of applicableExtractors) {
       const qualified = qualifiedExtensionId(ex.pluginId, ex.id);
-      const priorBody = priorRunsForNode.get(qualified);
-      if (opts.nodeHashCacheEligible && priorBody === opts.bodyHash) {
+      const prior = priorRunsForNode.get(qualified);
+      const bodyMatch = prior !== void 0 && prior.bodyHash === opts.bodyHash;
+      const sidecarOk = prior !== void 0 && prior.sidecarAnnotationsHash === opts.sidecarAnnotationsHash;
+      if (opts.nodeHashCacheEligible && bodyMatch && sidecarOk) {
         cachedQualifiedIds.add(qualified);
       } else {
         missingExtractors.push(ex);
@@ -11743,7 +12275,8 @@ function reusePriorNode(opts) {
       nodePath: opts.priorNode.path,
       extractorId: qualified,
       bodyHashAtRun: opts.bodyHash,
-      ranAt
+      ranAt,
+      sidecarAnnotationsHashAtRun: opts.sidecarAnnotationsHash
     });
   }
   return { ...base, extractorRuns };
@@ -11829,11 +12362,22 @@ async function walkAndExtract(opts) {
       }
       claimedPaths.add(raw.path);
       index += 1;
+      const sidecarResolution = resolveSidecarOverlay(
+        raw.path,
+        raw.path,
+        roots,
+        bodyHash,
+        frontmatterHash
+      );
+      const sidecarAnnotationsHash = sha256(
+        canonicalSidecarAnnotations(sidecarResolution.overlay.annotations)
+      );
       const cacheDecision = computeCacheDecision({
         extractors,
         kind,
         nodePath: raw.path,
         bodyHash,
+        sidecarAnnotationsHash,
         nodeHashCacheEligible,
         priorExtractorRuns
       });
@@ -11844,10 +12388,20 @@ async function walkAndExtract(opts) {
         missingExtractors,
         fullCacheHit
       } = cacheDecision;
+      const attachSidecar = (node2) => {
+        node2.sidecar = sidecarResolution.overlay;
+        if (sidecarResolution.parsedRoot !== null) {
+          sidecarRoots.set(node2.path, sidecarResolution.parsedRoot);
+        }
+        return sidecarResolution.issues.map(
+          (i) => i.nodeIds.length > 0 ? i : { ...i, nodeIds: [node2.path] }
+        );
+      };
       if (fullCacheHit && priorNode) {
         const reused = reusePriorNode({
           priorNode,
           bodyHash,
+          sidecarAnnotationsHash,
           strict,
           cachedQualifiedIds,
           applicableQualifiedIds,
@@ -11855,14 +12409,7 @@ async function walkAndExtract(opts) {
           priorLinksByOriginating,
           priorFrontmatterIssuesByNode
         });
-        const reusedSidecarIssues = resolveAndApplySidecar(
-          reused.node,
-          raw.path,
-          roots,
-          bodyHash,
-          frontmatterHash,
-          sidecarRoots
-        );
+        const reusedSidecarIssues = attachSidecar(reused.node);
         nodes.push(reused.node);
         cachedPaths.add(reused.node.path);
         for (const link2 of reused.internalLinks) internalLinks.push(link2);
@@ -11903,14 +12450,7 @@ async function walkAndExtract(opts) {
         nodes.push(node);
         for (const issue of fresh.frontmatterIssues) frontmatterIssues.push(issue);
       }
-      const sidecarIssues = resolveAndApplySidecar(
-        node,
-        raw.path,
-        roots,
-        bodyHash,
-        frontmatterHash,
-        sidecarRoots
-      );
+      const sidecarIssues = attachSidecar(node);
       for (const issue of sidecarIssues) frontmatterIssues.push(issue);
       emitter.emit(makeEvent("scan.progress", {
         index,
@@ -11921,7 +12461,7 @@ async function walkAndExtract(opts) {
       }));
       const extractorsToRun = partialCacheHit ? missingExtractors : applicableExtractors;
       for (const ex of extractorsToRun) {
-        freshlyRunTuples.add(`${ex.pluginId}/${ex.id}/${node.path}`);
+        freshlyRunTuples.add(`${ex.pluginId}\0${ex.id}\0${node.path}`);
       }
       const extractResult = await runExtractorsForNode({
         extractors: extractorsToRun,
@@ -11945,7 +12485,8 @@ async function walkAndExtract(opts) {
           nodePath: node.path,
           extractorId: qualified,
           bodyHashAtRun: bodyHash,
-          ranAt
+          ranAt,
+          sidecarAnnotationsHashAtRun: sidecarAnnotationsHash
         });
       }
     }
@@ -12246,30 +12787,42 @@ function canonicalFrontmatter(parsed, raw) {
     noCompatMode: true
   });
 }
-function resolveAndApplySidecar(node, relativePath2, roots, liveBodyHash, liveFrontmatterHash, sidecarRoots) {
+function canonicalSidecarAnnotations(annotations) {
+  if (!annotations || typeof annotations !== "object" || Array.isArray(annotations)) {
+    return yaml4.dump({}, { sortKeys: true, lineWidth: -1, noRefs: true, noCompatMode: true });
+  }
+  return yaml4.dump(annotations, {
+    sortKeys: true,
+    lineWidth: -1,
+    noRefs: true,
+    noCompatMode: true
+  });
+}
+function resolveSidecarOverlay(relativePath2, nodePathForIssue, roots, liveBodyHash, liveFrontmatterHash) {
   const issues = [];
   const mdAbs = resolveAbsoluteMdPath(relativePath2, roots);
   if (mdAbs === null) {
-    node.sidecar = { present: false };
-    return issues;
+    return { overlay: { present: false }, issues, parsedRoot: null };
   }
   const result = readSidecarFor(mdAbs);
   if (!result.present) {
-    node.sidecar = { present: false };
-    return issues;
+    return { overlay: { present: false }, issues, parsedRoot: null };
   }
   if (result.parsed === null) {
-    node.sidecar = { present: true, status: null, annotations: null, root: null };
     for (const parseIssue of result.issues) {
       issues.push({
         analyzerId: "invalid-sidecar",
         severity: "warn",
-        nodeIds: [node.path],
+        nodeIds: [nodePathForIssue],
         message: parseIssue.message,
         data: { sidecarPath: relativePathFromRoots(mdAbs, roots) }
       });
     }
-    return issues;
+    return {
+      overlay: { present: true, status: null, annotations: null, root: null },
+      issues,
+      parsedRoot: null
+    };
   }
   const status = computeDriftStatus({
     storedBodyHash: result.parsed.identityBodyHash,
@@ -12277,14 +12830,22 @@ function resolveAndApplySidecar(node, relativePath2, roots, liveBodyHash, liveFr
     liveBodyHash,
     liveFrontmatterHash
   });
-  node.sidecar = {
-    present: true,
-    status,
-    annotations: result.parsed.annotations,
-    root: result.parsed.raw
+  return {
+    // R15 closure (2026-05-07) — surface the full parsed root on the
+    // overlay so BFF consumers (UI inspector audit / plugin-contributions
+    // / debug panels) can read `for.*`, `audit.*`, `settings.*`, and
+    // plugin-namespaced sub-keys without re-reading the file. The
+    // `annotations` field above stays — it duplicates `root.annotations`
+    // by design so existing consumers keep working unchanged.
+    overlay: {
+      present: true,
+      status,
+      annotations: result.parsed.annotations,
+      root: result.parsed.raw
+    },
+    issues,
+    parsedRoot: result.parsed.raw
   };
-  sidecarRoots.set(node.path, result.parsed.raw);
-  return issues;
 }
 function resolveAbsoluteMdPath(relativePath2, roots) {
   if (isAbsolute6(relativePath2)) {
@@ -12951,8 +13512,13 @@ function registerExtensions(kernel, pluginRuntime, opts) {
     pluginRuntime
   };
   if (opts.killSwitches) composeOpts.killSwitches = opts.killSwitches;
+  if (opts.resolveEnabledOverride) composeOpts.resolveEnabled = opts.resolveEnabledOverride;
   const extensions = composeScanExtensions(composeOpts);
-  registerEnabledExtensions(kernel, pluginRuntime, { noBuiltIns: opts.noBuiltIns });
+  const registerOpts = {
+    noBuiltIns: opts.noBuiltIns
+  };
+  if (opts.resolveEnabledOverride) registerOpts.resolveEnabled = opts.resolveEnabledOverride;
+  registerEnabledExtensions(kernel, pluginRuntime, registerOpts);
   return extensions;
 }
 function buildScanIgnoreFilter(cfg, cwd) {
@@ -15076,11 +15642,14 @@ function renderListHuman(builtIns2, plugins, ansi) {
   return lines.join("\n") + "\n" + PLUGINS_TEXTS.listTipShow;
 }
 function builtInToListRow(b) {
+  const names = b.granularity === "extension" ? b.extensions.map(
+    (e) => e.enabled ? e.id : `${PLUGINS_TEXTS.rowGlyphOff} ${e.id}`
+  ) : b.extensions.map((e) => e.id);
   return {
     id: b.id,
     enabled: b.enabled,
     source: PLUGINS_TEXTS.sourceBuiltIn,
-    names: b.extensions.map((e) => e.id)
+    names
   };
 }
 function pluginToListRow(p) {
@@ -15132,7 +15701,17 @@ var PluginsShowCommand = class extends SmCommand {
   static paths = [["plugins", "show"]];
   static usage = Command16.Usage({
     category: "Plugins",
-    description: "Show a single plugin's manifest + loaded extensions."
+    description: "Show a single plugin's manifest + loaded extensions.",
+    details: `
+      Accepts a bundle / plugin id (\`core\`, \`claude\`, \`my-plugin\`)
+      or a qualified extension id (\`core/<ext-id>\`,
+      \`<plugin>/<ext-id>\`). When given a qualified id, validates the
+      extension exists and renders the parent bundle's detail (which
+      lists every extension with per-extension status for
+      granularity=extension bundles like \`core\`). The same id shapes
+      \`sm plugins enable\` and \`sm plugins disable\` accept resolve
+      cleanly here too.
+    `
   });
   id = Option16.String({ required: true });
   pluginDir = Option16.String("--plugin-dir", { required: false });
@@ -15140,16 +15719,22 @@ var PluginsShowCommand = class extends SmCommand {
     const plugins = await loadAll({ global: this.global, pluginDir: this.pluginDir });
     const resolveEnabled = await buildResolver(this.global);
     const builtIns2 = builtInRows(resolveEnabled);
-    const builtIn = builtIns2.find((b) => b.id === this.id);
-    const match = plugins.find((p) => p.id === this.id);
+    const stderr = this.context.stderr;
+    const stderrAnsi = ansiFor({ isTTY: stderr.isTTY === true, noColorFlag: this.noColor });
+    const lookupResult = resolveShowLookupId(this.id, builtIns2, plugins, stderrAnsi);
+    if ("error" in lookupResult) {
+      this.printer.error(lookupResult.error);
+      return ExitCode.NotFound;
+    }
+    const lookupId = lookupResult.bundleId;
+    const builtIn = builtIns2.find((b) => b.id === lookupId);
+    const match = plugins.find((p) => p.id === lookupId);
     if (!builtIn && !match) {
-      const stderr = this.context.stderr;
-      const ansi2 = ansiFor({ isTTY: stderr.isTTY === true, noColorFlag: this.noColor });
       this.printer.error(
         tx(PLUGINS_TEXTS.pluginNotFound, {
-          glyph: ansi2.red("\u2715"),
+          glyph: stderrAnsi.red("\u2715"),
           id: sanitizeForTerminal(this.id),
-          hint: ansi2.dim(PLUGINS_TEXTS.pluginNotFoundHint)
+          hint: stderrAnsi.dim(PLUGINS_TEXTS.pluginNotFoundHint)
         })
       );
       return ExitCode.NotFound;
@@ -15166,6 +15751,44 @@ var PluginsShowCommand = class extends SmCommand {
     return ExitCode.Ok;
   }
 };
+function resolveShowLookupId(id, builtIns2, plugins, ansi) {
+  if (!id.includes("/")) return { bundleId: id };
+  const errGlyph = ansi.red("\u2715");
+  const [bundleId, extId, ...rest] = id.split("/");
+  if (!bundleId || !extId || rest.length > 0) {
+    return {
+      error: tx(PLUGINS_TEXTS.qualifiedIdUnknownBundle, {
+        glyph: errGlyph,
+        bundleId: sanitizeForTerminal(id),
+        hint: ansi.dim(PLUGINS_TEXTS.qualifiedIdUnknownBundleHint)
+      })
+    };
+  }
+  const builtIn = builtIns2.find((b) => b.id === bundleId);
+  const userPlugin = plugins.find((p) => p.id === bundleId);
+  if (!builtIn && !userPlugin) {
+    return {
+      error: tx(PLUGINS_TEXTS.qualifiedIdUnknownBundle, {
+        glyph: errGlyph,
+        bundleId: sanitizeForTerminal(bundleId),
+        hint: ansi.dim(PLUGINS_TEXTS.qualifiedIdUnknownBundleHint)
+      })
+    };
+  }
+  const knownExts = builtIn ? builtIn.extensions.map((e) => e.id) : userPlugin?.extensions?.map((e) => e.id) ?? [];
+  if (!knownExts.includes(extId)) {
+    return {
+      error: tx(PLUGINS_TEXTS.qualifiedIdNotFound, {
+        glyph: errGlyph,
+        id: sanitizeForTerminal(id),
+        bundleId: sanitizeForTerminal(bundleId),
+        extId: sanitizeForTerminal(extId),
+        hint: ansi.dim(PLUGINS_TEXTS.qualifiedIdNotFoundHint)
+      })
+    };
+  }
+  return { bundleId };
+}
 function renderBuiltInDetail(b, ansi) {
   const enabled = b.enabled;
   const glyph = enabled ? ansi.green(PLUGINS_TEXTS.rowGlyphOk) : ansi.red(PLUGINS_TEXTS.rowGlyphOff);
@@ -15677,6 +16300,14 @@ var TogglePluginsBase = class extends SmCommand {
     await withSqlite({ databasePath: dbPath, autoBackup: false }, async (adapter) => {
       for (const id of targets) {
         await adapter.pluginConfig.set(id, enabled);
+        if (!enabled) {
+          const slash = id.indexOf("/");
+          if (slash < 0) {
+            await adapter.contributions.purgeByPlugin(id);
+          } else {
+            await adapter.contributions.purgeByPlugin(id.slice(0, slash), id.slice(slash + 1));
+          }
+        }
       }
     });
     const verbPast = enabled ? "enabled" : "disabled";
@@ -15746,7 +16377,7 @@ function omitModule(key, value) {
 var VIEW_SLOTS_CATALOG = [
   { id: "card.title.right", summary: "Small icon marker next to the card title \u2014 language flag, platform glyph." },
   { id: "card.subtitle.left", summary: "Single non-negative integer in the card subtitle row." },
-  { id: "card.footer.left.counter", summary: "Counter chip in the left footer of the card." },
+  { id: "card.footer.left", summary: "Counter chip in the left footer of the card." },
   { id: "card.footer.right", summary: "Counter chip in the right footer of the card." },
   { id: "graph.node.alert", summary: "Corner badge decoration on the graph node \u2014 alert / status." },
   { id: "inspector.header.badge.counter", summary: "Counter chip in the inspector header badge cluster." },
@@ -15757,7 +16388,7 @@ var VIEW_SLOTS_CATALOG = [
   { id: "inspector.body.panel.key-values", summary: "Flat key/value pairs (\u2264 50) in the inspector body." },
   { id: "inspector.body.panel.link-list", summary: "Clickable scope-relative paths (\u2264 100) in the inspector body." },
   { id: "inspector.body.panel.markdown", summary: "Sanitized markdown text (\u2264 4096 chars) in the inspector body." },
-  { id: "topbar.actions.indicator", summary: "Scope-wide indicator chip in the topbar actions cluster." }
+  { id: "topbar.nav.start", summary: "Scope-wide indicator chip at the start of the topbar nav (before the view-switcher links)." }
 ];
 var INPUT_TYPES_CATALOG = [
   { id: "string-list", summary: "Array of free-form strings." },
@@ -15776,7 +16407,7 @@ var PluginsCreateCommand = class extends SmCommand {
   static usage = Command16.Usage({
     category: "Plugins",
     description: "Scaffold a new plugin directory.",
-    details: "Emits plugin.json + extension stub + README. Pre-filled with one view contribution (slot `card.footer.left.counter`) and one setting (`string-list`); edit to taste. Use `sm plugins slots list` to see other options."
+    details: "Emits plugin.json + extension stub + README. Pre-filled with one view contribution (slot `card.footer.left`) and one setting (`string-list`); edit to taste. Use `sm plugins slots list` to see other options."
   });
   pluginId = Option16.String({ required: true, name: "plugin-id" });
   at = Option16.String("--at", { required: false });
@@ -15845,7 +16476,7 @@ function scaffolderExtractorStub(pluginId) {
  * export missing a string \\\`kind\\\` field\`.
  *
  * Declared view contributions (in plugin.json):
- *   - 'count' \u2192 slot \`card.footer.left.counter\` (renders as a chip
+ *   - 'count' \u2192 slot \`card.footer.left\` (renders as a chip
  *     in the left footer of the node card)
  *
  * Declared settings:
@@ -15868,7 +16499,7 @@ export default {
 
   viewContributions: {
     count: {
-      slot: 'card.footer.left.counter',
+      slot: 'card.footer.left',
       icon: '\u{1F50D}',
       label: 'kw',
       emitWhenEmpty: false,
@@ -16321,6 +16952,19 @@ var SCAN_TEXTS = {
 // cli/commands/watch.ts
 import { Command as Command18, Option as Option18 } from "clipanion";
 
+// core/runtime/fresh-resolver.ts
+async function buildFreshResolver(deps) {
+  const overrides = await tryWithSqlite(
+    { databasePath: deps.databasePath, autoBackup: false },
+    async (adapter) => adapter.pluginConfig.loadOverrideMap()
+  );
+  if (overrides === null) return deps.fallbackResolver;
+  return makeEnabledResolver(deps.effectiveConfig(), overrides);
+}
+function composeResolver(effectiveConfig, overrides) {
+  return makeEnabledResolver(effectiveConfig, overrides);
+}
+
 // core/watcher/i18n/runtime.texts.ts
 var RUNTIME_TEXTS = {
   /**
@@ -16388,8 +17032,16 @@ function createWatcherRuntime(opts) {
       events.onPluginWarning?.(warn);
     }
     const runOnePass = async () => {
+      const resolveEnabledOverride = await buildFreshResolver({
+        databasePath: opts.dbPath,
+        effectiveConfig: () => cfg,
+        fallbackResolver: pluginRuntime.resolveEnabled
+      });
       const kernel = createKernel();
-      registerEnabledExtensions(kernel, pluginRuntime, { noBuiltIns: opts.noBuiltIns });
+      registerEnabledExtensions(kernel, pluginRuntime, {
+        noBuiltIns: opts.noBuiltIns,
+        resolveEnabled: resolveEnabledOverride
+      });
       const emitter = opts.emitterFactory();
       const priorState = await tryWithSqlite(
         { databasePath: opts.dbPath, autoBackup: false },
@@ -16411,7 +17063,8 @@ function createWatcherRuntime(opts) {
       );
       const composeOpts = {
         noBuiltIns: opts.noBuiltIns,
-        pluginRuntime
+        pluginRuntime,
+        resolveEnabled: resolveEnabledOverride
       };
       if (opts.killSwitches) composeOpts.killSwitches = opts.killSwitches;
       const composed = composeScanExtensions(composeOpts);
@@ -17305,6 +17958,48 @@ import { WebSocketServer } from "ws";
 import { Hono } from "hono";
 import { HTTPException as HTTPException11 } from "hono/http-exception";
 
+// core/config/service.ts
+var ConfigService = class {
+  #opts;
+  #cache = null;
+  constructor(opts) {
+    this.#opts = opts;
+  }
+  /**
+   * Return the cached `ILoadedConfig` (loading on first call).
+   * Subsequent calls return the same object reference — callers
+   * MUST treat it as read-only.
+   */
+  get() {
+    if (this.#cache === null) {
+      this.#cache = loadConfig({
+        scope: this.#opts.scope,
+        cwd: this.#opts.cwd,
+        homedir: this.#opts.homedir,
+        ...this.#opts.strict ? { strict: true } : {}
+      });
+    }
+    return this.#cache;
+  }
+  /**
+   * Sugar for `this.get().effective` — the most common consumer pattern
+   * (the `sources` / `warnings` slots are only relevant to the
+   * `GET /api/config` and `sm config show` paths).
+   */
+  effective() {
+    return this.get().effective;
+  }
+  /**
+   * Drop the cached `ILoadedConfig`. Next `get()` re-reads every layer
+   * from disk. Called by routes after a successful `writeConfigValue`
+   * (PATCH preferences / project-preferences) and by the sidecar
+   * consent gate after it flips `allowEditSmFiles` to `true`.
+   */
+  reload() {
+    this.#cache = null;
+  }
+};
+
 // server/i18n/server.texts.ts
 var SERVER_TEXTS = {
   // Boot banner — printed by the server itself when it begins to listen.
@@ -17383,6 +18078,15 @@ var SERVER_TEXTS = {
   sidecarBodyNotObject: "Request body must be a JSON object.",
   sidecarNodePathRequired: "`nodePath` is required and must be a non-empty string.",
   sidecarForceMustBeBoolean: "`force` must be a boolean when present.",
+  sidecarConfirmMustBeBoolean: "`confirm` must be a boolean when present.",
+  /**
+   * 412 envelope when `POST /api/sidecar/bump` would create a `.sm`
+   * file but `allowEditSmFiles` is still false. The UI's bump
+   * call-path catches `code: 'confirm-required'` and opens a
+   * `ConfirmationService` dialog explaining `.sm` writes; on accept
+   * it retries with `confirm: true` in the body.
+   */
+  sidecarConsentRequired: "consent required to write .sm sidecar files in this project. Retry with `confirm: true` to grant (writes to .skill-map/settings.local.json \u2014 gitignored).",
   // 500 envelope when the built-in bump action ships without an
   // `invoke()` — should be impossible in production but the route
   // throws a typed envelope rather than a bare `Error` so the global
@@ -17422,6 +18126,12 @@ var SERVER_TEXTS = {
   // disabling the toggle.
   pluginsLocked: 'Plugin "{{id}}" is locked by the host and cannot be toggled.',
   pluginsExtensionLocked: 'Extension "{{bundleId}}/{{extensionId}}" is locked by the host and cannot be toggled.',
+  // 400 envelopes specific to the bulk `PATCH /api/plugins` endpoint.
+  // The single-id variants above still apply for per-entry validation
+  // (unknown id, granularity mismatch, lock); these cover the
+  // body-shape level.
+  pluginsChangesRequired: "Request body must include a `changes` array of `{ id, enabled }` entries.",
+  pluginsChangeMalformed: "Each entry in `changes` must have a string `id` and a boolean `enabled`.",
   // ---- preferences route (routes/preferences.ts) --------------------------
   //
   // GET / PATCH /api/preferences. The PATCH body is shaped
@@ -17576,11 +18286,7 @@ function registerConfigRoute(app, deps) {
   app.get("/api/config", (c) => {
     let loaded;
     try {
-      loaded = loadConfig({
-        scope: deps.options.scope,
-        cwd: deps.runtimeContext.cwd,
-        homedir: deps.runtimeContext.homedir
-      });
+      loaded = deps.configService.get();
     } catch (err) {
       throw new HTTPException(500, { message: formatErrorMessage(err) });
     }
@@ -18109,7 +18815,7 @@ async function groupContributionsByPath(rows) {
 import { HTTPException as HTTPException6 } from "hono/http-exception";
 function registerPluginsRoute(app, deps) {
   app.get("/api/plugins", async (c) => {
-    const resolveEnabled = await buildFreshResolver(deps);
+    const resolveEnabled = await buildFreshResolver2(deps);
     const items = listItems(deps, resolveEnabled);
     return c.json(
       buildListEnvelope({
@@ -18176,6 +18882,26 @@ function registerPluginsRoute(app, deps) {
     const body = await parsePatchBody(c.req.raw);
     return await persistAndProject(c, deps, qualified, body.enabled);
   });
+  app.patch("/api/plugins", async (c) => {
+    const changes = await parseBulkBody(c.req.raw);
+    for (const change of changes) {
+      const failure = validateBulkChange(change, deps);
+      if (failure !== null) {
+        return c.json(
+          {
+            ok: false,
+            error: {
+              code: failure.code,
+              message: failure.message,
+              details: { id: change.id }
+            }
+          },
+          failure.status
+        );
+      }
+    }
+    return await persistBulkAndProject(c, deps, changes);
+  });
 }
 function listItems(deps, resolveEnabled) {
   return [
@@ -18230,7 +18956,8 @@ function buildDiscoveredItem(plugin, deps, resolveEnabled) {
     source: classifyPluginSource(plugin.path, deps),
     granularity,
     ...optional,
-    ...bundleLocked ? { locked: true } : {}
+    ...bundleLocked ? { locked: true } : {},
+    ...plugin.status === "disabled" ? { startsAsDisabled: true } : {}
   };
 }
 function optionalDiscoveredFields(plugin, extensions) {
@@ -18300,10 +19027,26 @@ async function persistAndProject(c, deps, configKey, enabled) {
   const overrides = await tryWithSqlite(
     { databasePath: deps.options.dbPath, autoBackup: false },
     async (adapter) => {
-      await adapter.pluginConfig.set(configKey, enabled);
+      await applyChangeToAdapter(adapter, configKey, enabled);
       return await adapter.pluginConfig.loadOverrideMap();
     }
   );
+  return projectListResponse(c, deps, overrides);
+}
+async function applyChangeToAdapter(adapter, configKey, enabled) {
+  await adapter.pluginConfig.set(configKey, enabled);
+  if (enabled) return;
+  const slash = configKey.indexOf("/");
+  if (slash < 0) {
+    await adapter.contributions.purgeByPlugin(configKey);
+    return;
+  }
+  await adapter.contributions.purgeByPlugin(
+    configKey.slice(0, slash),
+    configKey.slice(slash + 1)
+  );
+}
+function projectListResponse(c, deps, overrides) {
   if (overrides === null) {
     return c.json(
       {
@@ -18317,7 +19060,7 @@ async function persistAndProject(c, deps, configKey, enabled) {
       500
     );
   }
-  const freshResolver = composeResolver(deps, overrides);
+  const freshResolver = composeResolver2(deps, overrides);
   const items = listItems(deps, freshResolver);
   return c.json(
     buildListEnvelope({
@@ -18330,21 +19073,119 @@ async function persistAndProject(c, deps, configKey, enabled) {
     })
   );
 }
-async function buildFreshResolver(deps) {
+async function parseBulkBody(req) {
+  let raw;
+  try {
+    raw = await req.json();
+  } catch {
+    throw new HTTPException6(400, { message: SERVER_TEXTS.pluginsBodyNotJson });
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new HTTPException6(400, { message: SERVER_TEXTS.pluginsBodyNotObject });
+  }
+  const obj = raw;
+  const changes = obj["changes"];
+  if (!Array.isArray(changes)) {
+    throw new HTTPException6(400, { message: SERVER_TEXTS.pluginsChangesRequired });
+  }
+  const out = [];
+  for (const entry of changes) {
+    if (!isWellShapedBulkEntry(entry)) {
+      throw new HTTPException6(400, { message: SERVER_TEXTS.pluginsChangeMalformed });
+    }
+    out.push({
+      id: entry.id,
+      enabled: entry.enabled
+    });
+  }
+  return out;
+}
+function isWellShapedBulkEntry(entry) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return false;
+  const obj = entry;
+  return typeof obj["id"] === "string" && typeof obj["enabled"] === "boolean";
+}
+function validateBulkChange(change, deps) {
+  const slash = change.id.indexOf("/");
+  if (slash < 0) {
+    const handle2 = findHandle(change.id, deps);
+    if (!handle2) {
+      return {
+        status: 404,
+        code: "not-found",
+        message: tx(SERVER_TEXTS.pluginsUnknown, { id: change.id })
+      };
+    }
+    if (granularityOf(handle2) !== "bundle") {
+      return {
+        status: 400,
+        code: "bad-query",
+        message: tx(SERVER_TEXTS.pluginsGranularityExtensionExpected, { id: change.id })
+      };
+    }
+    if (isPluginLocked(change.id)) {
+      return {
+        status: 403,
+        code: "locked",
+        message: tx(SERVER_TEXTS.pluginsLocked, { id: change.id })
+      };
+    }
+    return null;
+  }
+  const bundleId = change.id.slice(0, slash);
+  const extensionId = change.id.slice(slash + 1);
+  const handle = findHandle(bundleId, deps);
+  if (!handle) {
+    return {
+      status: 404,
+      code: "not-found",
+      message: tx(SERVER_TEXTS.pluginsUnknown, { id: bundleId })
+    };
+  }
+  if (granularityOf(handle) !== "extension") {
+    return {
+      status: 400,
+      code: "bad-query",
+      message: tx(SERVER_TEXTS.pluginsGranularityBundleExpected, { id: bundleId })
+    };
+  }
+  if (!hasExtension(handle, extensionId)) {
+    return {
+      status: 404,
+      code: "not-found",
+      message: tx(SERVER_TEXTS.pluginsExtensionUnknown, { bundleId, extensionId })
+    };
+  }
+  if (isPluginLocked(change.id) || isPluginLocked(bundleId)) {
+    return {
+      status: 403,
+      code: "locked",
+      message: tx(SERVER_TEXTS.pluginsExtensionLocked, { bundleId, extensionId })
+    };
+  }
+  return null;
+}
+async function persistBulkAndProject(c, deps, changes) {
   const overrides = await tryWithSqlite(
     { databasePath: deps.options.dbPath, autoBackup: false },
-    async (adapter) => adapter.pluginConfig.loadOverrideMap()
+    async (adapter) => {
+      for (const change of changes) {
+        await applyChangeToAdapter(adapter, change.id, change.enabled);
+      }
+      return await adapter.pluginConfig.loadOverrideMap();
+    }
   );
-  if (overrides === null) return deps.pluginRuntime.resolveEnabled;
-  return composeResolver(deps, overrides);
+  return projectListResponse(c, deps, overrides);
 }
-function composeResolver(deps, overrides) {
-  const { effective: cfg } = loadConfig({
-    scope: deps.options.scope,
-    cwd: deps.runtimeContext.cwd,
-    homedir: deps.runtimeContext.homedir
+async function buildFreshResolver2(deps) {
+  return buildFreshResolver({
+    databasePath: deps.options.dbPath,
+    effectiveConfig: () => deps.configService.effective(),
+    fallbackResolver: deps.pluginRuntime.resolveEnabled
   });
-  return makeEnabledResolver(cfg, overrides);
+}
+function composeResolver2(deps, overrides) {
+  return composeResolver(deps.configService.effective(), overrides);
 }
 function findHandle(id, deps) {
   const builtIn = builtInBundles.find((b) => b.id === id);
@@ -18387,6 +19228,7 @@ function buildEnvelope(deps) {
   };
 }
 function applyPatch(deps, body) {
+  let wrote = false;
   if (body.updateCheck && typeof body.updateCheck.enabled === "boolean") {
     try {
       writeConfigValue("updateCheck.enabled", body.updateCheck.enabled, {
@@ -18394,6 +19236,7 @@ function applyPatch(deps, body) {
         cwd: deps.runtimeContext.cwd,
         homedir: deps.runtimeContext.homedir
       });
+      wrote = true;
     } catch (err) {
       throw new HTTPException7(400, {
         message: tx(SERVER_TEXTS.preferencesPersistFailed, {
@@ -18402,6 +19245,7 @@ function applyPatch(deps, body) {
       });
     }
   }
+  if (wrote) deps.configService.reload();
 }
 async function parsePatchBody2(req) {
   const obj = await readJsonObject(req);
@@ -18496,7 +19340,7 @@ function applyPatch2(deps, body) {
   }
   for (const w of writes) {
     try {
-      writeConfigValue(w.key, w.value, { target: "project", cwd, homedir: homedir4 });
+      writeConfigValue(w.key, w.value, { target: "project-local", cwd, homedir: homedir4 });
     } catch (err) {
       const status = err instanceof ConfigValidationError ? 400 : 400;
       throw new HTTPException8(status, {
@@ -18507,6 +19351,7 @@ function applyPatch2(deps, body) {
       });
     }
   }
+  deps.configService.reload();
 }
 function collectWrites(body) {
   if (!body.scan) return [];
@@ -18732,6 +19577,7 @@ async function runPersistedScan(c, deps) {
   }
   try {
     return await withScanMutex(async () => {
+      const resolveEnabledOverride = await buildBffResolverOverride(deps);
       const outcome = await runScanForCommand({
         roots: [deps.runtimeContext.cwd],
         noBuiltIns: deps.options.noBuiltIns,
@@ -18744,6 +19590,7 @@ async function runPersistedScan(c, deps) {
         stderr: process.stderr,
         ctx: deps.runtimeContext,
         pluginRuntime: deps.pluginRuntime,
+        resolveEnabledOverride,
         printer: bffScanRunnerPrinter,
         emitterFactory: () => buildBroadcasterEmitter(deps.broadcaster)
       });
@@ -18761,6 +19608,13 @@ async function runPersistedScan(c, deps) {
     throw err;
   }
 }
+async function buildBffResolverOverride(deps) {
+  return buildFreshResolver({
+    databasePath: deps.options.dbPath,
+    effectiveConfig: () => deps.configService.effective(),
+    fallbackResolver: deps.pluginRuntime.resolveEnabled
+  });
+}
 async function loadPersistedScan(deps) {
   const opened = await tryWithSqlite(
     { databasePath: deps.options.dbPath, autoBackup: false },
@@ -18815,6 +19669,7 @@ async function runFreshScan(deps) {
   if (deps.options.noBuiltIns || deps.options.noPlugins) {
     throw new HTTPException9(400, { message: SERVER_TEXTS.freshScanRequiresPipeline });
   }
+  const resolveEnabledOverride = await buildBffResolverOverride(deps);
   const outcome = await runScanForCommand({
     roots: [deps.runtimeContext.cwd],
     noBuiltIns: deps.options.noBuiltIns,
@@ -18833,6 +19688,7 @@ async function runFreshScan(deps) {
     // discovering new plugins here would surface them in scan output
     // but not in `/api/plugins` or the kindRegistry).
     pluginRuntime: deps.pluginRuntime,
+    resolveEnabledOverride,
     // M8: explicit printer instead of the runner's old stdout=stderr
     // fallback. The fresh-scan response body IS the ScanResult JSON,
     // so `data` is never used here; warn/info/error route through
@@ -18912,12 +19768,20 @@ function registerSidecarRoutes(app, deps) {
     try {
       for (const w of result.writes ?? []) {
         if (w.kind === "sidecar") {
-          await store.applyPatch(w.path, w.changes);
+          await store.applyPatch(w.path, w.changes, {
+            confirm: body.confirm,
+            cwd: deps.runtimeContext.cwd,
+            homedir: deps.runtimeContext.homedir
+          });
         }
       }
     } catch (err) {
+      if (err instanceof EConsentRequiredError) throw err;
       throw new HTTPException10(500, { message: formatErrorMessage(err) });
     }
+    if (body.confirm === true) {
+      deps.configService.reload();
+    }
     const newVersion = result.report.version ?? null;
     const eventData = {
       nodePath: node.path,
@@ -18962,9 +19826,14 @@ async function parseBody(req) {
   if (forceRaw !== void 0 && typeof forceRaw !== "boolean") {
     throw new HTTPException10(400, { message: SERVER_TEXTS.sidecarForceMustBeBoolean });
   }
+  const confirmRaw = obj["confirm"];
+  if (confirmRaw !== void 0 && typeof confirmRaw !== "boolean") {
+    throw new HTTPException10(400, { message: SERVER_TEXTS.sidecarConfirmMustBeBoolean });
+  }
   return {
     nodePath: nodePathRaw,
-    force: forceRaw === true
+    force: forceRaw === true,
+    confirm: confirmRaw === true
   };
 }
 async function loadNode(deps, nodePath) {
@@ -19169,6 +20038,11 @@ function attachBroadcasterRoute(app, broadcaster) {
 // server/app.ts
 function createApp(deps) {
   const app = new Hono();
+  const configService = new ConfigService({
+    scope: deps.options.scope,
+    cwd: deps.runtimeContext.cwd,
+    homedir: deps.runtimeContext.homedir
+  });
   if (deps.options.devCors) {
     app.use("*", async (c, next) => {
       await next();
@@ -19188,7 +20062,8 @@ function createApp(deps) {
     runtimeContext: deps.runtimeContext,
     kindRegistry: deps.kindRegistry,
     contributionsRegistry: deps.contributionsRegistry,
-    pluginRuntime: deps.pluginRuntime
+    pluginRuntime: deps.pluginRuntime,
+    configService
   };
   registerScanRoute(app, { ...routeDeps, broadcaster: deps.broadcaster });
   registerNodesRoutes(app, routeDeps);
@@ -19257,6 +20132,17 @@ function formatError2(err, c) {
     };
     return c.json(envelope2, 400);
   }
+  if (err instanceof EConsentRequiredError) {
+    const envelope2 = {
+      ok: false,
+      error: {
+        code: "confirm-required",
+        message: err.message,
+        details: { key: err.key }
+      }
+    };
+    return c.json(envelope2, 412);
+  }
   const envelope = {
     ok: false,
     error: {
@@ -19696,50 +20582,64 @@ async function assembleBootBundle(options, runtimeContext) {
   for (const warn of pluginRuntime.warnings) {
     log.warn(sanitizeForTerminal(warn));
   }
-  const composed = composeScanExtensions({
-    noBuiltIns: options.noBuiltIns,
-    pluginRuntime
-  });
-  const kindRegistry = buildKindRegistry(composed?.providers ?? []);
+  const builtInProviders = options.noBuiltIns ? [] : collectBuiltInProviders();
+  const kindRegistry = buildKindRegistry([
+    ...builtInProviders,
+    ...pluginRuntime.extensions.providers
+  ]);
   const kernel = createKernel();
   kernel.setRegisteredAnnotationKeys(pluginRuntime.annotationContributions);
   const mergedViewContributions = mergeBuiltInViewContributions(
     pluginRuntime.viewContributions,
-    composed
+    options.noBuiltIns
   );
   kernel.setRegisteredViewContributions(mergedViewContributions);
   const contributionsRegistry = buildContributionsRegistry(kernel);
   return { pluginRuntime, kindRegistry, contributionsRegistry, kernel };
 }
-function mergeBuiltInViewContributions(userPluginContributions, composed) {
+function collectBuiltInProviders() {
+  const out = [];
+  for (const bundle of builtInBundles) {
+    for (const ext of bundle.extensions) {
+      if (ext.kind === "provider") {
+        out.push(ext);
+      }
+    }
+  }
+  return out;
+}
+function mergeBuiltInViewContributions(userPluginContributions, noBuiltIns) {
   const merged = [...userPluginContributions];
-  if (!composed) return merged;
+  if (noBuiltIns) return merged;
   const userKey = new Set(
     userPluginContributions.map(
       (c) => `${c.pluginId}/${c.extensionId}/${c.contributionId}`
     )
   );
-  for (const ext of [...composed.extractors, ...composed.analyzers]) {
-    const raw = ext.viewContributions;
-    if (typeof raw !== "object" || raw === null) continue;
-    for (const [contributionId, value] of Object.entries(raw)) {
-      if (typeof value !== "object" || value === null) continue;
-      const v = value;
-      if (typeof v.slot !== "string") continue;
-      const qualified = `${ext.pluginId}/${ext.id}/${contributionId}`;
-      if (userKey.has(qualified)) continue;
-      const entry = {
-        pluginId: ext.pluginId,
-        extensionId: ext.id,
-        contributionId,
-        slot: v.slot,
-        emitWhenEmpty: v.emitWhenEmpty === true
-      };
-      if (typeof v.label === "string") entry.label = v.label;
-      if (typeof v.tooltip === "string") entry.tooltip = v.tooltip;
-      if (typeof v.icon === "string") entry.icon = v.icon;
-      if (typeof v.emptyText === "string") entry.emptyText = v.emptyText;
-      merged.push(entry);
+  for (const bundle of builtInBundles) {
+    for (const ext of bundle.extensions) {
+      if (ext.kind !== "extractor" && ext.kind !== "analyzer") continue;
+      const raw = ext.viewContributions;
+      if (typeof raw !== "object" || raw === null) continue;
+      for (const [contributionId, value] of Object.entries(raw)) {
+        if (typeof value !== "object" || value === null) continue;
+        const v = value;
+        if (typeof v.slot !== "string") continue;
+        const qualified = `${ext.pluginId}/${ext.id}/${contributionId}`;
+        if (userKey.has(qualified)) continue;
+        const entry = {
+          pluginId: ext.pluginId,
+          extensionId: ext.id,
+          contributionId,
+          slot: v.slot,
+          emitWhenEmpty: v.emitWhenEmpty === true
+        };
+        if (typeof v.label === "string") entry.label = v.label;
+        if (typeof v.tooltip === "string") entry.tooltip = v.tooltip;
+        if (typeof v.icon === "string") entry.icon = v.icon;
+        if (typeof v.emptyText === "string") entry.emptyText = v.emptyText;
+        merged.push(entry);
+      }
     }
   }
   return merged;
@@ -20579,10 +21479,9 @@ function rankConfidenceForGrouping(c) {
 }
 
 // cli/commands/sidecar.ts
-import { existsSync as existsSync26, unlinkSync as unlinkSync3, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync26, unlinkSync as unlinkSync3 } from "fs";
 import { resolve as resolve30 } from "path";
 import { Command as Command23, Option as Option23 } from "clipanion";
-import yaml5 from "js-yaml";
 
 // cli/i18n/sidecar.texts.ts
 var SIDECAR_TEXTS = {
@@ -20610,10 +21509,51 @@ 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"
+  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 \u2014 gitignored)."
 };
 
 // cli/commands/sidecar.ts
+async function runWithSidecarConsent(bag, ansi, dispatch) {
+  try {
+    return await dispatch();
+  } catch (err) {
+    if (!(err instanceof EConsentRequiredError)) throw err;
+    const isTTY = bag.stdin.isTTY === true;
+    if (!isTTY || bag.yes) {
+      const errGlyph = ansi.red("\u2715");
+      bag.printError(
+        tx(SIDECAR_TEXTS.consentRequiredNonTty, {
+          glyph: errGlyph,
+          hint: ansi.dim(SIDECAR_TEXTS.consentRequiredNonTtyHint)
+        })
+      );
+      return ExitCode.Error;
+    }
+    const ok = await confirm(
+      SIDECAR_TEXTS.consentPrompt,
+      { stdin: bag.stdin, stderr: bag.stderr },
+      { defaultAnswer: "yes" }
+    );
+    if (!ok) {
+      bag.printInfo(
+        tx(SIDECAR_TEXTS.consentAborted, { glyph: ansi.cyan("\u2139") })
+      );
+      return ExitCode.Error;
+    }
+    bag.onAccept();
+    return await dispatch();
+  }
+}
 var SidecarRefreshCommand = class extends SmCommand {
   static paths = [["sidecar", "refresh"]];
   static usage = Command23.Usage({
@@ -20634,9 +21574,9 @@ var SidecarRefreshCommand = class extends SmCommand {
     ]
   });
   nodePath = Option23.String({ required: true });
-  // Complexity is from CLI ergonomics: db-load / not-found / abs-path
-  // / no-sidecar / fresh / write-error / json-vs-pretty branches.
-  // eslint-disable-next-line complexity
+  yes = Option23.Boolean("--yes", false, {
+    description: "Confirm writing .sm sidecar files in this project (sets allowEditSmFiles=true on first run)."
+  });
   async run() {
     const ctx = defaultRuntimeContext();
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...ctx });
@@ -20644,6 +21584,27 @@ var SidecarRefreshCommand = class extends SmCommand {
     const ansi = ansiFor({ isTTY: stdout.isTTY === true, noColorFlag: this.noColor });
     const okGlyph = ansi.green("\u2713");
     const errGlyph = ansi.red("\u2715");
+    return runWithSidecarConsent(
+      {
+        stdin: this.context.stdin,
+        stderr: this.context.stderr,
+        yes: this.yes,
+        onAccept: () => {
+          this.yes = true;
+        },
+        printInfo: (s) => this.printer.info(s),
+        printError: (s) => this.printer.error(s)
+      },
+      ansi,
+      () => this.#runOnce(ctx, dbPath, okGlyph, errGlyph, ansi)
+    );
+  }
+  // Inner dispatch — single attempt. The outer `run()` wraps every
+  // call in `runWithSidecarConsent` so an `EConsentRequiredError`
+  // surfaces as an interactive prompt (TTY) or a directed exit
+  // (non-TTY).
+  // eslint-disable-next-line complexity
+  async #runOnce(ctx, dbPath, okGlyph, errGlyph, ansi) {
     const persisted = await tryWithSqlite(
       { databasePath: dbPath, autoBackup: false },
       async (adapter) => adapter.scans.load()
@@ -20698,14 +21659,19 @@ var SidecarRefreshCommand = class extends SmCommand {
     }
     const store = new FilesystemSidecarStore();
     try {
-      await store.applyPatch(sidecarAbsPath, {
-        identity: {
-          path: node.path,
-          bodyHash: node.bodyHash,
-          frontmatterHash: node.frontmatterHash
-        }
-      });
+      await store.applyPatch(
+        sidecarAbsPath,
+        {
+          identity: {
+            path: node.path,
+            bodyHash: node.bodyHash,
+            frontmatterHash: node.frontmatterHash
+          }
+        },
+        { confirm: this.yes, cwd: ctx.cwd, homedir: ctx.homedir }
+      );
     } catch (err) {
+      if (err instanceof EConsentRequiredError) throw err;
       this.printer.error(
         tx(SIDECAR_TEXTS.refreshFailed, { glyph: errGlyph, message: formatErrorMessage(err) })
       );
@@ -20892,12 +21858,32 @@ var SidecarAnnotateCommand = class extends SmCommand {
   });
   nodePath = Option23.String({ required: true });
   force = Option23.Boolean("--force", false);
+  yes = Option23.Boolean("--yes", false, {
+    description: "Confirm writing .sm sidecar files in this project (sets allowEditSmFiles=true on first run)."
+  });
   async run() {
     const ctx = defaultRuntimeContext();
     const dbPath = resolveDbPath({ global: this.global, db: this.db, ...ctx });
     const stdout = this.context.stdout;
     const ansi = ansiFor({ isTTY: stdout.isTTY === true, noColorFlag: this.noColor });
     const errGlyph = ansi.red("\u2715");
+    return runWithSidecarConsent(
+      {
+        stdin: this.context.stdin,
+        stderr: this.context.stderr,
+        yes: this.yes,
+        onAccept: () => {
+          this.yes = true;
+        },
+        printInfo: (s) => this.printer.info(s),
+        printError: (s) => this.printer.error(s)
+      },
+      ansi,
+      () => this.#runOnce(ctx, dbPath, errGlyph, ansi)
+    );
+  }
+  // eslint-disable-next-line complexity
+  async #runOnce(ctx, dbPath, errGlyph, ansi) {
     const persisted = await tryWithSqlite(
       { databasePath: dbPath, autoBackup: false },
       async (adapter) => adapter.scans.load()
@@ -20944,10 +21930,25 @@ var SidecarAnnotateCommand = class extends SmCommand {
       );
       return ExitCode.Error;
     }
-    const scaffold = scaffoldSidecar(node);
+    if (existsSync26(sidecarAbsPath) && this.force === true) {
+      try {
+        unlinkSync3(sidecarAbsPath);
+      } catch (err) {
+        this.printer.error(
+          tx(SIDECAR_TEXTS.annotateFailed, { glyph: errGlyph, message: formatErrorMessage(err) })
+        );
+        return ExitCode.Error;
+      }
+    }
+    const store = new FilesystemSidecarStore();
     try {
-      writeFileSync5(sidecarAbsPath, scaffold, { encoding: "utf8" });
+      await store.applyPatch(
+        sidecarAbsPath,
+        scaffoldSidecarObject(node),
+        { confirm: this.yes, cwd: ctx.cwd, homedir: ctx.homedir }
+      );
     } catch (err) {
+      if (err instanceof EConsentRequiredError) throw err;
       this.printer.error(
         tx(SIDECAR_TEXTS.annotateFailed, { glyph: errGlyph, message: formatErrorMessage(err) })
       );
@@ -20973,8 +21974,8 @@ var SidecarAnnotateCommand = class extends SmCommand {
     return ExitCode.Ok;
   }
 };
-function scaffoldSidecar(node) {
-  const root = {
+function scaffoldSidecarObject(node) {
+  return {
     identity: {
       bodyHash: node.bodyHash,
       frontmatterHash: node.frontmatterHash,
@@ -20982,14 +21983,6 @@ function scaffoldSidecar(node) {
     },
     annotations: {}
   };
-  const body = yaml5.dump(root, {
-    sortKeys: true,
-    lineWidth: -1,
-    noRefs: true,
-    noCompatMode: true
-  });
-  const banner = "# Skill-map sidecar \u2014 managed artifact.\n# Comments in .sm are NOT preserved across `sm bump` (the bump action\n# re-serialises the file). Narrative / docs \u2192 the .md body, which is\n# never touched. See spec/cli-contract.md \xA7Sidecar bump for the\n# round-trip contract.\n\n";
-  return banner + body;
 }
 var SIDECAR_COMMANDS = [
   SidecarRefreshCommand,