From d33eadea7518c7b5c94d6b96d0124390d621a464 Mon Sep 17 00:00:00 2001
From: Chummy <chumyin0912@gmail.com>
Date: Thu, 19 Feb 2026 16:38:05 +0800
Subject: [PATCH] docs(config): document schema command and add schema test

---
 docs/commands-reference.md |  9 ++++++++-
 docs/config-reference.md   |  6 +++++-
 src/config/schema.rs       | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/docs/commands-reference.md b/docs/commands-reference.md
index 8c0d3ae..04a668f 100644
--- a/docs/commands-reference.md
+++ b/docs/commands-reference.md
@@ -2,7 +2,7 @@
 
 This reference is derived from the current CLI surface (`zeroclaw --help`).
 
-Last verified: **February 18, 2026**.
+Last verified: **February 19, 2026**.
 
 ## Top-Level Commands
 
@@ -22,6 +22,7 @@ Last verified: **February 18, 2026**.
 | `integrations` | Inspect integration details |
 | `skills` | List/install/remove skills |
 | `migrate` | Import from external runtimes (currently OpenClaw) |
+| `config` | Export machine-readable config schema |
 | `hardware` | Discover and introspect USB hardware |
 | `peripheral` | Configure and flash peripherals |
 
@@ -105,6 +106,12 @@ Runtime in-chat commands (Telegram/Discord while channel server is running):
 
 - `zeroclaw migrate openclaw [--source <path>] [--dry-run]`
 
+### `config`
+
+- `zeroclaw config schema`
+
+`config schema` prints a JSON Schema (draft 2020-12) for the full `config.toml` contract to stdout.
+
 ### `hardware`
 
 - `zeroclaw hardware discover`
diff --git a/docs/config-reference.md b/docs/config-reference.md
index 725993c..f9dfe45 100644
--- a/docs/config-reference.md
+++ b/docs/config-reference.md
@@ -2,12 +2,16 @@
 
 This is a high-signal reference for common config sections and defaults.
 
-Last verified: **February 18, 2026**.
+Last verified: **February 19, 2026**.
 
 Config file path:
 
 - `~/.zeroclaw/config.toml`
 
+Schema export command:
+
+- `zeroclaw config schema` (prints JSON Schema draft 2020-12 to stdout)
+
 ## Core Keys
 
 | Key | Default | Notes |
diff --git a/src/config/schema.rs b/src/config/schema.rs
index 22590e3..9227aec 100644
--- a/src/config/schema.rs
+++ b/src/config/schema.rs
@@ -3104,6 +3104,38 @@ mod tests {
         assert!(c.config_path.to_string_lossy().contains("config.toml"));
     }
 
+    #[test]
+    fn config_schema_export_contains_expected_contract_shape() {
+        let schema = schemars::schema_for!(Config);
+        let schema_json = serde_json::to_value(&schema).expect("schema should serialize to json");
+
+        assert_eq!(
+            schema_json
+                .get("$schema")
+                .and_then(serde_json::Value::as_str),
+            Some("https://json-schema.org/draft/2020-12/schema")
+        );
+
+        let properties = schema_json
+            .get("properties")
+            .and_then(serde_json::Value::as_object)
+            .expect("schema should expose top-level properties");
+
+        assert!(properties.contains_key("default_provider"));
+        assert!(properties.contains_key("gateway"));
+        assert!(properties.contains_key("channels_config"));
+        assert!(!properties.contains_key("workspace_dir"));
+        assert!(!properties.contains_key("config_path"));
+
+        assert!(
+            schema_json
+                .get("$defs")
+                .and_then(serde_json::Value::as_object)
+                .is_some(),
+            "schema should include reusable type definitions"
+        );
+    }
+
     #[test]
     fn observability_config_default() {
         let o = ObservabilityConfig::default();