@skill-map/spec 0.22.0 → 0.24.0

package/schemas/history-stats.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/history-stats.schema.json",
   "title": "HistoryStats",
-  "description": "Machine-readable output of `sm history stats --json`. Aggregates over `state_executions` within a time window. camelCase keys throughout. The `elapsedMs` top-level field is the command's own wall-clock (see `cli-contract.md` §Elapsed time) — distinct from `totals.durationMsTotal`, which is the sum of every execution record's duration.",
+  "description": "Machine-readable output of `sm history stats --json`. Aggregates over `state_executions` within a time window. camelCase keys throughout. The `elapsedMs` top-level field is the command's own wall-clock (see `cli-contract.md` §Elapsed time), distinct from `totals.durationMsTotal`, which is the sum of every execution record's duration.",
   "type": "object",
   "required": [
     "schemaVersion",
@@ -28,7 +28,7 @@
         "since": {
           "type": ["string", "null"],
           "format": "date-time",
-          "description": "Inclusive lower bound (ISO-8601). `null` means all-time — the earliest execution record is used."
+          "description": "Inclusive lower bound (ISO-8601). `null` means all-time, the earliest execution record is used."
         },
         "until": {
           "type": "string",
@@ -54,7 +54,7 @@
         "failedCount":     { "type": "integer", "minimum": 0 },
         "tokensIn":        { "type": "integer", "minimum": 0, "description": "Sum of `state_executions.tokens_in`. `null` values in the source are treated as 0." },
         "tokensOut":       { "type": "integer", "minimum": 0 },
-        "durationMsTotal": { "type": "integer", "minimum": 0, "description": "Sum of every execution's `duration_ms`. NOT the command's wall-clock — see `elapsedMs`." }
+        "durationMsTotal": { "type": "integer", "minimum": 0, "description": "Sum of every execution's `duration_ms`. NOT the command's wall-clock, see `elapsedMs`." }
       }
     },
     "tokensPerAction": {
@@ -142,7 +142,7 @@
         },
         "perFailureReason": {
           "type": "object",
-          "description": "Counts (not ratios) per failure reason. Every enum value of `state_executions.failure_reason` appears, with `0` when no occurrences — predictable shape for dashboards.",
+          "description": "Counts (not ratios) per failure reason. Every enum value of `state_executions.failure_reason` appears, with `0` when no occurrences, predictable shape for dashboards.",
           "required": [
             "runner-error",
             "report-invalid",

package/schemas/input-types.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/input-types.schema.json",
   "title": "InputTypes",
-  "description": "Closed catalog of input-types for plugin settings. The plugin author declares each user-configurable setting in the manifest's `settings` map by picking an `input-type` from this catalog; the kernel knows the schema for each type, the UI ships a generated form per type, and the CLI's `sm plugins config <id>` command exposes the same surface. Plugin authors NEVER write JSON Schema for settings — they pick a type by name and supply per-type parameters (label, default, min/max, options for enums, etc.). Closed catalog by design: every new input-type requires spec + UI form + CLI prompter + tests. Versioned via the manifest field `catalogCompat` (semver against the catalog as a whole). For the rationale and open issues, see ROADMAP.md §UI contribution system.",
+  "description": "Closed catalog of input-types for plugin settings. The plugin author declares each user-configurable setting in the manifest's `settings` map by picking an `input-type` from this catalog; the kernel knows the schema for each type, the UI ships a generated form per type, and the CLI's `sm plugins config <id>` command exposes the same surface. Plugin authors NEVER write JSON Schema for settings, they pick a type by name and supply per-type parameters (label, default, min/max, options for enums, etc.). Closed catalog by design: every new input-type requires spec + UI form + CLI prompter + tests. Versioned via the manifest field `catalogCompat` (semver against the catalog as a whole). For the rationale and open issues, see ROADMAP.md §UI contribution system.",
   "type": "object",
   "$defs": {
     "InputTypeName": {
@@ -22,7 +22,7 @@
       "description": "Closed enum of input-type identifiers. Adding an entry requires the full spec/UI/CLI/tests round-trip. Removing or renaming an entry is a catalog-major-bump and triggers `sm plugins upgrade` migration."
     },
     "ISettingDeclaration": {
-      "description": "Manifest-side declaration of a single setting, keyed in `IPluginManifest.settings[<settingId>]`. Discriminated by `type`; per-type parameters live in the `oneOf` branches below. The plugin author NEVER writes JSON Schema — `type` is a name from `InputTypeName`, the kernel validates the user-supplied value against the per-type value schema.",
+      "description": "Manifest-side declaration of a single setting, keyed in `IPluginManifest.settings[<settingId>]`. Discriminated by `type`; per-type parameters live in the `oneOf` branches below. The plugin author NEVER writes JSON Schema, `type` is a name from `InputTypeName`, the kernel validates the user-supplied value against the per-type value schema.",
       "oneOf": [
         { "$ref": "#/$defs/Setting_StringList" },
         { "$ref": "#/$defs/Setting_SingleString" },
@@ -206,7 +206,7 @@
           "type": "string",
           "pattern": "^[gimsuy]*$",
           "default": "",
-          "description": "ECMAScript regex flags allowed. Subset: `g`, `i`, `m`, `s`, `u`, `y`. Author chooses which flags the user-supplied pattern compiles with — the user supplies only the body."
+          "description": "ECMAScript regex flags allowed. Subset: `g`, `i`, `m`, `s`, `u`, `y`. Author chooses which flags the user-supplied pattern compiles with, the user supplies only the body."
         }
       },
       "description": "ECMAScript regex pattern (the body, no `/` delimiters). Validated by attempting `new RegExp(value, flags)` at form submit and at extractor invocation. Compilation failure → form error / `invalid-settings` at runtime. Value type at runtime: `string`."

package/schemas/issue.schema.json

@@ -38,7 +38,7 @@
     },
     "fix": {
       "type": ["object", "null"],
-      "description": "Machine-readable fix hint. Stability: experimental — shape may change before v1.",
+      "description": "Machine-readable fix hint. Stability: experimental, shape may change before v1.",
       "additionalProperties": false,
       "properties": {
         "summary": { "type": "string" },

package/schemas/job.schema.json

@@ -30,7 +30,7 @@
     },
     "nonce": {
       "type": "string",
-      "description": "Unique per-job token. `sm record` requires it to close the job — mismatch rejects with exit code 4."
+      "description": "Unique per-job token. `sm record` requires it to close the job, mismatch rejects with exit code 4."
     },
     "priority": {
       "type": "integer",
@@ -45,7 +45,7 @@
     "failureReason": {
       "type": ["string", "null"],
       "enum": ["runner-error", "report-invalid", "timeout", "abandoned", "job-file-missing", "user-cancelled", null],
-      "description": "Populated when `status = failed`. `job-file-missing` (legacy name preserved across the disk-to-DB shift) covers DB corruption where `state_jobs.content_hash` no longer resolves in `state_job_contents` — the runtime invariant should keep this state unreachable; the enum value exists as a defensive failure-mode label."
+      "description": "Populated when `status = failed`. `job-file-missing` (legacy name preserved across the disk-to-DB shift) covers DB corruption where `state_jobs.content_hash` no longer resolves in `state_job_contents`, the runtime invariant should keep this state unreachable; the enum value exists as a defensive failure-mode label."
     },
     "runner": {
       "type": ["string", "null"],

package/schemas/node.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/node.schema.json",
   "title": "Node",
-  "description": "A single markdown file in the graph. Identified by its relative path from the scope root. The `kind` is whatever the classifying Provider declares — open by design; the **built-in Claude Provider** emits `skill` / `agent` / `command` / `markdown` today, but external Providers (Cursor, Obsidian, …) MAY emit their own. Format-named kinds (`markdown`, future `toml`, future `json`) are reserved for the generic fallback only — when a file matches a specific role (agent / command / skill) that classification prevails over format naming.",
+  "description": "A single markdown file in the graph. Identified by its relative path from the scope root. The `kind` is whatever the classifying Provider declares, open by design; the **built-in Claude Provider** emits `skill` / `agent` / `command` / `markdown` today, but external Providers (Cursor, Obsidian, …) MAY emit their own. Format-named kinds (`markdown`, future `toml`, future `json`) are reserved for the generic fallback only, when a file matches a specific role (agent / command / skill) that classification prevails over format naming.",
   "type": "object",
   "required": ["path", "kind", "provider", "bodyHash", "frontmatterHash", "bytes", "linksOutCount", "linksInCount", "externalRefsCount"],
   "additionalProperties": false,
@@ -14,7 +14,8 @@
     "kind": {
       "type": "string",
       "minLength": 1,
-      "description": "Category assigned by the Provider. Open-by-design — any non-empty string an enabled Provider declares is valid (built-in Claude Provider catalog: `skill` / `agent` / `command` / `markdown`; external Providers MAY declare their own). Per-kind frontmatter schemas live with the Provider that emits the kind. Stability: stable."
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$",
+      "description": "Category assigned by the Provider. Open-by-design, any non-empty string an enabled Provider declares is valid (built-in Claude Provider catalog: `skill` / `agent` / `command` / `markdown`; external Providers MAY declare their own). The pattern restricts kind names to ASCII letters, digits, underscore, and hyphen, starting with a letter, up to 64 chars. The restriction is a security boundary: the UI uses the kind name as a fragment of CSS custom-property identifiers (`--sm-kind-<name>`) injected into a `<style>` tag, so values that would break out of the declaration context (semicolons, braces, whitespace) MUST be rejected at the kernel boundary. Per-kind frontmatter schemas live with the Provider that emits the kind. Stability: stable."
     },
     "provider": {
       "type": "string",
@@ -60,11 +61,11 @@
     },
     "sidecar": {
       "$ref": "#/$defs/sidecarOverlay",
-      "description": "Step 9.6.2 — co-located `.sm` sidecar overlay. Carries presence flag, drift status (null when no sidecar), and the parsed `annotations:` block (null when absent or empty). The kernel re-derives `status` on every scan from the live hashes; clients should treat it as authoritative for the snapshot but never persist it across scans."
+      "description": "Step 9.6.2, co-located `.sm` sidecar overlay. Carries presence flag, drift status (null when no sidecar), and the parsed `annotations:` block (null when absent or empty). The kernel re-derives `status` on every scan from the live hashes; clients should treat it as authoritative for the snapshot but never persist it across scans."
     },
     "isFavorite": {
       "type": "boolean",
-      "description": "Per-node favorite flag set by the local user from the UI. Sourced from `state_node_favorites` (zone `state_`, persistent across scans). Decorated by the BFF on every `/api/nodes` response via in-memory Set lookup against the favorites table — no SQL JOIN against `scan_nodes`. Absent on emissions that don't carry per-user state (e.g. `sm export --json`); consumers that don't recognise the field MUST ignore it."
+      "description": "Per-node favorite flag set by the local user from the UI. Sourced from `state_node_favorites` (zone `state_`, persistent across scans). Decorated by the BFF on every `/api/nodes` response via in-memory Set lookup against the favorites table, no SQL JOIN against `scan_nodes`. Absent on emissions that don't carry per-user state (e.g. `sm export --json`); consumers that don't recognise the field MUST ignore it."
     }
   },
   "$defs": {
@@ -100,7 +101,7 @@
         "root": {
           "type": ["object", "null"],
           "additionalProperties": true,
-          "description": "Parsed YAML root of the matching `.sm` sidecar. Mirrors the shape of `sidecar.schema.json` (top-level reserved blocks `identity` / `annotations` / `settings` / `audit` plus opt-in `<plugin-id>:` namespaces). Surfaced for the UI inspector's audit panel, plugin-contributions panel, and debug panel; NULL when the sidecar is absent or failed to parse. Note the duplication with `annotations` at this overlay level — existing consumers read from `annotations`, new consumers read structured sub-fields off `root` (`root.identity.*`, `root.audit.*`, etc.). The duplication is intentional and documented; do NOT remove the top-level `annotations` field."
+          "description": "Parsed YAML root of the matching `.sm` sidecar. Mirrors the shape of `sidecar.schema.json` (top-level reserved blocks `identity` / `annotations` / `settings` / `audit` plus opt-in `<plugin-id>:` namespaces). Surfaced for the UI inspector's audit panel, plugin-contributions panel, and debug panel; NULL when the sidecar is absent or failed to parse. Note the duplication with `annotations` at this overlay level, existing consumers read from `annotations`, new consumers read structured sub-fields off `root` (`root.identity.*`, `root.audit.*`, etc.). The duplication is intentional and documented; do NOT remove the top-level `annotations` field."
         }
       }
     }

package/schemas/plugins-doctor.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/plugins-doctor.schema.json",
+  "title": "PluginsDoctorReport",
+  "description": "Machine-readable output of `sm plugins doctor --json`. Aggregates per-status counts across built-in and drop-in plugins plus the structured issue / warning lists the human renderer produces. The `elapsedMs` top-level field is the command's own wall-clock (see `cli-contract.md` §Elapsed time).",
+  "type": "object",
+  "required": ["ok", "kind", "counts", "issues", "warnings", "elapsedMs"],
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "const": true,
+      "description": "Always `true` on the happy path. Error envelopes use the shared `{ ok: false, error: { code, message } }` shape from `cli-contract.md` §Error envelope and do NOT carry this schema's other fields. A doctor run that surfaces issues still returns `ok: true` (the verb succeeded; the issues live under `issues[]` and gate the exit code)."
+    },
+    "kind": {
+      "type": "string",
+      "const": "plugins.doctor",
+      "description": "Discriminator pinning this envelope to the plugins-doctor verb."
+    },
+    "counts": {
+      "type": "object",
+      "required": ["enabled", "disabled", "loaded", "incompatible", "invalid", "loadError", "warnings"],
+      "additionalProperties": false,
+      "description": "Aggregate counts across both built-in and drop-in plugins. `loaded` is the count of plugins whose runtime imported cleanly (status=enabled); `incompatible` folds the `incompatible-spec` and `incompatible-catalog` buckets; `invalid` is `invalid-manifest`; `loadError` is `load-error` + `id-collision`. The split mirrors the human table without committing to its label catalog.",
+      "properties": {
+        "enabled": { "type": "integer", "minimum": 0 },
+        "disabled": { "type": "integer", "minimum": 0 },
+        "loaded": { "type": "integer", "minimum": 0 },
+        "incompatible": { "type": "integer", "minimum": 0 },
+        "invalid": { "type": "integer", "minimum": 0 },
+        "loadError": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "issues": {
+      "type": "array",
+      "description": "One entry per plugin in a non-success state (`incompatible-spec`, `incompatible-catalog`, `invalid-manifest`, `load-error`, `id-collision`). Empty when every plugin is `enabled` or intentionally `disabled`. Iteration order matches the human renderer.",
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "reason"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Plugin id (bundle granularity) or qualified id (`<bundle>/<ext>`) for extension granularity."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "incompatible-spec",
+              "incompatible-catalog",
+              "invalid-manifest",
+              "load-error",
+              "id-collision"
+            ],
+            "description": "Failure mode. Matches the `IDiscoveredPlugin.status` enum minus `enabled` / `disabled` (those never land in `issues[]`)."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Sanitised human-readable explanation. May be empty when the loader supplied none."
+          }
+        }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "description": "Informational warnings that do NOT gate the exit code: `applicable-kind-unknown` (an extractor declares a `applicableKinds` referencing a kind no Provider emits) and `unknown-slot` (a view contribution targets a slot id absent from the closed catalog). Iteration order matches the human renderer.",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Qualified extension id (`<plugin>/<ext>`) for `applicable-kind-unknown`, or `<plugin>/<ext>/<contributionId>` for `unknown-slot`."
+          },
+          "kind": {
+            "type": "string",
+            "enum": ["applicable-kind-unknown", "unknown-slot"],
+            "description": "Warning discriminator."
+          },
+          "message": {
+            "type": "string",
+            "description": "Sanitised human-readable explanation."
+          }
+        }
+      }
+    },
+    "elapsedMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Command's own wall-clock duration in milliseconds (see `cli-contract.md` §Elapsed time)."
+    }
+  }
+}

