@skill-map/spec 0.17.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
@@ -681,6 +683,403 @@ Full surface in `@skill-map/testkit/index.ts`.
 
 ---
 
+## Annotation contributions
+
+> **Status.** Ships with spec v0.18.0 (Step 9.6.6). Plugins that want to write first-class fields into a node's co-located `.sm` sidecar declare them in their extension manifest under `annotationContributions`. The kernel validates the contributions at load time, surfaces the runtime catalog via `kernel.getRegisteredAnnotationKeys()` (consumed by the BFF / UI for autocomplete), and treats two plugins claiming the same root-exclusive key as a fatal startup error.
+
+### Manifest shape
+
+`annotationContributions` is an object map keyed by the annotation key the extension wants to own. Each entry declares an inline JSON Schema for the value plus two policy fields:
+
+```js
+// my-plugin/extensions/extractor.js
+export default {
+  id: 'my-extractor',
+  kind: 'extractor',
+  version: '1.0.0',
+  // ...rest of the extractor manifest...
+  annotationContributions: {
+    lastReviewedAt: {
+      schema: { type: 'string', format: 'date-time' },
+      // location and ownership default to 'namespaced' / 'shared'
+    },
+  },
+};
+```
+
+Field-by-field:
+
+| Field        | Type                              | Default        | Meaning                                                                                              |
+|--------------|-----------------------------------|----------------|------------------------------------------------------------------------------------------------------|
+| `schema`     | inline JSON Schema (object)       | required       | Validates the value the extension writes under this key. Compiled with AJV at load time.            |
+| `location`   | `'namespaced'` \| `'root'`        | `'namespaced'` | Where the key lands inside the sidecar (see below).                                                  |
+| `ownership`  | `'shared'` \| `'exclusive'`       | `'shared'`     | Conflict policy. REQUIRED to be `'exclusive'` when `location: 'root'`.                              |
+
+The `schema` field is **inline** — an object literal in the manifest, not a `$ref` to a file. Aligns with how the extractor / rule / action schemas already declare other inline shapes; avoids an extra path-resolution step at load time.
+
+### Namespacing default vs root opt-in
+
+By default a contribution lands inside the plugin's `<plugin-id>:` block at the sidecar root. Two plugins can ship a contribution with the same key and never collide because the runtime path keeps them under separate namespaces:
+
+```yaml
+# .claude/agents/architect.sm
+identity:
+  path: .claude/agents/architect.md
+  bodyHash: ...
+  frontmatterHash: ...
+annotations:
+  version: 3
+
+# Plugin 'reviewer' contributes 'lastReviewedAt'
+reviewer:
+  lastReviewedAt: 2026-05-06T10:00:00Z
+
+# Plugin 'auditor' also contributes 'lastReviewedAt' — different namespace, no conflict
+auditor:
+  lastReviewedAt: 2026-05-05T18:30:00Z
+```
+
+Opting into a top-level (root) key requires `location: 'root'` AND `ownership: 'exclusive'`. The pair travels together — a top-level reserved key cannot be silently shared between plugins, because `.sm` writes deep-merge per the `SidecarStore` contract and a shared root key would route non-deterministically. Use root sparingly: for every plugin that contributes a root key, the kernel reserves that name across the whole installed-plugin surface.
+
+```js
+// compliance-plugin/extensions/rule.js
+export default {
+  id: 'compliance-checker',
+  kind: 'rule',
+  // ...
+  annotationContributions: {
+    compliance: {
+      schema: {
+        type: 'object',
+        required: ['audit'],
+        properties: {
+          audit: { type: 'string' },
+          dueAt: { type: 'string', format: 'date-time' },
+        },
+      },
+      location: 'root',
+      ownership: 'exclusive',
+    },
+  },
+};
+```
+
+The resulting sidecar block:
+
+```yaml
+# .claude/agents/architect.sm
+identity: { path: ..., bodyHash: ..., frontmatterHash: ... }
+compliance:
+  audit: sox-2026
+  dueAt: 2026-12-31T23:59:59Z
+```
+
+### Ownership rules
+
+- `shared` (default) — multiple plugins MAY write the same key. Every plugin gets its own namespaced block; `last-write-wins` is per-`(plugin, key)` tuple inside `FilesystemSidecarStore.applyPatch`. Two plugins on the SAME namespaced key from the same plugin id is structurally impossible (one extension per kind per plugin id by spec), so the only collision surface is intra-extension.
+- `exclusive` — only this plugin may write the key. The kernel rejects any other plugin that tries to claim the same `(key, location: 'root')` tuple as `exclusive`. `exclusive` + `namespaced` is permitted but redundant in practice (the namespace already isolates by plugin id); use it as documentation when you want the manifest to scream "no other plugin should ever write this".
+
+### Collision behaviour — hard fail, no boot
+
+Two plugins claiming the same `(key, location: 'root', ownership: 'exclusive')` tuple is a **fatal startup error**. The kernel does NOT boot in this state — `loadPluginRuntime` throws `AnnotationContributionConflictError` and the host (CLI verb, BFF, watch mode) propagates the error and exits non-zero with a clear stderr message naming both offenders. Stricter than the default per-plugin `invalid-manifest` "disable just that plugin" path: annotation-namespace conflicts are non-recoverable because annotated `.sm` files would otherwise become non-deterministically routed.
+
+This is the only fatal path on the plugin-load surface. Every other failure mode (manifest invalid, schema invalid, dynamic-import failure, id collision) is per-plugin and the kernel keeps booting on the survivors.
+
+### Tier-1 typo guard (`core/unknown-field`)
+
+The built-in `core/unknown-field` Rule walks every parsed `.sm` and emits a `warn` issue per truly-unknown key. Three surfaces are checked:
+
+1. Inside `annotations:` — keys not in `annotations.schema.json`'s curated catalog (the ~25 conventional fields). Plugins do NOT contribute to `annotations:`; that block is skill-map-curated.
+2. At the sidecar root — keys outside the four reserved blocks (`for`, `annotations`, `settings`, `audit`) that are also NOT a registered plugin namespace `<plugin-id>:` AND NOT a registered `location: 'root'` contribution.
+3. Inside a registered `<plugin-id>:` namespace — values that fail the schema declared by the owning plugin's `annotationContributions[<key>].schema`.
+
+The rule never blocks a scan; advisories surface through the standard issue channel (CLI, UI, REST). When you ship a contribution, the loader compiles your inline schema, the runtime catalog publishes it, and `core/unknown-field` automatically validates user writes against your declaration.
+
+### Runtime catalog accessor
+
+Once every plugin has loaded, the runtime catalog is reachable via `kernel.getRegisteredAnnotationKeys()`:
+
+```ts
+// Each entry: { pluginId, key, location, ownership, schema }
+const keys = kernel.getRegisteredAnnotationKeys();
+```
+
+Pure read; no side effects. Built-in catalog fields from `annotations.schema.json` are NOT included — this catalog is plugin-only. The UI knows the built-in catalog separately via the schema bundle. The (future) BFF endpoint surfaces this through `GET /api/annotations/catalog` for autocomplete.
+
+---
+
+## 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

