fix(mesh): add inference-only embedded peer surface

.agents/skills/benchmark-tune/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: benchmark-tune
+description: Use this skill when running, debugging, interpreting, or documenting mesh-llm benchmark tune model-serving throughput trials, including choosing ctx/batch/ubatch/mmap/mlock/speculative-decoding sweeps, running benchmark tune on local or SSH hosts, collecting JSON evidence, and applying tolerance-aware recommendations. Trigger for requests mentioning benchmark tune, tuning tok/s, ctx_size tradeoffs, mmap or mlock tuning, speculative decoding, MTP, ngram, draft models, or replacing old gpu tune usage.
+---
+
+# Benchmark Tune
+
+Use `mesh-llm benchmark tune` for model-serving throughput tuning. Do not use
+`mesh-llm gpu tune` or `mesh-llm gpus tune`; the GPU namespace is for hardware
+inventory and raw fingerprinting (`mesh-llm gpus`, `mesh-llm gpus detect`, and
+hidden `gpus run-benchmark`).
+
+## Preflight
+
+Verify the command surface from the current checkout before long runs:
+
+```bash
+target/release/mesh-llm benchmark --help
+target/release/mesh-llm benchmark tune --help
+target/release/mesh-llm gpus --help
+```
+
+For performance work, use a release build on the target host:
+
+```bash
+just release-build
+```
+
+On NVIDIA remote hosts, verify that the release binary is actually using CUDA
+before recording performance results. For Jetson/Orin-style aarch64 CUDA hosts,
+prefer the repo's CUDA backend build path for the host, for example
+`scripts/build-linux.sh --backend cuda --cuda-arch 87`, with the host CUDA
+toolkit paths exported as needed. A generic release build that reports CPU
+devices is not valid performance evidence for GPU tune work.
+
+If the run is on a remote node over SSH and will take time, use the
+`remote-observable-process` skill. Prefer a TTY/login shell and `tee` logs over
+detached first attempts.
+
+## Targets
+
+Benchmark tune accepts already-downloaded local/configured model targets only.
+It will not fetch remote-only refs. If no explicit target is passed, it uses
+configured local models from `~/.mesh-llm/config.toml`.
+
+Use one of:
+
+```bash
+mesh-llm benchmark tune --model /models/model.gguf
+mesh-llm benchmark tune --models /models/a.gguf,/models/b.gguf
+mesh-llm benchmark tune
+```
+
+## Candidate Sweep
+
+Start with a bounded sweep, then expand around promising values:
+
+```bash
+mesh-llm benchmark tune \
+  --model /models/model.gguf \
+  --ctx-sizes 8192,32768,131072,262144 \
+  --batch-sizes 512,1024,2048 \
+  --ubatch-sizes 256,512,1024 \
+  --mmap-values auto,true,false \
+  --mlock-values false,true \
+  --speculative-types auto \
+  --throughput-tolerance-pct 10 \
+  --max-tokens 128 \
+  --debug-telemetry \
+  --json
+```
+
+Rules:
+
+- `ubatch` must be less than or equal to `batch`; invalid pairs are skipped.
+- `mmap` and `mlock` are separate controls. Sweep them independently when
+  diagnosing load/runtime behavior.
+- If `--mmap-values` is omitted, tune tries `auto`, `true`, and `false`.
+- If `--mlock-values` is omitted, tune tries `false` and only tries `true` when
+  the current mlock probe says the evaluated budget can be locked.
+- If `--speculative-types` is omitted, tune uses `auto`: it tries
+  `mtp` first when the model target looks like an MTP model, tries
+  discovered local draft-model candidates when available, tries ngram
+  candidates as a model-free fallback, then includes a disabled baseline.
+- Use `--no-speculative-tune` when you need to reproduce the older
+  fit-only/disabled-speculation behavior or isolate non-speculative regressions.
+- Use `--speculative-types mtp,draft,ngram,disabled` to force an
+  explicit speculative sweep. `draft` requires either `--spec-draft-models`, a
+  configured `draft_model_path`, or a local sibling GGUF whose filename looks
+  like a draft/EAGLE model for the target.
+- MTP and draft sweeps use `--spec-draft-max-tokens` and
+  `--spec-draft-min-tokens`. Ngram sweeps use `--spec-ngram-min` and
+  `--spec-ngram-max`.
+- Use longer `--max-tokens` when decode throughput is noisy; use shorter values
+  only for smoke checks.
+- Keep `--throughput-tolerance-pct` near the default `10` unless the user asks
+  for stricter raw throughput optimization.
+- Add `--debug-telemetry` when you need proof that speculative decoding is
+  actually active. It runs trial children with Skippy debug telemetry mirrored
+  into `target/gpu-tune/.../serve.log`.
+
+## Evidence
+
+Capture machine-readable output and trial logs:
+
+```bash
+mkdir -p target/benchmark-tune
+mesh-llm benchmark tune ... --json \
+  | tee target/benchmark-tune/$(hostname)-$(date +%Y%m%d-%H%M%S).json
+```
+
+For remote hosts, include host, branch, commit, binary path, command, and output
+path in the final report. Benchmark tune keeps per-trial logs under
+`target/gpu-tune/`; inspect those logs when a trial fails or startup readiness
+is slow.
+
+Useful JSON fields:
+
+- `benchmarks[].best`: tolerance-aware recommendation.
+- `benchmarks[].raw_best`: highest observed decode tok/s.
+- `benchmarks[].pareto_frontier`: tradeoff set for decode tok/s vs `ctx_size`.
+- `benchmarks[].trials[].decode_tok_s`: measured decode throughput.
+- `benchmarks[].trials[].candidate.speculative`: speculative mode and settings
+  used for that isolated trial.
+- `benchmarks[].trials[].timings`: lifecycle timing stats: `setup_ms`,
+  `readiness_ms`, `request_ms`, `shutdown_ms`, `total_ms`, and
+  `readiness_attempts`.
+- `benchmarks[].trials[].error` and `log_path`: first stop for failures.
+
+## Interpretation
+
+Report both raw best and recommended settings. The recommendation is
+tolerance-aware: candidates within `--throughput-tolerance-pct` of raw best are
+treated as throughput-equivalent, then larger `ctx_size` is preferred.
+
+Call out tradeoffs explicitly:
+
+- If raw best and recommended differ, explain the tok/s delta and context gain.
+- If `mmap` or `mlock` changes the winner, report those controls separately.
+- If speculative decoding changes the winner, report both tok/s and the active
+  speculative candidate. For MTP, inspect trial logs/telemetry for
+  `llama_stage.native_mtp.enabled`, drafted/accepted/rejected counts, and
+  accept rate before concluding it is helping. Use `--debug-telemetry` if those
+  attributes are not present in the trial log.
+- If all trials fail, summarize the shared failure reason and link the trial log
+  paths rather than claiming no viable configuration exists.
+- If results are close, avoid overfitting decimals; prefer the setting with the
+  better context or operational posture.