package/schemas/plugins-registry.schema.json

@@ -44,7 +44,7 @@
           "type": "string",
           "enum": ["bundle", "extension"],
           "default": "bundle",
-          "description": "Toggle granularity for this plugin. `bundle` (default) — the plugin id is the only enable/disable key; the whole set of extensions follows the toggle. `extension` — each extension is independently toggle-able under its qualified id `<plugin-id>/<extension-id>`. Built-in bundles use the same field: the `claude` bundle is `bundle` (the Provider and its kind-aware extractors form a coherent provider); the `core` bundle is `extension` (every kernel built-in is removable per the spec promise that no extension is privileged). Plugin authors should keep the default unless their plugin ships several orthogonal capabilities a user might reasonably want piecemeal."
+          "description": "Toggle granularity for this plugin. `bundle` (default), the plugin id is the only enable/disable key; the whole set of extensions follows the toggle. `extension`, each extension is independently toggle-able under its qualified id `<plugin-id>/<extension-id>`. Built-in bundles use the same field: the `claude` bundle is `bundle` (the Provider and its kind-aware extractors form a coherent provider); the `core` bundle is `extension` (every kernel built-in is removable per the spec promise that no extension is privileged). Plugin authors should keep the default unless their plugin ships several orthogonal capabilities a user might reasonably want piecemeal."
         },
         "storage": {
           "type": "object",
@@ -83,7 +83,7 @@
           "propertyNames": {
             "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
           },
-          "description": "Plugin user-configurable settings. Each entry picks an `input-type` from the closed catalog at `input-types.schema.json#/$defs/InputTypeName`. The plugin author NEVER writes JSON Schema for settings — they pick by `type` name and provide per-type parameters (label, default, min/max, options for enums, etc.). The kernel exposes the resolved settings to extractors via `ctx.settings.<settingId>` (or via the runtime as `IPluginSettings`); the UI generates a form per declaration; the CLI's `sm plugins config <id>` exposes the same surface. Settings are read once at extractor invocation; changing a setting requires `sm scan` to re-emit (per ROADMAP.md decision D4)."
+          "description": "Plugin user-configurable settings. Each entry picks an `input-type` from the closed catalog at `input-types.schema.json#/$defs/InputTypeName`. The plugin author NEVER writes JSON Schema for settings, they pick by `type` name and provide per-type parameters (label, default, min/max, options for enums, etc.). The kernel exposes the resolved settings to extractors via `ctx.settings.<settingId>` (or via the runtime as `IPluginSettings`); the UI generates a form per declaration; the CLI's `sm plugins config <id>` exposes the same surface. Settings are read once at extractor invocation; changing a setting requires `sm scan` to re-emit (per ROADMAP.md decision D4)."
         },
         "author": { "type": "string" },
         "license": { "type": "string", "description": "SPDX identifier." },

