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."
+          }
         }
       }
     }