@@ -0,0 +1,75 @@
+{
+  "$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 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": {
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonic counter. Bumped via the built-in `bump` Action when the underlying node changes meaningfully. Orthogonal to `stability` — `stability` carries the lifecycle stage; `version` is just a counter. There is no major: a change so big it would justify a major bump uses the convention `create a new node, supersede the old one` instead. Default: missing == unversioned."
+    },
+    "stability": {
+      "type": "string",
+      "enum": ["experimental", "stable", "deprecated"],
+      "description": "Lifecycle stage. Denormalized into `scan_nodes.stability` for fast queries (see `node.schema.json` #/properties/stability). Default: missing == unspecified."
+    },
+    "supersedes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of nodes this node replaces. Consumed by the built-in `superseded` rule and surfaces in `sm list --superseded`."
+    },
+    "supersededBy": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path (relative to scope root) of the node that replaces this one. When set, the current node is end-of-life and consumers should migrate."
+    },
+    "requires": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of nodes this node depends on. Surfaces in the dependency graph; the `broken-ref` rule flags missing targets."
+    },
+    "conflictsWith": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of nodes that cannot be active alongside this one. Surfaces in conflict detection (post-v0.5.0)."
+    },
+    "related": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Paths (relative to scope root) of conceptually related nodes. Soft link for navigation; no strong semantics, no rule enforcement."
+    },
+    "authors": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Multi-author list. Single-author files use a one-element array."
+    },
+    "license": {
+      "type": "string",
+      "minLength": 1,
+      "description": "SPDX identifier preferred (e.g. `MIT`, `Apache-2.0`); free-form accepted."
+    },
+    "source": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the canonical upstream (e.g. GitHub raw URL). Consumed by the `github-enrichment` Action for hash verification."
+    },
+    "sourceVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Tag, branch, or full commit SHA at the upstream. Drives `github-enrichment` SHA pin / tag resolution."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "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",
+      "format": "uri",
+      "description": "Canonical docs URL for this node (separate from `source`, which points at the file's upstream)."
+    }
+  }
+}