package/schemas/project-config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/project-config.schema.json",
   "title": "ProjectConfig",
-  "description": "Shape of `.skill-map/settings.json` (and its `.skill-map/settings.local.json` partner) inside a scope. Loaded by the layered config hierarchy (library defaults → user → user-local → project → project-local → env/flags) and deep-merged per key. All fields optional; defaults apply when absent. camelCase keys throughout — consistent with the rest of the spec.",
+  "description": "Shape of `.skill-map/settings.json` (and its `.skill-map/settings.local.json` partner) inside a scope. Loaded by the layered config hierarchy (library defaults → user → user-local → project → project-local → env/flags) and deep-merged per key. All fields optional; defaults apply when absent. camelCase keys throughout, consistent with the rest of the spec.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -54,19 +54,19 @@
             "debounceMs": {
               "type": "integer",
               "minimum": 0,
-              "description": "Milliseconds to wait after the last filesystem event before triggering an incremental scan. Groups bursts (editor saves, branch switches, package installs) into a single scan pass. Default 300. Set to 0 to disable debouncing — every filesystem event triggers a scan immediately."
+              "description": "Milliseconds to wait after the last filesystem event before triggering an incremental scan. Groups bursts (editor saves, branch switches, package installs) into a single scan pass. Default 300. Set to 0 to disable debouncing, every filesystem event triggers a scan immediately."
             }
           }
         },
         "extraFolders": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "**Privacy-sensitive, project-local only** (per `core/config/helper:PROJECT_LOCAL_ONLY_KEYS`) when entries point outside the project — opens disk access there. Default `[]`. Additional directories appended to the scan roots; same parsing / indexing as the project root. Paths starting with `~` resolve against the user home; relative paths resolve against the project root. Reference impl gates writes that introduce out-of-project paths behind `--yes` (CLI) and a confirm dialog (UI). **Stripped with a warning when found in the committed `project` layer** — paths are inherently per-machine and must not travel via the shared repo. This is the ONLY mechanism to extend the scan beyond the project root: skill-map does NOT auto-include the user's HOME based on Provider hints — every out-of-project path must be listed here explicitly."
