feat: add explain v1.0.0 request + receipt schemas

Author: Your Name

schemas/v1.0.0/commons/explain/receipts/explain.receipt.schema.json

@@ -0,0 +1,136 @@
+{
+  "$id": "https://commandlayer.org/schemas/v1.0.0/commons/explain/receipts/explain.receipt.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "explain.receipt",
+  "description": "Receipt for explain requests, extending the CommandLayer base receipt structure with explanation-specific result and usage fields.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "https://commandlayer.org/schemas/v1.0.0/_shared/receipt.base.schema.json"
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "x402": {
+          "description": "x402 envelope describing the explain verb and version for this receipt.",
+          "allOf": [
+            {
+              "$ref": "https://commandlayer.org/schemas/v1.0.0/_shared/x402.schema.json"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "verb": { "const": "explain" },
+                "version": { "const": "1.0.0" }
+              },
+              "required": ["verb", "version"]
+            }
+          ]
+        },
+        "result": {
+          "description": "Explanation result payload when status = 'ok' or 'partial'.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "explanation": {
+              "description": "The explanation content.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 500000
+            },
+            "format": {
+              "description": "Format of the explanation.",
+              "type": "string",
+              "enum": ["text", "markdown", "html", "json", "other"]
+            },
+            "audience": {
+              "description": "Effective audience the agent targeted.",
+              "type": "string",
+              "maxLength": 64
+            },
+            "depth": {
+              "description": "Depth actually applied.",
+              "type": "string",
+              "enum": ["overview", "detailed", "deep_dive"]
+            },
+            "includes_limitations": {
+              "description": "Whether the explanation explicitly calls out limitations or uncertainties.",
+              "type": "boolean"
+            },
+            "evidence_referenced": {
+              "description": "Whether the explanation explicitly referenced evidence or sources.",
+              "type": "boolean"
+            },
+            "evidence_summary": {
+              "description": "Short summary of the evidence the explanation was grounded in, if applicable.",
+              "type": "string",
+              "maxLength": 2000
+            },
+            "source_hash": {
+              "description": "Optional hash of the evidence or subject content (e.g., sha256 hex).",
+              "type": "string",
+              "minLength": 32,
+              "maxLength": 128
+            },
+            "confidence": {
+              "description": "Optional numeric confidence estimate for the explanation.",
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "warnings": {
+              "description": "Non-fatal warnings about the explanation (e.g., partial logs, missing features).",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024
+              }
+            },
+            "model_name": {
+              "description": "Identifier for the model or engine used, if applicable.",
+              "type": "string",
+              "maxLength": 256
+            }
+          },
+          "required": ["explanation"]
+        },
+        "usage": {
+          "description": "Optional resource usage metrics for this invocation.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "input_tokens": {
+              "description": "Number of input tokens consumed.",
+              "type": "integer",
+              "minimum": 0
+            },
+            "output_tokens": {
+              "description": "Number of output tokens produced.",
+              "type": "integer",
+              "minimum": 0
+            },
+            "total_tokens": {
+              "description": "Total tokens used (input + output), if available.",
+              "type": "integer",
+              "minimum": 0
+            },
+            "cost_usd": {
+              "description": "Optional cost for this call in USD (or equivalent fiat), if known.",
+              "type": "number",
+              "minimum": 0
+            },
+            "latency_ms": {
+              "description": "Observed end-to-end latency for this invocation in milliseconds.",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      },
+      "required": ["x402", "trace", "status", "result"]
+    }
+  ]
+}