@skill-map/spec 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,339 @@
 # Spec changelog
 
+## 0.28.0
+
+### Minor Changes
+
+- e21216e: Simplify plugin manifest fields beyond the file-layout refactor. The
+  previous `structure-as-truth-plugins` changeset moved bundle / kind /
+  id discovery onto the filesystem; this one extends the same principle
+  into the manifest schemas themselves so the only fields that survive
+  are the ones the kernel cannot derive from disk.
+
+  **Plugin manifest (`plugin.json`):**
+
+  - Drop `id` (the directory name is the id; AJV rejects manifests that
+    declare it).
+  - `description` and `catalogCompat` are now required (were optional).
+  - `granularity` is now optional with a default of `'extension'` (was
+    required). Most plugins drop the field entirely.
+  - Drop `settings` at the plugin level; settings move to the extension
+    manifests that actually consume them.
+
+  **Extension base (every kind):**
+
+  - Drop `id`, `kind`, `stability`, `preconditions` (free-form). The
+    loader injects `id` / `kind` / `pluginId` from the folder layout;
+    the other two were display-only and free-form respectively, and
+    the kernel never consumed them.
+  - `description` is now required.
+  - Rename `annotationContributions` (map) to `annotation` (singular):
+    one extension contributes at most one annotation key, and the key
+    is the extension's folder name. Use multiple extensions to
+    contribute multiple keys.
+  - Rename `viewContributions` to `ui` on the manifest. The
+    runtime-aggregated catalog (`Kernel.getRegisteredViewContributions()`,
+    `IPluginRuntimeBundle.viewContributions`) keeps its name.
+  - Add `settings: Record<id, ISettingDeclaration>` (moved from the
+    plugin manifest).
+
+  **Provider:**
+
+  - Drop the inline `kinds` map. The kind catalog now lives under
+    `<plugin>/kinds/<kindName>/` with two files per kind:
+    `schema.json` (frontmatter schema) and `kind.json` carrying the
+    `{ ui }` block. The loader walks the directory and projects each
+    entry into the runtime `kinds` descriptor.
+  - New schema `extensions/provider-kind.schema.json` validates the
+    `kind.json` shape.
+  - Drop `defaultRefreshAction`. The UI's `🧠 prob` refresh button is
+    retired; a replacement UX is TBD.
+  - `roots` is enforcement-grade: a Provider with declared `roots`
+    only sees files matching at least one glob; a Provider without
+    `roots` acts as the fallback for files unmatched by any other
+    Provider. Supported patterns: `prefix/**` (deep), `prefix/*`
+    (shallow), exact path. Two Providers whose roots both match the
+    same file produce `provider-ambiguous` (already in spec) and the
+    file stays unclassified.
+
+  **Extractor:**
+
+  - Drop `emitsLinkKinds` (the global closed enum of link kinds is the
+    contract; off-enum emissions drop with `extension.error`).
+  - Drop `defaultConfidence` (declare confidence per-emit on
+    `ctx.emitLink({ ..., confidence })`).
+  - Drop `applicableKinds` (array). Use `precondition.kind` instead with
+    qualified ids like `'claude/agent'`. The same `precondition` shape
+    is shared with Analyzer and Action.
+
+  **Analyzer:**
+
+  - Drop `emitsAnalyzerIds` (the qualified extension id is the default
+    `analyzer_id`).
+  - Drop `defaultSeverity` (declare severity per-emit on
+    `ctx.emitIssue({ ..., severity })`).
+  - Drop `consumes`, `configurable`, `recommendedActions`. The
+    analyzer↔action relationship is now declared from the Action side
+    via `precondition.analyzerIds` (Modelo B): one Action says "I
+    resolve these analyzer findings", instead of one Analyzer saying
+    "these actions help".
+  - Add `precondition: { kind?, provider? }` (same shape as Extractor).
+
+  **Action:**
+
+  - Drop `reportSchemaRef` and `promptTemplateRef`. The kernel now
+    resolves these by convention from the action folder:
+    `<action-dir>/report.schema.json` (always required) and
+    `<action-dir>/prompt.md` (required when `mode='probabilistic'`,
+    forbidden when `mode='deterministic'`).
+  - Drop `expectedTools`, `fanOutPolicy`, `precondition.stability`,
+    `precondition.custom`.
+  - Add `precondition.analyzerIds` (Modelo B).
+  - Rename `expectedDurationSeconds` to `probExpectedDurationSeconds`
+    to mark it as probabilistic-only via the `prob*` prefix convention.
+  - `mode` is now optional with default `'deterministic'` (was
+    required).
+
+  **Formatter:**
+
+  - Drop `formatId` (comes from the folder name; the loader injects it
+    into the runtime instance).
+  - Drop `supportsFilter` (every formatter supports `--filter`).
+
+  **Hook:**
+
+  - Drop `mode`. Hooks are deterministic-only; LLM-dependent reactions
+    are modeled as a deterministic hook that enqueues a probabilistic
+    Action via `ctx.queue('<plugin>/<action>', payload)`.
+
+  **Loader changes (`src/kernel/adapters/plugin-loader/`):**
+
+  - The exported manifest is stripped of any `id` / `kind` / `pluginId`
+    / `kinds` / `formatId` keys before AJV validation; the loader
+    injects the canonical values from the folder layout. Legacy
+    manifests that still inline these fields load cleanly.
+  - New `discoverProviderKinds(...)` reads `<plugin>/kinds/<k>/{schema.json,
+kind.json}` and merges the result into the runtime Provider
+    instance. Failure modes: missing or unparseable `schema.json`
+    → `load-error`; missing, unparseable, or AJV-invalid `kind.json`
+    → `invalid-manifest`.
+  - New `validateActionFileConventions(...)` enforces the
+    `report.schema.json` / `prompt.md` conventions.
+  - New `matchesAnyRoot(...)` powers Provider `roots` enforcement
+    inside `processRawNode`.
+
+  **Spec docs:**
+
+  - `architecture.md` §Extension kinds table, §Provider · `kinds`
+    catalog, §View contribution system updated.
+  - `plugin-author-guide.md` §Manifest section rewritten (id from
+    folder; description/catalogCompat required), §Extractor section
+    reworked around `precondition.kind`, drop guidance for
+    `emitsLinkKinds` / `defaultConfidence`.
+  - `view-slots.md` references `ui` map.
+
+  **Built-ins migration:**
+
+  - `core/bump/report.schema.json` and `core/mark-superseded/report.schema.json`
+    added (file conventions).
+  - `core/tools-count` extractor uses
+    `precondition: { kind: ['claude/agent'] }`.
+  - All built-in extensions drop `stability`, `preconditions`,
+    `emitsLinkKinds`, `defaultConfidence`, `emitsAnalyzerIds`,
+    `defaultSeverity`, `consumes`, `configurable`, `recommendedActions`,
+    `defaultRefreshAction`, `formatId` (formatter), `supportsFilter`,
+    `mode` (hook).
+  - `scripts/generate-built-ins.js` updated: `id` from bundle folder,
+    `granularity ?? 'extension'`, `toExtensionRow` drops the retired
+    display fields.
+
+  **Testkit:**
+
+  - `makeExtractorContext` populates `settings: {}` so test fixtures
+    satisfy the new required field on `IExtractorContext`.
+
+  ## User-facing
+
+  **Plugin manifests are smaller.** `plugin.json` drops `id`; every extension declares only `version` + `description` plus kind-specific fields. View contributions move to `ui:`. Provider kinds live under `kinds/<kindName>/`. Run `sm plugins doctor` after upgrading.
+
+- 8b7abbf: Structure-as-truth refactor for plugin extensions. The filesystem
+  layout (rather than declarative manifest fields) is now the single
+  source of truth for bundle / kind / extension id.
+
+  **Schema changes:**
+
+  - `PluginManifest` drops the required `extensions: string[]` array;
+    the kernel now auto-discovers extensions by walking
+    `<plugin-dir>/<kind>s/<name>/index.{js,mjs,ts}` for each known
+    kind. `granularity` is now required (no implicit default).
+  - `ExtensionBase` drops the `entry` field (it was an override for
+    the now-gone `extensions[]` path; the loader computes the entry
+    path from the discovered file).
+  - `viewContributions` moves from `base.schema.json` to
+    `extractor.schema.json` and `analyzer.schema.json`. Runtime
+    `ctx.emitContribution` only exists for those two kinds; declaring
+    view contributions on other kinds used to be a silent no-op and
+    is now rejected at manifest load.
+
+  **Loader changes:**
+
+  - `<plugin-dir>/<kind>s/<name>/` is the unit of discovery; the
+    loader walks `providers`, `extractors`, `analyzers`, `actions`,
+    `formatters`, `hooks` in canonical order, looking for an
+    `index.{js,mjs,ts}` inside each name directory.
+  - A manifest whose `kind` disagrees with the folder it lives under
+    (e.g. an `extractor` placed under `analyzers/`) is rejected as
+    `invalid-manifest` with a directed reason.
+  - Containment is enforced by construction: the loader never reads
+    paths the manifest could redirect, so `..`-escape and
+    absolute-path lanes are closed without runtime checks.
+
+  **Built-ins reorganization:**
+
+  - Source tree renamed `src/built-in-plugins/` → `src/plugins/` and
+    reorganized to `src/plugins/<bundle>/<kind>s/<name>/index.ts`.
+    Each bundle (`core`, `claude`, `gemini`, `agent-skills`) gains a
+    `plugin.json` with its metadata.
+  - `src/plugins/built-ins.ts` is now generated by
+    `scripts/generate-built-ins.js` (runs as `prebuild`, checked for
+    drift by `built-ins:check` in CI). The generator walks the
+    filesystem, reads each bundle's `plugin.json`, and emits static
+    imports + the legacy API surface (`builtIns()`,
+    `listBuiltIns()`, `builtInBundles`).
+
+  **Scaffolder (`sm plugins create`):**
+
+  - Emits the new layout: `extractors/<plugin-id>-extractor/index.js`
+    plus a `plugin.json` without `extensions` and without
+    `pluginId` on the extension export (the loader injects it from
+    `plugin.json#/id`). The legacy `mode: 'deterministic'` field on
+    the extractor stub was a no-op holdover from when extractors had
+    a mode and has been removed.
+
+  **Per-extension co-located files convention:**
+
+  Files that share the extension's folder with `index.{js,mjs,ts}`
+  are author-owned siblings. Two blessed names so consumers know
+  where to look:
+
+  - `text.ts` for externalised user-facing strings (one per
+    extension, imported by `index.ts` as `./text.js`).
+  - `<extension-name>.test.{ts,mjs,js}` for the colocated test
+    suite (picked up by the workspace's `plugins/**/*.test.ts`
+    glob).
+
+  Both are optional; the loader ignores anything that is not
+  `index.{js,mjs,ts}`, so future schemas / fixtures / conformance
+  scopes can live next to the code without manifest plumbing. The
+  in-tree built-ins under `src/plugins/` were migrated to this
+  shape: each analyzer's user-facing strings now live at
+  `<bundle>/analyzers/<name>/text.ts` instead of a centralised
+  `i18n/` directory.
+
+  ## User-facing
+
+  **Plugin layout changed.** Extensions now live at `<kind>s/<name>/index.js` (e.g. `extractors/keyword-counter/index.js`); `plugin.json` no longer lists `extensions[]` and requires `granularity`. Run `sm plugins doctor` after migrating, or use `sm plugins create` for new plugins.
+
+## 0.27.0
+
+### Minor Changes
+
+- f1efd1b: Remove the `-g/--global` flag and every implicit `$HOME` read from
+  skill-map. The CLI now operates exclusively on the project scope
+  (`<cwd>/.skill-map/`); there is no global / user scope, no
+  `SKILL_MAP_SCOPE` env var, no silent merge of user-level config or
+  plugins.
+
+  The user extends the scan beyond the project root via the existing
+  `scan.extraFolders` setting in project-local config (privacy-gated
+  through `sm config set --yes` or the Settings UI confirm dialog).
+  Plugins outside the project install per-project at
+  `<cwd>/.skill-map/plugins/` or load via the `--plugin-dir <path>`
+  escape hatch on the `sm plugins …` verb family.
+
+  **Narrow documented exception**: a single `~/.skill-map/settings.json`
+  file (validated by `user-settings.schema.json`) holds genuinely
+  per-machine preferences. Today it carries the update-check toggle +
+  its throttle bookkeeping; future per-machine settings (locale, theme)
+  extend it under their own sub-keys. There is no `.local` partner.
+  The file is NOT part of the project config layer system; it is read
+  directly by the module that owns each feature. `src/cli/util/user-settings-store.ts`
+  is the only module that calls `os.homedir()` for this file. The two
+  remaining `os.homedir()` callsites (`core/config/helper.ts`,
+  `core/runtime/reference-paths-walker.ts`) handle user-typed `~/foo`
+  expansion inside `scan.extraFolders` / `scan.referencePaths`, the
+  read is user-authored per invocation, not skill-map's own default.
+
+  Removed surface (`@skill-map/cli`):
+
+  - `-g/--global` flag inherited by every `SmCommand` verb (`bump`,
+    `check`, `config`, `export`, `graph`, `history`, `init`, `jobs`,
+    `list`, `orphans`, `refresh`, `scan`, `serve`, `show`, `sidecar`,
+    `watch`, every `plugins` subcommand). Calling any verb with
+    `-g/--global` now exits 2 with Clipanion's "unknown option" error.
+  - `SKILL_MAP_SCOPE=global` env var translation.
+  - `sm serve --scope project|global` flag.
+  - `sm config --source global` literal in `--source` outputs (the
+    source set is now `default | project | project-local | env | flag`).
+  - `IRuntimeContext.homedir` field.
+  - `IDbLocationOptions.global` field; `resolveDbPath` reduces to
+    `db ?? defaultProjectDbPath(ctx)`.
+  - `defaultUserPluginsDir` helper.
+  - `loadConfig` `scope: 'project' | 'global'` parameter and the
+    `user` / `user-local` file-pair iteration; the layer list is now
+    `defaults` → `project` → `project-local` → `override`.
+  - `USER_ONLY_KEYS` constant and the per-key locality enforcement
+    pinned to it. `updateCheck.enabled` is no longer part of the
+    config layer system; its toggle lives alongside the throttle
+    cache.
+  - `GET /api/health` response field `scope: 'project'|'global'`.
+  - `GET /api/plugins` item field `source: 'built-in'|'project'|'global'`
+    reduces to `'built-in'|'project'`.
+  - `scan_meta.scope` SQLite column and the matching `IScanResult.scope`
+    kernel field.
+
+  Removed surface (`@skill-map/spec`):
+
+  - `spec/cli-contract.md` § Global flags row for `-g/--global` and
+    the `SKILL_MAP_SCOPE` row in the env-var table.
+  - `spec/cli-contract.md` § serve flag table `--scope project|global`
+    row.
+  - `spec/architecture.md` § Config layering layers `user` and
+    `user-local`; `USER_ONLY_KEYS` set.
+  - `spec/db-schema.md` two-scope diagram; `scan_meta.scope` column;
+    `scope: 'global'` from `--source` enum text.
+  - `spec/schemas/scan-result.schema.json` `scope` property (was in
+    `required`).
+  - `spec/schemas/project-config.schema.json` `updateCheck`
+    description rewritten as the documented exception.
+  - `spec/schemas/plugins-registry.schema.json` status description's
+    `project / global / --plugin-dir` reference.
+
+  Added surface:
+
+  - `spec/cli-contract.md` § "Scope is always project-local"
+    normative paragraph at the top of the file, stating the
+    no-`$HOME`-reads principle and the update-check exception.
+  - `AGENTS.md` § Analyzers gains the matching operating rule for
+    agents working in the repo, "Skill-map MUST NEVER read `$HOME`
+    by default…".
+  - Regression test at `src/test/global-flag-removed.test.ts`
+    asserting Clipanion's "unknown option" error on `sm scan -g`.
+
+  Migration (no compat shim): pre-1.0, greenfield. Users who relied
+  on `~/.skill-map/skill-map.db`, `~/.skill-map/settings*.json`, or
+  `~/.skill-map/plugins/` move the files into their project
+  (`<cwd>/.skill-map/`) or pass `--plugin-dir <path>` per invocation.
+  Older DBs are not migrated, a fresh `sm init` regenerates without
+  the `scope` column.
+
+  ## User-facing
+
+  `-g/--global` is gone. `sm` reads only the current project
+  (`<cwd>/.skill-map/`). To scan outside the project, add paths via
+  `scan.extraFolders` in Settings. User-scope plugins move to
+  `<cwd>/.skill-map/plugins/` or load with `--plugin-dir <path>`.
+
 ## 0.26.0
 
 ### Minor Changes