+          "description": "**Privacy-sensitive, project-local only** (per `core/config/helper:PROJECT_LOCAL_ONLY_KEYS`) when entries point outside the project, opens disk access there. Default `[]`. Additional directories appended to the scan roots; same parsing / indexing as the project root. Paths starting with `~` resolve against the user home; relative paths resolve against the project root. Reference impl gates writes that introduce out-of-project paths behind `--yes` (CLI) and a confirm dialog (UI). **Stripped with a warning when found in the committed `project` layer**, paths are inherently per-machine and must not travel via the shared repo. This is the ONLY mechanism to extend the scan beyond the project root: skill-map does NOT auto-include the user's HOME based on Provider hints, every out-of-project path must be listed here explicitly."
         },
         "referencePaths": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "**Privacy-sensitive, project-local only** (per `core/config/helper:PROJECT_LOCAL_ONLY_KEYS`) when entries point outside the project — opens read-only disk access for link validation only. Default `[]`. Directories walked in parallel by the scan to collect existing absolute paths into a side set; the kernel passes the set to analyzers via `IAnalyzerContext.referenceablePaths` so `core/broken-ref` can resolve a link against the filesystem when the in-graph lookup misses. Files under these paths are NOT parsed and NOT indexed as nodes — the only effect is suppressing `broken-ref` warnings for targets that exist on disk outside the scan. Same write-gate analyzers as `extraFolders`. **Stripped with a warning when found in the committed `project` layer**."
+          "description": "**Privacy-sensitive, project-local only** (per `core/config/helper:PROJECT_LOCAL_ONLY_KEYS`) when entries point outside the project, opens read-only disk access for link validation only. Default `[]`. Directories walked in parallel by the scan to collect existing absolute paths into a side set; the kernel passes the set to analyzers via `IAnalyzerContext.referenceablePaths` so `core/broken-ref` can resolve a link against the filesystem when the in-graph lookup misses. Files under these paths are NOT parsed and NOT indexed as nodes, the only effect is suppressing `broken-ref` warnings for targets that exist on disk outside the scan. Same write-gate analyzers as `extraFolders`. **Stripped with a warning when found in the committed `project` layer**."
         }
       }
     },
