@skill-map/spec 0.18.0 → 0.20.0

package/schemas/input-types.schema.json

@@ -0,0 +1,260 @@
+{
+  "$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.",
+  "type": "object",
+  "$defs": {
+    "InputTypeName": {
+      "type": "string",
+      "enum": [
+        "string-list",
+        "single-string",
+        "boolean-flag",
+        "integer",
+        "enum-pick",
+        "enum-multipick",
+        "path-glob",
+        "regex",
+        "secret",
+        "key-value-list"
+      ],
+      "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.",
+      "oneOf": [
+        { "$ref": "#/$defs/Setting_StringList" },
+        { "$ref": "#/$defs/Setting_SingleString" },
+        { "$ref": "#/$defs/Setting_BooleanFlag" },
+        { "$ref": "#/$defs/Setting_Integer" },
+        { "$ref": "#/$defs/Setting_EnumPick" },
+        { "$ref": "#/$defs/Setting_EnumMultipick" },
+        { "$ref": "#/$defs/Setting_PathGlob" },
+        { "$ref": "#/$defs/Setting_Regex" },
+        { "$ref": "#/$defs/Setting_Secret" },
+        { "$ref": "#/$defs/Setting_KeyValueList" }
+      ]
+    },
+    "_Common": {
+      "type": "object",
+      "required": ["type", "label"],
+      "properties": {
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Short human-readable label shown above the form control. English-only per AGENTS.md."
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "Optional helper text shown below the control. English-only."
+        }
+      }
+    },
+    "Setting_StringList": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "string-list" },
+        "label": true,
+        "description": true,
+        "default": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "min": { "type": "integer", "minimum": 0, "description": "Minimum item count required to validate." },
+        "max": { "type": "integer", "minimum": 1, "description": "Maximum item count permitted." },
+        "itemMaxLength": { "type": "integer", "minimum": 1, "default": 256 }
+      },
+      "description": "Array of free-form strings. Renders as a tag input. Use for keyword lists, ignore patterns, allow-lists. Value type at runtime: `string[]`."
+    },
+    "Setting_SingleString": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "single-string" },
+        "label": true,
+        "description": true,
+        "default": { "type": "string" },
+        "minLength": { "type": "integer", "minimum": 0 },
+        "maxLength": { "type": "integer", "minimum": 1 },
+        "pattern": {
+          "type": "string",
+          "description": "Optional ECMAScript regex (no flags) the value must match. Validated at form submit AND at extractor invocation."
+        }
+      },
+      "description": "Single text input. Use for short identifiers, URLs, names. Value type at runtime: `string`."
+    },
+    "Setting_BooleanFlag": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "boolean-flag" },
+        "label": true,
+        "description": true,
+        "default": { "type": "boolean", "default": false }
+      },
+      "description": "On/off toggle. Renders as PrimeNG `<p-toggleswitch>`. Value type at runtime: `boolean`."
+    },
+    "Setting_Integer": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "integer" },
+        "label": true,
+        "description": true,
+        "default": { "type": "integer" },
+        "min": { "type": "integer" },
+        "max": { "type": "integer" },
+        "step": { "type": "integer", "minimum": 1, "default": 1 }
+      },
+      "description": "Integer input with optional bounds. Renders as PrimeNG `<p-inputnumber>` with spinner. Value type at runtime: `number` (always integer)."
+    },
+    "Setting_EnumPick": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label", "options"],
+      "properties": {
+        "type": { "const": "enum-pick" },
+        "label": true,
+        "description": true,
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "type": "string", "minLength": 1, "maxLength": 64 },
+              "label": { "type": "string", "minLength": 1, "maxLength": 64 }
+            }
+          }
+        },
+        "default": { "type": "string" }
+      },
+      "description": "Pick one from a closed set. Renders as PrimeNG `<p-select>` (≤ 7 options) or `<p-radiobutton>` group (≤ 4 options). Value type at runtime: `string` (the picked option's `value`)."
+    },
+    "Setting_EnumMultipick": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label", "options"],
+      "properties": {
+        "type": { "const": "enum-multipick" },
+        "label": true,
+        "description": true,
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "type": "string", "minLength": 1, "maxLength": 64 },
+              "label": { "type": "string", "minLength": 1, "maxLength": 64 }
+            }
+          }
+        },
+        "default": { "type": "array", "items": { "type": "string" } },
+        "min": { "type": "integer", "minimum": 0 },
+        "max": { "type": "integer", "minimum": 1 }
+      },
+      "description": "Pick zero or more from a closed set. Renders as PrimeNG `<p-multiselect>` or checkbox group. Value type at runtime: `string[]`."
+    },
+    "Setting_PathGlob": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "path-glob" },
+        "label": true,
+        "description": true,
+        "default": { "type": "string" },
+        "multiple": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, accepts `string[]` of glob patterns; when false (default), single `string`."
+        }
+      },
+      "description": "Glob pattern (POSIX-style, `**` / `*` / `?`). Validated against the project's installed glob library at form submit. Value type at runtime: `string` (when `multiple: false`) or `string[]`."
+    },
+    "Setting_Regex": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "regex" },
+        "label": true,
+        "description": true,
+        "default": { "type": "string" },
+        "flags": {
+          "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 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`."
+    },
+    "Setting_Secret": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "secret" },
+        "label": true,
+        "description": true,
+        "envVar": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "description": "Optional env var name the kernel checks first; if set in the process environment, that value wins over any stored value (lets CI inject without writing to disk). The user-supplied value is stored encrypted at rest."
+        }
+      },
+      "description": "Sensitive string (token, password, API key). Renders as `<input type=\"password\">` with reveal toggle. Stored encrypted at rest (kernel-managed key in `state_secrets` table). Logged as `<redacted>` in CLI output. Value type at runtime: `string`. Triggers an `audit.secret-read` event on every read."
+    },
+    "Setting_KeyValueList": {
+      "allOf": [{ "$ref": "#/$defs/_Common" }],
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "label"],
+      "properties": {
+        "type": { "const": "key-value-list" },
+        "label": true,
+        "description": true,
+        "keyLabel": { "type": "string", "minLength": 1, "maxLength": 32, "default": "Key" },
+        "valueLabel": { "type": "string", "minLength": 1, "maxLength": 32, "default": "Value" },
+        "default": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["key", "value"],
+            "properties": {
+              "key": { "type": "string" },
+              "value": { "type": "string" }
+            }
+          }
+        },
+        "min": { "type": "integer", "minimum": 0 },
+        "max": { "type": "integer", "minimum": 1 }
+      },
+      "description": "Editable mapping of strings to strings. Renders as a small editable table. Use for custom translations, alias maps, header overrides. Value type at runtime: `Array<{ key: string, value: string }>`."
+    }
+  }
+}

