@skill-map/spec 0.18.0 → 0.19.0

package/plugin-author-guide.md

@@ -83,19 +83,20 @@ Concrete examples for the reference impl's bundled extensions:
 | Extension | Short id (in the file) | Qualified id (in the registry) |
 |---|---|---|
 | Claude Provider | `claude` | `claude/claude` |
-| Frontmatter extractor | `frontmatter` | `claude/frontmatter` |
-| Slash extractor | `slash` | `claude/slash` |
-| At-directive extractor | `at-directive` | `claude/at-directive` |
+| Annotations extractor | `annotations` | `core/annotations` |
+| Slash extractor | `slash` | `core/slash` |
+| At-directive extractor | `at-directive` | `core/at-directive` |
+| Markdown-link extractor | `markdown-link` | `core/markdown-link` |
 | External-URL counter | `external-url-counter` | `core/external-url-counter` |
 | Broken-ref rule | `broken-ref` | `core/broken-ref` |
 | Trigger-collision rule | `trigger-collision` | `core/trigger-collision` |
 | ASCII formatter | `ascii` | `core/ascii` |
 | Validate-all rule | `validate-all` | `core/validate-all` |
 
-Two namespaces are convention for built-ins:
+Built-ins split between two namespaces:
 
-- **`core/`** — kernel-internal primitives (every built-in rule including `validate-all`, the ASCII formatter, the external-URL counter extractor). Platform-agnostic.
-- **`claude/`** — the Claude Code Provider bundle (the Provider plus the three extractors that decode Claude-specific syntax: frontmatter, slash, `@`-directive).
+- **`core/`** — kernel-internal primitives, platform-agnostic. Owns every built-in rule (including `validate-all`), the ASCII formatter, and the cross-vendor extractors (`annotations`, `slash`, `at-directive`, `markdown-link`, `external-url-counter`) any Provider can rely on.
+- **`claude/`** — the Claude Code Provider bundle: the Provider that classifies `.claude/{agents,commands,skills}` paths and parses their frontmatter. Vendor-specific bundles (`gemini`, `agent-skills`) follow the same shape — Provider only — since the syntax their nodes use is shared with Claude and lives in `core`.
 
 For your own plugin, the `id` you declare in `plugin.json` is the namespace for every extension the plugin contains. If your manifest declares `id: "my-plugin"` and your extension file declares `id: "foo-extractor"`, the kernel registers it as `my-plugin/foo-extractor`. You do **not** write the qualifier yourself — the loader injects it.
 
@@ -125,15 +126,15 @@ Every plugin and every built-in bundle declares a **granularity** that controls
 
 Built-in mapping:
 
-- **`claude`** — `granularity: 'bundle'`. `sm plugins disable claude` flips the Provider and the three Claude-specific extractors at once.
-- **`core`** — `granularity: 'extension'`. `sm plugins disable core/superseded` flips just the supersession rule; the other six core extensions (the four other rules, the ASCII formatter, the external-URL counter extractor) stay live.
+- **`claude`** / **`gemini`** / **`agent-skills`** — `granularity: 'bundle'`. Each vendor Provider bundle is enabled or disabled as a whole; today every such bundle ships only its Provider, so the toggle flips classification + frontmatter parsing for that platform.
+- **`core`** — `granularity: 'extension'`. `sm plugins disable core/superseded` flips just the supersession rule; every other core extension (every other rule, the ASCII formatter, the cross-vendor extractors) stays live.
 
 Per-verb behaviour:
 
 | Command | Bundle granularity | Extension granularity |
 |---|---|---|
 | `sm plugins enable claude` | OK — flips the bundle. | Rejected: `'core' has granularity=extension; use sm plugins enable core/<ext-id>`. |