@@ -88,7 +88,7 @@
       "properties": {
         "share": {
           "type": "boolean",
-          "description": "When true, `./.skill-map/skill-map.db` is expected to be committed — teams remove it from `.gitignore` so the execution log becomes a shared artefact. Stability: experimental. Default false."
+          "description": "When true, `./.skill-map/skill-map.db` is expected to be committed, teams remove it from `.gitignore` so the execution log becomes a shared artefact. Stability: experimental. Default false."
         }
       }
     },
@@ -99,7 +99,7 @@
         "ttlSeconds": {
           "type": "integer",
           "minimum": 1,
-          "description": "Global fallback TTL (seconds) used when an action manifest omits `expectedDurationSeconds` — typically `mode: local` actions where the field is advisory. Default 3600. The submit-time resolution still applies `graceMultiplier` and `minimumTtlSeconds`."
+          "description": "Global fallback TTL (seconds) used when an action manifest omits `expectedDurationSeconds`, typically `mode: local` actions where the field is advisory. Default 3600. The submit-time resolution still applies `graceMultiplier` and `minimumTtlSeconds`."
         },
         "graceMultiplier": { "type": "number", "minimum": 1, "description": "Default grace multiplier applied to `expectedDurationSeconds`. Default 3." },
         "minimumTtlSeconds": { "type": "integer", "minimum": 1, "description": "Floor for computed TTL. Default 60." },
@@ -126,7 +126,7 @@
             "failed": {
               "type": ["integer", "null"],
               "minimum": 1,
-              "description": "Seconds after `finishedAt` before a `failed` job is eligible for pruning. `null` = never auto-prune. Default `null` — failed jobs are kept for post-mortem."
+              "description": "Seconds after `finishedAt` before a `failed` job is eligible for pruning. `null` = never auto-prune. Default `null`, failed jobs are kept for post-mortem."
             }
           }
         }
@@ -142,12 +142,12 @@
     },
     "allowEditSmFiles": {
       "type": "boolean",
-      "description": "**Project-local only** (per `core/config/helper:PROJECT_LOCAL_ONLY_KEYS`). Grants this project permission to create / modify `.sm` annotation sidecars next to source files. Default `false`. The first time a verb or BFF route attempts a `.sm` write while this is `false`, the kernel raises `EConsentRequiredError`. The CLI surfaces it as an interactive `confirm()` prompt (or `--yes` bypass); the BFF returns 412 `confirm-required` so the UI can open a `ConfirmationService` dialog. On accept the flag is persisted to `<cwd>/.skill-map/settings.local.json` (gitignored, per-checkout) and never asked again. On decline the operation aborts WITHOUT persisting the rejection — the next attempt re-asks. **Stripped with a warning when found in the committed `project` layer** (`<cwd>/.skill-map/settings.json`) — each developer consents independently."
+      "description": "**Project-local only** (per `core/config/helper:PROJECT_LOCAL_ONLY_KEYS`). Grants this project permission to create / modify `.sm` annotation sidecars next to source files. Default `false`. The first time a verb or BFF route attempts a `.sm` write while this is `false`, the kernel raises `EConsentRequiredError`. The CLI surfaces it as an interactive `confirm()` prompt (or `--yes` bypass); the BFF returns 412 `confirm-required` so the UI can open a `ConfirmationService` dialog. On accept the flag is persisted to `<cwd>/.skill-map/settings.local.json` (gitignored, per-checkout) and never asked again. On decline the operation aborts WITHOUT persisting the rejection, the next attempt re-asks. **Stripped with a warning when found in the committed `project` layer** (`<cwd>/.skill-map/settings.json`), each developer consents independently."
     },
     "updateCheck": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Controls the once-per-day notification when a newer @skill-map/cli release is published on npm. Disabled in CI, when SM_NO_UPDATE_CHECK=1, when stderr is not a TTY, or when the project DB is missing. **User-scope only**: this key SHOULD live in `~/.skill-map/settings.json` and the reference implementation forces user-scope reads via `core/config/helper:USER_ONLY_KEYS` — a project-layer entry from an older install continues to validate but is silently ignored at read time. `sm config set` rejects writes to the project layer for this key (rerun with `-g`); the Settings UI's General section persists toggles to the user layer.",
+      "description": "Controls the once-per-day notification when a newer @skill-map/cli release is published on npm. Disabled in CI, when SM_NO_UPDATE_CHECK=1, when stderr is not a TTY, or when the project DB is missing. **User-scope only**: this key SHOULD live in `~/.skill-map/settings.json` and the reference implementation forces user-scope reads via `core/config/helper:USER_ONLY_KEYS`, a project-layer entry from an older install continues to validate but is silently ignored at read time. `sm config set` rejects writes to the project layer for this key (rerun with `-g`); the Settings UI's General section persists toggles to the user layer.",
       "properties": {
         "enabled": {
           "type": "boolean",

package/schemas/refresh-report.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/refresh-report.schema.json",
+  "title": "RefreshReport",
+  "description": "Machine-readable output of `sm refresh <node.path> --json` and `sm refresh --stale --json`. Reports the count of enrichment rows persisted across the targeted node set (universal enrichment layer per `architecture.md` §A.8). The `elapsedMs` top-level field is the command's own wall-clock (see `cli-contract.md` §Elapsed time).",
+  "type": "object",
+  "required": ["ok", "kind", "refreshed", "nodes", "elapsedMs"],
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "const": true,
+      "description": "Always `true` on the happy path. Error envelopes use the shared `{ ok: false, error: { code, message } }` shape from `cli-contract.md` §Error envelope and do NOT carry this schema's other fields."
+    },
+    "kind": {
+      "type": "string",
+      "const": "refresh.report",
+      "description": "Discriminator pinning this envelope to the refresh verb. Consumers can branch on this when handling multiple `--json` shapes."
+    },
+    "refreshed": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total count of enrichment rows persisted across all targeted nodes. Equal to the sum of every `nodes[i].enrichments`. Zero on `--stale` with an empty stale set or when no extractor matched any targeted node's kind."
+    },
+    "nodes": {
+      "type": "array",
+      "description": "Per-node breakdown of the refresh, in the iteration order the verb processed targets. Single-node mode emits exactly one entry; `--stale` emits one entry per node whose stale row drove inclusion. Empty array when nothing was refreshed.",
+      "items": {
+        "type": "object",
+        "required": ["path", "enrichments"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Scope-root-relative `node.path` of the refreshed node."
+          },
+          "enrichments": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Count of enrichment rows the extractor pipeline produced and persisted for this node."
+          }
+        }
+      }
+    },
+    "elapsedMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Command's own wall-clock duration in milliseconds (see `cli-contract.md` §Elapsed time)."
+    }
+  }
+}