package/schemas/issue.schema.json

@@ -2,15 +2,15 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/issue.schema.json",
   "title": "Issue",
-  "description": "Deterministic finding emitted by a rule when evaluating the graph. Not to be confused with `Finding`, which is probabilistic (LLM-produced).",
+  "description": "Deterministic finding emitted by a analyzer when evaluating the graph. Not to be confused with `Finding`, which is probabilistic (LLM-produced).",
   "type": "object",
-  "required": ["ruleId", "severity", "nodeIds", "message"],
+  "required": ["analyzerId", "severity", "nodeIds", "message"],
   "additionalProperties": false,
   "properties": {
-    "ruleId": {
+    "analyzerId": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
-      "description": "Kebab-case identifier of the rule that emitted this issue (e.g. `trigger-collision`, `broken-ref`, `superseded`)."
+      "description": "Kebab-case identifier of the analyzer that emitted this issue (e.g. `trigger-collision`, `broken-ref`, `superseded`)."
     },
     "severity": {
       "type": "string",
@@ -19,7 +19,7 @@
     },
     "nodeIds": {
       "type": "array",
-      "description": "`node.path` values involved in this issue. Most rules emit 1 or 2; trigger-collision may emit N. Field name uses `id` generically to remain stable across future identifier changes.",
+      "description": "`node.path` values involved in this issue. Most analyzers emit 1 or 2; trigger-collision may emit N. Field name uses `id` generically to remain stable across future identifier changes.",
       "minItems": 1,
       "items": { "type": "string" }
     },
@@ -47,7 +47,7 @@
     },
     "data": {
       "type": "object",
-      "description": "Rule-specific structured payload (e.g. the colliding trigger string, the missing target). Free-form.",
+      "description": "Analyzer-specific structured payload (e.g. the colliding trigger string, the missing target). Free-form.",
       "additionalProperties": true
     }
   }

package/schemas/link.schema.json

