@skill-map/spec 0.18.0 → 0.19.0

package/schemas/extensions/extractor.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/extensions/extractor.schema.json",
   "title": "ExtensionExtractor",
-  "description": "Manifest shape for an `Extractor` extension. An extractor consumes a parsed node (frontmatter + body) and emits output through three context-supplied callbacks rather than returning a value: `ctx.emitLink(link)` writes to the kernel's `links` table (validated against `emitsLinkKinds` before persistence), `ctx.enrichNode(partial)` merges author-canonical properties into the kernel's enrichment layer (separate from the author-supplied frontmatter), and `ctx.store` persists into the plugin's own KV namespace or dedicated tables. The runtime method is `extract(ctx) → void`. Extractors run in isolation: they MUST NOT read other nodes, the graph, or the DB. Cross-node reasoning lives in Rules. Extractors are dual-mode: `deterministic` extractors run synchronously inside `sm scan`; `probabilistic` extractors invoke an LLM through the kernel's `RunnerPort` (exposed as `ctx.runner`) and execute only as queued jobs (never during scan). See `architecture.md` §Execution modes for the full contract. Renamed from `detector` in spec 0.8.x — the FindBugs/SpotBugs lineage of \"detector\" connoted bug finding, while this kind extracts signals (relations, enrichments, custom data); ENRE (Entity Relationship Extractor) is the closer precedent.",
+  "description": "Manifest shape for an `Extractor` extension. An extractor consumes a parsed node (frontmatter + body) and emits output through three context-supplied callbacks rather than returning a value: `ctx.emitLink(link)` writes to the kernel's `links` table (validated against `emitsLinkKinds` before persistence), `ctx.enrichNode(partial)` merges author-canonical properties into the kernel's enrichment layer (separate from the author-supplied frontmatter), and `ctx.store` persists into the plugin's own KV namespace or dedicated tables. The runtime method is `extract(ctx) → void`. Extractors run in isolation: they MUST NOT read other nodes, the graph, or the DB. Cross-node reasoning lives in Rules. Extractors are deterministic-only: pure code, runs synchronously inside `sm scan`, same input → same output every run. LLM-driven enrichment of a node is an Action concern (queued as a job), not an Extractor concern. See `architecture.md` §Execution modes for the full contract. Renamed from `detector` in spec 0.8.x — the FindBugs/SpotBugs lineage of \"detector\" connoted bug finding, while this kind extracts signals (relations, enrichments, custom data); ENRE (Entity Relationship Extractor) is the closer precedent.",
   "allOf": [
     { "$ref": "base.schema.json" }
   ],
@@ -11,16 +11,9 @@
   "unevaluatedProperties": false,
   "properties": {
     "kind": { "const": "extractor" },
-    "mode": {
-      "type": "string",
-      "enum": ["deterministic", "probabilistic"],
-      "default": "deterministic",
-      "description": "`deterministic` (default): pure code, runs synchronously during `sm scan`. Same input → same output, every run. `probabilistic`: invokes an LLM via `ctx.runner` and runs only as a queued job (`sm job submit extractor:<id>`); never participates in `sm scan`. The kernel rejects probabilistic extractors that try to register scan-time hooks at load time. Omitting the field is equivalent to declaring `deterministic`."
-    },
     "emitsLinkKinds": {
       "type": "array",
-      "description": "Subset of `Link.kind` values this extractor is allowed to emit through `ctx.emitLink(...)`. Emitting an unlisted kind at runtime → kernel rejects the link and logs `extractor-kind-violation`.",
-      "minItems": 1,
+      "description": "Subset of `Link.kind` values this extractor is allowed to emit through `ctx.emitLink(...)`. Emitting an unlisted kind at runtime → kernel rejects the link and logs `extractor-kind-violation`. Empty array (`[]`) is the honest declaration for pure-contributions extractors that emit only via `ctx.emitContribution(...)` and never call `ctx.emitLink(...)` — Phase 3 of the View contribution system relaxed `minItems: 1` to admit this case (`{ kind: 'extractor', emitsLinkKinds: [], viewContributions: { ... } }`).",
       "items": {
         "type": "string",
         "enum": ["invokes", "references", "mentions", "supersedes"]
@@ -42,7 +35,7 @@
       "minItems": 1,
       "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
       "uniqueItems": true,
-      "description": "Optional opt-in filter. If declared, the extractor runs only on nodes whose kind is in this list. Absent = applies to all kinds (default). No wildcards — the absence of the field already means \"every kind\". Empty array is invalid (`minItems: 1`). Unknown kinds (not declared by any installed Provider) load OK but emit a warning in `sm plugins doctor` — the Provider may arrive later. The kernel filters fail-fast: nodes whose kind is excluded never see `extract()`, so a probabilistic extractor wastes zero LLM cost on inapplicable nodes."
+      "description": "Optional opt-in filter. If declared, the extractor runs only on nodes whose kind is in this list. Absent = applies to all kinds (default). No wildcards — the absence of the field already means \"every kind\". Empty array is invalid (`minItems: 1`). Unknown kinds (not declared by any installed Provider) load OK but emit a warning in `sm plugins doctor` — the Provider may arrive later. The kernel filters fail-fast: nodes whose kind is excluded never see `extract()`, so an extractor wastes zero CPU on inapplicable nodes."
     }
   }
 }

package/schemas/extensions/provider.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/extensions/provider.schema.json",
   "title": "ExtensionProvider",