-| `sm plugins enable claude/slash` | Rejected: `'claude' has granularity=bundle; use sm plugins enable claude`. | n/a (no bundle of granularity=bundle accepts qualified ids) |
+| `sm plugins enable claude/claude` | Rejected: `'claude' has granularity=bundle; use sm plugins enable claude`. | n/a (no bundle of granularity=bundle accepts qualified ids) |
 | `sm plugins disable core` | n/a | Rejected: same directed message as the bundle row above. |
 | `sm plugins disable core/superseded` | n/a | OK — persists `config_plugins['core/superseded'].enabled = 0`. |
 
@@ -160,7 +161,7 @@ The default (`'bundle'`) is the right answer for almost every plugin — keep th
 
 ### Extractor `applicableKinds` — narrow the pipeline
 
-An `Extractor` extension MAY declare an `applicableKinds` array on its manifest. When declared, the kernel runs the extractor **only** against nodes whose `kind` is in the list — the filter is fail-fast (no extractor context, no method call) so a probabilistic extractor wastes zero LLM cost (and a deterministic extractor zero CPU) on nodes it cannot meaningfully process.
+An `Extractor` extension MAY declare an `applicableKinds` array on its manifest. When declared, the kernel runs the extractor **only** against nodes whose `kind` is in the list — the filter is fail-fast (no extractor context, no method call) so the extractor wastes zero CPU on nodes it cannot meaningfully process.
 
 | `applicableKinds` | Behaviour |
 |---|---|
@@ -171,36 +172,37 @@ An `Extractor` extension MAY declare an `applicableKinds` array on its manifest.
 
 There is no wildcard syntax (no `'*'`) — omitting the field IS the wildcard. The pattern is intentional: a literal absence is unambiguous, a string sentinel would invite typos that silently disable the extractor.
 
-Use case — a probabilistic tag-inferrer that only makes sense for skills:
+Use case — a deterministic frontmatter-tag extractor that only makes sense for skills:
 
 ```javascript
 export default {
-  id: 'tag-inferrer',
+  id: 'tag-extractor',
   kind: 'extractor',
-  mode: 'probabilistic',
   version: '1.0.0',
-  description: 'LLM-derived tag links for skill nodes.',
+  description: 'Lifts the `tags:` frontmatter array into `references` links for skill nodes.',
   emitsLinkKinds: ['references'],
-  defaultConfidence: 'medium',
-  scope: 'body',
+  defaultConfidence: 'high',
+  scope: 'frontmatter',
   applicableKinds: ['skill'],
   async extract(ctx) {
     // Never invoked for agents, commands, hooks, or notes — the kernel
     // skipped this node before reaching us.
-    const tags = await ctx.runner.invoke({ /* prompt … */ });
+    const tags = Array.isArray(ctx.frontmatter.tags) ? ctx.frontmatter.tags : [];
     for (const t of tags) {
       ctx.emitLink({
         source: ctx.node.path,
-        target: t.path,
+        target: t,
         kind: 'references',
-        confidence: 'medium',
-        sources: ['tag-inferrer'],
+        confidence: 'high',
+        sources: ['tag-extractor'],
       });
     }
   },
 };
 ```
 
+> **Why no `mode` field?** Extractors are deterministic-only — they sit on `sm scan`'s synchronous loop, and the loop must stay fast and reproducible. If you need an LLM to infer something about a node (tags, summaries, suspicious imports), write an `Action` instead and let the user dispatch it via `sm job submit action:<id>`. The Action's report flows back through the job lifecycle, not through the Extractor pipeline.
+
 **Unknown kinds are non-blocking.** An extractor that lists a kind no installed Provider declares (typo, missing Provider plugin) still loads with status `loaded`; `sm plugins doctor` surfaces an informational warning so the author sees the mismatch. The exit code of `doctor` is NOT promoted to 1 by this warning — the corresponding Provider may legitimately arrive later (e.g. when the user installs the matching plugin), and the load contract favours forward compatibility over rigid checks. The full set of "known kinds" is the union of every installed Provider's `defaultRefreshAction` keys.
 
 ---
@@ -244,12 +246,12 @@ Authors who explicitly review each minor's changelog **MAY** widen across the ne
 
 ## The six extension kinds
 