@@ -13,7 +13,7 @@
     },
     "target": {
       "type": "string",
-      "description": "`node.path` of the destination. MAY point to a missing node; rules detect broken refs."
+      "description": "`node.path` of the destination. MAY point to a missing node; analyzers detect broken refs."
     },
     "kind": {
       "type": "string",
@@ -23,7 +23,7 @@
     "confidence": {
       "type": "string",
       "enum": ["high", "medium", "low"],
-      "description": "Extractor's self-assessed confidence. Rules MAY filter by confidence."
+      "description": "Extractor's self-assessed confidence. Analyzers MAY filter by confidence."
     },
     "sources": {
       "type": "array",

package/schemas/node.schema.json

@@ -20,24 +20,6 @@
       "type": "string",
       "description": "Identifier of the Provider extension that classified this node (e.g. `claude`)."
     },
-    "title": {
-      "type": ["string", "null"],
-      "description": "Human-readable title. Sourced from frontmatter `name` or falls back to filename. Null if neither is usable."
-    },
-    "description": {
-      "type": ["string", "null"],
-      "description": "Short description from frontmatter `description`. Null if absent."
-    },
-    "stability": {
-      "type": ["string", "null"],
-      "enum": ["experimental", "stable", "deprecated", null],
-      "description": "Denormalized from `metadata.stability` for fast queries."
-    },
-    "version": {
-      "type": ["integer", "null"],
-      "minimum": 1,
-      "description": "Monotonic version counter denormalised from sidecar `annotations.version` (Step 9.6.2). Pre-9.6.2 this field was a semver string sourced from `frontmatter.metadata.version`; the new shape is a single integer monotonic counter, orthogonal to `stability`. Major bumps mean `create a new node, supersede the old one`, not increment. See Decision #125 and `annotations.schema.json#/properties/version`."
-    },
     "frontmatter": {
       "type": "object",
       "description": "Full parsed frontmatter. See `frontmatter/base.schema.json` and `frontmatter/<kind>.schema.json`.",
@@ -118,7 +100,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 `for` / `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.for.*`, `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-registry.schema.json

@@ -27,6 +27,10 @@
           "type": "string",
           "description": "Semver range this plugin is compatible with (e.g. `^1.0.0`, `>=0.3.0 <0.4.0`). Checked via `semver.satisfies(specVersion, this)` at load time."
         },
+        "catalogCompat": {
+          "type": "string",
+          "description": "Optional semver range against the kernel's view-slots + input-types catalog version (e.g. `^1.0.0`). Independent from `specCompat` because the catalog evolves on its own cadence (new slots ship as minor bumps; rename/remove ships as catalog-major bumps that trigger `sm plugins upgrade`). Absent = the plugin declares no view contributions or settings AND opts out of catalog-version checking; `sm plugins doctor` will warn if such a plugin actually emits via `viewContributions` or `settings`. Mismatch surfaces as `incompatible-catalog` plugin status."
+        },
         "description": {
           "type": "string"
         },
@@ -73,6 +77,14 @@
             }
           ]
         },
+        "settings": {
+          "type": "object",
+          "additionalProperties": { "$ref": "input-types.schema.json#/$defs/ISettingDeclaration" },
+          "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)."
+        },
         "author": { "type": "string" },
         "license": { "type": "string", "description": "SPDX identifier." },
         "homepage": { "type": "string", "format": "uri" },
@@ -101,8 +113,8 @@
         "manifest": { "$ref": "#/$defs/PluginManifest" },
         "status": {
           "type": "string",
-          "enum": ["enabled", "disabled", "incompatible-spec", "invalid-manifest", "load-error", "id-collision"],
-          "description": "Resolved state after discovery. `disabled` = user-disabled via config; `id-collision` = two plugins (any combination of project / global / --plugin-dir) declared the same `id`, both blocked, no precedence; others = automatic."
+          "enum": ["enabled", "disabled", "incompatible-spec", "incompatible-catalog", "invalid-manifest", "load-error", "id-collision"],
+          "description": "Resolved state after discovery. `disabled` = user-disabled via config; `id-collision` = two plugins (any combination of project / global / --plugin-dir) declared the same `id`, both blocked, no precedence; `incompatible-catalog` = manifest's `catalogCompat` does not satisfy the kernel's catalog version (resolved via `sm plugins upgrade`); others = automatic."
         },
         "statusReason": {
           "type": ["string", "null"],

package/schemas/project-config.schema.json

@@ -57,6 +57,20 @@
               "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."
             }
           }
+        },
+        "includeHome": {
+          "type": "boolean",
+          "description": "**Privacy-sensitive** — opens disk access outside the project. Default false. When true, `sm scan` (without `-g`) appends every active Provider's `explorationDir` resolved against `~` (typically `~/.claude`, `~/.gemini`, `~/.agents`) to the scan roots. Files there are walked, parsed, and indexed as nodes alongside the project content. Reference impl: `sm config set scan.includeHome true` requires `--yes` to confirm; the Settings UI's Project section requires an explicit confirm dialog. The scan emits a stderr line listing the HOME paths it added so the operator sees the expanded surface."
+        },
+        "extraRoots": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "**Privacy-sensitive** 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), per the same analyzers as `includeHome`."
+        },
+        "referencePaths": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "**Privacy-sensitive** 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 `extraRoots`."
         }
       }
     },
@@ -129,6 +143,17 @@
       "properties": {
         "locale": { "type": "string", "description": "BCP-47 tag. Default `en`." }
       }
+    },
+    "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.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Default true. Set to false to disable both the npm registry probe and the CLI / UI banner."
+        }
+      }
     }
   }
 }

package/schemas/sidecar.schema.json

@@ -2,18 +2,18 @@
   "$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`). Carries skill-map's annotations, settings, audit, and plugin contributions about the markdown node it accompanies. Vendor file (`<basename>.md`) stays untouched. Top-level reserved blocks are `for`, `annotations`, `settings`, `audit`; everything else is treated as a plugin namespace (`<plugin-id>:`). Schema is `additionalProperties: true` so plugins can add namespaces without coordination; the built-in `unknown-field` rule 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": ["for"],
+  "required": ["identity"],
   "additionalProperties": true,
   "properties": {
-    "for": {
+    "identity": {
       "$ref": "#/$defs/identity",
-      "description": "Identity link to the markdown node this sidecar annotates. Drift detection compares stored hashes against the current file at scan time; mismatch emits the built-in `annotation-stale` warning (soft mode, never blocking)."
+      "description": "Anchor block linking this sidecar to its markdown node and capturing the body / frontmatter hashes at the moment of the last `bump`. Drift detection compares stored hashes against the current file at scan time; mismatch emits the built-in `annotation-stale` warning (soft mode, never blocking)."
     },
     "annotations": {
       "$ref": "annotations.schema.json",
-      "description": "Skill-map annotation catalog. See `annotations.schema.json` for the curated 15-field surface; users / plugins MAY add custom keys (rides on `additionalProperties: true`)."
+      "description": "Skill-map annotation catalog. See `annotations.schema.json` for the curated 13-field surface; users / plugins MAY add custom keys (rides on `additionalProperties: true`)."
     },
     "settings": {
       "type": "object",
@@ -70,7 +70,7 @@
         "frontmatterHash": {
           "type": "string",
           "pattern": "^[a-f0-9]{64}$",
-          "description": "sha256 of the canonical frontmatter (per the kernel's `canonicalFrontmatter` rule), hex-encoded lowercase, captured at the moment this sidecar was last bumped. Compared against the current frontmatter hash to detect drift."
+          "description": "sha256 of the canonical frontmatter (per the kernel's `canonicalFrontmatter` analyzer), hex-encoded lowercase, captured at the moment this sidecar was last bumped. Compared against the current frontmatter hash to detect drift."
         },
         "resolvedAs": {
           "type": "object",

package/schemas/summaries/agent.schema.json

@@ -27,7 +27,7 @@
     },
     "toolsObserved": {
       "type": "array",
-      "description": "Tool names the summarizer observed referenced in the body. MAY differ from `metadata.tools` / frontmatter.tools; rules can emit drift issues.",
+      "description": "Tool names the summarizer observed referenced in the body. MAY differ from `metadata.tools` / frontmatter.tools; analyzers can emit drift issues.",
       "items": { "type": "string" }
     },
     "interactionStyle": {

package/schemas/summaries/command.schema.json

@@ -22,7 +22,7 @@
     },
     "argsObserved": {
       "type": "array",
-      "description": "Argument structure as inferred from the body. MAY differ from declared `frontmatter.args`; rules can emit drift issues.",
+      "description": "Argument structure as inferred from the body. MAY differ from declared `frontmatter.args`; analyzers can emit drift issues.",
       "items": {
         "type": "object",
         "required": ["name"],

package/schemas/summaries/hook.schema.json

@@ -18,7 +18,7 @@
     },
     "triggerInferred": {
       "type": "string",
-      "description": "Event or condition the summarizer inferred from the body. MAY differ from declared `frontmatter.event`/`condition`; rules can emit drift issues."
+      "description": "Event or condition the summarizer inferred from the body. MAY differ from declared `frontmatter.event`/`condition`; analyzers can emit drift issues."
     },
     "sideEffects": {
       "type": "array",

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 in the Claude Provider catalog). 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" }
   ],