Merge branch 'master' into perf/optional-prometheus-tui

Author: theonlyhennygod

.gitignore

@@ -60,4 +60,4 @@ playground/
 rust_out
 
 # Auto-generated Tauri schemas
-apps/tauri/gen/schemas/linux-schema.json
+apps/tauri/gen/schemas/

CONTRIBUTING.md

@@ -387,6 +387,56 @@ Use these quick examples to align implementation choices before opening a PR.
 - **Bad**: config key changes without migration notes.
 - **Good**: config/schema changes include defaults, compatibility impact, migration steps, and rollback guidance.
 
+## Config Schema Versioning and Migrations
+
+ZeroClaw uses a forward-only schema versioning system for `config.toml`. This section
+explains when and how to create a migration.
+
+### When a migration IS needed
+
+A schema version bump is required when you **rename, move, or remove** an existing
+config prop. Examples:
+
+- Renaming `room_id` to something else
+- Moving a prop from one section to another
+- Removing a deprecated prop entirely
+
+### When a migration is NOT needed
+
+Adding a new config prop does **not** require a schema version bump. Use
+`#[serde(default)]` on the new field and it will be filled with its default value
+when loading older config files. This is the common case.
+
+### How the migration system works
+
+1. `crates/zeroclaw-config/src/migration.rs` contains `V1Compat`, a wrapper struct
+   that uses `#[serde(flatten)]` to deserialize both old-format and current-format
+   TOML into a single pass. Old fields live on `V1Compat`; current fields land on
+   `Config`.
+2. `V1Compat::into_config()` moves old field values into their new locations on
+   `Config` using typed field access — no string-based key manipulation. All call
+   sites use `config.providers.*` directly.
+3. For schema versions beyond V2, add `fn vN_to_vM(&mut Config)` functions that
+   mutate the `Config` struct directly.
+
+### How to add a new migration step
+
+1. Bump `CURRENT_SCHEMA_VERSION` in `crates/zeroclaw-config/src/migration.rs`.
+2. If the old field was on `V1Compat`, update the `migrate_providers()` or similar
+   method. If the change is between V2+ layouts, add a new `fn vN_to_vM(&mut Config)`
+   and call it from `into_config()` after the schema version check.
+3. Add tests in `tests/component/config_migration.rs` that:
+   - Deserialize a TOML string with the old layout
+   - Assert the migrated `Config` has values in the new locations
+   - Assert the old locations are empty/cleared
+4. Run `cargo test --test component -- config_migration` to verify.
+
+### `zeroclaw config migrate`
+
+Users can run `zeroclaw config migrate` to rewrite their on-disk `config.toml` to the
+current schema version. This command uses `toml_edit` to preserve comments and
+formatting while making structural changes.
+
 ## How to Add a New Provider
 
 Create `src/providers/your_provider.rs`:

Cargo.lock

@@ -92,6 +92,7 @@ serde_json = { version = "1.0", default-features = false, features = ["std"] }
 # Config
 directories = "6.0"
 toml = "1.0"
+toml_edit = "0.25"  # already a transitive dep via toml — zero added compile/binary cost
 shellexpand = "3.1"
 
 # JSON Schema generation for config export

Cargo.toml

@@ -504,6 +504,14 @@ impl<T: Provider + ?Sized> Provider for Arc<T> {
         self.as_ref().convert_tools(tools)
     }
 
+    fn supports_native_tools(&self) -> bool {
+        self.as_ref().supports_native_tools()
+    }
+
+    fn supports_vision(&self) -> bool {
+        self.as_ref().supports_vision()
+    }
+
     async fn chat_with_system(
         &self,
         system_prompt: Option<&str>,