-The kernel knows six categories. Four are dual-mode (deterministic or probabilistic per [`architecture.md` §Execution modes](./architecture.md)); two are deterministic-only because they sit at the system boundaries.
+The kernel knows six categories. Three are dual-mode (deterministic or probabilistic per [`architecture.md` §Execution modes](./architecture.md)); three are deterministic-only because they sit on the deterministic scan path.
 
 | Kind | Method | Receives | Returns | Mode |
 |---|---|---|---|---|
 | `provider` | `walk(roots, opts)` | filesystem roots | `IRawNode[]` | deterministic only |
-| `extractor` | `extract(ctx)` | one node + body + frontmatter + callbacks | `void` (output via `ctx.emitLink` / `ctx.enrichNode` / `ctx.store`) | dual-mode |
+| `extractor` | `extract(ctx)` | one node + body + frontmatter + callbacks | `void` (output via `ctx.emitLink` / `ctx.enrichNode` / `ctx.store`) | deterministic only |
 | `rule` | `evaluate(ctx)` | full graph | `Issue[]` | dual-mode |
 | `action` | `run(ctx)` | one or more nodes | execution record | dual-mode |
 | `formatter` | `format(ctx)` | full graph | `string` | deterministic only |
@@ -264,10 +266,10 @@ Pure single-node analysis. **Never** read another node, the graph, or the databa
 The runtime method is `extract(ctx) → void`. Output flows through three callbacks the kernel binds onto the context:
 
 - **`ctx.emitLink(link)`** — append a `Link` to the kernel's `links` table. The kernel validates against the extractor's declared `emitsLinkKinds` before persistence; off-contract kinds are dropped and surface as `extension.error` events. URL-shaped targets are partitioned into `node.externalRefsCount` and never persisted.
-- **`ctx.enrichNode(partial)`** — merge canonical, kernel-curated properties onto the node's enrichment layer (persisted into `node_enrichments` per `db-schema.md`). **Strictly separate from the author-supplied frontmatter** — the latter is IMMUTABLE from any Extractor. Use the enrichment layer for facts the author did not write but the Extractor inferred (computed titles, summaries, signals from probabilistic Extractors). Probabilistic enrichments track `body_hash_at_enrichment`; when the scan loop sees a body change, those rows are flagged `stale = 1` (NOT deleted, preserving the LLM cost paid to produce them) and surface for refresh via `sm refresh <node>` or `sm refresh --stale`. Deterministic enrichments are simply overwritten via PRIMARY KEY conflict on the next re-extract through the A.9 cache and are never stale-flagged.
+- **`ctx.enrichNode(partial)`** — merge canonical, kernel-curated properties onto the node's enrichment layer (persisted into `node_enrichments` per `db-schema.md`). **Strictly separate from the author-supplied frontmatter** — the latter is IMMUTABLE from any Extractor. Use the enrichment layer for facts the author did not write but the Extractor inferred (computed titles, summaries, signals derived from the body). Enrichment rows are overwritten via PRIMARY KEY conflict on the next re-extract through the A.9 cache and are never stale-flagged (Extractors are deterministic; re-running is free).
 - **`ctx.store`** — plugin-scoped persistence. Optional, only present when your `plugin.json` declares `storage.mode`. Shape depends on the mode (`KvStore` for mode A, scoped `Database` for mode B). See [`plugin-kv-api.md`](./plugin-kv-api.md).
 