package/architecture.md

@@ -70,7 +70,7 @@ Operations: `discover(scopes)`, `load(pluginPath)`, `validateManifest(json)`.
 The loader enforces two id-uniqueness analyzers during discovery (see [`plugin-author-guide.md` §Plugin id uniqueness](./plugin-author-guide.md#plugin-id-uniqueness) for the author-facing summary):
 
 1. **Directory name == manifest id.** A plugin lives at `<root>/<id>/plugin.json`. A mismatch surfaces as status `invalid-manifest`. This analyzer eliminates same-root collisions by construction.
-2. **Cross-root id collision blocks both sides.** Two plugins reachable from different roots (project + global, or any `--plugin-dir` combination) that declare the same `id` BOTH receive status `id-collision`. No precedence analyzer applies, coherent with §Boot invariant ("no extension is privileged"). The user resolves by renaming one of them.
+2. **Cross-root id collision blocks both sides.** Two plugins reachable from different roots (e.g. the project default `<cwd>/.skill-map/plugins/` and any `--plugin-dir` combination) that declare the same `id` BOTH receive status `id-collision`. No precedence analyzer applies, coherent with §Boot invariant ("no extension is privileged"). The user resolves by renaming one of them.
 
 In addition, the loader **qualifies every extension** with its owning plugin id before registering it. The registry stores extensions under the qualified id `<plugin-id>/<extension-id>` (e.g. `core/slash`, `core/broken-ref`, `hello-world/greet`). Authors continue to declare the short `id` in each extension manifest; the loader composes the qualified form from `manifest.id` at load time. Built-in extensions bundled with the reference impl declare their `pluginId` directly in `built-ins.ts`, `core/` for kernel-internal primitives (every analyzer, the formatter, the cross-vendor extractors `annotations` / `slash` / `at-directive` / `markdown-link` / `external-url-counter` / `stability`) and vendor-specific bundles such as `claude/` (the Claude provider) for Provider integrations whose territory is platform-bound. If a plugin author injects a `pluginId` field on an extension that disagrees with `plugin.json`'s `id`, the loader emits `invalid-manifest` with a directed reason.
 
@@ -173,12 +173,12 @@ Six kinds, all first-class, all loaded through the same registry. Each kind has
 
 | Kind | Role | Input | Output |
 |---|---|---|---|
-| **Provider** | Recognizes a platform. Declares the catalog of node `kind`s it emits via the `kinds` map; each map entry pairs the kind's frontmatter schema (path relative to the Provider's package directory) with its `defaultRefreshAction` (a qualified action id that drives the probabilistic-refresh surface). The Provider's walker hardcodes the paths it scans within the project (e.g. `.claude/`, `.gemini/`); it does NOT extend the scan into the user's HOME. Deterministic-only. | Filesystem walk results, candidate path. | `{ kind, provider } \| null`. |
-| **Extractor** | Extracts signals from a node body. Deterministic-only: runs synchronously inside `sm scan`. Output flows through three context callbacks (no return value): `ctx.emitLink(link)` for the kernel's `links` table, `ctx.enrichNode(partial)` for the kernel's enrichment layer (separate from the author's frontmatter), `ctx.store` for the plugin's own KV / dedicated tables. | Parsed node (frontmatter + body) + callbacks. | `void` (output via callbacks). |
-| **Analyzer** | Evaluates the graph. Dual-mode: `deterministic` runs in `sm check`, `probabilistic` runs in jobs. | Full graph (nodes + links). | `Issue[]`. |
-| **Action** | Operates on one or more nodes. Dual-mode: `deterministic` (in-process code) or `probabilistic` (rendered prompt the runner executes). | Node(s), optional args. | Deterministic: report JSON. Probabilistic: rendered prompt that a runner executes. |
-| **Formatter** | Serializes the graph. Deterministic-only. | Graph + optional filter. | String (ASCII / Mermaid / DOT / JSON / user-defined). |
-| **Hook** | Reacts declaratively to one of ten curated lifecycle events, eight pipeline-driven (`scan.started`, `scan.completed`, `extractor.completed`, `analyzer.completed`, `action.completed`, `job.spawning`, `job.completed`, `job.failed`) plus two CLI-process-driven (`boot` before verb routing, `shutdown` after the verb's exit code resolves). Dual-mode: `deterministic` runs in-process during the dispatch, `probabilistic` is enqueued as a job. Hooks REACT to events; they cannot block, mutate, or steer the pipeline. | A curated event payload (run-scoped, scan-scoped, job-scoped, or process-scoped) plus an optional declarative `filter` map. | `void` (reactions are side effects). |
+| **Provider** | Recognizes a platform. The kind catalog lives on disk under `<plugin>/kinds/<kindName>/{schema.json, kind.json}` (structure-as-truth); the loader projects it onto the runtime descriptor. The Provider's walker hardcodes the paths it scans within the project (e.g. `.claude/`, `.gemini/`); it does NOT extend the scan into the user's HOME. `Provider.roots` is enforcement-grade: a Provider with declared roots only sees matching files; a Provider without `roots` acts as the fallback. Deterministic-only. | Filesystem walk results, candidate path. | `{ kind, provider } \| null`. |
+| **Extractor** | Extracts signals from a node body. Deterministic-only: runs synchronously inside `sm scan`. Output flows through context callbacks (no return value): `ctx.emitLink(link)` for the kernel's `links` table (validated against the global closed enum of link kinds; per-extractor allowlist was retired with the structure-as-truth refactor), `ctx.enrichNode(partial)` for the kernel's enrichment layer (separate from the author's frontmatter), `ctx.emitContribution(id, payload)` for view contributions, `ctx.store` for the plugin's own KV / dedicated tables. | Parsed node (frontmatter + body) + callbacks. | `void` (output via callbacks). |
+| **Analyzer** | Evaluates the graph. Dual-mode: `deterministic` runs in `sm check`, `probabilistic` runs in jobs. The analyzer↔action relationship is declared from the Action side via `precondition.analyzerIds` (Modelo B). | Full graph (nodes + links). | `Issue[]`. |
+| **Action** | Operates on one or more nodes. Dual-mode: `deterministic` (in-process code) or `probabilistic` (rendered prompt the runner executes). Files-by-convention: every Action carries `<action-dir>/report.schema.json`; probabilistic Actions additionally carry `<action-dir>/prompt.md`. The retired `reportSchemaRef` / `promptTemplateRef` / `expectedTools` / `fanOutPolicy` manifest fields were replaced by these conventions and the simplified `precondition` block. | Node(s), optional args. | Deterministic: report JSON. Probabilistic: rendered prompt that a runner executes. |
+| **Formatter** | Serializes the graph. Deterministic-only. The `formatId` consumed by `sm graph --format <name>` comes from the formatter's folder name. | Graph + optional filter. | String (ASCII / Mermaid / DOT / JSON / user-defined). |
+| **Hook** | Reacts declaratively to one of ten curated lifecycle events, eight pipeline-driven (`scan.started`, `scan.completed`, `extractor.completed`, `analyzer.completed`, `action.completed`, `job.spawning`, `job.completed`, `job.failed`) plus two CLI-process-driven (`boot` before verb routing, `shutdown` after the verb's exit code resolves). **Deterministic-only** since the structure-as-truth refactor: LLM-dependent reactions are modeled as a deterministic Hook that enqueues a probabilistic Action via `ctx.queue('<plugin>/<action>', payload)`. Hooks REACT to events; they cannot block, mutate, or steer the pipeline. | A curated event payload (run-scoped, scan-scoped, job-scoped, or process-scoped) plus an optional declarative `filter` map. | `void` (reactions are side effects). |
 
 ### IO discipline, extensions never write to the filesystem
 
@@ -194,13 +194,14 @@ This invariant is what makes the consent gate at the kernel boundary sufficient:
 
 ### Provider · `kinds` catalog
 
-Every `Provider` MUST declare a non-empty map `kinds: { <kind>: { schema, defaultRefreshAction, ui } }` covering every `kind` it classifies into. Each entry carries three required fields:
+Every `Provider` declares its kind catalog via the filesystem (structure-as-truth): each kind lives under `<plugin>/kinds/<kindName>/` and ships exactly two files:
 
-- **`schema`**, path (relative to the Provider package) to the kind's frontmatter JSON Schema. The schema MUST extend [`frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) via `allOf` + `$ref` to base's `$id`. The kernel registers it with AJV at boot and validates every node's frontmatter against the entry matching its classified kind.
-- **`defaultRefreshAction`**, qualified action id (`<plugin-id>/<action-id>`) the UI's probabilistic-refresh surface (`🧠 prob`) dispatches for nodes of this kind. The action MUST exist in the registry; a dangling reference disables the Provider with status `invalid-manifest`. Plugins MAY override per-node via `metadata.refreshAction`; the Provider default is normative.
-- **`ui`**, presentation block: `{ label, color, colorDark?, emoji?, icon? }`. See §Provider · `ui` presentation below.
+- **`schema.json`**, the kind's frontmatter JSON Schema. MUST extend [`frontmatter/base.schema.json`](./schemas/frontmatter/base.schema.json) via `allOf` + `$ref` to base's `$id`. The kernel reads it once at boot, registers it with AJV, and validates every node's frontmatter against the entry matching its classified kind.
+- **`kind.json`**, the per-kind metadata, today just `{ ui: { label, color, colorDark?, emoji?, icon? } }`. See §Provider · `ui` presentation below. Validated against [`schemas/extensions/provider-kind.schema.json`](./schemas/extensions/provider-kind.schema.json) at load time.
 
-The catalog is the single source of truth for "which kinds does this Provider emit", the `IProvider` runtime contract derives the kind set from `Object.keys(kinds)`.
+The loader's discovery (`discoverProviderKinds`) projects every `kinds/<kindName>/` directory into the runtime descriptor `instance.kinds[<kindName>] = { schema, schemaJson, ui }`. The `IProvider` runtime contract derives the kind set from `Object.keys(kinds)`; authors do not write the map by hand any more.
+
+The retired manifest field `defaultRefreshAction` (the qualified action id the UI's `🧠 prob` button dispatched) was removed alongside the button. A replacement UX is TBD; until then, the kernel does not surface a Provider-declared "default refresh" path.
 
 ### Provider · `ui` presentation
 
@@ -362,7 +363,7 @@ Hooks introduce no new persisted state and do NOT participate in the determinist
 
 ### Locality
 
-- **Drop-in**: extensions live inside plugins, discovered at boot from `.skill-map/plugins/<id>/` and `~/.skill-map/plugins/<id>/`.
+- **Drop-in**: extensions live inside plugins, discovered at boot from `<cwd>/.skill-map/plugins/<id>/` only. The `--plugin-dir <path>` escape hatch on the `sm plugins …` verb family loads a custom directory per invocation when the user explicitly opts in.
 - **Built-in**: the reference impl bundles a default extension set (one Provider, four extractors, five analyzers, one formatter, one hook). The fifth analyzer, `core/validate-all`, replays every scanned node and link through the authoritative spec schemas via AJV, the kernel-side guard against persisting non-conforming graph rows. The first built-in Hook is `core/update-check`, which subscribes to `shutdown` and runs the once-per-day "update available" probe + banner that lived on the CLI entry path before the Hook kind had concrete consumers. These are loaded from `src/extensions/` and are indistinguishable from plugin-supplied extensions from the kernel's point of view.
 
 ---
@@ -440,23 +441,21 @@ This is what makes "CLI-first" a coherent analyzer: every CLI verb is a kernel f
 | # | Layer | Source | Audience |
 |---|---|---|---|
 | 1 | `defaults` | Bundled `defaults.json` (ships in the CLI binary). | Every install. |
-| 2 | `user` | `~/.skill-map/settings.json` | Per-machine, per-user; lives in `$HOME` (never in the repo). |
-| 3 | `user-local` | `~/.skill-map/settings.local.json` | Same audience as `user`; intended for values the user might want to keep out of dotfile sync. |
-| 4 | `project` | `<cwd>/.skill-map/settings.json` | **Committed to the repo**, values are shared with every collaborator and CI. |
-| 5 | `project-local` | `<cwd>/.skill-map/settings.local.json` | **Gitignored**, values are per-checkout, never travel via the repo. |
-| 6 | `override` | Caller-supplied (env vars, CLI flags). | Process-scoped, ephemeral. |
+| 2 | `project` | `<cwd>/.skill-map/settings.json` | **Committed to the repo**, values are shared with every collaborator and CI. |
+| 3 | `project-local` | `<cwd>/.skill-map/settings.local.json` | **Gitignored**, values are per-checkout, never travel via the repo. |
+| 4 | `override` | Caller-supplied (env vars, CLI flags). | Process-scoped, ephemeral. |
 
 The merge is per dot-path: a value declared at a higher layer replaces the value at lower layers; objects recurse, arrays replace. The loader records which layer last wrote each key in a `sources` map so `sm config show --source` can attribute every effective value.
 
-Layers 1, 2, 3, 5, 6 carry **per-user / per-machine state**. Only layer 4 (`project`) travels via the shared repo, so values landing in `project` are part of the contract every collaborator inherits.
+Only layer 2 (`project`) travels via the shared repo, so values landing in `project` are part of the contract every collaborator inherits. Layers 1, 3, 4 carry **per-machine / per-checkout state** that never leaves the project.
 
-### Per-key locality
+Skill-map deliberately has **no user-scope config layer**: there is no merge of `$HOME` state on top of the project. The CLI honours the principle "never read `$HOME` by default" (see `cli-contract.md` §Scope is always project-local). The narrow exception, `~/.skill-map/settings.json`, holds genuinely per-machine preferences (the update-check toggle + its throttle bookkeeping today; future locale / theme) but is **NOT** part of the config layer system: it is read directly by the module that owns the feature, never merged into the project layers above. See `cli-contract.md` §User-settings file for the contract.
 
-Two locality classes constrain which layers a given key MAY live in. Both are enforced in code (reference impl: `core/config/helper.ts`), not in the JSON Schema, the schema stays additive so older settings files keep validating even when a key is reclassified.
+### Per-key locality
 
-- **`USER_ONLY_KEYS`**, keys describing per-user preferences that have no project meaning. Read forces `scope: 'global'` (project layers ignored); write rejects `target: 'project'` with a directed error. Today: `updateCheck.enabled`.
+One locality class constrains which layers a given key MAY live in. It is enforced in code (reference impl: `core/config/helper.ts`), not in the JSON Schema, the schema stays additive so older settings files keep validating even when a key is reclassified.
 
-- **`PROJECT_LOCAL_ONLY_KEYS`**, keys describing per-user-per-project preferences. Valid in layers 1, 2, 3, 5, 6. **Stripped (with a warning) from layer 4 (`project`)** because the value is inherently per-user and must not be shared via the committed repo. Writes target `project-local` (`<cwd>/.skill-map/settings.local.json`); `sm config set` rejects `--scope project` for these keys.
+- **`PROJECT_LOCAL_ONLY_KEYS`**, keys describing per-user-per-project preferences. Valid in layers 1, 3, 4. **Stripped (with a warning) from layer 2 (`project`)** because the value is inherently per-user and must not be shared via the committed repo. Writes target `project-local` (`<cwd>/.skill-map/settings.local.json`); `sm config set` rejects writes to `project` for these keys with a directed error.
 
   Members:
   - `allowEditSmFiles`, per-project consent to create / modify `.sm` sidecars.
@@ -465,7 +464,7 @@ Two locality classes constrain which layers a given key MAY live in. Both are en
 
   All three describe disk access the local operator opted into; sharing them via the repo would silently expand every collaborator's scan surface to paths that only make sense on the original author's machine.
 
-Adding a new entry to either set is a behaviour change for older installs that wrote the key into a committed file, the value gets stripped (PROJECT_LOCAL_ONLY) or ignored (USER_ONLY) at read time. The changeset that adds the entry MUST document the migration.
+Adding a new entry is a behaviour change for older installs that wrote the key into a committed file, the value gets stripped at read time. The changeset that adds the entry MUST document the migration.
 
 ---
 
@@ -590,7 +589,7 @@ Two schemas describe the wire shape:
 
 ### Identity
 
-Each view contribution is identified by the qualified id `<pluginId>/<extensionId>/<contributionId>`. The plugin author declares contributions in the extension manifest under `viewContributions: Record<string, IViewContribution>`; the loader composes the qualified id from the plugin id, the extension id, and the Record key.
+Each view contribution is identified by the qualified id `<pluginId>/<extensionId>/<contributionId>`. The plugin author declares contributions in the extension manifest under `ui: Record<string, IViewContribution>` (renamed from `viewContributions` with the structure-as-truth refactor); the loader composes the qualified id from the plugin id, the extension id, and the Record key. The runtime catalog aggregated by `Kernel.getRegisteredViewContributions()` keeps the original `viewContributions` name, only the manifest-side field changed.
 
 ### Manifest
 
@@ -598,7 +597,7 @@ Each entry picks a `slot` name from the closed catalog and supplies presentation
 
 ```jsonc
 {
-  "viewContributions": {
+  "ui": {
     "breakdown": {
       "slot": "inspector.body.panel.breakdown",
       "label": "Keyword hits",
@@ -618,13 +617,13 @@ The plugin author picks ONE slot per contribution; that single decision determin
 
 ### Settings
 
-Plugin user-configurable settings live at the manifest root in `settings: Record<string, ISettingDeclaration>` (see [`schemas/plugins-registry.schema.json`](./schemas/plugins-registry.schema.json)). Each setting picks an input-type from the closed catalog at [`schemas/input-types.schema.json`](./schemas/input-types.schema.json) (`string-list`, `single-string`, `boolean-flag`, `integer`, `enum-pick`, `enum-multipick`, `path-glob`, `regex`, `secret`, `key-value-list`). The kernel exposes resolved settings to extractors via `ctx.settings.<settingId>`; the UI generates a form per declaration; the CLI's `sm plugins config <id>` exposes the same surface.
+Plugin user-configurable settings live **on each extension's manifest** (structure-as-truth) in `settings: Record<string, ISettingDeclaration>` (see [`schemas/extensions/base.schema.json`](./schemas/extensions/base.schema.json) and [`schemas/input-types.schema.json`](./schemas/input-types.schema.json)). Each setting picks an input-type from the closed catalog (`string-list`, `single-string`, `boolean-flag`, `integer`, `enum-pick`, `enum-multipick`, `path-glob`, `regex`, `secret`, `key-value-list`). The kernel exposes resolved settings via `ctx.settings.<settingId>` to the extension's runtime methods (`extract`, `evaluate`, `invoke`, etc.); the UI generates a form per declaration; the CLI's `sm plugins config <plugin>/<extension>` exposes the same surface. Plugin-level settings are no longer supported; the field was moved from `plugin.json` to each extension that consumes it.
 
-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 when the manifest detects mismatch; live re-emission is explicitly out of scope (rescan-required is a stability decision per `ROADMAP.md` §UI contribution system D4).
+Settings are read once at extension invocation; changing a setting requires `sm scan` to re-emit affected contributions. The UI surfaces a "settings changed, rescan needed" indicator when the manifest detects mismatch; live re-emission is explicitly out of scope (rescan-required is a stability decision per `ROADMAP.md` §UI contribution system D4).
 
 ### Runtime catalog
 
-The kernel exposes a runtime catalog (`Kernel.getRegisteredViewContributions()`) listing every plugin-contributed view contribution with its `pluginId`, `extensionId`, `contributionId`, `slot`, and the manifest-declared `label` / `tooltip` / `icon` / `emptyText` / `emitWhenEmpty`. The catalog is built once at boot from every loaded extension's `viewContributions` map, AJV-validated, and frozen, same lifecycle as `getRegisteredAnnotationKeys()`.
+The kernel exposes a runtime catalog (`Kernel.getRegisteredViewContributions()`) listing every plugin-contributed view contribution with its `pluginId`, `extensionId`, `contributionId`, `slot`, and the manifest-declared `label` / `tooltip` / `icon` / `emptyText` / `emitWhenEmpty`. The catalog is built once at boot from every loaded extension's `ui` map (renamed from `viewContributions` with the structure-as-truth refactor), AJV-validated, and frozen, same lifecycle as `getRegisteredAnnotationKeys()`.
 
 Analyzers see the catalog through `IAnalyzerContext.viewContributions` so cross-cutting checks (`core/unknown-slot`, `core/contribution-orphan`) can reason about emissions.
 
@@ -714,7 +713,7 @@ Same honest-note posture as [`plugin-kv-api.md`](./plugin-kv-api.md): isolated a
 
 Two built-ins ship with the system to cover catalog evolution and rename edge cases:
 
-- **`core/unknown-slot`**, walks every loaded plugin's `viewContributions[*].slot`; emits an `Issue` of severity `warn` for any slot not in the current kernel catalog. Parallel to `core/unknown-field` for annotations. Note: AJV at manifest load already rejects unknown slots as `invalid-manifest`; this analyzer covers the soft-warning path when a plugin remains loaded across a catalog version bump.
+- **`core/unknown-slot`**, walks every loaded plugin's `ui[*].slot`; emits an `Issue` of severity `warn` for any slot not in the current kernel catalog. Parallel to `core/unknown-field` for annotations. Note: AJV at manifest load already rejects unknown slots as `invalid-manifest`; this analyzer covers the soft-warning path when a plugin remains loaded across a catalog version bump.
 - **`core/contribution-orphan`**, joins `scan_contributions` against the live `scan_nodes` set; emits an `Issue` of severity `warn` for emissions whose `node_path` no longer exists (post-rename heuristic miss).
 
 ### Catalog versioning