diff --git a/docs/wire-schema/v1/error.schema.json b/docs/wire-schema/v1/error.schema.json
new file mode 100644
index 0000000..a186e28
--- /dev/null
+++ b/docs/wire-schema/v1/error.schema.json
@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kebab.local/wire-schema/v1/error.schema.json",
+  "title": "error.v1",
+  "description": "Structured fatal error emitted on stderr in --json mode. The `details` shape varies per `code`; consumers should branch on `code` and treat `details` as best-effort context.",
+  "type": "object",
+  "required": ["schema_version", "code", "message", "details"],
+  "properties": {
+    "schema_version": { "const": "error.v1" },
+    "code": {
+      "type": "string",
+      "enum": [
+        "config_invalid",
+        "not_indexed",
+        "model_unreachable",
+        "model_not_pulled",
+        "timeout",
+        "io_error",
+        "generic"
+      ]
+    },
+    "message": { "type": "string" },
+    "details": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Per-code free-form context. config_invalid: { path, cause }. not_indexed: { expected, found }. model_unreachable: { endpoint, source }. model_not_pulled: { model }. timeout: { source }. io_error: { kind }. generic: { chain (when --verbose) }."
+    },
+    "hint": {
+      "anyOf": [
+        { "type": "string" },
+        { "type": "null" }
+      ]
+    }
+  }
+}
diff --git a/docs/wire-schema/v1/schema.schema.json b/docs/wire-schema/v1/schema.schema.json
new file mode 100644
index 0000000..f168ff4
--- /dev/null
+++ b/docs/wire-schema/v1/schema.schema.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kebab.local/wire-schema/v1/schema.schema.json",
+  "title": "schema.v1",
+  "description": "kebab introspection report — wire schemas, capabilities, model versions, and index stats.",
+  "type": "object",
+  "required": ["schema_version", "kebab_version", "wire", "capabilities", "models", "stats"],
+  "properties": {
+    "schema_version": { "const": "schema.v1" },
+    "kebab_version": { "type": "string" },
+    "wire": {
+      "type": "object",
+      "required": ["schemas"],
+      "properties": {
+        "schemas": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z_]+\\.v[0-9]+$" }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": { "type": "boolean" },
+      "required": [
+        "json_mode", "ingest_progress", "ingest_cancellation",
+        "rag_multi_turn", "search_cache", "incremental_ingest",
+        "streaming_ask", "http_daemon", "mcp_server", "single_file_ingest"
+      ]
+    },
+    "models": {
+      "type": "object",
+      "required": [
+        "parser_version", "chunker_version", "embedding_version",
+        "prompt_template_version", "index_version", "corpus_revision"
+      ],
+      "properties": {
+        "parser_version": { "type": "string" },
+        "chunker_version": { "type": "string" },
+        "embedding_version": { "type": "string" },
+        "prompt_template_version": { "type": "string" },
+        "index_version": { "type": "string" },
+        "corpus_revision": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "stats": {
+      "type": "object",
+      "required": ["doc_count", "chunk_count", "asset_count", "last_ingest_at"],
+      "properties": {
+        "doc_count": { "type": "integer", "minimum": 0 },
+        "chunk_count": { "type": "integer", "minimum": 0 },
+        "asset_count": { "type": "integer", "minimum": 0 },
+        "last_ingest_at": {
+          "anyOf": [
+            { "type": "string", "format": "date-time" },
+            { "type": "null" }
+          ]
+        }
+      }
+    }
+  }
+}