@skill-map/spec 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,547 @@
 # Spec changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- e0fb57e: Step 14.2 — REST read-side endpoints + DataSource contract
+
+  Fills the `### Server` subsection's endpoint catalogue from the v14.1 stub
+  (`/api/health` real, `/api/*` 404) to the eight read-side endpoints the
+  Angular SPA at 14.3 will consume. New `spec/schemas/api/rest-envelope.schema.json`
+  formalises the list-envelope shape. Test totals 764 → 832 (+68).
+
+  **Files added (server)**
+
+  - `src/server/path-codec.ts` — `encodeNodePath` / `decodeNodePath`. Base64url (RFC 4648 §5, no padding). Mirrored at `ui/src/services/data-source/path-codec.ts` in 14.3.
+  - `src/server/envelope.ts` — list / single / value envelope builders. `REST_ENVELOPE_SCHEMA_VERSION = '1'`. Hardcoded to track `spec/schemas/api/rest-envelope.schema.json#/properties/schemaVersion/const`.
+  - `src/server/query-adapter.ts` — `urlParamsToExportQuery(params)` lifts URL search params into the kernel's `IExportQuery` via `parseExportQuery` (one grammar, two transports). `filterNodesWithoutIssues` post-filter handles `hasIssues=false` (the one filter the kernel grammar can't express).
+  - `src/server/routes/deps.ts` — shared `IRouteDeps` bag (`options`, `runtimeContext`).
+  - `src/server/routes/health.ts` — extracted from `app.ts` for symmetry with the other routes (no behavior change).
+  - `src/server/routes/scan.ts` — `/api/scan` + `/api/scan?fresh=1`. DB absent → returns the empty `ScanResult` shape (matches the `loadScanResult` synthetic fallback). `?fresh=1` rejects when the server was started with `--no-built-ins` or `--no-plugins`.
+  - `src/server/routes/nodes.ts` — `/api/nodes/:pathB64` (single) registered BEFORE `/api/nodes` (list) so the param doesn't shadow the literal prefix. Pagination defaults `offset=0`, `limit=100`; max `limit=1000`.
+  - `src/server/routes/links.ts` — `/api/links?kind=&from=&to=`.
+  - `src/server/routes/issues.ts` — `/api/issues?severity=&ruleId=&node=`. `ruleId` filter mirrors `sm check`'s qualified-or-suffix match.
+  - `src/server/routes/graph.ts` — `/api/graph?format=ascii|json|md`. Per-format content-type. Unknown format → `bad-query` 400.
+  - `src/server/routes/config.ts` — `/api/config`. Wraps `loadConfig` from the kernel. Layered-loader warnings forwarded to `process.stderr`.
+  - `src/server/routes/plugins.ts` — `/api/plugins`. Built-ins (gated by `noBuiltIns`) + drop-ins (gated by `noPlugins`). `source: 'built-in' | 'project' | 'global'` derived from the plugin's filesystem path against `defaultProjectPluginsDir`.
+
+  **Files edited (server)**
+
+  - `src/server/app.ts` — `IAppDeps` gains `runtimeContext` (mandatory). Routes registered via the new `routes/*` registrars BEFORE the `/api/*` 404 catch-all. `app.onError` extended to map `ExportQueryError` → 400 `bad-query` (alongside the existing HTTPException + uncaught-Error branches).
+  - `src/server/index.ts` — `createServer(options, extra?)` accepts an optional `extra.runtimeContext` so tests can drive against a tempdir scope; production callers (the `sm serve` verb) leave it undefined and the composition root falls back to `defaultRuntimeContext()`.
+  - `src/server/i18n/server.texts.ts` — adds error message templates: `dbMissingHint`, `freshScanRequiresPipeline`, `graphUnknownFormat`, `paginationLimitTooLarge`, `paginationInvalidInteger`, `nodeNotFound`, `pathB64Malformed`.
+
+  **Tests added (68)**
+
+  - `src/test/server-endpoints.test.ts` (24) — happy + error path per endpoint. Uses real `runScan` + `persistScanResult` against a `mkdtempSync` fixture (no `:memory:` per `feedback_sqlite_in_memory_workaround.md`).
+  - `src/test/server-pagination.test.ts` (10) — default page caps at 100, `?limit=1000` accepted, `?limit=1001` rejected, offset/limit boundaries, `?offset=-1` and `?offset=foo` rejected, offset past total returns empty + preserves total.
+  - `src/test/server-errors.test.ts` (8) — every `code` value maps to the documented HTTP status; canonical envelope shape on every error response.
+  - `src/test/server-query-adapter.test.ts` (16) — URL-param → IExportQuery matrix; `filterNodesWithoutIssues` post-filter behaviour.
+  - `src/test/server-path-codec.test.ts` (10) — round-trip on POSIX / unicode / spaces / very long paths; rejection of empty, non-alphabet, single-char inputs; uniqueness for distinct inputs.
+
+  **Spec**
+
+  - `spec/schemas/api/rest-envelope.schema.json` — new schema. `$id: https://skill-map.dev/spec/v0/api/rest-envelope.schema.json`. `oneOf` enforces that an envelope carries exactly one of `items` / `item` / `value` per kind (with sentinel kinds `health` / `scan` / `graph` reserved for routes that don't use the envelope).
+  - `spec/cli-contract.md` `### Server` — endpoint table expanded from 4 rows (v14.1 surface) to 12 rows (v14.2 surface) with full filters / status / shape per row. Error code source enumeration added (`not-found` / `bad-query` / `internal` / reserved `db-missing`). Stability stays `experimental — locks at v0.6.0`.
+  - `spec/CHANGELOG.md` `[Unreleased]` `### Minor` — entry for BFF endpoints + envelope schema.
+  - `spec/conformance/coverage.md` — row 25 added for `api/rest-envelope.schema.json` (status: 🔴 missing — implementation-side coverage exists in `src/test/server-endpoints.test.ts`; a kernel-agnostic conformance case is still required before v1.0.0 ships).
+  - `spec/index.json` — regenerated (40 → 41 files hashed).
+
+  **Decisions during implementation (flag for orchestrator)**
+
+  - The `db-missing` error code is kept in the documented enum but no v14.2 route currently emits it — `/api/scan` returns the empty `ScanResult` when the DB is absent, list routes return zero items, and `/api/health` already advertises `db: 'missing'`. Documented in the spec as "reserved for future endpoints (post-v0.6.0 mutations) where degradation is not safe". Removing the code would be a breaking change to the envelope contract; keeping it costs nothing.
+  - `ExportQueryError` from `parseExportQuery` is funneled to `bad-query` 400 via a new branch in `app.onError`. The brief listed it as a route-level concern; centralising in the global handler means future routes that go through the kernel grammar (e.g. a future `/api/export?q=...`) inherit the same envelope mapping for free.
+  - `urlParamsToExportQuery` builds a canonical raw query string and re-parses it through `parseExportQuery` instead of constructing `IExportQuery` directly. The extra parse is microseconds and guarantees the BFF and `sm export` can never drift on what counts as a valid filter token. When the grammar grows (e.g. `has=findings` post-Step 11), only `parseExportQuery` changes.
+  - `/api/scan?fresh=1` rejection on `--no-built-ins` / `--no-plugins` matches Decision §14.1's intent: the BFF surface should not silently produce empty results that look indistinguishable from "your project has no nodes". The `bad-query` envelope tells the operator they're holding a knife by the blade.
+  - Tests use `noPlugins: true` by default to keep them deterministic against `process.cwd()` — `loadPluginRuntime` walks the live cwd's plugins dir, which would surface ambient plugins from the test runner's host (none in CI today, but a developer running tests locally with their own plugins installed would see flake).
+  - The route registration order in `app.ts` is documented in the file's header comment. `/api/nodes/:pathB64` MUST register before `/api/nodes` (Hono matches in declaration order; the literal prefix wins otherwise).
+
+- d5488bf: Step 14.4.a — BFF WS broadcaster + chokidar wiring + scan event emission
+
+  First half of Step 14.4 lands. The BFF's `/ws` endpoint flips from
+  "upgrade-only stub" to a real broadcaster fed by a chokidar
+  filesystem watcher: every debounced batch runs the same
+  `runScanWithRenames` + persistence pipeline `sm watch` uses, and the
+  kernel's `ProgressEmitterPort` is bridged directly to the broadcaster
+  so `scan.*` / `extractor.completed` / `rule.completed` / `extension.error`
+  events reach every connected client verbatim — no envelope
+  construction in the BFF for the routine cases. Tests 832 → 854 (+22).
+
+  The UI-side consumer (`WsEventStreamService`) ships separately as
+  14.4.b.
+
+  **Files added (server)**
+
+  - `src/server/broadcaster.ts` — `WsBroadcaster` class. Owns the
+    connected-clients Set, fans `JSON.stringify(envelope)` once across
+    every open socket, evicts on backpressure (`bufferedAmount > 4 MiB`
+    → close 1009 + unregister), drains every client with code 1001 +
+    reason `'server shutdown'` on `shutdown()`. `IBroadcasterClient`
+    interface is structural so unit tests inject fakes without a real
+    `WebSocket`.
+  - `src/server/watcher.ts` — `createWatcherService(deps)` factory.
+    Wraps `createChokidarWatcher` with `scan.watch.debounceMs` from
+    config (override via `--watcher-debounce-ms`), runs the kernel scan
+    pipeline per debounced batch, persists via `withSqlite(...).scans.persist(...)`.
+    The per-batch `ProgressEmitterPort` bridges every event the kernel
+    orchestrator emits during the scan to `broadcaster.broadcast(envelope)`.
+    Per-batch failures log + continue (transient FS errors must not
+    kill the broadcaster); chokidar instance errors broadcast a
+    `watcher.error` advisory.
+  - `src/server/events.ts` — envelope helpers (`IWsEventEnvelope` shape,
+    `buildWatcherStartedEvent`, `buildWatcherErrorEvent`). The
+    `watcher.*` events are BFF-internal advisories — non-normative,
+    prefixed with `watcher.` to flag their non-spec status. Spec-mandated
+    shapes (`scan.*`, `extractor.completed`, `rule.completed`) are
+    forwarded verbatim from the kernel emitter, so this file does not
+    build them.
+
+  **Files added (tests)**
+
+  - `src/test/server-ws-broadcaster.test.ts` (15 tests) — broadcaster
+    unit tests against fake `IBroadcasterClient` instances. Coverage:
+    register/unregister/clientCount accounting, broadcast fan-out + JSON
+    stringify, readyState filter (skip closing/closed), per-client
+    `send()` failure isolation, backpressure eviction at the documented
+    threshold (`WS_BACKPRESSURE_BYTES = 4 MiB`), shutdown idempotency
+    - close-code/reason assertions, post-shutdown register immediate
+      close, post-shutdown broadcast no-op, circular-envelope serialization
+      failure handling.
+  - `src/test/server-ws-integration.test.ts` (7 tests) — end-to-end
+    against a real server. Boots `createServer({...})` with
+    `noWatcher: false`, watches a `mkdtempSync` cwd via the
+    `runtimeContext` override (production callers' cwd would point at the
+    test runner's repo root). Exercises: initial-batch `scan.completed`
+    observed by a connected client; multi-client fan-out (one batch fires
+    to two open clients); `clientCount` decrement on disconnect;
+    `handle.close()` shuts the watcher cleanly under 2s;
+    `validateServerOptions` rejects `--no-built-ins + watcher on`;
+    `--no-watcher` confirms no `scan.*` events fire.
+
+  **Files edited (server)**
+
+  - `src/server/ws.ts` — `noopWebSocketRoute(app)` deleted, replaced
+    with `attachBroadcasterRoute(app, broadcaster)`. Pulls the underlying
+    `ws` library `WebSocket` off `WSContext.raw` and registers it on
+    `onOpen`; unregisters on `onClose` / `onError`. Server-push only —
+    `onMessage` intentionally not registered at v14.4.a.
+  - `src/server/index.ts` — `createServer` composition root grows the
+    broadcaster + watcher lifecycle: instantiate `WsBroadcaster` →
+    build app (broadcaster threaded into `IAppDeps`) → bind listener →
+    start watcher (unless `--no-watcher`); `handle.close()` shuts in
+    order: `watcherService.stop()` → `broadcaster.shutdown()` → http
+    close → `wss.close()`. `ServerHandle` exposes the `broadcaster`
+    field for tests asserting `clientCount`.
+  - `src/server/app.ts` — `IAppDeps.attachWs: TWsRegistrar` removed;
+    replaced with `IAppDeps.broadcaster: WsBroadcaster`. The BFF wires
+    `attachBroadcasterRoute` directly inside `createApp` now (route
+    registrar pattern was the v14.1 scaffolding to allow swap-in at
+    v14.4 — that work is done, no need for the indirection).
+  - `src/server/options.ts` — adds `noWatcher: boolean` (default `false`
+    per Decision #121: a server with stale DB is a footgun) and
+    `watcherDebounceMs?: number` (override the config value).
+    Validator gains `watcher-requires-pipeline` (rejects
+    `--no-built-ins + watcher on` — would persist empty scans on every
+    batch) and `watcher-debounce-invalid` (non-integer / negative).
+  - `src/server/i18n/server.texts.ts` — eight new keys for watcher /
+    broadcaster lifecycle log lines.
+
+  **Files edited (CLI)**
+
+  - `src/cli/commands/serve.ts` — plumbs `--no-watcher` (documented) +
+    hidden `--watcher-debounce-ms` flag through to `IServerOptionsInput`.
+  - `src/cli/i18n/serve.texts.ts` — two new keys
+    (`watcherRequiresPipeline`, `watcherDebounceInvalid`).
+
+  **Files edited (tests)**
+
+  - `src/test/server-boot.test.ts` — the no-broadcaster-yet
+    close-1000-on-`onOpen` assertion is replaced with a "connection
+    stays open + registers" assertion. Default options grow
+    `noWatcher: true` (the watcher is exercised in the dedicated
+    integration file).
+  - `src/test/server-{db-missing,endpoints,errors,pagination}.test.ts`
+    — default options grow `noWatcher: true` so chokidar doesn't
+    subscribe to the test runner's cwd. No behavior change for these
+    tests; they exercise the REST surface, not the watcher.
+
+  **Spec**
+
+  - `spec/cli-contract.md` `### Server` — new **WebSocket protocol**
+    subsection. Documents the wire envelope (delegated to
+    `job-events.md` §Common envelope), the v14.4.a event catalog
+    (`scan.started` / `scan.progress` / `scan.completed` plus the
+    side-effect events `extractor.completed` / `rule.completed` /
+    `extension.error`, plus the BFF-internal advisories
+    `watcher.started` / `watcher.error`), the connection lifecycle
+    (no state push on connect; client polls `/api/scan` to seed; close
+    codes 1000 / 1001 / 1009), the backpressure rule, and the
+    loopback-only assumption (no per-connection auth through v0.6.0
+    per Decision #119). The endpoint table flips `GET /ws` from
+    `upgrade-only` to `implemented (v14.4.a)`. The `sm serve` flag
+    table grows `--no-watcher`. The verb-catalog row for `sm serve`
+    mirrors the new flag.
+  - `spec/CHANGELOG.md` `[Unreleased]` `### Minor` entry.
+  - `spec/index.json` — regenerated (41 files hashed; no schema added).
+
+  **ROADMAP.md** — bumped `Last updated`, marked Step 14.4.a landed
+  (14.4 carries an explicit (a/b) split now), 14.4.b still owes the
+  UI-side consumer. Earlier 14.3 prose pushed to "Earlier prose".
+
+  **Decisions taken inline (flag for orchestrator)**
+
+  - `issue.added` / `issue.resolved` (per `spec/job-events.md` §Issue
+    events line 446) **deferred to a follow-up**. The diff requires
+    comparing the new `ScanResult.issues` set against the prior
+    persisted snapshot; the watcher already loads the prior for the
+    rename heuristic, so the data is at hand, but the diff plumbing
+    (key derivation, set comparison, two emit calls per delta) is
+    enough material that it deserves its own brief. The 14.4.a surface
+    fans out exactly what the kernel emitter already produces.
+  - `scan.failed` **deferred to a follow-up**. The shape is not yet
+    locked in `spec/job-events.md` and would need a normative
+    addition. For 14.4.a, per-batch failures log via the kernel logger
+    and the watcher loop continues — same behavior as `sm watch`'s
+    `WATCH_TEXTS.batchFailed`.
+  - `scan.progress` **emitted, not throttled**. The kernel
+    orchestrator emits one event per node walked; on a small workspace
+    this is a handful of events per batch, on a large workspace it's
+    hundreds. The brief flagged throttling as optional at 14.4.a; the
+    bridge forwards verbatim today. The integration test observed 13
+    `scan.progress` events for a 4-file fixture, which is fine. A
+    throttle (250ms aggregation) is the obvious 14.6 polish if the
+    bundle / perf pass shows the fan-out swamping the channel.
+  - `watcher.started` / `watcher.error` BFF-internal advisories
+    **emitted** rather than silent. They give the SPA event-log a
+    clear "armed" signal and a surface for chokidar errors that don't
+    fit the spec's `scan.*` shape. Prefix marks them as non-normative;
+    consumers that follow the spec's "ignore unknown event types"
+    rule will not break.
+  - `IHealthResponse.watcher: 'on' | 'off'` **NOT added**. Keeping
+    the v14.2 health response shape stable was preferable to adding
+    one field for what tests / `--no-watcher` already cover. The
+    broadcaster's `clientCount` is exposed on `ServerHandle.broadcaster`
+    for test introspection without polluting the public health surface.
+  - The validator rejects `--no-built-ins + watcher on` because the
+    watcher would persist empty scans on every batch, silently wiping
+    the DB. `--no-plugins + watcher on` is OK (the built-in pipeline
+    is still complete on its own).
+  - `attachBroadcasterRoute` does NOT register `onMessage`. v14.4.a
+    is server-push only. A future client-initiated heartbeat / filter
+    request lands at 14.4.b or later.
+  - `WsBroadcaster` is a class (not a factory) per AGENTS.md
+    §Adapter wiring rule 5: factories scope to "adapters consumed via
+    ports", and the broadcaster is a plain BFF helper with no kernel
+    port to satisfy. The class is grandfathered no-`I*`-prefix per
+    §Type naming convention category 4.
+
+  **Smoke (live BFF, one-shot per AGENTS.md)**
+
+  The integration tests cover the live boot + WS upgrade + chokidar
+  batch + broadcast end-to-end against a `mkdtempSync` scope. The
+  diagnostic line `ws events received: scan.started, scan.progress
+× 13, extractor.completed × 4, rule.completed × 5, scan.completed`
+  confirms the full event sequence reaches a connected client during
+  a real scan against a 4-file fixture.
+
+- 4ff3f38: Step 14.5.d — Provider-driven kind presentation + envelope kindRegistry
+
+  Pre-1.0 minor breaking per `versioning.md` § Pre-1.0.
+
+  The Provider extension surface gains the required `kinds[*].ui` field
+  so each kind a Provider declares carries the presentation metadata the
+  UI needs to render it (label, base color, optional dark-theme color,
+  optional emoji, optional icon). The icon is a discriminated union —
+  `{ kind: 'pi'; id: 'pi-…' }` for PrimeIcons or `{ kind: 'svg'; path:
+'…' }` for raw SVG path data. The UI derives `bg` / `fg` tints from
+  `color` per theme via a deterministic helper, so the Provider declares
+  one base color per theme rather than four hex values.
+
+  The REST envelope shape (`spec/schemas/api/rest-envelope.schema.json`)
+  gains a new required `kindRegistry` field on every payload-bearing
+  variant (`nodes` / `links` / `issues` / `plugins` / `node` / `config`);
+  sentinel envelopes (`health` / `scan` / `graph`) stay exempt. The
+  registry is keyed by kind name and carries `{ providerId, label,
+color, colorDark?, emoji?, icon? }` — the BFF assembles it once at
+  boot from every enabled Provider and attaches it to every applicable
+  response so the UI can render Provider-declared kinds (built-in and
+  user-plugin alike) without hardcoding a closed kind enum. The change
+  keeps `schemaVersion` at `'1'` (greenfield — no released consumers
+  depend on the prior shape).
+
+  **Files edited (spec)**
+
+  - `spec/schemas/extensions/provider.schema.json` — adds `ui` to the
+    required field set on each `kinds[*]` entry, with discriminated
+    `oneOf` for `icon`.
+  - `spec/schemas/api/rest-envelope.schema.json` — new `kindRegistry`
+    definition; required on every payload-bearing variant; sentinel
+    variants explicitly forbid the field via `not.anyOf`. Version stays
+    at `'1'` (greenfield).
+  - `spec/CHANGELOG.md` — `[Unreleased]` `### Minor` entry.
+
+  **Files edited (kernel + built-in)**
+
+  - `src/kernel/extensions/provider.ts` — adds `IProviderKindUi` and
+    `IProviderKindIcon`; `ui` becomes required on `IProviderKind`.
+  - `src/built-in-plugins/providers/claude/index.ts` — every kind
+    (skill / agent / command / hook / note) declares its `ui` block
+    reusing the colors / labels / icons previously hardcoded in
+    `ui/src/styles.css`, `ui/src/i18n/kinds.texts.ts`, and
+    `ui/src/app/components/kind-icon/kind-icon.html`.
+  - `src/built-in-plugins/providers/claude/claude.test.ts` — new test
+    asserts every kind declares a well-formed `ui` block.
+  - `src/test/external-provider-kind.test.ts` — three mock providers
+    updated to declare `ui` on their `cursorRule` kinds.
+  - `src/test/plugins-cli.test.ts` — `dropMockProvider` helper template
+    declares `ui` on the inline mock `note` kind.
+
+  **Files added (conformance)**
+
+  - `spec/conformance/fixtures/plugin-missing-ui/` — drop-in Provider
+    fixture whose `kinds[*]` omits `ui` (plus a trivial `notes/example.md`
+    for the built-in Claude scan to grab).
+  - `spec/conformance/cases/plugin-missing-ui-rejected.json` — locks the
+    loader contract: `sm scan --json` exits 0, stderr matches
+    `plugin bad-provider:.*invalid.*must have required property 'ui'`,
+    the envelope still contains the built-in Claude provider, and the
+    one fixture node still gets scanned (one bad plugin does not take
+    down the scan).
+
+  **Decisions taken inline (flag for orchestrator)**
+
+  - `ui` is required, not optional — making it optional reintroduces the
+    pre-14.5.d trap of silently collapsing unknown kinds to `'note'`.
+    The cost (one object per kind in the manifest) is small.
+  - Icon is a discriminated union (`oneOf` with `kind` discriminator)
+    rather than two optional fields. Keeps the UI dispatch exhaustive
+    and AJV validates each variant cleanly.
+  - `schemaVersion` stays at `'1'` despite the required-field add.
+    Greenfield — no released consumers; a versioned migration buys
+    nothing today. Bumps the day a third-party consumer ships against
+    the wire.
+  - Severity (PrimeNG `<p-tag>` `severity` enum) is NOT declared by the
+    Provider. The UI tints kind tags with the registry's `color`
+    directly, avoiding a Provider-side dependency on a UI-framework
+    enum.
+  - BFF + UI sub-steps land in follow-up commits (14.5.d.iii / .iv /
+    .v) — the spec + kernel + built-in surface ship first so the
+    contract is visible before consumers wire up.
+
+- de20bc2: Step 14.5 (a + b) — Inspector polish: markdown body opt-in + linked-nodes panel + dead-link verify hybrid
+
+  Two sub-steps land together as a single feature unit. The Inspector
+  view (UI workspace) gains a real markdown body card, a dedicated
+  linked-nodes panel fed by the BFF's `/api/links` endpoint, and a
+  hybrid dead-link checker that combines the in-memory heuristic with
+  on-demand BFF verification. The spec + server side ships the minimal
+  contract the new UI surface depends on: an opt-in `?include=body`
+  parameter on `GET /api/nodes/:pathB64`, plus a corrected single-node
+  response shape. Tests 854 → 868 (+14 server) and UI 113 → 138 (+25
+  inspector / linked-nodes specs).
+
+  **Why on-demand body reads instead of persisting bodies in the DB**:
+  the kernel persists `body_hash` only (per `db-schema.md` §scan_nodes)
+  — the body itself is human content, not machine state, and
+  duplicating it in SQLite would inflate the DB without serving any
+  read-side query the kernel cares about. Inspector cards that DO want
+  to render the body (markdown preview at Step 14.5) opt into the
+  filesystem re-read; the list / graph / kind-palette views never need
+  it.
+
+  **Files added (server)**
+
+  - `src/server/node-body.ts` — on-demand body reader. Exports
+    `readNodeBody(cwd, relPath)` (returns `string | null`; `null` on
+    ENOENT / EACCES / EISDIR / ENOTDIR) and `stripFrontmatter(body)`
+    (drops the leading `---\n…\n---\n` block when present, leaves
+    fences in mid-document untouched). Path-traversal hardened: refuses
+    absolute paths and any relative path that resolves outside `cwd`.
+  - `src/test/server-node-body.test.ts` (11 unit cases) — covers
+    `stripFrontmatter` edge cases (empty, no frontmatter, missing
+    closing fence, fence in mid-document) and `readNodeBody` traversal
+    rejection + the four `null`-returning errno branches.
+
+  **Files edited (server)**
+
+  - `src/server/routes/nodes.ts` — `GET /api/nodes/:pathB64` extends
+    with `?include=body` opt-in (CSV-tolerant via the new
+    `parseIncludes` helper, so `?include=body,future-extension` reads
+    cleanly the day a second include lands). Same handler also FIXES a
+    long-standing shape bug: was emitting `{ item: { node, linksOut,
+linksIn, issues } }` (raw `INodeBundle` pass-through), now emits
+    the documented `{ item: Node, links: { incoming, outgoing },
+issues }` that the UI's `INodeDetailApi` and `StaticDataSource`
+    already expected. No prod consumer ran against the legacy shape
+    (the UI was internally branching on the legacy shape before the
+    REST adapter landed at 14.3.a), so the corrected shape ships as a
+    minor.
+  - `src/test/server-endpoints.test.ts` — assertions corrected to the
+    documented shape; 2 new cases for `?include=body` (returns body
+    on present file, returns `null` when the file is missing).
+
+  **Files added (UI)**
+
+  - `ui/src/app/components/linked-nodes-panel/{ts,html,css,spec.ts}`
+    — standalone Angular component. Inputs: `path`. Outputs:
+    `openPath`. Internally fires `dataSource.listLinks({from})` +
+    `listLinks({to})` in parallel; state machine
+    `idle/loading/ready/error`. Subscribes to `events()` filtered on
+    `scan.completed` for reactive refresh, plus a manual refresh
+    button in the card header. Token guard handles rapid path
+    changes. Renders rows with kind tag + clickable path +
+    confidence chip + sources. 10 spec cases.
+  - `ui/src/i18n/linked-nodes-panel.texts.ts` — i18n catalog.
+  - `ui/src/app/views/inspector-view/inspector-view.spec.ts` (15
+    cases) — first inspector-view spec. Covers empty / loading /
+    body-card states, stale-fetch token guard, kind-card smoke,
+    dead-link verify icon flow (heuristic-dead renders icon,
+    click → 404 confirms, click → 200 flips to live).
+
+  **Files edited (UI)**
+
+  - `ui/src/models/api.ts` — `INodeApi.body?: string | null` added.
+  - `ui/src/services/data-source/data-source.port.ts` —
+    `IDataSourcePort.getNode(path, opts?: {includeBody?: boolean})`.
+  - `ui/src/services/data-source/rest-data-source.ts` — propagates
+    `includeBody` to `?include=body`.
+  - `ui/src/services/data-source/static-data-source.ts` — ignores
+    the flag (demo bundle ships bodies inline; see
+    `scripts/build-demo-dataset.js` below).
+  - `ui/src/services/collection-loader.ts` — minor signature touch
+    for the `getNode` opts pass-through.
+  - `ui/src/models/node.ts` — `INodeView` loses three fields:
+    `body`, `raw`, `mockSummary`. The "Summary" mock card is
+    retired (description already lives in `inspector__desc`).
+  - `ui/src/app/views/inspector-view/inspector-view.ts` — body card
+    switches from `<pre>{{ n.body }}</pre>` to a `@switch` over a
+    `bodyState` signal (idle / loading / empty / unavailable /
+    error / ready) with token-guarded fetch via `effect()` keyed on
+    `path()`; markdown rendered via `MarkdownRenderer` and
+    `[innerHTML]`. Mounts `<sm-linked-nodes-panel>` as a separate
+    card between Relations and Body. Dead-link verify hybrid: the
+    Relations card chips (`supersededBy` / `supersedes` / `requires`
+    / `related`) keep the in-memory heuristic but now carry a verify
+    icon (`pi-question-circle`) that fires `getNode(path)` against
+    the BFF; three visual states `live` / `dead-confirmed` (404 → red
+    dashed border + `pi-times-circle`) / `dead-heuristic` (not in
+    scope, not yet verified). Per-node signals
+    `verifiedAlive` / `verifiedDead` / `verifyInFlight` reset on
+    `path()` change. Template refactor consolidates 4 inline
+    duplicated chip blocks into a single `<ng-template #pathChip>`
+    shared via `*ngTemplateOutlet`.
+  - `ui/src/app/views/inspector-view/inspector-view.{html,css}` —
+    templates + styles for the new body / verify states.
+  - `ui/src/i18n/inspector-view.texts.ts` — drops `summary*`, adds
+    `body.*` (loading / empty / unavailable / renderError),
+    `relations.verifyHint`, `relations.deadConfirmed`. `body: 'Body'`
+    (was `'Body (raw markdown)'`).
+
+  **Files edited (build pipeline)**
+
+  - `scripts/build-demo-dataset.js` — new `embedBodies(scan,
+fixtureDir)` post-processor reads each fixture's body from disk,
+    strips frontmatter, attaches to the demo `data.json` so the
+    demo experience matches the live BFF (~40 KB extra for 21
+    fixtures; bodies-on-bundle is the explicit demo-mode tradeoff).
+
+  **Spec**
+
+  - `spec/cli-contract.md` `### Server` — `/api/nodes/:pathB64` row
+    flips its shape column from the legacy bundle to the documented
+    `{ item, links: { incoming, outgoing }, issues }` and gains the
+    `?include=body` filter column.
+  - `spec/CHANGELOG.md` `[Unreleased]` `### Minor` — entry covering
+    the `?include=body` opt-in, the corrected response shape, and
+    the path-traversal defense.
+  - `spec/index.json` — regenerated (41 files hashed; no schema
+    added).
+
+  **ROADMAP** — `Last updated` bumped, "YOU ARE HERE" updated,
+  completeness marker now lists 14.5.a + 14.5.b as complete; "Next"
+  points at 14.5.c.
+
+  **Decisions taken inline (flag for orchestrator)**
+
+  - The corrected single-node shape ships as a minor (additive on
+    the contract surface) rather than a major. Rationale: no public
+    consumer ran against the legacy shape; the UI was decoding the
+    legacy shape internally before the REST adapter at 14.3.a
+    introduced the documented shape; and the spec table already
+    documented the new shape (the bug was in the implementation,
+    not the spec). Keeping the bump minor avoids burning a major
+    on a never-shipped wire format.
+  - `parseIncludes` is CSV-tolerant from day one (`?include=body`
+    and `?include=body,foo` both parse) so the second include can
+    land without a parser refactor. Unknown include values are
+    silently ignored — the BFF surface mirrors the spec's
+    "ignore unknown event types" rule for forward compatibility.
+  - Bodies are fetched per-node on inspector open, not pre-fetched
+    in the list endpoint. Keeps the list `/api/nodes` response
+    small (the list view never renders bodies) and matches the
+    read-side hot path: most nodes are listed but few are inspected.
+  - The dead-link verify is opt-in per chip click, not auto-fired
+    on inspector open. Heuristic-dead nodes are common in scoped
+    scans (a workspace that scans `docs/` but references `src/`);
+    auto-firing would burn one BFF round-trip per such reference.
+  - Per-node verification signals reset on `path()` change to avoid
+    stale state bleeding between inspector navigations. The signals
+    are scoped to the component instance; no global cache (the
+    cost is one BFF call per re-verify on revisit, which the user
+    triggers intentionally by clicking the icon).
+
+## 0.12.0
+
+### Minor Changes
+
+- 68c5e28: Step 14.1 — `sm serve` + Hono BFF skeleton
+
+  Adds `src/server/` Hono workspace with single-port wiring (`/api/health` real,
+  `/api/*` 404 stubs, `/ws` no-op upgrade, `serveStatic` + SPA fallback). Real
+  `ServeCommand` extracted from stub at `cli/commands/stubs.ts` to dedicated
+  `cli/commands/serve.ts` extending `SmCommand`. Loopback-only through v0.6.0
+  (Decision #119). Boot resilient to missing DB — `/api/health` reports
+  `db: 'missing'`. Spec `cli-contract.md` `sm serve` row updated to full flag
+  set; new `### Server` subsection (skeleton — endpoints fill at 14.2).
+
+  **Files added (server)**
+
+  - `src/server/index.ts` — `createServer(opts)` factory returning `ServerHandle` (`{ address, close }`); resolves spec version, builds the Hono app, instantiates a `WebSocketServer({ noServer: true })`, hands both to `@hono/node-server`'s `serve({ websocket: { server: wss } })`. Closing the http server tears down the WSS automatically (node-server registers the `'close'` hook internally); `close()` calls `wss.close()` defensively for forward-compatibility.
+  - `src/server/app.ts` — Hono app construction. Routes registered in single-port order: `GET /api/health` → real, `ALL /api/*` → structured 404, `GET /ws` via the injected `attachWs` registrar, static handler + SPA fallback. Global `app.onError` formats every uncaught throw into the error envelope.
+  - `src/server/options.ts` — `IServerOptions` + `validateServerOptions(input)`. Loopback-only check for `--dev-cors`; port range check `[0, 65535]`; scope validation.
+  - `src/server/paths.ts` — `resolveDefaultUiDist(ctx)` walks upwards from cwd looking for `ui/dist/browser/index.html`; `resolveExplicitUiDist(ctx, raw)` honours absolute paths for `--ui-dist`.
+  - `src/server/static.ts` — wraps `@hono/node-server`'s `serveStatic` middleware with the SPA-fallback layer (`serveStatic` does not do SPA fallback — it `next()`s on miss, which is exactly the seam we hook into). Absolute `root` paths work on POSIX in node-server@2.0.1 (verified runtime probe — implementation is `path.join(root, filename)`); the `.d.ts` "Absolute paths are not supported" string is stale (upstream issue honojs/node-server#187 still open). When the bundle is missing (`uiDist === null`), a tiny placeholder middleware serves the boot-without-bundle hint at `/`.
+  - `src/server/ws.ts` — `noopWebSocketRoute(app)` registers `GET /ws` via the official `upgradeWebSocket` re-exported from `@hono/node-server@2.x`. The 14.1 handler closes the connection in `onOpen` with code 1000 + reason `'no broadcaster yet'`. 14.4 swaps this registrar for the chokidar-fed broadcaster — one-line change in `index.ts`, `app.ts` untouched.
+  - `src/server/health.ts` — `buildHealth(deps)` synchronous; `resolveSpecVersion()` async, called once at boot.
+  - `src/server/i18n/server.texts.ts` — `SERVER_TEXTS` catalog.
+
+  **Files added (CLI)**
+
+  - `src/cli/commands/serve.ts` — `ServeCommand extends SmCommand`. Parses flags, validates, calls `createServer`, registers SIGINT/SIGTERM handlers, awaits shutdown. `protected emitElapsed = false` (long-running daemon).
+  - `src/cli/i18n/serve.texts.ts` — `SERVE_TEXTS` catalog.
+
+  **Tests added (15)**
+
+  - `src/test/server-boot.test.ts` (7) — boot/listen/health JSON, custom port, db state present/missing, structured 404, /ws upgrade closes with code 1000 + reason 'no broadcaster yet' (uses real `WebSocket` client from `ws`), shutdown < 1s + idempotent close, inline placeholder when uiDist null.
+  - `src/test/server-flags.test.ts` (6) — host non-loopback + dev-cors rejection, port out-of-range, port non-numeric, scope invalid, ui-dist missing, ui-dist with valid bundle.
+  - `src/test/server-db-missing.test.ts` (2) — `--db <missing>` exits 5, default boots cleanly with db:missing.
+
+  **Files edited**
+
+  - `src/cli/commands/stubs.ts` — `ServeCommand` removed; replaced with a comment pointer.
+  - `src/cli/entry.ts` — registers the new `ServeCommand`.
+  - `src/package.json` — adds `hono@4.12.16`, `@hono/node-server@2.0.1`, `ws@8.20.0` (deps); `@types/ws@8.18.1` (dev). All exact-pinned per AGENTS.md.
+  - `spec/cli-contract.md` — `sm serve` row replaced with the full 14.1 flag set; new `#### Server` subsection (stability: experimental).
+  - `spec/CHANGELOG.md` — `[Unreleased]` `### Minor` entry for the spec change.
+  - `spec/index.json` — regenerated (40 files hashed; previous head was 215 lines).
+
+  **Decisions during implementation (flag for orchestrator)**
+
+  - WebSocket support uses `@hono/node-server@2.x`'s built-in `upgradeWebSocket` plus the canonical `ws@8.20.0` Node WebSocket library, per the official README pattern. The previously-published `@hono/node-ws` adapter was deprecated when node-server@2.0 absorbed WebSocket support natively (PR honojs/node-server#328). The 14.4 broadcaster will replace `noopWebSocketRoute` with its own one-line registrar — no API churn between 14.1 and 14.4.
+  - The `/api/*` catch-all is wired with `app.all('/api/*', ...)` BEFORE the `/ws` registrar and the static handler so neither a `serveStatic` filesystem hit nor the SPA fallback can shadow API endpoints. `/ws` is registered BEFORE the static handler so a literal `/ws` path on disk inside `uiDist` cannot accidentally shadow the upgrade route.
+  - `serveStatic` from `@hono/node-server/serve-static` accepts absolute root paths at runtime on POSIX (its implementation is `path.join(root, filename)`); the `.d.ts` string saying otherwise is documentation drift, not a runtime contract. Verified with a runtime probe and cross-referenced against the open upstream issue (honojs/node-server#187). Documented in `src/server/static.ts` so future contributors don't re-investigate.
+
 ## 0.11.0
 
 ### Minor Changes
@@ -172,6 +714,155 @@ list`, `sm plugins doctor`, `sm db prune` plugin filter, runtime
 
 ## [Unreleased]
 
+### Minor
+
+- **Provider-driven kind presentation + envelope `kindRegistry`** —
+  Step 14.5.d. The Provider extension surface gains the required
+  `kinds[*].ui` field (label, color, optional dark-theme color, optional
+  emoji, optional icon) so each kind a Provider declares carries the
+  presentation metadata the UI needs to render it. The icon is a
+  discriminated union — `{ kind: 'pi'; id: 'pi-…' }` for PrimeIcons or
+  `{ kind: 'svg'; path: '…' }` for raw SVG path data wrapped in a
+  `viewBox="0 0 24 24"` tinted with `currentColor`. The UI derives bg /
+  fg tints from `color` per theme via a deterministic helper, so the
+  Provider declares one base color per theme rather than four hex
+  values.
+
+  The REST envelope shape (`schemas/api/rest-envelope.schema.json`)
+  gains a new required `kindRegistry` field on every payload-bearing
+  variant (`nodes` / `links` / `issues` / `plugins` lists, the `node`
+  single, and the `config` value envelope); sentinel envelopes
+  (`health` / `scan` / `graph`) stay exempt because they don't carry a
+  payload at the wire level either. The registry is keyed by kind
+  name and carries `{ providerId, label, color, colorDark?, emoji?,
+icon? }` — the BFF assembles it once at boot from every enabled
+  Provider and attaches it to every applicable response so the UI can
+  render Provider-declared kinds (built-in and user-plugin alike)
+  without hardcoding a closed kind enum.
+
+  **Why required, not optional**: making `ui` optional reintroduces the
+  trap the UI had pre-14.5.d (silently collapsing unknown kinds to
+  `'note'`). Forcing every Provider to declare presentation up-front
+  means the UI never has to invent visuals; the cost is one small
+  object per kind in the manifest.
+
+  **Why discriminated icon instead of two optional fields**: the
+  `oneOf` shape (with `kind: 'pi' | 'svg'` discriminator) keeps the UI
+  dispatch exhaustive without string-sniffing the payload, and AJV
+  validates each variant cleanly — a manifest cannot ship both `id` and
+  `path` simultaneously.
+
+  **Why `schemaVersion` stays at `'1'`**: the BFF is greenfield — no
+  released consumers depend on the previous (kindRegistry-less)
+  shape, so a versioned migration would only add ceremony. The
+  shape change is documented under this changelog entry; the version
+  bumps the day a third-party consumer ships against the wire.
+
+  Pre-1.0 minor breaking per `versioning.md` § Pre-1.0. The built-in
+  Claude Provider migrates in the same step (every kind declares its
+  `ui` block reusing the visuals previously hardcoded in the UI).
+
+  Conformance: new case `plugin-missing-ui-rejected` (with fixture
+  `plugin-missing-ui/`) locks the loader's behaviour against a drop-in
+  Provider that omits `ui` — `sm scan --json` exits 0, stderr matches
+  the canonical `must have required property 'ui'` diagnostic, and the
+  rest of the pipeline (built-in Claude) keeps running. Suite total:
+  5/5 passing across 2 scopes.
+
+- **BFF `/api/nodes/:pathB64` body opt-in** — Step 14.5.a extends the
+  single-node detail endpoint with the optional `?include=body` query
+  parameter. When set, the response's `item` carries `body: string |
+null` (the post-frontmatter file content read from disk on demand);
+  `null` indicates the source file was missing or unreadable when the
+  request landed. Without the flag, `item.body` stays `undefined` and
+  the handler does not touch the filesystem. The single-node response
+  shape is also corrected to the documented `{ schemaVersion, kind:
+'node', item: Node, links: { incoming: Link[], outgoing: Link[] },
+issues: Issue[] }` (the `### Server` table previously declared the
+  shape as the legacy `{ node, linksOut, linksIn, issues }` bundle —
+  see prose for the bug-fix rationale). No prod consumer ran against
+  the legacy shape, so the corrected shape ships as a minor.
+
+  **Why on-demand instead of persisting bodies in `scan_nodes`**: the
+  kernel persists `body_hash` only (per `db-schema.md` §scan_nodes) —
+  the body itself is human content, not machine state, and duplicating
+  it in SQLite would inflate the DB without serving any read-side
+  query the kernel cares about. Inspector cards that DO want to render
+  the body (markdown preview at Step 14.5) opt into the filesystem
+  re-read; the list / graph / kind-palette views never need it.
+
+  **Path-traversal defense**: the body reader (`src/server/node-body.ts`)
+  refuses absolute paths and any relative path that resolves outside
+  the scope root. A corrupted DB row or a future Provider that
+  forgets to sanitise its node paths cannot use this endpoint to leak
+  arbitrary files.
+
+- **BFF `/ws` protocol + watcher contract** — Step 14.4.a documents
+  the WebSocket surface. The `### Server` subsection grows a
+  **WebSocket protocol** block enumerating the wire envelope (delegated
+  to `job-events.md` §Common envelope), the v14.4.a event catalog
+  (`scan.started` / `scan.progress` / `scan.completed` plus the
+  side-effect events `extractor.completed` / `rule.completed` /
+  `extension.error`, plus the BFF-internal advisories
+  `watcher.started` / `watcher.error`), the connection lifecycle (no
+  state push on connect; client polls `/api/scan` to seed; close codes
+  used: 1000 / 1001 / 1009), the backpressure rule (4 MiB `bufferedAmount`
+  → close 1009 + unregister), and the loopback-only assumption (no
+  per-connection auth through v0.6.0 per Decision #119). The endpoint
+  table flips `GET /ws` from `upgrade-only` to `implemented (v14.4.a)`.
+  The `sm serve` flag table grows `--no-watcher` (default off — watcher
+  on per Decision #121); combining `--no-watcher` is documented;
+  combining `--no-built-ins` with the watcher is rejected (would
+  persist empty scans on every batch). The verb-catalog row for
+  `sm serve` mirrors the new flag.
+
+  `issue.added` / `issue.resolved` (the diff-based events from
+  `job-events.md` §Issue events) and `scan.failed` are explicitly
+  flagged as deferred — the 14.4.a surface fans out only what the
+  kernel emitter already produces; per-batch failure events and the
+  diff-based issue stream require additional plumbing in the BFF
+  watcher loop and land in a follow-up.
+
+  Additive minor per `versioning.md` § Pre-1.0; no breaking change to
+  any prior `/ws` behavior (the v14.1 / v14.2 / v14.3 surfaces all had
+  `/ws` documented as "upgrade-only — broadcaster lands at v14.4").
+
+- **BFF read-side endpoints** — Step 14.2 fills the `### Server`
+  subsection's endpoint catalogue from the v14.1 stub
+  (`GET /api/health` real, `ALL /api/*` 404) to the eight read-side
+  endpoints the Web UI consumes:
+  `GET /api/scan` (latest persisted `ScanResult`; `?fresh=1` for an
+  in-memory scan), `GET /api/nodes` (paginated, filtered list — same
+  query grammar as `sm export`), `GET /api/nodes/:pathB64` (single-node
+  bundle; `pathB64` is base64url of `node.path`), `GET /api/links`,
+  `GET /api/issues`, `GET /api/graph?format=...` (formatter rendering),
+  `GET /api/config`, `GET /api/plugins`. New
+  [`schemas/api/rest-envelope.schema.json`](schemas/api/rest-envelope.schema.json)
+  formalises the list-envelope shape (`{ schemaVersion, kind, items \|
+item \| value, filters, counts }`). The error envelope subsection
+  enumerates the v14.2 sources for each `code` value (`not-found` /
+  `bad-query` / `internal` / reserved `db-missing`). Stability stays
+  `experimental — locks at v0.6.0` (no change). Additive minor per
+  `versioning.md` § Pre-1.0; no breaking change — the v14.1 endpoint
+  catalogue was a stub explicitly slated to fill at v14.2.
+
+- **`sm serve` row + `### Server` subsection** in `cli-contract.md` —
+  Step 14.1 promotes `sm serve` from an implementation-defined stub to a
+  documented surface. The verb row at `§Verb catalog` › `### Server`
+  expands the flag set to the full 14.1 contract: `--port` (default
+  `4242`), `--host` (default `127.0.0.1`, loopback-only through v0.6.0),
+  `--scope project|global`, `--db <path>`, `--no-built-ins`,
+  `--no-plugins`, `--open` / `--no-open`, `--dev-cors`, `--ui-dist
+<path>` (hidden). New `#### Server` subsection documents the
+  single-port mandate, the boot-with-missing-DB resilience contract
+  (`/api/health` returns `db: 'missing'`), the v14.1 endpoint surface
+  (`GET /api/health` real, `ALL /api/*` 404 stubs, `GET /ws` upgrade-only,
+  static + SPA fallback), the structured error envelope shape, and the
+  flag table. Marked `*(Stability: experimental — locks at v0.6.0.)*` —
+  endpoints fill at v14.2, broadcaster at v14.4. Additive minor per
+  `versioning.md` § Pre-1.0 (no breaking change to the existing row's
+  semantics; the old wording was strictly less specific).
+
 ### Minor (breaking, pre-1.0)
 
 - **`Node.kind` opens to any non-empty string (was the closed enum
@@ -1159,9 +1850,9 @@ kind, normalizedTrigger)` and prints one row per group with the
       (`Links out (12, 9 unique)`). When N > 1 detector emits the same
       logical link, the row also gets a `(×N)` suffix.
 
-                                   `--json` output is byte-identical to before — raw rows, no merge.
-                                   Storage is byte-identical to before. The grouping is purely a
-                                   read-time presentation choice for human eyes.
+                                               `--json` output is byte-identical to before — raw rows, no merge.
+                                               Storage is byte-identical to before. The grouping is purely a
+                                               read-time presentation choice for human eyes.
 
   **Spec changes (patch)**:
 

package/cli-contract.md

@@ -316,7 +316,97 @@ Destructive verbs (`reset --state`, `reset --hard`, `restore`) require interacti
 
 | Command | Purpose |
 |---|---|
-| `sm serve [--port N] [--host ...] [--no-open]` | Start Hono + WebSocket for the Web UI. Default port is implementation-defined but MUST be the same across runs. Implementations MUST NOT bind 0.0.0.0 by default. |
+| `sm serve [--port N] [--host ...] [--scope project\|global] [--db <path>] [--no-built-ins] [--no-plugins] [--open\|--no-open] [--dev-cors] [--ui-dist <path>] [--no-watcher]` | Start Hono + WebSocket for the Web UI. Single-port mandate: SPA + REST + WS under one listener. Default port 4242, default host 127.0.0.1 (loopback-only through v0.6.0; multi-host deferred — see §Server). The watcher is on by default (Decision #121: a server with stale DB is a footgun); pass `--no-watcher` for CI / read-only deployments. |
+
+#### Server
+
+*(Stability: experimental — locks at v0.6.0.)*
+
+The reference implementation ships a Hono BFF rooted at `src/server/`. One Node process serves the Angular SPA, the REST API under `/api/*`, and the WebSocket at `/ws` — single-port mandate, no proxy. Loopback-only assumption through v0.6.0: no per-connection auth on `/ws`; combining `--dev-cors` with a non-loopback `--host` is rejected (exit 2).
+
+**Boot resilience**: `sm serve` boots even when the project DB is missing. `/api/health` reports `db: 'missing'` so the SPA can render an empty-state CTA instead of failing the connection. Explicit `--db <path>` that doesn't exist is the exception — that exits 5 (NotFound) per `§Exit codes`.
+
+**Endpoints (v14.2 surface)**:
+
+| Path | Status | Shape |
+|---|---|---|
+| `GET /api/health` | implemented | `{ ok: true, schemaVersion, specVersion, implVersion, scope: 'project'\|'global', db: 'present'\|'missing' }` |
+| `GET /api/scan` | implemented | latest persisted `ScanResult` (1:1 with `scan-result.schema.json`; byte-equal to `sm scan --json` modulo whitespace). DB absent → empty `ScanResult` shape (zero `nodes` / `links` / `issues`). |
+| `GET /api/scan?fresh=1` | implemented | runs an in-memory scan and returns the produced `ScanResult` without persistence. Rejects with `bad-query` (400) when the server was started with `--no-built-ins` or `--no-plugins` (would yield empty / partial results). |
+| `GET /api/nodes?kind=&hasIssues=&path=&limit=&offset=` | implemented | `RestEnvelope` (`kind: 'nodes'`) — paginated, filtered list. Filters share the `kind=` / `has=issues` / `path=<glob>` grammar with `sm export`. `hasIssues=false` is a server-side post-filter (not representable in the kernel grammar). Pagination defaults `offset=0`, `limit=100`; max `limit=1000`. |
+| `GET /api/nodes/:pathB64[?include=body]` | implemented | Single-node detail envelope: `{ schemaVersion, kind: 'node', item: Node, links: { incoming: Link[], outgoing: Link[] }, issues: Issue[] }`. `:pathB64` is base64url (RFC 4648 §5, no padding) of `node.path`. Missing node or malformed `pathB64` → 404 `not-found`. **`?include=body`** (Step 14.5.a) — opt-in flag that adds `item.body: string \| null` to the response. The body is read from disk on demand at request time (the kernel persists `bodyHash` only). `null` indicates the source file was missing / unreadable when the request landed (the watcher will re-emit `scan.completed` when it catches up). Without the flag, `item.body` is `undefined` and the handler does not touch the filesystem. |
+| `GET /api/links?kind=&from=&to=` | implemented | `RestEnvelope` (`kind: 'links'`) — list of links. Filters: `kind` (CSV whitelist of `link.kind`), `from` (exact match on `link.source`), `to` (exact match on `link.target`). No pagination at v14.2. |
+| `GET /api/issues?severity=&ruleId=&node=` | implemented | `RestEnvelope` (`kind: 'issues'`) — list of issues. Filters: `severity` (CSV from `error\|warn\|info`), `ruleId` (CSV; qualified or short suffix per `sm check --rules`), `node` (filter to issues whose `nodeIds` includes the path). No pagination at v14.2. |
+| `GET /api/graph?format=ascii\|json\|md` | implemented | formatter-rendered graph. `Content-Type` per format: `text/plain` (ascii), `application/json` (json), `text/markdown` (md / mermaid). Default `format=ascii`. Unknown format → 400 `bad-query`. |
+| `GET /api/config` | implemented | `RestEnvelope` (`kind: 'config'`) — merged effective config (defaults → user → user-local → project → project-local → override). |
+| `GET /api/plugins` | implemented | `RestEnvelope` (`kind: 'plugins'`) — list of installed plugins (built-in + drop-in) with status. Item shape: `{ id, version, kinds, status, reason, source: 'built-in'\|'project'\|'global' }`. |
+| `ALL /api/*` (other) | reserved | structured 404 envelope (see below); future endpoints land in subsequent sub-steps. |
+| `GET /ws` | implemented (v14.4.a) | accepts WebSocket upgrade and registers the client with the BFF broadcaster. Server-push only — the server fans `scan.*` (and forthcoming `issue.*`) events to every connected client. See **WebSocket protocol** below. |
+| `GET *` | implemented | static asset from the resolved UI bundle, falling back to `index.html` for SPA deep links. |
+
+List endpoints conform to [`schemas/api/rest-envelope.schema.json`](schemas/api/rest-envelope.schema.json). The `/api/scan` and `/api/health` responses carry their underlying `ScanResult` / `IHealthResponse` shapes directly (no envelope wrap). The `/api/graph` response carries the formatter's native textual output.
+
+**Error envelope** (mirrors `§Machine-readable output rules`):
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "not-found" | "bad-query" | "db-missing" | "internal",
+    "message": "<human-readable>",
+    "details": { ... } | null
+  }
+}
+```
+
+HTTP status mapping: `400` → `bad-query`, `404` → `not-found`, `500` → `internal` / `db-missing`.
+
+Error code sources at v14.2:
+
+- `not-found` (404) — unknown `/api/*` path; missing node on `/api/nodes/:pathB64`; malformed `pathB64` (treated as "no such node" so the client UX is uniform).
+- `bad-query` (400) — `ExportQueryError` from `parseExportQuery`; pagination beyond `limit ≤ 1000`; non-integer / negative `limit` / `offset`; unknown formatter on `/api/graph`; `?fresh=1` when the server started with `--no-built-ins` or `--no-plugins`.
+- `internal` (500) — uncaught error during a request (e.g. config-load failure, DB corruption surfacing through `loadScanResult`).
+- `db-missing` (500) — reserved for endpoints that cannot degrade to an empty result. The v14.2 routes uniformly degrade (`/api/scan` returns the empty shape; list endpoints return zero items) so this code is not currently emitted by any handler — it is documented for future endpoints (post-v0.6.0 mutations) where degradation is not safe.
+
+**Flag surface**:
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--port N` | `4242` | Listening port. `0` = OS-assigned (handle reports the bound port). |
+| `--host <ip>` | `127.0.0.1` | Listening host. Implementations MUST NOT bind `0.0.0.0` by default. |
+| `--scope project\|global` | `project` | Effective scope for `/api/*` reads. Alias for `-g/--global`. |
+| `--db <path>` | resolved per spec § Global flags | Override the DB file location. Missing explicit `--db` exits 5. |
+| `--no-built-ins` | off | Skip built-in plugin registration (parity with `sm scan --no-built-ins`). |
+| `--no-plugins` | off | Skip drop-in plugin discovery. |
+| `--open` / `--no-open` | `--open` | Auto-open the SPA in the user's default browser after listen. |
+| `--dev-cors` | off | Enable permissive CORS for the Angular dev-server proxy workflow. Loopback-only when set. |
+| `--ui-dist <path>` | auto | Override the UI bundle directory. Hidden flag — used by the demo build pipeline + tests; everyday users never need it. |
+| `--no-watcher` | off | Disable the chokidar-fed scan-and-broadcast loop. Use only for CI / read-only deployments — without the watcher, `/ws` stays open but no `scan.*` events ever fire. Combining with `--no-built-ins` is rejected (the watcher cannot run with an empty pipeline; would persist empty scans on every batch). |
+
+**WebSocket protocol** *(Stability: experimental — locks at v0.6.0)*:
+
+The `/ws` endpoint is the live-events channel for the SPA. Clients connect once at bootstrap, the server pushes events as they happen, and the SPA reconciles its in-memory store against the deltas. The wire envelope and `scan.*` payload shapes are normative in [`job-events.md`](./job-events.md) — the BFF emits them verbatim.
+
+- **Wire format**: each event is a single WebSocket text frame carrying one JSON object that conforms to `job-events.md` §Common envelope (`type`, `timestamp`, `runId?`, `jobId? | null`, `data`).
+- **Event catalog at v14.4.a**:
+  - `scan.started` (per `job-events.md` §Scan events line 325).
+  - `scan.progress` (per `job-events.md` line 345 — emitted by the kernel orchestrator at every node; throttling deferred to a follow-up).
+  - `scan.completed` (per `job-events.md` line 363).
+  - `extractor.completed` (per `job-events.md` line 384) and `rule.completed` (per `job-events.md` line 404) ride along as side effects of the same emitter bridge.
+  - `extension.error` (kernel-internal — emitted when an extension violates its declared contract; the BFF forwards verbatim).
+  - `watcher.started` and `watcher.error` — BFF-internal advisories. Non-normative; consumers MUST ignore unknown event types per the forward-compatibility rule.
+- **Deferred to a follow-up**: `issue.added` / `issue.resolved` (per `job-events.md` §Issue events line 446) and `scan.failed`. The 14.4.a surface fans out only the events the kernel emitter already produces; the diff-based issue events and a dedicated batch-failure event require additional plumbing inside the BFF watcher loop.
+- **Connection lifecycle**:
+  1. Client opens `ws://<host>:<port>/ws`. The server completes the WS handshake and registers the underlying socket with the broadcaster.
+  2. Server pushes events. The client sends nothing at v14.4.a — `onMessage` is intentionally not registered. A future heartbeat / subscribe / filter request lands in a follow-up.
+  3. Server has NO state push on connect (no replay of last events). The client SHOULD poll `/api/scan` once on connect to seed initial state, then rely on `/ws` for deltas.
+  4. On normal disconnect: client closes with code 1000 ('normal closure') or 1001 ('going away'). The broadcaster unregisters silently.
+  5. On server shutdown (SIGINT / SIGTERM): the broadcaster sends close code 1001 + reason `'server shutdown'` to every client, then closes the http listener.
+  6. **Backpressure**: if a client's outbound buffer (`bufferedAmount`) exceeds an implementation-defined threshold (the reference impl uses 4 MiB), the broadcaster closes that client with code 1009 ('message too big') and unregisters it. Clients SHOULD reconnect after backpressure eviction with a fresh `/api/scan` poll.
+  7. **Reconnect responsibility**: the server does NOT reconnect on the client's behalf and does NOT replay missed events on reconnect. The client SHOULD treat `/ws` as a best-effort delta channel and re-seed via `/api/scan` whenever the connection drops.
+- **Loopback-only assumption (Decision #119)**: no per-connection authentication on `/ws` through v0.6.0. The transport security boundary is the `--host` flag (defaults to `127.0.0.1`); the server rejects `--dev-cors` combined with a non-loopback `--host` precisely because that combination would expose `/ws` over the network without auth. Multi-host serve and an auth model re-open post-v0.6.0.
+
+**Graceful shutdown**: SIGINT / SIGTERM trigger a graceful close; the verb returns exit 0 on clean shutdown. Bind failure (port in use, EACCES) returns exit 2. The shutdown sequence drains the in-flight watcher batch (if any), closes every WS client with code 1001, then closes the http listener.
 
 ---
 

package/conformance/cases/plugin-missing-ui-rejected.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
+  "id": "plugin-missing-ui-rejected",
+  "description": "A drop-in Provider plugin whose `kinds[*]` entry omits the required `ui` block (Step 14.5.d) MUST be rejected by the loader with a clear `missing required property 'ui'` diagnostic on stderr, AND `sm scan` MUST exit cleanly with the rest of the pipeline (built-in Claude Provider) still running. Locks the contract that one bad plugin does not take down the scan.",
+  "fixture": "plugin-missing-ui",
+  "invoke": {
+    "verb": "scan",
+    "flags": ["--json"]
+  },
+  "assertions": [
+    { "type": "exit-code", "value": 0 },
+    { "type": "stderr-matches", "pattern": "plugin bad-provider:.*invalid.*must have required property 'ui'" },
+    { "type": "json-path", "path": "$.providers.length", "equals": 1 },
+    { "type": "json-path", "path": "$.providers[0]", "equals": "claude" },
+    { "type": "json-path", "path": "$.nodes.length", "equals": 1 }
+  ]
+}

package/conformance/coverage.md

@@ -32,8 +32,9 @@ This file is hand-maintained. A CI check before spec release compares the schema
 | 22 | `extensions/formatter.schema.json` | — | 🔴 missing | Case: `ascii` formatter manifest validates. |
 | 23 | `history-stats.schema.json` | — | 🔴 missing | Blocked by Step 5 (history). Case: seed `state_executions` with a deterministic fixture, run `sm history stats --json --since <T0> --until <T1> --period month --top 5`, assert the document validates and that `totals.executionsCount == sum(perAction.executionsCount)` and `errorRates.global == totals.failedCount / totals.executionsCount`. Percentiles (`p95`/`p99`) intentionally omitted in v1 — add later as a minor bump without breaking consumers. |
 | 24 | `extensions/hook.schema.json` | — | 🔴 missing | Case: a `deterministic` hook manifest with `triggers: ['scan.completed']` validates; a hook declaring an unknown trigger (e.g. `scan.progress`) fails with `invalid-manifest` at load time. |
+| 25 | `api/rest-envelope.schema.json` | — | 🔴 missing | Step 14.2 BFF list-envelope shape (`{ schemaVersion, kind, items \| item \| value, filters, counts }`). Case: hit `GET /api/nodes` against a primed scope, validate the response against the schema; assert the `oneOf` rejects an envelope that carries both `items` and `item`. Implementation-side coverage exists today (`src/test/server-endpoints.test.ts`) but a kernel-agnostic conformance case is required before v1.0.0 ships. |
 
-> **Note on Provider-owned schemas.** Per spec 0.8.0 Phase 3, the per-kind frontmatter schemas (`skill`, `agent`, `command`, `hook`, `note`) live with the Provider that emits them — for the built-in Claude Provider, that is `src/extensions/providers/claude/schemas/`. Those schemas are NOT counted in the spec's coverage matrix above; they belong to the Provider's own conformance suite (Phase 5 / A.13 — `src/extensions/providers/claude/conformance/coverage.md`). Phase 5 / A.13 also relocated the cases that exercised them (`basic-scan`, `rename-high`, `orphan-detection`) to the Provider's own `cases/` directory. The matrix shrinks from 28 to 23 rows accordingly. The Hook kind (A.11) brings it back up to 24.
+> **Note on Provider-owned schemas.** Per spec 0.8.0 Phase 3, the per-kind frontmatter schemas (`skill`, `agent`, `command`, `hook`, `note`) live with the Provider that emits them — for the built-in Claude Provider, that is `src/extensions/providers/claude/schemas/`. Those schemas are NOT counted in the spec's coverage matrix above; they belong to the Provider's own conformance suite (Phase 5 / A.13 — `src/extensions/providers/claude/conformance/coverage.md`). Phase 5 / A.13 also relocated the cases that exercised them (`basic-scan`, `rename-high`, `orphan-detection`) to the Provider's own `cases/` directory. The matrix shrinks from 28 to 23 rows accordingly. The Hook kind (A.11) brings it back up to 24, and Step 14.2's BFF envelope brings it to 25.
 
 Status legend: 🟢 covered (at least one case asserts the schema end-to-end) · 🟡 partial (covered only indirectly or via a sub-shape) · 🔴 missing.
 

package/conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "bad-provider",
+  "version": "0.1.0",
+  "specCompat": "*",
+  "extensions": ["provider.js"]
+}

package/conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/provider.js

@@ -0,0 +1,31 @@
+// Conformance fixture: provider whose `kinds[*]` entry deliberately
+// omits the required `ui` block (Step 14.5.d). The plugin loader MUST
+// reject this manifest with a clear "missing required property 'ui'"
+// diagnostic and the plugin MUST end up in `invalid-manifest` status.
+// The companion case `plugin-missing-ui-rejected.json` asserts the
+// stderr text and that `sm scan` survives (the loader degrades the
+// bad plugin and lets the rest of the pipeline continue).
+export default {
+  kind: 'provider',
+  id: 'bad-provider-provider',
+  version: '0.1.0',
+  description: 'provider whose note kind is missing the ui block',
+  stability: 'experimental',
+  explorationDir: '~/.bad',
+  kinds: {
+    note: {
+      schema: './schemas/note.schema.json',
+      schemaJson: {
+        $id: 'urn:test:bad-provider/note',
+        type: 'object',
+        additionalProperties: true,
+      },
+      defaultRefreshAction: 'bad-provider/summarize-note',
+      // NOTE: deliberately no `ui` — this is what the case asserts.
+    },
+  },
+  async *walk() {},
+  classify() {
+    return 'note';
+  },
+};

package/conformance/fixtures/plugin-missing-ui/notes/example.md

@@ -0,0 +1,8 @@
+---
+name: example
+description: Trivial markdown so the Claude built-in has something to scan.
+metadata:
+  version: 1.0.0
+---
+
+Body.

package/index.json

@@ -166,17 +166,21 @@
       }
     ]
   },
-  "specPackageVersion": "0.11.0",
+  "specPackageVersion": "0.13.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "11a95c44a9dd97180d2e281ba652b53e530020c592763113874a8c8bbd65ece8",
+      "CHANGELOG.md": "3e4ba3c64fdd33110465741fb697234a5cec0b5b604caa6721ee872aaf6df177",
       "README.md": "bd30780525e75379eaeb5f8a903bdc601daf3862f3ec69dffc96c437e8d476fc",
       "architecture.md": "9a6d96d150af60ed8d476af572d07dcce605f116fde720bebb2662b11250bf4b",
-      "cli-contract.md": "62a0f89f4da6207499b26c4ca8e35f3d59054a7521834698e5007f697b514af2",
+      "cli-contract.md": "45c2c72a8ff9266fb67593ad5f4e86e806d58cec48a1844da02ad1aaa36b8085",
       "conformance/README.md": "838b1247e1ffb402d96bd8a0fe9c1c0f4a99ed0fbc4bf8156f7a58330cac27f5",
       "conformance/cases/kernel-empty-boot.json": "ad4bbe9d637537625025c8bdb61285b1433568a2544b1ce0248f304ccff8c350",
-      "conformance/coverage.md": "4df23b78ec44887dc355e0622b9008bb2514f3b8e9c302db18eb51532fda5275",
+      "conformance/cases/plugin-missing-ui-rejected.json": "c6ce8f62a430d662aea33dec8ebf6493be6455037be3114e0d93d0eb57777287",
+      "conformance/coverage.md": "bddece19aa42297e75b2b1f6595bc9bb72fc849332a421b099fbdd1e8789e77d",
+      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/plugin.json": "4d78af6f12faa9d131e2a19f1dbb8f250baacc525978f3a8c858932b95da4ff6",
+      "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/provider.js": "da40b134d70f8bc8175cfa9c380ecb55d26b2240c8b467f22f3fcfab750c8747",
+      "conformance/fixtures/plugin-missing-ui/notes/example.md": "55767f0aa1b6774546a99f28c58e7b732aa9cfa5dfce8d0326470f7f622f577e",
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
       "db-schema.md": "cbd2d3395ca4f01065d6f15405c7442d59a468b15448377d6f9373fa6aeff334",
       "interfaces/security-scanner.md": "4a982667008f233656f44c61ce9948e062432d3debdcbf7a134da03bd4139d7d",
@@ -185,6 +189,7 @@
       "plugin-author-guide.md": "2dcdf8c570342d94c2c8f8d47594715254e3956d7939443023f1d6420e2b30d0",
       "plugin-kv-api.md": "04b2178f46fb88adeae9240df9c9e1761b660396072001dac32cd402e11a2d7d",
       "prompt-preamble.md": "fb40ab510234383326f198dec82cd6d744f28b7432eebac6cbfbb7ca1c483b7d",
+      "schemas/api/rest-envelope.schema.json": "7d9d74bcb2158019cb6e30306d40b9c7ffc67e9d202fb8210fe4e4a9e8fa4dab",
       "schemas/conformance-case.schema.json": "7cd0f3aae5124f24be57cddb213d002d0466f79d06fd3da896075c8b28650410",
       "schemas/execution-record.schema.json": "9628fa557cb856402f3a5f1d1167c609e46a197c850fe8171abfddd46c1028a8",
       "schemas/extensions/action.schema.json": "262272175c06a2e33c08f819a45c3ef8260276c91a9d0542fdffc932aeb32db7",
@@ -192,7 +197,7 @@
       "schemas/extensions/extractor.schema.json": "122d3f81ef91edcde9798e7dc8fcbf442a2996deea65aa4b03c9d5cb01ba2519",
       "schemas/extensions/formatter.schema.json": "2ab092aa37ae349c69b93071ed4f0e131affb7bb5799516ca82c721262631b36",
       "schemas/extensions/hook.schema.json": "7465c38e0765edf23e49d4f96c539d04323f1cf564af1c60ee637c79a6d39239",
-      "schemas/extensions/provider.schema.json": "27c627151fb98cf60763aaa122d807bbf007317f06bd31e92a2fca43c100e4b8",
+      "schemas/extensions/provider.schema.json": "518d7666841cfef8eb28aab788a6e6dfabf9e12f3f06de1c81be915cbe6c1088",
       "schemas/extensions/rule.schema.json": "8ff420bde498f50db114c352305d487c71aef2dd746fd0c24976ff6a09865c22",
       "schemas/frontmatter/base.schema.json": "dfee192458765b8cb872ef9e7145ec31b9e07ceb19ee44be48af2172329e7a38",
       "schemas/history-stats.schema.json": "23f472d1de06d23fc775aabba821f8375f347af4dc8d89ba567980d61a11f9de",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",

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

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/api/rest-envelope.schema.json",
+  "title": "RestEnvelope",
+  "description": "Wrapper shape for REST responses under `/api/*` (Step 14.2). Three variants distinguished by the `kind` discriminator and which payload field is present (`items` for list kinds, `item` for single-resource kinds, `value` for `kind: 'config'`). The `/api/scan` and `/api/health` responses are exempt — they carry the underlying `ScanResult` / `IHealthResponse` shape directly. The `/api/graph` response is also exempt — it returns the formatter's native textual output (text/plain or text/markdown). Step 14.5.d adds the required `kindRegistry` field on every payload-bearing variant so the UI can render Provider-declared kinds (label, color, icon) without hardcoding visuals; sentinel kinds (`health`, `scan`, `graph`) stay exempt because they don't carry an envelope payload. The change keeps `schemaVersion` at `'1'` — the BFF is greenfield (no released consumers run against `'1'` without `kindRegistry`), so a versioned migration buys nothing.",
+  "type": "object",
+  "required": ["schemaVersion", "kind"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1",
+      "description": "Envelope shape version. Bumped only on breaking changes. The Step 14.5.d addition of `kindRegistry` keeps the version at `'1'` because there are no released consumers in the wild."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["nodes", "links", "issues", "plugins", "config", "graph", "node", "health", "scan"],
+      "description": "Discriminator. List kinds (`nodes`, `links`, `issues`, `plugins`) carry `items`. The `node` kind carries `item`. The `config` kind carries `value`. The `health` / `scan` / `graph` values are reserved for documentation parity with the routes that DON'T use this envelope."
+    },
+    "items": {
+      "type": "array",
+      "description": "Present when `kind` is one of the list kinds (`nodes`, `links`, `issues`, `plugins`). Empty array is valid and means the filter matched zero rows."
+    },
+    "item": {
+      "type": "object",
+      "description": "Present when `kind` is `'node'`. Single-resource envelope payload."
+    },
+    "value": {
+      "type": "object",
+      "description": "Present when `kind` is `'config'`. Carries the merged effective config object."
+    },
+    "filters": {
+      "type": "object",
+      "description": "Echo of the URL filters the server applied, normalized into a JSON-friendly shape (arrays for multi-value filters, `null` for absent ones). Helps the client correlate the response with the request."
+    },
+    "kindRegistry": {
+      "type": "object",
+      "description": "Catalog of node kinds active in the current scope, keyed by kind name. Built once per server boot from every enabled Provider's `kinds` map and embedded into every payload-bearing envelope so the UI can render kind tags / palette swatches / graph nodes against Provider-declared visuals (label, color, icon) without ever hardcoding a closed kind enum. Sentinel envelopes (`health`, `scan`, `graph`) are exempt.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["providerId", "label", "color"],
+        "additionalProperties": false,
+        "properties": {
+          "providerId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Id of the Provider that contributed this kind. Lets the UI scope kind ownership and disambiguate when two Providers happen to declare the same kind name (kernel surfaces this as `provider-ambiguous` but the UI may still receive the merged registry during the conflict window)."
+          },
+          "label": { "type": "string", "minLength": 1 },
+          "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+          "colorDark": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+          "emoji": { "type": "string", "minLength": 1, "maxLength": 8 },
+          "icon": {
+            "oneOf": [
+              {
+                "type": "object",
+                "required": ["kind", "id"],
+                "additionalProperties": false,
+                "properties": {
+                  "kind": { "const": "pi" },
+                  "id": { "type": "string", "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$" }
+                }
+              },
+              {
+                "type": "object",
+                "required": ["kind", "path"],
+                "additionalProperties": false,
+                "properties": {
+                  "kind": { "const": "svg" },
+                  "path": { "type": "string", "minLength": 1 }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "counts": {
+      "type": "object",
+      "required": ["total", "returned"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total rows after filtering, before pagination is applied."
+        },
+        "returned": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Rows actually carried in `items` (≤ `limit`)."
+        },
+        "page": {
+          "type": "object",
+          "required": ["offset", "limit"],
+          "properties": {
+            "offset": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Pagination window offset (zero-based)."
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Maximum items the page may carry."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Pagination window. Present when the endpoint paginates (today: `/api/nodes` only)."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Tally + paging info. Present on every list / single envelope; absent on `health` / `scan` / `graph` responses (which don't use this envelope)."
+    }
+  },
+  "oneOf": [
+    {
+      "description": "List envelope — `items` payload + `counts` + `kindRegistry`.",
+      "required": ["items", "counts", "filters", "kindRegistry"],
+      "properties": {
+        "kind": { "enum": ["nodes", "links", "issues", "plugins"] }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["item"] },
+          { "required": ["value"] }
+        ]
+      }
+    },
+    {
+      "description": "Single-resource envelope — `item` payload + `kindRegistry`, no `counts` / `filters`.",
+      "required": ["item", "kindRegistry"],
+      "properties": {
+        "kind": { "const": "node" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["value"] }
+        ]
+      }
+    },
+    {
+      "description": "Value envelope — `value` payload + `kindRegistry`, no `counts` / `filters`.",
+      "required": ["value", "kindRegistry"],
+      "properties": {
+        "kind": { "const": "config" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["item"] }
+        ]
+      }
+    },
+    {
+      "description": "Sentinel kinds — reserved for routes that do NOT carry an envelope payload at the wire level (`health`, `scan`, `graph`). They do not carry `kindRegistry` either; clients that need it must call any payload-bearing endpoint at boot.",
+      "properties": {
+        "kind": { "enum": ["health", "scan", "graph"] }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["items"] },
+          { "required": ["item"] },
+          { "required": ["value"] },
+          { "required": ["kindRegistry"] }
+        ]
+      }
+    }
+  ],
+  "additionalProperties": false
+}

package/schemas/extensions/provider.schema.json

@@ -31,7 +31,7 @@
       },
       "additionalProperties": {
         "type": "object",
-        "required": ["schema", "defaultRefreshAction"],
+        "required": ["schema", "defaultRefreshAction", "ui"],
         "additionalProperties": false,
         "properties": {
           "schema": {
@@ -43,6 +43,66 @@
             "type": "string",
             "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*/[a-z][a-z0-9]*(-[a-z0-9]+)*$",
             "description": "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 by the time the graph is queried; a dangling reference disables the Provider with status `invalid-manifest`."
+          },
+          "ui": {
+            "type": "object",
+            "required": ["label", "color"],
+            "additionalProperties": false,
+            "description": "Presentation metadata the UI uses to render nodes of this kind (palette swatches, list tags, graph nodes, filter chips). Required so the UI never has to invent visuals for a kind a Provider declares. The Provider declares intent (label + base color, optional dark variant + emoji + icon); the UI derives bg/fg tints from `color` per theme via a deterministic helper. Reaches the UI via the `kindRegistry` field embedded in REST envelopes (`api/rest-envelope.schema.json`).",
+            "properties": {
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Plural human-readable label for groups of this kind (e.g. `'Skills'`, `'Agents'`, `'Cursor Rules'`). Used in filter dropdowns, palette tooltips, and any list grouping."
+              },
+              "color": {
+                "type": "string",
+                "pattern": "^#[0-9a-fA-F]{6}$",
+                "description": "Base hex color (light theme). The UI derives `bg` and `fg` tints from this value at runtime; declaring a single base value (instead of three) keeps the manifest small and lets the UI control accessibility-driven contrast."
+              },
+              "colorDark": {
+                "type": "string",
+                "pattern": "^#[0-9a-fA-F]{6}$",
+                "description": "Optional dark-theme variant of `color`. When absent, the UI falls back to `color`. Declared explicitly because a luminosity flip rarely matches the brand intent for kinds that should stand out in dark mode."
+              },
+              "emoji": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 8,
+                "description": "Optional decorative emoji used as a fallback when `icon` is absent or fails to render. Bound to a small length so the UI can lay it out predictably alongside text."
+              },
+              "icon": {
+                "description": "Optional discriminated icon descriptor. The UI prefers `icon` over `emoji`; when both are absent, the UI falls back to the first letter of `label` colored with `color`.",
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "required": ["kind", "id"],
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": { "const": "pi" },
+                      "id": {
+                        "type": "string",
+                        "pattern": "^pi-[a-z0-9]+(-[a-z0-9]+)*$",
+                        "description": "PrimeIcons identifier (e.g. `pi-cog`, `pi-bolt`). Matched verbatim against the `pi pi-<id>` class the UI emits."
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "required": ["kind", "path"],
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": { "const": "svg" },
+                      "path": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Raw SVG path data (the `d` attribute of one or more `<path>` elements, joined). The UI wraps it in `<svg viewBox=\"0 0 24 24\"><path d=\"...\"/></svg>` and tints it with `currentColor`."
+                      }
+                    }
+                  }
+                ]
+              }
+            }
           }
         }
       }