package/schemas/report-base-deterministic.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/report-base-deterministic.schema.json",
   "title": "ReportBaseDeterministic",
-  "description": "Universal base for deterministic Action reports. Every deterministic Action's report MUST extend this base via `allOf` + `$ref`. Symmetric with `report-base.schema.json` (the probabilistic / LLM base, which carries `confidence` + `safety`); deterministic vs probabilistic is the orthogonal axis declared by the Action manifest's `mode` field. Fields: `ok` (boolean — did the Action complete its logical work?), plus action-specific keys via `additionalProperties: true`. Action-specific shapes (e.g. bump's `version` / `noop` / `reason`) ride on the open extension.",
+  "description": "Universal base for deterministic Action reports. Every deterministic Action's report MUST extend this base via `allOf` + `$ref`. Symmetric with `report-base.schema.json` (the probabilistic / LLM base, which carries `confidence` + `safety`); deterministic vs probabilistic is the orthogonal axis declared by the Action manifest's `mode` field. Fields: `ok` (boolean, did the Action complete its logical work?), plus action-specific keys via `additionalProperties: true`. Action-specific shapes (e.g. bump's `version` / `noop` / `reason`) ride on the open extension.",
   "type": "object",
   "required": ["ok"],
   "additionalProperties": true,

package/schemas/sidecar.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/sidecar.schema.json",
   "title": "Sidecar",
-  "description": "Root shape of a co-located YAML sidecar (`<basename>.sm` next to `<basename>.md`). The `.sm` file IS the annotations file — every key under it is, conceptually, an annotation on the node. The YAML root organizes those annotations into structural blocks: `identity` (anchor + drift-detection hashes), `annotations` (the curated catalog of conventional fields), `audit` (timestamps), `settings` (reserved), and arbitrary `<plugin-id>:` namespaces for plugin-contributed data. Vendor file (`<basename>.md`) stays untouched. Schema is `additionalProperties: true` so plugins can add namespaces without coordination; the built-in `unknown-field` analyzer warns on truly unrecognized root keys (typo guard). Format is YAML — comments via `#`, multiline strings via `|` / `>`, permissive types per the YAML 1.2 spec. See `architecture.md` §Annotation system and ROADMAP §Step 9.6 for the design rationale.",
+  "description": "Root shape of a co-located YAML sidecar (`<basename>.sm` next to `<basename>.md`). The `.sm` file IS the annotations file, every key under it is, conceptually, an annotation on the node. The YAML root organizes those annotations into structural blocks: `identity` (anchor + drift-detection hashes), `annotations` (the curated catalog of conventional fields), `audit` (timestamps), `settings` (reserved), and arbitrary `<plugin-id>:` namespaces for plugin-contributed data. Vendor file (`<basename>.md`) stays untouched. Schema is `additionalProperties: true` so plugins can add namespaces without coordination; the built-in `unknown-field` analyzer warns on truly unrecognized root keys (typo guard). Format is YAML, comments via `#`, multiline strings via `|` / `>`, permissive types per the YAML 1.2 spec. See `architecture.md` §Annotation system and ROADMAP §Step 9.6 for the design rationale.",
   "type": "object",
   "required": ["identity"],
   "additionalProperties": true,