-A probabilistic extractor additionally receives `ctx.runner` (the `RunnerPort`) for LLM dispatch.
+Extractors are deterministic-only and never see `ctx.runner`. If an Extractor needs LLM-derived data on a node, that workload belongs in an Action — see [`architecture.md` §Execution modes](./architecture.md#execution-modes).
 
 > **Pick a syntax that doesn't collide with built-ins.** The built-in `at-directive` extractor fires on any `@token`; the built-in `slash` extractor fires on any `/token`. A new extractor that also matches one of those prefixes will likely fire on the same input, and if the two emit different `target` shapes the kernel raises a `trigger-collision` error. The example below uses a wikilink-style `[[ref:<name>]]` pattern to side-step this; reserve `@` and `/` for the built-ins.
 
@@ -604,11 +606,11 @@ The kernel validates the row passed to `ctx.store.write(table, row)` against the
 
 ## Execution modes
 
-Extractor / Rule / Action declare `mode` in the manifest with default `deterministic`. Provider / Formatter must NOT declare `mode`.
+Rule / Action / Hook declare `mode` in the manifest. Action's `mode` is required; Rule and Hook default to `deterministic`. Provider / Extractor / Formatter must NOT declare `mode` — they are deterministic-only by spec.
 
 ```jsonc
-// deterministic extractor — default, runs in sm scan
-{ "kind": "extractor", "id": "my-extractor", "mode": "deterministic", ... }
+// extractor — deterministic by spec, no mode field
+{ "kind": "extractor", "id": "my-extractor", ... }
 ```
 
 ```jsonc
@@ -721,7 +723,7 @@ By default a contribution lands inside the plugin's `<plugin-id>:` block at the
 
 ```yaml
 # .claude/agents/architect.sm
-for:
+identity:
   path: .claude/agents/architect.md
   bodyHash: ...
   frontmatterHash: ...
@@ -766,7 +768,7 @@ The resulting sidecar block:
 
 ```yaml
 # .claude/agents/architect.sm
-for: { path: ..., bodyHash: ..., frontmatterHash: ... }
+identity: { path: ..., bodyHash: ..., frontmatterHash: ... }
 compliance:
   audit: sox-2026
   dueAt: 2026-12-31T23:59:59Z
@@ -806,6 +808,278 @@ Pure read; no side effects. Built-in catalog fields from `annotations.schema.jso
 
 ---
 
+## View contributions
+
+> **Status.** Sibling system to annotation contributions, designed to let plugins surface per-node data in the UI without shipping any UI code. Plugin authors pick a **contract** by name from a closed kernel catalog, declare per-node emissions in their extension manifest, and emit payloads at scan time via `ctx.emitContribution(id, payload)`. The UI maps contracts to slots and renders. See [`architecture.md`](./architecture.md) §View contribution system for the normative contract.
+
+### What it solves
+
+Today, the only way a plugin can surface UI is implicit: extractors emit `Link` (rendered by the kernel-built `linked-nodes-panel`), rules emit `Issue` (rendered by the kernel-built issues panel), providers ship `kinds[*].ui` styling, and one-off plugins write into the sidecar via `annotationContributions`. The moment your extractor wants to surface anything else — a counter on each card, a stat breakdown panel in the inspector, a tree showing parsed structure, a per-node tag — there is no path. View contributions fill that gap. You declare what to surface; the UI decides where and how.
+
+### What you NEVER write
+
+- HTML, CSS, JavaScript, or Angular components.
+- JSON Schema for your contributions or your settings.
+- The slot id where your contribution appears (slots are UI-only).
+- The renderer component that draws your contribution.
+
+You DO write:
+
+- The `contract` name (one of 10 closed-catalog values).
+- Optional `label`, `tooltip`, `icon`, `emptyText`, `emitWhenEmpty` per contribution.
+- The per-node payload your `extract(ctx)` emits via `ctx.emitContribution(...)`.
+
+### Manifest shape
+
+Inside any extension manifest (`IExtractor`, `IRule`, ...), declare a `viewContributions` map next to `annotationContributions`. Each key is your local contribution id; the value picks a contract.
+
+```jsonc
+{
+  "id": "keyword-finder",
+  "kind": "extractor",
+  "viewContributions": {
+    "breakdown": {
+      "contract": "node-breakdown",
+      "label": "Keyword hits",
+      "emptyText": "No matches."
+    },
+    "total": {
+      "contract": "node-counter",
+      "icon": "🔍",
+      "label": "kw",
+      "emitWhenEmpty": false
+    }
+  }
+}
+```
+
+Field reference (full schema in [`schemas/view-contracts.schema.json`](./schemas/view-contracts.schema.json) at `$defs/IViewContribution`):
+
+| Field | Required | Notes |
+|---|---|---|
+| `contract` | yes | One of the 10 catalog names (see below). Unknown name → `invalid-manifest` at load. |
+| `label` | no | Short human-readable label. English-only per [`AGENTS.md`](../AGENTS.md) (`Externalized texts, not internationalized`). |
+| `tooltip` | no | Hover tooltip on the chip / panel header. |
+| `icon` | no | Single string. If matches Unicode `\p{Extended_Pictographic}` → emoji. Otherwise → PrimeIcons name (no `pi-` prefix). |
+| `emptyText` | no | Text shown when payload is empty AND `emitWhenEmpty: true`. |
+| `emitWhenEmpty` | no, default `false` | When `false`, kernel drops empty payloads silently so the slot stays clean. |
+
+### Contract catalog (closed)
+
+The kernel ships exactly these 10 contracts. Each has a fixed payload shape and a fixed set of UI slots it surfaces in. Adding a contract requires a spec / UI / scaffolder round-trip — discuss in [`ROADMAP.md`](../ROADMAP.md) before opening a PR.
+
+| Contract | Payload shape | Surfaces in |
+|---|---|---|
+| `node-counter` | `{ value: integer ≥ 0, severity?, label?, tooltip? }` | card chip + inspector header badge |
+| `node-tag` | `{ label, severity?, tooltip? }` | card chip + inspector header badge |
+| `node-breakdown` | `{ entries: Array<{ label, value, tooltip? }> }` (≤ 20) | inspector body (chart-bar) |
+| `node-records` | `{ columns: ≤6, rows: ≤50 }` | inspector body (table) |
+| `node-tree` | recursive `{ label, marker?, children? }` (depth ≤ 6, total ≤ 200) | inspector body (tree) |
+| `node-key-values` | `{ entries: Array<{ key, value, tooltip? }> }` (≤ 50) | inspector body (key-value list) |
+| `node-link-list` | `{ entries: Array<{ path, label?, kind? }> }` (≤ 100) | inspector body (link list) |
+| `node-markdown` | `{ markdown }` (≤ 4096 chars, sanitized) | inspector body (markdown text) |
+| `node-alert` | `{ icon?, severity?, count?, tooltip? }` | graph node corner badge |
+| `scope-stat` | `{ value, label?, severity?, tooltip? }` | topbar indicator |
+
+Per-contract semantics, edge cases, and exact payload schemas live in [`schemas/view-contracts.schema.json`](./schemas/view-contracts.schema.json) at `$defs/payloads/<contract>`. Read that schema before emitting.
+
+### Emit path
+
+Inside `extract(ctx)`, call:
+
+```ts
+ctx.emitContribution('breakdown', {
+  entries: Object.entries(perKeyword).map(([label, value]) => ({ label, value })),
+});
+
+ctx.emitContribution('total', { value: total });
+```
+
+The first argument is the manifest Record key (`'breakdown'` or `'total'` above), NOT the contract name. The kernel composes the qualified id from your plugin id, extension id, and this Record key.
+
+The kernel validates the payload against the contract's payload schema in `view-contracts.schema.json#/$defs/payloads/<contract>`. Off-contract payloads emit an `extension.error` event and drop silently — same posture as `emitLink` rejecting links not in your `emitsLinkKinds`.
+
+For `scope-stat`, rules use `ctx.emitScopeContribution(id, payload)` (extractors do not see this method — scope-level emission lives in rule context).
+
+### Settings
+
+User-configurable settings live at the manifest root in `settings: Record<string, ISettingDeclaration>`. Each entry picks an `input-type` from a closed catalog. You NEVER write JSON Schema for settings.
+
+```jsonc
+{
+  "id": "keyword-finder",
+  "version": "1.0.0",
+  "specCompat": "^0.20.0",
+  "catalogCompat": "^1.0.0",
+  "extensions": ["./extension.js"],
+  "settings": {
+    "keywords": {
+      "type": "string-list",
+      "label": "Keywords to track",
+      "description": "Words counted across each node's body.",
+      "default": ["TODO", "FIXME"],
+      "min": 1
+    },
+    "caseSensitive": {
+      "type": "boolean-flag",
+      "label": "Case-sensitive matching",
+      "default": false
+    }
+  }
+}
+```
+
+The 10 input-types:
+
+| Type | Value at runtime | Use for |
+|---|---|---|
+| `string-list` | `string[]` | keyword lists, ignore patterns |
+| `single-string` | `string` | URLs, names, identifiers |
+| `boolean-flag` | `boolean` | toggles |
+| `integer` | `number` (always integer) | counts, thresholds |
+| `enum-pick` | `string` | pick one from a closed set |
+| `enum-multipick` | `string[]` | pick zero or more |
+| `path-glob` | `string` or `string[]` | glob patterns |
+| `regex` | `string` | ECMAScript regex (body, no `/` delimiters) |
+| `secret` | `string` | tokens, passwords (encrypted at rest) |
+| `key-value-list` | `Array<{ key, value }>` | custom maps, alias dictionaries |
+
+Per-type parameter schema lives in [`schemas/input-types.schema.json`](./schemas/input-types.schema.json) at `$defs/Setting_<TypeName>`.
+
+The kernel exposes resolved settings to extractors via `ctx.settings.<settingId>`. Settings are read once at extractor invocation; **changing a setting requires `sm scan` to re-emit** affected contributions. The UI surfaces a "settings changed, rescan needed" indicator.
+
+### Catalog version
+
+The catalog of contracts and input-types evolves on its own cadence. Declare a semver range in your manifest:
+
+```jsonc
+{ "catalogCompat": "^1.0.0" }
+```
+
+Independent of `specCompat` (the spec version range). Mismatch surfaces as `incompatible-catalog` plugin status; resolution is `sm plugins upgrade <id>`, which runs registered migrations from the kernel's closed migration registry. When auto-migration is impossible (a contract you used was removed entirely), the upgrade verb fails loud (CLI exit ≠ 0 + console message) and your manifest needs a manual edit.
+
+`catalogCompat` is **optional**: omit it if your plugin declares no `viewContributions` and no `settings`. The doctor verb (`sm plugins doctor`) warns if such a plugin actually emits via `viewContributions` or declares `settings`.
+
+### Worked example — `acme/keyword-finder`
+
+Full plugin walkthrough:
+
+```
+plugins/acme-keyword-finder/
+├── plugin.json           ← manifest with settings + catalogCompat
+└── extensions/
+    └── extractor.js       ← extract() with ctx.emitContribution
+```
+
+`plugin.json`:
+
+```jsonc
+{
+  "id": "acme-keyword-finder",
+  "version": "1.0.0",
+  "specCompat": "^0.20.0",
+  "catalogCompat": "^1.0.0",
+  "extensions": ["./extensions/extractor.js"],
+  "settings": {
+    "keywords": {
+      "type": "string-list",
+      "label": "Keywords to track",
+      "default": ["TODO", "FIXME"],
+      "min": 1
+    }
+  }
+}
+```
+
+`extensions/extractor.js`:
+
+```js
+export const extractor = {
+  id: 'keyword-finder',
+  pluginId: 'acme-keyword-finder',
+  kind: 'extractor',
+  version: '1.0.0',
+  description: 'Counts configured keywords per node.',
+  stability: 'stable',
+  mode: 'deterministic',
+  emitsLinkKinds: [],
+  defaultConfidence: 'high',
+  scope: 'body',
+
+  viewContributions: {
+    breakdown: {
+      contract: 'node-breakdown',
+      label: 'Keyword hits',
+      emptyText: 'No matches.',
+    },
+    total: {
+      contract: 'node-counter',
+      icon: '🔍',
+      label: 'kw',
+      emitWhenEmpty: false,
+    },
+  },
+
+  extract(ctx) {
+    const keywords = ctx.settings.keywords;
+    const perKeyword = Object.create(null);
+    let total = 0;
+
+    for (const kw of keywords) {
+      const re = new RegExp(`\\b${escapeRegex(kw)}\\b`, 'gi');
+      const n = (ctx.body.match(re) ?? []).length;
+      perKeyword[kw] = n;
+      total += n;
+    }
+
+    ctx.emitContribution('breakdown', {
+      entries: Object.entries(perKeyword).map(([label, value]) => ({ label, value })),
+    });
+
+    if (total > 0) {
+      ctx.emitContribution('total', { value: total });
+    }
+  },
+};
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+```
+
+After `sm scan`, the UI surfaces:
+
+- A `🔍 N` chip on every node's card (when `total > 0`).
+- A "Keyword hits" panel in the inspector body for every node, with a horizontal bar chart per keyword.
+
+The plugin author wrote zero UI code, zero CSS, zero HTML, zero JSON Schema, and never typed the words "panel", "chip", "renderer", or "slot".
+
+### Scaffolder
+
+Hand-writing the manifest is supported but discouraged. Run:
+
+```sh
+sm plugins create
+```
+
+The scaffolder walks you through the closed catalogs (settings + view contributions) and emits a complete plugin directory with manifest, extension stub, test scaffold, and README. Hand-writing remains valid because the spec is the source of truth, but the scaffolder catches invalid contract picks at author time, while a hand-written manifest only fails at load time.
+
+Companion verbs:
+
+- `sm plugins doctor` — surfaces `incompatible-catalog`, `invalid-manifest`, deprecated-contract usage.
+- `sm plugins upgrade <id>` — applies catalog migrations registered in the kernel.
+- `sm plugins contracts list` — prints the catalog (contracts + input-types), flags deprecated entries.
+
+### Watch out for
+
+- **Don't pick a slot.** The plugin author never types `inspector.body.panel`, `card.footer.left`, etc. Slot mapping is a UI decision; if you find yourself wanting to "place" a contribution, you're working against the model.
+- **Don't write JSON Schema.** Settings use `type` from the input-type catalog; view contributions use `contract` from the contract catalog.
+- **Don't mutate payloads after emission.** The kernel validates and serializes at emit time; a plugin holding a reference to the emitted payload and mutating it later has undefined behavior.
+- **Don't emit HTML.** `node-markdown` accepts markdown with a sanitized allow-list; `[innerHTML]` bindings in the renderer are lint-banned (see [`context/view-contributions.md`](../context/view-contributions.md)).
+- **Don't try to read another plugin's contributions.** The BFF rejects cross-plugin reads at the route level.
+
+---
+
 ## See also
 
 - [`architecture.md`](./architecture.md) — extension contract, ports, execution modes.

package/schemas/annotations.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/annotations.schema.json",
   "title": "Annotations",
-  "description": "Catalog of conventional annotation fields skill-map ships out of the box, written into the `annotations:` block of a sidecar (`<basename>.sm`). Every field is OPTIONAL — a sidecar with an empty `annotations: {}` is valid. Schema is `additionalProperties: true` so users / plugins can add custom keys without coordination; the built-in `unknown-field` rule emits a warning on unrecognized keys (typo guard). The curated catalog is the load-bearing 14 fields below — versioning + supersession (`version`, `stability`, `supersedes`, `supersededBy`, `requires`, `conflictsWith`, `related`), provenance (`authors`, `license`, `source`, `sourceVersion`), taxonomy (`tags`), display (`hidden`), docs (`docsUrl`). The activity timestamp lives in the reserved `audit:` block (`audit.lastBumpedAt`), not in `annotations:`. Plugins that want first-class custom keys with their own validation declare `annotationContributions` in their manifest (see Step 9.6.6).",
+  "description": "Catalog of conventional annotation fields skill-map ships out of the box, written into the `annotations:` block of a sidecar (`<basename>.sm`). Every field is OPTIONAL — a sidecar with an empty `annotations: {}` is valid. Schema is `additionalProperties: true` so users / plugins can add custom keys without coordination; the built-in `unknown-field` rule emits a warning on unrecognized keys (typo guard). The curated catalog is the load-bearing 13 fields below — versioning + supersession (`version`, `stability`, `supersedes`, `supersededBy`, `requires`, `conflictsWith`, `related`), provenance (`authors`, `license`, `source`, `sourceVersion`), taxonomy (`tags`), docs (`docsUrl`). The activity timestamp lives in the reserved `audit:` block (`audit.lastBumpedAt`), not in `annotations:`. Plugins that want first-class custom keys with their own validation declare `annotationContributions` in their manifest (see Step 9.6.6).",
   "type": "object",
   "additionalProperties": true,
   "properties": {
@@ -64,11 +64,7 @@
     "tags": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 },
-      "description": "Free-form taxonomy tags. Consumed by `sm list --tag <name>` and UI faceted search."
-    },
-    "hidden": {
-      "type": "boolean",
-      "description": "When true, the node is excluded from default listings (still appears under `--all` / `--include-hidden`). Useful for in-progress nodes the author does not want surfaced yet."
+      "description": "**User-supplied** taxonomy tags. Skill-map's tag system is dual-source: this field carries the user's post-hoc tags (curator's view of the node from the `.sm` sidecar); `frontmatter.tags` carries the author's tags (intrinsic categories written in the `.md`). Both surfaces are first-class — `sm list --tag <name>` and UI faceted search match the union and the UI distinguishes them visually (`sm list --tag-source author|user` filters one source). Empty array and missing field are equivalent."
     },
     "docsUrl": {
       "type": "string",

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

@@ -24,7 +24,8 @@
         "health",
         "scan",
         "sidecar.bumped",
-        "annotations.registered"
+        "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."
     },
