add initial AI ball protocol docs

schemas/call_script_schema.json

@@ -1,23 +1,65 @@
 {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "AI Ball Call Script Schema",
+  "description": "Initial schema for AI球 concert/support call scripts executed by devices according to a playback timeline.",
   "type": "object",
-  "required": ["content_id", "title", "duration_ms", "actions"],
+  "additionalProperties": false,
+  "required": ["content_id", "title", "version", "duration_ms", "actions"],
   "properties": {
-    "content_id": { "type": "string" },
-    "title": { "type": "string" },
-    "duration_ms": { "type": "integer" },
+    "content_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique content or song identifier."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "duration_ms": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "resource_pack_id": {
+      "type": "string",
+      "description": "Optional expected resource pack id."
+    },
     "actions": {
       "type": "array",
       "items": {
         "type": "object",
+        "additionalProperties": false,
         "required": ["time_ms", "type", "value"],
         "properties": {
-          "time_ms": { "type": "integer" },
-          "type": { "type": "string" },
-          "value": { "type": "string" },
-          "duration_ms": { "type": "integer" },
-          "intensity": { "type": "number" },
-          "silent_alt": { "type": "string" }
+          "time_ms": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "type": {
+            "type": "string",
+            "enum": ["light", "sound", "expression", "vibration", "combo"]
+          },
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Resource id, preset name, or simple command value."
+          },
+          "duration_ms": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "intensity": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "silent_alt": {
+            "type": "string",
+            "description": "Fallback behavior when sound output should be muted."
+          }
         }
       }
     }

schemas/resource_pack_schema.json

@@ -1,19 +1,53 @@
 {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "AI Ball Resource Pack Schema",
+  "description": "Initial schema for AI球 resource packs used by devices and the PC host application.",
   "type": "object",
+  "additionalProperties": false,
   "required": ["pack_id", "version", "resources"],
   "properties": {
-    "pack_id": { "type": "string" },
-    "version": { "type": "string" },
+    "pack_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "target_firmware": {
+      "type": "string",
+      "description": "Optional compatible firmware version or range."
+    },
+    "description": {
+      "type": "string"
+    },
     "resources": {
       "type": "array",
       "items": {
         "type": "object",
+        "additionalProperties": false,
         "required": ["id", "type", "path"],
         "properties": {
-          "id": { "type": "string" },
-          "type": { "type": "string" },
-          "path": { "type": "string" }
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "type": {
+            "type": "string",
+            "enum": ["audio", "image", "animation", "light_preset", "expression", "other"]
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[A-Fa-f0-9]{64}$"
+          },
+          "size_bytes": {
+            "type": "integer",
+            "minimum": 0
+          }
         }
       }
     }