@skill-map/spec 0.18.0 → 0.20.0

package/plugin-author-guide.md

@@ -69,8 +69,8 @@ After every change to the `plugins/` folder, run `sm plugins list` to see the lo
 
 The `id` declared in `plugin.json` is **globally unique** across every active discovery root. The kernel enforces this in two places:
 
-1. **Directory name MUST equal manifest id.** A plugin lives at `<root>/<id>/plugin.json`. If `basename(<plugin-dir>) !== manifest.id`, discovery surfaces the plugin with status `invalid-manifest` and a reason naming both names. This rule eliminates same-root collisions by construction (a filesystem cannot host two siblings with the same name).
-2. **Cross-root id collisions are blocked, both sides.** If two plugins from different roots (project + global, or any combination of `--plugin-dir`) declare the same `id`, **both** receive status `id-collision`. There is no precedence rule — neither plugin loads its extensions; the user resolves the conflict by renaming one and rerunning. Coherent with the spec rule that no extension is privileged.
+1. **Directory name MUST equal manifest id.** A plugin lives at `<root>/<id>/plugin.json`. If `basename(<plugin-dir>) !== manifest.id`, discovery surfaces the plugin with status `invalid-manifest` and a reason naming both names. This analyzer eliminates same-root collisions by construction (a filesystem cannot host two siblings with the same name).
+2. **Cross-root id collisions are blocked, both sides.** If two plugins from different roots (project + global, or any combination of `--plugin-dir`) declare the same `id`, **both** receive status `id-collision`. There is no precedence analyzer — neither plugin loads its extensions; the user resolves the conflict by renaming one and rerunning. Coherent with the spec analyzer that no extension is privileged.
 
 `sm plugins list` shows the conflict; `sm plugins doctor` exits `1` whenever any `id-collision` is present.
 
