@skill-map/spec 0.17.0 → 0.19.0

package/schemas/api/rest-envelope.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/api/rest-envelope.schema.json",
   "title": "RestEnvelope",
-  "description": "Wrapper shape for REST responses under `/api/*` (Step 14.2). Three variants distinguished by the `kind` discriminator and which payload field is present (`items` for list kinds, `item` for single-resource kinds, `value` for `kind: 'config'`). The `/api/scan` and `/api/health` responses are exempt — they carry the underlying `ScanResult` / `IHealthResponse` shape directly. The `/api/graph` response is also exempt — it returns the formatter's native textual output (text/plain or text/markdown). Step 14.5.d adds the required `kindRegistry` field on every payload-bearing variant so the UI can render Provider-declared kinds (label, color, icon) without hardcoding visuals; sentinel kinds (`health`, `scan`, `graph`) stay exempt because they don't carry an envelope payload. The change keeps `schemaVersion` at `'1'` — the BFF is greenfield (no released consumers run against `'1'` without `kindRegistry`), so a versioned migration buys nothing.",
+  "description": "Wrapper shape for REST responses under `/api/*` (Step 14.2). Five variants distinguished by the `kind` discriminator and which payload field is present (`items` for list kinds AND `'annotations.registered'`, `item` for single-resource kinds, `value` for `kind: 'config'` and `'sidecar.bumped'`). The `/api/scan` and `/api/health` responses are exempt — they carry the underlying `ScanResult` / `IHealthResponse` shape directly. The `/api/graph` response is also exempt — it returns the formatter's native textual output (text/plain or text/markdown). Step 14.5.d adds the required `kindRegistry` field on every payload-bearing list / single / config variant so the UI can render Provider-declared kinds (label, color, icon) without hardcoding visuals; sentinel kinds (`health`, `scan`, `graph`) stay exempt because they don't carry an envelope payload. Step 9.6 closes the `'sidecar.bumped'` (R7) and `'annotations.registered'` (R7) gaps — both are payload-bearing but carry their own variant shapes (sidecar.bumped: `value` + `elapsedMs`, no `filters`/`counts`/`kindRegistry`; annotations.registered: `items` + `counts.total`, no `filters`/`kindRegistry`) because they project read-only kernel surfaces orthogonal to the kindRegistry. The change keeps `schemaVersion` at `'1'` — the BFF is greenfield (no released consumers depend on the prior shape), so a versioned migration buys nothing.",
   "type": "object",
   "required": ["schemaVersion", "kind"],
   "properties": {
@@ -13,8 +13,21 @@
     },
     "kind": {
       "type": "string",
-      "enum": ["nodes", "links", "issues", "plugins", "config", "graph", "node", "health", "scan"],
-      "description": "Discriminator. List kinds (`nodes`, `links`, `issues`, `plugins`) carry `items`. The `node` kind carries `item`. The `config` kind carries `value`. The `health` / `scan` / `graph` values are reserved for documentation parity with the routes that DON'T use this envelope."
+      "enum": [
+        "nodes",
+        "links",
+        "issues",
+        "plugins",
+        "config",
+        "graph",
+        "node",
+        "health",
+        "scan",
+        "sidecar.bumped",
+        "annotations.registered",
+        "contributions.registered"
+      ],
+      "description": "Discriminator. List kinds (`nodes`, `links`, `issues`, `plugins`) carry `items` + `filters` + `counts` + `kindRegistry`. The `node` kind carries `item` + `kindRegistry`. The `config` kind carries `value` + `kindRegistry`. The `sidecar.bumped` kind (Step 9.6.5, BFF half) carries `value` + `elapsedMs` (no `filters` / `counts` / `kindRegistry` — it's an action-result projection orthogonal to the kindRegistry surface). The `annotations.registered` kind (Step 9.6.6, BFF half) carries `items` + `counts.total` (no `filters` / `kindRegistry` — pure read-only catalog projection). The `health` / `scan` / `graph` values are reserved for documentation parity with the routes that DON'T use this envelope."
     },
     "items": {
       "type": "array",
@@ -26,7 +39,12 @@
     },
     "value": {
       "type": "object",
-      "description": "Present when `kind` is `'config'`. Carries the merged effective config object."
+      "description": "Present when `kind` is `'config'` or `'sidecar.bumped'`. For `'config'`, carries the merged effective config object. For `'sidecar.bumped'`, carries `{ nodePath, version, status }` (the Action-result payload from `POST /api/sidecar/bump`)."
+    },
+    "elapsedMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Wall-clock milliseconds the BFF spent serving the request. Present on action-result envelopes (`kind: 'sidecar.bumped'`); absent elsewhere."
     },
     "filters": {
       "type": "object",
@@ -34,49 +52,81 @@
     },
     "kindRegistry": {
       "type": "object",
-      "description": "Catalog of node kinds active in the current scope, keyed by kind name. Built once per server boot from every enabled Provider's `kinds` map and embedded into every payload-bearing envelope so the UI can render kind tags / palette swatches / graph nodes against Provider-declared visuals (label, color, icon) without ever hardcoding a closed kind enum. Sentinel envelopes (`health`, `scan`, `graph`) are exempt.",
+      "description": "Catalog of node kinds active in the current scope, keyed by kind name. Built once per server boot from every enabled Provider's `kinds` map and embedded into every payload-bearing envelope so the UI can render kind tags / palette swatches / graph nodes against Provider-declared visuals (label, color, icon) without ever hardcoding a closed kind enum. Sentinel envelopes (`health`, `scan`, `graph`) are exempt. Each entry MAY carry contributions from multiple Providers when several declare the same kind name (e.g. Claude `agent` and Gemini `agent`); the `providers` map keeps every contribution and `primaryProviderId` points at the one whose visuals drive the kind's primary CSS var. The kernel separately surfaces `provider-ambiguous` issues for files matched by more than one Provider; the UI may still receive the merged registry during the conflict window.",
       "additionalProperties": {
         "type": "object",
-        "required": ["providerId", "label", "color"],
+        "required": ["primaryProviderId", "providers"],
         "additionalProperties": false,
         "properties": {
-          "providerId": {
+          "primaryProviderId": {
             "type": "string",
             "minLength": 1,
-            "description": "Id of the Provider that contributed this kind. Lets the UI scope kind ownership and disambiguate when two Providers happen to declare the same kind name (kernel surfaces this as `provider-ambiguous` but the UI may still receive the merged registry during the conflict window)."
+            "description": "Id of the Provider whose visuals drive the kind's primary CSS var (`--sm-kind-<kind>`). Set on first registration (first Provider in iteration order); subsequent contributors append to `providers` without overwriting the primary."
           },
-          "label": { "type": "string", "minLength": 1 },
-          "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
-          "colorDark": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
-          "emoji": { "type": "string", "minLength": 1, "maxLength": 8 },
-          "icon": {
-            "oneOf": [
-              {
-                "type": "object",
-                "required": ["kind", "id"],
-                "additionalProperties": false,
-                "properties": {
-                  "kind": { "const": "pi" },
-                  "id": { "type": "string", "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$" }
-                }
-              },
-              {
-                "type": "object",
-                "required": ["kind", "path"],
-                "additionalProperties": false,
-                "properties": {
-                  "kind": { "const": "svg" },
-                  "path": { "type": "string", "minLength": 1 }
+          "providers": {
+            "type": "object",
+            "minProperties": 1,
+            "description": "Per-provider visuals for this kind name. Keyed by Provider id (e.g. `'claude'`, `'gemini'`). Lets the UI render a node painted with its own Provider's color via `entry.providers[node.provider]` when the kind name is shared across Providers.",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["label", "color"],
+              "additionalProperties": false,
+              "properties": {
+                "label": { "type": "string", "minLength": 1 },
+                "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                "colorDark": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                "emoji": { "type": "string", "minLength": 1, "maxLength": 8 },
+                "icon": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "required": ["kind", "id"],
+                      "additionalProperties": false,
+                      "properties": {
+                        "kind": { "const": "pi" },
+                        "id": { "type": "string", "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$" }
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "required": ["kind", "path"],
+                      "additionalProperties": false,
+                      "properties": {
+                        "kind": { "const": "svg" },
+                        "path": { "type": "string", "minLength": 1 }
+                      }
+                    }
+                  ]
                 }
               }
-            ]
+            }
           }
         }
       }
     },
+    "contributionsRegistry": {
+      "type": "object",
+      "description": "Catalog of registered view contributions active in the current scope, keyed by qualified contribution id `<pluginId>/<extensionId>/<contributionId>`. Built once per server boot from every enabled extension's `viewContributions` map and embedded into every payload-bearing envelope so the UI can fetch the catalog without a separate request. Sentinel envelopes (`health`, `scan`, `graph`), action-result envelopes (`sidecar.bumped`), and the catalog envelopes themselves (`annotations.registered`, `contributions.registered`) are exempt. Mirror of `kindRegistry`, parallel surface. Each entry references a contract by name from the closed catalog at `view-contracts.schema.json#/$defs/ContractName`; the UI consults its own contract→slot mapping (slots are UI-only) to render. Per-node payloads are delivered separately on `node` envelopes (single via `item.contributions`) or list envelopes (`items[].contributions`, only when `limit ≤ bff.maxBulkContributions`, default 200).",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["pluginId", "extensionId", "contributionId", "contract"],
+        "additionalProperties": false,
+        "properties": {
+          "pluginId": { "type": "string", "minLength": 1 },
+          "extensionId": { "type": "string", "minLength": 1 },
+          "contributionId": { "type": "string", "minLength": 1 },
+          "contract": { "$ref": "../view-contracts.schema.json#/$defs/ContractName" },
+          "label": { "type": "string", "maxLength": 64 },
+          "tooltip": { "type": "string", "maxLength": 256 },
+          "icon": { "type": "string", "maxLength": 64 },
+          "emptyText": { "type": "string", "maxLength": 128 },
+          "emitWhenEmpty": { "type": "boolean", "default": false }
+        }
+      }
+    },
     "counts": {
       "type": "object",
-      "required": ["total", "returned"],
+      "required": ["total"],
       "properties": {
         "total": {
           "type": "integer",
@@ -86,7 +136,7 @@
         "returned": {
           "type": "integer",
           "minimum": 0,
-          "description": "Rows actually carried in `items` (≤ `limit`)."
+          "description": "Rows actually carried in `items` (≤ `limit`). Present on list-kind envelopes (`nodes`, `links`, `issues`, `plugins`); absent on `'annotations.registered'` (no pagination, no filters — the catalog ships in its entirety in every response)."
         },
         "page": {
           "type": "object",
@@ -108,51 +158,112 @@
         }
       },
       "additionalProperties": false,
-      "description": "Tally + paging info. Present on every list / single envelope; absent on `health` / `scan` / `graph` responses (which don't use this envelope)."
+      "description": "Tally + paging info. Present on every list / single envelope; absent on `health` / `scan` / `graph` responses (which don't use this envelope). The list variants additionally require `returned`; the `'annotations.registered'` variant only requires `total`."
     }
   },
   "oneOf": [
     {
-      "description": "List envelope — `items` payload + `counts` + `kindRegistry`.",
-      "required": ["items", "counts", "filters", "kindRegistry"],
+      "description": "List envelope — `items` payload + `filters` + `counts` (with `returned`) + `kindRegistry` + `contributionsRegistry`. Used by `/api/nodes`, `/api/links`, `/api/issues`, `/api/plugins`.",
+      "required": ["items", "counts", "filters", "kindRegistry", "contributionsRegistry"],
       "properties": {
-        "kind": { "enum": ["nodes", "links", "issues", "plugins"] }
+        "kind": { "enum": ["nodes", "links", "issues", "plugins"] },
+        "counts": { "required": ["total", "returned"] }
       },
       "not": {
         "anyOf": [
           { "required": ["item"] },
-          { "required": ["value"] }
+          { "required": ["value"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     },
     {
-      "description": "Single-resource envelope — `item` payload + `kindRegistry`, no `counts` / `filters`.",
-      "required": ["item", "kindRegistry"],
+      "description": "Single-resource envelope — `item` payload + `kindRegistry` + `contributionsRegistry`, no `counts` / `filters`. Used by `/api/nodes/:pathB64`.",
+      "required": ["item", "kindRegistry", "contributionsRegistry"],
       "properties": {
         "kind": { "const": "node" }
       },
       "not": {
         "anyOf": [
           { "required": ["items"] },
-          { "required": ["value"] }
+          { "required": ["value"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     },
     {
-      "description": "Value envelope — `value` payload + `kindRegistry`, no `counts` / `filters`.",
-      "required": ["value", "kindRegistry"],
+      "description": "Value envelope — `value` payload + `kindRegistry` + `contributionsRegistry`, no `counts` / `filters`. Used by `/api/config`.",
+      "required": ["value", "kindRegistry", "contributionsRegistry"],
       "properties": {
         "kind": { "const": "config" }
       },
       "not": {
         "anyOf": [
           { "required": ["items"] },
-          { "required": ["item"] }
+          { "required": ["item"] },
+          { "required": ["elapsedMs"] }
+        ]
+      }
+    },
+    {
+      "description": "Action-result envelope — `value` + `elapsedMs` siblings, no `filters` / `counts` / `kindRegistry` / `contributionsRegistry`. Used by `POST /api/sidecar/bump` (Step 9.6.5, BFF half) where the response carries the bump report (`{ nodePath, version, status }`) plus the wall-clock duration. The registries are intentionally absent — the action result is orthogonal to both catalogs and the SPA already has them cached from a prior list call.",
+      "required": ["value", "elapsedMs"],
+      "properties": {
+        "kind": { "const": "sidecar.bumped" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["item"] },
+          { "required": ["filters"] },
+          { "required": ["counts"] },
+          { "required": ["kindRegistry"] },
+          { "required": ["contributionsRegistry"] }
+        ]
+      }
+    },
+    {
+      "description": "Annotation-catalog envelope — `items` + `counts.total` only, no `filters` / `kindRegistry` / `contributionsRegistry` / `returned`. Used by `GET /api/annotations/registered` (Step 9.6.6, BFF half). The catalog is small (typically 0–50 entries), ships in its entirety on every response, and does not paginate; `counts.total` doubles as `items.length`.",
+      "required": ["items", "counts"],
+      "properties": {
+        "kind": { "const": "annotations.registered" },
+        "counts": {
+          "not": { "required": ["returned"] }
+        }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["item"] },
+          { "required": ["value"] },
+          { "required": ["filters"] },
+          { "required": ["kindRegistry"] },
+          { "required": ["contributionsRegistry"] },
+          { "required": ["elapsedMs"] }
+        ]
+      }
+    },
+    {
+      "description": "View-contributions-catalog envelope — `items` + `counts.total` only, no `filters` / `kindRegistry` / `contributionsRegistry` / `returned`. Used by `GET /api/contributions/registered`. Mirror of `annotations.registered`. The catalog ships in entirety; `counts.total` doubles as `items.length`. Each item is an `IRegisteredViewContribution` shape: `{ pluginId, extensionId, contributionId, contract, label?, tooltip?, icon?, emptyText?, emitWhenEmpty? }`.",
+      "required": ["items", "counts"],
+      "properties": {
+        "kind": { "const": "contributions.registered" },
+        "counts": {
+          "not": { "required": ["returned"] }
+        }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["item"] },
+          { "required": ["value"] },
+          { "required": ["filters"] },
+          { "required": ["kindRegistry"] },
+          { "required": ["contributionsRegistry"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     },
     {
-      "description": "Sentinel kinds — reserved for routes that do NOT carry an envelope payload at the wire level (`health`, `scan`, `graph`). They do not carry `kindRegistry` either; clients that need it must call any payload-bearing endpoint at boot.",
+      "description": "Sentinel kinds — reserved for routes that do NOT carry an envelope payload at the wire level (`health`, `scan`, `graph`). They do not carry `kindRegistry` or `contributionsRegistry` either; clients that need either must call any payload-bearing endpoint at boot.",
       "properties": {
         "kind": { "enum": ["health", "scan", "graph"] }
       },
@@ -161,7 +272,9 @@
           { "required": ["items"] },
           { "required": ["item"] },
           { "required": ["value"] },
-          { "required": ["kindRegistry"] }
+          { "required": ["kindRegistry"] },
+          { "required": ["contributionsRegistry"] },
+          { "required": ["elapsedMs"] }
         ]
       }
     }

package/schemas/bump-report.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/bump-report.schema.json",
+  "title": "BumpReport",
+  "description": "Report shape produced by the built-in deterministic `bump` Action (Step 9.6.3, Decision #125). Extends `report-base-deterministic.schema.json` (the deterministic counterpart to `report-base.schema.json`, which carries the LLM-only `confidence` + `safety` fields). The bump Action returns one of three concrete shapes, distinguished by `ok` / `noop` / `reason`: success-with-write (`{ ok: true, version }`), silent-no-op under `force` (`{ ok: true, noop: true }`), or refusal (`{ ok: false, reason: 'fresh' }`).",
+  "allOf": [{ "$ref": "report-base-deterministic.schema.json" }],
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "noop": {
+      "type": "boolean",
+      "description": "True when the Action accepted the request but did not produce a write (the node was already fresh and `force: true` opted into the silent no-op path). Mutually exclusive with `version`."
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["fresh"],
+      "description": "Refusal reason, present only when `ok: false`. `fresh` = the node has no drift versus its sidecar and the caller did not pass `force: true`."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The new `annotations.version` value the Action wrote. Present only when `ok: true` and `noop` is absent."
+    },
+    "createdSidecar": {
+      "type": "boolean",
+      "description": "True when this bump created the `.sm` file (no sidecar existed on disk before). Triggers the `audit.createdAt` / `audit.createdBy` fill-in."
+    }
+  }
+}

package/schemas/extensions/base.schema.json

@@ -9,7 +9,7 @@
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
-      "description": "Kebab-case identifier unique within the extension's kind across the same plugin. The kernel registers every extension under the **qualified** id `<plugin-id>/<id>` (e.g. `core/frontmatter`, `claude/slash`, `hello-world/greet`) — see `architecture.md` §Extension kinds and `plugin-author-guide.md` §Qualified extension ids. Authors declare only the short id here; the qualifier is composed by the loader from the manifest's `id` (or, for built-ins, from the bundle declaration in `built-ins.ts`). The pattern is intentionally constrained to a single kebab-case segment without the `/` separator: the qualifier always lives in the plugin id, never in the extension id."
+      "description": "Kebab-case identifier unique within the extension's kind across the same plugin. The kernel registers every extension under the **qualified** id `<plugin-id>/<id>` (e.g. `core/annotations`, `core/slash`, `hello-world/greet`) — see `architecture.md` §Extension kinds and `plugin-author-guide.md` §Qualified extension ids. Authors declare only the short id here; the qualifier is composed by the loader from the manifest's `id` (or, for built-ins, from the bundle declaration in `built-ins.ts`). The pattern is intentionally constrained to a single kebab-case segment without the `/` separator: the qualifier always lives in the plugin id, never in the extension id."
     },
     "kind": {
       "type": "string",
@@ -38,6 +38,41 @@
     "entry": {
       "type": "string",
       "description": "Optional path to the module exporting this extension (relative to the plugin root). Absent → the kernel uses the path listed in the plugin manifest's `extensions[]` array."
+    },
+    "annotationContributions": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["schema"],
+        "additionalProperties": false,
+        "properties": {
+          "schema": {
+            "type": "object",
+            "description": "Inline JSON Schema for this contribution's value. Validated when the kernel routes a sidecar write through the extension's namespace (or root key, see `location`). Must be a valid JSON Schema document; an invalid `schema` rejects the extension at load with `invalid-manifest`."
+          },
+          "ownership": {
+            "enum": ["exclusive", "shared"],
+            "default": "shared",
+            "description": "Conflict policy for this key. `shared` (default) — the key is namespaced by default; multiple plugins MAY contribute to the same key, last-write-wins per the SidecarStore's deep-merge semantics. `exclusive` — only this plugin may write the key. REQUIRED when `location: 'root'` (a top-level reserved key cannot be silently shared between plugins)."
+          },
+          "location": {
+            "enum": ["namespaced", "root"],
+            "default": "namespaced",
+            "description": "Where the key lands inside the sidecar. `namespaced` (default) — written under the plugin's `<plugin-id>:` block at the sidecar root. `root` — written as a top-level key alongside the reserved blocks (`for`, `annotations`, `settings`, `audit`); requires `ownership: 'exclusive'` and is treated as elevated trust (two plugins claiming the same root key with `exclusive` is a hard-fail at orchestrator init). See `plugin-author-guide.md` §Annotation contributions."
+          }
+        }
+      },
+      "description": "Plugin-contributed annotation keys. Each entry declares an inline JSON Schema for the value the extension writes into a sidecar. Keys default to the plugin's `<plugin-id>:` namespace; opt-in to top-level via `location: 'root'` (requires `ownership: 'exclusive'`). The kernel exposes the runtime catalog via `kernel.getRegisteredAnnotationKeys()` for UI autocomplete; the built-in `core/unknown-field` Rule emits a warning on truly unrecognized keys (typo guard). See `plugin-author-guide.md` §Annotation contributions for the worked examples."
+    },
+    "viewContributions": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "../view-contracts.schema.json#/$defs/IViewContribution"
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+      },
+      "description": "Plugin-contributed view contributions. Each entry declares one rendering surface in the UI by picking a `contract` name from the closed catalog at `view-contracts.schema.json#/$defs/ContractName`. The kernel validates the manifest at load (`invalid-manifest` on unknown contract); the plugin emits per-node payloads via `ctx.emitContribution(<contributionId>, payload)` during scan; the runtime validates payloads against the contract's payload schema in `view-contracts.schema.json#/$defs/payloads/<contract>`; off-contract payloads emit `extension.error` and drop silently (mirror of `emitLink` off-contract drop). The kernel exposes the runtime catalog via `kernel.getRegisteredViewContributions()`; the BFF surfaces it at `GET /api/contributions/registered`. The plugin author NEVER picks a slot — slot mapping is a UI decision (see `ROADMAP.md` §UI contribution system). See `plugin-author-guide.md` §View contributions for worked examples."
     }
   }
 }

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" }
   ],