@@ -103,6 +104,26 @@
         }
       }
     },
+    "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"],
@@ -142,8 +163,8 @@
   },
   "oneOf": [
     {
-      "description": "List envelope — `items` payload + `filters` + `counts` (with `returned`) + `kindRegistry`. Used by `/api/nodes`, `/api/links`, `/api/issues`, `/api/plugins`.",
-      "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"] },
         "counts": { "required": ["total", "returned"] }
@@ -157,8 +178,8 @@
       }
     },
     {
-      "description": "Single-resource envelope — `item` payload + `kindRegistry`, no `counts` / `filters`. Used by `/api/nodes/:pathB64`.",
-      "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" }
       },
@@ -171,8 +192,8 @@
       }
     },
     {
-      "description": "Value envelope — `value` payload + `kindRegistry`, no `counts` / `filters`. Used by `/api/config`.",
-      "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" }
       },
@@ -185,7 +206,7 @@
       }
     },
     {
-      "description": "Action-result envelope — `value` + `elapsedMs` siblings, no `filters` / `counts` / `kindRegistry`. 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 kindRegistry is intentionally absent — the action result is orthogonal to the kind catalog and the SPA already has it cached from a prior list call.",
+      "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" }
@@ -196,12 +217,13 @@
           { "required": ["item"] },
           { "required": ["filters"] },
           { "required": ["counts"] },
-          { "required": ["kindRegistry"] }
+          { "required": ["kindRegistry"] },
+          { "required": ["contributionsRegistry"] }
         ]
       }
     },
     {
-      "description": "Catalog envelope — `items` + `counts.total` only, no `filters` / `kindRegistry` / `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`.",
+      "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" },
@@ -215,12 +237,33 @@
           { "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"] }
       },
@@ -230,6 +273,7 @@
           { "required": ["item"] },
           { "required": ["value"] },
           { "required": ["kindRegistry"] },
+          { "required": ["contributionsRegistry"] },
           { "required": ["elapsedMs"] }
         ]
       }

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",
@@ -63,6 +63,16 @@
         }
       },
       "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."
     }
   }
 }