@@ -22,7 +22,7 @@
     },
     "audit": {
       "$ref": "#/$defs/audit",
-      "description": "Skill-map's audit trail. Populated by the built-in `bump` Action starting in Step 9.6.3 (Decision #125). All fields are optional at the property level — the Action atomically fills `lastBumpedAt` + `lastBumpedBy` on every bump and `createdAt` + `createdBy` on first creation. `additionalProperties: true` so future fields land additively."
+      "description": "Skill-map's audit trail. Populated by the built-in `bump` Action starting in Step 9.6.3 (Decision #125). All fields are optional at the property level, the Action atomically fills `lastBumpedAt` + `lastBumpedBy` on every bump and `createdAt` + `createdBy` on first creation. `additionalProperties: true` so future fields land additively."
     }
   },
   "$defs": {
@@ -60,7 +60,7 @@
         "path": {
           "type": "string",
           "minLength": 1,
-          "description": "Relative path from the scope root to the `.md` file this sidecar annotates. Matches the canonical Node identifier (see `node.schema.json` #/properties/path). Survives content edits; breaks on file moves — `sm refresh` re-points the sidecar after a move."
+          "description": "Relative path from the scope root to the `.md` file this sidecar annotates. Matches the canonical Node identifier (see `node.schema.json` #/properties/path). Survives content edits; breaks on file moves, `sm refresh` re-points the sidecar after a move."
         },
         "bodyHash": {
           "type": "string",

package/schemas/summaries/markdown.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/summaries/markdown.schema.json",
   "title": "SummaryMarkdown",
-  "description": "Report produced by `markdown-summarizer` for a single `markdown` node (the format-named generic fallback owned by the built-in `core/markdown` Provider — see `architecture.md` §Provider · dispatch order). Extends `report-base.schema.json`. Stability: experimental.",
+  "description": "Report produced by `markdown-summarizer` for a single `markdown` node (the format-named generic fallback owned by the built-in `core/markdown` Provider, see `architecture.md` §Provider · dispatch order). Extends `report-base.schema.json`. Stability: experimental.",
   "allOf": [
     { "$ref": "../report-base.schema.json" }
   ],

package/schemas/summaries/skill.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/summaries/skill.schema.json",
   "title": "SummarySkill",
-  "description": "Report produced by `skill-summarizer` for a single `skill` node. Extends `report-base.schema.json`. Stability: experimental — field set may tighten as real summarizer output stabilizes.",
+  "description": "Report produced by `skill-summarizer` for a single `skill` node. Extends `report-base.schema.json`. Stability: experimental, field set may tighten as real summarizer output stabilizes.",
   "allOf": [
     { "$ref": "../report-base.schema.json" }
   ],

package/schemas/view-slots.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/view-slots.schema.json",
   "title": "ViewSlots",
-  "description": "Closed catalog of view slots. A view slot is a kernel-published handle that names a visual surface in the UI, fixes the renderer that draws there, and fixes the payload shape the plugin emits. The plugin author picks ONE slot per view contribution; the kernel validates `ctx.emitContribution(id, payload)` against that slot's payload schema in `$defs.payloads`. There is no separate notion of a 'contract' — the slot IS the contract. Closed catalog by design: every new slot requires a spec change + UI renderer mount + scaffolder support + conformance fixtures + tests. Compounds catalog evolution cost; see ROADMAP.md §UI contribution system → 'Known limitations carried forward'. Slots are versioned via the manifest field `catalogCompat` (semver against the catalog as a whole), not per-slot.",
+  "description": "Closed catalog of view slots. A view slot is a kernel-published handle that names a visual surface in the UI, fixes the renderer that draws there, and fixes the payload shape the plugin emits. The plugin author picks ONE slot per view contribution; the kernel validates `ctx.emitContribution(id, payload)` against that slot's payload schema in `$defs.payloads`. There is no separate notion of a 'contract', the slot IS the contract. Closed catalog by design: every new slot requires a spec change + UI renderer mount + scaffolder support + conformance fixtures + tests. Compounds catalog evolution cost; see ROADMAP.md §UI contribution system → 'Known limitations carried forward'. Slots are versioned via the manifest field `catalogCompat` (semver against the catalog as a whole), not per-slot.",
   "type": "object",
   "$defs": {
     "SlotName": {
@@ -35,7 +35,7 @@
       "minLength": 1,
       "maxLength": 64,
       "pattern": "^(?:pi pi-[a-z0-9-]+|pi-[a-z0-9-]+|fa-(?:solid|regular|brands) fa-[a-z0-9-]+|fa-[a-z0-9-]+|[^a-zA-Z].*)$",
-      "description": "Single string, prefix-discriminated by the UI. Four valid shapes: (1) emoji — any value starting with a non-ASCII-letter codepoint renders as text; (2) PrimeIcons — `pi-foo` or `pi pi-foo` renders as `<i class=\"pi pi-foo\">`; (3) FontAwesome explicit family — `fa-solid fa-foo` / `fa-regular fa-foo` / `fa-brands fa-foo` passes through as-is; (4) FontAwesome shorthand — `fa-foo` (no family token) defaults to `fa-solid fa-foo`. Bare class names without a `pi-` / `fa-` prefix are rejected at manifest load (invalid-manifest). Unknown PrimeIcons / FontAwesome names render no icon (silent fallback) plus a console warning."
+      "description": "Single string, prefix-discriminated by the UI. Four valid shapes: (1) emoji, any value starting with a non-ASCII-letter codepoint renders as text; (2) PrimeIcons, `pi-foo` or `pi pi-foo` renders as `<i class=\"pi pi-foo\">`; (3) FontAwesome explicit family, `fa-solid fa-foo` / `fa-regular fa-foo` / `fa-brands fa-foo` passes through as-is; (4) FontAwesome shorthand, `fa-foo` (no family token) defaults to `fa-solid fa-foo`. Bare class names without a `pi-` / `fa-` prefix are rejected at manifest load (invalid-manifest). Unknown PrimeIcons / FontAwesome names render no icon (silent fallback) plus a console warning."
     },
     "IViewContribution": {
       "type": "object",
@@ -67,7 +67,7 @@
         "priority": {
           "type": "number",
           "default": 100,
-          "description": "Optional ordering hint. Slots configured with `order: 'priority'` sort contributions ASC by this value, with alphabetical tie-break by qualified id. Default 100 — plugins use it to suggest where their contribution belongs relative to others sharing the same slot. The slot has the final say on whether `priority` is honoured at all."
+          "description": "Optional ordering hint. Slots configured with `order: 'priority'` sort contributions ASC by this value, with alphabetical tie-break by qualified id. Default 100, plugins use it to suggest where their contribution belongs relative to others sharing the same slot. The slot has the final say on whether `priority` is honoured at all."
         }
       },
       "allOf": [
@@ -101,12 +101,12 @@
         "properties": {
           "icon": {
             "$ref": "#/$defs/IconString",
-            "description": "Optional payload-time icon override. When omitted the manifest-declared `icon` (which is required for this slot — see `IViewContribution.allOf`) is rendered instead. Lets a plugin emit a different icon per node without redeclaring the manifest."
+            "description": "Optional payload-time icon override. When omitted the manifest-declared `icon` (which is required for this slot, see `IViewContribution.allOf`) is rendered instead. Lets a plugin emit a different icon per node without redeclaring the manifest."
           },
           "severity": { "$ref": "#/$defs/Severity" },
           "tooltip": { "type": "string", "maxLength": 256 }
         },
-        "description": "Single icon per node — small standalone marker rendered next to the card title. The manifest requires `icon`; the payload optionally overrides it per node and may add `severity` (color tint) and `tooltip`. No counts, no labels — for chip + number use a counter slot; for label + severity use a tag slot. 'Empty' for `emitWhenEmpty` is the absence of both payload `icon` and a manifest fallback (in practice never empty since the manifest icon is required)."
+        "description": "Single icon per node, small standalone marker rendered next to the card title. The manifest requires `icon`; the payload optionally overrides it per node and may add `severity` (color tint) and `tooltip`. No counts, no labels, for chip + number use a counter slot; for label + severity use a tag slot. 'Empty' for `emitWhenEmpty` is the absence of both payload `icon` and a manifest fallback (in practice never empty since the manifest icon is required)."
       },
       "card.subtitle.left": { "$ref": "#/$defs/payloads/_counter" },
       "card.footer.left": { "$ref": "#/$defs/payloads/_counter" },
@@ -286,7 +286,7 @@
                   "type": "string",
                   "minLength": 1,
                   "maxLength": 512,
-                  "description": "Node path within the scope. Resolved by the UI to a clickable link via `Router.navigate` — never rendered as a raw `[href]` (per the renderer attr-sanitization analyzer)."
+                  "description": "Node path within the scope. Resolved by the UI to a clickable link via `Router.navigate`, never rendered as a raw `[href]` (per the renderer attr-sanitization analyzer)."
                 },
                 "label": { "type": "string", "minLength": 1, "maxLength": 128 },
                 "kind": {
@@ -329,7 +329,7 @@
           "tooltip": { "type": "string", "maxLength": 256 },
           "severity": { "$ref": "#/$defs/Severity" }
         },
-        "description": "Single value summarizing the entire scope. Emitted ONCE per scan (not per node). Plugins use `ctx.emitScopeContribution(...)` (analyzer context) — extractors do not see `emitScopeContribution`."
+        "description": "Single value summarizing the entire scope. Emitted ONCE per scan (not per node). Plugins use `ctx.emitScopeContribution(...)` (analyzer context), extractors do not see `emitScopeContribution`."
       }
     }
   }

