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 mesh/crates/mesh-llm-config/src/model.rs.
• Authoring/editor support in mesh/crates/mesh-llm-config/src/authoring.rs when code needs to create or mutate it.
• Built-in schema metadata in mesh/crates/mesh-llm-config/src/model/built_in_schema.rs when it is a core mesh-llm setting.
• Validation diagnostics in mesh/crates/mesh-llm-config/src/validate.rs, with stable ConfigPath and canonical path metadata.
• Runtime schema aggregation/export in mesh/crates/mesh-llm-host-runtime/src/config_schema.rs.
• Owner-control apply behavior in mesh/crates/mesh-llm-host-runtime/src/runtime/config_state.rs when it can be changed dynamically.
• API/protocol conversion coverage in mesh/crates/mesh-llm-host-runtime/src/api/, mesh/crates/mesh-llm-host-runtime/src/protocol/, and mesh/crates/mesh-llm-protocol/proto/node.proto when it crosses process or node boundaries.
• UI adapter and fixture coverage under mesh/crates/mesh-llm-ui/src/features/configuration/ and mesh/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 mesh/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 mesh/crates/mesh-llm-plugin/src/manifest.rs and mesh/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 mesh/crates/mesh-llm-host-runtime/src/plugin/config.rs and mesh/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 mesh/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 mesh/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:

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:

cd mesh/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:

just build