-  "description": "Manifest shape for a `Provider` extension. A Provider declares its own universe: the platform it recognises (Claude Code, Codex, Gemini, Obsidian vault, generic MD), the catalog of node `kind`s it emits, the per-kind frontmatter schema each kind follows, and the filesystem directory (`explorationDir`) where its content lives. The catalog lives in the `kinds` map, keyed by kind name. Each map entry declares the relative path to the kind's frontmatter schema (resolved against the Provider's directory) and the qualified `defaultRefreshAction` id the UI's probabilistic-refresh surface dispatches for that kind. Spec only ships `frontmatter/base.schema.json` (universal); per-kind schemas live with their owning Provider so that adding a new platform is purely additive — no spec bump needed to introduce kinds. Exactly zero or one Provider MUST match any given file; multiple matches → the kernel emits an issue `provider-ambiguous` and the file is left unclassified. Providers are deterministic-only — they sit at the filesystem boundary and run during boot; probabilistic classification would make boot slow, costly, and non-reproducible. The `mode` field MUST NOT appear in Provider manifests. If you need LLM-assisted classification, write a probabilistic Extractor that emits classification hints via `ctx.emitLink`. Distinct from the **hexagonal-architecture** 'adapter' (`RunnerPort.adapter`, `StoragePort.adapter`, etc.), which is an internal driven-adapter implementing a port — Providers live in the extension surface, hexagonal adapters live in `src/kernel/adapters/`. Stability: stable as of spec v1.0.0 except where noted.",
+  "description": "Manifest shape for a `Provider` extension. A Provider declares its own universe: the platform it recognises (Claude Code, Codex, Gemini, Obsidian vault, generic MD), the catalog of node `kind`s it emits, the per-kind frontmatter schema each kind follows, and the filesystem directory (`explorationDir`) where its content lives. The catalog lives in the `kinds` map, keyed by kind name. Each map entry declares the relative path to the kind's frontmatter schema (resolved against the Provider's directory) and the qualified `defaultRefreshAction` id the UI's probabilistic-refresh surface dispatches for that kind. Spec only ships `frontmatter/base.schema.json` (universal); per-kind schemas live with their owning Provider so that adding a new platform is purely additive — no spec bump needed to introduce kinds. Exactly zero or one Provider MUST match any given file; multiple matches → the kernel emits an issue `provider-ambiguous` and the file is left unclassified. Providers are deterministic-only — they sit at the filesystem boundary and run during boot; probabilistic classification would make boot slow, costly, and non-reproducible. The `mode` field MUST NOT appear in Provider manifests. If you need LLM-assisted classification, write a probabilistic Action that runs as a queued job and writes back through the enrichment layer; Extractors are deterministic-only and Providers stay on the deterministic boot path. Distinct from the **hexagonal-architecture** 'adapter' (`RunnerPort.adapter`, `StoragePort.adapter`, etc.), which is an internal driven-adapter implementing a port — Providers live in the extension surface, hexagonal adapters live in `src/kernel/adapters/`. Stability: stable as of spec v1.0.0 except where noted.",
   "allOf": [
     { "$ref": "base.schema.json" }
   ],

package/schemas/frontmatter/base.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/frontmatter/base.schema.json",
   "title": "FrontmatterBase",
-  "description": "Truly universal frontmatter shape — `name` + `description` are the only fields every node, on every Provider, MUST carry. Per-vendor schemas (Anthropic Claude, Cursor, Obsidian, …) live in the Provider that emits the kind (declared via `provider.kinds[<kind>].schema`) and extend this base via `allOf` + `$ref` to its `$id`. `additionalProperties: true` is intentional: skill-map AGGREGATES vendor specs, it does not curate them. Vendor-specific fields (`tools`, `allowedTools`, `model`, `metadata`, etc.) flow through validation silently because the per-kind extension declares them. The future home for skill-map-only annotation fields (provenance, cross-vendor metadata) is a deferred decision — tracked separately, not in this schema.",
+  "description": "Universal frontmatter shape every Provider's per-kind schema extends via `allOf` + `$ref` to this `$id`. `name` and `description` are the two universally required fields; `tags` is a universally accepted optional field for author-supplied taxonomy. Per-vendor schemas (Anthropic Claude, Cursor, Obsidian, …) declare additional fields on top via the per-kind extension. `additionalProperties: true` is intentional: skill-map AGGREGATES vendor specs, it does not curate them. Vendor-specific fields (`tools`, `allowedTools`, `model`, etc.) flow through validation silently because the per-kind extension declares them.",
   "type": "object",
   "required": ["name", "description"],
   "additionalProperties": true,
@@ -16,6 +16,11 @@
       "type": "string",
       "minLength": 1,
       "description": "One-to-three-sentence description. REQUIRED."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "**Author-supplied** taxonomy tags written in the markdown frontmatter — what the file's author considers the node's intrinsic categories. Skill-map's tag system is **dual-source**: this field carries author tags; `sidecar.annotations.tags` carries user tags (post-hoc, written by whoever curates the project from their `.sm` sidecar). Both surfaces are first-class — searches and listings (`sm list --tag`, UI faceted search) match the union and the UI distinguishes them visually so the attribution stays explicit. Empty array and missing field are equivalent."
     }
   }
 }

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/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-contracts + input-types catalog version (e.g. `^1.0.0`). Independent from `specCompat` because the catalog evolves on its own cadence (new contracts 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

@@ -129,6 +129,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.",
+      "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` 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.",
   "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",

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" }
   ],