@@ -21,6 +21,28 @@
       "description": "Path globs (relative to scope root) that this Provider SHOULD be consulted for. Advisory — the kernel walks all roots and consults every Provider regardless, but this field lets `sm doctor` warn when no file matched a specific Provider (i.e. the Provider was loaded for a platform that isn't in this scope).",
       "items": { "type": "string" }
     },
+    "read": {
+      "type": "object",
+      "required": ["extensions", "parser"],
+      "additionalProperties": false,
+      "description": "Declarative file-discovery config consumed by the kernel walker. When present, the kernel walks every root, includes files whose extension matches `extensions`, parses each with the parser registered as `parser`, and yields raw nodes the orchestrator consumes. When absent, the kernel applies the default `{ extensions: ['.md'], parser: 'frontmatter-yaml' }` so the most common Provider shape needs no configuration. When a Provider also declares the runtime `walk()` method (TypeScript-only — never appears in this manifest), `walk()` wins and `read` is ignored: the runtime field is the escape hatch for Providers with non-standard discovery requirements. Built-in parsers ship with the kernel (`frontmatter-yaml`, `plain`); the set is closed by design and user plugins cannot register their own.",
+      "properties": {
+        "extensions": {
+          "type": "array",
+          "minItems": 1,
+          "description": "File extensions the walker yields. Strings include the leading dot. Lowercase-only by convention — match is case-sensitive and Providers MUST list every casing they want recognised.",
+          "items": {
+            "type": "string",
+            "pattern": "^\\.[a-z0-9]+$"
+          }
+        },
+        "parser": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identifier of a parser registered in the kernel-internal registry. Built-ins: `frontmatter-yaml` (markdown with `--- … ---` YAML frontmatter, prototype-pollution-safe, `js-yaml` JSON_SCHEMA-pinned), `plain` (entire body, empty frontmatter — for files carrying no frontmatter convention; the Provider derives `name` from the path inside `classify()`). Unknown ids surface as `UnknownParserError` from the walker; the orchestrator translates the error into a Provider issue with status `invalid-manifest`."
+        }
+      }
+    },
     "kinds": {
       "type": "object",
       "description": "Catalog of node kinds this Provider emits. Keyed by kind name (e.g. `skill`, `agent`, `note`). Each entry declares the relative path to the kind's frontmatter schema (the kernel resolves it against the Provider's package directory) and the qualified `defaultRefreshAction` id the UI dispatches when the user requests a probabilistic refresh on a node of that kind. The map MUST be non-empty: a Provider that emits no kinds is meaningless. Kind names follow camelCase / lowerCase convention; the spec does not constrain the value space (a Cursor Provider could declare `rule`, an Obsidian Provider could declare `daily`).",

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."
     }
   }
 }