@@ -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` |
+| Broken-ref analyzer | `broken-ref` | `core/broken-ref` |
+| Trigger-collision analyzer | `trigger-collision` | `core/trigger-collision` |
 | ASCII formatter | `ascii` | `core/ascii` |
-| Validate-all rule | `validate-all` | `core/validate-all` |
+| Validate-all analyzer | `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 analyzer (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.
 
@@ -110,7 +111,7 @@ What this means in practice:
 The kernel guards against two foot-guns:
 
 - If the extension file injects a `pluginId` field that doesn't match `plugin.json#/id`, the loader emits `invalid-manifest` with a directed reason. The composed qualifier MUST come from `plugin.json` — there is no second source of truth.
-- The kebab-case pattern on the extension `id` deliberately forbids `/`. This keeps the rule "the qualifier always lives in the plugin id, never in the extension id" enforced by AJV.
+- The kebab-case pattern on the extension `id` deliberately forbids `/`. This keeps the analyzer "the qualifier always lives in the plugin id, never in the extension id" enforced by AJV.
 
 For built-ins, the reference impl's `src/extensions/built-ins.ts` declares each extension's `pluginId` (`core` or `claude`) explicitly — built-ins do not have a `plugin.json`, so the bundle declaration IS the source of truth for their namespace.
 
@@ -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 analyzer; every other core extension (every other analyzer, 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`. |
 
@@ -150,7 +151,7 @@ In your own plugin's `plugin.json`, set `granularity` only when you opt into the
   "specCompat": "^1.0.0",
   "granularity": "extension",
   "extensions": [
-    "./extensions/orphan-skill-rule.js",
+    "./extensions/orphan-skill-analyzer.js",
     "./extensions/csv-formatter.js"
   ]
 }
@@ -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,13 +246,13 @@ 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 |
-| `rule` | `evaluate(ctx)` | full graph | `Issue[]` | dual-mode |
+| `extractor` | `extract(ctx)` | one node + body + frontmatter + callbacks | `void` (output via `ctx.emitLink` / `ctx.enrichNode` / `ctx.store`) | deterministic only |
+| `analyzer` | `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 |
 | `hook` | `on(ctx)` | a curated lifecycle event payload | `void` (reactions are side effects) | dual-mode |
@@ -259,15 +261,15 @@ The runtime instance you `export default` from an extension file MUST include bo
 
 ### Extractors
 
-Pure single-node analysis. **Never** read another node, the graph, or the database — cross-node reasoning is for rules. Spec at [`schemas/extensions/extractor.schema.json`](./schemas/extensions/extractor.schema.json).
+Pure single-node analysis. **Never** read another node, the graph, or the database — cross-node reasoning is for analyzers. Spec at [`schemas/extensions/extractor.schema.json`](./schemas/extensions/extractor.schema.json).
 
 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.
 
@@ -301,16 +303,16 @@ export default {
 ```
 
 
-### Rules
+### Analyzers
 
-Cross-node reasoning over the merged graph. Run after every Provider and extractor has completed. Spec at [`schemas/extensions/rule.schema.json`](./schemas/extensions/rule.schema.json).
+Cross-node reasoning over the merged graph. Run after every Provider and extractor has completed. Spec at [`schemas/extensions/analyzer.schema.json`](./schemas/extensions/analyzer.schema.json).
 
-Rules are dual-mode (`deterministic` default; `probabilistic` opt-in via the manifest). Deterministic rules run synchronously inside `sm scan` / `sm check` — same CI-safe baseline as today. Probabilistic rules are dispatched as queued jobs via the kernel's `RunnerPort`; they NEVER participate in the deterministic scan-time pipeline. Until the job subsystem ships at Step 10 the dispatch is stubbed: `sm scan` always skips probabilistic rules silently, and `sm check` exposes them via the opt-in `--include-prob` flag — the verb loads the plugin runtime, finds the registered prob rules (filtered by `--rules` and `-n` if set), and emits a stderr advisory naming them. The flag default is unchanged: deterministic-only, CI-safe. The `--async` companion is reserved for the future encoding (returns job ids without waiting once jobs land); today it is a no-op the advisory simply mentions. The flag does NOT extend to `sm scan` or `sm list`.
+Analyzers are dual-mode (`deterministic` default; `probabilistic` opt-in via the manifest). Deterministic analyzers run synchronously inside `sm scan` / `sm check` — same CI-safe baseline as today. Probabilistic analyzers are dispatched as queued jobs via the kernel's `RunnerPort`; they NEVER participate in the deterministic scan-time pipeline. Until the job subsystem ships at Step 10 the dispatch is stubbed: `sm scan` always skips probabilistic analyzers silently, and `sm check` exposes them via the opt-in `--include-prob` flag — the verb loads the plugin runtime, finds the registered prob analyzers (filtered by `--analyzers` and `-n` if set), and emits a stderr advisory naming them. The flag default is unchanged: deterministic-only, CI-safe. The `--async` companion is reserved for the future encoding (returns job ids without waiting once jobs land); today it is a no-op the advisory simply mentions. The flag does NOT extend to `sm scan` or `sm list`.
 
 ```javascript
 export default {
   id: 'orphan-skill',
-  kind: 'rule',
+  kind: 'analyzer',
   version: '1.0.0',
   description: 'Flags skill nodes with zero inbound links.',
   evaluate(ctx) {
@@ -321,7 +323,7 @@ export default {
     return ctx.nodes
       .filter((n) => n.kind === 'skill' && (inboundCount.get(n.path) ?? 0) === 0)
       .map((n) => ({
-        ruleId: 'orphan-skill',
+        analyzerId: 'orphan-skill',
         severity: 'info',
         message: `Skill ${n.path} has no inbound references.`,
         nodeIds: [n.path],
@@ -364,7 +366,7 @@ The eight hookable triggers (declaring any other event yields `invalid-manifest`
 1. `scan.started` — pre-scan setup (one per scan).
 2. `scan.completed` — post-scan reaction (one per scan).
 3. `extractor.completed` — aggregated per-Extractor outputs.
-4. `rule.completed` — aggregated per-Rule outputs.
+4. `analyzer.completed` — aggregated per-Analyzer outputs.
 5. `action.completed` — Action executed on a node.
 6. `job.spawning` — pre-spawn of runner subprocess (Step 10).
 7. `job.completed` — most common trigger (Step 10).
@@ -398,7 +400,7 @@ export default {
 
 > **Mode semantics.** Default `mode: 'deterministic'` runs `on(ctx)` in-process during the dispatch of the matching event, synchronously between the event's emission and the next pipeline step. `mode: 'probabilistic'` enqueues the hook as a job; until the job subsystem ships at Step 10, probabilistic hooks load but skip dispatch with a stderr advisory.
 
-> **What hooks CANNOT do.** Hooks REACT to events; they cannot block emission, mutate the graph, alter Extractor / Rule output, or enrich nodes. For graph mutations use `extractor.enrichNode`; for graph reasoning use a Rule; for periodic background work use a probabilistic Action wrapped in a hook that submits the job. The single-responsibility split keeps the kernel's deterministic baseline stable.
+> **What hooks CANNOT do.** Hooks REACT to events; they cannot block emission, mutate the graph, alter Extractor / Analyzer output, or enrich nodes. For graph mutations use `extractor.enrichNode`; for graph reasoning use a Analyzer; for periodic background work use a probabilistic Action wrapped in a hook that submits the job. The single-responsibility split keeps the kernel's deterministic baseline stable.
 
 ### Providers / Actions
 
@@ -450,15 +452,15 @@ Every Provider declares two required top-level fields beyond the manifest base:
 
 ## Frontmatter validation — three-tier model
 
-The kernel validates frontmatter on a graduated dial; tighter is opt-in. The model is normative — every conforming implementation MUST honour the three tiers — but the policy lives in **rules**, not the JSON Schemas. The schemas stay shape-only ([`schemas/frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) declares `additionalProperties: true` deliberately) so that authors can extend their own nodes without forking the spec. Per-kind frontmatter schemas live with the **Provider** that emits the kind (declared via `provider.kinds[<kind>].schema`); spec only ships the universal `base`.
+The kernel validates frontmatter on a graduated dial; tighter is opt-in. The model is normative — every conforming implementation MUST honour the three tiers — but the policy lives in **analyzers**, not the JSON Schemas. The schemas stay shape-only ([`schemas/frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) declares `additionalProperties: true` deliberately) so that authors can extend their own nodes without forking the spec. Per-kind frontmatter schemas live with the **Provider** that emits the kind (declared via `provider.kinds[<kind>].schema`); spec only ships the universal `base`.
 
 | Tier | Mechanism | Behavior on unknown / non-conforming fields |
 |---|---|---|
-| **0 — Default permissive** | `additionalProperties: true` on `base.schema.json` and on every per-kind frontmatter schema declared by an installed Provider. | Field passes silently, persists in `node.frontmatter`, and is available to every extension (extractors, rules, actions, formatters). |
-| **1 — Built-in `unknown-field` rule** | Deterministic Rule shipped with the kernel. Always active. | Emits an Issue with `severity: 'warn'` for every key outside the documented catalog (base + the matched kind's schema). |
+| **0 — Default permissive** | `additionalProperties: true` on `base.schema.json` and on every per-kind frontmatter schema declared by an installed Provider. | Field passes silently, persists in `node.frontmatter`, and is available to every extension (extractors, analyzers, actions, formatters). |
+| **1 — Built-in `unknown-field` analyzer** | Deterministic Analyzer shipped with the kernel. Always active. | Emits an Issue with `severity: 'warn'` for every key outside the documented catalog (base + the matched kind's schema). |
 | **2 — Strict mode** | [`schemas/project-config.schema.json`](./schemas/project-config.schema.json) `scan.strict: true` (team default in `settings.json`); also via `--strict` on `sm scan`. | Promotes **all** frontmatter warnings to `severity: 'error'`. They persist in the DB; `sm check` then exits `1` on the next read. CI fails. |
 
-> Tier 1 is normative behavior — the kernel ships the rule out-of-the-box. Disabling it is not a supported configuration; an unknown key that you want to keep is either (a) moved under `metadata.*` (the spec permits free-form keys there), or (b) carried as-is at the cost of a persistent `warn`-severity issue (informational unless you run Tier 2).
+> Tier 1 is normative behavior — the kernel ships the analyzer out-of-the-box. Disabling it is not a supported configuration; an unknown key that you want to keep is either (a) moved under `metadata.*` (the spec permits free-form keys there), or (b) carried as-is at the cost of a persistent `warn`-severity issue (informational unless you run Tier 2).
 
 ### Worked example — same node, three tiers
 
@@ -474,20 +476,20 @@ priority: high          # ← author-defined, not in any schema
 ---
 ```
 
-**Tier 0 (default permissive — no project config, default scan).** The field validates fine. `node.frontmatter.priority === 'high'` for any extractor / rule / action that reads the node. No issues raised by the schema itself.
+**Tier 0 (default permissive — no project config, default scan).** The field validates fine. `node.frontmatter.priority === 'high'` for any extractor / analyzer / action that reads the node. No issues raised by the schema itself.
 
-**Tier 1 (always-active `unknown-field` rule).** After `sm scan`, the rule emits:
+**Tier 1 (always-active `unknown-field` analyzer).** After `sm scan`, the analyzer emits:
 
 ```jsonc
 {
-  "ruleId": "unknown-field",
+  "analyzerId": "unknown-field",
   "severity": "warn",
-  "message": "Unknown frontmatter field 'priority' on skill node 'code-reviewer'. Add it to a custom rule or move it under metadata.* if intentional.",
+  "message": "Unknown frontmatter field 'priority' on skill node 'code-reviewer'. Add it to a custom analyzer or move it under metadata.* if intentional.",
   "nodeIds": ["code-reviewer.md"]
 }
 ```
 
-`sm scan` exits `0` (warnings do not fail the verb). The author can either move the key under `metadata.*` — where [`schemas/frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) already permits free-form keys, so the `unknown-field` rule does not match — or accept the persistent warning and add a Rule that consumes `priority` for whatever cross-node logic motivated the field.
+`sm scan` exits `0` (warnings do not fail the verb). The author can either move the key under `metadata.*` — where [`schemas/frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) already permits free-form keys, so the `unknown-field` analyzer does not match — or accept the persistent warning and add a Analyzer that consumes `priority` for whatever cross-node logic motivated the field.
 
 **Tier 2 (strict mode).** Either `scan.strict: true` in `.skill-map/settings.json`, or `sm scan --strict` on the CLI. The same `unknown-field` warning is now persisted at `severity: 'error'`. `sm scan --strict` exits `1` when the issue is created; `sm check` (which reads from the DB) also exits `1` thereafter. CI breaks until the field is reconciled.
 
@@ -503,15 +505,15 @@ The CLI flag wins when both are set (see the `--strict` description on `sm scan`
 
 ### Why no "schema-extender" plugin kind
 
-A reasonable next thought is: "I want my plugin to widen the frontmatter schema so my custom keys are first-class." The spec deliberately rejects that route. The accepted path is to write a deterministic **Rule** that:
+A reasonable next thought is: "I want my plugin to widen the frontmatter schema so my custom keys are first-class." The spec deliberately rejects that route. The accepted path is to write a deterministic **Analyzer** that:
 
 1. Reads the candidate keys from `node.frontmatter` (which Tier 0 already exposes).
 2. Validates them against whatever shape your domain expects (regex, enum, cross-node consistency).
 3. Emits Issues for violations.
 
-The trade-off is intentional: a "schema-extender" kind would force every consumer (the kernel, the storage layer, every other plugin, the UI) to re-resolve the active schema set per scan. A Rule-driven approach keeps the kernel's parser one-pass and the validation surface composable — the union of every author's rules is the project's policy.
+The trade-off is intentional: a "schema-extender" kind would force every consumer (the kernel, the storage layer, every other plugin, the UI) to re-resolve the active schema set per scan. A Analyzer-driven approach keeps the kernel's parser one-pass and the validation surface composable — the union of every author's analyzers is the project's policy.
 
-If the rule needs to be CI-blocking, the rule itself emits the Issue at `severity: 'error'`. `--strict` / `scan.strict` apply only to the kernel's own frontmatter-shape and `unknown-field` warnings; plugin-authored rules pick their own severity directly.
+If the analyzer needs to be CI-blocking, the analyzer itself emits the Issue at `severity: 'error'`. `--strict` / `scan.strict` apply only to the kernel's own frontmatter-shape and `unknown-field` warnings; plugin-authored analyzers pick their own severity directly.
 
 ---
 
@@ -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`.
+Analyzer / Action / Hook declare `mode` in the manifest. Action's `mode` is required; Analyzer 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
@@ -628,7 +630,7 @@ The full per-kind capability matrix lives in [`architecture.md` §Execution mode
 npm install --save-dev @skill-map/testkit
 ```
 
-The testkit ships builders, per-kind context factories, in-memory KV / runner fakes, and high-level `runExtractorOnFixture` / `runRuleOnGraph` / `runFormatterOnGraph` helpers. Most plugin tests reduce to one line per assertion.
+The testkit ships builders, per-kind context factories, in-memory KV / runner fakes, and high-level `runExtractorOnFixture` / `runAnalyzerOnGraph` / `runFormatterOnGraph` helpers. Most plugin tests reduce to one line per assertion.
 
 ```javascript
 import { test } from 'node:test';
@@ -647,7 +649,7 @@ test('emits one reference per [[ref:<name>]] token', async () => {
 });
 ```
 
-For rule tests, `runRuleOnGraph(rule, { context: { nodes, links } })` returns the issue array. For formatter tests, `runFormatterOnGraph(formatter, { context: { nodes, links, issues } })` returns the formatted string.
+For analyzer tests, `runAnalyzerOnGraph(analyzer, { context: { nodes, links } })` returns the issue array. For formatter tests, `runFormatterOnGraph(formatter, { context: { nodes, links, issues } })` returns the formatted string.
 
 For probabilistic extensions, `makeFakeRunner()` queues canned responses and records every call:
 
@@ -675,7 +677,7 @@ Full surface in `@skill-map/testkit/index.ts`.
 | `incompatible-spec` | manifest parsed but `semver.satisfies` failed against the installed spec. | Plugin built against an older / newer spec. |
 | `invalid-manifest` | `plugin.json` missing, unparseable, AJV-fails, OR the directory name does not equal the manifest id. | Typo, missing required field, wrong shape, mismatched directory name. |
 | `load-error` | manifest passed but an extension module failed to import or its default export failed schema validation. | Missing `kind` field, wrong `kind` for the file, runtime import error. |
-| `id-collision` | two plugins reachable from different roots declared the same `id`. Both collided plugins receive this status; no precedence rule applies. | Project-local plugin and a user-global plugin (or two `--plugin-dir` plugins) sharing an id. Rename one and rerun. |
+| `id-collision` | two plugins reachable from different roots declared the same `id`. Both collided plugins receive this status; no precedence analyzer applies. | Project-local plugin and a user-global plugin (or two `--plugin-dir` plugins) sharing an id. Rename one and rerun. |
 
 `sm plugins doctor` runs the full load pass and exits 1 if any plugin is in a non-`loaded` / non-`disabled` state (so any of `incompatible-spec` / `invalid-manifest` / `load-error` / `id-collision` trips it). Wire it into CI to catch breakage early.
 
@@ -713,7 +715,7 @@ Field-by-field:
 | `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.
+The `schema` field is **inline** — an object literal in the manifest, not a `$ref` to a file. Aligns with how the extractor / analyzer / action schemas already declare other inline shapes; avoids an extra path-resolution step at load time.
 
 ### Namespacing default vs root opt-in
 
@@ -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: ...
@@ -740,10 +742,10 @@ auditor:
 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
+// compliance-plugin/extensions/analyzer.js
 export default {
   id: 'compliance-checker',
-  kind: 'rule',
+  kind: 'analyzer',
   // ...
   annotationContributions: {
     compliance: {
@@ -766,13 +768,13 @@ 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
 ```
 
-### Ownership rules
+### Ownership analyzers
 
 - `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".
@@ -785,13 +787,13 @@ This is the only fatal path on the plugin-load surface. Every other failure mode
 
 ### 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:
+The built-in `core/unknown-field` Analyzer 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.
+The analyzer 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
 
@@ -806,11 +808,314 @@ 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 **slot** by name from a closed kernel catalog; the slot fixes both the renderer and the payload shape. Authors declare per-node emissions in their extension manifest and emit payloads at scan time via `ctx.emitContribution(id, payload)`. 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`), analyzers 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 and where; the kernel validates the payload against the slot's shape and the UI renders.
+
+### What you NEVER write
+
+- HTML, CSS, JavaScript, or Angular components.
+- JSON Schema for your contributions or your settings.
+- The renderer component that draws your contribution.
+
+You DO write:
+
+- The `slot` name (one of 15 closed-catalog values). The slot you pick fixes both where the data renders and what payload shape the kernel will accept.
+- 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`, `IAnalyzer`, ...), declare a `viewContributions` map next to `annotationContributions`. Each key is your local contribution id; the value picks a slot.
+
+```jsonc
+{
+  "id": "keyword-finder",
+  "kind": "extractor",
+  "viewContributions": {
+    "breakdown": {
+      "slot": "inspector.body.panel.breakdown",
+      "label": "Keyword hits",
+      "emptyText": "No matches."
+    },
+    "total": {
+      "slot": "card.footer.left.counter",
+      "icon": "🔍",
+      "label": "kw",
+      "emitWhenEmpty": false
+    }
+  }
+}
+```
+
+Field reference (full schema in [`schemas/view-slots.schema.json`](./schemas/view-slots.schema.json) at `$defs/IViewContribution`):
+
+| Field | Required | Notes |
+|---|---|---|
+| `slot` | yes | One of the 15 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, but required for counter slots and `card.title.right` | 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. |
+
+### Slot catalog (closed)
+
+The kernel ships exactly these 15 slots. Each slot fixes a renderer + a payload shape; multiple slots may share a payload shape (e.g. all counter slots accept `{ value }`). Adding a slot requires a spec / UI / scaffolder round-trip — discuss in [`ROADMAP.md`](../ROADMAP.md) before opening a PR.
+
+| Slot | Payload shape | Renderer |
+|---|---|---|
+| `card.title.right` | `{ icon?, severity?, tooltip? }` | icon marker (manifest icon required) |
+| `card.subtitle.left` | `{ value: integer ≥ 0, severity?, tooltip? }` | counter chip (manifest icon required) |
+| `card.footer.left.counter` | `{ value: integer ≥ 0, severity?, tooltip? }` | counter chip (manifest icon required) |
+| `card.footer.right` | `{ value: integer ≥ 0, severity?, tooltip? }` | counter chip (manifest icon required) |
+| `graph.node.alert` | `{ icon?, severity?, count?, tooltip? }` | graph corner badge |
+| `inspector.header.badge.counter` | `{ value: integer ≥ 0, severity?, tooltip? }` | counter chip (manifest icon required) |
+| `inspector.header.badge.tag` | `{ label, severity?, tooltip? }` | tag chip |
+| `inspector.body.panel.breakdown` | `{ entries: Array<{ label, value, tooltip? }> }` (≤ 20) | bar chart panel |
+| `inspector.body.panel.records` | `{ columns: ≤6, rows: ≤50 }` | table panel |
+| `inspector.body.panel.tree` | recursive `{ label, marker?, children? }` (depth ≤ 6, total ≤ 200) | tree panel |
+| `inspector.body.panel.key-values` | `{ entries: Array<{ key, value, tooltip? }> }` (≤ 50) | definition list panel |
+| `inspector.body.panel.link-list` | `{ entries: Array<{ path, label?, kind? }> }` (≤ 100) | clickable list panel |
+| `inspector.body.panel.markdown` | `{ markdown }` (≤ 4096 chars, sanitized) | sanitized markdown panel |
+| `topbar.actions.indicator` | `{ value, label?, severity?, tooltip? }` | scope chip |
+
+Per-slot semantics, edge cases, and exact payload schemas live in [`view-slots.md`](./view-slots.md) (catalog reference) and [`schemas/view-slots.schema.json`](./schemas/view-slots.schema.json) at `$defs/payloads/<slot>`. Read those 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 slot name. The kernel composes the qualified id from your plugin id, extension id, and this Record key, and looks up the slot you declared in the manifest to validate the payload.
+
+The kernel validates the payload against the slot's payload schema in `view-slots.schema.json#/$defs/payloads/<slot>`. Off-shape payloads emit an `extension.error` event and drop silently — same posture as `emitLink` rejecting links not in your `emitsLinkKinds`.
+
+For `topbar.actions.indicator`, analyzers use `ctx.emitScopeContribution(id, payload)` (extractors do not see this method — scope-level emission lives in analyzer context).
+
+### Multi-slot rendering
+
+Want the same data in two surfaces? Declare two contributions, each pointing at a different slot. There is no broadcast — the slot you pick is the slot the data renders in.
+
+```jsonc
+"viewContributions": {
+  "mentionsFooter": {
+    "slot": "card.footer.left.counter",
+    "icon": "@",
+    "label": "mentions"
+  },
+  "mentionsBadge": {
+    "slot": "inspector.header.badge.counter",
+    "icon": "@",
+    "label": "mentions"
+  }
+}
+```
+
+Then emit twice (typically with the same value):
+
+```ts
+ctx.emitContribution('mentionsFooter', { value: count });
+ctx.emitContribution('mentionsBadge', { value: count });
+```
+
+This is intentional: one source of truth per surface, no surprise duplication when a renderer changes its mind about which slots to draw in.
+
+### 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 slots 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 slot 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: {
+      slot: 'inspector.body.panel.breakdown',
+      label: 'Keyword hits',
+      emptyText: 'No matches.',
+    },
+    total: {
+      slot: 'card.footer.left.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 zero renderer logic.
+
+### Scaffolder
+
+Hand-writing the manifest is supported but discouraged. Run:
+
+```sh
+sm plugins create
+```
+
+The scaffolder walks you through the closed catalogs (settings + view contribution slots) 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 slot 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-slot usage.
+- `sm plugins upgrade <id>` — applies catalog migrations registered in the kernel.
+- `sm plugins slots list` — prints the catalog (slots + input-types), flags deprecated entries.
+
+### Watch out for
+
+- **Pick exactly one slot per contribution.** The slot determines both the renderer and the payload shape. If you want the same data in two surfaces (e.g. card chip + inspector badge), declare two contributions in the manifest, one per slot, and emit twice.
+- **Don't write JSON Schema.** Settings use `type` from the input-type catalog; view contributions use `slot` from the slot 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.
 - [`plugin-kv-api.md`](./plugin-kv-api.md) — Storage Mode A normative API.
-- [`db-schema.md`](./db-schema.md) — table catalog and migration rules (Mode B).
+- [`db-schema.md`](./db-schema.md) — table catalog and migration analyzers (Mode B).
 - [`schemas/plugins-registry.schema.json`](./schemas/plugins-registry.schema.json) — normative manifest shape.
 - [`schemas/extensions/*.schema.json`](./schemas/extensions) — per-kind manifest schemas.
 
@@ -820,8 +1125,8 @@ Pure read; no side effects. Built-in catalog fields from `annotations.schema.jso
 
 - Document status: **stable** as of spec v1.0.0. Future minor revisions add new sections (e.g. richer testkit coverage when actions gain helpers); breaking edits to the documented surface require a major bump per [`versioning.md`](./versioning.md).
 - The six plugin statuses (`loaded` / `disabled` / `incompatible-spec` / `invalid-manifest` / `load-error` / `id-collision`) are stable; adding a seventh status is a minor bump.
-- The structural rule **directory name MUST equal manifest id** is stable; relaxing it (allowing mismatch) is a major bump.
-- The cross-root id-collision rule (both sides blocked, no precedence) is stable; introducing precedence (e.g. project root wins over global) is a major bump.
+- The structural analyzer **directory name MUST equal manifest id** is stable; relaxing it (allowing mismatch) is a major bump.
+- The cross-root id-collision analyzer (both sides blocked, no precedence) is stable; introducing precedence (e.g. project root wins over global) is a major bump.
 - The `granularity` field on `PluginManifest` is stable as introduced. The two values (`bundle` / `extension`) are stable. Adding a third value is a minor bump; changing the default away from `bundle` is a major bump (every existing plugin manifest would silently flip toggle semantics).
 - The optional `applicableKinds` field on the Extractor manifest is stable as introduced. Adding a wildcard syntax (`'*'`) is a minor bump (additive, the existing "absent = all kinds" semantics keeps holding); changing the default away from "applies to every kind" or making the field required is a major bump. Promoting the unknown-kinds doctor warning to a hard load error is a major bump (today's contract is "load OK, surface as warning").
 - The recommended `specCompat` strategy is descriptive prose; revising the recommendation does not require a spec bump as long as the schema stays unchanged.