package/versioning.md

@@ -13,7 +13,7 @@ A given CLI release declares the spec range it implements (e.g. `"specCompat": "
 
 ## Semver for the spec
 
-Patch, minor, major have precise meaning for a specification — different from code.
+Patch, minor, major have precise meaning for a specification, different from code.
 
 | Bump | Allowed changes | Examples |
 |---|---|---|
@@ -30,13 +30,13 @@ All of the following are normative and governed by this policy:
 - Every JSON Schema in `schemas/` (fields, types, required, enums, defaults, `additionalProperties`).
 - Every MUST / SHOULD / MAY statement in prose documents ([`architecture.md`](./architecture.md), [`cli-contract.md`](./cli-contract.md), [`job-events.md`](./job-events.md), [`prompt-preamble.md`](./prompt-preamble.md), [`db-schema.md`](./db-schema.md), [`plugin-kv-api.md`](./plugin-kv-api.md), [`job-lifecycle.md`](./job-lifecycle.md)).
 - Exit codes, verb names, required flags, canonical error messages marked "normative".
-- Conformance fixtures and cases — removing or tightening a case is major.
+- Conformance fixtures and cases, removing or tightening a case is major.
 
 The following are **non-normative** and can change at any time without a version bump:
 
 - Editorial prose, examples, diagrams.
 - README layout, cross-link structure.
-- Filenames inside `../src/` (reference impl) — never referenced from spec normatively.
+- Filenames inside `../src/` (reference impl), never referenced from spec normatively.
 - Internal commentary inside `../ROADMAP.md` and `../CLAUDE.md`.
 
 ## Stability tags
@@ -63,16 +63,16 @@ Tags live inline in schema `description` fields and in prose via a leading `**St
 While the spec is `0.Y.Z`:
 
 - Minor bumps may contain breaking changes (documented as such in `CHANGELOG.md`).
-- Conformance is advisory — failing a conformance case is a bug report, not a spec violation.
+- Conformance is advisory, failing a conformance case is a bug report, not a spec violation.
 - `specCompat` in plugins should pin a minor range (`"^0.3.0"` means `>=0.3.0 <0.4.0`), not a major range.
 
 The first stable commitment is `spec-v1.0.0`. In the current reference roadmap, that tag ships with `cli-v1.0.0`.
 
 ## Independence in practice
 
-- **Spec `1.0.0` + CLI `0.1.0`** — spec is stabilized before the CLI ships its v1. Normal case during early life of the project.
-- **Spec `1.2.0` + CLI `0.8.0`** — spec gained an optional feature; CLI hasn't implemented it yet. Fine. Plugins needing that feature must declare `"specCompat": "^1.2.0"`.
-- **Spec `2.0.0` + CLI `1.4.0`** — CLI still targets spec v1. Operator must upgrade CLI before installing v2-targeting plugins.
+- **Spec `1.0.0` + CLI `0.1.0`**, spec is stabilized before the CLI ships its v1. Normal case during early life of the project.
+- **Spec `1.2.0` + CLI `0.8.0`**, spec gained an optional feature; CLI hasn't implemented it yet. Fine. Plugins needing that feature must declare `"specCompat": "^1.2.0"`.
+- **Spec `2.0.0` + CLI `1.4.0`**, CLI still targets spec v1. Operator must upgrade CLI before installing v2-targeting plugins.
 
 ## Change process