docs(nvpair-ui-broker): add normative service specification

[Noah-Tervalon-Nvidia]

Description

Adds services/nvpair-ui-broker/spec.md, the normative specification for the supervisor and client front door, derived from the Go source and its tests and following the structure of the existing specs.

It describes the broker as it runs today:

• ten supervised workers, with a single nvpair-proxy process behind the ollama-proxy: and lmstudio-proxy: namespaces;
• a bounded teardown that fits inside the 15 s the desktop app and nvpair-tui allow;
• worker stderr decoupled through a non-blocking sink with an overflow log;
• the engine settings operations every port change runs through, summarized with ENGINE_SETTINGS.md as the detailed protocol;
• a process-wide priority cache and a source-aware telemetry cache feeding the scheduler;
• the peer-activity and observed-address relays into the scanner.

Release intent

Changelog title

n/a

Changelog body

n/a

Bumps

• services: none
• nvpair-cluster-manager: none
• nvpair-engine-manager: none
• nvpair-errors: none
• nvpair-job-scheduler: none
• nvpair-manual-nodes: none
• nvpair-node-info: none
• nvpair-node-scanner: none
• nvpair-node-settings: none
• nvpair-proxy: none
• nvpair-tui: none
• nvpair-ui-broker: none
• nvpair-workload-manager: none

Scope

Documentation only: one new file. No Go, desktop, or version changes. ENGINE_SETTINGS.md is referenced, not duplicated.

Validation

• node scripts/spdx-headers.mjs passes.
• Every behavioral statement was checked against the source on develop.

Risk

None at runtime. spec.md is normative, so please flag any statement that does not match the code.

Checklist

• I have read the Contributing Guidelines.
• Every commit is signed off (git commit -s), certifying the Developer Certificate of Origin.
• New or existing tests cover the change. (Not applicable: documentation only.)
• Relevant documentation is updated.
• I checked the diff, changed filenames, and commit messages for credentials, private data, internal URLs, internal issue identifiers, and generated artifacts.
• I recorded the validation commands and results above.
• I declared version bumps in the release-intent block above. services/versions.json is written by automation — do not edit it by hand.

[nvrithik]

LGTM

[nvrithik]

Spec predates #148 (llama.cpp) and #117 (TUI rebuild); please re-verify against develop.

llama.cpp integration required. It is a third registered engine: --proxy-engines defaults to ollama,lmstudio,llamacpp
(§15 says "today ollama,lmstudio"), llamacpp-proxy:* is a live namespace served generically by engineproxy.go, and
advertiser.go registers lc. Please update §2, §7.0 (relay/method tables), §6/§5 (get-status), §7.3 and §7.8 (ol/lm),
and note in §7.7 that llama.cpp has no compatibility-port takeover.

Stale TUI statement. §3 "Change a port from the terminal" says nvpair-tui sends ollama-proxy:set-port; the TUI now uses
engine:preview-settings → engine:apply-settings (ui/enginesettings.go).