@skill-map/spec 0.17.0 → 0.19.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/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` / `hook` / `note` today, but external Providers (Cursor, Obsidian, …) MAY emit their own.",
+  "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,33 +14,12 @@
     "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` / `hook` / `note`; external Providers MAY declare their own). Per-kind frontmatter schemas live with the Provider that emits the kind. Stability: stable."
+      "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."
     },
     "provider": {
       "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": ["string", "null"],
-      "description": "Denormalized from `metadata.version` for fast queries. Must be a valid semver if present."
-    },
-    "author": {
-      "type": ["string", "null"],
-      "description": "Denormalized from `metadata.author` for fast queries."
-    },
     "frontmatter": {
       "type": "object",
       "description": "Full parsed frontmatter. See `frontmatter/base.schema.json` and `frontmatter/<kind>.schema.json`.",
@@ -78,6 +57,14 @@
       "type": "integer",
       "minimum": 0,
       "description": "http/https URLs in the body after normalization and exact-match dedup."
+    },
+    "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."
+    },
+    "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."
     }
   },
   "$defs": {
@@ -90,6 +77,32 @@
         "body": { "type": "integer", "minimum": 0 },
         "total": { "type": "integer", "minimum": 0 }
       }
+    },
+    "sidecarOverlay": {
+      "type": "object",
+      "required": ["present"],
+      "additionalProperties": false,
+      "properties": {
+        "present": {
+          "type": "boolean",
+          "description": "True when a `<basename>.sm` file accompanies the node on disk; false otherwise."
+        },
+        "status": {
+          "type": ["string", "null"],
+          "enum": ["fresh", "stale-body", "stale-frontmatter", "stale-both", null],
+          "description": "Drift status. NULL when no sidecar is present, or when the sidecar exists but failed to parse / validate (the row still records `present: true` so clients can distinguish absent from broken)."
+        },
+        "annotations": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "description": "Parsed `annotations:` block from the sidecar. NULL when no sidecar is present, when the block is absent / empty, or when the sidecar failed to parse / validate."
+        },
+        "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."
+        }
+      }
     }
   }
 }

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/report-base-deterministic.schema.json

@@ -0,0 +1,15 @@
+{
+  "$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.",
+  "type": "object",
+  "required": ["ok"],
+  "additionalProperties": true,
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "description": "True when the Action completed its logical work; false when it refused / errored. Silent no-ops (e.g. `force: true` against an already-fresh node) still report `ok: true` with an action-specific marker (e.g. bump's `noop: true`)."
+    }
+  }
+}

package/schemas/sidecar.schema.json

@@ -0,0 +1,96 @@
+{
+  "$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` 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": ["identity"],
+  "additionalProperties": true,
+  "properties": {
+    "identity": {
+      "$ref": "#/$defs/identity",
+      "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 13-field surface; users / plugins MAY add custom keys (rides on `additionalProperties: true`)."
+    },
+    "settings": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Reserved for skill-map's per-node settings. v0.18.0 ships the block empty; consumers ride on `additionalProperties: true`. Concrete fields land in later sub-steps as the runtime grows."
+    },
+    "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."
+    }
+  },
+  "$defs": {
+    "audit": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "lastBumpedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 datetime of the last `bump` Action invocation that materialised a write to this sidecar. Atomically set together with `lastBumpedBy` on every bump."
+        },
+        "lastBumpedBy": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identity of the bump invoker. Literal `'cli'` for `sm bump` (we are not threading user identity yet); `'plugin:<plugin-id>'` when a plugin's deterministic Action triggered the bump. Tests / future invokers MAY pass any non-empty string."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 datetime of the first `bump` invocation that ever wrote this sidecar. Set exactly once (when the `.sm` file did not previously exist on disk); stable across subsequent bumps."
+        },
+        "createdBy": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identity of the invoker that created the sidecar (same value form as `lastBumpedBy`). Set exactly once at creation time and stable thereafter."
+        }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "required": ["path", "bodyHash", "frontmatterHash"],
+      "additionalProperties": true,
+      "properties": {
+        "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."
+        },
+        "bodyHash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "sha256 of the body content (post-frontmatter), hex-encoded lowercase, captured at the moment this sidecar was last bumped. Compared against the current body hash to detect drift."
+        },
+        "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."
+        },
+        "resolvedAs": {
+          "type": "object",
+          "required": ["provider", "kind"],
+          "additionalProperties": false,
+          "properties": {
+            "provider": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Provider id that classifies this node (e.g. `claude`)."
+            },
+            "kind": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Kind within the Provider (e.g. `agent`, `skill`)."
+            }
+          },
+          "description": "Optional override of the Provider/kind classification. Set when path-based + content-based matching are ambiguous (a single `.md` matched by multiple Providers). When present, locks the classification to (`provider`, `kind`); when absent, the kernel uses its normal classification pipeline."
+        }
+      }
+    }
+  }
+}

package/schemas/summaries/{note.schema.json → markdown.schema.json}

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/summaries/note.schema.json",
-  "title": "SummaryNote",
-  "description": "Report produced by `note-summarizer` for a single `note` node. Extends `report-base.schema.json`. Stability: experimental.",
+  "$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.",
   "allOf": [
     { "$ref": "../report-base.schema.json" }
   ],
@@ -14,7 +14,7 @@
     "safety": true,
     "whatItCovers": {
       "type": "string",
-      "description": "One-sentence summary of the note's subject matter. REQUIRED. Named distinctly from `whatItDoes` since notes describe, not act."
+      "description": "One-sentence summary of the file's subject matter. REQUIRED. Named distinctly from `whatItDoes` since markdown notes describe, not act."
     },
     "topics": {
       "type": "array",
@@ -23,7 +23,7 @@
     },
     "keyFacts": {
       "type": "array",
-      "description": "Discrete claims or data points the note asserts. Useful for search and diffing over time.",
+      "description": "Discrete claims or data points the file asserts. Useful for search and diffing over time.",
       "items": { "type": "string" }
     },
     "relatedNodes": {