.agents/skills/benchmark-tune/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Benchmark Tune"
+  short_description: "Run mesh-llm benchmark tune safely."
+  default_prompt: "Use benchmark tune to evaluate local model-serving settings, choose candidate sweeps, and interpret results."

.agents/skills/config-settings-management/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: config-settings-management
+description: Use this skill when adding, renaming, removing, validating, or exposing mesh-llm config settings, including built-in settings, plugin config schemas, owner-control apply behavior, CLI validation, and UI configuration surfaces.
+metadata:
+  short-description: Keep mesh-llm config settings complete
+---
+
+# config-settings-management
+
+Use this skill before changing any setting that appears in
+`~/.mesh-llm/config.toml`, the owner-control configuration API, the runtime
+configuration UI, or an installed plugin's `config_schema`.
+
+## Mental Model
+
+Config settings are not just struct fields. A complete setting has:
+
+- A persisted TOML shape in `crates/mesh-llm-config/src/model.rs`.
+- Authoring/editor support in `crates/mesh-llm-config/src/authoring.rs` when
+  code needs to create or mutate it.
+- Built-in schema metadata in
+  `crates/mesh-llm-config/src/model/built_in_schema.rs` when it is a core
+  mesh-llm setting.
+- Validation diagnostics in `crates/mesh-llm-config/src/validate.rs`, with
+  stable `ConfigPath` and canonical path metadata.
+- Runtime schema aggregation/export in
+  `crates/mesh-llm-host-runtime/src/config_schema.rs`.
+- Owner-control apply behavior in
+  `crates/mesh-llm-host-runtime/src/runtime/config_state.rs` when it can be
+  changed dynamically.
+- API/protocol conversion coverage in `crates/mesh-llm-host-runtime/src/api/`,
+  `crates/mesh-llm-host-runtime/src/protocol/`, and
+  `crates/mesh-llm-protocol/proto/node.proto` when it crosses process or node
+  boundaries.
+- UI adapter and fixture coverage under
+  `crates/mesh-llm-ui/src/features/configuration/` and
+  `crates/mesh-llm-host-runtime/tests/fixtures/`.
+
+## Built-In Settings Checklist
+
+When adding or removing a built-in setting:
+
+- Update `MeshConfig` or the owning nested config struct in
+  `crates/mesh-llm-config/src/model.rs`.
+- Update defaults and editor helpers in `authoring.rs` if generated configs,
+  tests, or command flows need to write the setting.
+- Add, rename, or remove the corresponding descriptor in
+  `model/built_in_schema.rs`. Include owner, value schema, support state,
+  control surfaces, apply mode, restart scope, visibility, constraints, aliases,
+  and description.
+- Update validation in `validate.rs`. Prefer structured `ConfigDiagnostic`
+  helpers over plain string errors.
+- Preserve compatibility with existing TOML when possible. Use aliases and
+  warnings for renamed keys; reserve `version = 1` bumps for actual incompatible
+  persisted config format changes.
+- Update schema fixtures and UI adapter expectations when exported schema JSON
+  changes.
+- Run `mesh-llm config validate --config-path <fixture> --json` for at least one
+  valid and one invalid representative file.
+
+## Plugin Settings Checklist
+
+Plugin settings are install-time schemas, not hard-coded built-in settings.
+
+- The plugin manifest owns its schema through `config_schema` in
+  `crates/mesh-llm-plugin/src/manifest.rs` and
+  `crates/mesh-llm-plugin/proto/plugin.proto`.
+- Keep `schema_version` at
+  `mesh_llm_config::SUPPORTED_PLUGIN_CONFIG_SCHEMA_VERSION` unless the schema
+  format itself becomes incompatible. Tightening validation of existing v1
+  fields such as `required`, type, enum, object, array, or constraints does not
+  by itself require a schema version bump.
+- Host-side installed plugin schema loading and strict validation live in
+  `crates/mesh-llm-host-runtime/src/plugin/config.rs` and
+  `crates/mesh-llm-config/src/plugin_validation.rs`.
+- Required plugin settings must be rejected even when `[plugin.settings]` is
+  absent.
+- Missing or unavailable schemas should reject custom settings, but plugin
+  entries without custom settings should remain loadable when possible.
+- `allow_unvalidated_config` should produce warnings, not silently drop
+  diagnostics from success responses.
+
+## Owner-Control And UI
+
+- Dynamic apply behavior belongs in
+  `crates/mesh-llm-host-runtime/src/runtime/config_state.rs`.
+- The management API should return diagnostics for both rejected applies and
+  successful applies with warnings.
+- Protobuf changes must be additive unless explicitly approved as breaking.
+  Older nodes and clients should ignore unknown fields.
+- The UI should consume exported schema metadata instead of duplicating setting
+  ownership, labels, constraints, or apply behavior.
+- Snapshot fixtures in `crates/mesh-llm-host-runtime/tests/fixtures/` are the
+  cross-check between Rust schema export and the TypeScript adapter.
+
+## Validation
+
+Run cargo commands serially. For config-surface changes, start with:
+
+```bash
+cargo test -p mesh-llm-config --lib
+cargo test -p mesh-llm-host-runtime --lib schema_export
+cargo test -p mesh-llm-host-runtime --lib runtime_config
+cargo test -p mesh-llm-host-runtime --lib plugin_config
+cargo test -p mesh-llm-plugin --lib
+cargo test -p mesh-llm-plugin-manager --lib
+cargo test -p mesh-llm-cli config_validate --lib
+cargo test -p mesh-llm config_validate --lib
+cargo check -p mesh-llm
+cargo clippy -p mesh-llm-config -p mesh-llm-plugin -p mesh-llm-plugin-manager -p mesh-llm-host-runtime -p mesh-llm-cli -p mesh-llm --all-targets -- -D warnings
+```
+
+Also run the UI checks when the schema export or adapter changes:
+
+```bash
+cd crates/mesh-llm-ui
+npm test -- --run src/features/configuration/api/config-adapter.test.ts
+npm run typecheck
+```
+
+Use the repo build gate before publishing broad changes:
+
+```bash
+just build
+```